JIRA Integration

Applies to Collaborator 13.0, last modified on December 21, 2021

This topic describes how to setup Collaborator integration with JIRA issue-tracking system. To learn general principles of how any issue-tracking integration operates, see Issue-Tracking Integrations: Overview.

Configure Collaborator server

  1. Open the Collaborator login page in a browser and log in to Collaborator as an administrator.

  2. In Collaborator, go to ADMIN > Remote System Integrations > Issue-Tracking Services

  3. In the New Remote System Configuration section, select JIRA and click Create. This will display the configuration settings.

  4. Specify the setting values:

    Setting

    Description

    Title

    The configuration name as it will be displayed in Collaborator user interface.

    Server URI

    The JIRA server's URL and port.

    For instance: https://jira.acme.com

    JIRA user

    The user name that Collaborator will use for connecting to JIRA.

    The specified user must have read-write permissions to JIRA projects. Administrator permissions are NOT required. You may specify a regular user, or create a dedicated user for this integration.

    API token

    The API token or password to use for connecting to JIRA.

    For JIRA Cloud (SaaS) instances you need to specify API token. To generate token, log in to https://id.atlassian.com/manage/api-tokens, click Create API token, specify token caption and click Create.

    See Atlassian documentation for detailed information about API tokens.

    For JIRA Server (on-prem) instances you need to specify password.

    After specifying these values, you can click Test Connection to verify if you entered data correctly.

    Setting

    Description

    Project list

    A string containing the keys of JIRA projects to integrate with.

    Tip: Click Load Projects to read project keys from the JIRA instance specified by the Server URI setting.

    Project keys are case-insensitive. The Project List field can contain up to 2000 characters.

  5. After you specified the values, click Save. This will create and enable JIRA integration.

  6. Switch to the ADMIN > Remote System Integrations page. The Integration Status section allows you to quickly enable or disable integrations with remote systems.

  7. Locate the Enable JIRA Integration setting and verify that it is set to Yes.

  8. Once the JIRA configuration is enabled, automatic linking for the specified remote systems will be enabled in all active templates. However, Collaborator administrators may enable or disable linking per each template through its Automatically Add Remote System Links setting.
    Besides that, administrators can enable the ability to export review defects to the selected issue-tracking system. To enable defect export, go to the Review Templates screen, edit the appropriate template, change the Automatically Create New Work Item for External Defects setting for that specific system field to "Enabled" and select which project will be pre-selected in the dialog that suggests creating a ticket/work item.

Configure JIRA server

To display review information on the JIRA side you need to install Collaborator plug-in on your JIRA instance and configure your projects to use that plug-in.

Install plug-in

The plug-in works with both JIRA Cloud (SaaS) and JIRA Server (on-prem) instances of JIRA.

  1. Log into your JIRA instance as an administrator.
  2. Click the admin drop-down and choose Apps.
  3. Go to the Manage apps section and click Settings.
  4. In the following dialog, turn on the Enable development mode option and click Apply.
    Enabling development mode

    Click the image to enlarge it.

    This will allow to upload and install custom apps.

  5. Click Upload app.
  6. In the following dialog, specify https://collab-jira.smartbear.com in the From this URL field.
  7. Click Upload to upload and install the plug-in.
    Installing plug-in on JIRA cloud

    Click the image to enlarge it.

Once installed, the plug-in on will appear on the Manage apps page of the JIRA administration console.

  1. Visit the Collaborator JIRA Plug-in download page and get the most recent version of server plug-in.
  2. Log into your JIRA instance as an administrator.
  3. Click the admin drop-down and choose Manage apps.
  4. Go to the Manage apps section and click Upload app.
  5. In the following dialog, click Browse and specify path to the downloaded plug-in .jar file.
  6. Click Upload to upload and install the plug-in.
    Installing plug-in on JIRA server

    Click the image to enlarge it.

Once installed, the plug-in on will appear on the Manage apps page of the JIRA administration console.

Configure JIRA Projects

Now you need to configure your JIRA projects to display information about Collaborator reviews using the new plug-in.

For each project that should integrate with Collaborator, perform the following steps:

  1. Log into your JIRA instance as an administrator.
  2. Select the desired project in the Projects drop-down list.
  3. Click Project settings and scroll to the Collaborator Integration section.
  4. Specify the URL of your Collaborator server and credentials to use for connection:
    Plug-in settings

    Click the image to enlarge it.

  5. Enable or disable the Show reviews to everyone option to control whether review information could be available to users that are not participants of that review:

    • If disabled (default), the Collaborator panel will contain links and statuses to all linked reviews, however detailed review information would be displayed respecting the Restrict Access to Review setting.
    • If enabled, the Collaborator panel will contain links and statuses to all linked reviews. This list will be visible to any JIRA user and would contain the following information: link to the review on Collaborator server, current status, list of participants and their roles.

  6. Click Save.

Establish trusted connection

When your on-premises JIRA Server use SSL connection, its certificates may not be trusted by Collaborator server. In this case you will need to import that certificate as trusted.

To establish trust, you need to import the public key of your on-premises server as a trusted certificate to Collaborator keystore file:

  1. Get the certificate file from your on-premises JIRA server or network administrator.

  2. Locate the keystore file which you have generated while configuring Collaborator HTTPS connection.

    Default location is <Collaborator Server>/tomcat/conf/collab.ks, yet that could be changed while generating keystore.

  3. Use Java’s keytool utility to import the server's certificate to Collaborator keystore file. You can find the keytool utility in the $JAVA_HOME/bin directory:

    $JAVA_HOME/bin/keytool -importcert -alias jira-server -keystore <collab-keystore-path> -trustcacerts -file <certificate-path>

    For more information on command-line arguments of the keytool utility, see keytool documentation.

  4. Most likely you will be prompted to confirm the validity of the certificate. It is imperative for the security of the overall system that you verify the key matches the trusted material. Before accepting the certificate, you should contact the administrator that sent you the certificates and verify that the certificate fingerprints that you see match the certificate fingerprints that they intended to send you.

  5. The final step is to configure Collaborator to use the keystore. Open the <Collaborator Server>/ccollab-server.vmoptions file in a text editor, and add the following lines to it:

    -Djavax.net.ssl.trustStore=<collab-keystore-path>

    -Djavax.net.ssl.trustStorePassword=<collab-keystore-password>

  6. Restart the Collaborator server.

Now the integration between Collaborator and JIRA is configured and running.

See Also

Configure Issue-Tracking Integrations

Highlight search results