XpressDox Document Assembly » XpressDox Cookbook

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.

How do I know what the data element name is?

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

In trouble shooting a template, you need to know the data element names. Obviously.

But looking at an interview, the data element names are not always obvious, especially if you have used <>s.

Another situation is with ChooseFromDataSource, and ChooseFromFile (and the Include… variants of those commands), where XpressDox generates a special data element name.

The way to find out what the data element name of any control on the interview is, is as follows:

Put the cursor into the control in question.
Press and together.

The name of the data element (and also any condition applying to it) will be shown in the Help area at the bottom of the interview form.

Working with LinkToDataSource

Peter — Tue, 05 Jul 2011 19:45:15 +0000

Working with LinkToDataSource – example with a highly normalised data base.

You need to access a database which has the following structure:

Table “Contact”
ContactFirstName
ContactLastName
ContactTitle
Address
City
Region
ContactTypeId

Table “ContactType”
TypeId
TypeDescription
TypeCode

You can see that the actual value of TypeDescription is not kept in the Contact table, but a link to it is kept in the Contact table via the column ContactTypeId which corresponds with the TypeId column in the ContactType table.

Now, there is some text in the template that looks something like:

Dear <> <>

We will take pleasure in meeting with you on <> to conclude our contract.

<>Please make sure you bring your FICA details.<>

…

It is clear that we would need to configure a data source to access the Contact table. Suppose this is done and the data source is called “Contacts”. We could then put a ChooseFromDataSource command in the template, expanding the above snippet to something like:

<>

Dear <> <>

We will take pleasure in meeting with you on <> to conclude our contract.

<>Please make sure you bring your FICA details.<>

…

The issue then is how to get hold of the ContactType information (so that the test for TypeCode will work correctly). One way would be to configure the ContactType table as a sub-collection of the Contact table in the Contacts data source (you can see an example of this in the configuration of the Northwind CustomerOrder data source in the My Documents\XpressDox\Samples folder). The problem with this is that, although it would work, it would make it appear that each row in a Contact table has multiple ContactTypes, which is not the case.

Another approach would be to go about it in this way:

In addition to the Contacts data source defined above, define a ContactTypes data source, referencing the ContactType table, with an Id which is the TypeId column (fairly obvious).
Now we need to select a kind of “trigger field” in the interview which will trigger the reading of that ContactTypes data source. A good candidate is the AppointmentDate data element, as it will appear in the interview after the fields referencing the Contacts data source. This is good, because when the Contacts data source is read, the data element ContactTypeId will be read from the Contacts data source, and it is the value of this ContactTypeId data element which is needed as the Id to retrieve the ContactType information.
Then, use the following command:<)>>

What will happen, then, is that when the user enters the AppointmentDate and moves the focus out of that AppointmentDate field in the interview, XpressDox will read the ContactTypes data source, using the value of the ContactTypeId data element as the Id, and retrieve the relevant row from the ContactType table. This will populate the TypeCode data element, and so the test against it will have the correct values to test against.

The reason for the Id= parameter is that by default, when a LinkToDataSource command is executed, if the Id= parameter is missing, then the value of the data element in the command is used as the Id of the linked data source – and in this example, AppointmentDate is that data element, and obviously is NOT the Id of the ContactTypes data source.

Why not link to the ChooseFromDataSource?

In fact, there is no reason why not to link the ContactTypes data source to the data element of the ChooseFromDataSource command. Then the Contact Type information would be read “at the same time” as the Contact was chosen – or at least immediately after the Contact is chosen. The question is – what is the name of that data element? Because the command ChooseFromDataSource doesn’t specify a data element name, only a data source name. But in fact, for each ChooseFromDataSource command, XpressDox generates a dummy data element with name ‘XD’ followed by the data source name. So in this case the data element name is ‘XDContacts’. The ideal version of the above snippet would then be:

<>
<)>>
Dear <> <>

We will take pleasure in meeting with you on <> to conclude our contract.

<>Please make sure you bring your FICA details.<>

…

What about other linked database tables?

In practice, databases which are normalised as in this example will have numerous tables linked via “id” columns to the main Contact table. For example, the contact may have a home address, business address, postal address, billing address, etc. And in this kind of database, there would be a separate table “Address” containing only addresses, and in the Contact table, instead of there being columns containing the addresses themselves, there will be columns like “HomeAddressId”, “BusinessAddressId”, etc.
The way to handle this would be to configure a separate data source for each of the different address types, and use the configuration mapping feature to name the data elements uniquely – i.e. all the Home Address data elements would start with “Home”, all the Business Address elements would start with “Bus”, etc.
Then, if in a specific template you required the contact details as well as the business and postal address details (but not home address), then you would have a ChooseFromDataSource command to enable the user to select the contact, and then one LinkToDataSource command for the business address data source, and one LinkToDataSource command for the postal address details, something like this:

<>

<)>> <)>>

Web Server: Integration and URL Structure

Charl — Mon, 25 Apr 2011 13:45:37 +0000

Here are the technical instructions to construct the relevant URLs required to integrate the power of XpressDox Document Assembly into you own web sites or web applications.

Before you can run your first web based template, you will need:

the XpressDox Desktop, the application used to author your XpressDox templates. This can be downloaded from http://www.xpressdox.com/download/.
your XpressDox Web Server registration email containing your Username, Password and Unique Account Code. If you do not yet have an account, register at http://www.xpressdox.com/serverregistration/.

To run your first web based XpressDox template, you need:

an XpressDox template.
upload your template to the Server by logging in to the XpressDox Server Manager application, using your Username and Password, from the XpressDox ribbon in Word (XpressDox Ribbon > Settings > Server).

Your template is now in the cloud and ready to be integrated into your website and business process.

To integrate your template in your web site or web application, you need:

using the Server Manager, generate the unique URL that will point to the template by clicking the Generate URL button. The structure of this URL is described in detail below.
on your web page that the interview is to be displayed, create an iframe and set the src attribute to the URL described below.
the user completes the interview form and clicks Submit.
a document will be generated by the XpressDox Server and the user will be redirected to the Return URL specified in the original template URL.
the Return URL will point to a page on your site where you can control what the user is able to do with the generated document. For example, this could be a simple Thank You page, a Download page, or a link embedded in a particular process.

The structure of the URL required to integrate your template into you site is as follows:

the Server Manager is used to generate these URLs.
http://server.xpressdox.com/XpressDoxServer/Pages/XpressDoxInterview.aspx?templateIDs=[TEMPLATEIDS]&redirectURL=[THE_URL_REDIRECTED_TO_AFTER_DOCUMENT_ASSEMBLED]&[extraParam1]=[SOMEINFO]&[extraParam2]=[SOMEMOREINFO]

The parameters explained:

TEMPLATEIDS. This is the Unique Template Code used to identify the web based template. Multiple templates can be run in a single call. To do this, separate the relevant template codes with the pipe character: |.
THE_URL_REDIRECTED_TO_AFTER_DOCUMENT_ASSEMBLED. The URL to redirect back to once the document has been generated. The redirect URL structure is detailed below.
extraParam1=SOMEINFO. You can include any number of additional parameters in the posted URL. All additional parameters passed will be included in the returned URL. This is to allow your site to retain any context that may be important to you.

Below is the structure of the URL that the iframe is redirected to on completion of the documents—the Return URL:
http://[THE_URL_REDIRECTED_TO_AFTER_DOCUMENT_ASSEMBLED]?usageIDs=[USAGEID]|[DOCUMENT_NAME]&[extraParam1]=[SOMEINFO]&[extraParam2]=[SOMEMOREINFO]

The parameters explained:

THE_URL_REDIRECTED_TO_AFTER_DOCUMENT_ASSEMBLED. The URL that is redirected back to once the document has been generated.
USAGEID. The Unique Usage Code for a generated document.
DOCUMENT_NAME. The display name of the generated document.
UsageID and Document Name are separated by the pipe character: |. In the event that multiple documents are generated, the UsageID|DocumentName items will be further separated by the caret character: ^.
extraParam1=SOMEINFO. All your additional parameters passed with the initial template URL. You can now use this data to retain any context that may be important to you or your user.

Below is the structure of the URL used to download assembled files from the server, either Microsoft® Office Word files (.doc), PDF files (.pdf), or Data files (.xml):
http://server.xpressdox.com/XpressDoxServer/Pages/download.aspx?usageID=[USAGEID]&fileType=[TYPE_OF_FILE]

The parameters explained:

USAGEID. The Unique Usage Code for the generated document as returned in the return URL discussed above.
TYPE_OF_FILE. The type of file you want to download for the identified assembly. Each assembly can generate three possible files:

MS WORD Document (Set fileType to ‘doc’)
PDF Document (Set fileType to ‘pdf’)
XML Data File (Set fileType to ‘xml’)

Use a SQL Server Data Source to include Customer information on a template

HotDocs to XpressDox syntax conversion

Peter — Mon, 18 Apr 2011 15:17:03 +0000

The XpressDox template conversion utility introduced here can convert certain HotDocs fields to XpressDox fields, not just by replacing field delimiters, but in addition by translating the HotDocs syntax to XpressDox syntax.

Because both XpressDox and HotDocs have a very large vocabulary of commands and functions, the one-to-one conversion of one to the other is not possible in all circumstances. A rule of thumb is that the more effort put into using the advanced features of HotDocs, the less likely it is that the conversion to XpressDox syntax will be successful. In fact, XpressDox handles some situations (for example data bases and lookup lists in files) in radically different ways to those employed by other document assembly systems, so that appropriate migration to XpressDox will require some re-design.

However, the syntax converter will attempt at least to produce an XpressDox template that runs directly on being converted, if at all possible.

One feature that requires some initial consideration is that of boolean values – i.e. true or false values. XpressDox uses XML data, and all XML data values are manifested as strings. Thus, a HotDocs construct like «IF OPTION1» … «END IF» needs to become something like <> … <>. The template author will need to make a decision in advance as to what convention they will use for this (for example, will they be coding XpressDox Choose commands like <> or <> or <>) The syntax converter will provide this kind of conversion, but can only do the conversion if it has been provided with the string values for True and False which will be used in the converted XpressDox templates. That is why the two places where syntax conversion can be selected (see below) have an area where the “true” and “false” values are supplied.

Syntax conversion can be performed either on a per-document basis (using the “Convert Current Document’s Fields” feature in the first tab of the Template Author Utilities) , or else on all the documents in a folder (using the “Configure and Convert Delimiters” tab as described here).

When doing a per-document conversion, then the Replace field delimiters(Non-Interactive Conversion) option must be chosen, and then the Replace delimiters and Convert syntax option.

Note that you can select to use as the XpressDox field delimiters the “chevrons” that HotDocs uses (i.e. they are chosen as the Authoring Delimiters in the “Configure and Convert Delimiters” tab of the Template Author Utilities). In this case the Replace field delimiters option must still be chosen, even though, strictly speaking, the delimiters will not be replaced.

During the process of performing the conversion, the following conventions apply:

A HotDocs variable name is converted to an XpressDox data element name by translating all non-XML characters in the HotDocs variable name to ‘_’ (underscore).
A best attempt at translating the various HotDocs constructs is made.
In appropriate places, a <> command is generated in the document (and colored red as discussed below).
The resulting XpressDox fields are colored red, orange and blue to indicate the degree of certainty with which the translation can be regarded. Red is least certain, and blue most.
The red and orange fields have the original HotDocs field following them in a specially coded XpressDox comment field.

After the conversion has been done, the results need to be examined by the template author to ensure that the translation has produced a template that conforms with the system they have designed. In the simplest case, where all the fields contain only HotDocs variables, then the conversion will be adequate as-is. But as soon as other HotDocs constructs have been used, the resulting templates should be examined.

The “Convert Current Document’s Fields” tab has three buttons that assist with this – they are the three on the right colored red, orange and green. The first two will locate the relevant colored XpressDox field, and those fields can then be examined and changed, if necessary. The green button will remove all the comments which have been generated by the converter which contain the original HotDocs field.

It is recommended that the “Delete Comments” function is performed on all templates produced with syntax conversion, as in some cases the resulting XpressDox template will not run with those comments in place.

Version 3.5.0 (2011-03-04)

Peter — Thu, 17 Mar 2011 11:52:48 +0000

Templates authored in HotDocs®, GhostFill®, ContractExpress® and other document assembly systems can, with varying degrees of certainty, be converted to run successfully with XpressDox.

Why this works

In principle, almost any delimiters can be used by XpressDox as fillpoint delimiters. For historic reasons, the << and >> pair were chosen as the default, and all the XpressDox documentation and sample templates use those as the fillpoin delimiters. A fundamental design principle of XpressDox, however, was that the user should be allowed to choose his or her own delimiters.

The delimiters need to be chosen carefully, so that they are unambiguously interpreted by XpressDox as delimiters. An obviously bad choice would be to use ” and ” as the delimiters. The << and >> pair is a good choice as it is unlikely that these will be used in normal text inside a document. Correctly chosen, delimiters consisting of two characters (for example *{ and }*) will be less likely to occur naturally in a document than a single character (for example { and }) would be, and hence would be a good choice. Another good choice would be single characters which are unlikely to occur in normal usage, such as « and ».

Once you have decided on your choice of delimiters, if they are not the default XpressDox delimiters, then this choice needs to be registered with XpressDox so that the authoring tools (such as the Command Editor) use that pair of delimiters rather than the default XpressDox delimiters. This is done by using the Template Author Utilities in the ribbon or toolbar. The Template Author Utilities form consists of a number of tabs, and the first section in the Configure and Convert Delimiters tab gives access to the feature that allows you to choose your own delimiters. The delimiters thus configured are referred to as the Authoring Delimiters.

An important, and powerful, feature of XpressDox is that regardless of what authoring delimiters are decided on in the end, the XpressDox engine will always recognise a template which uses the following pairs of delimiters:

The default XpressDox delimiters << and >>
« and » (which are used in HotDocs templates)
%[ and ] (which are the GhostFill delimiters)
{ and } (which are used by ContractExpress and other document assembly systems)

These sets of delimiters are called XpressDox Native Delimiters.

The algorithm that XpressDox uses when interpreting a template is to first look for the authoring delimiters (which might be something like *( and )* if that’s what you’ve chosen, or might be any of the pairs of native delimiters), and if the template contains no fillpoints with those delimiters then it goes on to look for the next set in the list of native delimiters. Once it finds at least one fillpoint for a given pair of delimiters, it then settles on that pair as the delimiters for that template and any templates included via BaseTemplate, IncludeTemplate, InsertTemplate or MergeTemplate.

An effect of the above algorithm is that if a template authored for HotDocs, GhostFill, ContractExpress, or any system using one of the sets of native delimiters, has only “simple” fillpoins—that is the fields consist of variable names only within delimiters—then XpressDox can run that template without the need to make any changes to the content of the template. All that would be needed is to save that template as an XpressDox template in Microsoft® Office Word 2003 XML format, and run it.

Please note: the variable names in a simple template described above need to be valid XML element names, which will always be the case in some document assembly systems, but in particular might not be the case with HotDocs templates, where spaces are allowed in variable names.

If a foreign template contains fillpoints which are not simple, containing formatting instructions or conditional assembly or repeating instructions for example, then the syntax of those fillpoints needs to be changed to conform to XpressDox command syntax. When foreign templates have used many such fairly complex structures, the conversion process can be quite onerous. To assist with that, the Template Author Utilities Convert Current Document’s Fields has some powerful features which will make this onerous task less so. This feature is discussed later in this article.

Note on choosing your own delimiters: if you choose delimiters other than any of the native delimiters, then other users will not be able to run templates authored with those non-native delimiters unless they also register those delimiters on their system as the authoring delimiters. If those users are also advanced template authors then they can use the same process as described above, using the Template Author’s Utilities. However, you can ensure that all users get the same definition for the non-native authoring delimiters by ensuring that the file on your system with the path \o2Smart\XpressDox\WordAddin\SiteSettings.xml is installed in the same path for all other users of your templates which have non-native delimiters. (For Word 2003, the above path is \o2Smart\XpressDox\VSTO2003\SiteSettings.xml)

Save the converted template in XpressDox format

In order for a document to be run as a template by XpressDox, it must be saved as an XpressDox template. Typically, foreign templates will be in .doc or .dot or .rtf format, whereas XpressDox templates must be in Word 2003 XML format. Saving a document as an XpressDox template can be done in one of two ways:

Open the template in Word, and save it using the XpressDox Save as XpressDox Template button in the ribbon or toolbar
Convert an entire folder of documents as follows:
1. Load the XpressDox Template Author Utilities using the button on the ribbon or toolbar.
2. Choose the Configure and Convert Delimiters tab on the screen that appears. The screen will look like this:
3. The second part of that tab is the area where you can designate an entire folder of foreign templates to be saved in XpressDox template format. Choose the folder either by typing in the path or using the Browse button.
4. Optionally select the fillpoint delimiters that are on the existing foreign templates (which will be converted to the current Authoring Delimiters, as discussed above, and which are displayed for your information on the conversion form).
5. If you have chosen to convert text (field) delimiters, then the converter will also, if required, convert the syntax within the delimiters from HotDocs syntax to XpressDox syntax. If this is required, then check the checkbox labelled “Replace delimiters and Convert syntax (first pass). (Please read the article HotDocs to XpressDox syntax conversion for more details on syntax conversion).
  XpressDox, unlike other document assembly systems, does not have the concept of a data element containing a boolean (i.e. true/false) value (this is because the data used by XpressDox are XML, and XML supports only string value). This means that constructs like «IF OPTION1» «END IF» in HotDocs need to be translated into something like <> <> in XpressDox. The syntax converter will perform this translation, but needs to be given the “true” and “false” values that should be used, and hence the need to provide these in the converter’s screen.
6. Pressing Convert will cause all the Microsoft® Word documents in the provided folder to be converted to XpressDox templates.

Converting complex templates

In principle, there is a common set of features that various document assembly systems offer in order to automate the production of standard documents. However, that does not mean that there is necessarily a one-to-one correspondence between features in one system and similar features in another. This means that converting a template from, say HotDocs to XpressDox is not a simple matter of changing fillpoint delimiters. In any case, as discussed above, XpressDox will work natively with a template marked up with HotDocs delimiters. It is not just delimiters that may need to change, but the content of the fillpoints and sometimes even the basic design of the template and its commands.

The XpressDox utility for converting complex templates is found in the XpressDox Template Author’s Utilities, in the first tab called Convert Current Document’s Fields. The form with this tab visible looks like this:

The following steps are appropriate:

Load the document (foreign template) to be converted, into Word.
Load the template converter above.
Notice that there are a number of situations handled:
1. The foreign template contains Word Fillpoints, and these are to be converted to XpressDox fillpoints.
2. The foreign fillpoints use text delimiters, such as those used by HotDocs, GhostFill or other document assembly systems.
3. “Copy-and-paste” document assembly where a user has marked up a template with codes such as “****” and just uses copy-and-paste (or find-and-replace).
Choose the delimiters that are required.
Because this discussion is about complex templates, the check-box “Replace field delimiters only (Simple Conversion)” is not appropriate here.
Once the Convert button is pressed, then the converter takes each foreign field in turn and presents the contents (stripped of delimiters) in the “Existing field” text box. At the same time, the converter fills the “XpressDox field” drop-down box with samples of what might be used as data element names.
1. You can choose from the drop down list, or edit the XpressDox field.
2. If you choose one of the choices in the “Common Commands and Functions” list, then the converter will take the data element name that is now in the XpressDox field and insert it into the correct place in the chosen command/function.
3. Suppose in the previous step you choose a FormatDate or FormatNumber but don’t like the format that is provided. You can change that format, and then copy-and-paste it into the Snippets area. Then, in a later field, you can choose that format specifier in the Snippets drop-down and then paste it into the “XpressDox field”. In other words, the Snippets area gives you a place to store frequently used snippets of text to be copied into commands at a later stage of the conversion. Even into future documents to be converted.
4. Once you like the contents of the “XpressDox field”, press the Accept button, and the converter goes on to the next field in the foreign template.
The converter stores all the “Existing field” values as well as the resulting “XpressDox field” in a sort of “translation dictionary”. It stores that dictionary into the folder where the foreign template resides. Thereafter, whenever it encounters a field in a foreign template during conversion, it looks up the field contents in the dictionary, and presents as a default the corresponding XpressDox field in the “XpressDox field” on the conversion form. This means that after a few templates in a suite have been converted, as long as the original template author was consistent in the naming of variables (now data elements in XpressDox) and conditional commands, etc., then the conversion of templates becomes a question of inspecting the choice suggested for the conversion of a fillpoint, and pressing the Accept button over and over again.
Once a template has been converted, it must be saved as an XpressDox template (with the Save button on the ribbon or toolbar).

Select templates using a master template

Peter — Tue, 25 Jan 2011 11:47:10 +0000

You have an application which requires a fairly large number of templates to be merged, but you do not want the user to have to choose the correct templates to run using the XpressDox Explorer, you rather want to use document assembly commands to select the templates to be run depending on data or user choices.

You could use the RunTemplates command, which is fine if you know beforehand which templates should be run. The <> command will also present an interview for each template in its list. This might be what you want, but if you want to be able to select the templates to be run depending on data captured, then RunTemplates is not what is required.

The MergeTemplate command is almost the same as RunTemplates, but can be subject to an <> command, and so can be run depending on conditions that the template author dictates. Also, MergeTemplate does not present a new interview for the template to be merged (as does RunTemplates), XpressDox uses the data set which was used for the preceding template for this.

A code sample of how this might work in practice would be the following snippet:

<>
<>
<>
…
…
<>
… (somewhere in this template (or a template included by <>) would be commands to make sure that the interview captures all the information needed on the templates to be merged)
…
<><><>
<><><>
<><><>

If you call this template something like “MasterTemplate”, then all the user needs to do is run that one MasterTemplate, and all the decisions as to which further templates to be run are effectively made for them by the template logic.

Build all the subsidiary templates into one single document

Sometimes the requirement is that all the chosen documents are merged into one long document, rather than each being a separate document (the MergeTemplate command will create a separate Word document for each template merged).

This could be done by using the IncludeTemplate command in the place where MergeTemplate is used above. The drawback of this is that IncludeTemplate will include the entire text of the template BEFORE the interview is presented, and if that text is excluded via an If command, that is done while the template is being merged. This is satisfactory if there are not too many long templates thus included, but if the included templates are large and/or many then the resulting pre-interview text can be enormous and give rise to memory problems.

In a situation like this, the solution would be to use the InsertTemplate command. The InsertTemplate command is very similar in effect to IncludeTemplate, except that the text of the template is inserted into the merged document during the phase when the template is being merged. (The different phases of XpressDox are described in The Processing Phases of XpressDox).

There are some issues surrounding the insertion of one Word document into another (regardless of which command is used), these are Source and destination formatting, and Word section processing, specifically with regard to headers and footers and paragraph and page numbering.

It is highly recommended that Destination formatting be used. It means that care has to be taken to make sure that styles used in the inserted template are also defined (correctly) in the master template, and that Word skills are used to make sure that any paragraph numbering starts off at 1 again on the inserted document. That is all the subject of another article, yet to be written.

In order that headers and footers in the inserted document are included correctly into the master document, the command needs to be issued with the PreserveHeaders parameter:

<>

The next issue to be catered for is the question of encouraging Word to put its section breaks into the correct place. You will probably want to experiment yourself, but an example that works would look something like this:

…
================= Section Break (Continuous) ========================
<>
================== Section Break (Next Page) ========================
<>
<>
<>
================== Section Break (Next Page) ========================
<>
<>
<>
================== Section Break (Next Page) ========================
<>
<>

Actually, that example will not work correctly, as each template inserted will be preceded by a Section Break (Next Page) whereas only the first template needs that Section Break. This then needs some code to make sure that it happens only once, and the following example will do it:

…
<>
================= Section Break (Continuous) ========================
<>
================== Section Break (Next Page) ========================
<>
<>
<>
<>
<>
================== Section Break (Next Page) ========================
<>
<>
<>
<>
<>
<>
================== Section Break (Next Page) ========================
<>
<>
<>

How this works is that the XpressDox variable SB determines whether a Section Break (Next Page) should be inserted or not. It starts off its life with the value ‘Y’ so that the first template which is inserted will be preceded by a section break. But then after each template is inserted, the variable is set to ‘N’ so that for each subsequently inserted template, the section break will not be inserted.

Search for a file using the Explorer

Peter — Mon, 03 Jan 2011 09:11:17 +0000

The XpressDox Explorer does not contain an explicit “Search” function. Nonetheless, you can search in the currently open folder for a file, using the Windows file system’s wild card syntax.

The example below demonstrates how the wild card string *letter*.xdtpl will list all (and only) XpressDox templates with the string “letter” in the file name (type the wild card string in the File name area and then press the Open button)

A Rose by any other name

Peter — Tue, 21 Dec 2010 16:35:26 +0000

or, what should I call this data element?

One of the advantages of template development in XpressDox is that it is not necessary to spend a lot of time deciding on names for data elements. You can create a good first-time template just by plunking in fillpoints like <> <

> <> <> and away you go – an automatic interview will be created and you can capture the data and merge it into the template to create whatever document it is.

That’s good as far as it goes – you can get started with XpressDox very quickly. You don’t have to design, even conceptually, all the templates and their interactions and create a “data dictionary” before you get going. Just make templates and keep going until they’re all finished.

The problem is that without some help, the fields that you typed as <>, <> on the first template end up as <> and <> on one or other later template. And, because the field names are really XML data element names, surname and Surname are not the same thing, and definitely not First_Names and Firstnames.

Now, XpressDox does provide quite a lot of help in getting a consistent set of data element names, mainly via the Command Editor, which enables the display of already-chosen data elements in a way that the template author can re-use them correctly. However, experienced template authors tend to want to use just the keyboard and type all of the XpressDox fillpoints without having continual recourse to the Command Editor. For no other reason than this, it is useful to start off on a large project (i.e. many templates and/or many data elements) by deciding on a naming convention for the data elements. This does not mean that you need to decide on all the data elements up front, but that you decide on how you will assign a name to each new data element that you need to create as you go.

What follows is a set of suggestions (backed up by many lessons over the years from the school of hard knocks) not a set of rules. Probably you could add your own or make your own adaptations. Even so, when you design a set of naming conventions for your organisation, then they MUST become rules, and all template authors in your organisation MUST abide by them – otherwise chaos will be the rule. Here follow a set of rules (in addition to the obvious one, i.e. that data element names should conform to rules for XML element names), although the first one is a kind of meta-rule:

You should have a data element naming convention, even a bad one is better than none.
Call your data elements what they are. For example, if a data element’s value is an interest rate, call it InterestRate, not Interest and not Rate. Even better, call it InterestRatePercentage.
Try not to abbreviate. This and the previous item go together: usually you will abbreviate to save typing, but abbreviations often end up being cryptic and after all, the Command Editor is there to help get the name right. Think about how someone else will read your template and either understand it or not. And remember, that “someone else” is likely to be yourself in a few weeks/months/years and then you won’t remember that you abbreviated InterestRate to Int and InterestAmount to Intrst.
Because of Rule 2 you will end up having many data element names which consist of more than one natural language word (like “interest rate” becoming InterestRate or Interest_Rate). You need to decide how you will designate and delineate those words. My own preference is to use so-called Pascal case, whereas others will separate the words with an underscore, and have different rules regarding whether to use upper or lower case at the start of each word in the name. Almost universal, though, is an abhorrence for using ALL CAPITALS which tend to make the marked up text look very noisy.

That’s it – one meta rule and three rules. Easy enough to remember when there are only 3, but worth the effort in the long run.

Encrypt a template

Peter — Tue, 21 Dec 2010 11:42:07 +0000

You want people to be able to run a template that you have made, but don’t want anyone other than yourself to read or modify the template. This can be achieved by encrypting the template.

A template can be encrypted when saving it in the XpressDox Explorer. When saving a template, the XpressDox Explorer will open so that a name can be provided for the template file. On the bottom right corner of the Explorer form, to the right of the Save button, there is an area where a password can be entered. As soon as XpressDox finds a password in that area, it does the following:

Encrypts the password and saves it into the template.
Encrypts the template text then saves it in the file name provided.
Stores a copy of the un-encrypted template into the folder named “PreCrypto” which XpressDox creates as a sub-folder of the template folder. This ensures that in the case where the template author forgets the password, s/he can always recover an unencrypted copy of the template to work with. Care must be taken not to deliver that PreCrypto folder contents along with the encrypted template, or in other ways made available to unauthorised users.

Once a template is encrypted, it can only be opened for editing (or even if only for reading) by the XpressDox Explorer, and a user attempting to open the template will be prompted for the password. Only if the user supplies the correct password will the template open in Word.

However, an encrypted template (or a template including an encrypted template via <>) can be run by anyone without the need to provide the password.

The encryption facility and the RestrictToLicenses command can be used together to protect a reseller’s templates from being pirated.

The encryption and RestrictToLicenses can be applied to a sub-template which is included in every template in a suite of templates (along the same lines as layout commands). In this way sensitive document assembly commands can be protected whereas the more mundane processes can be left unencrypted.