Developer Guides

User Interface: Transaction Management

Suggest Edits

EPC provides a comprehensive suite of functionality via its JavaScript API, that can be leveraged by a partner integrations user-interface for transaction creation and management. The interface specification details for the JavaScript API's transaction object are available in the [Javascript API object reference] (https://docs.partnerconnect.elliemae.com/partnerconnect/reference#javascript-object-api-reference). This section illustrates common usage scenarios and patterns with sample payloads - let's jump in!


Transaction Origination

transaction.getOrigin

For interactive, UI driven workflows, the partner integration UI needs to invoke the transaction objects getOrigin method - usually during its initialization phase.

Upon invocation, the method returns a unique session id, along with an origination session token - called the partnerAccessToken, that need to be shared with the integrations back-end for it to invoke the REST API's GET https://api.elliemae.com/partner/v2/origins/:id endpoint and access originating user, organization and loan data to bootstrap the user interaction. If the integrations user-interface is launched in the context of an existing transaction, this method will also return the subject transactionId. Below are some sample return values for this method:

{
  partnerAccessToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ...",
  id: "49923419-2a51-4f13-ad47-3fa8a6b6adc6"
}

{
  partnerAccessToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ...",
  id: "49923419-2a51-4f13-ad47-3fa8a6b6adc6",
  transactionId: "int_e6be29eb-19ca-46a1-ba15-b60f9c160cbd"
}

transaction.refreshOrigin

The partnerAccessToken is a temporary session token, with a snapshot of user/organization/loan data, that is only valid for a duration of 300 seconds once created. If need be - an integration UI can call the transaction objects refreshOrigin method to create a new partnerAccessToken, and use it in coordination with its back-end to retrieve updated origination data. The refreshOrigin methods response object follows the same format as the getOrigin methods response object.


Transaction Initiation/Updates

transaction.create

The partner UI can call the create method on the transaction object to initiate a new service transaction request. The create method is intended to be invoked when a user on the integrations UI expresses intent to initiate a new service request for the subject partner product. This grants the partner integration the temporary entitlement to update the subject Encompass loan with data and documents - as appropriate for the service it is providing to the lender - upon transaction fulfillment.

When creating a transaction, the UI can specify the request type, and other custom inputs in the options attribute, that are necessary for the integrations back-end to process the request and prepare the corresponding response. The partner UI can also enable the subject user to include file attachments - or resources - as part of the transaction request.

{
  request: {
    type: "Asset Verification",
    options: {
      customOption: "value"
    },
    resources: [
      {
        id: "{{uuid}}",
        name: "{{name}}",
        mimeType: "{{mimeType}}"
      }
    ]
  }
}

transaction.update

A transaction request from a lender can be updated with new options and resources - up until the subject transaction is marked completed. To allow the lender to update the transaction as appropriate in such a scenario, send the new options and/or resources into the transaction objects update method - as illustrated in the example below:

{
  request: {
    options: {
      customOption: "newValue"
    },
    resources: [
      {
        id: "{{uuid}}",
        name: "{{name}}",
        mimeType: "{{mimeType}}"
      }
    ]
  }
}

📘

Request type immutability

The type for a lender initiated transaction request can not be updated once created. If you need to support the ability for a lender to change the request type for a transaction they have initiated, the initial transaction must be canceled via a transaction response status update (using the REST API), and the lender must initiate a new transaction request with the updated type


Transaction Context Management

transaction.get

The integration UI can retrieve the id for the current transaction in whose context it is operating, by invoking the get method on the transaction object. If no new transaction has been created in the current session, this method returns a null value for the id key in its response object:

{
  id: "49923419-2a51-4f13-ad47-3fa8a6b6adc6"
}

{
  id: null
}

transaction.set

This method can be used by an integration UI to set the transaction in whose context it desires to operate, for other methods on the transaction object that only operate in the context of an existing transaction. The subject transaction must be one that was created for the current loan and EPC product.

The methods that currently fall into this category are:

  1. transaction.update
  2. transaction.createEvent
{
  id: "49923419-2a51-4f13-ad47-3fa8a6b6adc6"
}

Although integrations are free to set the transactional context they are operating in, which may be necessary when providing views that allow users to switch between and perform actions on multiple transactions, the host application implicitly alters the transactional context in certain scenarios:

  1. If your integration is launched by a user in the context of an existing transaction, such as from the services page on Web Version of Encompass, the document icon on the services side-nav in Desktop Version of Encompass or when returning to a loan application in Encompass Consumer Connect, the transactional context is implicitly set to said transaction

  2. Every time a new transaction is created during a user's interaction with your integration, the context is set to the last created transaction

  3. If the integration was initially launched in the context of an existing transaction, the transaction.getOrigin method will always return the original transactionId the integration was launched in the context of, no matter how many times the transaction is set in the current interaction. You can leverage this to track the initial transaction context for a user interaction.


Transaction Events

transaction.createEvent

Transaction events are a flexible mechanism for ancillary communication in regards to the parent transaction. The transaction objects createEvent method provides the mechanism via which an integration UI can enable lender users to send comments and messages with regards to the subject transaction. For example:

{
   text: "Appraisal On Hold",
   type: "urn:elli:epc:lender:appraisal:hold",
   comments: "Free form comments go here",
   resources: [
      {
        id: "{{uuid}}",
        name: "{{name}}",
        mimeType: "{{mimeType}}"
      }
    ]
}

Closing User Interaction

The partner integration UI has multiple options to close and transfer control back to the host Encompass application. The corresponding methods on the transaction object are described below:

transaction.close

When the integration UI invokes this method, the control is transferred back to the EllieMae product (host application) on which the Partner UI is running. The host application assumes that the Partner UI completed the task without any failures.

transaction.cancel

The integration UI can call into this method to indicate that the task for which it was invoked was canceled by the user. Calling this method tells the EPC platform to close the integration UI and transfer control back to the host Encompass application.

transaction.error

The integration UI can call this method to indicate a failure in the task for which it was invoked. Calling this method will tells the EPC platform to close the integration UI and transfer control to the respective host Encompass application in an error state. The handling of the error varies by host application.


👍

JavaScript API Deep Dive

To learn about the JavaScript API available to your integrations user-interface in more detail, and dive in with some actionable code samples, refer to the EPC JavaScript API reference

Updated 12 months ago

What’s Next