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:

If no External Systems have been connected, when clicking that button the user will see this message:

So, let's go ahead and set up the Sequence Import Integration 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 "Sequence Import" to begin adding a new integration:

Here's what the "Create Sequence 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.

As you can see above, this integration is composed of 2 endpoints, the Search Endpoint and the Import Endpoint. The Search Endpoint will power the sequence search dialog and the Import Endpoint will handle actually importing the sequence. You can see these dialogs at the end of this tutorial.

It is unlikely that FakeSeqDepot's API's map directly to the endpoints that we expect. To handle that mapping, we'll be writing "glue" code inside of Teselagen's Integration Server. Let's open up that:

Clicking that button should open up the node-red integration server:

Using node-red you should be able to configure the "glue" code you need to connect to the API of you choice.

Let's go ahead and see how to set up the sequence-search endpoint in node red. First we need to see what the request and response JSON is expected to look like:

Next we'll need to start adding nodes to node-red to match this endpoint. We'll start with an http-in node. Grab an http-in node from the left hand panel and drag it into the editor anywhere. Double click on the node to begin editing it:

We'll need the route to be a POST to match our endpoint, and let's make the url "sequence-search":

Once we hit done, we can hit the red Deploy button at the top right:

After it successfully deploys, go back to Settings > Integrations Management and that URL should show up if we try to add a new Sequence Import integration (you may have to close and re-open the dialog to see it):

At this point we have an http-in node, but we still have to hit our FakeSeqDepot api. Let's say FakeSeqDepot has an API set up with a sequence GET route that looks like www.FakeSeqDepot.com/api/seqs?query=someSearch&page=X

We'll need to write some glue code convert our {searchTerm, pageNumber} json into the format that FakeSeqDepot expects. Let's wire that up using a "function" node:

As you can see above, I've dragged a function node into the flow, named it "Tg-->FakeSeqDepot", and connected the output of our sequence-search node to the input of the new node. A function node can take arbitrary javascript. Here's what we should put in ours:

By default node-red puts the body of any request onto the msg.payload. We'll need to add a .query property to the msg.req before passing it along to an http-request node.

Next let's add the GET request to the flow:

Set the method to GET and set the URL to www.FakeSeqDepot.com/api/seqs. We're passing the query params already in the function we set up above.

Next up let's again assume that the FakeSeqDepot returns a response that looks like:

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

We'll also need to convert the FakeSeqDepot response to the expected response outlined in the integration:

Let's add another function to handle the conversion. We'll call it "FakeSeqDepot --> 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!

Here's what the flow looks like in its entirety:

Now we need to set up the Sequence Import endpoint in node-red and finish configuring our Integration in the app. Here's what the import endpoint looks like:

Setting up the import endpoint should look very similar to our sequence-search endpoint. Here's what the final flow looks like:

As you can see, it looks very similar to the above flow. This time however we're making a request for a sequence with a particular uuid to /api/seqs/{id}. We'll still need functions on either side of that request to convert between our format and the format that the FakeSeqDepot expects.

Once we've hit deploy, we can finish filling out our Integration and try a request against it in the app.

Here's what the finished integration looks like:

Now we can hit the Import From External DB button from the DNA Sequence Library:

Let's choose our new Integration that we just set up:

Now when we hit Search, a request will be made to the node-red endpoint we specified in the Integration setting. Let's see what happens when we submit our search.

The next page in the dialog tries to load for about 30 seconds and then shows this screen:

It makes sense we would see an error because we are attempting to hit a fictitious API. If we flip over to the node-red tab, and hit the debugger icon in the top right corner, we should see this info displayed:

Node-red is letting us know that the GET request we're making to the FakeSeqDepot failed with an ENOTFOUND error! The node after it that tries to map() over the returned data has failed as well!

Let's fix this by removing our fake request and just return fake data instead. Instead of making you fix it all by hand, here's a JSON file that you can import. Unzip it, and upload the FakeFlow.json file to node-red (instructions here: https://nodered.org/docs/user-guide/editor/workspace/import-export).

After importing this file you should see a flow like this:

As you can see we've removed the http-request nodes in the middle of the flow. We've also added some green "debug" statements to log out what the payload coming in looks like. I've also added a red "catch" statement to catch any errors and route them to the http-out.

Take some time to explore the logic of the new nodes.

Delete the previous flow by Ctrl-clicking the "Flow 1" tab header and hitting "Delete". If you forget to delete our earlier flow the new routes won't be used because the old ones are still defined.

Hit the Deploy button to redeploy the new flow.

We can now go back to the app and re-try our import flow.

This time we should see 2 pages of possible sequences to download. Select a couple and try importing them!

Hooray! The import worked!

You can now find the sequences in your sequence library:

Additional resources:

The original flow we wrote together for the FakeSeqDepot

Node-red docs https://nodered.org/docs/

Did this answer your question?