Skip to main content
All CollectionsRegistry Toolkit (DESIGN Module)
External Integration: DNA Sequence Import
External Integration: DNA Sequence Import

How to hook up Sequence Import to an external API

Thomas Rich avatar
Written by Thomas Rich
Updated over a month ago

Contents of this Article

The DNA sequences library allows several ways to upload new data.

In this tutorial, we'll be hooking up functionality to allow importing DNA Sequences from your database or system of choice into the TeselaGen Molecules Toolkit. 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:

Integration Settings

So, let's go ahead and set up the Import Integration for DNA Sequences from App Settings > Integrations Management! Please note that 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.

There are many different Import Subtypes to choose from:

But we'll go ahead and 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.

Each endpoint has an Example Request and Example Response (if applicable) detailing what the node-red endpoint expects in the request and what the node-red endpoint should return:

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:

As you can see, there is a Format Endpoint http-in that receives the incoming request, a Helper Fn that allows us to execute arbitrary javascript code, and a Response http-out node that is responsible for completing the request.

Let's open 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:
​http://docs.teselagen.com/en/articles/4626993-custom-form-inputs-integrations

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 an 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-response

I've set up a fake endpoint we can use to mock the API. You can see it here or try it by running: 

curl https://raw.githubusercontent.com/tnrich/tg-fake-apis/main/FakeSeqDb_search.json

Response:

{
    "pageLength": 25,
    "seqs": [
        {
            "title": "someSeq",
            "uuid": "w2f343g"
        },
        {
            "title": "anotherSeq",
            "uuid": "28992hf2"
        }
    ],
    "allResults": 77
}

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 "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 in the chain 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 when deleting it).

To import, download this zip file and UNZIP it. Upload the unzipped 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:

Additional Resources

Did this answer your question?