Message transformations is one of the main topics when Azure technologies are used for integration solutions. There are several ways to do it, each one with their own pros and cons. Here we will explain 3 ways to perform XSLT Transformations in Azure and will provide reasons to help you choose the best scenario to apply them. Let’s put things in context.
What do we mean when we say transformation?
A transformation is a data structure translation, in which data moves from one structure to another. This can also be referred to as “mapping”. For example, we receive an invoice in the structure our suppliers use, and then we transform it to the structure our internal systems are expecting.
The 3 techniques
We will explain how to apply those transformations using the following three techniques, which require:
- Azure Integration Accounts and Logic Apps
- An Azure Function App
- An Azure API Management Policy
Azure Integration Accounts and Logic Apps
The Integration Account is the solution provided by Microsoft Azure to integrate business functions and data sources. It enables customers to take advantage of Logic Apps B2B / EDI and XML processing capabilities. In it you create, store, and manage B2B artefacts, such as trading partners, agreements, maps, schemas, certificates, and so on. The Integration Account needs to be bound to the Logic App where it will be used before you can work with its artefacts and be able to use them in Logic Apps operations, such as Transform XML or XML validation.
- It is the suite designed by Microsoft to create B2B integrations in the cloud.
- An integration account contains out-of-the-box support for all the artefacts you need.
- Integration accounts are native to Logic Apps.
- Higher cost compared to Pas-as-you-go especially on low usage scenarios due to fixed costs hosting the integration account.
The implementation should be done by uploading the map as an XSLT file, should it have references to assemblies that extend the XSL functionalities, those assemblies also have to be uploaded to the integration account.
Sample 01 – Example of an Integrations Account.
To bind the Integration Account with a Logic App you need to follow the following configuration step:
Sample 02 – Configuration at a Logic App bound with an Integration Account.
Once you have completed this, there is a full set of actions you can perform taking advantages of the Integration Account.
Sample 03 – XML Operations selection at Logic App.
To perform XML transformations, you need to select the option “Transform XML”.
Sample 04 – Transform XML Operation.
This option displays the maps present in the Integration Account and let you select the correct one to apply the transformation required to the input message. The input message could be a web request, or a file dropped in a FTP Server or OneDrive – the important thing is you need to pass XML content to the Transform XML function.
Sample 05 – Transform XML Operation with values as example.
Of course, you can create schema validations on the input and output of this map using the XML Validation function and the schemas uploaded to the integration account.
Sample 06 – XML Validation Operation.
In this example, we fill in the values with the output of the transformation to validate the resulting CDM schema.
Sample 07 – XML Validation Operation with values as example.
There are different Price Tiers to choose from. These are Free, Basic or Standard and here are the main uses for them:
- Free: For exploratory scenarios, not at production scenarios (no SLA).
- Basic: For when you want only message handling or to act as a small business partner that has a trading partner relationship with a larger business entity.
- Standard: For when you have more complex B2B relationships and increased numbers of entities that you must manage.
Sample 08 – Integration Account price tier limits.
For more information about price tiers you can find it in the following links:
An Azure Function App
One of the issues with the Integration Account is that its sole existence has a cost, since it is an entire solution thought to resolve complex B2B scenarios, but you may not need all of what it offers. In those cases, a good alternative could be having a custom Azure Function App to perform the transformations you need.
- It is one of the core functionalities of a serverless architecture, so you can choose to pay only for the usage with the Pay-As-You-Go methodology.
- Auto scales in case that needs more power processing this function. It is excellent for processes with a variable load.
- Function App HTTP trigger time-out in 230 seconds (*).
- Execution frequency, if the function will be executed continuously by multiple clients, estimate the usage and calculate the cost of using functions accordingly.
(*) Note: Regardless of the function app timeout setting (default 5 min, up to 10 min), 230 seconds is the maximum amount of time that an HTTP triggered function can take to respond to a request. This is because of the default idle timeout of Azure Load Balancer. For longer processing times, consider using the Durable Functions async pattern or defer the actual work and return an immediate response.
Our example is based on the information provided in the following post, which contains code that is free to use. Find it here:
Basically, the idea is to have a function which will receive an XML message. For example, a Logic App will call such function passing the XML message to be mapped.
To process the message and transform it to the correct output, we will need to have access to the XSLT maps required for this operation. Those need to be stored somewhere – this is why two Azure Blob stores are being used: one has the xslt files named mappers, and the other has all the DLL files for the extension objects and named extensionobjects. Both names are configurable from the Function App settings, creating the entries for Containers__Mappers and Containers__ ExtensionObjects as is shown in the screenshot below.
Sample 09 – Azure Blob stores created to hold the xslt files and extensionobject Dll files.
Those are being referenced in the Function App settings:
Sample 10 – Function App settings referring to the blob stores containers configured.
To call the Function App you just need to make a HTTP POST request. If you are planning to call it from a Logic App, it is a requirement to integrate with a Microsoft API management for security matters. The call from the Logic App could be done with this simple operation.
Sample 11 – Call of the Function App from the Http Request Operation in a Logic App.
Our implementation contains an improvement that simplifies the call to the Azure Function App. We changed the JSON schema to only 2 parameters, providing a cleaner call with no clutter.
Optional: a third parameter could be added to the call including the maps metadata file name, this allow to have different files where you can store those relations:
All the relationships between the extension objects and the XSL code have been moved to a single XML file hosted in a new Azure blob store. For example, if this function is used in multiple logic apps and the XSLT map changes requiring more extension objects or different ones, we do not need to update the parameters in all the function calls to contain these new references. Instead the details about the relationship of this map and its extension objects is updated in one single place, the metadata XML file, leaving all the calls intact.
Two new settings are being configured to apply this new feature; they are identified by the red rectangle. The blue rectangles are originals settings for this Azure Function App.
Sample 12 – Function App settings referring the original custom configurations and the two new added for our implementation.
If you are wondering about price tiers, they are detailed here: https://azure.microsoft.com/en-us/pricing/details/functions/
An Azure API Management Policy
The last – but not least – option is to use an Azure API Management Policy, which allows to transform the inbound(request) and outbound(response) messages of the API.
- If you always need to map the inbound messages (requests) or the outbound messages (responses) using an XSTL map, you can avoid having this transformation in your business logic by using a Policy.
- You probably already have an Azure API Management Service calling your Logic Apps or other services, so this will not add extra costs and it will just simplify your overall process.
- You cannot call external resources - everything needs to be included in the same XSLT. (No external templates or binaries)
- The template is compiled but if you are using very complex XSLT and huge XML blocks be aware that it could have an impact at the performance.
To implement this kind of transformation you need to edit the API policies statement and introduce the block where the transformation policy needs to be applied, for example in the inbound of an API call.
Press the code editor:
Sample 13 – Example of an Azure API Management panel including an xsl-transformation.
In the options to the right, navigate to the “Transformation policies” section and click on “Transform XML using an XSLT”. This will insert the <xsl-transform> … </xsl-transform> block with a basic XLST as example.
Sample 14 – Example of an xsl-transform block insertion at the inbound call of an API.
You need to introduce the content of the XSLT used in the transformation between the tags
Note: They can be added to All Operations (API level) or to a particular operation.
You can find a great example at this page: https://channel9.msdn.com/Blogs/Azure/XSLT-Policy-in-API-Management.
Here is the pricing for the API Management usage: https://azure.microsoft.com/en-us/pricing/details/api-management/.
- Transformations that handle B2B, are complex and include many artefacts relations such as schema validations, partners, maps, custom functions at assemblies, etc. We would recommend using Integration Accounts.
- For transformations with a variable load, we recommend using an Azure Function App. There’s no need to pay extra costs to host an Integration Account and you can use Pay-as-you-go.
- For transformations which always need to be performed in the request to an API or in its response, use the Azure API Management policies.
- You can of course use any combination of all of them and they can be applied in many scenarios.