Integrate Jira Information into CodeScene¶

CodeScene’s Jira integration is optional, but highly recommended if you have the information required for the analyses:

The Jira issue numbers are included/referenced in the commit messages.
You use labels and/or issue types in Jira to distinguish different kinds of work (e.g. Bugs, Features).

When present, CodeScene’s Jira integration lets you measure:

Accumulated costs per hotspot and sub-system.
Trends by work type, such as “Planned” versus “Unplanned” work.

The use cases for the Jira integration are described in Project Management Analyses.

Connect CodeScene to Jira¶

Previously, a separate service was required to connect CodeScene to Jira. Thi is no longer necessary because CodeScene can now connect directly to the Jira API. If you are still using the CodeScene Jira plugin, the documentation is available here: The CodeScene Jira integration service. However, we recommend using the new direct connection which also provides access to the latest analysis features.

Jira configuration is per project. Go to the “Project Management Integration” tab in your project’s configuration. Select “Jira” and click on “Save Configuration”:

Fig. 26 Start by selecting “Jira”¶

When you save the configuation, the form for configuring your Jira connection will appear:

Fig. 27 Jira configuration options¶

Fill in your Jira credentials here. We recommend using a Jira API token as the password. External Project ID is the Jira identifier for your project.

Fig. 28 “External Project ID” would be FJ¶

If an issue in your project looks like this, the External Project ID would be FJ.

Submitting the form with the “Test connection” box checked will cause CodeScene to immediately attempt to connect to your Jira provider.

When Use Issues for Hotspot Defect Statistics is checked, CodeScene will rely on Jira information for identifying defects rather than matching strings in commit messages. This affects how CodeScene compiles statistics related to the frequency of bugs in a codebase.

The remaining fields concern how CodeScene will interpret the Jira issues in your project.

Fig. 29 These fields determine how your data will be applied to the project¶

Cost Field and Cost Unit tell CodeScene how to calculate costs. There are three strategies which correspond to the three possibilities in the Cost Unit field:

Issues: the number of issues associated with a given file or architectural component
Points: the cost of an Issue in /Story points/.
Minutes: the cost expressed in time. This method requires that time has been reported on the specified cost-field in JIRA.

To use Issues, it is not necessary to configure Cost Field. For Points or Minutes, see the sections Using Story Points as Cost Estimation in Jira and Using Reported Time as Cost Estimation in Jira below.

The Supported Work Types should correspond to the different kinds of issue labels defined in your Jira project, in a semi-colon separated list. Please note that only types with the listed labels/type will be included in the analysis.

The Rename Work Types field allows the work types to be mapped to different analytical categories that you can define yourself. How you do this depends on the type of analysis you wish to perform.

When looking at cost trends, the most interesting distinction is typically between Planned- versus Unplanned Work. When available, the Jira labels will be translated to the specified label before being sent to CodeScene. For example, if your Jira project contains Feature and Documentation labels, like in the illustration above, these can be categorized together as Planned Work, while Bug and Defect are treated as Unplanned Work; the Refactoring label – which doesn’t have a translation – will be sent as is. Mapping labels this way can allow you to see more meaningful trends. You are free to map labels however you like depending on your analytical needs.

The Defect and Failure Labels pecify the JIRA labels and/or JIRA Issue Types that will be regarded as defects. Note that this is independent from the Supported Work Types configuration (eg. a label added here will be used even if it is not present in Supported Work Types)

The Ticket ID Pattern is a regular expression that tells CodeScene how to extract the Jira ID from commit messages. For most projects that use the standard PROJ-123 format, the default pattern will work: (.+-d+).

Using Story Points as Cost Estimation in Jira¶

When JIRA is configured to use Story Points as estimate for stories, epics, and possibly other issue types, the points will be added in a custom field JIRA creates for this purpose when Story Points is configured. The custom field will get a generated id. In order to be able to configure the PM integration service correctly, this custom field needs to be identified. The following command (against the JIRA service) using curl and jq will filter out the custom field for a project with the key CSE2 (see Atlassian Answers):

$ curl -u 'jirauser:jirapwd' \
'https://jira.example.com/rest/api/latest/issue/createmeta?expand=projects.issuetypes.fields'\
|jq '.projects[]|select(.key=="CSE2")|.issuetypes[]|select(.name=="Story")|.fields|with_entries(select(.value.name=="Story Points"))'
{
  "customfield_10006": {
    "required": false,
    "schema": {
      "type": "number",
      "custom": "com.atlassian.jira.plugin.system.customfieldtypes:float",
      "customId": 10006
    },
    "name": "Story Points",
    "hasDefaultValue": false,
    "operations": [
      "set"
    ]
  }
}

You can verify that this is in fact the field with the Story Points. Say that you already have a story CSE2-257 with Estimate: 4 filled in, then you can find the field name and verify the points with this command:

$ curl -u 'jirauser:jirapwd' \
https://jira.example.com/rest/api/latest/issue/CSE2-257
{
  ...
  "fields": {
    ...
    "timetracking": {},
    "customfield_10006": 4,

Using Reported Time as Cost Estimation in Jira¶

When using Minutes instead of Points, CodeScene searches Jira for the configured field name, usually timeoriginalestimate, having a non-empty value:

curl -u 'jirauser:jirapwd' \
'https://jira.example.com/rest/api/latest/search?jql=project=CSE2+and+timeoriginalestimate!=NULL'

Custom fields, however, cannot be searched like regular fields. Unfortunately, it seems it’s not possible to just use the complete field name, customfield_10006:

$ curl -u 'jirauser:jirapwd' \
'https://jira.example.com/rest/api/latest/search?jql=project=CSE2+and+customfield_10006!=NULL'
{
  "errorMessages": [
    "Field 'customfield_10006' does not exist or you do not have permission to view it."
  ],
  "errors": {}
}

Instead, there is a variant that uses cf[ID] (see the JIRA documentation), where ID is the id of the custom field, in our case 10006. Note that the brackets must be URL-encoded, so cf[10006] turns into cf%5B10006%5D:

curl -u 'jirauser:jirapwd' \
'https://jira.example.com/rest/api/latest/search?jql=project=CSE2+and+cf%5B10006%5D!=NULL'|jq .

This means that the code for sync must detect whether a custom field is being used, extract the id, and use that in the query.

Table of Contents

Previous topic

Next topic

Integrate Jira Information into CodeScene¶

Connect CodeScene to Jira¶

Using Story Points as Cost Estimation in Jira¶

Using Reported Time as Cost Estimation in Jira¶