SAP Business Network Material Traceability solution has released a new API for retrieving upstream/downstream genealogy data of your product across your value chain. In this blog we will get to know how to consume this newly released API.
As a prerequisite you must have a subscription to SAP Business Network Material Traceability application and access to SAP BTP cockpit. Any tool to test consumption of the API is also helpful. In this blog I will give examples of using Postman tools for testing the API.
This blog has three sections:
Log in to your BTP cockpit and select the sub account where you have subscribed to Material Traceability. Here we will instantiate necessary services for using the API, navigate to “Service Marketplace” and search for “Services for Material Traceability”
We can create an instance of the service either by selecting the “Create” option from “…” or by selecting the tile and opting for “Create”.
As you can see in the image, existing plans are listed along with any instances that have already been created. The genealogy data API is included in the plan named “genealogy”.
Create a service instance and choose “genealogy” as plan.
Enter a name for your new service instance. The service instance will be listed in SAP BTP cockpit under “Instances and Subscriptions” with this name.
Now we have created an instance of service needed to retrieve upstream/downstream genealogy of a product in SAP Business Network Material Traceability.
To consume this service in any of your solutions, we need to have a service binding created. This can be done by selecting, “Create Service Binding”
You name the binding with which it can be referenced when you are consuming this service from any of your solution.
Since we have already instantiated a service and created a service binding, we are now ready to consume the API using Postman. It is assumed that there is already some content available in SAP Business Network Material Traceability. You can read about different ways of contributing data to SAP Business Network Material Traceability here.
To consume this API we need an OAuth token. We can get this token by invoking a credential URL with client Id and secret. Client id and secret is available in the binding under “uaa” object, you can click on the binding in SAP BTP cockpit to see both. The URL to fetch the token is also available as “url” under “uaa” object. Once we have the URL to fetch the token, path “/oauth/token?grant_type=client_credentials” should be added to the URL.
Open a new POST request in Postman. Provide token fetch URL with the added path. Authorization should be “Basic Auth” and provide client id and secret as username and password.
Send the request using Postman. In the response body we will have token as value for “access_token”. Once we have the genealogy API request also ready, we will once again send the token fetch and pass the token for the genealogy API. There are ways to automate this by writing some script in Postman, you can find more details in Postman’s help documentation.
The API URL for genealogy data is available in the binding as “uri” (this key is available outside of “uaa” object). The path to add to this URL is available in the API help documentation. The API path varies depending on whether the genealogy of a product batch or serialized product has been requested . For product batch the URL should look like
For serialized products it is like
We will use the API on an SAP Business Network Material Traceability system which has a product genealogy as shown below.
The URL to retrieve the upstream data of this product “Choco Cream ALL” will be
By adding a parameter “direction” we can control whether to retrieve upstream data or downstream data. As default the API retrieves upstream data. Before starting with this URL, make sure you create a new token as the old one may have timed out.
The response to the genealogy API should have two main objects named “objects” and “relations”. The objects will give all the details about different MT events as part of supply chain and the relations conveys the genealogy. For the example given above, one of the objects returned is:
“Choco Cream ALL” is one of the products produced by an external supplier and delivered, the value in the key “external” indicates whether the event happened inside the company or outside with any of your supply chain partners. In relationship object there will be a pair which indicates the connection between this produce batch event and a receive batch event.
The key “c9842f0efc0bfadf4fa9a7c8a3fb48e68929aa43” covers an object
indicating the relationship between the produce and deliver event. This way the entire genealogy of the product can be composed from API data.
Genealogy API makes data consumption from SAP Business Network Material Traceability simple, allowing you to make use of its rich data set related to companies’ supply chains in any other solutions
As a prerequisite you must have a subscription to SAP Business Network Material Traceability application and access to SAP BTP cockpit. Any tool to test consumption of the API is also helpful. In this blog I will give examples of using Postman tools for testing the API.
This blog has three sections:
- Instantiating services for Material Traceability
- Creating a service binding
- Consuming it in Postman tool
Instantiating services for Material Traceability
Log in to your BTP cockpit and select the sub account where you have subscribed to Material Traceability. Here we will instantiate necessary services for using the API, navigate to “Service Marketplace” and search for “Services for Material Traceability”
We can create an instance of the service either by selecting the “Create” option from “…” or by selecting the tile and opting for “Create”.
As you can see in the image, existing plans are listed along with any instances that have already been created. The genealogy data API is included in the plan named “genealogy”.
Create a service instance and choose “genealogy” as plan.
Enter a name for your new service instance. The service instance will be listed in SAP BTP cockpit under “Instances and Subscriptions” with this name.
Now we have created an instance of service needed to retrieve upstream/downstream genealogy of a product in SAP Business Network Material Traceability.
Creating service binding
To consume this service in any of your solutions, we need to have a service binding created. This can be done by selecting, “Create Service Binding”
You name the binding with which it can be referenced when you are consuming this service from any of your solution.
Consuming in Postman tool
Since we have already instantiated a service and created a service binding, we are now ready to consume the API using Postman. It is assumed that there is already some content available in SAP Business Network Material Traceability. You can read about different ways of contributing data to SAP Business Network Material Traceability here.
To consume this API we need an OAuth token. We can get this token by invoking a credential URL with client Id and secret. Client id and secret is available in the binding under “uaa” object, you can click on the binding in SAP BTP cockpit to see both. The URL to fetch the token is also available as “url” under “uaa” object. Once we have the URL to fetch the token, path “/oauth/token?grant_type=client_credentials” should be added to the URL.
Open a new POST request in Postman. Provide token fetch URL with the added path. Authorization should be “Basic Auth” and provide client id and secret as username and password.
https://<<yourTokenFetchURL>>/oauth/token?grant_type=client_credentialsSend the request using Postman. In the response body we will have token as value for “access_token”. Once we have the genealogy API request also ready, we will once again send the token fetch and pass the token for the genealogy API. There are ways to automate this by writing some script in Postman, you can find more details in Postman’s help documentation.
The API URL for genealogy data is available in the binding as “uri” (this key is available outside of “uaa” object). The path to add to this URL is available in the API help documentation. The API path varies depending on whether the genealogy of a product batch or serialized product has been requested . For product batch the URL should look like
https://<<yourAPIURL>>/api/v1/genealogy/productbatch/{batchId}/{productid}/{systemId}For serialized products it is like
https://<<yourAPIURL>>/api/v1/genealogy/serializedproduct/{serialId}/{productid}/{systemId}We will use the API on an SAP Business Network Material Traceability system which has a product genealogy as shown below.
The URL to retrieve the upstream data of this product “Choco Cream ALL” will be
https://<<yourAPIURL>>/api/v1/genealogy/productbatch/BAT-CHALL-R/CH_ALL/F2C_FINBy adding a parameter “direction” we can control whether to retrieve upstream data or downstream data. As default the API retrieves upstream data. Before starting with this URL, make sure you create a new token as the old one may have timed out.
The response to the genealogy API should have two main objects named “objects” and “relations”. The objects will give all the details about different MT events as part of supply chain and the relations conveys the genealogy. For the example given above, one of the objects returned is:
{
"encodedKey": "d63eea5c9b8623cde011c4c80945e128b8eb0231",
"producedBatch": {
"status": "RELEASED",
"batchId": "BAT-CHALL",
"quantities": [
{
"qualifier": "DISCRETE",
"value": "75",
"unit": "KGS"
}
],
"properties": [
{
"name": "UTZ",
"value": "true"
},
{
"name": "LACTOSE",
"value": "false"
},
{
"name": "RAINFOREST_ALLIANCE",
"value": "true"
},
{
"name": "RSPO_NEXT",
"value": "true"
}
],
"creationDate": "20200501",
"productName": "Choco Cream ALL",
"location": "Germany",
"external": true
}
}
“Choco Cream ALL” is one of the products produced by an external supplier and delivered, the value in the key “external” indicates whether the event happened inside the company or outside with any of your supply chain partners. In relationship object there will be a pair which indicates the connection between this produce batch event and a receive batch event.
{
"fromEncodedKey": "d63eea5c9b8623cde011c4c80945e128b8eb0231",
"toEncodedKey": "c9842f0efc0bfadf4fa9a7c8a3fb48e68929aa43"
}The key “c9842f0efc0bfadf4fa9a7c8a3fb48e68929aa43” covers an object
{
"encodedKey": "c9842f0efc0bfadf4fa9a7c8a3fb48e68929aa43",
"deliveredBatch": {
"status": "RELEASED",
"vendorBatchId": "BAT-CHALL",
"goodsIssueDate": "20200512",
"external": true
}
}indicating the relationship between the produce and deliver event. This way the entire genealogy of the product can be composed from API data.
Genealogy API makes data consumption from SAP Business Network Material Traceability simple, allowing you to make use of its rich data set related to companies’ supply chains in any other solutions
- SAP Managed Tags:
| User | Count |
|---|---|
| 9 | |
| 8 | |
| 6 | |
| 4 | |
| 3 | |
| 3 | |
| 3 | |
| 3 | |
| 3 | |
| 3 |
