REFERENCE EDMS NO. REV.

VALIDITY

XXXX 00000000

Page 1 of 33

VersionDog
Group Admin Guide

This document describes basic functionalities

of the versiondog AdminClient and provides guidelines for
administration of versiondog in the CERN infrastructure

DOCUMENT PREPARED BY: DOCUMENT CHECKED BY: DOCUMENT APPROVED BY:

Marcin Bes [BE-ICS] Brice Copy [BE-ICS]

Montserrat Gonzalez Corral Jeronimo Ortola Vidal
[BE-ICS] [BE-ICS]

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 2 of 33

HISTORY OF CHANGES
REV. NO. DATE DESCRIPTIONS OF THE CHANGES

1.0 17 Jul 2011 First Version (M.Bes)

2.0 9 Oct 2015 Second Version (Montserrat G.C)

3.0 11 Nov 2015 Added sections User group management and Jobs
configuration (M.Bes)
4.0 29 Apr 2016 Update (M.Bes)

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 3 of 33

TABLE OF CONTENTS

Contents
1. Introduction .......................................................................................................... 4
2. Administration of versiondog ................................................................................... 5
3. Installation of the AdminClient ................................................................................ 5
4. Overview of the admin client ................................................................................... 5
5. User group management ........................................................................................ 7
5.1 Creating a new group of users ............................................................................. 7
5.2 Creating a new workspace for the group ............................................................... 8
5.3 Access rights management ............................................................................... 12
5.4 Adding users ................................................................................................... 17
5.5 Adding users using the LDAP synchronisation ...................................................... 18
6. Jobs Configuration ............................................................................................... 20
6.1 Common settings............................................................................................. 23
6.2 Time Plan ....................................................................................................... 24
6.3 Compare settings ............................................................................................ 26
6.4 Component-type specific settings ...................................................................... 28
6.5 Activating the Job ............................................................................................ 31
6.6 Checking the results of the job .......................................................................... 32
7. Final considerations ............................................................................................. 33
8. Other resources ................................................................................................... 33

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 4 of 33

1. Introduction

versiondog is software dedicated to PLC projects management. Main goals of versiondog are:
version and backup management
data backup
reporting
quality management

versiondog is a software with Client/server architecture as depicted below:

Figure 1 Example of client-server model

All projects are stored on servers whereas clients are distributed among user computers. Every
time user checks-out project from the server files are copied to his local machine and can be
modified, tested and locally versioned. After applying changes, user checks-in to the server with
new version of the project. History of changes is maintained with a minimal contribution of a
user.

Development of a PLC code is kept outside the versiondog and is still done with dedicated tools
as Simatic Step7 or Unity.

versiondog has a schedule mechanism called Jobs that automatically creates a backup of the
program running in a device and checks coherency of the retrieved program with a version
stored on server.

Service of versiondog in CERN infrastructure is provided to manage projects in

production and not in development.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 5 of 33

2. Administration of versiondog
All administrative tasks are done using the versiondog AdminClient which is installed next to
the UserClient and other clients:

Figure 2 versiondog directory in the Start menu

To login to the versiondog AdminClient you need to have the administrator rights. In order to
become a versiondog administrator send a request to [email protected].

The administration tasks are split among group admins. The main responsibility of each one is
to:

- Prepare the workspace for the group and maintain a clear structure of projects
- Manage a user group and its access rights
- Coordinate a schedule for projects according to needs of users

There are no different admin rights levels, so each administrator has full access to all
user groups, projects and program settings.

Since its not possible to programmatically prevent from interfering with areas that
are not under admins responsibility its crucial to stay self-disciplined when
undertaking actions to avoid problems.

3. Installation of the AdminClient

The AdminClient is installed next to the UserClient. The installation procedure is described in the
document versiondog InstallationGuide.

4. Overview of the admin client

The versiondog AdminClient is composed of several modules related to different aspects of the
versiondog system. The picture below presents the main window of the versiondog AdminClient.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 6 of 33

Figure 3 An AdminClient overview

The only parts related to Group Administrators responsibilities are the modules User
management and Jobs.

Only one administrator can start the Jobs or User management module at the
same time. Once its opened other administrators will get the information that
module is not accessible.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 7 of 33

Figure 4 Information about no access

Once changes in user management or Job configuration are done administrator must
save the changes and close the module.

5. User group management

This chapter describes best practices in user management and provides short step-by-step
instructions on how to configure a group of users, its working directory and its access rights.

5.1 Creating a new group of users

5.1.1 General information [from versiondog documentation]

User Management in VersionDog is group-oriented (it uses groups for users and
rights management). If necessary, you can manage rights on a user-by-user basis,
but we strongly recommend that you manage the rights with groups.
If rights are assigned directly to individual users, it becomes challenging to keep
track of who has which rights to which components (projects).

Create a few basic users groups and then create other groups with more and more
rights. These rights are often related to responsibilities within your user structure.
Use the responsibilities to name the groups and as a guideline to assign the rights.

If there is no strict need of differentiating the access level to your projects for different users,
we recommend to keep all your users in one group with the same access rights to all the
projects in the groups workspace.

5.1.2 Creating an empty group of users

To create a new group of users go to the User management module in the versiondog
AdminClient and choose Create new group.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 8 of 33

Figure 5 Creating new group

As a result a new empty group of users is created:

Figure 6 New empty group of users

In order to finish, enter the correct name of the created group and save changes.

5.2 Creating a new workspace for the group

For each group there should be created one directory for projects storage. Afterwards you can
create as many subdirectories as your group needs. Having such a structure will allow you to
limit the access of different groups of your users to different directories.

To assign group rights to specified directories, these directories must exist in versiondog. Each
directory path is seen in versiondog only if it contains at least one component (it cannot be
empty path).

The procedure of creating a directory structure is explained below.

To create a directory, login into the UserClient (as a regular user) and go to the Project Tree
on the left side of the window:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 9 of 33

Figure 7 The project tree

Right-click on the Client archive entry and select Edit->Directory:

Figure 8 Creating new directory for a group

Name the directory with exactly the same name as the name of the main group of
users you are responsible for.

As a next step create a new directory inside the one you created and name it EmptyProject:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 10 of 33

Figure 9 Creating a directory for fake component

Right-Click on the EmptyProject directory and select Edit->Component to add a new

component:

Figure 10 Creating new component

In the next window select the Siemens->SPS->Simatic S7 component type (the type does not
really matter, it has to be any empty component) and choose Create Component:

Figure 11 Creating new component

As the last step Check-In with created empty Component by selecting it and choosing Extras-
>Check-In component without base version (take selection):

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 11 of 33

Figure 12 Check-In with an empty Component

Click Copy all selected Components from local to server:

Figure 13 Copying local data to server

Once Check-In finishes you should see the Successful Check-In state:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 12 of 33

Figure 14 Check-In state

Now you can close the UserClient.

Instead of creating an empty fake component you can provide any real project that
will be stored in versiondog for your group.

Creating a component (empty or a real one) is necessary to create the directory

structure inside the versiondog. After configuring this, group-admin can assign
correct access rights for a group.

If there are no contraindications its recommended to keep all users in one group
that has the access to all projects in its workspace.

Once the access right for the group are assigned (as described in the next section),
the EmptyProject might be deleted. It is created only in order to make the
directory path visible in the UserManagement module of versiondog.

5.3 Access rights management

5.3.1 General outlines

When granting and removing user rights, it is important to have an organised approach.
Otherwise it is easy to lose track of who has rights to what, and where those rights came from.
One important discipline is to use user groups. It is easier to keep track of group rights, and in
the long run the use of groups will mean you spend less time on rights management.

Take special note of the following six key points when granting and removing rights:
1. Rights are cumulative. "Read" is the lowest level, then "Edit" then "Create", and
"Delete" is the highest.
This is why you cannot give a higher right without giving all lower rights at the same
time. Checking the "Delete" rights box, for example, will result in all four boxes in the
row being checked. Checking the "Read" rights box (the lowest) will result in just
"Read" rights being granted.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 13 of 33

2. After you have made any changes to rights, you need to SAVE or DISCARD them on
the ribbon.

Figure 15 No pending changes

In the screenshot above there are no pending changes (both "Save" and

"Discard pending changes are greyed-out).

Figure 16 Pending changes

In this second screenshot, "Save" and "Discard pending changes" are not
greyed-out, so changes have been made and need to be either saved or
discarded.

3. Individual user rights remain, no matter what you do with group rights (a reason to
avoid individual rights).
If you follow the best practices for managing users in VersionDog and stick to group
rights as far as possible (or even, ideally, exclusively) then you will not have to
constantly check if individual rights have been left after removing group rights.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 14 of 33

Actions that remove group rights DO NOT remove any individual rights that have
been granted.
4. A green check-mark in "User management" is the root of a right and a grey check-
mark is an inherited right.
o If you click on a box that does not already contain a green check-mark, then
a GREEN check-mark will appear for that right and GREEN check-marks for each
of the lower rights (to the left) will also appear. You have just granted all those
rights.
o If you click on a box that does contain a green check-mark, then the GREEN
check-mark will disappear for that right and any existing GREEN check-marks for
higher rights (to the right) will also disappear. You have just removed all those
rights.

5. Inherited rights are not designed to be removed directly, so you cannot uncheck a
grey check-mark.

If you try to uncheck a grey check-mark to remove an inherited right, then you will
find that instead of the grey check-mark disappearing, a green one will appear. In
fact, it might look like the grey check-mark has changed colour green, but what you
have effectively done is put a green check-mark ON TOP of a grey one. Inherited
rights (grey check-marks) cannot be removed directly, they have to be removed at
their root.

Hover the cursor over the check-mark and wait for the tooltip to tell you where the
root of that right is.

If you want to remove some of the inherited rights of a user or a number of users in
a group, but leave the existing rights for other members of the group (while sticking
to the recommended group rights strategy), you need to create a new group for the
user/users with the lower rights.

A group with one user is not a problem; it may in fact save a lot of time later if you
find you need to add another user with the same rights.

6. You can always find the root of an inherited right by hovering over the grey check-
mark and waiting for the tooltip.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 15 of 33

Figure 17 Inherited rights

7. If you need to remove rights from a user, just move the user out of the
corresponding group. If you always manage rights by groups, you can be sure that
the user will not retain rights to anything that they should not have access to. That
way, no rights will be carried over without your knowledge (something it is difficult
to be sure of if you assign rights to a user, not to a group).

5.3.2 Assigning rights to a user group

In AdminClient, go to the User management section and choose Extras -> Right per path:

Figure 18 "Rights per path"

In the next window, select your group directory in the Project tree on the left side and set proper
access rights in the group window by changing the default setting:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 16 of 33

Figure 19 Default access right for All Users

to the one that would give an exclusive access to the directory only to your group:

Figure 20 Limited access to the directory for the specified group of users

After changing the access rights close the window and click Save in the main UserManagement
window:

Figure 21 Save settings

In case you see Users instead of Groups in the Rights per path window:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 17 of 33

Figure 22 Rights Per path views

Click the button in the upper right corner to switch the view.

5.4 Adding users

To add a user select Create new user in the Start tab on the navigation ribbon:

Figure 23 Adding a new user

In the next window complete the data of the user and select the group(s) he should be assigned
to:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 18 of 33

Figure 24 A new user empty form

The username should be the same as the users NICE account login and the domain should be
set to CERN. This way user will be able to login using his NICE account credentials.

5.5 Adding users using the LDAP synchronisation

Its possible to import users massively using a synchronisation with the Active Directory. To do
this, go to the Synchronisation tab and click Synchronise users/groups from Active Directory:

Figure 25 Synchronisation tab

In the next window specify what Domain/Group you want to scan (in User
name/Password/Domain fields provide details of your own account):

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 19 of 33

Figure 26 Synchronisation form

Accept by clicking OK and you should see the result in the synchronisation manager:

Figure 27 Synchronisation manager

Select users you want to add from the group in the right (you can multi-select, pressing the Ctrl
key) and click the arrow to transfer users to versiondog.

Confirm by clicking OK.

There is no possibility of automatic LDAP synchronisation.

After this step move imported users to your group.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 20 of 33

6. Jobs Configuration
Mechanism of jobs allows you to prepare a schedule to create a backup of the project in the PLC
and compare it with the previous backup and/or the latest version stored on server. The
configuration of Jobs is placed under the Job module in the versiondog AdminClient.

Figure 28 Main window of Job module

To configure a job for the project select it in the Project tree and choose the tab of the project
type in right part of the window (SimaticS7 in this example):

Figure 29 Selecting project for Job creation

To create a new job, click Create new in the ribbon on top:

Figure 30 Create new Job

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 21 of 33

New entry should appear in the list of Jobs:

Figure 31 New Job entry

When you click on the row related to the new Job you will see Configuration of the job in lower
part of the window:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 22 of 33

Figure 32 Job configuration

If you dont see all options, check if the More options button is selected:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 23 of 33

Figure 33 More options button

The configuration section is split into several parts.

6.1 Common settings

This section contains common settings for the job and the configuration for upload from the
device.

Figure 34 Common settings

Job name field purpose is self-explanatory. You should choose meaningful name corresponding
to the project name.
Component is read-only field with the path to the component.
The field Notify contains the list of users that should be notified by an e-mail message about
result of each execution of the Job. You can add users to this list by clicking Edit.

In Save policy you decide under what circumstances backup should be stored on the server.
You can choose from the following options:

Figure 35 Save policy options

Two first options are very similar and the result is the same - new backup will be stored only in
case there were differences between two last backups.
Third option will keep the new backup even if it is exactly the same as the previous one.

Keep in mind that number of backups is limited and the oldest one will be removed when a new
one is created.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 24 of 33

We suggest to set the Save policy to Save current backup only if it is different to the previous
backup and keeping backup count low.

In the field Upload agent select the machine that corresponds to the type of the project. The
main indicator of the agents purpose is placed under its IP number or DNS name.

Figure 36 Selection of an agent machine

Serial number of the versiondog server should be left empty. It allows to decide which one of
servers should execute the Job, but in current configuration agents are used for the schedule
exclusively.

If you select Standard job for this component you allow users to use this Job configuration
to use functionality Upload and compare in the UserClient:

Figure 37 Upload and Compare

The Upload and compare functionality allows users to compare their working copies of the
project with a data source as a PLC.
If there is no Job configured with selected option Standard job for this component user wont
be able to perform this action.
Usage of the Upload and compare functionality is described in the versiondog UserGuide
document.

6.2 Time Plan

In this section you can set the frequency of the job execution and decide what actions should
be taken in case of the execution failure.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 25 of 33

Figure 38 Time plan

To set the frequency of the Job execution click Edit next to the Run field:

Figure 39 Date/time settings

We recommend to execute a job not more often than once a day at a different times to
balance load on the agent machines.

To configure an action in case of a failure click Edit next to On error field:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 26 of 33

Figure 40 On error settings

Here you can specify if the action should be repeated, how many times and what should be the
delay between the next attempts.

6.3 Compare settings

This section is related to the compare functionality.

Figure 41 Compare settings

There are two types of comparison available:

- Comparison between the version (the latest version of component stored on server) and
the last backup (data uploaded from a PLC).
- Comparison between the two last backups.

First (version vs backup) will tell you if the project running in the PLC is really matching the
binaries of the project stored on the server.
Second (last backup vs previous backup) will let you know if the content of the PLC was
changed since the last backup.

You can select both of the comparisons, choose only one or even decide not to compare
anything:

Figure 42 Compare policy

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 27 of 33

Similarly to the Upload Agent configuration you should select an agent with the label
corresponding to the type of the managed project:

Figure 43 Compare agent selection

The comparison between projects is done according to the central configuration of a comparator
for a given component type. Leaving Main configuration checkbox selected, these common
rules will be used for comparison.
However, if you need specific configuration for a comparator, uncheck the box and fill the
comparator configuration in the bottom clicking Comparator configuraton.
This will let you decide what exactly should be compared, as in the following example of Siemens
comparator settings:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 28 of 33

Figure 44 Siemens comparator configuration

6.4 Component-type specific settings

Other sections of the configuration are component-type related, which means they will differ for
different types of projects (e.g. Siemens and Schneider projects).

6.4.1 S7 specific settings

Figure 45 S7 specific settings

In the S7 specific settings you can configure the connection to the PLC and device-specific
options.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 29 of 33

S7 program path is the name of the program in the project and is automatically detected by
the extension *.s7p inside the project.

Access path determines the path of communication between an agent station and the PLC.

Figure 46 Access path options for the S7 component type

Once you select the correct path type for the connection more options will show up, as for
example for TCP/IP settings:

Figure 47 TCP/IP settings

In each case you have to provide the IP address or DNS name of the PLC.

In next fields you have to specify details as CPU slot and Rack and slot CPs. You can detect
this configuration automatically if you have already entered the IP or Name of the device. To
do this click the Automatic button and the following window should show up:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 30 of 33

Figure 48 UploadConfig for Simatic S7

When you click Scan it will scan the selected range on the device:

Figure 49 Results of the UploadConfig scan

This way you can not only automatically detect the configuration, but also confirm that there is
a connection with the device.

For the TCP/IP port field the default port number (102) should be left.

6.4.1.1 Options for S7 component backup

In this sub-section you can specify non-standard backup settings.

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 31 of 33

Figure 50 Options for backup

6.4.2 Schneider specific settings

Configuration of Schneider is analogical to the one related to S7 component.

Figure 51 SchneiderUnity specific settings

The only part you need to specify is the Media (the type of connection) and the IP Address or
DNS name of the PLC.

6.5 Activating the Job

After configuring the Job, save it.

Switch to the Execute tab in the ribbon:

Figure 52 Execute tab

And select Automatic to activate schedule:

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 32 of 33

Figure 53 Activating the scheduled Job

At this point, Job is scheduled and will be executed regularly. You can also invoke the job
manually by clicking Execute selected jobs once (a good practice to check whether the Job
runs correctly).

After configuring Job, do not forget to close Jobs Module. Access to this module is
exclusive and if you leave it opened you will block the access for others
administrators.

6.6 Checking the results of the job

After the job is executed results are inserted into a database. Summary of the result is also sent
by e-mail to the users included in notification configuration.

Results can be checked in the UserClient on the Backup tab:

Figure 54 Backup tab

You can see the list of backups in section at the bottom after selecting your project:

Figure 55 List of backups

1
 REFERENCE EDMS NO. REV. VALIDITY

XXXX 00000000

Page 33 of 33

7. Final considerations
The BE/ICS admin is allowed to:

- Define group admins

- Define component types
- Define group placeholders and tree organization

The group admin is allowed to:

- Define the users of his group.
- Configure the jobs schedule for his projects.

The group admin (can but) SHOULD NOT:

- Modify versiondog settings
- Modify applications of other groups
- Create new admins

8. Other resources
You can find other resources as UserGuide and InstallationGuide or Auvesy documentation
for versiondog on CERNs versiondog website:

https://wikis.web.cern.ch/wikis/display/EN/VersionDog

For requests, questions and problem reporting use JIRA:

https://its.cern.ch/jira/browse/VDOG/