The Processing Phases of XpressDox

When running a template in XpressDox (i.e. in the Word add-in), you are interacting with five phases of processing. These are:

1. Template normalisation.

This process consists of merging the templates referred to in «BaseTemplate()» and «IncludeTemplate()» commands, and also «UseScript()» commands, into one comprehensive template.  All of the commands in the Templates category in the Command Editor are processed in this phase (except for «InsertTemplate()» which is a special case). (Please note some further special cases which are described in Inserting documents with variable names (Part 2))

2. Data acquisition.

During this phase the data set to be merged into the template is prepared.  The data set can be acquired entirely from the user, in the data capture interview, or from one or more data sources (such as databases, spreadsheets, XML text files), or both.  Most XpressDox fillpoints are used in this phase, especially (but not only) those in the Data Capture (Interview) and Data Sources categories in the Command Editor.  Since the introduction of the OnExitSet command, it is possible to conditionally inject new data elements into the data set (obviously using that command) during the execution of the data acquisition phase.

3. Data merging.

All the commands which relate to insertion of data into the template to produce a merged document are executed during this phase.  This includes all the formatting functions (in the Formatting Dates, Formatting Numbers and Formatting Strings categories of the Command Editor), the Conditional commands, Repeating commands and Variable functions and commands.  Note that this is when SetV, IncrementV and GetV (i.e. the Variable functions) are executed.  This means, amongst other things,  that variables are unknown during the Data acquisition phase – i.e. they can’t be used to control what happens in the interview.

4. Bridging.

This phase is executed immediately after merging the data into the template, and specifically while the (otherwise temporary) values of any variables constructed during the merging phase are still known.  The only command executed in this phase is the «CreateDataElement()» command (which, amongst other things, explains why data elements created by this command can’t be used to merge into the current document (because they are created after the merging phase) although they can be merged into subsequent documents that use this data set with the Use Other Data feature, or the MergeTemplate or InsertTemplate commands).

5. Post assembly.

During this phase the merged document and the data set are saved into the files and locations required by the configuration (or to default locations where there is no configuration).  All the commands which are used (together with the configuration) in determining these locations are also processed at this point.  These are commands such as «SetSavedDocumentFileName()», «SetCustomDocumentProperty()», etc. – i.e. all those commands in the Post Merge category of the Command Editor.  This gives rise to some anomalous syntax which applies only to those commands, and that is the so-called File Path Fillpoints.
For example, if a merged document file name is to be constructed of, say, the string “Contract for” and then the first and second party’s names, the command might look something like
«SetSavedDocumentFileName(Contract for <FirstPartyNames> and <SecondPartyNames>)»
This requires that FirstPartyNames and SecondPartyNames are data elements (and notice that they are enclosed in single < and >).  This syntax applies to all Post Merge category commands (even «SetCustomDocumentProperty()», for example, even though it is not used to construct a file name).An important point to note here is that if the argument to a Post Merge command is to be constructed using conditional logic (i.e. with «If()»«End()») then there is a mixture of processing phases involved.  This is because in the end the Post Merge command can only accept one string (which may refer to data elements between < and >) but is processed after the third phase, which is when the «If()» commands are processed.  This is where the «CreateDataElement()» command is used – in order to bridge this gap between Phase 3 (Data merge) and Phase 5 (Post merge) processing.
By way of  illustration: suppose we need to save the merged document in a file with the data element CompanyNumber in its file name when the party is of type Company, and with the value of the IdentityNumber data element in the file name when the party is of type Individual.  The document logic (to be executed in the Data Merging phase) will be to create an XpressDox variable ‘Num‘ whose value is either the CompanyNumber or IdentityNumber depending on the value of PartyType, as follows:
«If(PartyType = ‘Company’)»«Setv(‘Num’,CompanyNumber)»«Else()»«Setv(‘Num’,IdentityNumber)»«End()»
Then, in Phase 4, create a data element, for use in Phase 5, called ‘Number’:
«CreateDataElement(‘Number’,GetV(‘Num’))»
Lastly, issue the command to construct the file name (executed in Phase 5):
«SetSavedDocumentFileName(Contract for <Number>)»

Note that, because the different phases are executed in chronological sequence, it is not necessary to place Phase 4 and Phase 5 commands anywhere particularly in the template – they can appear at the beginning or the end or somewhere in the middle. Similarly, the sequence of Phase 2 commands (those governing data acquisition) in the template have a bearing on the sequence of fields on the interview, but they can appear anywhere in the template relative to the commands in Phase 3 (the data merging phase).  This means, for example, that a «FormatNumber(SellingPrice)» can appear in the template before (or after) the command «ChooseFromList(SellingPrice,100,200,300)».