Basic Jira integration

The basic P4 Code Review integration with Atlassian Jira allows code reviews and committed changes to be associated with Jira issues. If your organization is using Altassian Jira and does not use the built-in jobs feature of P4 Server, the basic Jira integration is sufficient and you don't need the Jira integration with jobs.

On this page:

Overview of basic Jira integration

Basic Jira integration enables:

In P4 Code Review: Hyperlinks are created to Jira issues referenced in changelist descriptions, review descriptions, and review comments.
In the Web Links section of the Jira issue: Hyperlinks are created to the associated P4 Code Review changelist (commit) and review pages.

P4 Code Review 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 P4 Code Review workers must be working, see Worker status.
Enabling the Jira module requires that the specified Jira user has permission to view issues, update issues, and add remote links to issues in the Jira projects where the Jira integration is required.

When a user is provided, P4 Code Review uses HTTP Basic authentication with the provided username and password. If the username is left blank, P4 Code Review uses Bearer authentication with the password (token) instead.

Enabling the Jira module

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 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
	'title_summary'   => true, // set to True if user wants the title/description of review/job/commit in jira card. default is true. 
    ),

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 P4 DTG 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 P4 Code Review adding the job link to the Jira issue. This configurable is used to avoid a race condition between Jira and the P4 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 P4 Code Review commit, review, and Perforce job links are added to. P4 DTG 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.
- 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.

Be aware that:

If P4 Code Review fails to add a job link to a Jira issue because that Jira issue does not exist, the failure is logged by P4 Code Review. P4 Code Review will not try to add the job link to that Jira issue again.
If a job is updated and the DTG_DTISSUE field value is changed, a job link will be added to the new Jira issue. The job link will not be removed from the original Jira issue.

Jira SSL client configuration

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

If your Jira site certificate is not from a common Certificate Authorities, you might need to configure the P4 Code Review 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 P4 Code Review's connection with your Jira instance, see P4 Code Review to JIRA Connection Troubleshooting in the Perforce Knowledge Base.