Document Sharing
Copyright IBM Corporation and GTD Solution Inc. 2018, 2022
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.
- See the API Payload Size Restriction section for details on file upload size.
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 shipment, consignment, or transport equipment (TE). 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 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 submitted" will be sent when a bill of lading is uploaded.
Documents can be uploaded to TradeLens through the Shipment Manager UI or through the API. A document can also use an external URL reference if the document is stored outside of TradeLens. The UI will display the URL for an external file and the GET .../documents/{documentId}/metadata - Fetch document metadata API can be used to retrieve the external URL reference by providing the documentId.
If you are using the API to upload documents, you should use the GET .../transactions/{transactionId} - Fetch a transaction Document Sharing API to check the status of the transaction after the upload.
Note: If you are using the API to upload documents and want to validate your documents against the TradeLens platform schemas, you need to specify "gtd-ibm-authority" as the organizationId and find the platform schemas with the GET .../documentSchema Document Sharing API. You can also filter by name and type. For example, "SHIPPING_INSTRUCTIONS" is a platform defined document type. Then you can find the "ACTIVE" schema in the response and make note of the version and id. You can then call the GET .../documentSchema/{documentSchemaId} Document Sharing API using the id to retrieve just that schema.
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 document types (You can use the GET .../documentTypes Platform Constants API to find the list of supported document types.)
| Document Type | Trade Object | Document Events | Structured / Unstructured |
|---|---|---|---|
| SHIPPING_INSTRUCTIONS | Consignment | Shipping Instructions submitted | Both |
| BILL_OF_LADING | Consignment | Bill of Lading issued, submitted, surrendered, switched to paper, transferred | Both |
| SEA_WAYBILL | Consignment | Sea Waybill submitted | Both |
| VERIFY_COPY | Consignment | Verify Copy submitted | Both |
| COMMERCIAL_INVOICE | Shipment | Commercial Invoice submitted | Both |
| PACKING_LIST | Shipment | Packing List submitted | Both |
| BOOKING_CONFIRMATION | Consignment | Booking Confirmation submitted | Unstructured |
| HOUSE_BILL_OF_LADING | Consignment | House Bill of Lading submitted | Unstructured |
| HOUSE_WAYBILL | Consignment | House Waybill submitted | Unstructured |
| FORWARDER_CARGO_RECEIPT | Consignment | Forwarder Cargo Receipt submitted | Unstructured |
| BOOKING_REQUEST | Consignment | Booking Request submitted | Unstructured |
| CONTAINER_ARRIVAL_NOTICE | Consignment | Container Arrival Notice submitted | Unstructured |
| DELIVERY_ORDER | Consignment | Delivery Order submitted | Unstructured |
| MOTOR_CARRIER_LOAD_TENDER | Consignment | Motor Carrier Load Tender submitted | Unstructured |
| IMPORTERS_SECURITY_FILING | Shipment | Importers Security Filing submitted | Unstructured |
| IN_TRANSIT_BOND | Consignment | In Transit Bond submitted | Unstructured |
| ADVANCE_DECLARATION | Shipment | Advance Declaration submitted | Unstructured |
| PRO_FORMA_INVOICE | Shipment | Pro-Forma Invoice submitted | Unstructured |
| EXPORT_DECLARATION | Shipment | Export Declaration submitted | Unstructured |
| IMPORT_DECLARATION | Shipment | Import Declaration submitted | Unstructured |
| HEALTH_CERTIFICATE | Shipment | Health Certificate submitted | Unstructured |
| PHYTOSANITARY_CERTIFICATE | Shipment | Phytosanitary Certificate submitted | Unstructured |
| VETERINARY_CERTIFICATE | Shipment | Veterinary Certificate submitted | Unstructured |
| FUMIGATION_CERTIFICATE | Shipment | Fumigation Certificate submitted | Unstructured |
| INSPECTION_CERTIFICATE | Shipment | Inspection Certificate submitted | Unstructured |
| CERTIFICATE_OF_ANALYSIS | Shipment | Certificate of Analysis submitted | Unstructured |
| CERTIFICATE_OF_ORIGIN | Shipment | Certificate of Origin submitted | Unstructured |
| CARGO_TALLY_SHEET | Shipment | Cargo Tally Sheet submitted | Unstructured |
| CERTIFICATE_OF_INSURANCE | Shipment | Certificate of Insurance submitted | Unstructured |
| SHIPPER_LETTER_OF_INSTRUCTION | Shipment | Shipper Letter of Instruction submitted | Unstructured |
| INTERNAL_INVOICE | Shipment | Internal Invoice submitted | Both |
| BANKING_COVER_LETTER | Shipment | Banking Cover Letter submitted | Unstructured |
| NOTICE_OF_COMPLETION | Shipment | Notice of Completion submitted | Unstructured |
| WEIGHT_CERTIFICATE | Shipment | Weight Certificate submitted | Unstructured |
| QUALITY_CERTIFICATE | Shipment | Quality Certificate submitted | Unstructured |
| SHIPPING_ADVICE | Shipment | Shipping Advice submitted | Both |
| PICKUP_ORDER | TE | Pickup Order submitted | Unstructured |
| DANGEROUS_GOODS_REQUEST | TE | Dangerous Goods Request submitted | Unstructured |
| EQUIPMENT_INTERCHANGE_RECEIPT | TE | Equipment Interchange Receipt submitted | Unstructured |
| CUSTOM | Shipment, Consignment, TE | user_specifided_name submitted | Unstructured |
| PICTURES | Shipment, Consignment, TE | Pictures submitted | 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). 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 Type" under the document types and provides a name for the document type. If "Custom 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.
Sample Document events
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
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
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 DSS Data Sharing Sheets Data Provisioning Requirements by Role and the Data Access Rights by Role sections in the TradeLens Data Sharing Specification. Documents are associated with a shipment, consignment, or transport equipment.
-
If the role has an M (Mandatory that the participant provide the data in all applicable scenarios), a C (Conditional for the participant to provide the data; if the data and scenario are relevant and applicable to the shipment / consignment / transport equipment, and if the data is available to the participant, then the participant must provide it), or an O (Optional; the data can be published to the platform at the discretion of the participant) in the Data Provisioning Requirements by Role for the document type, then the role has Upload / Write permission (and Read permission) for the document type.
-
If the role is blank (not M, C, or O) in the Data Provisioning Requirements by Role table for the document type, then the role does not have Update / Write permission for the document type.
-
If the role has an R in the Data Access Rights by Role table for the document type, then the role has Read permission to the document type. If the role is blank (not R) in the Data Access Rights by Role table for the document type, then the role does not have Read permission to the document type.
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 different document types.
Our two organizations will have the roles of Transport Service Provider and Consignor. The carrier organization will create the consignment and is given the role of Transport Service Provider. The carrier organization will then add the other organization to the consignment as a party with the role of CONSIGNOR. 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. As mentioned above in the Sturctured and Unstructured Documents table, document types can be associated with a shipment, consignment, or transport equipment trade object. We will keep our example simple, but in a real scenario, the carrier would also add transport equipment for the consignment. A shipment trade object might also be created by a Cargo Interest or 3PL Agent organization and associated with the consignment. In our example, we will show documents for a consignment, but the process is similar for the other trade objects.
We log into the Shipment Manager UI as the consignor organization, and search for the carrier booking number to find the consignment. Notice the organization's role for the consignment is Consignor.
Consignor's view
We click on the Documents icon and see that no documents are available to our organization. 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
We want to upload a Shipping Instructions document. Since the consignor has permission to upload this document type, if we click Add a New Document, we see it as a choice. As mentioned previously in the Permissions section, you can see the TradeLens Data Sharing Specification for more information on document permissions.
Consignor's view
We select the Shipping Instructions document type and click Next as shown in the previous image. In this case, we will upload the file from our computer. We click Add a Reference and provide a document reference ID, choose the file, and click Upload. The document reference is made up of a key/value pair. There is a Reference Name (that will be filled in by TradeLens for certain document types) and a Reference Value that the user can specify. Note that additional references can be added (including a user specified Reference Name) by clicking Add a Reference. As discussed earlier, associating a structured document with a template has advantages, but for our simple example we will not use a template. If we wanted to validate our structured document against a template (schema), we would click the Associate With Template button and choose the template. We could also create a structured document through the UI by selecting Use A Template at the top, fill in the information for the document and click Submit.
Note: If you are using the API for uploading documents and want to validate against a platform schema, you need to specify "gtd-ibm-authority" as the organizationId to find the platform schemas with the GET .../documentSchema API. You can also filter by name and type. For example, "SHIPPING_INSTRUCTIONS" is a platform defined document type. Then you can find the "ACTIVE" schema in the response and make note of the version and id. You can then call the GET .../documentSchema/{documentSchemaId} API using the id to retrieve just that schema.
Consignor's view
The Shipping Instructions document is now shown in the list of documents for the consignment.
Consignor's view
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 Shipping Instructions document. Notice the carrier's role is Transport Service Provider.
Carrier's view
To see the document types that the Carrier can upload, we click Add a New Document as shown in the image above. Notice in the screen image below that the carrier has Write permission to the document types listed. The Shipping Instructions document type is not listed as a document type that the carrier (Transport Service Provider) can upload, but as shown previously, the carrier does have access to Read the Shipping Instructions document type.
Carrier's view
We will upload a Sea Waybill document 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 shows the uploaded documents that the consignor can see.
Consignor's view
One additional note: When the carrier adds transport equipment for the consignment, some additional parties will be added to the consignment automatically; these are ports, terminals, and country authorities involved in the movement of the transport equipment. The permission matrix as detailed in the TradeLens Data Sharing Specification is also used for these roles.