User Manual

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).

The following video demonstration provides an overview of the available Collaborative Modeling features.

Collaborating in real-time around representations required to launch a Collaborative Server. Please refer to the Collaborative Modeling - Administrator Manual learn how to set up and configure a Collaborative Server.

1. Overview

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.

2. Shared Modeling Projects

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.

2.1. Sharing a Local Modeling Project

The following video provides an example of how to share a modeling project.

The first step toward Collaboration is to share a Modeling Project, i.e., upload a local Modeling Project on the Server.

To do so :

Check that a CDO server has been started (by you or any other user)
If you do not have any local Modeling Project, create a standard Modeling Project (File > New > Modeling Project), add local semantic resources and create some representations. You should have the following state :
To Share you Local Modeling Project on the Server, right-click on the Modeling Project, and select Export… > Sirius > Shared Modeling Project from Local
The project you want to export is selected by default. The following options are available:
- Override existing resources: decide whether existing resources with the same name should be overridden on the server. Note that the override resource option of the export will only export if there is no other session connected to the repository, even if it is the same user and the same workspace. To override without checks a system property, it is possible to set the system property: -Dfr.obeo.dsl.viewpoint.collab.api.export.without.check=true.
- Connect to the exported project: decide if you want to connect to the exported project afterward.
- Select images to export on repository: Choose the images you want to export to the repository in this new wizard page. Note that the images used by the exported projects will be automatically exported to the repository to keep the consistency of the shared representations. This means that if you explicitly use an image in one of your projects to export, this image will be exported even if you didn’t select it.
Select the expected values for these options and press Next.
Enter the server location: keep unchanged if you have launched the Server yourself, or change the Repository Host to the Server IP address (e.g. 192.0.0.23) otherwise. Notice that you can define a default server location through the Collaborative Preferences. Click on Test Connection to be able to perform Finish.
Sirius exports the local project on the Server, and opens a wizard allowing you to Connect to the exported project.

Your project is now exported on the Server, and any other user can Connect to this project and Collaborate with you.

2.2. Connect to an existing Project

The following video provides an example of how to connect to an existing shared project.

Once a project has been exported , any user is able to connect to it by creating a Shared Modeling Project.

To do so :

Create a new Shared Modeling Project (File > New > Sirius > Shared Modeling Project).
Select one of the servers from the drop-down list. By default, the server with the alias Default is selected.
If necessary, change the server connection information in the Connection Information section. Keep the Repository Host unchanged if you launched the server yourself, otherwise enter the IP address of the server (e.g. 192.0.0.23).
If you changed the connection information, click on Save as… to save the connection information and enter an alias to identify the server among other configurations. Notice that you can retrieve server locations through Collaborative Preferences to add, edit or delete your configurations.
Click on Test Connection to be able to go to next Step.
Select the project you want to connect to, and the name to locally associate to your Shared Modeling Project.
Click on 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 specificities and additional behavior. Please refer to the Shared Modeling Project documentation to learn these specificities.

2.3. Overriding Sirius refresh preferences for a particular connected project

Both "Automatic Refresh" and "Do refresh at representation opening" can be specified for a given aird. Refer to Sirius documentation: Preferences associated with the aird file

For any new local project, the preferences are not overridden for the aird file and the preference values are those displayed in Windows > Preferences > Sirius.

The principle is the same for associating specific refresh preferences for a connected project. But, in case of a connected project, a page has been added in the "Connect to remote model" wizard to allow users to override refresh preferences for the being created connected project local aird. By default, "Enable project specific settings" is unchecked and both "Automatic Refresh" and "Do refresh at representation opening" preferences are those displayed in Windows > Preferences > Sirius.

It is nevertheless possible to change the default value using the preference fr.obeo.dsl.viewpoint.collab/PREF_ENABLE_PROJECT_SPECIFIC_SETTINGS_DEFAULT_VALUE. If set to true, then, by default, "Enable project specific settings" is checked.

The preference values are not shared between two connected users. The preferences are associated to the local aird of the "Connected project" but not with the shared aird.

2.4. Sharing representations

In the previous parts it was presented how to share or connect to a modeling project. Once working on a shared modeling project, new representation will be automatically placed on the repository and shared to another connected user.

It is possible to move shared representation to a local location using the "Move" contextual menu.

It will still be available on the shared modeling project, but the representation will be physically stored in the workspace instead of the remote repository. Note that there is a warning when the selected target is local.

2.5. Download a Local Copy of a Shared Project

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 Git.

To Import a local copy of a Shared Project:

Launch the Import wizard File > Import… > Sirius > Modeling Project from Remote
Select one of the servers from the drop-down list. By default, the server with the alias Default is selected.
If necessary, change the server connection information in the Connection Information section. Keep the Repository Host unchanged if you launched the server yourself, otherwise enter the IP address of the server (e.g. 192.0.0.23).
If you changed the connection information, click on Save as… to save the connection information and enter an alias to identify the server among other configurations. Notice that you can retrieve server locations through Collaborative Preferences to add, edit or delete your configurations.
Click on Test Connection to be able to go to next Step.
Select the project you want to download, and the name of the resulting local copy.

When importing the remote project locally, the imported images will be created in local projects that correspond to their location on the server. The import wizard allows you to choose from three different options for importing images:
- Import all images: import all images existing on the repository.
- Import only used images: import only images used by the project and its dependencies.
- Do not import images: Do not import any image.

Click on Finish. A pop-up allowing you to select the Viewpoints to activate on this new local Modeling Project should be displayed.

3. Managing Shared Modeling Projects

This section provides an overview of the specificities and features provided by a Shared Modeling Project.

3.1. Shared Modeling Project Appearance

A Shared Modeling Project is distinguishable from a standard Modeling Project by a Shared Decorator in 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.

3.2. Adding new Shared semantic resources

To add an existing Shared Semantic Resource (already stored on a Server) to a Shared Modeling Project, you can :

Right-click on the Modeling Project, select Add Remote Model and then Add existing remote model.
Right-click on the Project Dependencies node, select 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 :

Right-click on the Modeling Project, select Add Remote Model and then Create a New Remote Model.
Right-click on the Project Dependencies node, select Add Model and then Create a New Remote Model.
Drag and Drop a local resource from your workspace inside the Shared Modeling Project. The resource will be exported on the Server and then added to your project.
Select the resources to export and use the Export Semantic Resource Wizard (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.

Only resources of the same repository as the ones of the shared modeling project can be added.

Particular attention has to be put on remote resources that would aim to be shared by multiple shared modeling projects 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.

3.3. Connection with the Server

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 information 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.

3.4. Authentication management

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.

3.5. Current Restrictions

As a Shared Modeling Project is meant to be shared by several users, some restrictions have to be defined on each user environment :

Several users sharing the same Modeling Project can have different viewpoints activated/installed. However, if a Sirius is installed, then all the clients should share the same version of this Sirius (to avoid having different and incoherent behaviors during Refresh).
It is impossible to Control/Uncontrol Shared Semantic Resources or Representations. However, you can perfectly import or export fragmented projects. As long as they are coherent (self-contained), you can also import locally sub-fragments of models stored on the Server.

4. The Commit History View

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 the Server supports authentication)	The first line of the Commit description associated with this commit.

Time

User

Description

The date of the commit

The login of the user that committed the change (only if the Server supports authentication)

The first line of the Commit description associated with this commit.

4.1. Overview

The Commit History view is divided in two parts:

On the left, the list of commits and the description of the selected one.
On the right, the changes viewer displays the impacted elements by the selected commit(s).

4.2. Toolbar options details

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 commit list according to the selected element(s).

4.2.1. Commits list

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:
- either the selected semantic element(s)
- or the target and also the semantic elements of the selected representation element
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.

4.2.2. Other buttons:

Display as Tree: 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:

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.
Filter displayed elements in the changes tree: By default, this button is hidden. It is shown by customizing the Commit History View (see chapter Advanced Collaborative Use Cases).
This button allows user to activate or deactivate some filters (provided by the customization) to hide/show some element changes in the "Commit History" view.
In addition, a new entry "Filters…" is displayed in the Commit History view menu. When the user clicks on this entry, a new dialog is opened. In this dialog, the user can choose filters to apply by checking them.

By default, this menu is hidden if no entry is available.

The dialog to select filters to apply:

4.2.3. Changes viewer

The changes viewer displays impacted semantic elements and created or removed representations by the selected commit(s).

Representation modifications like moving a graphical element will not be displayed.

The changes list can be filtered by using the filter field.
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
Untouched: if the element is displayed as a node in the hierarchy. See the Display as Tree button.

Deleted, Added, Untouched and Modified decorators.

The changes are computed for each commit done by a user with one of the save actions.
The changes of commits done by wizards, actions and command line tools are not computed; those commits have a description which begins by specific tags like [Export], [Delete], [Maintenance], [User Profile], [Import], [Dump].

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 deletes 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 as selecting all commits that have been merged.

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:

Export metadata > All: export all activities from the repository.
Export metadata > Since selected commit: export all activities occurred since the selected commit.
Export metadata > Between each other: export all activities occurred between two selected commits (included).

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:

Commits which are tagged as technical commit (see below).
Commits that represent the same activity than the previous commit. Two commits match the same activity if they are made by the same user and have the exact same commit description.

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:

The user that made the commit.
The date of the commit.
The description of the commit.

Activities also hold custom properties denominated as ActivityProperty (see below).

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 activity contains changes corresponding to each modification realized during the current commit exported. Two fields describe these changes:

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 kinds of type are defined :
- CREATED for a new semantic element.
- DELETED for element remove.
- MODIFIED when a 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.

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.

5. Publishing and Receiving Changes

5.1. Publishing changes on the Server

The following video provides an example of collaborative work on a shared model.

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.

The underlying platform allows customizing the behavior, by introducing a decorrelation between save and commit.

5.2. Receiving Remote Changes

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.
- Initial state: two clients are using the same remote representation.
- First step: the client on the right moves an element.
- Second step: the client on the right commits. The client on the left is updated automatically.
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.
- Initial state: two clients are using the same remote representation.
- First step: the client on the right moves an element.
- Second step: the client on the right commits. The client on the left is not updated automatically, he has to refresh manually.

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.

6. Locking Mechanisms

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:

Modify a property of this element (attribute of a semantic element, size of a graphical element…)
Create/delete children on this element. However, if an element e1 contains an element e2, and if e1 is locked, you will be able to create new children on e2 (but not on e1).

You will be able to use two different kinds of locks:

Locks on demand, allowing you to preventively lock elements you want to modify. Once an element is explicitly locked, no one will be able to edit it until you release this lock on demand.
Automatic locks, that are taken automatically any time you make a modification on an element (semantic or graphical). The only purpose of such locks is to prevent other users to edit elements you are currently working on, and prevent from any conflict. An implicit lock is released any time you commit (save) your modifications on the server.

6.1. Locks on demand

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 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.

6.2. Automatic Locks

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 regard to a modification, we apply rules based on common sense:

Modify an attribute/reference of a semantic element → it is immediately locked for all other users ;
Create an element A inside an element B → B is immediately locked for all other users ;
Delete an element A inside an element B → A and B are immediately locked for all other users (to prevent other users from making modifications on A as it is going to be deleted).

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.

6.3. Lock behavior on Diagrams, Tables, and Trees

When creating, cloning or moving a representation, the associated semantic target element is automatically locked. This is useful to avoid that, on a connected project, the current user saves the newly created representation with a null target in case an other user had deleted the target just before the current user saves. Note that a warning is displayed in the dialog box to ask the user to save as soon as possible so that to release the lock.

This behavior can be deactivated using the preference CDOSiriusPreferenceKeys.PREF_LOCK_SEMANTIC_TARGET_AT_REPRESENTATION_LOCATION_CHANGE with a false value.

This behavior has a particular impact when using user profile. If the user has only a read only right on the semantic element, he cannot create/clone/move a representation on it.

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.

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.

7. Permission Mechanisms

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:

Modify a property of this element (attribute of a semantic element, size of a graphical element…)
Create/delete children on this element. However, if an element e1 contains an element e2, and you do not have WRITE access on e1, you will be able to create new children on e2 (but not on e1).

As elements decorated with a gray 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.

If the user has only a read only right on the semantic element, he cannot create/clone/move a representation on it. If trying, a pop-up will be displayed telling that it failed. See Lock behavior on Diagrams, Tables and Trees for more information.

8. Collaborative Preferences

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.

8.1. Repositories

In the Registered Repositories section, you can find all the repositories you saved. You can add new configurations, you can also duplicate, edit or delete existing configurations. All the configurations you save are serialized in the file ./configuration/fr.obeo.dsl.viewpoint.collab.ui/repository.properties in the form <alias> = <connection-type>://<server-location>:<port>/<server-name>.

If you click Add, a dialog opens, where you can enter the connection information for the new repository. These informations are pre-filled with the default repository information, or with the information of the selected repository if you click on Edit.

8.2. Default Repository Information

Allows specifying the default location of the Server.

Repository alias Server location Port number Repository Name Connection Type

Repository alias	Server location	Port number	Repository Name	Connection Type
The alias of the repository given by the user. Allows giving a name to the repository configuration to distinguish the various configurations. By default, the alias of a repository is `Default`.	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.

The alias of the repository given by the user. Allows giving a name to the repository configuration to distinguish the various configurations. By default, the alias of a repository is Default.

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.

8.3. Commit description

By activating this preference, any time you will perform a Save that involves 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 in the Commit Description dialog:

OK: The commit is performed with the given commit description.
Ignore: The commit is performed without the commit description.
Cancel: The commit is canceled. In this case, the user changes are kept unsaved and are still visible locally.

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 occurred in the repository.

The system property fr.obeo.dsl.viewpoint.collab.common.commit.description.max.length can modify the length of the commit message. By default the value is 255. Default value can be modified by products even if the system property is not set in the product .ini file. This property needs to be set to the same value on the client and the server.

This default 255 limit is due to the default org.eclipse.net4j.db.h2.H2Adapter that consider the commit comment as a VARCHAR. Increasing the value of this property requires a db adapter that handles that DBField with a type for longer text (like CLOB). If the commit description is longer than the accepted max length, it will be truncated before commit to match the max length in core wizards, actions and session save operations. For components extending the collaborative layer, if they directly call setCommitComment() and commit() methods on the CDO transaction, they can use fr.obeo.dsl.viewpoint.collab.common.internal.commit.CommitCommentUtil.fitCommitDescriptionLength(String) to fit their commit comment. -1 can be used to remove the limitation. Otherwise only values greater than or equals to 10 are accepted. "Xxxxxxxxxx" will become "Xxxx […]". If the property value if -1, it will take the system dependent SWT widget Text.LIMIT length.

8.4. Pre-filled commit description

By activating this preference, any time the user is asked to enter 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 participants 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.:

Default: This entry is a strategy used to select the most suited participant. It selects the first participant that can provide a commit description for the current context. It iterates on all registered participants until one can be activated (Mylyn, CDO History etc…). It starts from the one registered with the lowest priority in the extension point. The order of priority is represented by the order in the list below the default entry in the preference page (first at the top).
Optional Mylyn: This entry uses the current activated Mylyn task to build a commit description. It only uses tasks that are not completed. If there is no active (not complete) task, it provides an empty description. The description can be customized using the template defined in the preference page "Mylyn" > "Team". Activation criteria: There is an active Mylyn task (not completed).
CDO History: This entry uses the CDO History of the current repository. It gets the last commit description entered by the current user and uses it as a pre-filled commit description. It is only activated if the current session uses authentication. This participant also excludes commits that are tagged as technical commits. Activation criteria: The user is authenticated on the CDO Server.

By activating the preference "Automatically use the pre-filled description when none is provided", any time the user commits and do not specifically provide a commit description, the description computed from the mechanism described above will be used.

8.5. Session timeout

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.

9. Collaborative Session Details

The properties page (contextual action) on aird files of a shared modeling project has a tab named "Collaborative Session Details". It presents:

Repository information (location, port and name)
Information about connected users on the repository. With an anonymous server, there is only the number of connected users.
Locked elements for this connected project. Note that locks taken on table or tree content are not shown if the representation is not loaded.

Example: