Borrower Tasks
Overview
One of the foundational concepts in the Borrower Hub is Borrower Tasks, or tasks, for short.
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.
Tasks drive the borrower progress towards submitting the application, and beyond that, they help collect additional information in follow-up tasks.
Tasks can contain conditional logic for managing the flow and run simple or complex completion actions within our system or interact with external systems.
The content, order and behavior of tasks are completely customizable via our configuration blueprints. 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).
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.
The Structure Of A General Task
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.
During our onboarding process we work with each client individually to configure the most optimal flow based on their vision, requirements and legal constraints.
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.
A Borrower can continue to the next panel, only if all the required fields in the visible panel are filled out and validated.
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.
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.
Fields
Input fields, or fields, are the atomic part of information intake or information display (instructions or educational).
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.
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.
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.
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.
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.
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.
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.
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.
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
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).
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:
❌cannot edit application data in the Application Tab; they can just see it in read-only mode
✅can still create follow-up borrower tasks to request additional information and documents
✅can still push documents to the LOS
✅can still run Credit Check and other Services
When an application is frozen, the Borrower:
❌cannot edit the application data in tasks marked "Freeze Task when Application is Frozen"
✅can still edit application data in tasks that are not marked "Freeze Task when Application is Frozen"
Task Grouping
Depending on the complexity of the flow, we can separate the tasks in the task list into a few groups.
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.
Once one or more tasks in a group change their state to open, locked or completed, the group becomes visible.
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.
Organizing tasks into one, two, or more groups is entirely customizable via blueprints.
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 data.
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.
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 that can run any custom code written in our Domain Specific Language (i.e. DSL, a low-code concept).
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,
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.
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.
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.
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.
Last updated
