Overview

In this guide, we’ll walk you through creating your first Custom Report by connecting to an open REST API. Follow these simple steps to set up your datasource, fetch data, and display it on your dashboard!

Open REST API: https://randomuser.me/api/?results=3

Open

Add a Datasource

1. In the Custom Reports dashboard view, click .

2. Click Add datasource (New to datasources? check Learn about Datasources).

3. Provide a meaningful name for your datasource, such as Random User - No Auth for this example.

4. Enter the API endpoint URL in the provided field https://randomuser.me

5. Set Authentication type: No Auth for this example. To understand each authentication type more thoroughly, see Authentication types in Custom Reports datasources.

6. Click Add.

Add the Custom Reports gadget

1. Navigate to your Dashboard Hub app.

2. If you have not created a dashboard,

   1. Click the dashboard dropdown in the left corner or in the action menu in the right corner, and select Create dashboard.

   2. Name your dashboard, and click Create.

   3. Click Add Gadget.

3. If you already have a dashboard created, click Edit.

4. Click Add Gadget.

5. Type Custom Reports in the search bar in the gadget catalog, or navigate to the Custom Reports section in the left side navigation panel.

6. Locate the Custom Reports gadget, click Add, and click Open Editor.

Example: Random people in a table

Copy the JSON content in the following code block on the right. This simple report displays three random people in a table with three columns.

How it works

1. Data Fetching

The REST API at https://randomuser.me/api/?results=3 returns a JSON object containing random user details.

The uri section starts with datasource://random_DS, which is the name we use to refer to our datasource field, and following, the rest of the URI /api/ .

Then we use a query param ?results=3 to return from that API just 3 random users.

2. Data Parsing and Display

The gadget processes the returned JSON and extracts the results array.

A node type: 'table' is generated with three columns:

• The column Name displays the user’s picture and full name (title, first, and last).

  • header: 'Name'

  • src: '{picture.thumbnail}'

  • '{name.title} {name.first} {name.last}'

• The column Age displays the user’s age.

  • header: 'Age',

  • cell: '{dob.age}'

• The column Country displays the user’s country.

  • header: 'Country',
    cell: '{location.country}'

The dot notation is used to traverse paths in the JSON response. Remember that JSON looked like the following:

Download this JSON response here:

Open

3. Style

You need to be familiarised with CSS to better style your reports, for example:

This is part of Flexbox styling (ref), commonly used in web development to define how elements are laid out and behave within a flexible container.

This sets the width of the image to 40 pixels, automatically adjusts the image’s height to maintain its original aspect ratio, and rounds the image into a circle by applying a radius of 50% of the image’s dimensions.