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

EventDescriptionFeedback
loginInvoked after the user is
fully logged into the
application and the UI is
rendered.

NOTE: This event will not
fire for users with super
administrator privileges.
To test, please log in as a
non-administrator
account.
none

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:

Aggregate SetupFile Contacts
Borrower Summary OriginationFNMA Streamlined 1003
Borrower Summary ProcessingLink Liability
Changed CircumstanceMonthly Income
Disclosure TrackingRegZ Loan Estimate
Fee ItemizationTotal Monthly Payment
Fee Variance Worksheet

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.

MethodDescription
createAuthCode("LOConnectClientID")Generates a new auth code for the caller which
can be exchanged for an Access Token using the Encompass 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. See Invoking Developer Connect APIs.
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 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.

MethodDescription
delete("url_",
_headerObjOrAccessToken
)
Acts as the get() method but uses the DELETE verb.
get("url",
headerObjOrAccessToken)
Executes an HTTP GET request against the
specified URL. The headerObjOrAccessToken
can either be a JavaScript Object containing
name/value pairs that will be included as headers on the request OR it can be a string, which will used as the Access Token for the request. The function returns a Promise that resolves to the response from the server if successful or as an error if the server returns a non-200 response.
post("url",
contentObj,
headerObjOrAccessToken)
Performs an HTTP POST to a URL, passing the
specified contentObj in the request. If the
contentObj is a string, it is passed in its raw
format; if the contentObj is a JSON object, the call should stringify the object and place the result into the request body. The return value is a Promise that resolves to the response from the
server if successful or as an error for a non-200
response.
patch("url",
contentObj,
headerObjOrAccessToken)
Acts the same as post() method but uses the
PATCH verb.
put("url",
contentObj,
headerObjOrAccessToken)
Acts the same as post() method but uses the PUT verb.
delete("url",
headerObjOrAccessToken)
Acts as the get() method bu uses the DELETE
verb.

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.

MethodDescription
all()Returns the entire Loan object in the v3 Loan
Object model.
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()Syncs the loan workspace with any changes
made by other users.
isReadOnly()Indicates if the loan is editable or in a read-only
state.
calculate()Executes calculations and business rules.
execAction()Execute supported loan actions; This is specific to v3 stateful implementation.
commit()Attempts to commit/save all pending changes for the current loan to the server.

Events

EventDescriptionFeedback
precommitThis event is fired prior to saving and pending changes to the loan.
The guest can use this event to
perform custom validation and, via the feedback mechanism, prevent the loan from being saved. A “cause” attribute can be used to indicate whether the commit() (i.e., the loan save) was initiated by the user or by the code. For example:

{
"cause": "saveButton" | "script" | ... // [additional data can be added here as needed]
}

When the loan is saved through Save button, the cause = saveButton; when loan is saved through loan.commit(), cause = script
Boolean
A false value indicates that
the loan should not be
committed.
committedThis event makes the change to the loan permanent.
The event attempts to commit all pending changes for the current loan. The committed(save) may fail if a business rule is blocking the save.

If the save is executed or if the SSF commit method is called, then a 'committed' event is raised in the SSF. If the save fails for any reason, the 'committed' event is not raised.
changeThis event is fired for each change made by the user in the UI.None
syncThis event is fired after the loan is sync'ed within any saved state made outside of the user's workspace. This event should fire after any call to calculate() or merge(), assuming any changes are made to the loan.None
openFired after the loan is opened and ready for user interaction.None
closeFired just prior to closing the loan in the UI.None
premilestoneCompleteThis event is fired when the user attempts to complete a milestone and allows for custom validation, and cancellation, of the process.Boolean
A false value indicates that
the milestone should not be
completed.
syncThis event is fired after the loan is synced within any saved state made outside of the user's workspace, such as any call to calculate() or merge(), or from business rule firing, assuming any changes were made to the loan.None

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.

MethodDescription
set("key",
valueObj);
Sets a value into the session state for the object.
get("key");Returns a value already stored in 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.

getObject("objectNam
e
")
Returns a reference to an object exposed by the
application host, e.g. the Application, Loan or
Form object.
subscribe("objectNam
e
", "eventName",
callback)
Registers a callback for an event generated by
the specified object. The callback is a JavaScript
function reference.

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