Add maps for transformations in workflows with Azure Logic Apps

Applies to: Azure Logic Apps (Consumption + Standard)

Workflow actions such as Transform XML and Liquid require a map to perform their tasks. For example, the Transform XML action requires a map to convert XML between formats. A map is an XML document that uses Extensible Stylesheet Language Transformation (XSLT) language to describe how to convert data from XML to another format and has the .xslt file name extension. The map consists of a source XML schema as input and a target XML schema as output. You can define a basic transformation, such as copying a name and address from one document to another. Or, you can create more complex transformations using the out-of-the-box map operations. You can manipulate or control data by using different built-in functions, such as string manipulations, conditional assignments, arithmetic expressions, date time formatters, and even looping constructs.

For example, suppose you regularly receive B2B orders or invoices from a customer who uses the YearMonthDay date format (YYYYMMDD). However, your organization uses the MonthDayYear date format (MMDDYYYY). You can define and use a map that transforms the YYYYMMDD format to the MMDDYYYY format before storing the order or invoice details in your customer activity database.

This guide shows how to add a map for your workflow to use. You can add maps either to your linked integration account, or if you have a Standard logic app, you can add maps directly to your logic app resource.

Prerequisites

• An Azure account and subscription. If you don't have a subscription yet, sign up for a Azure account.

• The map that you want to add. To create maps, you can use any of the following tools:

  • Visual Studio Code and the Data Mapper extension. To call the maps created with Data Mapper from your workflow, you must use the Data Mapper Operations action named Transform using Data Mapper XSLT, not the XML Operations action named Transform XML. For more information, see Create maps for data transformation with Visual Studio Code.

  • Visual Studio 2019 and the Azure Logic Apps Enterprise Integration Tools extension.

  • Visual Studio 2015 and the Azure Logic Apps Enterprise Integration Tools for Visual Studio 2015 2.0 extension.

    Note

    Don't install the Azure Logic Apps Enterprise Integration Tools extension alongside the BizTalk Server extension. Having both extensions might produce unexpected behavior. Make sure that you only have one of these extensions installed.

    On high resolution monitors, you might experience a display problem with the map designer in Visual Studio. To resolve this display problem, either restart Visual Studio in DPI-unaware mode, or add the DPIUNAWARE registry value.

    For more information, review the Create maps section in this article.

• Based on whether you're working on a Consumption or Standard logic app workflow, you'll need an integration account resource. Usually, you need this resource when you want to define and store artifacts for use in enterprise integration and B2B workflows.

  Important

  To work together, both your integration account and logic app resource must exist in the same Azure subscription and Azure region.

  • If you're working on a Consumption logic app workflow, you'll need an integration account that's linked to your logic app resource.

  • If you're working on a Standard logic app workflow, you can link your integration account to your logic app resource, upload maps directly to your logic app resource, or both, based on the following scenarios:

    • If you already have an integration account with the artifacts that you need or want to use, you can link your integration account to multiple Standard logic app resources where you want to use the artifacts. That way, you don't have to upload maps to each individual logic app. For more information, review Link your logic app resource to your integration account.

    • The Liquid built-in connector lets you select a map that you previously uploaded to your logic app resource or to a linked integration account, but not both.

    So, if you don't have or need an integration account, you can use the upload option. Otherwise, you can use the linking option. Either way, you can use these artifacts across all child workflows within the same logic app resource.

• Consumption and Standard workflows support XSLT maps that reference external assemblies, which enable directly calling custom .NET code from XSLT maps. To support this capability, Consumption workflows also have the following requirements:

  • You need a 64-bit assembly. The transform service runs a 64-bit process, so 32-bit assemblies aren't supported. If you have the source code for a 32-bit assembly, recompile the code into a 64-bit assembly. If you don't have the source code, but you obtained the binary from a third-party provider, get the 64-bit version from that provider. For example, some vendors provide assemblies in packages that have both 32-bit and 64-bit versions. If you have the option, use the 64-bit version instead.

  • You have to upload both the assembly and the map in a specific order to your integration account. Make sure you upload your assembly first, and then upload the map that references the assembly.

  • If your assembly or map is 2 MB or smaller, you can add your assembly and map to your integration account directly from the Azure portal.

  • If your assembly is bigger than 2 MB but not bigger than the size limit for assemblies, you'll need an Azure storage account and blob container where you can upload your assembly. Later, you can provide that container's location when you add the assembly to your integration account. For this task, the following table describes the items you need:

    Item	Description
    Azure storage account	In this account, create an Azure blob container for your assembly. Learn how to create a storage account.
    Blob container	In this container, you can upload your assembly. You also need this container's content URI location when you add the assembly to your integration account. Learn how to create a blob container.
    Azure Storage Explorer	This tool helps you more easily manage storage accounts and blob containers. To use Storage Explorer, either download and install Azure Storage Explorer. Then, connect Storage Explorer to your storage account by following the steps in Get started with Storage Explorer. To learn more, see Quickstart: Create a blob in object storage with Azure Storage Explorer. Or, in the Azure portal, select your storage account. From your storage account menu, select Storage Explorer.

    To add larger maps, you can use the Azure Logic Apps REST API - Maps. For Standard workflows, the Azure Logic Apps REST API is currently unavailable.

Limitations

• Limits apply to the number of artifacts, such as maps, per integration account. For more information, review Limits and configuration information for Azure Logic Apps.

• Based on whether you're working on a Consumption or Standard logic app workflow, the following limitations apply:

  • Standard workflows

    • Support XSLT 1.0, 2.0, and 3.0.

    • No limits apply to map file sizes.

  • Consumption workflows

    • Azure Logic Apps allocates finite memory for processing XML transformations. If you create Consumption workflows, and your map or payload transformations have high memory consumption, such transformations might fail, resulting in out of memory errors. To avoid this scenario, consider these options:

      • Edit your maps or payloads to reduce memory consumption.

      • Create Standard logic app workflows, which run in single-tenant Azure Logic Apps and offer dedicated and flexible options for compute and memory resources.

Create maps

You can create maps using either Visual Studio Code with the Data Mapper extension or Visual Studio with the Azure Logic Apps Enterprise Integration Tools extension.

Visual Studio Code

When you create maps using Visual Studio Code and the Data Mapper extension, you can call these maps from your workflow, but only with the Data Mapper Operations action named Transform using Data Mapper XSLT, not the XML Operations action named Transform XML. For more information, see Create maps for data transformation with Visual Studio Code.

Visual Studio

When you create maps using Visual Studio, you'll need to create an integration project with either of the following tools:

• Visual Studio 2019 and the Azure Logic Apps Enterprise Integration Tools extension

• Visual Studio 2015 and the Azure Logic Apps Enterprise Integration Tools for Visual Studio 2015 2.0 extension.

In the integration project, you can build an integration map file, which lets you visually map items between two XML schema files. These tools offer the following map capabilities:

• You work with a graphical representation of the map, which shows all the relationships and links you create.

• You can make a direct data copy between the XML schemas that you use to create the map. The Enterprise Integration SDK for Visual Studio includes a mapper that makes this task as simple as drawing a line that connects the elements in the source XML schema with their counterparts in the target XML schema.

• Operations or functions for multiple maps are available, including string functions, date time functions, and so on.

• To add a sample XML message, you can use the map testing capability. With just one gesture, you can test the map you created, and review the generated output.

• After you build your project, you get an XSLT document.

Your map must have the following attributes and a CDATA section that contains the call to the assembly code:

• name is the custom assembly name.

• namespace is the namespace in your assembly that includes the custom code.

The following example shows a map that references an assembly named XslUtilitiesLib and calls the circumference method from the assembly.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:user="urn:my-scripts">
<msxsl:script language="C#" implements-prefix="user">
    <msxsl:assembly name="XsltHelperLib"/>
    <msxsl:using namespace="XsltHelpers"/>
    <![CDATA[public double circumference(int radius){ XsltHelper helper = new XsltHelper(); return helper.circumference(radius); }]]>
</msxsl:script>
<xsl:template match="data">
<circles>
    <xsl:for-each select="circle">
        <circle>
            <xsl:copy-of select="node()"/>
                <circumference>
                    <xsl:value-of select="user:circumference(radius)"/>
                </circumference>
        </circle>
    </xsl:for-each>
</circles>
</xsl:template>
</xsl:stylesheet>

Add referenced assemblies

Add maps

• If you're working with a Consumption workflow, you must add your map to a linked integration account.

• If you're working with a Standard workflow, you have the following options:

  • Add your map to a linked integration account. You can share the map and integration account across multiple Standard logic app resources and their child workflows.

  • Add your map directly to your logic app resource. However, you can only share that map across child workflows in the same logic app resource.

Add map to integration account

1. In the Azure portal, sign in with your Azure account credentials.

2. In the Azure portal search box, enter integration accounts, and select Integration accounts.

3. Find and select your integration account.

4. On the integration account's navigation menu, under Settings, select Maps.

5. On the Maps pane toolbar, select Add.

For Consumption workflows, based on your map's file size, now follow the steps for uploading a map that's either up to 2 MB or more than 2 MB.

Add maps up to 2 MB

1. On the Add Map pane, enter a unique name for your map.

2. Under Map type, select the type, for example: Liquid, XSLT, XSLT 2.0, or XSLT 3.0.

3. Next to the Map box, select the folder icon. Select the map to upload.

   If you left the Name property empty, the map's file name automatically appears in that property after you select the map file.

4. When you're done, select OK.

   After your map file finishes uploading, the map appears in the Maps list. On your integration account's Overview page, under Artifacts, your uploaded map also appears.

Add maps more than 2 MB

To add larger maps for Consumption workflows, use the Azure Logic Apps REST API - Maps.

---

Add map to Standard logic app resource

The following steps apply only if you want to add a map directly to your Standard logic app resource. Otherwise, add the map to your integration account.

Azure portal

1. On your logic app resource's menu, under Artifacts, select Maps.

2. On the Maps pane toolbar, select Add.

3. On the Add Map pane, enter a unique name for your map and include the .xslt extension name.

4. Next to the Map box, select the folder icon. Select the map to upload.

5. When you're done, select OK.

   After your map file finishes uploading, the map appears in the Maps list. On your integration account's Overview page, under Artifacts, your uploaded map also appears.

Visual Studio Code

1. In your logic app project's structure, open the Artifacts folder and then the Maps folder.

2. In the Maps folder, add your map.

---

Edit a map

To update an existing map, you have to upload a new map file that has the changes you want. However, you can first download the existing map for editing.

Delete a map

Next steps

• Transform XML for workflows in Azure Logic Apps
• Validate XML for workflows in Azure Logic Apps