Transaction Request Attachments

A common need for integrations is to support the ability for users to attach certain files to a service request, such as attaching the subject properties purchase agreement for an appraisal, or a borrowers eSigned consent form to verify their tax returns with the IRS. The EPC platform enables developers to easily build and offer this capability to their users on the integrations user-interface, allowing users to upload and attach files from their local drive, or from the loans eFolder.

On the front-end

Developing this capability for your integrations user-interface requires tying together two methods available on the JavaScript API:

Step 1: Launching the file picker

The first step in supporting this capability, is presenting the user with the host applications native file picker once they have expressed intent to attach a file (for example, when they click on an "Attach File" button rendered on your ordering interface). To do so - the integration must invoke the JavaScript API's application.performAction action method, as illustrated below:

import host from '@elliemae/em-ssf-guest'

...

let userSelectedResources // Container for user selected file references

try {
  const applicationObject = await host.getObject('application')
  userSelectedResources = await applicationObject.performAction('getAvailableResources')
} catch (error) {
  console.log({error})
}

...

Once the user is done selecting files to attach, the Promise object returned by the method on line 9 above will resolve to an array of resource objects - which are references to the user selected files that are to be included in the transaction request:

// userSelectedResources will resolve to:
[
  {
    id: 'RESOURCE_ID',
    name: 'RESOURCE_NAME',
    mimeType: 'RESOURCE_MIMETYPE'
  },
  ...
]

Step 2: Including user selected files in the transaction request

Once the integration has captured the references to the user selected files, it simply needs to include this array of resources in the transaction request object during transaction creation. It does so as part of its invocation of the JavaScript API's transaction.create method:

...

let transactionRequest = {
  request: {
    type: 'REQUEST_TYPE',
    options: {
      stringOption: 'SOME_VALUE',
      booleanOption: true,
      numericOption: 1000
    },
    resources: userSelectedResources // Include user selected resources in request
  }
}

// Now - initiate the transaction
try {
  const transactionObject = await host.getObject('transaction')
  const transactionData = await transactionObject.create(transactionRequest)

  applicationState.transactionId = transactionData.id
} catch (error) {
  console.log({error})
}

...

On the back-end

To access the user attached resources when processing the newly initiated transaction request, your integrations back-end needs to invoke the REST API's GET /transactions/:id/request/resources endpoint. In the response, your integration will receive URL's and authorization headers to callback into and download the attached file content:

[
  {
    "id": "02eb823b-9e6f-483c-a71f-f4b0abdbbcad",
    "name": "example1.pdf",
    "url": "https://int.streaming.us-west-2.skydrive.rd.elliemae.io/v1/clients/3010000024/02eb823b-9e6f-483c-a71 ...",
    "mimeType": "application/pdf",
    "authorization": "elli-signature 2DFBB545CD81FDABA293AD1A1435DAEB9CA907AD73591F448A1759D9327E55E520F970C543338D7BC48EC ...",
    "type": "urn:elli:skydrive"
  },
  {
    "id": "d714117c-247f-452e-9169-c112b6d24671",
    "name": "example2.pdf",
    "url": "https://int.streaming.us-west-2.skydrive.rd.elliemae.io/v1/clients/3010000024/02eb823b-9e6f-483c-a71 ...",
    "mimeType": "application/pdf",
    "authorization": "elli-signature 2DFBB545CD81FDABA293AD1A1435DAEB9CA907AD73591F448A1759D9327E55E520F970C543338D7BC48EC ...",
    "type": "urn:elli:skydrive"
  }
]

Now - you can use the information above to callback into the EPC platform and download each independent file attachment:

import requests

url = "https://int.streaming.us-west-2.skydrive.rd.elliemae.io/v1/clients/3010000024/02eb823b-9e6f-483c-a71 ..."

headers = {
  'Authorization': 'elli-signature 2DFBB545CD81FDABA293AD1A1435DAEB9CA907AD73591F448A1759D9327E55E520F970C543338D7BC48EC ...'
}

response = requests.request('GET', url, headers=headers)

...

Thats how simple it is to support user selected file attachments as part of transaction requests with your integration 🎉