SAP Cloud Integration mapping: Your options explained and compared

[MortenWittrock]

Introduction

One of the core functions of any integration platform is to translate between the various message formats understood by the systems, applications and services that we integrate. In Enterprise Integration Patterns terminology, this is the Message Translator pattern. These transformations are colloquially known as mappings, and every integration platform offers its own set of tools for building them.

In this blog post, I’d like to introduce you to the mapping options provided by SAP Cloud Integration, namely:

• Message mapping
• XSLT
• JavaScript and Groovy scripting

I will give you an overview of each option, and discuss their pros and cons. Plus a one-sentence TL;DR summary for the busy reader 🙂

Message mapping

The TL;DR version: Message mapping is easy to learn, and can be a very effective tool, but beware that if you apply it to the wrong problem, things can get ugly.

Overview

Message mapping is a graphical mapping tool, that doesn’t require any coding. Unlike the other two mapping options, the message mapping tool is built right into the SAP Cloud Integration UI. You construct a message mapping by connecting source structure fields to target structure fields via drag and drop, and possibly inserting functions in between.

The image above is an example of fields being mapped in a message mapping. When the mapping runs, the concat function will concatenate the contents of the FirstName and LastName source fields, and the result will be copied into the FullName target field.

The tool has a library of built-in functions for doing calculations, string handling, conversions etc. In addition to those, you can add your own, custom functions written in the Groovy scripting language.

A very similar message mapping tool ships with SAP's on-prem integration platform SAP PO, so developers coming from that background will feel right at home with SAP Cloud Integration’s version. You can also import existing message mappings from SAP PO via Cloud Connector.

Initially, message mapping supported only XML to XML transformations, but support for JSON (specifically Open API service definitions) was added later.

Pros and cons

The message mapping tool is exceedingly easy to pick up and get started with; you can learn the basics in a very short amount of time. It excels at mapping tasks of low to medium complexity. For that category of problems, message mapping can be a very effective tool.

However, solving highly complicated mapping problems with message mapping tends to result in mappings that are overly large, messy and disproportionately hard to test and maintain. In other words, be mindful of whether message mapping is a good fit for the task at hand.

XSLT

The TL;DR version: For XML to XML mapping, XSLT is the most powerful of the three mapping options, but that power comes at the cost of a steep learning curve.

Overview

Extensible Stylesheet Language Transformations (XSLT for short) is an XML language for transforming XML documents into other XML documents, HTML, JSON or text. An XSLT transformation is called a stylesheet (not to be confused with Cascading Style Sheets, which describe the presentation of HTML documents). XSLT is a standard maintained by the World Wide Web Consortium (W3C). SAP Cloud Integration supports XSLT 3.0, the latest version of the standard.

XSLT development revolves around writing templates. A template creates a part of the stylesheet’s output. It can match parts of the input document, or it can be called by name from another template. The XPath query language (another W3C standard) is used to navigate the input XML document. XPath enables the developer to pinpoint locations in the input in a very succinct way. Using XPath, extracting a value from a deeply nested, complicated XML structure can be trivial.

The stylesheet in the image above performs a so-called identity transformation, i.e. its output is identical to its input.

SAP Cloud Integration offers a rudimentary, built-in XSLT editor, but its functionality is very limited. If you want conveniences like debugging and stylesheet validation, you need a separate tool (typically an XML editor such as XMLSpy or Oxygen).

Pros and cons

Of the three mapping options offered by SAP Cloud Integration, XSLT is without a doubt the most powerful for XML to XML mappings. Faced with a complicated transformation, like mapping a large IDoc to a deeply nested XML structure, XSLT should be your first choice.

However, the language has a steep learning curve, that must be climbed, before one becomes productive. Also, if you want to get serious about XSLT development, you will need an XML editor, and that means one more tool to learn (and likely pay for as well).

One additional benefit of XSLT, is that stylesheets are text files, that you can store in a version control system like Git.

JavaScript and Groovy scripting

The TL;DR version: If the developer is willing to manage all aspects of a mapping themselves, scripting offers more flexibility and more control over input processing and output generation than message mapping and XSLT.

Overview

The Script step lets you add scripts written in Groovy or JavaScript to your integration flows. Script code can access and modify the contents of the exchange, like properties, attachments, headers and the message body. In addition to that, scripts can use built-in and external class libraries.

Scripts serve multiple purposes in SAP Cloud Integration, and one of those purposes is mapping. The image above is an example of a simple mapping performed in Groovy. It transforms a CSV-formatted message into an XML document. While the code is simplified for the sake of brevity, it does demonstrate the two main tasks performed by all mapping scripts:

• Process the input message
• Generate the output message

If you are handling plain text or XML, the built-in classes will go a long way. To process, say, an Excel spreadsheet attachment, you need an external library.

As is the case with XSLT, SAP Cloud Integration offers a very basic, built-in script editor. However, most developers opt for external editors or IDEs with a much richer feature set.

For a very comprehensive look at Groovy mappings in Cloud Integration, please see the blog post I *heart* Groovy mapping by SAP Mentors alumnus @engswee.

Pros and cons

Mapping in script code gives you full control over how the input is processed and how the output is generated. This is obviously great, and it lets you write, for instance, advanced text processing that goes well beyond the built-in capabilities.

The other side of that coin, though, is that the developer needs to manage every single aspect of the mapping themselves. This is due to the fact that JavaScript and Groovy are general-purpose programming languages, whereas message mapping and XSLT are specialised tools.

Also, if you are new to JavaScript, Groovy or indeed programming in general, there is a sizeable learning curve to overcome, before you become productive.

Like XSLT stylesheets, scripts have the added benefit of being text files, which means you can store them in your version control system.