The Jira Sensor is implemented by a pair of Ant tasks called jira-issue-extractor and jira-issue-sensor. The jira-issue-extractor task retrieves data in XML format from a Jira server about a specified set of Jira issues. The jira-issue-sensor task processes the data retrieved by jira-issue-extractor and sends it off to a Hackystat server as Issue sensor data instances (Section 25.12, “Issue”).
For each issue, the Jira sensor determines the name of the user currently assigned to resolve that issue. The Jira sensor uses the assigned user name to determine which Hackystat account will be sent the corresponding sensor data instance.
Jira is a tool for the management of software development issues. It is used, for example, to track the status of repairs to defects discovered during development and deployment of software systems, or other change requests
One alternative implementation approach for the Jira sensor is a server-side hook. We experimented with this approach previously, but our current approach does not require access to the machine running Jira, which may be a benefit in some situations.
The Jira sensor requires Java 1.5.0 or later, Ant 1.6.5 or later, and Jira 3.0 or later.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
In the HackyInstaller main window, select the Jira sensor and press "Configure Selected Sensor". Figure 26.35, “ Jira sensor installer configuration window ” shows what the configuration window should look like after the path to Ant is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable Jira Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
Ant home directory: This path specifies the top-level directory for Ant. The Jira sensor requires the placement of a sensor executable into Ant's lib/ directory.
Jira is a "multi-user" tool; in other words, the Issue data collected by the Jira sensor must be distributed among (potentially) several different Hackystat user accounts. To support the mapping of Jira data to Hackystat user accounts, you must specify the mapping of Jira usernames to Hackystat user keys using HackyInstaller. Section 2.7, “Sensors for multi-user tools and the usermaps.xml file” contains detailed instructions on this process.
Define an Ant target in your build.xml file that runs the Jira Issue Extractor task followed by the Jira sensor to send the retrieved data to Hackystat. Example 26.49, “Example Jira issue extraction and sensor target” illustrates such a target:
Example 26.49. Example Jira issue extraction and sensor target
<target name="jiraSensor"
description="Extracts Jira issues from a Jira server and sends them to Hackystat.">
<taskdef name="hacky-jira-issue-extractor" classname="org.hackystat.sensor.jira.JiraIssueExtractor" />
<hacky-jira-issue-extractor
outdir="${jira.report.dir}" 
verbose="off" 
projectPrefix="HACK" 
pid="10000" 
jiraServer="http://jira.hawaii.edu/" /> 
<taskdef name="hacky-jira-issue-sensor" classname="org.hackystat.sensor.jira.JiraIssueExtractorSensor" />
<hacky-jira-issue-sensor
verbose="off"
workspaceRoot="c:/jira/" > 
unassignedIssueOwnerHackystatAccountKey="888hdjdlc8i" > 
defaultUserHackystatAccountKey="jfheucb4h22u" > 
jiraUser="JiraUser" > 
jiraPassword="JiraUserPassword" > 
<fileset dir="${jira.report.dir}"> (11)
<include name="**.xml"/>
</fileset>
</hacky-jira>
</target>
Please note the following regarding Example 26.49, “Example Jira issue extraction and sensor target”:
| | Specifies where the Jira issue extractor should place the data downloaded from the Jira server. |
| | If verbose is on, then debugging data will be produced. |
| | The label used as a prefix for a given Jira project. Each invocation of the Jira extractor only retrieves data related to one project. If you wish to extract data for multiple projects, then run the Jira extractor multiple times before running the sensor. |
| | The numeric Project ID (PID) associated with this Jira Project. |
| | The URL to the Jira server. |
| | When using Jira with Hackystat, it is helpful to create a custom issue field called "Workspace", where developers can enter a Hackystat Workspace value to be associated with the issue. This Workspace value is typically entered without a Workspace Root. To facilitate analysis, this attribute asks the sensor to pre-pend the specified workspace root to the value of the Workspace field before sending the data to the server. In some Jira servers, no custom Workspace field is supplied. In this case, you can provide the "workspace" attribute to this sensor and supply it with a default Workspace string to be sent with all sensor data. |
| (11) | The fileset target specifies the set of XML files retrieved by the issue extractor task. |
| | If a Jira issue is not assigned to any user, then this attribute can be used to specify the user key to receive sensor data on those unassigned issues. If this attribute is not supplied and unassigned issues are encountered, they are ignored and no data on them is sent to the server. |
| | If a Jira issue is encountered that is assigned to a Jira account name that cannot be found in the Hackystat user map, then this attribute can specify the Hackystat user key to be sent the sensor data corresponding to this issue. If this attribute is not supplied and an unknown Jira account name is encountered, then the issue is ignored and no data on it is sent to the server. |
| | If the Jira server is not configured to allow "anonymous" read-only access to issues, then you must supply an account user and password to enable the issue extractor to login to Jira in order to get the date. The "jiraUser" attribute specifies the account user name. |
| | If the Jira server is not configured to allow "anonymous" read-only access to issues, then you must supply an account user and password to enable the issue extractor to login to Jira in order to get the date. The "jiraPassword" attribute specifies the account password. |
Section 4.14, “Measurement: Source code issues with Jira” provides another example of Jira sensor use with Hackystat.
If you are using Jira with SSL, you may get an error message with the sensor indicating that the certificate is untrusted. To fix this, you need to make Java aware of your server certificate. This involves the following: (1) Export the certificate from your browser. For example, with Internet Explorer you click on the certificate info, go to the Details tab, and export the certificate as a .cer file. (2) Using the Java "keytool", you can then import the certificate into your "truststore" which is located in $JAVA_HOME/jre/lib/security/cacerts. You can import it using 'keytool -import-file <servercert>.cer -keystore cacerts'
To verify your Jira sensor installation, invoke the target and check to see that data is sent to the server. Example 26.50, “Example Jira output” shows the shell output from an example run with verbose= "on" and some of the data elided for space reasons.
Example 26.50. Example Jira output
C:\cvs413\Stack>ant jiraIssueExtractor
Buildfile: build.xml
hacky-jira-issue-extractor:
[mkdir] Created dir: C:\IntegrationBuild\jira-sensor2\temp
[issue-extractor] Jira lives at: http://hackydev.ics.hawaii.edu:8080/
[issue-extractor] Determining latest Jira Issue.
[issue-extractor] Downloading http://hackydev.ics.hawaii.edu:8080/secure/IssueNavigator.jspa?view=rss&pid=10000&sorter/field=issuekey&sorter/order=DESC&tempMax=1&reset=true&decorator=none
[issue-extractor] Jira Issue Extractor will stop after downloading HACK-572
[issue-extractor] Downloading http://hackydev.ics.hawaii.edu:8080/browse/HACK-1?decorator=none&view=rss
[issue-extractor] Successfully extracted HACK-1.xml
[issue-extractor] Downloading http://hackydev.ics.hawaii.edu:8080/browse/HACK-2?decorator=none&view=rss
[issue-extractor] Successfully extracted HACK-2.xml
:
[issue-extractor] Downloading http://hackydev.ics.hawaii.edu:8080/browse/HACK-30?decorator=none&view=rss
[issue-extractor] Received: [404]
[issue-extractor] Failed to download HACK-30.xml
[issue-extractor] Failed to extract HACK-30.xml
:
[issue-extractor] Successfully extracted HACK-572.xml
[issue-extractor] Jira Issue Extractor stoping at last Jira Issue.
jira-issuesensor:
[issue-sensor] Sensor enabled?: true
[issue-sensor] Processing file: C:\IntegrationBuild\jira-sensor2\temp\HACK-1.xml
[issue-sensor] Sending issue data to Hackystat account zzyy76sdhfs
[issue-sensor] Processing file: C:\IntegrationBuild\jira-sensor2\temp\HACK-10.xml
[issue-sensor] No mapping. No default Hackystat account. No issue data sent.
[issue-sensor] Processing file: C:\IntegrationBuild\jira-sensor2\temp\HACK-100.xml
[issue-sensor] Sending issue data to Hackystat account Ty5kdcysce4wD
:
[issue-sensor] Hackystat data on 559 Jira Issues sent to http://hackystat.ics.hawaii.edu/ (23 secs.)
Most of this output is not shown when verbose mode is disabled.
Once you verify that Jira data is being sent from the client using verbose mode, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that Issue data for today's date was received by the server for the Jira tool, as illustrated in Figure 26.36, “ List Sensor Data with Jira data ”.
The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”
The Jira sensor writes out a file called jira.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.51, “Log file for Jira sensor”.
Example 26.51. Log file for Jira sensor
Hackystat Version: 6.3.1118 (November 18 2004 13:54:40)
SensorShell started at: 02/11/2005 16:51:55
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Activity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Perf
Defined shell command: Issue
Defined shell command: Build
Defined shell command: FileMetric
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> Issue [setTool, Jira]
setTool OK
#> Issue [add, TRUSS-1, Refactor Truss PBB code for distribution, Improvement, Major, Closed, 1094249226000, mpauldin, mpauldin, c:/jira/pbb/truss, 1108176715783, link=http://hackydev.ics.hawaii.edu:8080/browse/TRUSS-1]
Issue add OK (1)
#> Issue [add, TRUSS-3, Test ANTLR Parser on Truss PBB Code, Improvement, Major, Resolved, 1094618976000, mpauldin, mpauldin, c:/jira/pbb/truss, 1108176715783, link=http://hackydev.ics.hawaii.edu:8080/browse/TRUSS-3]
Issue add OK (2)
#> Issue [add, TRUSS-4, Post CLI and Diary Data to Truss PBB Website, Task, Major, Resolved, 1094619086000, mpauldin, mpauldin, c:/jira/pbb/truss, 1108176715783, link=http://hackydev.ics.hawaii.edu:8080/browse/TRUSS-4]
Issue add OK (3)
#> send
Sending sensor data (02/11 16:51:56)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
AutoSend: AutoSend OK ('send' command ignored)
Issue: Send OK (3 entries)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
Activity: Send OK (No entries to send.)
Coverage: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
BuffTrans: Send OK (No entries to send.)
Build: Send OK (No entries to send.)
If you are having problems extracting issues from the Jira server, try the following.
Verify that your Jira Issues are accessible with the following URL format:
[JIRA_URL]/browse/[JIRA_ISSUE_ID]?decorator=none&view=rss
Also verify that the Issue Navigator is accessible with the following URL format:
[JIRA_URL]/secure/IssueNavigator.jspa?view=rss&pid=[JIRA_PROJECT_ID]&sorter/field=issuekey&sorter/order=DESC&tempMax=1&reset=true&decorator=none
Verify that your project allows Anyone to view Jira issues. You may or may not need to also set your Jira Installation type to "public".
Verify that the jiraServer attribute value is the correct URL for your Jira Server by manually retrieving that URL in a browser.
Verify that the projectPrefix attribute value is the correct prefix for the Jira Issues you are extracting. For example, projectPrefix="HACK" is the prefix for the HACK-1 Jira Issue.
Verify that the pid (project identifier) attribute value is the correct identifier for the Jira Project from which you are extracting issues. For example, pid="10000" is the prefix for the Hackystat project. This value can be confirmed by accessing the following:
[JIRA_URL]/secure/BrowseProject.jspa?id=[JIRA_PROJECT_ID]
If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information:
The output from 'java -version'.
The output from 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the jira.0.log file.
The JiraSensor task.
A description of the problem you are having.
To disable Jira data collection temporarily, invoke HackyInstaller, bring up the Jira configuration window, and uncheck the "Enable Jira sensor" property, and apply the setting. To permanently uninstall the Jira sensor, press the "Uninstall" button and remove the Jira targets from your Ant build.xml files.