Perforce Public Knowledge Base - Swarm JIRA plugin usage
Reset Search
 

 

Article

Swarm JIRA plugin usage

« Go Back

Information

 
Problem
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.
Solution
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:

 

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

For example:
 
    'jira' => array(
        'host'     => 'http://jira.host:8080',
        '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:

kA0F0000000CqpVKAS_en_US_4_0


and Swarm changelist descriptions:

kA0F0000000CqpVKAS_en_US_4_1

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


kA0F0000000CqpVKAS_en_US_4_2

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'     => 'http://jira.host:8080',
        'user'     => 'jira-swarm-user',
        'password' => 'Password',
        'job_field' => 'DTG_DTISSUE',
        'timeout' => '50'

For example:

kA0F0000000CqpVKAS_en_US_4_3

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'     =>   'http://jira.host:8080',
    '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.


Troubleshooting

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:

   <host>/rest/api/latest/project

For example:

   http://jira.host:8080/rest/api/latest/project

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:
 
1.2.3.4 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:
 
1.2.3.4 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

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255