The CodeScene Jira integration service¶

This Jira integration is provided by a separate service that you deploy independently of CodeScene. You should have received a download link for the Jira integration service in your license email from Empear.

When run in Tomcat, you need to specify the required JNDI context paths in the file conf/Context.xml in Tomcat 7. Here’s an example configuration that you want to add to conf/Context.xml:

<Environment name="codescene/enterprise/pm/jira/config" value="/mydocs/codescene/codescene-jira.yml" type="java.lang.String"/>

<Environment name="codescene/enterprise/pm/jira/dbpath" value="/mydocs/codescene/db/codescene-enterprise-pm-jira" type="java.lang.String"/>

The application uses the paths above to resolve both the configuration file and the internal database for JIRA synchronization data.

Configure the Jira Service to access Jira and be accessed by CodeScene¶

All configuration is done via yaml file. That file has to be referenced in the Environment – if you run Tomcat as described above – or present in a local file in the same directory as the Jira integration service if you execute the JAR file.

The configuration file path is resolved in the following order:

Environment variable CODESCENE_JIRA_CONFIG, if set.
JNDI context path codescene/enterprise/pm/jira/config, if set. Can be configured in Tomcat 7 in conf/context.xml, like this:

<Environment name="codescene/enterprise/pm/jira/config"
  value="/etc/codescene/codescene-jira.yml"
  type="java.lang.String"/>

The file codescene-jira.yml in the current working directory.

If the configuration path doesn’t point to a valid YAML file the service fails to start.

sync:
  hour-interval: {number}
auth:
  service:
    username: {string}
    password: {string}
  jira:
    base-uri: {uri}
    username: {string}
    password: {string}
    rest-api-path: {string: optional, defaults to "/rest/api/latest"}
    http-timeout: {integer: optional, defaults to 10000}
projects:
  - key: {jira-project-key}
    cost-unit:
      type: {minutes|points}
      format: #optional
        singular: {format-string}
        plural: {format-string}
    cost-field: {jira-field-name}
    supported-work-types: [{jira-label}]
    rename-work-types: [{jira-label} => {codescene-label}]
    defect-and-failure-labels: [{jira-label}]
    work-in-progress-transition-name: {jira-status-name}
    ticket-id-pattern: {regex-pattern}

The jira username and password settings specify the credentials for connecting to Jira over using basic athentication. The password should be set to an atlassian API token and the username to the email address for the Atlassian account used to create the token. Note that basic authentication using user credentials/passwords is deprecated and will be removed.

The supported-work-types specify the JIRA labels and/or JIRA Issue Types you want to include in the analysis. Please note that only types with the listed labels/type will be included in the analysis.

The defect-and-failure-labels specify the JIRA labels and/or JIRA Issue Types that will be regarded as defects. Note that this is independent from the work-types configuration.

The cost-unit type has to be either minutes or points (e.g. story points).

The optional http-timeout field is in milliseconds. The plugin retrieves paged data from JIRA in multiple requests. This is the timeout for each one of those requests. In some situations it may be necessary to specify a value greater than the default 10,000 ms.

Example Configuration¶

sync:
  hour-interval: 4 # sync every 4 hours
auth:
  service:
    username: johndoe
    password: somepwd
  jira:
    base-uri: https://jira.example.com
    username: jirauser
    password: jiraapitoken
  # rest-api-path: /rest/api/latest (default)
projects:
  - key: CSE
    cost-unit:
      type: minutes
    cost-field: timeoriginalestimate
    supported-work-types:
      - Bug
      - Feature
      - Refactoring
      - Documentation
    ticket-id-pattern: (CSE-\d+)
  - key: DVP
    cost-unit:
      type: points
      format:
        singular: '%d point'
        plural: '%d points'
    cost-field: customfield_10006
    supported-work-types:
      - Bug
      - Feature
      - Refactoring
      - Documentation
    rename-work-types:
      - Bug => Unplanned Work
      - Feature => Planned Work
      - Documentation => Planned Work
    defect-and-failure-labels:
      - Bug
    work-in-progress-transition-name: Ongoing
    ticket-id-pattern: (DVP-\d+)

The previous example lists four supported-work-types (Bug, Feature, etc). These correspond to either Jira labels and/or Jira issue types. The fetched labels are used to show trends in the type of work we do.

Encrypting passwords in configuration files¶

If you want to avoid accidentally exposing passwords by pushing the config file to a version control system or by sending it to someone else, you can leverage _optional_ encryption of passwords.

Note: if encryption is on, you have to encrypt both passwords (“service” and “jira”)!

To use encrypted passwords:

1. Turn on encryption by setting the CODESCENE_JIRA_ENCRYPTION_KEY environment variable to the encryption master key you wish to use for encrypting the passwords. The encryption key must be at least 8 characters long.

2. Manually encrypt your passwords by invoking the jira plugin with special –encrypt-password switch:

# set the master password first
$ export CODESCENE_JIRA_ENCRYPTION_KEY=xxx

Encrypt the service password:

$ java -jar codescene-enterprise-pm-jira.standalone.jar --encrypt-password
2019-07-22 13:01:07.659:INFO::main: Logging initialized @3976ms
Enter the password:

Encrypted password: fuJNYidHv7yo5lHO80hgD/PLxJWC7QU9iuBcmGU24UYg2uxE+r0eGIgZZBbphlGI

Encrypt the Jira password:

$ java -jar codescene-enterprise-pm-jira.standalone.jar --encrypt-password
2019-07-22 13:03:30.065:INFO::main: Logging initialized @4175ms
Enter the password:

Encrypted password: ukTHVi+sKNxfgpgZDuRQgZbxulx1/JbpfJmTljZTdfN4TO/GUfYbfWtnjfvXtdJZ/4ehGsOYLKoqDvJAY+6YSQ==

Save the encrypted passwords in your config instead of the plaintext version:

sync:
  hour-interval: 1
auth:
  service:
    username: codescene-jira
    # encrypted version
    password: fuJNYidHv7yo5lHO80hgD/PLxJWC7QU9iuBcmGU24UYg2uxE+r0eGIgZZBbphlGI
  jira:
    base-uri: https://jira.example.com
    username: jirauser
    # encrypted version
    password: ukTHVi+sKNxfgpgZDuRQgZbxulx1/JbpfJmTljZTdfN4TO/GUfYbfWtnjfvXtdJZ/4ehGsOYLKoqDvJAY+6YSQ==
projects:
  - key: TEST
    cost-unit:
      type: minutes
    cost-field: timeoriginalestimate
    supported-work-types:
      - Bug
      - Feature
      - Refactoring
      - Documentation
    ticket-id-pattern: (TEST-\d+)

The encryption uses the AES256TextEncryptor from the well-established Jasypt library, which in turn uses the PBEWithHMACSHA512AndAES_256 algorithm. Check Jasypt’s documentation: http://www.jasypt.org/easy-usage.html

This field name can then be placed in the configuration file:

cost-unit:
  type: points
    format:
      singular: '%d point'
      plural: '%d points'
cost-field: customfield_10006