In this tutorial we'll be hooking up functionality to allow importing DNA Sequences from your database or system of choice into the TeselaGen Design module. The end goal is to be able to use the button below, Sequence Library > Import From External DB:
Note: You'll need to be an ADMIN to follow along with this tutorial.
If no External Systems have been connected, when clicking that button the user will see this message:
Settings > Integrations
So, let's go ahead and set up the Import Integration for DNA Sequences from App Settings > Integrations Management! Please note, only admin users can set this up and modify this functionality. Once you're on the following page, go ahead and click "Add" under "Import" to begin adding a new integration:
Here's what the "Create Import Integration" dialog looks like:
We'll start by giving our endpoint an accurate name. In this case I'll use a fake company name, FakeSeqDepot who we'll assume has a pre-existing API that we'll be connecting to.
We'll leave "Node Red Connected" checked and add a unique prefix of fake-seq-db.
We'll also leave the Subtype as DNA_SEQUENCE:
This integration is composed of 3 endpoints, the Format Endpoint, the Search Endpoint and the Import Endpoint. You can see these dialogs at the end of this tutorial.
The Format Endpoint can be used to ask additional questions before the search.
The Search Endpoint will power the sequence search dialog
The Import Endpoint will handle actually importing the sequence.
Let's hit Create now that we've filled in all the necessary information for this first dialog. You should see a message like so:
Go ahead and click the blue node-red integration link we've outlined in red above. You can also jump to the node-red integration from the newly created line item in the Integration Settings Page:
Editing the Node Red Server
Clicking either link should jump you into the node-red server:
Notice that the tab we're on should have 3 endpoints already set up inside of it. There is one for Format, Search and Import!
Let's zoom in on the Format endpoint:
Let's open up the "Helper Fn" by double clicking on it. We should see the side panel pop out like so:
As you can see above, the Helper function is already pre-populated with an example payload, and example payload response.
Let's edit the response slightly to add an extra status of "Still Workin' On It":
Once we hit Done,
We can hit the red Deploy button at the top right to update the node-red server:
After it successfully deploys, let's go try out our new integration by going to the DNA Sequences Library > Import From External DB > FakeSeqDepot:
As you can see, the new option we just added shows up:
Awesome! For more info on different field types you can use for your custom form, see here:
You can continue going through the flow and it should already be able to import an example sequence. To do any meaningful work, however, you'll need to hook up the search and import endpoints to the API you're interested in.
Connecting the example flow to a (fake) API
Zoom in on the Search endpoint:
For the search endpoint to communicate with an external API, we'll need to hook it up to an http-request.
Drag in an "http request" from the side panel:
And duplicate the Helper Fn. Connect these new nodes so it looks like so:
This is the general layout that most endpoints will follow:
http-in --> function to massage data for request --> request to external api --> function to massage data back to teselagen standard --> http-reponse
I've set up a fake endpoint we can use to mock the api. You can see it here or try it by running:
Double click the http request node to edit it, and set the URL to https://raw.githubusercontent.com/tnrich/tg-fake-apis/main/FakeSeqDb_search.json
and make the return value be "a parsed JSON object"
We'll need to convert the mock api response to the expected response outlined in the integration. Double click the 2nd "Helper Fn" and update it to process the api response. Let's also rename it to be SearchApi -> Tg:
Finally we add the http-response node as you can see chained above. Once we hit Deploy we can start communicating with the FakeSeqDepot search endpoint. If we test it out we should see a new response from the 2nd step of the Import From External Database dialog:
Nice! Setting up the actual import endpoint is much the same. I'll link to a fully set up example flow that you can upload below.
Uploading the full example
Navigate to Settings > Integrations
First make sure to delete your existing FakeSeqDb integration and its associated node-red flow (you'll be prompted to do this from when deleting it).
To import, download this zip file and unzip it. Upload the JSON file here in Settings > Integrations:
If you forget to do the previous step, you might encounter this warning:
That is just to let you know if the node-red flow you're importing has http-in nodes with the same url.
Assuming all goes well, you should see FakeSeqDb reappear in your list of integrations
And if you click View in Node Red, you should see the updated node-red flow:
The green nodes are just debugging nodes to console log the msg object out. You can watch them get hit as you run through the integration by clicking into the debug tab:
Node-red docs https://nodered.org/docs/
Intro to the node-red server: http://docs.teselagen.com/en/articles/4333346-node-red-integration-server
More info on custom form inputs: