How to Build Logic, Edit Checks, and Dynamic Behavior Into a Form.
This article covers the fundamentals of building any type of conditional action on a form, along with tools and general tips.
Table of Contents:
What is a conditional action?
Conditional actions (CAs) are any action that needs to be performed on a field or form based on a predefined condition being met. The following types of actions can be set up. Each one is linked to more details around their specific functions.
- Validate (Edit check)
- Email notification
- Popup message
- Event Trigger
- Event Terminate
Setting Up and Editing Conditional Actions
Prerequisite: User has Access to Form Builder and Save changes to forms
Select the object on the form that the action needs to be performed on. If the form needs a Hide condition, tap anywhere on the form outside of a field.
This opens the CA builder where any existing CAs on the current field can be accessed, or new ones can be created. To add a new CA, tap the add button (1) and then choose the desired action (2):
Next define the condition using the toolbar along the bottom. The arrows can be used to insert new conditions above/below the current selected row.
Continue to use arrows to drop new criteria (conditions) in. This will become the set of conditions which must be True in order for the selected action to occur. Read more below about the various criteria available.
Tap any row within the condition to highlight it and then either insert above/below, or delete it altogether. Rows can also be re-ordered by dragging them.
Lastly, tap OK, and then save the form in the form builder.
The form Must be saved in the form builder to save the conditional action
A similar workflow is done on the Mobile App as shown below.
Deleting the entire CA:
Deleting a single criteria:
Deleting the entire CA and Deleting a single criteria:
Conditions vs Blocks
By default, as shown above, the "Condition" option is selected when inserting new criteria. This creates a linear condition using 'And' or 'Or' to join each of the criteria. Sometimes conditions are more complex with a larger set of 'And's joined together by 'Or's. Here's an example:
Grouped criteria like above are referred to as "Blocks". To add a block, tap the block button first, followed by the insert arrow:
Then, with the whole block selected, tap the condition button and insert a criteria into that block:
Copying Conditional Actions
When a CA is copied, it goes to a local clipboard and can then be pasted via the paste icon to another field on the same form without losing any of the parameters.
Pasting CAs From One form to Another Form
When a CA gets copied, it also goes to the CA Clipboard where it can be accessed on other forms if needed.
When using the CA clipboard function, any field-based conditions that are not external variables will be reset and must be redefined on the destination form where it's being pasted. Other types of conditions will be retained.
To Paste a CA from the Clipboard, first open the CA builder on the field where the CA is needed, then open the clipboard and insert the desired CA. Notice in the example below, the criteria from the source condition got dropped because it is not an external variable.
In the mobile app, with a CA selected, tap the Copy icon at the top of the screen. Exit and open any other form or field. Tap paste within the conditional action screen.
Number Calculation – Computes a specified formula to compare to another number of calculation
Date/Time Calculation – Compute a Date/Time calculation to compare to a date or number. This will calculate the number of seconds and then return the value to the granularity defined within the form properties, For example, If the date granularity on the form is set to Days, 15January - 13January will return a value of 2.
Current Date - Use the current date in a comparison or calculation. This will be the current date/time of the user doing data entry based on their own time zone setting.
SubProfileID - Uses the Subject Profile ID of subject.
TxDate - "Treatment" date. This is the date of registration. In other words, the date defined by the study Builder as the visit/transaction date on the form that is serving as the subject registration form.
Current Interval - Use this to check the current scheduled visit interval of the data being entered. For example, Female subjects at the 3 month follow up visit do not need Vital signs collected. The condition would be:
If Current Interval is equal to 3-month follow up
AND External value (Gender) equals Female
Sites - This allows builders to use site ID (database ID) in conditions. The site ID can be found in the Site Manager:
Randomization - This will display in the criteria as the name of the randomization. Use the subject’s randomization allocation (coded value) to define a condition. That is found in the randomization allocation table:
External Values – List of External Variables that have been predefined within the external variables configuration. This is how cross-form logic is accomplished. For example, checking a date on the current form against a date on another form.
Fields – All fields on the current form.
Limitations and Considerations
Some actions are dynamic, meaning they are run during form completion or form rendering. Other actions don't get processed until the user taps save on a form. Consider this order of events when building in form logic.
- Hiding - Gets processed when opening a subject's casebook, opening a form, and filling out a form. If using several Hide CAs at the form level, this can start to slow down how fast a subject's casebook will load.
- Validations/edit checks - Get processed only when a form is saved
- Computations - Run both if a trigger condition is met during form completion and when the form is saved
- Populate - Runs when the form is opened and when a condition is met during form completion. Does not run based on saving the form
- Email Notifications - Run only when the the form is saved
Validations and Disable actions are the only two types of conditional action that should be used inside a normalized table (sub-form).
When building a condition on a field in a table, you can reference any other field within the table, or a field outside of the table. However, fields outside of a table cannot reference fields inside of the table. This is because the data inside the table is repeating, so the condition would not know which row to reference.
If a field contains both Hide and Validation type CAs, it's possible in instances where the field becomes hidden later on, a pre-existing query may exist from a validation that fired. To prevent this, an additional condition would be needed on the field to check for field being 'not blank' to prevent the validation from firing when the field is hidden.
Upload field types cannot be used with conditional actions. For example, the following CA would not work: "Send an email notification if 'Upload field A' is not blank." From a conditional action and data validation perspective, the system does not recognize changes to upload fields. Additionally, characterizing an upload field as 'required' in the field properties does not have an effect.