I was recently working with a customer that has been using BizTalk Server 2016 for quite a while and they wanted to start using Azure Logic Apps for some of their processes. I will note here that they were not in the process of completely moving off of BizTalk, but instead were just moving a few of the simpler processes out of BizTalk and were curious to see what Logic Apps could do for them.
What the customer wanted to do was use their BizTalk mapping file artifacts, as is, and use that artifact inside of a Logic App action to do a transformation to transform an incoming flat-file to an XML file.
The quick, executive summary answer to this question is, no, you can’t use the BizTalk mapper file inside of a Logic App. However, all is not lost, if you are on your BizTalk server machine and have your mapper artifacts, you can still achieve your goal. Otherwise, this would be a very short blog post.
In this blog post, we will go through the steps from BizTalk Server to Logic Apps, to transform a flat-file to an XML document. We won’t go through the process of actually creating the map itself, but we’ll look at it in the BizTalk Flat File Mapper.
Step 1 – Discover your BizTalk artifacts
Shown in the screenshot below is my BizTalk project that contains a BizTalk map (.btm file) and the source and destination schemas (.xsd files). In the case of this example, I am using Visual Studio 2015 because that was installed automatically on my BizTalk Azure VM. Here is a screenshot of my project.
To keep things simple, I’m not using Functoids or loops or anything like that. The purpose of this blog post is to discover how to go from what we have above, to Logic Apps. What we want to achieve though, is to use a Logic App to perform the transformation that BizTalk would have done for us.
Step 2 – Getting your XSL
As I said at the beginning of this post, you can’t use the BizTalk.btm map file with a Logic App. But really, it isn’t this .btm format file that you need, it is the XSL that is generated FROM this mapping operation that you need. But how to you get the XSL? It’s easy….
1. Right-click on your .btm file in the Visual Studio Solution Explorer and select the Validate Map menu item.
2. In the Visual Studio output window, you will see that the mapping component is going to be invoked (validated) and Visual Studio will report where the output XSL is located:
3. Go to the location/path listed in your output window and copy the .xsl file to a location where you can later use it with your logic app. Note that you will also need to copy both source and destination schemas for the Logic App to use too.
Step 3 – Creating your Logic App Integration Account
Normally, one might think that we would just start out right away and create a logic app. In our case however, we are going to need to use built in logic app actions that are designed to be used for ‘integration’. Actions such as transforms, XML validations, flat-file decoding etc. Generally speaking, what BizTalk is used for is enterprise integration and therefore, we need to use enterprise integration functionality that is not available in a normal logic app.
Anytime we are using integration actions, we need to create an integration account. Steps for creating an integration account can be found here. Perform that process now. You can set the Pricing Tier to Free.
Step 4 – Setting up your Integration Account
The simplest form of enterprise integration consists of source and destination schemas with an XSLT transform in the middle to perform some sort of transformation. After your integration account has been created, click on its icon from within your resource group.
What you will see are tiles for Schemas (.xsd), Maps (.xsl/.xslt), Assemblies etc.
1. Click on the Schemas tile.
2. Click on the +Add toolbar icon.
3. Give your schema a name (it doesn’t have to match your actual file name, although it probably should).
4. Browse for your actual schema file.
5. Select Ok to upload your schema file.
6. Repeat 1 – 6 for the second schema.
7. Go back to the tiles view in your integration account and click on the Maps tile.
8. Enter your map name and then select the Map type of XSLT. Upload the file.
Step 5 – Creating your Logic App
1. You will need to create a new Logic App. You can find basic instructions on how to do that here. Wait before you actually create the logic app, i.e., picking a template. You may be pushed right to the logic apps designer. If this is the case just go back to the main blade for the logic app.
2. Click on the Workflow settings menu item.
3. Click on the Integration account dropdown and find the integration account you previously created.
4. Click the Save button at the top of the blade.
5. Click on the Logic app designer menu item.
6. Choose the Blank Logic App template tile.
7. In the logic app design window, type in ‘http’ and then scroll down and choose the ‘When HTTP request is received’ icon. You will be passing in just flat-file data. Save the logic app.
8. Click the +New step button.
9. Type in ‘flat file’ and you should see the Flat File Decoding action. Select this action. The flat file decoder action outputs an xml document that you may do further conversions on. It also helps validate that the incoming flat file structure matches the schema.
10. For the Content setting, click your mouse in the content edit field and on the right-hand side, choose ‘See more’. From there, click on Body. This will insert the Body into the content field.
11. Click on the Schema Name drop-down and select the name of your schema, which in my case is BuyerFlatFileSchema. Save the logic app.
12. Click on the +New step button.
13. Type ‘xml validation’ into the search field and then select the XML Validation action. In the previous step, the flat file decoding step decoded the flat file document into XML, now you need to validate that XML against the SAME schema as in the last step. This may seem like an unnecessary step, but it is the kind of guarantee that most B2B processes expect as a document flows through the system.
14. For the Content, click in the content edit field and then choose Body in the dynamic content window.
15. For the Schema Name, choose the BuyerFlatFileSchema schema. Save the logic app.
16. At this point, you have gotten the flat file into the process, decoded it in to XML and validated the XML. The next thing that typically happens is that you need to confirm that the incoming XML document only has one root node. I cannot map one document format to another with the map from my BizTalk project if the document has more than one root node.
To validate this, you will using an xpath expression.
17. Click on the +New step button.
18. Type in Condition into the search field and select the Condition control icon.
19. Click the checkbox adjacent to the first edit field and place your cursor in that field. Select the Add dynamic content link if the dynamic content box does not appear.
20. Click on Expression in the dynamic content field. Either paste in or type the text below and then select the OK button.
21. Leave the middle field set to ‘is equal to’ and put your cursor in the last edit field on the right-hand side. Go through the same process as before, selecting dynamic content -> Expression and then put in the text:
22. Save the logic app.
23. Before going any further, let’s look at the full expression that you just created to understand what is going on. Click on the </> Logic app code review menu item.
In the code you will see this:
“equals”: [“@xpath(xml(body(‘Flat_File_Decoding’)), ‘string(count(/.))’)”,“@string(‘1’)”
- The first part of the expression highlighted above, takes the output of the flat file decoding action and makes sure the body represents an XML document
- Next, the XPath code says ‘get a count of the number of root nodes ‘/’ starting with the first root node as the current node ‘.’. All this of course has been turned in to a string by XPath.
- Finally, this output is compared to the string ‘1’ to make sure there is only one root node.
Go back to the Logic App designer.
24. Click on the Add an action link in the If true branch.
25. In the search field type in ‘xml’ and then look for the Transform XML icon. Click on the icon.
26. Put your cursor in the Content field and select Body from the Flat File Decoding section of the dynamic content dialog. For the Map, click on the Map drop-down control I select the name of my XSL map, BuyerToCustomer. This is the step in the workflow that actually does the full transformation from flat file to XML.
27. Save the logic app.
Step 6 – Testing your integration Logic App
1. Scroll to the top of your logic app and click on the Http request action. You should notice that you have a full URL available to you. Copy this URL to your clipboard.
2. Open Postman or tool of your choice that allows you to perform POST commands with data to your logic app.
3. Select a new tab in Postman and paste your URL into the address field. Make sure you select POST as the action you’re going to perform.
4. You do not need to modify the header settings because you will be putting in plain text. Click on the Body menu item and then the ‘raw’ choice button.
5. Put in some sample flat file data that you wish to pass in as shown below.
Make sure that at the end of the last line of text, you select Enter to make sure that you have a carriage return/line feed at that location.
6. Within Postman, click the Send button. What you should see is a 202 Accepted response in Postman.
7. Go back into the portal to the Overview blade for your logic app. Click on the Refresh toolbar button and then look at the Status in the Runs history section.
8. Click on the status and you will be taken to the ‘Logic app run’ blade where you can see the steps that your logic app took to complete the workflow. You can click on any of the actions and the action will expand and show you the details.