TeamForge Webhooks-based Event Broker supports TeamForge-JIRA integration. A new JIRA integration plugin version 1.1 is used to integrate TeamForge with JIRA using the TeamForge Webhooks-based Event Broker.
Before You Begin

Before you begin with the installation and the configuration of the TeamForge—JIRA integration plugin, generate the TeamForge Webhook URL using the create_webhook_event.py script.

JIRA Version Information

The following table provides the supported JIRA product versions and the version of the new TeamForge-JIRA integration plugin.

Supported JIRA VersionsCompatible Plugin
JIRA 7.0–8.4.2TeamForge-JIRA-adapter-1.1

Configure the JIRA Integration Plugin to Notify the TeamForge Webhooks-based Event Broker

This method of integration is based on the new TeamForge-JIRA integration plugin version 1.1 and is recommended for on-premises installation of JIRA. The TeamForge-JIRA integration via TeamForge Webhooks-based Event Broker brings associations and traceability between JIRA, TeamForge, and various tools supported by TeamForge Webhooks-based Event Broker.

Within JIRA, all the SCM related activities for the particular JIRA issue are tracked and displayed under the TeamForge tab on the JIRA issue page.

The TeamForge tab provides a summary of associations and also the details of a full listing of associations. This is a listing of immediate associations, activities with direct relationships to the JIRA issue at hand. To explore the chain of associations, click the Trace button. The traceability chain that includes commits, builds, reviews, deploys, and other XDS-based integration is displayed. On the Trace Associations page, clicking any node lights up all the association paths to that node. In addition, a small pop-up appears with details about the node in context. You can use SET AS TARGET button to expand the associations from the selected point. Another function exists to SEE more details about the node, opening a new browser tab.

The TeamForge-JIRA plugin 1.1 is packaged as a JIRA “add-on”. Once installed and configured, the add-on supplies issue tracker “work item” metadata to TeamForge. The TeamForge-JIRA plugin 1.1 needs configuration on a per project basis in JIRA, such that JIRA (many) to TeamForge (one) project mappings are established. It is therefore required to configure the TeamForge URL and the TeamForge credentials for each JIRA project. Once this configuration is done, the JIRA integration plugin will create and manage the needed sources.

Install the JIRA Integration Plugin

Use the TeamForge-JIRA plugin 1.1 to notify TeamForge of updates to JIRA issues and to vizualize the associations between JIRA and other tools. The TeamForge-JIRA plugin 1.1 must be installed once on each JIRA server you wish to connect to TeamForge. Install the TeamForge-JIRA plugin 1.1 using the JIRA add-on Manager. Refer to the Atlassian Marketplace for supported versions.

Install the TeamForge-JIRA Associations Add-on

  1. As a privileged JIRA user, navigate to Administration > Manage apps > Find new apps.
  2. Search the marketplace for the TeamForge Associations add-on for JIRA. Type ‘TeamForge Associations’ and search.
  3. Click Install.

Upgrade the TeamForge-JIRA Associations Add-on

New versions of the TeamForge-JIRA associations add-on will be visible in the Manage apps section (Administration > Manage apps > Manage apps).

Configure the JIRA Integration Plugin

Configure “TeamForge Associations” to notify TeamForge Webhooks-based Event Broker about JIRA issues.

  1. Configure the add-on from the Project settings page to notify TeamForge about the JIRA issues.
    1. Select Projects from JIRA Administration menu.
    2. Select your project from the list of projects on the Administration page.
    3. Select TeamForge on the Project settings page.

    4. Enter TeamForge URL in the TeamForge URL field.

    5. Enter valid TeamForge login credentials in the Username and Password fields.

    6. Enter the Webhook URL in the Webhook URL field.

    7. Click Save to save the configuration.

      Once the configuration is saved, JIRA issues are pushed to the configured Webhook URL.

Sync Existing JIRA Issues into TeamForge

To associate TeamForge objects to existing JIRA issues, click Sync Issues.

This step bootstraps JIRA issue data from the current project into the TeamForge. Note that this process may take several minutes (even hours) to complete, depending on the number of issues in the JIRA project.


Edit TeamForge-JIRA Mapping Configuration

Click Edit to modify current configuration, if required.


Delete Configured TeamForge Mapping from JIRA Project

Click Delete if you wish to completely dissociate the JIRA project from the configured TeamForge mapping.

Associate JIRA Issues to Version Control Commits

Associations between JIRA® issues and TeamForge-aware version control commits can be created via commit message references. Commits to TeamForge project repositories and external repositories that have been configured in TeamForge are also supported.

Creating Associations

  1. Using your desired terminal or IDE, instantiate a version control commit to a repository of your choice.
  2. In the commit message, make reference to JIRA ID(s) to which you wish to associate the commit surrounded by square brackets.

    Sample Commit Messages
    “[DEMO-123] This commit message will result in an association between
    JIRA issue DEMO-123 and this commit.”
    
    “[DEMO-123, DEMO-124] Here I’m associating two JIRA issues with project
    identifiers DEMO.” 
    

Viewing Associations inside JIRA

  1. Navigate to the desired JIRA issue details page.
  2. Click the TeamForge tab.
  3. A list of immediate associations appears. In other words, these objects are directly associated to the JIRA issue in context.
  4. Click Trace to view the first three levels of the traceability chain.

    All activities are mapped chronologically.
    Lines indicate direct associations.
    Use the “+” icon to explore further levels of traceability.

Remove TeamForge Mappings

As a JIRA site administrator, you can disable active TeamForge mappings for one or more or all the JIRA projects (Administration > Manage apps > TeamForge Associations), if you want to prevent a JIRA server that’s mirrored into a staging/testing environment from triggering events back to TeamForge (when there are changes to issues in JIRA projects that are mapped to TeamForge) thereby polluting the production TeamForge event data store.

Use this feature to disable all production JIRA-TeamForge mappings in stage environments and then test the TeamForge Associations add-on by creating a new mapping between a staging JIRA server and TeamForge server.

  1. Log on to the JIRA server as a site administrator.
  2. Select JIRA Administration > Manage apps.
  3. Select TeamForge Associations > Manage.
  4. Select one or more projects from the list to remove the TeamForge-JIRA mapping.
  5. Click Remove. A confirmation message is displayed.
  6. Click Remove to delete the mapping.

Migrate Existing JIRA Data from EventQ to TeamForge

If you configure the new JIRA integration plugin 1.1 to notify TeamForge, you must migrate the JIRA data from EventQ’s MongoDB database to TeamForge database, after upgrading to 19.3.

To migrate the JIRA data from EventQ’s MongoDB to TeamForge database:

This migration process is two-fold:

  1. Extract the existing JIRA data from EventQ’s MongoDB database and generate an SQL file based on the database option chosen.
  2. Execute the generated SQL file on the TeamForge database (Postgres/Oracle).

Extract JIRA Data from EventQ MongoDB

  1. Download the JIRA plugin jira-1.0.jar.

  2. Run this command to execute the migration script.

    java -jar jira-1.0.jar -migrate
    
  3. Enter the MongoDB hostname as localhost or just press ENTER for localhost to be taken as default host name.
  4. Enter the MongoDB port number or just press ENTER for 27017 to be taken as default port number.

  5. Enter the MongoDB database name for EventQ.

  6. Enter the MongoDB username and password.

  7. For Does TeamForge use Oracle Database [y/n]:, press y if you use Oracle. Press n if you use PostgreSQL.

    The migration script is executed and generates the jira_data_migration.sql file.

Execute the SQL File on PostgreSQL/Oracle Database

  • To execute the SQL file on PostgreSQL database:

    1. Log on to your TeamForge Server.

    2. Run this command to import the migrated data.

      sudo /opt/collabnet/teamforge/runtime/scripts/psql-wrapper <filepath of `jira_data_migration.sql`> 
      

      OR

      cat <filepath of `jira_data_migration.sql`> | sudo /opt/collabnet/teamforge/runtime/scripts/psql-wrapper 
      
  • To execute the SQL file on Oracle Database:

    1. Log on to your Oracle database.

    2. Run this command to import the migrated data.

      @<filepath of `jira_data_migration.sql`>