Convert templates from other systems to XpressDox format

Templates authored in HotDocs®, GhostFill® 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 (with effect from Version 4, all new installations of XpressDox will use « and » as the default delimiters), and all the XpressDox documentation and sample templates use those as the fillpoint 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 (see the screenshot a bit lower down in this article). 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 <Program Files Folder>\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 <Program Files Folder>\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 (with version 4 of XpressDox this is .docx format). Saving a document as an XpressDox template can be done in one of two ways:

1. Open the template in Word, and save it using the XpressDox Save as XpressDox Template button in the ribbon or toolbar
2. 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 third 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 Foreign Templates 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 «If(OPTION1 = ‘Y’)»  «End()» 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:

1. Load the document (foreign template) to be converted, into Word.
2. Load the template converter above.
3. Notice that there are a number of situations handled:
   1. The foreign template contains Word Merge Fields, 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).
4. Choose the delimiters that are required.
5. Because this discussion is about complex templates, the check-box “Replace field delimiters only (Simple Conversion)” is not appropriate here.
6. 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 fillpoint.
   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.
7. 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.
8. Once a template has been converted, it must be saved as an XpressDox template (with the Save button on the ribbon or toolbar).