Data Format - Actions

Example

Great that you made it so far already. In our previous pages, you saw the basic structure of a message, external attributes to a trip and vehicle and actor data we might send you. We have one object left, which is the most complicated with a lot of nested structures, the actions.

A single action describes that something is occurring at a specific time (whether in the past, present or future) and optionally at a specific location. Action events can typically be used in any lifecycle phase. This makes sense, since you can say an action can be planned, projected, actually happening or be realized. A single action object typically involves only one entity at a time.

Copy
Copied
{
  "id": "2a8af6c6-e4d5-5dfb-9532-e8b17c3ffd88",
  "name": "DCX|2020|32-2-888",
  "externalAttributes": {},
  "vehicle": {},
  "actors": [],
  "actions": [
    {
      "entity": {
        "id": "79d841c8-90f7-5c36-8ac4-9630d4979888",
        "externalAttributes": {
          "exceptionLateThreshold": "2020-10-14T09:11Z",
          "stopType": "DC",
          "externalStopId": "DCX|2020|32-2-888|DC",
          "label": "1",
          "returnFlowAllowed": "false",
          "cancelled": "false",
          "customer_data_taskNumber": "2284",
          "sequence": "1",
          "exceptionEarlyThreshold": "2020-10-14T07:56Z",
          "mutated": "false",
          "isOriginallyPlanned": "false",
          "administrative": "false"
        },
        "lifecycle": "planned",
        "location": {
          "entity": {
            "id": "8f14e45f-ceea-367a-9a36-aabb4bea2543",
            "name": "DCX",
            "externalAttributes": {
              "locationId": "7",
              "globalLocationNumber": "9210400000329",
              "customerLocationIdentifier": "NL1234AB0001"
            },
            "geoReference": {
              "lat": 52.1561113,
              "lon": 5.3878266,
              "type": "latLonPointGeoReference"
            },
            "administrativeReference": {
              "name": "DCX",
              "street": "Auroraweg 1",
              "postalCode": "1234AB",
              "city": "Eindhoven",
              "country": "NLD"
            }
          },
          "associationType": "inline"
        },
        "startTime": "2020-10-14T08:56:00Z",
        "endTime": "2020-10-14T09:18:00Z",
        "actions": [
          {
            "entity": {
              "id": "6162b713-fa89-38b2-bb27-6d1e6bbd1c70",
              "transportEquipment": {
                "entity": {
                  "id": "fb4a5174-8ab6-3061-8764-10e0794e2e39",
                  "externalAttributes": {
                    "licensePlate": "OS-44-HH",
                    "trailerType": "EURO_13_60_KOEL"
                  },
                  "equipmentType": "trailer"
                },
                "associationType": "inline"
              },
              "actionType": "attachTransportEquipment"
            },
            "associationType": "inline"
          },
          {
            "entity": {
              "id": "73385065-7f7d-3138-a908-f29e1da4458f",
              "lifecycle": "planned",
              "consignment": {
                "uuid": "03dee193-9f36-569f-b061-269f22bdd112",
                "entityType": "consignment",
                "associationType": "reference"
              },
              "actionType": "load"
            },
            "associationType": "inline"
          }
        ],
        "actionType": "stop"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "12576db0-1b92-3e96-b4b9-cc8a7bc4b27f",
        "from": {
          "uuid": "8f14e45f-ceea-367a-9a36-aabb4bea2543",
          "entityType": "location",
          "associationType": "reference"
        },
        "to": {
          "entity": {
            "id": "571d3a94-20bf-3921-9f65-b643d0003ccc",
            "name": "John's Shop",
            "externalAttributes": {
              "locationId": "1",
              "globalLocationNumber": "8710400011",
              "customerLocationIdentifier": "NL8891DG017X"
            },
            "geoReference": {
              "lat": 52.1561113,
              "lon": 5.3878266,
              "type": "latLonPointGeoReference"
            },
            "administrativeReference": {
              "name": "John's Shop",
              "street": "Septemberstraat 9",
              "postalCode": "8891DG",
              "city": "Almere",
              "country": "NLD"
            }
          },
          "associationType": "inline"
        },
        "actions": [

        ],
        "actionType": "move"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "b1c0acef-1108-5555-ae6f-bf8c96f9e74b",
        "externalAttributes": {
          "exceptionLateThreshold": "2020-10-14T10:11Z",
          "timeWindowStart": "2020-10-14T09:00Z",
          "stopType": "WINKEL",
          "timeWindowEnd": "2020-10-14T11:00Z",
          "externalStopId": "147531300",
          "label": "2",
          "returnFlowAllowed": "false",
          "cancelled": "false",
          "customer_data_taskNumber": "2284",
          "sequence": "2",
          "exceptionEarlyThreshold": "2020-10-14T08:56Z",
          "mutated": "false",
          "isOriginallyPlanned": "false",
          "administrative": "false"
        },
        "lifecycle": "planned",
        "location": {
          "uuid": "571d3a94-20bf-3921-9f65-b643d0003ccc",
          "entityType": "location",
          "associationType": "reference"
        },
        "startTime": "2020-10-14T09:56:00Z",
        "endTime": "2020-10-14T10:40:00Z",
        "actions": [
          {
            "entity": {
              "id": "308abb7f-138e-353d-bf3c-719589308730",
              "lifecycle": "planned",
              "consignment": {
                "entity": {
                  "id": "ff71d089-9c7e-347b-a70c-2d4a911facb5",
                  "externalAttributes": {
                    "externalShipmentId": "147531300HH-drop",
                    "externalOrderId": "482e4dea-d389-38ec-8057-55778241ac71",
                    "shipmentNumber": "1",
                    "cancelled": "false"
                  },
                  "type": "HB",
                  "goods": [],
                  "freightDocumentReferences": [
                      {
                          "type": "eCMR",
                          "authorityReference": "NL000000159999TFL",
                          "provider": {
                              "entity": {
                                  "id": "be307f84-2149-3686-8029-7598ad798888",
                                  "name": "transfollow"
                              },
                              "associationType": "inline"
                          },
                          "status": "draft",
                          "externalAttributes": {
                              "externalId": "316333",
                              "freightDocumentUrl": "https://portal.partner.transfollow.com/#/view/316333"
                          }
                      }
                  ]
                },
                "associationType": "inline"
              },
              "actionType": "unload"
            },
            "associationType": "inline"
          },
          {
            "entity": {
              "id": "def5197e-a9e6-35d1-868e-dce26b3d99c1",
              "lifecycle": "planned",
              "consignment": {
                "uuid": "66086228-f456-550c-a16b-5cd56edd4599",
                "entityType": "consignment",
                "associationType": "reference"
              },
              "actionType": "load"
            },
            "associationType": "inline"
          }
        ],
        "actionType": "stop"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "c9d6bcba-b514-3c07-82b7-9dfb596e0bfd",
        "from": {
          "uuid": "571d3a94-20bf-3921-9f65-b643d0003ccc",
          "entityType": "location",
          "associationType": "reference"
        },
        "to": {
          "entity": {
            "id": "868a4b62-023a-3d9d-b827-6152d8c5aaaa",
            "name": "Enterprise",
            "externalAttributes": {
              "locationId": "999",
              "globalLocationNumber": "8710400000123",
              "customerLocationIdentifier": "NL8213BT07RH"
            },
            "geoReference": {
              "lat": 52.1561113,
              "lon": 5.3878266,
              "type": "latLonPointGeoReference"
            },
            "administrativeReference": {
              "name": "Enterprise",
              "street": "Zazastraat 7",
              "postalCode": "8213BT",
              "city": "Oss",
              "country": "NLD"
            }
          },
          "associationType": "inline"
        },
        "actions": [

        ],
        "actionType": "move"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "56effb57-8455-5471-ad02-ce8049839d2e",
        "externalAttributes": {
          "exceptionLateThreshold": "2020-10-14T11:28Z",
          "stopType": "MC",
          "externalStopId": "DCX|2020|32-2-888|MC",
          "label": "3",
          "returnFlowAllowed": "false",
          "cancelled": "false",
          "customer_data_taskNumber": "2284",
          "sequence": "3",
          "mutated": "false",
          "isOriginallyPlanned": "false",
          "administrative": "false"
        },
        "lifecycle": "planned",
        "location": {
          "uuid": "868a4b62-023a-3d9d-b827-6152d8c5aaaa",
          "entityType": "location",
          "associationType": "reference"
        },
        "startTime": "2020-10-14T11:13:00Z",
        "endTime": "2020-10-14T11:31:00Z",
        "actions": [
          {
            "entity": {
              "id": "97aced43-f2a8-31bf-ace3-67707adc88b8",
              "lifecycle": "planned",
              "consignment": {
                "entity": {
                  "id": "62ed5339-e537-361c-bb09-1e38df306364",
                  "externalAttributes": {
                    "externalShipmentId": "DCX|2020|32-2-888|MC|1",
                    "externalOrderId": "2165ecf7-55dd-3afa-938a-2161b901bdef",
                    "shipmentNumber": "1",
                    "cancelled": "false"
                  },
                  "type": "emballage",
                  "goods": []
                },
                "associationType": "inline"
              },
              "actionType": "unload"
            },
            "associationType": "inline"
          }
        ],
        "actionType": "stop"
      },
      "associationType": "inline"
    }
  ]
}

Actions entity scheme

object

Container object

id
string <uuid>

Universally Unique Identifier to the action

object
stopId
string

As known in Simacan's environment

externalStopId
string

As known by the planning source

sequence
number

Provides an explicit sequence of the stops (typically only for convenience since it also be deduced from other sets of information)

stopType
string

Categorizes stops, typically linked to the type of location that's visited

stopNumber
number

Number of the stop as known in Simacan's database

timeWindowStart
string <date-time>

Start time of the agreed timewindow for the action

timewindowEnd
string <date-time>

End time of the agreed timewindow for the action

label
string

Label of the stop as seen in the Control Tower. Often filled with a letter for stops at the start, end, or additions-during-execution

remark
string

Remark on stop level, available to all parties with access to the planninginformation of the stop (typically delivered location and/or driver)

mutated
boolean

Indicates if current stop information has been updated or edited by users. Typically duplicate with isOriginallyPlanned

cancelled
boolean

Indicates if the stop has been cancelled. If true any actions for this stop can be safely ignored. However, If the specific stop hasn't been cancelled, it could still be that the complete trip has. Cancelled stops are also visible at the bottom in the trip details screen

geofenceArrival
string <date-time>

Date time for which we found a first vehicle's location inside the then active geofence. One of the triggers for determining the arrival time

geofenceDeparture
string <date-time>

Date time for which we found a first vehicle's location outside the then active geofence. One of the triggers for determining the departure time

exceptionEarlyThreshold
string <date-time>

Expected arrival before this time triggered highlighting of the trip in the Control Tower during execution. Realized arrival before this threshold highlights the trip after its completion

exceptionLateThreshold
string <date-time>

Expected arrival after this time triggered highlighting of the trip in the Control Tower during execution. Realized arrival after this threshold highlights the trip after its completion

breakTime
string

Start time of a break, duration of the break should be inferred from the other times on that hierarchical depth

administrative
boolean

Indicates if a stop serves an administrative purpose. If true the stop is there for administrative purposes and doesn't have to be realised. Any actions for that stop can be safely ignored

isOriginallyPlanned
boolean

Indicates if current stop information has been updated or edited by users. Typically duplicate with mutated

originalPlannedStart
timestamp

Start time of a stop when it was inserted before any mutations took place

originalPlannedEnd
timestamp

End time of a stop when it was inserted before any mutations took place

returnFlowAllowed
boolean

Boolean used to indicate goods can be picked up for that particular stop. Typically only expected to be true when it is not a oneWay trip

expectedTrafficDelay
number

Background information from shipper to carriers if traffic delay is expected on the drive

customer_data_taskNumber
number

Tasknumber from customer data

stopTags
Array of arrays
Deprecated
lifecycle
string

Indicates current lifecycle-phase. In most cases planned

startTime
string <date-time>

Start time of the timewindow for the action in ISO format.

endTime
string <date-time>

End time of the timewindow for the action in ISO format

object

The consignment that is the subject of this action

object

Container object

id
string <uuid>

Universally Unique Identifier to the consignment

type
string

Free text to describe type of consignment e.g. FTL, Full Truck Load, LTL Less than Truck Load, bulk, reverse logistics orders, pick up order, delivery order.

object

The various goods that need to be transported, together they are part of this consignment.

object

Simacan e-CMR extension

associationType
string

See the basics for an explanation

associationType
string

See the basics for an explanation

actionType
string

Typically Stop / Move / Load / Unload, based on this you can expect a different set of information

object

Nested Location Object

associationType
string

See the basics for an explanation

id
string <uuid>

Universally Unique Identifier to the location

name
string

Name set for the location

object
object
object
object
actions
object

Nested actions object