Using Jira tasks

You can use JIRA tasks in XL Release to interact with an Atlassian JIRA server. The following JIRA task types are available:

  • Jira: Create Issue: Create a new JIRA issue
  • Jira: Create Issue Json: Create a new JIRA issue with a JSON Object
  • Jira: Create Subtask: Create a new JIRA subtask under an existing JIRA issue
  • Jira: Query: Query JIRA using JQL
  • Jira: Query For Issue Ids: Same as Query but only returns the Issue IDs
  • Jira: Update Issue: Update a single JIRA issue to change its status or post a comment
  • Jira: Update Issues: Update multiple JIRA issues
  • Jira: Update Issues By Query: Update JIRA issues based on a query
  • Jira: Check Issue: Polls until a JIRA issue is one of the given statuses
  • Jira: Check Query: Polls until the JIRA issues returned by a query are a given status
  • Jira: Get Versions: Outputs the versions for a given JIRA project
  • Jira: Get Issue Details: Outputs the details for a given JIRA issue
  • Jira: Get All Sprints: Outputs the sprint names and IDs for a given JIRA board

The following release trigger is available:

  • Jira: Issue Trigger: Trigger a release when an issue matching the JQL criteria is created

For more information, see the tutorial Using variables to revise a JIRA issue list.

In the release flow editor, JIRA tasks are marked with a blue border.

Migration instructions

If upgrading to XL Release 9.0.0 and you currently use the xlr-jira-extension-plugin provided on xebialabs-community, you must use the xl-ci-tool to migrate the tasks to the new in-sourced tasks.

Steps

  1. Download the latest jar from the xl-ci-tool repository.
  2. Click here to download the xlr-jira-plugin migration mapping file.
  3. Shut down XL Release.
  4. Run the migration tool in test mode: java -jar xl_ci_tool_exec-1.3.1.jar -f </path/xlr-jira-mapping.json> -i </path/XLR_HOME> -preview.

Verify the results are as expected. When you are ready to perform the migration:

  1. Make a backup of the repository database.
  2. Run the migration tool: java -jar xl_ci_tool_exec-1.3.1.jar -f </path/xlr-jira-mapping.json> -i </path/XLR_HOME>.
  3. Delete the xlr-jira-extension-plugin.
  4. Start XL Release.
  5. Check any templates or existing releases that used the old JIRA tasks and verify that there are no errors.

Set up a JIRA server

To set up a JIRA server:

  1. In XL Release, go to Settings > Shared configuration and click image under Jira: Server.

    Note: You can configure JIRA servers on a folder level in Design > Configuration tab of the desired folder.

  2. In the Title field, enter the name of the JIRA server. This name will display in JIRA tasks.

  3. In the URL field, enter the URL of the JIRA server.

  4. If you use two-step verification to authenticate with your Atlassian Cloud site, you need to configure a REST API token to authenticate. See information from Atlassian for details.

  5. Depending on your authentication type, do one of the following:

  6. If using Jira Cloud, in the Username and API Token fields, enter the server login user ID and API token.

  7. If using Jira Server, in the Username and Password fields, enter the server login user ID and password.

  8. Click Save.

Create Issue task

The Jira: Create Issue task type creates an issue in JIRA.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Project: The JIRA project name.
  • Title: The issue title.
  • Description: The issue description.
  • Issue Type: The issue type. For example: bug or improvement. For a complete list, see the JIRA issue type documentation.

The output of the task is the ID of the JIRA issue that was created: issueId.

Create Issue Json task

The Jira: Create Issue Json task type creates an issue in JIRA using a JSON object.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • JSON Object: The JSON object used to create an issue.

The output of the task is the ID of the JIRA issue that was created: issueId.

Create Subtask task

The Jira: Create Subtask task type creates a subtask in JIRA under an existing parent issue.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Project: The JIRA project name.
  • Title: The issue title.
  • Parent Issue Key: The parent issue key.
  • Description: The issue description.

The output of the task is the ID of the JIRA subtask that was created: subtaskId.

Query task

The Jira: Query task type executes a JQL query on a JIRA server to retrieve a list of issue IDs and summaries.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Query: A JQL query that finds the issues that will be updated in this task

The output of the task is issues. This is a key-value map that contains the issue IDs (keys) and summaries (values) of the issues that were found. When the output is stored in a variable, you can use the data in a Jira: Update Issues task.

Query for Issue Ids task

The Jira: Query For Issue Ids task type executes a JQL query on a JIRA server to retrieve a list of issue IDs.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Query: A JQL query that finds the issues that will be updated in this task.

The output of the task is issueIds. This is a list of issue IDs for the issues that were found.

Update Issue task

The Jira: Update Issue task type updates a single issue in JIRA.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Issue Id: The ID of the issue to update.
  • New Status: The new status of the issue. For a complete list, see the JIRA Workflow documentation.
  • Comment: The text of a comment to add to the issue.

Update Issues task

The Jira: Update Issues task type updates multiple issues in JIRA.

The following properties are available:

  • Server: The JIRA server where XL Release connects.* Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.

  • Issues: A key-value map that contains the issue IDs (keys) and summaries (values) of each issue.

    The Jira: Query task type produces a key-value map that can be stored in a variable. You can then use that variable as input for a Jira: Update Issues task.

    The issue summaries (the values in the key-value map) are only required if you want to update them in JIRA, using the Update Summaries option.

  • New Status: The new status of the issues. For a complete list, see to the JIRA Workflow documentation.

  • Comment: The text of a comment to add to the issue.

  • Update Summaries: Indicates whether to change the issue summaries in JIRA.

Update Issues by Query task

The Jira: Update Issues by Query task type updates issues that are located by a JQL query.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Query: A JQL query that finds the issues that will be updated in this task.
  • New Status: The new status of the issues. For a complete list, see the JIRA Workflow documentation.
  • Comment: The text of a comment to add to the issues.

The output of the task is issues, a key-value map that contains the issue IDs (keys) and summaries (values) of the issues that were updated.

Check Issue task

The Jira: Check Issue task type continues polling until the given JIRA issue has an expected status.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Issue Id: The ID of the issue to check.
  • Expected Status List: A list of statuses to check for.
  • Poll Interval: The time in seconds between each polling action.

The output of the task is finalStatus which is the final status of the issue on last check.

Check Query task

The Jira: Check Query task type executes a JQL query on a JIRA server to retrieve a list of JIRA issues for which it keeps polling until the issues have an expected status.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Query: A JQL query that finds the issues that will be checked in this task.
  • Expected Status List: A list of statuses to check for.
  • Poll Interval: The time in seconds between each polling action.

The output of the task is issues. This is a key-value map that contains the issue IDs (keys) and summaries (values) of the issues that were found.

Get Versions task

The Jira: Get Versions task type outputs the versions for the given JIRA project.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Project Id: The JIRA project ID.

The output of the task is versions. This is a list of versions for the JIRA project.

Get Issue Details task

The Jira: Get Issue Details task type outputs the JSON Object for a single JIRA issue.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Issue Id: The ID of the issue to get the details for.

The output of the task is issueDetails. This is a key-value map that contains the JSON Object for the issue separated into fields as keys and their values.

Get All Sprints task

The Jira: Get All Sprints task type outputs the sprints for a given JIRA board.

The following properties are available:

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Board Name: The name of the board to get sprints from.

The output of the task is sprints. This is a key-value map that contains the sprint names (key) and IDs (value).

Issue Trigger task

The Jira: Issue Trigger trigger type starts a release when a new issue is created based on JQL.

  • Server: The JIRA server where XL Release connects.
  • Username, Password, API Token: The server login user ID, password, and API token. If set, these credentials will override the ones defined in the JIRA server configuration.
  • Jql: The query in JQL used to monitor new issues.

The output of the trigger is latestIssue. This can be used in release titles and tags for releases it triggers.

Release Notes

XL Release Jira plugin 9.0.0

Improvements

  • [XLINT-684] Insourced tasks from the xlr-jira community extension plugin (if using xlr-jira-extension-plugin, please follow the migration instructions):

    • Create Issue Json
    • Check Issue
    • Check Query
    • Get Versions
    • Get Issue Details
    • Get All Sprints
    • Query For Issue Ids
  • [XLINT-684] Insourced Issue Trigger from xlr-jira community extension plugin
  • [XLINT-585] Added new Create Subtask task to create a new JIRA subtask under an existing JIRA issue
  • [XLINT-685] Added new basic authentication method using API token to support JIRA Cloud

Bug Fixes

  • [XLINT-684] Fixed issue with Update Issues task in which giving New Status a value and setting Update Summaries would cause task to fail