Skip to content

Bulk Document Download and Upload

Copyright IBM Corporation and GTD Solution Inc. 2021

The bulk download and bulk upload features are currently in Beta.

This topic will cover how to download and upload multiple documents at one time. The bulk download and upload can be done using the UI or the API. Before downloading and opening shared documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.

Note: If you are using the UI to download documents in bulk, you need to ensure that system notifications are active for your organization. By default, system notifications will be active for the UI, but you can also set up system notifications to be sent to your login email, another email address that you have set up, or to a webhook. You can set up the email and webhook in Account > User Profile. You can check your system notification settings from Notifications > System Notifications as shown below:

bulkDownload_system_notifications1a

Bulk Download

Bulk download for one or multiple documents is available for consignments and shipments. Bulk download for transport equipment documents is not currently supported.

UI Example

Start the Download

Find the consignment or shipment that you want to download documents from and click the documents icon. You will then see all of the documents that you have permission to view. You can then select the documents that you want to download.

If a consignment is linked to one or more shipments, you will see an option to Show Related Document for the shipment(s). If you click the link, you can then also select the documents for the shipment(s). The same is true if a shipment is linked to one or more consignments; you will see the option to Show Related Document for the consignment(s). Note that the association will only go to the directly linked trade object(s), meaning that if a consignment links to a shipment that then links to other consignments, you will not see the 2nd level of consignments. You would need to navigate to those consignments from the shipment in this case. The following images show an example of a consignment that has a linked shipment that we can select to find the shipment documents.

bulkDownload_ui_dl2a2 bulkDownload_ui_dl2a4 bulkDownload_ui_dl2a6

The example that we will use for an entire flow will be to select all of the documents for a consignment, but the process is the same if you select documents from a consignment and the associated shipment(s), or for a shipment and the associated consignment(s). Once we make a selection, the Download Latest Version button will become active.

bulkDownload_ui_dl3a

You will then get a message from the UI that the download process has started. You will receive a system notification once it has completed. As noted at the top of this section, the notifications can go to the UI, email, or a webhook. The notification will contain the downloadRequestId that can be used to download the zip file (or to verify in the UI that you are downloading the correct zip if more than one notification exists in the system notifications section).

bulkDownload_ui_dl5a

Download the Zip File

To check for the notification on the UI, navigate to Notifications > Notification Inbox and then select the System Notifications tab. You can see the new notification in the image below, and you have the option to click on More Details (it contains the downloadRequestId and other information) or click the Download File link to download the zip file to your computer. The zip file is available for 24 hours. If the zip is no longer available, you will not see the Download File link. If you hover over the Download File link, it will display when the download link and zip file will expire.

bulkDownload_ui_dl7a

If you have email notifications set up for system notifications, the resulting email will contain additional details on the files and it will also contain the downloadRequestId that you can use with the API to download the zip file. The GET .../bulk​/documents​/download​/{bulkDownloadRequestId} - Downloads a ZIP file containing documents by bulkDownloadRequestId API, found in the Document Sharing Bulk Operations API section of the TradeLens Swagger, can be used to download the zip file (see the Download the Zip File in the API Example section below for details). You could also navigate to the UI and find the system notification as shown above and download the zip directly from the UI.

bulkDownload_ui_dl9a

API Example

See the API User Guide section for the Swagger URLs and for more information on the APIs, including a link for Authentication and Token Generation for API usage.

Start the Download

Find the consignment or shipment that you want to download documents from and then use the POST ...​/bulk​/documents​/downloadRequest - Download documents API, found in the Document Sharing Bulk Operations API section of the TradeLens Swagger.

If a consignment is linked to one or more shipments, you can also download the documents for the shipment(s) using the linkedDocs parameter. The same is true if a shipment is linked to one or more consignments; you can also download the documents for the consignment(s). Note that the association will only go to the directly linked trade object(s), meaning that if a consignment links to a shipment that then links to other consignments, you can not directly download documents for the 2nd level of consignments. You would need to use the shipment identifier and then linkedDocs would apply to the shipment's linked consignment(s). The Swagger for the POST .../bulk/documents/downloadRequest API contains more details for the API, but a few things to note about the linkedDocs parameter are listed here.

The linkedDocs option enables a user to download the documents for linked trade objects without specifying identifiers for all the trade objects. For example, the user can specify the shipment identifier with the linkedDocs option set as true . This would:

  • Download the shipment level documents for which the caller's organization has permissions to access.
  • Fetch the consignment(s) linked to the shipments.
  • Download the associated documents at the consignment(s) level for which the caller's organization has permissions to access.

The example that we will use for an entire flow will be to download all of the documents for a consignment, but the process is the same if you want to download documents from a consignment and the associated shipment(s), or for a shipment and the associated consignment(s), you would just use the linkedDocs parameter to include the directly associated trade objects. In our example, the consignment identifiers are specified and we receive the bulkTransactionId in the server response.

bulkDownload_api_dl24a bulkDownload_api_dl26a

Next, use the GET ...​/bulk​/transactions​/{bulkTransactionId} - Fetch bulk document transaction API, found in the Document Sharing Bulk Operations API section of the TradeLens Swagger and pass the bulkTransactionId that was received in the previous step. Notice in the below image that the downloadRequestId is returned and you can use this in the next section Download the Zip File to download the zip to your computer.

bulkDownload_api_dl28a

Download the Zip File

The GET .../bulk​/documents​/download​/{bulkDownloadRequestId} - Downloads a ZIP file containing documents by bulkDownloadRequestId API, found in the Document Sharing Bulk Operations API section of the TradeLens Swagger, can be used to download the zip file. Once you enter the downloadRequestId, click Execute to run the API and you will then receive a Download file link to download the zip file to your computer. The zip file is available for 24 hours. If the zip is no longer available, the API will return a not found message.

bulkDownload_api_dl20a

If you are using a posting type application (or your own program) to make the API call, you can save the result with a ".zip" extension to your computer.

bulkDownload_api_dl22a

Bulk Upload

Bulk upload for one or multiple documents is available for consignments and shipments. Bulk upload for transport equipment documents is not currently supported. If you have permission to upload certain documents to a consignment or shipment, you can upload multiple documents at one time through the UI or through the API.

If the shipment does not exist and the user is uploading a shipment document then following rules apply:

  • Roles: The organization uploading the shipment document must be of an org type that is eligible for creating a shipment. Shipments can be created by orgs of the types: Cargo Interest, 3PL Agent, and Certificate Issuer.
  • At least one shipmentReference must be provided. Note that the combination of shipmentRef and shipmentRefType must be unique within the scope of a given reference owner.
  • The callersPartyRole should be provided. It indicates the role of the caller on this shipment. Supported Roles: SELLER, BUYER, EXPORTER, IMPORTER, ORIGIN_3PL_AGENT, DESTINATION_3PL_AGENT, and CERTIFICATE_ISSUER.

If the shipment already exists for the given consignment:

  • Additional shipment references and additional parties can be added to the shipment.

Additionally, the org uploading a document must have the required permission for the Document Type based on their role in the consignment or shipment.

UI Example

In this example, we will upload a consignment document and a shipment document. The consignment already exists. The shipment does not yet exist, so it will be created using the shipmentReference that we provide on the upload. If you want to upload a shipment document to an already existing shipment, you would navigate to the documents section of the shipment and do the upload from there.

Start the Upload

Navigate to the documents section of the consignment and click the Bulk Document Upload button.

bulkUpload_ui3a

Click the Click to Upload Documents or drop files here link, or drag and drop files into that area. We will click the link and select some files to upload from our computer. We will upload a Booking Request document for the consignment and a Packing List document for a shipment (the shipment will be created as part of this process since it does not yet exist).

bulkUpload_ui5a

You can then select the consignment or shipment document type from the drop-down and add a document reference (if desired). If you have added document references, click the checkbox when complete.

bulkUpload_ui9a

Since one of the documents in our example is a shipment document, you will see additional fields to complete for the shipment. In this example, we have filled in our party role as the "Seller", specified the shipment reference that uniquely identifies the new shipment that will be created, provided an optional goods description, planned delivery date and planned completion date, and added an additional party to the shipment for a destination 3pl agent. Note that after checkbox next to the shipment reference is clicked to enter the reference, you can click the icon to view the value. Click the Add Document button to start the document upload and shipment creation (in this case).

bulkUpload_ui11a

You will receive a message indicating that a system notification will be sent (if enabled).

bulkUpload_ui13a

Check the Results

To check for the notification on the UI, navigate to Notifications > Notification Inbox and then select the System Notifications tab. You can see the new notification in the image below, and you have the option to click on More Details. If you have email notifications or a webhook set up for system notifications, you will receive the additional details on the files that were uploaded.

bulkUpload_ui15a bulkUpload_ui17a

From the shipment section of the UI, you can see that the shipment was created and the shipment document was uploaded (first image), and it is linked to the consignment (second image showing the consignments tab), and you can see that the consignment document was uploaded (third image) by clicking on the consignment and then the documents tab. Alternatively, you could navigate to the consignments section of the UI, find the consignment and then the documents tab. You can upload any additional documents to the shipment or consignment from the documents section of each trade object.

bulkUpload_ui19a bulkUpload_ui21a bulkUpload_ui23a

API Example

The PUT ...​/actionableDocFlows​/bulk - Bulk document upload automation Actionable Doc Flows API can be used to upload one or more documents for a consignment or shipment.
NOTE: This API can NOT be run using Swagger since Swagger does not support a multipart request with an arbitrary number of fields. The API is documented in Swagger exclusively for the purpose of helping subscribers understand the schema of the request and supported functionality. Users can try it out by using a posting method (such as POSTMAN) or through a client with direct API integration.

See the API User Guide section for the Swagger URLs and for more information on the APIs, including a link for Authentication and Token Generation for API usage.

Refer to the Swagger for the details on PUT ...​/actionableDocFlows​/bulk - Bulk document upload automation Actionable Doc Flows API. Some additional notes are mentioned below.

The Body has the following key/value pairs:

  • documentsMetadata
  • tradeObjectMetadata
  • Actual file attachments

Document Type: To get a list of Documents types you can call GET .../documentTypes Platform Constants API.

File Type: Supported file types are PDF, JSON, and IMAGE(JPEG,PNG).

Document References: This field is mandatory when uploading multiple documents of the same type.

Multiple actions can be completed based on the PUT ...​/actionableDocFlows​/bulk:

  • Creation of shipment object (if shipment does not already exist)
  • Add primary reference to shipment (if shipment does not already exist, or update existing shipment with new references)
  • Attach shipment to consignment (if shipment does not already exist)
  • Add caller's role to shipment
  • Add parties to shipment

Shipment References: To get a list of reference types you can call GET .../referenceTypes Platform Constants API.

Callers Party Roles: The supported roles are - SELLER, BUYER, EXPORTER, IMPORTER, ORIGIN_3PL_AGENT, DESTINATION_3PL_AGENT, CERTIFICATE_ISSUER

Shipment Party Roles: The supported roles are - SELLER, BUYER, EXPORTER, IMPORTER, ORIGIN_3PL_AGENT, DESTINATION_3PL_AGENT, CERTIFICATE_ISSUER

partyRef: To get a list of party references, you can call GET .../partners Business Partners API and set include_reference_records as true. The response has the ids of the business partners that you can use here as partyRef.

Actual file attachments: The key of the file attachment should map to the value specified in the document metadata : filePartKeys : file. This value will be used from the request to fetch the actual document attachment for the corresponding document.

The response to the PUT .../actionableDocFlows/bulk API will be a bulkTransactionId. Call the GET .../bulkTransactions/{bulkTransactionId} Actionable Doc Flows API using the bulkTransactionId to check the status of the upload.