Chapter 1 - Prerequisites and server setup

This chapter sets up the parts of Central Flows that every form shares: the SQL database, the DBXL document types, the FormsViewer environment variables and the three Central Flows templates. You do it once per environment (for example once for test and once for production). Adding Central Flows to an individual form is Chapter 2.

1.1 What you need

• Qdabra Forms (FormsViewer), with permission to manage templates and environment variables on the site.
• A DBXL server that FormsViewer can reach, and the DBXL Administration Tool. See the DBXL Administration Guide.
• SQL Server with SQL Server Management Studio (SSMS), for the Central Flows database.
• The Central Flows package: the database script (CentralFlows.sql), the DBXL document types, the Config / Dashboard / Global Admins templates and the setup documents for Microsoft Graph and Authy. Ask Qdabra for the package through the Customer Support Portal or Contact Us.
• The DBXL Migration Tool (Document Deployer) v3.5, installed on a machine that can connect to your DBXL server. Download it here: DBXL Migration Tool (Document Deployer) v3.5.

1.2 Create the database

Run CentralFlows.sql in SSMS. It creates a database named CentralFlows with these objects:

You will enter the database name (or its alias) in the CentralFlows_DB environment variable in section 1.6.

1.3 Deploy the DBXL document types

Extract the document types from the package, then import them with the DBXL Migration Tool:

For each document type:

1. Enter the URL of your DBXL server and click Connect.
2. Open the Import tab.
3. Select the folder where you extracted the document types.
4. Click Load and select the document type to import (one at a time).
5. Select Configuration as the item to import.
6. Enter your database server and catalog.
7. Click Run.

Open the DBXL Administration Tool and check that all five document types are listed.

1.4 Set the document type permissions

Central Flows writes to these document types as the DBXL service account: the Windows account DBXL runs under (the identity of the DBXL application pool in IIS, set when DBXL was installed; see the DBXL Administration Guide, Chapter 1). Give that account permission on each of the five document types:

1. Open the DBXL Administration Tool (DAT) in the browser and open the document type, for example CentralFlowsConfig.
2. Click the Permissions tab.
3. Under Document Type Level Permissions, click + Insert permissions.
4. Enter the service account in Name and Role Name, and check Add and Write. Adjust the other permissions as your organization requires.
5. Click Save at the top right.
6. Repeat for CentralFlowsGlobalAdmins, CentralFlowsHistory, CentralFlowsTasks and CentralFlowsUsers.

1.5 Add the XML mappings

Central Flows uses DBXL's XML-to-XML mapping. The XTP adds two groups to your form's data, qdxtp_Tasks and qdxtp_History. When this data is submitted to DBXL, DBXL saves each group as a separate document in CentralFlowsTasks and CentralFlowsHistory, using the mapping on that document type whose name matches the part after qdxtp_. The host field mapping writes the DocId of your form's document into each task and history document (Tasks_FormDocID, History_FormDocID), which is how they are linked to the form.

So the mappings are set on these two Central Flows document types, not on your form's own document type. In the DBXL Administration Tool:

1. Open the document type (first CentralFlowsTasks) and click the XML tab.
2. Add a new mapping of type XML->XML and enter the Mapping Name from the table below.
3. Under Host Field Mappings, click Add Host Field Mapping, enter the Field Path from the table and select the token DocId.
4. Click Save.
5. Repeat for CentralFlowsHistory.

1.6 Set the FormsViewer environment variables

Open the FormsViewer main page (the page that lists your form templates), click Manage Environment Variables, and add these keys:

If Central Flows runs in one site (for example the root site), add the keys once as Global variables. To run separate instances in different sites, add them as Site variables instead.

Environment variables keep the DBXL address and keys out of the form templates, so the same template works in test and production and no key is stored in the template.

1.7 Upload the Central Flows templates

Upload the three templates from the package on the FormsViewer Manage Templates page, and name them exactly:

• Central Flows Config
• Central Flows Dashboard
• Central Flows Global Admins

Use exactly these names; do not add a suffix such as a version number.

1.8 Add the Global Admins

Open the Central Flows Dashboard and click the Global Admins icon. The icon appears when no Global Admins list has been saved yet (the first time) and, after that, only to users who are Global Admins. Add the people who will administer Central Flows.

1.9 Optional: Microsoft Graph and Authy

• Microsoft Graph lets you assign forms to SharePoint groups and distribution lists. Register an app as described in "MS Graph API - Configure App Registration" and enter its values in the Graph... environment variables (section 1.6).
• Authy adds smartphone verification for the signed-in user. Create an API key as described in "Create Authy API Key"; Chapter 2, section 2.12 shows where it goes in the form.

For help, active customers can use the Customer Support Portal. For anything else, use Contact Us or e-mail [email protected].

Next: Chapter 2 - Adding Central Flows to a form