Lifecycle Integrations with Rational Software Architect and Design Management 4.0
Overview
When we speak of integrations across applications, we are talking about how one application interacts with another application to support a common workflow or activity. In the Rational solution for Collaborative Lifecycle Management (CLM) many applications, each specializing in a particular domain or role, integrate with each other (Figure 1), sharing data and participating in the lifecycle of the resources that are used in the software development process.
Rational Software Architect’s Design Management capability (RSADM) is an application specializing in the management of design oriented resources. These include sketches, UML models and related profiles, business process models, topology models, as well as custom defined resources. Design management capabilities facilitate the collaborative use of these resources enabling them to be commented on, reviewed and linked to other CLM resources. RSADM can manage the full lifecycle of these resources including parallel development scenarios.
Lifecycle Project Administration
RSADM is a Jazz based application that is part of the Rational solution for Collaborative Lifecycle Management (CLM). OSLC and the Jazz platform provide the technical foundation for lifecycle tool integration. It includes the Lifecycle Project Administration (LPA) application, which is an application that simplifies the management of projects across the lifecycle and provides a unified interface for managing related project areas in each of the CLM applications. LPA introduces the notion of a ‘lifecycle project’ which is an aggregation of one or more artifact containers (project areas) from the CLM applications. A LPA project shares a common set of users and manages the integrations and connections between the individual CLM applications. While each CLM application; Design Management, Requirements Management, Change and Configuration Management, and Quality Management still own and manage the lifecycle of their resources in their domain, the LPA provides a simplifying administrative view (Figure 2).
Linking
RSADM is an Open Services Lifecycle Collaboration (OSLC) compliant server. It provides an implementation of the Architecture Management (OSLC-AM) specification. The level of implementation of these specifications is sufficient to enable the linking of a RSADM resource to any OSLC AM, RM, Change Management (CM) or Quality Management (QM) compliant service provider. A summary of the types of links that can be established between resources in the various domains is shown in Figure 3. In addition to these, links can also be created from Rational System Architect, Rational Asset Manager and IBM Business Process Manager to RSADM resources
Each application displays the links between its resources in a manner appropriate for its users. RSADM web client and desktop client allow you to create and visualize links in the context of the resource (diagram or model element) on a separate tab. The Links tab in the web client (Figure 4) is divided up into two parts, the top part contains the links that the resource ‘owns’ or are considered properties of the resource. They point from the resource in context to other resources, often managed by other OSLC applications. The bottom section of the Links tab are the results of queries made to all of the associated OSLC servers, asking them if they have any resources with links to this one. Not all OSLC service providers may support this type of query, so many of the results may be empty. RSADM does support this style of query, and therefore associated projects that are RSADM managed will respond with results.
Linking, from an OSLC viewpoint is not a formal concept, but rather a pattern. It merely indicates that a resource has a property that references another OSLC backed resource (Figure 5). A link in the OSLC is no different than any other property other than it happens to reference another OSLC backed resource like a requirement or change request.
The OSLC does go further to suggest that links themselves can have properties, and describes the mechanism by which this can be done. RSADM supports only one such property, the ability for users to attach a short description of the link itself. It is important to understand that this is a description of the link, and not a description of the resource that is being referenced or referenced by.
RSADM and any OSLC compliant service provider have an underlying public data model that is based on RDF. All model resources that RSADM manages can be requested and represented in RDF. Links appear in these representations as simple triples, with the ‘owning’ resource as the subject and the referenced resource as the object. The predicate of this triple is considered the ‘link type’. It expresses the type of relationship from the subject to the object. The predicate is a URI. As with all good URIs the predicate should be resolvable. A resolvable URI is one that you can put in a browser and get something meaningful back.
RSADM allows you to use and even define any link type you want. The predicate does not even have to be resolvable (although that is preferred). There are limits to the use of custom link types that will become apparent as we look at how RSADM participates in integrations with other specific applications.
The following is an abbreviated example (Figure 6) of a RSADM resource (in Turtle RDF) with two links to requirements of type ‘Derives From’. Each link has a short description associated with the link itself. Notice that no information other than the URI is stored about the referenced requirement.
RSADM and the other Jazz based OSLC applications are, for all practical purposes, web applications and much of their functionality is exercised in a standard web browser. RSADM 4.0 is OSLC Core Version 2.0 compliant. It is possible to create any type of link to any type of OSLC backed resource. What is not specified by the OSLC is how links should be made visible to users of the applications.
Suppose we have two separate OSLC based applications, each with their own user interface. Resource 1 in Application 1 has a link to Resource A in Application A. This link is a property of Resource 1. When Application 1 displays Resource 1 in its user interface the link to Resource A is displayed in one form or another. When Application A displays Resource A in its user interface, it is more difficult to display the link because the link is not stored in Application A. See Figure 7.
This problem of bi-directional visibility of links is not resolved by any OSLC specification. Different implementations deal with it in different ways. Most of the time users want to know what is linked to a resource, in either direction. Presently there are several strategies for bi-directional visibility.
- Store a separate ‘back link’ in the target resource, that points back to the original resource
- Query all known service providers for resources that have a link to the resource you own.
- Establish one service provider as the ‘master’ link owner. Any link between resources on the two servers will always be stored on the one. The other ‘slave’ server will query the master server for links.
- Create a separate application independent of the resource managers to store all links. All applications will use this server to create links and will query this server to find them.
RSADM provides explicit support for the first three in its integrations with RTC, RRC and other RSADM providers. Depending on the type of service provider and its capabilities RSADM will use one or more of these strategies for bi-directional visibility. The fourth strategy requires a separate application to monitor changes in RSADM and other service providers, and is included only for completeness. RSADM does provide a REST service for monitoring changes in resources, and provides a REST service for getting links, however these are beyond the scope of this explanatory article.
Back Linking
The back link strategy is used by the first generation Jazz applications and is still used by exclusively by RTC and RQM (Figure 8). A back link is stored no differently than any other link. It is a simple triple that represents a property on a resource whose object is the URI of an OSLC managed resource. The predicate of this triple is the link type. It is important, when managing back links that forward and back link types are paired. This is necessary to facilitate link management. When a user creates or deletes a link the applications must ensure that the appropriate forward or back link is also created or deleted.
There are limitations with this strategy, not the least of which is authorization and edit permissions on separate application servers. For example suppose a user of Application 1 deletes the link from Resource 1 to Resource A in Application A, but that user does not have any permission, or even an account on Application A. The user has permissions to delete the forward link in Application 1, but is unable to delete the back link in Application A. Similar issues with latency, and network outages could result in the loss of link integrity with dangling forward or back links.
One advantage of back linking is the efficiency that an application can construct a user interface. With back linking an application does not have to go over the wire and query other applications for link information. It is stored and retrieved with the resource itself.
Most applications when displaying the properties of a resource, including its links to other resources, will display a human readable label for the link type, and the name or title of the resource it is linked to. Remember that at its core, a link is nothing more than a simple, single RDF triple that contains only the URI of the resource owning the link (subject), the type of link (predicate URI) and the URI of the target (object). If this is all that is stored in the application server then it must make at least two network calls to resolve the link type label and the target resource title to display in the user interface.
To improve performance and provide a little robustness across unreliable networks, an application can cache the name of the link type or name and icon of the resource on the other end of a link. It is reasonably safe to say that link type names are relatively stable and can be safely cached. But this is not the case for resource titles and icons. The name of a resource can and often does change. Assuming resource names are constant for all users, a smart application should update its own cache whenever it sees the resource name change on the owning server.
RSADM’s integration with RTC uses back links. It only supports two link types. In the RSADM user interface they appear as; Elaborates and Related To. In the RTC user interface it appears as Elaborated by Architecture Element and Related To. Both types of links can be created from the RSADM user interface. Only the Elaborated by Architecture Element link type can be created from the RTC user interface. In all of these scenarios the appropriate back link will get created. Similarly when the link is deleted, the back link gets deleted.
The RSADM shows links to RTC work items, alongside all other links on the Links tab of a resource. Figure 9 shows a link from a BMPN diagram to an RTC Task.
In the RTC user interface links are also displayed with all other links. Figure 10 shows the link from an RTC work item to a RSADM diagram.
Master Server
Another strategy for bi-directional visibility of links between two different applications is to designate one as the ‘master’, to which all links are created and managed. This means that between any two service providers, one of them manages the resources that are always the ones that contain the link property. The other application queries the master service provider for links, and then displays them in its user interface (Figure 11).
RSADM uses this integration strategy with RRC 4.0, Rational DOORS Next Generation Beta and DOORS 9.4.0.1. RSADM’s integration with these applications, like that with RTC is limited to specific link types. In the case of RRC, the link type Derives is used. It appears in the RSADM user interface as ‘Derives From’ (Figure 12), and in the RRC user interface as ‘Derives’ (Figure 13).
The advantage of this strategy is that there is only one triple stored in one of two applications. There are no maintenance issues when it comes to deleting the link. If the link is deleted by the master server, then it no longer exists in either context. If the user uses the ‘slave’ application’s user interface to delete the link, that application in turn requests the link to be deleted from the ‘master’ server.
This strategy only works when it is obvious which service provider is the master and which is the slave. It also requires the master server to implement some form of query. In this case RSADM implements enough of the OSLC Core Simple Query specification to permit RRC to use this public service to query for ”all RSADM resources that have a ‘Derives From’ relationship to the given RRC resource”. The results of this query populate the links section in the RRC user interface.
The RSADM integration with DOORS 9.4.0.1 also uses this strategy however DOORS supports more than one link type. It supports the SysML defined types; Refines, Satisfies, and Trace.
Query for Incoming Links
The most dynamic integration strategy supported is between RSADM and other RSADM servers. In this integration each instance of RSADM uses the OSLC Simple Query service to determine the incoming links to the current resource of interest. When RSADM displays the links from a resource in its web user interface, it first displays all the links ‘owned’ by the current resource grouped by link type. Each link is displayed with its name, icon (if available) and optional link description. This integration is not limited to only specific link types. Any custom link type will appear on the resource’s links page (Figure 14).
RSADM does not cache linked resource names or icons. This is true for all RSADM integrations. Therefore each time a link is displayed it requests, behind the scenes, the UI preview document of the target resource to get its name and icon. The UI preview is described in the OSLC Core specification and has been adopted by the AM, RM, CM and QM specifications. It describes the resource format and protocol for getting quick information about a managed resource. Normally the UI preview is used to display hover help on a resource. RSADM uses this same mechanism to get the current name and icon for a referenced resource on the owned links page (Figure 12).
Since many links are to resources managed on other servers, they may have different access or authorization credentials. Therefore it is possible for the user to not be authenticated with the other server when the links are displayed. If RSADM can not automatically get the UI preview to resolve the name and icon for the referenced resource, it will display the raw URI of the referenced resource, and provide a log in link that the user can authenticate through, and thus enabling the resolution of the UI preview. This is true for all links, not just RSADM to RSADM links.
Below the owned links section, are expandable sections, one for each associated project. In each are the results of a query to that associated project’s simple query service asking if that server has any resource that has any type of link to the current RSADM resource. Unfortunately not all OSLC service providers support this type of query. In fact at this time only RSADM supports the special of OSLC Simple query necessary to express this. When other applications begin to support this form of query, RSADM will leverage and use the information in its incoming links sections.
When links are discovered via this query, the link type may or may not be known to RSADM. If the link type is known then its human readable label is displayed. If not then the last segment of the link type URI is used as the label.
UI Preview
Rich hovers provide quick access to information to determine if additional details are required. Figure 15 shows the UI preview of a RSADM diagram resource, as seen in RTC UI, which is linked to a RTC work item.
Tracked Resource Set
RSADM supports another emerging specification: the Tracked Resource Set (TRS). This specification is like an RSS feed of changes published by an OSLC server. Whenever an OSLC service provider’s resources change (including creations and deletions), the event is published through this service. The service only identifies that something has changed; it does not publish the details of the change. If a consumer of this service is interested in exactly what changed in a resource it will explicitly GET a representation of the resource via the OSLC service.
A client application could keep track of changes to all resources across a number of OSLC service providers. If it also GETs the resource’s representations it has an opportunity to track and index all links in resources across domains and applications. The details of any client application performing this type of indexing of resource links is beyond the scope of this article. We only state here that RSADM supports this emerging specification, thus providing another mechanism for managing and viewing the bi-directionality of OSLC links.
Impact Analysis
RSADM’s impact analysis capabilities enable users to view graphs of interconnected resources and relationships not only within the modeling domains it manages but also includes links to OSLC resources it doesn’t manage. Impact analysis is a RSADM feature that enables the user to construct and work with dynamic diagrams showing the resources and the relationships between them.
An impact analysis is centered on a RSADM resource. Depending on the set of filters selected a different set of resources and relationships will appear in the diagram. This selection of filters is saved as a configuration and can be used in many impact analysis diagrams. OSLC resources appear alongside RSADM managed resources in a different color.
Impact analysis diagrams (Figure 16) are dynamic, and you can expand more levels of nodes and remove nodes to help focus on the important relationships and resources.
Reporting
IBM Rational Publishing Engine’s Document Studio is used to create report templates that are uploaded to RSADM and run to generate reports on RSADM managed resources. Anyone with appropriate permissions can run, view and store the results of a report. The report can include resources and relationships to resources on other CLM servers, including requirements in RRC, associated work items in RTC and associated test cases and test plans in RQM.
The sample report shown in Figure 17 includes some information that comes directly from the other CLM service providers and mixes it in with content from the RSADM and other service providers.
Summary and Next Steps
Design Management is an application that works with other applications at multiple levels. It integrates with other OSLC based service applications, leveraging the specifications and protocols to facilitate linking across domains and applications. The OSLC defines how user interfaces can show previews of resources linked to on other servers, and enable browsing and selecting of resources on other servers. RSADM has tighter integrations with key applications like RRC, DOORS and RTC that enable bi-directional visibility and management of links. Finally impact analysis and reporting capabilities include references to resources linked to on other servers. In general RSADM is an integrated life cycle tool for managing designs and their relationships to the other key life cycle resources of the software development process.
The Design Management project on jazz.net offers a 60 day trial so you can download and try it out. Additionally the library section on jazz.net contains articles, videos and other resources you may find helpful in learning more.
Copyright © 2012 IBM Corporation