Guide to using custom widgets

This article outlines how to get data from an external API into Geckoboard. You might choose this method of getting data into Geckoboard when the integration you would like is not already available, such as from your company’s own API.

There are however other ways to get data into Geckoboard, such as with CSV files or a spreadsheet, that are worth trying before using our Custom widgets.

Before you start

  1. Choose the data that you want to see on your dashboard and decide how you would like it visualized.
  2. Understand how to get that data from the datasource. For example, which endpoints do you need, and how is authentication handled?
  3. Decide which method (Push or Poll) is best, based on your development environment, application design, and datasource.
  4. Design how the data that you get back from the datasource should be transformed into the widget’s data.

Creating custom widgets using Node.js

Node.js is an open-source server framework and a useful tool for getting data from a datasource into your custom widgets on your Geckoboard dashboard.

Read our guide to creating custom widgets using Node.js.

Further reading

The process explained

This diagram explains the flow of data from the its source to your dashboard.Diagram_data_source_to_dashboard

Datasource

The data you want to see on your dashboard. This can be your own systems and databases, or a third-party/external API.

Your App

In order to use custom widgets, you need to develop an app that requests the data from the datasource, transforms it to meet the format Geckoboard expects, and then sends this data to Geckoboard.

Output

Your application needs to format the data from the datasource into the format the widget expects. Each widget type has a format defined in the Developer Documentation.

Your Dashboard

Your app then either sends the data directly to Geckoboard, or responds to a request from Geckoboard for the data that you want in the widget.

Push vs. Poll

There are two ways Custom widgets can receive data: Push and Poll methods.

The Push method means that your app sends the data directly to Geckoboard’s API. You are given a URL to send your widget data to.Push_method

The Poll method means that Geckoboard will send a request to the link that you give it, and expects your app to respond with the data for the widget.Poll_method

Tip

The biggest advantage of the Push method is that you can send data whenever you’re ready. For example, if you need to perform a long running task in order to get your data ready, using the Push method is best so that Geckoboard doesn’t time out waiting for the data (with the Poll method).

Create a new Custom Widget Poll widget

To create a Poll Custom Widget, follow these steps:

  1. Hover your cursor over the empty dashboard square you would like to position your widget and click the + button.

    Alternatively, click Add widget, located in the top right of your dashboard.
  2. Search for Custom Widgets using the Search sources field.

    Alternatively, you can also scroll down the alphabetical list of integrations until you reach Custom Widgets.
  3. Click on Custom Widgets legacy.
  4. For this example, we'll create a Line Chart. Click on Line Chart to begin setting up your widget.
  5. When the poll method is selected Geckoboard will periodically send a request to the endpoints specified on the widget and it expects to receive a response with a valid payload from your application.

    In order to do this, you'll need to copy the JSON payload from our Custom Widgets documentation and host it on Github as a gist. The code is:
    {
      "y_axis": {
        "format": "currency",
        "unit": "USD"
      },
      "series": [
        {
          "name": "GBP -> USD",
          "data": [
            1.62529,
            1.56991,
            1.50420,
            1.52265,
            1.55356,
            1.51930,
            1.52148,
            1.51173,
            1.55170,
            1.61966,
            1.59255,
            1.63762
          ]
        }
      ]
    }
    You can also use a service like Dropbox or your own website. The widget just needs to be able to access a link that hosts a file with data feed.
  6. Once you've saved the Gist, you'll now want to have a URL you can add to the widget that'll take it directly to the data.

    In Github, Click the Raw button. Now copy the URL in the address bar. This is the link you'll need from the widget to work.
  7. Return to the Line Chart configuration screen in Geckoboard. Paste the URL from in the URL Date Feed field.
  8. Set a Reload Time that makes sense for your widget.
  9. When you've finished configuring your widget, click Add widget.
  10. You'll now be taken back to your dashboard complete with your new widget.

    Note

    This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to programmatically update the widgets for you.

Create a new Custom Widget Push widget

To create a Push Custom widget, follow these steps:

    1. Hover your cursor over the empty dashboard square you would like to position your widget and click the + button.

      Alternatively, click Add widget, located in the top right of your dashboard.
    2. Search for Custom Widgets using the Search sources field.

      Alternatively, you can also scroll down the alphabetical list of integrations until you reach Custom Widgets.
    3. Click on Custom Widgets legacy.
    4. For this example, we'll create a RAG Column & Numbers widget. Click on RAG Column & Numbers to begin setting up your widget.
    5. Select Push in the Method field.

      The config window will now only show the the Push URL and Widget key fields.
    6. Click Add widget. You'll now be taken back to your dashboard complete with your new widget.
    7. Unlike the poll method, where data has to be exposed for Geckoboard to access it, the push API allows data to be pushed directly into our widgets and sent.

      Note

      The push API uses JSON exclusively. Additionally, files should not exceed 1 MB in size.

      In essence, to push data to your widget what you're doing is a post HTTP request with the correct payload to the URL specified in the widget configuration screen.

      In order to achieve this, I'll be pushing to a widget via cURL. Our Custom Widgets developer documentation includes an example on how to push data by cURL. This is the example:
      curl -X POST  https://push.geckoboard.com/v1/send/example-widget-key -d '{"api_key":"example-api-key","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"
    8. Hover your mouse pointer over the new widget. Click the more options icon in the top right corner to bring up the widget options.edit widget menu
    9. Click Edit.
    10. Copy the Push URL and replace the URL in the example cURL request.
      curl -X POST  https://push.geckoboard.com/v1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"example-api-key","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"
    11. Find your Geckoboard API key and and replace the example-api-key in the example cURL request.
      curl -X POST  https://push.geckoboard.com/v1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"568vrb67432f8767231c67d21c08e12a","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"
    12. Now we'll add our payload to the cURL request. As an example, we'll copy the RAG payload from our Custom Widgets documentation.
      {
        "item": [
          {
            "value": 16,
            "text": "Long past due"
          },
          {
            "value": 64,
            "text": "Overdue"
          },
          {
            "value": 32,
            "text": "Due"
          }
        ]
      }
    13. Then we'll add the payload to the cURL request.
      curl -X POST  https://push.geckoboard.com/v1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"568vrb67432f8767231c67d21c08e12a","data":{
        "item": [
          {
            "value": 16,
            "text": "Long past due"
          },
          {
            "value": 64,
            "text": "Overdue"
          },
          {
            "value": 32,
            "text": "Due"
          }
        ]
      }' -H "Content-Type:application/json"
    14. Now copy the request and paste it into your terminal window.

      Important note

      If you're using a Windows machine you'll need to escape all the quotes.

    15. If all is correct you'll receive a reply in your terminal client confirming that the push has been successful.

      Note

      This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to programmatically update the widgets for you.

Video resources

Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!

Sorry about that! Start a conversation now.