Functions

Evaluates expression, if the expression is true it returns or executes the then statement, if the expression evaluates to false it returns/executes the else statement.

if(expression, then, else)

if(${ae_death} = 'yes', 'SAE', if(${ae_hospital} = 'yes', 'SAE', if(...)))

This nested if statement will eventually cascade through the entire SAE criteria list to see if any were answered 'Yes', and if so it will return 'SAE', if not then it will move to the next criteria and so-on. The last statement should return 'false' or similar negative value.

Returns the value defined by expression if the question's value is empty. Otherwise, returns the current value of the question.

This can be used to ensure that a random number is only generated once, or to store the first value entered for a question in a way that is retrievable even if the response is changed later.

once(expression)

once(today())
When used in a calculation, returns the current date on form load. If an expression is in a calculation, constraint, or required condition, it is evaluated when the item becomes relevant and the item is not empty. Typically used in calculations. Could also be used in relevant conditions or constraints, but in these cases it's usually more clear to use as if() statement. For example:

Instead of using once(), you could also if(. != '', today(), .). If it's not empty, do expression. Otherwise, leave unchanged.

Checks whether string2 appears in string1, where string1 is a space-separated list of values. Either or both could be item references instead of hard-coded string literals.

selected(string1, string2)

selected(${diagnoses}, 'cancer')
Returns true if “cancer” was selected from a set of diagnoses. Otherwise, returns false.

not(selected(., 'c') or selected(., 'd'))
Returns true if the user did not choose c or d from the current item.

Note: Can be used as a shortcut for writing many or clauses. For example, selected('a b c d e', .) is a shortcut for ". = 'a' or . = 'b' or . = 'c' or . = 'd' or . = 'e'." This could be useful in if() statements, relevant logic, etc.

Returns the number of choices selected in a multiple choice question.

count-selected(select_multiple_item_name)

count-selected(${days_sick})
Returns the number of days the subject was sick (e.g. from a set of choices ${days_sick} such as Mon, Tue, Wed, etc.). Taking a space separated string and telling you how many of a given value exist. Can also be used to count the total number of selection choices in a space separated list. If you concatenate strings together with a space, or join repeating data with a space, in a calculate item, this function would return the total number of items in that string.

Returns the largest member of nodeset.

Only works on sets of numbers. Empty values (that is, variables referencing unanswered questions) are actually empty strings, and will not be automatically converted to zero (0). Learn more about Null Values in Form Logic.

max(nodeset)

In the below example form definition, the calculation max(${child_age}) would return the largest age of all the ages in the repeating item group.

If you wanted to see if one of the children was, say 5 years old, you could use the join or concat function to produce a string of all the responses, then use this string as the argument for the selected function.

For use with repeating item data from a different form, the max function can be used directly as part of the cross-form data pull. In this example, the largest value of the item from all repeats would be returned:

max(instance('clinicaldata')/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID='Event OID Here']/FormData[@FormOID='Form OID Here']/ItemGroupData[@OpenClinica:ItemGroupName='Item Group Name Here']/ItemData[@OpenClinica:ItemName='Item Name Here']/@Value)

Returns the smallest member of nodeset.

Only works on sets of numbers. Empty values (that is, variables referencing unanswered questions) are actually empty strings, and will not be automatically converted to zero (0). Learn more about Null Values in Form Logic.

min(nodeset)

In the below example, the calculation min(${child_age}) would return the lowest age of all the ages in the repeating item group.

Returns the sum of the members of nodeset. Can be used to tally responses to a repeated select question.

sum(nodeset)

The below example uses this function to tally the number of meal preference.

Returns the sum of the members of nodeset. Can be used to tally responses to a repeated select question.

count(nodeset)

The below example asks the user for the number of family members, then uses the count function to ensure follow-up questions are asked once per each family member.

Returns the number of non-empty members of nodeset.

count-non-empty(nodeset)

count-non-empty(${bp_sys})
Returns the number of times systolic blood pressure was blank, where ${bp_sys} captures systolic blood pressure inside a repeating group.

If a user adds a repeating group occurrence but does not put data into any of its fields, the count() function would increase by 1, but the count-non-empty() function would not increase.

Returns a particular iteration of a repeating value.

indexed-repeat(item_name, repeating_group_name, iteration)

item_name is the variable you want to retrieve
repeating_group is the name of the repeating group containing the item_name
iteration is the repetition number for the item_name

indexed-repeat(${bp_diastolic}, ${bp_rg}, ${bp_number})

When used as a calculation, returns the diastolic pressure from a specific repeat instance, where:

• ${bp_diastolic} is the value by the diastolic pressure captured across one or more repetitions
• ${bp_rg} is the name of the repeating group that collects multiple blood pressure values
• ${bp_number} is an integer indicating which repetition of the blood pressure to return

Returns an integer equal to the position of the current node within the node defined by xpath. The first entry has a position of 1, second entry 2, and so on.

Most often this is used in the form position(..) to identify the current iteration within a repeating group.

position(xpath)

position(..)
When used as a calculation inside a repeating group, will return the current repeat iteration. Could be used to assign a number for each repetition. In the example below, the first repeating group captures the names of each household member. The second repeating group asks for the birthdate for each household member entered in the first group. This shows how position() can be used with indexed-repeat().

Concatenates one or more arguments into a single string.

If any arg is a nodeset, the values within the set are concatenated into a string.

concat(arg1, arg2, arg3...)

concat(${yyyy},'-',${mm},'-',${dd})
Combines year, month, and day (each captured separately) into a single item formatted YYYY-MM-DD.

concat(${temp},' ⁰C')
Combines temperature value with units label (e.g. to display "37 ⁰C").

Converts arg to a string.

string(arg)
string references the item for which you wish to count characters

Returns True if the string is an exact and complete match for the expression. Regular expressions provide a standardized way of validating the syntax of data entered.

regex(string, expression)

string is the value you want to apply the regular expression to
expression is the regular expression

regex(., '([01][0-9]|2[0-3]):[0-5][0-9]') and string-length(.) = 5
When used as a constraint, ensures the user enters time in 24-hour format (HH:MM)

regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}')
When used as a constraint, ensures the user enters an email address in the format xxxx@xxxx.xxxx. Learn more about how to construct regular expressions.

Returns the substring of string beginning at the index start and extending to (but not including) index end (or to the termination of string, if end is not provided).

substr(string, start, end)
string references the data item you wish to parse
start is the index number of the beginning character you want to include
end is the index number of the first character after start that you do NOT want to include

Members of string are zero-indexed, so the first character of the string has index value of 0, the second character an index value of 1, etc.

substr(${date}, 0, 4)
Returns just the 4-digit year from a date field which has a format such as YYYY-MM-DD.

Returns the substring of string before the first occurrence of the target substring.

If the target is not found, or string begins with the target substring, then this will return an empty string.

substring-before(string, target)
string references the data item you wish to parse
target is the stopping point (up to which the system will return the partial string)

substr-before(${kit_num}, '-')
If the value of ${kit_num} is "123-ABC-XYZ", the function would return 123. Returns the string value before the first occurrence of the target.

Returns the substring of string after the first occurrence of the target substring. If the target is not found this will return an empty string.

substring-after(string, target)
string references the data item you wish to parse
target is the starting point, beyond which the system will return the remaining string

substr-after(${kit_num}, '-')
If the value of ${kit_num} is "112-ABC-XYZ", the function would return ABC-XYZ. Returns the string value after the first occurrence of the target. To return just XYZ, you could run this function two times, nested together.

Returns the number of characters in string.

If no value is passed in, returns the number of characters in the value of the question that this function call is tied to which can be useful in a constraint expression.

string-length(string)
string references the item for which you wish to count characters

substr(., string-length(.) - 4, string-length(.)) = ".pdf" or substr(., string-length(.) - 4, string-length(.)) = ".PDF"

Ensures only PDF files are uploaded when used as a constraint on a file field.

The substring function first gets the last 4 characters of the file name. Then it checks to see if the PDF file extension is all lowercase or uppercase.

Returns a copy of a string where every occurrence of a specified character is replaced by a new character.

translate(string, fromchars, tochars)

string is the item you want to translate
fromchars are the characters, if found within the string, you want to translate
tochars are the characters you want to translate to

If fromchars is longer than tochars then every occurrence of a character in fromchars that does not have a corresponding character in tochars will be removed from the string.

translate(substr(., string-length(.) - 4, string-length(.)), 'pdf', 'PDF') = '.PDF'

When used as a constraint on a file field, ensures the files with a PDF extension are uploaded, regardless of the case in which the file extension is written.

The substring function first gets the last 4 characters of the file name. Then it checks to see if the PDF file extension is all lowercase or uppercase.

translate(${input_item}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')
Would translate any lowercase letter into an uppercase letter for the string input_item.

OpenClinica reads in cross form data from a select_multiple item as a comma separated list. However, if you want to treat this as a select_multiple value on the form you read it into, it must be treated as a space separated list. For example, the following expression would convert these values into a space separated string upon reading it into the form:

translate(instance('clinicaldata')/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID='Event OID Here']/FormData[@FormOID='Form OID Here']/ItemGroupData[@OpenClinica:ItemGroupName='Item Group Name Here']/ItemData[@OpenClinica:ItemName='Item Name Here']/@Value, ',', ' ')

not(expression)

Truncates the fractional portion of a decimal number to return an integer.

int(number)

int(${age})
If ${age} = 24.6, would return the value 24.

Converts arg to number value.

If arg is a string of digits, returns the number value.

If arg is True, returns 1. If arg is False, returns 0.

If arg cannot be converted, returns NaN (not a number).

number(arg)

number(${year})
if ${year} = "1995", then number(${year}) would return 1995

Rounds a decimal number to some number of decimal places.

round(number, # places)

round(${pi}, 4)
If ${pi} = “3.14159”, then round(${pi}, 4) would return 3.1416

Returns a random number between 0.0 (inclusive) and 1.0 (exclusive).

random()

once(round(random()*3+1,0))

The above expression would return an integer of either 1, 2, or 3, and could thus be used to randomly assign participants to one of three groups.

The following logic could then be used to map the output of the above function to one of the three groups:

if(${rndm} = 1,'A', if(${rndm} = 2,'B', 'C'))

Returns the current date without a time component.

today()

The expression . <= today() could be used in a constraint to ensure the date entered is not a future date.

Returns the current date and time with the timezone.

now()

For example, this can be used to set the current date and time as default.

Converts time to a number representing a fractional day.

decimal-time(time)

For example,

• decimal-time('12:00:00.00+01:00') → evaluates to 0.5
• decimal-time('18:00:00.00+01:00') → evaluates to 0.75

Returns date as a string formatted as defined by format.

format-date(date, format)

format-date(${date},‘%d-%b-%Y’)

If ${date} = 2028-11-06 would return 06-Nov-2028

Month and day abbreviations are language and locale specific. If form locale can be determined, that locale will be used. Otherwise, the device locale will be used.

Returns dateTime as a string formatted as defined by format.

format-date-time(dateTime, format)

Raises number to a power

pow(number, power)

pow(2,3)
Returns the value 8.

Returns the natural log of number.

log(number)

log(30)
Returns 3.4011973816621555, the natural log of 30.

Returns the base-10 log of number.

log10(number)

log10(30)
Returns 1.4771212547196624, the base-10 log of 30.

Returns the absolute value of number.

abs(number)

abs(-5.23)
Returns 5.23.