TiS v5.1 - Issue Aggregation

GET /rest/tis/report/1.0/api/aggregation

POST /rest/tis/report/1.0/api/aggregation

Returns an aggregated report (sum, average, median, stddev) as text (CSV or JSON).

GET and POST methods provide the exact same functionality but POST method allows a much larger request size.

If your query parameters are too long to be used with a GET method (because you have a very long JQL or have too many statuses/fields selected) use POST method to access this endpoint.

The response time of this endpoint might be quite long, depending on how many issues you asked to be processed for your request.

Standard HTTP requests timeout at 60 seconds. In accordance with this limitation, this endpoint also has a 60-second limit. If the processing of your request takes longer than 60 seconds, you will get a timeout response (either from our service or from one of the gateways between your client and our service).

The max number of issues that can be processed before this timeout depends on how fast your Jira can supply the issues and their histories to our service. This in turn depends on the capacity and current load of your Jira.
On average, you should be able to get reports for thousands of issues without a problem. For busy Jira instances with lots of simultaneous users, this can be much lower. For relaxed instances with a lot of free capacity, this can be much higher.

If you keep getting timeout errors from this endpoint, you should consider using Asynchronous File Exports to get your data. Async Exports work by starting the export with a REST request, tracking progress with another REST request, and getting the completed file with yet another REST request. This way of using the REST API makes sure there are no technological timeout limits so you can get reports for as many issues as you need.

In short, this endpoint is easier to use but async export endpoints can supply reports for much larger data sets.

Request

The request takes all parameters you select on the screen for a report as query parameters.

Do not let the long text scare you. Not all parameters are always required and some are required based on filterType. See the params table below.

Basic:

<jira_url>/rest/tis/report/1.0/api/aggregation?aggregationType=<aggregationType>&filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>

With all parameters:

<jira_url>/rest/tis/report/1.0/api/aggregation?aggregationType=<aggregationType>&filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&multiVisitBehavior=<multiVisitBehavior>&averageDenominator=<averageDenominator>&statuses=<statuses>&groups=<groups>&includeDeletedStatuses=<includeDeletedStatuses>&startDate=<startDate>&endDate=<endDate>&dateRangeField=<dateRangeField>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&groupByFields=<groupByFields>

Parameters

Expand parameters...

Parameter	Description	Required	Value Samples
paramSetId	The ID of the reference parameter set that will be used to infer parameters. See Getting reports with Parameter Sets for details about getting reports with a reference parameter set.		276d7bea-f4df-49e6-b231-1b15d4ed852a
aggregationType	The aggregation type of the report. Possible options are: average sum median standardDeviation	Yes	average sum median standardDeviation
outputType	The output format of the report. Possible options are: CSV = Returns a CSV (comma separated value) that contains the report data as text. JSON = Returns a JSON (JavaScript Object Notation) that contains report data If not provided, "json" will be used.		csv json
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=	Only when filterType = user	user=admin
projectkey	If filterType is project, system expects a project key in the form projectKey=	Only when filterType = project	projectKey=ABC
jqlfilterID	If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID=	Only when filterType = jqlfilter	jqlFilterID=10145
customjql	If filterType is customjql, system expects a JQL Query in the form customjql=	Only when filterType = customjql	customjql=project=ABC
sprintID	If filterType is sprint, system expects a Sprint ID in the form 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 durationBetweenStatuses = Report will show the durations spent between two statuses 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 statusDurationByGroup = Report will show durations spent on each status on each user group as column values groupDurationByStatus = Report will show durations spent on each user group on each status as column values anyfieldDuration = Report will show how much time each issue field held each value statusCount = Report will show counts for each status transitionCount = Report will show counts for each transitions between statuses anyFieldCount = Report will show how many times each issue field held each value 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 durationBetweenStatuses assigneeDuration statusDurationByAssignee assigneeDurationByStatus groupDuration statusDurationByGroup groupDurationByStatus anyfieldDuration statusCount transitionCount anyFieldCount firstTransitionFromStatusDate firstTransitionToStatusDate lastTransitionFromDate lastTransitionToStatusDate
multiVisitBehavior	Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. See TiS v5.1 - Multi Visit Behavior		total first last average
averageDenominator	Defines which denominator to use while calculating average data. Effective only for export types that include Average or Standard Deviation data. Has two options: nonNull = Divides the total column value by the number of non-empty values in the column. This is the default. rowCount = Divides the total column value by the number of all issues in the column. For details please see TiS v5.1 - Aggregation		nonNull rowCount
historyFields	The IDs of fields (separated by commas) on JIRA Issues that will be used for Any Field reports. For details about Any Field report types please see: TiS v5.1 - Report Types Both system and custom fields are supported. For more information see TiS v5.1 - Field Names for REST Reports	only when columnsBy = anyfieldDuration or anyFieldCount	assignee,customfield_10020,customfield_10007,fixVersions
groupByFields	The IDs of fields (separated by commas) on JIRA Issue that will be used to group issues while aggregating data. Both system and custom fields are supported. Some fields are intentionally excluded. Date fields are included in a special format that allows data parts to be used. For further information see TiS v5.1 - 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. Typetypeattribute of each column defines whether the column is a Standard(std) orConsolidated(cons) column. Forstandardcolumns,idis the id of the status. For consolidatedcolumns, 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 v5.1 - Status. Other parameters may be included in the URL as a query parameter but statuses parameter is expected to be sent in request body encoded as "application/x-www-form-urlencoded" Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation.		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" ] } ]
assignees	Comma-separated list of login names of users that will be included in the report. If not provided or empty, the report will include all the assignees found in issues' histories.		joe.doe,dave.alvin joe.doe
groups	The names of user groups (separated by commas) that will be included in Group reports. 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
dbsMetrics	The list of metrics that will be showed as columns in Duration Between Statuses reports. The parameter must be provided as JSON text. The maximum number of metrics allowed is 10. Each metric will report the duration between two statuses and consists of the following parameters: name: (required) Name of the metric. Can only include alphanumeric characters and space. from: The starting status that the duration will be calculated from. Its format should be a JSON object contains id and order (first/last) of the status. Not defining this parameter means that the starting point will be "issue creation". to: (required) The target status that the duration will be calculated until. Its format should be a JSON object contains id and order (first/last) of the status. excluded: List of status ids that will be excluded from the calculations. Time spent on these statuses will not be added to total time. See TiS v5.1 - Report Types Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation.		[ { "name":"Resolution time", "to":{ "id":"5", "order":"first" } }, { "name":"Development time", "from":{ "id":"1", "order":"first" }, "to":{ "id":"6", "order":"last" }, "excluded":[ "10008", "10003" ] } ]
includeDeletedStatuses	Sets whether included statuses in issues' histories will be included in the report or not: Possible options are: true false If not provided, "true" is assumed.		true false
startDate	The start date of report filter. Only issues created/resolved/updated (based on dateRangeField value) after the given date will be included in the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used See TiS v5.1 - Date Range		2017-07-01 00:00
endDate	The end date of report filter. Only issues created/resolved/updated (based on dateRangeField value) before the given date will be included in the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used See TiS v5.1 - Date Range		2017-08-31 23:59
dateRangeField	The system date field of the Jira issue 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.	Only when either startDate or endDate is provided	created updated resolved
trimHistoryStartDate	The start date of history trim for issues. When provided, only activities in each issue's history after the given date will be processed for the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used See TiS v5.1 - Date Range		2017-07-01 00:00
trimHistoryEndDate	The end date of history trim for issues. When provided, only activities in each issue's history before the given date will be processed for the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used See TiS v5.1 - Date Range		2017-08-31 23:59
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	Required for Duration reports	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.	Required for Duration reports with non-24/7 calendar	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.61" 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" milliseconds = The values will be shown in milliseconds like "5235266" If not provided, "minutes" will be used.		humanReadable ddhhmmss hhmmss days hours minutes seconds milliseconds
dateFormat	The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS v5.1 - 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 TiS v5.1 - 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
sortBy	The report column that will be sorted. Currently, only Status Duration, Status Count, Duration Between Statuses and Assignee Duration reports support sort and the value of this parameter should be id of a standard status, name of a consolidated status or id of an assignee. See TiS v5.1 - Sort	Only when sortDir is provided	10000 my cons. status 1 5da17d34md123e99d4213c73
sortDir	The direction in which sort will be applied. See TiS v5.1 - Sort	Only when sortBy is provided	desc asc
filters	The list of report value filters. The parameter must be provided as JSON text. Currently, only Status Duration reports support filtering. The maximum number of filters allowed is 10. column should be either id of a standard status or name of a consolidated status. Possible operator options: greaterThan greaterThanEquals equals lessThanEquals lessThan Possible unit options: day hour minute second See TiS v5.1 - Filter		[ { "column":"10000", "operator":"greaterThanEquals", "value":"10", "unit":"day" }, { "column":"cons. status 1", "operator":"lessThan", "value":"5.5", "unit":"hour" } ]
emptyValueToken	The token to use for empty values in the report (for example when an issue has never visited a status) Selecting a custom token might make it easier for the requesting system to process the data. Possible options are: Hyphen ("-") (Default) Zero ("0") Null ("null") NoChar ("") SingleSpace (" ") NoToken ()		Hyphen Zero Null NoChar SingleSpace NoToken

Examples

Expand examples...

https://192.168.0.1/rest/tis/report/1.0/api/aggregation?aggregationType=average&filterType=user&user=admin&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&viewFormat=minutes&averageDenominator=rowCount

https://192.168.0.1/rest/tis/report/1.0/api/aggregation?aggregationType=sum&filterType=user&user=admin&columnsBy=statusDuration&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=csv&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate&sortBy=10000&sortDir=asc

https://192.168.0.1/rest/tis/report/1.0/api/aggregation?aggregationType=median&filterType=project&projectKey=PMP&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00 &dateRangeField=created&calendar=0&dayLength=24HourDays&viewFormat=minutes&outputType=json&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate  

https://192.168.0.1/rest/tis/report/1.0/api/aggregation?aggregationType=standardDeviation&filterType=jqlfilter&jqlFilterID=10004&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv&averageDenominator=nonNull&multiVisitBehavior=first

Responses

Expand responses...

Success

HTTP 200

Returns an aggregated report as text (CSV or JSON)

JSON...

{
    "total": 3,
    "totalIssueCount": 349,
    "dateTimeFormat": "dd/MMM/yy h:mm a",
    "dateFormat": "dd/MMM/yy",
    "timeZone": "Europe/Istanbul",
    "locale": "en-US",
    "viewFormat": "minutes",
    "isComposite": false,
    "columnsBy": "Status Duration",
    "multiVisitBehavior": "total",
    "calendar": {
        "id": null,
        "name": "normalHours",
        "monday": true,
        "tuesday": true,
        "wednesday": true,
        "thursday": true,
        "friday": true,
        "saturday": true,
        "sunday": true,
        "timeZone": "UTC",
        "holidayList": [],
        "holidaysSuccessfullyLoaded": true,
        "endTime": "00:00",
        "startTime": "00:00",
        "isDefault": null,
        "holidays": {}
    },
    "dayLength": "24HourDays",
    "query": " project  = 'VIS'",
    "trimHistoryStartDate": null,
    "trimHistoryEndDate": null,
    "reportDate": "13/Dec/22 1:28 PM",
    "version": "5.1.0.1",
    "includedStatuses": [
        {
            "id": "1",
            "name": "Open",
            "deleted": false,
        },
        {
            "id": "3",
            "name": "In Progress",
            "deleted": false,
        },
        {
            "id": "6",
            "name": "Closed",
            "deleted": false,
        },
        {
            "id": "5",
            "name": "Resolved",
            "deleted": false,
        }
    ],
    "excludedStatuses": [],
    "deletedStatuses": [],
    "isAggregationType": true,
    "isOverall": false,
    "isAverage": true,
    "isSum": false,
    "isMedian": false,
    "isStddev": false,
    "drawAllChart": true,
    "table": {
        "header": {
            "headerColumns": [],
            "groupByColumns": [
                {
                    "id": "project",
                    "value": "Project"
                },
                {
                    "id": "date:year:created",
                    "value": "Created (YEAR)"
                },
                {
                    "id": "date:month:created",
                    "value": "Created (MONTH)"
                }
            ],
            "fieldColumns": [],
            "valueColumns": [
                {
                    "id": "1",
                    "value": "Open",
                    "isConsolidated": false
                },
                {
                    "id": "3",
                    "value": "In Progress",
                    "isConsolidated": false
                },
                {
                    "id": "5",
                    "value": "Resolved",
                    "isConsolidated": false
                },
                {
                    "id": "6",
                    "value": "Closed",
                    "isConsolidated": false
                }
            ]
        },
        "body": {
            "rows": [
                {
                    "issueCount": 38,
                    "headerColumns": [],
                    "groupByColumns": [
                        {
                            "id": "project",
                            "value": "Virtual Sensor"
                        },
                        {
                            "id": "date:year:created",
                            "value": "2019"
                        },
                        {
                            "id": "date:month:created",
                            "value": "October"
                        }
                    ],
                    "fieldColumns": [],
                    "valueColumns": [
                        {
                            "id": "1",
                            "value": "-"
                        },
                        {
                            "id": "3",
                            "value": "1467.6289333333",
                            "raw": "8.805773684210527E7"
                        },
                        {
                            "id": "5",
                            "value": "1639798.6580166668",
                            "raw": "9.838791948166667E10"
                        },
                        {
                            "id": "6",
                            "value": "1639970.7625333334",
                            "raw": "9.83982457522E10"
                        }
                    ],
                    "currentState": []
                },
                {
                    "issueCount": 309,
                    "headerColumns": [],
                    "groupByColumns": [
                        {
                            "id": "project",
                            "value": "Virtual Sensor"
                        },
                        {
                            "id": "date:year:created",
                            "value": "2019"
                        },
                        {
                            "id": "date:month:created",
                            "value": "November"
                        }
                    ],
                    "fieldColumns": [],
                    "valueColumns": [
                        {
                            "id": "1",
                            "value": "1600334.75445",
                            "raw": "9.60200852677619E10"
                        },
                        {
                            "id": "3",
                            "value": "2383.2723833333",
                            "raw": "1.4299634375E8"
                        },
                        {
                            "id": "5",
                            "value": "1617989.54145",
                            "raw": "9.707937248702014E10"
                        },
                        {
                            "id": "6",
                            "value": "1617589.2776833333",
                            "raw": "9.705535666107913E10"
                        }
                    ],
                    "currentState": []
                },
                {
                    "issueCount": 2,
                    "headerColumns": [],
                    "groupByColumns": [
                        {
                            "id": "project",
                            "value": "Virtual Sensor"
                        },
                        {
                            "id": "date:year:created",
                            "value": "2021"
                        },
                        {
                            "id": "date:month:created",
                            "value": "July"
                        }
                    ],
                    "fieldColumns": [],
                    "valueColumns": [
                        {
                            "id": "1",
                            "value": "725854.09355",
                            "raw": "5.1512456135E10"
                        },
                        {
                            "id": "3",
                            "value": "-"
                        },
                        {
                            "id": "5",
                            "value": "-"
                        },
                        {
                            "id": "6",
                            "value": "-"
                        }
                    ],
                    "currentState": []
                }
            ]
        }
    }
}

CSV...

"Project","Created (YEAR)","Created (MONTH)","Number Of Issues","Open","In Progress","Resolved","Closed"
"Virtual Sensor","2019","October","38","-","1467.6289333333","1639798.3225","1639970.4272833334"
"Virtual Sensor","2019","November","309","1600334.4191166668","2383.2723833333","1617989.2060833334","1617588.9423166667"
"Virtual Sensor","2021","July","2","725853.7579666667","-","-","-"

Invalid Parameter

HTTP 400

When one or more of the required parameters are missing or one or more of the supplied parameter values are invalid.

messages array contains the error messages for invalid parameters.

{
    "message": "Invalid report parameters",
    "statusCode": 400,
    "messages": [
        "ERROR: Invalid outputType value: 'txt'. Possible values are 'csv' and 'json'",
        "ERROR: calendar parameter is required. Possible values are normalHours or ID of a custom defined calendar"
    ],
    "pluginVersion": "5.1.0.1",
    "time": "2023-01-16 12:07:08"
}

Timeout

HTTP 408

When your aggregated report cannot be completed before the request timeout. You should use async file export endpoint for large aggregated reports.

{
    "message": "Report calculation timed out. Consider using async file export.",
    "statusCode": 408,
    "pluginVersion": "5.1.0.1",
    "time": "2023-01-16 12:09:28"
}

Aggregation Limit Exceeded

HTTP 429

When you start too many simultaneous aggregated reports and exceed the concurrent aggregation limit per user.

You should wait for some of the aggregated reports to complete before starting a new one.

{
    "message": "You have reached the per-user concurrent aggregate calculation limit, set for Time in Status by your Jira Admin. Wait for running calculations to complete or cancel some of the running calculations and then try again. Contact your Jira Admin for details.",
    "statusCode": 429,
    "pluginVersion": "5.1.0.1",
    "time": "2023-01-16 12:10:37"
}

Page tree