TeamForge—JIRA Integration Using the Webhooks-based Event Broker

JIRA Version Information

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

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

This method of integration is based on the new TeamForge-JIRA integration plugin 1.0 and is recommended for on-premises installation of JIRA. The TeamForge-JIRA integration via TeamForge Webhooks-based Event Broker brings associations and traceability to JIRA. Traceability is therefore possible 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 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 question. 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.0 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.0 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 a TeamForge URL, Webhook URL, and a set of credentials each for TeamForge and Webhooks for each JIRA project. Note that once configured with the aforementioned URLs and credentials, the JIRA integration plugin will create and manage the needed sources.

Install the JIRA Integration Plugin

Use the TeamForge-JIRA plugin 1.0 to notify TeamForge of updates to JIRA issues and to vizualize the associations between JIRA and other tools. The TeamForge-JIRA plugin 1.0 must be installed once on each JIRA server you wish to connect to TeamForge. Install the TeamForge-JIRA plugin 1.0 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 > Add-ons > 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 > Add-ons > Manage apps).

Configure the JIRA Integration Plugin

1. Configure the add-on from the Project settings page to notify TeamForge about the work item activities.
   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 Username and Password fields.

      Note: The user whose credentials are provided must have API permissions in TeamForge, or the user should be a Project Admin.

   6. Enter the Webhook URL to which the JIRA work item activities are notified, Webhook Username, and Webhook Password in the respective fields.

      Note: You can obtain TeamForge Webhook URL by running the create_webhook_event.py script.
      Note: The user whose credentials are provided must have API permissions in TeamForge Webhooks-based Event Broker application, or the user should be a Project Admin.

   7. Click Test Configuration.

      Note: Only TeamForge related settings (TeamForge URL, Username, and Password) are validated while testing the configuration. Not applicable to Webhooks configuration.

      

   8. Click Save to save the configuration.

      

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

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 question.

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

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 > Add-ons.

   

3. Select TeamForge Associations > Manage.

   

4. Select one or more projects from the list to remove the TeamForge-JIRA mapping.
   Tip: You can select the Select All check box to select all the projects.
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.0 to notify TeamForge, you must migrate the JIRA data from EventQ’s MongoDB database to TeamForge database, after upgrading to 19.2.

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.
   Note: The migration script will be successful only if MongoDB is installed on the same machine from which the script is executed.

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`>
     

Related Links

• TeamForge Webhooks-based Event Broker Overview
• Install the TeamForge Webhooks-based Event Broker
• TeamForge-Jenkins Integration Using TeamForge Webhooks-based Event Broker
• TeamForge-TestLink Integration Using TeamForge Webhooks-based Event Broker