Working at TeselaGen, we've found that researchers often need their workflows to connect across multiple different systems and that custom "glue" code is required for each use case. Instead of having all of that glue code live directly in our codebase, we've created a set of integration points in our app that allow for arbitrary interactions with external systems to take place.

Note: You'll need to be an ADMIN to follow along with this tutorial.

Where to find integrations

These integration points live in the settings under Settings > Integrations:

There is a growing list of integration types:

  1. Import

  2. Export

  3. Custom Info

  4. Update *wip*

  5. File To Datatable

  6. Custom Worklist

Integration Structure

Each Integration consists of a Name, a sometimes optional Subtype, configurable Headers, and a set of one or more Endpoints (some of which may be optional).

For example, here's what the Create Import Integration Dialog looks like

Endpoint Structure

Each endpoint is responsible for doing one specific task and has a well defined and validated request/response structure. Let's take a closer look at the Import > Search Endpoint. This endpoint takes in a search term and returns a paged list of results. The results can be paged by numbers or tokens:

As you can see above, we can input a URL. This URL will need to conform to the specified request/response format. If any fields are missing or incorrectly named, we will throw a descriptive error.

Because the API of the external system you're connecting to is unlikely to match the required format, most of the time you'll want to set up some "glue" code in node-red to massage the data going between the Integration Endpoint and the external system.

Thankfully, URLs that already exist in the node-red server will be autocompleted if they match the request type. You can learn more about the node-red server here http://docs.teselagen.com/en/articles/4333346-node-red-integration-server. For a full example of setting up a DNA import integration click here: http://docs.teselagen.com/en/articles/4332711-external-integration-dna-sequence-import

Where The Integration "Shows Up"

The UI that each integration powers is slightly different. For example, when a new Import Integration is created, it will show up in the user's library for that particular subtype (dna/amino acid/etc.):

Yet, for example, a Custom Info Integration will show up as an option on the record right click:

A description of each Integration and where its UI will appear can be found in Settings > Integration

More Info

For more info about node-red http://docs.teselagen.com/en/articles/4333346-node-red-integration-server.

For a full example of setting up a DNA import integration http://docs.teselagen.com/en/articles/4332711-external-integration-dna-sequence-import

For an example of how to show custom UI within certain integrations (advanced) http://docs.teselagen.com/en/articles/4626993-custom-form-inputs-integrations

Did this answer your question?