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.

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

• The Perforce Defect Tracking Gateway (P4DTG) must be configured for Swarm, JIRA, and P4D, see Installing and configuring the Helix Defect Tracking Gateway in the Helix Defect Tracking Gateway Guide.
• The Swarm workers must be working, see Worker status.
• The JIRA module must be enabled, see Enabling the JIRA module.
• To add Perforce job links to JIRA issues, job links must be enabled and the JIRA job_field must be set, see Enabling Perforce job links in JIRA issues.

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
        ),

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.

Prerequisites for Perforce job links in JIRA issues:

• The JIRA module must be enabled
• The JIRA job_field must be set
• P4DTG must be configured

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:

• 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 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.

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.