Overview

Signals allows externally hosted data sources to be used in Tables for external data lookup and writing as well as externally hosted lists to be used as sources of data for attribute list items.

External Lists

This feature allows an Administrator to configure dropdown lists that are populated from external data sources.
 

External Data Sources

External Data Sources are used to populate the contents of a table row from a REST call based on a value entered into that table (i.e., GET method) or to push the content of that row to the service (i.e., POST & PATCH methods). Typical use cases for this include fetching the metadata of a bottle from an inventory based on a scanned barcode and updating the a table row with its data in an experiment.

Authentication

Both External Data sources and External Lists allow for a header value to be included that can include an API key to authenticate with the external source.
 

Limits

External List Source size and count limits

External Lists are limited to 20,000 items. Each tenant may contain up to 200 External Lists.

Response Time

To preserve the end-user experience the both External Data Sources and External Lists have maximum lengths in which they are expected to return a response.

For External Lists sources this is 30 seconds before timing out.

For External Data Sources this is 20 seconds before timing out.

 

External List Setup and Usage

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

 

Data format Requirements

Below is an example of what a properly formatted external list of animal species looks like. Each object in the data array can contain multiple items but will need to have one selected as the "key" during configuration. The "key" will be used to populate the list in Signals.

{
  "data": [
    {
      "type": "Cat"
    },
    {
      "type": "Dog"
    },
    {
      "type": "Mouse"
    }
  ]
}

To format your data to this specification will likely require an External Server. This external server would be provide the RESTful interface Signals interacts with and handle the formatting of your external data into the required JSON responses for GET requests from Signals Data Sources. Similarly it would allow for the formatting of data coming out of Signals when configured for POST and PUT requests and taking the appropriate action against your external data source.

 

External Data Source Setup and Usage

A setup guide for External Data Sources is included in the System Configuration Guide.

 

Authentication

During setup Administrators can include an API Key and header key name to include as part of the URL request made by Signals to retrieve data from the configured external data source.

 

Requirements

In order for Signals Notebook to connect to an external source url, the external site must provide a RESTful API.

Signals Notebook uses a standard RESTful convention for fetching, updating, and creating external resources that are represented as rows in Signals Notebook tables.

To format your data to this specification will likely require an External Server. This integration layer would be provide the RESTful interface Signals interacts with and handle the formatting of your external data into the required JSON responses for GET requests from Signals Data Sources. Similarly it would allow for the formatting of data coming out of Signals when configured for POST and PUT requests and taking the appropriate action against your external data source.

NOTE: For a brief description on REST APIs, please refer to https://en.wikipedia.org/wiki/Representational_state_transfer. 

NOTE: Please note that details on how to implement a RESTful API service are beyond the scope of this document.

 

Available operations and Examples

External Data Sources require a minimum of one operation for interacting with your External Data Source. This will determine the availability of fetching (GET), creating (POST), and updating (PUT) your External Data Source when used as a data source for an Admin Defined Table.

When the user fetches a row of data in a table, providing a key value, a GET request is made the the configured URL. For example if an External Data Source has been configured to fetch data about flasks used in the lab by their id with the additional configured fields being returned in the response:

 

Request URL

GET https://snb.example.com/flasks/88

JSON Response

{
  "id": "88",
  "name": "Flask A",
  "description": "This is fragile"
}

 

 

When a users wants to create a new row in the External Data Source, a POST request is made to the configured URL with a json body containing the data provided in the Table. 

 

Request URL

POST https://snb.example.com/flasks/

JSON Body

{
  "name": "Flask B",
  "description": "This is ceramic"
}

 

 

 

When a users wants to update a row in the External Data Source, a PUT request is made to the configured URL with a json body containing the data provided in the Table. 

 

Request URL

PUT https://snb.example.com/flasks/

JSON Body

{
  "id": "89",
  "name": "Flask B",
  "description": "This is metal"
}