Workgroups
Workgroups are hierarchical groupings of tasks, users, and entities such as quotes and policies. The Auto-Assign API endpoint can be used to automatically assign tasks and create associations between users and entities.
Workgroups can have multiple child workgroups, but only one parent workgroup. Multiple users can be assigned to the same workgroup.
Create a Workgroup
The Create Workgroup API endpoint can be used to create workgroups and add users to workgroups.
For example:
{
"name": "Level2.1",
"users": ["n8ec-akn2-nad9"],
"tag": "tag"
}
{
"name": "Level2.2",
"users": ["jae8-3ndc-bd23"],
"tag": "tag"
}
Once these workgroups have been created, you can create a parent workgroup and specify child workgroups by including the locators of the above workgroups in the list of subgroups.
For example:
{
"name": "Level1",
"subgroups": ["01NCA87CDD8D", "01SNCZOA83BC"],
"users": ["vf23-nd72-7bd3"],
"tag": "tag"
}
You can also specify a parent workgroup when creating a workgroup by specifying the locator of a parent workgroup in the parentLocator field.
For example:
{
"name": "Level1",
"parentLocator": "01DVS65J7BSL",
"users": ["vf23-nd72-7bd3"],
"tag": "tag"
}
The List Workgroups and Get Workgroup API endpoints can be used to retrieve workgroup details. See the Work Management API index for additional workgroup API endpoints.
Auto-Assign
The Auto-Assign API endpoint can be used to automatically assign a task to a user within a workgroup hierarchy.
Auto-Assigning Tasks to Users
The auto-assign algorithm will first attempt to assign the task to a user within the specified workgroup who has an association with the specified entity. If no such users are found within the workgroup, the algorithm will traverse the workgroup hierarchy using the specified traversal method until it finds a workgroup that contains a user who has an association with the specified entity, and will assign the task to that user.
If the algorithm finds multiple candidates within a workgroup, it will assign the task based on round robin selection, meaning it will select the user who has gone the longest without being auto-assigned a task.
Here’s an example of an auto-assign request to assign an existing task to a user who is currently associated with a quote:
{
"taskLocator": "01HBL21O8VAZ",
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote",
"workgroupLocator": "01DVS65J7BSL"
}
You can also specify a new task that will be created before the auto-assign algorithm attempts to assign the task.
For example:
{
"task": {
"description": "Example description",
"type": "underwritingReferral"
},
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote",
"workgroupLocator": "01DVS65J7BSL"
}
Auto-Assigning Tasks to Workgroups
If no candidates are found within the workgroup hierarchy, the algorithm will refer to the value of the assignToGroup field to determine whether it should then attempt to assign the task to the workgroup specified in the request instead of a user:
never- The task will never be assigned to the workgroup.ifNotAssigned- The task will be assigned to the workgroup only if the task is not currently assigned to a different workgroup. This is the default value.always- The task will always be assigned to the workgroup.
Here’s an example of an auto-assign request that specifies a value for the assignToGroup field:
{
"taskLocator": "01HBL21O8VAZ",
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote",
"workgroupLocator": "01DVS65J7BSL",
"assignToGroup": "never"
}
Traversal
The auto-assign algorithm can traverse a workgroup hierarchy using either a depthFirst or breadthFirst approach. Sibling workgroups are ordered by workgroup locator in ascending order.
By default, the traversal approach is none, meaning the auto-assign algorithm will only attempt to assign tasks to users within the workgroup specified in the request, but will not traverse the workgroup hierarchy when attempting to find users.
Here’s an example of an auto-assign request that specifies a value for the traversal field:
{
"taskLocator": "01HBL21O8VAZ",
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote",
"workgroupLocator": "01DVS65J7BSL",
"traversal": "breadthFirst"
}
Auto-Assigning Qualified Users
If a value for the associationRole field is specified in the request, the algorithm will only assign the task to a user with at least one of the qualifications necessary to be assigned to the specified association role. See the User Association guide for more information.
Note
Ensure users have the necessary qualifications before attempting to auto-assign tasks. User qualifications can be updated using the Update User Qualifications API endpoint.
Here’s an example of an auto-assign request that specifies a value for the associationRole field:
{
"taskLocator": "01HBL21O8VAZ",
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote",
"workgroupLocator": "01DVS65J7BSL",
"associationRole": "leadUnderwriter"
}
Auto-Assigning Tasks Without Specifying a Workgroup
If no workgroup is provided in the request, the algorithm will attempt to assign the task to a user who is associated with the specified entity, regardless of whether the user has been added to a workgroup. For this use case, if no such users are found, the request will fail, regardless of the value of the assignToGroup field. If the algorithm finds multiple candidates, it will assign the task based on round robin selection.
Here’s an example of an auto-assign request that doesn’t specify a workgroup:
{
"taskLocator": "01HBL21O8VAZ",
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote"
}
Using Auto-Assign to Create Associations
If no task is provided in the request, the algorithm will attempt to create an association between a user and the entity specified in the request. For this use case, if no such users are found, the request will fail, regardless of the value of the assignToGroup field. If the algorithm finds multiple candidates, it will assign the task based on round robin selection.
Here’s an example of an auto-assign request to create an association:
{
"referenceLocator": "01PWA37PACZQ",
"referenceType": "quote"
}