Share or Open on Web

Conditional actions - Referred to commonly in the help documentation as “CAs” - allow you to automate various actions depending on a specified condition (aka. expression) being true. The Conditional Action designer is found in the Form Builder, within any form, under the field and form properties. While most actions are designed at the field level, it's also possible to create Edit checks and Hide conditions at the form level.

Table of Contents

Accessing the CA Designer

Based on the currently selected object on a form, The conditional actions button can be tapped to open the CA design screen for the currently selected object in the form. On the web it looks like this:

The value shown indicates the number of Conditional Actions on the selected field or form.  As conditional actions are added or removed on the field, the number will change. 

On the app, use the CA button at the top - or the shortcut of CAs shown in the small window to right of CA button:

Open

How to Build a Conditional Action

To create a new conditional action, select the type of action that needs to be performed:

To insert conditions/criteria in the Expression Area shown in yellow above, click on the arrow at the bottom. Once at least one condition exists, the other arrows can be used to insert additional expressions where they are needed. To create blocked expressions, select the "Block" button prior to inserting a new condition. Expressions can also be deleted using the red "X" icon.

A similar process is shown here on the app:

Tap the icon at the top to create a new action and then select the “Type” of action needed.

Using the insert row icons in the middle will allow for defining and inserting the criteria from the bottom.

To delete a conditional action or criteria within a condition, first tap the row you want to delete, and then swipe to the left and tap the delete button:

Criteria that can be used as conditions

Number Calculation – Computes a specified formula to compare to other criteria

Date/Time Calculation – Compute a Date/Time calculation to compare to other criteria.  When using the calculation the field is calculating days, minutes, etc. To calculate years remember to divide by 365.25 days in a year.  When calculating days, divide by the number of days in a month.

Constants - System-known components:

• 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 subjects.

TxDate - This is the date the treatment started. It is usually baseline; however, that is determined by the study designer. It also is entered when the subject is registered (enrolled).

Current Interval - This is a very powerful constant and is used to compare the current interval. One of its many uses is the ability to use the same form over multiple intervals despite that form having subtle differences for each interval. By comparing the current interval you can hide the fields that are irrelevant to specified intervals.

Sites - This allows builders to use site ID (database/system ID) in conditions.  You can hide forms or fields based on site ID.  Note.  Please be sure to use the DB ID from the site manager as in the two screenshots below:  The site manager ID of the site we want to use is 2.  Notice in fig 2 how the DB ID of 2 is used in conditional action.  *Please note you will also need a trigger statement to populate. The site is equal to the text of 2 AND some trigger that is always true from the form.

Randomization - Use the subject’s randomization allocation (coded value) to define a condition. The randomization name will be displayed in the list based on how it was defined.

External Values – This allows the user to use defined fields from the External Variables application against other fields from other forms. This is covered in the External Variables help document.

Fields – list of all fields on the current form.

To create an entirely new conditional action, or to copy one for pasting onto another field, use the controls here:

When done, click the "Ok" button at the bottom prior to saving the form. Be sure to SAVE the form prior to exiting the form builder or opening a different form

Copying and Pasting Conditional Actions

Conditional Action Limitations and Considerations

Normalized Tables
Validations and Disable actions are the only two types of conditional action that should be used inside a normalized table (sub-form)

Hidden Fields
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 CA would be needed on the field to prevent the validation from firing when the field is hidden.

Upload Fields
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.

Conditional Action Types and Attributes

Validations (Edit Checks)

The Conditional Action type “Validation” allows users to validate a field’s value based on data or system variables. This is commonly known as an edit check and will cause an automatic query to be generated when the defined condition(s) are met. When the validation is triggered during data entry, a query is generated with the pre-defined “error message”:

This example shows the checking of a numeric range on a number field.

Select the field and open the CA design screen as shown below

Create a new action and select “Validation”:

Cross-form edit checks:

If an edit check references a field on another form in order to validate the data, changing the data on that other form will run the edit check at the target when the user is not active on the form. For example:

Form B has a date field in a normalized table that checks to make sure the date is not prior to date on Form A. If the user has already entered both forms A and B to evaluate the edit check as false, but then goes and updates Form A date field to be after the date entered in Form B, a query will automatically open in Form B’s normalized table row even though the user did not have that form open.

Validation Using the Min/Max property 

Note: This method is only available on number fields

The Min and Max fields represent the acceptable range of values that can be entered into a field.  For example, if the Min is set at 50 the field will display an error message stating, “Value violates low range (50)” when the value entered is less than 50. To set a single set of ranges for the Systolic Blood Pressure:

In this case, it is not necessary to write a manual conditional action. However, if the field is enabled and required based on another field’s answer or multiple validation conditional actions based on different range values, validations would need to be written for each of those messages.  Remember, these are only examples and the validation conditional action can be used for many different situations to make Users aware of an event. 

Override Query Deployment

A unique function with Validations is the ability to override default query distribution. By default, queries are deployed to specific roles as defined in the study configuration. However, each validation can be designed so when the edit check is triggered (e.g. A number is out of range), the resulting query is deployed to a more limited set of users than what might be normal.

In the example below, a validation (edit check) is set up on a field to only send a query to the Data Manager if the validation is triggered. This will override the normal query distribution which might be normally set to go to all roles in the study.

Hide - Conditionally hide fields and forms

Field Hiding

Fields can be hidden based on data entered (or not entered) either on the current form or other forms (external variables). This is also known as “Skip Logic”, used to focus data entry only on what is needed rather than leaving it to the user to decide what applies. This is in contrast to the Hidden field property or Role-based field blinding.

For a Hide condition, a common example is to collect further details based on a prior response.

In the example shown above, the conditional action is set up on the Specify field:

In this example, the operator is set as “Not Equal” because the field where the action is being written needs to be hidden at all times until the Race field has “Other” selected during data entry.

Example 2 - Hiding a field based on choices made in a multi-select field

The operators in a multi-select field work differently because there is no exact value to use as a trigger. A user could select one, some, or all choices. For this reason, the operators in a multi-select field are “in” and “not in” - meaning “includes” and “does not include”.

In this example, a ‘Specify’ field only needs to be displayed if the user selects the choices Mexico or Other, or both. So the condition should be to Hide if the multi-select field does NOT include the value 4 or 9 (coded values for the choices Mexico and Other):

In data entry, it looks like this:

Hiding Tabs/Pages On a Form

Hidden Tabs are often used when a form contains multiple tabs, but some tabs aren’t applicable and don’t need to be accessible for data entry.

Define the Conditional Action

The first step to hiding a tab is to define the conditional action as a HIDE. This can be done on any field (usually the first one) within the tab that needs a Hide action.

You will need to go into a test subject/form to test this scenario. It can’t be seen in the form builder preview mode. In this example, a tab is hidden until a response is made on the first tab:

Now notice the trigger has be set to show all the tabs that were hidden.

Hide Forms and Visits

There are a variety of reasons to dynamically change how visit forms and intervals are displayed in the Scheduled Visit/Event Forms table. One such reason may be differing randomization arms calling for differing treatment schedules. Protocols may define conditions where a form is not required based on the value of a field in a previous form.

Regardless of the reason, TrialKit allows you to hide forms and entire visit intervals in the Scheduled Visits/Events Table by creating form-level conditional actions. The remainder of this article explains how this can be done.

Form Level Conditional Actions

Edit Checks and Hides are the only two applicable actions to write at the form level.

In addition, when an interval has no visible forms, the entire interval will be hidden by the system. Let’s take a closer look.

Defining a Form Level Conditional Action

To define a form-level conditional action, load the form into the Form Builder. 

1. While no fields or labels are selected,

2. Click the Conditional Actions link.

This will display the Conditional Actions builder in the form palette. 

The below conditional action hides the current form (for this example the Follow-Up form was used) for the 3-Month visit interval if the subject is a female.

To determine the current interval, select it from the Constants section of the conditional action expression or formula.

For each interval that needs to hide a form, create a Hide conditional action. The rule for hiding is very simple. If any of the hide conditional actions are true, that form in that interval will be hidden.

Remember to tap OK and Save Form

Once the form-based conditional action has been defined, you can test it by viewing the Scheduled Visits/Events table.

Forms can also be hidden within unscheduled visits assuming the condition references an external variable in a scheduled visit.

Hiding Visit Intervals in the Scheduled Visit/Events Forms Table

TrialKit automatically hides visit intervals based on the forms that are available within the given interval. If there are one or more forms available, then the interval is displayed. If all the forms in a given interval have been hidden due to a condition, then the system automatically hides the visit interval.

Disable

The Disable action allows the user to define when a field can have data entered into it, but where the field itself is still visible. 

An example is shown here, where a description will be required if Yes is selected. The highlighted box on the form is grayed out when No is selected. 

Compute

The Compute Value Conditional Action allows a User to build calculations from a variety of operators and factors.

Compute actions will fire either when the condition is met (the trigger event) or when the user saves the form.

The formula for the computation is built in the bottom portion of the CA design screen (highlighted below). This example is a compute for age on a number field, based on a date of the birth variable being collected somewhere else:

BMI Sample Formula (standard units): weight (lb) / [height (in)]² x 703

Example: Weight = 220 lbs, Height = 6’0″ (72″)
Calculation: [220 ÷ (72)²] x 703 = 29.8

Example of BMI calculation on the web CA design screen:

Mobile app conditional action designer with the same CA:

Another way is to do a scoring field on the web is to add up the fields:

The condition will look at the image below: Notice how there are no trigger fields used.  The calculator next to the field will compute or on save of form it will always compute.

Computation Examples

TrialKit allows users to automatically populate values based on a specified condition and trigger. Populating can be based on all available conditions. Any field type can be populated with the exception of upload fields. This document explains how Populate Value works.

Populate

Populating a field is a way of automatically inserting specific data into a field based on some condition.

The populate action will occur either when the form is opened up or based on the defined trigger event during data entry on the form. That event is defined in the "condition" portion of the Conditional Action.

Any field defined in the condition becomes a trigger field. When a value in that field changes, the event is triggered. Because of this, and similar to Hide and Disable conditional actions, events/conditions must be triggered during data entry. This is supported in both the main form and sub-forms (normalized tables).

Defining a Populate Value Conditional Action

The Populate Value conditional action is the key to automatically populating field values. Like all other conditional actions, you must define a Populate Value for each field that you want to be populated.

The following shows a Populate Value conditional action that inserts the number 3 into a numeric field. The "3" is a Number type selected in the lower portion of the window.

The above image shows you how to conditionally populate field values. You must first enter the condition and then define the data with which to populate the field.

The condition is what defines the event to populate the field. In this case, the ABC_LFT select field is defined to be “Yes”. When the user selects “Yes” in the ABC_LFT field that will trigger the Populate Value event. In this case, the target field will be populated with the value “3.4”.

Types of Values with Which to Populate

The following describes the types of values with which to populate. It is important to understand the system will recognize the field type that you are populating and provide you with the appropriate values. There are rules for getting values to populate. One of the important rules is that a field type cannot only populate similar data. For example, if populating a date field, the source data cannot come from a text field.

• Number - This allows you to type in a number value. Remember you should only use like types. For example, you would not want to use this when populating a date field.

• Value - This allows you to enter a direct value to populate with. For example, it will include all the choices for select and radio fields. For text fields, it will allow you to enter text. For a date/Time field, it will give you a date control.

• Field - This allows you to choose from a list of fields within the current form. This list will contain fields of the same type.

• Constant - This allows you to populate with a predefined constant, including a randomization allocation. Be sure you select alike typed constant or you will receive an error message when saving the form.

• External Value - This allows you to pull data from any external field and populate the target or current field. A list of external fields that have been defined within the study will be presented.

Using Populate Value to Clear a Field - Clearing Data from a field with conditional action.

You can use the Populate Value conditional action to clear a field. It processes the condition exactly the same way. However, if you want to clear the target field, do not enter anything into the target value area, which is located at the bottom of the conditional action window. By leaving this blank, when the event is triggered by the user, the system will clear the field if the condition is true.

Populate upon form open

Populating can also be accomplished based on the form simply opening up, assuming the condition is true and there is a "Manual" property set on the Conditional action.

To create a Manual condition, simply enter the text "Manual" as the first part of the conditional action name.

When doing this Similar to a computed field. The following icon will appear next to the field and the condition will get checked automatically when a record is opened by a user.

If the condition is not yet true, the icon can be tapped by the user to manually trigger the populate if there is a “not” trigger condition already set.

Email Notifications

E-Mail Notifications - which also include in-app push notifications - allow for sending out a customized message to a specific distribution list based on some event or condition that takes place in data entry.

Before setting up an email notification CA, be sure to define the Message and Distribution list. These will be needed when configuring the CA within the form designer:

With the necessary notification and distribution list now available, the conditional action can be configured:

Distribution List

This is the list of recipients, by role, who will receive the email when the event occurs. If the role(s) selected is a site-type role, only the users at the corresponding site where the notice is triggered will receive the message. In other words, all users of a single role will not receive the notification unless the role is an Administrative role type.

1. Within the Form Builder Application, select the “Create Distribution List” link. When the link is clicked the Existing Email lists data table is displayed along with the Add New Contact form. Clicking the link will open the Define Email Distribution Lists page.

2. In the Distribution List Name text box field, enter the desired name for the distribution list, roles to receive the email, and notification type (email, push notification, or both).

3. Click the “Save Distribution List” button at the bottom of the form as shown in the figure above.  After clicking the button the Email Distribution List will populate the Existing Email Distribution Lists data table at the top of the Email Distribution Lists page.

Pop Up Message

Pop-up messages can be used to display a message to the user when they tap save on the form. This is displayed in the form save dialog window anytime the condition is met. See the example below for a

1. “Unusual value” entry in weight field where it is

2. Prompting you to verify data one last time but not putting an error on form status.

This option is not commonly used because the message goes away when the user dismisses the save popup window.

An alternative approach is by:

1. Using a text label in the form design and

2. Set a HIDE CA to conditionally display the text label (in red below) to the user. This ensures the user can always see the message, even when not saving the form.

Event Trigger

Event trigger action can be used to cause deployment of another form within the context of ePRO forms. In other words event triggers should only be setup on ePRO forms.

Select the Event Trigger type and the set the following properties described below.

Form to trigger - must be a form which already exists in the form library and gets filled out by a participant user.

Frequency at which to deploy the triggered form after the trigger condition is met

Maximum forms - How many deployments to trigger for a given event. This is alternative to using an Event Terminate condition. If terminating the event by a condition, set the max forms to something arbitrary/high.

Notification - When the event is triggered, which notification message should be sent to the ePRO subject. Notifications are separately pre-defined.

Distribution List - Which distribution list to use for deploying. This must contain the subject/patient user role in order to be subject specific where the notice only goes to the subject and not to all users under a role.

Event Terminate

Similar to the event trigger, this action will terminate a given event.

Select the Event Terminate type and the set the following properties described below. The conditional action can be on any field within the form, but usually makes the most sense to be on the field that is serving as the conditon.

Trigger Form - Which form triggered the event that now needs to be terminated

Name of the Conditional action that was used to start the triggered event now being terminated.

Flowchart of the save process

When configuring forms full of various conditional actions, some of which depend on external data, its important to have an understanding of the flow that the system follows when a user opens a form, fills it out, and taps the Save button. That process is detailed here.

1. Form opened

2. Populates and computes run. Values display in fields if applicable, but data has not yet been committed/saved.

3. As data is entered, when a field loses focus, conditions are evaluated for Hiding, Disabling, Populating, and Popup messages.

4. The form is saved by the user

5. Computations rerun

6. All Data is saved

7. Edit checks run

8. Randomization runs

9. Email Notifications run

Related articles