How to create an InfoPlugin for the SAP Business ByDesign (ByD) API

This guide demonstrates how to create an InfoPlugin for the SAP Business ByDesign (ByD) API. We’ll be using the GenericHttpInfoPlugin template available on the Innovation Hub portal.

We will use the below QueryMaterialIn SOAP endpoint as an example. This endpoint requires:

Authentication via a Base64-encoded username:password in the Authorization header
A SOAP XML request body
The query is further refined by the sap-vhost parameter

You will learn how to construct the request and process the SOAP XML response to display material information within your InfoPlugin.

Endpoint Setup

Endpoint URL: https://my350410.sapbydesign.com/sap/bc/srt/scs/sap/querymaterialin
Request Header:
- Authorization:
  - Type: Basic Authentication
  - Value: Base64 encoded username:password

Example: Authorization: Basic X01XZWb21lMQ==

Request Parameter: sap-vhost: my350410.sapbydesign.com
Request Body (SOAP XML):

<soap:Envelope

    xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

    xmlns:glob="http://sap.com/xi/SAPGlobal20/Global"

    xmlns:a00="http://sap.com/xi/AP/CustomerExtension/BYD/A0014">

    <soap:Header/>

    <soap:Body>

        <glob:MaterialByElementsQuery_sync>

            <MaterialSelectionByElements>

                <SelectionByInternalID>

                    <InclusionExclusionCode>I</InclusionExclusionCode>

                    <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>

                    <LowerBoundaryInternalID>P100801</LowerBoundaryInternalID>

                </SelectionByInternalID>

            </MaterialSelectionByElements>

            <ProcessingConditions>

                <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>

            </ProcessingConditions>

        </glob:MaterialByElementsQuery_sync>

    </soap:Body>

</soap:Envelope>

Response XML (SOAP XML):

Step 1: Create A New InfoPlugin on innovation Hub

Click on Create New InfoPlugin to open InfoPlugin configuration window.

InfoPlugin Name: Give a name to this infoplugin. For this example, we’ll name it GetMaterialInfo.
Input Parameters: This endpoint requires an input parameter called internalId. For this demo, we’ll add it to the InfoPlugin configuration and name it materialInternalId.
Select the GenericHttpInfoPlugin from the My Templates section to populate the APIs configuration area. You’ll see the default setup appear below.

Now, let's fill each section as below:

Let's name this API section as getMaterialInfoStep (Rename GenericHttpInfoPlugin)
baseUrl - represents the root address of the ByDesign API we are connecting to i.e., https://my350410.sapbydesign.com
path - specifies the resource being requested; here we are requesting querymaterialin service, so the path of the request is /sap/bc/srt/scs/sap/querymaterialin
httpMethod - POST is used to send the SOAP XML payload to the querymaterialin endpoint.
Headers -To ensure the correct processing of our SOAP endpoint request, we need to provide specific information in the HTTP headers, including Content-Type and Authorization.

Content-Type Header:

Content-Type: application/soap+xml; charset=utf-8
This header informs the server that the request body contains SOAP XML data, encoded in UTF-8.

Authorization Header:

Authorization: Basic X01SAMPLEABCxyz==
This header provides authentication credentials to the SAP ByDesign system.
The Basic scheme indicates we are using Basic Authentication.
X01SAMPLEABCxyz== is the Base64-encoded representation of username:password

Note: Use the following command on Mac terminal to generate the Base64 token :

echo -n "username:password" | base64

Replace the username and password with your actual SAP Business ByDesign credentials.
- queryParameters - These parameters provide further context and instructions to the SAP ByDesign system. Specifically, the sap-vhost parameter (my350410.sapbydesign.com) ensures that the request is routed to the correct server location.
- requestBody - This is where we specify the SOAP XML query. This tells the system what data to retrieve. We specify the internal ID of the material we want to query using ${parameters.materialInternalId} This is an input parameter. It's a placeholder that will be replaced with the actual material ID value when the InfoPlugin executes the request.

After completing these sections, the APIs section looks as below:

Now, let’s proceed to complete the Response Parameters.

When our InfoPlugin receives a response from the SOAP endpoint, it comes in XML format. To make this data easier to use in the front-end component, we'll convert it to JSON.

Why JSON? JSON is the standard data format for web applications. It's simple for front-end components to read, which simplifies displaying the data and improves performance compared to XML.

ResponseParameters - This section allows us to define how the SOAP XML response should be transformed into JSON. We do this using FreeMarker language, which enables us to extract specific data from the XML and structure it as JSON.

<#assign responseBody = response.getMaterialInfoStep.body!?default({})>

<#assign material = responseBody.Body.MaterialByElementsResponse_sync.Material>

{

  "materialID": "${material.InternalID!''}",

  "changeStateID": "${material.ChangeStateID!''}",

  "uuid": "${material.UUID}",

  "creationDateTime": "${material.SystemAdministrativeData.CreationDateTime}",

  "creationIdentityUUID": "${material.SystemAdministrativeData.CreationIdentityUUID}"

}

Here's a step-by-step breakdown of how it works:

1. Extracting the Response Body:

<#assign responseBody = response.getMaterialInfoStep.body!?default({})>

This line extracts the SOAP response body from the response object. If the body is empty or null, it defaults to an empty object.

2. Navigating the XML Structure:

<#assign material = responseBody.Body.MaterialByElementsResponse_sync.Material>

This line navigates through the XML structure to access the Material element, which contains the data we need. FreeMarker allows us to access XML elements using dot notation (e.g., Body.MaterialByElementsResponse_sync.Material).

3. Creating the JSON Object:

The curly braces {} define a JSON object.

Inside the JSON object, we specify key-value pairs.

${material.InternalID!''}: This extracts the value of the InternalID element and assigns it to the materialID key in the JSON object. The !'' part is a FreeMarker directive that provides a default empty string if the InternalID element is null or missing.

We repeat this process for other relevant elements (ChangeStateID, UUID, CreationDateTime, CreationIdentityUUID).

4. FreeMarker Interpolation:

The ${...} syntax is used for FreeMarker interpolation, which allows us to insert dynamic values from the XML into the JSON object.

The next section is Example Parameters

Here, we mention the example of a JSON payload to illustrate the outcome of the FreeMarker transformation. This simplifies front-end integration by providing a concrete example for parsing and displaying data.

{

    "success": true,

    "materialID": "P100801",

    "changeStateID": "20230210092712.6186800",

    "uuid": "00000000-0001-1ddf-bb8e-3c0c0e015874",

    "creationDateTime": "2010-11-10T02:26:08.828107Z",

    "creationIdentityUUID": "00000000-0001-1ddf-b9b2-c6832d3bd15e"

}

After completing all these sections, the InfoPlugin looks as below:

With this our InfoPlugin is ready to use in a wave. Now let’s proceed to create a simple wave to use this InfoPlugin to render the json results.

Step 2: Create a simple WAVE on Innovation Hub

Let’s create a simple wave to retrieve material information from the BYD API using the InfoPlugin above.

Go to Workspace on innovation hub and click on WAVEs to see Create New WAVE button on the right. When we click on Create New WAVE it opens a wave form as below:

Click on PROMPT to create a first prompt, where we present a text box to accept the material internal ID as an input parameter from the user. Let’s name the text field as material_internal_id, It looks as below after setup:

Now, let's set up the second interaction to retrieve and display the material information from the BYD API.

Choose the "GetMaterialInfo" infoplugin. This infoplugin will make the call to the BYD AI API.
You can configure the infoplugin to use the Material ID entered by the user in the first interaction. This tells the API which material to retrieve information for. To display these details, add the following freemarker to the prompt:

The details for Material ID ${ replies.materialResponse ? has_content ? 
then(replies.materialResponse.materialID, '')} are as follows: <br>Change State 
ID: ${replies.materialResponse ? has_content ? 
then(replies.materialResponse.changeStateID, '')}<br>UUID: 
${replies.materialResponse ? has_content ? then(replies.materialResponse.uuid, '')}
<br>Creation Date & Time: ${replies.materialResponse ? has_content ? 
then(replies.materialResponse.creationDateTime, '')}<br>Creation Identity UUID: 
${replies.materialResponse ? has_content ? 
then(replies.materialResponse.creationIdentityUUID, '')}

The results will be shown as below when we run this wave on the server:

How to create an InfoPlugin for the SAP Business ByDesign (ByD) API

Endpoint Setup

Step 1: Create A New InfoPlugin on innovation Hub

Here's a step-by-step breakdown of how it works:

Step 2: Create a simple WAVE on Innovation Hub

Comments