Create Handoff Model

Overview

This helper facilitates handing off part(s) of one model for further development in another.

Applicable To	Block,Class,Handoff Definition
Menu Entry	Power Pack  Handoff Tools > Create Handoff Model

Operation

The helper works by saving the current model as a new one and then deleting out-of-scope elements. This ensures that the GUIDs of the elements in the handoff model are the same as the originals, facilitating multiple exports / hand-backs using Rhapsody Diff-Merge.

The helper first performs a save to ensure any current changes are kept and then performs a Save As. The name and location (amongst other settings) may be controlled using properties as described below. All properties may be set at Project, Package or Handoff Definition level.

Location of Handoff Model

By default, the handoff model is created in the same package as the existing model (in a sub folder with the same name as the new model). The following property may be set to define a new location:

RhapsodyPowerPack.HandoffDefinition.TargetFolder

The property may be a full path (e.g. C:/Work/Handoff) or a relative path (relative to the current project’s rpy/rpyx file).

Name of Handoff Model

If launched directly from block(s) then the new model’s name is the existing model name with a suffix of _Handoff. If launched from a Handoff Definition, then the new model’s name is the same as the Handoff Definition name (see below).

After performing a Save As, the helper then cleans the new model in a multi-stage process:

Pre-Processing

This stage is only performed if the following property exists and is not empty (to avoid race conditions with custom profiles, this property does not exist by default – add it to your own custom profile to use it):

RhapsodyPowerPack.HandoffDefinition.PreHandoffPlugin

The above property allows your own helper to run before the following stages occur. The property should be set to the Menu Entry from the HEP file for the helper you wish to run. For example:

MyHelpers\Handoff Tools\Run Before Handoff

Stage 1 – The ‘Keep List’

The helper builds a list of ‘in-scope’ model elements that will not be deleted from the new model. This stage is performed in several sub-stages:

Stage 1.1 – Initial Scope

The initial scope may be defined in two ways:

· Launching the helper from selected blocks (those elements are the initial scope)

· Launching the helper from a Handoff Definition:

Handoff Definition

To create a re-usable initial scope:

1. Create a Handoff Specification (a new term based on package).

2. In that Handoff Specification, create a Handoff Diagram (optional but allows creation of the Handoff Specification graphically).

3. Create a Handoff Definition and add the initial scope element(s) using a <<handoffElement>> dependency

Example:

Stage 1.2 – Expansion of Scope by Swimlane

This stage is only performed if the following property is set to true:

RhapsodyPowerPack.HandoffDefinition.ExpandScopeBySwimlane

Each block in the initial scope has its references checked. If it is mapped to any activity diagram swimlane then the content of that ‘scope’ swimlane is checked: Any other elements in mapped swimlanes that have incoming or outgoing flows to/from elements in the scope swimlane will cause the mapped block(s) to be included in scope. For example, for the following diagram, if the initial scope was Block A then Block B would also be included. If the initial scope were Block B then both Blocks A and C would also be included:

Stage 1.3 – Instances

This stage is only performed if the following property is set to true:

RhapsodyPowerPack.HandoffDefinition.IncludeInstances

Each of the Blocks in scope has its references checked for instances of those blocks. Any instances in the references are included in the scope, along with the instance owner.

Stage 1.4 – Diagrams

This stage is only performed if the following property is set to true:

RhapsodyPowerPack.HandoffDefinition.IncludeDiagrams

Each of the Blocks in scope has its references checked for diagrams. Any diagrams in the references are included in the scope, along with the diagram owner. Note that references might be lifelines or swimlanes in which case sequence diagrams / activity diagrams for those references are included. Handoff diagrams are automatically excluded.

Use Case Diagrams

Use Case Diagrams are a special case since it is not usual for Blocks to appear on them. To include Use Case Diagrams, add them to the initial scope using <<handoffElement>> dependencies. Including a Use Case Diagram automatically includes all Actors and all Use Cases on those diagrams, as well as the owner of the Use Case Diagram.

Additional Includes

Whenever any model element is added to the keep list, it is also checked for:

· Stereotypes

· Connected Requirements

· Types

Stereotypes

If a model element in scope has stereotypes applied to it, then those stereotypes are automatically included in scope (unless they are read only – read only elements will not be deleted and so do not need to be added to the keep list)

Requirements

In-scope elements are automatically checked for dependencies to Requirements. By default, any dependency will cause a connected requirement to be included however the following (comma-separated list) property may be used to specify a list of dependency stereotypes – in which case only dependencies that have that stereotype are considered:

RhapsodyPowerPack.HandoffDefinition.RequirementTraceabilityStereotypes

Types

When a Block/Actor is included in scope, it’s attributes, operations and event receptions are checked for types. In the case of operations, arguments and return types are checked and in the case of event receptions, arguments are checked. Any non-read-only types are added to the keep list.

Stage 2 – Model Cleanup

The helper deletes any model elements that are not in scope. This stage is performed in several sub-stages:

Stage 2.1 – Activity Cleanup

This stage is only performed if the following property is set to true:

RhapsodyPowerPack.HandoffDefinition.CleanActivities

In this stage any activity diagrams that have swimlanes are processed. Any swimlanes that are not mapped to a block or are mapped to an out-of-scope block are deleted (before deleting the swimlane, the helper deletes all its content to prevent Rhapsody from moving that content to the nearest free swimlane and/or leaving dangling flows). This stage happens first as it is possible for flows to have tags that map to events / types that we want to delete, and their presence would prevent that deletion if this stage were to happen later.

Stage 2.2 – Package Deletion 1

During this stage, the helper processes the package tree, bottom-up. Any package that contains a model element in the keep list is flagged as do-not-delete. This flag is propagated up the tree such that the original model hierarchy is retained. If a package contains no in-scope elements and is not flagged, then it is deleted. For example, in the following model, if Block S1 was in scope then Pkg2 and Pkg1 would be retained but Pkg3 would be deleted.

Important Note:

For performance reasons only top-level elements in a package are checked. Adding elements to the keep list that are not at package level has no effect.

Stage 2.3 – Package Cleanup 1

During this stage, any remaining packages are ‘cleaned’ – that is their top-level elements are checked. If those top-level elements are not in the keep list, then they are deleted.

Reporting Deletions

During the first two sub-stages it may be the case that an element / package cannot be deleted (yet) if it is used elsewhere in the model. For example, if a package contains a type or an event then Rhapsody will not allow that package to be deleted if the type / event is in use. For this reason, any deletion attempts that fail during the first two sub-stages are not reported.

Stage 2.4 – Package Cleanup 2

Now that packages have been ‘cleaned’, this should have removed any model elements preventing other elements from being deleted and so a second run of package cleaning is performed; this time failed deletions are reported.

Stage 2.5 – Package Deletion 2

Lastly a second run of package deletion is performed; this time failed deletions are reported.

Stage 3 – Sequence Diagram Cleanup

There are two sub-stages to cleaning sequence diagrams:

Stage 3.1 – Cleaning Messages and Lifelines

This stage is only performed if the following property is set to true (and diagrams are included):

RhapsodyPowerPack.HandoffDefinition.CleanSequenceDiagrams

During this stage, Sequence Diagrams are cleaned:

· Any messages that are not to / from an in-scope block are deleted

· Any lifelines that do not have messages to / from an in-scope block are deleted

Stage 3.2 – Actor Creation for Unmapped Swimlanes

This stage is only performed if the following property is set to true (and diagrams are included):

RhapsodyPowerPack.HandoffDefinition.CreateActorsForUnmappedLifelines

During this stage, any remaining unmapped lifelines are re-mapped to new Actors. New Actors are created in the same location as the original blocks and have the same name. Unmapped lifelines are also re-named to have the same name they had before they became unmapped (deleting a block causes Rhapsody to rename any lifeline that represented that block to lifeline_x)

Post-Processing

This stage is only performed if the following property exists and is not empty (to avoid race conditions with custom profiles, this property does not exist by default – add it to your own custom profile to use it):

RhapsodyPowerPack.HandoffDefinition.PostHandoffPlugin

The above property allows your own helper to run after the previous stages have finished. The property should be set to the Menu Entry from the HEP file for the helper you wish to run. For example:

MyHelpers\Handoff Tools\Run After Handoff

File Logging

Activity is logged to the Rhapsody output window in the usual way but in addition a detailed file log may be produced by setting the following property to true:

RhapsodyPowerPack.HandoffDefinition.CreateLogFile

If the handoff was produced from a Handoff Definition, then the log file may be opened from Rhapsody by right-clicking the Handoff Definition and selecting Power Pack  Handoff  Open Log File which will open the file in whichever application is registered to handle files with a .log extension.