Watchers

Manage Watchers that monitor for Variable Value setting changes in your Screens.

Plan Availability:

What is a Watcher?

A Watcher is a Screen Builder tool that loads remote data from a data source external to the current Screen:

1. The Watcher “watches” a specific data property. This data property may correspond with the Variable Name setting value of a Screen control.

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

   • Script: The data source may be a configured Script that runs, and then returns a response. Scripts are available in all ProcessMaker editions. Avoid using Scripts as a Watcher's source to not affect Screen performance.

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

3. The response data assigns to a configured output property. This output data property may correspond with the Variable Name setting value of a Screen control.

View Watchers for a Screen

Permissions

Your user account or group membership must have the following permissions to view Watchers for 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 view Watchers for a Screen:

1. Open the Screen in which to view its Watchers. The Screen is in Design mode.

2. Click the Watchers button . The Screen is in Watchers mode. The Watchers screen displays all Watchers configured for this Screen.

Watchers screen in Watcher mode

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.

Add a Watcher to a Screen

Permissions

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 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.

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

Edit a Watcher for a Screen

Permissions

Your user account or group membership must have the following permissions to edit 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 edit a Watcher in 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 Edit icon for the Watch to edit. The Watchers screen displays that Watcher's settings with the Configuration panel expanded.

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

Search for a Watcher in a Screen

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.

Permission

Your user account or group membership must have the "Screens: View Screens" permission to search for Watchers in a Screen unless your user account has the Make this user a Super Admin setting selected.

See the Screens permissions or ask your Administrator for assistance.

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

1. View the Watchers for a Screen. The Watchers screen displays.

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.

If there are no search results, the following message displays: No Results.

Delete a Watcher from a Screen

Permissions

Your user account or group membership must have the following permissions to edit a Watcher in 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.

Deleting a Watcher from a Screen cannot be undone.

Follow these steps to delete a Watcher from a Screen:

1. Open the Screen in which to edit 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 Delete icon for the Watcher to delete. The following message displays: Watcher deleted.