versiondog user guide - cern
TRANSCRIPT
EDMS NO. REV. VALIDITY
0000000 1.0
DRAFT
REFERENCE
XXXX
Date : 2016-04-28
VersionDog
User Guide
This document describes basic functionalities of versiondog UserClient
DOCUMENT PREPARED BY: DOCUMENT CHECKED BY: DOCUMENT APPROVED BY:
Marcin Bes [BE-ICS]
Jeronimo Ortola Vidal [BE-ICS]
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 2 of 20
HISTORY OF CHANGES REV. NO. DATE PAGES DESCRIPTIONS OF THE CHANGES
1.0 2.0
13 Oct 2014 04 Apr 2016
1-12 1-20
First Version (M. Bes) Update (M. Bes)
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 3 of 20
TABLE OF CONTENTS 1. Introduction .......................................................................................................... 4 2. Becoming a versiondog user ................................................................................... 5
2.1 Installation of versiondog client ........................................................................... 5 2.2 Request for a user account. ................................................................................ 5
3. First login ............................................................................................................. 5 3.1 Configuration of the servers ................................................................................ 6
4. Checking-out projects from the server ..................................................................... 8 4.1 Server directories .............................................................................................. 8 4.2 Check-out ......................................................................................................... 9
5. Creating a new project .......................................................................................... 10 6. Working with project ............................................................................................. 13
6.1 Local archive .................................................................................................... 13 6.2 Modifying a project ........................................................................................... 14 6.3 Creating new local version ................................................................................. 14 6.4 Comparing local versions ................................................................................... 17 6.5 Standard job .................................................................................................... 17
7. Check-In (storing local version on server) ................................................................ 18 8. Jobs – versiondog scheduled actions ....................................................................... 19
8.1 Request for job configuration ............................................................................. 19 8.2 Checking results of Jobs .................................................................................... 20
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 4 of 20
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.
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 5 of 20
2. Becoming a versiondog user
2.1 Installation of versiondog client
Installation is described in a document “versiondog InstallationGuide”.
2.2 Request for a user account.
To use versiondog you need a user account. It will be created by the group admin responsible for managing the group you belong to or you can request it by sending a request to [email protected].
Your username should be the same as your NICE account login. When logging into the versiondog client use your NICE account password and you will be authenticated by the operating system.
3. First login Once you have your account and the versiondog client is installed on your machine you can start it by choosing UserClient from the start menu:
Figure 2 versiondog directory in the Start menu
The other client installed next to UserClient are:
- AdminClient – a tool for administrators
- EasyClient – very simplified, but limited version of UserClient
- ReportClient – a tool for monitoring online changes in the versiondog system as check-ins, check-outs, creating new versions, job results, etc.
When you start UserClient login window will appear:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 6 of 20
Figure 3 versiondog UserClient login window
3.1 Configuration of the servers
Versiondog installer already contains the server configuration, so it’s not necessary to configure it manually.
In case of missing configuration (as in the picture below), follow instructions.
To specify a connection with the CERN versiondog server select “Server settings…” from the drop-down menu:
Figure 4 Configuring new server
In the next windows choose “Add a server”, enter the configuration name (any name you want) and the versiondog server name (vdog-srv-01). Leave the Ports configuration with default values:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 7 of 20
Figure 5 Server configuration
Once the values are entered save the configuration and close the window.
Now you can login using your NICE username and password (enter CERN in the domain field):
Figure 6 Login window
On the first run you will be asked for the configuration of the parallel server:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 8 of 20
Figure 7 Parallel server configuration
Put the names as on the picture above and confirm by clicking OK.
4. Checking-out projects from the server
4.1 Server directories
To see what is stored on server you can click “Show server directories”
Figure 8 Server directories
After checking this field you can see the current structure of the projects on the server (grey font).
In the section “Component overview” you can see all projects (in versiondog called “components”) stored under the selected path:
Figure 9 List of projects
You should see only the projects inside the directory prepared for the group you belong to.
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 9 of 20
4.2 Check-out
To download a project from the server archive to your local archive, select one or more entries on the list and choose “Check-Out (take selection)”:
Figure 10 Check-Out of selected items
In the next window you can select or unselect projects to be copied by moving them between left (server) and right side (your selection).
Figure 11 Copy from server to local
When copying projects you can set:
- The number of versions to be copied from server (so you can see the history of changes)
- The “Under development” checkbox - you can leave an information to other users that this project is currently processed and no one should touch it.
You can even lock the access to the project, so no one else will be able to store a newer version of this project before you do this:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 10 of 20
Figure 12 Under development
Once you make your selection click the “Copy all selected components from server to local” button. When copying is finished you will see the status next to each component:
Figure 13 Check-Out state
The Check-Out window can be closed.
5. Creating a new project To create a new project, first create a new directory for it in an appropriate place in the hierarchy of yours group’s workspace.
If there is no directory structure prepared for your project, contact your Group Admin to get instructions on how to proceed.
Your local archive directory hierarchy should match the hierarchy of directories on server:
Figure 14 Creating new directory
Once the directory is created you can create new “component” inside:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 11 of 20
Figure 15 Creating new component
In the next step choose what type of project will be stored in this location (S7/Unity/TIA, etc):
Figure 16 Component manger
Once you made your selection, choose “Create Component”.
In current form the created component is empty and you have to provide project files.
Figure 17 Empty project
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 12 of 20
To do this, just select “Open file manager” and this will open the directory prepared for your projects. It’s enough to copy-paste your project files into this directory:
Figure 18 S7 project directory
Figure 19 Unity project directory
At this point you have only created a component with project files. It’s only a working copy and no local version of your project was created. To create base version with provided files select “Create base version”. It's a good practice to rename a created component so it’s easier to find it on the list of projects.
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 13 of 20
Figure 20 Renaming a component
6. Working with project
6.1 Local archive
During development project is stored in your local archive (by default directory C:\vdClientArchive). You can see and modify its structure in Project tree. Black font corresponds to the entries stored on your machine, grey – the ones on the server.
Figure 21 Project tree representation of local archive (black) and server archive (grey)
Below you can see projects stored in the archive:
Figure 22 List of projects in local archive
To start working on one of projects double click on the corresponding line or expand the Project Tree until you reach your component:
Figure 23 Single project view
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 14 of 20
Upper part of the window presents a summary of the project. In the lower part you have list of versions in your local archive (in the example only the initial one).
6.2 Modifying a project
To create new version you need to introduce changes in the project. You can open an editor (Unity, Simatic, etc) directly from versiondog:
Figure 24 Starting an editor
When your changes are done you will see that “Edit state” is no more “Equal”, but “Different”:
Figure 25 “Different” Edit state
6.3 Creating new local version
Once you consider your changes in working copy are completed you may create new local version. To do this select “Create new version” from the ribbon menu or right-click menu:
Figure 26 Creating new version
When you create new version, versiondog looks for differences and gives you a report:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 15 of 20
Figure 27 Change report
Once you accept the changes, put a change reason for the new version and click “New version”. You can also introduce detailed change reasons for each part of the project:
Figure 28 Change reason
As a result you have now two versions of your project:
Figure 29 Multiple versions of a project
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 16 of 20
You can also create new version without any changes (Extras->Version without difference), but usually there is no good reason to duplicate versions.
Status of comparison “Local<->Server” was updated and now shows:
Figure 30 “Local <-> Server” Status
Analogically, status “Server newer than client” would mean that someone checked-in to the server with new version and the one in Local archive is not up-to-date. To avoid such situations, always check-out with option “Lock for other users”.
6.3.1 Creating new version without comparison
In some situations comparison might be undesired step as it is time consuming. You might create new version without comparison by selecting Version without Difference:
Figure 31 Version without difference
Versiondog won’t compare created version and will only ask about a comment:
Figure 32 Commenting new version without difference
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 17 of 20
6.4 Comparing local versions
When you select version on the list you will get the detailed info about the changes in comparison with the previous version:
Figure 33 Differences between two last versions
To get more detailed information (as the one when you create new version) you can request detailed comparison:
Figure 34 Getting detailed differences
In general, it’s possible to compare any two versions on the list and compare any version with working copy:
Figure 35 Compare options
6.5 Standard job
For each project one of the jobs (a command scheduled by your GroupAdmin) can be selected as “Standard job” for the component.
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 18 of 20
If your project has its “Standard job” you can use functionality called “Upload and compare”. This way you can request upload of the program from the PLC and compare it with your working copy.
If the functionality Upload and compare is not available (greyed out) contact your administrator to configure this functionality.
Figure 36 Upload and compare
7. Check-In (storing local version on server) To send your local version to the server select your project and choose “Check-In (take selection)”:
Figure 37 Checking-In a project
For check-in process new window shows up:
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 19 of 20
Figure 38 Local to Server copy manager
Here you can select which projects you want to send to the server.
By default “Reset working state” checkbox is checked to remove lock from the project or status “in development” to release the project for other users.
Once you click “Copy all selected Components from local to server”, version is copied and as a result you will receive information about the check-in state:
Figure 39 Successful Check-In state
Additionally, status “Local <-> Server” should be “Equal”:
Figure 40 “Local <-> Server” Equal state
8. Jobs – versiondog scheduled actions
8.1 Request for job configuration
For each project stored on server your group admin can configure Job. Job is a scheduled command that, depending on configuration, will:
- Upload project data from a PLC - Save that data as a backup on the server
REFERENCE EDMS NO. REV. VALIDITY
XXXX 0000000 1.0 DRAFT
Page 20 of 20
- Compare saved backup with: previous backup and/or latest server version. Job will be executed periodically on agents machines and will provide report on the result by email.
To configure a schedule for your project you should contact your local admin and provide following information set:
- Name of the component (project) - IP address of the PLC - Information on who should receive email notifications after Job is executed.
If you have a special requirements regarding the configuration of the frequency of a Job execution or the settings of comparator (what should be compared), discuss possible options with your GroupAdmin. Otherwise, a default optimal configuration will be used.
8.2 Checking results of Jobs
After a job is executed results are inserted into the versiondog database. You will also receive an email with a summary of the result if your GroupAdmin configured this for you. The result of the last comparison between server version and PLC project is displayed in the project summary:
Figure 41 Server<->Device state
You have the access to the backups in Backup section:
Figure 42 Backup tab
When you select a project you will see list of stored backups:
Figure 43 List of backups