25 server and client tips for IBM Rational Software Architect Design Manager

Ways to optimize installing the server and using both clients

One of the developers of the Rational Design Management option offers tips and tricks for setting up the IBM Rational Design Management Server with the IBM Rational Software Architect Design Manager Server Extension and using both with either the web client, which is installed automatically with the server, or the thick client, called the IBM Rational Software Architect Design Manager Client Extension. The thick client is installed into the same package group as an existing IBM Rational Software Architect installation. The first part of the article, Set up the server, is intended for server administrators, while the second and third parts of the article, about using the web client and the Rational Software Architect client, are intended for users.


Wayne Diu, Software developer, IBM Canada

Wayne DiuWayne Diu is an advisory software developer at IBM Rational. He has worked on designing and implementing UML modeling features for the Rational Modeling Platform, and he was one of the developers responsible for creating the metamodel integration framework. He has been involved with a diverse collection of other features, such as printing, validation marker enhancements, and refactoring support. Wayne was also one of the developers for the Design Management option, which this article is about.

developerWorks Contributing author

02 August 2011

Also available in Chinese Russian


This article covers tips and tricks to help you with optimal setup of the IBM® Rational® Design Management Server with the IBM® Rational® Software Architect Design Manager Server Extension. Then it describes using both with either the web client, which is installed automatically with the server, or the thick client, called the IBM Rational Software Architect Design Manager Client Extension. The thick client is installed into the same package group as an existing IBM Rational Software Architect installation.

The first part of the article, Setting up the server, is intended for server administrators, while the second and third parts of the article, Using the web client and Using the Rational Software Architect client, are intended for users.

Setting up the server

1. Obtain an SSL certificate

Before even starting to install the server, apply for an SSL (secure socket layer) certificate. The application can take some time, and, after that, it has to be installed on the server. If you don't have a valid certificate, all of the functionality of the server will still be available. However, people connecting to the server using web browsers will see certificate errors, and the security of your data will be diminished, as Figure 1 shows.

Figure 1. An example of a security warning in Microsoft Internet Explorer 8
Web page titled Certificate Error

2. Use the setup wizard

You can set things up manually, but the easiest way to get up and running quickly is to go to https://servername:port/jts/setup and use the setup wizard. (Typically, the port should be 9443.) If this is your first time experimenting with the server, I recommend that you go through all of the steps of the wizard by clicking the Next button. Do not click Finish prematurely, because the next-to-last step, Create Sample Project, is highly recommended (see Figure 2). If you skip this step, you'll need to create projects yourself to use the Design Management server.

Figure 2. The Create Sample Project step
Jazz Team Server and Application Setup screen

3. Disable the ADMIN access

By default, the administrator username and password are both ADMIN. If you run the recommended setup wizard, you will be prompted to disable this account. If you choose not to disable the account during the setup process, please disable it manually later, or at least change the password.

4. Understand how administration tasks are grouped

It's important to understand how administrative tasks are grouped. Some are part of the Jazz Team Server (JTS) interface, while others are part of the Design Management application. Settings that affect the entire server, including the server's list of authorized users, the friend servers (other servers that your server can communicate with), and the type of back end database are all part of the JTS admin pages, accessible from the Jazz Team Server Administration section of https://servername:port/jts/admin (see Figure 3). JTS settings should be configured before the application-specific settings.

Figure 3. The Server Administration page includes an Application Administration section
Jazz Team Server Administration Home page

Settings that make sense only in the context of the Design Management application, such as the permissions a user has in a given project, the link types (used for defining links to friend servers), and the actual model contents stored in the back end database are accessible in other locations. These locations include the Application Administration section of the JTS admin pages and hyperlinked web pages within the project area itself. (Strictly speaking, user management and license management are also available from the Application Administration pages, but it is helpful to think of them as being there more for convenience than as correct categorization.)

The next three tips go through these three examples in detail:

  • Setting up permissions
  • Setting up CLM links
  • Importing the model contents

5. Adjust permissions properly

  1. To manage users, go to https://servername:port/jts/admin, and, from the Jazz Team Server Administration section, click the Jazz Team Server - User Administration hyperlink. Be sure you assign users appropriate repository permissions and the appropriate client access license.
    Note:Actual users should never be assigned the DM Application – Internal license.

After adding a user and assigning the Rational Software Architect Design Manager – Design Manager license or Rational Software Architect Design Manager – Design Reviewer license, it's easy to forget the extra step that is required to give the user access to a Design Management project.

  1. To add a user to a project, go back to the Jazz Team Server Administration Home page.
  2. In the Application Administration section, choose the Project Areas hyperlink under Design Management.
  3. Then select the desired project in the Active Project Areas section of the page.
  4. Make sure to add the user under the Members or Administrators section.
Figure 4. The Active Project Areas page, accessible from the Project Areas link on the Jazz Team Server admin page
Active Project Areas web page

Why is this step necessary? First, not every user should have access to every project. Also, in the future, there might be applications other than the Design Management application on the same JTS server. Access control on a project level will be particularly important then.

6. Learn how to set up CLM links

There are three main parts to setting up links for Rational® Collaborative Lifecycle Management (CLM).

Specify the friend server

  1. As discussed earlier, the friend server must be specified. This is done by going to the JTS admin home page, and then clicking the Jazz Team Server – Server Administration hyperlink. Click Friends (Outbound) in the menu at the left, and add the server you wish to be able to create links to.
Figure 5. Adding a friend server
Add Friend pop-up window

Larger view of Figure 5.

  1. After you add the friend server, you're prompted to log on to the other server and authorize your request. It doesn't matter if you're unable to do so (perhaps because you do not have the password). You or someone else who has access to that server can do this later by going to the Server Administration page of the friend server, and then clicking Consumers (inbound) in the menu at the left. You (or whoever logs into that server) will be given the opportunity to accept or deny the request.
Figure 6. Authorizing the inbound request
Authorize Provisional Key pop-up window

Larger view of Figure 6.

The second and third steps are application-specific, so they are not accessible from the hyperlinks in the Jazz Team Server Administration section.

Link your project to an artifact container


If you encounter an error while setting up links between different servers, ensure that the time settings of both servers are identical, and then try again.

The second step is to set up linking to a particular server from your project.

  1. From the Jazz Team Server Home page, in the Manage Applications section, click the Project Areas hyperlink.
  2. Select a project area, and then locate the Associations section and click Add hyperlink to add support for linking to the chosen artifact container. You can think of an artifact container as a project that contains artifacts of a certain type.
  3. Use the pop-up dialog window to choose the type of association for the link, which is either Uses or Provides.
Figure 7. Adding support for linking to the chosen artifact container
Add Association pop-up dialog window

Larger view of Figure 7.

Set up the link types that appear in the UI

The third and last step involves setting up the actual link types that will show in the UI when the end user adds a link.

  1. You must first navigate to the project area to set up CLM links (shortcut: https://servername:port/dm/web/projects/YourProjectArea#action=jazz.viewPage&id=rmps.app.settings).

The Project Linking page is in the Project Properties of a particular project. You can access the Project Properties from the menu at the top of the web page.

Figure 8. The menu to allow showing the project properties
Drop-down menu for Project Properties

When you set up a link, you can also set up the creation of "reverse links." Why do you want to link in both directions? Suppose you are designing an application, and you notice that the sequence diagram for the logout process reveals serious issues. You then submit a work item in IBM® Rational Team Concert™. If you were to create a link from this operation to the work item in Rational Team Concert, it would also be convenient for a link from the work item to your sequence diagram to be automatically created.

7. Import models from different machines onto a server

In the IBM Installation Manager, you might have noticed that the import engine is installed separately from the server. There is a reason for this: the import engine does not have to be installed and running on the same machine as the server. This enables you to import models that are not on the same machine as the server, or even to have multiple import engines running on different machines, which is useful when you have multiple project areas. Therefore, when entering the workspace path in the Import Definition web page, be sure to enter the path to the models that the import engine is running on.

How does the server figure out which import engine to use? This is defined by the engine name, which you must specify in both the Rational Software Architect Import Engine Configuration details and the Import Definition pages (Figure 9).

Figure 9. The import engine name, wdiuengine, in both the Import Configuration details and on the Import Definition page
Screen captures of both screens

Larger view of Figure 9.

8. Tips for importing models

Speed up the import process

In a rush to import your models? Ensure that the Validate model contents check box is cleared on the Request Import page.

For simple models, you might not notice much of a difference in the time taken by the importer, but for more complex models, the time difference can be substantial.

Keep in mind that basic validation for broken references is still performed, regardless of whether the Validate model contents check box is checked.

Figure 10. The Request Import page with no check boxes checked
Request Import screen

Larger view of Figure 10.

Solve broken references in imported models

If you have lots of broken references, it is likely that you missed importing some projects or you forgot to specify a path map. Path maps from Rational Software Architect are constants that help prevent broken references when opening models in different environments when the dependency has moved to a different location.

  1. To figure out what constants should be included, open your workspace in Rational Software Architect .
  2. Choose Window > Preferences > Modeling > Path Maps. Make a note of the path variables.

In Figure 11, the "Available path variables" pane of the Path Maps section in the Preferences page shows a custom path map named SHARED_PROFILES pointing to C:/shared/CustomProfiles.

Figure 11. Path Maps section shows available path variables
Preferences view, Path Maps section

Bonus tip:
Back to the Import Definition web page: If you chose the Import an entire workspace option, ensure that the corresponding project is in your workspace. If it isn't, you'll either need to open your workspace in Rational Software Architect and add the referenced project to your workspace or click Delete Import Definition and choose the Import individual projects option. Make sure that you include the referenced project this time.

  1. Next, expand the Path Maps section and click Add hyperlink.
  2. In the Variable column, enter the name of the path map. It must correspond to the name in the Path Maps Preferences page of Rational Software Architect .
  3. In the Value column, enter the name of the project imported to the server. Do not enter the directory name, such as C:/shared/CustomProfiles, as specified in the Path Maps preference page of Rational Software Architect .

Bonus tip:
If you chose the Import individual projects option, be sure to enter the project name as it appears in the Project Name to Use After Import column.

Figure 12. Specifying a path map
Import Definition page

Larger view of Figure 12.

Run an Ant script during the import process

You might have noticed an option on the Import Definition page to run an Ant script. The script is executed before importing resources onto the server. A typical use of this is to retrieve the latest code from the repository into the workspace before importing. This is particularly useful in conjunction with scheduled imports.

Ant script tips

A comprehensive guide to Ant scripting is beyond the scope of this article, so here are a few pointers:

  • For more details on Rational Team Concert Ant tasks, and the teamAccept and teamFetch tasks in particular, see the Multiple Stream Development article cited in the Resources section.
  • For a more comprehensive reference, see the Jazz build Ant task reference link in Resources.
  • It is helpful to log the progress of the Ant script.

Unfortunately, logging the progress of the Ant script is not covered by the references, so I have included a short sample in Listing 1.

The file called theExample.log is created and will be in the import engine's working directory, which is typically C:\Program Files\IBM\RSADMImportEngine on Microsoft Windows systems.

Listing 1. Sample Ant script that demonstrates logging
<project name="Example" default="main">
  <target name="main">
    <record name="theExample.log" loglevel="verbose" append="false"/>
    <antcall target="theExample"/>
  <target name="theExample">
    <echo message="This message will be logged!"/>

9. Understand process templates

When you create a new project (rather than using the default Sample Project), you'll be prompted to set a process template. You can either define the process templates yourself (see the "Creating a New Process Template" section of the documentation, cited in Resources) or use the two standard process templates that are included with the software. On a Windows system, they are installed by default to:
is C:\Program Files\IBM\DesignManagement

The key things to pay attention to when using different process templates are the roles and the default permissions.

  • The Basic Process Template, which is installed by default in the Sample Project (optionally created during the setup process), has no predefined roles, so everyone who is a member of that project can do almost anything (import models, add comments, and so forth).
  • However, for a real project, you would typically have users with defined roles. The Default Process Template includes Architect, Commenter, Publisher, and Project Lead roles, each with their own permissions, so it is more suited for a real project.

You can see and adjust the permissions from the Permissions tab of a project area's page.

  1. First, click Project Configuration or Team Configuration in the Configuration table on the left.
  2. Then, click on a role in the Roles list to see the Permitted Actions tree updated.
Figure 13. The Permissions tab of a project area administration page
Project Area administration page

Larger view of Figure 13.

Bonus tip:
If you created another project identical in every way to the Sample Project except the process template, you are likely to encounter permission problems when performing the same actions while logged in as a user with the default process roles. In addition to what was mentioned in the Adjust permissions properly section, be sure to define process roles in the Overview tab of the project area page. (The button appears when you hover the cursor over a row under the Actions column.)

Using the web client

Be sure to read the sections on both clients, because some tips are mentioned in only one section but explain how to accomplish the same task in the other client.

10. Get information at a glance

You can add your own dashboards and widgets for each project. The option to add the widget is hidden where the down arrow icondown arrow is, while the plus sign icon plus sign is used to add a new tab to contain additional widgets. These widgets pertain to Design Management: recent comments, recent links, reviews, top resources, validation, and a "Welcome" widget.

Figure 14. An initial Design Management dashboard for a new project
Dashboard example

Larger view of Figure 14.

11. Add visual comments by sketching on diagrams

You can add text comments to model elements, but when you do so for a diagram, you also have the ability to make a sketch on the diagram to further illustrate your point. You'll know that you can sketch when the diagram background becomes light blue and the tools in the palette can be used.

iconThis tip applies to the Rational Software Architect client, as well.

Figure 15. The diagram background becomes light blue when sketching is enabled
Diagram with blue background and sketch

Larger view of Figure 15.

12. Show the missing elements in the Explorer

Are you wondering what happened to all of the lifelines in an interaction? By default, elements that are not top-level elements are not shown. To show them, click the down arrow icon down arrow in the Explorer and choose Show Resource Contents.

Furthermore, the filter named Hide unnamed elements is enabled by default. To disable this filter, click the down arrow icon down arrow in the Explorer and choose Filters. (To adjust the filter settings for all users, choose Project Properties from the top toolbar, followed by Explorer Filtering in the left menu.)

icon In the Rational Software Architect client, you can find the down arrow in the header of the Design Explorer view.

Figure 16. The Show Resource Contents and Filters menu items
Explorer drop-down menu

icon In the web client, you can click the right arrow right arrow icon next to the element name to see its contents.

13. Visually show an element's relationships using relationship diagrams

Relationship diagrams are created by clicking the down arrow (down arrow) next to an element in the Explorer, then choosing the Relationship Diagram… option in the menu.

When a relationship diagram opens, the relationships are not shown on the diagram but only in the text properties to the right of the diagram. Click a shape on the diagram to select the context element, and then click the green plus sign (plus sign icon) in the pop-up bubble to show its relationships on the diagram.

Figure 17. The green plus sign in the pop-up shows relationships on the diagram
Relationship diagram

Larger view of Figure 17.

14. Locate missing comments

Is there a comment that shows in the web client which doesn't show up in the Rational Software Architect client? That's because the web client shows comments for resource contents (such as the comments made on events) when the higher-level resource (such as a package) is selected. However, in the Eclipse client, the comments between these elements are distinguished more: you need to select the contained element to see its comments.

15. Leverage search shortcuts

Looking for a particular type of diagram? Type sequence diagram into the search box (or the name of whatever type of diagram you're searching for).

icon This tip applies to the Rational Software Architect client also.

16. Create snapshots in advance

Make a snapshot before creating a review. This is important because, like imports, the process of creating a snapshot is not instantaneous.

Figure 18. Creating a snapshot
New snapshot web page

Using the Rational Software Architect client

Be sure to read the sections on both clients, because some tips are mentioned in only one section but explain how to accomplish the same task in the other client.

17. Establish a server connection

Connections to the server are added using the Design Explorer view.

To establish your first connection to the server, choose the Click here hyperlink. For subsequent connections, right-click the Server Connections item and choose New Model Repository Connection.

Bonus tip:
If the connection doesn't work:

  • Be sure you enter /dm (and not /dm/web) at the end of the URL.
  • The server is on port 9443 by default.
  • The protocol should be https, not http.
  • Try connecting to the web client using a web browser. This will help you identify intermittent connection problems.
Figure 19. The Design Explorer view before any connections have been added
Create a New Connection dialog

18. Optimize performance by adjusting cache settings for repository resources

Resources obtained from the server are cached to minimize network traffic and improve performance. If you have more free memory, you can increase the size of the cache.

  1. To do so, go to the installation folder (such as C:\Program Files\IBM\SDP) and make a backup of the eclipse.ini file.
  2. Then, in the eclipse.ini file, add the following line to the end of the file:

Be sure to substitute 10 for the desired cache size.

19. Install missing features to optimally display diagrams and properties

You can install the Rational Collaborative Architectural Management Client into Rational Software Architect . But if the feature is not installed and you attempt to open a diagram that requires a particular feature (such as Deployment Planning), you will get a prompt to open the diagram in the web client. To work with additional domains, use the Installation Manager to install the additional required features.

20. Browse elements quickly

The Comments view is linked to elements in the Design Explorer tree and search results. To quickly see the comments for model elements, have this view open when selecting elements from the Design Explorer view or Search (results) view. Also, the Properties view is linked to elements in the Design Explorer tree.

21. Understand workspace links

Workspace links (not to be confused with Collaborative Lifecycle Management links) are used to create a virtual association between a repository resource and the corresponding resource in the workspace. Your workspace is searched for resources corresponding to repository resources, and workspace links are added automatically when connecting to a project. You can add these links manually, but they are mostly unnecessary. Workspace links come in handy if you are working with the local version of a resource and want to add comments or Collaborative Lifecycle Management links to the corresponding resource on the repository.

If you delete a workspace link manually and then restart the application, the same link will not be recreated automatically. You must manually add workspace links that you have deleted.

You can tell whether a workspace element is linked by looking for the link indicator link indicator icon at the top-left of the icon in the Project Explorer. (See Figure 20.)

Figure 20. The link decoration shows that the Use cases model is linked to the repository
Project Explorer view

22. Locate the corresponding web client features

Do you miss the ability to generate a relationship diagrams in the web client?
Just right-click the element in the Design Explorer view or diagram, and choose the Relationship Diagram action.

icon It's available in the Rational Software Architect client, too.

If you found the Comment Dashboard widget from the web client useful, this functionality is also available in the web client. Right-click on a project and choose Search for elements with comments or Search for comments. In the Search view, along with the results, there is a drop-down menu to use to filter results.

icon It's available in the Rational Software Architect client, too.

23. Search for the corresponding workspace element on the repository

Suppose you have a workspace element and want to see if it's on the repository. To make matters worse, it's called "Main," as are many other elements, so doing a text search is out of the question. But you can quickly find an element in your workspace on the repository by going to the Properties view and choosing the General tab. The Repository section includes the resource number and a hyperlink to open the resource in the browser. (If the Properties view is showing the properties of a resource in your workspace, and a workspace link has been created for that resource, the Repository section will contain a hyperlink to show the element in the Design Explorer.)

Figure 21. Use the Properties view to locate the corresponding workspace element in the repository
Properties pop-up window

Also, if you right-click the element in the Project Explorer and choose Modeling References, References on Repository, the resources on the repository that reference the selected resource in your workspace will appear in the Search view.

This context menu item is also available for elements on diagrams.

24. See CLM links

There is a tab for Links in the web client, but where is it also in the Rational Software Architect client? Links can be managed from the Properties view or pop-up window.

Also, it is not possible to set up linking from the Rational Software Architect client. To do so, you will need to use the server, as described previously in the Learn how to set up CLM links section.

25. Generate reports for models on the repository

To enable reporting for repository models, you need Rational Software Architect Version 8.0.2 or later. In particular, although you might see an extra report option in Rational Software Architect 8.0 and Rational Software Architect 8.0.1, there will be no way to select the repository model. For full functionality, you must install the reporting features from the Installation Manager. For UML and BPMN, these are:

  • Architecture Reporting – Architecture Reporting (UML) with BIRT
  • Architecture Reporting – Architecture Reporting (BPMN) with BIRT

Architecture Reporting – Business Intelligence and Reporting Tools (BIRT) will be installed automatically with any of the above.

Reporting for deployment-planning models on repositories is not supported in Version 3.0. For best results, when generating reports for BPMN models on repositories, Rational Software Architect 8.0.3 or later is recommended.

Figure 22. Choosing the features required for reporting from the Installation Manager
IBM Installation Manager window

These three new report templates include details about comments and links on elements in the generated reports:

  • UML Repository Report
  • UML Repository Diagram Report
  • BPMN Repository Diagram Report
Figure 23. New report templates designed for UML models on the repository
Select Built-In Report dialog window


This article covered tips and tricks for getting the most out of the IBM Rational Design Management server and clients. By using these tips, server administrators will be able to set up Design Management servers with a better understanding of how things work, and end users will be familiar with techniques to work with designs more effectively.


The author expresses his gratitude to Anthony Hunter, Cherie Revells, and Dusko Misic for reviewing this article and to Judith Broadhurst for editing.



Get products and technologies



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

ArticleTitle=25 server and client tips for IBM Rational Software Architect Design Manager