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:
Import
Export
Update
Custom Info
File To Datatable
File To Datagrid
Custom Worklist
Twist Ordering
IDT Ordering
Integration Structure
Each Integration consists of a Name, a unique Endpoint Prefix, 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. I've added a name of TG Incubation Lab and an endpoint prefix of "tg-import":
Node Red Connected
We recommend leaving "Node Red Connected" checked, which allows you to enter an Endpoint Prefix that simplifies the set up of the routes and ensures your routes won't overlap with each other.
The endpoint prefix gets attached to each of the URL and will be used to set up the node-red endpoints the integration will be hitting against:
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:
Because the API of the external system you're connecting to is unlikely to match the required format, we'll set up boilerplate "glue" code in node-red that you can add onto to massage the data going between the Integration Endpoint and the external system.
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 > Integrations
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