# Workplans



Workplans are templates that automatically create [tasks](/features/work-management/tasks), assign tasks, and create [associations](/features/work-management/user-associations) in response to system [events](/configuration/general-topics/events) such as policy creation and quote validation.

When an event specified within the `workplanTriggers` <ApiLink name="ProductRef">configuration</ApiLink> object is triggered, the system will attempt to create the task specified in the workplan and [auto-assign](/features/work-management/workgroups#AutoAssign) the task, or create an association between a user and the entity specified in the workplan. See the [Workgroups](/features/work-management/workgroups) feature guide for more information.

Two [plugins](/configuration/plugins/overview) can be implemented to customize workplan functionality, which are executed in the following order: The [Workplan Selection Plugin](#WorkplanSelectionPlugin), then the [Workplan Execution Plugin](#WorkplanExecutionPlugin). The Workplan Selection Plugin specifies which workplans will be executed when an event is triggered. The Workplan Execution Plugin modifies the tasks and associations contained within each workplan returned by the Workplan Selection Plugin.

Configuration [#configuration]

The `workplanTriggers` configuration object specifies which workplans will be executed when an event occurs. Workplans are identified by the value specified in their `name` field.

For example:

```json
{
	"workplanTriggers": {
		"policy.quote.create": ["exampleWorkplan"],
		"policy.quote.issue": ["anotherWorkplan", "oneMoreWorkplan"]
	}
}
```

A comprehensive list of events can be found [here](/configuration/general-topics/event-definitions).

Once this configuration has been deployed, the system will begin executing the above workplans in response to the specified events.

Create a Workplan [#create-a-workplan]

The <ApiLink name="createWorkplan">Create Workplan</ApiLink> API endpoint can be used to create a workplan.

For example:

```json
{
	"name": "exampleWorkplan",
	"defaultGroup": "exampleWorkgroup",
	"items": [
		{
			"task": {
				"description": "Example task",
				"type": "underwritingReferral"
			},
			"referenceType": "quote",
			"referenceLocator": "01LAV31DAC8F"
		}
	]
}
```

When the workplan in the above example is executed in response to the event defined in the `workplanTriggers` configuration object, the auto-assign algorithm will attempt to create the specified `task` and assign it to a user in the specified workgroup who has an [association](/features/work-management/user-associations) with the specified quote.

See the [Workgroups](/features/work-management/workgroups) feature guide for more information on the auto-assign algorithm.

Workgroups specified in the request must be created manually using the <ApiLink name="createWorkgroup">Create Workgroup</ApiLink> API endpoint before the workplan is executed. Otherwise, workplan execution will fail.

The <ApiLink name="listWorkplans">List Workplans</ApiLink> and <ApiLink name="getWorkplan">Get Workplan</ApiLink> API endpoints can be used to retrieve workplan details. See the [Work Management API](/api/work-management) index for additional workplan API endpoints.

Plugins [#plugins]

<span id="WorkplanSelectionPlugin" />

Workplan Selection Plugin [#workplan-selection-plugin]

The Workplan Selection Plugin specifies which workplans will be executed when an event is triggered.

The request object contains an event and its associated workplans as specified in the `workplanTriggers` configuration object. The response object contains a list of workplans that will be executed in response to the event specified in the request object. Workplans can be added or removed as needed from the list of workplans returned by the response object.

If this plugin is not implemented, the system will execute workplans based on the `workplanTriggers` configuration object.

The following implementation example filters workplans specified in the `workplanTriggers` configuration object based on workplan `name`:

```java
public class WorkplanSelectionPluginImpl implements WorkplanSelectionPlugin {
    private static final Logger log = LoggerFactory.getLogger(WorkplanSelectionPluginImpl.class);

    @Override
    public WorkplanSelectionResponse selectWorkplans(WorkplanSelectionRequest workplanSelectionRequest) {
        if (workplanSelectionRequest.workplansSelection().eventType().equals("policy.quote.create")) {
            List<WorkplanSelectionItem> filteredWorkplans = workplanSelectionRequest.workplansSelection().workplans().stream()
                    .filter(workplan -> workplan.name().startsWith("quote"))
                    .collect(Collectors.toList());

            return WorkplanSelectionResponse.builder()
                    .workplansToExecute(filteredWorkplans)
                    .build();
        } else {
            return WorkplanSelectionResponse.builder()
                    .workplansToExecute(workplanSelectionRequest.workplansSelection().workplans())
                    .build();
        }
    }
}
```

<span id="WorkplanExecutionPlugin" />

Workplan Execution Plugin [#workplan-execution-plugin]

The WorkplanExecutionPlugin modifies the tasks and associations contained within each workplan returned by the WorkplanSelectionPlugin.

The request object contains a workplan and the tasks and associations contained within the workplan. The response object contains a list of tasks and a list of associations that will be created when the workplan is executed. Tasks and associations can be added or removed as needed from the lists returned by the response object.

If this plugin is not implemented, the system will create the pre-defined tasks and associations for a given workplan when the workplan is executed.

The following implementation example modifies tasks based on workplan `name`:

```java
public class WorkplanExecutionPluginImpl implements WorkplanExecutionPlugin {
    private static final Logger log = LoggerFactory.getLogger(WorkplanExecutionPluginImpl.class);

    @Override
    public WorkplanExecutionResponse decorateWorkplanExecution(WorkplanExecutionRequest workplanExecutionRequest) {
        List<TaskCreateRequest> modifiedTasks = new ArrayList<>(workplanExecutionRequest.execution().tasks());
        List<UserAssociationCreateRequest> associations = new ArrayList<>(workplanExecutionRequest.execution().associations());

        if (workplanExecutionRequest.execution().workplanName().equals("underwritingReview")) {
            modifiedTasks.remove(0);
        }

        return WorkplanExecutionResponse.builder()
                .tasks(modifiedTasks)
                .associations(associations)
                .build();
    }
}
```

See Also [#see-also]

* [Workgroups](/features/work-management/workgroups)
* [Tasks](/features/work-management/tasks)
* [User Associations](/features/work-management/user-associations)
* [Auto-Assign](/features/work-management/workgroups#AutoAssign)
* [Events](/configuration/general-topics/events)
* [Event Definitions](/configuration/general-topics/event-definitions)
* [Work Management API](/api/work-management)
* [Plugins](/configuration/plugins/overview)