The Groups API allows you to retrieve lists of groups, and lists of devices and datapoints in a group. It also allows you add devices and datapoints to a group, and delete devices and datapoints from a group.

URI Definition

Method

URI and Fields

GET

/iap/grp

Returns all groups that current user is permitted to read. This method allows pagination, sorting and filtering by name, though this is optional.

Query Parameters

name – filters groups by the specified name
scId – filters groups by segment controller’s id
scName – filters groups by segment controller’s name
pg – page number
sz – page size
sortOrder – sort order
sortBy – field by which sorting will be performed

Success Response

Collection of groups.

Example

https://localhost/iap/grp

Response

[
   {
       "id": 574,
       "name": "TestGroup",
       "geozoneId": 88,
       "devices": [
           "13"
       ],
       "datapoints": {
           "light-hlsb/0": {
               "datapointValueType": "HLSB",
               "name": "light-hlsb/0"
         },
           "motionControl": {
               "datapointValueType": "GROUP_MOTION_CONTROL",
               "name": "motionControl"
           }
       },
       "qualifiers": [
       ]
   }
]

/iap/grp/{id}

Returns a group with the specified ID. Returns nothing if the current user doesn't have permission to read this group.

Parameter

id – ID of the group

Success Response

Group with the specified ID.

Example

https://localhost/iap/grp/574

Response

{
   "id": 574,
   "name": "TestGroup",
   "geozoneId": 88,
   "devices": [
       "13"
   ],
   "datapoints": {
       "light-hlsb/0": {
           "datapointValueType": "HLSB",
           "name": "light-hlsb/0"
       },
       "motionControl": {
           "datapointValueType": "GROUP_MOTION_CONTROL",
           "name": "motionControl"
       }
   },
   "qualifiers": [
   ]
}

/iap/grp/gz/{id}

Returns a collection of groups related to the specified geozone. If flag recursive is set to true also returns all groups related to child geozones for the specified geozone. This method allows pagination, though it is optional.

Parameter

id – ID of the geozone

Query Parameters

recursive – if set to true enables recursive search in child geozones
pg – page number
sz – page size

Success Response

Collection of groups.

Example

https://localhost/iap/grp/gz/88

Response

[
   {
       "id": 574,
       "name": "TestGroup",
       "geozoneId": 88,
       "devices": [
           "13"
       ],
       "datapoints": {
           "light-hlsb/0": {
               "datapointValueType": "HLSB",
               "name": "light-hlsb/0"
           },
           "motionControl": {
               "datapointValueType": "GROUP_MOTION_CONTROL",
               "name": "motionControl"
           }
       },
       "qualifiers": [
       ]
   }
]

/iap/grp/count

Returns number of groups that matches passed filters.

Query Parameters

geozonePK – count groups that belongs only to the specified geozone
name – count only those groups which contains the specified substring in their names
scId – filters groups by segment controller’s id
scName – filters groups by segment controller’s name

Success Response

Number of groups for the specified filters.

Example

https://localhost/iap/grp/count

Response

{
"value": 2
}

PUT

/iap/grp

Update an already existed group with the specified properties.

Query Parameter

groupDTO – properties of the group

Success Response

Updated group.

Example

https://localhost/iap/grp

Request Body

{
"id":2002,
"name":"Updated group",
"geozoneId":88,
"devices":[],
"datapoints":{
   "light-hlsb/0":{
     "datapointValueType":"HLSB",
     "name":"light-hlsb/0"
   },
   "motionControl":{
     "datapointValueType":"GROUP_MOTION_CONTROL",
     "name":"motionControl"
   }
},
"qualifiers": []
}

Response

{
   "id": 2002,
   "name": "Updated group",
   "geozoneId": 88,
   "devices": [
   ],
   "datapoints": {
       "light-hlsb/0": {
           "datapointValueType": "HLSB",
           "name": "light-hlsb/0"
       },
       "motionControl": {
           "datapointValueType": "GROUP_MOTION_CONTROL",
           "name": "motionControl"
       }
   },
   "qualifiers": [
   ]
}

/iap/grp/delete

Deletes groups include or exclude the specific IDs.

Parameter

ids - the ids of groups to be deleted or excluded

Query Parameter

exclude - if TRUE, then all groups except specified IDs will be deleted ; if FALSE, then groups with the specified IDs will be deleted (default is FALSE)

Success Response

Collection with IDs of deleted groups.

Example

https://localhost/iap/grp/delete

https://localhost/iap/grp/delete?exclude=true

Request Body

[2003,2004,2005]

Response

[
   2003,
   2004,
   2005
]

/iap/grp/{groupId}/addDevs

Adds given devices to the group specified.

Parameter

groupId - group devices will be added to
deviceIds - devices to add

Success Response

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

Example

https://localhost/iap/grp/574/addDevs

Request Body

["14","15","17"]

Response

Response code 200

/iap/grp/{groupId}/assign/dev

Assigns the specified collection of devices to the specified group. Device can be assigned only to one group at a time, so in order to perform this operation make sure that device is not assigned to some other group. Throws ValidationException if and of devices already assigned to some other group.

Parameter

groupId - group devices will be added to
deviceIds - devices to add

Success Response

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

Example

https://localhost/iap/grp/574/assign/dev

Request Body

["14","15","17"]

Response

Response code 200

/iap/grp/{groupId}/assign/devs

Adds specified devices to the specified group.

Parameter

groupId – ID of the group devices will be added to
group members properties contains DIDs of devices to add to the group except excluded

Success Response

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

Example

https://localhost/iap/grp/468/assign/devs

Request Body

{
"processAllCurrentDevices":false,
"devicesDIDs": [
"3","4","5"
],
"devicesDIDsToExclude":[]
}

Response

Response code 200

/iap/grp/{groupId}/assign/dp

Adds specified datapoints to the specified group.

Parameter

groupId – ID of the group datapoints will be added to
group members properties contain qualifiers of datapoints to add to the group except excluded

Success Response

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

Example

https://localhost/iap/grp/468/assign/dp

Request Body

{
"devLevel":"*",
"blockNameLevel":"*",
"blockIndexLevel":"*",
"dpNameLevel":"*",
"valueLevel":"*",

"processAllCurrentDatapoints":false,
"datapointQualifiers": [
   "2/device/0/nviDO1",
   "2/device/0/nviDO2",
   "2/device/0/nviDO3"
],
"datapointQualifiersToExclude":[]
}

Response

Response code 200

/iap/grp/{groupId}/rmDevs

Removes specified devices from the specified group.

Parameter

groupId – group devices will be added to

deviceIds – devices to add

Success Response

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

Example

https://localhost/iap/grp/574/rmDevs

Request Body

["13","14","15","17"]

Response

Response code 200

/iap/grp/{groupId}/unassign/devs

Parameter

groupId – ID of the group that the datapoints will be added to

/iap/grp/{groupId}/unassign/dp

Removes specified datapoints from the specified group.

Parameter

groupId – ID of the group datapoints will be removed from
group members properties contain qualifiers of datapoints to remove from the group except excluded

Success Response

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

Example

https://localhost/iap/grp/468/unassign/dp

Request Body

{
"datapointQualifiers": [
"2/device/0/nviDO3"
]
}

Response

Response code 200

/iap/grp/getApplicable

Returns set of applicable groups for given devices. So all devices can be assigned on any of returned groups.

Query Parameter

deviceIds - devices to test

Success Response

Collections of suitable groups.

Example

https://localhost/iap/grp/getApplicable

Request Body

["13","14","15","17"]

Response

[
   {
       "id": 574,
       "name": "TestGroup",
       "geozoneId": 88,
       "schedules": [
           6,
           4
       ],
       "devices": [
       ],
       "datapoints": {
           "light-hlsb/0": {
               "datapointValueType": "HLSB",
               "name": "light-hlsb/0"
           },
           "motionControl": {
               "datapointValueType": "GROUP_MOTION_CONTROL",
               "name": "motionControl"
           }
       }
   }
]

/iap/grp/doImport/{importId}

Takes data from temporary cache by unique ID and moves devices to groups.

Parameter

importId - is a unique ID in temporary cache.
isProcess - if set to true then data from cache will be processed otherwise ignored and removed from cache

Success Response

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

Example

https://localhost/iap/grp/doImport/bb904c35-5d0d-4eb6-bf32-ac14736fcd4f?isProcess=true

Response

Response code 200

POST

/iap/grp

Creates new group in the CMS from the specified properties.

Query Parameter

groupDTO – properties of the group

Success Response

Created group.

Example

https://localhost/iap/grp

Request Body

{
"name":"New group",
"geozoneId":70
}

Response

{
   "id": 468,
   "name": "New group",
   "geozoneId": 70,
   "devices": [
   ],
   "datapoints": {
       "light-hlsb/0": {           "datapointValueType": "HLSB",           "name": "light-hlsb/0"       },       "motionControl": {           "datapointValueType": "GROUP_MOTION_CONTROL",           "name": "motionControl"       }   },   "qualifiers": [   ]}