In this document you will learn how to use the
Collaborative Modeling features introduced in OD 6.0,
which allow for real-time collaboration between remote users on any kind of representation supported by Sirius (diagrams, tables and trees).
Collaborating in real-time around representations required to launch a Collaborative Server. Please refer to the Collaborative Modeling – Administrator Guide to learn how to set up and configure a Collaborative Server.
The Sirius
Collaborative Modeling features allow you to share semantic models and representations
with several remote users.
All shared semantic models and representations are stored on a remote
Server (that you will be able to
launch yourself ).
Whenever you make a modification on a shared representation, saving the Modeling Project
propagates your changes in real-time to all users that have opened the same representation.
Any time a user makes a modification, Sirius relies on a fined grained lock mechanism that locks automatically all the elements that have been modified, so that no other user can edit it while the modifications have not been committed. This automatic locking feature prevents the users from any conflict, and hence from any manual merging phase. Of course, the Sirius platform will allow you to customize the automatic lock policies or simply disable it.
The Server technology (CDO) supports many VCS-standard features like branching or auditing. For simplicity reasons, the default Sirius UI does not provide actions for such features, but the underlying Sirius platform will allow you to define your own branch managers or audit handlers.
This section explains how to share a Local Modeling Project, connect to a Shared Modeling Project and download a local copy of a Shared Modeling Project. Any users connected to the same Shared Modeling Project will see all changes made by other users in real-time.
The first step toward Collaboration is to share a Modeling Project, i.e. upload a local Modeling Project on the Server. To do so :
File > New > Modeling Project
), add local semantic resources and create some representations. You should have the following state :
Export... > Sirius > Shared Modeling Project from Local
Next
.
Repository Host
to the Server IP address (e.g.
192.0.0.23
) otherwise. Notice that you can define a default sever location through the
Collaborative Preferences . Click on
Test Connection
to be able to perform Finish.
Your project is now exported on the Server, and any other user can Connect to this project and Collaborate with you.
Once a project has been exported , any user is able to connect to it by creating a Shared Modeling Project.
To do so :
File > New > Sirius > Shared Modeling Project
)
Repository Host
to the server IP address (e.g.
192.0.0.23
) otherwise. Notice that you can define a default sever location through the Collaborative Preferences. Click on
Test Connection
to be able to go to next Step.
Finish
. A pop-up allowing you to select the Viewpoints to activate on this new Shared Modeling Project should be displayed.
Your Shared Modeling Project is now connected to the server, and all the users connected to the same project will see the changes you make in real-time.
A Shared Modeling Project provides some specifities and additional behavior. Please refer to
the Shared Modeling Project documentation to learn these specificities.
Sirius allows you to download local copies of Remote Projects stored on a Server. The resulting local copy is a standard Modeling Project, completely disconnected from the server and other users.
It does not support collaborative modeling, but can be used even if you do not have access to a Server and/or in a version of Sirius without the collaborative modeling support enabled.
A typical usage of this feature would be to download a local copy of a Shared Modeling Project every month, and to commit this local copy on a VCS-based repository like SVN.
To Import a local copy of a Shared Project:
File > Import... > Sirius > Modeling Project from Remote
Repository Host
to the server IP address (e.g.
192.0.0.23
) otherwise. Notice that you can define a default sever location through the
Collaborative Preferences . Click on
Test Connection
to be able to go to next Step.
Finish
. A pop-up allowing you to select the Viewpoints to activate on this new local Modeling Project should be displayed.
This section provides an overview of the specificities and features provided by a Shared Modeling Project.
A Shared Modeling Project is distinguishable from a standard Modeling Project by a
Shared Decorator on the lower-right corner.
All the semantic resources are displayed with the same Decorator, and so do the representations.
For simplicity reasons, the default Sirius UI only allows fully shared projects (i.e. projects in which all representations and semantic resources are Shared). However, the underlying platform supports projects having both local and shared semantic models, and both local and shared representations.
To add an existing Shared Semantic Resource (already stored on a Server) to a Shared Modeling Project, you can :
Add Remote Model
and then
Add existing remote model
.
Add Model
and then
Add existing remote model
.
To upload a new Shared Semantic resource (from a local resource) to a Shared Modeling Project, you can :
Add Remote Model
and then
Create a New Remote Model
.
Add Model
and then
Create a New Remote Model
.
File > Export > Shared Semantic Resource from Local
) to upload them into the repository. Once it is done, Right-click on the
Project Dependencies node and select
Add Model
.
Note: Only resources of the same repository than the ones of the shared modeling project can be added.
Warning: A particular attention has to be put on remote resources that would aim to be shared by multiple shared modeling project because of export matter.
When exporting a modeling project, all the resources are exported including added semantic resources that may not be physically in the modeling project. Considering library/my.model added to 2 local modeling projects, project1 and project2, if you export project1 and then project2, the latter will succeed only if you check «Override existing resources» because the remote resource library/my.model will have been created with project1 export and will have to be overridden by project2 export.
By nature, a Shared Modeling Project needs to be constantly connected to the Server. When Sirius is closed with opened representations held by a Shared Modeling Project, the next opening will cause a silent reconnection to the server, allowing to access all informations needed to re-open editors on these Shared representations.
At any time, if a connection problem with the server is detected, a pop-up explaining the cause of the error is displayed and
the Project is automatically closed.
As soon as the connection with the Server is retrieved, you will be able to open your Shared Modeling Project again.
The technology used to
create Servers provides an authentication support. If the Server you try to connect to requires authentication, a pop-up allowing you to enter your login and password will be displayed whenever you want to connect.
Notice that if you check the
Remember Me
checkbox, then the login and password will be stored inside Eclipse Secure Storage, and will not be asked again. If you fail to provide a valid login and password, then you will not be able to connect to the server or open an existing Shared Modeling Project. To clear the stored credentials, you need to open the Eclipse preferences with the top menu
Window>Preferences, navigate to
General>Security>Secure Storage, select the
Contents tab. Unfold the tree to find and select the
fr.obeo.dsl.viewpoint.collab node and click on the Delete button.
As a Shared Modeling Project is meant to be shared by several users, some restrictions have to be defined on each user environment :
The Shared Modeling Projects keep tracks of all modifications made on the Server. From any shared element, including the Shared Modeling Project, right-click and select
Show Commit History
to open the
Commit History View.
This view lists all the commits (saves) that occurred on the Modeling Project, displaying the following information:
Time | User | Description |
---|---|---|
The date of the commit | The login of the user that committed the change (only if Server supports authentication) | The first line of the Commit description associated to this commit. |
The Commit History view is divided in two parts:
The Commit History View contains several buttons to modify the context of the commits list, filter those commits or modify the changes viewer tree layout. These actions are detailed below.
Link With Selection: If activated, the Commit History View will be linked with the selection. That means each time an element is selected from a shared project, the Commit History View will be refreshed to display the commits list according to the selected element(s).
Only one of the three following buttons can be activated at a time:
Show commits of the whole repository: The Commit History View will display all commits from the repository that owns the selected element(s).
Show commits of the selected element: The Commit History View will only display commits that imply either the selected semantic element(s) or the target of the selected representation element.
Show commits of the selected element and its children: The Commit History View will display all commits that imply either the selected semantic element(s) or the target of the selected representation element, and all the recursive sub-hierarchy of this(these) element(s). If A is selected and A contains B which contains C. B and C commits will also be displayed.
The two following buttons can be activated in addition of the previous ones:
Show commits of the related elements: The Commit History view will display, in addition, all commits that imply elements referenced by the selected element(s). The selected elements can be:
Merge Consecutive Commits with same user and description: If several consecutive commits have the same user and description, they will be merged in only one visible commit.
Filter
The commit list can be filtered by using the filter field. Only commits where the field value is present in the user or description are displayed.
Compute Impacted Representations
By default, representations impacted by one or several selected commit(s) are not displayed in the changes tree viewer. By activating this option, the Commit History view will compute the representations impacted according to the graphical modifications performed by the commit(s). For instance, if a container as been moved in a diagram, the representation will be displayed as modified. The details of graphical changes are not displayed.
The changes viewer displays impacted semantic elements and created or removed representations by the selected commit(s).
Warning: Representation modifications like moving a graphical element will not be displayed.
There are four kinds of changes. For each one, a different decorator appears on the element icon:
Added (the element has been created by this commit),
Modified (one or several element properties has been modified),
Removed (The element has been deleted from the model) and
Untouched if the element is displayed as a node in the hierarchy. See the
Display as Tree button.
A Deleted, Added, Untouched and Modified elements.
If several commits are selected, an element could appear several times: a commit creates this element for instance and a second modifies it etc. In that case, only the most recent version of the element will appear. For instance, an element A is created by a first commit, a second commit modifies it and a third delete it. If the three commits are selected, the element will be displayed once in the last version before removing. The decorator Deleted is displayed. Note that selecting a merge commit result has the same behavior than selecting all commits that have been merged.
The changes viewer can be displayed as a tree or in flat layout. In tree layout mode, impacted elements are displayed under their first untouched elements. The following image shows the same changes with a flat and tree layout:
It is possible to transform the commit history into a model that represents the different user activities on the CDO server. There are three actions available into the context menu:
These actions open a dialog letting the user choose where to save the model. Then the file is opened. It is a tree representation of all activities.
This model is denominated Activity Metadata. It contains an entry called Activity for each commit done in repository except:
With these rules applying two consecutive commits using the same description will be squashed together in the Activity Metadata model.
Each Activity holds information on:
Using a specific format in the commit description, it is possible to define custom properties. They are transformed into ActivityProperty element in the model. To be created, each property should be written at the end of the commit description using the following format:
team-<$propertyName> : <$value>
For example:
team-property1 : value1
A commit description holding the previous line would be exported as an Activity holding a sub element ActivityProperty. Its feature ‹name› will hold property1 and the feature ‹value› will hold value1. A specific property named technical is used to tag commits that are made by tools for technical reasons. They should not be used on commits holding modification made by users. Those commits are ignored during the Activity metadata extraction.
It is possible to have a text representation of all activities on the Text tab.
Each activities contains changes corresponding to each modification realized during the current commit exported. These changes are described by two fields.
The first one contains the URI of the semantic element change defined by the path of the used resource and the id of the impacted semantic element.
The second field of a change contains the type of the change. Three kind of type are defined : CREATED for a new semantic element, DELETED for element remove and MODIFIED when semantic element has been changed.
When two consecutive activities are squashed together, their changes are also merged in the same activity. If an element appears in several commits and so several times in the list of changes, only one state per element is displayed according to those priorities: Deletion, Modification and finally Creation.
Warning: Models that are added into a shared modeling project are automatically uploaded. You should save the model into a non shared modeling project in order to avoid adding it to the collaborative repository.
When you make modifications on shared representations or semantic models, your changes will be committed on the Server whenever you Save your editor/Modeling Project. Consequently, all the changes you make will not be visible to other users until you perform a Save action.
Notice that the underlying platform allows to customize the behavior, by introducing a decorrelation between save and commit.
Whenever a remote user commits (saves) a change on a shared model or representation, you will receive this change in real-time. According to your Refresh preferences (i.e. if Automatic Refresh is activated or not), the impacted representations will be updated in real-time or after a manual refresh.
In Automatic Refresh: all the changes committed by other users are integrated in real-time.
In Manual Refresh: when a change committed by another user impacts a representation you are working on, then an icon indicates that this representation Needs Refresh.
You will not be able to make any change on this representation until you launch a manual Refresh. Changes will then be integrated, and you will be able to edit the representation again.
This section is about giving an overview of the locking mechanisms provided by the Shared Modeling Projects.
When an element is locked by another user (semantic or graphical), it is displayed with a red padlock. In this case, you will not be able to:
You will be able to use 2 different kind of locks:
When you know that you are going to work on some elements (semantic or graphical), and do not want other users to interfere with your work, you will be able to lock those elements on demand.
To do so, select the elements you want to lock (from the
Model Explorer
view or from your current representation), right-click and select
Lock/Unlock... > Lock element
action.
The selected element are now locked (green padlocks indicate that you have the lock on these elements), and cannot be edited by anyone until you select the
Lock/Unlock... > Unlock element
action.
Closing the Modeling Project or exiting the application will not release any lock lock on demand.
Notice that you can lock/unlock directly an element and all its children by selecting the
Lock/Unlock... > Lock elements and all its descendants
action.
To lock a representation, simply right-click on it from the Modeling Explorer view or select the background of a representation an select
Lock/Unlock... > Lock representation
.
The Sirius API will allow you to specify whether locks on demand should be released when closing the project or exiting the application. Default behavior considers that such locks should be kept until the user performs an unlock action.
Whenever you modify a shared semantic or graphical element, an automatic lock will be placed on this element preventing any user from modifying the same element.
To determine which element should be locked in regards to a modification, we apply rules based on common sense:
These are the default rules for automatic locking. The underlying platform allows you to specify your own Lock Strategies
Automatic locks are released when you save (commit) your modifications. Closing the Modeling Project or exiting the application will release any automatic lock.
This section details the behavior of each Representation (Diagram, Table, Tree) when elements are locked.
Diagrams | Tables | Trees | |
---|---|---|---|
Appearance of a graphical element when underlying semantic element is locked by the current user |
![]() |
![]() |
![]() |
Appearance of a graphical element when underlying semantic element is locked by a distant user |
![]() |
![]() |
![]() |
Behavior of the Editor when the Representation is locked by the current user |
![]() ✓ Unrestricted |
![]() ✓ Unrestricted |
![]() ✓ Unrestricted |
Behavior of the Editor when the Representation is locked by a distant user |
![]() ✗ Impossible to move any graphical element ✗ All palette tools are disabled ✗ Impossible to make any graphical modification (Arrange All, Pin/Unpin, Show/Hide...) ✗ You can still edit semantic elements through the property view |
![]() ✗ Impossible to make any graphical modification (resize a column/a cell...) ✗ You can still edit semantic elements through the property view |
![]() ✗ Impossible to make any graphical modification (expand/collapse a Tree item...) ✗ You can still edit semantic elements through the property view |
Behavior of the Editor when a sub Representation Element is locked by the current user | Cannot happen: when making a graphical modification, the whole Diagram is locked, and not just the modified graphical element. |
![]() ✓ Unrestricted |
![]() ✓ Unrestricted |
Behavior of the Editor when a sub Representation Element is locked by a distant user | Cannot happen: when making a graphical modification, the whole Diagram is locked, and not just the modified graphical element. |
![]() ✗ Impossible to resize the locked Column/Cell. |
![]() ✗ Impossible to expand/collapse the locked Tree item. |
It is possible for the
Administrator to define specific permissions on the Collaborative Server. Consequently, with such a server you will only be able to modify elements for which the administrator gave you
WRITE
access.
When you do not have
WRITE
access on an element (semantic or graphical), it is displayed with a grey padlock. In this case, you will have exactly the same restrictions as for
locked by other elements. The only difference is that, contrary to lock by other elements, these padlocks will never disappear (unless the administrator changes your permissions). You will not be able to:
WRITE
access on e1, you will be able to create new children on e2 (but not on e1).
As elements decorated with a grey padlock have exactly the same behavior as elements decorated with a red padlock, you can refer to the Lock behavior Table to get the edition limitations on such elements.
If you need to modify an element and do not have sufficient rights, please contact your Server administrator so that he can give you the corresponding rights.
As any other component of Sirius, the Collaborative Features can be customized through the use of Preferences. To change Collaborative Preferences, got to
Window > Preferences > Sirius > Team collaboration
.
Allows to specify the default location of the Server.
Server location | Port number | Repository Name | Connection Type |
---|---|---|---|
The IP address of the server. If you launched the server, you can use
localhost . Otherwise, you will have to enter the IP address of the Server (e.g.
192.0.0.23 ).
|
The port number on which the server has been launched. You can easily retrieve this information by opening the
cdo-server.xml file you used to launch the server, and look at the
port="XXXX" value.
|
The Repository name. You can easily retrieve this information by opening the
cdo-server.xml file you used to launch the server, and look at the
repository name="XXXX" value.
|
Whether plain TCP or SSL connection should be used to connect to the server. You can easily retrieve this information by opening the
cdo-server.xml file you used to launch the server, and look at the
acceptor type="XXXX" value.
|
By activating this preference, any time you will perform a Save that involve Shared Semantic Resources or Representations, a pop-up asking you to enter a comment explaining your changes will be displayed.
The user has three options available on the Commit Description dialog:
If this preference is deactivated you can still enter a commit description when saving using a special command «Save with Description». It is available in «File» > «Save with Description» or using the key shortcut Ctr+Alt+S.
This commit description will be used inside the History View to list all changes that occured on the repository.
By activating this preference, any time the user is asked for entering a commit description, the framework will compute one using a list of registered participants (see description below). This description will be presented to the user so he can modify it or simply reuse it for its current commit.
Selecting one of the participant in the «Commit description provider» preference defines which participant will be used for the computation of commit description. If the current workbench context matches the activation criteria of the participant it returns a pre-filled commit description. Otherwise it returns an empty description.:
By activating the preference «Automatically use the pre-filled description when none is provided», any time the user commits and do not specifically provides a commit description, the description computed from the mechanism described above will be used.
By default, the connection to the CDO repository has a timeout of sixty seconds. However, in specific cases (like saving a large volume of modifications) the user may want to increase the session timeout value.
This can be achieved by adding the argument «fr.obeo.dsl.viewpoint.collab/PREF_CDO_SESSION_TIME_OUT» with a value in milliseconds in the plugin_customization.ini file (usually placed at the root of Eclipse). This file must be referenced in the platform option -pluginCustomization directly in the eclipse.ini. See chapter
Advanced Topics in Running Eclipse of Eclipse documentation for more details.
To set this preference in a launch configuration, the plugin_customization.ini to use needs to be added in the «Program argument» section by adding «-pluginCustomization» and the path of the file.
As an example, if the timeout needs to be set to two minutes then the argument to add will be «fr.obeo.dsl.viewpoint.collab/PREF_CDO_SESSION_TIME_OUT=120000».
Note that this argument will not change the specific timeout concerning the «Test connection» button that is set to ten seconds.
The properties page (contextual action) on aird files of shared modeling project has a tab named Repository Information. This presents the connected repository information (location, port and name), the current user and finally a list of other users connected on the same repository.
With an authenticated server
With an anonymous server