Jira

Swarm's Jira integration allows code reviews and committed changes to be associated with Jira issues, making it easy to reference associated issues, and see the state of a code review or committed change within Jira. To associate a code review with a Jira issue, include a Jira issue identifier in the review's description, for example SW-1234. Swarm links to the Jira issue and creates a link within the Jira issue back to the code review in Swarm. Multiple Jira issues can be included in the changelist description. As a code review progresses, Swarm updates each associated Jira issue with the review's current status.

For instructions on how to configure basic Jira integration, see Jira integration.

Additionally, if you have the Helix Defect Tracking Gateway (P4DTG) configured to integrate Perforce jobs with Jira issues. Swarm can be configured to add a link to a Perforce job within a Jira issue. Perforce job links are created when a new Jira or job is created or updated. This gives you direct access to the Perforce job from a link in the Issue Links section of the Jira issue.

For instructions on how to configure Jira integration and Perforce job links, see Jira integration and Perforce job links.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Jira integration

Basic Jira integration enables:

  • In Swarm: Hyperlinks are created to Jira issues referenced in changelist descriptions and review descriptions. Jira links in comments are only supported in the original Swarm review page. For example, if Jira issue SW-1234 is found in the text, the text is linked to the Jira issue in Swarm.

    For the legacy Jira linkify, the links for Jira issues in changelist descriptions, review descriptions, and comments open in a new tab in the web browser.

  • In the Issue Links section of the Jira issue: Creates hyperlinks to the associated Swarm changelist (commit) and review pages.

Note

Swarm fetches Jira project identifiers using a worker, once per the worker process' lifetime. See Worker configuration. New Jira projects will not auto-link to Jira until the project identifiers have been updated. By default, project identifiers are updated once every ten minutes.

Prerequisites for basic Jira integration

  • The Swarm workers must be working, see Worker status.
  • The Jira module must be enabled, see Enabling the Jira module.

  • The Jira user specified in the Jira module configuration must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    To troubleshoot the permissions:

    1. Log in to Jira as the Swarm Jira user.

    2. Retrieve an issue.

    3. Try to create a link.

Enabling the Jira module

By default, the Jira module is not enabled. To enable the Jira module, add the following configuration block to your SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'jira' => array(
        'host'         => '', // URL for your installed Jira web interface (start with https:// or  http://)
        'api_host'     => '', // URL for Jira API access, 'host' is used for Jira API access if 'api_host' is not set 
        'user'         => '', // Jira Cloud: the username or email address used to connect to your Atlassian account 
                              // Jira on-premises: the username required for Jira API access
                              // Jira on-premises with Personal Access Tokens (PATs): the username must be blank
        'password'     => '', // Jira Cloud: a special API token obtained from https://id.atlassian.com/manage/api-tokens
                              // Jira on-premises: the password required for Jira API access
                              // Jira on-premises with Personal Access Tokens (PATs): the Personal Access Token (PAT) obtained from Jira On-premises. 
        'relationship' => '', // Jira subsection name links are added to defaults to empty, links added to the "links to" subsection
        'ignored_users'=> array(), // Reviews or changes by users specified here are not linked to any Jira issue. 
    ),

  • host: URL for your Jira web interface starting with https:// or http://

    • For example, for a Jira cloud instance it might be: https://my-company-jira.atlassian.net

  • api_host (optional): URL for Jira API access, the host URL is used for Jira API access if api_host is not set.

  • user: The user must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    • Jira Cloud: Username or email address used to connect to your Atlassian account.

    • Jira on-premises: Username for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): The username must be blank.

  • password:

    • Jira Software Cloud: A special API token. To obtain your API token:

      1. Go to API Tokens.
      2. Log in with your Atlassian administrator credentials.
      3. Click Create and name your API token something recognizable, for example swarmjira.
      4. The API token is displayed in a dialog.
      5. Copy the token and paste it into the password configurable. It is a good idea to save the API token somewhere safe in case you need it in the future.

    • Jira on-premises: Password required for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): A Personal Access Token (PAT) obtained from Jira On-premises. For more information about PATs, see Using Personal Access Tokens.

  • relationship: sets which subsection of the Jira Issue Links section Swarm commit, Swarm review, and Perforce job links are added to. P4DTG is required for Perforce job links, see Jira integration and Perforce job links.
    • '' empty: links are added to the links to subsection of Issue Links section of Jira issues. This is the default value.
    • <JobLinksSubsectionName>: creates a new subsection in the Issue Links section of Jira issues. Links are added to this subsection.

    • Note

    Existing links are not moved to the subsection defined by the relationship configurable. However, if a link is updated or a new link is added, the link is added to the new subsection. The link is not deleted from its original location.

  • ignored_users: reviews or changes by users specified here are not linked to any Jira issue.

Jira SSL client configuration

Tip

If your Jira site certificate is from one of the more common Certificate Authorities (such as the CA used by Jira Software Cloud), the following configuration changes are not usually required.

If your Jira site certificate is not from one of the more common Certificate Authorities, you might need to configure the Swarm http_client_options configuration block in your SWARM_ROOT/data/config.php file.

For example, if your root and intermediate certificates are stored in a pem format file in /path/to/certs/jira.pem, point to the file with:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslcafile'     => '/path/to/certs/jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
        ),
    ),
)

For more information about configuring your Jira HTTP client options, see HTTP client options.

If you need to troubleshoot Swarm's connection with your Jira instance, see Swarm to JIRA Connection Troubleshooting in the Perforce Knowledgebase.

Jira integration and Perforce job links

Jira integration and Perforce job links enable:

  • In Swarm:

    • Creates hyperlinks to Jira issues referenced in changelist descriptions and review descriptions. Jira links in comments are only supported in the original Swarm review page. For example, if Jira issue SW-1234 is found in the text, the text is linked to the Jira issue in Swarm.

    • Creates hyperlink to associated Jira issues on the Swarm job page.

  • In the Issue Links section of the Jira issue:

    • Creates hyperlinks to the associated Swarm changelist (commit) and review pages.

    • When a Perforce job is created, creates a hyperlink to the Swarm job page.

    • If a job is added to a review, creates a hyperlink to the Swarm review page.

    • For fixes (p4 fix) to a job, when the job_field is set, creates a hyperlink to the Swarm changelist (commit) page.

    • When P4DTG replication detects a change to an issue, creates a job link for the associated Jira issue if it does not already exist.

For a summary of Jira integration and Perforce job link workflow, see Jira integration and Perforce job link workflow.

Prerequisites for Jira integration and Perforce job links

Enabling the Jira module

Important

If Swarm fails to add a Perforce job link to a Jira issue because that Jira issue does not exist, the failure is logged by Swarm. Swarm will not try to add the job link to that Jira issue again.

Note

If a Perforce job is updated and the DTG_DTISSUE field value is changed, a job link will be added to the new Jira issue. The Perforce job link will not be removed from the original Jira issue.

By default, the Jira module is not enabled. To enable Perforce job links in Jira issues, add the following configuration block to your SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'jira' => array(
        'host'            => '', // URL for your installed Jira web interface (start with https:// or  http://)
        'api_host'        => '', // URL for Jira API access, 'host' is used for Jira API access if 'api_host' is not set
        'user'            => '', // Jira Cloud: the username or email address used to connect to your Atlassian account 
			          // Jira on-premises: the username required for Jira API access
			          // Jira on-premises with Personal Access Tokens (PATs): the username must be blank
        'password'        => '', // Jira Cloud: a special API token obtained from https://id.atlassian.com/manage/api-tokens 
			          // Jira on-premises: the password required for Jira API access
			          // Jira on-premises with Personal Access Tokens (PATs): the Personal Access Token (PAT) obtained from Jira On-premises. 
        'job_field'       => '', // if P4DTG is replicating Jira issue IDs to a job field, list that field here
        'link_to_jobs'    => false, // set to true to enable Perforce job links in Jira, P4DTG and job_field required  
        'delay_job_links' => 60, // delay in seconds, defaults to 60 seconds 
        'relationship'    => '', // Jira subsection name links are added to defaults to empty, links added to the "links to" subsection
        'ignored_users'   => array(), // Reviews or changes by users specified here are not linked to any Jira issue 
    ),

  • host: URL for your Jira web interface starting with https:// or http://

    • For example, for a Jira cloud instance it might be: https://my-company-jira.atlassian.net

  • api_host (optional): URL for Jira API access, the host URL is used for Jira API access if api_host is not set.

  • user: The user must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    • Jira Cloud: Username or email address used to connect to your Atlassian account.

    • Jira on-premises: Username for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): The username must be blank.

  • password:

    • Jira Software Cloud: A special API token. To obtain your API token:

      1. Go to API Tokens.
      2. Log in with your Atlassian administrator credentials.
      3. Click Create and name your API token something recognizable, for example swarmjira.
      4. The API token is displayed in a dialog.
      5. Copy the token and paste it into the password configurable. It is a good idea to save the API token somewhere safe in case you need it in the future.

    • Jira on-premises: Password required for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): A Personal Access Token (PAT) obtained from Jira On-premises. For more information about PATs, see Using Personal Access Tokens.

  • job_field: If P4DTG is replicating Jira issue IDs to a job field, list the job field here.

  • link_to_jobs:
    • false: disable Perforce job links in Jira. The default setting is false.
    • true: enable Perforce job links in Jira.
  • delay_job_links: delay set in seconds. Sets the delay between a new Jira or job being created or updated, and Swarm adding the job link to the Jira issue. This configurable is used to avoid a race condition between Jira and the Helix Core Server. By default delay_job_links is set to 60 seconds, if a race condition is experienced increase the delay time.
  • relationship: sets which subsection of the Jira Issue Links section Swarm commit, Swarm review, and Perforce job links are added to. P4DTG is required for Perforce job links.
    • '' empty: links are added to the links to subsection of Issue Links section of Jira issues. This is the default value.
    • <JobLinksSubsectionName>: creates a new subsection in the Issue Links section of Jira issues. Links are added to this subsection.

    • Note

    Existing links are not moved to the subsection defined by the relationship configurable. However, if a link is updated or a new link is added, the link is added to the new subsection. The link is not deleted from its original location.

  • ignored_users: reviews or changes by users specified here are not linked to any Jira issue.

Jira SSL client configuration

Tip

If your Jira site certificate is from one of the more common Certificate Authorities (such as the CA used by Jira Software Cloud), the following configuration changes are not usually required.

If your Jira site certificate is not from one of the more common Certificate Authorities, you might need to configure the Swarm http_client_options configuration block in your SWARM_ROOT/data/config.php file.

For example, if your root and intermediate certificates are stored in a pem format file in /path/to/certs/jira.pem, point to the file with:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslcafile'     => '/path/to/certs/jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
        ),
    ),
)

For more information about configuring your Jira HTTP client options, see HTTP client options.

If you need to troubleshoot Swarm's connection with your Jira instance, see Swarm to JIRA Connection Troubleshooting in the Perforce Knowledgebase.

Jira integration and Perforce job link workflow

This section describes the workflow for Jira integration and job links in Jira issues when you request a new Swarm review from P4V.

Tip

The process for adding a Perforce job and creating a review differs for the other clients but the Swarm worker and Helix Defect Tracking Gateway (P4DTG) workflow is the same.

  1. Create a new Jira issue in your Jira system. P4DTG detects the new Jira issue and creates a new Perforce job for that Jira issue.
  2. Add the new Perforce job to a pending changelist in P4V. See Add a job to a pending changelist in the Helix Core Visual Client (P4V) Guide.
  3. Request a new Swarm review for the pending changelist in P4V. See Request a review in the Helix Core Visual Client (P4V) Guide.

    P4V passes the review request to the Swarm worker queue. The review request is processed by the next available Swarm worker, the new review is created. Swarm checks its Jira configuration. If the job_field exists in the Perforce job, Swarm adds a link to the new Perforce job in the Issue Links section of the Jira issue.

To check that these steps have been completed and to view the links:

  1. Open the new Swarm review. The associated Perforce jobs are displayed on the review page below the review description.
  2. Click the Perforce job link to open the job. The Swarm review link is displayed on the job page below the job description.
  3. Click the Details tab on the Perforce job page to view the DTG_DTISSUE field.
  4. Click the Jira link in the DTG_DTISSUE field to view the Jira issue. The Swarm review and Perforce job links are displayed in the Issue Links section of the Jira issue page.