SAP Business Network Material Traceability solution has introduced a new application that enables users to upload events via a templated spreadsheet. This additional feature provides SAP Business Network Material Traceability customers with an alternative method for pushing data, alongside the existing ECC add on and APIs.
This guide aims to assist SAP Business Network Material Traceability users in understanding the spreadsheet template for uploading events, using existing APIs as a reference. This guide is the first part of a two-part blog series. The first part covers uploading events for batches, while the second part delves into serialised products.
To follow the steps outlined in this guide, users must have an active subscription to the SAP Business Network Material Traceability application and access to a spreadsheet tool such as Microsoft Excel or OpenOffice Spreadsheet.
Users with the "ExpertUserDataCaptureTemplate" role assigned will have access to the "Upload Events" application. To access the application, users can either navigate directly from the FIORI launchpad or access it via the "Product Batches" or "Serialized Products" applications.
Using the Predefined Spreadsheet Template: The "Upload Events" application requires SAP Business Network Material Traceability events to be uploaded using a predefined spreadsheet template. This template can be downloaded from the "Upload Events" application itself.
How to Fill Out the SAP Business Network Material Traceability Spreadsheet Template for Batch genealogy
The Upload Events template can be best explained with a sample genealogy. Here is an example of a product genealogy traced based on batch.
Downloaded template will be filled with data needed to produce a genealogy graph like the given example. JSON payload for such a product genealogy is as given.
Before populating the SAP Business Network Material Traceability spreadsheet template with data, it is essential to familiarize yourself with its structure and requirements. This guide provides an overview of the template and its various components.
The SAP Business Network Material Traceability spreadsheet template consists of 14 tabs. The first tab provides help content and information about the template, such as the fact that bold column titles are mandatory and should not be removed. Non-mandatory columns, on the other hand, can be removed if the user wishes to simplify the template for their specific use case.
All tabs, except for the first one, contain multiple columns, typically with two titles: a descriptive title and a technical name. The descriptive title indicates the purpose of the column, while the technical name is reserved for use within the SAP Business Network Material Traceability solution. Some tabs also feature grouping titles, such as the "Receive Batch Deliveries" tab, which has a grouping title link called "Receive Batch Events". These titles can be links to related tabs or used solely for organizing columns.
To submit a receive event to the SAP Business Network Material Traceability system, data must be entered into both the "Receive Batch Events" and "Receive Batch Deliveries" tabs. Each entry in the "Receive Batch Events" tab must have at least one corresponding entry in the "Receive Batch Deliveries" tab. Failure to do so will result in a validation error when attempting to upload the spreadsheet.
The "Receive Batch Events" tab includes information about product batches received by the organization. Mandatory fields in this tab include Batch Number, Product Number, System, Creation Date, and Status. The following figure illustrates a JSON payload annotated with the corresponding column titles.
The spreadsheet tab should look like this.
The available quantities include DISCRETE, BASE_UNIT, ACTIVE_INGREDIENT, PER_PACK, TOTAL_HU, PACKAGES_IN_HU, NET_WEIGHT, TOTAL_GROSS_WEIGHT, TOTAL_VOLUME, and PFM_BASIC_CO2. You can find more information about these quantities in the API documentation.
Each quantity is represented by a column, with the value and unit specified in their respective technical names. These names are prefixed with a "q" for easy identification. To illustrate, let's use the PER_PACK quantity as an example. In the payload, you should provide the value and unit for PER_PACK in the columns titled "Per pack - Value" and "Per pack - Unit".
Spreadsheet columns with quantities filled for the payload is as given below.
In the "Properties" section following the "Quantities" columns, each property defined in SAP Business Network Material Traceability is displayed as an individual column. The technical name of every property is preceded by a "p" in its technical nomenclature. To input values for each property, fill in the corresponding column. Note that in this example, there is no property defined for the receive event; this will be addressed later when discussing the produce event tab.
The final column is designated for a specific use case related to the Catena-X network. Additional information about this column will be provided in subsequent blog posts.
In the "Receive Batch Deliveries" tab, the initial three columns are grouped under the "Receive Batch Events" heading. To maintain proper associations, users must ensure that each row in the "Receive Batch Events" section has at least one corresponding entry in the "Receive Batch Deliveries" section. This is achieved by verifying that the Batch Number, Product Number, and System are consistent between the two sections. It is compulsory to complete data entry in columns marked with bold titles. The JSON payload, annotated with the column name, is provided below.
After filling all necessary columns in this tab for the given example payload. The spreadsheet tab should look like as given.
If the spreadsheet is uploaded in its current state, we will end up having three receive events created in SAP Business Network Material Traceability. The batches will be listed down in the “Product Batches” application.
Next two tabs covers produce event of SAP Business Network Material Traceability. “Produce Batch Events” has all the details about the produced batch and “Produce Batch Components” contains the details about the batches which is consumed for producing the batches listed under “Produce Batch Events”.
The association is based on Batch Number, Product Number and System. It is not mandatory to have one corresponding component for each produce event, you can also have event “produce” where no components are specified.
In “Produce Batch Events” tab Batch Number, Product Number, System, Creation Date, Product Name and Status are mandatory. Annotated JSON payload should be like this.
Spreadsheet for example
Quantities should be filled exactly like it is done in the receive events. Consider the example provided, which includes two properties: GEPA and RSPO_NEXT. As these properties have been previously defined in SAP Business Network Material Traceability, the spreadsheet will contain two distinct columns labelled "GEPA" and "RSPO Next." It is essential to input the corresponding values for these properties into the appropriate cells within the spreadsheet.
Now we will explain how to properly set up the "Produce Batch Components" section, which is crucial for accurately reflecting the required components in the "Produce Batch Events." To ensure the components are displayed correctly in the appropriate produce events, it is essential to maintain consistency in batch number, product number, and system.
The first three columns in the "Produce Batch Events" section should provide details about the associations between the produce batch and its components. Subsequently, the following three columns, grouped under "Components (Related Product Batch Events)," should contain information about the component batches.
For instance, in the given example, three received batches are utilized in the produce event. The genealogy graph illustrates this by connecting the Chopped nuts, Choco cream, and wafers nodes to the Choco nuts bar node. The corresponding annotated JSON payload is provided below.
After filling component information, the spreadsheet will be as given below.
In the "Deliver Batch Events" tab, you will need to provide information related to the delivery events. Please ensure that all columns with a bold title are completed, as these are mandatory fields. To maintain the connection between the produce event and the delivery event in the genealogy, make certain that the product number and system are the same as those provided in the produce event. Additionally, the batch number should be equal to the vendor batch number.
For instance, the genealogy demonstrates the connection between the Choco nuts bar and its three corresponding delivery events. The JSON payload, which includes the column names, is provided below for reference.
The example content filled for delivery event in the spreadsheet should look like this.
Once all the tabs are filled the spreadsheet can be uploaded using the same “Upload Events” application. Application does some basic validation, once validation is done the events will be visible in Product Batches applications and the genealogy will be constructed to be viewed in graph.
This concludes the necessary steps and details involved in pushing product batch related events to SAP Business Network Material Traceability. In another blog we will cover how to push serialised product related events in Upload Events application.