Working with Collaboration Server

Navigation: Administration >

ABACUS Collaboration Server is both a ‘non-locking’ collaborative approach, but a ‘disconnected’ one also. ABACUS is ‘non-locking’ because it doesn't force the file to be locked by one user for it to be updated. Each user has their own local copy of the file, and as they make changes and save their file, those changes are recorded and stored for when the user wishes to commit them to the server.

ABACUS is ‘disconnected’ in the sense that you don’t need to be connected to the server or need network access whilst working on a file. ABACUS only requires access to the server when performing operations like creating a file, or performing a checkout, along with operations on an existing file - update, commit, or viewing the log of past commits. Access to the server is not required to work on the file, and your changes aren't sent to the server immediately (this allows you to easily discard your changes if you make a mistake). When you save your file, you are ‘just’ saving your copy locally – it is not until you commit that your local changes (changes made since your last commit), are sent to the server.

Creating a New Collaboration File

To create a new Collaboration file, select File | New ... and then select one of the first two options under the Collaboration Server Project section of the New Project dialog (i.e. either a blank Collaboration file, or create one from an existing ABACUS file). The third option is to ‘Checkout’ an Collaboration file someone else has already created, this will be covered in the next section.

When you choose to create a new Collaboration file, you will be given a dialog that will allow you to browse to where on a repository server you would like to store your file. It will also have the existing file path and name entered up the top if you chose ‘From Existing Model’ from the New Project dialog and supplied a file.

Creating a new Collaboration Server Project

URL: This is the URL to your repository server where the ABACUS Collaboration files are stored. You should ask the person who is managing the server what this URL should be.

The picture above shows a repository with four (4) existing ABACUS Collaboration projects, after entering the URL and pressing enter. You will see after you create a new Collaboration file, on the next screenshot for ‘Checkout’, there will be another folder and file under this repository.

Note

If you are using an https (SSL) server, and the server doesn't have a valid SSL certificate (common for intranet or non-public servers due to the cost of SSL certificates) there will be an extra step to take. You will be required to permanently accept all connections to that server in the dialog that pops up (it will also show a bit more information on the server). To do this, type 'p' (without the quotes) and press Enter. ABACUS will pop up a message reminding you of this before showing the dialog.

Note

You may be asked to login to the server in which case the person who is managing the server can provide the server username and password. Also, the login credentials for any servers that you have connected to are saved so if for any reason they need to be cleared this can be done via Tools | Options and then on the General tab by clicking Reset Subversion Saved Login and selecting the server from the drop-down list and clicking Clear Login and selecting OK in the dialog that appears.

Note

Unlike the screenshot shown above, typically a single ABACUS Project is included in each ABACUS Repository because if more than 1 ABACUS Project is created in a single ABACUS Repository, the ABACUS change log numbers are shared across all ABACUS Projects and this may confuse the users.

Preferred Filename: This affects both the folder and filename that will be used (if not already taken) when creating the file on the repository server. Note that a new folder is created automatically on the repository server for each file (for performance reasons, ABACUS Collaboration files are created in their own folder under the location browsed to in the dialog).

Store Working Copy in Directory: When a Collaboration file is created on a repository server, local working files need to be created on your computer, so you can work on the file without being connected to the network. This is the place that you will browse to when you want to open/re-open a ABACUS Collaboration file.

Checkout an Existing Collaboration File

If someone has already created a new Collaboration file, you can ‘checkout’ this file, which downloads a local copy and sets up the necessary files so ABACUS recognises this as a Collaboration file. The dialog is similar to the New Collaboration File Dialog. Enter the repository URL (subdirectories can be included in the URL), select the required file, and click OK. Subject to the note below the file will then be opened.

Note

Checking out an existing Collaboration Server Project

Collaboration File Differences

When you have created a Collaboration file (either a new one, or via ‘checkout’ of a file created by someone else), a folder will be created for the file, and it will commonly contain these 3 main types of files:

•‘.abacus’ file - this is the ABACUS file itself. Changes you make locally aren't immediately saved into this file, it is only written to when you commit. This file is a ‘normal’ ABACUS file, it can be given to non-EE users as a stand-alone project (without the .log file), or used as the starting point for a new Collaboration file.

•‘.changes’ file – the local (uncommitted) changes made to the file. If this file is missing, this means there are no local changes.

•‘.log’ file – this file has only the changes that were made by the last user (the contents of the user’s .changes file when they committed).

Note

There are various other files that may be created during the update and commit processes, namely; ‘.changesbefore’ file - this file is a copy of the .changes file after an update has been performed and is used to automatically reconcile any ID conflicts between the update and any local (uncommitted) changes before commit; ‘.backup’ file - this file is a copy of the .changes file before a user saves more local (uncommitted) changes to the .changes file; and ‘.error’ file - this file is a copy of the .changes file if there was any issue that caused ABACUS to fail to open the .abacus file and the user chose to revert their changes. These files may be ignored.

Opening a File

To Open a file, you only need to browse to where you chose to store the working copy, and open the ABACUS file that is stored there. When ABACUS sees that there is a .log file (and maybe a .changes file if you have made changes), it will treat the file as a Collaboration file.

Updating a File

Performing an ‘Update’ will check if a newer version of a file is located on the server. If there is, it will update to the newer file from the server, and download some temporary files that have a number as an extension – e.g. ‘Demo.125’. These files are the older versions of the .log file, and are used to determine what changes have been made to a file since you last updated it. This is needed to detect any conflicts that may have occurred so that you can resolve them.

If during the update process any conflicts were found, you will need to resolve them before you can open your file again (you can cancel but you will be prompted to resolve the conflicts again the next time you open your file and the file will close).

Automatic Update Reminder

While your ABACUS Collaboration file is open, there is an update reminder at user specified intervals which will give a notification that there are changes committed to the current file being worked with which will then give the option to update the file to the latest version. See Collaboration Automatic Update Check for more information on setting the update notification intervals.

Saving a File

When you save a file, this appends any changes you have made to the .changes file. It does not modify the .abacus file at this stage – only when the file is committed to the server will it be written over (or when you receive an update from the server).

Where is ‘Save As’?

There is no concept of Save As for Collaboration files. You can however, copy your working copy .abacus file, keeping in mind that it wont have your local changes in it.

Resolving Conflicts

If other users have committed changes to the file in a similar part of the file to you, there may be some conflicts between their changes and yours. For example, another user may delete a component that you had update a property on. You need to either undo their change (if you are sure that theirs shouldn't have happened), or discard your change (you may then go back into the file and redo your change).

Specifically there are 4 classes of conflicts that can occur;

1.Delete - When one user deletes an object that another user changes. E.g. User A deleted a component but User B changed the component's name or connected to it or added a child component to it etc.

2.Attribute - When two users both change the exact same 'attribute' of an object. E.g. Both User A and User B changed a component's name or its description or the value of one of its properties etc.

3.Reference - When two users change the exact same 'reference' an object has to another object. E.g. Both User A and User B changed a component's type or the source/sink component attached to a connection or the linked viewpoint for a diagram etc.

4.Collection - When two users change a 'collection' for an object. E.g. Both User A and User B moved a component from one parent to another or re-ordered a collection of children components.

Note

Various inconsequential conflicts are automatically resolved by ABACUS to minimise the overhead on users. For example any conflicting pan-zoom settings for diagrams are resolved to keep the latest pan-zoom settings.

Tip

For large amounts of conflicts, a simplified conflict resolution will be available instead giving the options Recommended to keep your conflicting changes aside from delete changes, Preference Mine to keep all your conflicting changes over theirs, and Preference Theirs to keep all their conflicting changes over yours.

Reviewing Changes

To view your uncommitted/unsaved changes, select File | Review Changes...

Note

This feature is usable in non Collaboration files where you can view a list of "Unsaved" changes, whereas Collaboration files will show you all the uncommitted changes, including the ones from the changelog file that haven't been committed.

User Action: The User Action column lists the action associated with the change that occurred.

First Object: The First Object column lists the first item to change as a result of the User Action.

Note

This is the very first item that has changed as a result of the action, where some actions can have multiple changes but not all are recorded. E.g. When the user deletes a component type, that component type being deleted may not be the first object, rather the unattachment of a component to a connections sink/source would be the first recorded change and be referenced when using the Show In Explorer functionality.

Field: The Field column lists a small description of the type of change that occurred.

Before: The Before column lists how the items attributes were prior to the User Action. In some cases, usually when creating new items this will be nothing.

After: The After column lists how the items attributes are after the User Action. In some cases, usually when creating new items this will be nothing.

Date/Time: The Date/Time column lists the dates that each of the change occurred.

Clicking the Show In Explorer button while having a change selected will highlight the item in the explorer.

Tip

You can get the same behaviour as selecting the Show In Explorer button by simply Double-Clicking the change!

Committing Changes

When you choose to commit your changes, the ABACUS file from the server is opened, your local changes are performed against it, and then your local .abacus file is overwritten with one that has your changes in it. Your changes file then overwrites the .log file, and both the .abacus file and the .log file are sent to the server. If the commit is successful a Commit Message dialog as shown below is provided to enter a message with the commit.

Note

The Commit Message is limited to 10000 characters.

Commit Message

Viewing a Log of Changes

To view a log of the changes to an Collaboration project, select File | View Log...

Viewing Log of changes

Maximum Log Entries: This will default to the last 10 entries but additional entries can be retrieved by changing the value and clicking the Retrieve button.

Revision: The Revision column lists the revision numbers committed to the Collaboration server, by default, in reverse chronological order.

Note

The revision numbers may not be continuous as only the ABACUS commits will be listed while the same Subversion repository may be being used for other ABACUS projects and/or other version control applications.

Date: The Date column lists the date that the revision was committed to the Collaboration server.

Time: The Time column lists the time of day (in 24 hour format) that the revision was committed to the Collaboration server.

Author: The Author column lists the Microsoft Windows login name for the user that performed the commit followed by their ABACUS user name, or 'Anonymous' if the user is not authenticated and anonymous users were allowed access to the Collaboration project at the time of the commit.

Log Message: The Log Message column lists the commit message that was provided with the revision as per the dialog shown above.

Download revision XX as stand-alone ABACUS file: If you select a given revision in the table and then click the Download button you will be able to extract the chosen ABACUS project revision from the server and save it as a local / stand-alone ABACUS project.

Note

To roll back to a previous revision please see this Avolution community article. If your ABACUS Collaboration Server Project is corrupt and you want to roll back, please see this article.

View change log for revision XX: Users can select a given revision in the table and then click the View Log button to show the chosen ABACUS project commit log files changes in this form. You can also select the Export button to extract the shown ABACUS project commit changes from the server as an .xml file.

Viewing an Audit Trail of Changes

To view an audit trail of the changes to any given element (i.e. component, connection, view, children etc) of a Collaboration project, right-click the element and select Audit Trail..., set the From and To Revision range and click Search.

Audit Trail of changes

Note

Once an element is deleted from the project you are no longer able to access specific audit trail information about that element. You can, however, still access the 'parent' component (for example) and see audit trail information about the deletion (in this case listing the ID of the element that was deleted). Furthermore, Component / Connection attachment is a 'property' of the connections so changing an attached component through the Explorer window or on Diagrams will show in the audit trail for a connection NOT the component, and deleting a connection and creating a new connection (as happens if you right-click 'Unattach' and then 'Connect ...' in catalogues) will result in loss of audit trail information for the original component - connection attachment altogether.

Note

By default the audit trail will recursively check for changes to any of the children of the selected element. This may result in long response times and accordingly the audit trail can be restricted to the element itself by deselecting the Recursive option under the Audit Options 'gear wheel' toolbar button in the Audit Trail dialog.

From Revision: This will default to the first / oldest revision available for the project on the Collaboration Server.

To Revision: This will default to the last / most recent revision available for the project on the Collaboration Server.

Note

After setting the From and To revision range click the Search button to retrieve any specific changes to the chosen element.

Revision: The Revision column lists the revision numbers committed to the Collaboration Server, by default, in forward chronological order.

Note

The revision numbers are unlikely to be continuous as only the revisions relevant to the chosen element will be shown and only the ABACUS commits will be listed while the same Subversion repository may be being used for other ABACUS projects and/or version control applications.

Date: The Date column lists the date that the user action was made.

Note

The date shown is the user action date, not the date the revision was committed to the Collaboration Server. Accordingly, the date may precede the corresponding revision commit date shown with the File | View Log... command.

Time: The Time column lists the time of day (in 24 hour format) that the user action was made.

Note

The time shown is the user action time, not the time the revision was committed to the Collaboration Server. Accordingly, the time will most probably precede the corresponding revision commit time shown with the File | View Log... command.

Author: The Author column lists the user that performed the action's Microsoft Windows login name followed by their ABACUS user name, or 'Anonymous' if the user is not authenticated and anonymous users were allowed access to the Collaboration project at the time of the user action.

Note

The Author listed in the Audit Trail dialog may not necessarily match the Author listed in the View Log dialog above for the same revision. This is because the View Log dialog lists the logged in user at the time of the commit while the Audit Trail dialog lists the logged in user at the time of the user action, and it is possible to have one user make changes and send their .changes file to another user to commit - as is the case when an external user (such as Avolution) is to work on a Collaboration project.

Details: The Details column lists the exact details of the user action as recorded at the Collaboration Server.

Tip

It is useful to group by the Revision column (as shown in the dialog above) and/or the User Action column to easily classify the changes to the element of interest.

Use of Scripting with Collaboration files

If you use scripting with Collaboration files, you should be aware of how to correctly delete an object from the model. Generally, when you are deleting an object, you will call the .Delete() method on it, rather than only removing it from its parent.

E.g. if you had comp1 as the parent of comp2 and you wish to delete comp2 in your script, you should call comp2.Delete(), rather than comp1.Components.Remove(comp2).

You may use remove if you intend to add the comp2 object to another place within the architecture, but it shouldn't be used if the intention is to delete the object.

There is an exception to this, for when you want to remove an object that 'lives' elsewhere in the model. When you wish to remove a standard instance from an architecture/component/connection, then you would do so by removing it from the instance's standard collection - arch1.Implementations.Remove(imp) - because deleting it would remove it from all instances.

Correctly using Delete in scripts is important because if an object is removed from the objectmodel and not re-added, then it won't be able to be located, but since it wasn't specifically 'deleted', Conflict Detection and Resolution will not correctly detect a conflict if another user was to attempt to use that object in any of their changes, and the end result will be a corrupted set of changes for that user.