Integrate Rational System Architect 11.4 and CLM 2012 applications by using OSLC

How to install and configure bidirectional linking from scratch

OSLC is a mature and powerful technology to integrate software lifecycle applications. Rational System Architect Version 11.4 and the Rational solution for Collaborative Lifecycle Management (CLM) 2012 applications are based on significantly different technologies and architectures. This article provides step-by-step guidance on how to set up and configure these products so they can work together in an integrated and seamless fashion.

Share:

Wolfram Richter, IT Architect, IBM

Wolfram Richter lives and works in Germany. He is a consultant with the IBM Software Services for WebSphere organization. He has a nine-year history in IBM middleware and business process management (BPM) technology and specializes in integrating SAP solutions with IBM software. Before his current assignment within IBM's own IT department, he worked as a pre-sales IT specialist and in education and training.



25 September 2012

Also available in Chinese Portuguese

Overview

Open Services for Lifecycle Collaboration (OSLC) allow software and product lifecycle tools from the same or different vendors to interoperate to support end-to-end processes. Such tools include software packages for project management, defect tracking, test management, architecture management, and other tasks. In this article, we will show how to set up OSLC integration between IBM® Rational® System Architect as the architecture management tool and the Rational solution for Collaborative Lifecycle Management (CLM) applications that provide requirements management, project planning, change and configuration management, build management, and test management capabilities. Setting this up on a Microsoft Windows 2008 R2 server requires you to navigate around some tripping hazards.

This article was written based on the experience gained when setting up the integration scenario within the IBM Beta Test Site in the SAP Center of Excellence of IBM located in Herrenberg, Germany. It assumes that you are familiar with the core concepts of the respective tools. It guides you through the installation and integration process in a step-by-step fashion, using the following product versions:

  • Microsoft Windows Server 2008 R2
  • Rational System Architect V11.4.2
    • Includes Microsoft SQL Server Express 2008
  • Rational System Architect XT V11.4.2 (System Architect XT)
  • Rational CLM 2012
    • Rational Team Concert 4.0
    • Rational Quality Manager 4.0
    • Rational Requirements Composer 4.0 Rational Requirements Composer

The author has successfully set up a similar configuration based on previous versions, such as System Architect V11.4.1.2 and CLM 2011 (Rational Team Concert, Rational Requirements Composer, and Rational Quality Manager 3.0). Although screen captures might differ in details, the overall approach does not change.


Install the software components

Throughout this article, the host name of the server is OSLC, and its domain is .example.com. Replace this with your server name and domain where appropriate. On the server, a Microsoft Windows user named "Rational" (OSLC\Rational) with administrative privileges has been created.

Prepare the Microsoft Windows 2008 R2 server

Installing and configuring Internet Information Services (IIS) is a prerequisite for Rational System Architect XT, and the .NET 3.5 Framework is a prerequisite for the System Architect OSLC security handshake.

  1. Use the Server Manager to add the Web Server (IIS) role. Be sure to select the following role services (see Figure 1):
    • Application Development
      • ASP.NET
      • ASP
      • ISAPI Extensions
      • ISAPI Filters
    • Security
      • Basic Authentication
      • Windows Authentication
  2. Use the Server Manager to add the .NET Framework 3.5 or later feature (see Figure 2).
Figure 1. Prerequisite IIS role services for System Architect XT installation
Windows Server role services selection dialog
Figure 2. Windows server feature .NET Framework 3.5.1
Windows Server Management Console Features section

Install Rational System Architect

In this example, System Architect has been installed to the default directory:

C:\Program Files (x86)\IBM\Rational\System Architect Suite

  1. Ensure that a valid license file is available for both Rational System Architect and System Architect XT or that both can be configured to use a license server that can provide valid licenses.
  2. Perform a complete installation of System Architect, including all prerequisites.

Configure System Architect using the Startup Wizard

If it doesn't come up automatically upon first start of System Architect, click Help > Startup Wizard to launch the wizard. Install an instance of SQL Server 2008, configure the System Architect installation and install the sample and tutorial encyclopedias. This creates (among others) the JK_Enterprises sample encyclopedia that we use to demonstrate OSLC integration (see Figure 3).

Figure 3. Startup Wizard sample encyclopedias
JK_Enterprises encyclopedia selected

Install System Architect XT

System Architect XT is required to render the diagrams as web pages when System Architect acts as OSLC provider. It installs into the same directory. If you get an 0x8007000B error message during installation (Figure 4), review the IIS role services for completeness and retry the installation.

Figure 4. System Architect XT installation error message when IIS role services are missing
installation error message 0x8007000b

Install and configure CLM 2012 applications

Install Rational Requirements Composer, Rational Team Concert, and Rational Quality Manager. An express installation using Tomcat is sufficient for this demonstration scenario. The Interactive Installation Guide will help you through the process.

  1. When using Microsoft Internet Explorer, add oslc.example.com to its trusted sites.
  2. Navigate to https://oslc.example.com:9443/jts/setup to set up the server.
  3. Log in using ADMIN and ADMIN user ID and password.
  4. Run the express setup.
    1. Confirm the public URI: https://oslc.example.com:9443/jts
    2. Create an administrative user (in this example, it is named rational).
    3. You can either use the provided trial licenses (Rational Requirements Composer Analyst, Rational Team Concert Developer, Rational Quality Manager Quality Professional, Contributor) or import your own licenses.

Create the CLM sample projects

To create some sample data, navigate to this location and create the "Money that matters" lifecycle sample projects:

https://oslc.example.com:9443/admin/web#/sample

The "rational" user should automatically be added to each project as administrator. In addition, a number of sample users are created. Although not strictly necessary for this OSLC linking scenario, these sample users should also be assigned the proper licenses. This can be done in the user management section of the Jazz Team Server administration page.

This step creates the following projects:

  • JKE Banking (change and configuration management) in /ccm
  • JKE Banking (quality management) in /qm
  • JKE Banking (requirements management) in /rm

Set up Rational System Architect as an OSLC consumer

The following example shows how to configure Rational Requirements Composer as RM provider for requirements to be linked from System Architect content. Almost the same steps are necessary to link with Rational Team Concert and Rational Quality Manager, albeit the configuration may take place in different locations. The developerWorks article titled Monitor Rational System Architect models by using Rational Team Concert explains how to use Rational Team Concert to monitor changes in System Architect.

Allow OSLC registration without privilege elevation

OSLC uses OAuth as an authentication mechanism, and it uses a callback mechanism to exchange the security handshake information. System Architect needs to open an HTTP endpoint on the local machine to be able to receive the handshake. By default, the Windows 2008 security policy prevents this for non-privileged users, which causes the OAuth handshake to fail more or less silently. This means that either System Architect needs to be run as administrator (defeating the purpose of a non-privileged process) or a URL ACL needs to be registered to allow regular users to open the endpoint.

From a command shell with elevated privileges (which has been run as administrator as Figure 5 shows), run the netsh command shown in Listing 1 once on the system that is running System Architect. Replace OSLC with the host name of the system that is running System Architect.

Figure 5. Setting the URL ACL through the netsh
netsh command in Windows command prompt

The sddl expression is equivalent to specifying user=Everyone, but also works on Windows locales other than English.

Listing 1. netsh command that allows everyone to open the OAuth http endpoint
netsh http add urlacl url=http://OSLC:8890/ sddl=D:(A;;GX;;;WD)

Create a Consumer Key in Rational Requirements Composer

In contrast to the other Jazz applications, such as Rational Team Concert and Rational Quality Manager, Rational Requirements Composer does not have its own OAuth configuration. It shares its configuration with the Jazz Team Server component.

  1. Navigate to https://oslc.example.com:9443/jts/admin.
  2. Select Server > Communication / Consumers (Inbound) (see Figure 6).
  3. Specify a name for the consumer (SA in this example), and provide a password.

Tip:
Clearing the Trusted check box will cause Rational Requirements Composer to explicitly ask the end user whether or not to trust the System Architect application to act on the user's behalf every time that the user logs into Rational Requirements Composer through System Architect. Since we have both environments under our own control and it is more convenient, we keep Trusted checked.

Figure 6. Creating a Consumer key for Rational Requirements Composer in the Jazz Team Server administration view
Name and secret provided and trusted box is checked

Register the System Architect callback URL as trusted

The OAuth mechanism in System Architect uses a callback URL that Rational Requirements Composer cannot determine to originate from a trusted source. This will cause the Trusted flag to be ignored if left unchanged.

  1. To prevent this, navigate to https://oslc.example.com:9443/jts/admin and click the Server tab.
  2. Select Configuration and then Advanced Properties, and search for com.ibm.team.repository.service.internal.oauth.OAuthServiceProvider.
  3. Add the callback URI, http://OSLC:8890/SAOSLCConsumer/, to the list of trusted client authorization URIs (Figure 7).
  4. Click the Preview link, and then Save the configuration.
Figure 7. Adding the System Architect URI as a trusted OAuth callback URL
OSLC callback URL entered as trusted URI

Register Rational Requirements Composer as an OSLC Service Provider in System Architect

This step needs to be done once for each System Architect encyclopedia and Rational Requirements Composer project.

  1. In System Architect, open the JK_Enterprise encyclopedia.
  2. Using the menu bar, select Tools > Service Provider Configuration.
  3. Under the Servers Established area, click the Add button,
  4. Configure the link to the Rational Requirements Composer server. Provide the following information (see Figure 8), and then click the Register button:
    • A name for the server (RRC in this example)
    • The root services URL of Rational Requirements Composer
      (https://oslc.example.com:9443/rm/rootservices)
    • The key created during the registration of the OSLC Consumer in Jazz Team Server
    • The secret selected during the registration.
Figure 8. Registering Rational Requirements Composer as Service Provider in System Architect
Name, root service URI, Consumer key, secret
  1. After registering the server, the Add button under the Communication Links area should be available. Click it, and select the RRC configuration.
  2. An authentication dialog should open, where you need to provide Rational Requirements Composer user credentials.
  3. After explicitly authorizing System Architect to access Rational Requirements Composer on the user's behalf, select JKE Banking from the list of Rational Requirements Composer requirements projects (Figure 9), and click Add.
  4. Close the Configure Service Provider dialog window.
Figure 9. Rational Requirements Composer project selection dialog in System Architect
RRC server and JKE Banking selected

If you get an error message that says "Could not load file or assembly System.Core..." after providing your authentication credentials (see Figure 10), you need to install Microsoft .NET Framework 3.5 and restart Rational System Architect.

Figure 10. "Could not load file or assembly System.Core... " error message
.NET assembly missing error message

If you get an "Access is Denied" error message (Figure 11) or if the dialog page cannot be loaded after providing the authentication credentials (Figure 12), you need to either run System Architect with elevated privileges or perform the URL ACL registration step.

Figure 11. "Access is Denied" error message
Access denied error dialog
Figure 12. Dialog page cannot be loaded
Internet Explorer error message

Link to Rational Requirements Composer requirement from System Architect

OSLC links to requirements can be created from System Architect diagrams, symbols, or definitions. In this example, we are using the Account Open use case diagram in the JK_Enterprises encyclopedia. We link the Customer actor definition in Rational Requirements Composer to the Customer symbol in the System Architect diagram.

  1. Right-click on the encyclopedia content, and select Link to Requirement from the context menu (see Figure 13). If you haven't authenticated against Rational Requirements Composer in your current System Architect session, you will see the Rational Requirements Composer login dialog window.
  2. You will get a dialog window allowing you to select Rational Requirements Composer requirements or collections.
Figure 13. Context menu allowing to link to a requirement
System Architect symbol context menu
  1. In the Rational Requirements Composer selection dialog (for artifact selection, see Figure 14), search for the requirement name or navigate to it through the Rational Requirements Composer folder structure, JK Enterprise Project > Use Case Content > Actors.
  2. Select the Composer actor, and click OK.
Figure 14. Select a Rational Requirements Composer requirement in System Architect
Rational Requirements Composer artifact picker

View the OSLC link target summary in Rational System Architect

In System Architect, the existence of an OSLC link is indicated by using a red triangle icon next to a symbol, definition, or diagram (Figure 15). If you hover your mouse pointer over such a triangle, a pop-up window depicting a summary of the link target will open (Figure 16). The content of this pop-up is actually rendered by the target system (Rational Requirements Composer in this example); therefore, it always reflects the latest content.

Red triangles by symbols, diagrams, definitions
Figure 16. Pop-up window shows the requirement summary
Rational Requirements Composer view

Set up System Architect as an OSLC provider

In this example, we will configure System Architect to provide architecture diagrams to Rational Team Concert work items. This might be useful to associate architecture information with a task.

Configure System Architect REST service to expose the encyclopedia as an OSLC link source

See the Configuring Rational System Architect encyclopedias as resources for linking topic in the information center for details. The REST service configuration is stored in the file SAServerConfiguration.xml in the System Architect installation directory (see Listing 2). In this example, it is located in:

C:\Program Files (x86)\IBM\Rational\System Architect Suite\System Architect

  1. Launch an editor such as Notepad or Wordpad as administrator
  2. Edit the SAServerConfiguration.xml file as follows:
    • Choose a logical server name,
    • Provide SQL as serverType,
    • Specify the SQL server connection where the System Architect encyclopedias reside as serverName.
    • If no workspaces are used, it is sufficient to provide only the encyclopedia name and leave the workspace configuration as-is.
Listing 2. SAServerConfiguration.xml file exposing the JK_Enterprises encyclopedia
<SAServerConfiguration> 
    <SAServers> 
        <Logicalserver name="SA" serverType="SQL" serverName="OSLC\SYSARCH" > 
            <Encyclopedias> 
                <Encyclopedia encyclopediaName="JK_Enterprises"> 
                    <Workspace ID="" name=""/> 
                </Encyclopedia> 
            </Encyclopedias> 
        </Logicalserver> 
    </SAServers> 
</SAServerConfiguration>
  1. Start or restart the System Architect REST service for the OSLC inbound communication to work. Launch a command window as administrator and execute the command in Listing 3 (also see Figure 17).

Tip:
If the service was already running, you need to restart it to pick up the changed configuration. Simply issue a net stop command using the same syntax before starting the service.

Listing 3. Command to start the System Architect REST service
net start "IBM Rational System Architect Rest Service"
Figure 17. Starting the System Architect REST service
NET START command executed in windows shell

Create the OAuth friend (outbound) configuration in Rational Team Concert

Rational Team Concert maintains its own OAuth configuration and does not participate in the Jazz Team Server configuration.

  1. Navigate to https://oslc.example.com:9443/ccm/admin.
  2. Add an entry to the Communication / Friends (outbound) section.
  3. An input dialog window (Figure 18) will ask you to provide the following information:
Figure 18. Creating an OAuth friend link in Rational Team Concert
Name, root services URI, secret provided and trusted

Tip:
Upon clicking Create Friend and then Next, you are presented with the provisional key. However, neither the key nor the secret will be required in the next steps.

Associate System Architect with the Rational Team Concert project

  1. Navigate to https://oslc.example.com:9443/ccm/web and click the Manage Project link of the JKE Banking project (Figure 19).
Figure 19. Rational Team Concert project overview
Link to Manage Project
  1. Scroll down to the Associations section, and click the Add button to open a selection dialog window.
  2. Select the SA application that was just created as the OAuth friend (Figure 20).
  3. Now another authentication dialog should open, this time rendered by System Architect XT (Figure 21). Rational System Architect authenticates against the operating system user registry. This is why you need to provide the Windows user credentials (the username needs to be specified in the Windows DOMAIN\USERNAME format, thus OSLC\Rational in this example).
  4. After your user credentials are authenticated, you will see a list of exposed System Architect encyclopedias. Select the JK_Enterprises_1 encyclopedia (_1 is appended automatically by System Architect), and click OK.
  5. Save the configuration.
Figure 20. Rational Team Concert Add Association view selections
SA and JK_Enterprises_1 encyclopedia selected
Figure 21. System Architect XT and IIS authentication dialog window
Username and password prompt

Link an Rational Team Concert work item to an System Architect architecture artifact

  1. Open a Rational Team Concert work item for the JKE Banking (Change Management) project, and navigate to its Links page.

You will see a new Elaborated by Architecture Element link type available (Figure 22).

Figure 22. New "Elaborated by Architecture Element" link type for Rational Team Concert work items
Rational Team Concert work item, links section
  1. Click Elaborated by Architecture Element to create a new link of this type.
  2. When the artifact selection dialog window opens, rendered by System Architect XT (Figure 23), you can filter for artifact names, types, and other attributes. In this example, we've simply searched for the Account Open use case diagram used in System Architect as the OSLC Consumer example
  3. Select an artifact on the right side, and click OK.
Figure 23. System Architect artifact selection dialog in Rational Team Concert
System Architect artifact selection, search for *open*

View the link summary

Now that the link has been created, you can easily access detail information from within the Rational Team Concert work item. Simply hover with your pointer over the link and a pop-up window will open (in the author's environment, this window did not open sporadically - restarting the System Architect REST service remedied this situation.). You may have to log into System Architect XT again. Since we did not set up System Architect XT to use https, Internet Explorer will show a warning that encrypted content (from Rational Team Concert) and unencrypted content (from System Architect XT) are to be shown on the same page (Figure 24). It is important to choose No here, otherwise the System Architect content will not load.

Figure 24. Warning about unencrypted content in an encrypted web page
Screen capture of the security warning

When you are logged in, the pop-up window shows technical information about the System Architect diagram. The diagram contents are loaded after you click the Show More link on the bottom of the pop-up window (see Figure 25).

Figure 25. Displaying an System Architect diagram in an Rational Team Concert pop-up window
Screenshot of System Architect content in Rational Team Concert popup window

Clicking the OSLC link will take you to the System Architect XT web site, where you can browse the diagram and all encyclopedia content. However, this use of System Architect XT requires additional setup steps, such as creating a SA catalog and assigning permissions to the user, which are beyond the scope of this article. See the Sample Task List for Access Control topic in the Rational System Architect information center for instructions.


Summary

OSLC is a powerful and mature technology to integrate software development lifecycle management software, regardless of the technology used to develop those tools. This article has shown that it is relatively simple to enable two products based on significantly different architectures and technologies to talk to each other. The author hopes that by giving step-by-step guidance, future projects will spend less time perusing the product documentation and have more time available to use them to their advantage.


Acknowledgements

The author thanks Hubert Zenner and Jiong Xie for their help regarding the products and for reviewing this article.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=836420
ArticleTitle=Integrate Rational System Architect 11.4 and CLM 2012 applications by using OSLC
publish-date=09252012