A DBXL solution typically is a complex system consisting of a database schema as well as several InfoPath templates along with their corresponding DBXL settings and database mappings. Maintaining and deploying those can be a challenging task. The DBXL Migration Tool (also known as Document Deployer) allows automating the process of building and deploying a DBXL solution.
Step one: creating an installer
The first step is to create a Document Deployer installer. Let us assume that a DBXL solution consists of several InfoPath templates saved as source files (typical setup when creating InfoPath templates with business logic). Furthermore, let us assume that the templates have already been deployed to DBXL and mappings have been created. To create the installer, follow these steps:
1. Create a Mappings\Samples folder next to the solutions
2. For each InfoPath Template, use the Migration Tool to export the configuration and save the mapping.xml into individual folders under the Mappings\Samples folder.
3. (Optional) Manually edit each mapping.xml file and remove the contents of the template node. This is done to keep the mappings files small; the build process will replace the template node with the fresh bits anyway.
4. Add an install.sql to one of the folders, it does not matter which one but make sure that the mapping with the SQL installer gets executed first. It is a best practice to have the install.sql create the database schema only if one does not exist already, this enables the upgrade scenario.
5. Add whatever documents needing to be deployed alongside the mappings in the corresponding SampleDocs folder.
6. Within the Mappings folder, create a Document Deployer install script (see example in the appendix).
7. (Optional) Create batch files to facilitate the deployment
Step 2: creating a build for the template DLLs
If you have an InfoPath solution with business logic, it has to be compiled before the XSN can be generated. Create an empty Visual Studio solution that will be used to build all of your InfoPath templates. Then create one C# project for each template and add the source files (typically FormCode.cs) as link to those solutions. You will need to add the missing references manually such as Microsoft.Office.Interop.InfoPath.SemiTrust. Make sure to edit the project properties to make sure that the names of the DLLs generated match the ones build by InfoPath.
Step 3: creating a Document Deployer build
Now that you can build the InfoPath business logic and that you have an installer structure in place, creating a Document Deployer build is simply a matter of creating a Document Deployer script that will combine the expanded template files with the DLLs and put the result into the mapping.xml files. See the appendix for the example of such a script.
Appendix: Example
Suppose that your DBXL system has two solutions, Users and Expense Reports (first one allows to edit the users in the system while the second one allows the users to edit their expense reports). Initially, you will have the following directory structure:
ExpenseSystem
Users
InfoPath Form Template
ExpenseReport
InfoPathFormTemplate
Add the Mappings\Samples folder and save the mappings for the two solutions. Assuming there is an install.sql file for each of the solutions that creates the database tables, the new folder structure will look like this:
ExpenseSystem
Users
InfoPath Form Template
ExpenseReport
InfoPathFormTemplate
Mappings
Samples
Users
install.sql
mapping.xml
ExpenseReport
install.sql
mapping.xml
Now create a DocumentDeployer scenario called InstallSamples.xml in the Mappings folder:
<?xml version="1.0" encoding="utf-8" ?>
<ScenarioDefinition>
<Imports useXpath="true">
<ImportActionDefinitions>concat($ScenariosPath, '\MigrateCore.xml')</ImportActionDefinitions>
</Imports>
<GlobalVariables>
<GlobalVariable name="installSql" value="True"/>
</GlobalVariables>
<Runs>
<Run name="InstallExpenseSystem">
<Action name="InstallDocType">
<param name="path">Samples\Users</param>
<param name="database">ExpenseDatabase</param>
<param name="installDatabase" useXpath="true">$installSql</param>
</Action>
<Action name="InstallDocType">
<param name="path">Samples\ExpenseReport</param>
<param name="database">ExpenseDatabase</param>
<param name="installDatabase" useXpath="true">$installSql</param>
</Action>
</Run>
</Runs>
</ScenarioDefinition>
It defines a global variable called installSql which specifies whether or not to execute the install.sql scripts. This variable when specified of DocumentDeployer's command-line allows to tweak the process to enable update scenarios. To invoke the installation, run the following command: "C:\Program Files\Qdabra Software\DBXLMigrationTool\DocumentDeployer.exe" InstallSamples.xml InstallExpenseSystem --databaseServer=yourDbServer --DBXLUrl=yourDbxlUrl --installSql=True|False
The Build scenario will look like this:
<?xml version="1.0" encoding="utf-8"?>
<ScenarioDefinition>
<GlobalVariables>
<GlobalVariable name="mappingRoot" value="C:\ExpenseSystem \Mappings\Samples\"/>
<GlobalVariable name="binariesRoot" value="path to the compiled dlls"/>
<GlobalVariable name="solutionsRoot" value=" C:\ExpenseSystem \"/>
</GlobalVariables>
<Classes xmlns:dd="http://www.qdabra.com/DocumentDeployer">
<dd:Class Assembly="Qdabra.DocumentDeployer.InfoPathTools" Name="Qdabra.DocumentDeployer.InfoPathTools.SolutionTools" Alias="Tools">
</dd:Class>
</Classes>
<ActionDefinitions>
<ActionDefinition name="AssembleAndUpdateMapping">
<Variables>
<Variable name="solutionSourcePath" output="false"/>
<Variable name="solutionDllPath" output="false"/>
<Variable name="templateXsnName" output="false"/>
<Variable name="mappingToUpdatePath" output="false"/>
</Variables>
<Methods>
<Method class="Tools" name="UpdateMapping">
<XPathParameter>$solutionSourcePath</XPathParameter>
<XPathParameter>$solutionDllPath</XPathParameter>
<XPathParameter>$templateXsnName</XPathParameter>
<XPathParameter>$mappingToUpdatePath</XPathParameter>
</Method>
</Methods>
</ActionDefinition>
</ActionDefinitions>
<Runs>
<Run name="AssembleExpenseSystem">
<Action name="AssembleAndUpdateMapping">
<param name="solutionSourcePath" useXpath="true">concat($solutionsRoot, "Users\InfoPath Form Template\manifest.xsf")</param>
<param name="solutionDllPath" useXpath="true">$binariesRoot</param>
<param name="templateXsnName">Users</param>
<param name="mappingToUpdatePath" useXpath="true">concat($mappingRoot, "Users\mapping.xml")</param>
</Action>
<Action name="AssembleAndUpdateMapping">
<param name="solutionSourcePath" useXpath="true">concat($solutionsRoot, "ExpenseReport\ InfoPath Form Template\manifest.xsf")</param>
<param name="solutionDllPath" useXpath="true">$binariesRoot</param>
<param name="templateXsnName">ExpenseReport</param>
<param name="mappingToUpdatePath" useXpath="true">concat($mappingRoot, "ExpenseReport\mapping.xml")</param>
</Action>
</Run>
</Runs>
</ScenarioDefinition>
Once you specify the location of the binaries, Document Deployer will assemble the solutions under the mappings folder which will create the final installer.