# Tasks



Overview [#overview]

*Tasks* represent work that users are expected to perform, often in relation to one or more system entities. They can be any of a set of types. Tasks can be used in a wide variety of situations, such as:

* An underwriter that needs to verify that a property inspection has been done satisfactorily
* A customer service representative that needs to contact an insured about a past-due invoice or pending lapse
* An agent coordinator that needs to ensure agents' and brokers' training and qualification process is complete

<Callout>
  Tasks differ from [User Associations](/features/work-management/user-associations) in that they represent a discrete activity that is no longer active once the task is completed. User associations typically represent longer-term associations where a user has an ongoing responsibility with regard to a particular entity.
</Callout>

Configuration [#configuration]

Each task type needs to be configured. In configuration, we might have:

```json
{
	"tasks": {
		"customerService": {
			"customerInquiry": {
				"defaultDeadlineDays": 1.5
			}
		},
		"underwriting": {
			"inspectionReview": {
				"defaultDeadlineDays": 2.25,
				"underwritingBlock": true
			}
		}
	}
}
```

<ApiSchema name="TaskTypeRef" />

Here we have two task types defined: `customerInquiry` has category `customerService`, and `inspectionReview` has category `underwriting`.

Deadlines [#deadlines]

Tasks have an optional `deadlineTime`, which represents the time by which the user is expected to complete the task.

If the `deadlineTime` for an incomplete task is changed, the task's state would also change as needed. For example, if changing from the past to the future, the state would change from `pastDeadline` to `active`.

<Callout>
  Future releases will enable automated task reassignment and/or escalation of tasks to supervisors or alternative users for tasks that are incomplete at their deadline time. An alternative `escalationTime` will allow escalation at a different time if desired.
</Callout>

Creation of Tasks [#creation-of-tasks]

Tasks are created manually via discrete calls to the Socotra API or programmatically via integration or plugins.

Tasks may also be created as part of underwriting flag creation via the inclusion of the optional `taskCreation` property in any <ApiLink name="UnderwritingFlagCreateRequest" />. The `taskCreationResponse` property of the <ApiLink name="UnderwritingFlagResponse" /> will contain the status of the resulting task creation.

The following changes can be made via the API to an existing task:

* Changing or removing the assigned user
* Completing it
* Cancelling it
* Changing the `deadlineTime`
* Adding or removing references
* Adding underwriting flag associations (to any type of flag, not just block)
* Removing underwriting flag associations

Underwriting Blocks [#underwriting-blocks]

When tasks are created and have types that are configured with `blocksUnderwriting: true`, then an underwriting flag will be created on the task's reference entities of type <ApiLink name="QuoteResponse">Quote</ApiLink> or <ApiLink name="PolicyTransactionResponse">Policy Transaction</ApiLink>. Likewise, if a quote or policy transaction is later added to the task, a flag will be created. Flags created this way are always of type `block`.

Underwriting flags have an optional `taskLocator` property to track this association. When there is a link between a task and an underwriting flag, completing or cancelling the task will clear the flag (but not vice versa: clearing a flag manually doesn't complete the task.)

You can update tasks to add underwriting flags that already exist. These too will clear when the tasks are completed or cancelled.

Task Diaries [#task-diaries]

Like other entities, Tasks are able to have associated [Diaries](/features/work-management/diaries).

See Also [#see-also]

* [Work Management API](/api/work-management)


## API Reference

TaskTypeRef
Properties:
  defaultDeadlineDays (number, required)
  blocksUnderwriting (boolean, required)
  numberingPlan (string)
  numberingString (string)