Watchers

What is a Watcher?

A Watcher is a Screen Builder tool that loads remote data in a Screen from an external data source.

1. The Watcher “watches” for a changed in a selected Screen control.

2. When the value of the control changes, the Watcher calls the configured external data source. The following may be the Watcher's data source:

   • Data Connector: The data source may be a Data Connector that gets data and returns a response.

   • Script: The data source may be a configured Script that runs, and then returns a response. Avoid excessive use of Scripts for better Screen performance.

3. The response data is assigned to a configured output property. This output data property is then displayed in another Screen control.

What new in Summer 2024

• Organize Watchers easily with drag-and-drop functionality.

• Temporarily disable specific Watchers when necessary.

• Access detailed logs to troubleshoot runtime errors with precision.

• Enjoy expanded editing space in the editor, enhancing your ability to work with Watchers.s.

View Watchers for a Screen

Follow these steps to view Watchers for a Screen:

1. Open the Screen for editing.

2. Click the Watchers button to view all Watchers for this screen.

   

3. The following information displays about each Watcher:

   • Name: The Name column displays the name of the Watcher.

   • Watching Variable: The Watching Variable column displays the Variable Name setting value (Request variable) for the control that the Watcher monitors for value changes.

   • Output Variable: The Output Variable column displays the Request variable that the Watcher places its output value after that Watcher performs its action.

   • Source: The Source column displays the name of the Data Connector or Script that the Watcher acts upon to determine its output value.

4. Use the move icon to adjust the order in which Watchers display in this list.

Add a Watcher to a Screen

Follow these steps to add a Watcher to a Screen:

1. Click the Watchers button .

2. Click the +Watcher button to add a new Watcher.

3. 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 setting, select the variable this Watcher monitors for changes.  The variables names are defined in Variable Name setting of Screen controls. 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, the Screen remains active for further interaction while the Watcher runs in the background.

   • Select the Show message while loading remote data toggle key to display an overlaying screen while the Watcher gets data from an external source. This option is not available if the Run Synchronously toggle key is enabled.

   • Select the Run watcher on Screen Load toggle key to run the Watcher as soon as the Screen displays without waiting for a change in the linked variable's value.

     

4. Expand the Source panel.

5. 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 (use sparingly for better Screen performance):

     1. From the Source drop-down menu, select a Script to run when the monitored 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 controls by referencing their Variable Names within mustache syntax. In the example below, FullName is the Variable Name for a control to store a Request participant's full name:

        {

         "Name": "{{ FullName }}"

        }

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

   • Use a Data Connector as the source:

     1. From the Source drop-down menu, select a Data Connector upon which to act when the monitored 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 in the Data Connector itself. Depending on the Data Connector selected, these resources may reference API resources or Collection records.

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

        1. Click the icon 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.

6. Expand the Output panel.

7. From the Output panel, specify variable to which the Watcher outputs its value after the Watcher performs the configured action. 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 output variable.  

        

     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 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 icon to delete an added property.

        5. Repeat steps 1 through 4 to map each required property from the Data Connector to a Variable Name.

8. Click Save to save the configuration.

Edit a Watcher

Follow these steps to edit a Watcher in a Screen:

1. View the Watchers for a Screen.  

   

   2. Click the Edit icon for the Watcher to edit. The Watchers screen displays with the Configuration panel expanded.

      

   3. Follow the instructions in the Add a Watcher section to edit the settings for this Watcher.

   4. Click Save to save the changes.

Bypass a Watcher

Temporary disable a Watcher by using the bypass option. Follow these steps to bypass a Watcher:

1. View the Watchers for a Screen.

   

2. 2. Click the Bypass icon for a Watcher to temporarily disable it.

3. Click the UnBypass icon  to enable the Watcher.

Search for a Watcher

Use the Search function to filter all Watchers from the Watchers screen. All Watchers in the Watchers screen may be used in the Screen from which the Watchers screen displays.

Follow these steps to search for a Watcher in a Screen:

1. View the Watchers for a Screen.

2. Enter in the Search setting the text to filter Watchers in that Screens by using any of the following criteria:

   • Name: Filter by the Watcher name that displays in the Name column.

   • Watching Variable: Filter by the control in that Screen from which the Watcher monitors for a change in its value by searching for that control's Variable Name value (Request value) that displays in the Watching Variable column.

   • Output Variable: Filter by the control in that Screen to which the Watcher places its output by searching for that control's Variable Name value that displays in the Output Variable column.

As you enter text into the Search setting, Watchers display that match your entered text.

Delete a Watcher

Follow these steps to delete a Watcher from a Screen:

1. View the Watchers for a Screen.

2. Click the Delete icon next to a Watcher to delete it.