README for Perforce Defect Tracking Gateway (P4DTG) Atlassian JIRA Plug-in
This document is intended for new users and for users who want an overview of
the JIRA plug-in. For details about using P4DTG, see the Perforce Defect
Tracking Gateway User's Guide.
IMPORTANT NOTE: The plug-in described in this document is a plug-in for the
P4DTG system, it is not a plug-in to be installed into your JIRA installation.
Do not copy the .jar, .dll, or .so files out of the P4DTG directory into your
JIRA installation otherwise you will probably corrupt your JIRA database and
delete critical files necessary for the JIRA server.
--------------------------------------------------------------------------------
Overview
This plug-in mirrors fields between JIRA issues and Perforce jobs. Users can
create new Perforce jobs and mirror them as new issues in JIRA. Users can also
edit certain fields in a Perforce job and have their changes mirrored in JIRA.
System Requirements
-------------------
Architecture: x86
Operating systems:
Windows XP, 2003, Vista, 2008, 7
GNU/Linux 2.6
FreeBSD 6
Software versions:
Perforce server 2006.2+
JDK 1.5.0+
JIRA 4.1.1+
*** Special Note ***
* The JIRA server's character encoding must be set to UTF-8 (default).
This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).
--------------------------------------------------------------------------------
Configuring the JIRA server
The DTG JIRA plugin has been developed with the JIRA server version 4.1.1. JIRA
ships with the RPC plugin which enables remote access through XML-RPC and SOAP.
Enabling the JIRA RPC plugin
----------------------------
First, turn on 'Accept remote API calls':
1. You must login to the JIRA server as a JIRA admin user.
2. Click the 'Administration' tab.
3. Click the 'General Configuration' link under the 'Global Settings' section
in the left-hand menu.
4. Click the 'Edit Configuration' link.
5. Select 'ON' for the 'Accept remote API calls' field.
6. Click the 'Update' button.
Second, enable 'System SOAP Service':
1. You must login to the JIRA server as an Administrator.
2. Click the 'Administration' tab.
3. Click the 'Plugins' link under the 'System' section in the left-hand menu.
4. Click the 'RPC JIRA Plugin' link.
5. Click 'Enable module' for the 'System SOAP Services' field.
JIRA User Permissions
----------------------------
By default, the JIRA installation creates three user groups "jira-users",
"jira-developers", and "jira-administrators". Each of these user group has it's
own set of permissions.
The P4DTG JIRA plug-in requires an administrative JIRA user. The simplest way to
achieve this is to assign this user to the "jira-administrators" group. There
are some JIRA SOAP methods require a JIRA administrative user, such as the
getCustomFields() method.
JIRA "Perforce Job Integration" plug-in
----------------------------
The JIRA server ships with the "Perforce Job Integration" plug-in using FishEye
and/or Crucible. Please turn the "Perforce Job Integration" off. There might be
unforeseen problems occurring if both the "Perforce Job Integration" and the DTG
JIRA replication are running at the same time.
--------------------------------------------------------------------------------
Configuring the JIRA plug-in
To configure the plug-in, launch the P4DTG configuration tool and perform
the following steps:
1. Click the "Defect Tracking Sources" tab.
2. Click "New".
3. From the "Type" dropdown list, choose "JIRA".
4. Specify the login account details for your JIRA server in the "Server
connection details" fields. The 'Server' field should be the JIRA server's
web services URL. For example,
Server: http://jiraserver:8080/rpc/soap/jirasoapservice-v2
User Name: jirauser
Password: jirapasswd
5. (Optional) To configure attributes, click "Edit attributes..." and specify
options as follows.
Enable Issue Creation: Use this attribute to enable creating new
issues in JIRA based off of Perforce jobs.
Wait time: Specifies the number of seconds that the replication engine
waits after detecting a connection error before it retries an operation.
Use -1 to default to the General Wait Duration specified for the
replication map.
TCP Port: This is the TCP port number of the DTG-JIRA proxy server will
be listening on. This port changes dynamically by DTG if it sees an
instance already running or evidence of an instance running.
Note: only change this value with the help of Perforce support.
Java options: Use this attribute to specify additional Java options for
starting the JIRA plugin.
Note: only change this value with the help of Perforce support.
Allow JIRA issue creation: Enable creating of new JIRA issue through
replication. Default is to disallow such creation. Specify either 'y'
or 'n'.
Batch size for issues: This attribute affects the memory used by the
Java process by limiting the number of issues returned per query of the
JIRA server. A small number limits the memory but increases processing
time when there are a large number of issues to be processed. A larger
number improves performance but consumes a much larger amount of memory.
Default is 100.
Note: only change this value with the help of Perforce support.
6. To verify your configuration, click "Check connection and retrieve fields".
If your entries are correct, the configuration tool displays "Valid
connection to server".
7. Finally, configure your Perforce Source and mappings as described in the
P4DTG User Guide.
8. The JIRA plug-in adds the following fields to the list of defect tracker
fields that is displayed in the Gateway Mappings dialog:
Status/Resolution: combines the Status and Resolutions fields so that they
can be mirrored with the Perforce Status field. See the jobspec.txt file
for an example jobspec which would allow for mirroring with a standard JIRA
4.1.1 or later installation. If the possible resolutions have been altered,
update the possible status fields accordingly. The sample jobspec requires
a Perforce Server 2008.1 or later.
Summary: contains the Issue subject.
To display this information in the corresponding Perforce job, map this
field to a TEXT field in the Perforce job specification.
Description: contains the Issue body.
To display this information in the corresponding Perforce job, map this
field to a TEXT field in the Perforce job specification.
Comments: the aggregate of the JIRA "Comments" field.
To display this information in the corresponding Perforce job, map this
field to a TEXT field in the Perforce job specification.
Fix: to append fix information to the JIRA issue "Comments" field,
map this field to the Perforce "Fix Details" field. You can specify details
to be appended, such as the change number or user who made the fix.
--------------------------------------------------------------------------------
JIRA Plug-in configuration XML file
The configuration XML file (default, "jira-config.xml") is for defining custom
fields and workflows (steps, transitions, etc.). There is no need to update the
config XML file if there no custom fields, no new workflows and no changes in
default statuses and resolutions.
Configuring custom fields
----------------------------
First, find the custom fields on the JIRA server administrative UI.
1. You must login to the JIRA server as a JIRA admin user.
2. Click the 'Administration' tab.
3. Click the 'Custom Fields' link under the 'Issue Fields' section in the
left-hand menu.
4. The 'View Custom Fields' screen will display all the custom fields
Second, update the configuration XML file (default, 'config/jira-config.xml').
1. Open the configuration XML file and enter each custom fields from the screen
as XML ... elements inside the ...
outer XML element.
2. The supported DTG field data types are "LINE", "TEXT", DATE" and "SELECT".
The following is the mapping of data types between DTG and JIRA.
DTG data type JIRA data type
------------- --------------
LINE Text Field (< 255 characters)
TEXT Free Text Field (unlimited text)
DATE Date Time
SELECT Select List
Note: 'SELECT' is a single select.
3. The supported DTG access permissions are "RO" (read-only) and "RW" (read and
write).
4. The following are examples of custom field XML elements.
...
...
Configuring custom workflows
----------------------------
First, find the workflows on the JIRA server administrative UI.
1. You must login to the JIRA server as a JIRA admin user.
2. Click the 'Administration' tab.
3. Click the 'Screens' link under the 'Issue Fields' section in the
left-hand menu.
4. For each screen requiring resolutions note each workflow and its
transition(s) in parentheses.
Second, find the transitions requiring resolutions on the JIRA server UI.
1. Open a separate Web browser window or tab.
2. Click the 'Administration' tab.
3. Click the 'Workflows' link under the 'Global Settings' section in the
left-hand menu.
4. For each custom workflow click the 'Steps'link under the 'Operation' heading.
Third, update the configuration XML file (default, 'config/jira-config.xml').
1. Open the configuration XML file and enter each custom workflow from the
screens as XML ... elements inside the
... outer XML element.
Inside each workflow there are step elements. Each step element contains
transitions. The step elements require values for the step name and
linkedStatus attributes. The transition elements require values for the name
and destinationStep attributes.
2. For each custom workflow create ...
XML elements inside the ...
outer XML element.
The 'name' attribute value is the display value from the 'View Screens' page
under the 'Workflow' heading.
3. The following are examples of custom workflow XML elements.
...
...
*** Important Notes ***
Custom fields
-------------
1. Custom fields should have unique names. The custom field name is assumed to
be unique and it is used to do reverse lookup of the custom field id in JIRA.
2. If custom fields exist in the JIRA server but are not defined in the
jira-config.xml file, the 'type' and 'access' attributes will be set to the
following default values:
type="LINE" access="RO"
Workflows (steps and transitions)
---------------------------------
1. Transitions should have unique "destinationStep" values in jira-config.xml.
This means each transition should be unique. The unique transitions can be
used multiple times inside the steps of the workflows.
*** The following configuration is right. Notice both "My Reopen Issue"
transitions point to the same 'destinationStep' value "My Reopened".
*** The following configuration is wrong. Notice both "My Reopen Issue"
transitions point to different 'destinationStep' values "My Reopened"
and "My Open"
2. Delete the default JIRA workflow in jira-config.xml if you are not using it.
3. The JIRA administrator needs to add (if missing) a 'Post Function' to clear
(set field value to 'None') the 'Resolution' field for transitions that move
an issue from a resolved state back to an unresolved state. If not in place
the user may see the following error displayed in the Perforce job's
'DTG_ERROR' field during replication:
"[UsageError]Error in job specification. Missing required field 'Status'."
Handling multi-select fields
----------------------------
DTG does not support multi-select fields. Therefore, JIRA multi-select fields
can only be copy as read-only text fields in DTG. The following are default
JIRA multi-select fields.
1. Component/s
2. Affects Version/s
3. Fix Version/s
Alter the Perforce jobspec to support 'Components', 'Affects Versions' and
'Fix Versions'. Copying read-only from JIRA to Perforce text fields. Please
see 'jobspec.txt' file for examples.
The workaround to mirror these fields is to setup single-select JIRA custom
fields, configure them in 'jira-config.xml' and map them to single-select
Perforce fields.