Using information from databases on your XpressDox templates
Background
The Data Sources facility provides a way for data captured into some other system to be merged into templates. For example, use information from a Staff or Customer database on your templates instead of typing it in. XpressDox can use data from SQL Server, MySQL, MS Access, Excel, SalesForce.
This would be achieved by defining the database as a Data Source. Then when a template is run, the user will be able to select one of the staff members or one of the customers during the interview.
A data source needs to be configured once, and then can be used by the template authors in many templates.
Configure a Data Source for a Data Base
Please see Configure a Data Source for a Database for detailed instructions on configuring a data source for a data base.
Configuring the Data Source Properties
The Data Source configuration screen looks like this:
There are essentially two main types of Data Sources:
1. The Standard Database Data Source. The system provides a very comprehensive wizard-based configuration tool which enables the template author to configure Data Sources based on MS Access databases, Excel spreadsheets, SQL Server databases, and other database systems such as, for example, MySQL.
2. Custom Data Sources. This is a plug-in feature available to .NET developers who can then supply interfaces to any relevant data, such as accounting systems where more sophisticated interaction with the data is required.
There are some concepts which apply to all Data Sources:
a. Name. This is the name which commands such as «IncludeDataSourceData(...)» and «ChooseFromDataSource()» would use to refer to the data source.
b. The Definition String. This is constructed by the wizard in the case of most data source configurations, but can be used here to customize and configure a particular Data Source. For example, where a data source is a Standard Database Data Source, then the Definition String defines which database to use, and the tables, columns, search criteria, etc.
The Definition String can be manually modified in the text box provided in the configuration UI. However, it may be that the Definition Strings have a complex structure, in which case the Data Sources themselves provide an editor which helps the user correctly construct the Definition String.
Some data sources, particularly some Custom Plug-ins, will have very simple (and perhaps empty) Definition Strings.
c. The Parent Element Name. Particularly when a template may access data from more than one Data Source, there is the chance that there may be a clash of data element names.
To resolve this conflict, one or both of the data sources could have the Parent Element Name set, and this would be used in the template to resolve the name clash.
For example, the Employee data source could have the Parent Element Name set to ‘Employee’, and then employee Fillpoints in the template would be something like: «Employee/FirstNames» «Employee/Surname»
d. Test Data Source. The ‘Test Data Source’ toolbar button will optionally present the Data Source’s search interface, and then show the selected XML data in a window. This is to help the template author get a view of what the data will look like, as well as show whether and how the Data Source user interaction works.
e. Prepare Schema. When authoring a template, especially one in a suite of templates which will use the same data, it is difficult to remember what data elements have been used before. To help with this, the Command Editor permits the author to choose specific templates which contain data elements which are to be re-used. It is also possible to choose a ‘schema’ for a Data Source in the same way.
In order to generate this schema for subsequent use in the Command Editor, either use the Test Data Source feature described above, which gives the option of producing a schema based on the data selected during the test, or use the ‘Make Schema’ toolbar button.
f. There is also a Use Data Source’s Editor button. There is a “Make Relative Path” button, used to change the path to the database from an absolute one into a relative one (necessary when referencing Access, Excel) and when you want to upload templates, your database and your DocumentAssembly.config file to your cloud account. Also, use this button to add further collections.
Other Properties
a. Allow User Home configuration to override. When a template is run from a given folder, then the list of data sources defined in the configuration for that folder is merged with the list of data sources defined in the user’s Home configuration. If two data sources have the same name, then the data source in the template folder configuration will take precedence over the same-named folder in the Home configuration. This behaviour can be modified on a per-data source basis by checking the ‘Allow User Home Configuration …’ checkbox for the data source in question.
b. Filter. The filter can be used to limit the set of rows returned by the data set. For example, a filter of ‘Department=Personnel’ would typically restrict the data source to data only for the ‘Personnel’ department. Filters can also be applied in the data source commands in the template.
c. Use for All Templates. Suppose all templates are to contain signature information of the person running the template. This can be achieved in at least two ways:
i. The signature information like name, email, telephone extension, etc. can be kept in each user’s Standard Date Items in the configuration for their Home folder.
ii. It may be that the company holds all that information in a central database. That database can then be defined to XpressDox as a Data Source, and either each relevant template could then have an «IncludeDataSourceData(Employee DataSource)» command entered on it; or
in each user’s Home configuration, the Employee data source could be defined with the ‘Use for All Templates’ flag set, and the ID Value for that user’s information in the Data Source entered. Then, without any further action on the user’s part, their own Employee information will be made available for every template that they run.
The ‘Use for All Templates’ indicator can be set on data sources in folders other than the user’s Home folder. These data sources are then made available on all templates run from that folder only.
When a Data Source is used on all templates, the ‘Refresh’ and ‘Save’ options can be configured as for the IncludeDataSourceData and ChooseFromDataSource commands.
Mapping the data source names
This is done using the Data Source Name Mapping button on the toolbar which looks like this:
This feature is provided for situations where, for example, templates may have been set up referring to various data elements, and then at some time thereafter a data source is used to provide values for those data elements. It may be that the names of the data elements in the data source are not the same as the data elements in the templates. It may be too time consuming, or inappropriate for some other reason, to change the names of the data elements in the templates. Using the Data Source Name Mapping feature enables the template author to change the names of the data elements in the data set extracted from the data source.
The names in the data source itself are not changed: the changes are applied to the data set after it has been extracted from the data source.
