RegisterLog In to Jazz.net dW

Using the Rational OSLC Adapter for Atlassian JIRA with the Rational solution for Collaborative Lifecycle Management

This article applies to an archived trial download.We recommend this article that is about the latest trial version of the IBM Rational Adapter for JIRA.

This is a technical preview of the Rational OSLC Adapter for JIRA.

Overview

The IBM Rational OSLC Adapter for JIRA enables you to use Atlassian® JIRA® with your Rational Team Concert (RTC), Rational Requirements Composer (RRC), and Rational Quality Manager (RQM) capabilities. While you might have standardized on the Rational solution for Collaborative Lifecycle Management (CLM), areas of your business might still be using JIRA for defect management. Integrate with JIRA to submit defects from RQM, track requirement implementation from RRC, or assign tasks from RTC. This functionality enables you traceability across lifecycle data, encompassing both your Rational and JIRA users.

Note: This technical preview is not intended for production use. Work done with this version cannot be migrated to later versions of the Rational OSLC adapter for JIRA.

Next steps

A technical preview of Rational OSLC adapter for JIRA is available as a free download on jazz.net. These are the general steps for setting up and running the adapter:

  1. Download the IBM Rational OSLC Adapter for JIRA
  2. Install and configure the adapter
  3. Use the adapter

Complete instructions are provided in the sections that follow.

For more help

If you encounter problems while completing the tasks in these topics or have general questions about the adapter, you can take these actions:

Supported integration use cases

There are several supported integration use cases available with the JIRA adapter. You can perform all of these use cases with the sample CLM application.

The Sample use cases for using the JIRA adapter section of this article provides instructional examples for performing some of the use cases.

This table lists the supported artifact linking use cases.

Link from

Association

Link to

Rational Team Concert      
  Change request (any type Create new or link to existing: Related change request JIRA Issue (any type
  Change request (any type) Create new or link to existing: Affected by defect JIRA Issue (any type)
  Change request (any type) Create new or link to existing: Affects a plan item JIRA Issue (any type)
Rational Quality Manager      
  Test case Create new or link to existing: Tests JIRA Issue (any type) as development artifacts
  Test execution results Create new or link to existing: Affected by JIRA Issue (any type) as development artifacts
  Test plans
Test cases
Test scripts
Test execution records
Test suites
Create new or link to existing: Related tasks JIRA Issue (any type) as quality tasks
Rational Requirements Composer      
  Requirement Create new or link to existing: Tracked by JIRA Issue (any type)
Requirement Create new or link to existing: Implemented by  

Downloading the adapter

The adapter is available as a free download. To obtain it:

  1. Go to https://jazz.net/downloads/rational-oslc-adapter-for-jira/releases/1.0
  2. Click All (9.26MB) under Platform.
  3. Login with your jazz.net ID.
  4. Review the accompanying license by clicking View License. If you agree to the license terms, select the checkbox and click Accept.
  5. Your download should begin. If your download does not begin, follow the instructions provided.
  6. Download the archive file to a location that you can access later.

Installing and configuring the adapter

Prerequisites

Before installing and configuring the adapter, you must have the following software installed:

  • The Rational solution for CLM (3.0.1.1, 4.0)
    • Download and deployment information is available on Jazz.net.
    • The standard configuration that comes with the solution, including Apache Tomcat and Apache Derby, is sufficient for this version unless you plan to test it in a customized environment.
  • Atlassian JIRA 4.4.0 to JIRA 4.4.5 inclusive

    Download and deployment information is available on the Atlassian website.

    The JIRA adapter does not yet provide support for Atlassian JIRA 5.x

  • Any of the following browsers:
    • Firefox 3.6 or later
    • Internet Explorer® 8 or later

      Note: When using Internet Explorer, if pages appear to be rendered incorrectly or clicking items has no effect, you must change the default rendering in the browser by modifying the Browser Mode and the Document Mode settings. Both settings must be set to the standard Internet Explorer 8 or later and not Compatibility View, Quirks Mode, or Internet Explorer 7.

      To view and modify these settings from Internet Explorer, select Tools > Developer Tools or press F12. In the Developer Tools window you can view the current Browser Mode and Document Mode settings and can click these items to view the available options or to change the settings.

Note: On Macintosh® systems, if your JIRA server uses SSL, you might not be able to use the Rational Team Concert client for Eclipse to link to artifacts in JIRA, if your client is using Eclipse versions earlier than 3.7.

Installing the JIRA adapter

To install the adapter:

  1. Extract the contents of the file you downloaded to a location that you can access from your JIRA server. This file should be a jar.

    Note: If you are using a Macintosh system and the default Archive Utility, this utility will unpack the jar contained within the archive. To avoid this result, unzip the file on the command line.

    • Open a terminal.
    • Change the directory to your download location. For example, cd/users/user/downloads
    • Unzip Rational-OSLC-Adapter-for-JIRA.zip
    • You should see a jar file in your directory.
  2. Start the JIRA server if it is not already started.
  3. Login to your JIRA server with administrative privileges.
  4. Click Administration, located at the top right of the page.
  5. On the Administration page, select Plugins from the Plugins drop down menu. You might be prompted to enter your JIRA administrative credentials.
  6. On the Plugins page, click the Install tab.
  7. Click Upload Plugin, and in the dialog that opens, browse to where you extracted the adapter jar file. Select the adapter, click Open and then click Upload. A message displays indicating that the plugin was successfully installed.
  8. Restart the JIRA server.

Linking issue types in JIRA to CLM artifacts

To add a custom field to your JIRA issue form so that links are created from JIRA issues to your CLM artifacts:

  1. Navigate to the Administration tab (if you are not still there), and click Custom Fields from the Issues section in the lower left of the page.
  2. Click Add Custom Field, and on the next page, select OSLC Links. This selection is available after you have installed the plug-in. Then click Next.
  3. Provide any name that you prefer for the field such as "OSLC Links."
  4. Under Choose applicable issue types and make sure Any issue type is selected.
  5. Under Chose applicable context, select a project to integrate with the Rational solution for CLM or accept the default Global context. Apply to all issues in JIRA.
  6. Click Finish.
  7. On the Screens page, you must select the Default Screen checkbox. Make any additional selections and then click Update.

Note: For best results, make sure that the JIRA project contains the default issue types that come with the product: bugs, tasks, new features, and improvements. For bi-directional links to be created, users must have permissions to edit issue types, as configured in JIRA administration.

Establishing friend servers

To enable cross-server communication, you must establish links between the JIRA server and the Rational Solution for Collaborative Lifecycle Management applications. To do this, add friends to the friend server list for CLM applications.

  1. Navigate to the Jazz Team Server Administration page and login with administrative privileges. You can access the page directly at this address:

    https://fully qualified hostname:port/jts/admin#action=jazz.viewPage&id=com.ibm.team.repository.server

  2. Click Friends (Outbound) from the Communication section in the left sidebar.
  3. Click Add, and provide these details:
    • Name: You can use any name.
    • Root Services URI: jira_base_url/rest/oslc/latest/rootservices (for example, a base URL could be: http://example.com:8080/)
    • OAuth Secret: You can use anything here (for example, myjirasecret)
    • Re-type Secret: The same as the previous entry
  4. Click Create Friend and then click Next.
  5. Configure the oAuth manager for oAuth authentication while creating a friend server. Click the Grant access for the provisional key link. Login with your JIRA credentials, if prompted. Specify a consumer name to remember your OAuth friendship by. Click Approve and then click Finish.
  6. Repeat steps 1 - 5 for Change and Configuration Management (CCM) administration and Quality Management (QM) administration. The Requirements Management application (RM) is already configured with the Jazz Team Server administration. You can access those pages directly at these addresses:
    • https://fully qualified hostname:port/ccm/admin
    • https://fully qualified hostname:port/qm/admin

    Note: The CLM 2012 server rename feature is not supported.

Deploying the sample application

To deploy the Rational solution for CLM sample application:

Some of the use cases supported by the adapter are inspired by the "Money that Matters" scenario and sample application that is included with the Rational solution for CLM. So that users of this version do not need to create data in the Rational solution for CLM before performing JIRA integration use cases, deploy the sample application. For instructions on deploying the sample application, see this topic:

http://publib.boulder.ibm.com/infocenter/clmhelp/v4r0/topic/com.ibm.jazz.install.doc/topics/t_install_sample_project.html

Associating project areas with JIRA

Rational Team Concert

To associate Jazz project areas with JIRA:

  1. Go to https://host:port/ccm/admin#action=jazz.viewPage&id=com.ibm.team.process.ProjectAreaManagement, and log in with administrative privileges.
  2. Open the project to associate with JIRA. Click Project Areas, then click Active Project Areas. Next click JKE Banking Change Management.
  3. In the Associations section, click Add.
  4. Enter your administrative credentials for the JIRA server.
  5. In the window that opens, specify the following information:
    1. For Application, select the option for JIRA that you just "friended" in the earlier section.
    2. For Association, select Provides - Related Change Requests.
    3. For Artifact Containers, select the project area that you created in JIRA.
    4. Click OK, scroll to the top of the page, and click Save.

Rational Quality Manager

To associate quality manager project areas with JIRA:

  1. Go to https://host:port/qm/admin#action=jazz.viewPage&id=com.ibm.team.process.ProjectAreaManagement, and log in with administrative privileges.
  2. Open the project to associate with JIRA. Click Project Areas, then click Active Project Areas. Next click JKE Banking Change Management.
  3. In the Associations section, click Add.
  4. Enter your administrative credentials for the JIRA server.
  5. In the window that opens, specify the following information:
    1. For Application, select the option for JIRA that you just "friended" in the earlier section.
    2. For Association, select Uses - Defects.
    3. For Artifact Containers, select the project area that you created in JIRA.
    4. Click OK, and repeat step 3. This time select Uses - Quality Management Tasks in the Association section.
    5. Click OK, scroll to the top of the page, and click Save.

Rational Requirements Composer

To associate requirements manager project areas with JIRA:

  1. Go to https:host:port/rm/admin, login with administrative privileges, and click Manage Projects under Requirements Management in the Application Administration section.
  2. Open the project to associate with JIRA. Click Project Areas, then click Active Project Areas. Next click JKE Banking Change Management.
  3. In the Associations section, click Add.
  4. Enter your administrative credentials for the JIRA server.
  5. In the window that opens, specify the following information:
    1. For Application, select the option for JIRA that you just "friended" in the earlier section.
    2. For Association, select Uses - Implementation Requests.
    3. For Artifact Container, select the project area that you created in JIRA.
    4. Click OK, and repeat step 3. This time select Uses - Requirements Change Requests in the Association section.
    5. Click OK, scroll to the top of the page, and click Save.

Configuring OAuth authentication

To configure OAuth authentication, follow the steps for your application server.

Apache Tomcat:

  1. Stop the Jazz Team Server if it is running.
  2. Navigate to the location where the the server.startup file is installed. These paths are the default locations: Windows: C:\Program Files\IBM\JazzTeamServer\server\server.startup.bat Linux: /opt/IBM/JazzTeamServer/server/server-startup
  3. Open the file and find the section where JAVA_OPTS arguments are made.

    Skip the next step for CLM 3.0.1.1 or later.

  4. For CLM 3.0.1.0,append the following JVM argument to the end of the section with the other JVM arguments for : JAVA_OPTS="$JAVA_OPTS -Dcom.ibm.team.repository.service.oauth.legacyMode=true".
  5. Save and close the file.
  6. Restart the Jazz Team Server.

IBM Websphere Application Server:

  1. Log into the WebSphere Application Server console at https://server host:9043/ibm/console
  2. On the left sidebar, click Servers > Server Types > Application Servers.
  3. Click the server in the content pane.
  4. Navigate to Server Infrastructure > Java and Process Management > Process Definition.
  5. Under Additional Properties, click Java Virtual Machine.

    Skip the next step for CLM 3.0.1.1 or later.

  6. For CLM 3.0.1.0, in the Generic JVM arguments field, add the following to the end: -Dcom.ibm.team.repository.service.oauth.legacyMode=true
  7. Save the configuration, and restart the server.

You must also work with the oAuth manager for completing the authentication. If you did not do this while creating the friend servers in Jazz, then from the JIRA UI, go to base_url/rest/oslc/latest/oauth/manager/ and activate the friend server entries before they can be used.

Using JIRA logging for the adapter

You can review the available log files to monitor your system and identify issues that might need to be addressed. You can use the logging feature in JIRA to monitor and debug the JIRA adapter.

From the JIRA Administration page, under Systems, then Troubleshooting and Support section, you can specify profiles for logging and logging levels for individual features and functions in JIRA. By default, the OSLC JIRA adapter logging options are not visible. To enable them, follow these steps:

  1. Locate the log4j.properties file in your JIRA deployment. A common location for it is:

    jira-deployment/webapp/WEB-INF/classes/log4j.properties

  2. Locate the CLASS-SPECIFIC LOGGING LEVELS block and add the following text to the list:
    # Start of OSLC Logging
    log4j.logger.com.ibm.oslc.cm.adaptor.jira = INFO, console, filelog
    log4j.additivity.com.ibm.oslc.cm.adaptor.jira =  false
    # End of OSLC Logging
  3. Stop and restart the JIRA server.

    After the JIRA server restarts, you can set the logging level for the JIRA adapter by specifying the logging levels for com.ibm.oslc.cm.adaptor.jira. By default, the logging levels are set to INFO.

Note: Setting the logging level to DEBUG will cause a large amount of data to be included in the atlassian-jira.log file found in the jira-home/logs folder.

At this point, you have completed the installation and configuration tasks. You can proceed to using the Rational OSLC adapter for JIRA.


Sample use cases for using the Rational OSLC adapter for JIRA

These use cases are inspired by the "Money that Matters" scenario in places where JIRA can be used with the Rational Solution for Collaborative Lifecycle Management. These examples are intended only to provide samples of how to explore the adapter and do not restrict or imply that other use cases cannot also be implemented. For more information about the Money that Matters scenario, see https://jazz.net/wiki/bin/view/Main/MTM_Lifecycle_Scenario.

For each use case, the user IDs for sample application users are only valid with the sample application. If you are creating your own data, users need to log in with the credentials set up in your projects.

If you are unable to perform any of the use cases, contact your Administrator to ensure that the requisite administrative tasks have been performed as detailed in Installing and configuring the adapter.

Note: If you are using Internet Explorer, do not choose to view only secure content.

Requirements Management to Change Management in JIRA

Bob (the product owner) is preparing for a sprint planning meeting. He has recently created a new story, assigned its priority, and related it to a requirement as an "implemented by" link. The remaining step is to create a task against the development team to analyze the impact of this story to the release schedule. The development team must determine whether the story can be added to sprint 2. However, he happens to know that the team that builds the features for this specific requirement manages their development activities with JIRA, so the task he creates must be submitted there, not in Rational Team Concert.

  1. Go to https://hostname:port/rm/web and log in with these credentials:
    • User Name: bob
    • Password: bob.
  2. Navigate to the JKE Banking (requirements) project from your dashboard.
  3. In the left sidebar, navigate to JKE Banking (requirements) > JKE Business Recover Matters > User Story Elaboration > Elaborated Stories, and open this requirement: 65: Allocate dividends by amount and frequency
  4. In the right sidebar, open the Links section, click the Add link to artifact icon, and select Tracked by.
  5. In the window that opens, select your JIRA project from the Artifact container menu, and click Create new. (Log in with your JIRA account if prompted) Note: If you are using Internet Explorer, you might be prompted to choose to view only secure content. You must click No.
  6. In the Summary field, enter "Analyze impact of the related change request to sprint 2: Allocate dividends by amount and frequency."
  7. In the Description field, enter "please review the related change request: Allocate dividends by amount and frequency" to add to sprint 2.
  8. Click Create. You can hover over the link to the task that you just created to see the preview details.
  9. Open the task that you just created in a new browser window or tab.
  10. Copy a link to the story that you have referred to in the links section in your requirement, and paste the link into the comments section of the task that you created in JIRA. Save your task.

Change Management in Rational Team Concert to Change Management in JIRA

Marco (the development lead) is running a sprint 2 planning meeting and has decided to include a new story in the iteration. Part of moving this story into sprint 2 is to create a task for his development team to build the feature. He knows that the development team that works on this component of the product uses JIRA for change management activities, and therefore he must create the task in the JIRA repository.

  1. Go to https://hostname:port/ccm/web/projects/JKE Banking (Change Management), and log in as user by entering marco in User Name and Password.
  2. Search for and navigate to the "61: Allocate dividends by amount and frequency" story.
  3. In the story, click the Links tab, and in the Add menu, click Related Change Request.
  4. In the window that opens, select your JIRA project from step 1. In step 2, click Create new. Click Task from the menu. Click OK.

    Note: If you are using Internet Explorer, you might be prompted to choose to to view only secure content. You must click No.

  5. A new JIRA dialog opens. (Log in with your JIRA account if prompted.) Provide some sample data in the required fields, and click Create.

You can hover over the link to the task that you just created to see the preview details.

Quality Management to Change Management in JIRA

Tanuj (the tester) is reviewing his dashboard and discovers that there is a story ready for testing. He has navigated to the story, reviewed its details, explored the build results, and is ready to execute the test case. If Tanuj discovers any defects, he knows for this particular feature, the developer uses JIRA for change management, and therefore must submit defects against the JIRA repository.

  1. Go to https://hostname:port/qm/web/console/JKE Banking (Quality Management), and log in by entering tanuj in User Name and Password.
  2. Search for and open the "7. Allocate dividends by amount and frequency" test case.
  3. For the purpose of this use case, you do not need to run an actual test; just generate mock test results. Click the Play icon, and in the window that opens, either accept the defaults settings, or choose some sample settings, and click OK.
  4. In the displayed results, select Partially Blocked from the Actual results menu.
  5. Scroll down to the Defects section of the results, and click the Create New Defect icon, which is the first icon available. You can hover over each icon to see the icon description.
  6. From the dialog box that opens, select your JIRA project from the menu, and click OK. Note: If you are using Internet Explorer, you might be prompted to choose to to view only secure content. You must click No.
  7. A new JIRA dialog box opens. (Log in with your JIRA account if prompted.) Provide some sample data in the required fields, and click Create.
  8. Save your test results.

You can hover over the link to the task that you just created to see the preview details.

Note: The quality management to change management JIRA integration supports additional uses cases from other quality management artifacts. See the earlier table for those that are supported, and explore those use cases also.

Macintosh is a trademark of Apple Inc.

Internet Explorer is a registered trademark of Microsoft Corporation in the United States and/or other countries.


Feedback
Was this information helpful? Yes No 18 people rated this as helpful.