It is possible to perform some operations on data for use in
- rendering of fixed text JotBlocks
- passing of data in DocumentTRAK designs
- application of data in email designs
Simple Concatenation
Simple concatenation is supported when merge fields are used alone or with some fixed text. In this case, merge fields are delimited by square brackets. For example
[UserFullName] sent [Document Name]
could output something like
John Doe sent Contract 1467859
Advanced Data Manipulation
Advanced formatting and data manipulation requires the use of javascript. Basic javascript operations are supported, as well as the use of some added libraries and AssureSign specific objects and functions.
Javascript must be contained within code delimiting blocks
[{ }]
Single statements that return a value implicitly may be included. For example, the following javascript will print the current year from the server to the document:
[{new Date().getFullYear()}]
when implemented in fixed text:
Simple concatenation may also be combined with javascript, such as:
[UserFullName] sent [{var s = getMergeField('Document Name'); return s.toUpperCase();}]which would produce the same value in a fixed text JotBlock as
[{var s = getMergeField('Document Name'); return get('UserFullName') + ' sent ' + s.toUpperCase();}]Important: You must return back simple types in your code. You cannot return back some object that cannot be cast to a string, such as a match array from a regular expression operation.
Manipulating data via javascript
When referencing merge fields in javascript, the square bracket delimited names are not supported. Instead, an AssureSign defined retrieval method must be used. Data may be either requested from a method specific to the type of data (this would be important in the case, for example, that a JotBlock and a Parameter have the same name), or from a generic method. Types of values that may be inserted include:
- Merge fields: while we sometimes refer to all insertion elements as "merge fields", strictly speaking these are elements that are predefined in the system and defined here
- Parameters: passed in when the document is submitted
- JotBlock values: available after the values have been submitted by the signer
- Prior values returned from a DocumentTRAK operation: for example, in the case that a DocumentTRAK operation requires an initial authentication call followed by another call using a value returned in the first call
Operations for retrieving these data elements include:
Generic method
- get: function(mergeFieldName|jotBlockName|parameterName|priorValueName)
Value type specific methods
- mergeField|getMergeField: function(mergeFieldName)
- jotBlock|getJotBlock: function(jotBlockName)
- parameter|getParameter: function(parameterName)
- priorValue|getPriorValue: function(key)
The assuresign model
An array of each type of values may also be accessed through the assuresign model, defined as:
assuresign: {
mergeFields: [{
name: '',
value: ''
}],
parameters: [{
name: '',
value: ''
}],
jotBlocks: [{
name: '',
value: ''
}],
priorValues: [{
name: '',
value: ''
}]
}An example of using the assuresign.jotBlocks array through the underscoreJs syntax is shown in the Multi-line statements example below.
Included JS libraries
Additional libraries have been included to allow direct calls and provide some underlying functionality exposed through other objects.
- momentJs ( see http://momentjs.com/😞 for date formatting
- underscoreJs (see http://underscorejs.org/😞 for various collection and object manipulation, and more
Additional helper functions
- formatDate: function(dateString, format) (using momentJS available formats)
- htmlEncode: function(str)
- xmlEncode: function(str)
- trim: function(str)
Multi-line statements
Statements requiring multiple lines of code must return a value explicitly. For example, the following returns the document name in upper case:
[{var s = get('Document Name'); return s.toUpperCase();}]
This would convert Contract 1467859 to CONTRACT 1467859.
Here is an example of inserting this in an email design that combines simple square bracket delimited merge fields, javascript, and markdown:
Since Document Name is also a predefined merge field, the following would all work as well:
[{var s = mergeField('Document Name'); return s.toUpperCase();}]
[{var s = getMergeField('Document Name'); return s.toUpperCase();}]
Given a JotBlock named [signer initials] where the signer was allowed to enter any casing, the following could be used to insert the initials in upper case in a DocumentTRAK operation:
[{var s = jotBlock('signer initials'); return s.toUpperCase();}]
Value collection iteration
An ideal use of value iteration would be in a DocumentTRAK design, which would allow for the use of a design to pass JotBlock values without requiring prior knowledge of the JotBlock names.
Inserting this into DocumentTRAK request XML
<JotBlocks>
[{var s='';_(assuresign.jotBlocks).each(function(j){s+=('<JotBlock name="'+xmlEncode(j.name)+'" value="'+xmlEncode(j.value)+'"/>
');});return s;}]
</JotBlocks>as shown here
would produce something like the following when sent to a service:
<JotBlocks>
<JotBlock name="JotBlock1" value="JotBlock1Value"/>
<JotBlock name="JotBlock2" value="JotBlock2Value"/>
</JotBlocks>Miscellaneous examples
Simple Formatting:
To format the [Transaction Start Date] field in YYYY-MM-DD format,
[{formatDate(get('Transaction Start Date'), 'YYYY-MM-DD')}]would output, for example, 2014-02-27
Advanced Concatentation and Formatting of a Date:
To produce some advanced date format such as This 27th Day of February 2014, you could use the moment object:
[{var d=moment(get('MergeFieldName'));return 'This '+d.format('Do')+' Day of '+d.format('MMMM YYYY');}]Date Addition:
To add 7 days to the [Completion Date] merge field, applying it when signing is complete, you could use the moment object:
[{moment(getMergeField('Completion Date')).add(7,'day').format('MM/DD/YYYY')}]Converting from UTC to a different Time Zone:
Converting from UTC to a different Time Zone requires two templates be set up, one for Standard Time and one for Daylight Savings Time. To change the [Completion Date] merge field to Central Time when signing is complete, you could use these moment objects:
Standard Time:
[{return moment(getMergeField('Completion Date')).add(-6,'hours').format('MMM DD YYYY h:mm A');}]Daylight Savings Time:
[{return moment(getMergeField('Completion Date')).add(-5,'hours').format('MMM DD YYYY h:mm A');}]Regular Expressions:
Using standard regular expressions to extract the area code from a phone number passed as a parameter
(would work against something like (626)555-5555, 626-555-5555, etc.):
[{return new RegExp(/[0-9]{3}/).exec(parameter('Phone number'))[0];}]Note that we are returning back the first element of the match array in this example ([0]). Your return must be able to be cast to a string.
