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 server instance. You will need to install and configure both components in order to use the plugin.

The remainder of this document is divided into the following sections.

Installation and Configuration: Jira Server

Note: The CodeSonar for Jira Plugin is for Atlassian Jira Server; it is not compatible with Atlassian Jira Cloud. CodeSonar also integrates with Jira Cloud: see the CodeSonar manual for more information.

  1. Download and install the CodeSonar plugin on your Jira Server instance.

    See the following Atlassian page for instructions: https://marketplace.atlassian.com/apps/1215734/codesonar-for-jira?hosting=server&tab=installation.

  2. Open the CodeSonar plugin configuration page by doing one of the following.

    • Visit the following URL on your Jira Server: https://<jira-server>/jira/plugins/servlet/codesonar/config.
    • Click the Configure button in the CodeSonar-Jira add-on (app) description box.

    The configuration page has several tabs for specifying mappings between the various properties of CodeSonar warnings and Jira issues, as well as specifying the location and certain other parameters of a CodeSonar hub. In the next few steps, you will work through these tabs.

  3. Configuration page, CodeSonar Hub tab: the connection settings used to communicate from Jira to the CodeSonar hub.

    Fill out all fields. It is recommended that you use a separate, dedicated hub user account for this Jira Server plugin and you do not share this account for interactive hub use.

    Field Meaning
    Hub Address The address of the CodeSonar hub, including protocol (http:// or https://). This should match the hub Public URL, which you will set when you configure the hub.
    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 authenticating with the hub to synchronize CodeSonar warning and Jira Issue information.
    Password The password corresponding to Hub Username.

  4. Configuration page, Priorities tab: mappings between the CodeSonar and Jira Priority fields.

    If you have added custom Priority values for either CodeSonar or Jira, or if the default mappings (shown in the following table) are not suitable, use the Add and Delete buttons to adjust the set of mappings.

    CodeSonar Priority Jira Priority
    None Lowest
    P0: High High
    P1: Medium Medium
    P2: Low Low

  5. Configuration page, States tab: mappings between the CodeSonar and Jira State fields.

    If you have added custom State values for either CodeSonar or Jira, or if the default mappings (shown in the following table) are not suitable, use the Add and Delete buttons to adjust the set of mappings.

    CodeSonar State Jira State
    Assigned In Progress
    Fixed Done
    None To Do

  6. Configuration page, Owners tab: mappings between CodeSonar warning owners (hub user accounts) and Jira users.

    This tab provides several mechanisms for specifying mappings. You can use any combination of these mechanisms.

    • Bulk Add Owners from Text Area

      Enter pairs of CodeSonar and Jira users, separated by a comma, then click Bulk Add Owners. 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

      Click Choose File to select a file to upload, then click Bulk Add Owners.

      The CSV file format is the same as that for Bulk Add Owners from a Text Area.

    • Automatically Map Owners

      When you click Automatically Map Owners, the plugin will attempt to map each CodeSonar user account to a unique Jira user account with a similar name.
      Similarity is established if the CodeSonar user name is a substring of the Jira user name or vice versa.
      Automatic mappings will not override existing mappings.

    • Manually Map Owners

      The table at the bottom of this tab shows all current owner mappings.

      • To delete an existing mapping, click the Delete Mapping button on the corresponding table line.
      • To add a new mapping, select the CodeSonar Owner and corresponding Jira Assignee from the drop-down lists, then click Add.

  7. Configuration page, Projects tab: mappings between Jira and CodeSonar projects.

    This tab provides two mechanisms for specifying mappings. You can use any combination of these mechanisms.

    • Automatic Project Creation

      When set to True, any CodeSonar project that submits 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 this tab shows all current project mappings.

      • To delete an existing mapping, click the Delete Mapping button on the corresponding table line.
      • To add a new mapping, enter a CodeSonar Project ID number, then select the corresponding Jira Project Key from the drop-down lists and click Add.

      The CodeSonar project ID can be extracted from the URL of the corresponding Project page in the web GUI. For example, if the URL is http://<codesonar-hub>/project/1234.html, the Project ID is 1234.

  8. [HTTPS CodeSonar Hubs Only] If your hub uses HTTPS (not HTTP), import its hub server certificate into the Jira server's certificate store.

    1. Navigate to the hub's Configure HTTPS page: click Settings in the quick navigation menu to open the Settings page, then switch to the HTTP tab and click the configure link.
    2. In the Server Certificate section, click Download Certificates(s) to download the hub server certificate.
    3. Upload this certificate to your Jira server. For instructions, see https://confluence.atlassian.com/jira/connecting-to-ssl-services-117455.html.

Installation and Configuration: CodeSonar Hub

Setting up the CodeSonar hub to work with the Jira Server plugin involves three main steps.

These steps are described in detail below.

Step A. Set the hub's Public URL.

First, you will set the hub's Public URL to the URL that the Jira server should use to access the hub.

  1. Sign in to the CodeSonar web GUI as a user with G_ADMINISTER_HTTP_SETTINGS permission. (It is sufficient to sign in as a user with the Administrator role. In particular, it is sufficient to sign in as the special Administrator user.)
  2. Click Settings in the quick navigation menu in the web GUI page header. The Settings page will open.
  3. Switch to the HTTP tab.
  4. Enter a suitable value in the Public URL field.
    • Make sure it includes the protocol and port.
    • The URL must be accessible from the Jira server instance.
    • For example: https://codesonar.example.com:7340.
  5. Click Update to save your changes.

Step B. Download and install the warning processors

To configure the CodeSonar hub for interaction with your Jira server instance, you will download and install several CodeSonar warning processors.

  1. Download the warning processors from the configuration page for CodeSonar's Jira plugin.

    1. Navigate to https://<jira-server>/jira/plugins/servlet/codesonar/config, where https://<jira-server> is the URL for your Jira Server instance. Alternatively, you can click the Configure button in the CodeSonar-Jira add-on description box.
    2. Click the Download Warning Processors link, near the top of the configuration form.

    This will download a zip file: csjira-processors.zip.

  2. Extract the contents of this zip file. This should create a directory named csjira.

  3. Copy all the files in the csjira directory into your CodeSonar hub's processors subdirectory.

    cp -r csjira/* <hubdir>/processors/

    where <hubdir> is the hub directory for your CodeSonar hub.

  4. On POSIX systems including Linux, be sure that all warning processor script files with extension .sh have execute permissions.

    chmod +x <hubdir>/processors/*.sh

  5. Sign into your hub's web GUI as a user with G_ADD_WPROCESSOR permission. (It is sufficient to sign in as a user with the Administrator role. In particular, it is sufficient to sign in as the special Administrator user.)

  6. Install the jira_A_CreateTicket warning processor.

    1. Edit the warning processor script file to set the CSONAR variable to match your CodeSonar installation location. The script file is <hubdir>/processors/jira_A_CreateTicket.bat on Windows systems and <hubdir>/processors/jira_A_CreateTicket.sh otherwise.
    2. In the hub's web GUI, navigate to the Manage Warning Processors page.
      1. Click Settings in the quick navigation menu in the web GUI page header. The Settings page will open.
      2. Switch to the Other Links tab.
      3. Click Warning Processors. The Manage Warning Processors page will open.
    3. Fill out the Install Warning Processor form.
      • Label: Automatically Create Jira Issues
      • Processor Executable: jira_A_CreateTicket.sh (or jira_A_CreateTicket.bat if on Windows)
      • Run processor automatically on incoming warnings?: selected
    4. Click Install.

  7. Install the remaining warning processors: jira_I_CreateTicket, jira_I_UpdateTicket, and jira_I_LinkToTicket.

    The process is the same as for jira_A_CreateTicket in step 6, except that you will not enable the Run processor automatically on incoming warnings option.

    Suggested Label Warning Processor Script Run processor automatically on incoming warnings?
    Automatically Create Jira Issues jira_A_CreateTicket (.sh or .bat) Yes
    Create New Jira Issue jira_I_CreateTicket (.sh or .bat) No
    Update Jira Issue jira_I_UpdateTicket (.sh or .bat) No
    Link to Existing Jira Issue jira_I_LinkToTicket (.sh or .bat) No

Step C. Edit global_settings.py

The Jira warning processors use a number of configuration settings. These must be set correctly in order for changes on the hub to be reflected in Jira.

  1. Open file <hubdir>/processors/jira_utils/global_settings.py for editing, where <hubdir> is the hub directory for your CodeSonar hub.

  2. Check the following settings, updating as required.

    Name Set to... Default
    IS_HTTPS_ENABLED True if your Jira Server is configured to use HTTPS, False otherwise. False
    HTTPS_CERTIFICATE_PATH The path to a file containing the Jira Server's HTTPS certificate in ASCII "PEM" format.
    (Interpreted relative to the hub directory.)
    If IS_HTTPS_ENABLED is False, this setting is ignored.    		 None
    LOG_FILE The path to a log file for the output of all commands sent to the Jira server by the hub's warning processors.
    (Interpreted relative to the hub directory.)    		 "processors/jira_plugin_log.txt"
    JIRA_LOCATION The location of the Jira server, expressed as <jirahost>:<jiraport>. "localhost:2990"
    JIRA_PATH This is URL path to the Jira installation on the server at JIRA_LOCATION "/jira"
    JIRA_USER The username of the Jira user that will be used to manage issues and tickets. "admin"
    JIRA_PASSWORD The password for JIRA_USER "admin"
    JIRA_TIMEOUT Timeout in seconds for communication between the CodeSonar warning processors and the Jira server. 5

Warning Processors

This section provides additional details about the various CodeSonar warning processors that come with the Jira plugin.

For more information on warning processors, see the CodeSonar manual.

Automatic Warning Processor

When you install the jira_A_CreateTicket warning processor, you will configure it to run in automatic mode.

Automatic warning processors are applied automatically to each warning submitted to the hub.

When the jira_A_CreateTicket is installed in automatic mode, the CodeSonar hub will automatically create Jira issues for all new incoming warnings. New instances of existing warnings will be associated with the existing corresponding Jira issue: a new Jira issue is not created in this case.

It will only create new Jira issues for new warnings submitted by new analyses, and the CodeSonar project for the analysis must be mapped to a Jira project (see the Jira configuration section above).

Interactive Warning Processors

When you install the jira_I_CreateTicket, jira_I_UpdateTicket, and jira_I_LinkToTicket warning processors, you will configure them to run in interactive mode.

Interactive warning processors run only when interactively triggered by a user.

Warning Processor Usage
jira_I_CreateTicket Create a ticket: Run manually on a CodeSonar warning to create and link a new, corresponding issue in Jira.
The CodeSonar project containing the warning must already be mapped to a Jira project in order for this to work (see the Jira configuration section above).
jira_I_UpdateTicket Update a ticket: Run manually on a CodeSonar warning that is already linked with a Jira issue to force an update to the corresponding Jira issue.
jira_I_LinkToTicket Link to ticket: Run manually on a CodeSonar warning to link it to an existing 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 in 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 and .sh for other operating systems.

My change to a Jira issue isn't affecting the corresponding CodeSonar warning.

There are several possible causes, including the following.

My change to a CodeSonar warning isn't affecting the linked Jira issue.

Changes to a CodeSonar warning are only propagated to the linked Jira issue when you manually run the "Update Ticket" warning processor on that warning.

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.

The most likely explanation is that the CodeSonar project that you are analyzing is not mapped to an existing Jira project.

To set up a mapping:

  1. Navigate to https://<jira-server>/jira/plugins/servlet/codesonar/config, where https://<jira-server> is the URL for your Jira Server instance. Alternatively, you can click the Configure button in the CodeSonar-Jira add-on description box.
  2. Change to the Projects tab
  3. Add a mapping table entry to map your CodeSonar project ID (a number) to the project key for a Jira project.
    • The CodeSonar project ID can be extracted from the URL of the corresponding Project page in the web GUI. For example, if the URL is http://<codesonar-hub>/project/1234.html, the Project ID is 1234.
    • Make sure that the Jira project that you are mapping allows for "Bug" issue types in its workflow.

If this does not resolve the issue, please examine the log file in your hub directory, jira_plugin_log.txt, and contact support for help.

Version

This documentation is for version 3.04 of the CodeSonar-Jira plugin.

Upgrading from an older version

If upgrading from an older version of the CodeSonar for Jira plugin, note that you will need to do the following.

  1. Download and install the upgraded CodeSonar for Jira plugin on your Jira Server instance.
  2. Check the CodeSonar for Jira plugin configuration and update if necessary.
    • In some old versions of the CodeSonar for Jira plugin, projects were mapped by name instead of ID.
      If you are upgrading from a version of the plugin that used project names for mappings, then all mappings will be deleted and you will need to re-map your projects.
  3. Save a copy of your existing <hubdir>/processors/jira_utils/global_settings.py file in a location outside your hub directory (<hubdir>). The existing file will be overwritten when you unpack the new warning processors.
  4. Update the CodeSonar for Jira warning processors on your hub.
    1. Remove the old CodeSonar for Jira warning processors from your hub using the functionality on the hub Manage Warning Processors page.
    2. Download the new warning processors using the Warning Processors link at the top of the CodeSonar-Jira configuration page.
    3. Install and configure the new warning processors as described above. Use the copy of global_settings.py that you saved in the previous step to help inform the configuration step.