Tracking event Workflow Tasks

Tracking event tasks are used to create, update, delete, and bulk import Tracking events.

Create Tracking event

Creates a tracking event and associates it with an order, commodity, or both. Resolves the event definition by name and auto-creates it if it does not exist.

task: "TrackingEvent/Create@1"
name: createTrackingEvent
inputs:
  organizationId: "{{ organizationId }}"
  orderId: "{{ orderId }}"
  eventDefinitionName: "Picked Up"
  includeInTracking: true
  sendEmail: false
  description: "Package picked up at origin"
  location: "New York, NY"
  eventDate: "{{ eventDate }}"
  skipIfExists: true
  customValues:
    carrier: "UPS"

Parameters

Parameter	Type	Required	Default	Description
organizationId	int	Yes	-	Organization ID
orderId	int	No	-	Order ID to associate the tracking event with. Either orderId or commodityId must be provided
commodityId	int	No	-	Commodity ID to associate the tracking event with. Either orderId or commodityId must be provided
eventDefinitionId	int	No	-	ID of an existing event definition. Takes precedence over eventDefinitionName when both are provided
eventDefinitionName	string	No	-	Name of the event definition. If no matching definition exists, one is auto-created. Either eventDefinitionId or eventDefinitionName must be provided
commodityIds	List<int>	No	-	Explicit list of commodity IDs to link this tracking event to. IDs not belonging to the order are silently dropped. Takes precedence over autoLinkToCommodities
includeInTracking	bool	No	false	Include in tracking display
sendEmail	bool	No	false	Send email notification
description	string	No	-	Event description
location	string	No	-	Event location
eventDate	DateTime	No	Current UTC time	Date/time of the event
skipIfExists	bool	No	false	Skip creation if a tracking event with the same event definition already exists on the order or commodity
customValues	object	No	-	Custom key-value pairs
eventDefinitionValues	object	No	-	Values for auto-creating the event definition when it does not exist (see below)

Event Definition Values

When eventDefinitionName does not match an existing event definition, one is created automatically. Use eventDefinitionValues to control the defaults for the new definition:

Property	Type	Default	Description
description	string	-	Default description for the event definition
location	string	-	Default location for the event definition
customValues	object	-	Custom key-value pairs for the event definition
includeInTracking	bool	false	Include in tracking display
sendEmail	bool	false	Send email notification
isInactive	bool	false	Whether the event definition is inactive
isAutomaticCreate	bool	false	Whether the event definition auto-creates

task: "TrackingEvent/Create@1"
name: createTrackingEvent
inputs:
  organizationId: "{{ organizationId }}"
  orderId: "{{ orderId }}"
  eventDefinitionName: "Customs Cleared"
  eventDefinitionValues:
    description: "Customs clearance completed"
    includeInTracking: true
    sendEmail: true

note

This task does not return any outputs. Use TrackingEvent/Get@1 to retrieve the created event if needed.

Get Tracking event

task: "TrackingEvent/Get@1"
name: getTrackingEvent
inputs: 
  trackingEventId: "123"

outputs:
  - name: trackingEvent
    mapping: "trackingEvent"

Update Tracking event

task: "TrackingEvent/Update@1"
name: updateTrackingEvent
inputs: 
  trackingEventId: "123"
  values: 
    customValues: "{{ customValues }}"
    description: "{{ description }}"
    eventDate: "{{ eventDate }}"
    eventDefinitionId: "{{ eventDefinitionId }}"
    includeInTracking: "{{ includeInTracking }}"
    isInactive: "{{ isInactive }}"
    location: "{{ location }}"
    sendEmail: "{{ sendEmail }}"

Delete Tracking event

task: "TrackingEvent/Delete@1"
name: deleteTrackingEvent
inputs:
  trackingEventId: "123"

Import Tracking Events

Bulk import tracking events for an order with duplicate detection and automatic event definition creation.

task: "TrackingEvent/Import@1"
name: importTrackingEvents
inputs:
  orderId: "{{ orderId }}"
  events: "{{ events }}"
  matchByFields:
    - "eventDefinitionName"
    - "eventDate"
  skipIfExists: true
  createEventDefinitions: true
  eventDefinitionDefaults:
    includeInTracking: true
    sendEmail: false
outputs:
  - name: importResult
    mapping: "result"

Parameters

Parameter	Type	Required	Default	Description
orderId	int	Yes	-	The order ID to import tracking events for
events	List	Yes	-	Array of event objects to import
matchByFields	List<string>	No	["eventDefinitionName", "eventDate"]	Fields to match existing events for duplicate detection
skipIfExists	bool	No	true	Skip importing if a matching event already exists
createEventDefinitions	bool	No	true	Auto-create missing event definitions
eventDefinitionDefaults	object	No	null	Default values for auto-created event definitions
matchByEventDefinition	List<string>	No	null	Fields to match EventDefinition by CustomValues instead of EventName

Event Object Properties

Each event in the events array can have the following properties:

Property	Type	Required	Description
eventDefinitionName	string	Yes	Name of the event definition
eventDate	DateTime	No	Date/time of the event
description	string	No	Event description
location	string	No	Event location
includeInTracking	bool	No	Include in tracking display
sendEmail	bool	No	Send email notification
customValues	object	No	Custom key-value pairs

Output Result

{
  "result": {
    "added": 5,
    "updated": 0,
    "skipped": 2,
    "failed": 0,
    "total": 5,
    "errors": []
  }
}

Using matchByEventDefinition

The matchByEventDefinition parameter enables matching EventDefinitions by CustomValues fields instead of EventName. This is useful for carrier event translation tables.

task: "TrackingEvent/Import@1"
name: importCarrierEvents
inputs:
  orderId: "{{ orderId }}"
  events:
    - eventDefinitionName: "Carrier Event"
      eventDate: "{{ eventDate }}"
      customValues:
        carrierId: 123
        carrierEventCode: "D"
        carrierDescription: "DELIVERED"
  matchByEventDefinition:
    - "customValues.carrierId"
    - "customValues.carrierEventCode"
  matchByFields:
    - "customValues.carrierId"
    - "customValues.carrierEventCode"
    - "eventDate"
  createEventDefinitions: true
  eventDefinitionDefaults:
    eventName: "Unknown"
    includeInTracking: true
outputs:
  - name: importResult
    mapping: "result"

Behavior when matchByEventDefinition is provided:

1. Extracts specified field values from input event's customValues
2. Finds EventDefinition where CustomValues matches on all specified fields
3. If not found and createEventDefinitions=true:
   • Creates EventDefinition with EventName from eventDefinitionDefaults.eventName
   • Builds EventDefinition.CustomValues by first layering eventDefinitionDefaults.customValues, then overwriting with the matched field values (match-by fields win on key conflicts)

Note: The matchByFields parameter also supports customValues.* fields for TrackingEvent duplicate detection.

tip

Tracking events can also be imported as part of order data using Order/Import@1. When importing orders with embedded trackingEvents, the same import logic (deduplication, event definition creation, custom values matching) is used. This is convenient when importing orders and their tracking events together in a single workflow step.

Auto-Link to Commodities

When a tracking event is added to an order (via OrderTrackingEvent/Create@1, TrackingEvent/Import@1, or Order/Import@1), it is automatically linked to first-level commodities of that order. First-level commodities are those where ContainerCommodityId is null (not nested inside a container).

Precedence for commodity linking (highest to lowest):

1. commodityIds input on OrderTrackingEvent/Create@1 — links exactly the specified commodity IDs that belong to the order; IDs not on the order are silently dropped
2. autoLinkToCommodities input on OrderTrackingEvent/Create@1 — per-task override that enables or disables auto-linking for a single task invocation
3. Org config tms.trackingEvents.autoLinkToCommodities — organization-wide default (enabled by default)

This behavior is enabled by default and can be disabled per-organization using an OrganizationConfig with config name tms.trackingEvents:

{
  "configName": "tms.trackingEvents",
  "customValues": {
    "autoLinkToCommodities": false
  }
}

tip

OrderTrackingEvent/Create@1 also accepts per-task autoLinkToCommodities and commodityIds inputs that override this org-wide default. See Auto-Link to Commodities for details.

Example Tracking event Workflow

workflow:
  name: "Tracking event / Create and Manage Example"
  description: "Create, retrieve, update, and delete a tracking event"
  version: "1.0"
  executionMode: "Sync"

inputs:
  - name: "orderId"
    type: "int"
    displayName: "Order ID"
    required: true
  - name: "eventDefinitionName"
    type: "string"
    displayName: "Event definition name"
    required: true
  - name: "description"
    type: "string"
    displayName: "Description"
    required: false
  - name: "location"
    type: "string"
    displayName: "Location"
    required: false
  - name: "eventDate"
    type: "Date"
    displayName: "Event date"
    required: false
  - name: "includeInTracking"
    type: "boolean"
    displayName: "Include in tracking"
    required: false
    defaultValue: "true"
  - name: "sendEmail"
    type: "boolean"
    displayName: "Send email"
    required: false
    defaultValue: "false"

activities:
  - name: "createTrackingEventActivity"
    description: "Create Tracking event"
    steps:
      - task: "TrackingEvent/Create@1"
        name: createTrackingEvent
        inputs:
          organizationId: "{{ organizationId }}"
          orderId: "{{ orderId }}"
          eventDefinitionName: "{{ eventDefinitionName }}"
          description: "{{ description }}"
          location: "{{ location }}"
          eventDate: "{{ eventDate }}"
          includeInTracking: "{{ includeInTracking }}"
          sendEmail: "{{ sendEmail }}"
          skipIfExists: true

Import Tracking Events

Bulk import tracking events from external data sources (carrier APIs, EDI, etc.).

task: "TrackingEvent/Import@1"
name: importTrackingEvents
inputs:
  orderId: "{{ orderId }}"
  events:
    - eventCode: "PICKUP"
      eventDate: "2024-01-15T10:00:00Z"
      location: "New York, NY"
      description: "Package picked up"
    - eventCode: "IN_TRANSIT"
      eventDate: "2024-01-16T08:00:00Z"
      location: "Philadelphia, PA"
      description: "In transit to destination"
outputs:
  - name: trackingEvents
    mapping: "trackingEvents"

Inputs

Parameter	Type	Required	Description
orderId	int	Yes	Order ID to associate tracking events with
events	array	Yes	Array of tracking event objects to import
events[].eventCode	string	Yes	Event definition code
events[].eventDate	datetime	Yes	Date/time of the event
events[].location	string	No	Location description
events[].description	string	No	Event description