Skip to main content

Legal

Tax & Accounting

Trade & Supply

Risk & Fraud

News & Media

Books

Developers

External dictionary

Using a common dictionary across multiple templates

Templates in
Contract Express Author
 are self-contained Microsoft Word documents that contain both the mark-up and the dictionary. This means all information about the template is stored in the template (and not, say, in some shared resource such as a database or external dictionary file) and all relevant information is visible in Author (including variable properties).
However, sometimes it is useful, if templates are to interact, for shared definitions to be available to multiple templates. This is the concept we call "External Dictionaries". The external dictionary can either be
File based
 or
Server based
. With either method, one template can reference multiple external dictionaries.

File based external dictionary

File based
 references are to
file locations
, either local or on a shared server, and not necessarily to uploaded templates in the Contract Express template repository. When a template is opened, Author looks for these external dictionaries at the specified locations and tries to open each in turn. It then copies out the variables, warnings, and lookup tables from the external dictionary and stores a
local copy
 in the dictionary of this template. The local copy is marked as external. If an external dictionary cannot be reached then Author carries on using the current locally cached version. All dictionary objects are visible through the various dictionary object editors but external ones are by default read-only. The
local dictionary
, with the currently cached external objects, is used when the template is uploaded.
When a template is opened, Author will attempt to
refresh file based external dictionaries,
 looking for it in its saved location. If you make changes to the external dictionary template and save the file, all other templates that are open in Word and use this external dictionary will
automatically
 update with the new external dictionary version.
To use
File based
 references, click on the
Options
 button in the Contract Express tab in Word. Tick the box ‘
Use file based external dictionary
’.

Server based external dictionary

For the
Server based
 external dictionary, the references point to uploaded templates in the Contract Express template repository. Contract Express copies the variables, warnings, and lookup tables from the external dictionary and stores a local copy in the dictionary of this template. The
local copy
 is marked as external. If an external dictionary cannot be reached then Author carries on using the current locally cached version. All dictionary objects are visible through the Dictionary Editor but external ones are by default read-only. The
local dictionary
, with the currently cached external objects, is used when the template is uploaded.
When a template is opened, Author will attempt to
refresh server based external dictionaries
 and prompt you to authenticate if there is no saved authentication token. If you update the external dictionary template and upload a new version to the server from Word, all other templates that are open in Word and use this external dictionary will
automatically
 update with the new external dictionary version.
If you do not want to refresh server based dictionaries automatically, you can opt out of this by selecting '
Do not refresh server based external dictionary automatically
' in
Options
.
To check if the refresh has been successful, click on the
External Dictionary
 button in the
Contract Express tab
 in Word.
To manage the external dictionaries connected to a template click on the
External Dictionary
 button. The list view shows all of the external dictionaries that are currently attached to this template. The columns show information relating to the last upload of the template to the server and last refresh within Author:
  • Reference: the template name of the attached dictionary preceded by a red, blue or green icon
    • Red warning: the last attempt to refresh from this dictionary failed
    • Blue information: a refresh is required. This can occur if a new version of the template has been uploaded to the server after the last refresh
    • Green tick: refresh was successful
  • Attach Type: the type of attachment of the dictionary
    • With pages: the questionnaire pages and groups are attached. This includes the page and group details, their order and variable allocation as well as the variable definitions
    • Without pages: the questionnaire pages and groups are not attached, only the variable definitions are imported
  • Last Refresh: the date (or time if today) of the last successful update
  • Last Upload: the date (or time if today) of the last successful upload of the template to the server
  • Location: the URL of the Contract Express web application where the external dictionary resides
The order reflects the order in which the external dictionaries will be refreshed. If several dictionaries define a variable of the same name then the definition used in this template is the one from the external dictionary earlier in the list.
There are actually three possible states for objects that can come from external dictionaries:
  • pure local
    , that is they are only defined locally
  • pure external
    , that is they are managed externally
  • locally overridden external
    , that is the object came from an external dictionary but has been locally modified
This last option is useful if you need to change a variable but cannot wait for the external dictionary to be updated (say by someone else), or you may just want to use a different prompt for a variable which originated in an external dictionary. If you are viewing a variable that originated from an external dictionary, then the General tab in the Dictionary Editor will contain an option called
Use external definition from
Name of Dictionary
.
 If this is checked then the variable is a pure external variable and no attributes can be changed. If it is unchecked then the object is a locally overridden external and its properties can be changed.

Attach an external dictionary

To attach a new dictionary click the External Dictionary button on the Contract Express tab in Word; the External Dictionary dialog will launch. If using the
Server based
 external dictionary; click the
Attach
 button to select templates which are located at the default server (the currently selected server in Options -> Server). You may select multiple files. The dictionary information from the template(s) will be copied into your template, and marked as external. If it is your first time interacting with the Contract Express web application via Author within a Word session, you will be asked to enter your credentials for the default server before being able to view the available templates.
If using the
File based
 external dictionary; click the
Attach
 button and browse to a file location where the dictionary is located. You may select multiple files. These DOCX files are opened and if they contain a Contract Express template then the dictionary information from that template will be copied into your template, and marked as external.
Note that if an external variable of the same name already exists then a new variable is
not
 created. Also if a pure local variable of that name already exists then it becomes a locally overridden external variable and none of its properties are updated.
Note that the Attach button is a "split" button with 2 options:
Attach without questionnaire pages and groups
 (the default option) and
Attach with questionnaire pages and groups
. To access the non-default option, you must click on the dropdown arrow beside the button:
The
Attach with questionnaire pages and groups
 option does the same as above but also copies the questionnaire pages from the external dictionaries as they are attached.
If the Attach Type of the external dictionary is “with pages” then the questionnaire pages and groups will be updated when refreshing. If the Attach Type of the external dictionary is “without pages” then the questionnaire pages and groups will not be updated when refreshed.

Detach an external dictionary

The
Detach
 button removes the external dictionaries selected in the list view. This will remove the definitions for pure external objects that came from those external dictionaries, even if they are used in your template. Any locally overridden external objects from those dictionaries will become pure local objects.
Note that the Detach button is a "split" button with 2 options:
Detach removing local definitions
 (the default option) and
Detach leaving local definitions
. To access the non-default option, you must click on the dropdown arrow beside the button:
The
Detach leaving local definitions
 option will remove the dictionaries but leave behind all their objects as pure local objects. This is useful, for example, if you want to create an external dictionary from multiple similar templates (ie open a blank document and Attach and then Detach (choosing "leaving local definitions") each template in turn. The result will be a blank template containing all dictionary objects from each template that can then be used as an external dictionary).

Refreshing external dictionaries

The
Refresh
 button refreshes the local copies of the objects from the external dictionaries selected in the list view. Only pure external objects are updated; locally overridden objects are not updated.
If a new object has been introduced to the external dictionary then the same rules as during attach are applied:
- if an external variable already exists then a new variable is
not
 created
- a pure local variable existing in the external dictionary will become a locally overridden external variable
If an object has been deleted then the same rules as for the default Detach are applied:
- pure external objects are removed
- locally overridden objects become pure local
The
Refresh overwriting local definitions
 option converts any locally overridden objects that originally came from the external dictionary into pure externals and updates their properties.
Refreshing external dictionaries via the Contract Express web application
With Contract Express 8.9 or higher, it is also possible to refresh external dictionaries via the Contract Express web application.
The
Related templates
 section on the Template Details page contains the link
View external dictionaries
. It allows you to check if the current template has any external dictionaries attached or if the current template is being used by any other templates as an external dictionary.
On the page that lists
Templates that use the current template as external dictionary
, it is possible to select one or more templates and refresh their external dictionaries with the most recent version from the current template. The dictionaries will be refreshed on the server only.

Typical process when using external dictionaries with a Template Hierarchy

There are generally 2 scenarios when working with external dictionaries
Scenario 1: The "Top Template" scenario:
In this scenario, T1 is always the template that is launched, it either attaches or includes T2 and T3 but they are never run standalone. Even if the answers need to be amended, it will be through the launch of the "top template":
T1
/ \
T2 T3
It is common for T1 to also be used as the dictionary and to have the full questionnaire order defined. T2 and T3 will attach T1 as their external dictionary and no local variables will be defined in these sub-templates. This has the advantage of the questionnaire order needing to be defined only once (in the T1 template). Any changes to questionnaire order and variable definitions (apart from computation definitions) will only need to be made in the top-template since its dictionary and questionnaire order will take precedence over the others in the hierarchy.
When working in this way:
  • Automate the top template (ie T1) and add a questionnaire order and ensure that it has been saved
  • Open or create the first of the sub-templates (ie T2) and choose
    Attach without questionnaire...
     to the top template from the External Dictionary menu item.
  • If the sub-template document already has variables that are defined in the dictionary, then use the
    Refresh, overwriting local definitions
     button to ensure that all variable definitions originate from the dictionary document.
  • If a new variable needs to be created for the sub-template that is not yet in the top template, then create this variable in the dictionary of the top template first. To refresh the sub-template to ensure this new variable is part of the sub-template dictionary, choose
    Refresh, overwriting local definitions
     from the
    External Dictionary
     dialog if the sub-template is open. Otherwise, the dictionary amendments will automatically be copied when the sub-template document is next opened, providing the dictionary template is reachable.
Scenario 2: Individual templates sharing common variables
In this scenario templates are launched separately. They are individual documents that share the same variables but are not thought of as a hierarchy. They do not reference each other include or attach statements:
T1 }
T2 } ED
T3 }
In order to maintain variable definition consistency and maximize reuse, an external dictionary is used (ED in the diagram above), but this is often a separate blank template (i.e. it has no Word content). It may or may not house a common questionnaire order depending on how many variables are used in the templates (those with a smaller number might benefit a more compact questionnaire over less pages than those with many variables in).
When working in this way:
  • Create the separate dictionary document first and ensure that it has been saved
  • Open or create a template document (T1). If it will be using the questionnaire from the top template then use
    Attach and append questionnaire...
     to the dictionary document, otherwise simply
    Attach without questionnaire...
     to the dictionary document.
  • If the template document already has variables that are defined in the dictionary, then use the
    Refresh, overwriting local definitions
     button to ensure that all variable definitions originate from the dictionary document.
  • If a new variable needs to be created for the template that is not yet in the external dictionary, then create this variable in the dictionary first. To refresh the template to ensure this new variable is part of the template dictionary, choose
    Refresh, overwriting local definitions
     from the
    External Dictionary
     dialog if the template is open. Otherwise, the dictionary amendments will automatically be copied when the sub-template document is next opened, providing the dictionary document is reachable.

See Also

Field types
Template

This article applies to:

  • Product: Contract Express

Related content