Tracking event Workflow Tasks

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

Create Tracking event

task: "TrackingEvent/Create@1"
name: createTrackingEvent
inputs: 
  values:
    customValues: "{{ customValues }}"
    description: "{{ description }}"
    eventDate: "{{ eventDate }}"
    eventDefinitionId: "{{ eventDefinitionId }}"
    includeInTracking: "{{ includeInTracking }}"
    isInactive: "{{ isInactive }}"
    location: "{{ location }}"
    sendEmail: "{{ sendEmail }}"
outputs:
  - name: trackingEvent
    mapping: "trackingEvent"

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
  }
}

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