--- title: "Calculate histograms over JIRA issue activities." method: POST path: "/histograms/jira" tags: ["histograms", "default"] --- # Calculate histograms over JIRA issue activities. `POST /histograms/jira` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/histograms/jira` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - JIRAHistogramsRequest: Request of `/histograms/jira`. - `priorities` string[]: Selected issue priorities. - `types` string[]: Selected issue types. - `epics` JIRAEpic[] - `id` string, required: JIRA issue key `PROJECT-###`. - `title` string, required: Title of this issue. - `created` string, date-time, required: When this issue was created. - `updated` string, date-time, required: When this issue was last updated. - `work_began` string, date-time: When the issue entered the "In Progress" stage or received a PR. This timestamp can be missing and is always less than or equal to `resolved`. - `resolved` string, date-time: When the issue finished: the stage is "Done" and all PRs are either released or rejected. This timestamp can be missing and is always greater than or equal to `work_began`. - `acknowledge_time` string, required: Time duration value. - `lead_time` string: Time duration value. - `life_time` string, required: Time duration value. - `reporter` string, required: Name of the person who reported the issue. - `assignee` string: Name of the assigned person. - `comments` integer, required: Number of comments in the issue excluding sub-tasks and children. - `comment_list` JIRAComment[]: The list of comments for the issue. - `author` string, required: The name of the user who created the comment. - `created` string, date-time, required: The date and time at which the comment was created. - `rendered_body` string, required: The comment text. - `priority` string, nullable, required: Name of the priority. The details are returned in `FilteredJIRAStuff.priorities`. - `rendered_description` string: The description of the issue rendered as HTML. - `status` string, required: Name of the status. The details are returned in `FilteredJIRAStuff.statuses`. - `story_points` number: Value of the "story points" field. - `type` string, required: Name of the issue type. The details are returned in `FilteredJIRAStuff.issue_types`. - `url` string, url, required: Link to the issue in JIRA web application. - `project` string, required: Identifier of the project where this epic exists. - `children` JIRAEpicChild[]: Details about the child issues. - `id` string, required: JIRA issue key `PROJECT-###`. - `title` string, required: Title of this issue. - `created` string, date-time, required: When this issue was created. - `updated` string, date-time, required: When this issue was last updated. - `work_began` string, date-time: When the issue entered the "In Progress" stage or received a PR. This timestamp can be missing and is always less than or equal to `resolved`. - `resolved` string, date-time: When the issue finished: the stage is "Done" and all PRs are either released or rejected. This timestamp can be missing and is always greater than or equal to `work_began`. - `acknowledge_time` string, required: Time duration value. - `lead_time` string: Time duration value. - `life_time` string, required: Time duration value. - `reporter` string, required: Name of the person who reported the issue. - `assignee` string: Name of the assigned person. - `comments` integer, required: Number of comments in the issue excluding sub-tasks and children. - `comment_list` JIRAComment[]: The list of comments for the issue. - `author` string, required: The name of the user who created the comment. - `created` string, date-time, required: The date and time at which the comment was created. - `rendered_body` string, required: The comment text. - `priority` string, nullable, required: Name of the priority. The details are returned in `FilteredJIRAStuff.priorities`. - `rendered_description` string: The description of the issue rendered as HTML. - `status` string, required: Name of the status. The details are returned in `FilteredJIRAStuff.statuses`. - `story_points` number: Value of the "story points" field. - `type` string, required: Name of the issue type. The details are returned in `FilteredJIRAStuff.issue_types`. - `url` string, url, required: Link to the issue in JIRA web application. - `subtasks` integer, required: Number of sub-tasks. - `prs` integer, required: Number of mapped pull requests. - `prs` integer, required: Overall number of mapped pull requests (including the children). - `labels_include` string[]: PRs must relate to at least one JIRA issue label from the list. Several labels may be concatenated by a comma `,` so that all of them are required. - `labels_exclude` string[]: PRs cannot relate to JIRA issue labels from the list. - `with` JIRAFilterWith[]: Groups of issue participants. The histograms will be calculated for each group. - `assignees` string[]: Selected issue assignee users. `null` means unassigned. - `reporters` string[]: Selected issue reporter users. - `commenters` string[]: Selected issue commenter users. - `projects` string[]: Issues must belong to these JIRA projects. - `histograms` JIRAHistogramDefinition[], required: Histogram parameters for each wanted topic. - `metric` 'jira-open' | 'jira-resolved' | 'jira-raised' | 'jira-acknowledged' | 'jira-acknowledged-q' | 'jira-life-time' | 'jira-life-time-below-threshold-ratio' | 'jira-lead-time' | 'jira-lead-time-below-threshold-ratio' | 'jira-acknowledge-time' | 'jira-acknowledge-time-below-threshold-ratio' | 'jira-pr-lag-time' | 'jira-backlog-time' | 'jira-resolution-rate', required: Currently supported JIRA activity metrics. * `jira-open` - number of issues active by the end of the time interval. * `jira-resolved` - number of issues closed in the given time range. * `jira-raised` - number of issues reported in the given time range. * `jira-acknowledged` - number of issues that are "In Progress" or "Resolved". This number matches the issues considered to calculate `jira-acknowledge-time` before applying the quantiles. * `jira-acknowledged-q` - number of issues that are "In Progress" or "Resolved". This number matches the issues considered to calculate `jira-acknowledge-time` after applying the quantiles. * `jira-life-time` - Mean Life Time - the time between min(issue creation, work began) and max(issue resolution, fixes released). * `jira-life-time-below-threshold-ratio` - ratio of issues with a `jira-life-time` below the threshold, disregarding the quantiles. The default threshold is 5 days. * `jira-lead-time` - Mean Lead Time - the time between when the work began and max(issue resolution, fixes released). * `jira-lead-time-below-threshold-ratio` - ratio of issues with a `jira-lead-time` below the threshold, disregarding the quantiles. The default threshold is 5 days. * `jira-acknowledge-time` - Mean Acknowledge Time - the time between when the issue was created and the work began = `min(transitioned to "In Progress", PR created)`. It equals to 0 for retrofitted issues with PRs before their creation times. * `jira-acknowledge-time-below-threshold-ratio` - ratio of issues with a `jira-acknowledge-time` below the threshold, disregarding the quantiles. The default threshold is 3 days. * `jira-pr-lag-time` - the time between when the issue transitioned to "In Progress" and the first PR was created. It equals to 0 if the difference is negative or no PRs are mapped to the issue. * `jira-backlog-time` - the time between when the issue was created and transitioned to "In Progress". * `jira-resolution-rate` - ratio between the number of resolved issues to the number of raised issues. - `scale` 'linear' | 'log': Histogram's X axis scale. - `bins` integer: Number of bars in the histogram. 0 or null means automatic. - `ticks` union[]: Alternatively to `bins` and `scale`, set the X axis bar borders manually. Only one of two may be specified. The ticks are automatically prepended the distribution minimum and appended the distribution maximum. - union - number - string: Time duration value. - `date_from` string, date, required: Date from when to start measuring the distribution. - `date_to` string, date, required: Date until which to measure the distribution. - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`. - `exclude_inactive` boolean, required: Value indicating whether issues with the last update older than `date_from` should be ignored. - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting. - `account` integer, required: Session account ID. ## Response `200` Calculated histograms. - CalculatedJIRAHistogram[]: Response from `/histograms/jira`. - `with` JIRAFilterWith: Group of JIRA issue participant names split by role. - `assignees` string[]: Selected issue assignee users. `null` means unassigned. - `reporters` string[]: Selected issue reporter users. - `commenters` string[]: Selected issue commenter users. - `metric` 'jira-open' | 'jira-resolved' | 'jira-raised' | 'jira-acknowledged' | 'jira-acknowledged-q' | 'jira-life-time' | 'jira-life-time-below-threshold-ratio' | 'jira-lead-time' | 'jira-lead-time-below-threshold-ratio' | 'jira-acknowledge-time' | 'jira-acknowledge-time-below-threshold-ratio' | 'jira-pr-lag-time' | 'jira-backlog-time' | 'jira-resolution-rate', required: Currently supported JIRA activity metrics. * `jira-open` - number of issues active by the end of the time interval. * `jira-resolved` - number of issues closed in the given time range. * `jira-raised` - number of issues reported in the given time range. * `jira-acknowledged` - number of issues that are "In Progress" or "Resolved". This number matches the issues considered to calculate `jira-acknowledge-time` before applying the quantiles. * `jira-acknowledged-q` - number of issues that are "In Progress" or "Resolved". This number matches the issues considered to calculate `jira-acknowledge-time` after applying the quantiles. * `jira-life-time` - Mean Life Time - the time between min(issue creation, work began) and max(issue resolution, fixes released). * `jira-life-time-below-threshold-ratio` - ratio of issues with a `jira-life-time` below the threshold, disregarding the quantiles. The default threshold is 5 days. * `jira-lead-time` - Mean Lead Time - the time between when the work began and max(issue resolution, fixes released). * `jira-lead-time-below-threshold-ratio` - ratio of issues with a `jira-lead-time` below the threshold, disregarding the quantiles. The default threshold is 5 days. * `jira-acknowledge-time` - Mean Acknowledge Time - the time between when the issue was created and the work began = `min(transitioned to "In Progress", PR created)`. It equals to 0 for retrofitted issues with PRs before their creation times. * `jira-acknowledge-time-below-threshold-ratio` - ratio of issues with a `jira-acknowledge-time` below the threshold, disregarding the quantiles. The default threshold is 3 days. * `jira-pr-lag-time` - the time between when the issue transitioned to "In Progress" and the first PR was created. It equals to 0 if the difference is negative or no PRs are mapped to the issue. * `jira-backlog-time` - the time between when the issue was created and transitioned to "In Progress". * `jira-resolution-rate` - ratio between the number of resolved issues to the number of raised issues. - `scale` 'linear' | 'log', required: X axis scale: linear or logarithmic. - `ticks` union[], required: Series of horizontal bar borders aka X axis. Their count is `len(y) + 1` because there are `N` intervals between `(N + 1)` ticks. - union - number - string: Time duration value. - `frequencies` integer[], required: Series of histogram bar heights aka Y axis. - `interquartile` Interquartile, required: Middle 50% range. - `left` union, required - number - string: Time duration value. - `right` union, required - number - string: Time duration value. ## Other responses - `400`: The request is invalid. - `403`: The user is forbidden to access the specified repositories on behalf of the specified account. - `404`: The specified account does not exist or the user is not a member. - `422`: The account's installation has not finished yet. ## Changes - **2023-04-14** `4dcbf99639b4`: 2 breaking - added the new required request property `epics/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/acknowledge_time` - added the new required request property `epics/items/allOf[subschema #2]/children/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/acknowledge_time` - **2023-04-07** `63ec2eb2e4b3`: 1 warning, 1 info - added the new `jira-acknowledge-time-below-threshold-ratio` enum value to the `items/metric` response property for the response status `200` - added the new `jira-acknowledge-time-below-threshold-ratio` enum value to the request property `histograms/items/metric` - **2023-03-10** `0cc28e1bffc4`: 2 info - added the new optional request property `epics/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/rendered_description` - added the new optional request property `epics/items/allOf[subschema #2]/children/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/rendered_description` - **2023-03-06** `ad9d052dadbd`: 2 info - added the new optional request property `epics/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/comment_list` - added the new optional request property `epics/items/allOf[subschema #2]/children/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/comment_list` - …earlier changes not shown [Operation history](https://skmtc.dev/athenian/apis/title/changes/histograms/jira/post.md) --- [API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)