Get started with Custom Reports
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!
Add a Datasource
In the Custom Reports dashboard view, click the More actions ellipses.
Select Add datasource
Provide a meaningful name for your datasource, such as Random User - No Auth for this example.
Enter the API endpoint URL in the provided field
https://randomuser.meSet Authentication type: No Auth for this example. To understand each authentication type more thoroughly, see Authentication types in Custom Reports datasources.
Click Add.
If you need to learn more about datasources in Dashboard Hub, see Learn about datasources.
Add the Custom Reports gadget
Open Dashboard Hub in Jira.
If you have not created a dashboard,
Click the dashboard dropdown in the left corner or click the More actions ellipses in the top right corner, and select Create dashboard.
Name your dashboard, then click Create.
Click Add Gadget.
If you already have a dashboard, click Edit.
Click Add Gadget.
Type Custom Reports in the search bar in the gadget catalog or navigate to the Custom Reports section in the left-hand navigation panel.
Locate the Custom Reports gadget, then click Add.
Click Open Editor.
Example: random users 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
Data Fetching
uri: 'datasource://random_DS/api/?results=3',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 follows the rest of the URI /api/ .
Then we use a query param ?results=3 to return three random users from that API.
Data Parsing and display
The gadget processes the returned JSON and extracts the results array.
path: 'results',A node type: 'table' is generated with three columns:
The Name column displays the user’s picture and full name (title, first, and last).
header: 'Name'
src: '{picture.thumbnail}'
'{name.title} {name.first} {name.last}'
The Age columndisplays the user’s age.
header: 'Age',
cell: '{dob.age}'
The Country column 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:
{
"results": [
{
"gender": "male",
"name": {
"title": "Mr",
"first": "Jorge",
"last": "Silveira"
},{
type: 'rest',
uri: 'datasource://random_DS/api/?results=3',
children: [
{
type: 'table',
path: 'results',
style: {
flex: 1
},
columns: [
{
header: 'Name',
cell: {
type: 'view',
style: {
alignItems: 'center',
gap: 8,
fontWeight: '800'
},
children: [
{
type: 'image',
style: {
width: 40,
height: 'auto',
borderRadius: '50%'
},
src: '{picture.thumbnail}'
},
'{name.title} {name.first} {name.last}'
]
}
},
{
header: 'Age',
cell: '{dob.age}'
},
{
header: 'Country',
cell: '{location.country}'
}
]
}
]
}
Download this JSON response here:
Style
You need to be familiar with CSS to better style your reports, for example:
style: {
flex: 1
}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.
type: 'image',
style: {
width: 40,
height: 'auto',
borderRadius: '50%'
},This sets the image's width to 40 pixels, automatically adjusts its height to maintain its original aspect ratio, and rounds the image into a circle by applying a radius of 50% of its dimensions.
Save and publish your report
Use the live Preview panel to review the final output.
Click Save, and your report is ready to be shared with your colleagues.
Troubleshooting common issues
Error: Cannot connect to datasource:
Double-check the API URL and ensure it uses HTTPS.
Verify your authentication credentials and token expiration.
Visualization problems:
Ensure all required fields are correctly mapped in the visualization editor.
Use the Debug Mode (toggle in the editor toolbar) to inspect data and ensure the JSON structure matches the visualization requirements.
Advanced knowledge
To move to the next level of Custom Reports, you should learn:
JSONata: JSON query and transformation language.
CSS: To style your reports.
Recharts: The composable charting library built on React components behind our charts.
Next steps
Need support? Create a request with our support team.