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