Interacting with Scripting Objects

For a guest application or script to interact with a scripting object exposed by the Host, it must first retrieve a reference to the object through the Guest libraries scripting utilities:

var scriptingObject = await elli.script.getObject("<objectId>");

Each Scripting Object available to the guest has a unique Object ID: a string value that identifies the object being retrieved based on the current context. 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 Guest application scripts. This object provides three primary functions to your application's code:

elli.script.getObject

Sample Usage:

let emObject = await elli.script.getObject('OBJECT_ID')

Interface:

Accepts a string input - the object ID for the scripting object you are trying to access

Returns a promise - which will resolve to an instance of the scripting object with the specified object ID as exposed by the Host application


elli.script.subscribe

Sample Usage:

let emSubscription = elli.script.subscribe('OBJECT_ID', 'EVENT_ID', callback)

Interface:

Accepts a string as the first argument - the object ID for the object that publishes the event you are trying to subscribe to

Accepts a string as the second argument - the event ID for the event you are trying to subscribe to

Accepts a function as the third argument - a callback function that you want executed when the event fires. The callback function you register will receive two arguments upon execution:

  1. An object as the first argument, which is a proxy for the scripting object that fired the event
  2. An object as the second argument, which is the event that was fired

Returns an object - a reference to the subscription that you just created, which can eventually be used to unsubscribe


elli.script.unsubscribe

Sample Usage:

elli.script.unsubscribe(emSubscription)

Interface:

Accepts an object as its only argument - the reference to the subscription you created and are trying to unregister

The next two sections discuss how to invoke the functions of a Scripting Object retrieved thru the getObject() function, and how to subscribe, receive, and, if appropriate, respond to events raised by a Scripting Object.


Invoking Host Exposed Scripting Object Functions

Once you have a reference to a Scripting Object via the elli.script.getObject() call, you can invoke functions on the object to interact with it. Functions may be used to retrieve or modify the state of the Scripting Object, depending on the use. As noted above, all function calls on Scripting Objects are asynchronous; thus, you must either await the result of the function call or use the Promise.then() function to invoke a callback when the function is completed. For example:

async function createTransaction = (request) => {
  // Access transaction scripting object
  var transactionObj = await elli.script.getObject('transaction');

  // Store transaction identifier once the transaction has been created
  applicationState.transactionId = await transactionObj.create(request);
}

The Ellie Mae JavaScript framework has one further optimization that can simplify your code: the framework will automatically await any Promise-valued parameter to a function exposed by a s scripting object.


Subscribing and Responding to Host Exposed Scripting Object Events

The current Ellie Mae JavaScript framework interface exposed to Partner integrations does not include any events for integrations to subscribe and respond to, but watch this space for enhancements!