Overview

External Actions are a key point of integration for Signals. External actions can be configured for many entity's within Signals. When setup, they make URL requests (utilizing either GET or POST submit methods) to your External Server or other configured URLs. This is used to enable custom workflows extending the functionality of Signals for end-users. Basic identifier information, typically an Entity's ID, about where the External Action was kicked off from is included in the URL parameter (for GET submit methods) or the request body (for POST submit methods).

When administrators configure External Actions they are able to set specific icons/buttons to be added to the user interface for the end-user to interact with and kick off an External Action.

For example a common use case for this functionality includes sample registration with your company's external restoration system. Once an Administrator has setup an external action for a Sample Entity:

1. The end-user clicks a "register" button.
2. A webpage opens that has the Signals Sample Entity ID passed to it.
3. Signals APIs are called to pull key information about that sample.
4. The webpage is used to register the sample with your company's external registration system.

NOTE:  Always be aware of the security in place on your externally managed websites. External Actions in signals are simply redirecting to the provided URL and any one with the url has the same access. Signals has no way of knowing who is accessing your external sites as they are outside our domain.

 

Authentication

When using external actions you should always have well defined authentication in place.

Users must verify the identity of those accessing their externally managed sites via credentials, VPNs, or on premise intranet access to their hosted pages used with External Actions. These sites are outside of Signals domain.

External Actions should make use of the Bearer Token Exchange in order ensure the access to the Signals APIs securely and with respect to their Signals user permissions when interacting with Signals via your company's external page. 

 

Basic Authentication Pattern for External Actions

In our basic External Action authorization pattern we see the External Action coming from Signals opening the URL provided for the External application. Upon opening the URL the following takes place.

1. External URL Authorization:

The URL requests user authentication/authorization as needed for secure access to your external systems.

This likely through the use of user credentials managed by the external system.

If the user is already behind a secure firewall, directly or indirectly via VPN on a company intranet, or otherwise authenticated, this step may be skipped.

NOTE: It should be noted that Signals is secured via IP whitelisting. This is to ensure secure access no matter where a user is accessing Signals from.

2. Bearer Token Exchange:

Once authorized the user should be redirected to the bearer token exchange flow as described here.

This will prompt a user to login with their Signals credentials and upon success redirect the user to the configured redirect_url along with the users bearer token. If utilizing SSO the need to enter credentials again will be governed by the company identity provider.

3. External Website:

The External service now has access to a bearer token obtained from Signals for the authenticated user.

The external tooling can make use of the Signals REST API as the authenticated user via the bearer token.

This architecture ensures secure access to both the external service and Signals.
 

Setup

As an administrator you can enable External Actions. Once enabled, actions will be available via the user interface or during signing events as configured.

A setup guide for External Actions is included in the System Configuration Guide

Additional Technical Details for External Action Setup

GET Submit Method

During setup you choose a name to be passed as as a URL parameter. The identifier of the entity the external action is setup for will be used as the value. The default parameter is __eid.

Example of an External Action URL for an Experiment entity: 

https://yourapplication.com/?__eid=experiment:03ae2d17-e94d-466a-ba83-94d89a3cea2f

In this example the url set for your External action is https://yourapplication.com/. The parameter name  set during setup in the example is __eid and the value passed is an experiment entity identifier, experiment:03ae2d17-e94d-466a-ba83-94d89a3cea2f.

POST Submit Method Form Data Example

Below is an example of the form data that is sent when using HTTP POST as your submit method for a Admin Defined Table entity.

{
  "data": {
    "id": "grid:8a9b9331-6e40-403f-9b9b-feba83ff0e57",
    "type": "grid",
    "attributes": {
      "name": "Data Table",
      "description": "",
      "createdAt": "2024-01-10T17:06:55.326Z",
      "modifiedAt": "2024-01-10T17:07:05.945Z",
      "digest": "76541692"
    },
    "relationships": {
      "createdBy": {
        "data": {
          "id": "100",
          "type": "user"
        }
      },
      "editedBy": {
        "data": {
          "id": "100",
          "type": "user"
        }
      },
      "ancestors": [
        {
          "data": {
            "id": "journal:b3f1335e-e52d-4cc0-832f-90bdb8b8d2fb",
            "type": "journal"
          }
        },
        {
          "data": {
            "id": "experiment:9247c379-a6bb-4b8c-8c79-423901d63343",
            "type": "experiment"
          }
        }
      ]
    }
  }
}

For actions on Folders the data object will contain an array of similar objects to above for each entity in the folder selected.

 

Additional Configuration and Triggers

Most external actions allow for two basic configurations:

1. Opening your provided URL in a dialog, when not selected the URL will open in a new browser window
2. Requiring write access to use the External Action

By default External Actions are triggered via User Actions and is the only available trigger for External Actions. 

Additional configuration and triggers for specific entities are described below:

Entities with Signing Workflows

Entities with signing flows (Experiments, Parallel Experiments, and Admin Defined Objects) will have the additional trigger Signing Event available with the option to choose one or many different signing events to trigger the External Action.

 

Entities with Required Templates

For Entities which utilize templates, such as Tables and Worksheets, you will be given to the option to Apply to all template or specify which templates to make the action available to.

 

Samples

For Sample entities you can specify which statuses to make the External Action available to.

Folders

For Folders you can specify which folders to make the External Action available to.

NOTE: External Actions for Folders must use HTTP POST as the submit method.

 

External Action Messages

When the External Actions make use of opening in a dialog, it sets up an event listener and waits for message events containing certain commands. They are issued via the JavaScript window.postMessage() method available in virtually all browsers. These commands are used as methods of controlling the size of the dialog, the title of the dialog, and importantly acting as a means of flow control through use of statuses returned to Signals indicating if an entity should be refreshed or for signing flows if they should continue or be abandoned. The posting of these message must be setup in your external site.

Each command consists of an array with two parts: first, a command name from the list of supported commands; and second, an array of arguments. 

The generic structure of a command is:

['commandName', [{optional args}]

Commands are issued by calling the postMessage() method on the modal’s parent window, which can be accessed via window.parent. To issue the command above, you would call:

 

window.parent.postMessage(
['commandName', []],
'https://snb.example.com/'
)

The second argument to postMessage is the origin (scheme + domain + optional port) of the receiving window, and ensures that the command is sent only to Signals Notebook.

Supported commands

For example these messages are often used during Signing Event triggers for Experiments. When a user attempts to sign and close their Experiment the configured External Action may use the API to check for specific fields. If they exist you would post the following message:

window.parent.postMessage(
['closeAndContinue', []],
'https://snb.example.com/'
)

This would result in the signing event completing successfully and allowing the next steps, if any, to take place.

If the specific field was missing you would post the following message:
 

window.parent.postMessage(
['closeAndAbort', []],
'https://snb.example.com/'
)

This would result in the signing event being aborted returning the end-user to whatever state the Experiment was in before attempting to sign.
 

Example Architecture

In our example architecture below we will look at a simplified architecture of an integration layer that handles External Actions. In this example Signals is configured to enable an External Action on Experiments triggered by a User Action. The purpose of the External Action is to open your hosted web site (and after proper authentication allow the user to lookup a project code using internal tooling and subsequently update a field on the Experiment with the project code.

In this simple architecture your external site simply reads the experiments entity ID from the External Actions URL parameter, allows the user to make use of the project code lookup, and when complete sends the chosen project code down to Signals via the REST API