TeamForge EventQ integrates with different flavors of work item, SCM/commit, build, and review servers using adapters.

EventQ Adapters

TeamForge EventQ collects metadata about key lifecycle activities from external sources like work item trackers, SCM repositories, CI/build servers, and code review systems. To do so, TeamForge EventQ relies on adapters to collect the metadata from sources. TeamForge EventQ packages the following adapters:

Type of Service Product Description
SCM/Version Control Git, Subversion
Builds/CI server Jenkins
Code Review ReviewBoard, Atlassian Crucible
Work Item/Issue Tracker CollabNet TeamForge, Atlassian JIRA

Source Association Keys

TeamForge EventQ uses source association keys to uniquely identify incoming data from activity sources that it monitors.

Adapters supply data to TeamForge EventQ through the message queue (MQ) layer. When a relevant activity occurs in source systems, TeamForge EventQ adapters generate a message with key metadata about the activity and place that message on the designated MQ server. When TeamForge EventQ receives the message, it must associate it to the proper source somehow. To do this, TeamForge EventQ supplies a unique “source association key” for each external source created. Adapters must supply this unique source association key with each message for the data to correlate with the appropriate project source.

Note that commit sources based on TeamForge project repositories do not need source associations keys since they are internal and are identified by other means. All other sources require source association keys.

Locate a Source Association Key

Source association key for existing activity sources are located on the corresponding source configuration page.

  1. From the activity stream, click Manage Sources.
  2. Select the desired source type toggle. TeamForge EventQ displays all existing sources.
  3. Click Edit on the source whose key you wish to obtain. You see the configuration page for the selected source.
  4. Locate the source association key for the selected source. On most browsers you can copy the key by clicking the small clipboard icon.

JIRA Integration

The TeamForge EventQ JIRA integration enhances further the extensible toolchain model of TeamForge by offering association and traceability between JIRA, TeamForge, and various orchestrated third-party tools. The TeamForge EventQ JIRA adapter enables JIRA as an alternative tracker for use with TeamForge by detecting and storing associations between JIRA issues and TeamForge managed SCM activities, like commits, builds and so on.

JIRA Version Information

The following table lists the compatible JIRA and TeamForge Associations Add-on versions. You can integrate TeamForge with JIRA using either the TeamForge-JIRA Associations Add-on or Webhooks.

ProductVersion(s) SupportedIntegrations Supported
JIRA Software6.3 - 6.4.14TeamForge Associations Add-on 2.11-6, Webhooks
7.0 - 7.4.4TeamForge Associations Add-on 2.11-7, Webhooks
JIRA Software Data Center 6.3 - 6.4.14TeamForge Associations Add-on 2.11-6, Webhooks
7.0 - 7.4.4TeamForge Associations Add-on 2.11-7, Webhooks
JIRA Core6.3 - 6.4.14TeamForge Associations Add-on 2.11-6, Webhooks
7.0 - 7.4.4TeamForge Associations Add-on 2.11-7, Webhooks

Integrate TeamForge and JIRA Using the Associations Add-on

This method of integration is based on TeamForge-JIRA associations add-on and is recommended for on-premises installation of JIRA. The TeamForge EventQ JIRA integration brings associations and traceability to JIRA. The TeamForge EventQ JIRA adapter enables JIRA as an alternative tracker for use with TeamForge by detecting and storing associations between JIRA issues and TeamForge managed SCM activities, like commits. Traceability is therefore possible between JIRA, TeamForge, and various EventQ-based third-party tools.

Inside TeamForge, JIRA issues are visible in activity streams and association visualizations. 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 EventQ JIRA adapter is packaged as a JIRA “add-on”. Once installed and configured, the add-on supplies issue tracker “work item” metadata to TeamForge EventQ. The JIRA adapter 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 project URL and a set of TeamForge credentials for each JIRA project. Note that once configured with the aforementioned URL and credentials, the JIRA adapter will create and manage the needed sources and source associations keys. For more about source association keys, see Source Association Keys.

Install a JIRA Adapter

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

Configure a JIRA Adapter

Configure “TeamForge Associations” to notify TeamForge EventQ about work item activities.

Before you start configuration, make sure that you have installed the TeamForge Associations add-on: verify that TeamForge Associations is present in the User-installed Add-ons list.

  1. Configure the add-on from the Project Administration page to notify TeamForge-EventQ about the work item activities.
    1. Navigate to Administration > TeamForge.

      The TeamForge Setup page appears.

    2. Find the TeamForge project to associate with and enter its URL in the Project Home URL field. Obtain the TeamForge Project Home URL by navigating to the target TeamForge project and clicking Project Home. Copy the URL from the browser.
    3. Using your valid TeamForge login credentials, click Test Configuration. The user whose credentials are supplied must have API permissions in both TeamForge and EventQ, or should be a Project Admin.
    4. Click Save to save the configuration. When you save your configuration, for each issue type in the JIRA project a corresponding source is created in the TeamForge EventQ.

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 EventQ data store. Note that this process may take several minutes (even hours) to complete, depending on the number of issues in the JIRA project.

Test or Modify Configuration

  1. Test the current configuration by clicking Test Configuration. The system indicates whether the supplied URL and credentials work properly.
  2. To modify the supplied credentials, click Edit Credentials.
    1. Modify either the Username or Password fields.
    2. Click Test Configuration to verify your settings.
    3. Click Save once testing is satisfactory.
  3. To modify the TeamForge project mapping, click Modify Project Mapping.
    1. Modify the ProjectHome URL field to reflect the desired TeamForge project.
    2. If required, update the credentials to match the TeamForge project.
    3. Click Test Configuration to verify that the supplied user had adequate permissions in the selected TeamForge project.
    4. Click Save Mapping once testing is satisfactory.

Delete Project Mapping Configuration

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

Integrate TeamForge and JIRA Using WebHooks

The TeamForge Integration for JIRA® Webhooks collects issue data from your JIRA Serve or JIRA Cloud for purposes of associations, traceability, and event reporting.

This integration relies on JIRA’s webhooks mechanism to send issue data to TeamForge EventQ for purposes of associations, traceability, and event reporting. Being webhooks-based, there is no adapter or software to install; simply configure TeamForge and JIRA webhooks to communicate with each other and start creating associations, traceability, and events reports based on JIRA data within TeamForge. With no adapter to install, TeamForge Webhooks Integration for JIRA is ideal for use with JIRA Cloud.

Viewing Associations and Traceability

Because there’s no need to install plugins, there is no mechanism to visualize associations between TeamForge objects and JIRA issues from within JIRA. To visualize associations, please use the Source Code tool in TeamForge.

Prerequisites

This integration is subject to limitations imposed by JIRA Webhooks and JIRA Cloud. See Atlassian® Documentation for specifications. In particular:

  • TeamForge HTTP or HTTPS access must be configured on ports 80 or 443 respectively. JIRA Cloud does not support alternate port configurations for webhooks.
  • If using HTTPS, TeamForge must be configured with a valid SSL certificate signed by a certificate authority to be an eligible JIRA Cloud hooks consumer. Self-signed certificates are not supported by JIRA Cloud. This is a limitation JIRA Cloud imposes on webhooks consumers.
  • TeamForge Integration for JIRA Webhooks is a point-to-point integration, therefore the following ports must be configured for access:
    PortFromToDescription
    443/80JIRA web serverTeamForge web server JIRA sends webhooks payload to TeamForge

Configuring the JIRA Cloud WebHooks

This integration documentation walks you through the creation of one or more webhooks triggers in JIRA. Each webhook should be scoped to a specific JIRA project issue type. It is therefore required that a separate webhook be set up for each issue type you wish to collect data from for purposes of associations and event reporting.

  1. In TeamForge, navigate to the Project that houses the source code repositories you wish to associate to the JIRA issues in question.
  2. Select Project Home > Project Admin > Tools and click Add Tool.
  3. Select JIRA Cloud from the Select Tool Type drop-down list.
  4. Type the Display Name. The Display Name is used to differentiate your JIRA projects/instances associated to this TeamForge project.
  5. Select the Include Traceability check box.
  6. Type the Source Name. This value differentiates the sources you define for this JIRA Project/instance. It is recommended that you name your new source to match the Issue Type in JIRA you’re configuring currently.
  7. Click Generate Webhook. You will be presented with a unique Webhook URL. This URL should only be used once, as it maps to a specific Project and Issue Type in JIRA.
  8. Copy the entire Webhook URL and retain it for future steps.
  9. Click Save to finish adding your tool (the new JIRA project/instance).
  10. In JIRA, as a privileged user navigate to System Administration > Webhooks.
  11. Click Create a Webhook and give it a descriptive name and toggle “Status” to Enabled.
  12. Paste the Webhook URL into URL field.
  13. Under the Events section, check the following issue events: created, updated, deleted.
  14. Under the Events section, input JQL to narrow the events triggering webhooks payloads to TeamForge as follows:
    • Supply a Project by entering: project = [select project name].
    • Supply an issue type by entering: and issuetype = [select issue type].

      A green tick mark indicates you’ve properly configured the webhook.

  15. Click Save. Webhook configuration is now complete for the issue type in question. You should see the newly configured webhook in the listing within the JIRA System Administration > Webhooks page.
  16. To verify the configuration, create a new issue matching the issue type in question and you should see a new representative activity in the EventQ Activity Stream. It is recommended that you house all issue types relating to a single JIRA project under the same “Tool” in TeamForge, creating a separate “source” for each issue type.
    1. Navigate to the newly created JIRA Cloud Tool in TeamForge: Project Admin > Tools > [Click the tool created in the steps above].
    2. Click Data source + to create a second source to house the second JIRA issue type.
    3. Continue with the steps as above.
  17. Repeat the above steps for each desired issue type.

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 as EventQ sources are also supported.

Creating Associations

  1. Using your desired terminal or IDE, instantiate a version control commit to your repository of choice.
  2. In the commit message, make reference to JIRA ID(s) to which you wish to associate the commit surrounded by square brackets.,br>
    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 Project Mappings

As a JIRA site administrator, you can disable active JIRA-TeamForge project mappings for one or more or all the projects (Administration > Add-ons > 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 > Add-ons.
  3. Select TeamForge Associations > Manage.
  4. Select one or more projects from the list to remove the project mapping.
  5. Click Remove. A confirmation message is displayed.
  6. Click Remove to delete the mapping.

Jenkins Integration

The TeamForge EventQ Jenkins adapter supplies build data from your Jenkins continuous integration server to TeamForge EventQ for purposes of metadata archival, traceability and event reporting.

The TeamForge EventQ Jenkins integration brings associations and traceability to Jenkins. The adapter displays associations between Jenkins builds and other tools within the TeamForge landscape like version control commits and binary artifacts. Traceability is therefore possible between Jenkins build, TeamForge, and various orchestrated third-party tools.

Inside TeamForge, Jenkins build details are visible in activity streams and association visualizations. Within Jenkins, associations are visible from the TeamForge Associations tab.

Clicking Trace provides a view of the build in the context of other associated activities. Use cases include root cause analysis and auditable traceability.

The TeamForge EventQ Jenkins adapter is packaged as a Jenkins plug-in. Once installed and configured, the plug-in supplies build results metadata for configured Jenkins jobs to TeamForge EventQ.

Jenkins Version Information

The following table lists the compatible Jenkins and TeamForge-Jenkins Plugin versions.

ProductVersion(s) SupportedIntegrations Supported
Jenkins (Job and Pipeline)1.645 and latercollabnet.hpi 2.0.4

Install a Jenkins Adapter

A new CollabNet Plugin for Jenkins (v2.0) is available that functionally subsumes both CollabNet Plugin v1.2.0 and EventQ Jenkins Adapter v2.0. Install this plugin using the web interface. Existing TeamForge-Jenkins integrations that use either CollabNet Plugin v1.2.0 (or earlier), or EventQ Jenkins Adapter v2.0 (or earlier), or both, must be migrated (uisng the migrate_jenkins_plugin.sh script) after installing the new CollabNet plugin.

CollabNet Plugin Features

  • Notify TeamForge EventQ when builds complete. The CollabNet Plugin must be installed once on each Jenkins server you wish to connect to TeamForge EventQ.
  • Authenticate users from TeamForge. If setup as the “Build & Test” appplication, it can even use Single Sign-On.
  • Authorization from TeamForge, including the ability to set permissions in Jenkins based on roles in your TeamForge project.
  • Upload the build log or workspace artifacts to the TeamForge Documents.
  • Upload workspace artifacts to the TeamForge File Release System, as a post-build publishing task or as a build promotion task.
  • Open/update/close TeamForge Tracker artifacts based on the Jenkins build status.
  • Upload workspace artifacts to the Lab Management Project Build Library. (Requires CollabNet Lab Management).

    Click here to know more about the requirements for installing the latest CollabNet plugin.

  1. If you are integrating TeamForge and Jenkins for the first time:
    1. Log on to the Jenkins Server as a previliged Jenkins user, navigate to Manage Jenkins > Manage Plugins > Available.
    2. Select the latest CollabNet Pluginand install the plugin.
    3. Restart your Jenkins server.
  2. Existing TeamForge-Jenkins integrations that use CollabNet Plugin v1.2.0 (or earlier):
    1. Log on to the Jenkins Server as a privileged Jenkins user, navigate to Manage Jenkins > Manage Plugins > Updates.
    2. Select the latest CollabNet Plugin and install the plugin.
    3. Download the migrate_jenkins_plugin.sh script and save it to <JENKINS_HOME_DIRECTORY>/jobs/.
    4. Change ownership of the migrate_jenkins_plugin.sh file.
      chmod 755 migrate_jenkins_plugin.sh
      
    5. Run the migrate_jenkins_plugin.sh script.
      ./migrate_jenkins_plugin.sh
      
  3. Existing TeamForge-Jenkins integrations that use either EventQ Jenkins Adapter v2.0 (or earlier) or both CollabNet Plugin v1.2.0 (or earlier) and EventQ Jenkins Adapter v2.0 plugins:
    1. Log on to the Jenkins Server as a privileged Jenkins users, navigate to Manage Jenkins > Manage Plugins > Installed.
    2. Select the EventQ Jenkins Adapter v2.0 and click Uninstall.
    3. If you have CollabNet Plugin v1.2.0 (or earlier) installed already, select the Updates tab. Select the Available tab otherwise.
    4. Select the latest CollabNet Plugin and install the plugin.
    5. Download the migrate_jenkins_plugin.sh script and save it to <JENKINS_HOME_DIRECTORY>/jobs/.
    6. Change ownership of the migrate_jenkins_plugin.sh file.
      chmod 755 migrate_jenkins_plugin.sh
      
    7. Run the migrate_jenkins_plugin.sh script.
      ./migrate_jenkins_plugin.sh
      

Configure a Jenkins Adapter

Configure the Jenkins adapter to notify TeamForge EventQ when builds complete.

Before you start the configuration, make sure that you have installed the Jenkins plug-in using the web interface. The TeamForge EventQ Jenkins adapter has a system configuration as well as job level configurations. The system configuration sets defaults to be used by subsequently configured job level configurations.

Configuring an Individual Jenkins Job

  1. Create a build source and have the configuration details handy for the following steps.
  2. As a privileged Jenkins user, locate the job you wish to report build data to TeamForge EventQ and navigate to its configuration page.
  3. Add a post-build action to Notify TeamForge EventQ when a build completes.
  4. Using the values you obtained in Step 1, copy and paste the Queue Server value into the Server URL field.
  5. Fill in the Server Username and Server Password fields. Copy and paste the queue username and password values from the values obtained in Step 1.
  6. Populate the Build source association key field with the value obtained in Step 1. For more information about association keys, see Source Association Keys.
  7. By default, the Optional TeamForge Association View check box is selected. If required, you can override the global configuration. Select the Override the Global CollabNet Configuration check box and type the TeamForge URL and user credentials.
  8. Save the job configuration.
  9. Run a build to test the new configuration and verify configuration. Information and errors will be reported to your Jenkins log and to the build console.

Configuring the Default Jenkins Global Settings

Now that you’ve set up your first job level configuration, you can save some effort next time around by defining system values for the Server URL, Server Username and Server Password. Note that each job needs a unique Source Association Key, so that will still need to be configured per job.

  1. Refer to Step 1 and obtain values for the Server URL, Server Username and Server Password.
  2. As a privileged Jenkins user, navigate to Manage Jenkins > Configure System page on the target Jenkins server.
  3. On the Jenkins configuration page, find the TeamForge EventQ section.
    1. Fill in the Server URL field. Copy and paste the Queue Server value into the Server URL field in Jenkins.
    2. Fill in the Server Username and Server Password fields.
  4. Save the configuration.

External Git Repository Integration

With a customized post-receive extension (hook) installed, Git servers external to TeamForge can notify TeamForge EventQ of Git “push” activity.

TeamForge project Git repositories are already wired to supply push activity data to TeamForge EventQ; no special configuration needed. This section instead details integration of Git repositories external to TeamForge.

The TeamForge EventQ Git adapter is packaged as a Git post-receive hook script. Once installed and configured, the hook script supplies push metadata for the selected repository to TeamForge EventQ. The push data is associated to the proper source using source association keys (see Source Association Keys). Configuration therefore requires that the message queue server URL and credentials be supplied, along with the appropriate source association key.

Install a Git Adapter

Install a Git adapter as a post-receive hook on Mac OS X/Linux.

Minimum Requirements:

  • Git 1.8.3.1 or later.
  • Python 2.6. Python v3.0 and later are not compatible.

Each external Git repository you wish to monitor with TeamForge EventQ requires the installation of a customized post-receive hook script as follows.

Install Git Post-receive Hooks

Contact the CollabNet Support to download the eventQ-git-adapter-[version].zip adapter file and unpack it inside your repository’s hooks directory.

For example, if your repository’s hooks directory is located at /path/to/repo.git/hooks, cd /path/to/repo.git/hooks, download the zip file to the current location, then unzip eventQ-git-adapter-1.0.zip.

This will unpack the following into your hooks directory:

  • Files: LICENSE.txt, README.txt, post_receive_orc_publish_amqp.conf.sample, post_receive_orc_publish_amqp.py
  • Directories: eventq/ and pika/

Configuration

  1. In a web browser, log into TeamForge EventQ as a privileged EventQ user and edit (or add) the relevant Commit source you wish to associate with this Git repository. Manage Sources > Toggle Commit > Add or Edit a Source > External repository
  2. On the Edit Source page, locate the section titled “Adapter Configuration Information” and copy all values; these values are used later in the configuration process.
  3. Switch back to your command line console and copy post_receive_orc_publish_amqp.conf.sample to post_receive_orc_publish_amqp.conf.
  4. Edit post_receive_orc_publish_amqp.conf and modify options for your specific installation, for example:
    • Logging Section
      • filename — Full path to the desired log file, for example, /tmp/post-commit.log.
      • level — The logging level, which is one of these: debug , info, warning, error, or critical.
    • RabbitMQ (amqp) Section
      • host — The hostname of the amqp server. Copy and paste the hostname from the Queue Server value from the Edit Source page in TeamForge EventQ.
      • port — The port number of the amqp server (default is 5672). Copy and paste the port number the Queue Server value from the Edit Source page in TeamForge EventQ.
      • username — Username used to access the amqp server. Copy and paste the queue username value from the Edit Source page in TeamForge EventQ.
      • password — Password used to access the amqp server. Copy and paste the queue password value from the Edit Source page in TeamForge EventQ.
    • TeamForge EventQ Section
      • source_association_key — key provided by TeamForge EventQ. Copy and paste the source association key value from the Edit Source page in TeamForge EventQ. For more on association kys, see Source Association Keys.

Activate Post-receive Hook

Copy or create a symlink called “post-receive” linking to post_receive_orc_publish_amqp.py.

External Subversion Repository Integration

With a customized post-commit extension (hook) installed, Subversion servers external to TeamForge can notify TeamForge EventQ of Subversion commit activity.

TeamForge project Subversion repositories are already wired to supply commit activity data to TeamForge EventQ; no special configuration needed. This section instead details integration of Subversion repositories external to TeamForge.

The TeamForge EventQ Subversion adapter is packaged as a Subversion post-commit hook script. Once installed and configured, the hook script supplies commit metadata for the selected repository to TeamForge EventQ. The commit data is associated to the proper source using source association keys (see Source Association Keys). Configuration therefore requires that the message queue server URL and credentials be supplied, along with the appropriate source association key.

Install a Subversion Adapter on Mac OS X/Linux

Install a Subversion adapter as a post-commit hook on Mac OS X/Linux.

Minimum Requirements:

  • Subversion 1.7 or later.
  • Python 2.6. Python v3.0 and later are not compatible.

Each external Subversion repository you wish to monitor with TeamForge EventQ requires the installation of a customized post-commit hook script as follows.

Install Subversion Post-commit Hooks

Contact the CollabNet Support to download the eventQ-subversion-adapter-[version].zip adapter file and unpack it inside your repository’s hooks directory.

For example, if your repository’s hooks directory is located at /path/to/svn/repos/my_repo/hooks, cd /path/to/svn/repos/my_repo/hooks, download the zip file to the current location, then unzip eventQ-svn-adapter-1.0.zip.

This will unpack the following into your hooks directory:

  • LICENSE.txt
  • README.txt
  • configdefaults.py
  • configwrapper.py
  • eventq_commit_gate_hook.py
  • orchestrator_commit_gate_hook_snippet.sh
  • pika/
  • post-commit.bat.sample
  • post_commit_orc_publish_amqp.conf.sample
  • post_commit_orc_publish_amqp.py

Configuration

  1. In a web browser, log into TeamForge EventQ as a privileged EventQ user and edit (or add) the relevant Commit source you wish to associate with this Subversion repository. Manage Sources > Toggle Commit > Add or Edit a Source > External repository
  2. On the Edit Source page, locate the section titled “Adapter Configuration Information” and copy all values; these values are used later in the configuration process.
  3. Switch back to your command line console and copy post_commit_orc_publish_amqp.conf.sample to post_commit_orc_publish_amqp.conf.
  4. Edit post_commit_orc_publish_amqp.conf and modify options for your specific installation, for example:
    • Logging Section
      • filename — Full path to the desired log file, for example, /tmp/post-commit.log.
      • level — The logging level, which is one of these: debug , info, warning, error, or critical.
    • svnlook Section
      • svnlook — The path to your svnlook executable, for example, /usr/bin/svnlook or/opt/subversion/bin/svnlook.
    • RabbitMQ (amqp) Section
      • host — The hostname of the amqp server. Copy and paste the hostname from the Queue Server value from the Edit Source page in TeamForge EventQ.
      • port — The port number of the amqp server (default is 5672). Copy and paste the port number the Queue Server value from the Edit Source page in TeamForge EventQ.
      • username — Username used to access the amqp server. Copy and paste the queue username value from the Edit Source page in TeamForge EventQ.
      • password — Password used to access the amqp server. Copy and paste the queue password value from the Edit Source page in TeamForge EventQ.
    • TeamForge EventQ Section
      • source_association_key — key provided by TeamForge EventQ. Copy and paste the source association key value from the Edit Source page in TeamForge EventQ. For more on association kys, see Source Association Keys.

Activate Post-commit Hook

Copy or create a symlink called “post-commit” linking to post_commit_orc_publish_amqp.py.

Install a Subversion Adapter on Windows

Install a Subversion adapter as a post-commit hook on Windows.

Minimum Requirements:

  • Subversion 1.7 or later.
  • Python 2.6. Python v3.0 and later are not compatible.

Install Subversion Post-commit Hooks

Contact the CollabNet Support to download the eventQ-subversion-adapter-[version].zip adapter file and unpack it inside your repository’s hooks directory.

For example, if your repository’s hooks directory is located at C:\csvn\repositories\my_repo\hooks, cd C:\csvn\repositories\my_repo\hooks, download the zip file to the current location, then unzip eventQ-svn-adapter-1.0.zip.

This will unpack the following into your hooks directory:

  • LICENSE.txt
  • README.txt
  • configdefaults.py
  • configwrapper.py
  • eventq_commit_gate_hook.py
  • orchestrator_commit_gate_hook_snippet.sh
  • pika/
  • post-commit.bat.sample
  • post_commit_orc_publish_amqp.conf.sample
  • post_commit_orc_publish_amqp.py

Configuration

  1. In a web browser, log into TeamForge EventQ as a privileged EventQ user and edit (or add) the relevant Commit source you wish to associate with this Subversion repository. Manage Sources > Toggle Commit > Add or Edit a Source > External repository
  2. On the Edit Source page, locate the section titled “Adapter Configuration Information” and copy all values; these values are used later in the configuration process.
  3. Switch back to your command line console and copy post_commit_orc_publish_amqp.conf.sample to post_commit_orc_publish_amqp.conf.
  4. Edit post_commit_orc_publish_amqp.conf and modify options for your specific installation, for example:
    • Logging Section
      • filename — Full path to the desired log file, for example, C:\Temp\post-commit.log.
      • level — The logging level, which is one of these: debug , info, warning, error, or critical.
    • svnlook Section
      • svnlook — The path to your svnlook executable, for example, C:\csvn\bin\svnlook.exe.
    • RabbitMQ (amqp) Section
      • host — The hostname of the amqp server. Copy and paste the hostname from the Queue Server value from the Edit Source page in TeamForge EventQ.
      • port — The port number of the amqp server (default is 5672). Copy and paste the port number the Queue Server value from the Edit Source page in TeamForge EventQ.
      • username — Username used to access the amqp server. Copy and paste the queue username value from the Edit Source page in TeamForge EventQ.
      • password — Password used to access the amqp server. Copy and paste the queue password value from the Edit Source page in TeamForge EventQ.
    • TeamForge EventQ Section
      • source_association_key — key provided by TeamForge EventQ. Copy and paste the source association key value from the Edit Source page in TeamForge EventQ. For more on association kys, see Source Association Keys.

Activate Post-commit Hook

  1. Copy the post-commit.bat.sample to post-commit.bat.
  2. Edit the post-commit.bat for your specific installation: set PYTHON_EXE to the full path to python.exe executable. For CollabNet Subversion Edge, this is typically C:\csvn\Python25\python.exe.

Crucible Integration

The TeamForge EventQ Crucible adapter enables communication between your Crucible server and TeamForge EventQ.

The TeamForge EventQ Crucible adapter is packaged as a Crucible add-on. Once installed and configured, the add-on supplies code review metadata for selected Crucible projects to TeamForge EventQ. The code review metadata is associated to the proper source using source association keys (see Source Association Keys). Configuration therefore requires that the MQ server URL and credentials be supplied, along with the appropriate source association key.

The TeamForge EventQ-Crucible adapter v1.0 supports Crucible 3.0.1

Install a Crucible Adapter

Install the Crucible adapter using the Crucible Add-on Manager.

TeamForge EventQ currently supports Crucible 3.0.1. Use the Crucible adapter to notify TeamForge EventQ when reviews are created or modified, or when files are added or removed from reviews. The Crucible adapter must be installed once on each Crucible server you wish to connect to TeamForge EventQ. Install the add-on by using the Crucible add-on Manager.

  1. Contact the CollabNet Support to download the eventQ-Crucible-adapter-[version].jar Crucible plug-in file.
  2. As a privileged Crucible user, navigate to Administration > Manage Add-ons > Upload Add-on.
  3. In the From my computer field, select your eventQ-Crucible-adapter-[version].jar file, then click Upload. You are now returned to the Manage Add-ons view and the TeamForge EventQ Adapter now be visible under User-installed Add-ons.

Configure a Crucible Add-on

Configure the “TeamForge EventQ Adapter” add-on to notify TeamForge EventQ about review changes.

Before you start configuration, make sure that you have installed the Crucible add-on: verify that TeamForge EventQ Adapter is present in the User-installed Add-ons list.

  1. As a privileged EventQ user, edit (or add) the relevant Review Source you wish to associate with this Crucible project. Manage Sources > Toggle Review > Edit the Source
  2. On the Edit Source page, find the Adapter Configuration Information section and copy all values; these values are used later in the configuration process.
  3. As a privileged Crucible user, navigate to Administration > Manage Add-ons.
  4. Click TeamForge EventQ Adapter from the User-installed Add-ons list. The TeamForge EventQ Adapter section displays new options, including “Configure”.
  5. Click Configure. You see a configuration form for each of your projects.\
  6. Find the project to associate with TeamForge EventQ and enter the following information.
    1. Populate the Server URL field. Copy and paste the Queue Server value from the Edit Source page in TeamForge EventQ. Make sure you include the “amqp” protocol and the port information.
    2. Populate the Server Username and Server Password fields. Copy and paste the queue username and password value from the Edit Source page in TeamForge EventQ.
    3. Populate the Source Association Key field. Copy and paste the source association key value from the Edit Source page in TeamForge EventQ. For more on association keys, see Source Association Keys.
  7. Click Save. Crucible now reports code review events for the configured project to TeamForge EventQ.

Crucible Adapter FAQs

Review Board Integration

The TeamForge EventQ-Review Board adapter enables communication between your Review Board server and TeamForge EventQ.

The Review Board adapter is packaged as a Review Board extension, and once installed provides web-based configuration inside Review Board.

The adapter supplies code review metadata for selected repositories to TeamForge EventQ. Code review metadata is associated to the proper source using source association keys (see Source Association Keys). Configuration therefore requires that the MQ server URL and credentials be supplied, along with the appropriate source association key.

Install or Upgrade a Review Board Adapter on Mac OS X/Linux

Install a Review Board adapter as a Review Board extension to retrieve code review data from instances of Review Board 1.7 and later.

Minimum Requirements

  • Review Board 1.7 or higher
  • Python 2.6 or 2.7. Version 3.0 and later are not compatible.
  • setuptools 2.1 or later
  • pip 1.5 - 6.0.6 (6.0.7 has issues and is not supported)
  1. Upgrade pip. Upgrade pip if you do not have the minimum required version.
    sudo pip install --upgrade pip
    
  2. Upgrade setuptools. Upgrade setuptools if you do not have the minimum required version.
    sudo pip install --upgrade setuptools
    
  3. Install or upgrade the TeamForge EventQ-Review Board adapter as a Review Board extension.
    • Installation
      • If your server has internet access, use the command below to install the EventQ adapter as an extension.
        sudo pip install --use-wheel --no-index --find-links=http://eventq.collab.net/RHEL/6/x86_64/wheelhouse eventq_rb
        
      • If your server cannot access the internet, see Install a Review Board Adapter Without Internet Access instead.
    • Upgrade
      • Add the -U flag to upgrade to the latest version of the Review Board adapter.
        sudo pip install -U --use-wheel --no-index --find-links=http://eventq.collab.net/RHEL/6/x86_64/wheelhouse eventq_rb
        
  4. Restart Review Board’s web server to register the newly installed EventQ adapter.

Install or Upgrade a Review Board Adapter Without Internet Access

The following instructions pertain to situations where your Review Board server does not have outbound access to the internet.

  1. Contact the CollabNet Support to download the eventq_rb-[version].zip archive file.
  2. Extract the archive file on the target server.
    unzip eventq_rb-[version].zip
    
  3. Install or upgrade the TeamForge EventQ-Review Board adapter as a Review Board extension.
    • Use the command below to install the EventQ adapter as an extension.
      sudo pip install --use-wheel --no-index --find-links=PATH_TO_WHEELHOUSE eventq_rb
      

      Where PATH_TO_WHEELHOUSE is the path to the directory where you unzipped the adapter file. Suppose you unzipped the adapter file to the /tmp directory. In such a case, the PATH_TO_WHEELHOUSE is /tmp.

      Example:

      sudo pip install --use-wheel --no-index --find-links=/home/myusername/wheelhouse/ eventq_rb
      
    • Add the -U flag to upgrade to the latest version of the Review Board adapter.
      sudo pip install -U --use-wheel --no-index --find-links=PATH_TO_WHEELHOUSE eventq_rb
      
  4. Restart Review Board’s web server to register the newly installed EventQ adapter.

Configure the Review Board Adapter (TeamForge Integrated)

Configure a TeamForge-integrated Review Board adapter to retrieve code review metadata.

Once the adapter has been installed successfully, configure Review Board by following these steps. The instructions below pertain to Review Board instances integrated with CollabNet TeamForge. See Configure the Review Board Adapter (Standalone) for configuration instructions when using a standalone version of Review Board.

  1. Log into TeamForge as a site-admin user.
  2. Select Admin > Integrated Apps.
  3. Select the Review Board option and click Administer. You should now see Review Board administrative page.
  4. Click Extensions from the menu bar to list your currently installed extensions. eventq-rb should be listed.
  5. Click Enable to activate the EventQ extension.
  6. Click Configure on the eventq-rb extension.

    The eventq-rb configuration page shows up. From here you can select and configure the repository whose reviews you would like to push to an EventQ review source. To create a review source in EventQ see: Manage Review Sources.

Configure a Review Board Respository

  1. Select the repository from the Repository drop-down list.
  2. Copy and paste the fields from the EventQ review source that you wish to associate to this repository.
  3. Click Save.
  4. Repeat steps 1 through 3 for each Review Board repository you wish to monitor in TeamForge EventQ.

Configure the Review Board Adapter (Standalone)

Configure a standalone instance of Review Board adapter to retrieve code review metadata.

Once the adapter has been installed successfully, configure Review Board by following these steps. The instructions below pertain to standalone Review Board instances.

  1. Log into your Review Board instance as a privileged user.
  2. Click the Admin link to reach the administrative page.
  3. Click Extensions on the menu bar to list your currently installed extensions. eventq-rb should be listed.
  4. Click Enable to activate the EventQ extension.
  5. Click Configure on the eventq-rb extension.

    The eventq-rb configuration page shows up. From here you can select and configure the repository whose reviews you would like to push to an EventQ review source. To create a review source in EventQ see: Manage Review Sources.

Configure a Review Board Respository

  1. Select the repository from the Repository drop-down list.
  2. Copy and paste the fields from the EventQ review source that you wish to associate to this repository.
  3. Click Save.
  4. Repeat steps 1 through 3 for each Review Board repository you wish to monitor in TeamForge EventQ.