UI Extension

Purpose

The UI Extension allows you to embed a page within an iFrame that is accessed within your app's settings, by those who have installed your app. Common use cases include:

• Exposing a login for an external system
• Providing an interface to toggle optional features
• Allowing the user to update configuration settings

App Prerequisites

• Your app must be configured with a signing secret

How it works

High level flow

• Seismic makes a POST call to the Url provided in your app configuration
• You respond with HTML
• Seismic displays the HTML within your app's client-facing configuration.
  • If your app is not enabled in the tenant, it will prompt the user for consent to view the configuration page

When it's triggered

When an administrator accesses your app's configuration page within their tenant's My Apps page, your app will invoke a POST request to the URL provided within your app.

Security & Authentication

It is recommended that you validate the Signing Secret in the POST request that Seismic is making to your URL

How to Configure

Configure the UI Extension Point

• Add UIExtension to your application as described here
• Fill out the Extension fields
• Extension Instance Name - A Name that references this usage of this extension point within your app
• Type field: Select a location for your HTML to be shown
  • The location of the iFrame is determined by the "Type" field. Currently, "configuration" is the only available option
• Url field: input a URL where your app will receive the POST request
  • The Url must be publicly available, not behind authentication or firewalls
• Click Save Changes
• Make sure to enable the extension point and click Save Changes

Payloads

Outbound

POST to the Url provided in your app configuration. The payload contains a signing secret, basic app details, basic user details, and basic request details.

{
    "appId": "fcdd244c-1cce-4e6b-aad9-7e6820a99a20",
    "appName": "sampleApp",
    "tenant": "mytenant",
    "tenantId": "b061ad37-1f5a-4531-b7d3-89807dccca68",
    "userId": "e6f77acb-6f11-482c-822b-5dbdcc002a20",
    "userEmail": "[email protected]",
    "language": "en-US",
    "requestId": "8709b156-b0d2-45fe-a43c-8aff052af56f",
    "version": "0.1.1",
    "timestamp": "2020-09-08T14:55:06Z"
}

Inbound

The expected response is any HTML that will be displayed within the configuration tab

<h1>Hello World</h1>
Good bye world

Generic Troubleshooting for Apps with Extension Points

• Ensure your app is configured with a signing secret. This is needed more often than not.
• Ensure the extension point is enabled within your app
• Ensure the tenant has the latest or correct version of the app. Sometimes this means pasting your Distribution Link into your browser to re-install the app
• If Seismic is expecting a response from your service, ensure it is responding within the correct amount of time