Introduction
...
Within HDX an organisation or location may only have one set of topline figures which will appear on its front page eg.
https://data.humdata.org/organization/ocha-afghanistan
At the top of the above organisation page are various statistics like “Conflict induced IDPs” and “Disease outbreaks”.
https://data.humdata.org/group/bwa
On the top left of this location are some numbers such as “Population, total” and “GDP per capita, PPP”.
Topline numbers for organisations come from data held in the datastore, whereas for locations the data comes from CPS. They can be read through the HDX api eg. https://data.humdata.org/api/action/hdx_topline_num_for_group?id=yem
Google Spreadsheet
Toplines should be stored in a Google spreadsheet in the “Secured Files” folder on the HDX Google drive is used instead eg. for Fiji’s data: https://docs.google.com/spreadsheets/d/1ObwjZNS8y_mdjNXjhPLSqi-YGtQxkCDIW3Vg2kpwjgs
To use a Google spreadsheet as a topline:
Export it as a csv by using File -> Publish to the web
Choose “Entire Document” and “Comma-separated values (.csv)” from the dropdowns
Click Publish
Copy the url which will be of the form: https://docs.google.com/spreadsheets/d/1ExKJOsFlZgVH-jvPc9DVwT3Gcusq7pLaxp7i2xnePDk/pub?output=csv
This url can then be used instead of a file import in a HDX resource
...
Column name | Description |
code | A unique identifier of the datum |
title | A descriptive name for the datum |
value | The value of the datum |
latest_date | The date when the datum was updated |
source | Some words stating where the datum came from |
source_link | A utl to the data that can be reached by the “Data” link of the topline |
notes | A description of the datum that appears when you hover over a number |
explore | A link to a visualisation but generally not used |
units | The units of the datum for display purposes eg. count, million, million_count |
Things to Look Out For
The code is not a generated unique identifier. It is just formed in some kind of logical way that is unlikely to conflict with other sheets eg. taking the acronym of the sheet’s title and adding a row number.
The value must just be an unformatted number ie. no separators
The units affects the display of value, for example a value of 3500000 with units of million will show as 35m
If there are insufficient rows (ie. not 4 or 8), one or more dummy rows must be put in eg. copy an existing row
...
- Log into Google spreadsheets using the user: hdx.gapps.triggers@gmail.com from Logins /wiki/spaces/HDX/pages/38551804. See Google Apps Triggers for more about permissions needed.
- Go to the menu Tools -> Script Editor in the spreadsheet. This opens a new script editing window.
- Name your script something descriptive eg. "OCHA Afghanistan Topline Resource and Datastore Triggers"
- Copy the code below into the Code.gs tab, replacing the values of the variables in the top 3 lines (resource_id, api_key, server_type).
- Then go to the Resources menu and select Current Project's Triggers.
- Click on the link which says "No triggers set up. Click here to add one now." and set it up as follows using the dropdown menus: Run: doOnEdit Events: From Spreadsheet | On edit
- Click notifications and from the Execution failure notifications dropdowns, choose the hdx.gapps.triggers@gmail.com email you want to use and set when to notify as "immediately".
- Create another trigger and set it up as follows using the dropdown menus: Run: doOnTimer Events: Time-Driven | Minutes timer | Every minute
- Click notifications and from the Execution failure notifications dropdowns, choose the hdx.gapps.triggers@gmail.com email you want to use and set when to notify as "immediately".
- A prompt may appear asking you to grant permissions to the user hdx.gapps.triggers@gmail.com which you should.
...
To set up a topline like requires that there be a dataset (by convention named something like “OCHA Afghanistan Topline Figures”) containing the appropriate data in the right format. An example of such a dataset can be found here: https://data.humdata.org/dataset/ocha-afghanistan-topline-figures.
Specifically the resource that is a csv entitled topline_figures contains the fields that are used.
...
You edit the organisation (Admin -> Edit in GUI or direct link eg. https://data.humdata.org/organization/edit/ocha-afghanistan)
Select “Use custom organization page”
You scroll down to “TOPLINE NUMBERS”
The “Resource ID” can be found from previewing the correct resource (eg. the csv) and taking the text after “...resource/” in the url eg. “ca6a0891-8395-4d58-9168-6c44e17e0193”
...