Entity Message

An Entity message is generated when the state of an Entity changes.

State changes are always the result of an action perform by the driver in the app. By default, the actions described below trigger the generation of an Entity message:

The driver started with a trip (pressing the start trip button)
The driver finished a trip (pressing the end trip button)
The driver arrival at a stop (pressing the arrival button)
The driver cancelled the arrival at a stop (pressing the undo arrival button)
The driver finished at a stop (pressing the sign-off/finish button)

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

Property	Nullable	Type	Description
foreignId	false	string	Contains the `foreignId` of the entity as provided in the trip message sent to the app
flag	false	string	Contains the `flag` of the entity as provided in the trip message sent to the app
checkout	false	CheckoutObject	A CheckoutObject containing all sign-off/questionnaire related data. The content of this field changes depending on the `flag` of the entity

The Entity message can be thought of as a "state update" message. The checkout property of the message will always contain the most recent sign-off/questionnaire state even if certain fields have already been included in a previous Entity message.

For example, upon arrival the checkout fields contains an arrival property.

{
  "foreignId": "1234-1",
  "flag": "stop",
  "checkout": {
    "arrival": "2024-01-17T08:30:05.769Z"
  }
}

On sign-off/departure a new Entity message is generated. This time the checkout field will contain both an arrival property ass well as a signOff property.

{
  "foreignId": "1234-1",
  "flag": "stop",
  "checkout": {
    "arrival": "2024-01-17T08:30:05.769Z",
    "signOff": "2024-01-17T10:22:34.642Z"
  }
}

Based on which fields are present in the checkout property of the message the state of an Entity can be inferred.

A trip with a start, but without an end has been started but not yet finished.
A trip with both a start and end has been finished.
A stop with a arrival, but without an signOff is currently being performed by the driver.

CheckoutObject

The CheckoutObject contains all sign-off/questionnaire data for an Entity.

The checkout object always consists of the properties described below.

Property	Nullable	Type	Description
start	true	string	ISO 8601 formatted timestamp of when the driver started with the trip. This property is only used for entities with a `flag` used for trips.
end	true	string	ISO 8601 formatted timestamp of when the finished with the trip. This property is only used for entities with a `flag` used for trips.
arrival	true	string	ISO 8601 formatted timestamp of when the driver arrived at the stop. This property is only used for entities with a `flag` used for stops.
signOff	true	string	ISO 8601 formatted timestamp of when the driver signs-off/departs from a stop. This property is only used for entities with a `flag` used for stops.
questionnaire	true	QuestionnaireAnswers	A QuestionnaireAnswers object containing all questionnaire answers as key-value pairs.

QuestionnaireAnswers

The QuestionnaireAnswers object contains all questionnaire answers as key-value pairs in a JSON object.

The key represents the question asked, and the value represents the answer given by the user (driver). The list of possible keys depends on the configured questionnaires. The full list of possible keys can be provided upon request.

Most answers can be represented as a primitive value (string, boolean or integer) like the examples below.

{
  "comment": "This is an example comment",
  "break_duration": 10,
  "has_damage": true
}

Some answers require a more complex data-structure like the answer to a question of type 'packaging' (amount received and delivered)

{
  "packaging": [
    {
      "delivered": 8,
      "received": 0,
      "type": "Europallets"
    },
    {
      "delivered": 0,
      "received": 5,
      "type": "Dusseldorfers"
    }
  ]
}

A previous version of the Trip Interface Description included the possibility for photos and signatures to be included in the QuestionAnswers object as a base64 encoded string. This is no longer possible, and has been replaced separate EntityAttachment messages.

Examples

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

The example below contains a possible Entity message generated when the driver started a trip. In this example a questionnaire is configured upon starting the trip asking the driver to inspect the vehicle before departure.

{
  "type": "Entity",
  "data": {
    "foreignId": "1234",
    "flag": "trip",
    "checkout": {
      "start": "2024-01-17T08:30:02.769Z",
      "questionnaire": {
        "vehicleDamaged": true,
        "damageDescription": "Example description of the damage",
        "papersPresent": true
      }
    }
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "TE-ST-12",
    "odometer": 250000
  },
  "messageTime": "2024-01-17T08:30:03.146Z"
}

The example below contains a possible Entity message generated when the driver finished a trip. In this example a questionnaire is configured asking the driver for expenses made during the trip.

As described, the checkout property contains both the answers to the "start trip questionnaire" as the "finished trip questionnaire". The vehicleDamaged, damageDescription and papersPresent fields contain the same values as in the message generated when starting the trip.

{
  "type": "Entity",
  "data": {
    "foreignId": "1234",
    "flag": "trip",
    "checkout": {
      "start": "2024-01-17T08:30:02.769Z",
      "end": "2024-01-17T16:47:13.023Z",
      "questionnaire": {
        "vehicleDamaged": true,
        "damageDescription": "Example description of the damage",
        "papersPresent": true,
        "expensesMade": true,
        "expensesAmount": 10.99,
        "expensesDescription": "Toll charges"
      }
    }
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "TE-ST-12",
    "odometer": 250120
  },
  "messageTime": "2024-01-17T16:47:13.341Z"
}

The example below contains a possible Entity message generated when the driver arrived at a stop. In this example there is no questionnaire configured upon arrival. The questionnaire field is therefore omitted.

{
  "type": "Entity",
  "data": {
    "foreignId": "1234-1",
    "flag": "stop",
    "checkout": {
      "arrival": "2024-01-17T08:52:06.388Z"
    }
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "TE-ST-12",
    "odometer": 250030
  },
  "messageTime": "2024-01-17T08:52:06.918Z"
}

The example below contains a possible Entity message generated when the driver cancelled a stop's arrival.

Cancelling the arrival is only possible after pressing the arrival button. This message can therefore only be generated after generating a message for the arrival. In the arrival message the arrival field contained a timestamp. When cancelling the arrival the arrival field is removed indicating the stop no longer has an arrival timestamp.

{
  "type": "Entity",
  "data": {
    "foreignId": "1234-1",
    "flag": "stop",
    "checkout": {}
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "TE-ST-12",
    "odometer": 250030
  },
  "messageTime": "2024-01-17T08:53:32.276Z"
}

The example below contains a possible Entity message generated when the driver signed-off/departed from a stop.

The questionnaire property contains the answers to the questionnaire configured for the stop.

In addition to the answers present in the questionnaire property, the app might generate multiple EntityAttachment messages.

{
  "type": "Entity",
  "data": {
    "foreignId": "1234-1",
    "flag": "stop",
    "checkout": {
      "arrival": "2024-01-17T08:52:06.388Z",
      "signOff": "2024-01-17T09:12:47.153Z",
      "questionnaire": {
        "shipment_unloaded": false,
        "not_unloaded_reason": "Goods damaged",
        "damage_description": "Example description of the damage"
      }
    }
  },
  "location": {
    "latitude": 52.2531361,
    "longitude": 5.4890928,
    "speedMs": 25,
    "bearing": 75.0
  },
  "origin": {
    "appId": 60000153,
    "deviceId": "358240051111110",
    "driverNumber": "110",
    "coDriverNumber": null
  },
  "vehicle": {
    "licensePlate": "TE-ST-12",
    "odometer": 250030
  },
  "messageTime": "2024-01-17T09:12:47.841Z"
}

Last modified: 16 May 2024