Summary
Table of Contents
- Variables
- Questions
- Property
- Constants
- Numeric Expressions
- All variables used in the expression must evaluate to a numeric value. A typical expression may appear as follows: weight/sqr(height)
- Date Expressions
- String Expressions
DataCollector Expressions provide the ability to write dynamically evaluated expressions, inside XML configuration files, that can reference questions and properties as variables. Expressions can currently be used in expression fields (of dependency, branch), the defaultValue field of questionType, and the renameTo field of formType. Both branch and dependency use Boolean Expressions, while defaultValue and renameTo use the expression evaluator.
Variables
There are four types of variables that can be referenced in an expression: questions, formulas, properties, and constants. Attempts to resolve the variable follow that order – first, an attempt is made to resolve the variable as a question; if that fails, an attempt is made to resolve it as a formula; if that fails, an attempt is made to resolve it as a property; and, finally, as a constant. If the variable is not one of the predefined constants, the name of the variable is returned, indicating it could not be resolved.
Note: Upon the evaluation of expressions containing a string, all spaces are removed from the value being evaluated. Therefore, all spaces should be removed from the string that is being compared to the value. For example, if the expression should check to see if a value is equal to ‘Adverse Event,’ the expression should read: value == ‘AdverseEvent’Questions
Questions can be referenced in two ways:
- If the referenced question is on the same form as the question to which the expression is attached, the question can be referenced using the questionId field in the template file.
- If the question is on a different form, the questionId can be prefixed with its dotted formId. The dotted formId is resolved using ID Resolution.
Property
Properties can be referenced directly or using bracket notation. The property, ‘studyStartDate,’ could be referenced to access the study start date for the entire trial, or reference studyStartDate[toolId] to reference a site-specific start date. Whatever is in brackets is pulled from the request, and then pulled from the properties file. Therefore, the actual property for the site-specific start date may be studyStartDate501.
Properties can also be used in conjunction with questions or forms. Below is a list of these properties:
Note: When using a form path, validationStatus, freezeStatus, lockStatus, and dataReview status will include hidden questions. For example: If only visible questions have been marked as SDV’d, the validationStatus of the form as a whole would be ‘No’.
| Property | Description | Property Options | Description |
|---|---|---|---|
| answerStatus | Resolves to the Answer Status metadata of the question or form referenced. | completed blank inProgress | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.answerStatus != ‘blank’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 must be completed. |
| violationStatus | Resolves to the Alert Status metadata of the question or form referenced. | clean alertClosedOverride alertClosed alertOpenOverride violation Note: The property option of violation refers to alerts that are open without reason. | Dependency expression: (this == ‘Y’ AND (#visit_1V.dm_1V.violationStatus == ‘clean’ OR #visit_1V.dm_1V.violationStatus == ‘alertClosedOverride’ OR #visit_1V.dm_1V.violationStatus == ‘alertClosed’)) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 must not have any open alerts. |
| validationStatus | Resolves to the Source Doc Verified metadata of the question or form referenced. | yes no | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.validationStatus == ‘yes’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 must be Source Doc Verified. |
| signedStatus | Resolves to the Signed by PI metadata of the question or form referenced. | yes no | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.signedStatus == ‘yes’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 must be Signed by the Principal Investigator. |
| freezeStatus | Resolves to the Freeze/Frozen Status metadata of the question or form referenced. | frozen partiallyFrozen unfrozen Note: The property option of partiallyFrozen only applies to forms. Questions can only be frozen or unfrozen. | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.freezeStatus == ‘unfrozen’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 is currently frozen. |
| lockStatus | Resolves to the Locked Status metadata of the question or form referenced. | locked partiallyLocked open Note: The property option of partiallyLocked only applies to forms. Questions can only be locked or open. | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.lockStatus == ‘open’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 is currently locked. |
| dataReviewStatus | Resolves to the Data Review Status metadata of the question or form referenced. | reviewed notReviewed | Dependency expression: (this == ‘Y’ AND #visit_1V.dm_1V.dataReviewStatus == ‘reviewed’) OR this != ‘Y’ Alert Text: ‘Yes’ is checked, however The Demographics Form for Visit 1 must be Data Reviewed. |
| size | Enforces a field length size restriction when coupled with questionTypeID or ‘this’ constant. The property can also be used by itself to check the number of children forms under a parent. | N/A | Dependency expression (question): this.size <= 3 Alert text (question): Length of response is greater than 3 characters. Please correct or clarify. Dependency expression (form): this != ‘N’ OR size == 0 |
Constants
Several constants have been defined for use in expressions:
| Constant | Description |
|---|---|
| this | If the expression is in the context of a question (dependency, etc), this resovles to the current stored value of the question |
| @@today | This is the recommended current time constant, based on the time zone set in their user profile. It will be displayed using the contextual question’s date format. |
| @@currentDate | The user’s current date, based on the time zone set in the user profile. |
| @@currentTime | The user’s current time, based on the time zone set in the user profile. |
| @@currentDateTime | The user’s current Date and Time, based on the time zone set in the user profile. |
Numeric Expressions
Numeric expressions are used when the expression is attached to a question of type float or integer. The following functions are supported:
- cos
- acos
- sqrt
- log
- floor
- exp
- ceil
- abs
- atan
- neg
- tan
- sin
- rnd
- asin
- sqr
While min() and max() may be expected functions for these expressions, it is recommended that the designer uses scripts to address those needs.All variables used in the expression must evaluate to a numeric value. A typical expression may appear as follows: weight/sqr(height)
Date Expressions
Date expressions provide a way to increase or decrease a base date by various time constants. All time constants must have a suffix with a pipe (|) and a time unit. The time units are:
- Y=year
- M=month
- D=day
- h=hour
- m=minute
- s=second
If the date of enrollment minus 18 years, plus a month offset were needed, an expression could be written as follows: dateOfEnrollment – 18|Y + monthOffset|M
If an assessment time shall occur 30 minutes +/-5 minutes, an expression could be written as follows: this >= iptm + 25|m AND this <= iptm + 35|m
If an assessment time shall occur at least 2 hours later, an expression could be written as follows: this >= lbtimh + 2|h
For all comparisons that use at least one partial date question, (at least one of) the partial date question(s) needs to be used on the left side of the comparison.
When a partial date is positioned on the left side of the expression, the system will compare it based on a partial date logic. However, if a full date is positioned first (on the left side of the expression), the system will try to calculate based on a full date logic which will fail when compared to a partial date.
String Expressions
String expressions consist only of variables and string literals. Literals are denoted by single quotes. If the variable cannot be resolved, it is treated as a literal having the value of the variable name. Example: ‘M0-’ + subjectStudyId. If subjectStudyId had a value of ’501,’ this expression would resolve to ‘M0-501.’
Need more help?
Please visit the Fountayn Contact Information page.