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

Success Response

Example

Request Body

Response

/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": [
   ]
}

/iap/grp/import

.Pre import stage, parses a CSV file and counts number of devices that will be processed. Saves parsed data into temporary import's cache.

Query Parameter

csv file with groups names and assigned to groups devices.

Success Response

Unique ID of import stage, number of devices which will be assigned to groups and number of devices which will be ignored because they are already in the group.

Example

https://localhost/iap/grp/import

Request Payload

------WebKitFormBoundarydNh2Op2OFrhgfoYA
Content-Disposition: form-data; name="file"; filename="import_groups.csv"
Content-Type: application/vnd.ms-excel

------WebKitFormBoundarydNh2Op2OFrhgfoYA--

Response

{
   "importId": "bb904c35-5d0d-4eb6-bf32-ac14736fcd4f",
   "accepted": 2,
   "ignored": 0
}

DELETE

/iap/grp/{id}

.Deletes the specified group from the CMS.

Parameter

id – ID of the group to be deleted

Success Response

Status of performed operation. True in case of success and false otherwise.

Example

https://localhost/iap/grp/2002

Response

{
"value": true
}

Queries

You can include queries with your IAP/REST request to specify a selection rule for your request. As described in Queries and Parameters, you can specify a query as a query parameter appended to the end of your URI preceded with a "?" character, or as a path parameter within a path element of the path component. The following list describes the optional path parameters for the devices id path element.

Path Parameter	Description
assetTag={tag}	Filters the devices for the specified asset tag
category={cat}	Filters the devices for the specified category. The value for cat can be edge for edge devices, or sc for segment controllers (edge servers) such as the SmarServer IoT.
connection={conn}	Filters for devices with the specified connection status.
description={desc}	Filters the devices for the specified description.
firmwareVersion={version}	Filters for devices running the specified firmware version number.
fixtureManufacturer	Filters for devices with the specified manufacturer.
fixtureModel	Filters for devices with the specified model.
geozone.description={gz_desc}	Filters the devices for the specified geozone description.
geozone.id={gz_id}	Filters for devices with the specified geozone ID.
geozone.name={gz_name}	Filters for devices with the specified geozone name.
groups.id	Filters for devices with the specified group ID.
groups.name	Filters for devices with the specified group name.
health={health}	Filters for devices with the specified health.
id={dev_id}	Filters for devices with the specified device ID.
installation_date={date}	Filters for devices with the specified installation date.
lampType	Filters for devices with the specified lampType.
lightDistributionType	Filters for devices with the specified lightDistributionType.
mac
name={device_name}	Filters for devices with the specified device name.
poleType
postInstallWattage
preInstallWattage
ratedLifeHours
status={status}	Filters for devices with the specified status. The status values can be provisioned, unprovisioned, provisioning, unprovisioning, or deleted.
timezone={tz}	Filters for devices installed in the specified timezone.
type={device_type}	Filters for devices with the specified device type.
uid={uid}	Filters for devices with the specified unique ID.
utilityAccountNo
utilityRate

The following list describes the optional path parameters for the block_name path element of the Datapoint Value endpoint:

Path Parameter	Description
type={profile}	Filters for blocks with the specified block type (profile).

The following list describes the optional path parameters for the datapoint_name path element of the Datapoint Value endpoint:

Path Parameter	Description
lvl_1_interval={log_interval_1}	Filters for datapoints with the specified log interval 1.
lvl_1_retention={log_retention_1}	Filters for datapoints with the specified log retention period 1.
lvl_2_interval={log_interval_2}	Filters for datapoints with the specified log interval 2.
lvl_2_retention={log_retention_2}	Filters for datapoints with the specified log retention period 2.
lvl_3_interval={log_interval_3}	Filters for datapoints with the specified log interval 3.
lvl_3_retention={log_retention_3}	Filters for datapoints with the specified log retention period 3.
name={dp_type}	Filters for datapoints with the specified datapoint type name.
status={sts}	Filters for datapoints with the specified status. The sts value can be online or offline.
tag={tag_name}	Filters for datapoints with the specified tag name.
tag.value={tag_value}	Filters for datapoints with the specified tag value.
type={dp_type}	Filters for datapoints with the specified datapoint type name.

The following list describes the optional path parameters for the prop_name path element of the Datapoint Value endpoint:

Path Parameter	Description
name={prop_type}	Filters for properties with the specified property type.
type={prop_type}	Filters for properties with the specified property type.
value={prop_value}	Filters for properties with the specified property value.