How to create and manage events

An event is created every time an associated rule or a geofence is triggered by a device ingestion.

The tracking service has four different event categories:

Event Type	Description
Geofence	Created whenever a device enters or exits an associated geofence
Sensor	Created when the reported sensor data triggers one of the sensor rules
Rule	Created when the reported device behavior triggers a configured rule
Shipment Status	Created when shipment status changes

Sensor events have the following types:

Event Type	Description
Battery, humidity, pressure and temperature events	Created when a corresponding sensor reading goes enters or exceeds the permitted range
Acceleration	Created when an acceleration sensor reading crosses the acceleration threshold
Attach	Created when a device is attached or detached
Tamper	Created when device cover is opened or closed

Rule events have the following types:

Event Type	Description
Dwelling	Created when a device has dwelled inside an associated geofence for longer than allowed
Detention	Created when a device has been stationary for longer than allowed, regardless whether the device is inside or outside of any geofence
Utilization	Created when a device starts moving after being stationary
Stock	created when number of devices in a geofence crosses one of the defined stock limits
Offline	Created when a device is late in sending its next planned ingestion
Online	Created when device starts ingesting data again
Shipment schedule	Created when a shipment deviates from the specified shipment schedule
Shipment estimate change	created when a newly calculated Estimated Time of Arrival (ETA) or Estimated Time of Departure (ETD) differs from the previous estimate, indicating a potential adjustment in the shipment's schedule

Both new events and existing events are managed via the events endpoint.

Events can also be consumed through the events output stream, which can offer performance advantages.

Shipment status change event

In addition to events managed via the rules and events APIs, the Shipment status change event is also available from the events output stream. This particular event is only accessible via the stream.

When this event is enabled for a project, all events are published to the events output stream for all shipments of the project whenever a change occurs in the content, shipment status, or segment status.

However, this does not apply to shipment ETD/ETA value changes, which can be tracked with a Shipment estimate change rule and event.

The Shipment status change event structure follows the same structure as other events, with the same common properties as other events, but with the values as:

Property	Type	Description
`trackingId`	String	Shipment ID
`timestamp`	Integer	The exact timestamp of the change, returned as milliseconds elapsed since 1 January 1970 00:00:00 UTC.
`ruleId`	`uuid`	For shipment state change events, the value is always `00000000-0000-4000-8000-000000000001`.
`initialState`	Boolean	For shipment state change events, the value is always `false`

These events only contain the properties of the shipment/segment objects which have changed, and the properties needed to identify the changed shipment/segment, which are:

Shipment ID in trackingId property.
Optional shipment ID in external systems in extOrderId property.

Specific segments are identified with:

Segment ID in segmentId property.
Index of the segment in the shipment in segmentIndex property. Note that the first index in a shipment is 0, the second index is 1, and so on.
Origin location of the segment with origin location ID and optional external location ID (origin.id and origin.extId properties).
Destination location of the segment with destination location ID and optional external location ID (destination.id and destination.extId properties).

For more information, refer to the shipment state change event OpenAPI schema below.

shipmentStateChangeEvent Schema

openapi: 3.0.0

info:
  version: 1.0.0
  title: Shipment state change event
  description: |
    Definition for the shipmentStateChangeEvent. This event is not available
    from Tracking REST APIs, but only from the events output stream.

    Even though this event is not available from the REST APIs, the event
    structure follows the same format as the other events so that all events
    published to output stream have the same common properties from `baseEvent`.

    These events are published for shipment/segment status changes and also
    for shipment/segment content changes. Events contain only the changed
    properties and those properties which are needed to identify the changed
    shipment/segment.

    These events are NOT published for the shipment/segment ETA estimate changes.
    There is a separate shipmentEtaChange event for that purpose.

paths: {}

components:
  schemas:

    shipmentStateChangeEvent:
      title: Shipment state change event
      description: |
        Events generated when shipment status or other shipment data changes.
      allOf:
        - $ref: '#/components/schemas/baseEvent'
        - $ref: '#/components/schemas/shipmentStateChangeProperties'

    baseEvent:
      # These properties are common for all events, but descriptions here
      # are specific to shipment state change event.
      properties:
        trackingId:
          description: Shipment ID
          type: string
          pattern: '^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
        timestamp:
          type: integer
          description: Change time. Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
          minimum: 2
          maximum: 4102448400000
        ruleId:
          type: string
          format: uuid
          description: |
            UUIDv4 which identifies the rule which triggers the event.
            For shipment state change events this has value `00000000-0000-4000-8000-000000000001`.
        initialState:
          description: Always false for the shipment state change event.
          type: boolean
      required:
        - trackingId
        - timestamp
        - ruleId
        - initialState

    shipmentStateChangeProperties:
      type: object
      properties:
        eventSource:
          type: string
          enum:
            - shipmentStateChange
        eventType:
          type: string
          enum:
            - SHIPMENT_CREATED
            - SHIPMENT_DELETED
            - SHIPMENT_UPDATED
        extOrderId:
          description: Unique identifier for identifying the shipment in external systems
          type: string
          maxLength: 50
        changeReason:
          description: Reason why the event was triggered
          allOf:
            - $ref: '#/components/schemas/shipmentChangeReason'
        changes:
          description: Shipment and segment changes
          allOf:
            - $ref: '#/components/schemas/shipmentChangeData'
      required:
        - eventSource
        - eventType
        - changeReason

    shipmentChangeReason:
      description: Reason for a shipment or segment state change.
      type: string
      enum:
        - apiShipmentCreate         # manual, shipment created with API
        - apiShipmentCreateFromPlan # manual, shipment created with API from plan
        - apiShipmentDelete         # manual, shipment deleted with API
        - apiShipmentIngest         # manual, shipment ingested with API
        - apiShipmentUpdate         # manual, shipment updated with API
        - apiShipmentUpdateTracker  # manual, shipment tracker updated with API
        - apiSegmentUpdate          # manual, segment updated with API
        - geofenceEvent             # automated, state change because of geofence event
        - locationEvent             # automated, state change because of location event
        - shipmentExpired           # scheduled, shipment expired
        - shipmentOngoingTooLong    # scheduled, shipment has been ongoing too long
        - shipmentPendingAutoStart  # scheduled, shipment has not started within given autostart interval

    shipmentChangeData:
      type: object
      properties:
        name:
          description: Name of the shipment
          type: string
          maxLength: 50
        description:
          description: Description of the shipment
          type: string
          maxLength: 1000
        autoStart:
          description: |
            A boolean parameter defining whether the shipment starts upon exiting the first origin
            location.
          type: boolean
        subShipment:
          description: Flag telling if shipment is a subShipment.
          type: boolean
        status:
          description: Status of the shipment.
          allOf:
            - $ref: '#/components/schemas/shipmentSegmentStatus'
        createdAt:
          description: Timestamp indicating when the shipment has been created
          allOf:
            - $ref: '#/components/schemas/dateV4'
        startedAt:
          description: Timestamp indicating when the shipment started
          allOf:
            - $ref: '#/components/schemas/dateV4'
        endedAt:
          description: Timestamp indicating when the shipment ended
          allOf:
            - $ref: '#/components/schemas/dateV4'
        providedEtd:
          description: User provided ETD for the shipment
          allOf:
            - $ref: '#/components/schemas/dateV4'
        providedEta:
          description: User provided ETA for the shipment
          allOf:
            - $ref: '#/components/schemas/dateV4'
        calculatedEtd:
          description: Calculated ETD for the segment
          allOf:
            - $ref: '#/components/schemas/dateV4'
        calculatedEta:
          description: Calculated ETA for the segment
          allOf:
            - $ref: '#/components/schemas/dateV4'
        ruleIds:
          description: Array of `ruleId`s to associate with the shipment
          type: array
          items:
            type: string
            format: uuid
            description: Must be a valid UUIDv4.
            maxItems: 10
        shipmentPlanId:
          description: A shipment plan's id that the shipment was generated from.
          type: string
          pattern: '^SHPP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
        segments:
          description: Array containing the segment details
          type: array
          items:
            description: Segment details
            type: object
            properties:
              extSegmentId:
                description: External segment ID
                type: string
                maxLength: 50
              segmentId:
                description: Segment ID
                type: string
                pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
              segmentIndex:
                description: Segment index (starting from 0)
                type: integer
                minimum: 0
              name:
                description: Name of the segment
                type: string
                maxLength: 50
              description:
                description: Description of the segment
                type: string
                maxLength: 1000
              status:
                description: Status of the segment.
                allOf:
                  - $ref: '#/components/schemas/shipmentSegmentStatus'
              transportMode:
                description: Transport mode of the segment
                type: string
                enum:
                  - car
                  - truck
                  - sea
                  - air
                  - barge
                  - rail
                  - railTruck
                  - truckRail
                  - bargeTruck
                  - truckBarge
                  - undefined
              trackingId:
                type: string
                minLength: 1
                maxLength: 50
                description:
                  This is a unique ID associated with the device data in HERE Tracking.
                  The `trackingId` gets assigned to a device when the device is claimed by a user.
              origin:
                description: Origin location of this segment
                allOf:
                  - $ref: '#/components/schemas/locationIds'
              destination:
                description: Destination location of this segment
                allOf:
                  - $ref: '#/components/schemas/locationIds'
              startedAt:
                description: Timestamp indicating when this segment started
                allOf:
                  - $ref: '#/components/schemas/dateV4'
              endedAt:
                description: Timestamp indicating when this segment ended
                allOf:
                  - $ref: '#/components/schemas/dateV4'
              providedEtd:
                description: User provided ETD for the segment
                allOf:
                  - $ref: '#/components/schemas/dateV4'
              providedEta:
                description: User provided ETA for the segment
                allOf:
                  - $ref: '#/components/schemas/dateV4'
              calculatedEtd:
                description: Calculated ETD for the segment
                allOf:
                  - $ref: '#/components/schemas/dateV4'
              calculatedEta:
                description: Calculated ETA for the segment
                allOf:
                  - $ref: '#/components/schemas/dateV4'

    shipmentSegmentStatus:
      description: Shipment/segment status
      type: string
      enum:
        - pending
        - ongoing
        - completed
        - cancelled

    dateV4:
      type: string
      format: date-time

    locationIds:
      description: Location IDs
      type: object
      properties:
        id:
          description: Location ID
          type: string
          pattern: '^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
        extId:
          description: External location ID in external service
          type: string
          minLength: 1
          maxLength: 100
      required:
        - id

Enabling Shipment status change event

The Shipment status change event event can be enabled for all shipments of the project using project features API by setting the parameter data.shipments.enableStateChangeEvents to true. The request must be sent with a project-scoped user token.

The following is an example of a curl request for enabling the feature:

userScopedToken="<project scoped user token>"
curl -X PATCH "https://tracking.hereapi.com/registry/v2/features" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer '"${userScopedToken}" \
  -d '{"data":{"shipments":{"enableStateChangeEvents":true}}}'