Purpose:

Allow users to perform one of an enumerated set of actions, as supported by the host application. For example, allowing the user to upload/attach a file to the transaction request, or update a set of invalid/expired credentials configured for their use with your integration.

Sample Usage:

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

...

const action = "ACTION_ID"

async function performAction(action) {
  try {
    const applicationObject = await host.getObject('application')
    const actionResult = await applicationObject.performAction(action)

    console.log(actionResult)
  } catch (error) {
    console.log({error})
  }
}

performAction(action)
import host from '@elliemae/em-ssf-guest'

...

const action = "ACTION_ID"

host.getObject('application')
  .then(
    (applicationObject) => {
      applicationObject.performAction(action)
        .then(
          (actionResult) => {
            	console.log(actionResult)
            }
          }
        )
        .catch(
          (error) => {
            console.log({error})
          }
        )
    }
  )
  .catch(
    (error) => {
      console.log({error})
    }
  )

📘

Runtime supported action discovery!

You can also discover whether the host application within which your integration is currently embedded supports a specific action or not. You can invoke the application.supportsAction method - which returns a boolean value indicating whether the action provided as an argument is supported by the host application.

Interface:

Input:

Action IDDescriptionSupporting Applications

getAvailableResources
Allow the user to select and attach files from the host applications document repository (the Encompass eFolder, for example), or upload attachments from their local drive.

References to said file attachments - referred to as resources in the EPC API - are made available to the caller of this method once the action is fulfilled by the user.

Desktop Version of Encompass

Web Version of Encompass

Returns:

Type: Promise

==> Resolved

A list of the attachments - referred to as resources in the EPC API - and associated attributes:

[
  {
    id: "<id>",
    repository: "urn:elli:skydrive",
    name: "<name>",
    mimeType: "<mimeType>"
  },
  {
    id: "<id>",
    repository: "urn:elli:skydrive",
    name: "<name>",
    mimeType: "<mimeType>"
  }
]

The id, name and mimeType attributes need to be echoed back to the EPC platform for each selected resource, as part of the transaction.create() method call when initializing a transaction (under the $.request.resources object). Read the transaction.create() method reference for more details.

Also - if the user closes the file selection modal without attaching any files - the Promise will resolve to an empty array - []

==> Rejected

An error is raised, containing a message attribute with details on the error that occurred

{
  message: "{{ERROR_DETAILS}}"
}

Input:

Action IDDescriptionSupporting Applications

updateCredentials
Allow the user to update the credentials assigned to them for use with your application - as long as they are entitled to do so by their Administrator.

The newly updated credentials are provided to the caller of this method once the action is fulfilled by the user.

Desktop Version of Encompass

Web Version of Encompass

Encompass Consumer Connect

Renders:

A credential input dialog - containing the credential keys that the user is allowed to update:

🚧

User vs Company Credentials

User's are only entitled to create/update user credentials delegated solely to them. Users are not allowed to touch shared credential sets, or company level credential sets configured by their Administrator

If your credential requirements specify a combination of user and company level credentials - users will only be able to supply you updated values of their user-level credentials. Sometimes - if a company credential has been marked as required in your applications credential requirements - and it has not been configured by the Administrator - users will be prompted with an error, asking them to contact their Administrator (required credentials need to be configured).

📘

Reasons for seeing "Contact Admin" credential prompt:

  1. You have not specified a credential requirements in your applications configuration
  2. You have not configured a required company level credential for your test user, acting as the test Administrator of your application sandbox

Returns:

Type: Promise

==> Resolved:

The credential key and value pairs - keys as defined in your applications configured credential requirements, values as entered by the user when prompted upon action invocation

{
  CREDENTIAL_KEY_A: "{{USER_ENTERED_VALUE}},
  CREDENTIAL_KEY_B: "{{USER_ENTERED_VALUE}}
}

If the user closes the credentials prompt without entering updated credential values, the Promise will resolve to an empty object - {}

==> Rejected

An error is raised, containing a message attribute with details on the error that occurred

{
  message: "{{ERROR_DETAILS}}"
}

Input:

Action IDDescriptionSupporting Applications

getRoles
Allow the user to obtain a list of Roles from Encompass Settings exposed to Encompass Partner Connect, so that a partner can support configurations based on that data. The user calling this action needs to have the required permission configured in the Encompass Settings.

Desktop Version of Encompass

Web Version of Encompass
`

Returns:

Type: Promise

==> Resolved:

A list of the Roles in the EPC API - and associated attributes:

[
   {
      "roleAbbr":"<roleAbbr>",
      "roleID":"<roleID>",
      "roleName":"<roleName>" 
   }
]

If the user does not have permission, the Promise will resolve to an empty object - {}

==> Rejected

An error is raised, containing a message attribute with details on the error that occurred

{
  message: "{{ERROR_DETAILS}}"
}

Input:

Action IDDescriptionSupporting Applications

getPersonas
Allow the user to obtain a list of Personas from Encompass Settings exposed to Encompass Partner Connect, so that a partner can support configurations based on that data. The user calling this action needs to have the required permission configured in the Encompass Settings.

Desktop Version of Encompass

Web Version of Encompass

Returns:

Type: Promise

==> Resolved:

A list of the Personas in the EPC API - and associated attributes:

[
   {
      "id":"<personaID>",
      "name":"<name>",
      "isInternal": < isInternal>,
      "isExternal": < isExternal>  
  }
]

If the user does not have permission, the Promise will resolve to an empty object - {}

==> Rejected

An error is raised, containing a message attribute with details on the error that occurred

{
  message: "{{ERROR_DETAILS}}"
}