Foreign Templates to XpressDox syntax conversion

A “foreign” template is a template marked up for use in another document assembly system, such as HotDocs®, GhostFill® or DealBuilder®/ContractExpress®.  The discussion below applies to HotDocs when using XpressDox versions prior to version 4, but after version 4 the discussion applies equally to GhostFill, DealBuilder and documents using Word Merge Fields as well as HotDocs.

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

Because XpressDox and the other 3 document assembly systems each 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 the foreign system, 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 «If(OPTION1 = ‘Y’)» … «End()».  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 «ChooseUsingCheckBox(Option,Y,N)» or «ChooseUsingCheckBox(Option,T,F)» or «ChooseFromRDBList(PersonIsMale,Yes,No)»)  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” (which, with new installations of XpressDox after Version 4 are the XpressDox default delimiters) 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:

1. 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).
2. A best attempt at translating the various foreign constructs is made (e.g. GhostFill dialogs are translated to XpressDox using tabs and Define commands).
3. In appropriate places, a «ChooseUsingCheckBox()» command is generated in the document (and colored red as discussed below).
4. The resulting XpressDox fields are colored red, dark red and blue to indicate the degree of certainty with which the translation can be regarded.  Red is least certain, and blue most.
5. The red and orange fields have the original foreign 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 or GhostFill variables,  then the conversion will be adequate as-is.  But as soon as other foreign 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, dark red 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 foreign system 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.

Using a dictionary

XpressDox version 4 introduces the concept of a dictionary to aid conversion of templates.  This is for the situation where you know exactly how a foreign fillpoint/merge field should be translated to XpressDox.  It is only necessary where the automatic translation for that field is inadequate.
What is required here is to provide a CSV file, called FillpointConverterDictionary.csv, which is stored in the folder containing the foreign templates to be converted.  This file can be created using Excel, or OpenOffice Calc or any other text editor.  The format of this CSV file is a line for each foreign field to be translated (as stated, only those fields for which the automatic conversion is inappropriate need be specified), where the contents of the foreign field (excluding the delimiters) is in the first column and the content of the XpressDox fillpoints (also excluding fillpoint delimiters) are in  in the second and subsequent columns.  An example (for GhostFill) would be:

Legal.Parties(‘Plaintiff’).isare<column>Plural(count(Plaintiff), ‘is’,’are’)
Legal.Parties(‘Plaintiff’).heshe<column>Gender(PlaintiffGender,count(Plaintiff),’he,she,it,they’,’Masculine,Feminine,Neuter’)

N.B. do not type the characters ‘<column>’ in the file – they are just used here to indicate where the next column in the CSV file starts.