Groups

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.

.

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>