Assigning activities

Ultimately, every activity is assigned to a group and a user in that group. This user has the primary responsible for closing the activity.

Activities can be temporarily assigned to queues. A queue is a repository belonging to a group which contains activities assigned to the group but not yet to any user in that group. Users in the group can then take ownership of activities manually as desired.

When you create an activity through the system APIs, PolicyCenter automatically executes the activity assignment rules to initially assign the activity to a group and user. You can use the /{activityId}/assign endpoint to reassign the activity as needed.

Assignment options

An activity can be assigned through the system APIs in the following ways:

To a specific group and user in that group
To a specific group only (and then PolicyCenter uses assignment rules to select a user in that group)
To a specific group and queue
To the user who holds a given role on the parent account, job, or policy
By re-running the activity assignment rules
- This can be appropriate if you have modified the activity since the last time assignment rules were run and the modification might affect who the activity would be assigned to.

The root resource for the /{activityId}/assign endpoint is Assignee. This resource specifies assignment criteria. The Assignee schema has the following fields:


Field	Type	Description
`autoAssign`	Boolean	Whether to assign the activity using assignment rules
`groupId`	string	The ID of the group to assign the activity to
`queueId`	string	The ID of the queue to assign the activity to
`role`	TypeKeyReference (`UserRole`)	The role on the parent object that identifies the user to assign the activity to
`userId`	string	The ID of the user to assign the activity to

The Assignee resource must specify an assignment option. It cannot be empty.

Assignment examples

When assigning activities to users, the user must be active and must have the "own activity" system permission.

Assigning to a specific group (and user)

The following payload assigns activity xc:1 to group demo_sample:31 and user demo_sample:1.

POST /common/v1/activities/xc:1/assign

{
  "data": {
    "attributes" : {
      "groupId" : "demo_sample:31",
      "userId" : "demo_sample:1"
    }
  }
}

The following payload assigns activity xc:1 to group demo-sample:31. Because no user has been specified, PolicyCenter will execute assignment rules to assign the activity to a user in group demo-sample:31.

POST /common/v1/activities/xc:1/assign

{
  "data": {
    "attributes" : {
      "groupId": "demo_sample:31"
    }
  }
}

Note that there is currently no endpoint that returns groups or group IDs. To assign activities to a specific group, the caller application must determine the group ID using some method other than a groups system API.

Assigning to a specific queue

The following payload assigns activity xc:1 to queue cc:32. Every queue is associated with a single group, so the activity will also be assigned to that group. Users in that group who have access to this queue can then manually take ownership of the activity.

POST /common/v1/activities/xc:1/assign

{
  "data": {
    "attributes" : {
      "queueId": "cc:32"
    }
  }
}

Note that there is currently no endpoint that returns queues or queue IDs. To assign activities to a queue, the caller application must determine the queue ID using some method other than a queues system API.

Assigning to a user with a given role

When an activity is assigned by role, PolicyCenter looks at the activity's parent (the account, job, or policy) and identifies the user with the given role. The activity is then assigned to that user. The role must be a code from the UserRole typelist.

For example, if an account activity is to be assigned to "Underwriter" and the underwriter for the account is Bruce Baker, the activity is assigned to Bruce Baker.

If you attempt to assign an activity by role and there is no user on the parent object with the given role, PolicyCenter:

Identifies the user that created the object (This is the user with the "Creator" role.)
Adds the given role to this user
Assigns the activity to this user

For example, suppose there is an account created by Christine Craft. The account has no underwriter. If a system API attempts to assign an activity for this account to "Underwriter", PolicyCenter will add the underwriter role to Christine Craft and then assign the activity to her.

The following payload assigns activity xc:1 to the user on the activity parent that has the underwriter role.

POST /common/v1/activities/xc:1/assign

{
  "data": {
    "attributes" : {
        "role" : {
	   "code" : "Underwriter"
        } 
    }
  }
}

Using automated assignment

The following payload assigns activity xc:1 using automated assignment rules.

POST /common/v1/activities/xc:1/assign

{
  "data": {
    "attributes": {
        "autoAssign" : true
    }
  }
}

For more information on assignment rules, see the Gosu Rules Guide.

Retrieving recommended assignees

When PolicyCenter users are assigning activities manually, the user interface includes a drop-down list of "recommended assignees". Typically, this list includes:

The roles held by users on the parent object
Users in the group the activity is currently assigned to.
Any queues belonging to the group the activity is currently assigned to.

The contents of this drop-down list are generated by an application-specific SuggestedAssigneeBuilder class. You can access the same contents by executing a GET with one of the following /assignee endpoints:


Endpoint	Returns
`/common/v1/activity/{activityId}/assignee`	The list of suggested assignees for this activity
`/account/v1/accounts/{accountId}/activity-assignees`	The list of suggested assignees for activities on this account
`/job/v1/jobs/{jobId}/activity-assignees`	The list of suggested assignees for activities on this job
`/policy/v1/policies/{policyId}/activity-assignees`	The list of suggested assignees for activities on this policy

The following is a portion of an example response from the Common API's /assignee endpoint.

GET /common/v1/activities/pc:301/assignees

{
    "count": 5,
    "data": [
        {
            "attributes": {
                "name": "Creator",
                "role": {
                    "code": "Creator",
                    "name": "Creator"
                }
            }
        },
        {
            "attributes": {
                "groupId": "systemTables:1",
                "name": "Edward Lee (Enigma Fire & Casualty)",
                "userId": "pc:23"
            }
        },
        {
            "attributes": {
                "groupId": "systemTables:1",
                "name": "Alice Applegate (Enigma Fire & Casualty)",
                "userId": "pc:8"
            }
        },
        ...
    ],
    ...