Use Google to find help fast. For example, search on "xpressdox choosefromlist".

How to Integrate an Interview using JavaScript

Step 1. Upload the template solution to the cloud

The first step is to design, author and upload the template ‘solution’ to the cloud. Usually a solution comprises a number of templates and supporting files, as in this case.

Step 2. Copy and paste the integration code from the cloud

There should be a particular template that runs your solution. Locate that template within your cloud account. Then click to the right of the template name, and choose the ‘Include in your Page’ option, as shown below. Need a cloud account? Register a Cloud Account free trial.

javascript integration include in your page

Step 3. Include the code snippets in your page

Follow the instructions to select a user profile and configure your results page URL. Then click ‘Show Me How’ for XpressDox to generate the code snippets for you. There are instructions and comments within the snippets to guide you.

javascript integration include in your page

Step 4. View your page

Install XpressDox Server

This document contains instructions on how to install your XpressDox Server. Before you start, please note:

  • We assume you have the authority and rights to add and configure a website on your network
  • We assume you have experience working with website and database configuration in a Windows environment.

Your XpressDox Server can be opened to the internet to allow remote access, if required.

Hardware Recommendations

Based on our experience we recommend your own hosted server has these, or higher, hardware specifications:

  • Processor: Intel Core i7-4770 Quad Core including Hyper Threading technology
  • RAM: 32 GB DDR3 RAM
  • Hard drives: 2 x 2TB SATA 6 GB/s 7200 rpm (software RAID) Enterprise Class
  • Connection: 1 GBit/s port
  • Bandwidth: 1 GBit/s

Software Requirements

  • Microsoft Windows Server 2012, or higher
  • Microsoft .Net Framework v4.5.2, or higher
  • Internet Information Services (IIS) v7, or higher
  • Microsoft SQL Server [Express] 2012, or higher, if XpressDox WinAuth Server or XpressDox Cloud Server (i.e. not XpressDox API Server) is being installed
  • Optional: Access to your Windows network, only if Windows Active Directory user authentication is required

1. Configure Windows Server

Using Server Manager, configure the roles and features of your Windows Server. In addition to the defaults ensure these values are set:

  • Server Role Web Server Role
  • Web Server (IIS) > Web Server > Security, enable Basic Authentication (WinAuth Only) or Windows Authentication (WinAuth Only)
  • Web Server (IIS) > Web Server > Performance, enable Static and Dynamic Content Compression
  • Features, .NET Framework 4.6 WCF Services -> HTTP Activation

2. Add or Configure Application Pool

Using IIS Manager, add or configure an application pool for your XpressDox Server processes. In particular ensure these values are set:

  • .NET CLR version, set to .NET CLR Version v4.0
  • Managed pipeline mode, set to Integrated
  • Identity, select Custom User Account and supply the details of an existing user, or create a new user if required. (If the templates will be stored on a different server to the software)

The selected or created user must have rights to access the XpressDox Shared Settings and XpressDox-configured Shared folders. (WinAuth Only)

3. Add or Configure Website Application

Using IIS Manager, add or configure a website application to host your XpressDox Server. In particular ensure these values are set:

  • IIS Authentication as required – Anonymous Authentication (All Server Versions) and Forms Authentication (Cloud Server Only) or Basic Authentication (WinAuth Server Only) or Windows Authentication(WinAuth Server Only)
  • Optional: Bindings, add https binding only if you require HTTPS access to your XpressDox Server and have an appropriate SSL certificate.

4. Install XpressDox Server Application Files

Run the installation file called [unzipped directory]\Setup-xpressdox-[winauth OR api]-[Vx.x.x].exe. Ensure these steps are taken:

  • Destination Directory, set to the physical path of your website application configured in IIS
  • When the application installation finishes, the Microsoft Office Access database engine installation launches automatically. Install the database engine. This is required by XpressDox Server to use Microsoft Excel files as data sources.

To install a licence key, create a text file [Installation_Directory]\License\XpressDoxServerLicense.lic and paste the provided key into this file.

5. Add or Configure Application Database

Required for XpressDox WinAuth Server OR XpressDox Cloud Server installations

Using your SQL Server database management tool:

  • Run the script found at [unzipped directory]\XpressDoxData.sql to configure your database

6. Configure XpressDox Server

Open HomeConfiguration\DocumentAssembly.config.xml and edit this setting: (WinAuth Only)

  • SharedSettingsConfigurationFolder, set to the path as configured in XpressDox Desktop Author for the Shared Settings Folder

Open Web.config and ensure your preferences are set for these values:

  • Set the ServerUrl property with your domain base url
  • XpressDoxApplicationDatabase, set to the connection string for your SQL Server application database
  • AdministratorEmail, set the email address of your System Administrator (WinAuth Only)
  • Email server settings, set your email server credentials if you require outbound email support
  • Replace all placeholders indicated by Square Brackets to match your desired configuration. A commented explanation text is included above each property.

7. Run XpressDox Server

Navigate to http[s]://[host name OR ip address]/xpressdox/protected/explorer.aspx to launch your XpressDox Server.

If you are using Windows Active Directory to authenticate users on your XpressDox Server, please note:

  • Users sign in to your XpressDox Server using their Windows domain network username and password
  • Your Windows network file and folder read/write permissions are used by your XpressDox Server to allow or deny a user access to files and folders

For further information on any errors, all detail is logged at [unzipped directory]\logs\XpressDoxApplicationLogging.log


Send support requests to XpressDox Support

Configure a Data Source for a Salesforce Database

XpressDox offers users a simple–to–use Salesforce with Word integration that enables Sales Reps and Managers to populate their documents with Salesforce data automatically. This means that anything from simple documents to complex quotes and contracts can be produced in seconds.

In order to prepare for this integration you need to download and install XpressDox if you haven’t done so already.

You will also need to get a security token so that XpressDox requests for data comply with the Salesforce’s security requirements. Here is more information about the Salesforce security token.

Once you have XpressDox installed, and your user name, password, and security token at hand, you are ready to begin authoring your first template to make Salesforce data available in Word. Follow the tutorial below for step–by–step instructions.

PDF documentHow to use your Salesforce data in Microsoft Word

Install a third party data source

It is possible to export an XpressDox configuration file which contains data source definitions. This exported configuration can then be sent to other interested parties and imported into their own configurations. A typical example is when a data source for a specific data base is created by, say, a system administrator, and this is to be transmitted for installation by someone at a remote branch.
If you have received an exported configuration file with data sources defined in it, and want to import those data source definitions into your own configuration, then here’s how to do it:

    1. Copy the exported configuration file to a known location.
    2. Start the XpressDox configuration utility and browser to the folder which you would like to configure.
    3. In the Data Sources tab of the configuration utility, click the New button in the toolbar (the button with the little green + sign in it)
    4. Select the option “Exit this wizard and …” (see screenshot) and then press the Finish button.

    1. A form will be presented which contains the current folder’s configuration file name, and a list of the data sources in the configuration file, something like this:

  1. Using the Browse button, select the file which you copied in step 1.
  2. A list of data sources in that configuration file will be presented to you – choose the one you want, and choose the option that you would like (typically “Copy the Datasource”) and then press OK.
  3. Pressing OK causes the data source definition to be copied into the configuration you are working with.
  4. Perhaps you will need, or want, to change the name of the data source, in which case do so.
  5. Using the “Use Data Source’s Editor”, make sure the data source definition is correct (e.g. if the data source refers to a data base you may need to modify the connection string).

XpressDox Cloud – iFrame Integration and URL Structure

This page contains technical instructions on how to access and construct the relevant URLs required to integrate the power of XpressDox Document Assembly into your own websites or web applications.


  1. XpressDox Desktop (Version 4 or higher).   XpressDox is a Microsoft® Word Add-In Application for authoring templates. This can be downloaded from:
  2. XpressDox Cloud Account – Go to and click on the “Register” Tab to register an account. – Your Username and Password will be emailed to you upon registration.
  3. Your existing website or web application that you plan to integrate with XpressDox.

Display the XpressDox interview in your site or application

Upload your XpressDox template to the cloud

Templates can be uploaded to your cloud account it two ways:

  1. Using the XpressDox Cloud Manager launched from the XpressDox ribbon in Microsoft® Word.

    (a) Login with your Username and Password and then upload your template to your cloud account.
    (b) You can simply drag templates from your desktop into the XpressDox Cloud Manager.
  2. Using the “Upload File” link on the website to upload your templates.

    (a) Go to to login.
    (b) Certain browsers support drag and drop as well. E.g. Chrome and Firefox.

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

Generate the interview URL

  1. Using the Cloud Manger select your template and click the “Embed Interview in your Website” button.
  2. Using the below dialog, generate the interview URL to be used in your site.
  3. Once the interview is completed you can choose to use the default results page, this will simply list the assembled documents and allow them to be downloaded by the user.
  4. Alternatively you can specify a custom return URL to a page where you can handle the assembled documents and display to the user as you wish. (See following sections for more information)
    (1) This approach is ideal for importing the documents into your business process or into your own document management system.
    (2) It is also required if you do not want the user to be able to download the assembled documents.
  5. Finally, click the “Generate iFrame HTML” button to generate the HTML required to display the interview in your site.
  6. Copy the html and paste it into the html (code) of your page where you want the interview to appear.

Set the color theme of the interview

You can choose from a number of different color themes in order to best match the interview display to your existing website.

  1. Login to
  2. Click the “Settings” menu item.
  3. Then select from the available list of themes.
  4. Click “Set Theme” to save your settings.

URL structure for developing a custom return page

This is the URL that your user will be redirected to after completing the XpressDox interview if you have specified a custom return page URL.

Structure of the return URL

https://Return_URL_as_specified_above?UsageIDs=[USAGEID]|[DOCUMENT_NAME]^[USAGEID]|[DOCUMENT_NAME]&CustomParam=[CUSTOMINFO]&AnohterCustomParam= [MORECUSTOMINFO]

must be https

The parameters explained:

Return_URL_as_specified_above – The URL identifying the page to which your user will be redirected to on completion of the XpressDox interview. E.g.

UsageIDsThis parameter will contain multiple records in the following format depending on the number of document assembled.

USAGEID – The Unique Usage Code used to identify the assembled document.

DOCUMENT_NAME – The display name of the assembled document.

UsageID and Document_Name are separated by the pipe character ‘|’.  In the event that multiple documents are generated, the Usage|DocumentName items will be further separated by the caret character  ‘^’.

Please Note: If a document is configured to be assembled in two different formats, e.g. .docx and .pdf, this does not constitute multiple documents being assembled, it is simply the same document in different formats.  See below for downloading instructions.

CustomParam=[CUSTOMINFO] – You can choose to add custom parameters to the interview URL (generated using the above dialog).  Any custom parameters added, will be returned to your application via the return URL.  These parameters can be used to retain context that may be important to your application.

Please Note: Although HTTPS is the recommended protocol, XpressDox cloud can be integration with HTTP or HTTPS.

Structure of the download URL

If you choose to use a custom return page, you will need to handle the downloading of assembled documents.  To download assembled documents, use the following URL structure.[USAGEID]&FileType=[TYPE_OF_FILE]

The parameters explained:

UsageID – The Unique Usage Code identifying an assembled document as returned in the return URL discussed above.

FileType – The type of file format you want to download for the identified assembly.   Each assembly can generate 3 possible files:

Microsoft  Word Document (docx format) (Set FileType to ‘doc’)

PDF Document (Set FileType to ‘pdf’)

XML Data File (Set FileType to ‘xml’)

Please Note: Not all file types are automatically assembled for each template, these file types need to be configured.

Send initial data to the XpressDox interview

Data can be sent to the XpressDox interview in two ways.  Either way, the data must be in XML format and be base64 encoded for it to be sent and used successfully.

As part of the interview URL

  1. Add an “initialData” parameter to the interview URL and set the value to the base64 encoded XML data.
  2. Only use this method for sending a small amount of data.
  3. Example below:
    XML Data:



    Please Note: If you choose to use this method the parameter must also be URL Encoded before it is sent.

Post the data as part of a HTML form to the interview URL

  1. Create an HTML form containing an “initialData” parameter.
  2. Example below:

    XML Data:

    HTML form:
    <form action="XpressDox Interview URL " method="post">
    <input name="initialData" type="hidden" value="PD94bWwgdmVyc2lvbj0iMS4wIj8%2BCjxSb290RWxlbWVudD48QmFyX051bWJlcl9fYz4xMjM0PC9CYXJfTnVtYmVyX19j" >

Upgrading to Version 4

Version 4 of XpressDox (XDv4) represents a major change from Version 3.

The principle change is that the format of an XpressDox template is no longer Word 2003 XML, but Office Open XML. Office Open XML (or OOXML) is the format in which Microsoft Word 2007 and 2010 save their documents – i.e. documents saved with .docx (or .docm) extension. In addition, there are a number of useful new commands and functions introduced in Version 4.

This article presents just those issues which the template author needs to take into account when upgrading to version 4 of XpressDox. For a full list of all the changes in Version 4, please see Version 4.1.0 Released.

Word 2003 and XpressDox V4

If you are using Word 2003, then before upgrading to XDv4 you will need to install the Microsoft Office Compatibility Pack from the web site

This very useful extension to Word 2003 enables any documents in OOXML format to be opened in Word 2003 and also to saved from Word 2003 (using the “Save as” function). This capability is needed by XpressDox so that it can save its templates in OOXML format.

Word 2007 and XpressDox V4

It is recommended that you make sure your Office 2007 is at SP2 at least (the latest service pack is SP3). This is to cater for issues which occurred in earlier versions of Office 2007 when opening documents created in Office 2010.

Convert Version 3 templates to Version 4 format

This conversion needs to be done because the XDv4 template format is not the same as in Version 3.

The conversion happens fairly painlessly – using the XpressDox explorer, open a folder containing Version 3 templates, and the explorer will suggest that you convert all of the templates in that folder and its sub-folders.

Clicking “Yes” will cause XpressDox to convert the templates to Version 4 format, and will move the older format templates to a sub-folder called Version3Templates.

In addition, XpressDox can be asked to convert all the folders in the Explorer’s Recently Used list – which will probably cover most of the folders that you use which contain old Version 3 templates.

When a template in the “Favourites” list is converted to Version 4 format, there is no automatic conversion of the file name in the configuration where the Favourite is defined.  However, XpressDox will check, when asked to run a “Favourite”, that a new format template exists, and run that if it is there.

XDv4 Template File Extensions

In Version 3 and previous versions, the XpressDox templates were stored with the file extension .xdtpl.  With XDv4, the actual format of the template is Open XML, but the templates are stored with extension .xdtpx or .xdtpm.  This is purely to distinguish them (in the XpressDox and Windows explorers) from other Open XML documents which will probably be stored with extension .docx (and .docm).

During the conversion process referred to above, if XpressDox is converting an old format template which contains VBA macros, it will save that template as a “macro enabled document”  (which is what Word 2007 and 2010 require), and use the extension .xdtpm.

This change in extension might cause problems where a template author has specified the .xdtpl extension in IncludeTemplate or BaseTemplate commands.  If this has happened, then the templates containing those commands will need to be changed.  The best course is to specify only a template file name without extension, optionally qualified with a helper folder alias.  This permits the actual template file to be saved with either .xdtpx or .xdtpm extension, and XpressDox will resolve that at the time it executes the IncludeTemplate or BaseTemplate.

Fillpoint Delimiters

Prior to XDv4, the default fillpoint delimiters were << and >>.  These are now called XpressDox Classic delimiters.  With Version 4, the default fillpoint delimiters for all new installations of XpressDox will be the “chevrons”, i.e. « and ».  This will not affect existing installations of XpressDox.  As before, XpressDox will in any case recognise on a per-assembly basis which delimiters are being used, so that even where a new installation at a site will default to chevrons as the delimiters for authoring, any templates authored (on other workstations) with the XpressDox Classic delimiters will continue to function correctly.


The XpressDox relevance “engine” has been upgraded.  XpressDox will now recognise data elements in various commands and contexts where this was not the case in earlier versions.  This will affect the layout of some interviews, because XpressDox has always used the first occurrence of a data element in a template to determine its position in the interview.  Because data elements are now recognised in more contexts than before, this might cause the position of some data elements to move higher up in the interview.


Data elements referenced in Tab commands will now be used to determine relative position of the data elements in the interview.  As explained above, this means that if the first occurrence of a data element is in a Tab command, this will determine its relative position in the interview.  This might cause data elements to change their position in the interview compared to interviews created in Version 3.  A workaround for this might be to move the Tab commands to the end of the template or assembly.

If, When, Setv:

Prior to Version 4, these commands/functions (and some other contexts) were not scanned for the occurrence of data elements.  With Version 4, data element names inside these fillpoints are recognised and used to determine relative positioning of the data element in the interview.  This might cause data elements to appear earlier in an interview than in previous versions, and might cause a control for a data element to appear when it did not appear at all in an interview constructed in a previous version.  CaptureDataElement, CaptureLater and ExcludeFromIV can be used either to change the position on the interview of a control or to exclude it completely from the interview.

Choose… commands:

In pre-Version 4 XpressDox, commands such as ChooseFromList, ChooseUsingCheckbox, and others (those in the Data Capture category in the Command Editor) would cause the relevant control to appear in the interview, regardless of whether or not the data element being chosen was used elsewhere in the template.  With XDv4 the control will only appear in the interview if the data element being captured is used elsewhere in the assembly.  The command CaptureAllDataElements can be used to cause those Choose controls to appear even where the data element is not used in the current assembly.

Note that the SetInterviewDataOnly command will issue a CaptureAllDataElements command implicitly.

The new relevance algorithms result in a more consistent treatment of placement of controls on the interview. However, there will be some instances when controls are in different places on the version 4 interview compared to the interview created with earlier versions. Don’t worry if this happens, because judicious use of the CaptureDataElement and CaptureLater commands will place the controls exactly where needed on the interview.


«InterviewIsWizard(yes)» (see here) is now implemented in the desktop version of XpressDox.  If there are Tabs defined, then those tabs will now appear in the treeview, where repeated items go.

A pair of navigation buttons will appear inside the interview form to help the user navigate through the nodes of the treeview.

Source Formatting

This feature in the BaseTemplate, IncludeTemplate and InsertTemplate has been improved.  No longer will this cause new styles to be inserted into the destination template.  Instead, the style in the source template is inserted with the same name into the destination, and replaces a same-named style in the destination.

This might have unexpected results because if the style “StyleA” appears in source AND destination, then any and all paragraphs in the destination which are formatted according to StyleA will, after the merge, be formatted with the StyleA from the source template.

Please see Source and Destination formatting in Version 4 for more comprehensive coverage of this subject.

Supervisor Functions

The Supervisor, Template Author and Template Runner (new feature) functions are now controlled via special XpressDox licence keys. The “Supervisor Toolkit” program (i.e. the one which was used to “sign” the supervisor’s home configuration) is no longer needed. The Template Author features are also controlled by the licence which is registered for that user, and no longer requires the user to empower themselves as a template author by specifying a password in their home configuration. If you have been using the Supervisor features, please contact to get more information on these features using Version 4.

The SaveAsText Command

Sometimes you might want the result of XpressDox merging data and template to be not a Word document but another document, for example a CSV file, or even another XML document, or programming code (yes, XpressDox can be used to generate programming code, or HTML, anything really).  In all those examples the type of data is actually text and not really a Word document.

«SaveAsText(Yes)» will cause XpressDox to save the text version of the merged document.

It would be as well to provide the extension that should be used by using the SetSavedDocumentFileName command, for example «SetSavedDocumentFileName(Table.csv)»

Note that this feature is available only in Version 4 and later of XpressDox.

The Round Function

The Round function performs rounding.  For example:


will round the value of the Amount data element name to the nearest whole number.

The Round function can take on extra optional parameter being the number of decimal places to which the number should be rounded (the default is 0).  <<Round(number,3)>> will round the value 1.2345 to 1.235.

Note that extra optional parameter is available only in Version 4 and later of XpressDox.

The RepeatWhile Command

Repeating information which is not in the form of repeating data in XML (i.e. multiple same-named XML elements) can be handled using the RepeatWhile command.

An example of the kind of repeating data that would need a RepeatWhile would be a data element that contains a comma-delimited list of directors of a company.  If the requirement is to list the directors each on their own line, then the following code would achieve this:

«SetVr(‘List’,concat(Directors,‘,’))»«Comment(make sure there’s a trailing comma otherwise the last substring-before doesn’t work)»

«RepeatWhile(GetV(‘List’) != ‘’)»

«substring-before(GetV(‘List’),‘,’)»«Comment(this inserts the name at the front of the list into the merged document)»

«SetVr(‘List’,substring-after(GetV(‘List’),‘,’))»«Comment(removes the name at the front of the list)»


Note that this feature is available only in Version 4 and later of XpressDox.