Atlassian Jira

This Plugin is used on the integration of BizDock and a Jira.

Jira is the tracker for teams planning and building great products. Jira is a commercial software provided by Atlassian.

See https://www.atlassian.com/software/jira for more details about the software.

The BizDock plugin for Jira

The Jira Plugin is made to work with the BizDock plugin for Jira. This last should be directly installed on Jira thanks the “Atlassian Marketplace for JIRA”.

This section explain how to configure the BizDock plugin for Jira.

Install the BizDock plugin:

  1. In Jira, select “Add-ons” under the “JIRA ADMINISTRATION” menu,
  2. Search the plugin thanks the “BizDock” keyword,
  3. Click on Install.

Display the configuration page of the BizDock plugin:

  1. In Jira, select “Add-ons” under the “JIRA ADMINISTRATION” menu,
  2. Select “Manage add-ons” on the left menu,
  3. Select the BizDock plugin,
  4. Click on Configure.

Main configuration

The maint configuration allows to:

  • Generate a new secret key
  • Reset the initial configuration

The BizDock secret key should be used for the parameter “authentication.key” of the Jira plugin of BizDock.

Projects creation configuration

When an Initiative is activated for the Jira plugin (see the integration page for more details), it's possible to create a new Jira project. The “Projects creation configuration” allows to configure the default values for non-synchronized data, for example the project creator.

Data mapping configuration

The data mapping configuration allows to configure the attributes to use for the synchronisation beetween a Jira issue and a BizDock Requirement.

Some attributes are fixed and not modifiable:

Requirement (BizDock) Issue (Jira)
Name Summary
Description Description
Status Status
Priority Priority

Some attributes are fixed but modifiable:

Requirement (BizDock) Issue (Jira) Value type (Jira)
Author Creator Email address
Estimation Original Estimate Numeric, could be also a string that represents a numeric

Some attributes are not fixed and so modifiable:

Requirement (BizDock) Value type (Jira)
Category String
Severity String
Story points Numeric, could be also a string that represents a numeric
Is scoped Boolean, could be also a string that represents a boolean (“true” or “false”)

For modifiable attributes, it's possible to select any Jira field that is compatible with the “Value type”.

The severity attribute is particularly, because first it should be mapped to a Jira field, and then a mapping with BizDock Severities should be done on BizDock (see the Configuration of the BizDock plugin for more details).

Data filtering configuration

The data filtering configuration allows to manage the queries to get the needs and the defects from Jira.

Every ticket in Jira is considered as an issue, so it would be needed to specify which ones correspond to a need and which ones to a defect. To do this the “type” attribute of an issue is usually used, for example it should be equal to “Bug” for a defect.

To express the definition of needs and defects, the JQL syntax is used. It is closed of SQL and allows to make powerful filters.

The default queries are:

  • Needs: project = ${_jiraProjectKey_} AND issuetype in (Epic, Improvement, “New Feature”)
  • Defects: project = ${_jiraProjectKey_} AND issuetype = Bug

“project = ${_jiraProjectKey_}” is simply used to get only the issues of the correct Jira project, it should be not modified.

To specify the results, it's possible to add filters to the queries, for example:

project = ${_jiraProjectKey_} AND issuetype = Bug AND summary = "test"

Here is the list of Jira attributes that could be filtered:

Name Definition Type
aggregateprogress Σ Progress Numeric
aggregatetimeestimate Σ Remaining Estimate Numeric
aggregatetimeoriginalestimate Σ Original Estimate Numeric
aggregatetimespent Σ Time Spent Numeric
assignee Assignee String
components Component/s String
created Created Date
creator Creator String
description Description String
duedate Due Date Date
environment Environment String
fixVersions Fix Version/s String
issuekey Key String
issuelinks Linked Issues String
issuetype Issue Type String
labels Labels String
lastViewed Last Viewed Date
priority Priority String
progress Progress String
project Project String
reporter Reporter String
resolution Resolution String
resolutiondate Resolved date Date
security Security Level String
status Status String
subtasks Sub-Tasks String
summary Summary String
thumbnail Images String
timeestimate Remaining Estimate Numeric
timeoriginalestimate Original Estimate Numeric
timespent Time Spent Numeric
updated Updated Date
versions Affects Version/s String
votes Votes Numeric
watches Watchers String
workratio Work Ratio String

All Jira custom attributes are also available. To use one, the pattern cf[{custom_attribute_id}] should be used, for example cf[10201].

The Jira attributes could not only be filtered on static values, but also on Initiative attribute values. Here is the list of provided Initiative attributes:

Name Definition Type
id The ID Numeric
refId The reference ID String
governanceId The governance ID String
erpRefId The ERP reference ID String
name The name String
description The description String
creationDate The creation date Date
isPublic True for a public Initiative, false for a confidential Boolean
archived True for an archived Initiative, false for an active Boolean
manager The manager name, for example “James Dev” String
sponsoringUnit The sponsoring unit name String
deliveryUnits The list of delivery unit names List of String
portfolioEntryType The type String
portfolios The list of portfolio names List of String

The Initiative custom attributes are also available. To use one, the pattern ${customAttributes.{custom_attribute_id}} should be used, for example ${customAttributes.CUSTOM_ATTRIBUTE_PortfolioEntry_7}. The custom attribute IDs are displayed in the configuration page of Custom attributes.

Only the Initiative custom attributes with type “Boolean”, “Integer”, “Decimal”, “String” and “Date” are available.

Finally some filter examples:

... AND summary ~ "${name}"
... AND cf[10201] ~ "${customAttributes.CUSTOM_ATTRIBUTE_PortfolioEntry_7}"
... AND created > ${customAttributes.CUSTOM_ATTRIBUTE_START_DATE}

Data Type

The Jira Plugin is working with the following Data Type:

Data exchange

Events

The Jira Plugin is treating the following Events:

  • IN events (Jira to BizDock): none
  • OUT events (BizDock to Jira): none

Scheduler

The Jira Plugin is managing the following Schedulers:

  • Load the Jira's issues as Requirements, see the integration page for more details

Manual

The Jira Plugin is managing the following manual actions:

  • Create a Jira's project with the Initative data, see the integration page for more details

Admin Commands

This Plugin provides one Admin Command:

  • Load Jira configuration: load the Jira statuses, priorities and severities, and prefill the corresponding mapping configurations (Requirement status mapping, Requirement priority mapping and Requirement severity mapping). After calling this command the mapping configurations should be completed with the BizDock corresponding ID (see the Configuration section for more details). If this command is called many times, then the existing mapping configurations are just adapted with new or removed entries.

Configuration

This Plugin the following configurations:

  • Global properties: Properties configuration
    • host.url: the url of the Jira instance. Don't forget to add a “\” before the “:” like this “https\:/” and no trailing “/” at the end of the url.
    • authentication.key: a valid API key for the BizDock plugin of Jira.
    • api.version: the version of the BizDock plugin of Jira.
    • pe.load.start.time: define when the load should start (time). Default value is 03h00.
    • pe.load.frequency: define how regularly (in minutes) the load should run.
  • Requirement status mapping: Properties configuration
    • Mapping between the Jira and the BizDock status. Each row is represented by “{Jira status ID}={BizDock status ID}”, for example “IN_PROGRESS=4”.
  • Requirement severity mapping: Properties configuration
    • Mapping between the Jira severities and the BizDock severities. Each row is represented by “{Jira severity ID}={BizDock severity ID}”, for example “SHOWSTOPPER=4”.
  • Requirement priority mapping: Properties configuration
    • Mapping between the Jira and the BizDock priorities. Each row is represented by “{Jira priority ID}={BizDock priority ID}”, for example “BLOCKER=4”.