Background
The Data Sources facility provides a way for data captured into some other system to be merged into templates. For example, users may wish to be able to have address and other contact information from Microsoft® Outlook inserted into letters.
This would be achieved by defining the Outlook Contacts as a Data Source. Then when a template is run, the user will be able to select that the Outlook Contacts data source be included in the template and will also be presented with a search interface to enable the relevant Contact to be selected.
Thereafter the Outlook Contact data becomes available for insertion into the template, in exactly the same way as for any other data.
It would typically be the template author who would configure data sources in the system.
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 three main types of Data Source:
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. The Standard Outlook Contacts Data Source. This provides access to the Outlook Contacts database, and can be configured to provide data from any Outlook Contacts folder; by default this is the current user’s Contacts folder (and sub-folders).
3. 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. 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.
c. The Definition String. This is used 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.
In the case of the Standard Outlook Data Source, the Definition String will be used to define the Outlook folder which must be looked up, as well as the Contact properties which should be presented in the data for insertion into templates.
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.
d. 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. For example, an Employee database may be used to provide data about the person running the template, say ‘FirstNames’, ‘Surname’, ‘BusinessPhone’, and these data elements would have the same names as similar data elements in the Outlook Contacts data source.
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»
e. 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.
f. 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.
g. 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.
h. 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.
i. Data Source Defined in another config file. This feature permits a data source defined in the configuration for one folder to be referenced from the configuration for another folder. This means that if the data source definition changes, for example if the server name or IP address of a data base changes, then the change need only be made in one place.
The data source in the referring configuration can be given a name different to that in the defining configuration. Hence the ‘Name in that file’ field.
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.
