Define External Variables
External Fields are used to create Conditional Actions that access fields defined in another form and use those fields within a defined expression. External fields can be any field in the current study and are defined by the User. Constants are similar to External Fields but are provided by the system. Therefore they are constant, thus the name. The following will describe how to define both External Fields and Constants and where to access them within Conditional Actions.
External fields are only available at the study level of the system. They can be used with Site or Subject related forms. They allow Users to define fields that exist outside the current form along with the interval that the field should be evaluated in, and for use with a conditional action in the current form.
Warn the Data Coordinator if the subject is female and has lost weight since the previous Follow Up Visit.
This requires a conditional action that makes use of two external fields. The first will pull subject’s gender from the demographics form. The second will pull the subject’s weight from the most recent visit interval. To define this, the following two step process is required:
- Define the External Field in the Define External Variables application and,
- Define Conditional Action in the Follow Up Form
Define External Fields
External Fields are extremely easy to define. To define an external field, hover the mouse over the Study menu and click the “External Variables…” link as shown in the figure below.
This will open the Define External Variables application shown below.
At the top of the application is the Current Externals Data Table which will display all of the existing external fields once they are defined. At the bottom of the application is the Add New Externals form. This is where the external fields are defined which will populate the Current Externals data table. To define an external field, simply complete the Add New Externals form and click the Save External button. After defining the external field the Current Externals Data Table will display the variable.
To define the External Variables described above:
1. Complete the Add New External form fields as shown below for variable
- Name: EnrollGender
- Type: External Field
- Form: Subject Enrollment
- Field: EN_GENDER
- Interval: Unscheduled
2. Click the Save External button. After clicking the Save External button the Define External Variables application will display in the Current Externals data table as shown in the figure below.
3. Complete the Add New External fields as shown below for variable
- Name: FUweight
- Type: External Field
- Form: Demographics And Baseline
- Field: DB_WEIGHT6
- Interval: Baseline
4. Click the Save External button. After clicking the Save External button the Define External Variables application will display in the Current Externals Data Table as shown in the figure below.
Conditional Actions - External Variables
Now that the External Variables have been defined, the Conditional Actions must be entered in the appropriate forms. To create the conditional actions, hover the mouse over the Study menu and click the “Form Builder…” link as shown in the figure below.
In the Form Builder, click the Select control in the row of the Follow Up form in the Existing Forms data table as shown in the figure below.
This will load the Follow-up form into the body/grid of the Form Builder. Select the Weight field in the form as shown below.
Now click the 0 – View/Edit link next to the Conditional Actions text in the Validations section as shown in the figure below.
This opens the Conditional Actions Builder. In the conditional actions builder click the Type drop down and select Popup Message. In the Popup Message area “This Female has lost weight since the last follow-up visit” is entered. In the client area create the following expression:
1. Click Block and then the Insert Last button. Then click Condition and the Insert Into button. The Conditional Actions Builder will look like the following figure.
2. Click the first (criteria) drop down as shown in the figure below. In the drop down the External Fields that were defined earlier are displayed under the External Values section header. Select the Enroll Gender External field.
3. Click the second (criteria) field drop down and select the field choice “Female” as shown below.
4. Click the Insert After button then click the (criteria) drop down and select the Form field FU_WEIGHT.
5. Click the equal drop down and select “less than“.
6. Click the next (criteria) drop down and select the External Value, “FUweight”.
7. The Conditional action should look like that displayed in the following figure.
8. Click the OK button after completing the Conditional Action.
9. Then, click the Save Form button in the Form Builder to save the conditional action with the form. The Conditional Action will display in the form when the form is completed and the field meets the conditional actions criteria. The figure below shows what the Form looks like when the conditional action Popup Message fires upon saving the form.
Below are the Add New Externals form fields descriptions.
The name designated for the external field can be anything. However, the name should describe the form and the field itself. This makes it easy to pick out the fields when there are lots of defined external fields.
Currently, the only selection available in the drop down list is External Fields. However, the ability to add other types of fields in the future is possible. For now, simply select External Field.
Select the form where the external field resides from the list presented.
Once a Form has been selected, all the fields defined in that form will populate the field drop down. Select the field to use externally.
The interval tells the system where to retrieve the data for the external field when evaluating the conditional action expression. It is comprised of all existing visit intervals, the most recent visit, or any interval. The most recent visit interval was used in the example. It means the interval that the external form resides in that is the closest before the current visit interval. Any visit interval can be used generically. For example, you may wish to see if a current medication has been prescribed to the subject. This will check all intervals. Any interval with data that matches will cause the condition to be true. (If a field is selected from the Enrollment Form the Interval will need to be Unscheduled).
External fields were used in the example above. The Conditional Action builder is smart enough to know exactly what to compare an external field with. For example, the external gender field can only be compared to the available field choices defined for gender. The figure below shows the drop down. External fields, like local fields, can be used on either side of the comparison:
Notice that External Fields have their own heading in the comparison drop down. This makes selecting them very easy. Then, when making the comparison as shown in the following figure, notice the Conditional Action Builder gives the correct comparison choices. Also notice that an external field like any other criteria can be compared to choices, numbers, constants and other external fields and local fields of a similar type.
If you know how to use conditional actions then you already know how to use External Fields. They must be defined first. Then they can be used like any other field in the current form.
One limitation of External Fields is they cannot be used when creating computed fields. However, that is scheduled for a future release.
Constants are nearly identical to External Fields. They are used in exactly the same way. However, they are not user defined. Instead the system defines constants for Users and automatically populates the criteria drop down. Currently, Constants can be used in all conditional actions, including computed fields. The following constants are available:
Use the current date in a comparison or calculation.
Compare the current interval. One of its many uses is the ability 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 the current interval.
This is the Randomization Allocation for this subject. Based on how a given subject is randomized, certain forms can add or omit fields that are pertinent to the allocation assigned to the subject. If there are multiple Randomization's in a Study the Randomization's will appear in the drop down.
This is the date the subject signed the informed consent. It was defined when the subject was enrolled and can be used to compare against other dates for validation or compute anniversaries, etc.
This is the date the subject was enrolled in the study. It can be used like any other date in the system.
This is the date the treatment started. It is usually baseline; however that is determined by the study designer. It too is entered when the subject is enrolled.