Tracking event Workflow Tasks

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

Create Tracking event

Creates a single tracking event and attaches it to an order, a commodity, or both. If the referenced event definition does not exist, it can be auto-created by supplying eventDefinitionValues.

At least one of orderId or commodityId must be provided.

Input Parameters

Parameter	Type	Required	Description
organizationId	int	Yes	The organization ID
eventDefinitionId	int	Conditional	ID of an existing event definition. Required if eventDefinitionName is not provided.
eventDefinitionName	string	Conditional	Name of the event definition. Required if eventDefinitionId is not provided. If no event definition matches this name and eventDefinitionValues is supplied, a new one is created.
orderId	int	Conditional	The order to attach the event to. At least one of orderId, commodityId, or commodityIds must be provided.
commodityId	int	Conditional	A single commodity to attach the event to. Can be combined with orderId and/or commodityIds.
commodityIds	List<int>	Conditional	Multiple commodities to attach the event to. Each listed commodity gets linked to the created event. Can be combined with orderId and/or commodityId.
description	string	No	Event description. Overrides the event definition's description.
location	string	No	Event location. Overrides the event definition's location.
includeInTracking	bool	No	Include in public tracking display
sendEmail	bool	No	Send email notification
eventDate	DateTime	No	Event date (converted to UTC; defaults to current UTC time)
customValues	object	No	Custom key-value pairs
skipIfExists	bool	No	Skip if an event with the same event definition already exists on the order (or commodity)
eventDefinitionValues	object	No	Values used to auto-create the event definition when eventDefinitionName does not match an existing one

YAML Structure

task: "TrackingEvent/Create@1"
name: createTrackingEvent
inputs:
  organizationId: "{{ organizationId }}"
  orderId: "{{ orderId }}"              # at least one of orderId/commodityId/commodityIds is required
  commodityId: "{{ commodityId }}"      # optional single commodity link
  commodityIds: "{{ commodityIds }}"    # optional multi-commodity link (List<int>)
  eventDefinitionId: "{{ eventDefinitionId }}"  # or use eventDefinitionName
  eventDefinitionName: "Picked Up"
  description: "Package picked up from origin"
  location: "Memphis, TN"
  includeInTracking: true
  sendEmail: false
  eventDate: "{{ eventDate }}"
  customValues: "{{ customValues }}"
  skipIfExists: false

Auto-Link to Commodities

When orderId is provided, the created tracking event is also linked to all first-level commodities of that order (commodities where ContainerCommodityId is null). This is controlled by the same tms.trackingEvents.autoLinkToCommodities org config described in Auto-Link to Commodities below.

Any commodities supplied via commodityId or commodityIds are linked in addition to the auto-linked first-level commodities.

note

Unlike OrderTrackingEvent/Create@1, TrackingEvent/Create@1 does not accept a per-task autoLinkToCommodities override — only the org-wide default applies to the auto-link step. However, you can explicitly target commodities by passing commodityId / commodityIds.

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
   • Copies only the matched fields to EventDefinition.CustomValues

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 all first-level commodities of that order. First-level commodities are those where ContainerCommodityId is null (not nested inside a container).

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 TrackingEvent Example Workflow" 
  description: "Create Tracking event Example Workflow"
  version: "1.0" 
  executionMode: "Sync"

inputs:
  - name: "customValues"
    type: "string,Object"
    displayName: "Custom values"
    description: "Custom values"
    multiple: false
    required: false
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.customValues"
  - name: "description"
    type: "string"
    displayName: "Description"
    description: "Description"
    multiple: false
    required: false
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.description"
  - name: "eventDate"
    type: "Date"
    displayName: "Event date"
    description: "Event date"
    multiple: false
    required: false
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.eventDate"
  - name: "eventDefinitionId"
    type: "EventDefinition"
    displayName: "Event definition id"
    description: "Event definition id"
    multiple: false
    required: true
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.eventDefinitionId"
  - name: "includeInTracking"
    type: "boolean"
    displayName: "Include in tracking"
    description: "Include in tracking"
    multiple: false
    required: true
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.includeInTracking"
  - name: "isInactive"
    type: "boolean"
    displayName: "Is inactive"
    description: "Is inactive"
    multiple: false
    required: true
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.isInactive"
  - name: "location"
    type: "string"
    displayName: "Location"
    description: "Location"
    multiple: false
    required: false
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.location"
  - name: "sendEmail"
    type: "boolean"
    displayName: "Send email"
    description: "Send email"
    multiple: false
    required: true
    defaultValue: ""
    additionalProperties:
      visible: true
      mapping: "trackingEvent.sendEmail"

outputs:
  - name: trackingEvent
    mapping: "createTrackingEventActivity.createTrackingEvent.trackingEvent"

activities:
  - name: "createTrackingEventActivity"
    description: "Create Tracking event"
    steps:
      - task: "TrackingEvent/Create@1"
        name: createTrackingEvent
        inputs: 
          trackingEvent:
            customValues: "{{ customValues }}"
            description: "{{ description }}"
            eventDate: "{{ eventDate }}"
            eventDefinitionId: "{{ eventDefinitionId }}"
            includeInTracking: "{{ includeInTracking }}"
            isInactive: "{{ isInactive }}"
            location: "{{ location }}"
            sendEmail: "{{ sendEmail }}"
        outputs:
          - name: trackingEvent
            mapping: "trackingEvent"
  - name: "getTrackingEventActivity"
    description: "Get TrackingEvent"
    steps:
      - task: "TrackingEvent/Get@1"
        name: getTrackingEvent
        inputs: 
          trackingEventId: "{{ createTrackingEventActivity.createTrackingEvent.trackingEvent.trackingEventId }}"
        outputs:
          - name: trackingEventFromGet
            mapping: "trackingEvent"
  - name: "updateTrackingEventActivity"
    description: "Update TrackingEvent"
    steps:
      - task: "TrackingEvent/Update@1"
        name: updateTrackingEvent
        inputs: 
          trackingEventId: "{{ getTrackingEventActivity.getTrackingEvent.trackingEvent.trackingEventId }}"
          trackingEvent:
            customValues: "{{ customValues }}"
            description: "{{ description }}"
            eventDate: "{{ eventDate }}"
            eventDefinitionId: "{{ eventDefinitionId }}"
            includeInTracking: "{{ includeInTracking }}"
            isInactive: "{{ isInactive }}"
            location: "{{ location }}"
            sendEmail: "{{ sendEmail }}"
  - name: "deleteTrackingEventActivity"
    description: "Delete TrackingEvent"
    steps:
      - task: "TrackingEvent/Delete@1"
        name: deleteTrackingEvent
        inputs: 
          trackingEventId: "{{ getTrackingEventActivity.getTrackingEvent.trackingEvent.trackingEventId }}"

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