--- name: cumulocity-manage-device-groups description: "Create a device group, assign devices to it and remove them, list and query its members, create a smart group whose members are the result of a stored query, and delete groups. Use when the user wants to create a device group or smart group, add or remove its devices, list its members, or delete it." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage device groups Source: https://cumulocity.com/docs/skills/device-management/manage-device-groups/ Sector: Skills, Device management & connectivity Release: Latest Description: Create a device group, assign devices to it and remove them, list and query its members, create a smart group whose members are the result of a stored query, and delete groups. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Groups organize devices according to your use case. A device can be in several groups, and a group can be part of other groups. Together with inventory roles, groups also control which users can access which devices. Cumulocity has two kinds of groups: * A **device group** is a managed object with the fragment `c8y_IsDeviceGroup` and the type `c8y_DeviceGroup`. You assign its members explicitly. The members are child assets of the group. * A **smart group** is a managed object with the fragment `c8y_IsDynamicGroup` and the type `c8y_DynamicGroup`. Its fragment `c8y_DeviceQueryString` stores an inventory query. The members are the devices that match the query at the time you read them. The platform stores no child references for a smart group. Smart groups are only visible in the Device Management application, not in the Cockpit application. > **Requirements:** > ROLES & PERMISSIONS: > > * To create and delete groups, and to assign and remove devices: ROLE_INVENTORY_ADMIN > * To list the members of groups: ROLE_INVENTORY_READ The examples use `` for the managed object ID of a device group, `` for the ID of a smart group, and `` for the managed object ID of a device. To find the ID of a device by its name, see [To filter devices by name](https://cumulocity.com/docs/skills/device-management/list-and-query-devices/#to-filter-devices-by-name). ### To create a device group {#to-create-a-device-group} Send a [Create one or multiple managed objects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource) request: ```http POST /inventory/managedObjects Content-Type: application/json Accept: application/json { "name": "Building A", "type": "c8y_DeviceGroup", "c8y_IsDeviceGroup": {} } ``` The platform returns HTTP 201 and the new group with its `id` and `"type": "c8y_DeviceGroup"`. Note the `id` as ``. ### To assign a device to the group {#to-assign-a-device-to-the-group} Send an [Assign a managed object as child asset](https://cumulocity.com/api/core/#operation/postManagedObjectChildAssetsResource) request: ```http POST /inventory/managedObjects//childAssets Content-Type: application/vnd.com.nsn.cumulocity.managedobjectreference+json Accept: application/json { "managedObject": { "id": "" } } ``` The platform returns HTTP 201 and the new reference, in which `managedObject.id` is ``. If the platform returns HTTP 404, the group or the device does not exist. To assign a subgroup, send the same request with the ID of the subgroup. ### To list the members of the group {#to-list-the-members-of-the-group} Send a [Retrieve all child assets of a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectChildAssetsResource) request: ```http GET /inventory/managedObjects//childAssets?pageSize=100 ``` The platform returns HTTP 200 and the `references` array. Each entry contains a member of the group in `managedObject`. ### To query devices by group {#to-query-devices-by-group} To combine group membership with other conditions, use the inventory query language. Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request: ```http GET /inventory/managedObjects?query=$filter=bygroupid()&pageSize=100 ``` The platform returns HTTP 200 and the members of the group in the `managedObjects` array. URL-encode the whole `query` value. The query language has two functions for groups: * `bygroupid(,)`: The direct members of the listed groups. * `isinhierarchyof()`: The group itself and all of its descendants, including subgroups and their members. For more conditions, see [List and query devices](https://cumulocity.com/docs/skills/device-management/list-and-query-devices/). ### To remove a device from the group {#to-remove-a-device-from-the-group} Send a [Remove a specific child asset from its parent](https://cumulocity.com/api/core/#operation/deleteManagedObjectChildAssetResource) request: ```http DELETE /inventory/managedObjects//childAssets/ ``` The platform returns HTTP 204. It removes only the reference. The device stays in the inventory. If the platform returns HTTP 422, the device is not a member of the group. ### To create a smart group {#to-create-a-smart-group} Send a [Create one or multiple managed objects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource) request with the query in `c8y_DeviceQueryString`: ```http POST /inventory/managedObjects Content-Type: application/json Accept: application/json { "name": "All pumps", "type": "c8y_DynamicGroup", "c8y_IsDynamicGroup": {}, "c8y_DeviceQueryString": "$filter=(name eq 'pump-*')" } ``` The platform returns HTTP 201 and the new smart group with its `id` and `"type": "c8y_DynamicGroup"`. Note the `id` as ``. ### To list the members of a smart group {#to-list-the-members-of-a-smart-group} 1. Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 and the smart group. Read the query from `c8y_DeviceQueryString`, here `$filter=(name eq 'pump-*')`. 2. Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request with the query as the `query` parameter: ```http GET /inventory/managedObjects?query=$filter=(name eq 'pump-*')&pageSize=100 ``` The query already starts with `$filter=`. URL-encode it as one parameter value. The platform returns HTTP 200 and the devices that match the query now in the `managedObjects` array. An empty array means that no device matches. ### To delete a group {#to-delete-a-group} Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request: ```http DELETE /inventory/managedObjects/ ``` The platform returns HTTP 204. It also deletes the subgroups of the group. The devices of the group and its subgroups stay in the inventory, because the parameter `cascade` is `false` by default. With `cascade=true`, the platform also deletes the devices. To delete a smart group, send the same request with ``. The devices that match its query are not affected. In the Device Management application, you manage groups in the **Groups** menu, see [Grouping devices](https://cumulocity.com/docs/device-management-application/grouping-devices/). ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /inventory/managedObjects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource): Create one or multiple managed objects - [POST /inventory/managedObjects/{id}/childAssets](https://cumulocity.com/api/core/#operation/postManagedObjectChildAssetsResource): Assign a managed object as child asset - [GET /inventory/managedObjects/{id}/childAssets](https://cumulocity.com/api/core/#operation/getManagedObjectChildAssetsResource): Retrieve all child assets of a specific managed object - [GET /inventory/managedObjects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource): Retrieve all managed objects - [DELETE /inventory/managedObjects/{id}/childAssets/{childId}](https://cumulocity.com/api/core/#operation/deleteManagedObjectChildAssetResource): Remove a specific child asset from its parent - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [DELETE /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource): Remove a specific managed object ## Linked from the documentation - [Grouping devices > Managing groups](https://cumulocity.com/docs/device-management-application/grouping-devices/#managing-groups)