ICE Mortgage Technology Scripting Objects Reference

This section provides a reference for the different Scripting Objects exposed to guests running within ICE Mortgage Technology applications.

Each Scripting Object described in the following sections includes a list of methods and events exposed by the object. Currently, each method/event is available in the Lender API context for the following integration types:

• Custom Form
• Custom Tool
• Plugin

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

The following objects are available and described in the following sections:

• Application Object
• Auth Object
• Http Object
• Loan Object
• Session object
• Script Object

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");

📘

Objects are accessed using a lowercase string, and the string is case-sensitive.

Application Object

The Application Object (ObjectID = "application") allows for access to applicationlevel UI elements, behaviors and events.

Accessibility

The Application Object is accessible from the following scripting contexts:

• Custom Form
• Custom Tool
• Plugin

Events

Methods

The following methods are provided by the Application Object.

GetApplicationContext
When invoked, returns a JSON object.

Code Examples
JSON Object Return Type:

{
	"route": {
		“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-tool”,
		“type”: “CUSTOM_TOOL”,
		“name”: “My Pipeline”,
		“id”: “GUID“
	}
}

Other possible values for route will be:

{
	“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-tool”,
	“type”: “GLOBAL_CUSTOM_TOOL”,
	“name”: “East Side Pipeline”,
	“id”: “ <GUID> “
} {
	“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-form”,
	“type”: “CUSTOM_FORM”,
	“name”: “My IFB Custom Form”,
	“id”: “04ae03f8-f63d-4019-8f65-94920e28712a“
}
{
	“route”: {
		“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-tool”,
		“type”: “CUSTOM_TOOL”,
		“name”: “My Pipeline”,
		“id”: “GUID“
	}
{
	“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-standardform”,
	“type”: “STANDARD_FORM”,
	“name”: “My IFB Standard Form1 ",“
	id”: “64326cca-ccc9-4e30-9510-c944840401ef“
} {
	“url”: “https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-00fdadf8b0fd/custom-tools-form”,
	“type”: “STANDARD_FORM "“
	name”: “LO Standard Form”,
	“id”: null
} {
	“url”: “https://encompass.ice.com/pipeline/03409b76-22ac-44c2-ae12-99fdadf8b1fd/standard-forms/64326ccaccc9-4e30-9510-c944840401ef”,
	“type”: “STANDARD_TOOL”,
	“name”: “COR PURCHASE ADVICELO Standard Form”,
	“id”: <GUID>
} {
	“url”: “https://encompass.ice.com/pipeline”,
	“type”: “OTHER”,
	“name”: null,
	“id”: null
}

GetDescriptor();
Returns a descriptor for the Application. A descriptor has the following schema:

{
   "id":"<app_id>",
   "name":"<app_name>"
}

navigate(navigateOptions);
Navigate to Application/Loan routes using script.
Navigate to Standard Form/Custom
Form/Custom Tool from Global Custom Tool

{
"target": "Borrower Summary Origination", 
  // Name of form as it appears in left navigation
"type": "STANDARD_FORM",
"context": {
"loanId": "c73a2639-225d-4720-97aa-5bcf834fd9a7"
}
}

//Types
STANDARD_FORM // All standard Forms (LO & Web IFB)
STANDARD_TOOL // All standard tool (LO & Web IFB)
CUSTOM_FORM // Web IFB Custom Form
CUSTOM_TOOL
GLOBAL_CUSTOM_TOOL 
OTHER // All other routes e.g.
pipeline/opportunities (global) and services/documents/conditions (loan)
Navigate to different form/tool from within same loan

{
"target": "Borrower Information", // Name of form as it appears in left navigation
"type": "CUSTOM_FORM",
  
// If Loan Id is missing from Context then it navigate to same loan's form/tool
}
Navigate to Global Custom Tool
{
"target": "Test Global Tool", // Name of form as it appears in left navigation
"type": "GLOBAL_CUSTOM_TOOL",
"context": {
"loanId": "c73a2639-225d-4720-97aa-5bcf834fd9a7"
}
  
}
Navigate to OTHER global routes i.e. Pipeline/Opportunities
{
"target": "pipeline", // Possible values Pipeline & Opportunities
"type": "OTHER"
}
Navigate to OTHER loan routes i.e. services, documents & conditions
{
"target": "services", // Possible values services, documents & conditions
"type": "OTHER"
}

performAction("actionName", actionOptions);
Performs a pre-defined action within the application, passing an optional actionOptions object with any options supported by the specified action. These actions generally will result in data being
returned to the caller via the actionCompleted event.

open(openOptions);
Accepts a target to open a new browser tab to a target URL or logical page location, or a resource which represents a logical resource to open (e.g. a document).

{
target: "..." | IOpenTarget,
type?: "..."
// IOpenTarget = {
entityType: "...",
entityId: "..."
}
//Only tested with string as a target

openModal(openOptions);
Similar to the open function but opens the specified location/resource in a modal window/dialog. The openOptions are the same as those for the open function. In some cases the context-specific option may drive how the modal content is delivered - i.e. IFB Forms.

{
target: "..." | IOpenTarget,
name: "...",
type?: "...",
size: 'sm/md/lg',
  
// Any context-specific options (example
- 'type' : 'form/tool')
}
// IOpenTarget = {
// entityType: "...",
// entityId: "..."
// }
//Only tested with string as a target

Code Examples
In custom forms, you can set up buttons and other controls with the openModal option to launch a modal window that contains a custom input form or a custom tool. When a form user clicks the button, a modal window opens the custom form or tool.

Similar to the open function, the openModal (openOptions) opens the specified location/resource in a modal window/dialog box. The openOptions are the same as those for the open function. Here is sample code for opening a customized version of the Borrower Information input form:

const appObj = await elli.script.getObject(‘application’);
const modalOptions = {
'type': 'form',
'size': 'md',
'name': 'Borrower Information',
'showFooter': true/false,
'formType': 'CUSTOM_FORM'
};
const modalResp = await appObj.openModal(modalOptions);

You can also enable forms that are not built using the Web Input Form Builder and Angular forms to be opened in modal windows. To open a non-WIFB or Angular forms using openModal:

const appObj = await elli.script.getObject('application'); 
const modalOptions = {
'type': 'form',
'size': 'md',
'name': 'Fee Itemization',
'formType': 'STANDARD_FORM'
};
const modalResp = await appObj.openModal(modalOptions);
// name - form name
// size - sm/md/lg/xl - defaults to xl
// formType - STANDARD_FORM

The following input forms can be launched with the openModal option:

supportsAction("actionName");
Returns a boolean indicating if a specified action is supported.

getCapabilities();
Returns a capabilities object that indicates what features/actions the application supports. If a capability is missing from the response object, the caller should assume it is not supported. The schema of the object is as follows:

{
supportedActions: [ "Action1","Action2"],
supportedFeatures: [ "Feature1","Feature2"]
}

keepSessionAlive();
Sends event to parent application that in turn calls SessionTimeoutService's handleActivity method to refresh the current session.

closeModal();
Sends event to parent application that in turn calls closeFormInModal function to close current modal.

getApplicationContext();
Returns the current context of the application as JSON object which will include the following entities:

• env
• route

Sample response for env
// Int environment
"env": {
"apiHost": "https://int.api.ellielabs.com"
}

//Staging environment
"env": {
"apiHost": "https://stg.api.elliemae.com"
}

Sample response for route
//Encompass standard form
"route": {
"url":
"https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-0fdadf8b0fd/customtools-
tool”,
"type": "STANDARD_FORM",
"name": "1003 Details of Transaction",
"id": "203eccb7-7f39-4a82-a8c2-dfb6652cf4ff"
}

//WEB IFB form
"route": {
"url":
"https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-0fdadf8b0fd/customtools-tool",
"type":
"STANDARD_FORM/CUSTOM_FORM",
"name": "1003 Details of Transaction",
"id": "203eccb7-7f39-4a82-a8c2-dfb6652cf4ff"
}

//Tools
"route": {
"url":
"https://encompass.ice.com/pipeline/12345b77-11ac-11c2-ae12-0fdadf8b0fd/customtools-tool",
"type":
"STANDARD_TOOL/CUSTOM_TOOL/GLOBAL_CUSTOM_TOOL",
"name": "File Contacts",
"id": null/<GUID>
}

//Other
"route": {
"url":
"https://encompass.ice.com/pipeline",
"type": "OTHER",
"name": null,
"id": null
}
  
Error: This API will throw an error if host runs into an exception while processing this request

print
Opens a browser’s print dialog with the content provided as Blob object. Use this print method to enable printing PDF files and JPG image files taht are accessed from a microapp (i.e., a source outside of Encompass).
This method can be used to execute print logic from parent window object to avoid security issues when a child application (hosted in an iframe) tries to print the content from within its iframe window.

Code Example

Sample code provided to use Print button to print a PDF or JPG file.

async function btnPrint_click(ctrl) { try {
/* To avoid CORS error while downloading the content from different origin
(than the EncompassWeb/Custom tool URL), response header "access-control- allow-origin" for file download
http request should not be empty & must contain valid values like https://encompass.ice.com or custom/global tool URL */
const data = await fetch('<URL_TO_PDF_OR_JPG_FILE>'); const blob = await data.blob();
const printOptions = { blob };
const appObj = await elli.script.getObject('application'); await appObj.print(printOptions);
} catch (err) {
console.log('Error occurred while printing ', err);
}
}

Argument
• printOptions
• blob - valid object of type Blob
Return Value
• Promise
(This method returns immediately and does not wait for print operation to complete.)
Error
• Invalid payload i.e., Missing blob in printOptions
• blob is not of type Blob

Auth Object

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

Accessibility

The Auth Object is accessible from the following scripting contexts:

• Custom Form
• Custom Tool
• Plugin

Methods

The following methods are provided by the Auth Object.

Code Example:

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

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

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

1. authObject.getUser().then(userData => {
     console.log('Here is your user data from host: ',
     userData);
   });
2. authObject.createAuthCode(“tirykwfo”).then(auth_code_from_host => {
   console.log('Authorization code from Host ' +
    auth_code_from_host + ‘must be exchanged
    for an access token.’);

 
Note: The argument to create createAuthCode, the LOConnectClientID is currently optional.

Http Object

The Http object provides APIs to make call-outs to external systems via HTTPS. By exposing this object from the host, it ensures that the call will bear the "Origin" header of the host application (e.g., https://encompassloanconnect.com)This is critical for situations where the guest's code is running in a strict-mode sandbox (where the "allowSameOrigin" flag is false).

Accessibility

The Http Object is accessible from the following scripting contexts:

• Custom Form
• Custom Tool
• Plugin

Methods

The following methods are provided by the Http Object.

Example

async function getNormalizedAddress() {
 let http = elli.script.getObject("http");
 let resp = await http.post("https://mysite.com/api", {
  addr: "1234 5th Str",
  city: "Pleasanton",
  state: "CA"
 }, "40f2qx8ywn62d");
 alert('Normalized value is ' + resp.addr);
}

Loan Object

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

Accessibility

The Loan Object is accessible from the following scripting contexts:

• Custom Form
• Custom Tool
• Plugin

Methods

The following methods are provided by the Loan Object.

Events

Code Example:
In your JavaScript file, first get the loan object like this:

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

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

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)
});

Code Example:
Here is sample code for the execute loan action.

[{
"op":"performAction","value":"calculateEEMMortgage"
}]

It returns a modified loan response as a result of the loan action.

Note: This method will auto-refresh the custom form with the updated loan response.
Also, this method invokes state API with all pending changes in the current changeset along with requested loan action, e.g.

[{
"op":"merge",
"value":"35000", "contractPath":"loan.fhaVaLoan.energyEfficientMortgageAmount"
},
{
"op":"performAction","value":"calculateEEMMortgage"
}]

Here are some examples of the supported loan actions:
• updateCorrespondentBalance
• updateCorrespondentFees
• copyItemizationToStateDisclosure
• calculateEEMMortgage

Session Object

The Session object provides session-level state storage for a guest application. Each guest's state is isolated from all others based on a unique identifier for the guest (e.g. an extension ID or Form ID). This object is provided in contexts where sandboxing will not allow the guest app to access the sessionStorage of the browser.

Accessibility

The Session Object is accessible from the following scripting contexts:

• Custom Form
• Plugin

Methods

The following methods are provided by the Session Object.

Notes

The implementation of this object should write the guest's state data to the host application's sessionStore, but should ensure that each guest's state is isolated, both from the host application as well as other guests. This should be done by creating naming conventions for guest keyspaces, e.g. ssf.guestId.key.

In order to ensure that guest applications cannot consume significant amounts of sessionStorage, restrictions should be placed on the number and size of the stored session state. In particular, we can start with these values:

• Each valueObj, when stringified, cannot exceed 5 KB
• An individual guest is limited to 5 session values

This will ensure that no guest can consume more than 25 KB of sessionStorage. There is no facility or access provided to write to applicationStorage. Guests that require persistent storage will need to implement an external (service-based) mechanism for this.

Script Object

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

Accessibility

The Script Object is accessible from the following scripting contexts:

• Custom Form
• Custom Tool
• Plugin

Methods

The following methods are provided by the Script Object.

Debugging via Browser Tools

The following online tutorial is available for understanding how to use Chrome’s DevTools:
• Get Started with Debugging JavaScript in Chrome DevTools