XpressDox Document Assembly » User Reference

The SetInterviewDataOnly Command

Peter — Tue, 25 Oct 2011 09:02:53 +0000

If the sole purpose of a template is to construct an interview, but the document merged from that template is not required, then the SetInterviewDataOnly command can be included in the template, and the merged document will be ignored.

A typical usage of this would be in conjunction with the MergeTemplate function, or the MergePDFForm function, where the template is a master template and based on the values of data input by the user, different templates are merged using the MergeTemplate (or MergePdfForm) function.

Example:

<>

Set Web Information for a Template

Peter — Tue, 25 Oct 2011 08:30:14 +0000

These commands will enable the template author to control the workflow around templates which are uploaded and run on an XpressDox server.

SendWebMail

You can provide as many of these commands as necessary. The command can be used to send an email attaching either (or none of) the merged Word document, the merged PDF document and/or the data set captured in the interview.

SetWebButtonText

This provides an alternative text on the button which by default has the text “Assemble Document” on it. Depending on the usage which the template is designed for, it might make sense to change this text to something like “Submit”, e.g.

<>

SetWebReturnURL

Enables the return URL to be provided so that when the interview is complete and the document assembled, this URL is activated.

An example would be:

<&activity=LoanApplication')>>

The ShowIfHasValue Function

Peter — Wed, 27 Jul 2011 13:56:17 +0000

This function is used mainly to get rid of empty paragraphs in a document.

<>

will insert the value of the AddressLine3 data element only if that data element has a non-empty value. If the value IS empty, then the entire paragraph containing the field is removed.

Note that this behaviour applies even when there is other text in the paragraph, and so the function should be used bearing that in mind.

Before this function was introduced, the only other way to achieve the same result would have been to code the following:

<> <> <>

The PlaceHolder Command

Peter — Wed, 27 Jul 2011 13:55:53 +0000

<> will create an invisible control on the interview, but will enable Headings or Footings to be attached to that control.

This would be used to include text into an interview screen, and in particular to include text which must appear or disappear depending on certain conditions.

For example:

<> <> ><> <> <><><< End()>>

The reference number is: <>

When the PartyType is ‘Company’ then the heading “Enter the Company Registration Number” will appear above the Reference_Number in the interview, otherwise “Enter the Passport Number or Social Security Number” will appear there.

Note that the data elements Dummy1 and Dummy2 in this example are named like that because they will not form part of the captured data set, and are not available for use in any other part of the template or merged document.
Each <> command will need its own unique (dummy) data element name.

Typically, the PlaceHolder command would be defined inside a Define command, as the PlaceHolder command is never used on its own but always in conjunction with Heading and/or Footing and perhaps Hyperlink.

The ChooseFromDataSource Command

Peter — Thu, 07 Jul 2011 08:50:49 +0000

The template author will use this command to provide a way for the user of a template to choose data from a Data Source and those data can then be inserted into the template.

Simple Form

The simplest form of the command is shown in this example:

<>

The first parameter is the data source name, and the second is the caption that will be displayed next to the control in the interview.

The control in the interview has a text area and also a button. If the user presses the button, then the data source search form is presented, and they then can search for the data that they require.

If the user knows the value of the Id for that data source (usually a code like an account number or in this example a contact Id), then they can type that into the text area, and the data will be retrieved as soon as the focus moves out of that text area – for example if the user presses the Tab key.

Refresh and Save Options

Another form of the command is

<>

The “RefreshSave” option means that if the user changes any of the data which was retrieved from the data source, then those changes will be written back to the data source. A full explanation of the RefreshSave parameter is given in Control how the user can change data source data.

Restrict the range of the search

Suppose you want the user to be able to select only Customers from the Contacts data source. Assuming the data source has a column called “ContactType”, the command would look something like:

<>

Use variable information in the Range

It might be that the contact type is actually in a data element which has already been populated (it might have been captured by the user in the interview, or included using an IncludeDataSourceData command, or one of many different ways of including data in the data set). Suppose the contact type is in a data element called ContactType - then it can be used in the Range as follows:

<')>>

Manage the button

The last parameter to the command enables the template author to either:

Insist that the user use the search button, in other words they can’t type in any arbitrary ID and have the data source retrieve it:
<>
Disallow the user from using the search button – i.e. they must know the ID of the data that they want:
<>
In effect, this is the same as using the LinkToDataSource command with a normal text box for the control, e.g.
<><>
The third option is “AllowSearch”, but that is the default and so can be left out.

The OptimizeParsing Command

Peter — Tue, 05 Jul 2011 14:20:43 +0000

During the running of a template, XpressDox creates a number of structures.

The most important one is an XSLT Style Sheet, which is used to drive the engine that merges the data into the template to form the merged document as an end result.

The second structure is a schema, which is used to assemble the interview. This schema is used by the desktop and also by the web versions of XpressDox in constructing the interview(s).

Now, these two structures are generated entirely from the template, and once they are constructed, XpressDox actually has no further need for the template itself. So, what XpressDox does now is to save those two structures (as well as another one containing script definitions) into the file system in a place near where the template resides. Then, on second and subsequent runs of the template, the template itself is ignored and only the saved style sheet and schema are used. Depending on the size, and to a certain extent the complexity (meaning depth of nesting of If and ForEach commands), this can lead to a significant reduction in elapsed time between selecting the template and being presented with an interview.

This feature is the OptimizeParsing feature, and all of it happens automatically and behind the scenes, and so there is no action needed on the part of the template author to enable this feature.

There are at least some situations where this feature might not be desired, when the template is encrypted. It might be that the reason for encrypting would become obvious if anyone were to find and read the style sheet which is created. It is up to the template author to decide whether this is a risk or not (the password itself is stored in the style sheet, but in encrypted form, so that is not a risk).

The Hyperlink Command

Peter — Tue, 05 Jul 2011 14:20:15 +0000

The Hyperlink command will attach a hyperlink to a heading or footing in the XpressDox interview. When the user clicks on the heading or footing, then the hyperlink will be launched.

An example would be:

<>

Variable information (sourced from data elements in the data set) can be inserted into the hyperlink URL at the time the user clicks it. This variable information is specified by including the data element name(s) inside single angle brackets, like this:

<)>>

The Hyperlink command needs to refer to a data element (in these examples this is the data element called Description) which has a Heading (or Footing) command specified for it, and that Heading or Footing should be styled by the template author to look like a hyperlink, i.e. underlined and some shade of blue. For example:

<> <>

The Description data element can be defined in full using the Define command, which would look something like this:

<>

The LinkToDataSource Command

Peter — Tue, 05 Jul 2011 14:19:53 +0000

LinkToDataSource links any control on the interview to a data source (a control is what the user uses to enter data, such as a straight forward text box, or a checkbox, or a dropdown, etc.). It means that when the focus moves off that control, a call to the data source is made, to retrieve the data.

The simplest example is where a value like an account number is entered in the interview, and the system is required to read the data for that account number from the data source.

Basic form of the command.

Suppose a data source has been configured to access a database table called Account, and the data source itself is named Account. Further the Id of the data source is defined to be a single column (it doesn’t matter what the column name is, as long as it is configured correctly in the XpressDox configuration for the data source). Further, there is a data element in the interview called AccountNumber, and the user is expected to enter the value of the Id of the data source here.

The command

<>

will link the data source named Account to the control which captures the value of AccountNumber, and when the focus moves out of that control in the interview, the value of that control, which is now the value of the AccountNumber data element, will be used as the Id to retrieve the relevant row from the data source’s table.

Notice that the LinkToDataSource command does not specify what sort of control the AccountNumber data element is to be captured with. That means that constructs like:

<>
<>

would mean that the user would choose one of those three values from the drop-down list, and whichever one they chose would cause the relevant record to be read from the data source.

More advanced uses.

Suppose a data source called Cases has been configured, but this data source has a composite id, in other words the Id consists of more than one database column. In this example, suppose those columns are the Client Number and the Case Number.

Then, the interview could be constructed so that the user is requested to type in a data element called ClientNumber and another data element called CaseNumber. Assuming the ClientNumber is typed in first, then the idea would be that as soon as the CaseNumber is typed in that the system will have enough information to retrieve the relevant record from the Cases data source. The command

<,')>>

will construct the value of the Id from the two data elements ClientNumber and CaseNumber, separated by a comma (which is the default separator between elements of a composite Id) and request the value of the data for that Id from the data source. This will all be triggered after the user has entered the value in the control on the interview for CaseNumber, and has moved the focus (e.g. by pressing the Tab key) out of that control.

Note the quotes around ‘id=,’. These are to prevent the comma between and from being taken as a delimiter between parameters to the command.

Note also the < … > surrounding ClientNumber and CaseNumber. These are to indicate that ClientNumber and CaseNumber are the names of data elements, and that the values of the data elements should replace them in constructing the value of the Id.

The RefreshSave parameter (and the other possible values that it can have) is described in full in the articles Control how the user can change data source data and Other advanced features in XpressDox

As with all other commands which retrieve data from a data source, when the data are retrieved, ALL the columns in the row retrieved from the data source become part of the data set, even those not referred to in the template. This issue is discussed in detail in XML and Data Sets, and also in this article.

Filling PDF Forms

Peter — Mon, 04 Jul 2011 09:01:28 +0000

PDF documents which have been prepared with PDF Form Fields (using a suitable PDF Form editor) can be filled with data captured with an XpressDox interview. In fact, the PDF form can be filled with data from ANY source, as long as it is in XML form.

There are a few steps that have to be taken to prepare the PDF from for use by XpressDox, the most important one being to map the data elements in the XML data set to the form fields in the document. This is done by running the Prepare PDF Form utility, which is accessed via the button in the Advanced Template Author group in the ribbon (or in the toolbar in Word 2003). This will list the fields as the appear in the PDF form, and initially will name the fields with an “F” followed by the field number.

If the author of the PDF form assigned appropriate names to the fields, then those field names could be used as the data element names for XpressDox. The mapping will then be achieved by pressing the “Use Internal Name” button on the Prepare PDF Form utility. Otherwise, you can set data element names for the fields by clicking in the data element name field itself on the utility form and assign the name you would like (much as you would rename a file in the Windows Explorer) .

Sometimes you will be preparing a PDF form which has been authored by someone in a different organisation (e.g. you may be preparing some or other government PDF form for filling with XpressDox) and it may be that the fields are not named in a way that lets you see how the fields appear on the PDF form. The XpressDox utility allows you to open the form in a PDF viewer, and will identify the fields by writing the contents of the Data Element Name column in the utility into the relevant field in the form. This will enable you to identify at least the text fields in the PDF form. Unfortunately, there is no easy way like this to identify fields like check boxes and radio buttons, so at worst these will have to be named and tested and identified by trial and error.

The “Create Interview Template” button on the utility will create a set of XpressDox <> commands which can function as the source for the capture of the data elements in an interview. This is particularly useful for arriving at the correct definition of what is required for check box and radio button controls.

Once the form has been prepared, it is saved (by pressing the OK button on the utility).

The PDF form is filled under control of a normal XpressDox template. The XpressDox template will identify the data set to be used, usually by capturing it in the interview, and then fills the PDF form using the <> function. This function enables you to indicate the name of the PDF form file to be filled, and optionally the name of the file with which the merged result must be saved. For example:

<>

and/or

<>

The actual location of the PDF files is governed by the XpressDox configuration in the same way as the source and location XpressDox templates and merged files is controlled.

Note that the name of the PDF form as well as the output merged field name are in quotes. This is because MergePDFForm is a function. It has the powerful benefit that the names of those two files can be constructed at template run time using XpressDox conditional logic. For example <>

The Plural Function

Peter — Mon, 18 Apr 2011 12:35:34 +0000

Generic documents such as contracts often have numerous places where constructs such as “is/are” or “child/children” appear, or else the singular is always used document has a preamble has words to the effect of “masculine usage includes feminine and singular includes plural”.

With document assembly, and XpressDox in particular, the template can provide instructions in conditional assembly which can insert the correct words in the places where they are required.

An example would be

The name<> of my child<> <>< 1, and )>><><>

Sometimes the number cannot be inferred using count() and has to be requested explicitly either in an interview or perhaps in data retrieved from a data source which is nonetheless not repeating. In this case a boolean expression can be used in place of count():

<>
The name<> of my child<> <>