- Created by Emre Toptancı, last modified by Berkay Öztürk on 30.06.2022
Introduction
You can get Time in Status report data via REST. The parameters of the REST call correspond to on-screen Time in Status report parameters.
Authentication and Authorization
All REST requests shown in this document require authentication.
Authentication is handled by the Jira instance that hosts the app. Basic Authentication and OAuth can be used.
In cases where the user cannot be authenticated or authorized, one of these error responses is returned:
All endpoints will return the following responses on auhtentication and authorization related errors.
Invalid Licence
HTTP 401
Unauthorized (401)
Encountered a "401 - Unauthorized" error while loading this page.
Unauthorized access
Invalid User
HTTP 401
When used user is not valid then JIRA server returns html page like that
Unauthorized (401)
Encountered a "401 - Unauthorized" error while loading this page.
Basic Authentication Failure - Reason : AUTHENTICATED_FAILED
Rest API Disabled
HTTP 503
When Rest API is disabled for the plugin, then this html is returned.
HTTP Status 503 – Service Unavailable
Type Status Report
Message Rest API is disabled
Description The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
Getting Issue Data
Single issue
GET /rest/tis/report/1.0/api/issue
POST /rest/tis/report/1.0/api/issue
Returns a single issue report as text (CSV or JSON)
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. See the params table below.
Basic:
<jira_url>/rest/tis/report/1.0/api/issue?issueKey=<issueKey>&columnsBy=<columnsBy>&calendar=<calendar>
With all parameters:
<jira_url>/rest/tis/report/1.0/api/issue?issueKey=<issueKey>&columnsBy=<columnsBy>&fields=<fields>&statuses=<statuses>&groups=<groups>&includeDeletedStatuses=<includeDeletedStatuses>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| issueKey | Key of the issue that report will be generated for. | Yes | ABC-1 |
| outputType | The output format of the report. Possible options are:
If not provided, "json" will be used. |
| |
| columnsBy | Defines the column structure of the report. Possible options are:
| Yes |
|
| multiVisitBehavior | Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. |
| |
| fields | The IDs of fields (separated by commas) on JIRA Issues that will be added to report output as columns. Both system and custom fields are supported. For more information see TiS v4.24 - Field Names for REST Reports | assignee,customfield_10020,customfield_10007,description,duedate, fixVersions | |
| 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 v4.24 - Report Types Both system and custom fields are supported. For more information see TiS v4.24 - Field Names for REST Reports | only when columnsBy = anyfieldDuration or anyFieldCount | assignee,customfield_10020,customfield_10007,fixVersions |
| 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 v4.24 - 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"
]
}
]
| |
| 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" |
| |
| 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. Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation. | only when columnsBy = durationBetweenStatuses | [
{
"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:
If not provided, "true" is assumed. |
| |
| 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 | 2017-07-01 00:00 | |
| trimHistoryStartDate | 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 | 2017-08-31 23:59 | |
calendar | The calendar that report durations will be calculated based on. Possible options are:
Tip: You can get the IDs of calendars using the Calendars endpoint, explained at the end of this page | Required for Duration reports |
|
| dayLength |
| Required for Duration reports with non-24/7 calendar |
|
| viewFormat | The format of duration data in the report. Possible options are:
If not provided, "minutes" will be used. |
| |
| dateFormat | The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS v4.24 - 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. |
| |
| dateTimeFormat | The string format to use for displaying values of fields of type DateTime If empty or missing, the datetime format defined in TiS v4.24 - 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. |
|
Examples
https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=XYZ-34&columnsBy=statusDuration&calendar=normalHours https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=ABC-3&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&calendar=normalHours&dayLength=24HourDays&viewFormat=minutes&outputType=csv https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=TEST-85&columnsBy=statusDuration&calendar=0&dayLength=24HourDays&viewFormat=minutes&outputType=json https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=TTP-123&columnsBy=statusDuration&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=TIS-1&columnsBy=statusDuration&calendar=1&dayLength=businessDays&viewFormat=humanReadable https://192.168.0.1/rest/tis/report/1.0/api/issue?issueKey=QWERTY-45&columnsBy=statusDuration&trimHistoryStartDate=2017-09-01 00:00&trimHistoryEndDate=2017-10-31 00:00&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv
Responses
Success
HTTP 200
Returns a single issue report as text (CSV or JSON)
{
"dateTimeFormat": "yyyy-MM-dd hh:mm a",
"dateFormat": "yyyy-MM-dd",
"timeZone": "Asia/Istanbul",
"locale": "en-US",
"isComposite": false,
"columnsBy": "Last Transition From Status Date",
"query": "key in (sspwsd-21)",
"reportDate": "2020-08-21 02:47 PM",
"version": "4.11.0.1",
"isAggregationType": false,
"isOverall": false,
"isAverage": false,
"isSum": false,
"table": {
"header": {
"headerColumns": [
{
"id": "issuekey",
"value": "Key"
},
{
"id": "summary",
"value": "Summary"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "3",
"value": "In Progress",
"isConsolidated": false
},
{
"id": "10000",
"value": "To Do",
"isConsolidated": false
}
]
},
"body": {
"rows": [
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-21"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "2020-10-14 11:46 AM",
"raw": "1602665218203"
}
],
"currentState": []
}
]
}
}
}
"Key","Summary","To Do","Done","In Progress" "ABC-1","Example 1","112 d 23 h 34 m 37 s","4 s","10 s"
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.
{
"statusCode": 400,
"messages": [
"ERROR: Invalid outputType value: 'xls'. Possible values are 'csv' and 'json'"
],
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:24:16"
}
Issue list
GET /rest/tis/report/1.0/api/list
POST /rest/tis/report/1.0/api/list
Returns a list report 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.
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/list?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>&startDate=<startDate>&endDate=<endDate>&dateRangeField=<dateRangeField>
With all parameters:
<jira_url>/rest/tis/report/1.0/api/list?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>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&groupByFields=<groupByFields>&pageSize=<pageSize>&startIssueIndex=<startIssueIndex>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| outputType | The output format of the report. Possible options are:
If not provided, "json" will be used. |
| |
| filterType | Defines how the issues to be included in the report will be selected. Possible options are:
| Yes |
|
| user | If filterType is user, system expects a user name in the form user= | Only when filterType = user |
|
| projectkey | If filterType is project, system expects a project key in the form projectKey= | Only when filterType = project |
|
| jqlfilterID | If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID= | Only when filterType = jqlfilter |
|
| customjql | If filterType is customjql, system expects a JQL Query in the form customjql= | Only when filterType = customjql |
|
| sprintID | If filterType is sprint, system expects a Sprint ID in the form sprintID= | Only when filterType = sprint |
|
| columnsBy | Defines the column structure of the report. Possible options are:
| Yes |
|
| multiVisitBehavior | Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. |
| |
| pageSize | The maximum number of issues in a page. (1-200) The default is 200 and values greater than 200 or less than 0 will be processed as 200. | 50 | |
| startIssueIndex | The issue index to start at. The default value is 0. The resultset is always paged as exact multiples of pageSize. startIssueIndex points to a page of resultset rather than an individual issue. The app WILL NOT return a page that contains pageSize number of issues and starts with the issue specified with startIssueIndex. The app WILL rather return the page in the resultset that contains pageSize number of issue and includes the issue specified with startIssueIndex. (You don't need to worry about this behavior if you always use startIssueIndex as a multiple of pageSize) | 10 | |
| 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. For more information see TiS v4.24 - Field Names for REST Reports | assignee,customfield_10020,customfield_10007,description,duedate, fixVersions | |
| 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 v4.24 - Report Types Both system and custom fields are supported. For more information see TiS v4.24 - Field Names for REST Reports | only when columnsBy = anyfieldDuration or anyFieldCount | assignee,customfield_10020,customfield_10007,fixVersions |
| 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 v4.24 - 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"
]
}
]
| |
| 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" |
| |
| 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. 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:
If not provided, "true" is assumed. |
| |
| 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 | 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 | 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:
| Only when either startDate or endDate is provided |
|
| 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 | 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 | 2017-08-31 23:59 | |
calendar | The calendar that report durations will be calculated based on. Possible options are:
Tip: You can get the IDs of calendars using the Calendars endpoint, explained at the end of this page | Required for Duration reports |
|
| dayLength |
| Required for Duration reports with non-24/7 calendar |
|
| viewFormat | The format of duration data in the report. Possible options are:
If not provided, "minutes" will be used. |
| |
| dateFormat | The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS v4.24 - 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. |
| |
| dateTimeFormat | The string format to use for displaying values of fields of type DateTime If empty or missing, the datetime format defined in TiS v4.24 - 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. |
|
Examples
https://192.168.0.1/rest/tis/report/1.0/api/list?filterType=user&user=admin&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&viewFormat=minutes&pageSize=20 https://192.168.0.1/rest/tis/report/1.0/api/list?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=csv&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate&startIssueIndex=75 https://192.168.0.1/rest/tis/report/1.0/api/list?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&pageSize=90&startIssueIndex=5 https://192.168.0.1/rest/tis/report/1.0/api/list?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 https://192.168.0.1/rest/tis/report/1.0/api/list?filterType=customjql&customjql=project=ABC&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes https://192.168.0.1/rest/tis/report/1.0/api/list?filterType=sprint&sprintID=2&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=json&pageSize=5
Responses
Success
HTTP 200
Returns a list report as text (CSV or JSON)
{
"startIssueIndex": 0,
"endIssueIndex": 4,
"pageSize": 5,
"total": 23,
"dateTimeFormat": "yyyy-MM-dd hh:mm a",
"dateFormat": "yyyy-MM-dd",
"timeZone": "Asia/Istanbul",
"locale": "en-US",
"viewFormat": "minutes",
"version": "4.11.0.1",
"isComposite": false,
"columnsBy": "Status Duration",
"query": "project = SSPWSD AND created >= 1970-09-01 AND created <= 2020-12-31",
"reportDate": "2020-08-21 03:41 PM",
"includedStatuses": [],
"excludedStatuses": [
{
"id": "10001",
"name": "Done",
"deleted": false
}
],
"deletedStatuses": [],
"isAggregationType": false,
"isOverall": false,
"isAverage": false,
"isSum": false,
"table": {
"header": {
"headerColumns": [
{
"id": "issuekey",
"value": "Key"
},
{
"id": "summary",
"value": "Summary"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "Consolidated Column",
"containsStatuses": [
"3"
],
"isConsolidated": true,
"hint": "Contains In Progress"
},
{
"id": "3",
"value": "In Progress",
"isConsolidated": false
},
{
"id": "10000",
"value": "To Do",
"isConsolidated": false
}
]
},
"body": {
"rows": [
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-23"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "-"
},
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "4398.8132666667",
"raw": "263928796"
}
],
"currentState": []
},
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-22"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "-"
},
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "3780.0",
"raw": "226800000"
}
],
"currentState": []
},
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-21"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "-"
},
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "3200.8131666667",
"raw": "192048790"
}
],
"currentState": []
},
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-20"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "-"
},
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "1722.8131",
"raw": "103368786"
}
],
"currentState": []
},
{
"headerColumns": [
{
"id": "issuekey",
"value": "SSPWSD-19"
},
{
"id": "summary",
"value": "As a user, I'd like a historical story to show in reports"
}
],
"groupByColumns": [],
"fieldColumns": [],
"valueColumns": [
{
"id": "A",
"value": "-"
},
{
"id": "3",
"value": "-"
},
{
"id": "10000",
"value": "1080.0",
"raw": "64800000"
}
],
"currentState": []
}
]
}
},
"calendar": {
"id": "0",
"name": "Default Calendar Settings",
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false,
"startHour": 8,
"startMinute": 0,
"endHour": 17,
"endMinute": 0,
"holidaysText": null,
"timeZone": "Asia/Istanbul",
"holidaysWithDesc": [],
"holidaysWithoutDesc": [],
"holidayMap": {},
"default": true,
"startTime": "08:00",
"endTime": "17:00"
}
}
"Key","Summary","Consolidated Column","In Progress","To Do" "SSPWSD-23","As a user, I'd like a historical story to show in reports","-","-","4398.8132666667" "SSPWSD-22","As a user, I'd like a historical story to show in reports","-","-","3780.0" "SSPWSD-21","As a user, I'd like a historical story to show in reports","-","-","3200.8131666667" "SSPWSD-20","As a user, I'd like a historical story to show in reports","-","-","1722.8131" "SSPWSD-19","As a user, I'd like a historical story to show in reports","-","-","1080.0"
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.
{
"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": "4.9.0.1",
"time": "2020-09-04 15:21:37"
}
Synchronous File Export
GET /rest/tis/report/1.0/out/file
POST /rest/tis/report/1.0/out/file
Returns Time in Status report data, in one piece, as a file export.
Sychronous means you will call a single REST endpoint (with all the required parameters) to start the export and the response of the request will return the export file.
For Asynchronous File Exports, please see here
This type of file export might return a response in a few seconds for a few issues of data but it might also take tens of minutes for 6 digit datasets.
There is no option to track export progress for Synchronous File Exports. If you need to track progress, you should use Asynchronous File Exports
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.
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/out/file?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>&outputType=<outputType>&startDate=<startDate>&endDate=<endDate>&dateRangeField=<dateRangeField>
With all parameters:
<jira_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>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&groupByFields=<groupByFields>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| outputType | The output file format of the report. Possible options are:
| Yes |
|
| filterType | Defines how the issues to be included in the report will be selected. Possible options are:
| Yes |
|
| user | If filterType is user, system expects a user name in the form user= | Only when filterType = user |
|
| projectkey | If filterType is project, system expects a project key in the form projectKey= | Only when filterType = project |
|
| jqlfilterID | If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID= | Only when filterType = jqlfilter |
|
| customjql | If filterType is customjql, system expects a JQL Query in the form customjql= | Only when filterType = customjql |
|
| sprintID | If filterType is sprint, system expects a Sprint ID in the form sprintID= | Only when filterType = sprint |
|
| columnsBy | Defines the column structure of the report. Possible options are:
| Yes |
|
| 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:
For details please see TiS v4.24 - Aggregation |
| |
| multiVisitBehavior | Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. |
| |
| 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. For more information see TiS v4.24 - Field Names for REST Reports | assignee,customfield_10020,customfield_10007,description,duedate, fixVersions | |
| 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 v4.24 - Report Types Both system and custom fields are supported. For more information see TiS v4.24 - 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 for average 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 see TiS v4.24 - 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 v4.24 - 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"
]
}
]
| |
| 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" |
| |
| 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. Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation. | only when columnsBy = durationBetweenStatuses | [
{
"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:
If not provided, "true" is assumed. |
| |
| startDate | The start date of report filter. When provided, 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 | 2017-07-01 00:00 | |
| endDate | The end date of report filter. When provided, 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 | 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:
| Only when either startDate or endDate is provided |
|
| 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 | 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 | 2017-08-31 23:59 | |
calendar | The calendar that report durations will be calculated based on. Possible options are:
Tip: You can get the IDs of calendars using the Calendars endpoint, explained at the end of this page | Required for Duration reports |
|
| dayLength |
| Required for Duration reports with non-24/7 calendar |
|
| viewFormat | The format of duration data in the report. Possible options are:
If not provided, "minutes" will be used. |
| |
| dateFormat | The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS v4.24 - 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. |
| |
| dateTimeFormat | The string format to use for displaying values of fields of type DateTime If empty or missing, the datetime format defined in TiS v4.24 - 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. |
| |
| sortBy | The report column that will be sorted. Currently, only Status Duration 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 v4.24 - Sort | Only when sortBy is provided |
|
| sortDir | The direction in which sort will be applied. See TiS v4.24 - Sort | Only when sortDir is provided |
|
| 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:
Possible unit options:
| [
{
"column":"10000",
"operator":"greaterThanEquals",
"value":"10",
"unit":"day"
},
{
"column":"cons. status 1",
"operator":"lessThan",
"value":"5.5",
"unit":"hour"
}
]
|
Examples
https://192.168.0.1/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 https://192.168.0.1/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 https://192.168.0.1/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 https://192.168.0.1/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 https://192.168.0.1/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&sortBy=10123&sortDir=asc&dateFormat=yy-MM-dd&dateTimeFormat=yyyy-MM-dd HH:mm:ss
Response
The REST call returns an XLS, XLSX or CSV file that contains all the data in the report.
Asynchronous File Export
Returns Time in Status report data, in one piece, as a file export.
Asychoronous means (as a minimum) you will call a REST endpoint to start the export, call another REST endpoint to track its progress and (when completed) call yet another REST endpoint to download the file.
For Synchronous File Exports, please see here.
Start an export
POST /rest/tis/report/1.0/api/file
Starts the processing of an async file export.
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/file?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>&outputType=<outputType>&startDate=<startDate>&endDate=<endDate>&dateRangeField=<dateRangeField>
With all parameters:
<jira_url>/rest/tis/report/1.0/api/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>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&groupByFields=<groupByFields>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| outputType | The output file format of the report. Possible options are:
| Yes |
|
| filterType | Defines how the issues to be included in the report will be selected. Possible options are:
| Yes |
|
| user | If filterType is user, system expects a user name in the form user= | Only when filterType = user |
|
| projectkey | If filterType is project, system expects a project key in the form projectKey= | Only when filterType = project |
|
| jqlfilterID | If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID= | Only when filterType = jqlfilter |
|
| customjql | If filterType is customjql, system expects a JQL Query in the form customjql= | Only when filterType = customjql |
|
| sprintID | If filterType is sprint, system expects a Sprint ID in the form sprintID= | Only when filterType = sprint |
|
| columnsBy | Defines the column structure of the report. Possible options are:
| Yes |
|
| 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:
For details please see TiS v4.24 - Aggregation |
| |
| multiVisitBehavior | Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. |
| |
| 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. For more information see TiS v4.24 - Field Names for REST Reports | assignee,customfield_10020,customfield_10007,description,duedate, fixVersions | |
| 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 v4.24 - Report Types Both system and custom fields are supported. For more information see TiS v4.24 - 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 for average 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 see TiS v4.24 - 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 v4.24 - 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"
]
}
]
| |
| 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" |
| |
| 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. Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation. | only when columnsBy = durationBetweenStatuses | [
{
"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:
If not provided, "true" is assumed. |
| |
| 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 | 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 | 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:
| Only when either startDate or endDate is provided |
|
| 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 | 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 | 2017-08-31 23:59 | |
calendar | The calendar that report durations will be calculated based on. Possible options are:
Tip: You can get the IDs of calendars using the Calendars endpoint, explained at the end of this page | Required for Duration reports |
|
| dayLength |
| Required for Duration reports |
|
| viewFormat | The format of duration data in the report. Possible options are:
If not provided, "minutes" will be used. |
| |
| dateFormat | The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS v4.24 - 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. |
| |
| dateTimeFormat | The string format to use for displaying values of fields of type DateTime If empty or missing, the datetime format defined in TiS v4.24 - 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. |
| |
| sortBy | The report column that will be sorted. Currently, only Status Duration 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 v4.24 - Sort | Only when sortBy is provided |
|
| sortDir | The direction in which sort will be applied. See TiS v4.24 - Sort | Only when sortDir is provided |
|
| 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:
Possible unit options:
| [
{
"column":"10000",
"operator":"greaterThanEquals",
"value":"10",
"unit":"day"
},
{
"column":"cons. status 1",
"operator":"lessThan",
"value":"5.5",
"unit":"hour"
}
]
|
Examples
https://192.168.0.1/rest/tis/report/1.0/api/file?filterType=user&user=admin&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&viewFormat=minutes&outputType=xls https://192.168.0.1/rest/tis/report/1.0/api/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 https://192.168.0.1/rest/tis/report/1.0/api/file?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=xlsx&groupByFields=assignee,date:year:resolutiondate,date:week:resolutiondate https://192.168.0.1/rest/tis/report/1.0/api/file?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 https://192.168.0.1/rest/tis/report/1.0/api/file?filterType=customjql&customjql=project=ABC&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv https://192.168.0.1/rest/tis/report/1.0/api/file?filterType=sprint&sprintID=2&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv&sortBy=10123&sortDir=asc
Responses
Success
HTTP 200
When the parameters are validated and the export process has successfully started on the system.
{
"exportId": "6ac3af4e-1d2b-4886-8455-23932fc2620c",
"statusLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/6ac3af4e-1d2b-4886-8455-23932fc2620c"
}
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.
{
"statusCode": 400,
"messages": [
"ERROR: calendar parameter is required. Possible values are normalHours or ID of a custom defined calendar",
"ERROR: endDate parameter is required. Expected format is yyyy-MM-dd hh:mm<br>"
],
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:41:29"
}
Export Limit Exceeded
HTTP 429
When you start too many simultaneous file exports and exceed the concurrent export limit per user.
You should either wait for some fo the file exports to complete or cancel some of the running file exports.
{
"status": 429,
"messages": [
"ERROR: You've reached your concurrent export limit. Wait for running file exports to complete or cancel some of the running file exports."
],
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:52:29"
}
Get status of all exports
GET /rest/tis/report/1.0/api/file
A detailed list of async file exports in the system.
Supports paging
Request
<jira_url>/rest/tis/report/1.0/api/file
Parameters
Parameter | Description | Required |
|---|---|---|
| pageNumber | The page index to start at, when paging is employed. Works with zero-based index so pageNumber for the first page is 0. The default value is 0. | No |
| pageSize | The maximum number of items in a page. The default is 100 and values greater than 100 will be processed as 100 | No |
Examples
https://192.168.0.1/rest/tis/report/1.0/api/file https://192.168.0.1/rest/tis/report/1.0/api/file?pageNumber=10&pageSize=5
Responses
Success
HTTP 200
Returns a JSON that contains all file exports of your instance, running or completed.
{
"pageNumber": 2,
"pageSize": 5,
"totalExportCount": 24,
"last": false,
"exports": [
{
"exportId": "6a5c3529-af63-44e1-a17c-d3546b135db0",
"created": "24/Aug/20 5:21 PM",
"completed": 23,
"total": 23,
"downloadLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/download",
"status": "Successful"
},
{
"exportId": "abdcd876-b45e-4815-8f01-cdf20fd1fd0a",
"created": "24/Aug/20 5:14 PM",
"completed": 23,
"total": 23,
"downloadLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/download",
"status": "Successful"
},
{
"exportId": "09db197c-54d7-4409-a7d8-31be0f927dc4",
"created": "24/Aug/20 5:11 PM",
"completed": 23,
"total": 23,
"downloadLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/download",
"status": "Successful"
},
{
"exportId": "2e602b9a-9183-4042-84de-1a06ccb7d43d",
"created": "24/Aug/20 4:56 PM",
"message": "Report is aborted by user",
"status": "Aborted By User"
},
{
"exportId": "7916057a-c22c-4ea1-a371-2c72059472b2",
"created": "24/Aug/20 4:45 PM",
"completed": 23,
"total": 23,
"downloadLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/download",
"status": "Successful"
}
]
}
Invalid Paging Parameters
HTTP 400
When at least one of the providedg pagin parameters contain an invalid value.
{
"status": 400,
"message": "Invalid paging parameters.",
"messages": [
"For input string: \"two\""
],
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:17:23"
}
Get status of a single export
GET /rest/tis/report/1.0/api/file/
Details of a single async file export in the system.
Request
<jira_url>/rest/tis/report/1.0/api/file/<export_id>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| export_id | The id of the file export that you want to query the information for | Yes | d57e59ca-568a-43a0-8baa-2b86a404d1fc |
Example
https://192.168.0.1/rest/tis/report/1.0/api/file/d57e59ca-568a-43a0-8baa-2b86a404d1fc
Responses
Success
HTTP 200
Returns a JSON that contains detailed information of a file export.
{
"exportId": "c960b836-516b-45ac-b707-170114bdef74",
"created": "24/Aug/20 5:23 PM",
"completed": 23,
"total": 23,
"downloadLink": "https://192.168.0.1/rest/tis/report/1.0/api/file/c960b836-516b-45ac-b707-170114bdef74/download",
"status": "Successful"
}
Export Not Found
HTTP 404
When an export with the given export_id is not found. The export_id might be invalid or the export might belong to another user
{
"message": "The export with id 29c33054-64b3-44e5-8e01-2c71a7e4s could not be found or you do not have permission to view it.",
"statusCode": 404,
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:21:28"
}
Download export file
GET /rest/tis/report/1.0/api/file//download
Downloads the file for a completed async file export operation.
Request
<jira_url>/rest/tis/report/1.0/api/file/<export_id>/download
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| export_id | The id of the file export that you want to query the information for | Yes | 341abae0-e277-4302-a6f9-cd7b5643ddef |
Examples
https://192.168.0.1/rest/tis/report/1.0/api/file/341abae0-e277-4302-a6f9-cd7b5643ddef/download
Responses
Success
HTTP 200
Returns a file that contains the generated export data.
Export Not Found
HTTP 404
When an export with the given export_id is not found. The export_id might be invalid or the export might belong to another user.
{
"message": "The export with id 341abae0-e277-4302-a6f9-cd7b5643ddef could not be found or you do not have permission to view it.",
"statusCode": 404,
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:38:57"
}
Export Not Completed
HTTP 404
When the export is in a state other than Successful. The export might still be in progress, might be aborted or might have failed.
{
"message": "The report with id d6db17d3-40b6-4afd-a1f5-4b7639c4a08c is not completed. It is still being processed.",
"statusCode": 404,
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:49:05"
}
Export Failed
HTTP 404
When the export is in a state other than Successful. The export might still be aborted or might have failed.
{
"message": "The report with id d6db17d3-40b6-4afd-a1f5-4b7639c4a08c failed or is aborted.",
"statusCode": 404,
"messages": [
"Report is aborted by user"
],
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:51:54"
}
Abort an export
DELETE /rest/tis/report/1.0/api/file/
Abort a running async file export.
Request
<jira_url>/rest/tis/report/1.0/api/file/<export_id>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| export_id | The id of the file export that you want to query the information for | Yes | 341abae0-e277-4302-a6f9-cd7b5643ddef |
Examples
https://192.168.0.1/rest/tis/report/1.0/api/file/341abae0-e277-4302-a6f9-cd7b5643ddef
Responses
Success
HTTP 200
Returns a JSON that contains information about the aborted export.
{
"exportId": "b841b270-77b6-41d8-9d4f-25c48211a49c",
"created": "24/Aug/20 5:35 PM",
"completed": 1,
"total": 23,
"status": "Aborted By User"
}
Export Not Found
HTTP 404
When an export with the given export_id is not found. The export_id might be invalid or the export might belong to another user.
{
"message": "The export with id 3c2099ce-3874-4812-ad95-e8fecfdff821 could not be found or you do not have permission to view it.",
"statusCode": 404,
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:52:32"
}
Export Already Completed
HTTP 404
The file export was not aborted because the export was completed before the abort command was received by the process.
{
"message": "Could not abort since the report has already completed",
"statusCode": 404,
"pluginVersion": "4.9.0.1",
"time": "2020-09-04 16:32:54"
}
Calendars
GET /rest/tis/report/1.0/data/calendars
A list of calendars defined in the system with their IDs can be requsted through the following REST endpoint.
Request
<service_url>/rest/tis/report/1.0/data/calendars
Parameters
This request requires no parameters.
Examples
https://192.168.0.1/rest/tis/report/1.0/data/calendars
Responses
Success
HTTP 200
Returns a JSON that contains all calendars defined in your instance, including the predefined 7/24 (normalHours) Calendar and Default Calendar Settings.
{
"calendars": [
{
"id": "normalHours",
"name": "7/24",
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": true,
"sunday": true,
"workHours": "00:00 - 00:00",
"holidayList": [],
"holidays": [],
"timeZone": "Asia/Istanbul"
},
{
"id": "0",
"name": "Default Calendar Settings",
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false,
"workHours": "08:00 - 17:00",
"holidayList": [],
"holidays": [],
"timeZone": "Asia/Istanbul"
},
{
"id": 2,
"name": "Team A calendar",
"monday": true,
"tuesday": true,
"wednesday": true,
"thursday": true,
"friday": true,
"saturday": false,
"sunday": false,
"timeZone": "(UTC+03:00) Europe/Istanbul",
"startTime": "00:02",
"endTime": "17:00",
"holidayList": [
{
"date": "01/12/2019",
"applyEachYear": false,
"description": "Sample holiday"
}
],
"holidays": {
"01/12/2019": "Sample holiday"
}
}
]
}
The holidayList element in the JSON result returns data in a better structure. API consumers are strongly recommended to use this holiday array.
The holidays element is included just for backward compatibility and may be removed in future releases.
Statuses
GET /rest/api/2/status
You can use this endpoint to get the list of statuses (and their IDs) defined on your Jira instance.
Request
<service_url>/rest/api/2/status
Parameters
This request requires no parameters.
Examples
https://myjirainstance/rest/api/2/status
Details about this endpoint can be found in Atlassian Jira documentation.
Spreadsheet Automation Samples
You can also pull data from Time in Status REST API directly into your spreadsheet to automate reporting. For details, see: TiS Server and Data Center - Sample Spreadsheet Integration Files
While using the spreadsheet, use the Request Parameters table from Start an Export endpoint in this document as reference.
- No labels