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.

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