Conditionally Installing EDI Party Agreements within BTDF
We heavily use the BizTalk Deployment Framework to aid in the deployment of simple to complex BizTalk solutions. One of the greatest benefits is the ability to run custom deployment tasks and scripts. In previous blogs we have shown how to run a custom post deployment scripts in BTDF, today, we will show how custom scripts can be used to conditionally import a binding file during BTDF deployment.
Conditionally importing trading partner configurations is significant because when assigning a send port to a trading partner agreement, BizTalk will sometimes disallow the undeployment or re-deployment of the referenced application. Or, in this case, the client does not want to override trading partner settings every time an application is updated.
The overall steps we will take is
- Create binding file – in our case containing only trading partner agreements and no port or orchestration bindings
- Update an existing BTDF project to add binding file to install directory
- Update the BTDF installation wizard to include a new page controlling whether or not the binding import will occur
- Update BTDF to execute an import bindings command
First, we will create the binding file.
1. Open the BizTalk Administration Console
2. Right click on the default BizTalk Application, usually ‘BizTalk Application 1′
3. Select Export –> Bindings…
4. Select ‘Export Global Party Information’
5. Select ‘Ok’, then browse to the created file
6. Within the file, remove the ModuleRefCollection, SendPortCollection, DistributionListCollection, and ReceivePortCollection nodes. This will allow the file to only update the trading partner and agreements within BizTalk.
Next, add the file to BTDF in the default ‘Deployment’ folder created during the recommended BTDF configuration for the project. Below, the file is named ‘TradingPartnerSettings.xml’
Within the Deployment.btdf settings file, which contains all of the BTDF deployment settings, we will next add the TradingPartnerSettings file to the installation directory when installed using the MSI. Within the ‘CustomRedist’ target, we will use the CreateItem tag to include the file in the installer, and extract into the installation directory on when installed (Copy)
<Target Name="CustomRedist"> <!-- Add to installer --> <CreateItem Include="..\Deployment\TradingPartnerSettings.xml"> <Output TaskParameter="Include" ItemName="TradingPartnerSettingsVars" /> </CreateItem> <!-- Add to install directory when MSI is executed --> <Copy SourceFiles="@(TradingPartnerSettingsVars)" DestinationFolder="$(RedistDir)\Deployment" /> </Target>
This assumes that the file is located within the root of the ‘Deployment’ folder where the BTDF project resides.
Next, we will create a CustomPostDeployTarget to execute BTSTask, BizTalk’s command line utilities, to import the above mentioned binding file.
<Target Name="CustomPostDeployTarget"> <Exec Command="BTSTask ImportBindings /ApplicationName:$(BizTalkAppName) /Source:"TradingPartnerSettings.xml"" Condition="$(ImportAgreements) == 'true'" /> </Target> <Target Name="CustomPostUndeployTarget" />
The above script will run BTSTask using the name of the installed application. Even though the binding file was created from ‘BizTalk Application 1′ it will not override any bindings in the application because we have previously removed the orchestration and port bindings from the file in the above steps. The last important part of the Exec command is the inclusion of a condition. This specific condition will ensure that the BTSTask ImportBindings command is only executed if the variable ‘ImportAgreements’ is set to true. You may ask, ‘What is the ImportAgreements’ variable?’ That comes next!
The ImportAgreements variable is set within the installation wizard used when deploying the application using the MSI generated by BTDF. We will need to add a page to the installation wizard allowing us to ask the user a user the question ‘Do you want to import the trading partner bindings?’ The response will be selected using a check box, and stored in the ImportAgreements variable. To accomplish this, we will add the following snippet into the ‘InstallWizard.xml’ file of BTDF.
<!-- ask the question, do you want to import the trading partner bindings? --> <SetEnvUIConfigItem> <PromptText> Should trading partner agreements and partner configurations be imported? </PromptText> <Caption>Import trading partner agreements and partner configurations.</Caption> <PromptValue>false</PromptValue> <ValueType>Checkbox</ValueType> <EnvironmentVarName>ImportAgreements</EnvironmentVarName> </SetEnvUIConfigItem>
The SetEnvUIConfigItem node represents a page within the install wizard. The Prompt Text is the text within the wizard page, and the caption is the text that appears next to the check box. In this instance, we are defaulting the checkbox as ‘unchecked’, and setting the value of the checkbox to the ‘ImportAgreement’ variable, which can be used in BTSTask command.
The InstallWizard.xml file should look like this when the new SetEnvUIConfigItem has been added.
Now, when building and installing, and then executing the MSI, we can see a new page has been added to the installer
Clicking ‘Finish’ at the end of the page will complete the deployment, and import the bindings containing the trading partner information!