encompass lo connect custom tools implementation guide · 2019-01-29 · encompass lo connect...

Encompass LO Connect Custom Tool Implementation Guide

Encompass LO Connect Custom Tool Implementation Guide 2

Copyright Statement © 2019 Ellie Mae, Inc. Ellie Mae®, Encompass®, AllRegs®, DataTrac®, Ellie Mae Network™, Mavent®, Millennial Tracker™, Mortgage Returns®, Prospect Manager®, Total Quality Loan®, True CRM®, TQL® and the Ellie Mae logo are trademarks of Ellie Mae, Inc. or its subsidiaries. All rights reserved. Other company and product names may be trademarks or copyrights of their respective owners.

Encompass Developer Connect / Encompass LO Connect

Rev. 01/29/2019


Contents Introduction ................................................................................................................................................................................................ 4

Basic Concepts ............................................................................................................................................................................................ 4

The Ellie Mae Scripting Framework ........................................................................................................................................................ 4

Integration Details for Custom Tools ...................................................................................................................................................... 6

Running in a Sandbox.............................................................................................................................................................................. 7

Browser Compatibility ............................................................................................................................................................................ 7

Asynchronous Programming Model ....................................................................................................................................................... 8

Process Overview ...................................................................................................................................................................................... 10

Ellie Mae Scripting Objects for Custom Tools ........................................................................................................................................... 11

Script Object.......................................................................................................................................................................................... 11

Auth Object ........................................................................................................................................................................................... 12

Loan Object ........................................................................................................................................................................................... 14

Authenticating to Developer Connect and Other External Websites....................................................................................................... 18

Enabling Guest Access to Scripting Objects .......................................................................................................................................... 18

Accessing Scripting Objects in a Guest Application .............................................................................................................................. 20

Subscribing to Script Object Events ...................................................................................................................................................... 21

Responding to Events............................................................................................................................................................................ 21

Invoking Developer Connect APIs ......................................................................................................................................................... 23

Performing Single Sign-On (SSO) with External APIs or Applications ................................................................................................... 24


Introduction Ellie Mae's web-based application support advanced customization by allowing third parties (lenders or partners) to inject custom functionality via self-authored HTML, JavaScript and/or CSS. These customizations can then interact with, modify or extend the functions and behaviors of the host application, whether that's one of Ellie Mae's Connect products or even the Encompass SmartClient.

This document describes the basic approach to customization as well as the specific use cases and integration methods that the customization is meant to address.

Basic Concepts The Ellie Mae Scripting Framework

Whenever an Ellie Mae product allows for injection of custom functionality, it does so using an Ellie Mae technology framework known as the Ellie Mae Scripting Framework. The Scripting Framework isolates the third-party's customizations away from the host application (for example, Encompass LO Connect) by loading the custom HTML/JavaScript into a "sandboxed" container (see Running in a Sandbox below). When custom code/UI is loaded in a sandbox, we refer to that as a guest of the application, and the terms host and guest will be used throughout this document.

Besides isolation, the Scripting Framework provides a communication channel for all interactions between the host and its guest(s). To enable communication, each host publishes a set of scripting objects that can be invoked using JavaScript within the guest. These objects provide two core interaction patterns for the guest to consume:

1. Functions. Each scripting object provides a set of functions that can be invoked by the guest to retrieve or modify the state or behavior of the host application. For example, a host may expose a function to retrieve the data of the loan currently being edited by the logged-in user.


Scripting Object Function Example var loan = await elli.script.getObject("loan"); loan.setFields({ "1109": 200000 });

Events. Events allow guests to respond to (and intercede in) actions within the host application. For example, a guest may be interested in knowing any time the user modifies a loan data field in a form.

Scripting Object Event Example elli.script.subscribe("loan", "change", function(loan) { alert('The loan has changed!');

The set of functions and events supported by each scripting object are published as part of the Ellie Mae Scripting Objects for Custom Tools. However, the set of scripting objects exposed to a guest is dependent on the integration context in which the guest is loaded. Different guests will have different sets of functionalities exposed to them to ensure data confidentiality and security. For example, a script created by a Credit Service Provider would have significantly restricted access compared to a script created by the Encompass lender that licenses the Encompass system.

The next section describes the integration type supported by Ellie Mae's Custom Tool suite of product and, describes the scripting objects that are accessible in the context.


Integration Details for Custom Tools

This section below is the integration type details for custom tools.

Security Context Custom code runs with the privileges and access of the user logged into the host application.

Origin Policy Origin Policy: Standard

Description:

• Applies standard "same-origin" security controls to the integration • Used in cases where the integration is served from a domain other than the Application's

domain

Restrictions:

• Cannot directly access host window DOM or JavaScript objects • Cannot modify or override the CSS or styling of the host application • Cannot invoke any web-based API that does not allow calls from the guest's origin (i.e.

domain) via CORS restrictions • Cannot access or use the Session ID or Access Token from the host application (use the Auth

Object to generate an API Access Token for use by your custom code)

Implementation Method • Full web page/application • Hosted, maintained and operated by the lender/partner • Launched on-demand by the user • Presented as a "Tool" within the Encompass Loan Editor UI

Applicable Use Case • Provide a completely custom UI that can interact with the Loan and participate in the Loan

editing flow


• Provide integration to external systems with their own UI using SSO

Running in a Sandbox

The Scripting Framework isolates all custom code written by a lender or partner by loading it within a sandboxed environment that limits its access to the rest of the application. Sandboxing is achieved by the HTML5 iframe tag's sandbox attribute.

When running inside the Scripting Framework sandbox, all guest scripts/applications can do the following:

• Load and execute arbitrary JavaScript code

• Access the window object of the sandbox

• Create form elements, such as <input> tags, and submit forms (note: depending on the context, these elements may not be visible to the user)

• Create pop-ups (e.g. window.open()) and modal dialogs

Browser Compatibility

The Scripting Framework is compatible with all browsers and versions supported by the Encompass web applications, which is made possible by the use of a polyfill. A polyfill is JavaScript library which provides support for modern JavaScript objects (e.g. the Promise object) in legacy web browsers, such as Internet Explorer. The most popular polyfill is provided as part of the Babel open source project, and it is with this polyfill that the Scripting Framework is tested.

In the Getting Started section below, you will learn how to automatically include the Babel Polyfill in your project to provide effortless compatibility, or you can substitute this with a different polyfill library. Note, however, that Ellie Mae cannot ensure compatibility between Scripting Framework and any non-Babel polyfill library.

https://babeljs.io/docs/en/babel-polyfill


Important! When writing custom JavaScript that runs within a Scripting Framework guest, the author is responsible for any browser compatibility issues that may be relevant to their use case. In particular, your JavaScript must conform to the ES5 specification in order to support all browsers under which it may run. In the documentation below, the code examples makes liberal use of ES6 and ES2017 syntax, which are not supported in Internet Explorer.

Asynchronous Programming Model

All interactions your custom code performs using functions or events published by the Scripting Objects are performed asynchronously. The JavaScript asynchronous programming model is based on the notion of a Promise: an object that represents the eventual completion of an asynchronous task or function invocation. All functions exposed by Scripting Objects return a Promise to the caller, which can then be used to register a callback that will be invoked when the function has been completed.

For example, the following code reads the value of a TextBox control from an Custom Input Form by first retrieving a reference to the control (via elli.script.getObject()) and then invoking the TextBox's value() function. Note that both functions are asynchronous and require the use of the Promise.then() function to achieve the desired behavior:

Async Programming using ES5 function displayTextValue() {

// The call to getObject() returns a Promise that, when completed, returns a

// reference to the loanObject which would contain the method you can invoke to get other information

elli.script.getObject("loan").then(function(loanObject) {

The code above is written using ES5 syntax which, although compatible with all supported browsers, can be difficult to write, read and debug. Alternatively, the same logic can be written using ES6/ES2017 syntax is a much more compact and readable way:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise


Async Programming using ES6/ES2017 // Note that the function is prefixed by the "async" keyword

async function displayEntireLoan() {

// Retrieve the loan object by awaiting the result of the getObject() call

let loan = await elli.script.getObject("loan");

// Retrieve the entire encompass loan using another await

let completeLoanObjectFromHost = await loan.all();

console.log('The entire loan object looks like: ' + completeLoanObjectFromHost);

}

By using the "async" and "await" keywords introduced in ES2017, the code is greatly simplified and follows a more conventional flow. However, because ES2017 language features are not supported in Internet Explorer, this code will need to be transpiled to ES5-compatible syntax prior to being uploaded into the Ellie Mae Asset Library. Transpilation is performed using the Elli-CLI tool, which is described in the Getting Started section on the next page. The result of running the tool is a new JavaScript file which can be used with your Custom Input Form and supports legacy browsers.


Process Overview The overall process for implementing a custom tool in Encompass LO Connect involves the following high-level tasks.

<Umang, please review>

Task Description

1 Develop and deploy the custom tool.

The client developer creates the custom tool and publishes the tool’s HTML page. The client developer provides the URL of the custom tool to the Encompass LO Connect administrator.

2 Integrate the custom tool.

Integration includes the following tasks:

• Configuring scripting objects. Enable guest access to scripting objects, set up event subscriptions and configure how your application will respond to events. To learn more, see Ellie Mae Scripting Objects for Custom Tools.

• Authenticating to Developer Connect and other external websites. Obtain an access token for Developer Connect APIs and set up SSO. To learn more, see Authenticating to Developer Connect and Other External Websites.

3 Add the custom tool to Encompass LO Connect via the Admin portal.

The Encompass LO Connect administrator adds the custom tool to Encompass LO Connect. The administrator must have the URL of the custom tool in order to add it successfully. For step-by-step instructions, see the Encompass LO Connect online help.

http://help.elliemae.com/documentation/lo-connect/Content/lo-connect/Welcome.htm


Ellie Mae Scripting Objects for Custom Tools This section provides a reference for the different Scripting Objects exposed to guests running custom tool within Ellie Mae applications.

Unless otherwise noted, each object is a singleton and should be exposed using an Object ID that is the lower-case version of the Object type. For example, the Application object would be exposed with the Object ID of "application".

Objects are accessed in the guest using the elli.script.getObject() function, as in the following example for loan object:

var loan = await elli.script.getObject("loan");

Script Object

The Script object (elli.script) is the root object exposed by the Secure Scripting Framework guest system and is available as a global in the guest application context.

Methods

Method Description

connect()

Invoked by the guest window to connect it to the Scripting Framework and start receiving

events.

getObject("<objectName>") Returns a reference to an object exposed by the application host, e.g. the Loan object.

subscribe("<objectName>",

"<eventName>", <callback>) Registers a callback for an event generated by the specified object. The callback is a

JavaScript function reference.


Availability

The Script object is available in all Scripting Framework contexts.

Auth Object

The Auth object (ObjectID = "auth") provides access to identity and authorization-related functionality.

Methods

Method Description

createAuthCode("<oauthClientID>") Generates a new auth code for the caller which can be exchanged for an Access Token using the Client Secret associated with the given OAuth Client ID. In certain contexts, the auth code is tied to the currently logged in user's identity. Note: this API returns a string containing an auth code (not an access token). The returned auth code must be exchanged for an access token using the steps documented in the Token Exchange document referenced above.

getUser()

Returns an entity providing basic user identity information for the current user. The user identity object has the following schema: {

"id": "<userIDWithoutRealm>",

"realm": "<encompassInstanceIDOrRealmURN>",

"firstName": "<firstName>",

"lastName": "<lastName>"

}


Code Examples:

In your Javascript file, first get the auth object like this:

To start using the methods on auth object, you can directly invoke the methods as follows:

let authObject = await elli.script.getObject(‘auth’);

1. authObject.getUser().then(userData => {

console.log(‘Here is your user data from host: ’, userData);

});

2. authObject.createAuthCode(your_client_id).then(access_token_from_host => {

console.log(‘Access token from Host ‘ + access_token_from_host);

})

Note: your_client_id is currently optional.


Loan Object

The Loan object (ObjectID = “loan”) provides methods for interacting with an open loan in the application's editor screen(s).

Methods

Method Description

all() Returns the entire Loan object in the v3 Loan Object model. calculate()

Pushes any pending changes to the server and executes any calcs/triggers/rules (i.e. all pending changesets are submitted to the Workspace Service's "state" API). This does not cause the loan to be saved.

getField("<fieldId>")

Returns the value of a single field using its field ID.

setFields(<fieldMap>)

Sets the values of one or more fields on the Loan. The <fieldMap> is a JSON object with Field IDs as the object's properties, e.g.

{

"1109": 400000,

"1172": "FHA",

"762": "2018-03-04"

}

merge()

Merges any changes from other user sessions into the loan workspace (via the Workspace Service's sync operation), making changes from other users/processes visible.


isReadOnly() Indicates if the loan is editable or in a read-only state.

Code Examples:

In your Javascript file, first get the loan object like this:

To start using the methods on loan object, you can directly invoke the methods in the follow way:

let loanObject = await elli.script.getObject(‘loan’);


1. loanObject.all().then(responseFromHostWithLoan => {

console.log(‘Here is your loan response from host: ’, responseFromHostWithLoan);

;

2. loanObject.getField(fieldIdYouAreLookingFor).then(fieldValue => { 1. console.log(‘Field’ + fieldIdYouAreLookingFor + ‘has value: ‘ + fieldValue);

})

To get value of field with fieldId 4002, you would do:

loanObject.getField(4002).then(val => {

console.log(‘FieldId 4002 has value: ‘, val);

})

3. loanObject.setFields(fieldIdMap); To set fieldId 4002 to be “Justin”, you would do: let fieldMap = { ‘4002’ : ‘Justin’ }; loanObject.setFields(fieldMap);

4. loanObject.isReadOnly(resp => { console.log(‘Loan is read only: ’, resp) });

5. loanObject.calculate(resp => { console.log(‘Response from Host: ’, resp) });

6. loanObject.merge(resp => { console.log(‘Response from Host: ’, resp) });


Events

Event Description Feedback

change

This event is fired after any action that causes a round trip to the Workspace Service and receiving a modified loan. This includes any changes to trigger fields as well as any calls to the merge() or calculate() methods.

None

Subscribing to change event:

Example:

elli.script.subscribe(‘loan’, ‘change’, functionNameYouWantToCallOnChange);

elli.script.subscribe(‘loan’, ‘change’, loanChanged);

function loanChanged(obj, loanData) {

console.log(‘Change event was fired. Here’s the info: ’, obj, loanData);

}


Authenticating to Developer Connect and Other External Websites Enabling Guest Access to Scripting Objects

Requirements

Ensure that X-Frame-Options is removed from the header of your guest application. Having any kind of X-Frame-Options may

prevent the guest application from being rendered inside the host. Refer to the following link for detailed information:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options.

In order for a guest application to interact with the host, it must load and initialize the Scripting Framework Guest Library: a JavaScript library containing the functions that allow for retrieval of the scripting objects published by the host application. The means by which an integration loads and initializes the library depends on the integration context in which the custom code executes.

However, in cases where the lender or partner is creating a custom page/application hosted on a remote web server, it is the responsibility of the lender or partner to load the Scripting Framework Guest Library into their page before attempting to use it. Loading the Scripting Framework guest library can be done in one of two ways, depending on your development approach and application architecture:

Approach #1: Include as Script Tag The most straightforward approach to including the Scripting Framework Guest Library into your web page/application is to include a <script> tag in your page(s) that references the Scripting Framework Guest Library from Ellie Mae's web servers, for example:

<script src="https://cdn.elliemae.io/elliemae/core/ssf/1.0/elli.ssf.guest-with-polyfill.js"></script>

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options

https://cdn.elliemae.io/elliemae/core/ssf/1.0/elli.ssf.guest-with-polyfill.js

https://cdn.elliemae.io/elliemae/core/ssf/1.0/elli.ssf.guest-with-polyfill.js


This script defines a single, global object, elli.script, which provides all of the entry-point functions in the guest library. The script tag should be included in your page prior to any other scripts that attempt to invoke the elli.script object (preferably in the <head> portion of the page).

Ellie Mae provides two versions of the Scripting Framework Guest Library for you to choose from when adding your script tag:

• The elli.ssf.guest-with-polyfill.js file includes an Internet Explorer-compatible polyfill library that allows use of modern JavaScript features (e.g. Promises) that are not available in legacy web browsers. This should be your default choice unless you are already including a polyfill library (e.g. the Babel Polyfill library) in your page as a separate script tag.

• The elli.ssf.guest.js file includes only the Scripting Framework Guest components and excludes the polyfill library. Use this version of the script only if you are already including a polyfill library in your page. Note that the script tag for your polyfill library must precede the script tag for the Scripting Framework Guest Library.

Approach #2: Include as an NPM Package If you are building your web application using a JavaScript dependency management/bundling tool such as npm or yarn, you can include the Scripting Framework Guest Library package in your project as a dependency. The package is published as a public NPM package under the name @elliemae/em-ssf-guest. The following example shows how you would install this to your project using npm:

$ npm install @elliemae/em-ssf-guest

NOTE

The em-ssf-guest package does not include a polyfill as a dependency in order to prevent lock-in with a specific polyfill implementation. If you do not already have a polyfill included in your package.json file's dependencies section, then you will need to add a dependency on the Babel Polyfill library and include the library in your bundle file.

https://babeljs.io/docs/en/babel-polyfill

https://www.npmjs.com/

https://yarnpkg.com/en/


Accessing Scripting Objects in a Guest Application In order for a guest application or script to interact with a scripting object provided by the host, it must first retrieve a reference to the object through the Scripting Framework scripting utilities: var loan = await elli.script.getObject("loan");

Each Scripting Object available to the guest has a unique Object ID: a string value that uniquely identifies the object being retrieved based on the current context. For example, in the case above, the identifier loan is used to retrieve the current Loan object from the host application. Note that, as with all Scripting Object calls, the elli.script.getObject() call is asynchronous and requires that we await the result (or use the Promise.then() function).

The elli.script object is the core, global scripting object available to all Scripting Framework guest scripts. This object provides two primary functions to your custom code:

Function Description

elli.script.getObject("<objectId>") Returns the Scripting Object with the specified Object ID from the host application

elli.script.subscribe("<objectId>",

"<eventName>", <callbackFunction>)

Creates a subscription for an event emitted by a Scripting Object


Subscribing to Script Object Events

Many Scripting Objects emit events to notify the guest of changes in state or user action, and guest applications can use these events to customize the behavior of the system. Subscribing to an event is done using the elli.script.subscribe() function.

Event Subscription // Define an event handler function to run when the event occurs

async function onLoanChange(loan, changeset) {

var loanAmount = await loan.getField("1109");

alert('The Loan Amount is ' + loanAmount);

}

// Register the callback with the event

elli.script.subscribe("loan", "change", onLoanChange);

When creating an event handler/callback function, the function signature should have the following signature:

async function eventCallback(sourceObject, eventData);

The sourceObject is a reference to the Scripting Object that emitted the event; the eventData is any additional data associated to the event (the contents of which will be different for different events). The actual names of the parameters you use is not important.

Responding to Events

The Scripting Framework model allows the host application to expose two types of events:

• Fire-and-forget Events: The application raises the events asynchronously and does not wait for any acknowledgement from the guest(s). Your event handler code cannot assume that the application remains in the same state as when the event was fired since it is possible the state has changed between the time the event was raised and the time your code is executing.


Additionally, any return value from your event handler is ignored.

• Interactive Events: These events provide the event handler the chance to provide feedback to the host that can be used to affect its behavior. For example, a host may raise a "beforeSave" event that allows an event subscriber to provide feedback that causes the save action to be cancelled.

When you subscribe to an interactive event, your event handler function is expected to return either a feedback value consistent with the desired feedback required by the event, or a Promise that resolves to the specified feedback value. For example, consider an interactive event that expects a boolean as its feedback value. The following code demonstrates a synchronous event handler that directly returns a feedback value:

Synchronous event handler // A trivial, synchronous function that returns a fixed feedback value

function onBeforeLoanSave(loan, eventData) {

return false;

}


elli.script.subscribe("loan", "beforeSave", onBeforeLoanSave);

The more common pattern will be to use an asynchronous function that generates a Promise, allowing for more sophisticated interaction patterns:

Asynchronous event handler // An asynchronous function that provides feedback

async function onBeforeLoanSave(loan, eventData) {

var loanAmount = await loanAmount.getField("1109");

return loanAmount > 10000;


}


elli.script.subscribe("loan", "beforeSave", onBeforeLoanSave);

Because the return value of all "async" functions is a Promise, the Scripting Framework will "await" the result of the Promise before sending the result back to the host application.

Of note is that all interactive events have a timeout that specifies the maximum amount of time that guests have to provide feedback. Keep this timeout in mind when you implement your event handler. If, for example, you intend to interact with the user or perform an action that may have an unpredictable response time, you may need to provide immediate feedback to the host to abort the current action and then perform the desired, long-running process. Once the process is complete, use a Scripting Object function to re-initiate the action that was aborted (e.g. a Loan.Save() action).

Invoking Developer Connect APIs

In integration types that support user-level security (Forms, Tools, Plugins), a developer's custom code may need to interact with Ellie Mae's REST-based Developer Connect APIs. Because all Developer Connect APIs require a valid OAuth2 Access Token, the developer's JavaScript must first obtain such a token through a process called Token Exchange. This process provides a secure method to generate an access token using the developer's OAuth Client Credentials. For integrations that run with the User Security Context, this token is tied to the same Encompass User Identity as the user logged into Encompass.

The basic Token Exchange flow follows the following pattern:

1. The developer's script invokes the host application to generate an auth code . An auth code itself does not provide access to the Developer Connect APIs; instead, it must be exchanged for an access token as described in subsequent steps.


var auth = await elli.script.getObject("auth");

var authCode = await auth.createAuthCode("6fQi0678Vx0p");

// The developer's Dev Connect OAuth Client ID

2. Once you get the authorization code, you can invoke the Developer Connect APIs using either fetch() or XMLHttpRequest().

Performing Single Sign-On (SSO) with External APIs or Applications

Identity and authorization are critical issues when calling most web-based APIs or accessing secure web sites. Such systems require some form of user authentication prior to accessing the core functions of the API or site, which typically results in the creation of an Access Token or Session ID that gets passed with all subsequent requests.

When your code runs within an Ellie Mae application, you can avoid a separate authentication process with the secure API/site by implementing a single sign-on (SSO) flow with the user's Ellie Mae identity. An SSO flow allows a system to establish "trust" with another party, in this case Ellie Mae, so that it can use the identity information from the trusted party to authorize access into its system. To perform an SSO flow, you can use the Auth Object published by the host application to obtain an OAuth2 Auth Code (via the createAuthCode() function). This code can then be passed to your web API or site as a means to identify the caller. Your server-side code can then invoke the Ellie Mae Identity Service to exchange the Auth Code for an Access Token. Finally, the Access Token can then be used to determine the identity of the authenticated user. Assuming the flow succeeds and the user is authorized to access your system, your application can then generate its own Access Token or Session ID that can be returned to the browser.

The following diagram describes the flow:

encompass lo connect custom tools implementation guide · 2019-01-29 · encompass lo connect...

Documents