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.
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:
Once we click 'Create', we should see a new folder populated with Connector files. Let's locate the
_definition.yaml file end edit it:
_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
ApiKey as well as three custom 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.
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:
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:
After you finish inputting the data create the Connector.
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:
Now we need to trigger our Connector. The easiest way to trigger is to navigate to Development → API Documentation and locate our Connector there:
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:
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:
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:
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:
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> </div> </div>
The final result: