How to create a Connector

In the previous guide on how to create a card with Node.js proxy we showed how you can integrate data from a third-party API to show weather in Boston. However, what if we wanted to reuse the same API for multiple Cards? We could duplicate the code, however this would incur an overhead in code maintenance. If the API changed we'd have to go through every single Component using that API and change it, which could be quite tedious.

Luckily, Digital Assistant provides an elegant solution for managing your API's through Connectors. In this guide we're going to recreate the API for fetching the weather information in Boston, however this time we're going to use a Connector.

Creating Connector template

First of all we will create a new template that we'll use to create new Connectors. We'll start by navigating to the Connectors folder in Development → Manage Spaces → Global → Connectors, where we'll create a new folder for our weather Connector. We're going to use a template with custom authorization, since we don't need OAuth 2.0 in this instance:

Create a new Connector

Once we click 'Create', we should see a new folder populated with Connector files. Let's locate the _definition.yaml file end edit it:

Find _definition.yaml file and edit it

Within _definition.yaml we can set which fields are going to be required, optional or hidden when creating a new Connector. Additionally, we can set custom fields that our API might need. In this case, we're going to set the ApiEndPoint, ApiKey as well as three custom fields:

Set connector template fields

We've also added a label and a hint to our custom fields. Click 'Save' and now we're ready to create our Connector.

Create the Connector

Now we're going to create a new Connector using the custom template we've just created. To create a new Connector let's navigate to Content Manager → Service Connectors and click on 'Create New Connector'. After we enter the name and title, we'll set our Connector Type to be our custom template:

Set the Connector type to be custom template

After selecting the type you should see the fields that we've defined in the template such as the Api Key, Latitute, etc. Using a template allows us to create a new Connector by defining the data that we wish to retrieve without the need to hard code it into the Card's logic. Since we're creating a weather Connector for Boston, we're going to enter Boston's latitude and longitude as well as our API key:

Enter the details for the Connector

After you finish inputting the data create the Connector.

Construct and test the request

Now our Connector has the data, however we still need to configure the Connector's template to use it. A Connector can have multiple scripts e.g. to search, to retrieve a specific record, to post a message etc. But by default it contains one script named proxy.js. Connectors that will use our template will pass their data into this file whenever they're called. Therefore, we need to construct a request that will use the data passed from the Connector to send a request to the weather API.

We're going to open the weather Connector template's folder in VS Code and we'll create a break point in proxy.js file to see what data gets passed:

Create a break point in proxy.js

Now we need to trigger our Connector. The easiest way to trigger is to navigate to Development → API Documentation and locate our Connector there:

Locate the Connector

Expand it and click 'Try it out!'. The request will fail, but that's fine because we only want to trigger our break point to see the data. If you look back at VS Code you should see that your break point was triggered and you can inspect the variables on the top left pane. Specifically activity.Context.connector will hold the variables we set for our Connector:

Inspect the variables

We'll replace the API request URL with the following string to ensure our weather API gets called with the right credentials:

const response = await api(
     activity.Context.connector.endpoint + '?' +
    'lat=' + activity.Context.connector.custom1 + '&' +
    'lon=' + activity.Context.connector.custom2 + '&' +
    'units=' + activity.Context.connector.custom3 + '&' +
    'appid=' + activity.Context.connector.apikey

Save the file and if you click 'Try it out!' again you should see that you're receiving data from the API:

The API is now returning the dat

Adding the Connector to the Card

Now instead of using a Node.js proxy, we're going to create a new Card that will use our Connector instead. Let's navigate to Development → Manage Spaces → Global → Components and click on 'New Component'. We're going to create a new Card, which will use our newly created Connector:

Create a new empty Card that uses our Connector

To connect the Connector please make sure you select it from the Connector dropdown and set the Service, which in our instance will be the default API Proxy service.

Then, we'll navigate to the Card's Designer and in the Settings tab we should see the data from the API in the Preview data window:

Data in the preview

If you don't see the data in the preview or it shows your ip address instead, try to navigate to the Preview tab and back. This will force the Connector to make a new request, which should update the preview window.

Next, we'll use the data from the API and insert it into our Card's template:

<div class="layout-horizontal p prsm">
  <div class="font-body1 layout-self-center layout-flex">
    <p>City: </p>
    <p>Temperature: </p>

The final result:

The final result