cxtms 1.9.13

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

@@ -0,0 +1,154 @@
+# Geography & Lookup Entity Reference
+
+## Contents
+- Country
+- State
+- City
+- PostalCode
+- Port
+- Vessel
+- CustomCode
+- ModeOfTransportation
+
+Country, State, City, PostalCode, Port, Vessel, CustomCode, ModeOfTransportation.
+
+## Country
+
+Composite key: `organizationId` + `countryCode`.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `countryCode` | `string` | PK part (ISO code) |
+| `organizationId` | `int` | PK part |
+| `name` | `string` | |
+| `customValues` | `Dictionary` | jsonb |
+
+**Collections:** `states`
+
+---
+
+## State
+
+Composite key: `organizationId` + `countryCode` + `stateCode`.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `stateCode` | `string` | PK part |
+| `countryCode` | `string` | PK part, FK to Country |
+| `organizationId` | `int` | PK part |
+| `name` | `string` | |
+| `customValues` | `Dictionary` | jsonb |
+
+**Navigation:** `country`
+
+---
+
+## City
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `cityId` | `int` | PK |
+| `organizationId` | `int` | |
+| `cityName` | `string` | |
+| `stateCode` | `string` | FK to State |
+| `countryCode` | `string` | FK to Country |
+| `longitude` | `double?` | From Location.X (GraphQL) |
+| `latitude` | `double?` | From Location.Y (GraphQL) |
+| `customValues` | `Dictionary` | jsonb |
+
+**Navigation:** `state`, `country`
+
+---
+
+## PostalCode
+
+PK: `id` (int, auto). Scoped per organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | Postal/zip code value |
+| `countryCode` | `string` | FK to Country |
+| `placeName` | `string` | Place/city name |
+| `stateCode` | `string?` | FK to State |
+| `accuracy` | `AccuracyTypes?` | 1=Region, 2=Municipality, 3=Neighborhood, 4=Place, 5=Street, 6=Centroid |
+| `timeZone` | `string?` | IANA timezone ID (e.g., `America/Chicago`). GraphQL auto-resolves from GPS coordinates when not stored |
+| `longitude` | `double?` | From Location.X (GraphQL computed) |
+| `latitude` | `double?` | From Location.Y (GraphQL computed) |
+| `customValues` | `Dictionary` | jsonb |
+| `location` | `Point?` | WGS 84 (SRID 4326). X=longitude, Y=latitude |
+
+**Navigation:** `country`, `state`
+
+**Mutations:** `ChangeCode`, `ChangePlaceName`, `ChangeCoordinates(lat, lng, accuracy)`, `ChangeCountry`/`ChangeCountryCode`, `ChangeState`/`ChangeStateCode`, `ChangeTimeZone`, `ChangeCustomValues`, `ChangeLatitude`, `ChangeLongitude`
+
+---
+
+## Port
+
+String-based PK (e.g., UN/LOCODE).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `portId` | `string` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `countryCode` | `string` | FK to Country |
+| `stateCode` | `string?` | FK to State |
+| `isAir` | `bool` | Mode flags |
+| `isMariTime` | `bool` | |
+| `isRoad` | `bool` | |
+| `isRail` | `bool` | |
+| `isMail` | `bool` | |
+| `isBorderCrossingPoint` | `bool` | |
+| `isMyCompany` | `bool` | |
+| `portRemarks` | `string?` | |
+| `customValues` | `Dictionary` | jsonb |
+
+**Navigation:** `country`, `state`
+
+---
+
+## Vessel
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `vesselId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `vesselCode` | `string?` | |
+| `carrierId` | `int?` | FK to Contact (carrier) |
+| `countryCode` | `string?` | FK to Country (flag state) |
+
+**Navigation:** `carrier`, `country`. No customValues.
+
+---
+
+## CustomCode
+
+Organization-specific lookup codes (Schedule D, Schedule K, etc.).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | |
+| `description` | `string` | |
+| `isCommonlyUsed` | `bool` | |
+| `codeType` | `CustomCodeTypes` enum | ScheduleD, ScheduleK |
+
+No customValues.
+
+---
+
+## ModeOfTransportation
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `modeOfTransportationId` | `int` | PK |
+| `organizationId` | `int` | |
+| `description` | `string` | e.g., "Air", "Ocean", "Ground" |
+| `customValues` | `Dictionary` | jsonb |
+
+Referenced by Rate, Lane, Discount, and Order (via `customValues.modeOfTransportationId`).

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

@@ -0,0 +1,77 @@
+# Job Entity Field Reference
+
+Job groups related orders and accounting transactions.
+
+## Job
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `jobId` | `Guid` | PK (UUID) |
+| `organizationId` | `int` | Tenant scope |
+| `jobNumber` | `string` | Business-facing number |
+| `description` | `string?` | |
+| `isDraft` | `bool` | |
+| `customerId` | `int?` | FK to Contact |
+| `divisionId` | `int?` | FK to Division |
+| `employeeId` | `int?` | FK to Contact |
+| `jobStatusId` | `int?` | FK to JobStatus |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `customer` | `Contact?` |
+| `division` | `Division?` |
+| `employee` | `Contact?` |
+| `jobStatus` | `JobStatus?` |
+
+### Collections
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orders` | `[Order]` | Via JobOrder join |
+| `accountingTransactions` | `[AccountingTransaction]` | Via JobAccountingTransaction join |
+| `commodities` | `[Commodity]` | Direct FK |
+
+### GraphQL Computed
+
+- `getJobOrders(filter)` — orders via JobOrder join
+
+---
+
+## JobOrder (Join Entity)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `jobId` | `Guid` | FK to Job |
+| `orderId` | `int` | FK to Order |
+
+No customValues. No audit fields (uses BaseEntity, not AuditableEntity).
+
+---
+
+## JobStatus
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `jobStatusId` | `int` | PK |
+| `organizationId` | `int` | |
+| `jobStatusName` | `string` | |
+| `priority` | `int` | |
+| `statusStage` | `StatusStage` enum | Pending=1, InProgress, Completed |
+| `customValues` | `Dictionary` | jsonb |
+
+---
+
+## StatusStage Enum
+
+Used by JobStatus, OrderStatus, ContactStatus:
+
+| Value | Int |
+|-------|-----|
+| `Pending` | 1 |
+| `InProgress` | 2 |
+| `Completed` | 3 |

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

@@ -0,0 +1,85 @@
+# Notification Entity Reference
+
+Real-time notification system. Notifications are org-scoped with per-user read tracking via `UserNotification`.
+
+## Notification
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `notificationId` | `int` | PK |
+| `organizationId` | `int` | FK to Organization |
+| `title` | `string` | Required |
+| `message` | `string?` | Body text, supports Markdown |
+| `type` | `NotificationType` | System=0, OrderUpdate=1, TaskAssignment=2, Alert=3, Info=4 |
+| `priority` | `NotificationPriority` | Low=0, Normal=1, High=2, Urgent=3 |
+| `targetUserId` | `string?` | If set, targets one user; if null, broadcasts to all active org users |
+| `entityType` | `string?` | Linked entity type (e.g. "Order", "Job") |
+| `entityId` | `int?` | Linked entity PK |
+| `expiresAt` | `DateTime?` | Optional expiration |
+| `created` / `lastModified` | `DateTime` | Audit fields (from `AuditableEntity`) |
+| `createdBy` / `lastModifiedBy` | `string` | Audit fields |
+
+### Domain Methods
+
+- `ChangeTitle(string)`, `ChangeMessage(string?)`, `ChangeType(NotificationType)`, `ChangePriority(NotificationPriority)`, `ChangeExpiresAt(DateTime?)`
+
+---
+
+## UserNotification
+
+Per-user read state join entity.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `userNotificationId` | `int` | PK |
+| `notificationId` | `int` | FK to Notification |
+| `userId` | `string` | FK to ApplicationUser |
+| `isRead` | `bool` | Default false |
+| `readAt` | `DateTime?` | Set when marked read |
+
+### Domain Methods
+
+- `MarkAsRead()` — sets `IsRead = true`, `ReadAt = UtcNow`
+- `MarkAsUnread()` — resets both
+
+---
+
+## GraphQL
+
+### Queries
+
+- `getNotification(organizationId, notificationId)` → single notification for current user (projected from UserNotification)
+- `getNotifications(organizationId, filter?, search?, orderBy?)` → offset-paged list for current user; default sort: `-notification.created`
+- `getUnreadNotificationCount(organizationId)` → int
+
+### Mutations
+
+- `createNotification(organizationId, values)` → creates Notification + UserNotification rows; publishes to subscription topic per user
+- `markNotificationRead(organizationId, notificationId)` → bool
+- `markAllNotificationsRead(organizationId)` → int (count marked)
+- `deleteNotification(organizationId, notificationId)` → DeleteResult
+
+### Subscriptions
+
+- `onNotificationReceived(organizationId, userId)` → real-time via PostgreSQL NOTIFY/LISTEN
+  - Topic: `{organizationId}_{userId}_notifications`
+
+### GraphQL DTO (projected from UserNotification)
+
+Flattens `Notification` + `UserNotification` into single DTO: `notificationId`, `organizationId`, `title`, `message`, `type`, `priority`, `targetUserId`, `entityType`, `entityId`, `expiresAt`, `isRead`, `readAt`, `created`, `createdBy`, `lastModified`, `lastModifiedBy`, plus resolved `createdUser` / `updatedUser`.
+
+---
+
+## Targeting Logic
+
+On `CreateNotification`:
+1. If `targetUserId` is provided → single `UserNotification` row
+2. If null → queries all active `UserEmployee` records in org → one `UserNotification` per user
+3. After save, publishes `NotificationDto` to each user's subscription topic via `INotificationEventSender`
+
+## Infrastructure
+
+- `NotificationConfiguration` — EF Core config: title max length, indexes on `OrganizationId`, composite index on `(OrganizationId, Created DESC)` for paging
+- `UserNotificationConfiguration` — indexes on `UserId`, `NotificationId`, composite on `(UserId, IsRead)`
+- `NotificationEventSender` — uses HotChocolate `ITopicEventSender` to publish to subscription topics
+- Real-time delivery: PostgreSQL `NOTIFY/LISTEN` channel (configured in `DependencyInjection`)

package/skills/cxtms-developer/ref-entity-order-sub.md

@@ -0,0 +1,160 @@
+# Order Sub-Entity Field Reference
+
+## Contents
+- OrderEntity
+- TrackingEvent
+- EventDefinition
+- LinkedOrder
+- OrderDocument
+
+Entities associated with orders: OrderEntity (parties), TrackingEvent, LinkedOrder, OrderDocument.
+
+## OrderEntity
+
+Represents a party role (Shipper, Consignee, Carrier, etc.) on an order.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderEntityId` | `int` | PK |
+| `orderId` | `int` | FK to Order |
+| `contactId` | `int?` | FK to Contact |
+| `contactAddressId` | `int?` | FK to ContactAddress |
+| `nonContactName` | `string?` | Name when no contact linked |
+| `entityType` | `EntityTypes` enum | Shipper, Consignee, Carrier, etc. |
+| `orderEntitySequence` | `int` | Sort order |
+| `isDeleted` | `bool?` | Soft delete |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `contact` | `Contact?` |
+| `contactAddress` | `ContactAddress?` |
+
+### GraphQL Computed
+
+- `contactName` — mapped from `contact.name`
+- `attachments` — filterable collection
+- `getOrderEntityAttachments(idPropertyName, filter, orderBy, search)` — resolver
+
+### Import Behavior (Order/Import)
+
+When importing order entities via `Order/Import@1`:
+- The `contact` and `contactAddress` nested objects are excluded from direct field mapping and processed separately.
+- **ContactAddress matching** uses `ImportOrderOptions.ContactAddressMatchByFields` — scoped to organization and (when persisted) to the resolved contact. Supports Lucene filter-based matching on any ContactAddress field (e.g., `["addressLine", "postalCode"]`). If null/empty, falls back to matching by `contactAddressId` only.
+- Both contacts and contact addresses are cached per import session to prevent duplicate creation.
+
+### EntityTypes Enum
+
+Shipper=0, Consignee=1, Carrier=2, Vendor=3, UltimateConsignee=4, NotifyParty=5, Intermediate=6, ForwardingAgent=7, DestinationAgent=8, PickupFrom=9, DeliverTo=10, DeliveryCarrier=11, ReceivedBy=12, USPPI=13
+
+---
+
+## TrackingEvent
+
+Milestone/tracking event on an order or commodity.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `trackingEventId` | `int` | PK |
+| `eventDefinitionId` | `int` | FK to EventDefinition |
+| `eventDate` | `DateTime?` | When the event occurred |
+| `description` | `string?` | |
+| `location` | `string?` | |
+| `isInactive` | `bool` | |
+| `includeInTracking` | `bool` | Show in tracking UI |
+| `sendEmail` | `bool` | Trigger email notification |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `eventDefinition` | `EventDefinition` |
+
+---
+
+## EventDefinition
+
+Template/type definition for tracking events.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `eventDefinitionId` | `int` | PK |
+| `eventName` | `string` | |
+| `description` | `string?` | |
+| `location` | `string?` | Default location |
+| `isInactive` | `bool` | |
+| `includeInTracking` | `bool` | Default for events |
+| `sendEmail` | `bool` | Default for events |
+| `sendEmailDocumentId` | `int?` | FK to DocumentTemplate |
+| `isAutomaticCreate` | `bool` | Auto-create on triggers |
+| `triggerEventName` | `string?` | Trigger config |
+| `triggerEntityName` | `string?` | |
+| `triggerConditionFields` | `string?` | |
+| `customValues` | `Dictionary` | jsonb |
+
+### GraphQL Resolvers
+
+| Resolver | Arguments | Returns | Description |
+|----------|-----------|---------|-------------|
+| `getContact` | `customValuesKey: String!` | `Contact` | Looks up a Contact by ID stored in `customValues[key]` |
+
+---
+
+## LinkedOrder
+
+Links between orders (source → target).
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `sourceOrderId` | `int` | FK to Order (source) |
+| `targetOrderId` | `int` | FK to Order (target) |
+| `isDeleted` | `bool` | Soft delete |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `sourceOrder` | `Order` |
+| `targetOrder` | `Order` |
+
+---
+
+## OrderDocument
+
+Document template linked to an order for generation.
+
+### Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderDocumentId` | `int` | PK |
+| `orderId` | `int` | FK to Order |
+| `documentTemplateId` | `int?` | FK to DocumentTemplate |
+| `workflowId` | `Guid?` | FK to Workflow (for generation) |
+| `lastGeneratedFile` | `string?` | File path/key |
+| `lastGeneratedTime` | `DateTime?` | |
+| `regenerateOnOrderChange` | `bool` | Auto-regenerate |
+| `metadata` | `Dictionary` | jsonb — auto-populated keys: `orderId`, `orderPickupId`, `orderDeliveryId`, `thirdPartyContactId`, `carrierId` |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `order` | `Order` |
+| `documentTemplate` | `DocumentTemplate?` |
+
+### GraphQL Computed
+
+- `getLinkToDocument(expiresInDays)` — returns signed URL

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

@@ -0,0 +1,183 @@
+# Order Entity Field Reference
+
+## Contents
+- Order Scalar Fields
+- Order Navigation Properties
+- Order Collection Properties
+- Pre-filtered OrderEntity Collections (GraphQL)
+- Order Computed/Resolved GraphQL Fields
+- OrderTypes Enum
+- EntityTypes Enum (for OrderEntity)
+- Order CustomValues
+
+Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.customValues.myField }}`.
+
+## Scalar Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderId` | `int` | Primary key |
+| `organizationId` | `int` | Tenant scope |
+| `orderNumber` | `string` | Business-facing number |
+| `trackingNumber` | `string?` | |
+| `orderType` | `OrderTypes` enum | See enum below |
+| `isDraft` | `bool` | Draft orders excluded from default queries |
+| `orderStatusId` | `int` | FK to OrderStatus |
+| `lastOrderStatusModified` | `DateTime?` | Auto-set on status change |
+| `entityTypeId` | `int?` | FK to EntityType |
+| `divisionId` | `int` | FK to Division |
+| `equipmentTypeId` | `int?` | FK to EquipmentType |
+| `billToContactId` | `int?` | FK to Contact |
+| `employeeContactId` | `int?` | FK to Contact |
+| `salespersonContactId` | `int?` | FK to Contact |
+| `created` | `DateTime` | |
+| `createdBy` | `string` | User ID |
+| `lastModified` | `DateTime` | |
+| `lastModifiedBy` | `string` | User ID |
+
+## Navigation Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderStatus` | `OrderStatus` | `.statusName`, `.statusStage` |
+| `division` | `Division` | `.name` |
+| `equipmentType` | `EquipmentType` | |
+| `billToContact` | `Contact` | Full contact object |
+| `employeeContact` | `Contact` | |
+| `salespersonContact` | `Contact` | |
+| `organization` | `Organization` | |
+| `entityType` | `EntityType` | |
+| `createdUser` | `User` | `.firstName`, `.lastName`, `.email` |
+| `updatedUser` | `User` | |
+
+## Collection Properties
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderEntities` | `[OrderEntity]` | Shipper, Consignee, Carrier, etc. (by `entityType`) |
+| `charges` | `[Charge]` | Direct charges |
+| `orderCommodities` | `[OrderCommodity]` | Join to commodities (has own `customValues`) |
+| `trackingEvents` | `[TrackingEvent]` | Milestones |
+| `orderDocuments` | `[OrderDocument]` | |
+| `jobs` | `[Job]` | |
+| `jobOrders` | `[JobOrder]` | |
+| `orderTags` | `[OrderTag]` | |
+| `orderCarriers` | `[OrderCarrier]` | |
+| `allTags` | `[OrderAllTagsView]` | View: all tags including from commodities |
+| `allRelatedOrders` | `[OrderRelatedOrdersView]` | Orders sharing commodities |
+| `attachmentsSummary` | `OrderAttachmentSummaryView?` | DB view: `.totalCount`, `.hasAny` (active attachments) |
+| `notesSummary` | `OrderNoteSummaryView?` | DB view: `.totalCount`, `.hasAny` (non-deleted notes) |
+| `outgoingLinks` | `[LinkedOrder]` | |
+| `incomingLinks` | `[LinkedOrder]` | |
+
+## Pre-filtered OrderEntity Collections (GraphQL)
+
+These are virtual fields that filter `orderEntities` by type:
+
+| Field | EntityType |
+|-------|------------|
+| `orderEntityCarriers` | Carrier |
+| `orderEntityVendors` | Vendor |
+| `orderEntityPickups` | Shipper |
+| `orderEntityDeliveries` | Consignee |
+| `orderEntityDeliveryCarriers` | DeliveryCarrier |
+| `orderEntityDeliverTo` | DeliverTo |
+| `orderEntityPickupFrom` | PickupFrom |
+| `orderEntityDestinationAgent` | DestinationAgent |
+| `orderEntityForwardingAgent` | ForwardingAgent |
+| `orderEntityIntermediate` | Intermediate |
+| `orderEntityNotifyParty` | NotifyParty |
+| `orderEntityUltimateConsignee` | UltimateConsignee |
+| `orderEntityReceivedBy` | ReceivedBy |
+| `orderEntityUsppi` | USPPI |
+
+## Computed/Resolved GraphQL Fields
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `commoditySummary` | `CommoditySummary` | `.totalWeight`, `.totalPieces`, `.totalQuantity`, `.totalVolume` |
+| `accountingSummary` | `AccountingSummary` | |
+| `getContact(idPropertyName)` | `Contact` | Resolve contact from `customValues[idPropertyName]` |
+| `getPort(idPropertyName)` | `Port` | Resolve port from `customValues[idPropertyName]` |
+| `getVessel(idPropertyName)` | `Vessel` | Resolve vessel from `customValues[idPropertyName]` |
+| `getCountry(idPropertyName)` | `Country` | Resolve country from `customValues[idPropertyName]` |
+| `getRoute(idPropertyName)` | `Route` | Resolve route from `customValues[idPropertyName]` |
+| `getModeOfTransportation(idPropertyName)` | `ModeOfTransportation` | |
+| `getCustomCode(idPropertyName)` | `CustomCode` | |
+| `getRelatedOrderByProperty(idPropertyName)` | `Order` | Resolve related order from `customValues[idPropertyName]` |
+| `getCharge(chargeDescription)` | `Charge` | Single charge by description |
+| `getChargesByChargeType(chargeType)` | `[Charge]` | Charges filtered by type |
+| `getOrderSummary(weightUnit, volumeUnit, dimensionsUnit)` | `OrderSummary` | |
+| `lastTrackingEvent(eventDefinitionName)` | `TrackingEvent` | Most recent |
+| `attachmentsSummary` | `OrderAttachmentSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
+| `notesSummary` | `OrderNoteSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
+| `notesCount(threadFilter)` | `int` | |
+| `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+| `getCommoditiesWithRelatedOrder(orderType!, filter?)` | `[Commodity]` | Leaf commodities linked to related orders of specified type. Traverses commodity hierarchy, excludes wrappers. |
+
+## OrderTypes Enum
+
+| Value | Int | Notes |
+|-------|-----|-------|
+| `Order` | 0 | Generic order |
+| `Quote` | 1 | |
+| `WarehouseReceipt` | 2 | Warehouse order |
+| `Purchase` | 3 | Pickup order |
+| `ParcelShipment` | 4 | |
+| `AirShipmentOrder` | 5 | |
+| `OceanShipmentOrder` | 6 | |
+| `CargoMovement` | 7 | |
+| `EntityType` | 8 | Type defined by EntityType |
+| `PickupOrder` | 9 | |
+| `LoadOrder` | 10 | |
+| `BookingOrder` | 11 | |
+| `Freight` | 12 | |
+| `DeliveryOrder` | 13 | |
+
+## EntityTypes Enum (for OrderEntity)
+
+| Value | Int | Description |
+|-------|-----|-------------|
+| `Shipper` | 0 | Origin party |
+| `Consignee` | 1 | Destination party |
+| `Carrier` | 2 | Transport provider |
+| `Vendor` | 3 | |
+| `UltimateConsignee` | 4 | |
+| `NotifyParty` | 5 | |
+| `Intermediate` | 6 | |
+| `ForwardingAgent` | 7 | |
+| `DestinationAgent` | 8 | |
+| `PickupFrom` | 9 | |
+| `DeliverTo` | 10 | |
+| `DeliveryCarrier` | 11 | |
+| `ReceivedBy` | 12 | |
+| `USPPI` | 13 | US Principal Party in Interest |
+
+## CustomValues
+
+`Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:
+
+```yaml
+# Template expressions
+value: "{{ entity.customValues.myField }}"
+value: "{{ entity.customValues['my-field'] }}"
+
+# NCalc conditions
+conditions:
+  - expression: "isNullOrEmpty([entity.customValues.myField?]) = false"
+
+# Update via Order/Update task
+inputs:
+  orderId: "{{ entity.orderId }}"
+  order:
+    CustomValues.myField: "newValue"        # Dot notation (single field)
+    customValues:                            # Bulk update (merge)
+      field1: "value1"
+      field2: "{{ computed }}"
+```
+
+**Known system customValues keys:**
+- `modeOfTransportationId` / `modeOfTransportationIdDescription` — transport mode
+
+**Resolver pattern** — Many GraphQL fields resolve entities from customValues IDs:
+`getContact(idPropertyName)` reads `customValues[idPropertyName]` as a contact ID and returns the full Contact object. Same pattern for ports, vessels, countries, routes, etc.

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

@@ -0,0 +1,41 @@
+# Organization Entity Reference
+
+Core tenant entity. Each organization represents a company/tenant in the system.
+
+## Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `organizationId` | `int` | PK |
+| `companyName` | `string` | Required |
+| `addressLine` | `string?` | |
+| `addressLine2` | `string?` | |
+| `cityName` | `string?` | |
+| `countryCode` | `string?` | |
+| `stateCode` | `string?` | |
+| `postalCode` | `string?` | |
+| `phoneNumber` | `string?` | |
+| `faxNumber` | `string?` | |
+| `uniqueId` | `Guid` | Immutable external identifier |
+| `slug` | `string?` | URL-friendly identifier for Public API routes (lowercase, hyphenated) |
+| `isDeleted` | `bool` | Soft delete |
+| `customValues` | `Dictionary?` | jsonb, merged on update |
+| `created` / `lastModified` | `DateTime` | Audit fields (from `AuditableEntity`) |
+| `createdBy` / `lastModifiedBy` | `string` | Audit fields |
+
+## Slug
+
+Generated by `SlugGenerator`: lowercased, non-alphanumeric stripped, spaces→hyphens, truncated to max length. Numeric suffix appended for uniqueness.
+
+Used by `PublicApiOrganizationResolver` to resolve org by slug or GUID in Public API URLs. Cached 1h sliding.
+
+## Relationships
+
+- `AspNetUserEmployees` — users belonging to this organization
+
+## Domain Methods
+
+- `ChangeSlug(string?)` — trims and lowercases
+- `ChangeCompanyName(string)`, `ChangeAddressLine(string?)`, etc.
+- `ChangeCustomValues(Dictionary?)` — merges into existing values
+- `DeleteOrganization()` — sets `IsDeleted = true`