URI Definition

Method

URI and Fields

GET

/iap/alarms

Returns all alarms that the current user is permitted to get, unless a filter is specified.

Response

Parameter	Description
id	[integer]
timestamp	[time]
category	[string]
severity	[string]
state	[string]
geozone	"id" : [integer], "name": [string]
device	The device ID. "id" : [integer], "name" : [string] "uidType" : [string], "uid": [string]
group	"id" : [integer], "name": [string]
type	[string]
details	[string]
alarmTargetType	[string]

Query Parameters

The following query parameters can be used with this endpoint.

Parameter	Description
activeOnly	Filter alarms by their state. If set to true then only active alarms are returned. If set to false then all alarms are returned.
deviceId	Count alarms that have a related device with the specified ID.
deviceName	Count alarms that have a related device with the specified name.
scId	Filters alarms by the segment controller’s ID
scName	Filters alarms by the segment controller’s name.
pg	Specifies the collection of alarms on the page identified by the Page number. Skipped if null or negative.
sz	Page size. Skipped if null or negative.
order	Sort order.
sortBy	Field on which sorting will be performed.

Example

https://localhost/iap/alarms?order=asc&pg=1&sortBy=timestamp&sz=25

Response:

[
   {
       "id": 1760,
       "timestamp": "2019-01-11T15:27:52.994-08:00[America/Los_Angeles]",
       "category": "System-SW",
       "severity": "Major Fault",
       "state": "Active",
       "geozone": {
           "id": 88,
           "name": "World"
       },
       "device": {
           "id": "25",
           "name": "Test Device",
           "uid": "00D07111EA6B"
       },
       "type": "Type mismatch",
       "details": "Device type mismatch for device Test Device",
       "alarmTargetType": "DEVICE"
   }
]

/iap/alarms/count

Returns either the count of active alarms that the current user is permitted to get, or returns the count of active alarms at the current moment (AlarmState.ACTIVE).

Query Parameters

The following query parameters can be used with this endpoint.

Parameter	Description
activeOnly	Filter alarms by their state. If set to true then only active alarms are returned. If set to false then all alarms are returned.
deviceId	Count alarms that have a related device with the specified ID.
deviceName	Count alarms that have a related device with the specified name.
scId	Filters alarms by the segment controller’s ID
scName	Filters alarms by the segment controller’s name.

Example

https://localhost/iap/alarms/count

Response:

{
"value": 5
}

/iap/alarms/definitions

Returns all alarm definitions that the current user is permitted to get.

Example:

https://localhost/iap/alarms/definitions

Response:

[
{
"scope": "AlarmDefinitionDTO",
"id": 1908,
"name": "New alarm definition",
"description": "Test definition",
"alarmType": 6,
"scope": "DEVICE",
"target": [
"2"
],

       "subscribers": [
       ]
   },
{
"scope": "AlarmDefinitionDTO",
"id": 1906,
"name": "Updated alarm definition",
"description": "Updated Test definition",
"alarmType": 14,
"scope": "DEVICE",
"target": [
"2",
"13"
],
"subscribers": [
]
}
]

/iap/alarms/definitions/{id}

Returns the alarm definition for the specified ID. Throws a ServiceRuntimeException if the specified alarm definition was not found.

Properties

The following property is used with this endpoint.

Parameter	Description
id	[integer] The ID of the alarm definition.
alarmDefinitionDTO	Properties from which a new alarm definition will be created

Success Response

Updated alarm definition.

Example:

https://localhost/iap/alarms/definitions/1906

Response:

[
{
"scope": "AlarmDefinitionDTO",
   "id": 1906,
   "name": "Updated alarm definition",
   "description": "Updated Test definition",
   "alarmType": 14,
   "scope": "DEVICE",
   "target": [
       "2",
       "13"
   ],
   "subscribers": [
       {
           "id": 486,
           "userName": "user",
           "firstName": "User",
           "lastName": "User",
           "emailAddress": "user@user.com"
       },
      {
           "emailAddress": "user35@user.com"
       },
{
           "id": 44,
           "userName": "admin",
           "firstName": "System",
           "lastName": "Administrator",
           "emailAddress": "fake_email@localhost.net"
}
]

/iap/alarms/definitions/{id}/subscribers

Updates the list of subscribers for the specified alarm definition.

Properties

The following property is used with this endpoint.

Parameter	Description
id	[integer] The ID of the alarm definition.
collection of subscriberDTO	Subscribers properties, can be an ID of a user in the CMS or just an email address.

Success Response

Updated alarm definition.

Example:

https://localhost/iap/alarms/definitions/1906/subscribers

Request Body:

[
{"id":44},
{"id":486},
{"emailAddress":"user35@user.com"}
]

Response:

{
    "scope": "AlarmDefinitionDTO",
    "id": 1906,
    "name": "Updated alarm definition",
    "description": "Updated Test definition",
    "alarmType": 14,
    "scope": "DEVICE",
    "target": [
        "2",
        "13"
    ],
    "subscribers": [
        {
            "id": 44,
            "userName": "admin",
            "firstName": "System",
            "lastName": "Administrator",
            "emailAddress": "fake_email@localhost.net"
        },
        {
            "id": 486,
"userName": "user",
            "firstName": "User",
            "lastName": "User",
            "emailAddress": "user@user.com"
        },
        {
            "emailAddress": "user35@user.com"
        }
    ]
}

/iap/alarms/dev/count

Returns the count of active alarms for the provided device IDs, or for all accessible devices if the list of provided IDs is null or empty.

Properties

The following property is used with this endpoint.

Parameter	Description
deviceId	[integer] The ID of a device IDs.

Query Parameter

The following query parameter can be used with this endpoint.

Parameter

Description

importantOnly

If set to true then only important alarms would be counted. Default value is "false".
Important alarms:

Day burner
Night outage
Knockdown
Stuck relay
Gateway not communicating
Lamp failure
Out of tolerance

Success Response:

List of pairs with the device ID and count of currently active alarms.

Example:

https://localhost/iap/alarms/dev/count

Request Body:

["2","25"]

Response:

[
    {
        "deviceId": "25",
        "count": 1
    }
]

/iap/alarms/dev/count/{deviceId}

Returns the number (count) of active alarms for devices using skipping non-communicating logic.

Properties

The following property is used with this endpoint.

Parameter	Description
deviceId	[integer] The ID of a device.

Response

Parameter	Description
deviceId	[integer]
count	[integer]

Example:

https://localhost/iap/alarms/dev/count/25

Response:

{
"value": 1
}

/iap/alarms/device/{deviceId}

Returns all alarms related to the specified device, including the cleared alarms.

Properties

The following property is used with this endpoint.

Property	Description
deviceId	[integer] The ID of a device.

Query Parameters

The following query parameters can be used with this endpoint.

Query Parameter	Description
pg	The page number. Skipped if null or negative.
sz	Page size. Skipped if null or negative.

Example:

https://localhost/iap/alarms/device/25

Response:

[
   {
       “id”: 1760,
       “timestamp”: “2019-01-11T15:27:52.994-08:00[America/Los_Angeles]”,
       “category”: “System-SW”,
       “severity”: “Major Fault”,
       “state”: “Active”,
       “geozone”: {
           “id”: 88,
           “name”: “World”
       },
       “device”: {
           “id”: “25”,
           “name”: “Test Device”,
           “uid”: “00D07111EA6B”
       },
       “type”: “Type mismatch”,
       “details”: “Device type mismatch for device Test Device”,
       “alarmTargetType”: “DEVICE”
   }
]

/iap/alarms/export

Exports alarms with the specified date range in CSV or PDF format. Response code is 200 in case of success, or some error code otherwise.

Query Parameters

The following query parameters can be used with this endpoint.

Query Parameter	Description
start	Specifies the start date for filtering based on a range of dates.
end	Specifies the end date for filtering based on a range of dates.
format	The format of the output file. Either CSV (the default) or PDF.
activeOnly	Filters alarms by their state. If set to true then only active alarms are returned. If set to false then all alarms are returned.

Example:

https://localhost/iap/alarms/export?start=2019-07-26T00:26:46.462-07:00[America/Los_Angeles]&end=2019-07-26T00:26:48.462-07:00[America/Los_Angeles]&format=csv&activeOnly=true

Response:

Output stream with alarms.

/iap/alarms/ids

Returns all alarm IDs that the current user is permitted to get, unless a filter is specified.

Query Parameters

The following query parameters can be used with this endpoint.

Parameter	Description
activeOnly	Filter alarms by their state. If set to true then only active alarm IDs are returned. If set to false then all alarm IDs are returned.
deviceId	Filter alarms that have a related device with the specified ID.
deviceName	Filter alarms that have a related device with the specified name.
scId	Filters alarms by the segment controller’s ID
scName	Filters alarms by the segment controller’s name.
pg	Specifies the collection of alarm IDs on the page identified by the page number. Skipped if null or negative.
sz	Page size. Skipped if null or negative.
order	Sort order.
sortBy	Field on which sorting will be performed.

Example

https://localhost/iap/alarms?order=asc&pg=1&sortBy=timestamp&sz=25

Response:

[
1760,
1765
]

/iap/alarms/types

Returns all default alarm types.

Example

https://localhost/iap/alarms/types

Response:

[
   {
       "id": 14,
       "name": "No valid coordinates",
       "messageTemplate": "Invalid coordinates have been received for SATM device %2$s"
   },
   {
       "id": 6,
       "name": "Out of Tolerance",
       "messageTemplate": "%s has a stuck relay."
   },
   {
       "id": 22,
       "name": "Last motion light level setting sent is out of sync with the device",
       "messageTemplate": "Last motion light level setting sent is out of sync with the device %s"
   },
   {
       "id": 19,
       "name": "Last repeater parameters sent are out of sync with the device",
       "messageTemplate": "Last repeater parameters sent are out of sync with the device %s"
   },
   {
       "id": 8,
       "name": "Device not communicating",
       "messageTemplate": "%s has not been communicating with the gateway."
   },
   {
       "id": 25,
       "name": "Type mismatch",
       "messageTemplate": "Device type mismatch for device %s"
   },
   {
       "id": 4,
       "name": "Day Burner",
       "messageTemplate": "%s was on during the day, but was supposed to be scheduled off."
   },
   {
       "id": 5,
       "name": "Night Outage",
       "messageTemplate": "%s was off during the night, but was supposed to be scheduled on."
   },
   {
       "id": 9,
       "name": "Gateway not communicating",
       "messageTemplate": "Gateway %s has not been communicating with the CMS software."
   },
   {
       "id": 18,
       "name": "Last schedule sent is out of sync with the device",
       "messageTemplate": "Last schedule sent is out of sync with the device %s"
   },
   {
       "id": 11,
       "name": "Placement error",
       "messageTemplate": "Several SATM devices without UID from different groups found nearly to device %s"
   },
   {
       "id": 15,
       "name": "No placement",
       "messageTemplate": "Unable to find SATM device without UID near to device %2$s"
   },
   {
       "id": 20,
       "name": "Last motion parameters sent are out of sync with the device",
       "messageTemplate": "Last motion parameters sent are out of sync with the device %s"
   },
   {
       "id": 10,
       "name": "Ambiguous placement",
       "messageTemplate": "Several SATM devices without UID from the same group found nearly to device %s"
   },
   {
       "id": 13,
       "name": "No device found",
       "messageTemplate": "No device found for UID %2$s (RC %3$s)"
   },
   {
       "id": 26,
       "name": "Provisioning failure",
       "messageTemplate": "Device %s failed to provision."
   },
   {
       "id": 12,
       "name": "No coordinates",
       "messageTemplate": "There are no coordinates received for SATM device %2$s"
   },
   {
       "id": 24,
       "name": "Last override command sent is out of sync with the device",
       "messageTemplate": "Last override command sent is out of sync with the device %s"
   },
   {
       "id": 3,
       "name": "Stuck Relay",
       "messageTemplate": "%s has a stuck relay."
   },
   {
       "id": 21,
"name": "Last DOT ID assigned is out of sync with the device",
       "messageTemplate": "Last DOT ID assigned is out of sync with the device %s"
   },
   {
       "id": 23,
       "name": "Last current tolerance threshold setting sent is out of sync with the device",
       "messageTemplate": "Last current tolerance threshold setting sent is out of sync with the device %s"
   },
   {
       "id": 7,
       "name": "Lamp Failure",
       "messageTemplate": "%s has lamp failure."
   },
   {
       "id": 27,
       "name": "Move to group failure",
       "messageTemplate": "Device %s move to group failed"

   },
   {
       "id": 16,
       "name": "knockdown",
       "messageTemplate": "The light pole has been knocked down for device %s"
   },
   {
       "id": 17,
       "name": "Firmware update failed",
       "messageTemplate": "Firmware update failed for device %s"
   }
]

PUT

/iap/alarms/clear

Changes the state to INACTIVE_OPERATOR for the specified alarms. Alarms are specified in the payload as an array of alarm IDs.

Response code is 200 in case of success, or some error code otherwise.

Parameters:

Parameter	Description
alarmId	IDs of alarms

Example:

https://localhost/iap/alarms/clear

Request Body:

[1760]

Response:

empty

/iap/alarms/devs

Returns all alarms related to the specified devices, including the cleared ones. A successful request returns a collection of device IDs with their alarms.

Parameters:

Parameter	Description
deviceIds	IDs of devices.

Query Parameters

Query Parameter	Description
activeOnly	Filter alarms by their state. If set to true then only active alarms will be returned. If set to false then all alarms will be returned
gpsOnly	Filter alarms by their type. If set to true then only GPS-related alarms will be returned. If set to false then all alarms will be returned regardless of their type.

Example:

https://localhost/iap/alarms/devs

Request Body:

["2","25"]

Response:

[
   {
       "deviceId": "25",
       "alarms": [
           {
               "id": 1760,
               "timestamp": "2019-01-11T15:27:52.994-08:00[America/Los_Angeles]",
               "category": "System-SW",
               "severity": "Major Fault",
               "state": "Active",
               "geozone": {
                   "id": 88,
                   "name": "World"
               },
               "device": {
                   "id": "25",
                   "name": "Test Device",
                   "uid": "00D07111EA6B"
               },
               "type": "Type mismatch",
               "details": "Device type mismatch for device Test Device",
               "alarmTargetType": "DEVICE"
           }
       ]
   }
]

POST

/iap/alarms/definitions

Creates a new alarm definition with the specified properties. Successful response is the created alarm definition.

Parameters:

Parameter	Description
alarmDefinitionDTO	The properties from which a new alarm definition is created. Specified in the request body.

Example:

https://localhost/iap/alarms/definitions

Request Body:

{
"name":"New alarm definition",
"description":"Test definition",
"alarmType":14,
"scope":"DEVICE
"target":["2"],
"subscribers":[]
}

Response:

{
   "scope": "AlarmDefinitionDTO",
   "id": 1908,
   "name": "New alarm definition",
   "description": "Test definition",
   "alarmType": 14,
   "scope": "DEVICE",
   "target": [
"2"
   ],
   "subscribers": [
   ]
}

DELETE

/iap/alarms/definitions/{id}

Deletes the specified alarm definition from the CMS. The response code is 200 in case of success, or an error code otherwise.

Example:

https://localhost/iap/alarms/definitions/1908

Query Parameters

Optional query parameters can be used with your REST request. Specifying queries is described under Queries and Parameters, Path Parameters, and Query Parameters.