Collection runner for the logistics blockchain

TradeLens was launched by the world's largest shipping company Maersk and is based on the blockchain technology from IBM. Its core task is the secure and trustworthy logging of all logistical events between the original shipper and final consignee within the global transport chain. This enables all participants in this blockchain to use reliable and tamper-proof data in their own supply chain management in order to ensure an efficient flow of goods. Tracking and tracing becomes child's play. A simple, scalable and secure implementation using Workato has already been described in detail in another article (see comment). At this point, we would like to go into more detail about the equally important preceding step of test automation before going live. It ensures that we have understood the API and its use and that automation in production can be successful.

Source:

API development always includes meaningful documentation, which usually consists of a blog-like implementation guide and a technical description; the latter is regularly created using the tool Swagger (now OpenAPI) tool. In the case of TradeLens, both have been done extremely well: Detailed, comprehensive, comprehensible, technically mature. The implementation of the individual steps in Postman is given to the API integrator straight away, so we don't need to say any more about it here. We want to go straight into automation with the help of collection runners.

A collection runner is a sequence of individual queries that are combined into a chain thanks to the pre-request script and test script. A query can use the result of a previous query and process it further in order to compare it with an expected value. If the actual value corresponds to the expected value, a green symbol is displayed, otherwise a red one. The queries are mostly REST queries, the exchanged content mostly JSON data. This is also the case with TradeLens. In this specific example, we have selected a TradeLens event in which a rail carrier reports the loading of a container to the blockchain. This requires three individual steps: (1) authorization in the IBM Cloud, (2) authorization in TradeLens and (3) transmission of the event content to TradeLens.

Source:

In the first step, the IBM Cloud provides an Access and Refresh Token in exchange for a valid API key that was created during onboarding on TradeLens. This access and refresh token is used to request an exchange token from the TradeLens Solution Manager, which is ultimately used to report the specific event to the TradeLens platform. The two-stage token creation enables the event publisher, in our case the rail transport company, to assign the authorization to use the TradeLens API in its name itself in the IBM Cloud user administration(Identity and Access Management, IAM for short). If the Access and Refresh Token is valid, TradeLens grants an Exchange Token for sending the events (also called Bearer Token or Onboarding Token). This separation of authentication responsibility from service responsibility follows the modern OAuth 2.0 standard, which aims to avoid the continuous exchange and redundant storage of passwords between services. In order for TradeLens to accept the IBM Cloud user management as an authorization instance, the IBM Cloud user management was made known to TradeLens during onboarding so that TradeLens can assess the validity of the access and refresh token. Interested parties can find an understandable introduction to how OAuth 2.0 works and further authentication mechanisms in the following video.

If the client has received an exchange token, it inserts this as an "Authentication" field preceded by the word "Bearer" in its event POST request: The POST request thus provides TradeLens with a valid access code for sending the event. In the following screenshot, the URL to which the POST request is sent is abstracted by a variable so that it can be easily parameterized from a script.

So much for the basic process. Now to the automation and validation within the Postman Collection Runner.

As soon as the Postman client has sent the first POST request to the IBM Cloud IAM with the API token in the message body, the access and refresh token of the IBM Cloud IAM should be written from the associated response to a collection variable. This is to be used in the subsequent step, authentication with TradeLens. Collection variables have a scope for a collection, which is nothing other than several requests that have been grouped together in a collection (similar to a folder). They can therefore share those variables, i.e. access and change them, which have been defined as collection variables. There are also local variables, environment variables and global variables, which we will discuss later.

Postman offers the option of executing JavaScript programs before and after a request for automations within collections. This is easily done by creating a corresponding JavaScript program in the "Pre-request Script" or "Test Script" tab. Postman also provides numerous methods and properties for the interaction, which are contained in the pm object. Let's take a closer look.

In line 3, two local variables are defined with the JavaScript keyword let: The response variable records the response of the POST request immediately preceding the test script in JSON format(pm.response.json()); this gives the response a structure that facilitates further processing in Postman. Immediately afterwards, the variable accessRefreshToken is defined and the previously saved variable response is immediately assigned to it as a string, which is achieved using the stringify method. We will see why this is done in a moment.

But first an explanation of why we use two local variables: Their scope only extends from the beginning to the end of this single test run (collection run). Consequently, there is no need to worry about whether they could collide with variables defined elsewhere outside this test run, as this could lead to errors.

In line 6, the response converted to a string is saved as a collection variable; it is therefore also available to the other two POST requests. This is only relevant for the request immediately following step 1, as it accesses this collection variable in order to receive an exchange token (bearer token) from TradeLens.

Finally, three tests are executed in lines 9 to 17: If the response represents a success message (i.e. 200 code according to the HTTP standard), it contains a section called "access_token" and one called "refresh_token". If all three conditions are met, this first POST request was successful. Postman acknowledges this with a green symbol.

After the access and refresh token has been saved in a collection variable, it can be accessed directly in the second POST request, here in the body of the second step. In Postman, this is done using two curly brackets with the variable name as the identifier {{AccessRefreshToken}}.

Similar to the first step, we save the response of this second POST request in a collection variable for further use. This time it is the exchange token, which TradeLens calls "onboarding_token" in the JSON document. It is again stored in a collection variable. In addition, the test script checks whether it is again a positive 200 HTTP response and whether the word "onboarding_token" is contained in the body of the response this time. If both criteria are met, the test is considered successful - green tick.

After these two security-related preparatory steps, authentication against the user's own user database and against TradeLens, we finally come to the essential point: the transmission of the transport event relevant to the user to TradeLens.

In contrast to the two previous steps, three automation steps must be carried out: Firstly, the onboarding token must be inserted as an authentication header field in the pre-request script; secondly, the body should be loaded dynamically from a JSON file so that employees unfamiliar with Postman can also add new test data to a test run or send test data to the tester in the form of easy-to-create JSON files; thirdly, the response to this POST request should be checked for success. Let's start with the first measure, the transmission of the onboarding token as a header field.

In line 2, a local variable called "bearerToken" is created, which is assigned the value "Bearer " followed by the content, i.e. the onboarding token, of the corresponding collection variable. In line 3, we add this local variable as the header element "Authorization" to the pending POST request or update the value of this header element if it already exists. The "upsert" method from database development is also used for this in the JavaScript extension of Postman. In addition, in lines 6 and 7 we retrieve the current ISO 8601-compliant time in the Europe/Berlin time zone from an external time service in order to save it in a global variable called "TimeStamp" in the time format (datetime). This global variable is to be fed into the transport data to be transmitted, as TradeLens would like to know the time of transmission. Of course, you could also have used a collection or environment variable instead of a global variable; we have opted for a global one to demonstrate its use. Finally, in line 11, the collection variable "IterationData" is to be populated with all the test data - again as a string, as Postman requires for variable content. The test data comes from the previously mentioned separate JSON document, which the Collection Runner loads into Postman. This "sideloading" of test data in Postman is a very welcome feature to separate the creation of automation by a test automation engineer from the use of test automation or the provision of real test data by a department employee.

The body of the pending POST request then also looks unspectacular. It only contains the collection variable "IterationData", which in turn contains the exemplary test data set shown below. The red arrows show where the collection variable defined in the JavaScript is used and where Postman replaces it with concrete values in the background. For test purposes, the time of the transport event was equated with that of the event transmission; in productive automation, the former time is transferred by the transport management system and does not need to be supplemented.

In the test data example, another advantage of "sideloading" in Postman becomes clear: the delivery of several test data sets, which Postman then processes sequentially without the user having to restart the test automation. The blurred fields contain potentially confidential test data, so they have been removed here. The remaining fields are artificial test data with no reference to reality.

The last step in this third POST request is to check the success of the post. This is guaranteed if either a 201 or 202 HTTP response is received from TradeLens, which contains the text "Event submitted" in the body. This brings us to the end of our test automation with Postman. If you start the Collection Runner, all steps are run through for each iteration, i.e. for each data record read in, and the test results are clearly displayed in Postman with red or green icons. Success can also be verified in the TradeLens web interface. Here you can see all the events to which your organization has access - including those you have published yourself. However, this would take us too far afield here.

Postman is a wonderful tool for understanding APIs and for their initial, step-by-step implementation and test automation. Once this first hurdle has been overcome, nothing stands in the way of automation and integration into the production systems. However, this is where more powerful tools such as the cloud-based low-code integration and automation platform Workato come into play, which is also ideal for the test automation of APIs. For surface-oriented test automation and continuous operational monitoring, we then use no-code RPA tools such as Leapwork. They enable automated testing of programs with user interfaces such as web applications, Citrix applications or even installed programs and apps. We will devote a separate article to this highly efficient tool and present its strengths using a specific example.

Business Automatica reduces process costs by automating manual activities, increases the quality of data exchange in complex system architectures and connects on-premise systems with modern cloud and SaaS architectures.