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
Event | Description | Feedback |
---|---|---|
login | Invoked 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 Setup | File Contacts |
Borrower Summary Origination | FNMA Streamlined 1003 |
Borrower Summary Processing | Link Liability |
Changed Circumstance | Monthly Income |
Disclosure Tracking | RegZ Loan Estimate |
Fee Itemization | Total 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.
Method | Description |
---|---|
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.
Method | Description |
---|---|
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.
Method | Description |
---|---|
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
Event | Description | Feedback |
---|---|---|
precommit | This 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. |
committed | This 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. | |
change | This event is fired for each change made by the user in the UI. | None |
sync | This 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 |
open | Fired after the loan is opened and ready for user interaction. | None |
close | Fired just prior to closing the loan in the UI. | None |
premilestoneComplete | This 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. |
sync | This 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.
Method | Description |
---|---|
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
Updated about 1 month ago