Activity Message

An Activity message is generated when the drivers current activity changes.

The Drivers App contains a feature to keep track of the activity of the driver. This should not be confused with activities within a trip. The activity tracking feature is a completely separate feature and still works without trips.

Activity tracking starts as soon as the driver starts its shift with the "Start trip" activity. During a shift there is always just one active activity. Starting a new activity automatically ends the previous activity. As a result, 2 Activity messages are generated when switching activity

A message for finishing the current activity
A message for starting the new activity

The data field of an Activity message always contains the properties described below.

Property	Nullable	Type	Description
id	false	string	A unique identifier (UUIDv4) for this activity record. The finish activity message has the same ID as the start activity message, because they both reference the same activity.
activity	false	string	The name of the activity. By default, the English name of the activity is used. The language can be changed upon request.
code	false	integer	A unique identifier for a type of activity. It is recommended to use this value for identifying activities instead of the `activity` field. The possible values depends on the activities configured in the app. A full list may be provided upon request.
startTime	false	string	ISO 8601 formatted timestamp of when the activity was started.
startTimeMillis	false	long	Unix timestamp (milliseconds) of when the activity was started.
endTime	true	string	ISO 8601 formatted timestamp of when the activity was finished. When an activity has not yet been finished, this field is `null`.
endTimeMillis	true	long	Unix timestamp (milliseconds) of when the activity was finished. When an activity has not yet been finished, this field is `null`.
foreignId	true	string	If an activity is started/finished between arriving at and signing-off a stop, this field contains the foreignId of related Entity.
questionnaire	true	QuestionnaireAnswers	Sine activities may be configured with a questionnaire. If this is the case, this field contains the answers to the questionnaire.

Co-driver

When the co-driver functionality is enabled both the main driver and the co-driver share the same activities. Each activity message is just sent once. The OriginObject contains both the driverNumber of the main driver (driverNumber) and the co-driver (coDriverNumber)

There are a few important events which cause the driver/co-driver to change. These events are:

A co-driver joins the main driver during a shift
The main driver and co-driver switch places
A co-driver leaves the driver during a shift

All of the above events also trigger an activity change. Some examples are included below.

Examples

The examples below contain different types of Activity messages. Each example contains a JSON snippet together with a brief explanation.

The example below contains a possible Activity message generated when the driver starts the "Unloading" activity.

{
  "type": "Activity",
  "data": {
    "id": "12b54def-b44d-4995-b2be-bceab7fc853d",
    "activity": "Unloading",
    "code": 21,
    "startTime": "2024-01-17T12:35:33.326Z",
    "startTimeMillis": 1705494933326,
    "endTime": null,
    "endTimeMillis": null
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 250000
  },
  "messageTime": "2024-01-17T12:35:34.769Z"
}

The example below contains a possible Activity message generated when the driver finishes the "Unloading" activity.

{
  "type": "Activity",
  "data": {
    "id": "12b54def-b44d-4995-b2be-bceab7fc853d",
    "activity": "Unloading",
    "code": 21,
    "startTime": "2024-01-17T12:35:33.326Z",
    "startTimeMillis": 1705494933326,
    "endTime": "2024-01-17T12:54:12.031Z",
    "endTimeMillis": 1705496052031
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 250000
  },
  "messageTime": "2024-01-17T12:54:12.213Z"
}

The example below contains a possible Activity message generated when the driver starts the "Waiting" activity.

In this example both the foreignId and questionnaire fields contains a value. The foreignId field refers to the stop Entity this activity is related to. The questionnaire field contains the answers to a questionnaire asked when starting the activity.

{
  "type": "Activity",
  "data": {
    "id": "3809223b-6e04-4221-8989-f069e12f0384",
    "activity": "Waiting",
    "code": 38,
    "startTime": "2024-01-17T12:54:12.031Z",
    "startTimeMillis": 1705496052031,
    "endTime": null,
    "endTimeMillis": null,
    "foreignId": "1234-1",
    "questionnaire": {
      "reason": "Example reason for waiting",
      "expectedDuration": 25
    }
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": "111"
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 250000
  },
  "messageTime": "2024-01-17T12:54:12.393Z"
}

The example below contains a possible Activity message generated when a co-driver joins during a shift.

In this example both the driverNumber and coDriverNumber fields contain a value. The value in coDriverNumber is the driver number of the co-driver that joined the main driver during a shift.

{
  "type": "Activity",
  "data": {
    "id": "ba9d1358-97e0-4d43-b662-75604572412b",
    "activity": "Passenger login",
    "code": 190,
    "foreignId": null,
    "startTime": "2024-12-11T10:46:26.566Z",
    "startTimeMillis": 1733913986566,
    "endTime": null,
    "endTimeMillis": null,
    "questionnaire": {}
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 0.0,
    "bearing": 0.0
  },
  "origin": {
    "appId": 60000146,
    "deviceId": "358240051111110",
    "driverNumber": "2",
    "coDriverNumber": "1"
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 0
  },
  "messageTime": "2024-12-11T10:46:26.580Z"
}

The example below contains a possible Activity message generated when the main driver and co-driver swap places.

In this example the driver with driver number 1 (previously the co-driver) becomes the main driver. The driver with driver number 2 (previously the main driver) becomes the co-driver.

{
  "type": "Activity",
  "data": {
    "id": "c9fa217d-bff9-4960-9922-850ac7caa5a7",
    "activity": "Driver swap",
    "code": 191,
    "foreignId": null,
    "startTime": "2024-12-11T10:52:08.878Z",
    "startTimeMillis": 1733914328878,
    "endTime": null,
    "endTimeMillis": null,
    "questionnaire": {}
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 0.0,
    "bearing": 0.0
  },
  "origin": {
    "appId": 60000146,
    "deviceId": "358240051111110",
    "driverNumber": "1",
    "coDriverNumber": "2"
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 0
  },
  "messageTime": "2024-12-11T10:52:08.911Z"
}

The example below contains a possible Activity message generated when the co-driver leaves the main driver during a shift.

In this example the co-driver (with driver number 2) leaves the main driver (with driver number 1) during the shift.

{
  "type": "Activity",
  "data": {
    "id": "03d9f67b-4c38-46fb-89b1-e190463c8601",
    "activity": "Passenger logout",
    "code": 192,
    "foreignId": null,
    "startTime": "2024-12-11T11:50:42.912Z",
    "startTimeMillis": 1733917842912,
    "endTime": null,
    "endTimeMillis": null,
    "questionnaire": {}
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 0.0,
    "bearing": 0.0
  },
  "origin": {
    "appId": 60000146,
    "deviceId": "358240051111110",
    "driverNumber": "1",
    "coDriverNumber": "2"
  },
  "vehicle": {
    "licensePlate": "AA-BB-12",
    "odometer": 0
  },
  "messageTime": "2024-12-11T11:50:42.950Z"
}

Last modified: 11 December 2024