Report Data

It is possible to access report data via REST call to a JIRA endpoint introduced by Time in Status. The parameters of the REST call correspond to Time in Status report parameters.


Rest Call Format

The REST call should be made in the following format

<base_url>/rest/tis/report/1.0/out/file?filterType=<filterType>&user=<user>&projectKey=<projectKey>&jqlFilterID=<jqlFilterID>&customjql=<customjql>&sprintID=<sprintID>&columnsBy=<columnsBy>&fields=<fields>&statuses=<statuses>&groups=<groups>&includeDeletedStatuses=<includeDeletedStatuses>&startDate=<startDate>&endDate=endDate&dateRangeField=<dateRangeField>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&groupByFields=<groupByFields>&dateFormat=<dateFormat>&dateTimeFormat=<dateTimeFormat>


Parameters


Token

Description

Required

Value Samples

base_urlThe baseURL of your JIRA instance.Yes
outputType

The output file format of the report. Possible options are:

  • XLS = Returns an Excel file in XLS format that contains both the data and calculated averages.
  • XLSX = Returns an Excel file in XLSX format that contains both the data and calculated averages.
  • CSV = Returns a CSV (comma separated value) file that contains the report data.
  • CSVAVERAGE = Returns a CSV (comma separated value) file that contains only average durations.
  • CSVSUM = Returns a CSV (comma separated value) file that contains only sums of durations.
Yes
  • xls
  • xlsx
  • csv
  • csvaverage
  • csvsum
filterType

Defines how the issues to be included in the report will be selected. Possible options are:

  • user = Report will filter out the issues assigned to the selected user
  • project = Report will filter out issues in the selected Jira project
  • jqlfilter = Report will filter out issues based on an existing JQL filter
    • The value advanced is deprecated but is still valid and will be processed as jqlfilter.
  • customjql = Report will filter out issues based on a given JQL query 
  • sprint = Report will filter out issues based on an existing sprint 
Yes
  • user
  • project
  • jqlfilter
  • customjql
  • sprint
user

If filterType is user, system expects a user name in the form user=<some_user_name>

Only when filterType = user
  • user=admin
projectkey

If filterType is project, system expects a project key in the form projectKey=<project_key>

Only when filterType = project
  • projectKey=ABC
jqlfilterID

If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID=<jqlFilterID>

Only when filterType = jqlfilter
  • jqlFilterID=10145
customjql

If filterType is customjql, system expects a JQL Query in the form customjql=<customJQL>

Only when filterType = customjql
  • customjql=project=ABC
sprintID

If filterType is sprint, system expects a Sprint ID in the form sprintID=<sprintID>

Only when filterType = sprint
  • sprintID=2
columnsBy

Defines the column structure of the report. Possible options are:

  • statusDuration = Report will show durations spent on each status as column values
  • assigneeDuration= Report will show durations spent on each assignee as column values
  • statusDurationByAssignee = Report will show durations spent on each status on each assignee as column values
  • assigneeDurationByStatus = Report will show durations spent on each assignee on each status as column values
  • groupDuration= Report will show consolidated durations spent on members of each group as column values
  • statusCount = Report will show counts for each status
  • transitionCount = Report will show counts for each transitions between statuses
  • firstTransitionToStatusDate = Report will show the date the issue transitioned TO each status for the FIRST time as column values
  • firstTransitionFromStatusDate = Report will show the date the issue transitioned FROM each status for the FIRST time as column values 
  • lastTransitionToStatusDate = Report will show the date the issue transitioned TO each status for the LAST time as column values
  • lastTransitionFromDate = Report will show the date the issue transitioned FROM each status for the LAST time as column values
Yes
  • statusDuration
  • assigneeDuration
  • statusDurationByAssignee
  • assigneeDurationByStatus
  • groupDuration
  • statusCount
  • transitionCount
  • firstTransitionFromStatusDate
  • firstTransitionToStatusDate
  • lastTransitionFromDate
  • lastTransitionToStatusDate
fields

The IDs of fields (separated by commas) on JIRA Issue that will be added to report output as columns.

Both system and custom fields are supported.


assignee,customfield_10020,customfield_10007,description,duedate, fixVersions
groupByFields

The IDs of fields (separated by commas) on JIRA Issue that will be used to group issues for average or sum data.

Both system and custom fields are supported. Some fields are intentionally excluded.

Date fields are included in a speacial format that allows data parts to be used. For further information look at TiS v4.8 - Field Names for REST Reports


assignee,customfield_10140,date:year:resolutiondate,date:week:resolutiondate
statuses

A JSON array listing statuses for which the durations will be included in the report.

If not provided or left empty, the report will include all statuses in selected issues' histories.

For assignee based reports, durations of unselected statuses will be excluded from durations of assignee columns.

Supports two formats: Basic and Advanced


Basic:

Basic format is a comma separated list of status ID's to be included in the report.


Advanced:

Advanced format is a JSON text that contains status definitions.

Advanced format must be employed if you want to use the Consolidated Columns feature.

Type type attribute of each column defines whether the column is a Standard (std) or Consolidated (cons) column. For standard columns, id is the id of the status. For consolidated columns, the statuses array contains the IDs of statuses to be included in the column. For more information on status selection and column consolidation, please see TiS v4.8 - Status


Basic:

1,3,4,5,10001,10234

Advanced:

[
   {
      "id":"6",
      "type":"std"
   },
   {
      "id":"2",
      "type":"std"
   },
   {
      "name":"cons. status 1",
      "type":"cons",
      "statuses":[
         "10008",
         "3",
         "10007"
      ]
   }
]
groups

The names of user groups (separated by commas) that will be included in Group Time report.

If not provided or empty, the report will included all durations in a column named "Not a member of selected groups"


  • jira-administrators
  • jira-users, jira-administrators
includeDeletedStatuses

Sets whether included statuses in issues' histories will be included in the report or not:

Possible options are:

  • true
  • false

In not provided, "true" is assumed.


  • true
  • false
startDateThe start date of report interval in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format.
If time parameter is no given default time "00:00" will be process
Yes2017-07-01 00:00
endDateThe end date of report interval in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format.
If time parameter is no given default time "00:00" will be process
Yes2017-08-31 23:59
dateRangeField

The dateConditionField type that startDate and endDate parameters will be based on. Possible options are:

  • created = The startDate and endDate parameters will be used to filter issues based on issue create date.
  • updated = The startDate and endDate parameters will be used to filter issues based on issue last update date.
  • resolved = The startDate and endDate parameters will be used to filter issues based on issue resolution date.
Yes
  • created
  • updated
  • resolved

calendar

The calendar that report durations will be calculated based on. Possible options are:

  • normalHour = The durations will be based on a 7/24 calendar. (default)
  • 0 = The default business calendar
  • n = ID of a custom calendar

Tip: You can get the IDs of calendars using the Calendars endpoint, explained at the end of this page

Yes
  • normalHours
  • 0
  • 1
  • 2
dayLength
  • 24HourDays = Each day will be 24 hours.
  • businessDays = Can be used for calendars other than 7/24. The durations will be based on the business calendar defined in admin settings. Length of each day will also be based on business hours defined in admin settings.

  • 24HourDays
  • businessDays
viewFormat

The format of duration data in the report. Possible options are:

  • humanReadable = The values will be shown like "44 d 5 h 2 m 35 s"
  • ddhhmmss = The values will be shown like "44:05:02:35"
  • hhmmss = The values will be shown like "1061:02:35"
  • days = The values will be shown in days, as a single decimal value like "44.71"
  • hours = The values will be shown in hours, as a single decimal value like "1061.04"
  • minutes = The values will be shown in minutes, as a single decimal value like "63662.59"
  • seconds = The values will be shown in seconds, like "3819755"
Yes
  • humanReadable
  • ddhhmmss
  • hhmmss
  • days
  • hours
  • minutes
  • seconds
dateFormat

The string format to use for displaying values of fields of type Date

If empty or missing, the date format defined in Time in Status Format Settings page is used. If Format Settings date format is also empty, the default date format set for Jira is used.

You can refer to the Java Documentation for more information about Date Format Strings.


  • yyyy-MM-dd
  • dd/MM/yy
  • dd/MMM/yyyy
dateTimeFormat

The string format to use for displaying values of fields of type DateTime

If empty or missing, the datetime format defined in Time in Status Format Settings page is used. If Format Settings datetime format is also empty, the default datetime format set for Jira is used.

You can refer to the Java Documentation for more information about Date Format Strings.


  • yyyy-MM-dd hh:mm a
  • dd/MM/yy HH:mm
  • dd/MMM/yyyy HH:mm:ss



Examples:

http://192.168.0.71:7500/jira75/rest/tis/report/1.0/out/file?filterType=user&user=admin&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&dayLength=24HourDays&viewFormat=minutes&outputType=xls&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate


http://192.168.0.71:7500/jira75/rest/tis/report/1.0/out/file?filterType=project&projectKey=PMP&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=0&dayLength=24HourDays&viewFormat=minutes&outputType=xlsx&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate&dateFormat=yyyy-MM-dd&dateTimeFormat=yyyy-MM-dd hh:mm a


http://192.168.0.71:7500/jira75/rest/tis/report/1.0/out/file?filterType=jqlfilter&jqlFilterID=10004&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv&dateFormat=yy-MM-dd&dateTimeFormat=yyyy-MM-dd HH:mm:ss


http://192.168.0.71:7500/jira75/rest/tis/report/1.0/out/file?filterType=customjql&customjql=project=ABC&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv&dateFormat=yy-MM-dd&dateTimeFormat=yyyy-MM-dd HH:mm:ss


http://192.168.0.71:7500/jira75/rest/tis/report/1.0/out/file?filterType=sprint&sprintID=2&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv&dateFormat=yy-MM-dd&dateTimeFormat=yyyy-MM-dd HH:mm:ss


Return

The REST call returns an XLS, XLSX or CSV file that contains all the data in the report.



Calendars

A list of calendars defined in the system with their IDs can be requsted through the following REST endpoint.


<base_url>/rest/tis/report/1.0/data/calendars


Example:

http://192.168.0.74:8080/rest/tis/report/1.0/data/calendars


Return

The call returns a JSON text that contains all calendar definitions in the system.







  • No labels