JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

Jira Cloud Integration for CodeSonar

CodeSonar provides an integration for Jira Cloud through a warning processor. This page provides information about configuring and using the integration.

For Jira Server integration information, see Third-Party Software Integrations: External Integrations: Project Management.

Overview

The Jira Cloud integration is implemented as a warning processor that ships with CodeSonar.

When installed, this warning processor allows users to specify relationships between CodeSonar warning groups and Jira issues, and then push information on-demand from warnings to their mapped issues. Information transfer is currently one-way: the hub sends warning information to Jira Cloud, but Jira Cloud does not send warning information to the hub. In particular, issue updates performed in the Jira Cloud interface will not be reflected in corresponding warning reports. This may change in a future release.

Jira Cloud deployments are highly customizable. In consequence, the warning processor is highly configurable. In all cases, you will need to provide the location of your Jira Cloud instance, a default project key, and a mapping from hub usernames to usernames on your Jira Cloud instance. The remaining default settings for the warning processor are designed to work with a Jira "Bug Tracking" project in its default configuration. You may need to perform further warning processor configuration if you are working with other Jira Cloud project types.

Setting Up

The setup steps must be performed on the machine that is running the hub.

We strongly recommend that the person performing setup be highly familiar with your organization's Jira Cloud deployment: configuration requirements depend heavily on your Jira configuration.

  1. Make sure you have the following information.
  2. Run the following command to generate the warning processor files and move them into the hub directory.
    codesonar jira_cloud_hub_install.py hubdir service_location pkey

    Where:

    The subcommand will create two files.

    For more information, including optional subcommand components, see codesonar jira_cloud_hub_install.py below.
  3. Edit file hubdir/processors/jira_cloud.settings.json to configure the warning processor.
    (If you specified a different processor name with --processor-name, edit the correspondingly-named .json file.)
    1. In all cases, you will need to edit the warning_issue_field_maps.CS_JIRA_USER_MAP object to specify the mapping from hub user account usernames to Jira user accounts. You will not be able to push information from a mapped warning to a Jira issue if the warning processor cannot determine how to handle the warning's Owner .
      JSON Property Set to
      warning_issue_field_maps.CS_JIRA_USER_MAP.source owner
      warning_issue_field_maps.CS_JIRA_USER_MAP.target The Jira issue field that indicates the user to whom the issue is assigned. In most cases this will be Assignee.
      warning_issue_field_maps.CS_JIRA_USER_MAP.options.hubuser The Jira user account that corresponds to the hub user account whose username is hubuser.

      Specify an instance of this property for each hub user account.
      (It is sufficient to define mappings only for users that have ANALYSIS_OWN_WARNINGS permission for one or more analyses on the hub, since those are the only users who can be a warning Owner.)

      The value is either a string or an object.

      • string: The Jira user account name ("display name"), spelled exactly with correct letter casing. Use the empty string to indicate that the issue should be unassigned.
      • object: an object with exactly one of the following properties:
        display_name [string] The Jira user account name ("display name"), spelled exactly with correct letter casing.
        email_address [string] The email addresss used to identify the user in Jira. Email address may be hidden and therefore may not be a reliable way to identify users.
        account_id [string] The Jira user account ID string. This is usually 24 characters of random letters and numbers, and can be found in the URL of a user profile page found by searching for 'People' in Jira. An account ID is the most reliable way to identify a Jira user.
      warning_issue_field_maps.CS_JIRA_USER_MAP.options.None A special case of warning_issue_field_maps.CS_JIRA_USER_MAP.options.hubuser for the case where the CodeSonar warning has no Owner.
    2. If your Jira project is not a "Bug Tracking" project in its default configuration, or you have customized the sets of Priority, State, and Finding values for your hub, you may need to edit additional JSON properties in order to configure the warning processor.
      • jira_service.service_location.warning_issue_types are the issue types that will be presented as an option when the warning processor creates a new Jira issue fore the service at service_location.
      • warning_issue_field_maps.HIGH_MED_LOW_PRIORITY_MAP describes the mapping between CodeSonar warning Priority values and Jira issue "Priority" values.
        • Use the warning_issue_field_maps.HIGH_MED_LOW_PRIORITY_MAP.target property to specify a different Jira issue field to map to.
        • If you have added custom CodeSonar Priority values to your hub, make sure they are represented here.
        • Certain Jira issue types, such as those found in "Team Managed Scrum" projects do not include a priority field. If your issue type does not have a priority field, see the notes on Customizing Mappings, below.
      • warning_issue_field_maps.SIMPLIFIED_WORKFLOW_STATUS_MAP describes the mapping between CodeSonar warning State values and Jira issue "Status" values.
        • Use the warning_issue_field_maps.SIMPLIFIED_WORKFLOW_STATUS_MAP.target property to specify a different Jira issue field to map to.
        • If you have added custom CodeSonar State values to your hub, make sure they are represented here.
        • If one or more of your specified Jira issue types (in the warning_issue_types property) does not have a field that corresponds to warning State, or if the issue types have differing corresponding fields, see the notes on Customizing Mappings, below.
      • warning_issue_field_maps.FINDING_CUSTOM_FIELD_MAP describes the mapping between CodeSonar warning Finding values and Jira issue "Finding" values.
        • This mapping is not used in the default warning processor configuration, because the Jira "Bug" issue type does not have a suitable field to map to. See the notes on Customizing Mappings, below, for more information.
        • Use the warning_issue_field_maps.FINDING_CUSTOM_FIELD_MAP.target property to specify a different Jira issue field to map to.
        • If you have added custom CodeSonar Finding values to your hub, make sure they are represented here.
      JSON schema documentation is available in $CSONAR/py/processors/jira_cloud/jira_cloud_warning_processor.settings.schema.json
  4. Sign into the hub as a user with G_ADD_WPROCESSOR permission.

    It is sufficient to authenticate as a user with the special Administrator role, which immutably has this permission. In particular, it is always sufficient to authenticate as special user Administrator.

  5. Open the Admin Settings page, switch to the Other Links tab, and click Warning Processors.
    The Manage Warning Processors page will open.
  6. Fill out the Install Warning Processor form as follows.
    Form Field Contents Notes
    Label Jira You can specify a different label if you prefer.
    Processor Executable
    hub_directory/processors/    		 jira_cloud.bat (Windows)
    jira_cloud.sh (otherwise)
    		 If you provided a different processor name with --processor-name, specify the correspondingly-named .bat or .sh file.
    Run processor automatically on incoming warnings. unselected The warning processor is suitable for Manual mode only.
  7. Click Install.
    The processor will be installed. The page will be updated to display the new set of installed processors, along with a confirmation message showing the processor's label, executable, and display script.

Using the Integration

Once the warning processor is set up, you can start using it.

The processor can provide two kinds of operation:

The integration has the following authentication and authorization requirements.

Map a warning to a Jira issue

  1. Navigate to the Warning Report of interest.
  2. Scroll to the Change Warning form.
  3. Select the Link to Jira Issue checkbox, and make any other changes you want to make to the Change Warning form.
  4. Save your changes.
    1. Click Save Changes.
    2. If you have not already authenticated a Jira Cloud session, you will be prompted for your credentials.
      Enter your Log-In Name and API Token , then click Login.
    The hub will display a page with heading "Warning Processor: Jira Cloud".
  5. Specify the Jira issue to which the warning should be linked.
    1. If you have configured several different service locations for the warning processor, make sure the correct one is selected as the Atlassian Service.
    2. Are you mapping to an existing Jira issue, or do you want to create a new one for this warning?
      • EXISTING ISSUE
        1. Select the Link existing issue radio button.
        2. Enter the Jira Issue key for the Jira issue you want to map to.
        3. If you want to push existing warning properties to the issue, select the Push now? checkbox. Leave it unselected if you want to keep the current values of the Jira issue.
      • NEW ISSUE
        1. Enter the Jira Project key for the Jira project that the new issue will belong to.
        2. Select the Jira Issue type to create.
        3. Depending on your warning processor configuration, there may be additional form fields. If so, fill these out to specify further aspects of the new Jira issue.
        Warning properties are always pushed to the new issue.
    3. Click OK.
    The hub will display a page with heading "Warning Processor: Jira Cloud".
  6. Check the page contents to make sure they are as you expect, then click Continue.
    The Warning Report will be displayed.
  7. Inspect the Warning Report Change History. It should include a new comment with prefix [codesonar-jira] link that provides an automatically-generated record.
  8. Inspect the Jira Cloud issue whose key is jira_issue_key. The issue should be updated to reflect any changes to warning properties since last time you performed this synchronization.

Push a warning's properties to its mapped Jira issue

  1. Navigate to the Warning Report of interest.
  2. Scroll to the Change Warning form.
  3. Select the Push to Jira Issue jira_issue_key checkbox, and make any other changes you want to make to the Change Warning form.
  4. Save your changes.
    1. Click Save Changes.
    2. If you have not already authenticated a Jira Cloud session, you will be prompted for your credentials.
      Enter your Log-In Name and API Token, then click Login.
    The hub will display a page with heading Warning Processor: Jira Cloud, containing a Link to Jira form.
  5. Check the page contents to make sure they are as you expect, then click Continue.
    The Warning Report will be displayed.
  6. Inspect the Warning Report Change History. It should include a new comment with prefix [codesonar-jira] push that provides an automatically-generated record.
    If you made other changes to the warning properties, they will be recorded in a separate comment.
  7. Inspect the Jira Cloud issue whose key is jira_issue_key. The issue should be updated to reflect any changes to warning properties since last time you performed this synchronization.

Change Multiple Warnings

You can use the warning processor with the CodeSonar Change Multiple Warnings functionality. The following additional notes apply.

API tokens

Each hub user that uses the warning processor to create or push information to a Jira issue will need an API token for the Jira Cloud instance.

codesonar jira_cloud_hub_install.py

The general form of the codesonar jira_cloud_hub_install.py subcommand is as follows.

codesonar jira_cloud_hub_install.py hubdir service_location pkey
[-h]
[--processor-name dest_name] [--overwrite]

Where the command components are as follows.

hubdir The path to the hub directory.
service_location The Atlassian service location with which the warning processor should communicate.
This will typically be a hostname of the form your-service-.name.atlassian.net
pkey The default Jira Project Key for warning synchronization. By default, CodeSonar warnings will be associated with Jira issues in this project (users will have the opportunity to specify a different project key when they create a mapping).
[-h] Instructs the subcommand to print a help message and then exit.
[--processor-name dest_name] The name with which to create the warning processor setup files. Two files will be created:
  • A warning processor installation script hubdir/processors/dest_name.ext, where ext depends on the local system and hubdir is the specified hub directory.
    • Windows: hubdir/processors/dest_name.bat
    • otherwise: hubdir/processors/dest_name.sh
  • A configuration file hubdir/processors/dest_name.settings.json
If [--processor-name dest_name] is not specified, the basename will be jira_cloud.
[--overwrite] Specifies that the subcommand should overwrite existing hubdir/processors/dest_name.ext and hubdir/processors/dest_name.settings.json, if they exist.
If --overwrite is not specified, the subcommand will fail if it encounters an existing file in either of these locations.

Uninstalling

To uninstall the warning processor, follow the standard procedure for uninstalling warning processors.

Customizing Mappings

CodeSonar warning property → Jira issue field mappings can be modified or disabled. If a CodeSonar warning property (Finding, Owner, Priority, Status) does not have a corresponding Jira issue field, the mapping associated with that warning property must be disabled to prevent a FieldMapping synchronization error.

Disable mappings for all issue types on all projects for your Jira service

  1. If you haven't already done so, open your configuration file hubdir/processors/jira_cloud.settings.json for editing.
  2. Find the cs_warning_fields property for the service location you are interested in. Its default setting is: 
        "cs_warning_fields": {
        "priority": "HIGH_MED_LOW_PRIORITY_MAP",
        "state": "SIMPLIFIED_WORKFLOW_STATUS_MAP",
        "finding": null,
        "owner": "CS_JIRA_USER_MAP"
        }
  3. Set the value of the corresponding property to null.

    For example, to disable mapping of the CodeSonar warning Priority property to Jira, set cs_warning_fields.priority to null:

        "cs_warning_fields": {
        "priority": null,
        "state": "SIMPLIFIED_WORKFLOW_STATUS_MAP",
        "finding": null,
        "owner": "CS_JIRA_USER_MAP"
        }

Disable mappings for an individual issue type on an individual project for your Jira service

  1. Identify the following information.
  2. If you haven't already done so, open your configuration file hubdir/processors/jira_cloud.settings.json for editing.
  3. Create a projects property under jira_services.service_location, then create jira_services.service_location.projects.project_key and jira_services.service_location.projects.project_key.issue_types.

    For example, suppose that your service location is your-service-name.atlassian.net and the project key of interest is ABC. Then you will add the following.

        "jira_services": {
        "your-service-name.atlassian.net": {
            ...
            "projects": {
                "ABC": {
                    "issue_types": {}
                }
            }
            ...
  4. For each issue type for which you wish to disable mappings, do the following.
    1. Under jira_services.service_location.projects.project_key.issue_types, create a property whose name matches the issue type name.
    2. Insert a cs_warning_fields property into the issue type property you just created. For each CodeSonar warning property whose mapping to Jira should be disabled, set the corresponding cs_warning_fields sub-property to null.

    For example, to disable mapping CodeSonar warning Priority to Jira "Task" issues on the ABC project only, retaining default settings for all other issues and projects:

        "jira_services": {
        "your-service-name.atlassian.net": {
            "cs_warning_fields": {
                "priority": "HIGH_MED_LOW_PRIORITY_MAP",
                "state": "SIMPLIFIED_WORKFLOW_STATUS_MAP",
                "finding": null,
                "owner": "CS_JIRA_USER_MAP"
            },
            "projects": {
                "ABC": {
                    "issue_types": {
                        "Task": {
                            "cs_warning_fields": {
                                "priority": null,
                                "state": "SIMPLIFIED_WORKFLOW_STATUS_MAP",
                                "finding": null,
                                "owner": "CS_JIRA_USER_MAP"
                            }
                        }
                    }
                }
            }
            ...
 

To report problems with this documentation, please visit https://support.codesecure.com/.