Skip to content

Sample Postman Scripts

Copyright IBM Corporation and GTD Solution Inc. 2021

Note: The sample Postman scripts and environment variables are provided "AS IS" without warranty.

Overview

This topic is intended for Developers that want to see how Postman scripts can be used to interact with TradeLens through the TradeLens API. You will find a Postman collection and an envVariables file that you can customize. In order for the full collection to run completely, it assumes that you will use an organization that has access to consignments on the given zone, and that the first consignment found has a transport equipment (TE). If this is not the case, then the collection will not run without error, but you can still find benefit from reviewing the collection and make appropriate changes for your specific case. For example, instead of adding a reference for the TE, you could choose to add a reference to a consignment that your organization is authorized to access.

For additional information on using the TradeLens API, see the API User Guide. For more information on the authentication process, see the topic Authentication and Token Generation for API usage.

For additional information on Postman, see https://www.postman.com. We will not go into details on how to use Postman in this topic.

Scenario

The Postman collection is made up of 3 main sections: Org Token Generate, Queries, and Publish Events.

In the Org Token Generate section, the API will get an access token from Cloud IAM, and then the API will get an exchange token from Solution Authorizer. See the topic Authentication and Token Generation for API usage for more details on this process.

In the Queries section, there are 4 query (GET) API: Query Consignments by size, Query Consignment Events by consignmentId, Query TE Events by consignmentId, and Query All TE by consignmentId.

In the Publish Events section, there is a Publish referenceAdded Event for a TE.

Procedure

Download

Note: Before downloading and opening files, ensure that you have antivirus protection per your company policy with the latest virus definitions.

Download the TLSamplePostmanScripts.zip that contains the ClientPostmanInterfaceExampleTL.postman_collection.json and the ClientPostmanInterface envVariables.postman files.

The envVariables file contains several main variables that you will set for your environment. Then resave the file so it can later be imported into Postman. The main variables are:

  • environment url
  • OrgID and Org ApiKey
  • Originator ID and Originator name
  • eventSubmissionTime8601

Variable Details

  • Specify the environment url, which is used to set where you want to run the scenario. For example, if you are using the Sandbox environment, set envURL to platform-sandbox.tradelens.com. If your organization has been onboarded onto a stack other than platform, replace platform with your stack name.
  • Specify the organization ID (OrgID) and organization ApiKey in variables OCOrgId and OCApiKey. See the topic Authentication and Token Generation for API usage for more details on how to obtain an ApiKey if you do not have one.
  • Specify both the originator ID and originator name in variables originatorId and originatorName.
  • Update the eventSubmissionTime8601 variable so that it is close to when you run the scripts. This will ensure that the events you publish are ordered (by submission time) within any other events submitted to the trade object.

Import

Import the scripts and variable file into Postman.

Log into TradeLens

Log into the TradeLens UI. See the topic Shipment Manager. You can use the Shipment Manager UI to view the consignments and associated TE that your organization has access to view, including any events that you publish.

Run Scripts

Run each of the 3 sections of Postman scripts: Org Token Generate, Queries, and Publish Events. In addition to the information returned from the scripts, you can also check the Shipment Manager UI for the events that you publish.

Check Results

Check the results on the TradeLens UI. Find the consignment and TE that your script used for publishing the event. Navigate to the consignment, then to the TE, then check the events for the TE to see the reference that was added. You can also see the reference for the TE in the related details section of the TE. If you have altered the script, for example to add a reference to a consignment instead of a TE, then look for the results of your modification.