---
title: "Watchers"
slug: "watchers"
updated: 2024-09-22T20:41:13Z
published: 2024-09-22T20:41:13Z
canonical: "docs.processmaker.com/watchers"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.processmaker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchers

> [!TIP]
> [**Plan Availability:**](https://www.processmaker.com/products/pricing/) ![Professional](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Standard.png)![Professional](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Professional.png)![Enterprise](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/Enterprise.png)

  

## 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](/v1/docs/data-connector) that gets data and returns a response.
  - **Script:** The data source may be a configured [Script](/v1/docs/scripts) that runs, and then returns a response. [Avoid excessive use of Scripts for better Screen performance](/v1/docs/screen-design-best-practices#avoid-using-watchers-with-scripts).
3. The response data is assigned to a configured output property. This output data property is then displayed in another Screen control.

> [!TIP]
> **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.
> 
> [Embedded content](https://cdn.iframe.ly/G7AdxRI)

## 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](/v1/docs/permission-descriptions-for-users-and-groups#description-of-platform-permissions) permissions or ask your Administrator for assistance.

Follow these steps to view Watchers for a Screen:

1. [Open](/v1/docs/manage-screens#edit-a-screen) the Screen for editing.
2. Click the **Watchers** button ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a3b19fa1-0b66-4d18-8ae1-2f65af322ee4.png) to view all Watchers for this screen.

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/578b79ac-c4fc-4ec3-adc3-569443abc759.png)
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](/v1/docs/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](/v1/docs/data-connector) or [Script](/v1/docs/scripts) that the Watcher acts upon to determine its output value.
4. Use the move icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/7c9aa5e3-b4ec-4703-bdaf-568d18b2945e.png) to adjust the order in which Watchers display in this list.

## 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](/v1/docs/permission-descriptions-for-users-and-groups#description-of-platform-permissions) permissions or ask your Administrator for assistance.

Follow these steps to add a Watcher to a Screen:

1. Click the **Watchers** button ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/a3b19fa1-0b66-4d18-8ae1-2f65af322ee4.png).
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.

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/b93ea9d8-93c0-43f1-9108-6f734336f2c4.png)
4. Expand the **Source** panel.
5. From the **Source** panel, select whether the Watcher acts upon a [Data Connector](/v1/docs/data-connector) or runs a [Script](/v1/docs/scripts) when the monitored [Request variable](/v1/docs/request-variable) changes. Follow these guidelines:

  - **Use a Script as the source (**[**use sparingly for better Screen performance**](/v1/docs/screen-design-best-practices#avoid-using-watchers-with-scripts)**):**

    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](https://mustache.github.io/mustache.5.html). 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.

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/2457a264-2c52-4bc9-ac77-2b3d9742096a.png)
    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![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/850291dd-eca1-46b1-9b0e-907a82cb03c3.png) 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.

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/f0df9de5-1386-48b8-8ded-172f2ec51ecc.png)

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

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/275035ee-8c02-4341-a029-8452ac06948d.png)
      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 ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/acd0c3e6-44fd-4057-b072-f8102229a86b.png) 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

**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](/v1/docs/permission-descriptions-for-users-and-groups#description-of-platform-permissions) permissions or ask your Administrator for assistance.

Follow these steps to edit a Watcher in a Screen:

1. [View the Watchers for a Screen](/v1/docs/watchers#view-watchers-for-a-screen).

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/578b79ac-c4fc-4ec3-adc3-569443abc759.png)

  1. Click the **Edit** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/59abf79e-02a5-47f1-9540-b5b55fa5c5e9.png) for the Watcher to edit. The **Watchers** screen displays with the **Configuration** panel expanded.

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/870d274a-0439-4e37-a4b8-fdb355d56b01.png)
  2. Follow the instructions in the [Add a Watcher section](/v1/docs/watchers#add-a-watcher-to-a-screen) to edit the settings for this Watcher.
  3. 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](/v1/docs/watchers#view-watchers-for-a-screen).

![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/578b79ac-c4fc-4ec3-adc3-569443abc759.png)
2. 2. Click the **Bypass** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/7bad00f1-38f7-48c1-89c6-1735b051074e.png) for a Watcher to temporarily disable it.
3. Click the **UnBypass** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/f9415789-6db0-4246-b264-eac4774e7c85.png) 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.

**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](/v1/docs/permission-descriptions-for-users-and-groups#description-of-platform-permissions) 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](/v1/docs/watchers#view-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](/v1/docs/request-variable)) 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.

> [!NOTE]
> If there are no search results, the following message displays: **No Results**.

## Delete a Watcher

**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](/summer-2024/A7mdugENW7gZw1jmnrOv/administrator/add-users/permission-descriptions-for-users-and-groups#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. [View the Watchers for a Screen](/v1/docs/permission-descriptions-for-users-and-groups#description-of-platform-permissions).
2. Click the **Delete** icon ![](https://cdn.document360.io/2d311614-fcb7-4424-8b4c-d4d3091eebeb/Images/Documentation/7720e99f-0dc6-4fc2-8bf4-19f06c65f6f3.png) next to a Watcher to delete it.