CodeSonar for JIRA Plugin - Documentation

Overview

This guide provides instructions on how to install and configure the CodeSonar for JIRA plugin. The plugin allows CodeSonar and JIRA users to take advantage of the following features:

The plugin is structured as two separate components: one for the CodeSonar hub, and one for a JIRA cloud or server instance. The following sections describe how to install and configure both components.

JIRA Configuration

To configure a JIRA instance to work with a CodeSonar hub, perform the following steps on the JIRA instance:

The configuration page is broken up into multiple sections, each of which is explained below.

CodeSonar Hub

In this section, you can specify the connection settings used to communicate from JIRA to the CodeSonar hub.

Field Meaning
Hub Address The address of the CodeSonar hub. This should be entered with a prefix of “http://“, or “https://“ for encrytped connections.
Timeout (ms) The amount of time the JIRA server will wait before timing out when communicating with the CodeSonar hub. The default timeout is 30 seconds.
Hub Username The CodeSonar username used when updating a warning on the hub if it’s been changed in JIRA.
Password The password for the CodeSonar username mentioned above.

HTTPS Connections

When using HTTPS as the protocol for the CodeSonar hub, the hub’s certificate must be imported into the JIRA server’s certificate store. See the following Atlassian page for insturctions on adding SSL certificates to JIRA servers: https://confluence.atlassian.com/jira/connecting-to-ssl-services-117455.html.

Priorities

Here you can specify the mappings between the CodeSonar and JIRA Priority fields. Below is a table that lists the default mappings:

CodeSonar Value JIRA Value
None Lowest
P0: High High
P1: Medium Medium
P2: Low Low

States

In this section, you can provide mappings between the CodeSonar and JIRA State fields. Below is a table of the default mappings:

CodeSonar Value JIRA Value
Assigned In Progress
Fixed Done
None To Do

Owners

This section provides a few options for mapping CodeSonar owners to JIRA users.

Bulk Add Owners from Text Area

Here you can enter pairs of CodeSonar and JIRA users, separated by a comma. Each user pair should be separated by a new line. For example:


CS User 1, JIRA User 1
CS User 2, JIRA User 2

Bulk Add Owners from CSV File

You may also upload a user mapping from an external CSV file. The format of the file is the same as the format used when entering users into the Bulk Add Owners text area.

After clicking Choose File to select the CSV file to be uploaded, click the Bulk Add Owners next to it to start uploading the file.

Automatically Map Owners

If the name of a CodeSonar owner is a substring of a JIRA user name, clicking Automatically Map Owners will create a mapping for that owner. Automatic mappings will not override existing mappings.

Manually Map Owners

The table at the bottom shows the current mappings, and allows you to delete a mapping, as well as manually add a new one using the drop-down lists.

Projects

This section allow for providing mappings between JIRA and CodeSonar projects. Mappings may be entered manually for existing JIRA projects, or new JIRA projects can be created automatically for a CodeSonar project.

Automatic Project Creation

When set to True, any CodeSonar project that submit warnings to a JIRA server that does not already have a mapping in the table of existing mappings will result in a new JIRA project being created and mapped to that CodeSonar project. The new JIRA project that is created will be cloned from the project specified from the drop-down “Project Key Name [to be cloned]”.

Table of Project Mappings

The table at the bottom of the Projects page lists the current mappings between CodeSonar Project Id and JIRA Project Key. New mappings can be manually added by clicking the Add button, and existing mappings can be deleted by clicking the Delete button.

CodeSonar Hub Configuration

Configuration of the CodeSonar hub involves the following:

Each of these steps are described below.

Installing the Warning Processors

To configure the CodeSonar hub, several warning processors must be installed. You can download these from the link provided on the configuration page for CodeSonar’s JIRA plugin.

On the jira server instance, go to url “/jira/plugins/servlet/codesonar/config”, or click on the “Configure” link in the CodeSonar-JIRA add-on description box. Near the top of the configuration form, you should see a link called “Download Warning Processors”. Clicking on this link will download a zip file “processors.zip”.

Extract the contents of this zip file into your CodeSonar hub’s “processors” directory, and follow the instructions in the CodeSonar manual for install a Warning Processor. You should install “jira_A_CreateTicket” to run automatically, and the other three (“jira_I_CreateTicket”, “jira_I_UpdateTicket”, and “jira_I_LinkToTicket”) should be configured to run interactively. Instructions for how to install the Warning processors are given here briefly as a reference.

  1. Edit the warning processor scripts to contain the correct values for HUB and CS_BASE so that they match your hub and codesonar installation locations. If on windows, edit the scripts that end in “.bat”, otherwise, edit the ones that end with “.sh”.
  2. Navigate to the warning processors page on your hub. To do this, go to Settings -> Other Links -> Warning Processors.
  3. Install the “jira_A_CreateTicket” processor, entering for the Label “Automatically Create JIRA Issues”, and for the “Processor Executable”, type in “jira_A_CreateTicket.sh” (or “jira_A_CreateTicket.bat” if on windows) without the quotes.
  4. Check the box that says “Run processor automatically on incoming warnings.”
  5. For the other warning processors, install them in the same way, but do not click “Run processor automatically on incoming warnings.” Here are some suggested labels to use for these other warning processors:
Warning Processor Script Label
jira_I_CreateTicket Create New JIRA Issue
jira_I_UpdateTicket Update JIRA Issue
jira_I_LinkToTicket Link to Existing JIRA Issue

Setting the Public URL

To set the Public URL on the hub, go to the CodeSonar hub and navigate to the Administrator settings page. At the top, there should be a section called “HTTP”. Under that section, you should see a field for “Public URL”. Set this to the URL that is accessible from the JIRA server instance.

Configuring global-settings.py

The following configuration settings are listed in the file “jira_utils/global-settings.py”, located in the “processors” directory of your hub (after you have installed the warning processors that come with the JIRA plugin):

Name Default Value Meaning
IS_HTTPS_ENABLED False True if the hub is configured to use HTTPS.
HTTPS_CERTIFICATE_PATH - If IS_HTTPS_ENABLED is True, this should point to the location of the hub’s SSL certificate.
LOG_FILE “jira_plugin_log.txt” The location for the output of all commands sent to the JIRA server by the hub’s warning processors. By default it will be saved to the hub’s root directory.
JIRA_LOCATION “localhost:2990” The url location of the JIRA server.
JIRA_PATH “/jira” This is url path to the JIRA installation on the server at JIRA_LOCATION
JIRA_USER “admin” The username of the JIRA user that will be used to manage issues and tickets.
JIRA_PASSWORD “admin” The password for JIRA_USER
JIRA_TIMEOUT 5 Timeout in seconds for communication between the CodeSonar warning processors and the JIRA server.

These settings are used by the JIRA warning processors on the hub, and they must be set correctly in order for changes on the hub to be reflected in JIRA.

Warning Processors

Below is a brief description of the functionality of each warning processor that comes with the JIRA plugin.

Create Ticket (Automatic)

Installing this processor will allow the CodeSonar hub to automatically create JIRA issues for all incoming warnings. It will only create new JIRA issues for new warnings submitted by any new analyses, and the analysis’ project must be mapped to a JIRA project (see the JIRA configuration section above).

Create Ticket (Interactive)

For any existing warning on the CodeSonar hub, you can visit the warning report page and manually run this warning processor to create a corresponding issue in JIRA. You must have mapped the CodeSonar project to a JIRA project in order for this to work (see the JIRA configuration section above). After running this, it will create a new issue on the JIRA server.

For any existing warning on the CodeSonar hub, you can link it to an existing JIRA issue by manually running this warning processor.

Update Ticket (Interactive)

If any warning on the CodeSonar hub is already linked with a JIRA issue, you can use this processor to force an update to the corresponding JIRA issue.

Troubleshooting

When I try to install a warning processor, I see the message “CreateProcess failed: 5: Access is denied.” or “install : exited with status 255”

This is probably because the name of the warning processor’s directory was entered into the “Processor Executable” field. Make sure to enter the name of the warning processor’s executable script file, which should end in “.bat” for Windows, or “.sh” for other operating systems.

My change to a JIRA issue isn’t affecting the corresponding CodeSonar warning.

This is likely due to the JIRA issue and the CodeSonar warning being out of sync with respect to their warning properties. Try setting the JIRA issue’s properties to match the CodeSonar warning’s properties. This should put the JIRA issue in the same state as the CodeSonar warning, causing the two items to be back in sync, and allowing any JIRA issue changes to affect the corresponding CodeSonar warning.

Another possible cause is that the “Public Url” was not set on the CodeSonar hub. If this is the case, the description in the JIRA issue will not contain a prefix in the url, but rather just the path to the CodeSonar warning (for example, “/warninginstance/23.html”). Make the the Public Url is set to an address that is accessible from the JIRA server.

My change to a CodeSonar warning isn’t affecting the linked JIRA issue.

In order for changes on a CodeSonar warning to affect the JIRA issue, you have to manually run the “Update Ticket” warning processor on the CodeSonar warning, in addition to changing the warning properties.

When I run a new analysis in CodeSonar, no new JIRA issues are created on my JIRA server, even though I have the jira_A_CreateTicket warning processor installed and set to run automatically on incoming warnings.

In order to create a new JIRA issue, the CodeSonar project must first be mapped to an existing JIRA project. To do this, go to the CodeSonar-JIRA plugin’s configuration page (in JIRA, as an Admin, click the “gear”, then Add-ons, Manage add-ons, then find “CodeSonar for JIRA”, expand it, and click Configure), click on the “Projects” tab, then add your CodeSonar project to a JIRA project. Make sure you use the exact project ID of the CodeSonar project (shown in your CodeSonar hub project page URL: http://<interface>:<port>/project/<project_ID>.html). Also make sure that the JIRA project associated with the CodeSonar project allows for “Bug” issue types in its workflow.

If these suggestions don’t work, please examine the log file in your hub directory, “jira_plugin_log.txt”, and contact support for help.

Version

This documentation is for version 2.04 of the CodeSonar-JIRA plugin.

Upgrading from an older version

If upgrading from an older version of the CodeSonar-JIRA plugin, note that you will need to install the new Warning Processors on your hub. To do this, simply download the new Warning Processors using the “Warning Processors” link at the top of the CodeSonar-JIRA configuration page.

Also note that the previous projects mapped on the “Projects” section of the CodeSonar-JIRA configuration page will be lost, since CodeSonar Project IDs are now used instead of Project names.