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:
Open the Screen in which to add a Watcher. The Screen is in Design mode.
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.
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):
From the Source drop-down menu, select a Script from the Script section to run when the monitored Request variable's value changes.
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 }}"
}
Optionally, in the Script Configuration setting, include JSON configuration settings your Script uses when it runs.
Use a Data Connector as the source:
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.
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:
From the Type drop-down menu, select whether to pass data as a Parameter, Header or in the Body.
From the Key drop-down menu, select from a list of keys available in the Data Connector resource.
In the Value setting, enter the Request variable from which to pass data.
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:
A Data Connector is the source:
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:
In the Source setting, enter the Data Connector property from which to receive data.
In the Form Variable setting, enter the Request variable which will receive the output from the Watcher.
Repeat steps 1 through 4 to map each required property from the Data Connector to a Variable Name.
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.
Related Topics
What is a Watcher?View Watchers for a ScreenSearch for a WatcherEdit a Watcher for a ScreenDelete a Watcher from a ScreenWhat is Screen Builder?Preview a Screen for Desktop and Mobile DevicesControl DescriptionsView ScreensScreen TypesScreen Builder ModesValidate Your ScreenAdd, Delete or Rename a PageManage Calculated PropertiesAdd Custom CSS to a ScreenPublish Your ScreenScreen Design Best PracticesLast updated