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

Interview Integration – JavaScript and iFrame

Over and above the API (Server to Server Communication), XpressDox also offers Interivew Integration. (3rd Party Server to Browser to XpressDox Server Communication).

Integration Information

The XpressDox Server provides code snippets to make integration of interviews really easy for you. To access these snippets:

  • Sign in to your XpressDox Cloud or Server account
  • Click to view any interview
  • Click the Include Interview in your Page link on the left hand side of the page
  • Set your preferences and click the Show Me How button
  • JavaScript and iFrame code snippets (including explanatory comments) you need to integrate the template interview with your page will be generated automatically for you

We recommend you use the JavaScript integration so that you have more control over the interview in your page. We supply the following JavaScript methods once the interview is loaded:

  • xdInterview.mask(message);This adds the loading overlay to the interview with the custom message text
  • xdInterview.unmask();This removes the loading overlay
  • xdInterview.getInterviewData();This method returns the interview data in xml format
  • xdInterview.getInterviewDataBase64();This method returns the interview data in base64 format
  • xdInterview.navigatetoURL(navigateURL);This method redirects the page, without the “leaving page message”, to the provided URL

We supply the following JavaScript event/hooks once the interview is loaded:

  • function xdox_OnCustomClick() { }XpressDox will call this method when the custom button is clicked. Used with this command: SetWebCustomButton
  • function xdox_OnTabShown(totalNumberOfTabs, currentTabIndex) { }XpressDox will call this method when a tab is clicked. Please note currentTabIndex is 1 based.
  • function xdox_OnAssembleClick() { }XpressDox will call this method when the Assemble button is clicked. If your implementation returns false, the XpressDox code will no longer assemble the document and redirect to another page.

An example of these methods being implemented is as follows: function xdox_OnCustomClick() {console.log("The user clicked the custom web button"); }

How to replace a server license

From time to time, you will find your server license needs replacing. The license is set to expire after a given amount of time and a new one will be supplied to you by a representative at XpressDox. Please follow these steps to apply the new license:

  1. Create a new text file at [Installation_Directory]\License\XpressDoxServerLicense.lic if one does not already exist.
  2. Open this file.
  3. Paste the new license key into this file.
  4. Remove any other files that may be in the [Installation_Directory]\License folder. Only XpressDoxServerLicense.lic should exist in this folder.
  5. Restart the application pool in IIS.

The SetWebButtonText command

Any template run on the web, will include a button on which the user can click to finish off the interview and begin the merge process to generate the document. By default the text on this button is ‘Assemble’. The <<SetWebButtonText()>> command will allow the template author to change the text to something which is perhaps more relevant in the context of your web application.


The SetWebReturnURL command


After an XpressDox template has been run from within your own web application or website, the «SetWebReturnURL» command can be used to specify a result page i.e. where the browser should point now that the document has been assembled. The return URL can be written into the application via the interview URL generated by XpressDox Cloud, but the more secure way of doing it is to include the command inside the template itself. This return page can be anything from thanking the user for completing the interview and informing them of the next step in the process, or a page allowing the user to download the assembled documents. Your application is completely in control at this point.

The details of the assembly process (details of the template run and download links for the assemble documents and associated data file) will be posted (HTTP POST) in XML format via an HTML form to the specified URL on completion of the interview. The name of the parameter containing the xml data will be set to xdResultData.

An example would be:

For more information about integrating an interview into your web page, please see the documentation built into XpressDox Cloud. To access the integration information, login to XpressDox Cloud, click to view any interview and then click the “Include Interview in your Page” link on the left had side of the page (link also available in the dropdown menu on the explorer page). Answer the very simple form and hit the “Show Me How” button and the code you need, along with an explanation, will be generated for you.

The SendWebEmail Command

Upon the completion of a document generated via the server, an automated email can be sent using the <<SendWebEmail>> command. Examples include the delivery of the completed documents to a contact at the firm, or an email notification to a client informing them of the next step in their legal proceedings now that this document has been completed. This means that the template, authored in Word, is not restricted to only one <<SendWebEmail>> command.

An example of the <<SendWebEmail>> command.


Note that this command consists of several parameters, each separated by a comma.

The first 3 parameters refer to the email addresses to which the email should be sent. The first parameter is the address that will appear in the To field in the email, the second is what will appear in the CC field, and the third is what will appear in the BCC field. Email addresses may be hard coded, in which case they would need to be in ‘’, or can be data elements from the template. Data elements do not require ‘’. Multiple addresses may be used, separated with semi-colons.

The 4th parameter refers to the email address from which this email will be sent. Although the email is automatically generated by the XpressDox web server, it will appear to have been sent from the address in this parameter.

The following 2 parameters passed through this command refer to the email itself; the subject and the body. It is useful to build the subject from data elements within the template to make the email more relevant when it arrives in the recipient’s inbox. This can be achieved using the <<concat>> command.
Example <<SetV('Subject',concat(‘Will for ‘,Full_Name))>> In this example, the value of Subject, which has been set as a variable, will read GetV(‘Subject’). Note that the variable name should appear in ‘’. When the email arrives, instead of the subject being something generic like ‘Will’, it will include the value of Full_Name from the template; ‘Will for Anthony Moor’, making it easier to identify. Note that ‘Will for ‘ is in ‘’ since it is hard coded text; however since Full_Name is a data element from the template, no ‘’ are required.

Making use of a separate html file provides the opportunity to customise the body of the email. Should no file be specified here, the default wording will be used. The <<SendWebEmail>> command refers only to the name of that html file. Text, as well data elements from the template, may be used in the html file to construct the body of the email, but instead of the data elements appearing in the usual << >> delimiters, they need to be in [ ].

The last 3 parameters in the command refer to attachments to be sent accompanying this email; ie. the Word document, the pdf document, and the xml data set respectively. Files which do need be delivered with this email should have the value True; whereas files which do not need to be delivered should have the value False.

Note that the parameters in the command will always be in the following order: To, CC, BCC, From, Subject, Body of file, Word document, pdf document, xml dataset. Hence, should any of the parameters not require values, for example ‘bcc’, they should not be eliminated from the command altogether, but an empty set of ‘’ should appear in the command.

This example means that To contains the value of a data element from the template, there is no bcc value, and the xml dataset file will not be attached to this email.

The Ordinal Command

Ordinal is used within a ForEach to output the ordinal value (that is, ‘first’, ‘second’, etc.) of the position in the list of the current item:

The <<Ordinal(only ,first ,second ,third ,fourth ,fifth ,sixth ,subsequent )>>party is <<firstnames surname>>.
<<End(ForEach party)>>

This would result in something like this:

The first party is Fred Basset.
The second party is Harry Smith.
The third party is Ivan Bosman.
The fourth party is Maximilian Jones.
The fifth party is Johan Smit.
The sixth party is William Wilberforce.
The subsequent party is Mortimer Rodent.
The subsequent party is Petrus du Toit.

Notice how when there are more repeated items than the arguments to the Ordinal command cater for (in the above there are 7 arguments but 8 repeated items), then the last argument is used for the excess items.

In the case of only one party in the list, this would read:

The only party is Fred Basset.

If the Ordinal command above were coded as

<<Ordinal(,first ,second ,third ,fourth ,fifth ,sixth ,subsequent )>>

In other words, the first parameter to the command is empty, then in the case of only one party in the list, it would then read:

The party is Fred Basset.

To make sure the seventh and eighth parties are correctly numbered, the Ordinal command could be coded as <<Ordinal(only ,first ,second ,third ,fourth ,fifth ,sixth ,seventh ,eighth ,ninth ,tenth ,subsequent )>>

The CaptureAsLongText Command

CaptureAsLongText and InsertFormattedText. The data capture interview will provide a multi-line control into which the data for the data element can be captured: <<CaptureAsLongText(PropertyDescription)>>

If this long text is included in the document via a simple fillpoint (in the above example: <<PropertyDescription>>), then any line breaks which the user may have typed, say by pressing ‘Enter’ in the data capture control, will be ignored.

In the above example the parameter ‘6’ requests that the data capture control on the form be approximately 6 lines long.

If it is required that the line breaks or other formatting such as bold, underline or italic in the captured data be included in the document, then the command InsertFormattedText must be used:

The above example will permit the user to type the ‘Address’ in as many lines as necessary, and include the ‘Address’ in the document with the lines separated by line breaks.

Different parts of the ‘long text’ can be formatted in the long text control (by the user) as bold, underlined or italic by using the Word shortcut keys for this formatting, namely <Ctrl B>, <Ctrl U> and <Ctrl I>, respectively.


If required, the command can be issued without the control becoming visible on the interview unless the value of the data element is required elsewhere in the template.  This is done as follows:


More about the interview can be found in the Relevance article.

Note that when using the InsertFormattedText command, it is not necessary to use a CaptureAsLongText command, unless the number of lines in the data capture control is required to be different to the default, in which case the CaptureAsLongText command must appear in the template before the InsertFormattedText command.

Rich and Classic Options

With Version 7.1.1 the Rich option was added. The Rich option will cause a “Rich Text Editor” to be used as the data-capture control on the interview.


This will cause the data in the Address data element to be kept as HTML, which in turn will cause the InsertFormattedText function to render the HTML correctly into the assembled document.

«CaptureAsLongText(Address,3,Always)» is the same as «CaptureAsLongText(Address,3,Always,Classic)»

InsertFormattedText can be used to render HTML which has been entered external to XpressDox. For example, HTML in a column in a database row.

The CaptureDataElement and CaptureDataElements Commands

The commands in XpressDox which control the format of the interview do typically not appear on the interview unless they are required in the template being run.  This mechanism allows, amongst others, the specification of all interview-layout commands in one template which is then included (with IncludeTemplate or IncludeCodeTemplate) by the templates requiring that layout; at the same time, only the data elements required for the creation of the merged document from the including template will be presented in the interview.

Forcing Capture

However, it may be that one or more data elements are required to be captured.  The CaptureDataElement command will achieve this.

For example:



Controlling Sequence

The sequence of controls on an interview is determined by the first occurrence of the data element in the template.  Thus:




will cause the radio button list for data element BuyerGender to appear in the interview before that for SellerGender.


The CaptureDataElements variation of this command will permit the specification of more than one data element to be captured:


The ChooseFromList Command

ChooseFromList. This is a command which will present the user (via the interview) with a list of options from which to choose the value of a data element rather than a free-format text field. For example, the following will help the user capture one of South Africa’s provinces:

I live in <<ChooseFromList(province,Eastern Cape,Free State,Gauteng,KwaZulu-Natal,Limpopo,Mpumalanga,Northern Cape,North-West,Western Cape)>><<ToUpper(province)>>

Note that it is important to include a fillpoint indicating where the result of the data capture must be inserted – hence the <<ToUpper(province)>> in the example. If this is omitted then the data element will be captured but will not appear in the document.