Groups

A group is a set of users who represent a single business unit or who are assigned a single body of work.

Querying for groups

To retrieve information about a group, use the following endpoints:

  • GET /admin/v1/groups
  • GET /admin/v1/groups/{groupId}

For example, the following is the snippet of the response payload when retrieving the information for group demo_sample:31.

GET /admin/v1/users/demo_sample:31

{
    "data": {
        "attributes": {
            "displayName": "Alexandria Branch",
            "groupType": {
                "code": "branch",
                "name": "Branch office"
            },
            "id": "demo_sample:31",
            "name": "Alexandria Branch",
            "parent": {
                "displayName": "Eastern Region",
                "id": "demo_sample:29",
                "type": "Group",
                "uri": "/admin/v1/groups/demo_sample:29"
            },
            "securityZone": {
                "displayName": "Auto and Property",
                "id": "default_data:1"
            },
            "supervisor": {
                "displayName": "Sue Smith",
                "id": "demo_sample:2",
                "type": "User",
                "uri": "/admin/v1/users/demo_sample:2"
            }
        },
        ...
    }
}

Creating groups

To create a group, use the following endpoint:

  • POST /admin/v1/groups

When creating a group, you must specify the following values:

  • groupType - a value from the GroupType typelist, such as general
  • name - a string value
  • parent - A JSON object with an id field that references the id of the parent group
  • securityZone - A JSON object with an id field that references the id of the group's security zone
  • supervisor - A JSON object with an id field that references the id of the user who is the supervisor

As of this release, there is no endpoint for retrieving information about security zones. To identify the ID of the desired security zone, you must use some other method.

The user who is designated as the supervisor of the group is not required to be a member of the group. Also, designated a user as the supervisor does not automatically add the user to the group as a member.

For example, the following request creates a new group:
POST /admin/v1/groups

{
  "data": {
    "attributes": {
        "groupType": {
            "code": "general"
        },
        "name": "Cloud API Group 1",
        "parent": {
            "id": "systemTables:1"
        },
        "securityZone": {
            "id": "default_data:1"
        },
        "supervisor": {
            "id": "demo_sample:7"
        }
    }
  }
}

Assigning users to a group

You cannot assign a user to a group using the /admin/v1/users endpoint. You must use the /admin/v1/groups/{groupId}/users endpoint. For more information, see Assigning users to groups

.

Assigning producer codes to a group

A group can be associated with one or more producer codes. For more information, see Producer codes.

.

Assigning users to groups

The GroupUser entity

In PolicyCenter, users and groups are tracked as separate User and Group entities. There is a third entity, GroupUser, whose purpose is to track information about one assignment of a user to a group. For example, if an instance of GenericCenter has two groups and three users and every user belongs to every group:

  • There would be two instances of Group
  • There would be three instances of User
  • There would be six instances of GroupUser (user 1 to group A, user 1 to group B, user 2 to group A, and so on)

In addition to tracking a single user assignment to a group, the GroupUser entity also tracks information about the user’s capabilities within the group. This includes the following fields:

  • manager - Boolean indicating whether the user has permission to view the activity of others in the group
  • member - Boolean indicating whether the user is a working member of the group (for purposes of work assignment), as opposed to simply being associated with the group as a manager or other auxiliary person
  • loadFactor - Percent of work that can be assigned to the user

Querying for group/user information

To retrieve information about user assignments for a group, use the following endpoints:

  • GET /admin/v1/groups/{groupId}/users
    • Returns a collection of user assignments for the group
  • GET /admin/v1/groups/{groupId}/users/[groupUserId}
    • Returns information about a specific user assignment to the group

For example, the following is the snippet of the response payload when retrieving the information for the GroupUser assignments in group demo_sample:31. Note that the count is 12, which means the group has 12 users. Information is then provided about each GroupUser assignment, including who the user is, and whether the user is a member or a manager.

GET /admin/v1/users/demo_sample:31/users

{
    "count": 12,
    "data": [
        {
            "attributes": {
                "id": "cc:SfZwdri9ldAAUgR46xZT7",
                "manager": false,
                "member": true,
                "user": {
                    "displayName": "Andy Applegate",
                    "id": "demo_sample:1",
                    "type": "User",
                    "uri": "/admin/v1/users/demo_sample:1"
                }
            },
            ...
        },
        {
            "attributes": {
                "id": "cc:SZPhG_CUIA3E1sO2AiZ_s",
                "manager": false,
                "member": true,
                "user": {
                    "displayName": "Betty Baker",
                    "id": "demo_sample:8",
                    "type": "User",
                    "uri": "/admin/v1/users/demo_sample:8"
                }
            },
            ...
        },
        ...

Adding a user to a group

To add a user to a group, use the following endpoint:

  • POST /admin/v1/groups/{groupId}/users

In the request, you must specify the user to be added to the group. You can optionally specify other attributes. If you do not, the following default values are used:

  • member: true
  • manager: false
  • loadFactor: null

For example, the following request adds user demo_sample:18 to group demo_sample:31.

POST /admin/v1/groups/demo_sample:31/users

{
  "data": {
    "attributes": {
        "user": {
            "id": "demo_sample:18"
        }
    }
  }
}

This assigns user demo_sample:18 to group demo_sample:31 as a member. The user is not a manager of the group and has a null load factor. (If a field’s value is null, the field is not included in Cloud API responses.)

Modifying information about a user’s GroupUser assignment

To modify a user’s GroupUser assignment information, use the following endpoint:

  • PATCH /admin/v1/groups/{groupId}/users/{groupID}

For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser object whose id is xc:55. This user is a member of the group and not a manager of the group. The following PATCHes the GroupUser assignment so that the user is a manager of the group and not a member. (They can view work assigned to other users in the group, and they will not have work assigned to them.)

PATCH /admin/v1/groups/demo_sample:31/users/xc:55

{
  "data": {
    "attributes": {
        "manager": true,
        "member": false
    }
  }
}

Removing a user from a group

To remove a user from a group, you must delete the corresponding GroupUser assignment. To do this, use the following endpoint:

  • DELETE /admin/v1/groups/{groupId}/users/{groupUserId}

For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser object whose id is xc:55. The following request removes user demo_sample:18 to group demo_sample:31.

DELETE /admin/v1/groups/demo_sample:31/users/xc:55

<no request body>

Updating groups

Use the following endpoint to modify an existing group:

  • PATCH /admin/v1/groups/{groupId}
For example, the following request updates the supervisor of group xc:202:
PATCH /admin/v1/groups/xc:202

{
  "data": {
    "attributes": {
        "supervisor": {
            "id": "demo_sample:6"
        }
    }
  }
}

Deleting groups

Use the following endpoint to delete an existing group:

  • DELETE /admin/v1/groups/{groupId}
For example, the following request deletes group xc:202:
DELETE /admin/v1/groups/xc:202

<no request body>