rpy/plugins/org.eclipse.papyrus.interoperability.rpy.doc/src/site/mediawiki/rpyMigrationUser.mediawiki

=Papyrus Rpy Interoperability=
This documentation talks about the import of models created with the software '''IBM Rational Rhapsody''' into Papyrus. '''IBM Rational Rhapsody''' is developed by the IBM company. In this documentation, we reference this software as '''Rhapsody'''. 

==Which Rhapsody version models are supported?==
The migration tool has been developed with IBM Rhapsody 8.0.3. Nevertheless, it should work with previous and next versions.

==Features==
Currently, the Papyrus Rpy Interoperability Tools has been developed for Rhapsody SysML models. It doesn't yet cover the whole Rhapsody elements in its transformation.

===UML Mapping===
Papyrus migration tools allows to import Rhapsody models as UML Model. Some Rhapsody elements can be mapped on different UML elements depending on their context, the stereotypes applied on them, the value of a given feature and so on. Here, this table give you the supported Rhapsody Semantic Object and their possible mapping used to create the UML model.

{| class="wikitable" border="1"
! style="text-align: center; font-weight: bold;" | Rhapsody Element
! style="text-align: center; font-weight: bold;" | UML Element
|-
| DefaultSubsystemType
| Package
|-
| IAction
| OpaqueBehavior
|-
| IActor
| Actor
|-
| IArgument
| Property
|-
| IArgument
| Parameter
|-
| IAssociationEnd
| Association
|-
| IAssociationEnd
| Property
|-
| IAttribute
| Property
|-
| IClass
| Interface
|-
| IClass
| Class
|-
| IComment
| Comment
|-
| IDefaultDrvdTrans
| Vertex
|-
| IDescription
| Comment
|-
| IEnumerationLiteral
| EnumerationLiteral
|-
| IEvent
| SignalEvent
|-
| IEvent
| Signal
|-
| IGeneralization
| Generalization
|-
| IGuard
| Constraint
|-
| IInformationFlow
| Connector
|-
| IInterfaceItemTrigger
| Trigger
|-
| IObjectLink
| Connector
|-
| IObjectLink
| ConnectorEnd
|-
| IPart
| Property
|-
| IPart
| Association
|-
| IPrimitiveOperation
| Operation
|-
| IProject
| Model
|-
| IReception
| Reception
|-
| IRelation
| Property
|-
| IRelation
| Port
|-
| IState
| State
|-
| IStateChart
| StateMachine
|-
| ITransition
| Transition
|-
| IType
| UML Primitives Types
|-
| IType
| DataType
|-
| IType
| Enumeration
|-
| IType
| InstanceSpecification
|-
| IType
| Class
|-
| IVariable
| Designer
|}

===SysML Mapping===
The Rhapsody SysML Stereotypes are mapped with SysML 1.1 stereotypes provided by Papyrus.
The following stereotypes are supported (not complete list).
{| class="wikitable" border="1"
! style="text-align: center; font-weight: bold;" | SysML 1.1 Stereotype
|-
| BindingConnector
|-
| Block
|-
| ConstraintBlock
|-
| ConstraintProperty
|-
| Dimension
|-
| FlowPort
|-
| FlowPort
|-
| FlowProperty
|-
| FlowSpecification
|-
| NestedConnectorEnd
|-
| Unit
|-
| ValueType
|}

===Properties's Type Mapping===
* The Rhapsody Types Libraries (like ''PredefinedTypes'', ''PredefinedTypesC'', ''PredefinedTypesCpp'', etc) are not imported (legal reason). Nevertheless, a UML Package is created, when required, for each of these libraries, when the Rhapsody model contains references to a type defined in those libraries. This package contains DataType representing the type provided by the Rhapsody libraries. By this way, the types of the user model are preserved by the transformation.
* To ease user experience, we always import the UML Predefined Types library, but we doesn't use the provided types in the imported model.
* In some case, a Package called '''UserTypesDeclaration''' is created. The goal of this package is to group the type declared using the '''C++ declaration''' field text in Rhapsody. It is not a reference to an existing type, it is only a name given by the user to the type.

===Diagram Mapping===
*Papyrus Rhapsody Migration Tools allows to import Rhapsody SysML Diagrams as Papyrus SysML 1.1 Diagrams. The supported diagrams are:
**Internal Block Diagram
**Block Definition Diagram
**Parametric Diagram

*The tool creates the diagrams and the elements represented in them when Papyrus Diagram support it. The tool tries to respect the location of the nodes, anchors, ports, and links.

===Internationalization===
If you defined Label in addition of the name for your objects in the Rhapsody model, Papyrus migrate them too in a property file. You will be able to switch between displaying name and label with the Internationalization feature provided by Papyrus.

==How to launch the import of a Rhapsody (SysML) Model==
Firstly, of course, you need to have a Rhapsody Model, like this one: 

[[Image:images/user/InitialRpyModel.png|frame|none]]


Import the full Rhapsody model in our Eclipse Workspace as shown in the image.

[[Image:images/user/RpyImport_Step1.png|frame|none]]


Go to the menu '''Import Wizard > Papyrus > Papyrus SysML Models''', then '''Next'''.

[[Image:images/user/Rpy_Step2.png|frame|none]]



Here, you select a file, a folder or a set of folder to import one or several Rhapsody models in the same time, then '''Next'''.

[[Image:images/user/RpyImport_Step3.png|frame|none]]

You select the '''*rpy''' files to import. You can set the number of threads to use (useful to import several models in the same time), then '''Finish'''. It runs the transformation.

[[Image:images/user/RpyImport_Step4.png|frame|none]]

And now you get the imported model, in a subfolder called ''output/yourRhapsodyProjectName''.
In this folder you will found: 
In it, you will find the Papyrus model, with these files:
*'''<projectName>'''''.uml'': the uml model
*'''<projectName>'''''.notation'': the diagrams 
*'''<projectName>'''''.di''
*'''<projectName>'''''.properties'': it contains the labels defined for your object in Rhapsody
*'''<projectName>'''''.umlrpy'': these files are the result of an intermediate transformation. Your file and all its Rhapsody dependencies have been migrated into an intermediate format, before being converted into a Papyrus Model.

[[Image:images/user/RpyImportResult.png|frame|none]]


If you are in the Project Explorer, a shortest method allows you to import a selected ''*.rpy'' file, doing '''Right-Click > Import SysML Rhapsody Model'''.

==Why my CSS are ignored in imported Diagrams?==
The goal of the Papyrus Rpy Interoperability feature is to provide the same display for a given Rhapsody Diagram and its equivalent in Papyrus. As the CSS stylesheet can impact the display of the diagram, our transformation process add a specific information to each imported display property to bypass CSS renderer. Technically we add an '''EAnnotation''' named '''PapyrusCSSForceValue''' to ignore CSS value. All CSS customizations can be impacted, like connector routing or compartment visibility.