Skip to content

Document Sharing

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019

Notes:

  • Due to continuous enhancements, some of the screen images in the examples below might be different than what you see on the current level of TradeLens.
  • Before downloading and opening shared documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.

TradeLens provides a framework for sharing trade documents among trade parties, with security, access control and privacy. You can upload, download, edit, and view documents if you have the required permission. The document sharing function means that documents can be stored, viewed, and acted upon by the different parties in a consignment. The permission matrix uses a combination of the party's role and the permission granted for that role to a given document type. See the Data Access Rights section in the TradeLens Data Sharing Specification topic for more details, and the Permissions section below.

Structured and Unstructured Documents

Documents can be uploaded as either structured JSON or unstructured documents. Structured JSON documents are defined through document schemas. The document schema (or template) enables validation of the JSON document during upload. If a structured document is uploaded without a schema, no validation of the structure for the JSON document will be done. Unstructured documents can be PDF or image (JPEG, PNG) files. When an action is taken on a document, a document event is sent by the platform automatically that indicates what action was taken; for example, "Bill of lading available" will be sent when a bill of lading is uploaded.

There are several advantages to uploading structured documents with a schema, beyond the validation of the structure for the document:

  • If you edit the file through the UI, the schema will show any additional fields beyond what you initially provided. Without a schema, the UI can only show you the fields that were present on the initial upload, and you can not add any new fields.
  • Schemas provide a standard layout, the fields are organized, and you will get additional function like the date picker widget from the UI.

Currently supported list of documents

Document Type Document Action Document Events Structured / Unstructured
SEA_WAYBILL Upload Bill of lading available Both
COMMERCIAL_INVOICE Upload Commercial invoice available Both
PACKING_LIST Upload Packing list available Both
BILL_OF_LADING Upload Bill of lading available Unstructured
BOOKING_CONFIRMATION Upload Booking confirmation Unstructured
SHIPPING_INSTRUCTIONS Upload Shipping instructions submitted Unstructured
EXPORT_DECLARATION Upload Export documentation submitted Unstructured
IMPORT_DECLARATION Upload Import documentation submitted Unstructured
HEALTH_CERTIFICATE Upload Cargo geography specific certificate submitted Unstructured
PHYTOSANITARY_CERTIFICATE Upload Cargo geography specific certificate submitted Unstructured
VETERINARY_CERTIFICATE Upload Cargo geography specific certificate submitted Unstructured
FUMIGATION_CERTIFICATE Upload Cargo geography specific certificate submitted Unstructured
INSPECTION_CERTIFICATE Upload Cargo geography specific certificate submitted Unstructured
CERTIFICATE_OF_ANALYSIS Upload Cargo geography specific certificate submitted Unstructured
CERTIFICATE_OF_ORIGIN Upload Certificate of origin available Unstructured
PRO_FORMA_INVOICE Upload Commercial invoice available Unstructured
CONTAINER_ARRIVAL_NOTICE Upload Container arrival notice submitted Unstructured
DANGEROUS_GOODS_REQUEST Upload Dangerous goods request submitted Unstructured
OTHER Upload Other document available Unstructured

An optional docTypeNamespace field is available when uploading a document through the Document Sharing API (this field is set automatically by the Shipment Manager UI based on how the document is uploaded). The docTypeNamespace field is used to specify whether the docType being provided belongs to the TradeLens platform (platform is the default) or if it is user provided (custom).

From the API, if docTypeNamespace is set to platform, the API will ensure the given docType actually exists in the TradeLens platform list. If it does not exist, a validation error will be returned. The Shipment Manager UI will automatically set docTypeNamespace to platform unless the user choses "Custom Document Type" under the document types and provides a name for the document type. If "Custom Document Type" is chosen, the UI will set docTypeNamespace to custom. If the docTypeNamespace is set to custom, then the docType must not be equal to any of the reserved TradeLens platform supported documentation types.

Document events

Document Sharing1b

Versioning

When a new version of a document is uploaded using the same document reference ID, or a structured document is edited, changed, and saved, the version will be incremented. You can edit the last version of a structured document. You can download any version of a document if you have the required permission.

Versions, Structured (JSON) and Unstructured (PDF) documents Document Sharing2b

Immutablity

In addition to being able to download each version of a document, the Shipment Manager UI also shows a Consistency Check message (see the bottom of the following image) to indicate that the document has been verified on the blockchain. Once a document (or a version of a document) is selected, the document will be retrieved from the secure Blockchain Document Store and the hash stored on the blockchain will be compared with a newly generated hash. After this check is complete, the Consistency Check will indicate that the document has been verified on the blockchain and is immutable.

Download option on the left for each version, Consistency Check for the selected document Document Sharing3b

Permissions

Overview

Permission for a document is determined through a combination of the organization's role and the document type. The TradeLens platform will check the authority for the document, based on the organization's role, according to the permission matrix as detailed in the Data Provisioning Obligations and the Data Access Rights sections in the TradeLens Data Sharing Specification. Documents are associated with a consignment and the permissions are determined by the Data Access Rights and the Data Provisioning Obligations in the TradeLens Data Sharing Specification.

  • If the role has an M (mandatory, must be provided for all consignments) or a C (conditional, provided for consignment if available) in the Data Provisioning Obligations table for the document type, and a Y (access granted) in the Data Access Rights table for the document type, then the role has Write permission for the document type in the consignment.

  • If the role is blank (not M or C) in the Data Provisioning Obligations table for the document type, and a Y in the Data Access Rights table for the document type, then the role has Read permission for the document type in the consignment.

  • If the role has N (access not granted) in the Data Access Rights table for the document type, then the role does not have read or write permission to the document type in the consignment.

Example

In this section, we will go through an example to illustrate the permissions for documents within a consignment based on the role of the party. We will use the Shipment Manager UI with two different organizations in a consignment to show how the platform determines the access allowed for some sample documents.

Our two organizations will have the roles of Ocean Carrier and Consignor. The carrier creates the consignment and adds an organization to the consignment as a party with the role of CONSIGNOR. At some point during the shipping process, the carrier will also add transport equipment for the consignment. The carrier can provide the carrier booking number to the consignor so they can see information about the consignment and access documents for the consignment based on their consignor role. The consignor could use the Shipment Manager UI or the APIs to interact with the consignment and documents.

We log into the Shipment Manager UI as the consignor organization, and search for the carrier booking number to find the consignment.

Consignor's view Document Sharing54d

We click on the Documents button (or Full Details and then the Documents tab) and see that no documents have been uploaded yet for the consignment. There might be documents for the consignment, but if we do not have permission for the document type, we will not see them.

Consignor's view Document Sharing41d

We want to upload a Commercial Invoice and a Dangerous Goods document. Since the consignor has permission to upload/write these two document types, if we click Add a New Document, we see them as choices. If you refer back to the Data Provisioning Obligations and the Data Access Rights sections in the TradeLens Data Sharing Specification, you will see that the document types listed are the ones with Write permission for the consignor role (C in the Data Provisioning Obligations, and Y in the Data Access Rights).

Consignor's view Document Sharing42c

We select the Commercial Invoice document type and click Upload or Create as shown in the previous image. In this case, we will upload the file from our computer. We provide a document reference ID, choose the file, and click Upload. As discussed earlier, associating a structured document with a template has advantages, but for our simple example we will not use a template.

Consignor's view Document Sharing43d

The commercial invoice is now shown in the list of documents for the consignment.

Consignor's view Document Sharing44d

We upload the Dangerous Goods document in the same way and see it in the list of documents.

Consignor's view Document Sharing45d Document Sharing46d

Now we will log into the Shipment Manager as the carrier organization and search for the carrier booking number to find the consignment. When we click on the Documents button, we see that for the documents uploaded so far, the carrier has access to see the Dangerous Goods document, but not the Commercial Invoice document. This matches what you will find in the Data Provisioning Obligations and the Data Access Rights sections in the TradeLens Data Sharing Specification. The role of Ocean Carrier has N for the Commercial Invoice document type in the Data Access Rights table, so there is no access for the carrier. The role of Ocean Carrier has Y for the Dangerous Goods document type in the Data Access Rights table, and C for the Dangerous Goods document type in the Data Provisioning Obligations table, so the carrier has Write (and Read) permission.

Carrier's view Document Sharing48d

To illustrate that the carrier has Write permission for the Dangerous Goods document type, we will upload a new version of the Dangerous Goods document. We click Add a New Document as shown in the image above and then select the Dangerous Goods Request document type and click Upload or Create. Notice in the screen image below that the carrier has Write permission to the document types listed (C in the Data Provisioning Obligations table for the document type, and a Y in the Data Access Rights table for the document type).

Carrier's view Document Sharing49c

Since we want this to be an updated version of the same document, we use the same document reference ID.

Carrier's view Document Sharing50d

Notice that the version changes to V2, and the "Modified By" field shows our example carrier (e2e-d) instead of the consignor (gtd-demo).

Carrier's view Document Sharing51d

We also upload a Container Arrival Notice as the carrier organization. Since it is the same process we have already shown, we will not repeat the steps in this example.

The consignor's view from the Documents button for the consignment shows the uploaded documents that the consignor can see.

Consignor's view Document Sharing60d

If we click on the consignment card from the first sceen of the UI, we can see more information. Note: The small warning symbol next to the transport equipment ID (TEID) indicates Dangerous Cargo if you hover over the icon.

Consignor's view Document Sharing55d

If we click on the transport equipment card, we can see details about the events, including the documents that were uploaded. In the image below, we have selected the filter for All Event Types and All Events so we can see both of the Dangerous goods request submitted events for the Dangerous Goods Request documents. If Latest Events is selected, you would see the latest events corresponding to the latest version for each document.

Consignor's view Document Sharing56d

We can click on the document icon to get additional details on the document event. In the image below, we have selected the Commercial Invoice. Notice at the bottom, there is a link to preview the document from the consignor's view.

Consignor's view Document Sharing57d

However, since the carrier does not have permission to view the commercial invoice, the carrier's event detail for the commercial invoice will not have an active link for preview and there will be an "!" to indicate that the document is not available (hovering over the "!" will display a message).

Carrier's view Document Sharing58d

One additional note for our example: When the carrier adds transport equipment for the consignment, additional parties are added to the consignment automatically. These are ports, terminals, and country authorities. The permission matrix as detailed in the Data Provisioning Obligations and the Data Access Rights sections in the TradeLens Data Sharing Specification is also used for these roles.