Custom Widgets Using Node.js — Push 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 — Push Method


This is guide covers creating a Custom Integration using Node.js to Push data to your dashboard.

For part two see: Custom Widgets Using Node.js  — Poll method.

For a language/platform agnostic overview, see our Custom Widgets article.

Introduction

For this example of creating a custom Integration, we will connect to Flowdock, a team chat web application. We will get data from Flowdock, format it in a way Geckoboard expects, and push it to a widget on our dashboard.

In this article:

Our Goal


Flowdock has what are called 'flows'. Each flow is a chat room or channel with a specific topic or focus.

When we access the Flowdock API, each message that is sent comes with a layer of information around it. In this message layer is an array called 'tags' that has identified all of the hashtags used in a message.

We decide that we want to create a Geck-o-Meter that gauges how often the hashtag '#awesome' is used in a day in our Development flow.

Thus our goal is that each time an '#awesome' hashtag is used, the needle on our Geck-o-Meter will rise and the value will increase.

Back to top

 

Getting Started


Push URL and API Key

Push widgets send their data to a unique URL that is given in the widget set up. Since we want to Push to a Geck-o-Meter, we should then add it to our dashboard, and choose Push for the method. We will take note of this URL to use in our application.

We will also need our Geckoboard API key. This is found by clicking your avatar at the top right corner of your dashboard and choosing Account Settings.

 

Payload

Each time our application sends data to Geckoboard, it will send it as a payload, structured like this:

Where "example-api-key" is your unique API key, and the value to the 'data' property is the widget data.

In this case we are using a Geck-o-Meter, which is formatted like this:

And all together, like this:

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

 

Pushing to the Widget

After you have set up your widget on your dashboard, you can test it by Pushing data to it with curl. Here's how this would look for a Geck-o-Meter (replace the URL with the widget's unique Push URL and 'example-api-key' with your API key):

If all goes well you should see {"success":true} from curl and your Geck-o-Meter on your dashboard should now read a value of 23.

Back to top

 

Tools Needed


Consulting the Flowdock REST API, we find that we can use a personal API token or OAuth for authentication. We will use a personal API token in favor of OAuth for the sake of simplicity, as well as that our application has no front facing 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.

Here we will use Flowdock's own npm module 'flowdock' to create a streaming session to our Development flow.

For Pushing our data to the widget on our dashboard, we will use the 'request' module.

We also need the ID of the flow that we want data from. We can use curl to find this:

Where :organization is the name of our organization, and :flow is the name of the flow. This returns a JSON object, the first property of which is 'id'.

Back to top

 

Application Design


We can now design our application.

Here we initialize our variables, including our Flowdock personal API token, the Flowdock flow ID, and create a new session and stream based on these values. We also initialize the start time and define the hashtag we are looking for.

We also define our Geckoboard API key, and the Geckoboard Push URL for the widget, as well as our payload with the Geckoboard API key and the Geck-o-Meter.

As well, we define the Geck-o-Meter and payload as plain JavaScript objects so we can easily update the values. We will convert it to JSON when we are ready to push it to the widget.

Now we watch for the tags in messages. If it has been less than twenty-four hours, pass the array to a function that checks for our hashtag. Otherwise, reset the time and the count, then pass the array to check for our hashtag.

Now push the data to the widget using 'request'. Since we defined our payload as a plain JavaScript object, convert it now to JSON. If there is an error, log it to the console, otherwise return Geckoboard's response.

Here is the code all together:

The meat of importance here is that we are using the 'request' module to push our data to the widget to its Push URL. This can be accomplished using other modules in other ways, but overall the approach will be similar: gather the data, format it to what a Geckoboard widget expects, and push it to the widget's Push URL.

Back to top

Was this article helpful?
👍

Thank you for your feedback!