Perforce Public Knowledge Base - Swarm JIRA plugin usage
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Swarm JIRA plugin usage

« Go Back


When the Swarm JIRA plugin is configured Swarm will:
  • expand Jira issues in changelist / review descriptions to be a URL that points to the issue in JIRA.
  • automatically create or update any associated JIRA issues with links back to Swarm whenever a Perforce change is committed, a code review is created, or a code review is updated.
This document describes how it is configured and what you should expect from the integration.
To configure the plugin, you must add a 'jira' section to the data/config.php file under the install directory.

In Swarm 2013.2, the Jira server is queried to get the list of JIRA project IDs, so a JIRA login with permission to update the issues must be specified:


    // 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
        'timeout'   => 5,  // optional, timeout for JIRA API requests, in seconds.
                           // Default is 5 seconds,

For example:
    'jira' => array(
        'host'     => '',
        'user'     => 'jira-swarm-user',
        'password' => 'Password',
        'job_field' => '',
        'timeout' => '50'

The jira user (jira-swarm-user in the above example) must have permissions to edit issues in each project where you wish this feature to work.

When configured as above, issue names with be replaced with JIRA links in Swarm reviews:


and Swarm changelist descriptions:


The JIRA issue will also be updated when the Swarm review changes state. For example:


If P4DTG is being used you can also specify the 'job-field' to replace that field with a link to the JIRA issue:
    'jira' => array(
        'host'     => '',
        'user'     => 'jira-swarm-user',
        'password' => 'Password',
        'job_field' => 'DTG_DTISSUE',
        'timeout' => '50'

For example:


Note that In Swarm 2013.1 you needed to specify a list of JIRA project IDs that  swarm will search for:
 // this block should be a peer of 'p4'
'jira' => array(
    'host'     =>   '', // URL for your installed JIRA web interface
    'projects' => array(
        '<project id>', '<project id>'  // list of projects to link issues for

For example:
'jira' => array(
    'host'     =>   '',
    'projects' => array(
        'SW', 'PROJONE'

This will replace any text in the description fields of changes and reviews that matches 'SW-NNNN' or 'PROJONE-NNNN' with a link to the Jira issue.


Note: Swarm will only refresh JIRA connection details every 10 minutes, so if you have made a change to 'config.php' then it may not be recognized for up to 10 minutes.

JIRA projects are cached (<swarm>/data/cache/jira/projects).   This jira project list cache is refreshed every 10 minutes.

If the swarm link is not being displayed in reviews and changes then it is possible that the 'host' field is incorrect. You can test for this problem using a browser on the swarm machine using the URL:


For example:

If the response is empty ('[ ]' ) then try logging in from the browser to the JIRA host using user and password specified in 'config.php'.

You can also check the logs in JIRA to ensure the requests are arriving. These can be found under the JIRA install (default location on linux is /opt/atlassian/jira/logs) and are called access_log.YYYY-MM-DD. An example of a project request is: 123x456x7 jira-swarm-user [11/Oct/2013:15:10:07 +0100] "GET /rest/api/latest/project HTTP/1.1" 200 259 76 "-" "Zend\Http\Client" "16p8t2y"

If JIRA is not being updated when the review is updated, you can also check the JIRA logs for a REST POST for the issue. For example: 123x456x7 jira-swarm-user [11/Oct/2013:15:48:02 +0100] "POST /rest/api/latest/issue/SW-1/remotelink HTTP/1.1" 201 116 188 "-" "Zend\Http\Client" "1ri8rft"

You can check for errors returned from JIRA in the swarm logs which by default are found under the 'data' directory in swarm install in a file called 'log'.
Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255