POST /rest/export

Starts the asynchronous processing of an export file.

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:

<service_url>/rest/export?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>&outputType=<outputType>

With all parameters:

<service_url>/rest/export?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

paramSetId

The ID of the reference parameter set that will used to infer parameters.

See TiS Cloud - Getting reports with Parameter Sets for details about getting reports with a reference parameter set.


  • 276d7bea-f4df-49e6-b231-1b15d4ed852a
outputType

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

  • XLS = Returns an Excel file in XLS format that contains the list, averages, sums, median and standard deviation.
  • XLSX = Returns an Excel file in XLSX format that contains the list, averages, sums, median and standard deviation.
  • CSV = Returns a CSV (comma separated value) file that contains the report data.
  • CSVAVERAGE = Returns a CSV (comma separated value) file that contains only calculated averages.
  • CSVSUM = Returns a CSV (comma separated value) file that contains only sums of values.
  • CSVMEDIAN = Returns a CSV (comma separated value) file that contains only calculated median.
  • CSVSTDDEV = Returns a CSV (comma separated value) file that contains only calculated standard deviation.
Yes
  • xls
  • xlsx
  • csv
  • csvaverage
  • csvsum
  • csvmedian
  • csvstddev
filterType

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

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

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

Only when filterType = user
  • user=admin
projectkey

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

Only when filterType = project
  • projectKey=ABC
jqlfilterID

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

Only when filterType = jqlfilter
  • jqlFilterID=10145
customjql

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

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

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

Only when filterType = sprint
  • sprintID=2
columnsBy

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

  • statusDuration = Report will show durations spent on each status as column values
  • durationBetweenStatuses = Report will show the durations spent between two statuses as column values.
  • statusDurationByTimePeriod = Report will show durations spent on each status in each time-period as column values
  • timePeriodDurationByStatus = Report will show durations spent in each time-period on each status as column values
  • assigneeDuration= Report will show durations spent on each assignee as column values
  • statusDurationByAssignee = Report will show durations spent on each status on each assignee as column values
  • assigneeDurationByStatus = Report will show durations spent on each assignee on each status as column values
  • groupDuration= Report will show consolidated durations spent on members of each group as column values
  • 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
  • lastTransitionFromStatusDate = Report will show the date the issue transitioned FROM each status for the LAST time as column values
Yes
  • statusDuration
  • durationBetweenStatuses
  • statusdurationbytimeperiod
  • timeperioddurationbystatus
  • assigneeDuration
  • statusDurationByAssignee
  • assigneeDurationByStatus
  • groupDuration
  • statusDurationByGroup
  • groupDurationByStatus
  • anyFieldDuration
  • statusCount
  • transitionCount
  • anyFieldCount
  • firstTransitionFromStatusDate
  • firstTransitionToStatusDate
  • lastTransitionFromStatusDate
  • lastTransitionToStatusDate
timePeriod

The time period to use for statusDurationByTimePeriod and timePeriodDurationByStatus report types. Has no effect on other report types.

Possible values are:

  • Year
  • Quarter
  • Month
  • Week
  • Day

If not defined, Month will be used as the default value.


  • Year
  • Quarter
  • Month
  • Week
  • Day
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 Cloud - Report Options


  • nonNull
  • rowCount
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 Cloud - Multi Visit Behavior


  • total
  • first
  • last
  • average
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 Cloud - 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 Cloud - Report Types

Both system and custom fields are supported. For more information see TiS Cloud - Field Names for REST Reports

only when columnsBy = anyfieldDuration or anyFieldCountassignee,customfield_10020,customfield_10007,fixVersions
groupByFields

The IDs of fields (separated by commas) on JIRA Issue that will be used to group issues for aggregated 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 Cloud - Field Names for REST Reports


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

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

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

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

Supports two formats: Basic and Advanced


Basic:

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


Advanced:

Advanced format is a JSON text that contains status definitions.

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

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

Please refer to Jira Cloud REST API Documentation to get the IDs of your users


  • 557058:0d90377f-13ee-4313-9f66-00555aa280e3
  • 557058:0d90377f-13ee-4313-9f66-00555aa280e3, 5f3a9d459a01310041a64ecc
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 (or status sets) and consists of the following parameters:


name: (required)

Name of the metric. Can only include alphanumeric characters and space.


from:

The starting status(es) that the duration will be calculated from. Its format should be a JSON object contains id and order (first/last) of the status(es).

Not defining this parameter means that the starting point will be "issue creation".


to: (required)

The target status(es) that the duration will be calculated until. Its format should be a JSON object contains id and order (first/last) of the status(es).


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.

See TiS Cloud - Report Types

only when columnsBy = durationBetweenStatuses
[
   {
      "name":"Resolution time",
      "to":{
         "id":["5", "7"],
         "order":"first"
      }
   },
   {
      "name":"Development time",
      "from":{
         "id":["1", "2", "3"],
         "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.

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

See Date Range


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

See 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 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 Date Range


2017-08-31 23:59

calendar

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

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

Tip: You can get the IDs of calendars using the Calendars endpoint.

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
  • 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"

If not provided, "minutes" will be used.


  • humanReadable
  • ddhhmmss
  • hhmmss
  • days
  • hours
  • minutes
  • seconds
dateFormat

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

If empty or missing, the date format defined in 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 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 Sort

Only when sortDir is provided
  • 10000
  • my cons. status 1
  • 5da17d34md123e99d4213c73
sortDir

The direction in which sort will be applied.

See 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, Duration Between Statuses and Status Count 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 Cloud - 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

https://tis.obss.io/rest/export?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://tis.obss.io/rest/export?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://tis.obss.io/rest/export?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://tis.obss.io/rest/export?filterType=jqlfilter&jqlFilterID=10004&columnsBy=statusDuration&multiVisitBehavior=average&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv

https://tis.obss.io/rest/export?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://tis.obss.io/rest/export?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": "d57e59ca-568a-43a0-8baa-2b86a404d1fc",
    "statusLink": "https://tis.obss.io/rest/export/d57e59ca-568a-43a0-8baa-2b86a404d1fc"
}

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.

{
    "status": 400,
    "message": "Invalid report parameters",
    "messages": [
        "ERROR: filterType parameter is required. Possible Values are user, project, jqlfilter, customjql and sprint",
        "ERROR: Invalid outputType value: 'pdf'. Output type should be one of these parameters 'xls, xlsx, csv or csvClassic, csvAverage' when request is sent to get a file"
    ],
    "pluginVersion": "1.18.0.1",
    "time": "2020-03-19 05:08:11"
}

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,
    "message": "You've reached your concurrent export limit. Wait for running file exports to complete or cancel some of the running file exports.",
    "messages": null,
    "pluginVersion": "1.18.0.1",
    "time": "2020-03-19 05:54:29"
}
  • No labels