China Unicom IOT Integration
Copyright IBM Corporation and GTD Solution Inc. 2021
You can download a Chinese version of this document here: TradeLens-CUIOT-通过中国联通物联网接入指南.pdf.
- 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 or China Unicom IOT Gateway (CU-IOT).
- Before downloading and opening documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.
This document will guide a user in China to integrate with TradeLens using the in-country identity provider from China Unicom called the IOT (Internet of Things) Gateway (CU-IOT). Some key ideas and concepts are listed below to better help technical teams follow the guide:
3 ways to connect with TradeLens using CU-IOT
- Use UI
- Use a REST / JSON API
- Use EDI, where EDI files containing event information would be transferred to TradeLens FTP or email servers using Integration Framework. For details on this method, contact your Onboarding representative.
CU-IOT unique portal is the entrance for a Chinese end user to log into TradeLens UI. CU-IOT unique portal account is managed by CU-IOT.
CU-IOT gate-way is the entrance for a Chinese end user to call CU-IOT authentication API.
TradeLens Sandbox is the environment that you will use during development and testing, so at first you will only have access to the Sandbox UI and APIs. You will have access to the TradeLens Production UI and APIs only after the testing is complete.
TradeLens publishes all the available APIs at Swagger (https://platform-sandbox.tradelens.cn/documentation/swagger/). You can get the URLs and JSON message details that should be applied to the respective APIs and also run some tests to better understand the APIs.
TradeLens participants can only access data available in TradeLens systems through API Subscription, API Query, or the TradeLens UI. EDI is not available for any participants to received data from TradeLens.
Administration and User Accounts
CU-IOT unique portal administration account can be only created by CU-IOT internally. Once this administration account is created, an end user is able to create a sub-account under the same organization. CU-IOT will create CU-IOT unique portal account based on the end user's email address. After the account is created, CU-IOT will send an email to ask the end user to reset the initial password within 72hrs.
After the password has been reset, the end user will then be able to log into TradeLens through the CU-IOT unique portal.
If a sub account user needs to be created, the administration user can add the account in “User Center”. The new user will be required to reset their initial password.
After logging into "User Center", click "add new user" and input the required information.
After CU-IOT sub account is created, the administration user needs to add this user in the TradeLens UI by clicking Account then clicking User Management. If you want this new user to also be an administrator ID in TradeLens for the organization, check the Administrator box. If a Chinese organization has a user that is located outside of China and that user needs to log into the same organization, then the administrator needs to add that user to the organization using the TradeLens UI.
Logging into TradeLens UI and Swagger
The TradeLens URLs are:
- Sandbox Shipment Manager UI: https://platform-sandbox.tradelens.cn/
- Sandbox Swagger APIs: https://platform-sandbox.tradelens.cn/documentation/swagger/
- Production Shipment Manager UI: https://platform.tradelens.cn/
- Production Swagger APIs: https://platform.tradelens.cn/documentation/swagger/
- The full URL is required, including the "https://".
- Incognito (private) browser windows do not work, use only non-incognito browser windows for the UI and Swagger.
- Safari browser only works if you enable 3rd party cookies.
Logging into the UI
For this example, we will log into the Sandbox Shipment Manager UI using https://platform-sandbox.tradelens.cn/ which redirects to the CU-IOT unique portal to enter our userid, password, and the captcha code.
We choose the Sandbox UI.
If you are a member of more than one organization, you will be able to select the organization that you want to log into and then you will see the Shipment Manager UI. Otherwise, if you are only a member of one organization, you will not need to choose an organization and you will immediately see the Shipment Manager UI and be able to view Shipments, Consignments, and Transport Equipment for your organization.
Logging into Swagger
If you are already logged into the UI on your browser, then you will automatically be logged into Swagger if you go to https://platform-sandbox.tradelens.cn/documentation/swagger/. If you are not already logged in, then the process is very similar to logging into the UI.
For this example, we are not already logged into the UI, so we will show the login flow for Swagger using https://platform-sandbox.tradelens.cn/documentation/swagger/.
Click on "login". This will redirect to the CU-IOT unique portal to enter our userid, password, and the captcha code.
Locate the TradeLens Swagger Sandbox option and click it (you might need to click the left or right arrows to find it).
You will then be redirected to the Swagger page. If you still see a "login" button, click the "login" one more time to complete the process. If you are a member of more than one organization, you will be able to select the organization that you want to log into and then you will see the Swagger APIs. Otherwise, if you are only a member of one organization, you will not need to choose an organization and you will immediately see the Swagger APIs. You can select the Swagger page that you want to work with, for example "Event Publish API".
Alternate method using CU-IOT to log in
Alternatively, you could also access TradeLens through the CU-IOT unique portal at https://sso.10646.cn using the CU ID and password.
After logging into CU-IOT unique portal, the end user can log into the TradeLens Sandbox UI or the TradeLens Production UI (which will be only available after Sandbox testing) by clicking the icon in their portal main page.
Integration - TradeLens API through CU-IOT gate-way authentication
The end user needs to log into CU-IOT unique portal to get CU-IOT gate-way App ID and App Secret, which will be used in authentication flow.
Get App ID and App Secret in CU-IOT Gateway
If this is the first time that the user is being set up, then the user needs to log into the "Ability Platform" to subscribe to the TradeLens service.
After logging into "Ability Platform", scroll down the page to find "TradeLens" service in "Value-Added Ability" section and subscribe to this service.
Fill in the required information.
Confirm the order and wait for the confirmation.
Enable the service of the TradeLens service in the order list and wait for the confirmation.
Then go to the application list and check the App ID and App Secret. Please use production App Secret for further steps.
Note: Several tools and programming languages support REST APIs that can be used to obtain the tokens, but Postman will be used in this document as an example.
The process for authentication and Token Generation for API usage requires the generation of 3 “Tokens”: the first is called the “token”, the second is called the “Access Token”, and the third is called the "Solution Token" or "Bearer Token".
token is used in the call to CU-IOT gateway authentication API. This token is required to be generated by you, based on the AppID and AppSecret. The Python code example and JAVA code (TokenRequestBuilder.java) shown below can be used to generate this token.
Access Token is provided in the response from CU-IOT gateway. It is the value of the "userInfo" field and is to be used in the call to the TradeLens authentication API.
Bearer Token or Solution Token is the response from the TradeLens authentication API. It will be used to call the TradeLens platform APIs.
The first “token” is used in authentication API in CU-IOT gate-way.
- Create a “POST” API on Postman
- Add the URL https://gwapi.10646.cn/api/tradelensLogin/V1/0Main/vV1.0
- On the header add the key “Content-Type” with value “application/x-www-form-urlencoded“ and the key “Accept” with Value “application/json
On the body of you API you will provide your API with the following format, note that ‘username’ is the username in CU-IOT portal. See the Python and JAVA example below for how you can generate the token:
Here is a Python example (provided "AS IS" without warranty) showing how to get the timestamp, trans_id, and token:
def get_timestamp_transid_token(app_id, app_secret):
now = datetime.datetime.now()
timestamp = now.strftime('%Y-%m-%d %H:%M:%S %f')[:-3]
trans_id = now.strftime('%Y%m%d%H%M%S%f') + str(random.randint(100,999))
original_str = 'app_id' + app_id + 'timestamp' + timestamp + 'trans_id' + trans_id + app_secret
token = encode.Encode.SM3(original_str)
return (timestamp, trans_id, token)
A JAVA example (provided "AS IS" without warranty) can be seen or downloaded here: TokenRequestBuilder.java
Now click on Send and you will receive your “Access Token”, userInfo in the image below.
Call the second API to generate your “Bearer Token”:
- Send this POST request:
Note: Your organizationId was provided to you as part of the TradeLens provisioning/onboarding process (if you are an organization admin, you can also find your organizationId from the Shipment Manager UI User Management section), for example: 98e2f3cc-e801-4a34-9eef-e4b2e3a65ff1.
Include these headers:
Header: Content-Type: application/json
Header: Accept: application/JSON
Copy and paste the value of "userInfo" received as an answer from your first API call into a field called "access_token". This will be the "Body" of the API.
Once the request is sent, the response will contain the "Solution Token" that you can use as the "Bearer Token" for requests to TradeLens to publish, subscribe, or query events through the TradeLens APIs. The Solution Token is valid for 1 hour because the Identity Provider (IDP) CU-IOT token expires in 1 hour. When the Solution Token expires, a 401 will be returned, only then do you need to obtain 3 new tokens. Client code should not cache the CU-IOT Token or Access Token, but instead get new ones when the Solution Token expires. So, the process should be: obtain calculated CU-IOT Token => get CU-IOT Access Token => get Solution Token (Bearer Token) => cache and check for expiration of only the Solution Token and if it is expired, get a new CU-IOT Token and CU-IOT Access Token and Solution Token (Bearer Token). Note that the token could expire right as it is being used. If this happens, a 401 will be the response. The calling code should check for a 401 and handle it by getting new tokens.
- Send this POST request:
Publish your first event
- We will test an Actual Gate In (actualGateIn) event. The Swagger for this event is located in the Transport Events section of the Event Publish API page. See the API User Guide Swagger API Documentation section for the Swagger URLs. For quick reference, the specific link to the Event Publish API Swagger page on Sandbox is: Event Publish API.
- We will send a POST https://platform-sandbox.tradelens.cn/api/v1/transportEvents/actualGateIn
- Three headers are required on the HTTPS request: Accept, Content-Type, and Authorization.
- To call the TradeLens APIs, use the Solution Token as the Bearer Token by setting it in the Authorization header as Bearer solution_token.
- At this point, we are only testing that the Bearer Token is accepted, and since this is the Sandbox environment, it does not matter if our Actual Gate In event specifies a real transport equipment.
- If the Bearer Token was accepted, and the syntax of the API is valid, then you will get a "201 Created" status message. Note that this does not necessarily mean that the request was fully processed, it just means that the request was accepted. Since we did not specify a valid transport equipment, the Actual Gate In would not match to a transport equipment object so it would not be fully processed.
Once the integration layer is able to procure tokens as explained in “Token Generation with Postman” and able to publish events for the events described in Swagger, then the next step is to ensure that the events being published are properly getting linked to a trade object (shipment, consignment, transport equipment).
The example below describes how a port can do further testing. A subset of consignments, for which the port has visibility because the consignment touches the terminal/port being integrated, will be available in the Sandbox environment. You will need to select one or more consignments and transport equipment from these environments to ensure that the events that the integration layer is publishing are visible in the TradeLens UI.
- Log into TradeLens UI using the CU-IOT unique portal.
- You will see all of the consignments that you are authorized to view.
- Select one or several consignments to be used for your event publishing tests. Copy the Carrier Booking Number (CBN) and the transport equipment in the test consignments.
- From your integration layer, publish the relevant events for the CBN / transport equipment selected.
- Verify the events are shown after you revisit the test consignments, and verify that the transport equipment events show your org name as the publisher of the event.
- Click on an event to view the event details and inspect that all the data elements appear correct, such as location, time, etc. Review the documentation in the Swagger for each API and click on Model to see an explanation of each field.
- After validating all the data for all published events, ensure that the event has been published in the correct flow of the events. Example: Gate out (Empty) should be followed by Gate in (Full), which should be followed by loaded on Vessel, etc.
- After event publishing with test data is complete, you will need to publish with live data on the Sandbox zone and notify the onboarding support team to verify that the port / network events are properly linking with events from other participants on the same consignments.
- Once the onboarding team testing completes, you will be provided with the production URL endpoints and you can grant your team access to the production org so that a new system user can be created, and the integration layer can be updated with production endpoints URLs.