Entity

An Entity is the base building block for structuring trips.

All objects, actions, an events are modeled as entities. An entity may for example represent a trip, a load/unload action (stop), a consignment, or a goods line. Entities themselves may be the parent of one or multiple entities in a one-to-many relationship.

Each entity must always consist of at least a foreignId, and flag field may be complemented with additional fields as described in the table below.

Property	Required	Type	Description
foreignId	true	string	Unique identifier used to identify an entity. This value must always stay the same when referencing the same entity. Most often, an internal database ID is used.
flag	true	string	Used to specify the type of entity. There is no predefined list of possible flags. You can determine the flags yourself to match your trip structure. Some commonly used flags are: `trip`-> entity representing a trip `stop`-> entity representing a load/unload stop `goods_line`-> entity representing a goods line like an Europallet
rank	false	long	Used to determine the order in which entities are displayed in the app. Entities are sorted in ascending order meaning entities with a lower rank will appear first. When no rank is provided entities are displayed in the order in which they are received.
title	false	string	A human-readable name for the entity. When left empty the `foreignId` is used as title
meta	false	JsonObject	Field used to provide additional (meta) data for an entity. For example, an address, contact details, references, action descriptions (load/unload), etc. There are no predetermined fields for the values within the metadata. You may add as many fields as you want as long as the `meta`fields contains a valid JSON object. Each value should be provided with a unique key. Combining multiple values in a single field is not supported.
entities	false	Entity array	To model a hierarchy, an entity may contain one or multiple entities as children. A possible commonly used hierarchy is trip -> stop -> goods line

Examples

Each of the examples below contains a JSON snippet together with a brief explanation.

The example below contains a possible JSON structure for an entity representing a trip. The entities field contains an array of entities to create a logical hierarchy. In this example the trip entity contains 2 entities representing a stop.

{ "foreignId": "1234", "flag": "trip", "rank": 20240115, "title": "3", "meta": { "driver": "John Doe", "driverNumber": 1, "vehicle": "TE-ST-01", "date": "15-01-2024" }, "entities": [ { "foreignId": "1234-1", "flag": "stop", "rank": 1, "title": "Load action 1234-1", "meta": { "type": "load", "date": "15-01-2024", "address": { "name": "FleetGO Barneveld", "address": "Anthonie Fokkerstraat 43A", "zipCode": "3772 MP", "city": "Barneveld", "countryCode": "NL", "latitude": 52.12818, "longitude": 5.56580 } }, "entities": [] }, { "foreignId": "LO-1234-2", "flag": "stop", "rank": 2, "title": "Unload action 1234-2", "meta": { "type": "unload", "date": "15-01-2024", "address": { "name": "FleetGO Barneveld", "address": "Anthonie Fokkerstraat 43A", "zipCode": "3772 MP", "city": "Barneveld", "countryCode": "NL", "latitude": 52.12818, "longitude": 5.56580 } }, "entities": [] } ] }

The example below contains a possible JSON structure for an entity representing a stop.

{
  "foreignId": "1234-1",
  "flag": "stop",
  "rank": 1,
  "title": "Load action 1234-1",
  "meta": {
    "type": "load",
    "date": "12-02-2020",
    "address": {
      "name": "FleetGO Barneveld",
      "address": "Anthonie Fokkerstraat 43A",
      "zipCode": "3772 MP",
      "city": "Barneveld",
      "countryCode": "NL",
      "latitude": 52.12818,
      "longitude": 5.56580
    }
  },
  "entities": []
}

The example below contains the possible JSON structure for an entity representing a goods line

{
  "foreignId": "1234-2-9876",
  "flag": "goods_line",
  "meta": {
    "name": "Europallet with smartphones",
    "unit": "pallet",
    "weight": 1000.0,
    "amount": 2,
    "ldm": 4
  },
  "title": "Smartphones",
  "entities": []
}

Last modified: 16 May 2024