XpressDox Document Assembly » Help

Understanding XpressDox Artefacts

Peter — Mon, 14 Nov 2011 12:01:59 +0000

When a template runs, XpressDox creates a number of internal structures. The most important of these is an XSLT Stylesheet. The stylesheet contains the definition of how the data from an XML data set are to be inserted into the Word template in order to generate the merged document. The stylesheet is constructed entirely from the contents of the XpressDox fillpoints in the template which is run (and in any templates included via «IncludeTemplate()» or «BaseTemplate()» commands).

The other important internal structure is the Schema. This is created by XpressDox from the stylesheet. The schema is used to construct the interview in the XpressDox desktop, and also in the browser version of XpressDox.

These internal structures are called “artefacts”, and for large templates the time taken to construct these artefacts can become unacceptably large. And seeing that the artefacts will be exactly the same each time a template is run, it seems a pity to have to construct them each time. For this reason XpressDox creates the artefacts only when the template is run for the first time, and after it (or any of its Included or Base templates) has changed. The artefacts are stored in the “XDArtifacts” sub-folder of the template folder, with the same file name as the template, with the extension changing for each of the artefacts. On the second and subsequent times that a template is run, instead of re-creating the artefacts, XpressDox reads them out of the XDArtifacts sub-folder. (The XDArtifacts folder is not shown in the XpressDox Explorer, as it would just create clutter).

In fact, on the second and subsequent runs of a template, the template file itself is not used by XpressDox, except that its time stamp is used to compare with the artefact’s time stamp to work out whether the template has changed since the time the artefact was created.

Suppress artefact creation

It might be that you (the template author) do not want the template artefacts created, for whatever reason (for small templates (less than about 10-20 pages) this will possibly not make a noticeable difference in execution time). This can be achieved using the command «OptimizeParsing(Off)».

Restoring backups

When restoring a backed up version of a template, care must be taken to take the artefacts into account. This can be done by restoring the backup of the artefacts (in the XDArtifacts folder), or by deleting the artefacts for the restored file.

The reason that this care must be taken is that, for reasons of efficiency, the way that XpressDox determines whether a template has changed since the artefacts were created is by comparing the “Date Modified” of the template with the date modified of the artefact. In the case where a template is restored from a backup, that template’s date modified is highly unlikely to be later than the artefact files, and so when the template is next run, its contents will be ignored and the artefacts will used to create the interview and to perform the merge. But the artefacts in this case will have been created from a later version of the template, not the one that was restored, and so restoring the backup of the template on its own, without restoring the backed up version of the artefacts (or deleting the artefacts), will have no effect.

No related posts.

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')>>

Version 3.11.0 Release

Peter — Tue, 27 Sep 2011 19:37:40 +0000

2011-09-27 Version 3.11.0

<> permits empty “display data element name” (defaults to the first one) when also including a data element name prefix.
The XpressDox SDK has been released. This facilitates embedding XpressDox into another application and permitting display of the XpressDox interview, and application of XpressDox configuration. The SDK can be used on PCs that do not have Microsoft® Office installed (although Office is still required for the authoring of templates and XpressDox configuration functions).

2011-09-12 Version 3.10.2 (Limited release, Word 2007 and 2010 only)

<> supports backtrack XPATH syntax (i.e. “../” at the start of the path)>>.
A bug in the handling of <> has been fixed.
Template Author filtering has been applied to context menus in the XpressDox Explorer, as well as to the “Run This Template” function.

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.

Version 3.9.3 (2011-07-27)

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

2011-07-27 Version 3.9.3

Functionality has been added to enable XpressDox site supervisors to customise the Shared (or Office) Folders settings in the XpressDox Explorer on a per-department or even per-user basis. This is done by assigning a new property to a data source (only in the Shared Settings configuration) which causes data from that data source to be used as though it were “Standard Data Elements”. Instructions are in the new XpressDox Supervisor’s Guide which can be downloaded in the usual Supervisor location on the XpressDox web site.
The <> function can be used to show the value of a data element if it has one, but if it is empty then the whole paragraph in which the function appears will be removed. It means that something like

<> <> <>

can be replaced with

<>

There have been requests to enable headings and footings to be shown conditionally. This can now be achieved with the <> command. This command will put an invisible field onto the interview, but headings and footings attached to the data element specified in the command will be shown. If the data element (a dummy, it is not available for use elsewhere in the template) is subject to a condition, then the heading and/or footing attached to it will appear and disappear subject to the condition. The full syntax of the command is <>. The Define command now includes the PlaceHolder choice in the list of Data Capture Commands, which means that the PlaceHolder command and the relevant Heading and/or Footing commands can all be defined in one.
Force.com data sources now have the ability to show a search dialog. This is for testing purposes only, as integration with Force.com databases is not envisioned to involve users searching the database from an XpressDox template, but rather in the Force.com application itself.

Version 3.9.2 (2011-07-19)

Peter — Tue, 19 Jul 2011 10:23:43 +0000

2011-07-19 Version 3.9.2

When data is included into the data set, the sequence in which this happens is:

Data from Standard Data Items in the configuration;
Data from data sources configured as “Use for all templates”;
Data from <> commands.

Prior to this release, step c. was performed before the other two.

The data source name mapping feature now has a “Add Prefix to All Names” button.
The configuration of data sources now includes a feature to handle seriously normalised data bases, enabling the configuration of “lookup tables”.
PDF Form handling recognises XFA form fields in a PDF form.

Version 3.9.1 (2011-07-07)

Peter — Thu, 07 Jul 2011 08:58:27 +0000

Version 3.9.1 contains some bug fixes as well as the following enhancements:

<> can apply to a <> command in order to permit intuitive handling of highly-normalised databases.
Any number of <> commands can apply to the same data element.
The <> command is implicitly issued for multi-language templates.

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.