Summary

This article covers the basics of using targets and dependencies.

Table of Contents

Targets and Dependents are some of the most powerful and most complex parts of the Fountayn Scripting Language. This guide is intended to provide all the information you need to effectively implement targets and dependents in your scripts so you get the desired results that you expect.

Targets

Targets are one way that you can trigger a script to execute. You can list as many targets as you would like in a single script. This is one of the major advantages of using scripts over the standard dependencies within the eClinical platform. You can write one script that does a format check or checks to see if the question is answered and then you can apply as many questionTypeIds to that script as targets as you wish. In terms of dependencies, you would have a single dependency with the same logic repeated for every questionTypeId. In scripts, you would still have to set all the questionTypeIds as targets, but if you want to change the logic or the alert text, you only have to do it in one place.

Note: Targets do not have to be questions. Targets can also be forms!


Targets are going to be used most often in scripts because the action happens against that target. If you set the target of an alert script, the alert will appear on that question when the alert needs to be shown. If you don’t want the alert to show on the question, you would use a dependent, which is discussed next in this guide.

When using commands other than the alert command (ie. assign, createform, etc.), targets are going to be used. The only case where you do not need a target or a dependent to trigger a script is on the import scripts. Those scripts will only have a body since they will automatically be triggered by the import process.

Targets appear like this at the end of a script:

     </body>
  <target typeId="rate" action="update" when="after"/>
</script>

Dependents

Dependents in scripts are a way to cause a script to re-evaluate but not cause any action to happen on the dependent question or form. Typically, dependents will be used mainly in alert scripts. One of the major advantages of the scripting language is that we can build a network of edit checks that will evaluate alerts based on information on forms that are not actively being saved.

Using scripts we can specify an absolute dependent path to a question on another form or simply another form. In most cases, you would use this with the alert command where you want cross-form checks to be re-evaluated when any of the data used in the script is changed.


Note: You cannot use a dependent without a target!


An example of a dependent used with a target is as follows:

     </body>
  <target typeId="rate" action="update" when="preprocess"/>
  <dependent path="/screening/dm.dob" />
</script>


Targets vs. Dependents

A general rule of thumb is that dependents are only used in alert scripts. In those cases, the dependent path should be used on questions that should trigger the script but not show the alert.



Note: Questions can be a target OR a dependent. They cannot be both in the same script!


The “action” Attribute

The action attribute tells the script which action should trigger the script. The possible options for the “action” attribute are:

  • Update – This triggers the script to run whenever the target or dependent question/form is updated (saved).
  • Create – This triggers the script to run whenever the target form is created (typically via the createForm command).

Following is an example:

     </body>
  <target typeId="rate" action="update" when="after"/>
</script>


These actions can all be combined with the “when” attribute to determine if the script will run “preprocess” or “after” the action happens. So in our example above, the script will be triggered after the “rate” question is saved.

The “when” Target Attribute

The “when” attribute is used to specify when a script should be executed. This can be useful to designate that a script should not execute until the form has been completely and cleanly saved. This attribute can also be useful to designate when a script should execute immediately after data is entered or modified on a form or question.

Note: This attribute is not available for dependent paths.


“When” Attribute Options

The following options are available for the “when” attribute.

before

The script will execute after the ‘Save Form’ button is clicked but before the data on the question/form is actually saved.

Note: This attribute was depreciated but was kept as the default for backwards compatibility. All new scripts should use “preprocess” or “after”.

After

The script will execute after both the ‘Save Form’ button is clicked and the data on the question/form is saved. In the case of a script which assigns a value to a field, using ‘after’ will result in two audit entries for the field. The first will show the field saved blank (initial save), and a second will show the result of the assigned value.


Note: It is not possible to control the order in which scripts will execute upon form save. Therefore, if multiple ‘after’ scripts are on the same form it may be necessary to repeat logic in subsequent scripts to ensure the logic is processed in the desired order. For example, if Script A is assigning a value to a question, and that value is needed for Script B, the script will need to include logic to recalculate the value rather than reference the question where it will be assigned.


Preprocess

The script will execute immediately after the data for the question/form is entered or modified.


This option should not be used with any script that makes changes to the database. For example, scripts that create forms should not use the ‘preprocess’ option.


Assignments can occur during preprocessing. Scripts that perform assignments will populate the question on the form with the appropriate answer. The answer on the question will then be saved when the form is saved.


Note: Alert scripts need to use the ‘preprocess’ option so that users can see the alerts as they are editing the forms.



Unlike ‘after’ scripts, it may be possible to sequence a series of ‘preprocess’ scripts to execute in succession. For example, the ‘Site Number’ can be populated by a preprocess script, and that value can then be used to set the ‘Subject ID’. However, when multiple scripts are set to ‘preprocess’ and are triggered by the same targets or dependents, it is not possible to set the order in which the scripts will execute.


Examples

In the following example, let’s assume that the script is setting the age based on the screening visit date and the birth date question. If the user were to enter a date with an incorrect format and the “when” attribute was set to “preprocess”, it would attempt to assign the age question with an incorrectly formatted date and it would cause an error. Since the “when” attribute is set to “after”, it will wait to run the script until the question/form is saved without opening any new alerts.

<script scriptId="date_of_birth">
    <body>

    </body>
    <target typeId="visitdtnscreen" when="after" />
    <target typeId="brthdtc" when="after" />
</script>


In the following example, an alert is fired when the date entered occurs in the future. By setting the ‘when’ attribute to ‘preprocess’ the alert is displayed as soon as the user enters the unacceptable date, allowing the user to correct the date before saving the form.

<script scriptId='futurePartialDate' >
  <body>
    <s:alert>
      <s:expression>
        <s:or>
          <s:lte>
            <s:partialDatePath path=':value' type='partialdate' />
            <s:toPartialDate adjust='none' >
              <s:currentDate name='currentDate' />
              <s:string value='dd[]/MM[]/yyyy[]' />
            </s:toPartialDate>
          </s:lte>
          <s:not>
            <s:isSet/>
          </s:not>
        </s:or>
      </s:expression>
      <s:correction>
        <s:string value='optional' />
      </s:correction>
      <s:text>
        <s:string value='date can&apos;t be in the future' />
      </s:text>
    </s:alert>
  </body>
  <target action='update' shouldReconcile='true' typeId='scriptPartialDate' when='preprocess' />
</script>


The “shouldReconcile” Attribute

If set to true, this attribute will cause the script to be re-executed when running the mid-study change utility ‘reconcile’ on any target or dependent form or question. This would typically be set to false in the case of an email trigger script, but true in the case of an assignment or alert script.


Note: When not specified, this attribute is true by default.



Note: Please note that shouldReconcile=”false” is incompatible with the attribute when=”preprocess”. Therefore, a preprocess script will always reconcile.
In very rare cases when the need may arise, the script’s logic may need to be updated to check for previousValue as a way to circumvent execution at reconcile unless there is a true change in value(s).


Example:

<script scriptId="set_completed">
    <body>  
 
    </body>
    <target action='update' shouldReconcile='true' typeId='complete' when='after' /> 
</script>

Need more help?

Please visit the Fountayn Contact Information page.