Important Note: Our new Datasets feature improves on and replaces the majority of Custom Widget use. Custom Widgets are still available, but are no longer receiving updates or improvements.
Custom Widgets Using Node.js — Poll Method
This is guide covers creating a Custom Integration using Node.js with the Poll method.
For part one see: Custom Widgets Using Node.js — Push method.
For a language/platform agnostic overview, see our Custom Widgets article.
In part one, we connected to Flowdock (a team chat application) and pushed data from it to a widget on our dashboard.
This time we will again connect to the Flowdock API but we will instead create an application that provides an endpoint for our Geckoboard widget, which will be set up using the Poll method.
This means that Geckoboard will send a request to the URL that we define and our application will respond with the widget data.
In this article:
In our previous example, we connected to the Flowdock API and watched for hashtags in messages. Every time a certain hashtag was mentioned, we increased the value on our Geck-o-Meter.
If we send a curl request to a flow, we can see that it returns, among other data, an array of users. Each element of the array contains data about the user, including a 'last_activity' property.
We then decide that we would like to have a List widget on our dashboard that displays all the users in our Development flow that have been active in the past ten minutes.
Widget Set Up
We know now what we want to see on our dashboard—a List of users active in the past ten minutes. We can now begin to set up our widget. Click on 'Add Widget' on the top right corner of the dashboard. Then select 'Custom Widgets', and finally 'List'.
In order to point the widget to our application, we need to host it. You can provide your own hosting, or use a service. See this guide for how to use Heroku, a free service, to host your Node.js application.
Let's look at the format for a List widget payload:
We will again use a personal API token in favor of OAuth for the sake of simplicity, as well as that our application has no front face web interface, i.e. it will remain on the back-end.
You can find your Flowdock Personal API token at https://flowdock.com/account/tokens.
Getting the Data
In our last example, we used the Flowdock 'flowdock' npm module to connect to the Flowdock API and watch for the data we were interested in.This time we can design our application in a slightly different way.
Geckoboard will Poll our application at the interval we configure in the widget set up. We will use the 'express' module to receive and reply to requests to our application. Each time a request is sent to our application, we will use the 'request' module to send a request to the Flowdock API endpoint for the flow we want data from, and then use 'express' to pass it back to Geckoboard.
We can now design our application.
Here we require the 'express' module and create a new application with it. We also require the 'request' module and set the port of our application to the system's environment port if (or 5000 if there is no system port set).
We also define the URL to where we will send a request to the Flowdock API.
Now we define a route in our 'express' application, meaning that each time a request is sent to the route, we want to do something in response.
Here the 'something' is to use the 'request' module to send a request to the Flowdock API with a callback as the second argument. In the callback the flow information is passed as 'flow'.
Lastly, we tell our app to listen for requests.
Here it is all together: