Building the Delivery Room UI

Overview

This chapter describes how to build the Delivery Room UI that point of sale recipients will use to view, provide electronic consent, electronically sign, and complete eClose packages. It also describes how to create and end a Delivery Room session.
The Delivery Room UI
The user interface components that make up the Delivery Room are as follows:

Landing Page
Consent Agreement
Pending Tab
Complete Tab
Preview Package
Review Documents Screen
eSign Room (the Signing Room)

📘
The examples shown in this section depict the default Delivery Room screens without customization. Theme and UI customization is defined in the UICustomization object and passed by the ICE Mortgage Technology Framework when the Delivery Room is created.

Landing Page

The Landing page provides cards representing tasks to be completed by the point of sale recipient. The tasks are categorized into Pending or Complete states accessible by tabs. The cards provide a button to execute the task (eSign, Review, etc.) which sends the user to another screen.

1010 — Default Landing Page - Tasks Screen

Consent Agreement

Before recipients can start a task, they must review and accept the electronic consent agreement. If the recipient has not yet provided consent to receive documents electronically, they will be prompted to accept eConsent when launching a task. The recipient may also change their consent decision by clicking the Change eConsent button.
Notes:

The Accept and Decline eConsent buttons are not customizable but do follow the theme.
The eConsent agreement is provided by ICE Mortgage Technology and is not configurable.
eConsent Agreement

Pending Tab

Tasks the recipient has not yet completed will be displayed on the Pending tab of the Tasks screen.

Complete Tab

Tasks the recipient, lender, or system has already completed will be presented on the Complete tab of the Tasks screen. A task is considered completed by the system if the lender voids it or the Task expires.

No Tasks Screen

When there are no pending or completed tasks, an informational icon will be displayed on the screen with explanatory text.

Preview Package

Packages that contain electronic signature requests, also known as eSign packages, may be released to recipients for viewing prior to the eSign date. A banner on the Task screen displays the earliest date the recipient can electronically sign the documents in the package. Recipients can view such packages by clicking the Preview button on the task card. Preview package documents open in the Review Documents screen.

Review Documents Screen

The Review Documents screen is used when the user reviews or previews documents. When a recipient clicks the Review or Preview button on a task card, the documents open in the Review Documents screen. The title on the Review Documents screen will match the title on the source card.

eSign Room (the Signing Room)

The eSign or Signing Room is the area where the recipient applies the necessary electronic signatures.

📘
The eSignature provider that is used in the Signing Room may differ between integrations. The ICE Mortgage Technology platform determines the eSignature provider that will be utilized based on the underlying product requirements.

UI Customization

Delivery Room fonts and color palette are customizable. Partners can alter the UI theme to match the desired brand palette for a more seamless customer experience.

The Delivery Room theme is applied during session creation. This allows for customization down to the user level and avoids issues on new deployments as the theme changes. Theme and UI customization is defined in the uiCustomization object that is passed when a Delivery Room session is created.

Theme

A theme applies a generalized set of stylings across the site.

There are some areas of the UI where theming does not apply as expected. With this initial release, the following areas of the site do not follow the theme:

Tabs underline, used on the Tasks page (planned to address in a future release)
Document Viewer, used in Review Page (planned to address in a future release) Entire viewer including internal icons, focus outlines, etc
Banner icon (planned to address in a future release)
Green check on completed cards (No current plan to support)
Signing Room (No current plan for support)

Fonts

Multiple font names can be provided with comma-separated values.
Default: proxima-nova, Arial, sans-serif. Proxima-nova will be the primary font and Arial and san-serif fonts will be used as fallback fonts if the browser is not supporting proxima-nova font.

Colors

Color themes are provided in named sets that have multiple color codes that apply color for text, buttons, modals, and alerts.
Any set that is omitted will use the default theme colors for that set. However, any set that is provided must include the expected count as shown in the default colors image and theme examples.

neutral is primarily used for borders, texts and some cases for background color. When not using the default color theme, 11 colors must be provided.
brand is used in link text, and buttons. When not using the default color theme, 8 colors must be provided.
success, warning, and danger are used in related text, modals, and message banners. When not using the default color themes, the following number of colors must be provided:
- Success: 2 colors
- Warning: 3 colors
- Danger: 2 colors

Default Colors

Widgets

Widget customization allows some targeted overrides of the general theme.
Titles allow for varying text while buttons also allow overriding fonts and colors.
While most pages and buttons are customizable, there are some that are not customizable at this time. This is straight forward by reviewing the customization schema after reviewing the application screens.

Cards

The card widgets elements (title, button) on the Task page can be customized individually by type (eSign, Review, Completed, Expired). These follow the convention {{type}}-card-{{element}}.

📘
The Preview Card button text is not customizable. If the application detects the task is in preview based on the dates, it will override the button text to Preview.

Screenshots

The following screens will help you identify where widget customization applies.

Header

Tasks

Consent

Review

Opening a Delivery Room

In order to open a Delivery Room, a session needs to be created. Sessions are created by the CreateSession operation in the Create Session . This API passes UI parameters (uiCustomization object) to allow customization on a per call basis.

When attempting to open a Delivery Room, it is possible the package did not get created (failed after the Package CreateEvent) or was cancelled after the Package Create Event was sent. These errors should be handled by removing / hiding the package from your system at this point using the error response.

The Create Session API response will provide the URL to access the Delivery Room UI unless an error occurs; see Error Handling. Place the URL in an iFrame and watch the iFrame source for the URL to change or handle in the page you have provided in the returnUrl parameter when creating the session. You can also redirect to the room if you wish.

❗️
Leaving the Room
Status events are only made available when the recipient clicks the Leave button. For this reason, your integration should encourage the user to exit the Delivery Room using the Leave button, instead of closing the window upon completion. For example, the Delivery Room should not open in another tab, as the user will likely close the window upon completion rather than clicking Leave.
While actual mechanisms are out of scope for this document, here are some examples:
• Redirect to a custom page with only an iFrame
• Dynamically replace the current body
• Use an HTML overlay / modal (do not use a browser modal)
More information about the leaving the Delivery Room is provided in the next section.

Leaving the Room

The returnUrl parameter is required when creating the session and is used by the Leave button to return the user from the Delivery Room to the Partner portal. During the redirect, the user's status is added as query parameters to the URL to be captured, if needed.

Leave Button

The Leave button will execute the redirect to the returnUrl provided with the appropriate state parameters added. It is up to the Partner portal to handle these parameters and these are currently the only provided status updates. If they are missed, they should be provided again the next time through making the updates eventually consistent.

State Parameters

When redirecting to the Partner portal the delivery UI will place a query parameter for the state including package status and each task status if a package was accessed.

Parameter	Description
package.status	Represent the package status across all recipients. Values are: Created, Voided, Replaced, Expired, Completed, Cancelled
[task id].status	Represents the recipient's task status. Values are: Restricted, Incomplete, Completed
error	Platform error code provided for logging and diagnostic purposes.
error_description	Platform error description provided for logging and diagnostic purposes
correlationId	Used to help in diagnostics. Value is a generated unique string.

The reason will be UserRequest and have status when successful; see Error Handling below for more details on other values.

Error Handling

Errors may occur during the session creation or use of the room by the user.

Create Session API

Scenario	Description	Status / Code	Summary	Example Details
Environment Mismatch	Provided Elli-Environment header does not match executing environment.	400 / DPF-1037	The environment provided in the request must match execution environment.	---
Missing Required Authentication Header	Missing Elli-SubscriptionId, Elli-SigningKeyId, or Elli-Signature headers.	401 / DPF-1001	Required field missing	{header name}
Subscription Not Found	Provided subscription does not contain a valid enabled Partner integration id.	401 / DPF-2004	SubscriptionId provided is not authorized for access.	---
Signing Key Not Found	Provided signing key id was not found in the Partner configuration.	401 / DPF-2005	SigningKeyId provided does not exist for subscription.	---
Invalid Authentication	The signing key id passed was not found in the provided integration.	401 / DPF-2002	Invalid authorization.	---
Package Not Found	The package, identified by instanceId, groupNamespace, groupId, and packageId was not found either because it does not exist or has not been released to the recipient.	400 / DPF-1002	A referenced entity does not exist.	Package does not exist for PackageId={packageId}.
Recipient not found	The recipient was not found on the package.	400 / DPF-1002	A referenced entity does not exist.	Recipient does not exist for PackageId={packageId} RecipientId={recipientId}
Invalid Integration	The integration id on recipient does not match the subscription.	403 / DPF-6004	Recipient cannot be accessed by this Partner integration.	Partner recipient not mapped integrationId ={integrationId}
Bad Request Input	The format of the request was invalid. The nested errors array will contain more info.	400 / DPF-1000	The format of the request is invalid in one or more way; see errors for details on each failure.	---
Package Cancelled	The package has been called because it was never or is no longer valid.	409 / DPF-8000	The request could not be completed because the state of an entity cannot be changed now.	Unable to access the package {packageId} because it is cancelled.
Unexpected Error	Something went wrong that has not been explicitly categorized.	500 / DPF-0000	Unexpected exception	Something went wrong...

Room Response

When the user leaves the room UI by pressing the button or an issue occurs the room UI will append the error reason and description as query parameters on your return URL. If somehow your return URL cannot be resolved a simple error page will be displayed.

Example Error Reasons and Descriptions

Reason	Description	Has Status
UserRequest	Recipient clicked the button in the Delivery Room to return to the Partner portal.	X
UserTimeout	Recipients session timed out.	X
SessionNotFound	Session could not be found when Delivery Room tried to open.	-
ExchangeAlreadyFailed	There was an exchange failure and the exchange was attempted again.	-
MultipleExchangeRequests	An exchange was attempted after it already succeeded.	-
ExchangeTimeout	The exchange token returned when starting the session timed out before the exchange attempt.	-
UnexpectedExchangeError	Some error occurred during exchange that was unanticipated.	-
StartAlreadyFailed	There was a start failure and the start was attempted again.	-
MultipleExchangeRequests	A start was attempted after it already succeeded.	-
StartTimeout	The session id returned when exchanging the session timed out before the start attempt.	-
UnexpectedStartError	Some error occurred during start that was unanticipated.	-
Cancelled	The package was cancelled after session was created.	X
{unexpected error}	Improperly handled error. This should be treated as a general Unexpected Error