# Workgroups



Workgroups are hierarchical groupings of [tasks](/features/work-management/tasks), users, and entities such as quotes and policies.
The <ApiLink name="autoAssign">Auto-Assign</ApiLink> API endpoint can be used to automatically assign tasks and create [associations](/features/work-management/user-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 [#create-a-workgroup]

The <ApiLink name="createWorkgroup">Create Workgroup</ApiLink> API endpoint can be used to create workgroups and add users to workgroups.

For example:

```json
{
	"name": "Level2.1",
	"users": ["n8ec-akn2-nad9"],
	"tag": "tag"
}
```

```json
{
	"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:

```json
{
	"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:

```json
{
	"name": "Level1",
	"parentLocator": "01DVS65J7BSL",
	"users": ["vf23-nd72-7bd3"],
	"tag": "tag"
}
```

The <ApiLink name="listWorkgroups">List Workgroups</ApiLink> and <ApiLink name="getWorkgroup">Get Workgroup</ApiLink> API endpoints can be used to retrieve workgroup details. See the [Work Management API](/api/work-management) index for additional workgroup API endpoints.

<span id="AutoAssign" />

Auto-Assign [#auto-assign]

The <ApiLink name="autoAssign">Auto-Assign</ApiLink> API endpoint can be used to automatically assign a task to a user within a workgroup hierarchy.

Auto-Assigning Tasks to Users [#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](/features/work-management/user-associations) 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:

```json
{
	"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:

```json
{
	"task": {
		"description": "Example description",
		"type": "underwritingReferral"
	},
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote",
	"workgroupLocator": "01DVS65J7BSL"
}
```

Auto-Assigning Tasks to Workgroups [#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:

```json
{
	"taskLocator": "01HBL21O8VAZ",
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote",
	"workgroupLocator": "01DVS65J7BSL",
	"assignToGroup": "never"
}
```

Traversal [#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:

```json
{
	"taskLocator": "01HBL21O8VAZ",
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote",
	"workgroupLocator": "01DVS65J7BSL",
	"traversal": "breadthFirst"
}
```

Auto-Assigning Qualified Users [#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](/features/work-management/user-associations#RoleQualification) necessary to be assigned to the specified association role. See the [User Association](/features/work-management/user-associations) guide for more information.

<Callout>
  Ensure users have the necessary qualifications before attempting to auto-assign tasks. User qualifications can be updated using the <ApiLink name="updateUserQualifications">Update User Qualifications</ApiLink> API endpoint.
</Callout>

Here's an example of an auto-assign request that specifies a value for the `associationRole` field:

```json
{
	"taskLocator": "01HBL21O8VAZ",
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote",
	"workgroupLocator": "01DVS65J7BSL",
	"associationRole": "leadUnderwriter"
}
```

Auto-Assigning Tasks Without Specifying a Workgroup [#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`:

```json
{
	"taskLocator": "01HBL21O8VAZ",
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote"
}
```

Using Auto-Assign to Create Associations [#using-auto-assign-to-create-associations]

If no task is provided in the request, the algorithm will attempt to create an [association](/features/work-management/user-associations) 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:

```json
{
	"referenceLocator": "01PWA37PACZQ",
	"referenceType": "quote"
}
```

Next Steps [#next-steps]

* [Workplans](/features/work-management/workplans)

See Also [#see-also]

* [Tasks](/features/work-management/tasks)
* [User Associations](/features/work-management/user-associations)
* [Work Management API](/api/work-management)