Using Mappings

Objective

After completing this lesson, you will be able to Explain the utilization of mappings in the Integration Suite.

Mappings

In this Lesson, the following topic is discussed:

Mappings in an overview.

Mappings in an Overview

The following mapping types are available:

  • Message Mapping.
  • XSLT Mapping.
  • Mapping with Scripting.
  • Operation Mapping from Enterprise Service Repository (On-Premise).
Message Mapping

The Java SDK for message mapping and user-defined functions (UDFs) is the same as for the process integrations. To use them, you need the body in XML or JSON format. The source and destination mapping can be defined using one of the following file types:

  • XML Schema Definitions (XSD)
  • OData V2/V4 metadata files with .edmx or .xml extensions
  • WSDL
  • Swagger/OpenAPI Spec JSON file

Mapping Editor

This lesson does not involve the use of a message mapping. The mapping editor, however, provides all the necessary tools to map XML or JSON messages.

  • No. 1: Adding the source structure.
  • No. 2: Adding the target structure.
  • No. 3: The actual assignment of the values depending on the context.
  • No. 4: Other representation of the mapping.
  • No. 5: Simulation of the mapping with a source file.
  • No. 6: Define a user defined function (UDF)

Testing

We can test/simulate the mapping using the monitor.

Implemented Samples via Guidelines

Implemented Samples via Tutorials, Missions, and Blogs

SAP Cloud Platform Integration (CPI): Use cases of node functions in message mapping | SAP Blogs

Videos

Message Mapping in SAP CPI || Step by Step guide

Read more here:

XSLT Mapping

XSLT (Extensible Stylesheet Language Transformations) is a language originally designed for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text, or XSL Formatting Objects, which may subsequently be converted to other formats, such as PDF. A style sheet is processed by an XSLT processor such as Xalan or Saxon. Both are included in every Java SDK. We use XSLT mapping in the exercises. There is an amazing online editor, Groovy IDE for easy development and testing of your scripts.

Sample

This example copies the content of the source file without any namespaces and their corresponding prefixes, and generates a target file.

The namespaces are:

This is necessary in order to be able to access the contents of the response via XPATH.

The XSL stylesheet creates the result document through a template that only includes the original element names and attributes.

The result after transformation:

Testing and Limitations

Testing XSLT mapping requires deploying the integration flow or using external tools. Without deployment, testing is not possible. To speed up the tasks related to integration flow transport, testing, and error handling, you can use tools like the DOST Add-on.

Implemented Samples via Guidelines

Learn the Basics → Access Header and Properties → Access Header and Properties in XSLT Mapping: Access Header and Properties in XSLT Mapping

Blogs

Read more here:

Mapping with Scripting

Mappings can also be implemented using Groovy or JavaScript.

Sample

In this example, the list of order items is restructured in a different way.

The source JSON Payload:

Testing

Testing of Groovy script mapping can be done by deploying the integration flow or using external tools. It is not possible to test without deploying it.

Read more here:

Operation Mapping from Enterprise Service Repository (On-Premise)

To save time and effort when creating integration content, you can import existing content from your ES repository directly into Cloud Integration. To do so, you must configure the connection settings to connect to the On-Premise ES system through Cloud Connector. This allows you to reuse previously created integration content and avoid redundant work in the Cloud Integration web application.

Import Content from ESR

Once you have configured the connection to the ES Repository, you can proceed to import the content from it through the "Resources" tab in the integration flow editor. At present, you are able to import:

  • Message mapping
  • Value mapping
  • Operation mapping
  • WSDL

Read more here:

Summary

Mapping is the process of converting a source format into a different target format using various techniques in SAP Cloud Integration. The source and target structures must first be defined, which can be done via XSDs, WSDLs, and more definitions in message mapping. The Message Mapping Editor, which offers context handling, user-defined functions, and testing options, is used for the build-in variant of mapping in XML and JSON formats. The XSLT procedure, which requires XML as an input format and offers a simple editor, can create more target formats and is useful for creating attachments. Testing is done via integration flow deployment or external tools like XML Spy. Mapping via scripting offers the greatest degree of freedom in terms of source and target formats and requires a written language that supports the formats, such as XMLSlurper for Groovy scripting language. Testing here is also done via integration flow deployment or external tools like IntelliJ IDEA. If all data structures such as XSD and WSDLs are already created in the Enterprise Service Repository, message mapping can be connected and used.

Create an XSLT Mapping

Business Scenario

In the previous exercise, we received a feed as a response to the API call containing the results. To make the next API call to retrieve the customerID for an ordered product, we must include the SalesOrderId and ItemPosition in the request. To achieve this, we must cache the two values as Exchange Properties for each ProductID loop. To access the feed using XPath expressions, we must remove the namespaces, which can be done using an XSLT template.

The following image provides an overview of where the new component operates.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create an XSLT Template as Mapping component.
  3. Customize the HTTP call Call_fetch_LineItems.
  4. Save as version, deploy, and debug your integration process.

Prerequisites

You have completed the final step of creating a request and replying an external call.

Outcome After This Exercise

A functional XSLT template is available, which removes the namespaces from the payload, enabling access to the values using XPath expressions.

What Do You Learn Within This Exercise?

Learn how to create a mapping component using an XSL template.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Check the status after the last exercise step.

    3. Imagine that integration flow is more edited.

Task 2: Create an XSLT Template as Mapping Component

Steps

  1. Check out the result of the last call.

    1. In your browser run again the following URL to get two (&$top=2) data records. Replace {property.ProductID} with HT-1000.

      Use the following URL: https://< your API >/ProductSet('${property.ProductID}')/ToSalesOrderLineItems/&$top=2

    2. Find the root tag Feed and the name spaces. We have three name spaces * xmlns, xmlns:m, and xmlns:d*.

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910111213141516171819
      <feed 
xmlns="http://www.w3.org/2005/Atom" 
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
xml:base="https://sapes5.sapdevcenter.com/sap/opu/odata/iwbep/GWSAMPLE_BASIC/">
   ........

<content type="application/xml">
        <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
                <d:SalesOrderID>0500000000</d:SalesOrderID>
                <d:ItemPosition>0000000010</d:ItemPosition>
                <d:ProductID>HT-1000</d:ProductID>
.....

</content>
	</m:properties>
........
</feed>

    3. The specific values that we are interested in are uniquely identified by the xmlns:m namespace.

  2. Add an XSLT Mapping component after Call_fetchLineItems.

    1. Add an XSLT Mapping component after Call_fetchLineItems.

    2. Use the create icon within the context-sensitive menu to create a new XSLT template.

      An editor opens.

    3. Enter the following code snippet within the xsl:template element.

      Code Snippet
      Copy code
      Switch to dark mode
      12345678910
      
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	 <xsl:template match="*">
                <xsl:element name="{local-name()}" >
                        <xsl:apply-templates select="@* | node()"/>
                </xsl:element>
        </xsl:template>
</xsl:stylesheet>

    4. This code snippet instructs the XSLT template to copy the entire feed while removing the namespaces.

    5. Change the variable match within the xsl:template element.

      Code Snippet
      Copy code
      Switch to dark mode
      12
      Old:  <xsl:template match="/">
New:  <xsl:template match="*">

    6. Choose the OK button located in the top right corner.

    7. Exit the XSLT editor and return to your integration flow.

  3. Check out the XSLT template.

    1. Choose the XSLT Mapping 1 component to call the configuration bar.

    2. Rename it to XSLT_Mapping_removeNamespaces.

    3. Switch to the Processing tab.

    4. Choose the link /mapping/XSLTMapping1.xsl.

    5. Check out your entry.

    6. Navigate back without changes, with the bread crumb navigation DelayedDelivery_Process.

Task 3: Customize the HTTP Call Call_fetch_LineItems

Steps

  1. Customize the HTTP call Call_fetch_LineItems.

    1. We have observed that the result feed contains 1400 records. Checking the template in the monitor with such a large number of records would be significantly more difficult. To simplify this, we can limit the number of returned records to two.

    2. Open the HTTP connection line at Call_fetchLineItems. Choose the Connection tab.

    3. Add the following addition to the Query:

      &$top=2

Task 4: Save as Version, Deploy, and Debug your Integration Process

Steps

  1. Save as version, deploy, and debug your integration process.

    1. Perform the following steps:

      1. Save as version.
      2. Deploy.
      3. Jump to theOverview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to the Overview → Manage Integration Content.

  2. Verify if the limit of two data records is working correctly.

    1. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    2. As there is only one active ProductID (HT-1000) in the list, we have only one XSLT_Mapping_removeNamespaces step. To view the result message from the previous step, select the corresponding step.

    3. The process is working as expected.

  3. Compare before and after the step, XSLT_Mapping_removeNamespaces.

    1. Choose the step End above without changing the other settings.

    2. After comparing the previous payload, it can be observed that all the name spaces have been removed. This would enable us to access the values using XPath expressions in the next step.

  4. Learn more about the XSLT Mapping component.

    1. Navigate back to your Integration Process, open the configuration panel of the XSLT Mapping component, and choose the question mark icon.

Create and Configure a Second General Splitter

Business Scenario

In the previous step, we received over 1000 data records for a ProductId (HT-1000). To process each data record individually, we need to create a second loop for the results of the Call_fetchLineItem. We have already done this before, so here is a brief description. We will maintain the $top restriction on the http Call_fetchLineItem to simplify monitoring.

To understand the second loop, it is important to examine the context and the step within the respective loop. The iteration specifications are based on the currently set parameters.

Task Flow

In this exercise, you will perform the following steps in the task:

Step 1: Log on to the integration flow DelayedDelivery_Process.

Step 2: Create and configure a second General Splitter.

Step 3: Save as version, deploy, and debug your integration process

Prerequisites

You have completed the last step of creating and XSLT Mapping.

Outcome After This Exercise

A running second General Splitter with name Splitter_iterateOverEntries.

What Do You Learn Within This Exercise?

Review exercise to use and configure a General Splitter.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise

Task 1: Create and Configure a Second General Splitter

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Following the status after the last exercise step.

    3. Imagine that the integration flow is more edited.

  2. Create and configure a second General Splitter.

    1. Set a second General Splitter with name Splitter_iterateOverEntries after XSLT_Mapping_removeNamespaces component.

    2. Enter the following values under the processing tab, which ensures that each entry element is processed individually.

      Field NameValue
      Expression TypeXPATH
      XPATH Expression//entry
      Grouping1
      Streamingflagged
      Stop on Exceptionflagged

  3. Save as version, deploy and debug your integration process.

    1. Perform the following steps:

      1. Save as version.
      2. Deploy.
      3. Jump to the Overview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to the Overview → Manage Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    3. Remember, one product loop and two LineItem loops

      • No. 1: is Loop LineItem one.
      • No. 2: is loop LineItem two.

Create and Configure a Content Modifier for the SalesOrderID

Business Scenario

We are once again storing the SalesOrderID and ItemPosition of each individual data record as Exchange Properties in a familiar manner. The following overview image provides an understanding of the location where the new component works. As this is a repeated exercise, only a brief description is given.

Task Flow

In this exercise, you will perform the following tasks:

Step 1: Log on to the integration flow DelayedDelivery_Process.

Step 2: Create and configure an Content Modifier.

Step 3: Save as version, deploy, and debug your integration process.

Prerequisites

The creation and configuration of a second General Splitter is now complete.

Outcome After This Exercise

The SalesOrderID and ItemPosition values are saved as Exchange Properties within a Content Modifier.

What Do you Learn Within This Exercise?

Review exercise to create and configure a Content Modifier component.

Exercise Options

To carry out this exercise, you can choose from the following options:

  1. Live Environment: Using the instructions provided below, you can perform the steps in your SAP BTP account.
  2. Platform Simulation: Follow the step-by-step instructions within the simulation.
  3. Side-by-side: Follow the step-by-step instructions within the simulation and perform the steps in your SAP BTP account simultaneously.

Note

We strongly recommend to perform the steps in the live environment.
ExerciseStart Exercise

Steps

  1. Log on to the integration flow DelayedDelivery_Process via Integration Suite.

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_randomNumber → DelayedDelivery_Process.

    2. Following the status after the last exercise step.

    3. Imagine that the integration flow has been edited further.

  2. Create and configure a Content Modifier.

    1. Add a Content Modifier component after the Splitter_iterateOverEntries component.

    2. Rename it Modify_setSalesOrderIDAsProperty.

    3. Configure two Exchange Properties.

      Field NameValue
      First value
      NameSalesOrderID
      Source TypeXPATH
      Source Value//SalesOrderID
      Data Typejava.lang.String (S is upper case)
      Second Value
      NameItemPosition
      Source TypeXPATH
      Source Value//ItemPosition
      Data Typejava.lang.String (S is upper case)

  3. Save as version, deploy, and debug your integration process.

    1. Imagine that the integration flow has been edited further.

      1. Save as version.
      2. Deploy.
      3. Jump to the Overview → Manage Integration Content.
      4. Set log level to trace.
      5. Deploy again.
      6. Jump again to the Overview → Manage Integration Content.

    2. Navigate to your Integration Flow Model in Overview → Monitor Message Processing → Message Processing Run.

    3. Check out the first LineItem loop.

    4. The ProductID is set in the first Content Modifier, while the ItemPosition and SalesOrderID are correctly set in the first LineItem loop.

    5. Check out the second LineItemLoop.

    6. You will see that the ProductID is the same, but the ItemPosition and SalesOrderID are different.

Log in to track your progress & complete quizzes