Download Postman Collection
API Reference

Overview

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.

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, 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 APIs provide methods to create, update, delete and retrieve Tasks, and add/view Task Comments.

    • Sub-Task APIs provide methods to create, update, delete and retrieve Sub-Tasks, and add/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 Sub-Tasks, each of which tracks work that needs to be performed as part of the completion of the parent Task object. Sub-Tasks, however, are not separately assignable: they are implicitly assigned to the same assignee as the parent Task object.

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. 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

Sub-Task objects include a boolean attribute named 'required', which indicates whether the parent task should enforce a rule that indicates that the object's parent Task 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 object has a boolean attribute named 'autocomplete'. This attribute, when true, indicates that the Task 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.

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 template to add a 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 user group
  • entityId, which is a unique ID for the role or user group
  • relationship, which is authorization type. For example, the following authorization object could be used to represent the role who can use the task template to add a 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.

For more details about implementing Workflow Tasks in Encompass, also see the Working with Task-Based Workflows Setup Guide.

© ICE Mortgage Technology, Inc. All rights reserved. Terms of Use