Skip to main content

Azure BizTalk Rules | A Getting Started Guide (deprecated)


Update December 12 2016: It looks like this service has disappeared from the azure portal and documentation that was previously available has also disappeared. 

This connector was developed for v1 of Logic Apps, and whilst Logic Apps has gone on to v2 + general availability, this connector was not one of the connectors that was supported by the current version of Logic Apps. 

I don't know if there is any plans to bring this connector back in the future, but if I see any updates, then I will update this post. 

One of the things I've been playing around with lately is the Azure BizTalk Rules API App from Azure (currently in public preview). BizTalk Rules has been around since BizTalk Server 2004, however the server offering for BizTalk required a large upfront investment in terms of cost as well as skills required to effectively leverage the tool.

The introduction of several BizTalk capabilities as a PaaS (Platform as a Service) offering in Azure is intended to make the capability more available to a wider group of people. In the rules engine's case, Microsoft has revamped the user interface and it looks to be more user friendly than the server offering (I haven't personally used the server offering, but I made this observation based on images and blogs I've read online), and the pay for what you use model means there isn't such a big initial investment required to start leveraging the capability.

The Problem

One of the things I am involved with in my day to day activities at work is helping clients build workflows (using Nintex Workflow) to automate their business processes. Although Nintex Workflow is an easy to use tool, one of the things I have always aimed to do is de-couple decision logic from process logic in the workflow so that changes in an organisation can be easily applied to the business process by business users without the need for someone to go and modify the workflow.

To a certain extent, a number of tools and approaches can be used to achieve this e.g. storing information in SharePoint lists and having the workflow dynamically get information as it goes through it's flow, or another alternative is to create an app form that helps to drive some of the logic in the workflow. However, something still felt missing and I continued looking at other ways to take this to another level.... and this is where I think Azure BizTalk Rules can come in to help improve the way workflows as well as applications are built.

By decoupling business logic from applications and workflows, the Azure BizTalk Rules allows us to:
  • Centralise management of business rules and leverage the rules across multiple applications and workflows used in the business. (i.e. making your business rules loosely coupled from the applications/workflows and provide one source of truth for business rules in your organisation.)
  • Adapt business logic to changes in the business environment and have the changes applied to the applications that are governed by the business rules quickly and effectively.
  • Allow business analysts to maintain the business rules with the assistance of developers. 
  • Achieve the benefits of decoupling, without significant up front investment in money or training.
The Azure BizTalk Rules page provides a great overview of the capabilities of the service as well as a walkthrough of how to use the service. Unfortunately, as I hadn't previously used BizTalk Rules, I found the walkthrough a little difficult to follow, and needed to do a bit more reading online to get started. The best resource for me came from MSDN.

I put together this blog post to share what I learnt and hopefully help anyone else new to to BizTalk Rules get started with a Hello World type tutorial. 

The Steps

Prerequisites

Before we start, the following activities are recommended:
  • Have a quick read on the Azure Biz Talk Rules page to get an introduction into the product and it's terminologies e.g. Vocabularies, Rules, Policies.
  • Follow the steps in Create PO Schema File as you will need this if you want to follow along in your own environment. The link will take you to a BizTalk Server 2013 Tutorial. Although the tutorial itself cannot be directly used for the Azure equivalent, I found it a very good read as it provided better explanation of the concepts of the technology.
  • Follow the steps in Create The Test Files as you will need this if you want to follow along in your own environment. 
  • Follow the steps in Create a Rules API App as you will need this if you want to follow along in your own environment.

High level steps

  1. Create the vocabularies
  2. Create the business policy
  3. Create the rules
  4. Test the policy
  5. Use the policy in a REST call
Important Note: The screenshots below are taken from an API app where I have already completed all the steps in this tutorial. Therefore you will note that things that we are creating e.g. rules, policies and vocabularies already exist in the screenshot, whilst they won't exist in your screen.

1. Create the vocabularies

Vocabularies are intended to make rules easier to understand by people in a particular business domain or industry. The intention is to map terms used in the technical implementation into a more friendly name. This exercise will need to be driven by the developer in collaboration with the business expert.

In this exercise, we will be creating three vocabularies. The first two vocabularies will be used to map terms used in the technical implementation with business friendly terms, whilst the third vocabulary will be used to define constant values which can be used as a parameter inside a rule. 
  1. Open your BizTalk Rules API App you created in the Preview Portal.
  2. Under the components heading, select the tile called Vocabulary Definitions.
  3. In the Vocabulary definitions blade that opens, click the add button.
  4. Another blade should open containing a form. Enter the following information in the form and save your changes:
    - Name: RequestedQuantity
    - Description: {enter a description here that you would like to display to users}
    - Definition Type: XML
    - Schema: {select add schema, and upload the PO.xsd file you have saved into your computer from the pre-requisite step, and select to use the po schema.}
    - Xpath: {expand the item node, and select Quantity}
    - Fact: {leave as default for now}
  5. Repeat the steps above to create a new vocabulary with the following information:
    - Name: RequestStatus
    - Description: {enter a description here that you would like to display to users}
    - Definition Type: XML
    - Schema: {select to use the po schema.}
    - Xpath: {select Status}
    - Fact: {leave as default for now}
  6. Repeat the steps above to create the last vocabulary with the following information:
    - Name: MaximumNumberOfItemsAllowed
    - Description: {enter a description here that you would like to display to users}
    - Definition Type: Literal
    - Data Type: Number
    - Input: 1000

2. Create the business policy

A business policy is intended to store a collection of business rules. The business policy is the thing that is called via API by your applications and workflows. This exercise can be driven by the business expert in collaboration with a developer.

In this exercise we will create a business policy called ProcessPurchaseOrder which is intended to tell us whether the order that we pass through is approved or declined based on the requested quantity.

  1. Back to the Rules API App blade, click on the Policies tile.
  2. Create a new policy called ProcessPurchaseOrder

3. Create the rules

Rules are statements that represent individual business rules about a particular policy and is made up of a condition (If....), as well as an action (then this should happen...).

In this exercise we will create two rules that will define when the business policy for ProcessPurchaseOrder will result to an approved status or a denied status, based on the requested quantity passed into the rules engine.
  1. After creating the business policy, click on the business policy to open the rules blade
  2. Click on the add button in the blade that opens
  3. Enter the following details into the form that appears:
    - Name: ApprovalRule
    - Description: {enter a description here that you would like to display to users}
    - If: {leverage the autocomplete functionality to type the following conditions}. RequestedQuantity is_less_than_equal_to MaximumNumberOfItemsAllowed
    - Then: {leverage the autocomplete functionality to type the following Action}. RequestStatus equals "Approved"
  4. Enter the following details into the form that appears:
    - Name: DeniedRule
    - Description: {enter a description here that you would like to display to users}
    - If: {leverage the autocomplete functionality to type the following conditions}. RequestedQuantity is_greater_than MaximumNumberOfItemsAllowed
    - Then: {leverage the autocomplete functionality to type the following Action}. RequestStatus equals "Denied"

4. Testing the policy

Once we have finished defining the business policy, the next step is to test it to make sure it works. This can be done inside the Business Policy user interface.

We will perform the following test cases to check that the approved and declined rules are working as expected.
  • Test Case 1:
    MaximumNumberOfItemsAllowed = 1000
    SamplePO.xml with a quantity of 400
    Expected Result of Approved.
  • Test Case 2:
    MaximumNumberOfItemsAllowed = 1000
    SamplePO2.xml with a quantity of 700
    Expected Result of Approved
  • Test Case 3:
    MaximumNumberOfItemsAllowed = 500
    SamplePO.xml with a quantity of 400
    Expected Result of Approved
  • Test Case 4:
    MaximumNumberOfItemsAllowed = 500
    SamplePO2.xml with a quantity of 700
    Expected Result of Denied
  1. From the ProcessPurchaseOrder blade, select the Test button
  2. In the Test Policy blade that opens, click on the Import XML button
  3. Upload SamplePO.xml file that you have in your computer from the steps you followed in the pre-requisites, and press OK
  4. The RequestedQuantity input value on the screen should update to display the value from the Quantity property in the XML you have uploaded (i.e. 400). Click the Run Test button.
  5. After the test execution completes, the result of the test should be displayed in the RequestStatus output field. Check if this matches with your expected outcome.
  6. Run another test by following the steps above, but this time upload the SamplePO2.xml which has a quantity of 700. 
  7. So far both tests we have run have returned an approved outcome. Let's change things up by modifying the constant for the vocabulary MaximumNumberOfItemsAllowed, and let's set the value to 500.
  8. Run the test policy again against SamplePO.xml and SamplePO2.xml, and check to see if the test returns your expected outcome. In this case SamplePO.xml should pass, while SamplePO2.xml should fail.

5. Use the policy in a REST call

Having tested and verified the policy we created, it is now time to use this in an application or workflow. The easiest way to achieve this is by calling the policy via REST API.

In this example we will use Postman as our web service client, but this is applicable inside a workflow or a web application that  you may be building.

  1. Return to the BizTalk Rules API app blade, and select All Settings
  2. In the settings blade, click on Application Settings, and set the Access Level value to either Public (anonymous) or Public (authenticated). For this demo purpose, I am going to select the anonymous option, as this is not going to be used in a production environment.
  3. Back in the API app blade, select the API Definition tile, and click on the Download Swagger button. Downloading the swagger definitions will make it easy for us to call the API as it provides details that we need to make the call e.g. request url.
  4. Open up postman in chrome, and import the swagger definition you downloaded
  5. Click on the Collections tab, and click through the new collection you have added until you get to the method called ProcessPurchaseOrder. You will notice that most of the configuration has been done for you. 
  6. The next step is to enter in the content to the rest call. However first we need to find out what the body of the call should contain.
  7. Based on the Azure BizTalk Rules page I referenced above, the body of the call should be in this format:

    {"<XMLSchemName>_<RootNodeName>":"<XML Instance String>"}
  8. I find it easiest to get the XMLSchemName and RootNodeName string from the swagger definition you downloaded. So open up the definition in a text editor and copy the relevant property into the position of XMLSchemName and RootNodeName.
  9. Open up the a xml file containing the test data e.g. SamplePO.xml, copy and paste the xml string into the XML instance string position. (Mimify the xml and make sure any url in the xml has a backslash). Your api call content should now look something like this...
    {"po_PurchaseOrder":"<ns0:PurchaseOrder xmlns:ns0=\"http://EAISolution.PurchaseOrder\"><Header><ReqID>ReqID_0</ReqID><Date>Date_0</Date></Header><Item><Description>Description_0</Description><Quantity>400</Quantity><UnitPrice>20</UnitPrice></Item><Status>XYZ</Status></ns0:PurchaseOrder>"}
  10. Paste the content into body of the call in Postman, set the content-type to application/json, and make sure to change the request url from http to https.
  11. Execute the web request, and you should get back a json response with a similar format to one shown below. You will notice that the status property has been set to Approved. Of course you will need to parse both the json and xml string in your workflow or application in order to get the status and use it.
    {
      "po_PurchaseOrder": "<ns0:PurchaseOrder xmlns:ns0=\"http://EAISolution.PurchaseOrder\"><Header><ReqID>ReqID_0</ReqID><Date>Date_0</Date></Header><Item><Description>Description_0</Description><Quantity>400</Quantity><UnitPrice>20</UnitPrice></Item><Status>Approved</Status></ns0:PurchaseOrder>"
    }

Conclusion

Personally, I find the introduction of the BizTalk capabilities (and in this case the Rules engine) as a PaaS offering very exciting as this allows us to further leverage these enterprise level capabilities in more applications and workflows. It would be interesting to see developments in this area as it heads into general availability. My questions for now are:
  • How much of the on premise capabilities will be brought over to the cloud offering e.g. currently the cloud equivalent of vocabularies do not support .NET objects and databases.
  • From a cost point of view, how much will it end up costing to use this capability in the cloud
Have you used the server offering for BizTalk Rules before? Have you had a chance to play around with the public preview of Azure BizTalk Rules? It would be interesting to hear other people's thoughts with the new cloud service that Azure is offering and whether this is something you would consider using in your application developments.

Popular posts from this blog

Access Web App | Filter a view by current user login (deprecated)

Update (April 1 2017): Microsoft has released an update that willl stop the creation of new apps starting June 2017, and shut down any remaining apps by April 2018. See more here

The problem One of the things I needed to do lately was see if a view within Access Web Apps can be configured to filter data that is related to the logged in user. e.g. as a user I want to be able to view a list of projects where I had been assigned as the project owner.

In SharePoint, this would have been quite easy to achieve as we can create a view and set the filter to {column name} is equal to [me].

Unfortunately Access Web Apps does not quite work this way:

No people picker control in Access Web Apps - this means we need to store and manage our own list of user data within a table in your Access Web App Database (or find a way to link a table with SharePoint's user profile or hidden user information list).Access Web Apps is a relational database - this means the approach to filtering a table view is…

Nintex Workflow | parsing JSON responses from json-only web requests

Update 03/08/16:
Logic Apps has gone GA, and has undergone a major v2 change since this post was written. For the most part, the core actions remain the same but just renamed or work a little differently e.g. http listener (now known as "When an http request is received" + "Received") and conditions (now triggered via the add a condition" button instead of being configured inside the http action.)

It is worth noting that the BizTalk JSON Encoder API app can no longer be found in the marketplace. This is now a native function in Logic Apps. Though, I'll try to refresh this post with the how to do it in the version of Logic Apps that GA'd, I'm not sure when I will have to do it, so if you can't wait, I suggest looking at the xml function can be found here.

Update 07/08/16:
Steps for new Logic App UI that has GA have been added into the solution section below.
The problem
One of the things I have been working on lately in the Nintex Workflow world,…