List all Monitors

The following example shows how to list all configured monitors.

Request

GET /ws/Monitor

Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
  <resultTotalRows>2</resultTotalRows>
  <requestedStartRow>0</requestedStartRow>
  <resultSize>2</resultSize>
  <requestedSize>1000</requestedSize>
  <remainingSize>0</remainingSize>
  <Monitor>
    <monId>148214</monId>
    <cstId>2</cstId>
    <monLastConnect>2014-07-09T22:01:41.187Z</monLastConnect>
    <monLastSent>2014-07-09T22:02:09.000Z</monLastSent>
    <monTopic>DeviceCore</monTopic>
    <monTransportType>tcp</monTransportType>
    <monFormatType>json</monFormatType>
    <monBatchSize>1</monBatchSize>
    <monCompression>zlib</monCompression>
    <monStatus>INACTIVE</monStatus>
    <monBatchDuration>60</monBatchDuration>
    <monLastSentUuid>ac59ee13-07b4-11e4-a573-fa163ef93b22</monLastSentUuid>
  </Monitor>
  <Monitor>
    <monId>148215</monId>
    <cstId>2</cstId>
    <monLastConnect>2014-07-21T21:24:02.507Z</monLastConnect>
    <monLastSent>2014-07-14T17:17:15.000Z</monLastSent>
    <monTopic>DeviceCore,XbeeCore</monTopic>
    <monTransportType>http</monTransportType>
    <monTransportUrl>https://google.com</monTransportUrl>
    <monFormatType>json</monFormatType>
    <monBatchSize>100</monBatchSize>
    <monCompression>none</monCompression>
    <monStatus>DISABLED</monStatus>
    <monBatchDuration>10</monBatchDuration>
    <monTransportMethod>PUT</monTransportMethod>
  </Monitor>
</result>

Create an Http Monitor

The following sample shows how to create a simple HTTP monitor.

POST /ws/Monitor

Payload:

<Monitor>
  <monTopic>DeviceCore,XbeeCore</monTopic>
  <monTransportType>http</monTransportType>
  <monTransportUrl>https://your web site url</monTransportUrl>
  <monTransportToken>username:password</monTransportToken>
  <monTransportMethod>PUT</monTransportMethod>
  <monFormatType>json</monFormatType>
  <monBatchSize>100</monBatchSize>
  <monCompression>none</monCompression>
  <monBatchDuration>10</monBatchDuration>
</Monitor> 

Create a Tcp Monitor

The following sample shows how to create a TCP monitor.

POST /ws/Monitor

Payload:

<Monitor>
   <monTopic>DeviceCore,XbeeCore</monTopic>
   <monTransportType>tcp</monTransportType>
   <monFormatType>json</monFormatType>
   <monBatchSize>100</monBatchSize>
   <monCompression>none</monCompression>
   <monBatchDuration>10</monBatchDuration>
   <monAckOption>explicit</monAckOption>
   <monAutoReplayOnConnect>true</monAutoReplayOnConnect>
</Monitor>

Recover Disabled Monitor

An HTTP monitor that is not able to successfully connect over a 24 hour period is disabled. Once disabled:

• System alarm is generated to indicate the monitor state was changed to disabled.
• Remote Manager does not make any more attempts to connect the monitor.
• Persistent monitors no longer store missed monitor events.

To recover a disabled monitor, re-enable the monitor using the v1/monitors/inventory/{monitorId}/reset API and then wait for the monitor to reconnect.

Delete Monitor With Condition

The following examples shows how to delete all TCP monitors that are currently inactive:

DELETE ws/Monitor?condition=monTransportType='tcp' and monStatus='INACTIVE' 

Delete Monitor

The following sample shows how to delete a monitor.

DELETE /ws/Monitor/148214

Create Polling Monitor

The following sample shows how to create a polling monitor.

Request

POST /ws/Monitor

Payload

<Monitor>
  <monTopic>DeviceCore,DataPoint/00000000-00000000-00000000-00000000</monTopic>
  <monTransportType>polling</monTransportType>
  <monDescription>Query monitor saves push notifications but does not send them.</monDescription>
</Monitor> 

Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
  <location>Monitor/433016</location>
</result>

To query the data from a polling monitor, see v1/monitors.

Monitor HTTP/HTTPS Transport Protocol

This section highlights the details associated with an HTTPS or HTTP connection between the Remote Manager server and the customer web server. This is a high speed, transport over a HTTP connection. This transport requires that the customer has a publicly facing web server application. Remote Manager will be the HTTP client and will push any configured published events to the customer’s web server. This transport uses basic authentication and therefore HTTPS is recommended. HTTP is available for debugging or troubleshooting.

To configure an HTTP monitor, specify http as the monTransportType setting. Additionally, specify monTransportUrl, monTransportToken, and monTransportHeaders options.

monTransportType: (Required) Sets the transport type, TCP or HTTP. For HTTP, set the transport type to HTTP.

monTransportUrl: (Required) Specifies the URL of the customer web server. The URL should be of the following form:

http[s]://customer.domain.com/application/path

monTransportToken: (Required) Specifies the credentials for basic authentication in the following format:

username:password

monTransportMethod: (Optional) Specifies the HTTP method to use to send data: PUT or POST. The default is PUT.

The following example shows how to create an HTTP monitor:

<Monitor>
   <monTopic>DeviceCore,XbeeCore</monTopic>
   <monTransportType>http</monTransportType>
   <monTransportUrl>your website url</monTransportUrl>
   <monTransportToken>username:password</monTransportToken>
   <monTransportMethod>PUT</monTransportMethod>
   <monFormatType>json</monFormatType>
   <monBatchSize>100</monBatchSize>
   <monCompression>none</monCompression>
   <monBatchDuration>10</monBatchDuration>
</Monitor>

monTransportHeaders: (Optional) Specifies HTTP header fields in the following format:

header-name: header-value
header-name-2: header-value-2 

The standard and custom HTTP headers outlined below cannot be overridden.

Protocol

Once the HTTP monitor has been configured, the monitor will be activated and Remote Manager will connect to the customer’s web server. Any matching events will be published to the specified URL using the supplied token credentials. Please note that if the monitor’s URL or credentials are configured incorrectly or if the customer’s web server is unreachable, Remote Manager will periodically attempt to connect to the web server for up to 24 hours. The monitor will be disabled after 24 hours without a successful connection.

Events are published using the configured monTransportMethod: PUT or POST. The default is an HTTP PUT operation. The standard HTTP headers of the published event include:

• Authorization: Basic…
• Content-Type: “application/xml;charset=UTF-8” or “application/json;charset=UTF-8”
• Content-Length: indicates how many bytes of payload data are in the message
• [Content-Encoding: deflate] - if present, indicates the monitor event data is compressed

Additionally, the following custom header fields will be set to describe the payload being delivered:

• Monitor-Protocol-Version: indicates what version of push protocol is being used. The current version is ‘1’.
• Monitor-DataBlockId: a rotating integer ID that identifies the data block.
• Monitor-Aggregate-Count: the number of publish events included in this batch.

The body of the PUT operation is the published event payload data. Its format, compression, and size are indicated in the headers above. The payload data format is the same as for the TCP transport.

The returned HTTP status code indicates the ability of the customer application to receive and process the data:

• 200 - indicates customer application successfully received and processed the data

Standard HTTP headers

• Host: Indicates the domain name, and the port number of the server
• Accept: “text/html,application/xml,application/json”
• Accept-Language: “en-us”
• Accept-Charset: “UTF-8,ISO-8859-1”
• Cache-Control: “no-cache”
• Pragma: “no-cache”
• [Accept-Encoding: deflate]—If present, indicates the monitor event data is compressed.

Monitor Event Payload

Data is encapsulated in a message envelope that includes the topic, operation, and timestamp plus the data itself. This will be formatted according to the format type requested when establishing the monitor. Additionally, when the monAutoReplayOnConnect option is enabled, there will be a replay=“true” attribute if the message is being resent.

XML format

<?xml version="1.0" encoding="UTF-8"?>
<Msg topic="3/DeviceCore/882/7" operation="create|update|delete" timestamp="2010-12-03T13:34:00.001Z" [replay="true"]>
    <DeviceCore>
        <id>
            <devId>882</devId>
            <devVersion>7</devVersion>
        </id>
        <devRecordStartDate>2010-12-03T13:34:00Z</devRecordStartDate>
        <devMac>00:40:9D:3D:71:15</devMac>
        <devConnectwareId>00000000-00000000-00409DFF-FF3D7115</devConnectwareId>
        ...
    </DeviceCore>
</Msg>

JSON format

{
   "Document":{
      "Msg":{
         "timestamp":"2010-12-03T13:34:00.001Z",
         "topic":"3/DeviceCore/882/7",
         "operation":"UPDATE",
         "DeviceCore":{
            "id":{
               "devId":882,
               "devVersion":7
            },
            "devMac":"00:40:9D:3D:71:15",
            "...": "..."
         }
      }
   }
}

Tcp Transport Protocol

This section details standard TCP/IP and SSL socket connections between a client application and Remote Manager. Because authentication messages flow across the socket, we strongly recommend using SSL. Use standard TCP/IP connections for debugging and troubleshooting only.

Monitor configuration options for TCP

The Monitor API provides two TCP-specific elements:

monTransportType: (Required) Sets the transport type, TCP or HTTP. For TCP, set the transport type to TCP.

monAckOption: (Optional) Specifies acknowledge options for sent messages.

• explicit: Client must explicitly acknowledge TCP push events.
• off: Remote Manager automatically acknowledges events when sent.

The default is off.

The following example shows how to create a TCP monitor:

<Monitor>
   <monTopic>DeviceCore,XbeeCore</monTopic>
   <monTransportType>tcp</monTransportType>
   <monFormatType>json</monFormatType>
   <monBatchSize>100</monBatchSize>
   <monCompression>none</monCompression>
   <monBatchDuration>10</monBatchDuration>
   <monAckOption>explicit</monAckOption>
   <monAutoReplayOnConnect>true</monAutoReplayOnConnect>
</Monitor>

Protocol

When a monitor is created through the Web Services API, a Monitor ID is assigned and returned to the caller. If the monitor is configured to use the TCP transport the customer application can activate the monitor by establishing a TCP socket connection back to the Remote Managerserver. SSL monitor sockets should be made to port 3201 while unsecure TCP sockets should be made to port 3200.

Once Remote Manager makes the socket connection, the customer application must send a ConnectRequest message through that connection to the Remote Manager server. The server will authenticate the request and send back a response. Once the connect request succeeds, the server will begin sending PublishMessages to the customer application as events matching the monitor configuration occur. There are two options on how the customer application can acknowledge the PublishMessages: explicit and off. The acknowledgment option is configured using the monAckOption in the Monitor web service. If not specified, the monAckOption defaults to off.

Explicit means that the customer application will acknowledge the receipt of PublishMessages using the PublishMessageReceived message. The dataBlockId in the PublishMessageReceived indicates that all events up to and including that dataBlockId were successfully received, i.e. one PublishMessageReceive message can acknowledge multiple PublishMessages. If the customer application detects a missing dataBlockId or cannot process a PublishMessage, it should disconnect the TCP socket. On the next reconnect, the replay will start with the unacknowledged push event. (Note that monAutoReplayOnConnect needs to be enabled.)

The off option means that Remote Manager will treat the push event as acknowledged when it is written to the TCP socket. Any PublishMessageReceived messages will be ignored by Remote Manager if the monitor is configured with monAckOption set to off.

As long as the monitor socket connection remains open, monitor events will flow from the server to the customer application per the requirements established in the monitor configuration. If the socket is closed for any reason, the monitor will be deactivated and monitor events will stop flowing to the customer application. When the monitor is deactivated, the monitor’s status will be marked as SUSPENDED (for monitors configured for auto replay of missed events using monAutoReplayOnConnect), otherwise INACTIVE. The customer application can reactivate the monitor socket in the same manner as the initial connection.

Conventions

In this protocol, all multi-byte numeric fields must be transmitted in big endian format. All text data must be transmitted as UTF-8 characters. See RFC 2279 as a reference for this format.

Framing

All messages between the client application and the Remote Manager server are framed as follows:

• Header [6 Bytes]
  • Type: [2 Bytes] - indicates the type of message being exchanged
  • Length: [4 Bytes] - indicating size of the framed message payload
• Payload [n Bytes] - the wrapped message