BizTalk Rules Engine (BRE) Mass Export / Import Tool

I am currently going through a BizTalk migration from one physical infrastructure to a new virtualized environment.  Rather than attempt to join the new environment to the existing BizTalk group, we decided to stand up a brand new environment altogether (new SSO servers, new SQL backend, etc).  This procedure is fairly straightforward from the installation, host setup, applications deployment, and binding deployment perspective.  However, moving over our 50 some on rules from BRE has proven to be daunting.

The best mechanism out-of-the-box is the Business Rules Deployment Wizard.  However, I would need to run this wizard over 300 times considering that all of our vocabularies and policies have multiple versions that I would like to maintain moving forward into the new environment.

To overcome this problem, I wrote an application that allows us to export / import all the vocabularies and policies stored in BRE in one shot.  This includes all non-published, published, and deployed versions.

  

Contents of this Post


In this post, I will provide

  • An overview of the tool’s use case (previous section)
  • An overview of the tool
  • Information on where to obtain the tool and source code
  • A brief explanation of how to use the tool
  • A detailed walkthrough of the tool

In this post, I will not be covering the source code, but all of the source code is posted on GitHub and you will find instructions for downloading the source in the “Where to Obtain Tool” section.

If you would like a detailed walk-through of the source, please send me a comment and I will work on providing more detailed information on how the code works.

  

Overview of Tool


(For an overview that discusses the objective of the BRE Mass Import / Export Tool, please see the previous section)

The objective of this tool is twofold:

  1. Export all vocabularies and policies stored in one BRE into two files (vocab.export.xml & policy.export.xml)
  2. Import all vocabularies and policies from two files into another BRE (executed as two separate steps; the main reason for doing this is two steps is due to the fact that many of your policies will most likely depend upon items in your vocabularies.)

 

Where to Obtain the Tool


All of the source code and the latest builds are stored in my GitHub: https://github.com/jixer/biztalk-rules-export/tree/master/SOURCE/MAIN

You directly grab a zip download of the latest release here: https://github.com/jixer/biztalk-rules-export/raw/master/BUILD/v1.0.0.0.zip

If you would like to grab the source code, but you’re unfamiliar with GitHub, please check out my guide “Source Code Used on This Blog and GitHub“.

  

How to Use the Tool (Simple)


The end-to-end example I will provide for using this tool will build on top of the scenario I provided in the introduction: Migrating BizTalk Rules Engine policies and vocabularies from one server to another.

Before we begin, it’s important to understand a few things.  For starters, this is a console application.  Running it as if it were a forms application will yield you no output and may cause unintended results.

There are the three main functions of the application:

Function 1:

Export all rules from the server you’re running the application on into the vocab.export.xml & policy.export.xml files.  This is done by executing the command line application with no arguments:


$PATH\v1.0.0.0>.\BizTalkRulesUtility.exe

 

Function 2:

Import the vocabularies into the rules engine of the server you are currently running the application on.  This will pull from the “vocab.export.xml” file within the directory of where you’re running the application.  This is done by providing the argument “iv” to the command line application:


$PATH\v1.0.0.0>.\BizTalkRulesUtility.exe iv

 

Function 3:

Import the policies into the rules engine of the server you are currently running the application on.  This will pull from the “policy.export.xml” file within the directory of where you’re running the application.  This is done by providing the argument “ip” to the command line application:


$PATH\v1.0.0.0>.\BizTalkRulesUtility.exe ip

 

IMPORTANT!

Please note that you will still need to publish and deploy all vocabularies and policies that you desire.  The tool does not automatically do this for you.

For a more detailed walkthrough of all steps, please read through the following “Let’s Get Started” section.

 

Let’s Get Started (Detailed Walkthrough)


The server names I will use throughout this example are BizTalkEnvironment-Old and BizTalkEnvironment-New.  These will correspondingly represent the rules source environment and rules destination environment.

 

Step 1:

For starters, copy the latest release of all files (or your own compiled binaries) to both servers.

 

Step 2:

Log into BizTalkEnvironment-Old

Note: Steps 3 through 5 will all utilize BizTalkEnvironment-Old

 

Step 3:

Open a command prompt with Administrative privileges and navigate to the directory where you stored the BizTalkRulesUtility executable.

Screenshot 2015-09-14 17.42.01

 

Step 4:

Run the executable with no parameters and wait for the tool to go to the next line.


C:\Users\cmyers\Desktop\v1.0.0.0>.\BizTalkRulesUtility.exe

C:\Users\cmyers\Desktop\v1.0.0.0>

Note: If you receive any errors, feel free to post them below in the comments and I can help you sift through them.

 

Step 5:

Verify that the two export files were generated: “policy.export.xml” and “vocab.export.xml”

Screenshot 2015-09-14 17.44.36

 

Step 6:

Copy the “policy.export.xml” and “vocab.export.xml” to BizTalkEnvironment-New in the same directory where you stored the executable.

 

Step 7:

Log onto the BizTalkEnvironment-New server

Note: All remaining steps will utilize BizTalkEnvironment-New

 

Step 8:

Open a command prompt with Administrative privileges and navigate to the directory where you stored the BizTalkRulesUtility executable.

 

Step 9:

Import the vocabularies into the current server’s BRE from the “vocab.export.xml” file using the console application.  Please note that this file MUST exist with the same name in the current directory for this tool to work.

To execute this step, run the command line tool while providing an argument of “iv”.


C:\Users\cmyers\Desktop\v1.0.0.0>.\BizTalkRulesUtility.exe iv

C:\Users\cmyers\Desktop\v1.0.0.0>

 

Note: This tool is very basic and will not provide any output.  You will need to verify the import through the BizTalk Business Rules Composer.

 

Step 10:

Open the BizTalk Business Rules Composer.  First, verify that all of the vocabularies were imported.  Next, publish all necessary vocabulary versions.  This step is crucial as the following step may fail if you do not manually publish vocabulary dependencies.

 

Step 11:

Import the policies into the current server’s BRE from the “policy.export.xml” file using the console application.  Please note that this file MUST exist with the same name in the current directory for this tool to work.

To execute this step, run the command line tool while providing an argument of “ip”.


C:\Users\cmyers\Desktop\v1.0.0.0>.\BizTalkRulesUtility.exe ip

C:\Users\cmyers\Desktop\v1.0.0.0>

 

 

Step 12:

With all of the policies imported, go back one final time to the BizTalk Business Rules Composer tool.  As mentioned previously, this tool does not publish or deploy any vocabularies or policies.  This is a manual step that you will need to perform through the BizTalk Business Rules Composer.

 

Conclusion


Although it may not be a two click procedure, you can probably see how this tool could potentially save you countless hours of manually attempting to import and export rules one by one through the Business Rules Deployment Wizard.

If you find this post or tool useful please let me know in the comments below or contact me on Twitter (About Me).

If you find any bugs for this tool or would like to contribute, please let me know.

Before using this tool, please read the disclaimers below.

 

Disclaimers


Please review the following disclaimers before using this tool:

  • Usage of this tool is at your own risk. It is not recommended to use this tool as is in a production critical environment until you are fully familiar with the code and outcomes of execution.
  • Author of this tool cannot be held liable for any negative impacts of this tool.
  • Tool was built and tested against BizTalk 2009. It has not been tested or verified at this point to work within other versions of BizTalk.
    Note: If you do use this in other BizTalk environments and find it to work, please mention this in the comments below.

Tags: , , , , , ,

Reader's Comments »

  1. By Kian, Ting on April 20, 2016 at 12:36 am
  2. By Kian, Ting on April 20, 2016 at 12:37 am

    I have made modificaiton to the tool to be able to import pre existing rules that is in the target location, previouly the tool will not be able to overwrite rules that is already existent in the target location. But now it can overwrite it.
    https://github.com/kianting/biztalk-rules-export

  3. By chris on May 18, 2016 at 7:13 pm

    Thank you for resolving this issue. I have merged your changes into my repository and closed the issue you created. Great work on this fix and thank you for keeping this open source project alive and healthy!

Leave a Reply