You're on your way to the next level! Join the Kudos program to earn points and save your progress.
Level 1: Seed
25 / 150 points
1 badge earned
Challenges come and go, but your rewards stay with you. Do more to earn more!
What goes around comes around! Share the love by gifting kudos to your peers.
Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!
Join now to unlock these features and more
All organizations which are working with Jira have some reporting needs. With different reports you can improve project management, team performance, forecasting and progress tracking based on real-time, visual data. For some companies the most valuable reports are personal and team reports, which improve employee’s productivity and keep teams on track. And of course, every company has it’s own unique reporting needs. Some reporting functions can be found in Jira out-of-the-box. But if you want something unique and flexible, you need an app like Report Builder.
Our example: Actual time vs. estimation
The process of report creation with Scripted Report is split into three tabs:
One more tab called Permissions will be useful if you want to share the report with someone, but we’ll cover this part at the end of this guide.
Let’s try to solve the task of getting a time tracking report from Jira based on JQL query and get an understanding of each tab.
The tab provides the ability to add input fields and define the category of your report. At the moment there are more than 10 predefined input field types. You can choose any category from the list or skip this step.
In our case, we will choose the category “Table”, because it would be a great way to see the estimated time over the spent time in table format.
We create two input fields:
We set up those two fields the following way:
To control the final data view, the Template tab provides a Handlebars template editor. If you’re not aware with Handlebars, we’re suggesting to check out the official site of the template engine.
As mentioned before, we decided to use the table format to represent the data. We assume that it will be an array of issue objects which come from Jira API, so we need to create a table row for each of these objects.
Let’s go over some of these methods:
SR.getValueByFieldName(fieldName:String) – returns the input field value based on fieldName string parameter
SR.getIssuesByJQL(jql:String, <fields:String>) – returns an array of Jira issues based on JQL query and the list of comma-separated fields. If the fields parameter is not set, then Jira Navigable fields will be returned
You fill in the fields JQL and Fields Picker. The first thing you need to do is getting the values in the script.
To get the data from the input fields with the help of SR.getValueByFieldName() you need to pass the field name value that was set in the General tab. Please note that the Fields Picker is a multi-select field which returns an array of values.
As the SR.getIssuesByJQL() uses the string type for both parameters, you convert the selected fields to the comma-separated string. As the request to the Jira API is an asynchronous operation, you should be using top-level await to wait for a response.
The issue in the last code shows the time that comes from Jira and is presented in milliseconds. So you need to define the helper function that will convert incoming values into hours.
You now need to apply this conversion to the map callback function.
Finally, you’re passing the value of the issues as part of the rendering object inside the SR.render() method. If you want to pass more values, you need to add another property to the rendering object.
All you are now left with is clicking on the “Get Report” button at the top-right and view the results.
Here you can see the complete code for the Script tab:
To regulate the group of users that could view, edit and admin your report, you can configure the Permissions tab. The selected users will see the shared report in the “Shared” tab in the Scripted Report dashboard.
Currently, there are three roles of report users available:
1. View access – the user has the ability to only view the report. The user cannot save the input parameter values or edit the report configuration tab.
2. Edit access – the user has the ability to view the report and save the input parameter values. The user cannot edit the report configuration tab.
3. Admin access – the user has the ability to view the report, save the input parameter values and edit the report configuration tab.
The creator of the report always has admin access rights! Creator rights cannot be changed.
The Permissions tab allows sharing the direct link to the report. Please note that the respective user should have permission to at least view the shared report (role 1).
When the report set up suits your goals, save your report and choose a self-descriptive name. You will find all your report in the Scripted Report dashboard in the tab “My reports”
You already know how to get the spent time in comparison to the estimated time for issues. But what if you want to get a report that will calculate the work time for a whole project, so multiple issues from multiple users? This can be achieved with minor changes in the report script.
First, you need to define the object that will store each project worklog as a key-value pair.
Next, pick the project field in the Fields Picker to be returned from the Jira API. Define the calculation logic inside the foundIssues.map() callback:
Finally, pass the “projects” object as part of the rendering object and update the Template tab to show the data.
These operations will show you the report with extended data.
Please note that you didn’t lose the previous report, but calculated project logs in addition to it. This shows the flexibility of Scripted Reports, to fetch and use the Jira data in multiple ways.
The integrated report gallery is a list of predefined reports. The predefined gallery reports cannot be edited, but you can copy them into your private report list for editing.
To copy the report, please click the button “Copy” at the top-right of the report viewing page. Right after the click your report will be created automatically in your “My Reports” tab of the Scripted Report dashboard.
If you have any further reporting needs, please contact our Report Building Service team, which will provide any report for you.
Andrei Pisklenov _Actonic_