Message mapping basics

Contoso Motor Co. is past hypercare on SAP S/4HANA, and Theo's integration team now has to empty SAP Process Orchestration. XP1 runs exactly 64 integrated configurations. The Migration Assessment rated 31 Ready to migrate, 21 Adjustment required and 12 Evaluation required, and 7 had no traffic in 12 months. The architecture decisions are retire 7, keep 31, adapt 12, move 8 and rebuild 6. Everything that isn't retired leaves PO. Most of those interfaces carry a graphical message mapping built in the Enterprise Services Repository (ESR), and about 25 of them are IDoc interfaces. This course teaches the mapping skill they all depend on in SAP Cloud Integration.

The good news for PI/PO developers: Cloud Integration uses the same mapping model. A message mapping has a source structure, a target structure, field-to-field assignments and functions between them. At runtime it reads the source message into queues and builds the target one field at a time. If you understood queues in ESR, you'll recognize them here. If you didn't, lesson 2 fixes that, because queues explain almost every mapping bug.

Where a mapping lives

You can keep a mapping in two places. A Message Mapping flow step with a local mapping definition (an .mmap file) belongs to one integration flow. A Message Mapping artifact lives in the integration package (Artifacts tab, then Add, then Message Mapping) and can be used by many flows. You create an artifact from scratch, upload one as a .zip, or import it from an ES Repository. An artifact must be deployed before any flow can use it.

In the flow step's Processing tab, Reference Type decides how the step finds its mapping. Static points to a local or referenced .mmap file. Dynamic reads the mapping at runtime from a header or property, written as ${header.name} or ${property.name}, whose value has the form ref:<message mapping ID>. It can also read from the Partner Directory as pd:<Partner ID>:<Parameter ID>. One limit to remember: if a flow uses the SAP Process Orchestration runtime profile, SAP says to define the mapping as a flow step, not as an artifact.

Source and target structures

The mapping editor accepts these files for source and target messages: XML Schema (XSD), WSDL (remote references aren't supported), OData V2 or V4 metadata (.edmx or .xml) and Swagger/OpenAPI 2.0 or 3.0 JSON. SAP lists limits for the JSON case: no composed schemas such as anyOf or allOf, no external references, and no objects without properties. For IDocs you upload the IDoc's XSD. Contoso takes it from the imported IDoc in the PO ESR or generates it from the IDoc documentation in S/4HANA (transaction WE60), so the XSD matches the release and extensions actually in use.

For PO content there's a shortcut: Import from ES Repository. Once a connection to the PO system is configured, you choose the ESR, pick a message mapping and import it together with dependent objects such as WSDLs. Some mappings can't run as they are. SAP's examples: a JDBC or RFC lookup has to be replaced by an adapter call that writes the result to a header or property, and adapter-specific message attributes become headers or properties set in a Content Modifier or script. Mappings with imported archives fail to import. These are the reasons why some of Contoso's interfaces landed in adapt or rebuild.

Building a first mapping

1. Add a Message Mapping step to the integration process and choose Create, or open a mapping artifact and choose Edit.
2. Add the source and target messages from your uploaded schema files.
3. Drag a source field onto a target field. A line appears and the target field gets a mapping expression.
4. Select the target field to open the Mapping Expression area, and add functions from the Functions pane between source and target.
5. Use Map all on matching nodes for a quick start, then fix exceptions by hand. Use Export to download the mapping as a spreadsheet for review (SAP notes the row order isn't guaranteed).
6. Save. Function nodes whose outputs aren't connected are removed automatically on save.