1. David Boyd Avatar David Boyd
  2. Untitled project
  3. javascript-charts-for-jira-cloud

Wiki

Clone wiki

javascript-charts-for-jira-cloud / Chart Options

View History

Chart Options

Agile Board

Default Value: none

Select a board to use for the chart dates. The dates for the time axis will then be taken from whichever sprint is active each time the chart loads.

Chart Height

Default Value: null - Chart height is automatically calculated

To override the height, set this value to your desired height in px.

Parameters

  • height {number} height in px (min: 100, max: 4096)

Cutoff Date

Default Value: null - The chart will display up to the current date

If you want a chart to display up to a specific date (past or future) you can select a new date with this option.

Note: To cancel a cutoff date, once set, re-click on the selected date on the calendar again.

Dates

Default Value: Custom Dates - The user will define the dates for the chart

Parameters

  • Custom Dates define your own dates
  • Active Sprint use dates from an Active Sprint on a specific agile board

Days Previously

Default Value: 365 - the chart will display data over the previous year

Used to override how far back in time the chart should display data (in days)

JQL

Filter issues via JQL query

This is where you can define a custom query to determine which issues will be included in the chart. If you have never searched JIRA using a JQL query before, please read this guide before continuing.

Pro-tip: When building a chart it is advantageous to have another browser tab open with the JIRA Issue Search page where you can verify that your JQL query is returning the issues you expect

In general, the JQL you enter here is fairly straighforward. For example if you want to graph the number of issues created each month in multiple projects you can do:

project in (X, Y, Z)

where X,Y,Z are the project keys

For the Time Series option mentioned above: None (graph total issues returned) The JQL query is repeated once for each time period on the chart and the number of issues returned is graphed, rather than using a specific time series field (eg. created date) from each issue for the chart. This option is useful for showing the total number of issues growing or shrinking over time. The add-on will append DURING (X,Y) to the JQL query in the background, substituting X and Y for each period of the chart. This means that the JQL must be written in the past tense.

project in (X, Y, Z) and status was "To Do"

resolution changed to "Fixed" by currentUser()

project = PWC AND status CHANGED FROM "In Progress" TO "Resolved" BY jsmith

Please see the section JQL-based archeology with history operators from this blog, for a way better explanation. Please note again, that the DURING (X, Y) part of the query is added by this add-on automatically, but if you are validating your query in the JIRA Issue Search page, you will need to add it yourself.

The same applies to the specifiers $BEGIN and $END which are replaced with the start and end of the time period, and which can be used for further filtering of issues project = PWC AND created <= $END

Parameters

  • jql [string][3] (max length=1024)

Axis

Default Value: none

Defines which axis a label or gridline is associated with. Only applies when the dataset type is set to 'gridline'

Parameters

  • X
  • Y

Data set name

Default Value: none

Defines the name of the dataset, which will be displayed on the chart legend

Parameters

  • name [string][3] Name of the dataset (max length: 40 chars)

Type

Default Value: line

Parameters

  • line
  • bar
  • area
  • spline
  • gridline This is used to add a label to a specific point on a chart axis

Value

Default Value: none

The axis value at which to place a gridline label.

If the Axis value is 'X' the label must be in the form YYYY-MM-DD HH:MM.

If the Axis value is 'Y' the label must be a number

Parameters

  • label [string][3] (max length=16 chars)

Label

Default Value: none

Defines the text displayed for a gridline label on the chart. Only visible when the dataset type is set to 'gridline'

Parameters

  • label [string][3] maximum length of 32 chars

Time Series Field

Default Value: none

While the y-axis of each graph shows the count of issues returned from the JQL query, each issue needs to be mapped to a point on the x-axis (time). But the time value for each issue could be different. So, when configuring the chart it is necessary to define which date/time you want to use when graphing the issue count. For example, in the JIRA instance I use, each issue is associated with the following dates and times:

Parameters

  • Created
  • Resolved
  • Updated
  • Due Date
  • Last Viewed
  • etc ...
  • None (graph total issues returned) - This one is a bit tricky. It is here to allow you to do historical queries of JIRA issues. For example, if you wanted to know how many issues were in an Open state each week, then this is the option you need. Selecting this option requires you to write the JQL query carefully.

Y axis

Default Value: Issue Count

What value to use for the y-axis for this dataset.

Parameters

  • Issue Count
  • Story Points sums the story points for all issues found
  • etc ...

Average per issue

Default Value: false - y-axis value will not be averaged per issue

You can divide the y-axis value by the number of issues found

Set dataset color

Default Value: none - color will be chosen automatically

You can define permanent colors for each dataset. These will be maintained between chart views.

Line width

Default Value: 1

Defines the line width used on the chart. Only applies when the dataset type is set to 'line'

Parameters

  • width [number][4] width in px (min: 1, max 10)

Connect Gaps

Default Value: false - When no issues are found, a 0 y-value is included in the dataset

When set to true, a null value is added to the dataset and the chart will join the gap

Parameters

  • true
  • false

Y scaling factor

Default Value: 1

Some values in Jira are stored as seconds. This field allows division of the Y axis by a scaling factor. eg. To convert seconds to mins = 60

Parameters

  • factor [number][4] value to divide by (min: 1)

Show Grid

Default Value: false - no grid is overlayed on the chart

Will overlay a grid on the chart

Parameters

  • true
  • false

Chart Style

Default Value: Plotly

This add-on utilises publicly available JavaScript charting libraries to build its charts. The intention is to support as many popular JavaScript charting libraries as possible. If your library is not here, or you would like an additional one added, please use the "Links" menu to contact the vendor

Parameters

Period

Default Value: Monthly

This is the value of the time series 'bins'. On the chart there will be one datapoint per period. If there is no Time Series Field selected for a dataset, then the chart will be calculated based on issues returned from the JQL query executed for each period

Parameters

  • Hourly
  • Daily
  • Weekly
  • Biweekly
  • Monthly
  • Yearly

Theme

Default Value: Light

Atlassian theme value for the UI.

Parameters

  • light
  • dark

Chart Title

Default Value: none

The title displayed on the dashboard gadget. The title has a maximum length of 64 chars.

Y axis max

Default Value: null - Maximum value for Y axis is automatically calculated

To override the Y-axis Maximum value, set this value

Parameters

  • value {number} Y axis minimum value to show (min: 0, max: 65535)

Y axis min

Default Value: null - Minimum value for Y axis is automatically calculated

To override the Y-axis minimum value, set this value

Parameters

  • value {number} Y axis minimum value to show (min: 0, max: 65535)

[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global Objects/String

[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global Objects/Number

Updated