TransFollow freight document Lifecycle

1.Freight document lifeCycle

Creating a freight document.

Freight documents are created by an accountholder that will be known as the submitter of this document. The submitter must be logged in. Creation is done by a call POST /freightdocuments providing a request body that contains at least all the mandatory attributes. The API Endpoint Specifications describe what these are. The roles of Consignor, PlaceOfTakingOver and Consignee are mandatory. A Carrier role may be included from the start or added later, while the freight document is in draft. Roles can be occupied by accounts or by email addresses of people without an account. When a freight document is created everyone with a role is notified about this fact. When a person has a role in the freight document (via an email address) and does not have a TransFollow account, the user is informed via email and is also informed that they can create an account. All parties will have role-specific separate access to the freight document, according to their permissions. A freight document can be created in draft, which means some changes still are allowed. Or it is created in state issued.

Delegating the original role's rights to a different account.

Every user that has the original role on a freight document can delegate his or her rights - of a specific role within this freight document - to another account. Delegation can be done on account level or in the context of one freight document. In case of an account delegation the DELEGATE receives the rights until the rights are withdrawn (for every existing and new freight document). If an account has more roles than one each role can be delegated separately (at account level or per freight document). The original account can share his rights (e.g. to sign for an approval as carrier) with another account. This account will receive all default (belonging to the role) rights, including the DELEGATE right itself. The original account will still have all rights as well. The delegate account can itself delegate its newly received rights to a third account.

Structured Goods.

Besides a 'goods' description (text) attribute it is possible to add a collection of structured Goods. When describing the goods on the freight document either the goods description can be used or a (number of) structured Goods item(s) can be added. Offering both types of 'goods' for the same document will be refused. Structured goods objects can contain goods (type GOOD) and/or returnable transport items (type RTI). The objects have a predefined set of fields, some of which are mandatory. See the API specification for details.

Changing a freight document.

Freight documents can only be changed by the submitter of the document and only as long as the document has the draft status. The submitter cannot replace the roles of Consignor, Consignee or Carrier, only add them while in draft status. If replacing them is needed a new freight document must be created. The submitter can change many things on the freight document. The API specification details all of them. Updating is done by a call PUT /freightdocuments/{id}, providing a request body that holds a complete set of desired sub-entities and attributes. Please note that all sub-entities that are not included in the request body will be processed as empty, which can lead to loss of data. See the API Endpoint Specifications for an example.

Cancelling a freight document

Only freight documents with status draft can be cancelled by calling POST /freightdocuments/{freightDocumentId}/cancel. Cancelled freight documents will be not visible anymore for any of the roles.

Issuing a freight document.

Freight documents can be issued by the submitter of this document only. Issuing means that the document changes status from draft to issued or is created as issued. The submitter account must have sufficient credits to be able to issue a freight document. Changing from draft is done by a call to POST /freightdocuments/{id}/issue. From this moment on the document is in business, the main content of the document is legally fixed for the rest of it's lifecycle. Only a select set of data, like ETA's (Estimated Time of Arrival) associated with the freight document may change. The reason for this is that all parties legally must deal with the same 'contract'. Additions in the form of comments (with optional attachments) are only allowed in the context of a cargo transfer from one party to the next.

TransFollow Process

Signing a freight document

A freight document starts it's legal life with status issued. At every main transfer of cargo it's status must change further. After being picked up by the carrier it will become in transit. After being handed over at the destination it will become delivered. During the in transit state cargo can be transferred to subsequent carriers. At every cargo transfer a process of 'signing' for - or approving of - the transfer must be excecuted by the two parties involved, one of which is always the carrier. It is therefore not possible to approve a cargo transfer directly between consignor (sender) and consignee (receiver of the goods). The approval process is described below.

Following the status of a freight document

A freight document can be updated with status information, approvals and comments. The carrier can also update the ETA attributes while being underway. All this information is available to every party (or subsitute party) that is assigned a role in the freight document. Relevant changes can be viewed by polling the freight document or by accessing it after a notification. A client system can get notified through a so-called subscription on a freight document. When a status changes for the freight document (to ISSUED, TRANSIT or DELIVERED for example) the subscription will execute a POST call to a callback URL at the clients system.

2.Approval of a freight document on cargo transfer


Before transferring goods the parties involved might want to add a comment to the freight document. This is possible, but only on the device of the carrier and only after the document is ISSUED. Pictures can be added to a comment as attachments.

Starting a transfer approval

The two parties present at every transfer, more specific at collection, delivery or transfer between carriers, will start the approval process in the same manner every time. The carrier (the carrier that transfers the goods in case of two subsequent carriers) will select the right freight document on his device and chooses which cargo transfer is being approved. He then has a choice between an implicit approval - without evidence - and an approval with evidence. An implicit approval can be used when the other party is not present yet but is trusted to pick up the goods later. When not implicit, the two parties have a choice between two types of evidence: a TransFollow Approval (TFA) or a Sign-on-Glass Approval (SGA). If they agree on the right method they can start the chosen procedure even without being online.

Approval Activity

The TFA is the strongest method in terms of provability and non-repudiation. It requires that both (or at least the carrier) counterparties have access to the FreightDocument in issued or transit state. Since the parties were known in their respective roles (Consignor, Carrier or Consignee) when the freight document was issued, they have access to a subset of transactional secrets s1, s2 and s3. Together with authenticating secrets these form the raw ingredients for the TFA approval handshake.

The signing process of a freight document requires two mobile devices. One device is used by the party that represents the consignor or consignee and needs the TF Android app to be installed. The second device is used by the carrier and it needs an mobile application in which the TF Android App integration interface is integrated. If integration with a TMS is not required, the carrier can also use the TF Android app as a standalone app.