Custom Widgets Using Node.js — Poll Method

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:

Our Goal

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.

Back to top

Getting Started

Widget Set Up

We know now what we want to see on our dashboarda 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:

You can find the payload format for this widget and other Custom Widgets in our Developer API.

Back to top

Tools Needed

If we again consult the Flowdock REST API, we find that we can use a personal API token or OAuth for authentication.

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

 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.

Back to top

Application Design

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'.

We then initialise our payload as an empty array, parse the 'flow' from JSON into a JavaScript object, and then check for every user that has a 'last_activity' value less than ten minutes ago. If they do, we add it to our payload.

Finally, we reply to the Geckoboard request with our built up payload of the users, converted from a plain JavaScript object to JSON. 

Lastly, we tell our app to listen for requests.

Here it is all together:

Back to top

Was this article helpful?

Thank you for your feedback!