Introduction

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.

Back to top

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.

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.

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.

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.

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

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.

Larger view of Figure 5.

2. 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.

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

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.

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.

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).

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.

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.

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.

3. Next, expand the Path Maps section and click Add hyperlink.
4. 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 .
5. 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.

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.

<project name="Example" default="main">
  <target name="main">
    <record name="theExample.log" loglevel="verbose" append="false"/>
    <antcall target="theExample"/>
    …
  </target>
  
  <target name="theExample">
    <echo message="This message will be logged!"/>
  </target>
  …
  
</project>

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:
drive:\installationdirectory\server\conf\dm\processtemplates
where
drive:\installationdirectory
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.

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.)

Back to top

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 is, while the 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.

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.

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

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 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 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.)

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

In the web client, you can click the right arrow 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 () 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 () in the pop-up bubble to show its relationships on the 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).

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.

Back to top

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.

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:
   -Dcom.ibm.xtools.rmpc.ui.RepositoryResourceManager.REPOSITORY_UI_CACHE_SIZE=10

Reminder:
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 at the top-left of the icon in the Project Explorer. (See Figure 20.)

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.

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.

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.)

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.

Note:
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.

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

Back to top

Summary

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.

Back to top

Acknowledgements

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

Resources

Learn

• Get additional information related to this article:
  • For details about Rational Team Concert Ant tasks, and the teamAccept and teamFetch tasks in particular, see the Multiple Stream Development article in the Jazz.net Library.
  • For a more comprehensive reference, see the Jazz build Ant task reference. on Jazz.net.
  • For more information, see the Creating a New Process Template section of the "Getting Started with Jazz Project Areas and Process documentation."
  • Read the Installing the Design Management Server and Server Extensions part of the Jazz technology documentation.
  
  
• To learn more about Rational Software Architect, start at the developerWorks page. Also explore the product overview and the information center, where you'll find installation and use instructions.
  
  
• Learn more about the Rational Design Management project for collaborative architecture design and analysis.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  
  
• 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 the Rational Software Architect Design Manager for evaluation (and be sure to check for updates).
  
  
• Download either or both versions of Rational Software Architect for a trial:
  • Rational Software Architect Standard Edition
  • Rational Software Architect for WebSphere Software
  
  
• 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.
  
  

Discuss

• Join the discussion in the Using Design Management forum on Jazz.net.
  
  
• Share your knowledge and help others who use Rational software by writing a developerWorks article. You'll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website. Find out what makes a good developerWorks article and how to proceed.
  
  
• Follow Rational software on Facebook and Twitter (@ibmrational), 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.
  
  
• Connect with others who share your interests by joining the developerWorks community and responding to the developer-driven blogs.
  
  

About the author

Wayne 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Setting up the server
• Using the web client
• Using the Rational Software Architect client
• Summary
• Acknowledgements
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Software Architect
• Buy: Rational Software Architect

Dig deeper into Rational on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers