v1/monitors

Use the v1/monitors API to monitor Remote Manager activity and push notifications to a client application. Each configured monitor specifies the Remote Manager events or activities to monitor, the notification mechanism, and the transport type (tcp, http or polling).

For a practical tutorial with monitors, see Tutorial: Experimenting with Remote Manager Monitors

Note The tutorial uses the XML based APIs. The concepts are identical to the json APIs described here.

Monitored events can include

• Data: Data pushed into Remote Manager from remote gateways in the form of DataPoints (directly or through DIA or Smart Energy), FileData, and so on.
• Status: General status updates such as connection status, remote device availability, and so on.
• Alarms: Alarm status updates, such as when alarms are triggered or reset.

The Monitor web service is available only for Remote Manager accounts with a subscription to the Push Monitor service.

History

Use the v1/monitors/history API to retrieve saved push events that may have been sent or have yet to be sent to push monitors. This feature is available for customers who are subscribed to the Push Monitor service.

Not all monitors save push events. Monitors that support saving of push events (sometimes called persistent monitors) can have those events replayed on restart and the history can be retrieved. When a monitor is updated to change the topics that are being monitored, existing saved push events are not affected. Regardless of when the events are generated, event timestamps are saved using the server timestamp. Queries using this API with start_time or end_time parameters restrict the returned events based on the server timestamps of those events. Queries using this API with a cursor or when receiving more than one push event, enable the return of a polling cursor.

Polling cursor

In addition to the normal paged output options for version 1 web services (for example, count, size, cursor and next_uri), the monitors/history API supports polling for subsequent results by returning a polling cursor (result elements polling_cursor and polling_uri). The polling cursor is returned for every monitors/history query that has returned any results or has received a cursor as input, allowing a continuation of that query at a later time.

You can always use a polling_cursor to poll for any added push events (which are ordered by timestamp) that were saved by the monitor since the last call that returned the polling_cursor. If the API is paging through a large set of existing results, the polling cursor and the traditional cursor are both be set to an identical value. However, if all results have been returned for a continued query, no traditional cursor is set because all pages of existing results have been returned. Those results will still receive a polling_cursor element, allowing further continuation of those queries. The polling_cursor avoids having to manually calculate the required timestamp and add the start_time parameter to subsequent queries: use the polling_cursor or the polling_uri directly to retrieve subsequent data.

URI

https://<hostname>/ws/v1/monitors

Formats

Parameters

Elements

acknowledgement

For TCP monitors only. Indicates whether the client will explicitly acknowledge TCP push events or allow Remote Manager to automatically acknowledge events when sent. Options include: explicit or off. The default is off.

add_headers

Accepted only in the monitor update (PUT) request.

For HTTP monitors only. A list of HTTP header names and values to add to the monitor. The headers specified here replace any existing headers of the same name.

Use the following format:

[
  "header-name: header-value",
  "header-name-2: header-value-2"
]

See the headers and remove_headers fields for related information.

auth_token

For HTTP monitors only. Credentials for basic authentication in the following format:

username:password

Use the headers field to specify the Authorization or other proprietary header to use an authentication model other than Basic.

The auth_token field and header values are never exposed once set.

auth_token_set

For HTTP monitors only. If the auth_token is set for the monitor, this field is set to true. If the auth_token is not set for the monitor, this field is not present or set to false.

batch_duration

Specifies an upper bound on the number of seconds messages are aggregated before sending. The default is 10.

batch_size

For HTTP and TCP monitors. Specifies an upper bound on how many messages are aggregated before sending a batch. The default is 100.

compression

Keyword that specifies the method used to compress messages. Options include: zlib or none. The default is none. For zlib, the deflate algorithm is used to compress the data; use inflate to decompress the data.

connect_timeout

For HTTP monitors only. Time in milliseconds Remote Manager waits when attempting to connect to the destination http server. A value of 0 means use the system default of 5000 (5 seconds). Most monitors do not need to configure this setting.

customer_id

Remote Manager identifier for the customer.

description

Optional text field used to label or describe the monitor.

format

Only used for http or tcp monitors, indicates the format of the delivered data.

• xml
• json

headers

For HTTP monitors only. A list of HTTP header names and values in the following format:

[
  "header-name: header-value",
  "header-name-2: header-value-2"
]

Returned in the GET response only as a comma separated list of header names. The auth_token field and header values are never exposed once set.

For example:

[
  "header-name",
  "header-name-2"
]

See the add_headers and remove_headers fields for related information.

id

System-generated identifier for the monitor.

last_connect

Returned in the GET response. Specifies last connection time to the client application.

last_sent

Returned in the GET response. Specifies the timestamp of the last message pushed to the client application.

last_sent_uuid

The UUID of the last sent event. The UUIDs of events can be used to uniquely track delivered events if necessary.

method

For HTTP monitors only. HTTP method to use for sending data: PUT or POST. The default is PUT.

persistent

Boolean value that specifies whether Remote Manager replays any missed published events before any new published events are forwarded. A value of true indicates missed published events are replayed. False indicates missed published events are not replayed. The default is false. In /ws/Monitor API, this field corresponds to the monAutoReplayOnConnect field.

response_timeout

For HTTP monitors only. Time in milliseconds Remote Manager waits for a response for pushed events from the http server. A value of 0 means use the system default of 5000 (5 seconds). Most monitors do not need to configure this setting.

remove_headers

Accepted only in the monitor update (PUT) request.

For HTTP monitors only. A list of HTTP header names to remove from the monitor

Use the following format:

[
  "header-name",
  "header-name-2"
]

See the headers and add_headers fields for related information.

schema

Monitors can use a templating language to transform from the Remote Manager data schema to an external schema. The schema language is Handlebars.

See Tutorial: Monitors with Templated Payloads for more details.

For example, a translation schema for a monitor using the DataPoint/00000000-00000000-00000000-00000000/metrics/sys/* topic:

[{{#eachFiltered this}}{{#if @index}},{{/if}}
  {
    "timestamp": "{{formatTime DataPoint.timestamp}}",
    "stream": "{{DataPoint.streamId}}",
    "value": "{{DataPoint.data}}",
    "device": "{{firstPathComponent DataPoint.streamId}}"
  }{{/eachFiltered}}
]

Generates output to the HTTP target (or in the ws/v1/monitors/history query) that looks like this (Note that only two events are shown):

[
  {
    "timestamp": "2022-09-12T21:39:00.000Z",
    "stream": "00000000-00000000-00000000-00000000/metrics/sys/cpu/used",
    "value": "57.490000",
    "device": "00000000-00000000-00000000-00000000"
  },
  {
    "timestamp": "2022-09-12T21:39:00.000Z",
    "stream": "00000000-00000000-00000000-00000000/metrics/sys/mem/used",
    "value": "42.900000",
    "device": "00000000-00000000-00000000-00000000"
  }
]

For the above schema translation, the original Remote Manager DataPoint data looks like the following. This is the data that is delivered from a monitor that does not use a schema template.

Note: In this example, the context data is shown. The context data is used only by the schema language template. It is not sent to HTTP or TCP monitors. See the include_context parameter on the v1/monitors/history API.

[
  {
    "DataPoint": {
      "cstId": 42,
      "data": "57.200000",
      "description": "",
      "id": "5007ca81-32e3-11ed-81ca-0ab18c42f584",
      "previousData": "57.490000",
      "quality": 0,
      "serverTimestamp": 1663018827801,
      "streamId": "00000000-00000000-00000000-00000000/metrics/sys/cpu/used",
      "streamType": "FLOAT",
      "streamUnits": "%",
      "timestamp": 1663018740000
    },
    "context": {
        "deviceName": "Fury",
        "deviceType": "Digi ConnectIT4",
        "groupPath": "/42_Digi_International/Stores/",
        "groupPathV1": "Stores/",
        "vendorId": "4261412874"
    },
    "group": "Stores",
    "operation": "INSERTION",
    "timestamp": "2022-09-12T21:40:27.905Z",
    "topic": "42/DataPoint/00000000-00000000-00000000-00000000/metrics/sys/cpu/used"
  },
  {
    "DataPoint": {
      "cstId": 42,
      "data": "42.910000",
      "description": "",
      "id": "5007ca82-32e3-11ed-81ca-0ab18c42f584",
      "previousData": "42.900000",
      "quality": 0,
      "serverTimestamp": 1663018827801,
      "streamId": "00000000-00000000-00000000-00000000/metrics/sys/mem/used",
      "streamType": "FLOAT",
      "streamUnits": "%",
      "timestamp": 1663018740000
    },
    "context": {
        "deviceName": "Fury",
        "deviceType": "Digi ConnectIT4",
        "groupPath": "/42_Digi_International/Stores/",
        "groupPathV1": "Stores/",
        "vendorId": "4261412874"
    },
    "group": "Stores",
    "operation": "INSERTION",
    "timestamp": "2022-09-12T21:40:27.905Z",
    "topic": "42/DataPoint/00000000-00000000-00000000-00000000/metrics/sys/mem/used"
  }
]

schema_type

If a schema is specified, the schema_type of handlebars must be specified.

status

Returned in the GET response. Specifies the current connection status to the client application.

Any PUT request to a monitor resets the monitor state.

topics

A list of one or more topics to monitor. For example:

[
    "devices",
    "DataPoint"
]

Supported monitor topics include:

• alert_status
• devices
• firmware_updates
• firmware_updates_progress
• jobs
• Alarm
• AlarmStatus
• CLIEvent
• DataPoint
• DataStream
• DeviceCore
• FileData
• FileDataCore
• Job
• JobResult
• XbeeCore

type

The type of the monitor. Valid types are polling, http or tcp.

• Polling monitors collect information inside of Remote Manager for eventual retrieval via the v1/monitors/history API. The v1/monitors/history API uses efficient mechanisms and paging to allow you to very quickly retrieva data from a bookmark (cursor) where you last stopped reading.
• HTTP monitors are used to send push events to a client application via HTTP PUT or POST call. See HTTP/HTTPS transport protocol
• TCP monitors are used when a client application wants to connect with a TCP protocol TCP Transport to fetch monitor events.

url

For HTTP monitors only. URL of the customer web server. For http URLs, the default listening port is 80; for https URLs, the default listening port is 443.

History Fields

Among other values, the monitors/history API outputs these unique fields: