Find help fast by searching “xpressdox [command name]” in Google
The XpressDox Cookbook
The official XpressDox Cookbook contains various recipes for different aspects of XpressDox. It is intended to complement the User Reference. The latter document is comprehensive in that it covers all of the XpressDox commands and functions, but does so to a limited depth. The Cookbook is designed to give in-depth coverage of certain commonly used aspects.
Authoring Templates (an introduction):
Mark up a Document to be a Template
XpressDox has a Find-and-Replace utility which speeds up the process of marking up a template from an existing document.
Naming conventions
Deciding on a set of rules for naming of data elements can lead to efficiency in template authoring.
The Command Editor
The Command Editor empowers the template author by presenting an alphabetic list of all the XpressDox commands, with functionality which provides wizards for completion of the command as well as supplying examples of commands.
Moving around in XpressDox: The Explorer
“If I were going to Limerick, I wouldn’t be starting here”, an Irishman told a tourist. Yet it can be like that with the Microsoft file and folder explorers, which often enough open far away from where you want to be. The XpressDox Explorer solves this problem for you.
Search for a file using the Explorer
You can use the Windows® file system’s wild card syntax to search for a file in a folder.
Tips for Authoring Templates – Part 1
There are two very useful features in the ribbon versions of Word, which can make the template author’s life a lot easier. These are the Access Key feature and the Quick Access Toolbar.
Tips for Authoring Templates – Part 2
You need a tool to help locate the text that XpressDox inserts into fillpoints. Word®’s Find and Replace come to your aid.
How do I know what the data element name is?
The name of a data element is not always obvious when looking at the data element’s control on an interview screen. There is a way to find out the data element name for any control on the interview.
Best practices:
Best Practices for Advanced Authors: Part I
Developing applications in XpressDox requires some pre-planning and good practices.
Best Practices for Advanced Authors: Part II – The Interview.
The XpressDox Interview is a very important component of an XpressDox document application, and can occupy at least as much effort as ensuring the merged document is correct.
Troubleshooting a template:
Trouble shooting Ends and Elses
In complex templates, the balancing of End and Else commands with the matching If or ForEach can become difficult. This recipe explains how to use the Template Painter and the Debug command.
Trouble shooting Conditional Capture
Conditional Capture can sometimes result in unexpected behaviour, where data elements either are unexpectedly removed from the data capture interview, or appear on the interviewwhen they shouldn’t. This recipe gives some tips on how to trouble shoot these situations.
Trouble shooting missing pictures in documents
Normally pictures, logos, etc., are handled without problems by XpressDox. But sometimes the pictures go missing from the merged document and are replaced by a red X in a box. This recipe discusses why this can happen and gives some advice on how to correct the situation.
Adding comments to a template
Comments can be added to a template either within the body of a command, or using the Comment command.
Where have all my data elements gone?
Sometimes you will have marked up a template and then when you run it, one or more of the data elements don’t appear in the data capture interview. Conversely, sometimes the data element may appear in the capture interview but not on the merged document. This Cookbook recipe gives the background to why this might be, and what you can do about it.
The Interview / Questionnaire:
Provide default values
Using a simple text file as a data source, XpressDox provides the template author with the ability to set data elements to default values which the template user can then accept, or modify for each template run.
Working with Help
Often the name of a data element is descriptive enough to for a user to know what to enter when capturing data. But sometimes more help is needed. XpressDox Docussembly™ has a number of mechanisms available for the template author to provide the data capturer with help in capturing data, in particular using the Help command and also Help in conjunction with IncludeTemplateText.
Validating a NINO
The XpressDox Rule command with its IsRegexMatch option can be used to validate a NINO.
Tips and Hints using the Rule Command
The Rule command can be included into many templates, and hard rules can be softened.
Laying out the data capture interview
XpressDox will create a data capture interview automatically, using the data elements defined on the template. The sequence in which the data elements appear on the interview can be controlled with the CaptureDataElement command, and the Heading and Tab commands can assist with further layout.
Data capture interview layout tips
Although XpressDox will automatically construct a data capture interview for a template when that template is run, template authors will want to make use of the layout commands to control the layout of the interview.
The CaptureLater Command
When a template is run, XpressDox constructs a data capture interview which is guided by the XpressDox merge fields which are coded in the template. The CaptureLater command is one of the commands which can be used to influence this.
Styling and coloring the Caption, Footing and Heading
The style (i.e. bold, italic and/or underline) and color of a Caption or Heading can be set to enhance the usability of the XpressDox data capture interview.
Build a bi-lingual interview
It would be really useful for XpressDox to be able to present an interview in French if the user is a French speaker, and in English for English users, where the document itself is in English. For the same template. And vice versa. XpressDox can indeed do that, as long as the template author marks up the template accordingly.
Using verbose Choose commands
Radio buttons and check boxes provide a way of enabling users to make quick choices. The results of these can be either sort, terse text values or can indeed be whole paragraphs.
Capture a multi-line address in one field
You may not want to have to define 3 or 4 or some maximum number of address line data elements, and have the user capture them one at a time, and still provide conditional formatting logic to suppress any empty data elements. XpressDox document assembly supports this by the concept of long text fields.
Dynamic Captions – changing captions on the fly
Captions can be changed in the interview / questionnaire according to choices made by the user during the interview process.
Show the result of Date arithmetic in the interview
Display calculated dates in the interview using functions in an OnExitSet.
Some Authoring tools:
Understanding XpressDox Artefacts
XpressDox creates internal structures which can consume a lot of time for large templates.
Concatenating strings
There are times when it is necessary to concatenate the values of data elements, variables and/or hard-coded strings together to form a value which is then stored in a variable. The concat function does this.
Working with strings
This cookbook recipe demonstrates various tricks in working with strings.
Inserting documents with variable names
Use the values of data elements to construct the name of a template to be Included.
Run a template for a number of data sets, and print the merged documents
After data sets have been saved as a result of running templates, it is possible to use those data sets, either individually or in batches, to produce mass mailing documents.
Encrypt a template
A template can be encrypted by providing a password when the template is saved.
Data Sheets
Create a data sheet for each XpressDox template when it is saved.
Look up a fee in a tariff table
The TableLookup command in XpressDox Document Assembly can be used to look calculate values such as tax amounts or fees payable where these values are quoted in a tabular form, such as legislated tariffs.
Select templates using a master template
Selection of multiple templates to be run can be done by the user using the XpressDox explorer, but the template author can also control the selection of templates using a master template with document-selection logic built into it.
Apply a different letter head depending on the user’s choice
Sometimes a firm needs to issue letters on different letterheads, depending on circumstances, and so the user should be allowed to choose which letterhead to us.
Managing contact details on letters
Ensuring correct contact details on a letterhead can be a huge problem in a large enterprise. XpressDox has a number of features which make it possible to overcome this problem. One of these is the Data Source Configuration feature together with the ChooseFromDataSource command.
Define layout in a base template
Sometimes a letterhead needs to dictate not just things like the company’s logo and fairly static items like the directors’ names, but also the position of the addressee information and data elements like ‘Your Reference’ and ‘Our Reference’, for example.
Calculations:
Performing calculations
XpressDox can perform arithmetic calculations on data element values. This is done in an intuitive way by simply typing in the calculation.
Using variables to calculate totals
XpressDox give the template author the ability to perform calculations and other operations on the values of data elements, and to store those values in variables for later use in the template. One example of this is the ability to calculate totals on repeated data elements.
Why do my calculations not work? (Part 1)
Usually performing calculations with XpressDox is straightforward. There are some issues to be born in mind, and this Cookbook recipe explores these.
Why do my calculations not work? (Part 2)
Calculations can give trouble when the data elements being operated on are not of the correct format. The RenderAsNumeric function will address that problem.
Handling calculations and Regional Settings in XpressDox
Calculations with XpressDox need special consideration when working with number formats that are not compliant with US or UK regional settings.
Arithmetic in XpressDox
Doing arithmetic in an XpressDox template in different regions takes some preparation, but there are XpressDox commands that can help the template author with this.
Document logic:
Conditional Numbering of Paragraphs
Some times the numbering of paragraphs is not known at the time a template is authored. This shows how to apply numbering dependent on the data supplied at the time the template is run.
Advanced Conditional Logic
Complex conditions involving tests for more than one condition can be easily coded in XpressDox
Conditional inclusion of paragraphs and clauses
Sometimes there are just too many choices of paragraph or clause to be included or excluded from a document. Using If and Else commands is inappropriate when there are hundreds of combinations. XpressDox has the powerful InsertDocument command to handle just this situation – where the user running the template chooses which clauses should be inserted.
Handling gender
Suppose you have a document which you want to personalise as far as pronouns are concerned. In other words, instead of having “he/she” in many places, you want to have only “he” or “she” depending on the sex of the party concerned. Check how this is done using the ChooseUsingCheckbox command.
Test for Any or All repeated items meeting criteria
It is sometimes necessary to test whether at least one (Any) of a group of repeated items meets a particular set of criteria, and also to test whether All of the group meet those criteria. This article discusses how to construct those tests.
Working with Page Breaks
Using a page break in a template is fairly straightforward, even when the page break is conditional. In other words, when the page break is to be included or excluded on the basis of an «If» command.
Working with Section Breaks
Section breaks are used in Word® to separate different parts of the same document which typically have different attributes. This becomes an issue for the template author when one or more sections are included (or excluded) from the document according to some conditional logic.
Repeating Data:
Working with repeated elements – Part 1
Repeating data elements presents a challenge to the template author, especially in formulating sentences and descriptions where the number of parties or invoice items or other repeating data is unknown at the time of authoring the template. This recipe in the Cookbook demonstrates how XpressDox meets this challenge.
Working with repeated elements – Part 2
A common issue with repeating data is the requirement to refer to the items within the list by their ordinal values.
Document per Repeated Item
Produce a separate document for each repeating item.
Document per Repeated Item – with Filter
The Document per Repeated Item feature can also be filtered so that only those repeated items fulfilling a particular set of criteria will have a document prepared.
Manage the number of occurrences of a repeater
Apply restrictions governing the number of repeaters entered.
Formatting of assembled documents:
Format a date in archaic form
Using standard XpressDox functions and commands, XpressDox renders a date in archaic form, i.e. 2009-09-02 becomes “the 2nd day of October in the Year of Our Lord Two Thousand and Nine”.
Format an Identity Number
The FormatNumber function in XpressDox can help the template author make sure that the template user captures valid numeric data, as well as format the result for readability.
HotDocs (and other) Conversions:
How to Convert HotDocs Templates to XpressDox Templates
Looking for a HotDocs alternative? Want to run your templates on the Web? Join the growing number of firms getting better value for money with XpressDox!
What to Expect of the Conversion from HotDocs
The HotDocs-to-XpressDx converter aims to prepare a set of templates which can be run in XpressDox with minimal modifcation.
Convert templates from other systems to XpressDox format
HotDocs, GhostFill and other templates can easily be converted for use with XpressDox Document Assembly.
Foreign Templates to XpressDox syntax conversion
The syntax of HotDocs®, GhostFill® and other fields can be converted automatically to XpressDox syntax.
Data sources:
Configure a Data Source for a Database
The New Data Source wizard is used to configure a database for use in XpressDox.
Configure a Data Source for a Salesforce Database
XpressDox has a powerful data source configuration tool which makes SalesForce information from various linked tables available to any template.
Using a Stored Procedure as a Data Source
Stored Procs can be configured as data sources in XpressDox.
Configure a Web Service as a Data Source
Get information in XML format from a web service.
Use a SQL SELECT as a data source
Use a SQL SELECT query as a data source.
Configure A Data Source for an Elite Database
There is a lot of information kept in the practice management systems, and XpressDox data sources enable this information to be made available to documents in Word.
How to change data or insert new data into a data source
Data from a data base can be inserted into a template. Perhaps this data has changed since it was last updated in the database, and the template-running-user is the one who knows about this change. It should be permissible for the user to change the data and have the change propagated back into the database.
Make data source information available on all templates
Global information sometimes needs to be made available to all templates. Either all templates in an organisation, or all templates in a specific application or group of applications. XpressDox Document Assembly makes this possible via the Configuration of a data source.
Install a third party data source
Data sources configured by another person can be included in your own configuration by using the New Data Source configuration wizard.
Creating new Data in a Data Source
Templates can be authored which guide the user in creating new records in a data base, for example opening a new account in an accounting system.
Use a SQL Server Data Source to include Customer information on a template
XpressDox can provide data from a large number of source databases. In particular, SQL Server databases can be configured as Data Sources in XpressDox, and this makes it possible to include data form those databases in templates. This Cookbook recipe shows how to configure a SQL Server Customer table, from the Microsoft sample database “AdventureWorks”, as a Data Source, and then goes on to explain how to reference that Data Source in a template.
Download the AdventureWorks database
The SQL Server database referred to in sample templates can be downloaded from this site.
Save the Dataset into a Database Column
Save the dataset into a single column in a database, and retrieve it into the correct level of the XML hierarchy.
The Data Set Data Source
Use XpressDox saved XML data set files as a data source.
Working with LinkToDataSource
Often data bases are designed with information split over a number of tables but this information needs to appear to the end user as if it is in only one table. This can be achieved with data base joins, or else with the LinkToDataSource command.
Run a “mail merge”
Use one template to generate a letter to each of a set of clients whose contact details are saved in a database.
Configuration:
Force saving of merged documents
When the file name of the merged document is provided either in the configuration, or using the «SetSavedDocumentFileName()» command, then XpressDox will save that merged document regardless of whether or not the user checks the Save Merged Document? check box on the data capture interview for that template.
API:
Which API should I use?
XpressDox Document Assembly document automation can be customised by a developer using one of three APIs (Application Programming Interfaces). This article describes the APIs and why any one of them would be chosen above the others.
Should you still be on Version 3, you need to know:
Upgrading to Version 4
Version 4 of XpressDox contains some major changes. This article has advice for the template author on what to expect when upgrading from version 3 or earlier,
Source and Destination formatting in Version 4
Style handling when merging two templates has improved in Version 4, but needs to be understood to be really useful.
