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, BillingCenter 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 BillingCenter uses assignment rules to select a user in that group)
To a specific group and queue
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
`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, BillingCenter 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.

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 BillingCenter users are assigning activities manually, the user interface includes a drop-down list of "recommended assignees". Typically, this list includes:

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

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