Migrating from Version 1.0

This section is intended for Partners who plan to migrate their existing application built on version 1.0 of the EPC platform to version 2.0

I. Migration Overview

The fundamental workflows of an application are primarily unchanged between versions 1.0 and 2.0. An application will continue to be built around the core transactional concepts:

1. Transaction Origination - Origination context is received by an application's User-Interface (UI) through the host Encompass application via the JavaScript API (historically called the Secure Scripting Framework, or SSF). The origination context is then used to access user/organization credentials, loan data, and user/organization data via the REST API's https://api.elliemae.com/partner/v2/origins endpoint, as governed by the application's origin data entitlements (historically called the application's manifest).

2. Transaction Initiation and Fulfillment - A new transaction is created either by the application UI on a user's behalf via the JavaScript API, or via a Lender's own application that uses the Developer Connect Services API. Once a transaction is created, an application is notified via a Webhook. After that, the application can retrieve the transaction request information (user/company credentials, loan data, and attachments, as governed by the application's request data entitlements) via the https://api.elliemae.com/partner/v2/transactions endpoint, and begin servicing the request. Once the request is serviced, the application can send response loan data and attachments to the EPC platform. EPC will accept the response (as governed by the application's response data entitlements) and notify the application via a Webhook once the response is successfully processed and the subject loan is updated.

The origin REST resource continues to be a primary resource in EPC 2.0, encapsulating the interactive origination context for an application's UI. The transaction REST resource (and its request and response child resources) continues to be the primary communication mechanism between a Lender/Consumer facing Encompass application and an application on the EPC platform, and the webhook resource continues to be the messenger for asynchronous notifications.

The new REST resource introduced in EPC 2.0 is the product resource. The product resource represents an instance of a Partner application, and enables Partners to self-service their application on-boarding and management. Its data model encapsulates the various pieces of information that govern an application on the EPC platform, such as an application's development environment (sandbox or production), development status, listing information, routing information, credential requirements, and data (loan information read/write) and access (who can view and create transactions) entitlements.

To summarize the changes between the two versions:

The following sections cover the changes in achieving the primary use-cases of application on-boarding/management, development, and release.

II. Application On-boarding and Management

The first significant improvement in the Partner development experience is application on-boarding and management:

A. On-boarding a Product Instance

In version 1.0, Partners needed to work with Ellie Mae to on-board multiple instances of their products onto the platform, providing isolated instances to test in development environments (Development, QA, Staging, UAT/CTE, Production etc). This process involved a production deployment to the EPC platform, which could take several days. With EPC 2.0, this task can be completed with a simple API call to the https://api.elliemae.com/partner/v2/product endpoint, reducing the turn-time from days to seconds. Partners are empowered to create as many instances of their product required to adhere to their internal software development lifecycle.

B. Product Listing Management

In version 1.0, a product's listing name was managed via the Partner developer portals Integration On-boarding/Management page. In EPC 2.0, this information is managed via operations on the listingName attribute of the product RESTful resource, which can be modified by making simple API calls to the https://api.elliemae.com/partner/v2/product endpoint.

C. Product User-Interface Management

In version 1.0, a product's UI was hosted by the EPC platform. All the distributable artifacts for the UI web application (such as HTML, CSS and JavaScript files) needed to be zipped into a single directory and uploaded to the platform via the Partner developer portal's Integration On-boarding/Management page. This model imposed significant limitations for Partners using contemporary development frameworks for their UI application.

With EPC 2.0, Partners can host their UI application on their own infrastructure, and follow their own artifact distribution/deployment methodologies. EPC 2.0 only mandates that the application be served over HTTPS. All EPC needs to know for the UI application is the URL, which is used to route to the application within a parent Lender/Consumer-facing Encompass application. This information is encapsulated within the interfaceUrl attribute of the product RESTful resource, which is modified by making simple API calls to the https://api.elliemae.com/partner/v2/product endpoint.

D. Product Webhook Endpoint Management

In version 1.0, a product's Webhook endpoint registration was managed via the Partner developer portal's Integration On-boarding/Management page. In EPC 2.0, this information is managed via operations on the webhooks attribute of the product RESTful resource, which is modified by making simple API calls to the https://api.elliemae.com/partner/v2/product endpoint:

{
  "webhooks": [
    {
      "resource": "urn:elli:epc:transaction",
      "events": [
        "created",
        "updated"
      ],
      "signingkey": "{{YOUR_WEBHOOK_SIGNING_KEY}}",
      "url": "{{YOUR_WEBHOOK_URL}}"
    },
    {
      "resource": "urn:elli:epc:transaction:event",
      "events": [
        "created"
      ],
      "signingkey": "{{YOUR_WEBHOOK_SIGNING_KEY}}",
      "url": "{{YOUR_WEBHOOK_URL}}"
    }
  ]
}

Functionally, Webhooks in EPC 2.0 provide the same transaction lifecycle notifications provided by Webhooks in EPC 1.0, notifying a Partner's application when:

1. A new transaction request has been created by a Lender - via the urn:elli:epc:transaction resources created event
2. A transaction's request has been successfully processed and the subject loan has been updated - via the urn:elli:epc:transaction:event resources created event
3. An existing transaction request has been updated with request loan data/attachments by a Lender - via the urn:elli:epc:transaction resources updated event

Further changes in EPC 2.0 are detailed in the Working with Webhooks section of this guide, including details on the specific REST resources that can be subscribed to Webhooks (the transaction and transaction event resources), and the specific event types of resources (created, updated etc) that are tied to a transaction's lifecycle.

II. RESTful API

1. origin resource:

📘

EPC 1.0 endpoint: https://api.elliemae.com/partner/v1/origin
EPC 2.0 endpoint: https://api.elliemae.com/partner/v2/origins/:id

Data Contract:

2. transaction resource:

📘

EPC 1.0 endpoint: https://api.elliemae.com/partner/v1/transactions/:id
EPC 2.0 endpoint: https://api.elliemae.com/partner/v2/transactions/:id

Data Contract:

3. webhook resource:

Data Contract:

III. JavaScript API

The JavaScript API, formerly referred to as the Secure Scripting Framework (SSF), has two primary changes:

1. ES6 Promises has replaced completion-hook/events as the callback mechanism for completion of asynchronous workflows
2. Exposed scripting objects have more scoped functionality (transaction and application object) as opposed to the single all-encompassing scripting object in EPC 1.0 (sandbox-interaction object).

Below is a chart of use-cases and their methods for the EPC 1.0 and EPC 2.0 JavaScript API. Please note the changes:

Note: Scroll left to view the complete row