# Borrower Tasks OLD Detailed

## Overview

One of the foundational concepts in the Borrower Hub is *Borrower Tasks,* or tasks, for short.&#x20;

{% hint style="info" %}
It is important to understand the capabilities of tasks to realize the virtually unlimited combination of flows and behaviors that you can implement for almost any situation.
{% endhint %}

Tasks drive the borrower progress towards submitting the application, and beyond that, they help collect additional information in follow-up tasks.&#x20;

Tasks can contain conditional logic for managing the flow and run simple or complex completion actions within our system or interact with external systems.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FOnM5QJx97Dj8Wvqaw6kS%2FTasks.png?alt=media\&token=e1d903f1-1718-4a1e-965c-bf960dc1d277)

The content, order and behavior of tasks are completely customizable via our configuration [blueprints](https://docs.himaxwell.com/admins-and-tech-support/enterprise-level-admin-management/blueprints#what-is-a-blueprint). If a Maxwell client has more than 1 site, each site can have its own flow by applying a separate blueprint. This allows clients to make fast changes and adjustment to their flow through configuration only.

## Task Types

There are two types of tasks based on how much control the client has over configuring their content:

#### General Tasks

These are the majority of tasks that we create. The content and logic of the questions (fields) of these tasks is completely customizable to our client's needs via blueprints. Each task can contain any combination of fields, logic, and and may contain multiple consecutive screens screens of questions within the same task (Panels).

![General Task](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FLGKTbE6IY899ttKdbYis%2FGeneral%20tasks.png?alt=media\&token=ddec5065-012b-468b-8c9e-18e010f6e976)

#### Special Tasks

Some tasks have specialized behavior, and the questions and experience inside of them are not as customizable, with the exception of the text of labels, buttons, and descriptions. Examples of such tasks are Credit Report, Assets with VOA integration, Employers with VOE integration, etc.

![Special VOA Task](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FKQx1PxQEkrUtRtfe3isF%2FSpecial_tasks.png?alt=media\&token=58878438-39c6-47b3-8e54-40044e8bd430)

## The Structure Of A General Task

![A task consist of Panels, Groups and Fields (questions)](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsUaMSIPzrrSh3ouvM%2Fimage.png?alt=media\&token=0eca40a0-336c-4188-b07c-b30f19e96da7)

The content of each general task is completely defined and customizable via a blueprint. A task consists of one or more Panels, which contain one or more Groups, which contain one or more Fields.

{% hint style="info" %}
During our onboarding process we work with each client individually to configure the most optimal flow based on their vision, requirements and legal constraints.
{% endhint %}

![An example of a task panel with all possible labels and tooltips](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FuhbjqBCpNX0Nm5Sytndm%2FTask_panel.png?alt=media\&token=0547f1fb-a3e1-4131-b6ba-e4082d3633a0)

### Panels

Each task has one or more panels. A panel is a container containing one or more groups of input fields. Only one panel is visible to the borrower at a time. If a task has more than one panel, then the borrower can navigate between the panels using the *Previous* and *Continue* buttons at the bottom of the panel.&#x20;

![Only one panel is be visible at a time](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsUmUszXNzDxadXxNh%2Fimage.png?alt=media\&token=cd42c129-351d-4287-a8e0-bf824b24d10f)

A Borrower can continue to the next panel, only if all the required fields in the visible panel are filled out and validated.&#x20;

The label of the *Continue* button changes to *Complete* on the last panel, or if the task has only one panel. This signifies that the borrower is about to complete the current task. Of course, the button labels are customizable per task and per panel - for example if a task submits the application we can configure the button label to say "*Submit Application*".

Each panel can have optional title and description. Each of them can have an optional tooltip button that can provide extra information.

### Start Panel

Optionally, each task can have a start panel with custom content to introduce the borrower to the task they are starting.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FIB5GNwvhFslv4XeeBUxN%2FStart_panel.png?alt=media\&token=5ed936bc-e3ab-4139-b94a-dfdefb71dd7d)

### Groups

Each panel contains one or more groups of input fields. Most of the time the groups are invisible to the borrower. However, each group can have an optional title and description and tooltips to help the user where needed.

Groups allow us to better combine fields in logical sets. They also allow showing and hiding a set of questions based on logic.&#x20;

![Titles and descriptions are optional](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-Mfs_ISH5hnDqwbqnVkt%2Fimage.png?alt=media\&token=2880073c-4fe6-46d3-b99e-0e4d42c6fa9a)

### Fields

Input fields, or fields, are the atomic part of information intake or information display (instructions or educational).&#x20;

Most of the fields require some sort of input form the borrower, usually in the form of a question. Other fields can be used for feedback or informational purposes by showing any custom copy or visuals, including embedding video from a third party provider, such as YouTube.

Some examples of field types are:

* text
* currency
* choice buttons
* select dropdown
* content (to make a point or explain something)
* arrays - a complex list of similar items that a borrower can have 0 or more of (e.g. list of employers, assets, dependents, etc)
* address with autocomplete
* and many more

For usability, we configure our blueprints to render one field per row, so that the borrowers can easily navigate the page top-to-bottom. In certain cases it is permissible to have 2 or 3 fields next to each other if it makes sense, such as city, state and zip code.

The order and placement of fields is entirely customizable via blueprints. In addition, each field must have a label, e.g. *Are you married?*. If an explanation is needed, a second row can be added for explanation, and also the label and explanation can have tooltips.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-Mft0BRYNNY9A2FI9cnP%2F-Mft3z9P2jzq4SKqBVjc%2Fimage.png?alt=media\&token=f3d92f38-8ff0-4fec-9234-a0738935873b)

Input validation is important. In the blueprints we can set which fields are required and which are not. Some fields come with default validation, such as format for SSN, and phone numbers, but other inputs may require more advanced validation. Via blueprints we can write expressions per field that can run a more complex validation including using the values from other inputs.

## Task States

Depending on where the borrower is in the application process, their tasks can be in one of a number of states. The logic that determines when a task should move from one state to another is completely customizable via the blueprints.

### Open State

When a task is in the open state, the borrower can start working on it, i.e. the fields are available to be filled out.&#x20;

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsddD_4uAnHU7xxn6e%2Fimage.png?alt=media&#x26;token=7e76c95b-4fea-4da6-850d-4af2fe49d9ce" alt=""></div>

When a task's state was changed from locked or hidden to open, a "*new"* badge will be displayed next to the task title until the borrower opens that task for the first time.

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-Mfshjp6kq51Cg7MFFQd%2Fimage.png?alt=media&#x26;token=6c6d505d-a225-4707-9d81-dee89f135018" alt=""></div>

### Completed State

When a task is completed, it is marked as such. The borrower can go back to this task at any time if they feel like they need to change certain information. Some special tasks, such as *Invite Co-Borrower* may not allow changing data, but every general task can be edited.

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsdrD1VIO8hUM373mq%2Fimage.png?alt=media&#x26;token=7effbe8d-749d-4c27-8048-61eeca8ba858" alt=""></div>

### Locked State

Sometimes we do not want the borrower to start working on a task until they complete one or more previous tasks, or if certain conditions are met. In this case a task's initial state can be set to be locked.&#x20;

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsdupfLw3YtV6aVi9S%2Fimage.png?alt=media&#x26;token=ee180b18-f94f-4524-b646-beb0b6be5fd3" alt=""></div>

If the borrower views it, they will not be able to see its content. Instead, they will see a message saying that the task is not yet available.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FIIuumtSRAjdhar7qk9Y9%2FTask_locked.png?alt=media\&token=c7da6045-3bb2-429a-843f-1a4fd7bb59d4)

### Locked - Requires Authentication State

A task can be configured to initially be in the locked state and in order to unlock it, the borrower needs to create an account.&#x20;

This behavior is useful if a client wants to allow anonymous users to start the application process but require them to sign up at a specific point during the process.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2F8A8H0a6bPLKSJVnO3i0w%2FLocked_requires_authentication_state.png?alt=media\&token=904b6e6b-9cb3-4952-86b3-653e1cc4aeb0)

### Hidden State

In certain cases we may want to have tasks that are not initially displayed in the task list because they may or may not become available at a later point depending on whether a certain condition is met. This is useful if the flow contains logic that branches. Depending on the path that a borrower has chosen, we can move one set of tasks or another from a hidden to locked or open state.

For example, at the beginning we may ask if the loan purpose is for *Purchase* or *Construction*. Since those choices will require us to collect different type of information, we may choose to have the set of tasks associated with each choice to be initially hidden. Once the borrower makes their choice, we can make only the relevant tasks visible (as open or locked) in the task list.

Another valid reason to hide tasks is to keep the borrower focused on the tasks that are coming up soon without overwhelming them with a long list of tasks.

### Frozen State

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfswNl5ubpYVIkxS8wf%2Fimage.png?alt=media&#x26;token=3fd5bdf0-a2b7-44c4-9e55-1da3bc3630bd" alt="A completed task when frozen appears as Completed &#x26; Locked"></div>

<div align="center"><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsdupfLw3YtV6aVi9S%2Fimage.png?alt=media&#x26;token=ee180b18-f94f-4524-b646-beb0b6be5fd3" alt="A locked or open task when frozen appears as Locked"></div>

Generally completed tasks can be viewed by the borrower at a later point and they can change the information. However, in certain cases, such as after submitting the application, we may not want the borrower to edit those tasks any more. For that reason, in the blueprint we can configure any task to become frozen after a certain event happens (e.g. the borrower completes the *Submit Application* task).&#x20;

When a task becomes frozen, the borrower will still see it in the list of tasks, and will be able to view it in read-only mode, but will not be able to change any of the data. The LO will also not be able to edit the task information in the Lender Hub, however they may be able to edit the information in the Lender Hub application tab (see Application Freezing below for how to disable editing information for the LO).

## Application Freezing

As described in the *Task States* section, tasks can be frozen after an event occurs, and the Borrower/LO cannot edit those tasks. However, the LO can still edit application data via the Lender Hub application tab. In certain cases, our clients do not want the LO to be able to edit application data in the application tab once an event has occurred. To address this scenario, we can freeze the entire application.

A simple way to freeze an application is by using a Complete Action on a task - once a borrower or LO completes a task, such as "*Submit Application"* we can freeze the application.

We often want to freeze most tasks for the borrower when the application is frozen for the Loan Officer. Tasks have a blueprint setting "Freeze Task when Application is Frozen" that will automatically freeze the task when the application is frozen. This behavior is the same as freezing the task directly as discussed in the *Task States* section.

We can also handle more complex cases, such as freezing the application within a custom Saga, after the application is pushed to an LOS, or if an external event happens, such an external system calls a webhook.

When an application is frozen, the LO or Processor:

* :x:cannot edit application data in the Application Tab; they can just see it in read-only mode
* :white\_check\_mark:can still create follow-up borrower tasks to request additional information and documents
* :white\_check\_mark:can still push documents to the LOS
* :white\_check\_mark:can still run Credit Check and other Services

When an application is frozen, the Borrower:

* :x:cannot edit the application data in tasks marked "Freeze Task when Application is Frozen"
* :white\_check\_mark:can still edit application data in tasks that are not marked "Freeze Task when Application is Frozen"

![A frozen application in the Lender Hub Application Tab in read-only mode](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2F6O2xPdgWPQsvApa8CLvT%2FFrozen_application_LP.png?alt=media\&token=3892c870-dd01-4a9a-a28c-6222851cd46c)

## Task Grouping

Depending on the complexity of the flow, we can separate the tasks in the task list into a few groups.&#x20;

Generally, we start with a blueprint containing 2 groups: *Application* and *Follow-ups.* Initially the borrower sees only the *Application* group. The *Follow-ups* group is not visible, since all of its tasks are initially in the hidden state.&#x20;

Once one or more tasks in a group change their state to open, locked or completed, the group becomes visible.&#x20;

<div><figure><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2FfykBivHTErc0SGXavTTG%2FApplication_tasks.png?alt=media&#x26;token=64322d97-b8ac-40aa-911e-a27871ddf570" alt=""><figcaption></figcaption></figure> <figure><img src="https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2Fs72kRs2H4CZK2ZcnQYNI%2FFollow_ups_tasks.png?alt=media&#x26;token=8a45e8cd-ba3c-47ac-8c1a-2cbc643cb140" alt=""><figcaption></figcaption></figure></div>

When the borrower returns the application, the first open task will be displayed automatically. Only the group containing this task will be expanded. The user can manually expand all visible groups at any point.

If all the tasks in a group are completed or frozen, the group will be automatically collapsed and will have a checkmark next to it. The borrower will be able to manually expand it at any point.&#x20;

Organizing tasks into one, two, or more groups is entirely customizable via blueprints.&#x20;

## Task Logic

Task logic can determine the visibility of:

* tasks
* panels
* groups of fields
* fields

By default all of the above items are visible, but they can be configured via the blueprint to be hidden and show when certain conditions are met. We determine the conditions by writing logical expressions using a proprietary expression language called *HippoLogic* that we have developed.

This is a powerful tool that allows virtually unlimited possibilities for creating smart flows. In addition, since everything is blueprint driven, our clients can make multiple tweaks and adjustments to the logic of their flow with quick turn around times.

With *HippoLogic* we can express simple conditions such as to show an item if a field has a certain value, or complex conditions, such as to show an item if there is a gap of employment larger than *x* amount of months.

Some examples:

* **Show a new task** to request proof of contract if the borrower answered *Yes* to the question "Have you signed a contract" anywhere in the flow before that.
* **Change the state of a task** from locked to open, only after another task or tasks have been successfully completed.
* **Show sets of follow-up tasks** depending on whether the application dat&#x61;*.*
* **Show an additional panel** with a request for explanation (fields) **if the sum of the borrower's assets** is lower than a certain amount.
* **Show an additional group of fields** for a mailing address on the same panel, if the borrower answered in the previous group that their mailing address is different than their home address.
* **Show a field** asking for the period of military service if the borrower has indicated previously they are a veteran.

![Conditionally display the Purchase or Refinance group of fields](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsmDvMnu0FWsrbv8th%2Fimage.png?alt=media\&token=e6492f7a-4110-493d-90cc-6c31cb986a15)

![Conditionally display a follow up question based on length of residence](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsmZ1Qq0Bs5DyIYbes%2Fimage.png?alt=media\&token=1cd1676c-30c7-4a31-8a3b-b3351345acee)

## Completion Actions

Task logic is useful in determining when an item should become visible but there are cases when even more complex behavior is needed. That's where we use completion actions.

Completion actions are configured via the blueprints, and can be quickly modified. Each task can have one or more actions that are triggered upon its completion.

Completion actions can be simple or complex. A simple action can open another task when the current task is completed. A complex action can trigger [Sagas](https://docs.himaxwell.com/admins-and-tech-support/enterprise-level-admin-management/sagas#what-is-a-saga) that can run any custom code written in our Domain Specific Language (i.e. DSL, a low-code concept).&#x20;

The Saga that a completion action runs may contain any custom logic that can take any number of conditions into consideration based on the application and borrower data. Sagas can change the internal state of the application, or interface with external systems and integrations.

With completion actions we can create any custom behavior upon task completion. Here are a few examples:

* Send email and/or SMS notifications to borrowers and LOs
* Generate brand new tasks, or change their states
* Run any number of integrations, such as, but not limited to:
  * run credit check,&#x20;
  * automatically push data to LOS
  * create disclosure packages
  * freeze an application

## Co-Borrower Tasks

When a co-borrower is added to an application, they will get their own set of tasks to complete. Depending on each client's requirements, within the blueprint we can pick and choose which tasks should be individual per borrower, and which should be common to the application:

* **Individual Tasks** - these tasks can be individually completed by each borrower, because a separate task is created for each one of them. For example, each borrower will have to individually complete their own *Your Assets* task since it asks for borrower-specific information.\
  &#x20;
* **Common Tasks** - one task is created per application, and not assigned to a specific borrower. Each one of the borrowers can complete the common task. For example, there will only be only one *Loan & Property* task which can be completed by either borrower, since all applicants are applying for the same loan.

Based on certain conditions, our system can allow the main borrower to fill out their co-borrowers tasks, which is useful if the two parties are a married couple.

In other cases, both the main borrower and the co-borrowers will have to individually complete their own  tasks, if they have decided to keep their information separate. Only common tasks (e.g. *Loan & Property*) will be available for both parties.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNeX8nmtEPnFygumL_k%2F-MfsJkCKUMzBGrhej4n_%2F-MfsglroloiM_kvrtF94%2Fimage.png?alt=media\&token=58df06bd-4907-40b3-89e4-fb651e8e571b)

## Borrower Tasks in the Lender Hub

Our Lender Hub has a section in the Application view called *Borrower Tasks.* It shows the same view of the task list and the state of each task as the borrower sees it in the Borrower Hub.

![](https://2622734615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNeX8nmtEPnFygumL_k%2Fuploads%2F5OdVDtXqEdQjJlMaSDCT%2FBorrower_tasks.png?alt=media\&token=b77bc59c-3960-4693-9ab5-0e088eb84399)

Having the option to see things from the borrower's perspective, allows the LO to better guide a borrower who is on the phone with them. This also allows the LO to see details of where a borrower is in the application completion process, and even complete tasks on the borrower's behalf.

The *Borrower Tasks* section also allows the LO or a Processor to manually add custom follow-up tasks for the borrower, as needed. We can configure a preset list of tasks depending on each client's specific process requirements to keep things streamlined for the LOs.&#x20;
