Compare Models

Overview

This helper compares models and uses Rhapsody decorations to annotate the differences.

Applicable To	Project, Package
Menu Entry	Power Pack  Compare Models
Demonstration	Watch the Video

Pre-requisites

This helper employs a Rhapsody feature called Decorations to apply icons to the elements in the model browser. This feature can result in very long load times (see the note at the end of this document). To avoid these load times when models are not being compared, an additional profile is necessary (ModelComparison.sbsx). When the helper is launched, all currently running instances of Rhapsody with projects loaded are checked for the profile and if any are missing the helper offers to add the missing profile(s).

Operation

The helper first detects how many running instances of Rhapsody there are. Two running instances creates a two-way comparison, three instances creates a three-way comparison. Any other number reports an error. All running instances must have a project loaded or again an error is reported.

Decorations

Having multiple instances is necessary for two reasons:

1. Rhapsody will not allow more than one project with the same name in the same rhapsody instance

2. Differences are shown in the model(s) using Decorations which are, by their nature, transient (they do not modify the model and therefore do not trigger configuration management changes)

The helper may be launched from either a project or package which defines the scope of the comparison. The models being compared and the comparison scope are indicated in the starting UI:

A two-way comparison is performed between a base model and a right model.

A three-way comparison adds a left model into the mix.

To run the comparison, click Run Comparison

Two-Way Comparisons

Whenever two models are compared, if an element is in one and not the other it is impossible to determine if the element was added or deleted. To make this distinction, the helper uses the concept of a base model. A base model is assumed to have not been changed, which results in the following behavior:

· Elements in the base model that are not found (by GUID) in the right model are marked as deleted in the base model.

· Elements in the right model that are not found in the base model are marked as added in the right model.

· Elements in the base model that are found in the right model but are different are marked as modified in the right model.

· Elements in the base model that are found in the right model but with a different ‘full path’* are marked as moved in both models. Note that only a single decoration is allowed – if an element is modified AND moved it will only be marked as modified.

*The full path is checked with the name of the element omitted, this allows the helper to distinguish between elements that were moved and elements that were renamed.

The UI reports these differences as listed model elements. Clicking a model element navigates to it in the model.

The model is decorated using the following icons:

	Added
	Deleted
	Moved
	Modified

In addition, if the elements appear on diagrams, they are colored red, green, orange or dark blue for deleted / added / moved.

Three-Way Comparisons

In a three-way comparison, the base model uses additional decorations/colors to distinguish between deleted in left, right or both (moved uses the same colors but different icons)

Icon	Meaning	Diagram color
	Deleted in Left	Orange
	Deleted in Right	Magenta
	Deleted in Both	Red
	Moved in Left	Blue
	Moved in Right	Blue
	Moved in Both	Blue
	Modified in Right	Orange
	Modified in Left	Orange
	Modified in Both	Orange

Setting the Base Model

Whichever model launched the helper becomes the Base model, so (for example) if you want to see what was added to a model in a two-way comparison, launch the helper from the ‘other’ model.

Reference Units

When performing comparisons, if a unit is REF and Read Only in both models then it is ignored. If it is REF but is Read-Write in at least one (that is it is an editable reference) then it is included in the comparison.

Checking by Path

Sometimes you want to compare models that were created separately (and so will have different GUIDs). For this case, select Compare by Path on the Options menu:

Minimal Comparison

By default, the helper performs a minimal comparison – that is whenever it finds a new/deleted/moved element it stops processing that tree so elements underneath are not annotated. This speeds up the comparison and uses less icons (applying decorations to Rhapsody models can quickly increase GDI usage). For example, the graphics below show a minimal comparison versus a non-minimal one:

This option may be switched off using the options menu.

Ignoring Remote Artifacts

When comparing models that have remote artifacts such as requirements from IBM Doors Next Generation (DNG), if the models are offline then this can cause many differences as dependencies will be unresolved. The menu Options  Ignore remote skips any remote artifacts during comparison. REF elements are automatically ignored.

Clearing Decorations

Each model panel in the UI has a button to remove the current decorations, as well as a global button to remove them all. Note that for performance reasons this only removes decorations from model elements in the corresponding table. Reloading a Rhapsody project automatically clears decorations, but this also requires the helper to be relaunched as it assesses the instances and loaded projects on launch. Note that closing the helper automatically removes all decorations.

Clashes

On rare occasions there may be a class such as an element that was moved or modified in one model and deleted in another. These differences are noted in the UI but the icon in the base model will have the latest one applied (this will usually be the moved icon).

Logging

The helper automatically creates a log file in a sub folder of the project called Compare Model Logs. It may be opened directly (using the registered system editor for .log files) from the UI using the menu Log  Open Log File

Abort vs Force Stop

The abort button provides the facility to abort – that is stop at the next safe point. If Rhapsody is responding normally, the comparison will stop within a few seconds. However, if Rhapsody locks up for any reason, Abort won’t work as the tool is stuck waiting for Rhapsody which isn’t responding. Force Stop forcibly terminates the comparison immediately.

Generating a HTML Report

Clicking Generate HTML Report (this button is only available once a comparison run has completed) will produce a report of the differences found. The report is generated into the same folder as the logs.

Opening the Generated Report

Once generated the report is opened either in Rhapsody or in an external browser (or both) depending on the value of the following property:

RhapsodyPowerPack.ReportingTools.OpenInBrowser

Note that documentation opened in Rhapsody uses the same tab each time, but Rhapsody does not automatically switch to this tab so if you have selected a different tab (for example a diagram) then you must manually select the report tab to view the generated documentation.

Navigation

Navigation into Rhapsody is achieved through the Power Pack Web Link Listener. However, that listener is only available on the first Rhapsody instance and so all navigation links will attempt to navigate to that Rhapsody instance. You may navigate from there to the other Rhapsody instances using Locate in Other Rhapsody Instances. If navigation fails, then the GUID may be used in conjunction with the Find Model Element helper.

Alternatively, the Web Link Listener may be started / stopped on the appropriate instance using the Project menu Power Pack  Web Link Listener:

Running Model Visualizer

To better understand the impact of changes, the Compare Models tool can present an impact analysis using the Model Visualizer. Visualizations may be automatically generated and used by the Model Visualizer to visualize a path through the model, starting at the changed element(s).

To enable this feature, you must first define Visualization Templates. Visualization Templates are defined in Visualization Libraries (whilst libraries may be created anywhere, the comparison tool only looks for them in profiles to optimize performance)

The comparison tool can automatically generate Visualizations from these templates which are then used by the Model Visualizer. Each template should have:

· A list of applicable types

· A path

If either of these two properties are empty at the time of generation, they are reported as warnings.

Naming

Generated Visualization(s) have the same name as the templates from which they are generated (if the template name ends in ‘Template’ then this is removed). Name clashes are resolved by the standard Rhapspody method of appending _x integers to the names.

Applicable Types

The following property is a comma separated list that defines the types for which this Visualization Template will be used.

RhapsodyPowerPack.Attribute.Path

For example: Port,ProxyPort

Path

The following property defines the path through the model to visualize, starting at the changed element(s).

RhapsodyPowerPack.Attribute.Path

Paths are written using a subset and superset of the Context Pattern language. Supported concepts are described in Visualizing Paths. Paths may be written manually or using the Path Editor.

Testing Paths

Since a template cannot be visualized (it has no <<visualizes>> dependencies itself), the easiest way to create and test a template is to first create a Visualization (make sure this is in a read-write Visualization Library) – test it and then use the menu Rhapsody Power Pack  Model Visualizer  Save as Template.

The new template will be created in the same library as the Visualization with a Template suffix in its name.

Operation

When a comparison is run, the tool first collects any available Visualization Templates from Visualization Libraries in all currently loaded Profiles. These are indexed according to their applicable types and compared against the changed items. Visualizations may then be auto generated for:

· All changed elements

· All changed elements by type

Both options are available on the context menu for a changed element (it does not matter which changed element – what matters is the tab on which these elements appear which defines the project in which the visualization will be generated)

Multiple Visualizations

Multiple visualizations may be registered against the same element type, allowing different paths to be visualized for the same changed element(s). The tool will generate a Visualization for each path.

Location of Generated Visualizations

The tool will generate new Visualizations into a package in the following order of priority:

· User defined

· Auto-created

User-Defined Package Location

You may define a location for the Visualizations using the following property on the project:

RhapsodyPowerPack.Comparemodels.VisualizationPackage

This should be a full path to an existing read-write package (the path may be obtained easily using Get Full Path)

Auto-Created Package Location

If the above mechanism fails (if the property is empty or points at an invalid/empty path) then the tool attempts to locate / create a new package at root level called Visualizations. If this fails, then an error is reported and the operation is aborted.

Auto-Running the Model Visualizer

Generated visualizations may be manually launched using RhapsodyPowerPack  Model Visualizer  Visualize Path

The Model Visualizer may also be automatically launched using the menu Visualize  Auto-Run Model Visualizer

This will run the visualizer for each generated visualization (which could result in multiple windows depending on how many Visualizations were generated).

Auto-Deleting Visualizations

By default ,Visualizations must be manually deleted however if the menu Visualization  Auto-Delete Visualizations is toggled on then generated Visualizations are automatically deleted after the Model Visualizer has run. Toggling the menu option to run Model Visualizer will also switch off auto-deletion (so the generated Visualizations may still be manually used)

Running Diff Merge

More fine-grained comparisons may be obtained using Rhapsody’s own Diff Merge tool which may be launched from the helper by clicking Run Diff Merge. When launched, Diff Merge will use the same scope as the current scope in Compare Models. Diff Merge is run using the command line options detailed in the IBM help: Diff Merge Command Line Options. Before running Diff merge., set the required options using the Diff merge menu:

Recursive

If this option is selected then Diff Merge will compare the current scope and all its children recursively, otherwise only the current scope element is compared (-recursive).

Merge Mode

If this option is selected the Diff Merge is launched in merge mode (-xmerge), if not then it is launched in compare mode (-xcompare)

Swap Left & Right

If this option is selected, then the left model in Compare Models is passed to Diff Merge as the ‘right’ model and vice-versa. This is because Rhapsody Diff Merge can automatically take the ‘left’ model as the result in merge scenarios.

Long Load Times for Rhapsody Decorations

Decorations are applied based on the property:

Format.Decoration.StyleNames

This is a comma separated list of strings.

This property is invisible to the Rhapsody UI and may only be accessed programmatically.

At the time of writing:

· If this property is not empty when a project loads, the load time for that project is exponentially longer.

· If the property is populated programmatically, Rhapsody ignores it.

· If a conditional property is used, Rhapsody ignores it.

Essentially this means that decorations may only be used if the property is hard coded into the property file, which results in very long load times for models.

For this reason, the property (and its associated properties) is kept separate from the Power Pack Profile in a separate Model Comparison profile. All models that are involved in the comparison must have this profile loaded so that Rhapsody can find the icons to apply.