Add a Watcher to a Screen

Add a Watcher to a Screen.

Add a Watcher to a Screen

Permissions Required

Your user account or group membership must have the following permissions to add a Watcher to a Screen unless your user account has the Make this user a Super Admin setting selected:

• Screens: Edit Screens

• Screens: View Screens

See the Screens permissions or ask your Administrator for assistance.

Follow these steps to add a Watcher to a Screen:

1. Open the Screen in which to add a Watcher. The Screen is in Design mode.

2. Click the Watchers button. The Watchers screen displays all Watchers configured for this Screen.
3. Click the +Watcher button. The Watchers screen displays with the Configuration panel expanded.
4. From the Configuration panel, configure how the Watcher monitors for a control's value to change. Follow these guidelines:

   • In the Watcher Name setting, enter the name of the Watcher. This is a required setting.

   • From the Variable to Watch drop-down menu, select which Screen control by its Variable Name setting value (Request variable) the Watcher monitors for its value to change. This is a required setting.

   • Select the Run Synchronously toggle key to prevent further interaction with the Screen until the Watcher's action completes. If the Run Synchronously toggle key is not selected when the Watcher runs, the Screen remains active for further interaction. The Run Synchronously toggle key is disabled by default.

   • Select the Show message while loading remote data toggle key to display an overlaying screen while the Watcher runs. The Show message while loading remote data toggle key is not available if the Run Synchronously toggle key is enabled since the Watcher runs while further Screen interaction is permitted. While the Watcher runs, the overlaying screen displays the name of the Watcher and that it is running. The Show message while loading remote data toggle key is disabled by default.

   • Select the Run watcher on Screen Load toggle key to run the Watcher when the Screen displays. The Run watcher on Screen Load toggle key is disabled by default.

5. Select the Source panel.
6. From the Source panel, select whether the Watcher acts upon a Data Connector or runs a Script when the monitored Request variable changes. Follow these guidelines:

   • Use a Script as the source (avoid to not affect Screen performance):

     1. From the Source drop-down menu, select a Script from the Script section to run when the monitored Request variable's value changes.

     2. Optionally, in the Input Data setting, enter a valid JSON object the Watcher passes to the Script prior to running as input data for the Script. The Script may reference Screen control values by referencing their Variable Name setting values when placed within mustache syntax. In the example below, FullName is the Variable Name setting value for a control to store a Request participant's full name:

        {

        "Name": "{{ FullName }}"

        }

     3. Optionally, in the Script Configuration setting, include JSON configuration settings your Script uses when it runs.

   • Use a Data Connector as the source:

     1. From the Source drop-down menu, select a Data Connector from the Data Connector section upon which to act when the monitored Request variable's value changes. The Endpoint setting displays below the Source drop-down menu.
     2. From the Endpoint drop-down menu, select which resource to act upon in the selected Data Connector. These resources are configured from the Data Connector itself. Depending on the Data Connector selected from the Data Connector section of the Source drop-down menu, these resources may reference API resources or Collection records.

     3. From the Outbound Configuration section, specify how the Watcher maps data from a Request variable to a property of the Data Connector. Follow these guidelines:

        1. Click theicon to add a new property.
        2. From the Type drop-down menu, select whether to pass data as a Parameter, Header or in the Body.

        3. From the Key drop-down menu, select from a list of keys available in the Data Connector resource.

        4. In the Value setting, enter the Request variable from which to pass data.

7. Select the Output panel.
8. From the Output panel, specify to which Request variable that the Watcher outputs its value after the Watcher performs the action configured from the Source panel. The variable that the Watcher outputs its value does not need to be in this Screen. The output variable may be in a different Screen referenced elsewhere in this Request. Follow these guidelines:

   • A Script is a source:

     1. In the Output Variable setting, enter the Request variable to which the Watcher outputs the value of its result.
   • A Data Connector is the source:

     1. From the Output Variable Property Mapping section, specify how the Watcher maps values from the Data Connector to the output Request variable specified in the Form Variable setting. In doing so, the Watcher maps the Data Connector output as a set of properties in JSON format to the output Request variable. Follow these guidelines to map each property:

        1. Click the +Property button. The Source and Form Variable settings display to specify the Data Connector property and Request variable which will receive the output from the Watcher.
        2. In the Source setting, enter the Data Connector property from which to receive data.

        3. In the Form Variable setting, enter the Request variable which will receive the output from the Watcher.

        4. Optionally, click the Delete iconto delete an added property.
        5. Repeat steps 1 through 4 to map each required property from the Data Connector to a Variable Name.

9. Click Save. The Watcher displays in the Watchers screen. The following message displays: Watcher saved.

Ensure to save your Screen. The Watcher is not added to your Screen until you save it. Doing so will save your work if that your session expires.

Watchers screen with a new Watcher

Related Topics

pageWhat is a Watcher?pageView Watchers for a ScreenpageSearch for a WatcherpageEdit a Watcher for a ScreenpageDelete a Watcher from a ScreenpageWhat is Screen Builder?pagePreview a Screen and Its JSON Data ModelpageEdit Your ScreenpageView ScreenspageScreen TypespageScreen Builder ModespageValidate Your ScreenpageAdd, Delete or Rename a PagepageManage Calculated PropertiespageAdd Custom CSS to a ScreenpageSave Your ScreenpageScreen Design Best and Worst Practices