Integrate your enterprise and software architectures

Steve Arnold and Jas Atwal walk you through integrating enterprise architecture stored in IBM Rational System Architect with model elements stored in the Rational Software Architect extension for Design Management. Then they show how to use the integration to save time by easily navigating between the enterprise and system elements and how to spot traceability gaps and to visualize the relationships.

Share:

Steve Arnold (steve.arnold@uk.ibm.com), Senior Technical Consultant, IBM

photo of Steve ArnoldSteve lives in Twickenham, London, with his wife and young daughter.  Professionally, he has worked as a technical consultant for IBM Rational software since 2000, where he is a certified scrum master specialising in agile project delivery, modeling, and patterns-based engineering. Outside of work, he enjoys spending time with his family and also studying, teaching, and practising tai chi.  He has written several articles covering the latest features in Rational Software Architect 7.5 and 8, as well as articles discussing various extensions to Rational Software Architect, Rational RequisitePro, and Rational Team Concert.


developerWorks Professional author
        level

Jas Atwal (jas.atwal@uk.ibm.com), Technical Consultant, IBM

Author1 photoJas Atwal has lived in Royal Leamington Spa all of his life and can speak two languages. Jas completed his BSc degree in Accountancy at Cardiff University and then went on to complete his MSc in Information Technology for Management. After graduating from university, Jas joined Popkin Software, working with Rational System Architect within the enterprise architecture domain. Jas has over a decade of experience working with enterprise architecture solutions and currently works as a client technical professional within the Rational division of the IBM Software Group. You can reach Jas by email or on Linked in.



22 January 2013

Also available in Russian

Overview

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

  1. 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
deployment topology

Starting everything

After you've got everything installed, you need to start everything.

  1. Start Rational Software Architect Design Manager by selecting Start > All Programs > Rational Design manager > Start the Jazz Team Server.
  2. 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
Services (Local) list
  1. 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.
  2. 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:

  1. Navigate to the Rational System Architect installation folder:
    C:\Program Files (x86)\IBM\Rational\System Architect Suite\System Architect
  2. Open the SAServerConfiguration.xml in any file editor.
  3. 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 WorkspaceID="1".
    • 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 "Root".
Figure 3. Setting up Rational System Architect as a resource provider
Rational System Architect server configuration XML

You may configure more than one encyclopedia as a resource provider. Simply add another Encyclopedia tag to the <Encyclopedias> section.

Figure 4. Setting up additional encyclopedias as resources
another encyclopedia tag added
  • Close and Save the file.
  • Restart the IBM Rational System Architect REST service.
Figure 5. Restart IBM Rational System Architect REST service
Screen capture, Microsoft Windows local services

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:

  1. Within a web browser, navigate to https://fullyqualifiedservername:9443/jts/admin.
  2. Select the Jazz Team Server - Server Administration link.
  3. Within the Communication section on the left, click the Consumers (inbound) link. Enter a Consumer Name value, such as sadm.
  4. Enter a Consumer Secret value, such as sadm (this does not have to be the same as the Consumer Name).
  5. Retype your consumer secret.
  6. Select the Trusted check box.
  7. Click Register.
  8. Copy the generated consumer key, which you will need in the next step.
Figure 6. Register a Design Management extension consumer
Dialog window for creating a consumer key
Figure 7. Table that lists consumer keys by consumer name
also lists functional user ID and trusted status

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:

  1. Start Rational System Architect and open your encyclopedia (the JK_Enterprises one for this example).
  2. Select the Tools > Service Provider Configuration.
  3. Within the Configure Service Provider dialog window, under Servers Established, select Add.
  4. 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:
      https://fullyqualifiedservername:9443/dm/rootservices
    • 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:
      2cddf3486af146ff90f866e2ba6d42a2
    • Consumer Secret. Enter the same value that you entered within the Design Management Consumer Key section, for example: sadm
Figure 8. Register Service Provider dialog window
Information entered as described
  1. 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.

  1. Still in the Configure Service Provider dialog window, within the Collaboration Links section, select Add. You will be prompted to choose a service.
  2. 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.
  3. 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.
  4. Select your project from the Architecture Management section, and click Add.
  5. Click Close to close the Configure Service Provider dialog window.
Figure 9. List of OSLC service providers
List of Service window

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

  1. Log in to the Rational Software Architect Design Management extension, and navigate to the admin page at https://fullyqualifiedservername:portNumber/jts/admin.
  2. 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
Server Administration view
  1. Click the Friends (Outbound) link on the left side, and choose Add to the friends list.
  2. 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:
      http://machine-name:8889/SAOSLC/rootservices
    • A keyword for the secret (for example, sa)
    • Click the Trusted check box.
Figure 11. Link Rational Software Architect extension for Design management and Rational System Architect
Information added in the Add Friend window
  1. Click Create Friend, and then click Next.
  2. In the Authorize Provisional Key screen, click Finish.
Figure 12. Finish creating the friend request
Authorize Provisional Key screen

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

  1. Navigate to the Rational Software architect Extension for Design Management admin page at https://fullqualifiedservername: portNumber/jts/admin.
  2. In the application Administration section, click the Project Areas link under Design Management (/dm).
Figure 13. Manage project areas
Manage Applications view for Design Management
  1. In the list of projects, click the one that you want to link to, and you should see the project area Administration screen next.
  2. Scroll down, and in the Associations section, click Add.
  3. 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
JK_Enterprises_1 encyclopedia selected
  1. Click OK in the Add Association window.
  2. 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

  1. 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.
  2. Then, view the models by clicking the Models link.
Figure 15. Reservation System model view in Design Manager
Options: Explore, create reviews or snapshots
  1. 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.
  2. Click the Links tab (see Figure 16).
  3. 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
Links drop-down menu with different types of links
  1. 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
Add Link - Elaborates view
  1. Click Browse, and then select from the options:
    1. Choose whether it's a definition or a diagram.
    2. Select the type, and then search for the element (or use the wildcard symbol *).
    3. Select the element that you wish to link to, and click OK.
Figure 18. Choose model elements from Rational System Architect
Select Model Item dialog window
  1. In the Add Link window, click OK, and verify that the relationship is added to the model element in Design Management extension.
  2. Click Save on the model element details pages.

Explore links

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.

  1. 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 icon for relationships at the top-right of the screen.
  2. Select the element, and click the green plus sign that appears on the relationship diagram toolbar row of toolbar icons.

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
Illustration of relationships
  1. Now select the Rational System Architect element (in this case, the Reservation System), and choose preview icon shows binoculars 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
Rich hover view of reservation system details
  1. Now open the System Architect artifact by clicking the open element icon icon shows a page with an arrow in the corner on the toolbar. This will open the element in Rational System Architect XT.
Figure 21. Navigation to the element in Rational System Architect XT
Reservation System element description

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.

  1. Start Rational System Architect and open your encyclopedia (for this example: JK_Enterprises).
  2. Locate the artifact that you want to link to Rational Software Architect. For this example: Reservation System, Architecture Building Block Definition.
  3. Right-click the artifact and select Link to Architecture. If you are prompted, select Continue to this website.
  4. Enter your Design Management user ID and password, and select Log In.
  5. 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.
  6. Within the Matching Model Resources filter field, enter Component to show just the matching components. You should see a single item result, in a tabular format.
  7. Select the ReservationSystem radio button, and click OK.
Figure 22. Create Link dialog window
Linking to a Rational Software Architect element
  1. 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
OSLC link details
  1. 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:

  1. Within Rational System Architect, select Reports > Report Generator, and click Add.
  2. (Optional) Provide a Report name and Description.
  3. Select HTML for the Report Type.
  4. Enter a path and file name for the Output file.
  5. Select HTML Tables.xsl for the Style sheet.
  6. In the first drop-down menu, select Definitions.
  7. Select Where, deselect All types, and select Architecture Building Blocks from the list, click the partial check box, and then click OK.
  8. Select Properties to Print and, from the Available properties section, select Name and Type (by holding the CTRL key), select Add, and click OK.
  9. In the second drop-down menu, select Links to external Definitions.
  10. Select Properties to Print and, from Available properties, select Name and Type (hold the CTRL key), and select Add.
  11. 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
    • Name
Figure 24. Rational System Architect OSLC report options
Report Generator dialog window
  1. 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
Report Generator results
  1. Close the report by selecting Close in the Reports dialog window.
  2. 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:

  1. Within Rational System Architect, select File > New Diagram.
  2. From the available list, select Explorer, and then click OK.
  3. Enter a name and select OK.
  4. Within the TOGAF 9 Viewpoint property, select Choices, and then select and drag the Generic Explorer Diagram into the field, and click OK.
  5. Locate the Reservation_System component definition type within the Explorer window, and drag it into the diagram workspace.
  6. Select Dictionary > New Definition.
  7. From the options, select Explorer Object Report, and click OK.
  8. Enter a name (for this example, OSLC links), and click OK.
  9. Select Edit Content.
  10. In the first drop-down menu select Definitions, and then select Where.
  11. Clear All types and, from the list, select OSLC Link.
  12. Then click OK, OK, OK.
  13. Navigate to the newly created OSLC links Explorer Object Report definition type within the Explorer window, and drag this report definition onto the diagram.
  14. Right-click on the reservationSystem OSLC Link definition type on the diagram, and select Show Immediate Relatives.
  15. A line drawn between the two objects on the diagram shows that the relationship exists.
  16. 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
Diagram of enterprise and system elements

Summary

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.

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, DevOps
ArticleID=855597
ArticleTitle=Integrate your enterprise and software architectures
publish-date=01222013