cxtms 1.9.13

package/skills/cxtms-developer/ref-entity-accounting.md

@@ -0,0 +1,180 @@
+# Accounting Transaction Entity Field Reference
+
+## Contents
+- AccountingTransaction Fields
+- Charge Entity
+- Payment Entity
+- Accounting Enums
+- Accounting CustomValues
+
+Field names as used in workflow expressions: `{{ entity.transactionNumber }}`, `{{ entity.customValues.myField }}`.
+
+## AccountingTransaction Fields
+
+### Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `accountingTransactionId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `divisionId` | `int` | Division scope |
+| `transactionNumber` | `string` | Business-facing number |
+| `transactionDate` | `DateTime` | Date of transaction |
+| `dueDate` | `DateTime` | Payment due date |
+| `paidDate` | `DateTime?` | When fully paid |
+| `accountingTransactionType` | `AccountingTransactionType` enum | Invoice, Bill, CreditMemo |
+| `accountingTransactionStatus` | `AccountingTransactionStatus` enum | Open, Paid, Void |
+| `amountDue` | `decimal` | Charges total minus payments |
+| `amountPaid` | `decimal` | Sum of applied payments |
+| `paidAs` | `PaidAs` enum | Prepaid, Collect |
+| `isDraft` | `bool` | Not yet submitted |
+| `note` | `string?` | |
+| `accountId` | `int?` | FK to AccountingAccount |
+| `applyToContactID` | `int?` | FK to Contact (customer/vendor) |
+| `billToContactAddressId` | `int?` | FK to ContactAddress |
+| `paymentTermsId` | `int?` | FK to PaymentTerm |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+### Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `applyToContact` | `Contact` | Customer or vendor |
+| `billToContactAddress` | `ContactAddress` | Billing address |
+| `division` | `Division` | |
+| `organization` | `Organization` | |
+| `paymentTerm` | `PaymentTerm` | |
+| `account` | `AccountingAccount` | |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+### Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `charges` | `[Charge]` | Via AccountingTransactionCharges join |
+| `payments` | `[Payment]` | Via AccountingTransactionPayment join |
+| `jobs` | `[Job]` | Via JobAccountingTransaction join |
+
+### Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `getChargesTotalAmount` | `decimal` | Sum of non-void charges |
+| `getAmountDue` | `decimal` | Charges total minus amountPaid |
+| `getRelatedOrders(filter, orderBy)` | `[Order]` | Orders linked via charges |
+| `getRelatedOrdersByOrderType(orderType)` | `[Order]` | Filtered by order type |
+| `getRelatedOrderByOrderType(orderType)` | `Order` | First match |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+---
+
+## Charge Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `chargeId` | `int` | Primary key |
+| `organizationId` | `int?` | |
+| `description` | `string?` | |
+| `chargeType` | `ChargeType` enum | Income, Expense, Credit |
+| `chargeStatus` | `ChargeStatus` enum | Pending, Open, Posted, Paid, Void |
+| `amount` | `decimal` | Calculated: `quantity * price` |
+| `price` | `decimal` | Unit price |
+| `quantity` | `decimal` | |
+| `unit` | `string?` | e.g., "TV", "Pallet", "Kg" |
+| `applyBy` | `ApplyBy` enum | Pieces, Weight, ChargeableWeight, Volume, Container, Calculated, FlatRate |
+| `applyToContactId` | `int` | FK to Contact (who pays) |
+| `paidAs` | `PaidAs` enum | Prepaid, Collect |
+| `currencyId` | `int` | FK to Currency |
+| `accountingItemId` | `int` | FK to AccountingItem |
+| `salesTaxId` | `int?` | FK to SalesTax |
+| `salesTaxRate` | `decimal` | |
+| `salesTaxAmount` | `decimal` | Computed: `salesTaxRate * amount` |
+| `totalAmount` | `decimal` | Computed: `amount + salesTaxAmount` |
+| `showInDocuments` | `bool` | |
+| `isConsolidated` | `bool` | |
+| `allowAutomaticUpdate` | `bool` | |
+| `note` | `string?` | |
+| `rateId` | `int?` | FK to Rate |
+| `customValues` | `Dictionary` | Own customValues |
+
+**Navigation:** `applyToContact`, `currency`, `accountingItem`, `salesTax`, `rate`, `orders` (many-to-many)
+
+---
+
+## Payment Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `paymentId` | `int` | Primary key |
+| `organizationId` | `int` | |
+| `divisionId` | `int` | |
+| `applyToContactId` | `int` | FK to Contact |
+| `amountReceived` | `decimal` | Total payment amount |
+| `currencyId` | `int` | FK to Currency |
+| `paymentDate` | `DateTime` | |
+| `checkNumber` | `string` | |
+| `memo` | `string` | |
+| `accountingAccountId` | `int` | FK to AccountingAccount |
+| `paymentStatus` | `PaymentStatus` enum | Posted=1, Void=2 |
+| `customValues` | `Dictionary` | Own customValues |
+
+**Navigation:** `applyToContact`, `currency`, `accountingAccount`, `division`, `organization`, `accountingTransactions` (many-to-many)
+
+**Join entity `AccountingTransactionPayment`** has `amountApplied` field — the amount from this payment applied to a specific transaction.
+
+---
+
+## Enums
+
+### AccountingTransactionType
+| Value | Int | Description |
+|-------|-----|-------------|
+| `Invoice` | 0 | Revenue — billed to customer |
+| `Bill` | 1 | Expense — owed to vendor |
+| `CreditMemo` | 2 | Credit adjustment |
+
+### AccountingTransactionStatus
+`Open=0`, `Paid=1`, `Void=2`
+
+### ChargeType
+`Income`, `Expense`, `Credit`
+
+### ChargeStatus
+`Pending`, `Open`, `Posted`, `Paid`, `Void`
+
+### ApplyBy
+`Pieces`, `Weight`, `ChargeableWeight`, `Volume`, `Container`, `Calculated`, `FlatRate`
+
+### PaymentStatus
+`Posted=1`, `Void=2`
+
+### PaidAs
+`Prepaid=0`, `Collect=1`
+
+---
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Present on:
+- `AccountingTransaction.customValues`
+- `Charge.customValues`
+- `Payment.customValues`
+
+```yaml
+# Access in workflow expressions
+invoiceNumber: "{{ entity.transactionNumber }}"
+customerName: "{{ entity.applyToContact.name }}"
+customField: "{{ entity.customValues.myField }}"
+
+# Charge access via collection
+chargeAmount: "{{ entity.charges[0].amount }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.accountingTransactionStatus] = 'Open'"
+  - expression: "[entity.amountDue] > 0"
+```

package/skills/cxtms-developer/ref-entity-commodity.md

@@ -0,0 +1,239 @@
+# Commodity Entity Field Reference
+
+## Contents
+- Commodity Scalar Fields
+- Commodity Navigation Properties
+- Commodity Collection Properties
+- Commodity Computed/Resolved GraphQL Fields
+- Commodity Container/Child Pattern (Self-Referencing)
+- CommodityTrackingNumber Sub-Entity
+- OrderCommodity Join Entity
+- Commodity Enums
+- Commodity CustomValues
+- CommodityEvent (Bridge Entity)
+
+Field names as used in workflow expressions: `{{ entity.description }}`, `{{ entity.customValues.myField }}`.
+
+## Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `description` | `string` | Required |
+| `pieces` | `int` | Number of pieces |
+| `quantity` | `int?` | Inner quantity per piece |
+| `unit` | `string?` | Unit of measure (e.g., "TV", "Pallet", "Kg") |
+| `note` | `string?` | |
+| `serialNumber` | `string?` | Domain only (not in GraphQL) |
+| `isDeleted` | `bool?` | Soft delete |
+
+### Weight Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `weight` | `decimal?` | Per piece (or total if `weightByTotal`) |
+| `weightTotal` | `decimal?` | Calculated: `weight * pieces` |
+| `weightUnit` | `WeightUnit` enum | Lb, Kg |
+| `weightByTotal` | `bool` | When true, weight = sum of children |
+
+### Dimension Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `height` | `decimal?` | |
+| `dimensionsUnit` | `DimensionsUnit` enum | In, Cm, M, Ft |
+
+### Volume Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `volumePiece` | `decimal?` | Calculated: `L * W * H` converted to volumeUnit |
+| `volumeTotal` | `decimal?` | Calculated: `pieces * volumePiece` |
+| `volumeUnit` | `VolumeUnit` enum | Ft, Vlb, Vkg, M, In, Cm |
+
+### Value Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `unitaryValue` | `decimal?` | Value per unit |
+| `unitaryValueTotal` | `decimal?` | Calculated: `unitaryValue * quantity * pieces` |
+| `valueByTotal` | `bool` | When true, value = sum of children |
+
+### Foreign Keys
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityStatusId` | `int?` | FK to CommodityStatus |
+| `commodityTypeId` | `int?` | FK to CommodityType |
+| `packageTypeId` | `int?` | FK to PackageType |
+| `warehouseLocationId` | `int?` | FK — cascades to children |
+| `containerCommodityId` | `int?` | FK self-ref (parent commodity) |
+| `jobId` | `Guid?` | FK to Job |
+| `inventoryItemId` | `int?` | FK to InventoryItem |
+| `billToContactId` | `int?` | FK to Contact |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+## Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityStatus` | `CommodityStatus` | `.statusName`, `.statusStage` |
+| `commodityType` | `CommodityType` | `.code`, `.description` |
+| `packageType` | `PackageType` | `.name` |
+| `warehouseLocation` | `WarehouseLocation` | |
+| `containerCommodity` | `Commodity` | Parent commodity |
+| `job` | `Job` | |
+| `inventoryItem` | `InventoryItem` | |
+| `billToContact` | `Contact` | |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+## Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `containerCommodities` | `[Commodity]` | Child commodities in this container |
+| `orderCommodities` | `[OrderCommodity]` | Join to orders (has own `customValues`) |
+| `commodityTrackingNumbers` | `[CommodityTrackingNumber]` | Tracking numbers |
+| `commodityTags` | `[CommodityTag]` | Tags (has own `customValues`) |
+| `allTags` | `[CommodityAllTagsView]` | View: includes inherited tags |
+| `trackingEvents` | `[TrackingEvent]` | |
+| `shipments` | `[Order]` | Related orders (GraphQL) |
+
+## Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `totalAmount` | `decimal` | Computed: `unitaryValue * quantity` |
+| `packageTypeName` | `string` | From packageType.name |
+| `trackingNumbers` | `[TrackingNumber]` | From commodityTrackingNumbers |
+| `getChildCommodities(filter)` | `[Commodity]` | Child commodities |
+| `getParentCommodity` | `Commodity` | Parent commodity |
+| `getRelatedOrders(filter)` | `[Order]` | Related orders |
+| `getRelatedOrder(filter)` | `Order` | First related order |
+| `getCommodityTrackingNumber(idPropertyName)` | `TrackingNumber` | Lookup |
+| `getCommodityAttachments(filter)` | `[Attachment]` | |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+## Container/Child Pattern (Self-Referencing)
+
+Commodities form a tree via `containerCommodityId`:
+
+```
+Container Commodity (parent)
+  ├── Child Commodity 1
+  ├── Child Commodity 2
+  └── Child Commodity 3
+```
+
+- Parent → children: `containerCommodities` collection
+- Child → parent: `containerCommodity` navigation
+- When `weightByTotal=true`, weight is computed as sum of children
+- Changing warehouse location on parent cascades to children
+- Changing commodity status on parent cascades to children
+- Deleting parent cascades to children
+
+## CommodityTrackingNumber Sub-Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityTrackingNumberId` | `int` | PK |
+| `trackingNumber` | `string` | |
+| `trackingNumberType` | `string?` | BOL, PRO, PO, etc. |
+| `isPrimary` | `bool` | |
+| `syncOrderId` | `int?` | |
+
+## OrderCommodity Join Entity
+
+Links commodities to orders with per-association metadata:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityId` | `int` | |
+| `orderId` | `int` | |
+| `customValues` | `Dictionary` | **Own** customValues, separate from Commodity |
+| `commodity` | `Commodity` | Navigation |
+| `order` | `Order` | Navigation |
+
+## Enums
+
+### WeightUnit
+`Lb`, `Kg`
+
+### DimensionsUnit
+`In`, `Cm`, `M`, `Ft`
+
+### VolumeUnit
+| Value | Description |
+|-------|-------------|
+| `Ft` | Cubic feet |
+| `Vlb` | Volumetric lbs |
+| `Vkg` | Volumetric kg |
+| `M` | Cubic meters |
+| `In` | Cubic inches |
+| `Cm` | Cubic cm |
+
+### CommodityStatusStage
+`Pending=1`, `InProgress`, `Completed`
+
+### CommodityStatus (enum, distinct from entity)
+`Pending`, `OnRoute`, `Delivered`, `Cancelled`, `InQuote`, `OnHand`, `OnPacking`, `InTransit`
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:
+
+```yaml
+# Template expressions
+value: "{{ entity.description }}"
+value: "{{ entity.customValues.myField }}"
+value: "{{ entity.containerCommodity.description }}"
+
+# Access weight with unit conversion
+weight: "{{ entity.weight }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.pieces] > 0 AND isNullOrEmpty([entity.customValues.lotNumber?]) = false"
+
+# Update via Commodity/Update task
+inputs:
+  commodityId: "{{ entity.commodityId }}"
+  commodity:
+    CustomValues.lotNumber: "LOT-001"
+    CustomValues.hazmat: true
+```
+
+**Entities with own customValues:**
+- `Commodity.customValues` — commodity-level fields
+- `OrderCommodity.customValues` — per-order-per-commodity fields
+- `CommodityType.customValues` — type-level fields
+- `CommodityTag.customValues` — tag-level fields
+
+---
+
+## CommodityEvent (Bridge Entity)
+
+Links tracking events to individual commodities for granular item-level tracking.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `commodityEventId` | `int` | PK |
+| `commodityId` | `int` | FK to Commodity |
+| `trackingEventId` | `int` | FK to TrackingEvent |
+
+**Navigation:** `commodity`, `trackingEvent` (with `eventDefinition`)
+
+Used in Flow workflow aggregations:
+```yaml
+aggregations:
+  - name: "hasCommodityEvent"
+    parameter: "eventCode"
+    expression: "any([Commodity.CommodityEvents], [each.TrackingEvent.EventDefinition.EventCode] = [eventCode])"
+```

package/skills/cxtms-developer/ref-entity-contact.md

@@ -0,0 +1,163 @@
+# Contact Entity Field Reference
+
+## Contents
+- Contact Scalar Fields
+- Contact Navigation Properties
+- Contact Collection Properties
+- Contact Computed/Resolved GraphQL Fields
+- ContactType Enum
+- ContactAddress Sub-Entity
+- Contact Other Related Enums
+- Contact CustomValues
+
+Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.customValues.myField }}`.
+
+## Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `name` | `string` | Required. Company/display name |
+| `contactFirstName` | `string?` | |
+| `contactLastName` | `string?` | |
+| `contactType` | `ContactType` enum | See enum below |
+| `accountNumber` | `string?` | |
+| `emailAddress` | `string?` | |
+| `phoneNumber` | `string?` | |
+| `mobilePhoneNumber` | `string?` | |
+| `faxNumber` | `string?` | |
+| `website` | `string?` | |
+| `idNumber` | `string?` | EIN, DUNS, etc. |
+| `idNumberType` | `IDNumberType?` enum | EIN, DUNS, ForeignEntityId, Other |
+| `divisionId` | `int` | Primary division FK |
+| `paymentTermId` | `int?` | FK to PaymentTerm |
+| `creditLimit` | `decimal?` | |
+| `paidAs` | `PaidAs?` enum | Prepaid, Collect |
+| `isACorporation` | `bool?` | |
+| `isDeleted` | `bool` | Soft delete flag |
+| `contactStatusId` | `int?` | FK to ContactStatus |
+| `entityTypeId` | `int?` | FK to EntityType |
+| `parentContactId` | `int?` | Self-referencing FK |
+| `tags` | `[string]` | String array |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+## Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `division` | `Division` | Primary division |
+| `paymentTerm` | `PaymentTerm` | |
+| `contactStatus` | `ContactStatus` | `.statusName`, `.statusStage` (Active/Inactive) |
+| `entityType` | `EntityType` | |
+| `parentContact` | `Contact` | Self-referencing parent |
+| `createdUser` | `User` | |
+| `updatedUser` | `User` | |
+
+## Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactAddresses` | `[ContactAddress]` | Addresses with types (Billing, Shipping, Other) |
+| `contacts` | `[Contact]` | Linked contacts (TO this contact) |
+| `linksToContacts` | `[Contact]` | Contacts this one links TO |
+| `contactLinks` | `[ContactLink]` | Link details (type: ParentContact, FactoringCompany, SalesPerson) |
+| `equipmentTypes` | `[EquipmentType]` | Carrier only |
+| `discounts` | `[Discount]` | Via ContactDiscount join |
+| `rates` | `[Rate]` | Carrier rates |
+| `additionalDivisions` | `[Division]` | Beyond primary division |
+| `orders` | `[Order]` | Via OrderCarrier |
+
+## Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `getContactAddressByType(addressType)` | `[ContactAddress]` | Filter by "Billing", "Shipping", "Other" |
+| `getFirstContactAddressByType(addressType)` | `ContactAddress` | First match |
+| `getContactAttachments(filter, orderBy)` | `[Attachment]` | |
+| `getCustomValuesAttachment(filter)` | `Attachment` | From customValues `attachmentId` key |
+| `availableCredit` | `[AvailableCreditByCurrency]` | Carrier/Customer only |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+
+## ContactType Enum
+
+| Value | Int | Notes |
+|-------|-----|-------|
+| `Customer` | 1 | Can have accounting |
+| `Carrier` | 2 | Can have accounting, equipment types |
+| `Vendor` | 3 | |
+| `Contact` | 4 | Generic, must have linked contact |
+| `Driver` | 5 | |
+| `Employee` | 6 | Can have user account |
+| `SalesPerson` | 7 | |
+| `ForwardingAgent` | 8 | |
+| `FactoringCompany` | 9 | |
+| `Lead` | 10 | |
+| `PoolPoint` | 11 | |
+| `DistributionCenter` | 12 | |
+| `Store` | 13 | |
+| `ContactUser` | 14 | User associated with contact |
+| `USPPI` | 15 | US Principal Party in Interest |
+
+## ContactAddress Sub-Entity
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `contactAddressId` | `int` | PK |
+| `addressLine` | `string?` | |
+| `addressLine2` | `string?` | |
+| `addressType` | `AddressType` enum | Billing=1, Shipping=2, Other=3 |
+| `cityName` | `string?` | |
+| `countryCode` | `string?` | FK to Country |
+| `stateCode` | `string?` | FK to State |
+| `postalCode` | `string?` | |
+| `isInactive` | `bool?` | |
+| `latitude` | `double?` | From Location.Y (GraphQL resolved) |
+| `longitude` | `double?` | From Location.X (GraphQL resolved) |
+| `customValues` | `Dictionary` | Own customValues (separate from Contact) |
+| `country` | `Country` | Navigation |
+| `state` | `State` | Navigation |
+
+GraphQL resolver: `formattedAddress(outputFormat, addressFormat, lang, multiline)` — formatted string.
+
+## Other Related Enums
+
+| Enum | Values |
+|------|--------|
+| `IDNumberType` | EIN, DUNS, ForeignEntityId, Other |
+| `PaidAs` | Prepaid, Collect |
+| `AddressType` | Billing=1, Shipping=2, Other=3 |
+| `ContactLinkType` | ParentContact=1, FactoringCompany, SalesPerson, ContactAddressLink |
+| `ContactStatusStage` | Active=0, Inactive=1 |
+| `PaymentType` | Card=1, AccountCredit=2, Cash=3, Check=4, BankTransfer=5, Other=7 |
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:
+
+```yaml
+# Template expressions
+value: "{{ entity.name }}"
+value: "{{ entity.customValues.myField }}"
+
+# Access contact address
+address: "{{ entity.contactAddresses[0].addressLine }}"
+
+# NCalc conditions
+conditions:
+  - expression: "[entity.contactType] = 'Customer'"
+
+# Update via Contact/Update task
+inputs:
+  contactId: "{{ entity.contactId }}"
+  contact:
+    CustomValues.myField: "newValue"
+```
+
+**Entities with own customValues:**
+- `Contact.customValues` — contact-level custom fields
+- `ContactAddress.customValues` — address-level custom fields
+- `ContactPaymentMethod.customValues` — payment method custom fields