About Task-Based Workflows
Task-based workflows provide a way for loan team members in Encompass (web version) to more effectively manage and automate tasks across the entire loan lifecycle and adopt an exception-based workflow. A workflow task is different from the milestone task that exists in Encompass. Workflow tasks provide a much more robust framework for managing tasks. You can configure tasks and assign them to roles that work on the loan. As the roles get assigned to a user or user group as part of your typical loan workflow, the assignee in the workflow task is set automatically.
More About Task-Based Workflows
For a full introduction to task-based workflows, see the Encompass (web version): Working with Task-Based Workflows guide. The following videos are also available:
Workflow Task APIs
The Encompass Workflow Task Service provides a generalized framework for managing work within an external business process. The Task Service provides the core concept of the Task, which represents an assignable unit of work in a workflow, as well as the APIs for creating, assigning, and completing workflow tasks.
Additionally, the service provides for commonly used extensions to Tasks, including the notion of Subtasks and Task Groups.
Workflow Task API Sets
Encompass Developer Connect provides the following sets of APIs to create and manage tasks and task instances:
-
Workflow Task Configuration APIs provide methods and endpoints to configure Task Templates and Task Settings. The Workflow Task Configuration APIs are:
- Task Template APIs provide methods to configure Task Group, Task, and Sub-Task Templates. Administrators can create, update, retrieve, and delete these templates.
- Task Settings APIs provide methods to configure global level settings for Tasks and Sub-Tasks.
-
Workflow Task Instance Management APIs provide methods and endpoints to create and manage workflow task instances. The Workflow Task Instance Management APIs are:
-
Task Group APIs provide methods to create, update, delete and retrieve Task Groups, add and view Task Group Comments.
-
Task APIs provide methods to create, update, delete and retrieve Task Groups Tasks, add and view Task Comments.
-
Sub-Task APIs provide methods to create, update, delete and retrieve Task Groups SubTasks, add and view Sub-Task Comments.
-
Task Pipeline API retrieves workflow tasks assigned to a user or assigned to the user's User Group(s).
-
Task-Related Entities
The Task object is the primary resource of the Task Service and provides attributes for tracking the state for a single unit of work, including the entity to which the work is assigned and the completion status of that work. The Task may optionally contain 1 or more SubTasks, each of which tracks work that needs to be performed as part of the completion of the parent Task object. Subtasks, however, are not separately assignable: they are implicitly assigned to the same assignee as the parent Task object.
A TaskGroup represents a collection of related Tasks, however the nature of the relationship is not defined by the Task Service. The TaskGroup also maintains a completion status, which may or may not represent the roll-up of the completion status of all tasks assigned to the group. Like SubTasks,
TaskGroups are not assignable.
Common Functionality for All Task APIs
POST
The location header will contain GET route beginning with version information. For example, Location - v1/workflow/tasks/61d0886e-cdf8-4eb9-a060-5a1823df268c
If a query parameter view=entity is passed, the response body will be the entire updated data contract of the posted resource. It should match the body of a GET call.
PUT and PATCH
If a query parameter view=entity is passed, the response body will be the entire updated data contract of the posted resource. It should match the body of a GET call.
To validate PUT and PATCH requests, the instanceID of the user requesting these operations should correlate to with the instanceID of the entity. If the instance IDs do not correlate, an HTTP-403 Forbidden error will be returned.
DELETE and RETRIEVE (all query parameters)
To validate DELETE and RETRIEVE requests, the instanceID of the user requesting these operations should correlate to with the instanceID of the entity. If the instance IDs do not correlate, an HTTP-403 Forbidden error will be returned.
If there are any child entities under the entity to be deleted, the delete operation will fail with an HTTP-409 Conflict error. However, passing force=true with the delete call will delete the parent entity and all child entities.
Use of EntityType URNs
In several of the API contracts, URNs are used to represent entity types that exist outside of the Task Service domain, such as Loan, User, Trade, Condition, etc. These URNs may be generated by ICE Mortgage Technology (for Encompass-defined objects) or by an external system to represent an object type that's outside the Lending Platform namespace.
For example, the Encompass User entity type is represented by an URN of the format, urn:elli:encompass:user. Similarly, an Encompass Role will have the URN, urn:ell:encompass:role.
EntityType URNs ensure that the Task system can support assignment or association to external objects in an abstracted manner. For example, a Task could be assigned to an Encompass User:
{ "entityType": "urn:elli:encompass:user", "entityId": "jsmith" }
Or, to an externally-defined queue:
{ "entityType": "urn:abc_lender:task:queue", "entityId": "my_task_queue" }
When URNs are used, they are generally opaque to the service, meaning the service will not attempt to parse or interpret the meaning of the URN or its constituent parts. Thus, any lender-defined URN is appropriate for any TypeURN-valued attribute in the system.
There are cases, however, when the Service can leverage these URNs, such as to control access to Tasks, TaskGroups, etc. When the "assignee" of a Task has the well-known URN for an Encompass User (urn:elli:encompass:user), the system can grant or deny access to the resource based on the identity present on the request. Thus, when a user makes a request to retrieve or modify tasks, that user must either be the designated assignee or must have an elevated privileged (e.g. an Administrator persona) to perform the specified action.
Required and Autocomplete
All of the Task Service objects include a boolean attribute named required, which indicates whether the Task Service should enforce a rule that indicates that the object's parent (Task or TaskGroup) cannot be marked as complete until all required children are completed. This provides a degree of assurance that lower-level work cannot be bypassed before marking a higher-level work items as done.
Conversely, the Task and TaskGroup objects both have a boolean attribute named autocomplete. This attribute, when true, indicates that the Task or TaskGroup should automatically be marked complete when all required children are complete.
Custom Attributes
All resource types provided by the Service provide for customAttributes a set of user-defined name/value pairs that can be assigned to the resource instance. Custom Attributes are considered opaque to the Task Service and will not be validated except to ensure they have a valid JSON format. These attributes are not indexed and cannot be used for search/filtering; they simply provide for additional state to be stored on the instance for custom extensions to the object model.
Tags
All resource types provided by the Service allow for a set of tags: an array of user-defined string values that are associated to the instance of the object.
As with customAttributes, tags are opaque to the Service and no validation will be required beyond ensuring that each tag is non-empty. However, unlike customAttributes, tags will be indexes and can be used to efficiently filter a set of resources to find all items with a given tag (or tags).
Associations
As previously mentioned, associations are another method for extending the Task Service object model. An association is a 3-tuple combining the following elements:
- entityType, which is a Type URN as described earlier in this document
- entityId, which is a unique ID for the entity with which the Task Service object has a relationship
- relationship, which is user-defined string describing the relationship between the Task Service object and the associated object. For example, the following association object could be used to represent the relationship between a Task and an UnderwritingCondition within a Loan:
{
"entityType": "urn:elli:encompass:loan:underwritingcondition",
"entityId": "{12345678-abcd-...}",
"relationship": "appliesTo"
}
The associations of an object in the Task Service are opaque to the service and the service will provide no validation of the association other than to require that the entityType have a URN format and that all attributes are non-empty. Associations can then be used by the consuming application to present additional context in the user interface or for automated processes that may be interacting with the Task.
Authorizations
Authorizations can be used to authorize who can use the task group/task template to add a task group/task instance to the loan. An authorization is a 3-tuple combining the following elements:
- entityType, which is a Type URN of the role or group
- entityId, which is a unique ID for the role or group
- relationship, which is authorization type. For example, the following authorization object could be used to represent the role who can use the task group/task template to add a task group/task instance to the loan
{
"entityType": "urn:elli:encompass:role",
"entityId": "{12345678-abcd-...}",
"relationship": "CAN_CREATE"
}
Required Fields
Name and Type are minimal required fields to create task service object.
© ICE Mortgage Technology, Inc. All rights reserved.