Open topic with navigation

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.

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.

Swarm can also 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.

By default, JIRA module and Perforce job links are disabled.

See Enabling the JIRA module and Enabling Perforce job links in JIRA issues for details on configuring these features.

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

Prerequisites for JIRA integration and job links in JIRA

Enabling the JIRA module

When enabled, the JIRA module links JIRA issues referenced in change descriptions, job descriptions, comments, and reviews to your local JIRA service. 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
		'user'      => '', // the username required for JIRA API access
		'password'  => '', // the password required for JIRA API access
		'job_field' => '', // optional, if P4DTG is replicating JIRA issue IDs
				  // to a job field, list that field here
        ),
Note

If your JIRA web interface uses HTTPS, you may need to configure HTTP client options so that Swarm can connect successfully.

Enabling Perforce job links in JIRA issues

When a Perforce job is created, a link to that job is added to the associated JIRA issue. When P4DTG replication detects a change to an issue, such as description, status, etc. a job link is added to the associated JIRA issue if it does not already exist.

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.

Prerequisites for Perforce job links in JIRA issues:

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
		'user'      => '', // the username required for JIRA API access
		'password'  => '', // the password required for JIRA API access
		'job_field' => '', // optional, 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 
	),

link_to_jobs:

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 Server. By default delay_job_links is set to 60 seconds, if a race condition is experienced increase the delay time.

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 Perforce Defect Tracking Gateway (P4DTG) workflow is the same.

  1. Create a new JIRA issue in your JIRA system.
  2. P4DTG detects the new JIRA issue and creates a new Perforce job for that JIRA issue.
  3. Add the new Perforce job to a pending changelist in P4V, see Add a job to a pending changelist in the P4V User Guide.
  4. Request a new Swarm review for the pending changelist in P4V, see Request a review in the P4V User Guide.
  5. P4V passes the review request to the Swarm worker queue.
  6. The review request is processed by the next available Swarm worker, the new review is created.
  7. 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.
  3. The Swarm review link is displayed on the job page below the job description.
  4. Click the Details tab on the Perforce job page to view the DTG_DTISSUE field.
  5. Click the JIRA link in the DTG_DTISSUE field to view the JIRA issue.
  6. The Swarm review and Perforce job links are displayed in the Issue Links section of the JIRA issue page.