Integration Advisor – The Mapping Runtime Artifacts and their purpose
In this blog post, I will provide you with detailed information on each component of the Mapping Guideline (MAG) Runtime Artifacts that can be generated by Integration Advisor, and how to use them in your SAP Middleware product. If you first wish to find out more information on what a MAG actually is and how to create one, I would recommend to read the blog post on creating a MAG using the MAG Editor. If you are completely new to Integration Advisor and wish to have an overall understanding of the product I would recommend to start with the blog post titled integration content advisor: Overview of components and further reading. From this blog post you will be able to access many other blogs and read them in a logical sequence.
The MAG Runtime Artefacts are one of the key outputs of, and a huge accelerator for, any Integration Scenario implemented using Integration Advisor. In the main section of this blog post I will explain how they are generated, and what each component of the artifacts is to be used for. I will also describe the two different types of Runtime Artifacts that are currently available.
The MAG specific Runtime Artifacts and their purpose
The Interface Implementation Process
The implementation of an interface using Integration Advisor always follows several logical steps:
- Obtain an initial agreement on which Source and Target message types to use, and select them from the appropriate Type System libraries
- Create 2 Message Implementation Guidelines (MIGs) from the selected message types
- Iteratively refine the MIG definitions. As the MIG definitions are refined you can generate the MIG documentation automatically for review by peers and other people involved in the interface definition. In addition, the MIG editor provides the capability to even add review comments against Fields and Segments directly in the MIG definition itself.
- Once the MIGs have been defined the Mapping Guideline (MAG) can be created. Again, this can be an iterative process and for each iteration, the MAG Documentation can be automatically generated for review by others.
- After sign-off of the MIGs and MAG, the Runtime Artefacts can be generated from the MAG Editor for use in the SAP Middleware solution you are using.
The types of Runtime Artifacts available
Currently you can generate two type of Runtime Artifacts using the Integration Advisor, Runtime Artifacts for SAP Process Integration (PI) and/or Runtime Artifacts for SAP Cloud Platform Integration (SCPI or CPI):
- Runtime Artifacts for SAP Process Integration (PI) These are artifacts that can be imported into the Enterprise Service Repository (ESR) of SAP PI. Details of these are specified in the next section. SAP PI is the Enterprise Grade middleware solution provided by SAP that is typically used in On-Premise architectures. Note that the artifacts contain no proprietary mapping language or schemas and can be used in earlier versions of SAP PI as long as an XSLT 2.0 compliant parser is available in the PI system.
- Runtime Artifacts for SAP Cloud Platform Integration (SCPI or CPI) The Runtime Artifacts for CPI comprise mappings and schemas that can be imported as resources into the Integration Flows (iFlows) that form the interface definition objects in CPI. CPI forms one of the core Cloud Services that make up the SAP Cloud Integration Suite available on the SAP Cloud Platform (SCP).
What Runtime Artifacts are generated
When you export the Runtime Artifacts you will find that ZIP archives are created. The filename generally consists of the MAG name, but whitespace and special characters are replaced by underscores (_). As can be seen in the screenshot above, for the Process Integration artifacts, an ‘_PO’ suffix is added to the ZIP file name. These ZIP files can then be:
- For PI or PO, imported directly as an Archive into a Software Component Version (SWCV) in your Enterprise Service Repository (ESR).
- For CPI, the content can be extracted, and imported as mapping or schema resources into your CPI Integration Flow (iFlow).
Contents of the PI Runtime Artifacts
As can be seen in the screenshot above, the contents of the ZIP file for Process Integration are relatively simple. The Process Integration Runtime Artifacts consists of 3 XSL Transformation (XSLT) files:
- The MIG pre-processor XSL – In this case called “MIG-EDIFACT-ORDERS-D01B_PO_preproc.xsl”, this XSLT performs manipulation of the incoming (source) message and adds any qualifier nodes into the XML structure.
- The actual mapping XSL – In this case called “MAG-EDIFACT-ORDERS-D01B-to-IDOC-ORDERS.ORDERS05_PO.xsl”, this XSLT performs the actual mapping of the Source message structure into the Target message structure (but still with qualified nodes).
- The MIG post-processor XSL – in this case called “MIG-IDOC-ORDERS.ORDERS05_PO_postproc.xsl”, this XSLT converts the qualified nodes to render the XML into the final expected Target data structure.
To use the runtime artifacts, the ZIP file should be imported into the appropriate Software Component Version (SWCV) in your ESR and the 3 XSL should be added as 3 steps within an Operation Mapping. This blog post provides the details on how to use the content in an Operation Mapping in your SAP PI or SAP PO instance as well as any other pre-requisites to consider.
Contents of the CPI Runtime Artifacts
The contents of the CPI Runtime Artifact ZIP file are described here next. At the top-level, the ZIP file contains the XSLT for the mapping as well as two folders, one to hold the Source MIG artifacts and the second to hold those for the Target MIG. The one important thing to note is that the contents of the MIG folders will differ depending on which Type System the message is derived from.
In our example we are using an EDI -> SAP IDOC scenario; as a result, additional EDI-specific content is generated. The section below therefore describes the content in relation to this scenario.
- The actual mapping XSL – In this case called “MAG-EDIFACT-ORDERS-D01B-to-IDOC-ORDERS.ORDERS05.xsl”, this XSLT performs the actual mapping of the Source message structure into the Target message structure (but still with qualified nodes).
- Source (EDIFACT) MIG Folder
- The inbound EDI XSD – In this case called “UN-EDIFACT_ORDERS_D01B.xsd”, this XML Schema is used for (optionally) EDI validation and splitting, as well as the EDI à XML conversion
- The MIG pre-processor XSL – In this case called “MIG-EDIFACT-ORDERS-D01B_preproc.xsl”, this XSLT performs manipulation of the incoming (source) message and adds any qualifier nodes into the XML structure.
- The EDI extended validation XSD – In this case called “MIG-EDIFACT-ORDERS-D01B_RD.xsd”, this XML Schema for optional use and allows extended EDI validation after the qualifier pre-processing has taken place.
- Test Data – In this case called “MIG-EDIFACT-ORDERS-D01B_testdata_ICA.xml”, test data is always generated for each MIG, regardless of whether Source or Target. This can be used during iFlow testing to validate the result.
- The MIG post-processor XSL – In this called “MIG-EDIFACT-ORDERS-D01B_postproc.xsl”, this is not used. The post-processor XSL is always generated for both Source and Target MIGs but is not actually required for Source MIG processing.
- Target (IDOC) MIG Folder
- The MIG pre-processor XSL – In this case called “MIG-IDOC-ORDERS.ORDERS05_preproc.xsl”, this XSLT performs manipulation of the incoming (source) message and adds any qualifier nodes into the XML structure. The pre-processor XSL is always generated for both Source and Target MIGs but is not actually required for Target MIG processing.
- The IDOC extended validation XSD – In this case called “MIG-IDOC-ORDERS.ORDERS05_RD.xsd”, this XML Schema for optional use and allows extended IDOC validation after the qualifier pre-processing has taken place.
- The MIG post-processor XSL – in this case called “MIG-IDOC-ORDERS.ORDERS05_postproc.xsl”, this XSLT converts the qualified nodes to render the XML into the final expected Target data structure.
- Test Data – In this case called “MIG-IDOC-ORDERS.ORDERS05_testdata_ICA.xml”, test data is always generated for each MIG, regardless of whether Source or Target. This can be used during iFlow testing to validate the result.
Pre-defined Integration Packages and iFlow templates for CPI
As a further accelerator for CPI interface implementations, we provide a standard Integration Package accessible via the API Business Hub that contains a pre-defined set of templates. These cover several typical scenarios (e.g. EDI -> IDOC, EDI -> SOAP, IDOC -> EDI, IDOC -> cXML, etc.) and the list of templates and scenarios covered is growing rapidly. You simply need to copy the Integration Package into your own CPI tenant and then you can copy and adapt the iFlows to your needs. Of course, as we roll out updates to the Integration Package you’ll be informed and can take on new templates to use. The Integration Package is called “EDI Integration Templates for Integration Content Advisor (ICA)”.
In addition to the templates, you will find comprehensive downloadable documentation explaining in detail how each template can be used and where to utilise each Integration Advisor Runtime Artifact objects in the iFlow steps.
The Runtime Artifacts that can be generated by Integration Advisor are one of the key accelerators that Integration Advisor provides, the other is the MIG and MAG documentation. By supporting the automatic generation of mapping and validation run-time objects, reliance on technical knowledge is reduced to nearly zero. You as the business domain expert can simply use intuitive graphical user interfaces to implement both the Source message structure, the Target message structure as well as the mapping between. Then with a couple of button presses you can automatically generate both documentation and the run-time objects themselves. Typically, in a ‘traditional’ implementation methodology more than 60% of all effort would be spent on these activities. This is reduced dramatically using Integration Advisor. The runtime artifacts can be handed over to your Technical developer to implement the last 15% of the development.
Integration Advisor is a rapidly evolving product with new features being added on a regular basis, so please re-visit our blog posts on a regular basis for news on any changes and enhancements.
Read the following blog posts for more information:
Overview of Integration Advisor: Integration content advisor: Overview of components and further reading
Creating MIGs using the MIG Editor: Integration Advisor: Create a custom interface using the MIG Editor
Creating a MAG using the MAG Editor: Integration content advisor: Create a mapping using MAG editor