Issues work vs original estimate

\n \n \n \n \n \n \n \n {{#each issues}}\n \n \n \n \n \n \n {{/each}}\n

Ticket	Actual work	Original estimate	Remaining estimate
{{this.key}}	{{this.timespent}} h	{{this.timeestimate}} h	{{this.remaining}} h

","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"type":"hardBreak"},{"text":"Tab 3: Script","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"A comprehensive guide to Scripted Report API (aka SR API) is provided in ","type":"text"},{"text":"this","type":"text","marks":[{"type":"link","attrs":{"href":"https://actonic.atlassian.net/wiki/spaces/ARB/pages/887390219"}}]},{"text":" guide.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"To manage the data provided, you can use JavaScript in the General tab. The code will run in the top-level await scope with the defined SR object. This object is constructed to help with tasks like interacting with Jira API, quickly getting data from the input fields of the General Tab, and passing the final data to the template.","type":"text"}]},{"type":"paragraph","content":[{"text":"Let's go over some of these ","type":"text"},{"text":"methods","type":"text","marks":[{"type":"link","attrs":{"href":"https://actonic.atlassian.net/wiki/spaces/ARB/pages/887390219"}}]},{"text":":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SR.fields.getValueByFieldName(fieldName:String) – returns a promise with the input field value based on ","type":"text"},{"text":"fieldName","type":"text","marks":[{"type":"em"}]},{"text":" string parameter. Please note that some pickers could be a multi-select field that returns an array of values.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SR.jira.getIssuesByJQL(jql:String, , ) – returns a promise with an array of Jira issues based on JQL query and the list of comma-separated fields. If the fields parameter is not set, then ","type":"text"},{"text":"Jira Navigable","type":"text","marks":[{"type":"link","attrs":{"href":"https://confluence.atlassian.com/jirakb/navigable-vs-orderable-field-838538013.html"}}]},{"text":" fields will be returned","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SR.render(templateValues:Object, ) – passes the values from the JavaScript to the template defined in the Template tab. It is possible to set some after rendering logic with the callback parameter","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"You fill in the fields JQL and Range Picker. The first thing you need to do is get the values in the script. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":252,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":252,"alt":"image-20240325-225346.png","id":"f41e76bb-fe03-4e7f-87f7-0072383c32a3","collection":"contentId-1114341377","type":"file","height":154}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"To get the data from the input fields with the help of ","type":"text"},{"text":"SR.fields.getValueByFieldName() ","type":"text","marks":[{"type":"em"}]},{"text":"you need to pass the field name value that was set in the General tab.","type":"text"}]},{"type":"codeBlock","content":[{"text":"const jqlField = await SR.fields.getValueByFieldName('jql-field');\nconst { start, end } = await SR.fields.getValueByFieldName('range');","type":"text"}]},{"type":"paragraph","content":[{"text":"As the ","type":"text"},{"text":"SR.jira.getIssuesByJQL()","type":"text","marks":[{"type":"em"}]},{"text":" 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.","type":"text"}]},{"type":"codeBlock","content":[{"text":"const jql = `created >= \"${start}\" and created <= \"${end}\"${jqlField && ` AND ${jqlField}`}`;\nconst foundIssues = await SR.jira.getIssuesByJQL(jql, FIELDS.join(','));","type":"text"}]},{"type":"paragraph","content":[{"text":"Now, fetch the Jira issues and control the final data object which is possible with the ","type":"text"},{"text":"JavaScript map()","type":"text","marks":[{"type":"em"}]},{"text":" method: ","type":"text"}]},{"type":"codeBlock","content":[{"text":"const issues = foundIssues.map(({ key, fields }) => {\n /* Get properties:\n key - issue key\n timespent - Time Spent\n timeoriginalestimate - Original estimate\n timeestimate - Remaining\n */\n const {\n timeestimate,\n timeoriginalestimate,\n timespent,\n } = fields;\n return {\n key,\n timespent: millisecondsToHours(timespent),\n timeestimate: millisecondsToHours(timeoriginalestimate),\n remaining: millisecondsToHours(timeestimate),\n };\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"The issue in the last code shows the time that comes from Jira and is presented in milliseconds. So it would help if you defined the helper function that will convert incoming values into hours.","type":"text"}]},{"type":"codeBlock","content":[{"text":"const millisecondsToHours = (milliseconds) => {\n if (isNaN(milliseconds)) {\n return 0;\n }\n return (Math.round(((milliseconds / 3600) + Number.EPSILON) * 100) / 100);\n};","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, you're passing the value of the issues as part of the rendering object inside the ","type":"text"},{"text":"SR.render()","type":"text","marks":[{"type":"em"}]},{"text":" method. If you want to give more values, you need to add another property to the rendering object.","type":"text"}]},{"type":"codeBlock","content":[{"text":"SR.render({ issues });","type":"text"}]},{"type":"paragraph","content":[{"text":"All you are now left with is clicking on the \"Get Report\" button at the top-right and viewing the results.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1350,"alt":"image-20240326-095948.png","id":"a8aaf37e-2fa1-4a94-9188-d2ec5b9fbe30","collection":"contentId-1114341377","type":"file","height":391}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Here you can see the complete code for the Script tab:","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"/* 1. Define constants */\nconst FIELDS = [\n 'timespent',\n 'timeoriginalestimate',\n 'timeestimate'\n];\n/* 2. Define helper functions */\nconst millisecondsToHours = (milliseconds) => {\n if (isNaN(milliseconds)) {\n return 0;\n }\n return (Math.round(((milliseconds / 3600) + Number.EPSILON) * 100) / 100);\n};\n/* 3. Getting parameters for the JQL request */\nconst jqlField = await SR.fields.getValueByFieldName('jql-field');\nconst { start, end } = await SR.fields.getValueByFieldName('range');\n/* 4. Requesting issues by JQL string and fields list */\nconst jql = `created >= \"${start}\" and created <= \"${end}\"${jqlField && ` AND ${jqlField}`}`;\nconst foundIssues = await SR.jira.getIssuesByJQL(jql, FIELDS.join(','));\n/* 5. Parsing data from the response and creating the final object */\nconst issues = foundIssues.map(({ key, fields }) => {\n /* 5.1 Get properties:\n key - issue key\n projectKey - project key\n timespent - Time Spent\n timeoriginalestimate - Original estimate\n timeestimate - Remaining\n */\n const {\n timeestimate,\n timeoriginalestimate,\n timespent,\n } = fields;\n /* 5.2 Issue work time vs original estimate logic */\n return {\n key,\n timespent: millisecondsToHours(timespent),\n timeestimate: millisecondsToHours(timeoriginalestimate),\n remaining: millisecondsToHours(timeestimate),\n };\n});\n/* 6. Passing values to the handlebars template engine */\nSR.render({ issues });","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Permission tab","type":"text"}]},{"type":"paragraph","content":[{"text":"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 report in the \"Shared\" tab in the Scripted Report dashboard.","type":"text"}]},{"type":"paragraph","content":[{"text":"Currently, there are three roles of report users available:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"View access","type":"text","marks":[{"type":"strong"}]},{"text":" – the user can only view the report. The user cannot save the input parameter values or edit the report configuration tab.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Edit access","type":"text","marks":[{"type":"strong"}]},{"text":" – the user can view the report and save the input parameter values. However, the user cannot edit the report configuration tab.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Admin access","type":"text","marks":[{"type":"strong"}]},{"text":" – the user can view the report, save the input parameter values, and edit the report configuration tab.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The creator of the report always has admin access rights! Creator rights cannot be changed.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Permissions tab allows sharing the direct link to the report. Please note that the respective user should have permission to view the shared report (role 1).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Saving your report","type":"text"}]},{"type":"paragraph","content":[{"text":"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.\"","type":"text"}]},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"8a2a4e6a-8549-4b3d-971e-348dc07fbee9","collection":"contentId-1114341377","type":"file"}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Report improvements: Changing the script","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"First, you need to add ","type":"text"},{"text":"project","type":"text","marks":[{"type":"em"}]},{"text":" field to your constant ","type":"text"},{"text":"FIELDS","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"const FIELDS = [\n 'timespent',\n 'timeoriginalestimate',\n 'timeestimate',\n 'project'\n];","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, you need to simple refactoring. Replace ","type":"text"},{"text":"foundIssues.map()","type":"text","marks":[{"type":"em"}]},{"text":" to ","type":"text"},{"text":"foundIssues.reduce()","type":"text","marks":[{"type":"em"}]},{"text":", also add ","type":"text"},{"text":"result.issues.push(issue)","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"and ","type":"text"},{"text":"return result","type":"text","marks":[{"type":"code"}]},{"text":" to the end. Well, define the calculation logic of projects inside the ","type":"text"},{"text":"foundIssues.reduce() ","type":"text","marks":[{"type":"em"}]},{"text":"like issue work time logic. Now, you should get a code like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"const { issues, projects } = foundIssues.reduce((result, { key, fields }) => {\n /* 5.1 Get properties:\n key - issue key\n projectKey - project key\n timespent - Time Spent\n timeoriginalestimate - Original estimate\n timeestimate - Remaining\n */\n const {\n project: {\n key: projectKey,\n },\n timeestimate,\n timeoriginalestimate,\n timespent,\n } = fields;\n /* 5.2 Issue work time vs original estimate logic */\n const issue = {\n key,\n timespent: millisecondsToHours(timespent),\n timeestimate: millisecondsToHours(timeoriginalestimate),\n remaining: millisecondsToHours(timeestimate),\n };\n /* 5.3 Add current issue to result */\n result.issues.push(issue);\n /* 5.4 Find a project of the current issue in the processed project */\n const foundProject = result.projects.find(({ key }) => key === projectKey);\n if (foundProject) {\n /* 5.5 If project key is already exist then recalculate time */\n foundProject.timeestimate += timeoriginalestimate;\n foundProject.timespent += timespent;\n foundProject.remaining += timeestimate;\n foundProject.timeestimateHours = millisecondsToHours(projects[projectKey].timeestimate);\n foundProject.timespentHours = millisecondsToHours(projects[projectKey].timespent);\n foundProject.remainingHours = millisecondsToHours(projects[projectKey].remaining);\n } else {\n const project = {\n key: projectKey,\n timespent,\n timeestimate: timeoriginalestimate,\n remaining: timeestimate,\n timeestimateHours: millisecondsToHours(timeoriginalestimate),\n timespentHours: millisecondsToHours(timespent),\n remainingHours: millisecondsToHours(timeestimate),\n };\n /* 5.6 Add new project to result */\n result.projects.push(project);\n }\n return result;\n}, {\n issues: [],\n projects: []\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally, pass the \"projects\" object as part of the rendering object and update the Template tab to show the data.","type":"text"}]},{"type":"codeBlock","content":[{"text":"SR.render({ issues, projects });","type":"text"}]},{"type":"codeBlock","content":[{"text":"

Projects work vs original estimate

\n \n \n \n \n \n \n \n {{#each projects}}\n \n \n \n \n \n \n {{/each}}\n

Project Key	Actual work	Original estimate	Remaining estimate
{{this.key}}	{{this.timespentHours}} h	{{this.timeestimateHours}} h	{{this.remainingHours}} h

","type":"text"}]},{"type":"paragraph","content":[{"text":"These operations will show you the report with extended data.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":368,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1029,"id":"fa513283-2715-47ba-b16e-e4c092d5eab0","collection":"contentId-1114341377","type":"file","height":1280}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"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. ","type":"text"}]},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"ee2b3935-b0d4-4927-a038-461c0b6ef34d","collection":"contentId-1114341377","type":"file"}}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Using the report gallery","type":"text"}]},{"type":"paragraph","content":[{"text":"The integrated report gallery is a list of predefined reports. The goal of Scripted Reports is to cover basic user needs and create a platform for unique report creation. The predefined gallery reports cannot be edited inside the Gallery itself, but you can copy them into your private report list for editing.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Please click the button “Export to JSON“ as follows:","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1280,"id":"feb16007-2b3d-4aea-8e87-2b899ce43cd5","collection":"contentId-1114341377","type":"file","height":115}}]},{"type":"orderedList","attrs":{"order":2},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Copy the JSON","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":626,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":626,"id":"c4626a22-b9cf-4d55-b390-5604ffa13531","collection":"contentId-1114341377","type":"file","height":590}}]},{"type":"orderedList","attrs":{"order":3},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Proceed to your reports dashboard, and import the JSON copied","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1280,"id":"f5d49a92-7095-4e39-bb9f-c454fe9e8e0c","collection":"contentId-1114341377","type":"file","height":195}}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Report Building Service","type":"text"}]},{"type":"paragraph","content":[{"text":"If you have any further reporting needs, please get in touch with our Report Building Service team, which will provide any report for you. Read more about our service ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.actonic.de/en/report-building-service/"}}]},{"text":".","type":"text"}]}],"version":1}

Browser not supported