0% found this document useful (0 votes)

1K views214 pages

Contract Express v9 - API Manual

Uploaded by

Yuri Avanci Laguardia

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views214 pages

Contract Express v9 - API Manual

Uploaded by

Yuri Avanci Laguardia

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

1 Contract Express® API Manual

Version 9 | 17 November 2022

2 Contract Express® API Manual

Disclaimer

This manual as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms
of such a license. The content of this document is furnished for informational use only, is subject to change without notice and does not
represent a commitment on the part of Thomson Reuters. Thomson Reuters assumes no responsibility or liability for any errors or
inaccuracies that may appear in this manual.

Copyright © 2022 Thomson Reuters.

All rights reserved. Except as permitted by such license, this manual may not be copied, photocopied, reproduced, translated or converted
to any electronic or machine-readable form in whole or in part without the prior written approval of Thomson Reuters.

Trademarks

Contract Express, Contract Express for SharePoint, Contract Express for Salesforce, Contract Express Author, Contract Express Drafter,
Contract Express DealBuilder, Contract Express Administrator, ContractExpress.com, Contract Express Cloud, Contract Express for
SharePoint Cloud, Contract Express QuickStart, and the Contract Express system are trademarks of Thomson Reuters. All other brand or
product names are trademarks or registered trademarks of their respective owners.

For technical support contact: [email protected]

3 Contract Express® API Manual

Contents
1. Introduction ........................................................................................................................................................6
2. Getting started with the API ...............................................................................................................................7
2.1 Suggested Approach ...................................................................................................................................7
2.2 Postman Overview .....................................................................................................................................7
2.3 Before using Postman – Create an API client in Contract Express .............................................................7
2.4 Contract Express API Quickstart .................................................................................................................9
2.5 Contract Express Integration Sample/Sample App ....................................................................................9
2.6 Other considerations for accessing the Questionnaire ..............................................................................9
3. Security ............................................................................................................................................................ 10
3.1 Authentication & Authorization .............................................................................................................. 10
3.1.1 Authorization Code grant type for obtaining an Access Token ............................................................... 10
3.1.2 Implicit grant type for obtaining an access token ................................................................................... 13
3.1.3 Validating the identity token ................................................................................................................... 15
3.1.4 Refresh tokens ......................................................................................................................................... 15
3.1.5 Context .................................................................................................................................................... 15
4. API Reference .................................................................................................................................................. 17
4.1 Requests .................................................................................................................................................. 18
4.2 Entities ................................................................................................................................................... 112
5. Embedding the Questionnaire ...................................................................................................................... 155
5.1 Launching a Questionnaire .................................................................................................................... 155
5.1.1 URL Name=Value Parameters ............................................................................................................... 155
5.1.2 Target Window ...................................................................................................................................... 157
5.1.3 Target <IFRAME> ................................................................................................................................... 157
5.2 Designing a Custom Questionnaire Layout ........................................................................................... 161
5.2.1 Nelson Layout ........................................................................................................................................ 163
5.2.2 Building a Skeleton ................................................................................................................................ 163
5.2.3 Building the Alerts ................................................................................................................................. 166
5.2.4 Building the Questionnaire.................................................................................................................... 166
5.2.5 Building a Repetition Grid ..................................................................................................................... 170
4 Contract Express® API Manual

5.2.6 Adjusting the Preview Document .......................................................................................................... 174

5.3 Styling a Custom Questionnaire Layout ................................................................................................ 175
5.3.1 Style Properties ..................................................................................................................................... 175
5.3.2 Convention for ClassNames................................................................................................................... 179
5.3.3 Icomoon Font ........................................................................................................................................ 187
5.4 JavaScript Library ................................................................................................................................... 188
5.4.1 General Functions.................................................................................................................................. 188
5.4.2 Alert Functions ...................................................................................................................................... 194
5.4.3 Questionnaire Functions ....................................................................................................................... 195
5.4.4 Page Functions....................................................................................................................................... 196
5.4.5 Group Functions .................................................................................................................................... 198
5.4.6 Repetition Grid Functions...................................................................................................................... 199
5.4.7 Repetition Group Functions .................................................................................................................. 200
5.4.8 Variable Functions ................................................................................................................................. 202
5.4.9 Preview Functions ................................................................................................................................. 206
5.4.10 HTML Identifier Functions ..................................................................................................................... 210

17 November 2022
5 Contract Express® API Manual

Revision Notes
Revision Date Comments
9.0 17 November 2022 Irrelevant content removed, version number changed, and formatting updated.
8.10.0 01 March 2022 Version number changed and formatting updated.
8.9 01 Sept 2021 Version number changed and Postman/Quickstart details updated.
8.8.0 01 February 2021 Version number changed.
8.7.0 01 July 2020 Version number changed.
8.6.0 11 March 2020 Version number changed.
8.5.0 12 September 2019 Version number changed and formatting amended.
8.1.1 4 June 2019 Formatting corrected.
8.1.0 25 April 2019 Version number changed.
8.0.0 5 February 2019 Postman example updated.
7.3.2 4 June 2018 Formatting corrected.
7.3.1 25 May 2018 Irrelevant content removed.
7.3.0 15 January 2018 Postman section updated and minor changes made to correct typing mistakes.
7.2.0 02 August 2017 Revised Section 2.
7.1.0 02 February 2017 Updated Authentication and Getting Started with the API using Postman section to
cover more of the available flows for obtaining an access token.
7.0.0 05 September 2016 Updated Authentication and Getting Started with API using Postman
(authorization code flow).
6.0.0 20 May 2016 Updated Authentication and Getting Started with API using Postman.
6.0.0 30 November 2015 Added document version API calls.
5.4.0 24 April 2015 Added Getting Started with API using Postman.
5.4.0 20 April 2015 Updated for 5.4 release.
5.2.4 9 January 2015 Correct minor typographical errors.
5.2.3 5 January 2015 Corrected message details in 5.1.3.
5.2.2 14 May 2014 Added document upload.
5.2.1 30 April 2014 Published.
5.2.0 21 April 2014 First draft.
6 Contract Express® API Manual

1. Introduction
This document describes the Contract Express Application Programming Interface (API) and is intended to help
programmers to develop client applications that can make use of the resources managed by an instance of
Contract Express. The main resource of business interest is likely to be a Contract, expressed as a set of
Documents generated from some Templates. What follows is a description of Templates, Contracts and
Documents, and how a client application can manipulate them via the Contract Express services.

The API is designed in a RESTful style. Central to this approach is the use of a "uniform interface" based on four
guiding principles:

1. Identification of resources. For example, using URIs. The resources themselves are conceptually
separate from the representation used to return them to the client. Resources are usually collections of
items of the same type, and there is a way to address both the collection and individual items in that
collection.

2. Manipulation of a resource. The representation of a resource returned to the client is enough for it to
modify or delete the resource.

3. Self-descriptive responses. Each request or response should include enough information to describe
how to process the message. For example, identifying the content-type formatter required to parse the
message.

4. Hypermedia as the engine of application state. Clients make state transitions through actions that are
dynamically identified within a response (e.g., links). Except for simple fixed entry points to the
application, a client should not assume that any particular action is available for any resource beyond
those described in representations previously received from the server.

There are four main sections to this manual:

• The first uses Postman to show how to get started with the API.
• The second describes how to access the API when it has been secured using one of several supported
mechanisms.
• The third is the API Reference section, detailing the requests that can be made to the API.
• Finally, we look at how to incorporate the questionnaire into the user interface of a host system and
customize it so that it adopts the "look and feel" of the host.

17 November 2022
Getting started with the API 7

2. Getting started with the API

To make calls to the Contract Express API, you must have a Contract Express client and be authorized by the
Contract Express Identity Server.

For testing purposes, we suggest that an API client is created through the Contract Express UI, as outlined in the
Before using Postman section. For production purposes, you may use this approach; alternatively, if you have an
on-premises instance of Contract Express, you may create a client within the Contract Express backend
configuration as outlined in the Security section. Both approaches are equally valid, and the resultant client
behaves in the same way. Authorization is achieved using this client with one of the OpenID Connect or OAuth2
supported flows; these are also outlined in this section.

On successful authorization, the Contract Express Identity Server issues an access token; this is then used to
make API calls for the lifetime of the token; after this a new one must be acquired. A new token may be
acquired either by going through the authorization process again or by using a valid refresh token. We start with
our suggested approach, continue with details of how to use Postman to test the API, and finish with a brief
discussion of our sample application and other considerations for accessing the questionnaire.

2.1 Suggested Approach

We suggest that anybody that is new to the CE API starts with Postman, using the supplied Contract Express API
Quickstart exercise. The Quickstart covers the most common Contract Express API calls and is fully documented,
with real examples.

If you require behaviour not covered in the Quickstart, we suggest that you experiment in the Contract Express
UI using your browser’s integrated developer tools (F12 or Ctrl+Shift+I in most browsers) to determine which API
calls are required for the desired behaviour. Alternatively, you may consult the API reference section of the
manual. Once you have found the calls you require, we suggest that they are added to your Quickstart collection
to experiment further. Additionally, you may wish to experiment with our sample application to see what a
typical integration might look like. To obtain a copy of the sample application, please see our Contract Express
Knowledge Base.

2.2 Postman Overview

If you do not have Postman, you can download it from here. It is worth consulting the documentation if you are
not familiar with Postman, the introduction can be accessed here.

2.3 Before using Postman – Create an API client in Contract Express

To make any calls to the Contract Express API, you will need to create an API client within the Contract Express
Admin section. Additionally, you will need to know your authorization and token URLs – these can be found by
browsing to your OpenID configuration endpoint (https://myhost.mydomain.com/id/core/.well-known/openid-
configuration OR https://myhost.mydomain.com/IdServ/core/.well-known/openid-configuration.

17 November 2022
8 Contract Express® API Manual

To create a Contract Express client, please do the following:

1. Sign in to Contract Express as an Administrator.

2. Open the Admin page.

3. Select API Clients.

4. Click + Add Client.

5. Fill in the details. Your client’s name and ID must be unique. For Postman, the Redirect URI should be
https://www.getpostman.com/oauth2/callback.

6. Make a note of your client ID and Secret - you will need them when you configure the Quickstart.

17 November 2022
Getting started with the API 9

2.4 Contract Express API Quickstart

The Contract Express API Quickstart is a Postman exercise that uses real examples, using the most common
requests, to introduce you to Contract Express’ API. The preconfigured collection includes numerous requests
including how to:

• Get a list of your templates

• Get all versions of a template (using reference)
• Create a contract (from a specified template)
• Get and update answers
• Generate a document

To obtain a copy of the API Quickstart, please see our Contract Express Knowledge Base under the
“Documentation and Resources” section. Within the package, you will also find our quick guide “Getting started
with Contract Express API using Postman” which will provide a more detailed walkthrough on how to setup the
Postman environment. Both the collection and environment are provided as supplements to the Quickstart and
may be imported into Postman.

To configure the Quickstart, you will also need your Contract Express authorization and token URLs. You may
obtain these from your Contract Express OpenID endpoint - [Contract Express URL]/id/core/.well-known/openid-
configuration or depending on your application directory, it may be [Contract Express URL]/IdServ/core/.well-
known/openid-configuration - for example: https://eu1.contractexpress.com/IdServ/core/.well-known/openid-
configuration

2.5 Contract Express Integration Sample/Sample App

The Contract Express sample application demonstrates a typical, simple integration with Contract Express
including how Authentication and Embedding the Questionnaire work. To obtain a copy of the sample
application, please see our Contract Express Knowledge Base under the “Documentation and Resources”
section.

2.6 Other considerations for accessing the Questionnaire

The examples above aim to help familiarize you with the Template API. However, there are other aspects related
to accessing the questionnaire in an external application that must be considered. For example, they do not cover
the Contract resource in any way. The Contract resource is the key transactional item that contains the answers
from a user interacting with the questionnaire and the documents that are produced from that answer set. This
is described in more detail in the API reference section.

Although every request to the API is authenticated using the access token described above, there are several ways
to obtain the access token depending on how Contract Express Identity Server has been configured and how the
client application access has been configured. For example, the OAuth Authorization Code flow was used above,
but the Implicit flow can also be used. Also, Identity Server can support various authentication mechanisms, such
as username and password, Windows authentication, ADFS and others.

17 November 2022
10 Contract Express® API Manual

3. Security
Any description of security must address two basic questions: who are you? (Authentication) and what are you
allowed to do? (Authorization).

Most of the Contract Express API calls access protected resources which require authorization. Therefore, a
client application needs to be authorized by an existing Contract Express user to make calls on their behalf and
gain access to the protected resource targeted by the call.

To obtain authorization, the application MUST request an access token from the Security Token Service (STS)
hosted in the Contract Express Identity Server web application. The STS implements the OpenID Connect and
OAuth 2.0 protocols for authentication and authorization purposes. The STS also offers support for multiple
authorization grant types and authentication flows. While multiple authentication mechanisms are supported
(Local login/Forms based authentication) and using external identity providers (Windows integrated or ADFS)
not all are suitable for certain authorization grant flows.

After the user’s successful authentication and the completion of the authorization flow, the Contract Express
Identity Server will issue an access token. Contract Express will use the access token to construct a set of
application specific “claims”, such as: The user is Ted, he is in the Thomson Reuters license space, he has the role
of template author, and he is a member of the “Development” and “UK” groups - these claims are used to make
decisions regarding authorization, which we also discuss below.

3.1 Authentication & Authorization

Authentication is handled by the Contract Express Identity Server. Identity Server supports the following
authentication methods: Forms Based Authentication (FBA), Windows Authentication and SSO (ADFS, Azure AD
and Okta). Availability of these methods is dependent on how the Identity Server was configured. To request an
access token, the client application needs to be registered with the Contract Express Identity Server. When
registering the application, an authorization grant flow must be assigned. The flows available are “Authorization
Code” and “Implicit”.

3.1.1 Authorization Code grant type for obtaining an Access Token

This flow enables a client application to obtain authorization without directly requesting it from the resource
owner. The application will redirect the resource owner to the Identity Server where he can authorize the
application. On a successful authorization, the Identity Server will send an authorization code to the client which
can be exchanged for the access tokens. More details about this flow can be found in the OAuth 2.0 spec.

17 November 2022
Security 11

3.2.1.2 Requesting the access token

To obtain an access token via the Authorization Code flow, the client application must make a GET request to
the Contract Express Identity Server authorization endpoint (example:
https://myhost.mydomain.com/id/core/connect/authorize). The table below contains a list of mandatory and
optional query string parameters that can be part of the request:

Parameter Description Expected value Required

redirect_uri The URL where The client application redirect URI (example: Yes
(callback URL) the authorization https://myhost.domain.com/callback)
code will be sent
(must match the
one which was
registered for the
client)
auth URL The URL pointing https://myhost.domain.com/id/core/connect/authorize Yes
to the Contract
Express ID Server
authorization
endpoint
access token URL The URL pointing https://myhost.domain.com/id/core/connect/token Yes
to the Contract
Express ID Server
token endpoint
client_id The client ID that client_id Yes
was created
when setting up
the API client
client_secret The client secret client_secret Yes
that was created
when setting up
the API client
scope One or more CEAPI (mandatory for API access) Yes
scopes (white CEAPI openid (for extra security)
space separated) CEAPI offline_access (to acquire a refresh token)
the application
requires
authorization for.
state A value that A value that the Identity Server will echo back No (recommended)
IdServ will echo
back in the
response
containing the
code. This can be
used to correlate
the request and
the response to
enhance security.

17 November 2022
12 Contract Express® API Manual

As presented with environment variables in Postman:

If the authorize request is valid, the Contract Express login page will be displayed, and the user can authenticate.
After successfully authenticating, an authorization code will be generated and sent to the client application as a
URL fragment (or as a form_post).

The callback endpoint in the client application should extract the code received in the response from the
Identity Server and make a POST request to the token endpoint (example:
https://myhost.mydomain.com/id/core/connect/token) to exchange it for an access token. If the state
parameter was set in the authorize request, it should be validated before attempting to extract the
authorization code.

The POST request to the token endpoint requires authentication. Authentication is handled by passing the client
id and secret pair as fields in the body (client_id=<client_id value>, client_secret=<client_secret value>) or in
the Authorization header using Basic authentication. If using the Basic authentication method, the value of the
header is expected to be (Basic <Base64 encoded string> where <Base64 encoded string> is: <client_id
value>:<client_secret value> Base64 encoded.

17 November 2022
Security 13

The request must also contain the following key value pairs in the body:

- grant_type=authorization_code

- redirect_uri=<client application redirect uri> (example: https://myhost.domain.com/callback)

- code=<authorization code from the Identity Server response>

If the call to the token endpoint was successful, an access token should be included in the response. The
response might also include an id token and/or a refresh token (if the openid and/or offline_access scopes were
added in the authorize request). The access_token is stored by the client application and is used when making
API calls that require authorization.

3.1.2 Implicit grant type for obtaining an access token

The implicit flow is a simplified version of the authorization code flow optimized for web applications developed
using JavaScript. The client application that uses this flow will redirect the Resource Owner to the Identity Server
where they can start the authorization process. On a successful authorization, the Identity Server will send an
access token to the client. More details about this flow can be found in the OAuth 2.0 spec.

3.2.2.1 Registering an Implicit grant type client with the Contract Express Identity Server
This section applies to on-premises deployments of Contract Express; the registration of a new client is done by
adding a new client element to the “CEClientsConfig.xml” file located in the “Content” folder where Contract
Express is deployed (example: C:\inetpub\wwwroot\id (or IdServ)\Content).

An example Implicit client element can be found below:

<Client ClientName="Contract Express API Test" Enabled="true" ClientId="ContractExpressAPITest" Flow=" Implicit"

ClientUri="https://localhost:44300" AccessTokenLifetime="3600">
<RedirectUris>
<RedirectUri>https://myhost.domain.com/callback</RedirectUri> (the endpoint where the authorization code will
be returned)
</RedirectUris>
<AllowedScopes>
<AllowedScope>CEAPI</AllowedScope> (mandatory scope required to access the Contract Express API)
<AllowedScope>openid</AllowedScope> (optional scope – if requested by the client it will ensure better
security)
</AllowedScopes>
</Client>

17 November 2022
14 Contract Express® API Manual

3.2.2.2 Requesting the access token

To obtain an access token through the Implicit flow the client application must make a GET request to the
Contract Express Identity Server authorization endpoint (example:
https://myhost.mydomain.com/id/core/connect/authorize). The table below contains a list of mandatory and
optional query string parameters that can be part of the request:

Parameter Description Expected value Required

client_id Client identifier. The client application ID (example: Yes
ContractExpressAPITest)
scope One or more scopes CEAPI openid Yes
(white space separated)
the application requires
authorization for.
redirect_uri The URL where the The client application redirect URI Yes
authorization code will (example:
be sent (must match the https://myhost.domain.com/callback)
one which was
registered for the
client).
response_type The type of response id_token token Yes
expected by the client
application (for the
Implicit flow the value
must be set to id_token
token).
state A value that IdServ will A value that the Identity Server will No (recommended)
echo back in the token echo back.
response. This can be
used to correlate the
request and the
response to enhance
security.
nonce A value which the A value which the Identity Server will Yes
Identity Server will echo echo back in the id_token, which
back in the id_token, should be used to correlate the token
which should be used to to the request.
correlate the token to
the request.

If the authorize request is valid the Contract Express login page will be displayed, and the user can authenticate.
After successfully authenticating an access token will be generated and sent to the client application as a URL
fragment.

The callback endpoint in the client application should extract the access token from the Identity Server response
and validate the id_token and the nonce found inside it. If the state parameter was set in the authorize request
it should be validated before attempting to extract the authorization code.

The access_token is stored by the client application and is used when making API calls that require
authorization.

17 November 2022
Security 15

3.1.3 Validating the identity token

The identity token (id_token) is a security token that MUST be validated by client applications if it is found in the
token response. The token validation can be done locally by the client or by sending the token to the identity
token validation endpoint of the Contract Express Identity Server.

To validate the token with the Identity Server, a POST request is made to the validation endpoint - example:
https://myhost.mydomain.com/id/core/connect/identitytokenvalidation with the following key value pairs in
the body:

• token = <id_token value>

• client_id = <client application id>

On a successful validation a 200 response with token’s associated claims will be returned. For details about
validating the token in the client application, please consult the sample application and the OpenID Connect
spec.

3.1.4 Refresh tokens

Refresh tokens allow the client application to request new access tokens without requiring the user to re-
authorize it. To receive this token, the application must include the “offline_access” scope in the request made
to the token or authorize endpoint (depending on the flow used). The only flow that supports the return of a
refresh token in the token response is the Authorization Code flow. To acquire a new access token, the client
must make a POST request to the token endpoint (example:
https://myhost.mydomain.com/id/core/connect/token).

The POST request to the token endpoint requires authentication. Authentication is handled in the same way as
described in section 3.2.2.2.

The request must also contain the following key value pairs in the body:

• grant_type=refresh_token
• refresh_token = <refresh_token value>

If the call to the token endpoint was successful, an access token should be included in the response.

3.1.5 Context
While the access token obtained from the previous steps confirms that the user authorized the client application
to make requests in their name, it does not guarantee that it will be able to access the resource. Contract
Express needs to confirm that the user is allowed access to that resource through its own authorization
mechanism.

There are two levels to authorization: Firstly, general authorization for actions on a class of object, such as
"Authors are allowed to manage templates", and secondly permission on a particular object, such as "Ted is
allowed to read contract number 42".

Consider first the statement “Authors are allowed to manage templates”. This type of rule describes a general
“authority” and is specified in terms of an “action” on a “resource” being allowed if some condition on “claims”
is true. So, in the example above the resource is “templates”, the action is “manage” and the test is

17 November 2022
16 Contract Express® API Manual

“role=author”. The set of all such rules is called a policy and is defined in the web.config file; therefore, it is per
Contract Express instance, not per license space, and our cloud users cannot configure this policy for
themselves. Each API method has an associated set of Action/Resource pairs, as described in the Reference
section. If the policy does not grant them all to the current user, then the call to that API method is rejected as
“Forbidden”. The Action/Resource pairs are also used to adapt the user interface, so that for example certain
tabs in the admin page are only offered if the current user has “Manage/Licence” authority.

Here is an extract from the web.config policy:

Some authorization demands vary according to the state of the object being used. So, for example using a
template normally requires Use/Templates authority, but if the template in question has the property IsMajor
set to false, then using the template requires Test/Template authority.

Now consider the statement “User Ted is allowed to read contract number 42”. This type of rule describes
permission on a particular securable object and is called an “access control rule”. There are currently five
categories of securable object in the system: Templates, Contracts, Folders, Approvals and External Tables.
Access to any particular instance of any of those types is controlled by an Access Control List (ACL) which is an
ordered list of access control rules. Each rule specifies a permission (None, Read, Write or Full) based on a claim
having a particular value. So, in the example above the ACL on contract 42 will contain the rule stating, “grant
Read permission if the ‘userid’ claim has the value ‘Ted’”. Where an ACL has multiple rules, the effective
permission is determined by the first rule that matches the user’s claims. So, if there was a later rule in the ACL
on contract 42 that stated, “Group UK has permission None”, Ted would still get access even though he is in the
UK group because the user specific rule was earlier in the list and matched his claims. Every single ACL has an
implied first rule that states “grant full permission if role is admin”. The ACL for an object can be modified by
anyone who has "Full" permission. Typically, things for which the current user has effective permission of
“None” are not returned in queries and give a “Not found” response in instance specific actions; it is as if they
don’t exist for that user.

17 November 2022
API Reference 17

4. API Reference
This section of the manual consists of two parts. Firstly, the requests used to manipulate the resources. Some of
these require structured data in the request or return structured data in the response. This structured data, which
we call Entities, are described in the second part.

Each request is described in terms of the URI identifying the resource and the HTTP method used. Then there is a
description of each parameter used in the request, and the data returned in the response. We also describe the
authorization required to perform the action. Each action also has an example invocation using the "curl" tool
described here http://en.wikipedia.org/wiki/CURL.

Some resources, such as templates, are identified by string values. Such values are subject to certain constraints.
They may not contain the characters '<', '>', '*', '%', '&', ':', '\', '/', '#', or '?' and may not
have '.' as the last non-whitespace character.

The API is tightly coupled to the HTTP protocol and makes systematic use of the standard HTTP methods.

Resource Method
GET PUT POST DELETE
Collection, for example List the URIs and Replace the Create a new Delete the entire
api/templates perhaps other entire collection entry in the collection.
details of the with another collection. The
collection's collection. new entry's URI is
members. assigned
automatically and
is usually
returned by the
operation.
Item, for example Retrieve a Replace the Perform some Delete the
api/templates/MyTemplate representation of addressed action on the addressed
the addressed member of the addressed member of the
member of the collection, or if it member of the collection.
collection. doesn't exist, collection.
create it.

In one case the OPTIONS method is used on a resource to test the current user's authorization without incurring
the overhead of retrieving a representation of that resource.

17 November 2022
18 Contract Express® API Manual

4.1 Requests

A client performs some operation on the resources managed by the API by submitting HTTP requests, where the
URL path identifies a resource or collection of resources, and the HTTP method might distinguish certain actions
on that resource. The table below gives a summary of the main resources, and the following pages then give
details about each action on that resource.

Resource Comment
/api Main entry point to API, links to resource
collections.
/api/upload/templates Upload a docx file, to be used as a template.
/api/templates Collection of templates accessible to current
user.
/api/templates/{reference} A specific template.
/api/templates/{reference}/acl The access control list for the template.
/api/templates/{reference}/dictionary The current local dictionary of the specified
template.
/api/templates/{reference}/versions All versions of the specified template.
/api/templates/{reference}/versions/{version} A specific template version.
/api/templates/{reference}/versions/{version}/content The docx template file that was last uploaded
for this template version.
/api/templates/{reference}/versions/{version}/subtemplates The sub templates used by this template
version.
/api/templates/{reference}/approvalsteps The steps of the approval process for this
template.
/api/templates/{reference}/approvalsteps/{title} An individual step in the approval process for
this template.
/api/templates/{reference}/history The history of events relating to the
template.
/api/contracts Collection of contracts accessible to current
user.
/api/contracts/{id} A specific contract.
/api/contracts/{id}/acl The access control list for the specified
contract.
/api/contracts/{id}/answers The current answer set for the specified
contract.
/api/contracts/{id}/questionnaire/pages/{page} A questionnaire page for the specified
contract.

17 November 2022
API Reference 19

Resource Comment
/api/contracts/{id}/documents The documents for the contract, based on
current answers.
/api/contracts/{id}/documents/zip Download all documents as a single zip file.
/api/contracts/{id}/documents/{docid} The meta data for the specified document.
/api/contracts/{id}/documents/{docid}/content The content byte stream for the specified
document.
/api/upload/documents/{docid} Upload an edited version of a generated
document.
/api/contracts /{id}/inputdocuments External documents uploaded for a contract.
/api/contracts /{id}/invitations Invitations to collaborate on a contract.
/api/contracts/{id}/snapshot A zip file allowing reconstruction of the
contract in its current state (debug).
/api/contracts/{id}/templates The templates that are used for attachments
for this contract (preview).
/api/contracts/{id}/templates/{template}/wording The consolidated wording for the specified
template used by the contract (preview).
/api/contracts/{id}/approvals The approvals relating to a contract.
/api/approvals The approvals awaiting approval.
/api/folders Collection of root folders accessible to the
current user.
/api/folders/{id} A specific folder.
/api/folders/{id}/acl The access control list for the specified
folder.
/api/folders/{id}/contracts The contracts in this folder.

17 November 2022
20 Contract Express® API Manual

/api
Method: GET

Parameters:

None

Response:

Returns the EntryPoint entity.

Authorization:

Unauthenticated.

Remarks:

The EntryPoint entity is the root of the API installed on the site. It indicates the version number and gives links to
the primary collections of resources, such as Templates and Contracts. It also contains assertions about copyright,
trademarks, and patents. This is the only resource that permits unauthenticated access.

Example:

curl

17 November 2022
API Reference 21

/api/upload/templates
Method: POST

Parameters:

Name Location Type Default Comment

template Content DOCX Required The template document.

Response:

The request content can either be the byte stream of the DOCX file that is the template, or it can be structured as
a multi-part MIME with the single part being the DOCX file. The response is a TemplateVersion entity, with a
content type of application/json or application/xml.

Authorization:

Requires Manage/Templates authority. If the template already exists then it requires Write permission on the
template, otherwise for a new template the user is automatically granted Full permission.

Remarks:

The template document is validated on upload, and is rejected if it is not a valid DOCX file, or it does not have a
custom property named db_template_reference whose value is a valid string identifier, or the mark-up in the
document is not well formed. Further if the template version already exists then it will be overwritten unless the
Major flag is true in which case the upload is rejected.

Example:

curl --request POST --upload-file MyTemplate.docx https://myhost.mydomain.com/rest/api/upload/templates

17 November 2022
22 Contract Express® API Manual

/api/templates
Method: GET

Parameters:

Name Location Type Default Comment

manage Query string bool False True means consider minor template
versions.
$filter Query string string None OData
$orderby Query string string None OData
$top Query string int 1024 OData
$skip QueryString int 0 OData

Response:

Returns a Template entity list, with no child entities pre-populated and no links. The Content-type is either
application/json or application/xml.

Authorization:

The response will only contain templates for which the current user has at least Read permission. Use/Templates
and Use/Queries authority is required.

Remarks:

When 'manage' is true and the user has Manage/Templates authority then the response contains details of the
current version, irrespective of whether it is a major or minor version. It also returns template details where there
are no active versions if the user has Write permission on that template. When 'manage' is false the response will
only contain information about the current Major version.

Simple OData querying is supported.

Example:

curl https://myhost.mydomain.com/rest/api/templates?manage=true

17 November 2022
API Reference 23

/api/templates/{reference}
Method: GET

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.

Response:

A Template entity with none of the current version properties instantiated, nor any child objects. It will have a
Link for creating a new contract from this template. The content-type can be application/json or application/xml.

Authorization:

Requires at least Read permission on the template and Use/Templates authority.

The reference must be a valid string identifier. The template and all its versions will be deleted. Note this will mean
that any contracts based on the template will no longer be able to display the questionnaire, or regenerate
documents.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/templates/MyTemplate

17 November 2022
API Reference 27

/api/templates/{reference}/acl
Method: GET

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.

Response:

Returns the ACL for the specified template with content-type application/json or application/xml.

Authorization:

Requires Full permission on the template and Manage/Templates authority.

Remarks:

An ACL is an ordered list of AccessControlRule entities.

Example:

curl https://myhost.mydomain.com/rest/api/templates/MyTemplate/acl

17 November 2022
28 Contract Express® API Manual

/api/templates/{reference}/acl
Method: PUT

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
acl Body entity None The new access control list.

Response:

No content.

Authorization:

Requires Full permission on the template and Manage/Templates authority.

Remarks:

Set the ACL on the template. An ACL is an ordered list of AccessControlRule entities.

Example:

curl --request PUT --header "Content-Type: application/json" --data "[{Claim:""role"",Value:""user"",Right:1}]"

curl --request PUT --header "Content-Type: application/json" --upload-file NewTV.json

https://myhost.mydomain.com/rest/api/templates/MyTemplate/versions/1.0/

17 November 2022
API Reference 33

/api/templates/{reference}/versions/{version}
Method: DELETE

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
version Path string Required The version identifier.

Response:

No content.

Authorization:

Requires at least Write permission on the template and Manage/Templates authority.

Remarks:

Deletes a specific version of template.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/templates/MyTemplate/versions/1.0/

17 November 2022
34 Contract Express® API Manual

/api/templates/{reference}/versions/{version}/dictionary
Method: GET

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
version Path string Required The version identifier.

Response:

The dictionary of the specified template, content-type application/xml. An Etag header is also returned that can
be used for the fulfilment of subsequent requests from the client cache.

Authorization:

Requires Read permission on the template and Manage/Templates authority.

Remarks:

Retrieves the local (unconsolidated) Dictionary for the specified version of the template. This supports the sharing
of dictionary objects across templates while they are being prepared in the Author tool. The dictionary is only
available as XML.

Example:

curl https://myhost.mydomain.com/rest/api/templates/MyContract/versions/1.0/dictionary

17 November 2022
API Reference 35

/api/templates/{reference}/versions/{version}/content
Method: GET

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
version Path string Required The version identifier.

Response:

Byte stream of content type application/vnd.openxmlformats-officedocument.wordprocessingml.document. An

The fully instantiated ApprovalStep entity for the added step. The content-type can be application/json or
application/xml.

Authorization:

Requires at least Write permission on the template and Manage/Templates authority.

Remarks:

The reference must be a valid string identifier.

Example:

curl --request POST --header "Content-Type: application/json" --data "{TemplateReference:""MyTemplate"",

Title:""Legal""}" https://myhost.mydomain.com/rest/api/templates/MyTemplate/approvalsteps

17 November 2022
API Reference 39

/api/templates/{reference}/approvalsteps/{title}
Method: GET

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
title Path string Required The step identifier.

Response:

The ApprovalStep entity for the specified step of the specified template. The content-type can be application/json
or application/xml.

Authorization:

Requires at least Read permission on the template and Manage/Templates authority.

Remarks:

The reference and title must both be valid string identifiers.

Example:

curl https://myhost.mydomain.com/rest/api/templates/MyTemplate/approvalsteps/Legal

17 November 2022
40 Contract Express® API Manual

/api/templates/{reference}/approvalsteps/{title}
Method: PUT

Parameters:

Name Location Type Default Comment

reference Path string Required The template identifier.
title Path string Required The step identifier.
step Body entity Required The modified ApprovalStep.

Response:

The fully updated ApprovalStep entity for the specified step of the specified template. The content-type can be
application/json or application/xml.

Authorization:

Requires at least Write permission on the template and Manage/Templates authority.

Remarks:

The reference and title must both be valid string identifiers. Only updateable fields of the ApprovalStep will be
updated. Some dependent fields will also be updated in the response, such as ModifiedBy.

Example:

curl --request PUT --header "Content-Type: application/json" --data "{ApprovalStepId:4224,

curl --request POST --header "Content-Length: 0"

https://myhost.mydomain.com/rest/api/contracts?template=TestTemplate

17 November 2022
44 Contract Express® API Manual

/api/contracts
Method: GET

Parameters:

Name Location Type Default Comment

direct Query string bool false True means only directly shared
contracts.
$filter Query string string None OData
$orderby Query string string None OData
$top Query string int 256 OData
$skip Query string int 0 OData
sortVarName Query string string None Template variable name.
sortRepeatCtx Query string string None The repeat context of the variable.
sortDataType Query string string string A CE data type. One of: string , string* ,
date , time , integer , float , boolean ,
note
sortDesc Query string boolean false
filterVarName Query string string None Template variable name.
filterValue Query string string None The value to filter on.
filterRepeatCtx Query string string None The repeat context of the variable.
filterDataType Query string string string A CE data type. One of: string , string* ,
date , time , integer , float , boolean ,
note

Response:

Contract entity list, with no child entities pre-populated and no links. The Content-type is either application/json
or application/xml.

Authorization:

The response will only contain contracts for which the current user has at least Read permission. Use/Contracts
and Use/Queries authority is required.

17 November 2022
API Reference 45

Remarks:

When 'direct' is true then the response only contains contracts for which the user has at least Read permission
but No permission on the contract's containing folder.

The underlying query is restricted to the most recently created 1024 contracts after applying permission and
'direct' constraints, but before the applying the OData constraints.

Please note we have different parameters for filtering/sorting metadata columns as opposed to template specific
data. Sorting/Filtering on metadata columns use the standard OData query string parameters listed in the table
above (prefixed by the $). For sorting/filtering on template specific data use the custom filter and sort query string
parameters.

Example:

curl https://myhost.mydomain.com/rest/api/contracts?direct=true

17 November 2022
46 Contract Express® API Manual

/api/contracts/{id}
Method: OPTIONS

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

No response body. The header "Allow: GET, PUT, DELETE" is returned.

Authorization:

Requires Use/Contracts authority.

Remarks:

Used by the questionnaire as a "pre-flight" check that the current user has the relevant authority, without
incurring overhead of data retrieval of a successful GET method.

Example:

curl --request OPTIONS https://myhost.mydomain.com/rest/api/contracts/42

17 November 2022
API Reference 47

/api/contracts/{id}
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

Contract entity with any existing Document child entities and for each of those the current DocumentVersion
entity. Links to questionnaire, answers, documents, template and containing folder.

Authorization:

Requires at least Read permission on the contract and Use/Contracts authority.

Remarks:

Retrieves a specific Contract entity.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42

17 November 2022
48 Contract Express® API Manual

/api/contracts/{id}
Method: PUT

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
contract Body entity Required The contract object with updated field
values.

Response:

The updated Contract entity with any existing Document child entities and for each of those the current
DocumentVersion entity. Links to questionnaire, answers, documents, template and containing folder. Content-
type is either application/json or application/xml.

Authorization:

Requires at least Write permission on the contract and Use/Contracts authority.

Remarks:

Updates a specified contract. The Contract Id in the entity must match the id used in the Path. IsExplicitName,
ExternalReference, ExternalLabel and Name are set by this action. All other fields are unaffected.

Example:

curl --request PUT --header "Content-Type: application/json" --data "{ContractId:42,

IsExplicitName:true,ExternalReference:null,ExternalLabel:null,Name:""My special name""}"
https://myhost.mydomain.com/rest/api/contracts/42

17 November 2022
API Reference 49

/api/contracts/{id}
Method: DELETE

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

No content.

Authorization:

Requires at least Write permission on the contract and Use/Contracts authority.

Remarks:

Deletes a specific contract.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/contracts/42

17 November 2022
50 Contract Express® API Manual

/api/contracts/{id}
Method: POST

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
folderid Query string int Required The destination folder id.

Response:

No content.

Authorization:

Requires at least Write permission on the contract and the destination folder, and Use/Folder and
Manage/Contracts authority.

Remarks:

Moves a contract to a new folder. The ACL of the contract remains the same and does not inherit that of the
destination folder.

Example:

curl --request POST --header "Content-Length: 0" https://myhost.mydomain.com/rest/api/contracts/42?folderid=12

17 November 2022
API Reference 51

/api/contracts
Method: GET

Parameters:

Name Location Type Default Comment

docid Query string long Required A document identifier.
version Query string string Required The contract version.

Response:

Contract entity with any existing Document child entities and for each of those the DocumentVersion entity
relating to the specified version of the contract. Links to questionnaire, answers, documents, template and
containing folder.

Authorization:

Requires at least Read permission on the contract and Use/Contracts authority.

Remarks:

Retrieves the Contract entity that contains the specified Document. The version is the Base64 encoding of the
ContractVersion property of those DocumentVersions to be included in the response. This "reverse" lookup is
useful for retrieving a Contract from information saved in a generated document. Note the response is a single
Contract entity and not a collection as might be expected from the resource path.

Example:

curl https://myhost.mydomain.com/rest/api/contracts?docid=77&version=AAAAAAAA4pI%3d

17 November 2022
52 Contract Express® API Manual

/api/contracts/{id}/acl
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

Returns an AclPair entity with content-type application/json or application/xml.

Authorization:

Requires Full permission on the contract and Manage/Contracts authority.

Remarks:

The ACL pair consists of an explicit ACL, which is null if the contract is inheriting its permissions from the containing
folder, and an implicit ACL which is the ACL of the containing folder. Returning both allows the client to distinguish,
and display either without an additional GET request.

An ACL is a list of AccessControlRule entities.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/acl

17 November 2022
API Reference 53

/api/contracts/{id}/acl
Method: PUT

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
acl Body entity None The explicit access control list.

Response:

No content.

Authorization:

Requires Full permission on the contract and Manage/Contracts authority.

Remarks:

Set the explicit ACL on the contract. Setting this to null makes the contract inherit the ACL of the containing folder.

Example:

curl --request PUT --header "Content-Type: application/json" --data "[{Claim:""role"",Value:""user"",Right:1}]"

https://myhost.mydomain.com/rest/api/contracts/42/acl

17 November 2022
54 Contract Express® API Manual

/api/contracts/{id}/answers
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

An AnswerSet, content-type application/xml. An Etag header is also returned that can be used on subsequent
POST for detecting conflicting updates.

Authorization:

Requires Read permission on the contract, and Use/Contracts and Use/Questionnaires authority.

Remarks:

Retrieves the current answer set for the specified contract. The answer set is typically the answer to questions
provided through the questionnaire, and any explicitly set parameters. The answer set is only available as XML.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/answers

17 November 2022
API Reference 55

/api/contracts/{id}/answers
Method: POST

Parameters:

Name Location Type Default Comment

ifmatch Header etag None Used for the detection of update conflicts.
id Path long Required The contract identifier.
answers Body xml Required The new answers.

Response:

No content.

Authorization:

Requires Write permission on the contract, and Use/Contracts and Use/Questionnaires authority.

Remarks:

Merges the submitted answers with the existing answers for the specified contract. Parameter values in the
submitted answers are discarded, as parameters are invariant after contract creation. For requests initiated by a
browser, the ifmatch header is usually automatically populated based on the Etag of the currently cached request,
if there was one.

Example:

curl --request POST --upload-file Answers.xml https://myhost.mydomain.com/rest/api/contracts/{id}/answers

17 November 2022
56 Contract Express® API Manual

/api/contracts/{id}/questionnaire/pages/{page}
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
page Path int Required The 1 based index of the page of the full
questionnaire.
navigate Query string string self The page requested relative to the index
specified in the 'page' parameter. Options
are {self, next, previous, first, last}.
readOnly Query string bool false True means that the questionnaire page
will not be used for submitting modified
answers.

Response:

An ActivatedPage with content-type application/xml or application/javascript. An Etag header is also returned

that can be used on subsequent POST of answers updated on this page for detecting conflicting updates. The
response will have links for self, next, previous, first and last pages, the answers and the documents.

Authorization:

Requires Read permission on the contract and the underlying template, and Use/Contracts and
Use/Questionnaires authority.

Remarks:

Retrieves the appropriate questionnaire page definition as XML or JavaScript. JSON is not supported. The
JavaScript representation is well suited to conversion to HTML in a very flexible manner described more fully in
section 5, Embedding the Questionnaire.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/questionnaire/pages/1?navigate=first

17 November 2022
API Reference 57

/api/contracts/{id}/documents
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

Contract entity with Document child entities and for each of those the current DocumentVersion entity, and zero
or more GeneratedAlert child entities. Content-type application/json or application/xml.

Requires Read permission on the contract and Use/Contracts and Use/Documents authority.

Remarks:

Documents generated from templates will default to using the content-type of application/vnd.openxmlformats-
officedocument.wordprocessingml.document. Uploaded documents will use the content type given during
upload. The client can request a response content type of application/pdf either by using a request Accept header,
or by setting the 'pdf' query string parameter to 'true'. In this case the system will attempt to convert the
document into a PDF, returning a "Not acceptable" response if this is not possible.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/documents/77/versions/81/content

17 November 2022
API Reference 65

api/upload/inputdocuments/{id}
Method: POST

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
document Content - Required The document content.

Response:

No content. The Location response header will contain the URL for the InputDocument.

Authorization:

Requires Write permission on the contract and Use/Contracts and Use/Questionnaires authority.

Remarks:

The request content can either be the byte stream of the document, or it can be structured as a multi-part MIME
with the single part being the document. There must be a Content-Type header on the request. The uploaded
content is available to attach or include in the set of generated documents for the contract. For the input
document to be used in this way there must be a suitable field in a template that uses a file upload variable that
is set to a value that identifies this input document.

Example:

curl --request POST --upload-file MyExternalDocument.docx

https://myhost.mydomain.com/rest/api/upload/inputdocuments/42

17 November 2022
66 Contract Express® API Manual

api/contracts /{id}/inputdocuments
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

A list of InputDocument entities for the contract. Content-type application/xml or application/javascript.

Authorization:

Requires Read permission on the contract and Use/Contracts and Use/Questionnaires authority.

Remarks:

api/contracts /{id}/invitations
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

Returns a list of Invitation entities for the Contract. Content-type can be application/xml or application/json.

Authorization:

Requires Read permission on the contract and Use/Contracts authority.

Remarks:

Invitations are created using an appropriate api/email request.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/invitations

17 November 2022
70 Contract Express® API Manual

api/contracts /{id}/invitations/{itemid}
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
itemid Path long Required The invitation identifier.

Response:

Returns the specified Invitation entity. Content-type can be application/xml or application/json.

Authorization:

Requires Read permission on the contract and Use/Contracts authority.

Remarks:

Invitations are created using an appropriate api/email request.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/invitations/1234

17 November 2022
API Reference 71

api/contracts /{id}/invitations/{itemid}
Method: DELETE

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
itemid Path long Required The invitation identifier.

Response:

No content.

Authorization:

Requires Full permission on the contract and Use/Contracts authority.

Remarks:

Full permission is required because the request might restrict who has access to the contract.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/contracts/42/invitations/1234

17 November 2022
72 Contract Express® API Manual

/api/contracts/{id}/documents/zip
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
signed Query string bool false True if a zip of the signed documents is
required.

Response:

All the current document contents for the specified contract as a single zip file. Content-type application/zip.

Authorization:

Requires Read permission on the contract and Use/Contracts and Use/Documents authority.

Remarks:

This method will use the default content type of the documents inside the zip archive. No attempt to regenerate
the documents will be made if there are none for the current answer set.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/documents/zip

17 November 2022
API Reference 73

/api/contracts/activity/{year}/{month}
Method: GET

Parameters:

Name Location Type Default Comment

year Path int Required The calendar year.
month Path int Required The calendar month.
format Query string string None CSV to indicate response required as
comma separated values.

Response:

A list of Activity entities, as content type application/json, application/xml or text/csv. For content type text/csv a
content disposition of attachment is added.

Authorization:

Summarizes only those contracts for which current user has at least Read permission and requires
Manage/Contracts and Use/Queries authority.

Remarks:

The Activity entity in this case states how many times a specific template was used by a particular user in the
specified month. Note that all dates used are based on UTC times. The format parameter is intended for use in
situations where there is no control over the Accept header in the request.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/activity/2014/4

17 November 2022
74 Contract Express® API Manual

/api/contracts/charges/{year}/{month}
Method: GET

Parameters:

Name Location Type Default Comment

year Path int Required The calendar year.
month Path int Required The calendar month.

Response:

The content type is application/xml with a content disposition of attachment.

Authorization:

Requires Read permission on the contract, and Use/Contracts and Use/Preview authority.

Remarks:

The response is the consolidated wording of the top template or an attachment template for the set of templates
used by the contract. The JavaScript is optimized for document Preview and a proportion of the wording text may
have been redacted.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/templates/TestTemplate/wording

17 November 2022
78 Contract Express® API Manual

api/contracts/{id}/templates/uptodate
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

Boolean true or false. The content-type can be application/json or application/xml.

Authorization:

Requires at least Read permission on the contract and the underlying template, and Use/Contracts authority.

Remarks:

Returns true if the contract is using the most up to date templates.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/templates/uptodate

17 November 2022
API Reference 79

api/contracts/{id}/templates/uptodate
Method: POST

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

No content.

Authorization:

Requires at least Write permission on the contract and Read permission on the underlying template, and
Use/Contracts authority.

Remarks:

Updates the contract to use the most recent versions of the underlying templates.

Example:

curl --request POST --header "Content-Length: 0"

https://myhost.mydomain.com/rest/api/contracts/42/templates/uptodate

17 November 2022
80 Contract Express® API Manual

api/contracts/{id}/ esignature/cancel
Method: POST

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

No content.

Authorization:

Requires at least Write permission on the contract, and Use/Contracts authority.

Remarks:

Updates the contract to cancel the E-Signature request.

Example:

curl --request POST --header "Content-Length: 0"

https://myhost.mydomain.com/rest/api/contracts/42/esignature/cancel

17 November 2022
API Reference 81

/api/contracts/{id}/approvals
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.

Response:

A list of Approval entities for the specified Contract. Content-type application/json or application/xml.

Authorization:

Requires Read permission on the contract and Use/Contracts and Use/Approvals authority.

Remarks:

None.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/approvals

17 November 2022
82 Contract Express® API Manual

/api/contracts/{id}/approvals/{title}
Method: GET

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
title Path string Required The approval name.

Response:

Approval entity as Content-type application/json or application/xml.

Authorization:

Requires Read permission on the Contract and Use/Contracts and Use/Approvals authority.

Remarks:

The title parameter must be a valid string identifier.

Example:

curl https://myhost.mydomain.com/rest/api/contracts/42/approvals/Legal

17 November 2022
API Reference 83

/api/contracts/{id}/approvals/{title}
Method: POST

Parameters:

Name Location Type Default Comment

id Path long Required The contract identifier.
title Path string Required The approval name.
action Query string string Required The action to perform on the approval.
approvertype Query string string Null Either 'userid' or 'group'.
approver Query string string Null The user id or group name.
comment Query string string Null A comment to add to any email that
might be triggered.

Response:

No content.

Authorization:

Requires Write permission on the Contract and Use/Contracts and Use/Approvals or Manage/Approvals authority
depending on the action.

Remarks:

The title parameter must be a valid string identifier. The action parameter must be one of the values requests,
forward, grab, approve, reject or revoke. If the action is request then Use/Approvals authority is required,
otherwise for all other values Manage/Approvals is required. If the action is grab or forward then the approver
and approvertype parameters must not be null and indicate either the user who has grabbed the approval, or the
user or group to which it has been forwarded. The ApprovalStep associated with this Approval may have been
configured to send emails, in which case this request may trigger the sending of one or more emails.

Example:

curl --request POST --header "Content-Length: 0"

curl --request POST --header "Content-Length: 0"

https://myhost.mydomain.com/rest/api/folders?name=foo&category=contract

17 November 2022
88 Contract Express® API Manual

/api/folders/{id}
Method: GET

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.

Response:

Folder entity with any existing Contract and Folder child entities populated. Content-type application/json or
application/xml.

Authorization:

Requires at least Read permission on the folder and Use/Folders authority. The child entities will not be populated
unless the user also has Use/Queries authority.

Remarks:

Retrieves a specific folder and its contents.

Example:

curl https://myhost.mydomain.com/rest/api/folders/3

17 November 2022
API Reference 89

/api/folders/{id}
Method: POST

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.
name Query string string Required The name of the new sub-folder.

Response:

No content, but with a Location header with the URL of the new folder.

Authorization:

Requires at least Write permission on the folder and Use/Folders authority.

Remarks:

Creates a new sub-folder of the specified folder with the given name. The new folder will inherit the ACL of the
specified folder. The name must not be the same as any existing sub-folders of the specified folder.

Example:

curl --request POST --header "Content-Length: 0" https://myhost.mydomain.com/rest/api/folders/3?name=bar

17 November 2022
90 Contract Express® API Manual

/api/folders/{id}
Method: PUT

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.
folder Content entity Required The Folder entity with updated properties.

Response:

The updated Folder entity, with content-type of application/json or application/xml.

Authorization:

Requires at least Write permission on the folder and Use/Folders authority.

Remarks:

Update the Name property of the folder. The name must not be the same as any existing sub-folders of the
specified folder.

Example:

curl --request PUT --header "Content-Type: application/json" --data "{FolderId:3, Name:""My special name""}"
https://myhost.mydomain.com/rest/api/folders/3

17 November 2022
API Reference 91

/api/folders/{id}
Method: DELETE

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.

Response:

No content.

Authorization:

Requires at least Write permission on the folder and all its descendants and Use/Folders authority.

Remarks:

Deletes a specific folder and all its contents.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/folders/3

17 November 2022
92 Contract Express® API Manual

/api/folders/{id}
Method: POST

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.
parentid Query string int Required The destination folder id.

Response:

No content.

Authorization:

Requires at least Write permission on the folder being moved and the destination folder, and Use/Folders
authority.

Remarks:

Moves a folder to a new parent folder. The ACL of the folder remains the same and does not inherit that of the
new parent folder. A value of zero for the parentid means make the folder an absolute "root" folder, and this
requires CreateRoot/Folders authority.

Example:

curl --request POST --header "Content-Length: 0" https://myhost.mydomain.com/rest/api/folders/3?parentid=17

17 November 2022
API Reference 93

/api/folders/{id}/acl
Method: GET

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.

Response:

Returns an AclPair entity with content-type application/json or application/xml.

Authorization:

Requires Full permission on the folder and Use/Folders authority.

Remarks:

The ACL pair consists of an explicit ACL, which is null if the folder is inheriting its permissions from its parent folder,
and an implicit ACL which is the ACL of the parent folder. Returning both allows the client to distinguish, and
display either without an additional GET request.

An ACL is a list of AccessControlRule entities.

Example:

curl https://myhost.mydomain.com/rest/api/folders/3/acl

17 November 2022
94 Contract Express® API Manual

/api/folders/{id}/acl
Method: PUT

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.
acl Body entity None The explicit access control list.

Response:

No content.

Authorization:

Requires Full permission on the folder and Use/Folders authority.

Remarks:

This removes the association of a Template and a Profile from a Folder.

Example:

curl --request DELETE https://myhost.mydomain.com/rest/api/folders/3/templates/777

17 November 2022
98 Contract Express® API Manual

/api/folders/{id}/contracts
Method: POST

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.
template Query string string Required The template reference.
version Query string string None The specific version to use. The current
version is used if none specified.
minor Query string bool false False means only use Major template
versions for this contract.

Response:

Contract entity, with no child entities pre-populated. Links to self, questionnaire, answers, documents, and
template. The Content-type is either application/json or application/xml.

Authorization:

Requires Write permission on the folder. When 'minor' is false then requires Read permission on template, and
Use/Folders, Use/Contracts and Use/Templates authority. When 'minor' is true then requires Write permission
on template and Test/Templates instead of Use/Templates authority.

Remarks:

This creates a new contract in the specified folder. ACL of the new contract inherits from that folder. The identity
claims of the user who uploaded the template version are used for determining authorization on sub-templates.

Example:

curl --request POST --header "Content-Length: 0"

https://myhost.mydomain.com/rest/api/folders/3/contracts?template=TestTemplate

17 November 2022
API Reference 99

/api/folders/{id}/contracts
Method: GET

Parameters:

Name Location Type Default Comment

id Path int Required The folder identifier.

Response:

Contract entity list, with no child entities pre-populated. Links to self, questionnaire, answers, documents, and
template. The Content-type is either application/json or application/xml.

Authorization:

The response will only contain contracts for which the current user has at least Read permission. Use/Folders,
Use/Contracts and Use/Queries authority is required.

Remarks:

This returns all the contracts visible to the current user in the specified folder.

Example:

curl https://myhost.mydomain.com/rest/api/folders/3/contracts

17 November 2022
100 Contract Express® API Manual

/api/account/login
Method: POST

Parameters:

None.

Response:

A string which is used as an anti-forgery token. Content type is text/plain. There will also be a Set-Cookie response
header.

Authorization:

The caller needs Use/Licence authority, so must provide credentials via an Authorization header.

Remarks:

This request is only useful where the target instance of Contract Express is configured for Forms Based
Authentication. This call allows the caller to receive an FBA authentication cookie and anti-forgery token that can
be used on subsequent calls. The Authorization header would typically use the Basic or SWT schemes described
in section 4.1 below. This is the programmatic equivalent of the login screen. It is used when embedding the
questionnaire so that the browser has a cookie that will be automatically added to subsequent requests by the
browser.

Example:

curl --request POST --header "Content-Length: 0" –header "Authorization: SWT RG9tYWlu..."
https://myhost.mydomain.com/rest/api/account/login

17 November 2022
API Reference 101

/api/account/logout
Method: POST

Parameters:

None.

Response:

No content. There will be a Set-Cookie response header.

Authorization:

Requires Use/Licence authority.

Remarks:

Clears the session cookie. It will also trigger any logout functionality that has been configured for this user.

Example:

curl --request POST --header "Content-Length: 0" https://myhost.mydomain.com/rest/api/account/logout

17 November 2022
102 Contract Express® API Manual

/api/account/password
Method: POST

Parameters:

Name Location Type Default Comment

body Content entity None The UserNewPassword entity with the old
and new passwords.

Response:

No content.

Authorization:

Requires Use/Licence authority.

Remarks:

This will change the current user's password. It requires the old password to be correctly specified as well as the
new one. It will also trigger an email to be sent to the current user alerting them to the fact the password has
been changed and allowing them to reset it easily.

Example:

curl --request POST --header "Content-Type: application/json" --data "{CurrentPassword:""Password1"",

NewPassword:""Password2""}" https://myhost.mydomain.com/rest/api/account/password

17 November 2022
API Reference 103

/api/account/settings
Method: GET

Parameters:

Name Location Type Default Comment

userid Path string None Optionally the id of the user whose
settings are to be retrieved.

Response:

Returns a UserSettings entity. Supports application/json and application/xml content types.

Authorization:

Requires Use/Licence authority to get the current user’s settings by not specifying a value for the userid parameter
and Manage/Licence authority when a userid parameter is specified.

Remarks:

This retrieves various settings relating to the specified user. If the user does not currently exist within the
LicenceSpace, and the Licence allows for another user to be created, then the user will be automatically created
with appropriate default settings. The response object will include a child LicenceSpace object, with any Subsite
specific overrides applied. If userid was not specified, then the UserSettings will have its AuthorizedActions
property set with all the resource/action authorities granted to the current user.

Example:

curl https://myhost.mydomain.com/rest/api/account/settings

17 November 2022
104 Contract Express® API Manual

/api/account/settings
Method: PUT

Parameters:

Name Location Type Default Comment

body Content entity None The UserSettings entity with the updated
property values.

Response:

No content.

Authorization:

Remarks:

This returns the list of groups that the current user can see and whose names contain the substring specified in
the name parameter. The search space will either correspond to the LicenceSpace or the Subsite to which the
caller belongs.

Example:

curl https://myhost.mydomain.com/rest/api/account/groups?name=dev

17 November 2022
108 Contract Express® API Manual

/api/account/notices
Method: GET

Parameters:

None.

Response:

Returns a list of Notice entities. Supports application/json and application/xml content types.

Authorization:

Requires Use/Licence authority.

Remarks:

This returns the list of active Notice entities that have not yet been acknowledged by the current user.

Example:

curl https://myhost.mydomain.com/rest/api/account/notices

17 November 2022
API Reference 109

/api/account/notices
Method: POST

Parameters:

Name Location Type Default Comment

noticeid Query string int Required The id of the last notice.

Response:

No content.

Authorization:

Requires Use/Licence authority.

Remarks:

This records the id of a Notice entity that is the last which the current user has acknowledged. Notice ids are
monotonically increasing integers, so all prior Notices are also deemed to have been acknowledged.

Example:

curl https://myhost.mydomain.com/rest/api/account/notices?noticeid=42

17 November 2022
110 Contract Express® API Manual

/api/account/permission
Method: POST

Parameters:

Name Location Type Default Comment

acl Body entity None A list of AccessControlRule entities.

Response:

Returns a string with content type text/plain.

Authorization:

Requires Use/Licence authority.

Remarks:

Calculates the effective permission that would be granted to the current user by the Access Control List specified
in the body of the request. The response will be one of None, Read, Write or Full.

Example:

curl --request POST --header "Content-Type: application/json" --data "[{Claim:""role"",Value:""user"",Right:1}]"

https://myhost.mydomain.com/rest/api/account/permission

17 November 2022
API Reference 111

/api/account/token
Method: GET

Parameters:

Name Location Type Default Comment

template Query string string Required The template identifier
profile Query string string None Optional profile identifier

Response:

Returns a string representation of the public token for the specified template with content-type application/json
or application/xml.

Authorization:

Requires Full permission on the template and Manage/Templates authority.

Remarks:

Retrieves a token for guest access to a template. When added to the public URL this allows guests to launch the
questionnaire for that template and generate a set of documents. If the profile is specified, then that Profile will
be used when the template is launched. Note the ACL on the template must have been set to allow guest access
and there must be a Major version of the template before the token can be used.

Example:

curl https://myhost.mydomain.com/rest/api/account/token?template=MyTemplate

17 November 2022
112 Contract Express® API Manual

4.2 Entities

This section describes the application specific structured data types. A number of other media types are used by
the system, for example Template and Document content is often represented as Office Open XML, described
here http://en.wikipedia.org/wiki/Office_Open_XML.

The entities themselves have properties that may be a reference to some other entity, or collection of entities,
but more commonly are some scalar value type corresponding to C# long, int, bool, string, DateTime etc.

Reference string Unique identifier for a template within the license space.
Version string The current version of this template.
FolderId int The id of the template folder (aka category) to which this
combination of template and profile is associated. This property is
null if the entity represents the underlying template itself.
ProfileReference string The profile to be used with the template in this case.
Name string A name for the combination of template and profile.
Description string The description of the current version.
Keywords string Any whitespace delimited keywords for the current version.
UploadedBy string The display name of the user who uploaded the current version.
UploadedById string The user id of the user who uploaded the current version.
UploadedOn DateTime The date and time the current version was uploaded.
IsInactive bool A template is inactive if all versions are inactive.
Advertise bool True if this template can be shown on the public page for this
license space.
Share byte 0 – Single user access
1 – Shared with other authenticated users
2 – Shared with unauthenticated guests
3 – Shared with both authenticated users and unauthenticated
guests
EffectiveRight int The permission that the current user has on the template:
0 – None
1 – Read
2 – Write
3 – Full
Versions List<TemplateVersion> Sometimes this property will be instantiated with data for one or
more versions of the template, to avoid additional round trip to
services.

17 November 2022
API Reference 117

Links:

Name Comment
newcontract The URL for creating a new contract from this template.

Remarks:

The Template entity holds properties of a particular template, or a template and profile combination, including
some properties of the current version of that template. The current version is the version (test or live depending
on context) that is valid at the moment the request was made. Supports JSON and XML serialization.

17 November 2022
118 Contract Express® API Manual

TemplateVersion
Properties:

Name Type Comment

Reference string Unique identifier for this template within the license space.
Version string The unique identifier of this version of the template.
IsMajor bool True if this is a "major" version, to be used by business users, as opposed
to a "minor" version that is used for testing by the template authors.
Name string The name that will be used for documents generated from this template.
Description string The description of this version.
Keywords string Any whitespace delimited keywords for this version.
CompilerVersion string The version of the Contract Express template compiler used when
uploading this template version.
ValidFrom DateTime The date and time at which this is the correct version to use.
ValidTo DateTime The date and time at which this is no longer the correct "minor" version.
Null means valid indefinitely.
MajorValidTo DateTime The date and time at which this is no longer the correct "major" version.
Null means valid indefinitely.
UploadedBy string The id of the user who uploaded this version.
UploadedOn DateTime The date and time this version was uploaded.
IsInactive bool True if this template has been inactivated.
NettPrice decimal Price for using this template to generate a document.
EffectiveRight int The permission that the current user has on the template:
0 – None
1 – Read
2 – Write
3 – Full

Links:

None.

Remarks:

Properties of a particular version of a template. Note that EffectiveRight does not vary between versions; it is
really a property of the Template but is included here as a convenience. Supports JSON and XML serialization.

17 November 2022
API Reference 119

AccessControlRule
Properties:

Name Type Comment

Claim string One of "role", "group", "userid" or "guestid", which is the type of security
principal to which this rule applies.
Value string The instance of that type of security principal to which this rule applies.
Right int The access right granted by this rule.
0 – None
1 – Read
2 – Write
3 – Full

Links:

None.

Remarks:

AccessControlRule entities are combined in a sequence to form an Access Control List (ACL) for a given securable
object, such as a specific template, folder, or contract. For the "role" claim, the allowed values are "admin",
"author", "user" or "guest". For the "group" or "userid" claim the allowed values are any user or group that has
been created in the current license space. The rights are cumulative, so "Full" implies "Write", which in turn implies
"Read"; in this model it is not possible to grant "Write" permission without also granting "Read" permission.
Supports JSON and XML serialization.

17 November 2022
120 Contract Express® API Manual

Dictionary
Properties:

See Remarks.

Links:

None.

ContractId long Unique identifier for this contract within the license space.
FolderId int The folder containing this contract. Null means the contract has
been deleted from its folder.
TemplateReference string The template used to create this contract.
IsTest bool True if this contract was created to test the template.
ProfileReference string The profile used when creating this contract.
CreatedAt DateTime When the contract was created.
CreatedBy string The id of the user who created this contract.
ModifiedAt DateTime The date and time this contract was last modified.
ModifiedBy string The display name of the user who last modified this contract.
ModifiedById string The user id of the user who last modified this contract.
Requester string The user who requested approval of this contract.
ExternalReference string If used, then is an alternate key for this contract. It is intended for
embedding a key value from a host system.
ExternalLabel string A free text area for packing additional data from a host system.
IsExplicitName bool True if the name of this contract has been explicitly set and is no
longer to be computed by the templates.
Name string The name of this contract.
Share byte 0 – Single user access
1 – Shared with other authenticated users
2 – Shared with unauthenticated guests
3 – Shared with both authenticated users and unauthenticated
guests
EffectiveRight int The permission that the current user has on the template:
0 – None
1 – Read
2 – Write
3 – Full
Status string The status of this contract.

17 November 2022
API Reference 127

Name Type Comment

StatusLabel string The configurable display name for the Status.
ESignatureId string The identifier used by the external eSignature system to uniquely
identify the set of documents being managed through the signature
process.
Alerts List<GeneratedAlert> The set of Alert entities triggered during document generation.
Documents List<Document> Sometimes this property will be instantiated with data for one or
more Documents associated with this contract, to avoid additional
round trip to services.

Links:

Name Comment
questionnaire The activated questionnaire pages for this contract.
answers The answers provided for this contract.
documents The documents produced for this contract.
folder The folder containing this contract.
template The template from which this contract was created.

Remarks:

A Contract entity is a container for a set of documents produced by applying answer data to a template (and any
sub-templates). There may be zero or more documents. There will be exactly one "top" template. Supports JSON
and XML serialization.

17 November 2022
128 Contract Express® API Manual

AnswerSet
Properties:

See Remarks.

Links:

None.

Remarks:

An AnswerSet describes a rich collection of data used (or produced) by a set of templates, such as the answers
provided for question variables, the parameter settings used, and blocks of export data. The AnswerSet entity is
only available as XML. The XML schema (answers.xsd) for an answer set accompanies this manual.

17 November 2022
API Reference 129

Document
Properties:

Name Type Comment

DocumentId long Unique identifier for this document within the license space.
ContractId long The contract to which this document is associated.
Source string The origin of this document. This can be "template" indicating it
was derived from a template or "upload" indicating it was
uploaded by a user.
SourceReference string If Source is "template" then this is the reference for the template
from which this document was generated, and for "upload" it is
the unique identifier of the uploaded document.
Occurrence int This is a counter per Source/SourceReference pair within the
parent contract and is used in combination with them to track
logical documents over regeneration of the document wording.
IsExplicitName bool True if the name of this document has been explicitly set and is
no longer to be derived from the template.
Name string The name of this document.
ChargedAt DateTime The charge point for this document, which is when it was first
generated.
ChargedAmount decimal The nominal price of this document, for usage-based charging.
IsSigned bool True if the document has been signed.
DocumentVersions List<DocumentVersion> Sometimes this property will be instantiated with data for one or
more DocumentVersion entities associated with this Document,
to avoid additional round trip to services.

Links:

None.

Remarks:

Properties of a logical document, of which there may be many versions, but which would be considered versions
of the "same" document. Supports JSON and XML serialization.

17 November 2022
130 Contract Express® API Manual

DocumentVersion
Properties:

Name Type Comment

DocumentVersionId long Unique identifier for this DocumentVersion.
DocumentId long The id of the Document of which this is a version.
CreatedAt DateTime When the version of the document was generated.
CreatedBy string The user who triggered the generation of this version of the document.
Name string The name calculated from the template definition and the current
answers.
Complete bool True if the generated document has no unresolved fields or spans.
ContractVersion byte[] The version of answers used to generate this version of the document.
FormId Guid The exact set of template versions used for the overall contract for which
this version of the document was generated.
TemplateVersion string The version of the template associated with the parent Document that
was used to generate this document version.
ContentType string The content type of the stored representation of this version of the
document.
FileExtension string The default file extension if something of this content type were to be
saved. This is primarily used to guide SQL Server free text search
indexing.

Links:

None.

Remarks:

Properties of a specific version of a generated document. Supports JSON and XML serialization.

17 November 2022
API Reference 131

GeneratedAlert
Properties:

Name Type Comment

Compulsory bool True if this alert has stopped the generation of documents.
Message string The message to be shown.

Links:

None.

Remarks:

Alerts are defined in the templates, with a condition that triggers the alert. Compulsory alerts are ones that must
be resolved before documents can be produced. Supports JSON and XML serialization.

17 November 2022
132 Contract Express® API Manual

ContractHistory
Properties:

Name Type Comment

Id long Unique identifier for this ContractHistory event within the license
space.
ContractId long The Contract to which this event relates.
ApprovalTitle string Optional identifier of the Approval on Contract to which this event
relates.
ActionType string The type of event.
Title string A short title for this particular event.
Description string A longer description, giving details of this event.
CreatedAt DateTime The date and time this event occurred.
CreatedBy string The user responsible for triggering this event.
System bool True if this event only to be displayed to users in the admin role.
Deleted bool True if this event is no longer to be shown.

Links:

None.

Remarks:

A SystemHistory entity details some event that has occurred within the system that may be related to a Template.
Supports JSON and XML serialization.

17 November 2022
API Reference 133

InputDocument
Properties:

Name Type Comment

InputDocumentId long Unique identifier for this InputDocument.
ContractId long The id of the Contract for which this InputDocument was uploaded.
CreatedAt DateTime When the InputDocument was uploaded.
CreatedBy string The user who uploaded the InputDocument.
FileName string The file name associated with the InputDocument during upload.
ContentType string The content type of the uploaded document.

Links:

None.

Remarks:

An InputDocument is a document that is not known to have been generated by the answer set applied to the
templates for this Contract. It is usually a document for a source other than Contract Express that has been
uploaded in response to a file upload question in the questionnaire. Such document can be attached to the set of
generated documents, or for a limited subset of content types can be included in the wording of a generated
document. Supports JSON and XML serialization.

17 November 2022
134 Contract Express® API Manual

Invitation
Properties:

Name Type Comment

InvitationId long Unique identifier for this Invitation.
ContractId long The id of the Contract to which this is an Invitation.
CreatedAt DateTime When the Invitation was made.
CreatedBy string The user who made the Invitation.
Invitee string The display name for the recipient of the Invitation.
Email string The email address to which the Invitation was sent.
GuestId string The internal unique ID for this invitation that is used in the token issued
with the Invitation.
IsExpired bool True if this Invitation has expired.

Links:

None.

Remarks:

An Invitation to an external party to collaborate on a Contract. The invitation will be sent by email and will contain
a token granting that user access for a fixed period of time. Supports JSON and XML serialization.

17 November 2022
API Reference 135

Approval
Properties:

Name Type Comment

ContractId long Unique identifier for Contract with which this Approval is
associated.
Title string The name of this Approval, unique per Contract.
ContractName string The name of the associated Contract.
Order int The sequence number of this step.
Level int For future use.
Applicable bool True if this Approval is relevant for the Contract.
Required bool True if an approver will need to explicitly approve the
Contract.
PrimaryApprover string The user id of the primary approver.
Status string The internal identifier of the status of the Approval.
StatusLabel string The configurable display label for Status.
CreatedAt DateTime The date and time this approval was created.
ModifiedAt DateTime The date and time this approval was last modified.
EffectiveRight int The permission that the current user has on the Approval:
0 – None
1 – Read
2 – Write
3 – Full
Approvers List<AccessControlRule> The users and groups who can act as Approvers on this
Approval.

Links:

None.

Remarks:

An Approval entity tracks the application of an ApprovalStep to a particular Contract. There may be more than
one Approval per Contract. Supports JSON and XML serialization.

17 November 2022
136 Contract Express® API Manual

Folder
Properties:

Name Type Comment

FolderId int Unique identifier for this Folder within the license space.
ParentId int The identifier for the parent folder. Null if there is no parent.
Name string The name of the folder, which must be unique within the parent
folder.
ContentType byte 0 – Contract folder.
1 – Template folder (category)
Share byte 0 – Single user access
1 – Shared with other authenticated users
2 – Shared with unauthenticated guests
3 – Shared with both authenticated users and unauthenticated
guests
EffectiveRight int The permission that the current user has on the folder:
0 – None
1 – Read
2 – Write
3 – Full
Contracts List<Contract> Sometimes this property will be instantiated with data for any
Contract entities contained in this folder, to avoid additional round
trip to services.
SubFolders List<Folder> Sometimes this property will be instantiated with data for any
Folder entities contained in this folder, to avoid additional round
trip to services.

Links:

None.

Remarks:

Folders are arranged in a tree structure. A folder has at most one parent but can have zero or more sub-folders.
A folder with no parent is a "root" folder. Supports JSON and XML serialization.

17 November 2022
API Reference 137

Activity
Properties:

Name Type Comment

Who string A context appropriate identifier for the subject of some activity, for
example a user id.
What string A context appropriate identifier for the object of some activity, for
example a template reference.
HowMany int The number times it happened.

Links:

None.

Remarks:

Activity entities are used for simple reporting. For example, with contracts, it says how much (HowMany) a user
(Who) has used a template (What). Supports JSON, XML, and comma separated vale (CSV) serialization.

17 November 2022
138 Contract Express® API Manual

ActivatedPage
Properties:

Name Type Comment

readonly bool True if the activated page has been constructed on the assumption
that it does not need to respond to data changes.
Dictionary Dictionary That portion of the full consolidated dictionary that is needed to
support the current page. The dictionary elements will have been
partially evaluated in the light of existing answers.
Session AnswerSet That portion of the existing set of answers that is needed by the
current page.

Links:

Name Comment
self The request to refresh the current page.
previous The request to get the previous relevant page.
next The request to get the next relevant page.
first The request to get the first relevant page.
last The request to get the last relevant page.
answers The request to get the current full answer set.
documents The request to get the documents generated from the current answers.

Remarks:

The ActivatedPage is a representation of a questionnaire page. It can be serialized as XML or as JavaScript (not
JSON). Various elements of the dictionary are expressions, primarily to represent dynamic on page behavior. These
will be executable JavaScript if that serialization format is chosen, or Contract Express Mark-up Language in the
XML format.

17 November 2022
API Reference 139

TemplateInFolder
Properties:

Name Type Comment

TemplateInFolderId int The identifier for this association between a folder, a template and
a profile.
FolderId int The identity of the associated Folder.
TemplateReference string The identity of the associated Template.
ProfileReference string The identity of the associated Profile. This may be null is the
default profile is to be used.
Name string The name to present to the user for this combination.
Description string The description of this combination.

Links:

None.

Remarks:

TemplateInFolder entities are a way of presenting an underlying Template to a user as if it was a different
template, through the application of a Profile. You may choose to use a different name to refer to this combination
and provide a more specific description. Such combinations are also arranged into Folders, to make them easier
for a user to discover. Note that a user can only access a Template if they have access to the underlying Template
via its Access Contol List, and they have access to a Folder with which that Template is associated, according to
the Folder's Access Control List. Imagine a world in which there is only one Template, capable of generating any
document. Such a Template might require the user to answer an unreasonable number of questions.
TemplateInFolder structures allow a user to experience this one template as if it was a library of templates by
jump starting a session with a predefined sub-set of answers in the Profile. We poor mortals fall short of this ideal
and are only capable of writing approximations to this supreme Template, that cover some subset of all possible
documents, but even so the FolderInTemplate concept can still be useful. Supports JSON and XML serialization.

17 November 2022
140 Contract Express® API Manual

Profile
Properties:

Name Type Comment

ProfileReference string The identifier for this Profile in the License space.
Description string The description of this Profile.
ModifiedAt DateTime The date and time this Profile was last modified.
ModifiedBy string The name of the user who last modified this Profile.

Links:

None.

Remarks:

A profile is a collection of parameter settings that control various aspects of system behavior, and optionally some
answer values to question variables. The Profile entity holds a few metadata values for the profile itself, which is
represented in exactly the same format as an AnswerSet. Supports JSON and XML serialization.

17 November 2022
API Reference 141

ExternalTable
Properties:

Name Type Comment

Name string The name of the ExternalTable, which must be unique within the
License space.
Handler string One of a number of built in handlers required to access the external
table data. Currently supported are SQL, OData and SharePoint.
RowLimit int The maximum number of rows returned in a single read. Zero
means unlimited.
Server string Specification of the means of accessing the resource manager, so
for example a connection string for SQL data sources or the site URL
for OData.
Target string The name of the resource being accessed on the Server, so for SQL
the qualified name of the table or view, or for OData the name of
the resource collection.
Share byte 0 – Single user access
1 – Shared with other authenticated users
2 – Shared with unauthenticated guests
3 – Shared with both authenticated users and unauthenticated
guests
EffectiveRight int The permission that the current user has on the folder:
0 – None
1 – Read
2 – Write
3 – Full

Links:

None.

Remarks:

ExternalTable entities define the means of accessing some external managed tabular data source. Supports JSON
and XML serialization.

17 November 2022
142 Contract Express® API Manual

RecordSet
Properties:

See Remarks.

Links:

None.

Remarks:

A recordset is the result of an ExternalTable query. The recordset entity is only available as XML. It comprises a
root 'recordset' element with zero or more 'row' elements, each with one or more 'field' elements. The text value
of the field element is the value of that field of that row in the recordset. In this way it describes a tabular collection
of values. The XML schema (recordset.xsd) for a recordset accompanies this manual.

17 November 2022
API Reference 143

View
Properties:

See Remarks.

Links:

None.

Remarks:

A View defines a query that can be presented to an ExternalTable. The View entity is only represented as XML. It
is based for legacy reasons on a subset of the SharePoint CAML View schema (https://msdn.microsoft.com/en-
us/library/office/ms438338.aspx ). The XML Schema for the subset we use (camlsubset.xsd) accompanies this
manual.

17 November 2022
144 Contract Express® API Manual

EmailWording
Properties:

Name Type Comment

Name string The identifier for this EmailWording template in the License space.
Subject string The subject line for emails produced from this template.
Body string The body of emails produced from this template.

Links:

None.

Remarks:

EmailWording entity represents an email template used for generating certain emails. Currently two templates
are used by the system, named "User invitation into the system" and the other "Guest invitation to edit a
contract". The Subject and Body can contain fields that will be given a value appropriate to their context. Supports
JSON and XML serialization.

17 November 2022
API Reference 145

Licence
Properties:

Name Type Comment

Name string The name of the organization to whom the licence was issued.
ReadOnly bool For future use.
AllowGuests bool True if guest access is allowed under this licence.
VaryTerms bool True if the Terms of Service and Privacy Policy can be varied.
ValidTo DateTime The date and time at which the license expires.
UserLimit int The total number of users allowed under the licence.
UserCount int The number of users that are currently granted access to the system under
this license.

Links:

Name Comment
adverts The URL for the public page for this license, with links to "advertised" templates.

Remarks:

The Licence entity contains those properties enforced by the terms of the licence issued. This may be an
automatically generated trial licence or it may be a full licence issued by Thomson Reuters. Supports JSON and
XML serialization.

17 November 2022
146 Contract Express® API Manual

UserSettings
Properties:

Name Type Comment

UserId string The unique identifier for this user.
HomeFolderId int The folder that is the default folder in which Contracts are created by
this user.
Locale string The input locale used in questionnaires started by this user.
DateSequence string The year/month/day sequence to use when displaying dates.
TimeZone string For future use.
HasAgreedTerms bool True if the user is deemed to have agreed the terms of service.
HideWelcomeScreen bool True if this user will not see the Welcome screen at login.
Email string Email address for this user.
DisplayName string Friendly name for this user for display purposes.
HasNotices bool True if this use has un-acknowledged Notices.
LastNoticeId int The last Notice acknowledged by this user.
EasyRename bool True if this user is to be prompted to rename a Contract at the end of
the questionnaire.
AuthenticationMode string How this user authenticated with the system.
ShadowFBAUrl string The URL of shadow site configured for forms-based authentication.
AuthorUrl string The URL from which to download Contract Express Author.
AuthorizedActions List<Pair<string>> The list of action/resource pairs for which this user has been granted
authority.
LicenceSpace LicenceSpace Various configuration settings not specific to this user.

Links:

None.

Remarks:

The UserSettings entity represents user specific configuration settings. Supports JSON and XML serialization.

17 November 2022
API Reference 147

LicenceSpace
Properties:

Name Type Comment

Theme string The Theme to be applied for users in this LicenceSpace.
DefaultProfile string The default Profile to be used when creating a new Contract.
DefaultLocale string The default Locale to be applied to the UserSettings of new users to
this LicenceSpace.
DefaultTimeZone string For future use.
TermsOfService string URL to the Terms of Service.
PrivacyPolicy string URL to the Privacy Policy.
EmbeddingDomain string Pattern for determining which host is allowed to embed the
questionnaire. For example, "*.salesforce.com" means any host
ending ".salesforce.com" is acceptable.
TransientContracts bool True if Contracts should be automatically deleted on log out.
DefaultHomeFolder string Pattern used for creating a (non-guest) user's home folder at an
appropriate position in the overall tree of folders.
AutoAgreeTerms bool True if the end user is automatically deemed to have agreed terms.
UseCategories bool True if the template category functionality should be exposed in the
user interface.
ESignatureEnabled bool True if the eSignature functionality should be exposed in the user
interface.
TemplateAccess byte The default access to be granted to newly uploaded templates. 0 –
uploading user has full access, 1 – uploading user has full access and
authors have write access, and 2 – uploading user has full access,
authors have write access and users have read access.
TemplateView byte When creating a new document or invitation which template selection
tab should be displayed initially, 0 – All, 1 – Recent, or 2 – Category.

Links:

None.

Remarks:

The LicenceSpace entity represents configuration settings that affect all users covered by a particular license.
Supports JSON and XML serialization.

17 November 2022
148 Contract Express® API Manual

WelcomeScreen
Properties:

Name Type Comment

SubsiteName string Null indicates this is the welcome page for the main site, otherwise
this is the name of the subsite for which this welcome page is to
be shown.
Title string The title to be shown at the top of the welcome page.
Description string Some wording that is shown on the welcome page.
Video string An embedded video that can be viewed on the welcome page.
Link{N} string Link1 … Link10 are ten links to be included on the welcome page.
Each consists of some text to be displayed, followed by a
semicolon, followed by a URL.
WelcomeImages List<WelcomeImage> A number of images and captions to be displayed on the welcome
page. At most four images are allowed.

Links:

None.

Remarks:

The WelcomeScreen entity allows an administrator to configure a welcome screen with various useful resources
including some text, a video, some links to other resources and some images. Supports JSON and XML serialization.

17 November 2022
API Reference 149

WelcomeImage
Properties:

Name Type Comment

SubsiteName string Null indicates this is an image for the welcome page for the main
site, otherwise this is the name of the subsite for which this
welcome image is to be shown.
Sequence int Controls the order this image is shown relative to other images on
the same welcome screen.
Title string The caption for this image.
Description string Some wording that is shown alongside the image.

Links:

None.

Remarks:

The WelcomeImage entity holds the title and some descriptive text for an image to be shown on the welcome
screen. Supports JSON and XML serialization.

17 November 2022
150 Contract Express® API Manual

Notice
Properties:

Name Type Comment

NoticeId int Unique identifier for this Notice.
StartsAt DateTime The anticipated start date and time of the period this Notice
covers.
EndsAt DateTime The anticipated end date and time of the period this Notice covers.
Title string A short title to be displayed for this Notice.
Description string A longer description of the issue to which this Notice relates.
CreatedBy string The user who created this Notice.
Closed bool True if this Notice has been closed.
ReasonClosed string The reason, say "Completed" or "Postponed", for this Notice being
closed.
ClosedBy string The user that closed this Notice.

Links:

None.

Remarks:

The Notice entity describes some system wide event of which users need to be made aware. This might for
example be some downtime to allow for system upgrade or maintenance. The NoticeId is a monotonically
increasing value so that it is easy to track which Notices have been acknowledged by a given user. The properties
once saved are immutable as they must not change after a user has acknowledged them. Supports JSON and XML
serialization.

17 November 2022
Embedding the Questionnaire 155

5. Embedding the Questionnaire

5.1 Launching a Questionnaire

A questionnaire is launched by referencing the MVC page EditContract in some URL. The parameters that are
included in the URL determine which contract is edited and how it is edited.

The target of the URL can be a browser window itself, or it can be the SRC property of an HTML <IFRAME> element
that is embedded within a window.

5.1.1 URL Name=Value Parameters

The named parameters that determine which contract is edited and how it is edited are:

• ContractIdentifier

• ReadOnly

• Layout

• Format

• Color

• UserTheme

• IgnoreParent

• OnFinish

ContractIdentifier

This is a numeric value that uniquely identifies the contract within the license space.

This is the only parameter that must be included in the URL.

ReadOnly

This is a boolean value that specifies whether the edit is read-only; that is, when set to true it is effectively a review
of the contract values.

If this is not supplied, then the edit will be read-write.

Layout

This is a text value that determines how the editing elements, and in particular each page of the questionnaire,
are arranged. It is one of:

17 November 2022
156 Contract Express® API Manual

• Nelson A single column questionnaire that adapts to the width of the device.

• Standard Provides backwards compatibility with CEDB versions 4.4 and 4.5.

• Custom Used by clients with their own deployment of Contract Express.

If this is not supplied, then the layout will be Nelson.

Format

This is a text value that specifies the widest width boundary for the questionnaire HTML elements. It is one of:

• Wide For widths greater than 1024px.

• Trim For widths between 600px and 1024px, inclusive.

• Narrow For widths less than 600px.

If this is not supplied, then the format will be determined solely by the device. Similarly, if this is supplied but the
actual width of the device is not wide enough to support it then the format will also be determined by the device.

The format is used by the layout procedure. For example, the Nelson layout presents the potential questionnaire
pages as a static list to the left of the questions in Wide format but presents them as a popup list above the
questions in Trim and Narrow format.

Color

This is a text value that determines the color scheme. Different layouts support different color schemes:

• Nelson The only color scheme currently supported is:

LightBlue

• Standard The color schemes supported are:

GrayGray (default)
OrangeGray

• Custom For customized deployments the color schemes can also be

customized

UserTheme

This is a text value that determines certain user-specific variations, such as the color of the Previous/Next/Save &
Close icons so that they match the user's theme in Contract Express Cloud.

If this is not supplied, then there are no variations to the color scheme.

17 November 2022
Embedding the Questionnaire 157

IgnoreParent

This is a boolean value that is used only when the questionnaire is embedded within an <IFRAME> of some parent
window. When set to true the questionnaire behaves as if it were not within an <IFRAME> element but was within
the top window of the browser. In particular, no messages are posted to the parent window, and no messages
from the parent window are handled, as in section 5.1.3 (<IFRAME> does not communicate with Parent) below.

OnFinish

This is a numeric value that specifies what action to take when the user finishes editing the contract.

If the questionnaire is embedded within an <IFRAME> element that is communicating with its parent window, as
in 5.1.3 (<IFRAME> communicates with Parent) below, then this parameter is ignored. Otherwise:

• 0 Re-direct the browser's top window to:

public/ContractIdentifier/documents

• non-zero Re-direct the questionnaire's window to:

public/ContractIdentifier/documents?embed=simple

5.1.2 Target Window

When the target of the EditContract URL is the top window of a browser then the questionnaire adjusts the format
(wide/trim/narrow) according to the inner-width of that window and adjusts the height of the questionnaire
according to its inner-height.

5.1.3 Target <IFRAME>

When the target of the EditContract URL is an <IFRAME> element, its format (wide/trim/narrow) and its available
height are determined by whether or not the <IFRAME> element is communicating with its parent window.

<IFRAME> does not communicate with Parent

A questionnaire that is embedded within an <IFRAME> element does not attempt to communicate with its parent
window if the URL includes the parameter:

IgnoreParent = true

Its format (wide/trim/narrow) is determined by the inner-width of the <IFRAME> window, and its available height
is determined by that window's inner-height.

<IFRAME> communicates with Parent

A questionnaire that is embedded within an <IFRAME> element communicates with its parent window if the URL
includes the parameter:

IgnoreParent = false

17 November 2022
158 Contract Express® API Manual

Or if the parameter is not set.

Its format (wide/trim/narrow) is determined by the inner width of the <IFRAME> window, and its available height
is determined by the parent window's response when the height is requested.

The communication between the <IFRAME> element and its parent window is accomplished by posting messages.
Note that message posting is asynchronous. The JavaScript execution process in which a request-style message is
posted must terminate before any response-style message can be handled.

The messages posted are:

Event Message Text Description

When the SRC of the request:login:<token> Posted to the <IFRAME>
<IFRAME> element element by the parent
has been loaded. window.
The <token> is validated
before the questionnaire
sessions begins.
No response is expected.
When the user clicks request:save Posted to the <IFRAME>
some element in the element by the parent
parent window that window.
warrants termination
Requests Contract Express
of the questionnaire
to save, if possible, all data
session.
on the current
questionnaire page.
response:save:<notsaved> Posted to the parent
window by the <IFRAME>
element.
If the <notsaved> value is
blank, then all the data was
saved. Otherwise, the
<notsaved> value describes
why the data was not
saved.
When the SRC of the request:size Posted to the parent
<IFRAME> has been window by the <IFRAME>
request:size:fullwidth
loaded, or when the element.
size of the <IFRAME>
Requests the parent
element changes.
window for the initial height
and width of the <IFRAME>
element.

17 November 2022
Embedding the Questionnaire 159

Event Message Text Description

The fullwidth variant
indicates that the contract's
profile includes the value
db_full_width=true
response:size:<height>x<width> Posted to the <IFRAME>
element by the parent
window.
<height>, a non-negative
integer, is the height
allocated by the parent
window for the <IFRAME>
element.
<width>, a non-negative
integer, is the width
allocated by the parent
window for the <IFRAME>
element.
Periodically when request:scrolltotop Posted to the parent
refreshing window by the <IFRAME>
questionnaire pages, element.
swapping to preview
Requests that the parent
mode, etc..
window scrolls to its top
position (0,0).
No response is expected.
The user finishes the request:finish Posted to the parent
questionnaire. window by the <IFRAME>
element.
Informs the parent window
that the questionnaire
session has finished.
No response is expected.
request:finish:nopages There are no questionnaire
pages.
request:finish:<ErrorMessage> The questionnaire session
finished with an error.
The user's session has request:timeout Posted to the parent
already expired when window by the <IFRAME>
the user attempts element.
some further
The session has expired due
to a lack of user interaction.

17 November 2022
160 Contract Express® API Manual

Event Message Text Description

interaction with the Note that it is too late to
questionnaire. save any data.
No response is expected.

Examples of messages posted by the Parent window

<iframe-element>.contentWindow.postMessage( "request:login:Q32gKa8b", "*" ) ;

Examples of messages posted by the <IFRAME> element

window.parent.postMessage("response:save:", "*");
window.parent.postMessage("response:save:There are 4 errors on the questionnaire!", "*");
window.parent.postMessage("request:size", "*");
window.parent.postMessage("request:size:fullwidth", "*");
window.parent.postMessage("request:scrolltotop", "*");
window.parent.postMessage("request:finish", "*");
window.parent.postMessage("request:timeout", "*");

Example of a message handler defined in the Parent window

17 November 2022
Embedding the Questionnaire 161

function handlePostedMessage(_Event) {
var _MessageText = _Event.originalEvent.data;
var _MessageTextLower = _MessageText.toLowerCase();

// handle a response to original request save the data on the current questionnaire page
if (_MessageTextLower.substr(0, 14) === "response:save:") {
var _SaveResponseText = _MessageText.substr(14);
if (_SaveResponseText !== "") {
alert(_SaveResponseText);
}
}

// handle a request for the size of the IFRAME element

else if (_MessageTextLower === "request:size") {
var _IframeElement = ... ;
var _Height = ... ;
var _Width = ... ;
var _SizeResponseText = "response:size:" + _Height.toString() + "x" + _Width.toString();
_IframeElement.contentWindow.postMessage(_SizeResponseText, "*");
}

// handle a request for the size of the IFRAME element in full width mode
else if (_MessageTextLower === "request:size:fullwidth") {
var _IframeElement = ... ;
var _Height = ... ;
var _Width = ... ;
var _SizeResponseText = "response:size:" + _Height.toString() + "x" + _Width.toString();
_IframeElement.contentWindow.postMessage(_SizeResponseText, "*");
}

// handle a request to scroll to the top of this parent window

else if (_MessageTextLower === "request:scrolltotop") {
window.scrollTo(0, 0);
}

// handle a request when the user finishes the questionnaire

else if (_MessageTextLower === "request:finish") {
var _IframeElement = ... ;
_IframeElement.src = "";
}

// handle a request when the user's session expires

else if (_MessageTextLower === "request:timeout") {
...
}
}

5.2 Designing a Custom Questionnaire Layout

Those clients that have deployed an instance of Contract Express may, if they wish, design and style their own
questionnaire layout.

In the following sections, by way of example, the design of the Nelson layout is given. It shows what JavaScript
functions must be defined by the client in a custom layout, and which Contract Express interface functions are
used in that design. See section 5.4 (JavaScript Library) for a complete list of the interface functions.

In summary, the JavaScript functions which must be defined by a custom layout are:

17 November 2022
162 Contract Express® API Manual

Function Name Description

cetBuildSkeleton Build the HTML elements that are independent of any specific questionnaire
page.
This function is called by Contract Express during initialization, and
whenever the format changes.
cetBuildAlerts Build the HTML elements that represent all the potential alerts for a specific
questionnaire page, whether compulsory or not, and whether activated or
not.
This function is called by Contract Express on each inter-page navigation,
whenever the number of on-page repetitions varies, and whenever the
skeleton is re-built.
cetBuildQuestionnaire Build the HTML elements that represent a specific questionnaire page.
This function is called by Contract Express on each inter-page navigation,
whenever the number of on-page repetitions varies, and whenever the
skeleton is re-built.
cetOnPageLoad A callback from Contract Express whenever any questionnaire page has
been re-built and after its contents have been instantiated.
cetBuildRepeatGrid Build the HTML elements that represent a grid of repeated variables within
a questionnaire page.
This function may be called from the layout function cetBuildQuestionnaire,
and whenever the user explicitly edits the grid.
cetPreviewHeightAdjustment This function allows the layout to adjust (downwards) the height made
available for the preview document.
It might be used when the questionnaire and the preview document are laid
out one on top of the other.
cetPreviewWidthAdjustment This function allows the layout to adjust (downwards) the width made
available for the preview document.
It might be used when the questionnaire and the preview document are laid
out beside each other.
cetOnPreviewToggle A callback from Contract Express whenever the user toggles between
showing the preview document and hiding it. See the Nelson layout for an
example of its use.

17 November 2022
Embedding the Questionnaire 163

5.2.1 Nelson Layout

This questionnaire layout adapts itself according to the available width of the device.

In narrow format (less than 600px) preview is not available.

In trim format (between 600px and 1024px) the preview document appears underneath the questionnaire.

In wide format (more than 1024px) the preview document appears to the right of the questionnaire.

In all formats the variables are arranged in a single column occupying the full width available, with the variable
prompt appearing above the input value, and the guidance appearing below.

5.2.2 Building a Skeleton

This function is called by Contract Express during initialization and whenever the format changes. Its purpose is to
build the HTML elements that are independent of any specific questionnaire page.

Part of the procedure will be locating the alerts, locating the questionnaire, and locating any preview document.

// Function Call : cetBuildSkeleton( html-element, integer, string, boolean )

// Return Type : void

function cetBuildSkeleton(_HostElement, _HostWidth, _Format, _PreviewEnabled)

{

Firstly, preview will only be made available in wide or trim format, and when preview has been enabled.

var _PreviewVisible = ((_Format === "wide" || _Format === "trim") && _PreviewEnabled);

The following two JavaScript variables will be instantiated to HTML elements where the questionnaire and the
preview document will be located, respectively.
var _QuestionnaireLocation = null;
var _PreviewLocation = null;

The top and bottom divisions

The overall structure consists of a top <DIV> for the actionable items, and a bottom <DIV> which will contain the
contract details. Note that new <DIV> elements are created using the general interface function CreateElement.
var _StructuralTop = ContractExpress.CreateElement(_HostElement, "DIV", {});
var _StructuralBottom = ContractExpress.CreateElement(_HostElement, "DIV", {});

The top division

The first element in the top <DIV> informs the user that the contract is read-only. Note this uses the interface
function CreateReadOnlyButton, and the message will only appear if the contract is indeed read-only.

ContractExpress.CreateReadOnlyButton(_StructuralTop, "DIV", {});

17 November 2022
164 Contract Express® API Manual

The next elements in the top <DIV> are the inter-page navigation buttons which use the interface functions
CreatePreviousPageButton and CreateNextPageButton, respectively. They each have an associated icon which is
created by the interface function CreateIcomoon. Note that these buttons will automatically enable/disable
depending upon the circumstances.
ContractExpress.CreateIcomoon(_StructuralTop, "SPAN", { icon: "ArrowLeft" });
ContractExpress.CreatePreviousPageButton(_StructuralTop, "A", {});
ContractExpress.CreateIcomoon(_StructuralTop, "SPAN", { icon: "ArrowRight" });
ContractExpress.CreateNextPageButton(_StructuralTop, "A", {});

The next element in the top <DIV> is the button which toggles the visibility of the preview document, and which
uses the interface function CreatePreviewToggle.
if (_PreviewVisible) {
ContractExpress.CreateIcomoon(_StructuralTop, "SPAN", { icon: "Document" });
ContractExpress.CreatePreviewToggle(_StructuralTop, "A", {});
}

The final element in the top <DIV> is the button to terminate the session, which uses the interface function
CreateFinishButton.
ContractExpress.CreateIcomoon(_StructuralTop, "SPAN", { icon: "Template" });
ContractExpress.CreateFinishButton(_StructuralTop, "A", {});

The bottom division: narrow format

The bottom division in narrow format is entirely devoted to the questionnaire, as preview is not available.
if (_Format === "narrow") {
_QuestionnaireLocation = _StructuralBottom;
}

The bottom division: trim format

The bottom division in trim format has the questionnaire above the preview document, with a draggable resizer
between them to change their relative heights. This whole arrangement is accomplished using the interface
function CreateResizer.
else if (_Format === "trim") {
var _Resizer = ContractExpress.CreateResizer(_StructuralBottom, "Resizer", false, false);
_QuestionnaireLocation = _Resizer.top;
_PreviewLocation = _Resizer.bottom;
}

The bottom division: wide format

In wide format the bottom division consists of a left <DIV> for the progress information and alerts, and a right
<DIV> for both the questionnaire and the preview document. When the preview document is made visible, the
left <DIV> is hidden and the right <DIV> expands leftwards to fill the void.
else if (_Format === "wide") {
NelsonElementWideLeft = ContractExpress.CreateElement(_StructuralBottom, "DIV", {});
NelsonElementWideRight = ContractExpress.CreateElement(_StructuralBottom, "DIV", {});
}

The first element at the top of the left <DIV> is a question progress bar, which uses the interface function
CreateQuestionProgressBar.

17 November 2022
Embedding the Questionnaire 165

ContractExpress.CreateQuestionProgressBar(NelsonElementWideLeft, "DIV", {});

Immediately below is a list of all the questionnaire pages, which uses the interface function
CreatePageNavigationList.

ContractExpress.CreatePageNavigationList(NelsonElementWideLeft, "DIV", {});

The final element at the bottom of the left <DIV> is a placeholder where alerts are raised. This uses the interface
function SetAlertsLocation.
var _AlertsDiv = ContractExpress.CreateElement(NelsonElementWideLeft, "DIV", {});
ContractExpress.SetAlertsLocation(_AlertsDiv);

The right <DIV> has the questionnaire to the left of the preview document, with a draggable resizer between them
to change their relative widths. This whole arrangement is accomplished using the interface function
CreateResizer.
var _Resizer = ContractExpress.CreateResizer(NelsonElementWideRight, "Resizer", true, false);
_QuestionnaireLocation = _Resizer.left;
_PreviewLocation = _Resizer.right;

The questionnaire

The questionnaire's location is set using the interface function SetQuestionnaireLocation.

ContractExpress.SetQuestionnaireLocation(_QuestionnaireLocation);

The preview document

If the preview document is available, then its location is set using the interface function SetPreviewLocation.
if (_PreviewVisible) {
ContractExpress.SetPreviewLocation(_PreviewLocation);
}

The preview host element consists of a static area that does not scroll sitting above the scrollable document
wording, and which uses the interface function CreatePreviewDocument.
var _PreviewBar = ContractExpress.CreateElement(_PreviewLocation, "DIV", {});
ContractExpress.CreatePreviewDocument(_PreviewLocation, "DIV", {});

The first element in the static area holds any attachment documents that may also be previewed, together with
buttons for tabbing between them. This uses the interface function CreatePreviewDocumentTabGroup.

ContractExpress.CreatePreviewDocumentTabGroup(_PreviewBar, "DIV", {});

The remaining elements in the static area are buttons for navigating between occurrences of the selected variable
in the document wording. These use the interface functions CreatePreviewOccurrencePrevious,
CreatePreviewOccurrenceNumber, and CreatePreviewOccurrenceNext.
ContractExpress.CreatePreviewOccurrencePrevious(_PreviewBar, "SPAN", { icomoon: { icon: "ArrowLeft" } });
ContractExpress.CreatePreviewOccurrenceNumber(_PreviewBar, "SPAN", {});
ContractExpress.CreatePreviewOccurrenceNext(_PreviewBar, "SPAN", { icomoon: { icon: "ArrowRight" } });

17 November 2022
166 Contract Express® API Manual

5.2.3 Building the Alerts

Recall that the location of the alerts was established when building the skeleton.

This function is called by Contract Express on each inter-page navigation, whenever the number of on-page
repetitions varies, and whenever the skeleton is re-built.

// Function Call : cetBuildAlerts( html-element )

// Return Type : void

function cetBuildAlerts(_HostElement)
{

The list of alerts may vary from one questionnaire page to the next, depending upon which variables are
mentioned in those alerts. This list is provided by Contract Express using the interface function
AllAlertsOnThisPage.

var ALERTOBJECTS = ContractExpress.AllAlertsOnThisPage();

The Nelson layout lists all compulsory alerts above any non-compulsory alerts. The test uses the interface function
AlertIsCompulsory and the alert itself uses the interface function CreateAlert.

Firstly, the compulsory alerts are created.

for (var aindex in ALERTOBJECTS) {
var ALERTOBJECT = ALERTOBJECTS[aindex];

if (ContractExpress.AlertIsCompulsory(ALERTOBJECT)) {
ContractExpress.CreateAlert(_HostElement, "DIV", { icomoon: { icon: "Error" } }, ALERTOBJECT);
}
}

Secondly, the non-compulsory alerts are created.

for (var aindex in ALERTOBJECTS) {
var ALERTOBJECT = ALERTOBJECTS[aindex];

if (!ContractExpress.AlertIsCompulsory(ALERTOBJECT)) {
ContractExpress.CreateAlert(_HostElement, "DIV", { icomoon: { icon: "Error" } }, ALERTOBJECT);
}
}

5.2.4 Building the Questionnaire

Recall that the location of the questionnaire was established when building the skeleton.

This function is called by Contract Express on each inter-page navigation, whenever the number of on-page
repetitions varies, and whenever the skeleton is re-built.

In addition to the format parameter, the function is also parameterized with the actual width allocated to the
questionnaire. This additional information is provided if the custom layout wishes to be more precise about how
questionnaires are constructed.

17 November 2022
Embedding the Questionnaire 167

// Function Call : cetBuildQuestionnaire( html-element, integer, string )

// Return Type : void

function cetBuildQuestionnaire(_HostElement, _HostWidth, _Format)

{

Page Title

Recall that the list of questionnaire pages, including the currently selected questionnaire page, is only made visible
in wide format. And so, the questionnaire begins with the page title for trim and narrow formats using the
interface function CreatePageTitle.

if (_Format === "trim" || _Format === "narrow") {

ContractExpress.CreatePageTitle(_HostElement, "H1", {});
}

Page Guidance

The next element in the questionnaire is the page guidance, if it exists, using the interface functions
PageGuidanceExists, and CreatePageGuidance.

if (ContractExpress.PageGuidanceExists()) {
ContractExpress.CreatePageGuidance(_HostElement, "DIV", { icomoon: { icon: "Info" } });
}

Alerts

Recall that the alerts are only located in wide format. And so, for trim and narrow formats, the alerts are explicitly
added to the questionnaire by calling the layout function cetBuildAlerts.

if (_Format === "trim" || _Format === "narrow") {

var _AlertsDiv = ContractExpress.CreateElement(_HostElement, "DIV", {});
cetBuildAlerts(_AlertsDiv);
}

Groups

A questionnaire page consists of a collection of variables that are partitioned into distinct groups. The list of groups
is provided by Contract Express using the interface function AllGroupsOnThisPage.

var GROUPOBJECTS = ContractExpress.AllGroupsOnThisPage();

for (var gindex in GROUPOBJECTS) {

var GROUPOBJECT = GROUPOBJECTS[gindex];
}

Group Title

Each group begins with the group title using the interface function CreateGroupTitle.

var _GroupTitle = ContractExpress.CreateGroupTitle(_HostElement, "H2", {}, GROUPOBJECT);

Group Guidance

The group title is followed by any group guidance using the interface functions GroupGuidanceExists and
CreateGroupGuidance.

17 November 2022
168 Contract Express® API Manual

if (ContractExpress.GroupGuidanceExists(GROUPOBJECT)) {
ContractExpress.CreateGroupGuidance(_HostElement, "DIV", {}, GROUPOBJECT);
}

Grid of Repetitions

If the group contains repeated variables and its presentation is in the form of a grid, either repeating across or
repeating down, then the values of those variables are laid out as a read-only table with an explicit button that
enables the user to edit them separately. This uses the interface functions GroupIsRepeatedGridAcross,
GroupIsRepeatedGridDown and CreateRepetitionGridEditButton, and calls the layout function
cetBuildRepeatGrid defined in section 5.2.5 (Building a Repetition Grid) below. Note that the edit button occurs
alongside the group title.

if (ContractExpress.GroupIsRepeatedGridAcross(GROUPOBJECT)
|| ContractExpress.GroupIsRepeatedGridDown(GROUPOBJECT)) {
ContractExpress.CreateRepetitionGridEditButton(_GroupTitle, "A", {}, GROUPOBJECT);
cetBuildRepeatGrid(_HostElement, false, false, 0, GROUPOBJECT);
}

Group Repetitions

Whether or not the variables in a group are actually repeated, Contract Express assumes that groups always have
repetitions. The test for whether or not a repetition of a group contains repeated variables uses the interface
function ActualRepetition.

The list of repetitions of a group is provided by Contract Express using the interface function
AllRepetitionsOfThisGroup.

else
{
var REPETITIONOBJECTS = ContractExpress.AllRepetitionsOfThisGroup(GROUPOBJECT);

for (var rindex in REPETITIONOBJECTS) {

var REPETITIONOBJECT = REPETITIONOBJECTS[rindex];

Repetition Title

The title of a particular repetition of a group, together with the navigation and management buttons, is conditional
upon it actually having some repeated variables. This uses the interface functions ActualRepetition,
CreateRepetitionTitle, CreateRepetitionNavigationButtons, and CreateRepetitionManagementButtons.

if (ContractExpress.ActualRepetition(REPETITIONOBJECT)) {
var _RepeatHeader = ContractExpress.CreateElement(_HostElement, "DIV", {});
ContractExpress.CreateRepetitionTitle(_RepeatHeader, "H3", {}, REPETITIONOBJECT);
ContractExpress.CreateRepetitionNavigationButtons(_RepeatHeader, "DIV", {}, REPETITIONOBJECT);
ContractExpress.CreateRepetitionManagementButtons(_RepeatHeader, "DIV", {}, REPETITIONOBJECT);
}

Variables

The list of variables in a repetition, whether or not they are actually repeated, is provided by Contract Express
using the interface function AllVariablesInThisRepetition.

17 November 2022
Embedding the Questionnaire 169

var VARIABLEOBJECTS = ContractExpress.AllVariablesInThisRepetition(REPETITIONOBJECT);

for (var vindex in VARIABLEOBJECTS) {

var VARIABLEOBJECT = VARIABLEOBJECTS[vindex];

Variable Body

The components of a variable consist of its preamble text, its prompt text, its guidance text, its input values, and
an area for reporting invalid values. These are collected together using the interface function CreateVariableBody.
When a variable becomes relevant or irrelevant, or when a variable is selected by a mouse click or tab operation,
it is the complete variable body that is re-styled.

var _VariableBody = ContractExpress.CreateVariableBody(_HostElement, "DIV", {}, VARIABLEOBJECT);

Variable Preamble

A variable begins with any preamble text using the interface functions VariablePreambleExists and
CreateVariablePreamble.

if (ContractExpress.VariablePreambleExists(VARIABLEOBJECT)) {
ContractExpress.CreateVariablePreamble(_VariableBody, "DIV", {}, VARIABLEOBJECT);
}

Variable Validation

The area reserved for validation messages occurs above the other components and uses the interface function
CreateVariableValidation.

ContractExpress.CreateVariableValidation(_VariableBody, "DIV", { icomoon: { icon: "Error" } }, VARIABLEOBJECT);

Variable Prompt

The next component is the variable's prompt text which uses the interface function CreateVariablePrompt.

ContractExpress.CreateVariablePrompt(_VariableBody, "DIV", {}, VARIABLEOBJECT);

Variable Value

The next component is the variable's input elements which uses the interface function CreateVariableValue.

ContractExpress.CreateVariableValue(_VariableBody, "DIV", {}, VARIABLEOBJECT);

Variable Guidance

The final component is the variable's guidance text which uses the interface functions VariableGuidanceExists
and CreateVariableGuidance.

if (ContractExpress.VariableGuidanceExists(VARIABLEOBJECT)) {
ContractExpress.CreateVariableGuidance(_VariableBody, "DIV", {}, VARIABLEOBJECT);
}

17 November 2022
170 Contract Express® API Manual

Finally, at the bottom of the questionnaire is a replica button for navigating to the next questionnaire page. It uses
the interface functions NextPageExists, CreateNextPageButton, and CreateFinishButton.

if (ContractExpress.NextPageExists()) {
ContractExpress.CreateNextPageButton(_HostElement, "A", {});
}
else {
ContractExpress.CreateFinishButton(_HostElement, "A", {});
}

OnPageLoad

Immediately after the questionnaire page has been constructed, and when all variable values have been assigned,
and when all effects have been processed, Contract Express calls back to the layout. This gives the layout an
opportunity to process its own effects, such as re-styling elements.

// Function Call : cetOnPageLoad( string, boolean )

// Return Type : void

function cetOnPageLoad(_Format, _PreviewVisible) {

5.2.5 Building a Repetition Grid

This function may be called from the layout function cetBuildQuestionnaire, and whenever the user explicitly edits
the grid.

When called from cetBuildQuestionnaire, the host element for the grid will be within the questionnaire itself. For
a user edit the host element will be a modal-style <DIV> that occupies the full width and height of the <IFRAME>,
and which contains a button to close the edit. Upon a close the questionnaire is re-drawn and scrolled to its
original position before the edit.

// Function Call : cetBuildRepeatGrid( element, boolean, boolean, integer, object )

// Return Type : void

function cetBuildRepeatGrid(_HostElement, _EditEnabled, _CloseEnabled, _OnCloseScrollTo, GROUPOBJECT)

{

Group Title, Group Guidance and Close Button

When the grid is hosted in the modal-style <DIV> it is headed by the group title, group guidance and a close button
using the interface functions CreateGroupTitle, GroupGuidanceExists, CreateGroupGuidance and
CreateRepetitionGridCloseButton.

if (_CloseEnabled) {
var _GroupTitle = ContractExpress.CreateGroupTitle(_HostElement, "H2", {}, GROUPOBJECT);

ContractExpress.CreateRepetitionGridCloseButton(_GroupTitle, "A", {}, _OnCloseScrollTo);

if (ContractExpress.GroupGuidanceExists(GROUPOBJECT)) {
ContractExpress.CreateGroupGuidance(_HostElement, "DIV", {}, GROUPOBJECT);
}
}

17 November 2022
Embedding the Questionnaire 171

Group Repetitions

The list of repetitions of a group is provided by Contract Express using the interface function
AllRepetitionsOfThisGroup.

var REPETITIONOBJECTS = ContractExpress.AllRepetitionsOfThisGroup(GROUPOBJECT);

Group Variables

The list of variables in a group is arbitrarily found in the first repetition using the interface function
AllVariablesInThisRepetition.

var GROUPVAROBJECTS = ContractExpress.AllVariablesInThisRepetition(REPETITIONOBJECTS[0]);

Grid <TABLE>

The grid, whether repeating down or repeating across, is laid out as a <TABLE> using the interface function
CreateElement.

var _GridTable = ContractExpress.CreateElement(_HostElement, "TABLE", {});

var _GridTableRow;
var _GridRowCell;
var _GridCellDiv;

Repeat Down

The test for a grid which repeats down the table uses the interface function GroupIsRepeatedGridDown.

if (ContractExpress.GroupIsRepeatedGridDown(GROUPOBJECT))
{

Repeat Down - Variable Prompt

The first row contains the prompts for all the variables and uses the interface functions CreateElement and
CreateVariablePrompt.

_GridTableRow = ContractExpress.CreateElement(_GridTable, "TR", {});

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});
for (var vindex in GROUPVAROBJECTS) {
var GROUPVAROBJECT = GROUPVAROBJECTS[vindex];
_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});
ContractExpress.CreateVariablePrompt(_GridRowCell, "DIV", {}, GROUPVAROBJECT);
}

Repeat Down - Repetition Rows

The intermediate rows contain the repetitions using the interface function CreateElement.

for (var rindex in REPETITIONOBJECTS) {

var REPETITIONOBJECT = REPETITIONOBJECTS[rindex];

_GridTableRow = ContractExpress.CreateElement(_GridTable, "TR", {});

17 November 2022
172 Contract Express® API Manual

Repeat Down - Repetition Title and Management

Each row begins with the title of a particular repetition of a group using the interface function
CreateRepetitionTitle.

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});

var _RepeatHeader = ContractExpress.CreateElement(_GridRowCell, "DIV", {});
ContractExpress.CreateRepetitionTitle(_RepeatHeader, "H3", {}, REPETITIONOBJECT);

Repetitions are only inserted and deleted from the questionnaire itself, and not when the user is editing values.
This uses the interface function CreateRepetitionManagementButtons.

if (!_CloseEnabled) {
ContractExpress.CreateRepetitionManagementButtons(_RepeatHeader, "DIV", {}, REPETITIONOBJECT);

Repeat Down - Variable Value

The other columns of a repetition contain the input elements for each of the variables, using the interface
functions AllVariablesInThisRepetition and the layout function cetBuildRepeatGridVariableValue.

var VARIABLEOBJECTS = ContractExpress.AllVariablesInThisRepetition(REPETITIONOBJECT);

for (var vindex in VARIABLEOBJECTS) {
var VARIABLEOBJECT = VARIABLEOBJECTS[vindex];
cetBuildRepeatGridVariableValue(_GridTableRow, _EditEnabled, VARIABLEOBJECT);
}

Repeat Down - Variable Guidance

The last row contains the guidance for all the variables and uses the interface functions CreateElement and
CreateVariableGuidance.

_GridTableRow = ContractExpress.CreateElement(_GridTable, "TR", {});

Repeat Across

The test for a grid which repeats across the table uses the interface function GroupIsRepeatedGridAcross.

else if (ContractExpress.GroupIsRepeatedGridAcross(GROUPOBJECT))
{

Repeat Across - Repetition Title and Management

The first row contains all the repetition titles using the interface function CreateRepetitionTitle.

17 November 2022
Embedding the Questionnaire 173

_GridTableRow = ContractExpress.CreateElement(_GridTable, "TR", { className: "Grid" });

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", { className: "Grid" });
for (var rindex in REPETITIONOBJECTS) {
var REPETITIONOBJECT = REPETITIONOBJECTS[rindex];

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});

_GridCellDiv = ContractExpress.CreateElement(_GridRowCell, "DIV", {});

var _RepeatHeader = ContractExpress.CreateElement(_GridCellDiv, "DIV", {});

ContractExpress.CreateRepetitionTitle(_RepeatHeader, "H3", {}, REPETITIONOBJECT);
}

Repetitions are only inserted and deleted from the questionnaire itself, and not when the user is editing values.
This uses the interface function CreateRepetitionManagementButtons.

if (!_CloseEnabled) {
ContractExpress.CreateRepetitionManagementButtons(_RepeatHeader, "DIV", {}, REPETITIONOBJECT);
}

Repeat Across - Variables

The other rows contain the prompt, values, and guidance for each of the repetition variables in the repetition.

for (var vindex in GROUPVAROBJECTS) {

var GROUPVAROBJECT = GROUPVAROBJECTS[vindex];

_GridTableRow = ContractExpress.CreateElement(_GridTable, "TR", {});

Repeat Across - Variable Prompt

Each row begins with the variable prompt using the interface function CreateVariablePrompt.

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});

ContractExpress.CreateVariablePrompt(_GridRowCell, "DIV", {}, GROUPVAROBJECT);

Repeat Across - Variable Value

The intermediate columns of contain the input elements for each of the variables, using the interface functions
AllVariablesInThisRepetition and the layout function cetBuildRepeatGridVariableValue.

for (var rindex in REPETITIONOBJECTS) {

var REPETITIONOBJECT = REPETITIONOBJECTS[rindex];
var VARIABLEOBJECTS = ContractExpress.AllVariablesInThisRepetition(REPETITIONOBJECT);
var VARIABLEOBJECT = VARIABLEOBJECTS[vindex];
cetBuildRepeatGridVariableValue(_GridTableRow, _EditEnabled, VARIABLEOBJECT);
}

Repeat Across - Variable Guidance

Each row ends with the variable guidance using the interface function CreateVariableGuidance.

_GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TH", {});

ContractExpress.CreateVariableGuidance(_GridRowCell, "DIV", {}, GROUPVAROBJECT);

Variable Value

This subsidiary function in the layout definition is used by grids that repeat down and grids that repeat across.

17 November 2022
174 Contract Express® API Manual

function cetBuildRepeatGridVariableValue(_GridTableRow, _EditEnabled, VARIABLEOBJECT) {

var _GridRowCell = ContractExpress.CreateElement(_GridTableRow, "TD", {});

Variable Value - Read Only

When editing of the grid is not enabled the table cell contains the formatted value of the variable. This uses the
interface function GetVariableValueFormatted.

if (!_EditEnabled) {
var _ValueText = ContractExpress.GetVariableValueFormatted(VARIABLEOBJECT)
} ) ;

ContractExpress.CreateElement(_GridCellDiv, "SPAN", { innerText: _ValueText });

Variable Value - Read Write

When editing of the grid is enabled the table cell contains the input elements for the variable. This uses the
interface function CreateVariableValue.

else
{
ContractExpress.CreateVariableValue(_GridRowCell, "DIV", {}, VARIABLEOBJECT);
}

5.2.6 Adjusting the Preview Document

These two functions allow the layout to adjust (downwards) the height and width made available for the preview
document.
// Function Call : cetPreviewHeightAdjustment( string, boolean )
// Return Type : integer

function cetPreviewHeightAdjustment(_Format, _PreviewVisible) {

return (_Format === "wide" && _PreviewVisible === true ? 1
: _Format === "wide" && _PreviewVisible === false ? 0
: _Format === "trim" && _PreviewVisible === true ? 1
: _Format === "trim" && _PreviewVisible === false ? 0
: _Format === "narrow" && _PreviewVisible === true ? 1
: _Format === "narrow" && _PreviewVisible === false ? 0
: 0);
}

// Function Call : cetPreviewWidthAdjustment( string, boolean )

// Return Type : integer

function cetPreviewWidthAdjustment(_Format, _PreviewVisible) {

return (_Format === "wide" && _PreviewVisible === true ? 14
: _Format === "wide" && _PreviewVisible === false ? 0
: _Format === "trim" && _PreviewVisible === true ? 0
: _Format === "trim" && _PreviewVisible === false ? 0
: _Format === "narrow" && _PreviewVisible === true ? 0
: _Format === "narrow" && _PreviewVisible === false ? 0
: 0);

A callback from Contract Express whenever the user toggles between showing the preview document and hiding
it.

17 November 2022
Embedding the Questionnaire 175

// Function Call : cetOnPreviewToggle( string, boolean )

// Return Type : integer

function cetOnPreviewToggle(_Format, _PreviewVisible) {

5.3 Styling a Custom Questionnaire Layout

5.3.1 Style Properties

In addition to the regular style properties, such as TextAlign, the following bespoke properties are also supported
when creating HTML elements:

Icomoon

Create a child element that is an icon in the Icomoon font.

For example

ContractExpress.CreateElement(_, "A", { icomoon: { icon: "Help" }, innerText: "Help" });

Disabled

Create a disabled element.

For example

ContractExpress.CreateElement(_, "INPUT", { disabled: true });

Creates the HTML element

<INPUT DISABLED />

Checked

Create a checked element.

OnClickShowHideToggle

Create an element such that a user click will toggle the visibility of some other element.

For example

ContractExpress.CreateElement(_, "SPAN", { onClickShowHideToggle: "foo", innerText: "Show foo" });

Creates the HTML element

<SPAN onClick="...('foo')">Toggle foo</SPAN>

TrackMouse

Track mouse movements over the element created.

If it is an <IMG> element or an <INPUT> element with type IMAGE, then the SRC property of the element will be
extended:

OnMouseOver ".rollover"

OnMouseDown ".rolldown"

OnMouseUp ".enabled"

OnMouseOut ".enabled"

For example

ContractExpress.CreateElement(_, "IMG", { src: "foo.enabled.gif", trackMouse: true });

Creates the HTML element

<IMG SRC="foo.enabled.gif" onMouseOver="...(this,'rollover') onMouseDown="...(this, 'rolldown') onMouseUp=

"...(this,'enabled')" onMouseOut= "...(this,'enabled')" ></IMG >

For all other elements the class is extended:

OnMouseOver "MouseOver"

OnMouseDown "MouseDown"

OnMouseUp "MouseOver"

OnMouseOut ""

For example

ContractExpress.CreateElement(_, "SPAN", { trackMouse: true });

Creates the HTML element

17 November 2022
Embedding the Questionnaire 179

<SPAN onMouseOver="...(this,'MouseOver') onMouseDown="...(this, 'MouseDown') onMouseUp= "...(this,'MouseOver')"

onMouseOut= "...(this,'')" ></SPAN >

5.3.2 Convention for ClassNames

Some of the interface functions which create HTML elements actually create multiple elements.

For example, the interface function CreateQuestionProgressBar actually creates two HTML elements,
representing the bar itself plus a child HTML element representing the percentage progress. In this case, the class
name of the child element will be the class name of the bar element concatenated with the text "Meter". The
function call:

ContractExpress.CreateQuestionProgressBar(_, "DIV", { className: "MyQuestionProgress" });

Will create the HTML elements

Furthermore, some of the elements are volatile and their change of appearance should reflect that volatility.

For example, the function call:

ContractExpress.CreateVariableBody(_, "DIV", { className: "MyVariable" });

Will create the HTML elements

When that variable is selected by the user, the class name is modified:

When that variable becomes irrelevant due to other values on the questionnaire, the class name is modified again:

The following table lists all the helper functions which create multiple HTML elements or volatile elements,
together with their corresponding class name extensions.

17 November 2022
180 Contract Express® API Manual

Function Class Name Extension Descendant Element

CreatePageNavigationSelector Complete The OPTION element represents a
questionnaire page which is
complete.
Incomplete The OPTION element represents a
questionnaire page which is
incomplete.
Irrelevant The OPTION element represents a
questionnaire page which is
irrelevant.
CreatePageNavigationList First The element represents the first
questionnaire page.
ThisPage The element represents the
current questionnaire page.
Complete The element represents some
other questionnaire page which is
complete.
Incomplete The element represents some
other questionnaire page which is
incomplete.
Irrelevant The element represents some
other questionnaire page which is
irrelevant.
CreateQuestionProgressBar Meter Represents the percentage
progress through the
questionnaire.
CreateGroupBody DisabledHidden All the variables in the group are
irrelevant and
db_disabled=hidden.
DisabledGhosted All the variables in the group are
irrelevant and
db_disabled=ghosted.
CreateGroupTitle DisabledHidden All the variables in the group are
irrelevant and
db_disabled=hidden.
DisabledGhosted All the variables in the group are
irrelevant and
db_disabled=ghosted.

17 November 2022
Embedding the Questionnaire 181

Function Class Name Extension Descendant Element

CreateGroupGuidance DisabledHidden All the variables in the group are
irrelevant and
db_disabled=hidden.
DisabledGhosted All the variables in the group are
irrelevant and
db_disabled=ghosted.
CreateRepetitionBody DisabledHidden All the variables in this repetition
of the group are irrelevant and
db_disabled=hidden.
DisabledGhosted All the variables in this repetition
of the group are irrelevant and
db_disabled=ghosted.
CreateRepetitionTitle DisabledHidden All the variables in this repetition
of the group are irrelevant and
db_disabled=hidden.
DisabledGhosted All the variables in this repetition
of the group are irrelevant and
db_disabled=ghosted.
CreateRepetitionNavigationButton Number The SPAN element that contains
s the repetition number. e.g. 3 of 6
Disabled All the variables in this repetition
of the group are irrelevant and
db_disabled=ghosted.
CreateRepetitionManagementButt Disabled All the variables in this repetition
ons of the group are irrelevant and
db_disabled=ghosted.
CreateVariableBody Invalid The variable has an invalid value.
Selected The variable is the currently
selected variable.
DisabledHidden The variable is irrelevant and
db_disabled=hidden.
DisabledGhosted The variable is irrelevant and
db_disabled=ghosted.
CreateVariablePreamble DisabledHidden The variable is irrelevant and
db_disabled=hidden.
DisabledGhosted The variable is irrelevant and
db_disabled=ghosted.

17 November 2022
182 Contract Express® API Manual

Function Class Name Extension Descendant Element

More <More...>...</More> occurs in the
variable's preamble text.
CreateVariablePrompt Compulsory The compulsory symbol (*)
element after the prompt.
DisabledHidden The variable is irrelevant and
db_disabled=hidden.
DisabledGhosted The variable is irrelevant and
db_disabled=ghosted.
More <More...>...</More> occurs in the
variable's prompt text.
CreateVariableGuidance DisabledHidden The variable is irrelevant and
db_disabled=hidden.
DisabledGhosted The variable is irrelevant and
db_disabled=ghosted.
More <More...>...</More> occurs in the
variable's guidance text.
CreateVariableValue DisabledHidden The variable is irrelevant and
db_disabled=hidden.
DisabledGhosted The variable is irrelevant and
db_disabled=ghosted.
Committed The variable's value has been
committed.
UnknownCommitted The variable has an unknown
value which has been committed.
CommittedDisabledHidden The variable is irrelevant and
db_disabled=hidden and its value
has been committed.
CommittedDisabledGhosted The variable is irrelevant and
db_disabled=ghosted and its value
has been committed.
UnknownCommittedDisabledHid The variable is irrelevant and
den db_disabled=ghosted and it has an
unknown value which has been
committed.
UnknownCommittedDisabledGho The variable is irrelevant and
sted db_disabled=hidden and it has an
unknown value which has been
committed.

17 November 2022
Embedding the Questionnaire 183

Function Class Name Extension Descendant Element

Checkbox The variable's type is a boolean
and its presentation is a single
checkbox.
CheckboxDisabled The variable is irrelevant, and its
type is a boolean and its
presentation is a single checkbox.
BooleanList The variable's type is boolean and
its presentation is a pair of radio
buttons.
BooleanListDisabled The variable is irrelevant and its
type is a boolean and its
presentation is a pair of radio
buttons.
TrueOption The variable's type is boolean.
TrueOptionDisabled The variable is irrelevant and its
type is a boolean.
FalseOption The variable's type is boolean.
FalseOptionDisabled The variable is irrelevant and its
type is a boolean.
TextEditbox The variable's type is text.
TextEditboxDisabled The variable is irrelevant and its
type is text.
NumberEditbox The variable's type is number.
NumberEditboxDisabled The variable is irrelevant and its
type is number.
FileUpload The variable's type is file-upload.
FileUploadDisabled The variable is irrelevant and its
type is file-upload.
DateEditbox The variable's type is date.
DateEditboxDisabled The variable is irrelevant and its
type is date.
Calendar The variable's type is date and its
presentation is a popup calendar.
CalendarButton A button in a popup calendar.
CalendarYearMonth The year/month row in a popup
calendar.
CalendarYear The year in a popup calendar.

17 November 2022
184 Contract Express® API Manual

Function Class Name Extension Descendant Element

CalendarYearEditbox The year value in a popup
calendar.
CalendarMonth The month in a popup calendar.
CalendarMonthList The dropdown list of months in a
popup calendar.
CalendarDay A day in a popup calendar.
CalendarDayWeekend A Saturday/Sunday in a popup
calendar.
CalendarDayWeekday A Monday - Friday in a popup
calendar.
CalendarDayToday Today's day in a popup calendar.
CalendarDayValid A valid day of the month in a
popup calendar.
CalendarDayInvalid An invalid day of the month in a
popup calendar.
ValueTimeEditbox The variable's type is time.
ValueTimeEditboxDisabled The variable is irrelevant and its
type is time.
ValueClock The variable's type is time and its
presentation is a popup clock.
ValueClockButton A button in a popup clock.
ValueClockList A dropdown list of numbers in a
popup clock.
ByFormatEditbox The variable's type is number,
date, or time and presentation by-
format.
ByFormatEditboxDisabled The variable is irrelevant and its
type is number, date, or time and
presentation by-format.
ByFormatList The variable's type is date, or time
and presentation by-format.
ByFormatListDisabled The variable is irrelevant and its
type is date, or time and
presentation by-format.
NumberByFormatPrefix The prefix text of a variable of
type number and presentation by-
format.

17 November 2022
Embedding the Questionnaire 185

Function Class Name Extension Descendant Element

NumberByFormatSuffix The suffix text of a variable of type
number and presentation by-
format.
SearchListEditbox The variable's presentation is a
search-list.
SearchListEditboxDisabled The variable is irrelevant and its
presentation is a search-list.
SearchListEditboxNonEmpty The variable's presentation is a
search-list and the editbox
contains one or more characters.
SearchList The variable's presentation is a
search-list and there are one or
more entries returned by the
search.
SearchListEmpty The variable's presentation is a
search-list and there are no
entries returned by the search.
SearchListOption The variable's presentation is a
search-list and there are one or
more entries returned by the
search.
SelectList The variable's presentation is a
select-list.
SelectListDisabled The variable is irrelevant and its
presentation is a select-list.
ButtonList The variable's presentation is a list
of checkbox or radio buttons.
ButtonListDisabled The variable is irrelevant and its
presentation is a list of checkbox
or radio buttons.
AllOption The "select all" option of a
variable.
AllOptionDisabled The "select all" option of an
irerelevant variable.
UnknownOption The "set unknown" option of a
variable.
UnknownOptionDisabled The "set unknown" option of an
irrelevant variable.

17 November 2022
186 Contract Express® API Manual

Function Class Name Extension Descendant Element

OtherOption The "enter other" option of a
variable.
OtherOptionDisabled The "enter other" option of an
irrelevant variable.
OtherEditbox The other value of a variable.
OtherEditboxDisabled The other value of an irrelevant
variable.
SetPreviewLocation Hidden The preview document is hidden.
CreatePreviewDocument Margin The margin surrounding the
content of the preview document
wording.
Content The wording of the preview
document.
CreatePreviewDocumentTabGrou Button A zoom or navigation button for
p the collection of previewable
attachments.
SelectedTop The top document currently being
previewed.
SelectedSub A previewable attachment
currently being previewed.
AvailableTop The top document which is not
currently being previewed.
AvailableSub Any other previewable
attachment which is not currently
being previewed.
CreatePreviewToggleHiddenSymb On The toggle button is turned on.
ols
Off The toggle button is turned off.

CreatePreviewToggleExcludedText On The toggle button is turned on.

Off The toggle button is turned off.
CreatePreviewToggleBrackets On The toggle button is turned on.
Off The toggle button is turned off.
CreatePreviewToggleSpanNumber On The toggle button is turned on.
s
Off The toggle button is turned off.

17 November 2022
Embedding the Questionnaire 187

5.3.3 Icomoon Font

The Icomoon font portrays certain characters as icons, in a similar fashion to the dingbat family of fonts.

Properties

The pertinent properties when creating an Icomoon element are:

Property Name Property Type Description

Icon string The mnemonic that identifies the iconic character.
FontSize string Determines the size of the icon.
Disabled boolean Extends the class name.
ClassName string The bespoke class name of the element.
InnerText string If this is specified, the text occurs beside the icon.
TextAlign string Left: the text occurs to the left of the icon.
Right: the text occurs to the right of the icon.

The composite class name of the Icomoon element is determined by the Icon (example given), Disabled and
ClassName properties:

Icon Disabled ClassName Composite Class Name

non-null false null "Icomoon IcomoonIcon"
non-null true null "Icomoon IcomoonIcon IcomoonDisabled"
non-null false non-null "Icomoon IcomoonIcon ClassName"
non-null true non-null "Icomoon IcomoonIcon IcomoonDisabled ClassName"

17 November 2022
188 Contract Express® API Manual

Characters

The characters in the Icomoon font are identified by their mnemonic:

5.4 JavaScript Library

5.4.1 General Functions

CreateElement

Parameter 1 html-element _ParentElement

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The text of the element will be a localized translation of the phrase "Read Only".

ReadOnly

Return Type boolean

Description Returns true if-and-only-if the EditContract URL includes the name=value pair:

readonly=true

CreatePageNavigationSelector

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The tag name should be "SELECT".
The SELECT element will contain child OPTION elements for each separate questionnaire
page.

CreatePageNavigationList

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
This will contain a child element for each separate questionnaire page.
Each child element will contain an Icomoon icon to indicate its completeness, next to the

Parameter 3 array _Parameters

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.

17 November 2022
Embedding the Questionnaire 193

The TABLE element will contain rows for the total number of relevant variables, the
number of complete relevant variables, and the number of incomplete relevant variables.
Of those, there are rows indicating the number of unknown values, the number of unsure
values, and the number of deferred values. The numbers themselves will be split into two
columns representing the current questionnaire page and all questionnaire pages.

CreateResizer

Parameter 1 html-element _ParentElement

Parameter 2 string _ClassName

Parameter 3 boolean _IsHorizontal

Parameter 4 boolean _IsVisible

Return Type html-element

Description Create an HTML DIV element as the next child of the parent element.
The element will contain three child elements, the middle element of which represents a
draggable bar that resizes the proportions of the other two child elements.
A horizontal resizer arranges the outer child elements to the left and to the right of the
draggable bar.
A vertical (non-horizontal) resizer arranges the outer child elements above and below the
draggable bar.
The resizer can be initially hidden or visible.

GetParameterValue

Parameter 1 string _ParameterName

Return Type variant

Description Get the value of a Contract Express db_ parameter.

GetLink

Parameter 1 string _LinkMnemonic

images
styles
scripts
self
previous
first
last
answers

17 November 2022
194 Contract Express® API Manual

documents
tables

Return Type string

Description Get the HREF for the specified RESTful link.

5.4.2 Alert Functions

SetAlertsLocation

Parameter 1 html-element _ParentElement

Return Type void

Description Inform Contract Express where the alerts will be built.

AllAlertsOnThisPage

Return Type list<object>

Description Each object in the list represents an alert that mentions at least one variable on the
current questionnaire page.

AlertIsCompulsory

Parameter 1 object ALERTOBJECT

Return Type boolean

Description The alert object is a member of the list returned by AllAlertsOnThisPage.

Returns true if that object represents a compulsory alert.

CreateAlert

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Parameter 4 object ALERTOBJECT

Return Type html-element

17 November 2022
Embedding the Questionnaire 195

It will contain two child elements.

The first child element is the Icomoon error icon, whose ID is determined by the interface
function AlertMessageIconID.
The second child element will contain the text of the alert's message, whose ID is
determined by the interface function AlertMessageTextID.

5.4.3 Questionnaire Functions

SetQuestionnaireLocation

Parameter 1 html-element _ParentElement

Return Type void

Description Inform Contract Express where the questionnaire will be built.

PreviousPageExists

Return Type boolean

Description Returns true if-and-only-if a questionnaire page occurs before the current questionnaire
page.

NextPageExists

Return Type boolean

Description Returns true if-and-only-if a questionnaire page occurs after the current questionnaire
page.

NumberedPageExists

Parameter 1 number _PageNumber

Return Type boolean

Description Returns true if-and-only-if the specified questionnaire page exists.

CreatePreviousPageButton

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Return Type html-element

17 November 2022
196 Contract Express® API Manual

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The button element is automatically disabled whenever the interface function
PreviousPageExists returns false.

CreateNextPageButton

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Return Type html-element

5.4.4 Page Functions

PageNumber

Return Type number

Description The number of the current questionnaire page.

PageNumberTitle

Return Type string

Description A string of the form "M of N", where M is the current questionnaire page number and N is
the total number of questionnaire pages.

PageTitleExists

Return Type boolean

Description Returns true if-and-only-if the current questionnaire page has a title.

PageGuidanceExists

Parameter 3 array _Parameters

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The element will contain a localized translation of the text "M of N", where M is the

17 November 2022
198 Contract Express® API Manual

number of the current questionnaire page and N is the total number of questionnaire
pages.

5.4.5 Group Functions

AllGroupsOnThisPage

Return Type list<object>

Description Each object in the list represents a group within the current questionnaire page.

GroupTitleExists

Parameter 1 object GROUPOBJECT

Return Type boolean

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Returns true if-and-only-if the specified group has a title.

GroupGuidanceExists

Parameter 1 object GROUPOBJECT

Return Type boolean

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Returns true if-and-only-if the specified group has some guidance.

CreateGroupTitle

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Parameter 4 object GROUPOBJECT

Return Type html-element

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The ID of the element created is determined by the interface function GroupTitleHostID.
The single child element will contain the static or active text for the title of the specified
group.
The ID of the child element is determined by the interface function GroupTitleTextID.

17 November 2022
Embedding the Questionnaire 199

CreateGroupGuidance

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Parameter 4 object GROUPOBJECT

Return Type html-element

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The ID of the element created is determined by the interface function
GroupGuidanceHostID.
The single child element will contain the static or active text for the guidance of the
specified group.
The ID of the child element is determined by the interface function GroupGuidanceTextID.

5.4.6 Repetition Grid Functions

GroupIsRepeatedGridAcross

Parameter 1 object GROUPOBJECT

Return Type boolean

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Returns true if-and-only-if the specified group is presented as a grid with repetitions
across.

GroupIsRepeatedGridDown

Parameter 1 object GROUPOBJECT

Return Type boolean

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Returns true if-and-only-if the specified group is presented as a grid with repetitions
down.

CreateRepetitionGridEditButton

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

17 November 2022
200 Contract Express® API Manual

Parameter 3 array _Parameters

Parameter 4 object GROUPOBJECT

Return Type html-element

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The button element enables the user to edit the repeated variables in a "modal" dialog.

CreateRepetitionGridCloseButton

Parameter 1 html-element _ParentElement

Parameter 2 string _TagName

Parameter 3 array _Parameters

Parameter 4 integer _OnCloseScrollTo

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The button element enables the user to close the editing of the repeated variables and
return to its original scroll position in the questionnaire.

5.4.7 Repetition Group Functions

AllRepetitionsOfThisGroup

Parameter 1 object GROUPOBJECT

Return Type list<object>

Description The group object is a member of the list returned by AllGroupsOnThisPage.

Each object in the list represents a repetition of the specified group.

ActualRepetition

Parameter 1 object REPETITIONOBJECT

Return Type boolean

Description The repetition object is a member of the list returned by AllRepetitionsOfThisGroup.

Returns true if-and-only-if all of the variables in the repetition are actually repeated
variables.

17 November 2022
Embedding the Questionnaire 201

Description The repetition object is a member of the list returned by AllRepetitionsOfThisGroup.

Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The ID of the element created is determined by the interface function
RepetitionManagementHostID.
The element will contain child elements that are used for inserting new repetitions of the
group and deleting existing repetitions of the group, providing that group is governed by a
dynamic group-repeat variable.

5.4.8 Variable Functions

AllVariablesInThisRepetition

Parameter 1 object REPETITIONOBJECT

Return Type list<object>

Description The repetition object is a member of the list returned by AllRepetitionsOfThisGroup.

Each object in the list represents a variable in the specified repetition of a group.

VariableIsDefinitelyRelevant

Parameter 1 object VARIABLEOBJECT

Return Type boolean

Description The variable object is a member of the list returned by AllVariablesInThisRepetition.

Returns true if-and-only-if the specified variable and repetition is definitely relevant.

VariableIsDefinitelyIrrelevant

Parameter 1 object VARIABLEOBJECT

17 November 2022
Embedding the Questionnaire 205

Parameter 3 array _Parameters

Parameter 4 object VARIABLEOBJECT

Return Type html-element

Description The variable object is a member of the list returned by AllVariablesInThisRepetition.

Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
The ID of the element created is determined by the interface function
VariablePreambleHostID.
The single child element will contain the static or active text for the preamble of the
specified variable.
The ID of the child element is determined by the interface function
VariablePreambleTextID.

CreateVariablePrompt

Description Inform Contract Express where the preview document will be built.

CreatePreviewDocument

Parameter 1 html-element _ParentElement

Return Type html-element

Description Create an HTML element with the specified tag name and parameters as the next child of
the parent element.
If there are no occurrences of the selected variable in the document wording then this
element will be blank. Otherwise, it will contain the occurrence number and the total
number of occurrences.

17 November 2022
210 Contract Express® API Manual

5.4.10 HTML Identifier Functions

AlertMessageHostID

Parameter 1 object ALERTOBJECT

Return Type string

Description The alert object is a member of the list returned by AllAlertsOnThisPage.

The identifier of the element returned by the interface function CreateAlert.

AlertMessageTextID

Parameter 1 object ALERTOBJECT

Return Type string

Description The identifier of the element that contains the text of the page title.

PageGuidanceHostID

Return Type string

Description The identifier of the element returned by the interface function CreatePageGuidance.

17 November 2022
Embedding the Questionnaire 211

VariablePromptTextID

Parameter 1 object VARIABLEOBJECT

Executive Profile Key Impact Areas: Muhammad Zia Shahid
No ratings yet
Executive Profile Key Impact Areas: Muhammad Zia Shahid
5 pages
OPT or Resource Training Notes
No ratings yet
OPT or Resource Training Notes
27 pages
Module 4: Connecting To Additional Resources: in This Module, You Will Learn
No ratings yet
Module 4: Connecting To Additional Resources: in This Module, You Will Learn
31 pages
AmitJoshi - DirectorDelivery 5 1
No ratings yet
AmitJoshi - DirectorDelivery 5 1
4 pages
Difference - VB - Net & C#
No ratings yet
Difference - VB - Net & C#
15 pages
Java/J2EE Expert with 17 Years Experience
No ratings yet
Java/J2EE Expert with 17 Years Experience
14 pages
Preludesys Project Management Insights
No ratings yet
Preludesys Project Management Insights
5 pages
Zen Wor X Case Study
No ratings yet
Zen Wor X Case Study
6,248 pages
Mails 2
100% (1)
Mails 2
23 pages
InsightGlobal Contact List
No ratings yet
InsightGlobal Contact List
4 pages
Webmethods Deployer Installation and Users Guide
75% (4)
Webmethods Deployer Installation and Users Guide
54 pages
APAIntSol4.4 Studentmanual 16nov2021
No ratings yet
APAIntSol4.4 Studentmanual 16nov2021
240 pages
IBM ReqPro and DB2 Development Tools
50% (2)
IBM ReqPro and DB2 Development Tools
29 pages
Module 11: Deploying Mule Applications Applications
No ratings yet
Module 11: Deploying Mule Applications Applications
28 pages
Skill Set PDF
No ratings yet
Skill Set PDF
3 pages
Foundations For High Scalability in Mule 4 PDF
No ratings yet
Foundations For High Scalability in Mule 4 PDF
33 pages
Web Methods EDIINT Module User's Guide 6.5
0% (1)
Web Methods EDIINT Module User's Guide 6.5
98 pages
10-4 Error Messages Reference
No ratings yet
10-4 Error Messages Reference
2,710 pages
Anypoint Platform Datasheet
No ratings yet
Anypoint Platform Datasheet
2 pages
01 Context
No ratings yet
01 Context
10 pages
Boolean Logic for Keyword Searches
No ratings yet
Boolean Logic for Keyword Searches
12 pages
Senior IT Professional: Digital Transformation Expert
No ratings yet
Senior IT Professional: Digital Transformation Expert
5 pages
WebMethods SOAP Developer's Guide - Software AG Documentation
100% (1)
WebMethods SOAP Developer's Guide - Software AG Documentation
154 pages
SaaS, PaaS, IaaS: Uses and Benefits
No ratings yet
SaaS, PaaS, IaaS: Uses and Benefits
3 pages
C2C Companies
No ratings yet
C2C Companies
2 pages
SOAP Vs REST Headtohead Comparison
No ratings yet
SOAP Vs REST Headtohead Comparison
7 pages
VBeyond Company
No ratings yet
VBeyond Company
24 pages
Manufacturing Admin
No ratings yet
Manufacturing Admin
604 pages
ARC300 B2CCommerceArchitect Part 1 Discovery & Design
No ratings yet
ARC300 B2CCommerceArchitect Part 1 Discovery & Design
136 pages
02 Anypoint Platform
No ratings yet
02 Anypoint Platform
22 pages
IT Technologies Software Development Life Cycle (SDLC)
No ratings yet
IT Technologies Software Development Life Cycle (SDLC)
6 pages
Webmethods Interview Quesstions
No ratings yet
Webmethods Interview Quesstions
1 page
Vendor Contacts 1
No ratings yet
Vendor Contacts 1
102 pages
Prime Vendor Database
No ratings yet
Prime Vendor Database
250 pages
Resume
No ratings yet
Resume
3 pages
Recruiter Contact List
No ratings yet
Recruiter Contact List
54 pages
Getting Started With Anypoint Platform (Mule 4) : Development: Fundamentals Course, Which Includes This Content and More
No ratings yet
Getting Started With Anypoint Platform (Mule 4) : Development: Fundamentals Course, Which Includes This Content and More
3 pages
Open Positions
No ratings yet
Open Positions
6 pages
JKT Corporate
No ratings yet
JKT Corporate
22 pages
US Largest Staffing Co.s
No ratings yet
US Largest Staffing Co.s
6 pages
Software Product Development
No ratings yet
Software Product Development
15 pages
Getting Started With Support From SAP (Support Accreditation)
No ratings yet
Getting Started With Support From SAP (Support Accreditation)
20 pages
Bench Sales Report - Consolidated-Anet-RiyaLamba
No ratings yet
Bench Sales Report - Consolidated-Anet-RiyaLamba
131 pages
UKG Product Support Requirement Gathering Workforce Integration Migration/Go Live Root Cause Analysis Installation and Upgrades Project Management
No ratings yet
UKG Product Support Requirement Gathering Workforce Integration Migration/Go Live Root Cause Analysis Installation and Upgrades Project Management
2 pages
APAAppNet - Studentmanual - 25jan2019 - Module 2. Introducing MuleSoft, The Application
No ratings yet
APAAppNet - Studentmanual - 25jan2019 - Module 2. Introducing MuleSoft, The Application
18 pages
Global Tech Solutions for Enterprises
No ratings yet
Global Tech Solutions for Enterprises
18 pages
Vendor List (Bench Sales)
No ratings yet
Vendor List (Bench Sales)
9 pages
150519-Detailed English Ad No 4
No ratings yet
150519-Detailed English Ad No 4
6 pages
02 M3 IntroducingTheSolutionInCloudEdition Workbook Updated
No ratings yet
02 M3 IntroducingTheSolutionInCloudEdition Workbook Updated
215 pages
APAAppNet - Studentmanual - 25jan2019 - Module 4. Identifying, Reusing and Publishing
No ratings yet
APAAppNet - Studentmanual - 25jan2019 - Module 4. Identifying, Reusing and Publishing
31 pages
Resume - Rohit - Singh - Verma - Detailed
No ratings yet
Resume - Rohit - Singh - Verma - Detailed
9 pages
US IT Technical Recruiter Profile
No ratings yet
US IT Technical Recruiter Profile
3 pages
APIGEE Edge For Private Cloud 4.51.00
No ratings yet
APIGEE Edge For Private Cloud 4.51.00
983 pages
APDevFundamentals4.1 StudentManual 04nov2018
No ratings yet
APDevFundamentals4.1 StudentManual 04nov2018
532 pages
CV - Ranjithkumar M
No ratings yet
CV - Ranjithkumar M
2 pages
ContractExpress Author Getting Started Manual
No ratings yet
ContractExpress Author Getting Started Manual
135 pages
Service Contracts Public API-1
100% (1)
Service Contracts Public API-1
65 pages
Introduction To Express - Js
No ratings yet
Introduction To Express - Js
9 pages
CCXT
100% (1)
CCXT
143 pages
Integrate Salesforce API with Boomi
No ratings yet
Integrate Salesforce API with Boomi
32 pages
225 Kubernetes Realtime Interview Questions
No ratings yet
225 Kubernetes Realtime Interview Questions
82 pages
Velocloud Partner Guide 33
No ratings yet
Velocloud Partner Guide 33
83 pages
Vsphere Esxi Vcenter Server 703 Authentication Guide
No ratings yet
Vsphere Esxi Vcenter Server 703 Authentication Guide
169 pages
Modern Authentication With Azure Active Directory For Web Applications Developer Reference Vittorio Bertocci Download
No ratings yet
Modern Authentication With Azure Active Directory For Web Applications Developer Reference Vittorio Bertocci Download
78 pages
Resume Avats
No ratings yet
Resume Avats
1 page
Granta MI 2023 R1 Release Notes
No ratings yet
Granta MI 2023 R1 Release Notes
27 pages
Identity and Data Security For Web Development Jonathan Leblanc PDF Download
100% (3)
Identity and Data Security For Web Development Jonathan Leblanc PDF Download
61 pages
Ebook CISSP Domain 05 Identity and Access Management (IAM)
100% (1)
Ebook CISSP Domain 05 Identity and Access Management (IAM)
84 pages
Proof-of-Possession Tokens in Microservice Architectures
No ratings yet
Proof-of-Possession Tokens in Microservice Architectures
44 pages
Enabling The Uk Open Banking Specification: A Forgerock Technical Solution Guide
No ratings yet
Enabling The Uk Open Banking Specification: A Forgerock Technical Solution Guide
15 pages
Cloud Computing Authentication
No ratings yet
Cloud Computing Authentication
4 pages
Shon Harris Audio Book
No ratings yet
Shon Harris Audio Book
381 pages
Tatmeen WKI-0062 Technical Guide For Dispensers v2.0
No ratings yet
Tatmeen WKI-0062 Technical Guide For Dispensers v2.0
27 pages
8.2-AWS Cognito - Digital Cloud Training
No ratings yet
8.2-AWS Cognito - Digital Cloud Training
7 pages
SAP SFSF Joule
No ratings yet
SAP SFSF Joule
62 pages
Traefik Labs - White Paper - Kubernetes For Cloud-Native Application Networks
No ratings yet
Traefik Labs - White Paper - Kubernetes For Cloud-Native Application Networks
23 pages
Identity and Access Management Overview
80% (5)
Identity and Access Management Overview
57 pages
Developing Applications With Azure Active Directory: Principles of Authentication and Authorization For Architects and Developers Manas Mayank
100% (2)
Developing Applications With Azure Active Directory: Principles of Authentication and Authorization For Architects and Developers Manas Mayank
55 pages
Microsoft Entra Verified ID Guided Tour Part 2
No ratings yet
Microsoft Entra Verified ID Guided Tour Part 2
59 pages
Mastering ASP - NET Core Security
100% (3)
Mastering ASP - NET Core Security
148 pages
Custom Domain Configuration For Joule
No ratings yet
Custom Domain Configuration For Joule
4 pages
OAuth 2.0 in Flutter with AWS Cognito
No ratings yet
OAuth 2.0 in Flutter with AWS Cognito
10 pages
Building Secure Applications With Keycloak (OIDC/JWT) : Abhishek Koserwal Red Hat
No ratings yet
Building Secure Applications With Keycloak (OIDC/JWT) : Abhishek Koserwal Red Hat
20 pages
CC Unit 4
No ratings yet
CC Unit 4
22 pages
Senior IAM Engineer with Cloud Expertise
0% (1)
Senior IAM Engineer with Cloud Expertise
4 pages
Sonam Forgerock 2
No ratings yet
Sonam Forgerock 2
5 pages
SAP Cloud Identity Services - Identity Authentication, Solution Overview
No ratings yet
SAP Cloud Identity Services - Identity Authentication, Solution Overview
36 pages
Release Notes - Roam v6.1
No ratings yet
Release Notes - Roam v6.1
6 pages
Mobile Money API Security Guide
No ratings yet
Mobile Money API Security Guide
49 pages
Seclore Hardware Sizing Requirements - V1.0
No ratings yet
Seclore Hardware Sizing Requirements - V1.0
24 pages