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.

Screenshot of the Mapping Editor. Information about the steps are provided in the following text.

  • 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 can 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 a helpful 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:

  • 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/"

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

Screenshot of the Source XML.

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

Screenshot of the XSL Stylesheet.

The result after transformation:

Screenshot of 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:

Screening to the source JSON Payload.
Screenshot of the Groovy script.
Screenshot of the Result.

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. Now, 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 and Configure a Content Modifier for SalesOrderID and ItemPosition

Business Scenario

To expand your integration process, you want now to store the currently processed SalesOrderID and ItemPosition and enrich it in this process. The option to use an Exchange Property into a Content Modifier enables you to enrich your Message.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create and configure a Content Modifier.
  3. Save as version, deploy, and debug your integration process.

Prerequisites

You have completed the task of creating and configuring an OData call.

Outcome after this exercise

The Exchange Property is used to store the SalesOrderID and ItemPosition that is being processed.

This graphic shows the outcome.

What do you learn within this exercise?

You learn how to use and configure a Content Modifier with an Exchange Property.

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

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

    1. Navigate within the Integration Suite welcome page to Design → Integrations → DelayedDelivery_Package_CLD900_Date_Number → DelayedDelivery_Process_Number.

    2. This is the status after the last exercise step.

      The graphic shows the start of the exercise.

Task 2: Create and Configure a Content Modifier

Steps

  1. Enlarge the swim lane of your processes.

    This graphic shows the enlargement of your process.

    1. Keep adjusting the right border of your swim lane until the border line becomes active.

    2. Use the mouse to drag the center point towards the right side.

    3. Proceed in the same manner to the right of the End_Message_ Events.

  2. Create and configure a Content Modifier.

    1. Position an additional Content Modifier object after the General Splitter, just like at the beginning.

      The graphic shows the adding of a content modifier.
      Choose the Content Modifier artifact.

    2. Name it Modify_setProductIDasProperty.

      The graphic shows the naming of the Content Modifier.

    3. Switch to the Exchange Property tab.

      The graphic shows the Exchange Property setup.

    4. Choose the Add button, and enter the following data.

      Field NameValue
      ActionCreate
      NameSalesOrderID
      Source TypeXPATH
      Source Value//SalesOrderID
      Data Typejava.lang.String (S in upper case)
      Second Value 
      ActionCreate
      NameItemPositionID
      Source TypeXPATH
      Source Value//ItemPositionID
      Data Typejava.lang.String (S in upper case

Task 3: 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 Overview → Manage Integration Content.
      4. Set the log level to trace.
      5. Deploy again.
      6. Jump again to Overview → Manage Integration Content.

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

      Screenshot of the trace monitoring.

    3. Choose the End_Message_with_ProductID event from the first loop.

    1. Switch to the Message Content tab, and choose the Exchange Property link.

      Now, you see the cached ProductID, SalesOrderID, and ItemPositionID as properties, which are set correctly.

    2. Switch back to the Integration Flow Model tab.

    3. Now, choose the Message Content tab and then choose Exchange Properties.

    Screenshot of the Exchange properties cached.

  2. Learn more about the Content Modifier component.

    1. Return to your Integration Process.

    2. Access the configuration bar of the Content Modifier.

    3. Choose the question mark symbol.

      questionmark

    4. You are taken directly to the Help site of the Content Modifier.

      Screenshot of the Define Content Modifier in SAP Help Portal.

Create and Configure a second Router

Business Scenario

After extra exchange properties have been used with the Content Modifier and the message query has been expanded, empty information must be filtered out. This can be made visible using the router artifact.

Task Flow

In this exercise, you will perform the following tasks:

  1. Log on to the integration flow DelayedDelivery_Process.
  2. Create and configure a Router.
  3. Save as version, deploy, and debug your integration process.

Prerequisites

The creation of a Content Modifier with the Exchange Properties has been completed by you in the last step.

Outcome after this exercise

A working integration flow with a filtering of non existent SalesOrderIDs.

Outcome.

What do you learn within this exercise?

Get familiar with on how to use and set up a Router that consists of two routes.

Task 1: Log on to the Integration Flow DelayedDelivery_Process

Steps

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

    1. Navigate within the Integration Suite Welcome page to Design → Integrations → DelayedDelivery_Package_CLD900_Date_Number → DelayedDelivery_Process_Number.

    2. Follow the status after the last exercise step.

      Exercise start.

Task 2: Create and Configure a Router

Steps

  1. Set a Router.

    1. Place a router artifact in a known way according to the Modify_setSalesOrderIDandItemPositionIDasProperty, name it Router_SalesOrderID.

      Router.

    2. Rename the existing End Message Event to End_Message_with_ProductID.

  2. Create the following Condition in the router:

    1. Choose the line between the router and the End_Message_with_ProductID artifact. Choose the General tab and change the name from Route 1 to SalesOrderID_Available.

      Name router.

    2. Switch to the Processing tab. In the Condition field, enter the following (that means if at least one child product exists, take this path):

      /ProductSet/Product/ToSalesOrderLineItems/SalesOrderLineItem/count(SalesOrderID)>0.

      Router processing tab.
      NameInput
      Condition

      /ProductSet/Product/ToSalesOrderLineItems/SalesOrderLineItem/count(SalesOrderID)>0

  3. Create the default route.

    1. A default route is essential in all cases, and for this purpose, we can use a second Message End event. In order to achieve this, choose the navigation menu plus and add an End Message Event artifact. Now, you can move the SalesOrderID_Available route slightly downwards.

      add an end message
      Name route no sales order id available.

    2. Change the name of this new route to No_SalesOrderID_Available.

    3. Name the new End event End_Message_without_SalesOrderID.

    End message without sales order id.

    1. Rename the existing End_Message_with_ProductID event to End_Message_with_SalesOrderID.

      End message with sales order id.

    2. Go to the Processing tab, and set the No_SalesOrderID_Available route as the default one.

      Set route as default.

Task 3: 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 Overview → Manage Integration Content.
      4. Set the log level to trace.
      5. Deploy again.
      6. Jump again to Overview → Manage Integration Content.

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

    3. As the product list contains both existing and non existent IDs, it is necessary to follow both paths.

      Go to the monitoring and first choose the End_Message_with_ProductID artifact. Choose the Message Content tab and check the Payload without any SalesOrderID information.

      Monitoring trace without sales order id.

    Now, you see entries for some SalesOrderIDs.

    Monitoring trace with sales order id.

    1. Now, check the monitor trace messages without SalesOrderIDs. To do this, choose the End_Message_without_SalesOrderID artifact and choose the Message Content tab to check the payload with SalesOrderIDs.

      Monitoring without sales order ids.

      Now, you see entries for some SalesOrderIDs without any entries.

      Monitoring payload without sales order ids.

  2. Learn more about the Router component.

    1. To access the help page for the router, navigate to your integration process, open the configuration bar of the Router, and choose the question mark symbol. This brings up the Help page in the usual manner.

Log in to track your progress & complete quizzes

Learning

SAP FacebookSAP YoutubeSAP LinkedIn