Historically, many organizations develop enterprise and software architectures in isolation from each other, or they try to reconcile them manually. This isolation causes several problems:
- It limits the value of the enterprise architecture, because it might deviate from reality.
- The development teams might inadvertently contravene the enterprise architecture, as they are unaware of its contents.
- It's not possible to analyze the traceability to identify traceability gaps between enterprise and software architectures.
- Individuals don't know where to find, or don't have access to, the various models that they might need. For example, a software designer might not know how to get access to the enterprise architecture but might need to see it.
By using IBM® Rational® Jazz™ technology (see Resources for links to both), it is now possible to link elements in an enterprise architecture stored in IBM® Rational® System Architect with model elements stored in IBM® Rational® Software Architect extension for Design Management (sometimes called Design Manager). This capability has several benefits:
- Saves time by making it quick and easy to navigate to the right part of an associated model
- Improves application quality by helping to ensure that application architecture conforms to enterprise architecture
- Facilitates reporting and gap analysis between enterprise and software architectures
This tutorial shows you how to perform these tasks:
- Configure the integration between Rational System Architect and Rational Software Architect.
- Easily create links between your enterprise and software architectures to make it quick and simple to navigate between the two domains.
- Use the graphical capabilities of both tools to understand the relationships between your enterprise and system architectures.
- Use the reporting capabilities to document and identify traceability gaps between your enterprise and software architectures.
Get ready to run this tutorial
- We will not cover the installation and setup of Rational System Architect, Rational Software Architect, the Rational Software Architect extension for Design Management, or Rational System Architect XT. We base this article on the assumption that you have these installed and configured on one or more systems.
Summary of what’s installed and running
We used the following topology to create this article, and we recommend that you use it if you want to evaluate this configuration. The topology in Figure 1 shows the separation between components installed on the server and client, although they were installed on a single computer for this tutorial (running Microsoft Windows, 64-bit), for convenience. Also, at the time of writing, this integration is not supported for Rational System Architect running on an Oracle database server.
Figure 1. Software installation topology
After you've got everything installed, you need to start everything.
- Start Rational Software Architect Design Manager by selecting Start > All Programs > Rational Design manager > Start the Jazz Team Server.
- Confirm that the Rational System Architect REST service is running by going to Administrative tools and verifying that the IBM Rational System Architect REST service is started, as shown in Figure 2. This service provides the OSLC interfaces that are used by Rational Software Architect extension for Design Management.
Figure 2. System Architect REST service is running
- Start Rational System Architect, and create a new Sample project. Alternatively, open the JK Enterprises encyclopedia provided, which is the example we use here. In this tutorial, we configured the Rational System Architect encyclopedia to be an enterprise encyclopedia, just to support navigation from the Design Management extension to enterprise architecture elements through the Rational System Architect XT media.
- If you don't have an existing project area in Design Management, create a project area on the server, and import any model that was created in Rational Software Architect by using the Design Management import engine (the import process is not covered in this article).
Configure Rational System Architect to connect with Rational Software Architect extension for Design Management
For the Design Management extension to connect to a Rational System Architect repository, you need to set up Rational System Architect to be a resource provider, linking through OSLC.
Set up Rational System Architect to provide OSLC services
To do this, configure the SAServerConfiguration.xml file with the details of the SQL server instance, the encyclopedia name, and the workspace ID by following these steps:
- Navigate to the Rational System Architect installation folder:
C:\Program Files (x86)\IBM\Rational\System Architect Suite\System Architect
- Open the SAServerConfiguration.xml in any file editor.
- Edit the following sections:
- Logical server name, where the name can be any user-defined name.
- serverType, where the type must be SQL
- serverName, where name must be the SQL Server instance name
- encyclopediaName, where the name must be encyclopedia name as seen in Rational System Architect.
- Workspace ID, where the ID is the numeric value assigned to each workspace. If you have not set up workspaces, type the default
- Name, which must be the name of the workspace in the Manage Workspace menu within Rational System Architect. If you have not set up workspaces, the default name is
Figure 3. Setting up Rational System Architect as a resource provider
You may configure more than one encyclopedia as a resource provider. Simply add another Encyclopedia tag to the
Figure 4. Setting up additional encyclopedias as resources
- Close and Save the file.
- Restart the IBM Rational System Architect REST service.
Figure 5. Restart IBM Rational System Architect REST service
Link Rational System Architect to the Rational Software Architect extension for Design Management
The first step is to create a consumer key within the Design Management extension that can be used by Rational System Architect. The second step is to take this information (the consumer key, the consumer secret, and the rootservices URI), and configure Rational System Architect so that it can connect to and use resources from the Rational Software Architect extension for Design Management server.
Create a consumer key
Log in with Administrator privileges and follow these steps:
- Within a web browser, navigate to https://fullyqualifiedservername:9443/jts/admin.
- Select the Jazz Team Server - Server Administration link.
- Within the Communication section on the left, click the Consumers (inbound) link. Enter a Consumer Name value, such as
- Enter a Consumer Secret value, such as
sadm(this does not have to be the same as the Consumer Name).
- Retype your consumer secret.
- Select the Trusted check box.
- Click Register.
- Copy the generated consumer key, which you will need in the next step.
Figure 6. Register a Design Management extension consumer
Figure 7. Table that lists consumer keys by consumer name
Configure Rational System Architect to use resources from the Rational Software Architect extension for Design Management
To do the second part, you need to follow the steps below:
- Start Rational System Architect and open your encyclopedia (the JK_Enterprises one for this example).
- Select the Tools > Service Provider Configuration.
- Within the Configure Service Provider dialog window, under Servers Established, select Add.
- Within the Register Service Provider dialog window (see Figure 8), enter these details from the Design Management extension:
- Name. Enter the same name as provided for Consumer Key. This does not need to be the same.
- Root Service URL. Copy and paste from Design Management in the section where you created the Consumer Key, for example:
- Consumer Key. Copy and paste from the Rational Software Architect extension for Design Management in the section where you created the Consumer Key, for example:
- Consumer Secret. Enter the same value that you entered within the Design Management Consumer Key section, for example:
Figure 8. Register Service Provider dialog window
- Click Register.
Create project collaboration links
Now that a connection to the Design Management server is established, you need to create a collaboration link so that Rational System Architect recognizes which project in Rational Software Architect you want to link artifacts to.
- Still in the Configure Service Provider dialog window, within the Collaboration Links section, select Add. You will be prompted to choose a service.
- From the drop-down menu in List of Service dialog window (Figure 9), select sadm (the name of the Service Provider that you registered earlier). If you receive a Security Alert dialog to state that you want to proceed click Yes.
- Within the Authorize dialog window, enter your Rational Software Architect extension for Design Management user ID and password, and select Log in. If you are prompted to allow this collaboration, select Yes.
- Select your project from the Architecture Management section, and click Add.
- Click Close to close the Configure Service Provider dialog window.
Figure 9. List of OSLC service providers
Configure Rational Software Architect extension for Design Management to talk to Rational System Architect
In this section, you will configure the Rational Software Architect extension for Design Management server to communicate with the Rational System Architect repository. Then you will create a link between your project area on the Rational Software Architect server and the actual encyclopedia in Rational System Architect.
Link Rational Software Architect with Rational System Architect
- Log in to the Rational Software Architect Design Management extension, and navigate to the admin page at https://fullyqualifiedservername:portNumber/jts/admin.
- Click the server link at the top of the page, and in the Server Administration view, you should see the server properties Status page.
Figure 10. Rational Software Architect extension for Design Management server properties
- Click the Friends (Outbound) link on the left side, and choose Add to the friends list.
- In the Add Friend dialog window (Figure 11), provide the following information:
- A name for the link (for example,
Rational System Architect)
- The root services URI for Rational System Architect:
- A keyword for the secret (for example,
- Click the Trusted check box.
- A name for the link (for example,
Figure 11. Link Rational Software Architect extension for Design management and Rational System Architect
- Click Create Friend, and then click Next.
- In the Authorize Provisional Key screen, click Finish.
Figure 12. Finish creating the friend request
You should now see the friend relationship on the friends list, which means that the Rational Software Architect server is linked to Rational System Architect. After this is created, you're now ready to link your project area to your encyclopedia in Rational System Architect.
Link a project area to an encyclopedia
- Navigate to the Rational Software architect Extension for Design Management admin page at https://fullqualifiedservername: portNumber/jts/admin.
- In the application Administration section, click the Project Areas link under Design Management (/dm).
Figure 13. Manage project areas
- In the list of projects, click the one that you want to link to, and you should see the project area Administration screen next.
- Scroll down, and in the Associations section, click Add.
- In the Add Association dialog window (Figure 14), choose Rational System Architect from the application drop-down menu (when prompted to log in , use your Windows login credentials). Then, from the Artifact Containers list, choose whichever Rational System Architect encyclopedia you want to connect to.
Figure 14. Connect a project area to an encyclopedia
- Click OK in the Add Association window.
- Click Save in the Project Area page.
The Rational Software Architect extension for Design Management project is now linked to the Rational System Architect encyclopedia. You can now link model elements to enterprise architecture elements, as illustrated in the sections that follow.
Linking from Rational Software Architect extension for Design Management to Rational System Architect
Now that the servers and projects are linked, you can start to link your software architecture with your enterprise architecture. This is useful for two primary reasons:
- The link makes it very simple and efficient, because the architects can simply click the link to navigate to the relevant portion of the enterprise architecture (EA). They don't need to go to another tool and search the EA to understand the context of what they're building and any constraints that the enterprise architecture might place on their design.
- With the links in place, you can also visually browse and analyze the relationships, and identify those design elements that should be linked to the EA but aren't.
Create links between the applications
- In the Rational Software Architect extension for Design Management, navigate to the web interface, https://fullyqualifiedservername:portNumber/dm/web, and select the project area that is connected to Rational System Architect.
- Then, view the models by clicking the Models link.
Figure 15. Reservation System model view in Design Manager
- Now navigate to a model element that should be linked to an element in the enterprise architecture, and double-click on it to open its description.
- Click the Links tab (see Figure 16).
- Click Add, and choose Elaborates. (If you don't see the Elaborates link types, go to project properties from the Administration drop-down menu, and deploy the predefined link types from the Project Linking page).
Figure 16. Add a link to a model element
- In the Add Link dialog window (Figure 17), choose the Rational System Architect project from the drop-down menu, and log in with your Windows credentials.
Figure 17. Choose the enterprise architecture project
- Click Browse, and then select from the options:
- Choose whether it's a definition or a diagram.
- Select the type, and then search for the element (or use the wildcard symbol *).
- Select the element that you wish to link to, and click OK.
Figure 18. Choose model elements from Rational System Architect
- In the Add Link window, click OK, and verify that the relationship is added to the model element in Design Management extension.
- Click Save on the model element details pages.
In this section, you will explore how you can view and navigate to the links after they have been set up, so you can understand what is and what isn't linked to elements in the enterprise architecture.
- With the model element that you just connected to an element in Rational System Architect still open, create a new relationship diagram by clicking the Relationship Explorer symbol at the top-right of the screen.
- Select the element, and click the green plus sign that appears on the relationship diagram toolbar .
You should now see a diagram that shows the element's relationships, including its relationship to the architecture element in Rational System Architect.
Figure 19. Relationship diagram
- Now select the Rational System Architect element (in this case, the Reservation System), and choose preview from the toolbar to see a rich hover view that provides high-level details of the element.
Figure 20. Rational System Architect rich hover feature
- Now open the System Architect artifact by clicking the open element icon on the toolbar. This will open the element in Rational System Architect XT.
Figure 21. Navigation to the element in Rational System Architect XT
Link from Rational System Architect to Rational Software Architect extension for Design Management
As an enterprise architect, you might be interested in understanding the design details behind a system that is represented in the enterprise architecture. Or you might be interested in analyzing which elements of the enterprise architecture are realized by detailed software designs and, perhaps more importantly, which elements are not realized. The following sections show the mechanics of creating a link from a Rational System Architect element to a design in Rational Software Architect and then how you can navigate and analyze those relationships.
Create links from Rational System Architect to the Rational Software Architect extension for Design Management
Now that the configuration is finished, you can start creating OSLC links from Rational System Architect into Rational Software Architect.
- Start Rational System Architect and open your encyclopedia (for this example: JK_Enterprises).
- Locate the artifact that you want to link to Rational Software Architect. For this example: Reservation System, Architecture Building Block Definition.
- Right-click the artifact and select Link to Architecture. If you are prompted, select Continue to this website.
- Enter your Design Management user ID and password, and select Log In.
- In the Create Link dialog window (Figure 22), in the "Search for these words..." field, enter
Reservation,and then select the magnifying glass search icon to the right of the search text.
Note: You can use the drop-down list at the start of the search text box to change the search criteria from All Model Content to All Diagrams.
- Within the Matching Model Resources filter field, enter
Componentto show just the matching components. You should see a single item result, in a tabular format.
- Select the ReservationSystem radio button, and click OK.
Figure 22. Create Link dialog window
- You will see a red link icon next to the artifact within the explorer view of Rational System Architect. Hover your mouse cursor over this link icon, and you will see the linked artifact within a rich hover view.
Figure 23. Rational System Architect rich hover view of the artifact
- You can select the Details link to view the full artifact within the Design Management extension.
Create Rational System Architect reports
Having linked enterprise artifacts to solution artifacts, you can now create a tabular report by following these steps:
- Within Rational System Architect, select Reports > Report Generator, and click Add.
- (Optional) Provide a Report name and Description.
- Select HTML for the Report Type.
- Enter a path and file name for the Output file.
- Select HTML Tables.xsl for the Style sheet.
- In the first drop-down menu, select Definitions.
- Select Where, deselect All types, and select Architecture Building Blocks from the list, click the partial check box, and then click OK.
- Select Properties to Print and, from the Available properties section, select Name and Type (by holding the CTRL key), select Add, and click OK.
- In the second drop-down menu, select Links to external Definitions.
- Select Properties to Print and, from Available properties, select Name and Type (hold the CTRL key), and select Add.
- Highlight each property and change the order so that the order suits you, and then click OK. For example:
- Provider Type
- Link Type
- Project Name
Figure 24. Rational System Architect OSLC report options
- Select Generate to display the report within your default web browser. If prompted, check Allow Blocked Content. This report enables you to easily view which of the enterprise architecture elements have corresponding design elements in Rational Software Architect.
Figure 25. Report output lists architecture building blocks linked to solution components
- Close the report by selecting Close in the Reports dialog window.
- Select Yes or No when prompted to save the report file.
Create a Rational System Architect explorer diagram
You can also use System Architect Explorer diagrams to graphically analyze the relationships between enterprise artifacts and solution artifacts by following these steps:
- Within Rational System Architect, select File > New Diagram.
- From the available list, select Explorer, and then click OK.
- Enter a name and select OK.
- Within the TOGAF 9 Viewpoint property, select Choices, and then select and drag the Generic Explorer Diagram into the field, and click OK.
- Locate the Reservation_System component definition type within the Explorer window, and drag it into the diagram workspace.
- Select Dictionary > New Definition.
- From the options, select Explorer Object Report, and click OK.
- Enter a name (for this example,
OSLC links), and click OK.
- Select Edit Content.
- In the first drop-down menu select Definitions, and then select Where.
- Clear All types and, from the list, select OSLC Link.
- Then click OK, OK, OK.
- Navigate to the newly created OSLC links Explorer Object Report definition type within the Explorer window, and drag this report definition onto the diagram.
- Right-click on the reservationSystem OSLC Link definition type on the diagram, and select Show Immediate Relatives.
- A line drawn between the two objects on the diagram shows that the relationship exists.
- If you hover your mouse cursor over the OSLC link symbol on the diagram, you will see a rich hover summary of information from Rational Software Architect Design Manager and a details link that you can use to navigate to the Rational Software extension for Design Management web user interface.
Figure 26. Explorer diagram
By integrating Rational System Architect and Rational Software Architect, you save time because you can accomplish more in three key ways:
- Easily create links between your enterprise and software architectures, which makes it quick and simple to navigate between the two domains.
- Use the graphical capabilities of both tools to help you understand the relationships between your enterprise and system architectures.
- Use the reporting capabilities to document and identify traceability gaps between your enterprise and software architectures.
- Learn more about Rational System Architect
- To learn more about Rational Software Architect:
- Start at the Rational Software Architect family of products page and be sure to check the developerWorks page.
- Also, explore the product overview, the information center for installation and use instructions, and the Rational Software Architect wiki for more resources.
- Check the Rational Software Architect Design Manager and Rational Rhapsody Design Manager page on Jazz.net, and see the Get products section here for links to download the software for free trials.
- Also explore Jazz.net and Open Services for Lifecycle Collaboration (OSLC).
- Browse the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- 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, anytime, and many of the Getting Started ones are free.
Get products and technologies
- Download a free, fully enabled trial version of Rational System Architect.
- Download any of these for a trial at no charge:
- 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.
- Join the discussion in the Rational Development Tools forum on developerWorks and the Using Design Management forum on Jazz.net.
- Get connected with your peers and keep up on the latest information in the Rational community.
- 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.