Click on the + button at the top of the required area in Data Composer to add your field.

For example, if you want to add a calculated field to a work type, select the work type, select Data Composer > Work Item, then click the + button as shown in this image.

The buttons at the top right of the editor have the following functions:

	Opens the debugger (see below).
	Opens an expression help blade. The blade shows syntax, common functions, examples, and a version changelog.
	Validates the expression to ensure the syntax is correct. Errors will be presented at the foot of the window:
	Toggles the expression window between full-screen view and normal view.

in

Changes the case to uppercase. 

Example

toUpper(workitem.roles.client.ods.person.lastName)  

Converts Smith to SMITH. 

Changes the case to lowercase.

Example

toLower(workitem.roles.client.ods.person.lastName)

Converts Smith to smith.

Changes to title case (first letter upper case).

Example

toTitleCase(workitem.roles.client.ods.person.lastName)

Converts smith to Smith.

Note: this function only works for text in lowercase. It will not convert all uppercase text to title case. To do this, combine the two functions together as follows: ToTitleCase(tolower(my_field))

Returns true if the field's value is null or an empty string.

Example

IsNullOrEmpty(workitem.keyDates.kd-file-review.taskDueDate.date.utc.value.toString())

Returns true if the work item's File Review Key Date has been set, else false.

Returns true if the string starts with the characters provided. 

Example

startsWith(workitem.type.systemName, 'matter-dispute')

Returns true if the work item system name starts with matter-dispute.      
 

Returns true if the string starts with the characters provided, regardless of case. 

Returns true if the string ends with the characters provided.

Example

endsWith(workitem.type.systemName, 'dispute')

Returns true if the work item system name ends with dispute.      
 

Returns true if the string ends with the characters provided, regardless of case.

Returns true if the field contains the string specified. 

Example

contains(workitem.type.path,'defendant')

Returns true if the work item system name

matter-dispute-defendant-pi-medical-negligence

contains the word defendant. 

Returns true if the field contains the string specified, regardless of case. 

truncate / left (my_field,number of characters)

right (my_field,number of characters)

Returns all the text to the left (or right) of a string, for the number of characters specified. 

Example

left(workitem.roles.client.ods.person.firstName,1)            
truncate(workitem.roles.client.ods.person.firstName,1)

Converts John to J. 

toUpper(workitem.roles.client.ods.person.lastname) + ' ' +           
toUpper(truncate(workitem.roles.client.ods.person.firstName, 1))

Converts John Smith to SMITH J.

This kind of function can be used to build up names in the format required by specific documents. It is frequently used in ODS calculated fields to create dedicated court or contract participant names.

Counts the number of items in a list. 

Example

count(workitem.roles.witness)

Returns the number of witness participants assigned to the work item.  

E.g., returns: "3" 

count(children!q?path=proceeding&closed=true)

Counts the number of proceedings created (whether currently open or closed) on a matter.

If statement that will check a condition, and then return specified values for true and false. 

Example

if (count(workitem.roles.witness)) > 0           
Then           
'Has witnesses'           
Else           
'Does not have witnesses'

Checks if there are one or more witnesses, if so, it returns the text Has witnesses. If there are none, it returns Does not have witnesses.

If subtype.id = 13081 Then true Else false

If the id of work item subtype is 313081, then return true, else return false.

Note: this can simply be abbreviated to:

subtype.id = 313081 

as the default return values are true or false.

Nested Ifs can be used so that each condition is tested in turn, until a positive result is found.

For example:     
The following code checks the Matter Jurisdiction and returns the appropriate office address. If no Jurisdiction is found, the default Perth address is returned:

If(matterJurisdiction.jurisdiction.name) = 'Victoria'     
Then '150 Bourke Street, Melbourne VIC 3000'     
Else     
If(matterJurisdiction.jurisdiction.name) = 'New South Wales'     
Then '12 Castlereagh Street, Sydney NSW 2000'     
Else     
If(matterJurisdiction.jurisdiction.name) = 'Queensland'     
Then '64 Eagle Street, Brisbane QLD = 4000'     
Else     
'19 St Georges Terrace, Perth WA 6000'

Returns today's date.

Example

$root.env.now.utc.value

Returns: 

2023-09-25T13:43:33.7516307Z 

The date is returned in the default format of the browser. 

See the format expression, below on how to apply formats to dates.      
 

An example of checking if a date is greater than now:      
parseDate(keyDates.kd-initial-instructions-confirmed.taskDueDate.date.utc.value,'en-GB') > now()

Return the difference between two dates, as per the datePart, namely: 'ms' (milliseconds), 's' (seconds), 'm' (minutes), 'd' (days), 'y' (years). 

Example

dateDiff(workitem.roles.claimant!1.ods.person.dateOfBirth, $root.env.now.utc.value,'y')

Returns the age of the 1st claimant in years, by comparing the number of years between their birth date and today's date.

dateDiff(workitem.children!q?path=kd-instruction-received&closed=true!1.taskDueDate.date.utc.value, workitem.keyDates.kd-re-exchange-date.taskDueDate.date,'d') 

Calculates the number of days from the date of the initial instruction to a property exchange date. 

Adds a number to a date, as per the datePart value, namely: 'ms' (milliseconds), 's' (seconds), 'm' (minutes), 'h' (hours), 'd' (days), 'M' (months), 'y' (years). 

Commonly used with the format function to format the results. 

Example

dateAdd('d', 10, workitem.keyDates.kd-incident-date.taskDueDate.date.utc.value)

Adds 10 days to the date that instructions were received. 

Returns:

2023-08-29T09:36:43.2100000+00:00 

dateAdd('y', -1 , workitem.keyDates.kd-incident-date.taskDueDate.date.utc.value)

Subtracts 1 year from the date of an incident. 

Returns:

2023-08-01T08:00:00.0000000+00:00 

Converts the string representation of a date and time to a 'DateTime' equivalent, using the mandatory culture code.

Commonly used to convert date fields held on Form Builder forms (as they are actually stored in ShareDo in string format).

Example

parseDate(workitem.form-sample-date.dateField1,'en-GB')

Converts a Form Builder date from a string to a date, using the British culture code.

Returns: 

2023-09-12T00:00:00.0000000+00:00

The same field, but using the American culture code:

parseDate(form-sample-date.dateField1,'en-US')

Returns:

2023-12-09T00:00:00.0000000+00:00

Note the days/months are reversed.

The format function can be used in conjunction with parseDate:  

format(parseDate(form-sample-date.dateField1,'en-GB'),'dd MMM yyyy')

Returns:

12 Sep 2023       
 

Formats the value using the specified format (and optional culture code if specified). 

Typically used with dates and number values. 

Examples

Date example: 

format($root.env.now.utc.value, 'd MMMM yyyy')

Presents todays date in the format requested. 

Note: the ordinal can be applied to the day component: 

format($root.env.now.utc.value, 'ddos MMMM yyyy')

Result: 28th September 2023 

Just return the year component:

format($root.env.now.utc.value, 'yyyy')

Result: 2023 

Format can be combined with other functions: 

format(dateAdd('d', -182, keyDates.kd-incident-date.taskDueDate.date.utc.value), 'd MMMM yyyy')

This subtracts 6 months from the incident date and formats the result: 

1 September 2023 

.. and now including the ordinal: 

format(dateAdd('d', -182, keyDates.kd-incident-date.taskDueDate.date.utc.value), 'dddos MMMM yyyy')

Result: 1st September 2023 

Number examples: 

Using the culture code of "DE" (Germany) to present currency in the format used in Austria and Germany (e.g. 500,00.00) 

workitem…..damages.value!q?format=@n&cultureCode=de-DE      
 

Using a precision e.g. 'n', 'n2' to control decimal places.            
'n' - number.

format(12345,'n2') returns 12,345.00      
 

'p' - percentage.

format(0.39755, 'p2')  

Returns 39.75%      

'c' - currency.      
format (12345, 'c2')      
Returns £12,345.00

'c' - currency field with country code.     
format(name of field.value, 'c2', 'countrycode')     
For example:     
format(form-custom-legal-qualification.legalQualificationPreIncidentSalary.value, 'c2', 'en-AU')     
Returns $3,434.78     
This can be combined with the use of variables.     
For example:     
var total1 =     
form-custom-mb-legal-qualification.legalQualificationPreIncidentSalary.value     
+     
form-custom-mb-legal-qualification.legalQualificationPostIncidentSalary.value     
;     
format(total1, 'c2', 'en-AU')

Returns a number expressed in words. 

Case - 'lower' (default), 'upper', 'title' 

Example

numberToWords (document.questionnaire.attempts_made_to_contact.value, 'title')

Returns: "Two".

numberToWords(workitem.no_of_witness)

Where no_of_witness is a Calculated Field

containing a Count of all Witnesses. 

Returns: "Three" 

Note that as the default is "lower", this does not need to be passed. 

numberToWords(dateDiff(workitem.roles.occupier!1.ods.person.dateOfBirth,$root.env.now.utc.value,'d'), 'upper')

Returns: "SEVENTEEN" 

Calculates the age of the first occupier participant living in property for sale. 

Returns a currency expressed in words. 

currencyCode - supported values are: 'usd', 'cad', 'aud', 'gbp' 

Case - 'lower' (default), 'upper', 'title' 

Example

currencyAmountToWords(workitem.descendants!q?type=offer-received-settlement&closed=true!1.offerTransactions.totalAmount, 'gbp', 'upper')

Converts the amount of the most recent offer received (£15,500.01) into British Pounds and returns the value as text, in capital letters:

"FIFTEEN THOUSAND FIVE HUNDRED POUNDS AND ONE PENCE" 

currencyAmountToWords(document.questionnaire.pay_amount.value, 'usd', 'title')

Converts the amount input into a Form Builder questionnaire on a prepare document blade into US Dollars, using title case. 

"Twelve Dollars and Fifty-Five Cents" 

Returns a new string in which all occurrences of a value are replaced with a new value. 

Example

replace(roles.claimant!1.ods.contact.direct-line!1.value,'+44 ','0')

This example replaces the international country code from the claimants telephone number with 0. 

N.B. This can also be used on the ODS, making it available to all entities/participants.

For example:     
On the root of ODS.contact, create a calculated field with the following:     
replace(direct-line!q?primary=true.value,'+44 ','0')     
This will now be available for the primary Direct Dial number on all ODS entries.

Rounds a decimal value to the nearest whole number. 

Example

For example, a dateDiff function returns the total number of days between two key dates, as follows:

e.g. 13.59069479188 days 

Using the round function: 

round(dateDiff(roles.claimant!1.ods.person.dateOfBirth, $root.env.now.utc.value,'d'))

The result would be 14 days.

Rounds a value down to the nearest whole number. 

Example

A dateDiff function may return 13.59069479188 days.

Using the floor function: 

floor(dateDiff(roles.claimant!1.ods.person.dateOfBirth, $root.env.now.utc.value,'d'))

Would return 13 days.

Rounds a value up to the nearest whole number. 

Example

A dateDiff function may return 13.59069479188 days. 

Using the ciel function: 

ciel(dateDiff(roles.claimant!1.ods.person.dateOfBirth, $root.env.now.utc.value,'d'))

Would return 14 days.

Evaluates the arguments in order and returns the value of the first expression that doesn't evaluate to null.

Example

coalesce(roles.landlord!1.ods.name, roles.land-owner!1.ods.name, roles.freeholder!1.ods.name)

Where one or more participant roles could be assigned to a work item, then cycle through each of the participant names (in order specified) and return the first name found. 

Returns a substring that starts at the specified character position (startIndex) and continues to the end of the string 

for the length of characters specified. The index is 0 based.

Example

substring(workitem.reference, 2, 2)

This extracts all the text from the 2nd character to the 4th character. 

e.g. D.MD.23.0012 becomes MD.

To return a substring where you do not know the start index or the length of the value you need to retrieve, for example if you need everything after the . in the following:     
QWERTY.6666232

you can use this as an example:

var startIndex = indexOf(workitem.reference, '.') + 1;     
substring(workitem.reference, startIndex, workitem.reference.length() - startIndex)

This would return:

6666232

Returns the number of characters in a string.

Example

length(workitem.reference)

If the workitem reference is D.MD.23.0012, the length function returns 12.

Returns the zero-based index of the first occurrence of the specified substring in the string. The comparisonType is an optional boolean (true or false). false (default) for case-sensitive comparison, true for case insensitive.

Example

indexOf(workitem.reference, 'M')

Where the workitem reference is D.MD.23.0012

Returns 2.

Returns the zero-based index of the last occurrence of the specified substring in the string.  The comparisonType is an optional boolean (true or false). false (default) for case-sensitive comparison, true for case insensitive.

Example

lastIndexOf(workitem.reference, 'D')

Where the workitem reference is D.MD.23.0012

Returns 3.

Splits a string based on a specified delimiter into an array of sub-strings.

Example

‘ABC.12345’.split('.')

Returns ['ABC', ‘12345’]

You can use the elementAt(index) function (0 based) to access either part:

'ABC.12345'.split('.').elementAt(0)

Returns 'ABC'

Looks up the specified index number in a list. For example, find the 3rd item in the list.

Example

elemantAt(workitem.roles.witness, 2)

Returns the 2nd witness in the list.

Returns a new list constructed from the specified property of each element in the list. 

Example

A participant may have more than one role on a work item (e.g. both client and claimant). 

Where we need to extract the participant role of a recipient to a document, the results are therefore returned as a list.

Using the pluck expression allows us to extract what we need from that list. 

For example, on a document template that has a To: Recipient role, create a document calculated field on Document Recipient > Context Participant. Use the expression:

pluck(roles, 'roleType.systemName')

This would return the system names of the role of the selected document recipient: e.g. "client,claimant" 

This can be combined with the If Then Else statement. 

e.g. Where a letter is directed to one of a number of participant roles, you may wish to amend the subject line of the letter to best reflect the recipient's interest: 

if(contains(pluck(roles, 'roleType.systemName'), 'client'))           
Then           
'Your claim'           
else           
'Your clients claim'

In this example, when writing to either the client or any of their representatives: if the recipient is the client, return the words "Your claim", else return "Your client's claim". 

Declare a local variable and assign a value to it.      
Use the ; character to end the declaration.      
Example

var sub_total1 =       
fee-estimate-drafting-amount.value +       
fee-estimate-due-diligence-amount.value      
;      
var sub_total2 =       
fee-estimate-deduction-of-title-amount.value +       
fee-estimate-financial-charges-release-amount.value      
;      
Var total = sub_total1 + sub_total2

;      
Format(total, ‘c2’)

This creates two local variables to capture two sub totals.      
It then creates a third variable and adds the two sub totals together to store the total value.

Finally, it formats the total as a Currency value.  

NB! If any field values in the above calculation are Null, the sub totals / total may also return Null.      
Use the coalesce command to replace any Null field values with 0      
For example: 

coalesce(fee-estimate-deduction-of-title-amount.value, 0)      
 

Mathematical Calculations 

() x2 / x + - 

Calculations can be performed using the standard BODMAS rule.

Example

currencyAmountToWords(document.questionnaire.weekly_pay_amount.value * 52, 'usd' , 'title') =

Takes the amount input by the user into a prepare document questionnaire field and multiplies it by 52. 

It is then formatted to return the value in words, in US format: 

One Thousand Three Hundred and Forty-Four Dollars 

select  

Projects each element of a list into a new form. 

Parameter: 

Selector = a transform function to apply to each element to return all the results as a single value. 

roles.claimant.select(x => x.ods.name)

Returns: 

Brian Edwards,Whit Stillman,John McClaim,James Sample 

Iterate through each of the claimants for the work item. 

x represents each individual entry returned by roles.claimant.

Accordingly, x (roles.claimant ) is the parent root and child tags can be used to extract specific data.

In this example, ods.name is used to obtain the name of each claimant.

Select then returns all the results and projects into its new form (a list of claimants presented in a comma-separated format).      
 

selectMany

Projects each element of a sequence to a list and flattens the resulting sequences into one sequence.

Parameter: 

Selector = a transform function to apply to each element to return all the results as a single value. 

workitem
.roles.third-party
.selectMany(x => x.ods.contact.email)
.select(x => x.value)
.join(', ')

This lists out all the emails for third parties on a work item.
We have a list of third parties and each one of those third parties has a list of emails.

The selectMany in this case, will take each list of emails and flatten it out into a single list, then you can do a simple / 'normal' select to get the email value from a single list.

This is particularly useful for financial queries:

invoiceDetails.transactions
   .selectMany(x => x.financialTransactions)
   .filter(x => x.segmentCode.code = 'ABC123')

where

Allows you to filter a list/array based on some predicate.

See the filter function below.

workitem.roles.witness     
.where(x => x.ods.name.startsWith('Bob'))     
.select(x => x.ods.name)     
Returns:

All the witness' names that begin with ‘Bob’.

any

Returns a true result where any result in the list matches a value. Otherwise, it returns false.

form-limtestform.housing-multiple.any(x => x.id = 500000525)

Returns a true result if ANY of the entries selected by the user return a value of 500000525.

This function is ideal for a situation where the user can select multiple entries from an option set, and you need to determine if one specific entry was selected.     
E.g.:      
An option set is presented to the user, asking them to select ALL the Housing Statuses that the client has held in the past 3 years.      
This will check whether the user selected the option set entry for HomeOwner, even if they also selected other statuses, and returns the appropriate text.

if (form-limtestform.housing-multiple.any(x => x.id = 500000525) = true) then     
  'The Client has been a HomeOwner'     
else     
  'This Client has not been a HomeOwner'

As a second example, imagine trying to find whether the first half of a property's postcode is a match on a code in a list of restricted codes. E.g., is M33 3AB on the list, by matching just ‘M33’.

/* The postcodes you want to check for */
var referenceList = [ 'M33', 'L22', 'BD1' ];
 

/*
 The postcode you are checking against.
 In a real implementation, for the client, this is probably:
   var realPostcode = context.client.locations.5002500.address.postcode
*/
var realPostcode = 'L22 2AY';
 

/*
 For each of the reference postcodes ('r'), check whether our real postcode
 starts with 'r'.
*/
var matched = referenceList.Any(r => startsWithIgnoreCase(realPostcode, r));

if (matched) then true else false

all

Returns a true result where all results in the list match a value. Otherwise returns false.

workitem.roles.witness

.all(x = x.ods.name.startsWith('Bob'))

Returns a true if ALL of the witness' names start with 'Bob'.

Combining a couple of the functions above: getting a list of child properties using where to filter them based on the value of a form builder field (zz-required) and then using all to check whether they all have the same specified requirement-type value.

children!q?path=property!1-1000     
.where(x => x.form-property-status.property-zz-required.id = 5023402)     
.all(x => x.form-property-status.property-zz-requirement-type.id = 500000094)

filter 

Filters a list of values based on a predicate. filter is an alias of where.

Parameter: 

Predicate = a function to test each element for a particular condition. 

 roles.claimant           
.filter(x => x.legalCapacity.legalCapacity = true)           
.select(x => x.ods.name)

Returns: 

Whit Stillman,John McClaim 

Iterate through each of the claimants for the work item and filter by the legal capacity of each claimant.

I.e. x.legalCapacity.legalCapacity = true

Select returns the name of the each relevant participant and transforms the filtered results into a list of claimants presented in a comma-separated format.  

join  

Concatenates the elements of a list, using the specified delimiter between each element. 

Parameter: 

Delimiter = String 

e.g. join ('|') 

roles.claimant           
.select(x => x.ods.name)           
.join(', ')

Returns: 

Brian Edwards, Whit Stillman, John McClaim, James Sample

Remember: by default, the select function will return multiple values in a transformed list/array. 

join allows each value in the list to be replaced by a different separator – in this example, a comma followed by a space. 

Alternatively,  

.join('|') - returns a pipe-separated list. 

.join('\n ') - returns entries separated by a "new line" or carriage return.     
 

replace 

Replace each instance of a value with another value. 

Parameters: 

oldValue = string 

newValue = string 

roles.claimant           
.select(x => x.ods.name)           
.join(', ')           
.replace(', ', ' and')

Returns: 

Brian Edwards and Whit Stillman and John McClaim and James Sample 

+44 replace with 0 

replace(roles.claimant!1.ods.contact.direct-line!1.value,'+44 ','0')       
 

replaceLast 

Replace the last instance of a value with another value. 

Parameters: 

oldValue = string 

newValue = string 

roles.claimant           
.select(x => x.ods.name)           
.join(', ')           
.replaceLast(', ', ' and')

Returns: 

Brian Edwards, Whit Stillman, John McClaim and James Sample 

As above, where join produces a list of comma-separated values, the final comma is replaced with the word "and". 

This is typically used in letters and emails to return a list of participants.       
 

orderBy 

Sorts the elements of a list in ascending order. 

roles.claimant      
.select(x => x.ods.name)      
.orderBy()      
.join(', ')

Returns: 

Brian Edwards, James Sample, John McClaim, Whit Stillman 

The list of participant names is returned in alphabetical order. 

You can also pass in a predicate to order by different properties before returning a set of results. For example using this data:

{      
   "workitem": {      
       "roles": {      
           "witness": [      
               {      
                   "roleOrder": {      
                       "value": 1      
                   },      
                   "ods": {      
                       "name": "Nathan Witness"      
                   }      
               },      
               {      
                   "roleOrder": {      
                       "value": 2      
                   },      
                   "ods": {      
                       "name": "Wendy Witness"      
                   }      
               },      
               {      
                   "roleOrder": {      
                       "value": 3      
                   },      
                   "ods": {      
                       "name": "Andrew Witness"      
                   }      
               }      
           ]      
       }      
   }      
}

Script example 1:

workitem.roles.witness      
.orderBy(x => x.ods.name)      
.select(x => x.ods.name)

This script:

1. Takes the list of witnesses.
2. Orders the list alphabetically by name.
3. Returns only the name property:

[      
   “Andrew Witness”      
   “Nathan Witness”      
   “Wendy Witness”      
]

Script example 2:

workitem.roles.witness      
.orderBy(x => x.roleOrder.value)      
.select(x => x.ods.name)

This script:

1. Takes the list of witnesses.
2. Orders the list by role order.
3. Returns only the name property:

[      
   “Nathan Witness”      
   “Wendy Witness”      
   “Andrew Witness”      
]      
 

orderByDescending 

Sorts the elements of a list in descending order. 

roles.claimant           
.select(x => x.ods.name)           
.orderByDescending()           
.join(', ')

Results: 

Whit Stillman, John McClaim, James Sample, Brian Edwards

The list of participant names is returned in reverse alphabetical order.       
 

union  

Joins multiple lists together 

Source1 – first list 

Source2 - second list 

etc 

roles.claimant-counsel           
.select(x => x.ods.name)           
.union(roles.claimant-solicitor.select(x => x.ods.name))           
.union(roles.claimant-litigation-friend.select(x => x.ods.name))

Results: 

Andrew Barrister, Larry Friend, Simon Solicitor 

Returns a list of all the participants in any of the three roles that act on behalf of the claimant (counsel, solicitor, litigation friend). 

Note that other functions, such as Join, orderBy, etc., can be applied to the result.       
 

Note that where a union function is called and no results are found, the expression will return null. 

To prevent this, a filter can be placed on the union so that it only returns a result if at least one value exists. 

roles.claimant           
.select(x => x.ods.name)           
.union(roles.defendant.select(x => x.ods.name))           
.union(roles.claimant.select(x => x.ods.name).filter (x => x.ods.name <> null))           
.join(', ')

In this example, a filter is applied to the union with a litigation friend participant role - as this role may not always be filled a work item.       
 

sum 

Returns the sum of a list of numeric values. 

workitem.descendants!q?path=invoice-general&closed=true            
.sum(x => x.invoiceDetails.totalAmount)

This expression performs a sum of all the 'General' Invoice amounts on the work item.        
 

average 

Returns the average of a list of numeric values. 

workitem.descendants!q?path=invoice-general&closed=true.           
average(x => x.invoiceDetails.totalAmount)

This returns the average invoice amount.       
 

min 

Returns the minimum value in a list of values. 

workitem.descendants!q?path=invoice-general&closed=true.           
select(x => x.invoiceDetails.totalAmount)           
.min()

This returns the invoice with the least total amount to be paid.       
 

max 

Returns the maximum value in a list of values. 

workitem.descendants!q?path=invoice-general&closed=true.select(x => x.invoiceDetails.totalAmount)           
.max()

This returns the invoice with the largest total amount to be paid.