Azure Logic Apps Designer: Accessing BizTalk Schema Distinguished Fields
1. Introduction
Within BizTalk Server development there exists a concept known as property promotion which involves defining an XML schema field (or attribute) to be either a Distinguished Field or a Property Field (or both). In both cases the promoted properties are added to a message’s context by the BizTalk messaging engine. However, there are a few important differences between the two types. Property fields can be used for message routing, tracking, are persisted to the BizTalk Message Box database and can be accessed throughout all the phases of BizTalk message processing. Distinguished Fields, on the other hand, can only be access in the BizTalk orchestration workflow, and are not used for routing or persisted; they are essentially aliases which reference an XPath expression pointing to the appropriate XML data field. The method of creating and using Distinguished Fields is as follows:
XML schema field(s) are promoted using the BizTalk schema editor as shown below:
The result of creating these promoted properties causes the BizTalk schema editor to add an xs:annotation field to the BizTalk schema with details of each of the promoted properties as shown below:
Fields that are now marked as distinguished can be accessed in an orchestration workflow using the ‘dot notation’. This makes it easy to retrieve and assign values to the XML schema field, for example:
But when these BizTalk schemas are migrated to a Logic App integration account this functionality is lost; it is not available within the Logic App workflow designer. What follows in the next section of this article is a solution to this problem that will provide the developer with a similar method and development experience of accessing and using these schema fields.
2. Solution Overview
The solution will make use of an Azure Logic Apps Custom Connector. The connector will have two actions: one for getting the schema distinguished field values and presenting them to the developer in the Logic App workflow at design-time, and one for setting the schema distinguished field values.
At design-time the connector ‘Get’ action will need to provide a drop-down list of Integration Account schemas to choose from as a parameter. It will also accept an XML message as a parameter to retrieve the actual value at run-time. It will also need to provide a list of Dynamic content swagger values in the designer representing the schema distinguished fields. The connector ‘Set’ action will also accept two parameters: an XML message and a list of schema distinguished fields and their new values as Key/Value pairs (the key being an xPath expression to the distinguished field).
The Custom Connector will need to make use the extended OpenAPI definitions for dynamic values and schemas, and the Azure Logic Management namespace.
3. Azure Function
Most of the functionality of this solution will be done within an Azure Function. The function will need to perform the following tasks:
Retrieve a list of XSD schemas stored in the Logic App Integration Account;
For a given XSD, return a JSON schema object representing the XSD distinguished fields;
For a given XSD and XML message, return a JSON object containing the distinguished field values;
For a given XML message and a set of Distinguished Field/Value pairs, return an updated XML message containing the new values.
Create a New Azure Function
The steps required to perform this are as follows:
We now need to create a folder for the XSLT map. For this we need to use Kudu. The URL will be in the follow form (just replace the highlighted with the Function Apps name that is being used): https://xxdemos.scm.azurewebsites.net/DebugConsole/?shell=powershell
Login to Kudu, select PowerShell from the Debug Console, navigate to the Azure Function Folder, and type mkdir Maps at the prompt to create a new sub-folder Maps, e.g.:
Create a new file Promotions.xslt and upload the XSLT file to this new sub-folder. The Promotions.xslt code is as follows:
<?xml version="1.0" encoding="UTF-16"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:msxsl="urn:schemas-microsoft-com:xslt"
xmlns:var="http://schemas.microsoft.com/BizTalk/2003/var"
xmlns:s0="http://schemas.microsoft.com/BizTalk/2003"
xmlns:s1="http://www.w3.org/2001/XMLSchema"
xmlns:userCSharp="http://schemas.microsoft.com/BizTalk/2003/userCSharp"
exclude-result-prefixes="msxsl var s1 s0 userCSharp">
<xsl:output omit-xml-declaration="yes" media-type ="application/json" method="text" version="1.0" />
<xsl:param name="Output" select="'json'" />
<xsl:param name="XML" select ="''" />
<xsl:variable name ='inputMessage' select='userCSharp:convertXMLStringToXPathNodeIterator($XML)' />
<xsl:template match="/">
<xsl:apply-templates select="/s1:schema" />
</xsl:template>
<xsl:template match="/s1:schema">
<xsl:if test="$Output='json'">
<xsl:text>{"type": "array", "items": {"type": "object", "properties": </xsl:text>
</xsl:if>
<xsl:text>{</xsl:text>
<xsl:for-each select="s1:element/s1:annotation/s1:appinfo/s0:properties/s0:property">
<xsl:variable name="name" select="userCSharp:getName(string(@xpath))" />
<xsl:text>"</xsl:text><xsl:value-of select="$name" /><xsl:text>": </xsl:text>
<xsl:choose>
<xsl:when test="$Output='json'">
<xsl:text>{"type": "string"}, "</xsl:text><xsl:value-of select="concat('_', $name)" /><xsl:text>": {"type": "string"}</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:if test="$Output='xpath'">
<xsl:text>"</xsl:text><xsl:value-of select="@xpath" /><xsl:text>"</xsl:text>
</xsl:if>
<xsl:if test="$Output='getvalues'">
<xsl:text>"</xsl:text><xsl:value-of select="userCSharp:getValue($inputMessage, @xpath)" /><xsl:text>", "</xsl:text>
<xsl:value-of select="concat('_', $name)" /><xsl:text>": "</xsl:text>
<xsl:value-of select="@xpath" /><xsl:text>"</xsl:text>
</xsl:if>
</xsl:otherwise>
</xsl:choose>
<xsl:if test="position() != last()">
<xsl:text>, </xsl:text>
</xsl:if>
</xsl:for-each>
<xsl:text>}</xsl:text>
<xsl:if test="$Output='json'">
<xsl:text>}}</xsl:text>
</xsl:if>
</xsl:template>
<msxsl:script language="C#" implements-prefix="userCSharp">
<msxsl:using namespace="System.IO" />
<msxsl:using namespace="System.Xml.XPath" />
<![CDATA[
public string getName(string param1)
{
string localName = "local-name()='";
int nameStart = param1.LastIndexOf(localName) + localName.Length;
int nameFinish = param1.IndexOf("'", nameStart + 1);
return param1.Substring(nameStart, nameFinish - nameStart);
}
public object convertXMLStringToXPathNodeIterator(string XML)
{
if (XML != String.Empty)
{
using (StringReader sr = new StringReader(XML))
{
XPathDocument xpd = new XPathDocument(sr);
XPathNavigator xpn = xpd.CreateNavigator();
return xpn.Select("/");
}
}
else
{
return String.Empty;
}
}
public string getValue(XPathNavigator xpn, string xPath)
{
XPathNodeIterator xni = xpn.Select(xPath);
try
{
xni.MoveNext();
return xni.Current.Value;
}
catch(System.Exception ex)
{
return String.Empty;
}
}
]]></msxsl:script>
</xsl:stylesheet>
5. Create a new file project.json and upload the file to the root folder (i.e. the same folder as run.cx). Adding this file will cause the relevant NuGet packages to be loaded. The project.json file should contain the following:
{
"frameworks": {
"net46":{
"dependencies": {
"Microsoft.Azure.Management.Logic": "3.0.0",
"Microsoft.Rest.ClientRuntime": "2.3.10",
"Microsoft.IdentityModel.Clients.ActiveDirectory": "3.14.2",
"Microsoft.Azure.Services.AppAuthentication": "1.1.0-preview"
}
}
}
}
6. In the run.csx file add the following code (you will need to update the three values: subscriptionId, resourceGroup, integrationAccount to match your Azure subscription ID and the name of the resource group and integration account, and mapName with the location of the promotions.xslt file):
#r "Newtonsoft.Json"
using Microsoft.Azure.Management.Logic;
using Microsoft.Azure.Management.Logic.Models;
using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Rest;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net;
using System.Text;
using System.Xml;
using System.Xml.Xsl;
public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, string action, TraceWriter log)
{
string subscriptionId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
string resourceGroup = "xxxxxxx";
string integrationAccount = "xxxxxxxx";
string response = String.Empty;
string content = await req.Content.ReadAsStringAsync();
// Get LogicManagementClient object to access the Integration Account artefacts
var provider = new AzureServiceTokenProvider();
var token = await provider.GetAccessTokenAsync("https://management.azure.com/");
var client = new LogicManagementClient(new TokenCredentials(token));
client.SubscriptionId = subscriptionId;
switch (action)
{
case "list":
// Retrieve a list of Integration Account schema names
var schemas = client.Schemas.ListByIntegrationAccounts(resourceGroup, integrationAccount);
response = "[";
foreach (IntegrationAccountSchema ias in schemas)
{
response = response + "{\"id\": \"" + ias.Name + "\", \"name\": \"" + ias.Name +"\"}, ";
}
if (response.Length > 0) {response = response.Substring(0, response.Length -2);} // Remove trailing comma
response = response + "]";
break;
case "json":
case "xpath":
case "getvalues":
// Get Integration Account schema
string schemaName = req.Headers.GetValues("SchemaName").First();
IntegrationAccountSchema schema = client.Schemas.Get(resourceGroup, integrationAccount, schemaName);
response = execPromotionsXSLT(action, schema.ContentLink.Uri, content);
break;
case "setvalues":
// Iterate through each key/value pair and update the appropriate XML element value
var jo = JObject.Parse(req.Headers.GetValues("SetValues").First());
var xd = new XmlDocument();
xd.LoadXml(content);
foreach (KeyValuePair<string, JToken> xpath in jo)
{
xd.SelectSingleNode(xpath.Key).InnerText = (string)xpath.Value;
}
// Return the update XML document
return req.CreateResponse(HttpStatusCode.OK, xd.DocumentElement, "application/xml");
break;
}
return req.CreateResponse(HttpStatusCode.OK, JsonConvert.DeserializeObject(response), "application/json");
}
private static string execPromotionsXSLT(string xsltAction, string schemaURI, string xmlContent)
{
// The promotions.xslt will return a different JSON object depending on the parameter supplied:
// json - a JSON schema representing XSD distinguished fields
// xpath - a JSON object with the distinguished field name/xpath value as a key/value pair
// values - a JSON object with the distinguished field name/XML value as a key/value pair
string mapName = @"D:\home\site\wwwroot\GetPromotions\Maps\promotions.xslt";
// Load schema
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.Load(schemaURI);
// Set required XSLT objects
XslCompiledTransform transform = new XslCompiledTransform();
XsltSettings settings = new XsltSettings(true, true);
XmlUrlResolver resolver = new XmlUrlResolver();
XsltArgumentList argumentList = new XsltArgumentList();
// Set XSLT parameters
argumentList.AddParam("Output", String.Empty, xsltAction);
if (xmlContent != String.Empty) { argumentList.AddParam("XML", String.Empty, xmlContent); }
// Execute XSLT transform
using (StringReader stringReader = new StringReader(xmlDoc.OuterXml))
{
using (XmlReader xmlReader = XmlReader.Create(stringReader))
{
using (StringWriter stringWriter = new StringWriter())
{
transform.Load(mapName, settings, resolver);
transform.Transform(xmlReader, argumentList, stringWriter);
return stringWriter.ToString();
}
}
}
}
7. On the Azure Functions Integrate blade, set the following values:
8. In the Integration Account Access control (IAM) grant the Azure Function access to the Integration Account:
9. Create two XSD files (provided in Appendix A) and uploaded them to the Logic App Integration Account.
Testing the Azure Function
At this point the Azure Function can now be unit tested to ensure that it works as expected. Create two Header values: SchemaName & SetValues. Perform the four tests below setting the action, SchemaName & SetValues values and reviewing the output. For example, Test 4 will look like this:
Test 1: Get a list of Integration Account schemas
Set: action=list
Output: [{"id":"Address","name":"Address"},{"id":"Person","name":"Person"}]
Test 2: Get a JSON schema object of the XSD’s distinguished fields
Set: action=json, SchemaName=Person
Output: "type":"array","items":{"type":"object","properties":{"Title":{"type":"string"},"_Title":{"type":"string"},"Forename":{"type":"string"},"_Forename":{"type":"string"},"Surname":{"type":"string"},"_Surname":{"type":"string"}}}}
Test 3: Get the XML message values of the distinguished fields
Set: action=getvalues, SchemaName=Person, Request body: <ns0:Person xmlns:ns0="http://AzureBizTalkMapsDemo/Person"><Title>Mr.</Title><Forename>Peter</Forename><Surname>Smith</Surname></ns0:Person>
Output: {"Title":"Mr.","_Title":"/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Title' and namespace-uri()='']","Forename":"Peter","_Forename":"/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Forename' and namespace-uri()='']","Surname":"Smith","_Surname":"/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Surname' and namespace-uri()='']"}
Test 4: Set distinguished field values in the XML message to new values
Set: action=setvalues, SchemaName=Person, SetValues={"/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Forename' and namespace-uri()='']": "Richard"}, Request body: <ns0:Person xmlns:ns0="http://AzureBizTalkMapsDemo/Person"><Title>Mr.</Title><Forename>Peter</Forename><Surname>Smith</Surname></ns0:Person>
Output: <ns0:Person xmlns:ns0="http://AzureBizTalkMapsDemo/Person"><Title>Mr.</Title><Forename>Richard</Forename><Surname>Smith</Surname></ns0:Person>
4. Logic Apps Custom Connector
The configuration of the Custom Connector is defined in an OpenAPI file given in Appendix C. It contains the definition for the four paths given in section 3, but only the retrieving distinguished fields and setting distinguished fields will be visible in the designer. The key parts to this configuration are the x-ms-dynamic-values and x-ms-dynamic-schema tags which define the operation to call at design time to retrieve the required values and present the result in the Logic App designer.
- Create a new Logic App Custom Connector resource;
- Go to the Logic App Custom Connector resource and click edit. A screen like this below will appear:
- Configure the Custom Connector as follows:
1. Upload an OpenAPI file: given in Appendix C;
2. Upload connector icon: given in Appendix C;
3. Icon background color: #3F4790 (‘BizTalk Blue’);
4. Description: BizTalk Promoted Properties and Distinguished Fields;
5. Host: host name of the Azure Function. Should match the host in the OpenApi file;
6. Base URL: /
- Click the Update Connector link in the top-right corner.
5. Testing in the Logic App Designer
Test 1: Retrieving Distinguished Field values from XML messages
1. Create a Logic App work flow like the following (the XML messages are provided in Appendix B):
2. When the new Custom Connector (Get BizTalk Schema Promotions action) is added a drop-down list of Integration Account schemas should be displayed:
3. Compose a JSON object with the XML messages distinguished field values which should appear in the Dynamic content window:
4. When the Logic App is run the following response should be generated:
Test 2: Setting a Distinguished Field value in an XML message
1. Create a Logic App work flow like the following:
2. The important thing to note here is that the Distinguished Field name to use from the Dynamic content is the one prefixed with an underscore (since this value is an xPath string of the Schema field). The Values parameter must be a JSON object of key/value pairs as shown.
3. When the Logic App is run the following response should be generated:
6. Summary
This purpose of this article was to provide a method of accessing Distinguished Fields defined in BizTalk schemas that have been migrated to an Azure Logic App Integration Account. Workflows that makes considerable use of Distinguished Fields will hopefully find the Custom Connector useful. Moreover, the article is also designed to introduce the developer to Logic Apps Custom Connectors and show how they can be used to extend the integration capabilities of Logic Apps. Further, it demonstrates how the Integration Account artefacts can be accessed, both at design-time and at run-time, and how the extended OpenAPI definitions can be used to generate dynamic content within the Logic App designer.
7. References
Deploy and call custom APIs from logic app workflows:
/en-us/azure/logic-apps/logic-apps-custom-api-host-deploy-call
Extend an OpenAPI definition for a custom connector:
/en-us/connectors/custom-connectors/openapi-extensions
How to use Azure Managed Service Identity (public preview) in App Service and Azure Functions:
/en-us/azure/app-service/app-service-managed-service-identity
Use Resource Manager authentication API to access subscriptions:
/en-us/azure/azure-resource-manager/resource-manager-api-authentication
Distinguished Fields vs. Promoted Properties:
https://blog.sandro-pereira.com/2009/03/28/distinguished-fields-vs-promoted-properties/
Microsoft.IdentityModel.Clients.ActiveDirectory Namespace:
/en-us/dotnet/api/microsoft.identitymodel.clients.activedirectory?view=azure-dotnet
Getting started with the Logic Apps SDK:
http://www.bizbert.com/bizbert/2015/10/22/GettingStartedWithTheLogicAppsSDK.aspx
LogicManagementClient class:
/en-us/python/api/azure.mgmt.logic.logicmanagementclient?view=azure-python
8. Appendix A: Schemas Files
Person.xsd
<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://AzureBizTalkMapsDemo/Person" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" targetNamespace="http://AzureBizTalkMapsDemo/Person" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:annotation>
<xs:appinfo>
<b:schemaInfo root_reference="Person" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" />
</xs:appinfo>
</xs:annotation>
<xs:element name="Person">
<xs:annotation>
<xs:appinfo>
<b:properties>
<b:property distinguished="true" xpath="/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Title' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Forename' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Person' and namespace-uri()='http://AzureBizTalkMapsDemo/Person']/*[local-name()='Surname' and namespace-uri()='']" />
</b:properties>
</xs:appinfo>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="Title" type="xs:string" />
<xs:element name="Forename" type="xs:string" />
<xs:element name="Surname" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Address.xsd
<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://AzureBizTalkMapsDemo/Address" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" targetNamespace="http://AzureBizTalkMapsDemo/Address" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Address">
<xs:annotation>
<xs:appinfo>
<b:properties>
<b:property distinguished="true" xpath="/*[local-name()='Address' and namespace-uri()='http://AzureBizTalkMapsDemo/Address']/*[local-name()='Street' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Address' and namespace-uri()='http://AzureBizTalkMapsDemo/Address']/*[local-name()='City' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Address' and namespace-uri()='http://AzureBizTalkMapsDemo/Address']/*[local-name()='State' and namespace-uri()='']" />
<b:property distinguished="true" xpath="/*[local-name()='Address' and namespace-uri()='http://AzureBizTalkMapsDemo/Address']/*[local-name()='ZipCode' and namespace-uri()='']" />
</b:properties>
</xs:appinfo>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="Street" type="xs:string" />
<xs:element name="City" type="xs:string" />
<xs:element name="State" type="xs:string" />
<xs:element name="ZipCode" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
9. Appendix B: Sample Message Files
Person.xml
<ns0:Person xmlns:ns0="http://AzureBizTalkMapsDemo/Person">
<Title>Mr.</Title>
<Forename>David</Forename>
<Surname>Jones</Surname>
</ns0:Person>
Address.xml
<ns0:Address xmlns:ns0="http://AzureBizTalkMapsDemo/Address">
<Street>100 S. Federal Hwy</Street>
<City>Fort Lauderdale</City>
<State>FL</State>
<ZipCode>33302</ZipCode>
</ns0:Address>
10. Appendix C: Custom Connector Files
ConnectorOpenAPI.json
** **
(Replace the highlighted with the host name of the Azure Function)
{
"swagger": "2.0",
"info": {
"title": "BizTalkSchemaPromotedProperties",
"description": "BizTalk Promoted Properties and Distinguished Fields",
"version": "1.0"
},
"host": "xxxxx.azurewebsites.net",
"basePath": "/",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/api/GetPromotions/schema/list": {
"get": {
"description": "Gets a list of all the integration account schemas.",
"summary": "Schema List",
"operationId": "GetSchemaList",
"x-ms-visibility": "internal" ,
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SchemaList"
}
}
}
}
},
"/api/GetPromotions/schema/json": {
"get": {
"description": "Gets a JSON schema for the XML schema's promoted properties and disinguished fields.",
"summary": "JSON Schema",
"operationId": "GetJSONSchema",
"x-ms-visibility": "internal",
"parameters": [
{
"name": "SchemaName",
"in": "header",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
}
}
}
},
"/api/GetPromotions/schema/getvalues": {
"post": {
"description": "Gets the BizTalk schema's promoted properties and disinguished fields for a schema instance.",
"summary": "Get BizTalk Schema Promotions",
"operationId": "GetPromotions",
"parameters": [
{
"name": "SchemaName",
"in": "header",
"required": true,
"description": "Select schema with distiguished fields",
"type": "string",
"x-ms-summary": "Schema",
"x-ms-dynamic-values": {
"operationId": "GetSchemaList",
"value-path": "id",
"value-title": "name"
}
},
{
"name": "xml",
"in": "body",
"schema": { "type": "string" },
"x-ms-summary": "XML"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/DynamicResponseGetPromotions"
}
}
}
}
},
"/api/GetPromotions/schema/setvalues": {
"post": {
"description": "Sets the BizTalk schema's promoted properties and disinguished fields for a schema instance.",
"summary": "Set BizTalk Schema Promotions",
"operationId": "SetPromotions",
"parameters": [
{
"name": "xml",
"in": "body",
"required": true,
"schema": { "type": "string" },
"x-ms-summary": "XML"
},
{
"name": "SetValues",
"in": "header",
"required": true,
"description": "{ \_field\:, \value\, ... }",
"type": "string",
"x-ms-summary": "Values"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
}
}
}
}
},
"definitions": {
"SchemaList": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
},
"DynamicResponseGetPromotions": {
"type": "object",
"x-ms-dynamic-schema": {
"operationId": "GetJSONSchema",
"parameters": {
"SchemaName": {
"parameter": "SchemaName"
}
},
"value-path": "items"
}
}
},
"parameters": {},
"securityDefinitions": {},
"security": [],
"tags": []
}
ConnectorIcon.png
