A DBXL solution is typically 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 these can be a challenging task. The DBXL Document Deployer (also known as the Migration Tool) allows automating the process of building, updating and deploying DBXL solutions.
Command Line Tool
Configuration
The command line tool is configured via two XML files:
-
DocumentDeployerConfig.xml: It contains the main tool configuration and includes settings such as DBXL URL, logging settings, plug-in settings.
-
A scenario file, which configures the plug-ins and defines runs. Each run is a set of customizable actions that the tool will run.
First, configure the tool to point to your local DBXL:
1. From the Start Menu, select Programs > Qdabra DBXL Migration Tool > Configure.
2. Change the value of <DbxlRoot> to your local instance
3. Save and close the configuration file.
The Document Deployer tool uses XML Scenario files that define the actions to be executed. Each scenario file is split into two sections. The ActionDefinitions part defines various DBXL actions, and the Runs section invokes those actions. Defining action definitions can be a daunting task, but you can accomplish a lot with the action definitions that ship with Document Deployer.
Execution
To execute the Document Deployer command line tool, select Programs > Qdabra DBXL Migration Tool > DBXL Migration Tool. Make sure that DocumentDeployerConfig.xml is properly configured, as described above. Then execute the tool using the following syntax:
> DocumentDeployer.exe pathToScenarioFile runName [results filename]
For example, to run one of the sample scenarios that comes with the tool, use the following command:
> DocumentDeployer.exe Scenarios\QdCatBaseTaxonomy.xml CreateTaxonomy
You can list the runs defined in the scenario by running this:
> DocumentDeployer.exe pathToScenarioFile
Variables
Document Deployer has three types of variables, allowing the user to set values at different moments of the deployment process.
1. DocumentDeployerPath – specifies the root of the Document Deployer installation.
2. ScenariosPath – specifies the folder that contains the out-of-the-box scenarios
3. DBXLUrl – Defaults to the configuration setting, can be changed dynamically
4. DocServiceTimeout – Defaults to .NET setting, can be changed dynamically
5. EnumDBTimeout - Defaults to .NET setting, can be changed dynamically
-
Global variables: Each scenario contains a section for Global Variables. When defined, they override the Predefined variables. Global variables can be used to allow factoring out the action definitions and to also enable advanced command-line scenarios.
-
Command-line variables: Command-line variables override the both variables above and thus provide flexibility in the execution of Document Deployer. Any number of command-line variables can be present in the command, and all of the DBXL variables can be overridden on the command-line using this syntax. The command-line variables are specified with the following syntax: --variableName=variableValue.
In order to list all of the variables available in a scenario, run this command: > DocumentDeployer.exe pathToScenarioFile -vars
Importing previous runs
It is possible to import previous DocumentDeployer runs via -importLog=path switch. This will inject the results of previous executions (if they were saved) into the current results document.
Document Deployer UI
The Document Deployer UI provides an easy-to-use interface for these actions. The steps below will guide the novice user through the use of Document Deployer UI. It assumes that you have a Document Type that you would like to migrate from one instance of DBXL to another.
1. In Start Menu > Programs, click on Document Deployer UI to open the tool.
2. In the Export tab we will export a Document Type and its documents to a local folder.
a. Enter the source DBXL Server Root where you have created the Document Type. The URL will have the following structure: http://<servername>/QdabraWebService
b. Click Connect. This will load a list of Document Types into the Configuration dropdown.
c. Select the Document Type from this dropdown.
d. Click the Documents and Configuration checkboxes from the Items to export section.
e. Enter a local export path. Alternatively, click on the Select button and navigate your local drive to select the folder.
f. Click Run to perform the export.
Figure 1
3. In the Import tab, we will import the Document Type and its documents into a different instance of DBXL. (Alternatively, you can delete the document type configuration from DAT and import the document type into the same DBXL instance. That scenario is ideal for someone who wishes to practice these steps.)
a. Enter the destination DBXL Server Root and click the Connect button.
b. In the Export Path field, enter the local path where the configuration and documents were saved.
c. Click Load to populate the Configuration dropdown with the list of Document Types available in that Export path folder.
d. From the dropdown, select the Document Type you’d like to import.
e. Select the Documents and Configuration checkboxes.
f. Enter the Database servername and the Initial Catalog (database).
g. Click Run to perform the import.
Figure 2
Migrating a DBXL solution
Document Deployer allows you to migrate complex solutions from one server to another. The migration process can be broken up into these steps:
1. Analyze your solution - Suppose you need to migrate a Timecards solution. There are two initial steps:
a) Edit the Timecard configuration in DBXL and determine the list of SQL tables used to shred the data. Let's say that Timecards shred into two tables: Hours and WorkItems.
b) Figure out the dependencies. For this, open the form in Design mode in InfoPath and inspect the secondary data sources. In a typical DBXL solution, data connections such as QueryDocuments are indicative of a dependency. Verify the web service arguments to find out which are the Document Types that we depend upon.
Repeat these two steps for all the Document Types involved in your solution. When done, you will end up with a Solution Manifest that will list all Document Types and dependencies. For example, in the case of the Timecard solution, the manifest will look like this:
Main Document Type: Timecard
Shreds into: Hours, WorkItems
Depends on: TimecardConfig
Depends on: Employees
Shreds into: Employees
Depends on: Projects
Shreds into: Projects
2. Create SQL scripts - Now that you know what your solution is composed of, it is time to create the SQL scripts. If you are lucky you already have them around. Otherwise you'll need to re-create them. The easiest way to do so is by using SQL Server Management Studio. For every DocType, create one install.sql that creates all of the tables that the DocType needs. Don’t forget to check for the existence of Views.
3. Export the document types – Configure the tool, then use Document Deployer to export the four document types (Timecard, TimecardConfig, Employees and Projects) along with their documents into C:\Temp\Samples.
4. Copy the SQL scripts - Place the SQL scripts in the same folder where Document Deployer created the exported mappings and documents folder. The final and complete migration folder will have the following structure:
Samples
DocTypeName
mapping.xml
install.sql
SampleDocs
5. Perform the import - Use Document Deplyoer to import the four document types, along with their documents, making sure that the tool is properly configured to point at the target DBXL instance.
Appendix
Scenario files and their Action Definitions
Below you’ll find a list of all scenario files and their action definitions. If you want to achieve tasks other than those covered by the built-in scenarios, you can either create a new scenario file or modify an existing one. Also note that you can import action definitions from other scenario files without having to copy them over. See Scenarios\Migrate.xml for an example on this.
• QdCatBaseTaxonomy.xml: This scenario defines actions that can populate the taxonomy for the qForm solution that ships as part of DBXL v2.1 and v2.2. It contains the following action definitions:
o AddHierarchy: adds a hierarchy to a specified document type
o AddCategory: adds a category for a specified hierarchy
o ChainCategory: puts one category under another
o EnumerateDocumentIds: lists documents matching specific criteria
o RemoveEnumeratedDocuments: removes listed documents
• DeployQdCatBaseInstances.xml: This scenario defines actions that can create instances of the qForm solution and accomplish complex tasks such as tagging documents and assigning workflow. It contains the following action definitions:
o GetHierarchy: gets the DocID of a specific QdCatalogBase hierarchy
o EnumerateDocumentIds: lists documents matching specific criteria
o RemoveEnumeratedDocuments: removes listed documents
o RemoveAllDocuments: removes all documents for a document type
o TagDocument: tags a document with a specified category
o AddEmailFlow: adds e-mail flow to a document
o AddCatalogBase: adds an instance of the qForm
• Cleanup.xml: This scenario contains only one generic RemoveAllDocuments action definition that eases DBXL cleanup.
• DeployPictureForm.xml: This scenario demonstrates the use of compile-on-the-fly plug-ins and bulk deployment. It contains the following action definitions:
o UploadDoctype: uploads a hardcoded document type (can be modified to be made more generic)
o AddPictureDocument: uploads one document with a base64-encoded image
o BulkDeploy: uses an external plug-in to upload all sample pictures (requires Vista to work as-is)
• MigrateCore.xml: This scenario allows the export and import documents and document types. It contains the following action definitions:
o ExportDocType: exports a specified document type to a given folder
o ListDocumentsForDoctype: enumerates all documents for the specified document type
o DownloadListedDocuments: exports documents listed by the previous action definition
o ImportDocType: imports a specified document type into DBXL
o ImportDocuments: imports specified documents into DBXL
o ExportDoctypeWithTaxonomyAndFlow: a complex action definition that can export a qForm-derived solution along with all its taxonomy and flow
o ImportDoctypeWithTaxonomyAndFlow: a complex action definition that can import a qForm-derived solution along with all its taxonomy and flow
Each of the scenario files (other than MigrateCore.xml) contains examples of how to use the actions. For document migration, the usage examples are in a separate file, Migrate.xml, which also demonstrates how you can easily build your own scenario by importing action definitions from existing scenario files.
Release Notes
-
Document Deployer supports Basic authentication in addition to NTLM authentication. It uses the default credentials when connecting to DBXL. However, should the login fail it will present a blocking WinForm UI to the user prompting for the password. As of the current version, Document Deployer can only run unattended if login failures do not occur. Note that the username will be stored in the application settings.
-
ExportDocuments actually downloads documents instead of exporting them. The difference? The DocID PI gets preserved when you download documents (this scenario is very useful for bulk updates). The ActionDefinition you want to use to export documents is ExportFullDoctype, making sure to set the following variables to false: optionMapping, optionTaxonomy, optionFlow.
-
ListDocument Types does not output anything into the command window; it only exports results into an XML file. Run this command below, then inspect results.xml to see the list of Document Types:
> DocumentDeployer.exe Scenarios\Migrate.xml ListDocument Types results.xml
-
Note that sometimes complex solutions shred into a database which might not yet exist on the target DBXL machine. Because of this, install.sql scripts will fail to run. To solve this problem, create a fake Document Type called ensured in the Samples folder and, in it, create an install.sql script (without the mapping). The code in it could look like this:
IF NOT EXISTS( SELECT * FROM sys.databases WHERE name = 'YourDB' ) CREATE DATABASE YourDB
GO
USE YourDB;
IF NOT EXISTS (SELECT * FROM dbo.sysusers where name='NT AUTHORITY\NETWORK SERVICE')
BEGIN
CREATE USER [NT AUTHORITY\NETWORK SERVICE] FOR LOGIN [NT AUTHORITY\NETWORK SERVICE] WITH DEFAULT_SCHEMA=[dbo]
EXEC sp_addrolemember N'db_datareader', N'NT AUTHORITY\NETWORK SERVICE'
EXEC sp_addrolemember N'db_datawriter', N'NT AUTHORITY\NETWORK SERVICE'
END
GO
-
Document Deployer will run against a DBXL v2.0 instance. However, you need to make sure that you do not use the new DB aliases such as #DBXLDB# (sample XML files make use of it to keep the examples generic). Instead, you will have to replace #DBXLDB# with the actual database name.