Entity Exploration

In this lesson you will use the cxtms gql CLI tools to discover and inspect CX entity types directly from the live GraphQL schema. This skill pays off every time you need to know an exact field name or understand what a type looks like before writing a workflow or module.

---

Prerequisites

You must be logged in to your CX organization:

bash
1npx cxtms login

Verify the active organization before running queries:

bash
1npx cxtms whoami

---

Step 1 — Discover the Order Type

Start by finding the GraphQL type that represents an Order in query results:

bash
1npx cxtms gql types --filter order

Example output (truncated):

1OrderGqlDto
2OrderCommodityGqlDto
3OrderEntityGqlDto
4OrderStatusGqlDto
5OrderTagGqlDto
6OrderAttachmentSummaryGqlDto
7OrderRelatedOrdersView
8...

The primary order type used in orders query results is OrderGqlDto. Inspect it:

bash
1npx cxtms gql type OrderGqlDto

You will see all scalar fields, navigation properties, and computed resolvers — including customValues, orderEntities, charges, trackingEvents, and the getPort, getContact, getModeOfTransportation resolvers.

---

Step 2 — Inspect the Contact Type

bash
1npx cxtms gql type ContactGqlDto

Key things to verify:

• contactType field (enum: Customer, Carrier, Vendor, Driver, Employee, etc.)
• contactAddresses collection (each address has its own customValues)
• customValues at the contact level

To see the ContactAddress type:

bash
1npx cxtms gql type ContactAddressGqlDto

---

Step 3 — Find Sub-Entity Types

List order sub-entities:

bash
1npx cxtms gql types --filter orderentity

Inspect the OrderEntity type:

bash
1npx cxtms gql type OrderEntityGqlDto

Confirm:

• entityType field (enum: Shipper=0, Consignee=1, Carrier=2, etc.)
• contactId, contactAddressId
• customValues

Inspect TrackingEvent:

bash
1npx cxtms gql type TrackingEventGqlDto

---

Step 4 — Audit Fields

Audit fields are inherited from AuditableEntity. Verify they exist on OrderGqlDto:

These fields are present on all primary entities (Order, Contact, Commodity, AccountingTransaction) and most lookup entities. JobOrder is a notable exception — it uses BaseEntity and has no audit fields.

---

Step 5 — EntityKind Mapping Table

The entityKind identifier is used in module YAML (entityKind:) and Flow workflow triggers (entity.name:). It does not map one-to-one with entity type names:

The orderType and contactType enums are filters within the EntityKind, not separate EntityKinds. A workflow triggered on EntityKind: Order fires for all order types — you then filter by entity.orderType in a condition if you need a specific type.

---

Step 6 — Query an Order and See customValues

Use the orders root query with a known orderId. Replace 1 with your organization ID and 123 with a real order ID:

bash
1npx cxtms query '{
2  orders(organizationId: 1, filter: "orderId:123", take: 1) {
3    items {
4      orderId
5      orderNumber
6      orderType
7      customValues
8      created
9      createdBy
10      orderEntities {
11        entityType
12        contactId
13        contact { name }
14      }
15      trackingEvents {
16        eventDefinition { eventName }
17        eventDate
18        location
19      }
20    }
21  }
22}'

The customValues field returns a raw JSON object. Any key-value pairs stored on the order appear here. If customValues is null or {}, the order has no custom fields set.

---

Step 7 — Explore the Commodity Type

bash
1npx cxtms gql type CommodityGqlDto

Verify:

• containerCommodityId (self-referencing parent)
• containerCommodities collection (children)
• weightByTotal, valueByTotal flags
• customValues
• orderCommodities — each has its own customValues

Query a commodity with its order associations:

bash
1npx cxtms query '{
2  commodities(organizationId: 1, filter: "commodityId:456", take: 1) {
3    items {
4      commodityId
5      description
6      pieces
7      weight
8      weightUnit
9      customValues
10      orderCommodities {
11        orderId
12        customValues
13      }
14    }
15  }
16}'

Notice that Commodity.customValues and OrderCommodity.customValues are separate dictionaries. Each can hold different data.

---

Summary

In this lesson you:

1. Used cxtms gql types --filter to discover type names in the live schema
2. Used cxtms gql type to inspect fields on OrderGqlDto, ContactGqlDto, OrderEntityGqlDto, and CommodityGqlDto
3. Identified the audit fields common to all primary entities
4. Learned the EntityKind mapping: Order covers all order types, Contact covers all contact types
5. Ran a live GraphQL query to see customValues data on a real order
6. Confirmed that OrderCommodity.customValues is separate from Commodity.customValues

Use cxtms gql type <TypeName> as your first step whenever you start building a new module or workflow — never guess field names.