**Watchers**
===================

**Create Watcher**
+++++++++++++++++++++++++++++
.. http:post:: /_alerting/watchers/
  
  **Description** Use this API to create new Watcher by supplying all necessary information. Please note, only one Watcher can be created per IoT Gateway.

  **HTTP Method** POST
  
  **Endpoint:** ``/_alerting/watchers/``

  **Request Header** ``Authorization`` `Basic Token`

  **Request Parameters**

  Query Parameters

    - ``pipeline_id`` (string, *optional*): ID of the Pipeline/Gateway for which we need a Watcher
    - ``is_hidden`` (integer, *optional*): Indicates whether the watcher is system created 

  Body Parameters

    - ``watcher_name`` (string, *required*): Name of the Watcher.
    - ``function_id`` (string, *required*): ID of the Function.
    - ``plant_id`` (string, *required*): ID of the Plant.
    - ``site_id`` (string, *required*): ID of the Site.
    - ``gateway_id`` (string, *required*): ID of the IoT Gateway.
    - ``is_enabled`` (integer, *required*): Indicates whether the Watcher is enabled (1 or 0).
    - ``triggers`` (list of objects, *required*): List of triggers, each with the following:
        
        - ``condition`` (list of objects, *optional*): List of conditions, each with:

            - ``comparison`` (string, *required*): Comparison symbol (e.g., '<=').
            - ``monitor_id`` (string, *required*): ID of the monitor.
            - ``tag_id`` (string, *required*): ID of the tag
            - ``threshold`` (string, *required*): Threshold value of the tag.


        - ``id`` (string, *required*): ID of trigger
        - ``minimum_duration`` (string, *required*): Minimum duration for the trigger (alert marked if condition is true for more than this duration).
        - ``name`` (string, *required*): Name of the trigger.
        - ``notifyTo`` (list of objects, *required*): Notification preferences:

            - ``email`` (boolean, *required*): Send notifications via email.
            - ``sms`` (boolean, *required*): Send notifications via SMS.
            - ``users`` (list of string, *required*): List of user IDs to notify.
            - ``whatsapp`` (boolean, *required*): Send notifications via WhatsApp.


        - ``severity`` (integer, *required*): Severity level of the trigger (lower number implies higher importance).
        - ``trigger_relation`` (string, *required*): Relation between multiple condtion
    
  **Sample Request**

    .. code-block:: sh

        curl -X POST 'https://app.4pointx.com/_alerting/watchers/' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Basic <token>' \
        -d '{
            "created_at_time": 1696827561516,
            "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
            "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
            "is_enabled": 1,
            "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
            "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
            "triggers": [
                {
                    "condition": [
                        {
                            "comparison": ">=",
                            "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                            "tag_id": "I_RM3201_RTD_09",
                            "threshold": "60"
                        }
                    ],
                    "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                    "minimum_duration": "0s",
                    "name": "I_RM3201_RTD_09 >= 60",
                    "notifyTo": {
                        "email": true,
                        "sms": false,
                        "users": [
                          user1@email.com,
                          user2@email.com
                        ],
                        "whatsapp": false
                    },
                    "severity": 1,
                    "trigger_relation": "AND"
                },
                {
                    "condition": [
                        {
                            "comparison": "<=",
                            "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                            "tag_id": "I_RM3201_RTD_09",
                            "threshold": "30"
                        }
                    ],
                    "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
                    "minimum_duration": "2s",
                    "name": "I_RM3201_RTD_09 <= 30",
                    "notifyTo": {
                        "email": true,
                        "sms": false,
                        "users": [
                          user3@email.com
                        ],
                        "whatsapp": true
                    },
                    "severity": 2,
                    "trigger_relation": "AND"
                }
            ],
            "watcher_name": "Example_watcher"
        }'

    *Note*: Used when a "condition" Gateway is created

    .. code-block:: sh

        curl -X POST 'https://app.4pointx.com/_alerting/watchers?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af' \
                     -H 'Authorization: Basic <token>'


  **Sample Response**

  Success

     ..  code-block:: json

        {
            "id": "8c254283-19f3-4bdb-996a-e748a617bea3"
        }

  Error

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorized access to module by general-user"
        }
      }


    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Invalid content type"
        }
      }
          

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Insufficient inputs"
        }
      }

          
    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Watcher already exists for a given Gateway"
        }
      }


    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Please provide at least one notification medium (SMS, Email, or WhatsApp) for the selected user(s)."
        }
      }


    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Select at least one user to notify"
        }
      }




**Delete Watcher**
++++++++++++++++++++++++
.. http:delete:: /_alerting/watchers/<watcher_id>

  **Description** Deletes an existing Watcher.

  **HTTP Method** DELETE

  **Endpoint** ``/_alerting/watchers/<watcher_id>``

  **Request Header** ``Authorization`` `Basic Token`

  **Request Parameters**

  URL Parameters

    - ``watcher_id`` (string, *required*) The ID of the Watcher that is to be deleted.

    
  **Sample Request**

    .. code-block:: sh

        curl -X DELETE 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' -H 'Authorization: Basic <token>'

  **Sample Response**

  Success 

    .. sourcecode:: json

        "Deleted"

  Error 

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorized access to module by general-user"
        }
      }


    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Invalid Watcher ID"
        }
      }       




**Update Watcher**
+++++++++++++++++++++++++++++++
.. http:put:: /_alerting/watchers/<watcher_id>
  
    **Description** Use this API to update the configuration of an existing Watcher.

    **HTTP Method** PUT
    
    **Endpoint** ``/_alerting/watchers/<watcher_id>``

    **Request Header** ``Authorization`` `Basic Token`

    **Request Parameters**

    Query Parameters

    - ``pipeline_id`` (string, *optional*): ID of the Pipeline/Gateway for which we need a Watcher
    - ``monitor_id`` (string, *optional*): ID of the Monitor
    - ``is_hidden`` (integer, *optional*): Indicates whether the watcher is system created 

    Body Parameters

      - ``watcher_name`` (string, *required*): Name of the Watcher.
      - ``function_id`` (string, *required*): ID of the Function.
      - ``plant_id`` (string, *required*): ID of the Plant.
      - ``site_id`` (string, *required*): ID of the Site.
      - ``gateway_id`` (string, *required*): ID of the IoT Gateway.
      - ``is_enabled`` (integer, *required*): Indicates whether the Watcher is enabled.
      - ``triggers`` (list of objects, *required*): List of triggers, each with the following:
          
          - ``condition`` (list of objects, *optional*): List of conditions, each with:

              - ``comparison`` (string, *required*): Comparison symbol (e.g., '<=').
              - ``monitor_id`` (string, *required*): ID of the monitor.
              - ``tag_id`` (string, *required*): ID of the tag
              - ``threshold`` (string, *required*): Threshold value of the tag.


          - ``id`` (string, *required*): ID of trigger
          - ``minimum_duration`` (string, *required*): Minimum duration for the trigger (alert marked if condition is true for more than this duration).
          - ``name`` (string, *required*): Name of the trigger.
          - ``notifyTo`` (list of objects, *required*): Notification preferences:

              - ``email`` (boolean, *required*): Send notifications via email.
              - ``sms`` (boolean, *required*): Send notifications via SMS.
              - ``users`` (list of string, *required*): List of user IDs to notify.
              - ``whatsapp`` (boolean, *required*): Send notifications via WhatsApp.


          - ``severity`` (integer, *required*): Severity level of the trigger (lower number implies higher importance).
          - ``trigger_relation`` (string, *required*): Relation between multiple condtion


    URL Parameters

        - ``watcher_id`` (string, *required*) The ID of the Watcher that is to be updated.
    

    **Sample Request**

      .. code-block:: sh

        curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Basic <token>' \
        -d '{
                "created_at_time": 1696827561516,
                "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
                "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
                "gateway_name": "My Gateway 1",
                "is_enabled": 1,
                "is_hidden": 0,
                "last_update_time": 1701172774457,
                "latest_alert_date": 1667260702000,
                "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
                "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
                "total_alerts": 4,
                "triggers": [
                    {
                        "condition": [
                            {
                                "comparison": ">=",
                                "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                                "tag_id": "I_RM3201_RTD_09",
                                "threshold": "60"
                            },
                            {
                                "comparison": "<=",
                                "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                                "tag_id": "I_RM3201_RTD_09",
                                "threshold": "30"
                            }
                        ],
                        "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                        "minimum_duration": "0s",
                        "name": "I_RM3201_RTD_09 >= 60 OR I_RM3201_RTD_09 <= 30",
                        "notifyTo": {
                            "email": true,
                            "sms": false,
                            "users": [
                              user1@email.com,
                              user2@email.com
                            ],
                            "whatsapp": false
                        },
                        "severity": 1,
                        "trigger_relation": "OR"
                    },
                    {
                        "condition": [
                            {
                                "comparison": "<=",
                                "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                                "tag_id": "I_RM3201_RTD_08",
                                "threshold": "90"
                            }
                        ],
                        "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
                        "minimum_duration": "0s",
                        "name": "I_RM3201_RTD_08 > 90",
                        "notifyTo": {
                            "email": true,
                            "sms": false,
                            "users": [
                              user3@email.com
                            ],
                            "whatsapp": true
                        },
                        "severity": 2,
                        "trigger_relation": "AND"
                    }
                ],
                "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
                "watcher_name": "Example_watcher"
            }'

      *Note*: Used when a "condition" Gateway is updated

      .. code-block:: sh

        curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af' \
                     -H 'Authorization: Basic <token>'
      
      *Note*: Used when a "condition" Monitor is updated

      .. code-block:: sh

        curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af&monitor_id=ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37' \
                     -H 'Authorization: Basic <token>'

    **Sample Response**

    Success

      .. sourcecode:: json

          "Updated"


    Error

      .. sourcecode:: json

        {
          "error": {
            "status": 401,
            "message": "Unauthorized access to module by general-user"
          }
        }


      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Invalid content type"
          }
        }
            

      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Insufficient inputs"
          }
        }

            
      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Watcher already exists for given IoT Gateway"
          }
        }


      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Please provide at least one notification medium (SMS, Email, or WhatsApp) for the selected user(s)."
          }
        }


      .. sourcecode:: json

        {
          "error": {
            "status": 400,
            "message": "Please select at least one user to notify"
          }
        }

     


**Fetch Watcher**
+++++++++++++++++++++++++++++++++
.. http:get:: /_alerting/watchers/<watcher_id>

  **Description** Returns detailed information of a specific Watcher.

  **HTTP Method** GET

  **Endpoint:** ``/_alerting/watchers/<watcher_id>``

  **Request Header** ``Authorization`` `Basic Token`

  **Request Parameters**

  URL Parameters
    
    - ``watcher_id`` (string, *required*): The ID of the Watcher.

  **Sample Request**

    ..  code-block:: sh

       curl -X GET 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' -H 'Authorization: Basic <token>'

  **Sample Response**

  Success 

    .. sourcecode:: json

      {
          "created_at_time": 1696827561516,
          "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
          "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
          "gateway_name": "My Gateway 1",
          "is_enabled": 1,
          "is_hidden": 0,
          "last_update_time": 1701172774457,
          "latest_alert_date": 1667260702000,
          "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
          "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
          "total_alerts": 4,
          "triggers": [
              {
                  "condition": [
                      {
                          "comparison": ">=",
                          "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                          "tag_id": "I_RM3201_RTD_09",
                          "threshold": "60"
                      }
                  ],
                  "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                  "minimum_duration": "0s",
                  "name": "I_RM3201_RTD_09 >= 60",
                  "notifyTo": {
                      "email": true,
                      "sms": false,
                      "users": [
                        user1@email.com,
                        user2@email.com
                      ],
                      "whatsapp": false
                  },
                  "severity": 1,
                  "trigger_relation": "AND"
              },
              {
                  "condition": [
                      {
                          "comparison": "<=",
                          "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                          "tag_id": "I_RM3201_RTD_09",
                          "threshold": "30"
                      }
                  ],
                  "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
                  "minimum_duration": "2s",
                  "name": "I_RM3201_RTD_09 <= 30",
                  "notifyTo": {
                      "email": true,
                      "sms": false,
                      "users": [
                        user3@email.com
                      ],
                      "whatsapp": true
                  },
                  "severity": 2,
                  "trigger_relation": "AND"
              }
          ],
          "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
          "watcher_name": "Example_watcher"
      }

  Error 

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorized access to module by general-user"
        }
      }


      


**Fetch List of Watchers**
++++++++++++++++++++++++++++++++
.. http:get:: /_alerting/watchers/_list

  **Description** Returns a list of configured Watchers along with their details for a specified Function.

  **HTTP Method** GET

  **Endpoint:** ``/_alerting/watchers/_list``

  **Request Header** ``Authorization`` `Basic Token`

  **Request Parameters**

  Query Parameters
    
    - ``function_id`` (string, *required*): The ID of the Function.

  **Sample Request**

    ..  code-block:: sh

       curl -X GET 'https://app.4pointx.com/_alerting/watchers/_list?function_id=f14600e7-cf2c-4f7f-af99-784b07b73a99' -H 'Authorization: Basic <token>'

  **Sample Response**

  Success

    .. sourcecode:: json

      [
         {
            "created_at_time": 1696827561516,
            "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
            "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
            "gateway_name": "My Gateway 1",
            "is_enabled": 1,
            "is_hidden": 0,
            "last_update_time": 1701172774457,
            "latest_alert_date": 1667260702000,
            "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
            "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
            "total_alerts": 4,
            "triggers": [
                {
                    "condition": [
                        {
                            "comparison": ">=",
                            "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                            "tag_id": "I_RM3201_RTD_09",
                            "threshold": "60"
                        }
                    ],
                    "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                    "minimum_duration": "0s",
                    "name": "I_RM3201_RTD_09 >= 60",
                    "notifyTo": {
                        "email": true,
                        "sms": false,
                        "users": [
                          user1@email.com,
                          user2@email.com
                        ],
                        "whatsapp": false
                    },
                    "severity": 1,
                    "trigger_relation": "AND"
                },
                {
                    "condition": [
                        {
                            "comparison": "<=",
                            "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                            "tag_id": "I_RM3201_RTD_09",
                            "threshold": "30"
                        }
                    ],
                    "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
                    "minimum_duration": "0s",
                    "name": "I_RM3201_RTD_09 <= 30",
                    "notifyTo": {
                        "email": true,
                        "sms": false,
                        "users": [
                          user3@email.com
                        ],
                        "whatsapp": true
                    },
                    "severity": 2,
                    "trigger_relation": "AND"
                }
            ],
            "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
            "watcher_name": "Example_watcher"
        },
        {
            "created_at_time": 1696827561718,
            "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
            "gateway_id": "dc70949d-acdb-410a-af3d-16ec0sd54520af",
            "gateway_name": "My Gateway 2",
            "is_enabled": 1,
            "is_hidden": 0,
            "last_update_time": 1701172774457,
            "latest_alert_date": 1667260702000,
            "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
            "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
            "total_alerts": 0,
            "triggers": [
                {
                    "condition": [
                        {
                            "comparison": ">=",
                            "monitor_id": "ac41ffga-0d4b-4e1e-8sde2-c05sd482dd37",
                            "tag_id": "RM_RM3201_RTD_09",
                            "threshold": "60"
                        },
                        {
                            "comparison": ">=",
                            "monitor_id": "ac41ffga-0d4b-4e1e-8sde2-c05sd482dd37",
                            "tag_id": "RM_RM6401_RTD_06",
                            "threshold": "60"
                        }
                    ],
                    "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                    "minimum_duration": "0s",
                    "name": "RM_RM3201_RTD_09 >= 60 AND RM_RM6401_RTD_06 >= 60",
                    "notifyTo": {
                        "email": true,
                        "sms": false,
                        "users": [
                          user1@email.com,
                          user2@email.com
                        ],
                        "whatsapp": true
                    },
                    "severity": 1,
                    "trigger_relation": "AND"
                }
            ],
            "watcher_id": "4e2545283-ef45-6f66-6984-7g48aa17bea3",
            "watcher_name": "My Example Watcher"
        }
      ]

  Error

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorized access to module by general-user"
        }
      }



    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Insufficient inputs"
        }
      }

          
          
    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Invalid function_id"
        }
      }

 


**Fetch Watcher Count**
+++++++++++++++++++++++
.. http:get:: /_alerting/watchers/_count

  **Description** Returns the total number of Watchers currently configured for a Function.

  **HTTP Method** GET

  **Endpoint:** ``/_alerting/watchers/_count``

  **Request Header** ``Authorization`` `Basic Token`

  **Request Parameters**

  Query Parameters

    - ``function_id`` (string, *required*): The ID of the Function.
      
  **Sample Request**

    ..  code-block:: sh

        curl -X GET 'https://app.4pointx.com/_alerting/watchers/_count?function_id=f14600e7-cf2c-4f7f-af99-784b07b73a99' -H 'Authorization: Basic <token>'

  **Sample Response**

  Success 

    .. sourcecode:: json

      5
        

  Error

    .. sourcecode:: json

      {
        "error": {
          "status": 401,
          "message": "Unauthorized access to module by general-user"
        }
      }

    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Insufficient inputs"
        }
      }

          
          
    .. sourcecode:: json

      {
        "error": {
          "status": 400,
          "message": "Invalid function_id"
        }
      }