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 V184.108.40.206 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.
- Use the Server Manager to add the Web Server (IIS) role. Be sure to select the following role services (see Figure 1):
- Application Development
- ISAPI Extensions
- ISAPI Filters
- Basic Authentication
- Windows Authentication
- Application Development
- 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
Figure 2. Windows server feature .NET Framework 3.5.1
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
- 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.
- 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
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
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.
- When using Microsoft Internet Explorer, add oslc.example.com to its trusted sites.
- Navigate to https://oslc.example.com:9443/jts/setup to set up the server.
- Log in using ADMIN and ADMIN user ID and password.
- Run the express setup.
- Confirm the public URI: https://oslc.example.com:9443/jts
- Create an administrative user (in this example, it is named rational).
- 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:
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
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.
- Navigate to https://oslc.example.com:9443/jts/admin.
- Select Server > Communication / Consumers (Inbound) (see Figure 6).
- Specify a name for the consumer (
SAin this example), and provide a password.
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
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.
- To prevent this, navigate to https://oslc.example.com:9443/jts/admin and click the Server tab.
- Select Configuration and then Advanced Properties, and search for com.ibm.team.repository.service.internal.oauth.OAuthServiceProvider.
- Add the callback URI, http://OSLC:8890/SAOSLCConsumer/, to the list of trusted client authorization URIs (Figure 7).
- Click the Preview link, and then Save the configuration.
Figure 7. Adding the System Architect URI as a trusted OAuth callback URL
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.
- In System Architect, open the JK_Enterprise encyclopedia.
- Using the menu bar, select Tools > Service Provider Configuration.
- Under the Servers Established area, click the Add button,
- 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
- 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
- After registering the server, the Add button under the Communication Links area should be available. Click it, and select the RRC configuration.
- An authentication dialog should open, where you need to provide Rational Requirements Composer user credentials.
- 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.
- Close the Configure Service Provider dialog window.
Figure 9. Rational Requirements Composer project selection dialog in System Architect
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
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
Figure 12. Dialog page cannot be loaded
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.
- 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.
- 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
- 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.
- Select the Composer actor, and click OK.
Figure 14. Select a Rational Requirements Composer requirement in System Architect
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.
Figure 15. Triangle icons indicate the existence of OSLC requirement links
Figure 16. Pop-up window shows the requirement summary
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
- Launch an editor such as Notepad or Wordpad as administrator
- Edit the SAServerConfiguration.xml file as follows:
- Choose a logical server name,
- Specify the SQL server connection where the System Architect encyclopedias reside as
- If no workspaces are used, it is sufficient to provide only the encyclopedia name and leave the
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>
- 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).
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
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.
- Navigate to https://oslc.example.com:9443/ccm/admin.
- Add an entry to the Communication / Friends (outbound) section.
- An input dialog window (Figure 18) will ask you to provide the following information:
- A name for the friend (this example uses SA)
- The root services URI (http://oslc.example.com:8889/SAOLSC/rootservices)
- A password as the shared secret
- Whether or not to establish a trust relationship between the servers (yes)
Figure 18. Creating an OAuth friend link in Rational Team Concert
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
- 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
- Scroll down to the Associations section, and click the Add button to open a selection dialog window.
- Select the SA application that was just created as the OAuth friend (Figure 20).
- 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).
- 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.
- Save the configuration.
Figure 20. Rational Team Concert Add Association view selections
Figure 21. System Architect XT and IIS authentication dialog window
Link an Rational Team Concert work item to an System Architect architecture artifact
- 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
- Click Elaborated by Architecture Element to create a new link of this type.
- 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
- Select an artifact on the right side, and click OK.
Figure 23. System Architect artifact selection dialog in Rational Team Concert
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
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
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.
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.
The author thanks Hubert Zenner and Jiong Xie for their help regarding the products and for reviewing this article.
- For more about Rational System Architect:
- The Rational System Architect page on developerWorks and the Rational System Architect product home page offer product information, user community access and learning resources.
- Learn more about Rational System Architect: XT.
- Check the Rational System Architect Information Center for documentation for all versions, or get support from the Rational System Architect and Rational System Architect XT help topics. See the sections on Installing and upgrading Rational System Architect and Installing Rational System Architect XT information centers for details on the installation prerequisites and process.
- For more about Collaboration Lifecycle Management:
- Check the documentation for Installing Rational solution for Collaborative Lifecycle Management, 4.0 releases, for more information on the Rational Team Concert, Rational Requirements Composer, Rational Quality Manager installation prerequisites and process. For more about Open Services for Lifecycle Collaboration (OSLC):
- Read the article titled Monitor Rational System Architect models by using Rational Team Concert to learn how to track changes to the System Architect encyclopedia using OSLC and Rational Team Concert (developerWorks, 2012).
- Visit the Open Services web site to learn about the OSLC standard.
- The OAuth web site contains in-depth information on the authorization mechanism underlying OSLC.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Subscribe to the developerWorks weekly email newsletter, and choose the topics to follow. Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
Get products and technologies
- Download a free, fully enabled trial version of Rational System Architect.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Participate in the Enterprise Architecture and Business Architecture forum, where you can share information about methods, frameworks, and tool implementations. Discussions include tool-specific technical discussions about Rational System Architect.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
- Get connected. Join the Rational community to share your Rational software expertise and get connected with your peers.