Integration Advisor – change in namespace handling of root node
In this blog post I would like to share with you an update in the logic on how Integration Advisor (of SAP Integration Suite) handles namespace declarations for message root nodes. I will also explain if and how your existing Message Implementation Guidelines (MIGs) and Integration Flows are affected by this change and what you should remember when you update your runtime artefacts in your Integration Flow next time. This relates to your existing MIGs for SAP S/4HANA SOAP Type Systems and Custom Messages (only if a namespace is used). These changes have been applied with the latest software update from June 2023.
Earlier and extended namespace support
In the past, Integration Advisor only had a preliminary support for namespace handling. We allowed namespace prefixes only at the root node level (as common for so called form=unqualified) and removed these prefixes as part of the actual Integration Advisor processing.
In the screenshot above, you see an example of an Integration Flow in connection with Integration Advisor artifacts. The green box marks the processing steps considered as IA-internal processing (between IA-preprocessing and IA-postprocessing). Earlier, the root node of the message payload did not carry the namespace prefix in the processing steps inside this green box. To be precise, these namespace prefixes were removed in the IA-preprocessing and added in the IA-postprocessing (flow step “SAP SOAP – Qualifier Post-Processing”).
One of the recent additions to our Type System library is the GS1 XML library. In this context, we have also extended our features to support XML elements and attributes which are part of a namespace and require a namespace declaration (so called form=qualified). You can find more information in this blog post: Link
To have a uniform behavior we have also changed the logic for existing messages to be in sync with the new approach.
What has changed?
A node will now carry its namespace prefix in the IA-internal payload format if this is required by the message standard. To put it simply, the namespace prefix will no longer be removed by the IA-preprocessing and thereby is not required to be added by the IA-postprocessing.
In the above screenshot you see an example message payload for the message OrderRequest (from the Type System “SAP S/4HANA Cloud SOAP”). As indicated by the green box, the root node is now called ns1:OrderRequest (earlier OrderRequest without namespace).
This change is relevant for message types from the following Type Systems:
- SAP S/4HANA Cloud SOAP
- SAP S/4HANA On Premise SOAP
- Custom Messages (if the message is defined in a namespace).
What are the consequences at runtime?
Firstly, this change has no immediate impact on the runtime behavior of your Integration Flows. This will only come into effect once you trigger a new Export of Runtime Artifacts and update your Integration Flow.
Secondly, the Runtime Artifacts generated by Integration Advisor will work together seamlessly – this applies to both the previous and the new approach. However, old and new Runtime Artifacts (XSLTs, XSDs) are not compatible and therefore a mix of old and new files won’t work.
What do you need to know and do?
If you want to update your Integration Flow, you need to replace ALL the files using the latest export of runtime artifacts. (Replacing only some files while keeping others would lead to the before described incompatibility of old and new files.)
Moreover, when you plan to update your Integration Flow first time after this new behavior is applied, you should check if one of the following (seldomly occurring) situations applies to your Message Implementation Guideline (MIG) or your Integration Flow:
- Your MIG uses XSD Assertions and the XPath of any of your MIG Assertions uses an absolute path starting from the root node.
- If this is the case, you need to change the XPath of your Assertion to include the namespace prefix of the root node.
- Or preferably use a relative XPath starting from the level where you have defined the XSD Assertion.
- Your Integration Flow has an additional flow step within the IA-internal processing (see green box in first screenshot) and this flow step defines an absolute XPath including the root node.
- If so, you also need to add the root node namespace prefix to this XPath.
- Your Integration Flow has an additional flow step within the IA-internal processing and this flow step is executing an additional processing/transformation (like a Groovy or XSLT script).
- If so, you need to check if your script needs to be updated as well.
And how do you figure out which namespace prefix should be added? You can simply open your MIG in the MIG Editor, click on the root node and navigate to the technical details shown under the Identifier section in the Details tab. The field XML Node Name shows the exact way how this node is called in an XML Payload and will contain the namespace prefix if required.
Which of your MIGs are affected?
In general, this new behavior will apply to all new and existing Message Implementation Guidelines (MIGs).
For all the existing MIGs that are affected by this change, we have automatically made the required adoptions such that these MIGs work in the new way. In such cases, you will find a new Notification on the root node of your MIG that informs you about this change. Refer this screenshot for example:
In the next couple of months we will also show a warning whenever you try to export new runtime artefacts (for MIGs or MAGs) to remind you that your MIG or one of your MIGs (in case of MAG) follow the new behavior.
This blog post summarizes the new behavior around namespace declarations for the root node as well as the question if and how your MIGs and Integration Flows are affected by this.