This document describes the functionality provided by the XL Release addon for Jira.
As a prerequisite, the reader should have a good understanding of administering Jira Work Flows, Screens and Custom Fields. For more information, please refer to :
- Jira Administration Guide
- Jira Administration Tutorial Videos
If you wish to extend the plugin, the following will be useful :
The sdk requires an Oracle ojdbc driver in the local maven repository. After downloading the ojdbc6.jar file, you can run the following maven command to install it with:
atlas-mvn install:install-file -Dfile=path/to/ojdbc6-11.2.0.2.0.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0.2.0 -Dpackaging=jar
To build the plugin you'll need to install jta 1.0.1 jar in your local maven repository. Download the jta.jar from Oracle.
Unzip the file and install the jar with the following command:
mvn install:install-file -Dfile=<path>/jta.jar -DgroupId=jta -DartifactId=jta -Dversion=1.0.1 -Dpackaging=jar
Also note that on Windows, the above may fail if running in PowerShell. Run from cmd.exe instead.
To run the plugin in a development Jira instance, execute atlas-run from the checked out projects root directory. Or if you wish to run the plugin from a docker container, checkout xeor atlassian dev container
The XL Release addon for Jira is a Jira plugin with a primary focus of starting releases in XL Release triggered from Jira work flows. The plugin provides a transition post function for this purpose.
- Start release from template Post Function
- Global XL Release Server authentication
- Per issue XL Release Server authentication
- Per issue XL Release template
- Matches custom fields on an issue to like named XL Release template variables
- Passes issue number to XL Release template variable called issue
- XL Release Password Field
- Custom field type that hides the password on input and display
- XL Release 4.6+
- Jira 6.3.x, 6.4.x
The addon can be downloaded directly from the plugin's repository on Github.
Please follow the instructions detailed in the "Installing by file upload" section of Atlassian's Universal Plugin Manager documentation.
The post function can be used in a work flow transition. You may wish to take note of the ordering of the postfunction. For example you may not wish to start a release if another aspect of the transition fails(e.g. saving the Jira ticket).
The function uses predefined custom fields on an issue for input and output. At bare minimum, 2 custom fields are required,
- A field to indicate the release template to start in XL Release
- A field to capture the XL Release id after a successful start
Other optional input custom fields are,
- A field to indicate the XL Release Server url
- A field to indicate the username to use for authentication in XL Release Server
- A field to indicate the password to use for authentication in XL Release Server
- A field to indicate the release title to use
Any other custom field on an issue is used as input to XL Release template variables. The association is made based on the field name. The issue number is mapped to an XL Release template variable called issue if present.
The name of the custom fields can be customized via the function's parameter settings.
Any errors encountered are logged as comments on the issue.
| Parameter | Description | Required | Default |
|---|---|---|---|
| Template Field Name | The custom field name that is defined on an issue containing the XL Release template to start the release from. The issue must define and set this custom field. | Yes | XLR Template Name |
| Release id field name | The custom field name that is defined on an issue that will register the release id after this function starts it. The issue must define this custom field. | Yes | XLR Release Id |
| Url | Url of the XL Release Server. Will be used when no url is specified on an issue. Can be blank. | No | http://localhost:5516 |
| Username | Username to use for authentication to the XL Release Server. Will be used when no username is specified on an issue. Can be blank. | No | admin |
| Password | Password to use for authentication to the XL Release Server. Will be used when no password is specified on an issue. Can be blank. | No | admin |
| Release title field name | The custom field name that is defined on an issue containing the title for the release. Does not have to be defined on issue, will be automatically generated for issue number. | No | XLR Release Title |
| Url field name | The custom field name that is defined on an issue containing the XL Release Server url. If this custom field is defined and set on an issue, it will override the default setting. | No | XLR Url |
| Password field name | The custom field name that is defined on an issue containing the XL Release username. If this custom field is defined and set on an issue, it will override the default setting. | No | XLR Password |
Unfortunately, Jira does not have a password custom field type. This plugin introduces such a type that hides the password on input and display.
New XLR Releases can have variable values passed in from JIRA. Define JIRA Custom Fields and XLR Variables with identical names. When the release is started, the value of the variable in JIRA will be passed to XL Release.
The table below shows the mapping of JIRA types to XL Release types:
| JIRA Variable Type | XL Release Variable Type | Notes |
|---|---|---|
| Checkbox (multiple values) | List | |
| Date Picker (date) | Date | |
| Date Time Picker (datetime) | Date | |
| Number Field | Number | |
| Radio Buttons | String | The selected item value |
| Select List (cascading) | List | |
| Select List (single choice) | String | |
| Select List (multiple choice) | List | |
| Text Field (multi-line) | List or Map | One value per line. Use the form "k=v" for map. |
| URL Field | String | |
| User Picker (single user) | String |
The above is the recommending mapping. Since variable values are transformed as JIRA type -> json -> XLR type, some other mappings may work. For example, JIRA numbers will likely map to String release valiables. However, if your JIRA type and XLR type is incompatible, you'll get an exception when the release is created.
- JIRA issue labels are added to the release as tags.
- XLR variable "issue" (String type) gets the JIRA issue ID.
The following screenshots are samples from a potential integration scenario.
Sample workflow that introduces a Release status. A user will transition to this state from the Done status.
Sample custom release screen that is associated with the workflow transition.
Sample error messages logged by the post function to the issue's comments.
