1) What is AVS ?

AVS stands for Advanced Versioning System, it is a SCM software which integrates a file version manager and a bug tracking engine working in pair in a single SQL database.

2) Getting started..

Start the server - Windows, User mode
From Windows "start" menu, or using the desktop shortcut created during installation... the server is being launched for the very first time!

At that stage, the server repository must be created, and this requires a root user: a dialog is prompted to request the root name, password, and optionnaly his mail address for change request notifications.

A checkbox allows the root user to be added in one of the default groups, the "Super users" group. From this group, the root user will be able to manage files, assign change requests to himself, whereas if not, he will only be reserved for administrative tasks. In any cases, this choice can be changed at any time afterwards in the "user management" feature. When started, the server creates an icon in the system tray: red during startup, green once available for clients.

The root user, permanently inserted in a hidden root group, cannot be deleted. When inserted in tbe "Super users" group, he can then create and assign change requests to himself and modify files according to the tasks he will have created on his change requests: he can work with AVS without creating new users if not needed.

Start the server - Windows, Service mode
A Window service is created to let AVS server run in service mode. By default, the service startup is configured as "manual". Open the service control panel from the configuration panel/administration tools and set it as "automatic" if you want to use it. In service mode, AVS server does not use any graphical resources, such as dialog boxes or even system tray.
After installation, the service will not be started. If granting Inno Setup launch suggestion, the server will be launched in user mode, with dialog boxes, splash screen, etc... enabled.
If AVS server is launched for the first time using the service mode, the root user will have its default parameters:

login: root
password: root
superUser: true

Default password should be changed quickly to avoid security issues. Mail can also be changed at any time within the user administration panel available in the client application.
Start the server - Linux/Unix
AVS server can be launched under Linux and Unix with the "launchNoUi.sh" shell, and stopped with "stopAvs.sh". It will then run without graphical components, hence the very first dialog box used to define the root user will not be displayed. Instead, root parameters can be appended to the start command within the "launchNoUi.sh" as follows:
java -cp "avs-server.jar:derby.jar:activation.jar:mail.jar" com.spamworks.sourcemanager.server.logic.SourceServer -noUI -rootLogin=login -rootPws=password -rootMail=mail -rootSuperUser=true or false
If not provided at the first launch, the root user will have following default parameters:

login: root
password: root
superUser: true

Default password should be changed quickly to avoid security issues. Mail can also be changed at any time within the user administration panel available in the client application.

Start the client
At that stage, the database is created and only the root user can log onto the system. To do so, he must open a browser on http://avs-server:8090/client dynamic page, where 'avs-server' is either the avs server hostname or its ip address. If you want to start
AVS client from AVS server host, you can also run the "AVS client" shortcut from the start menu or use the "Start client" from the popup menu available on right-clicking on AVS server system tray icon (only under windows user mode).
AVS server uses the TCP port 8090 hence any firewall must leave this port opened to let the client connect the server.
The start web page contains a link to launch the jnlp client. You can right click on the link and select "Save target as", and put the "avs.jnlp" file on your desktop, to ease next start: double click on the desktop file and the client application will start. For more information about jnlp applications, please go to the following url: http://java.sun.com/developer/technicalArticles/Programming/jnlp/
The client application starts with a login prompt. For the very first login, use "root" and the password you have chosen for the root user above: only the root can login for the moment.

The root user has of course access to all the features, except if he does not belong to any group but the hidden root group: in such case, he cannot be assigned any change request.

3) Manage users

Go in the administration tab of the client application, and select "User management".

The following predefined group set is provided, that can either be modified or even deleted if needed:

- Guest (can only make queries on the change request database)
- Developer (can modify files, create unassigned or auto-assigned change requests)
- Tester (cannot modify files, but full rights on change requests)
- Integrator (can create projects and update templates, unassigned and auto-assigned change requests, and modify files)
- Administrator (can only manage the system: create users and groups, modify the server parameters)
- Super users (all access rights)

You can create as many group as you want. For each group, you can select the access associated within the following list:

- Administer server: create users and groups, modify the server parameters
- Create CR: can create a new change request of any type (bug or enhancement)
- Change CR severity: can modify change requests' severity
- Change CR state: can change a change request state to any state but "closed"
- Close CR: can change a change request state to "closed"
- Auto assign CR: can assign a change request to self
- Assign CR: can assign a change request to anyone
- Query CR: fetch change requests matching a set of given parameters
- Manage projects: create projects, target releases and update templates
- Manage files: can create, delete and modify files and folders

If the administrator has created new change request life cycles, he may also have created new access rights by the way.
If so, those access rights will also appear in the user management panel.

4) Manage projects

To create a project, you need the "Manage project" access. When you do have that access, you have a "project" tab in the client application. Switch to this tab to create projects, define target releases and update templates.
Projects cannot be deleted for the time being, but this feature is planned.

A baseline is an existing version of a project, while a target is a version which is not yet existing but planned to. When creating a task, one must select the target release the task is dedicated to.

An update template must be choosen to update the user's client repository.


An update template always refers to a baseline, a target release, and a task list. When updating the client repository, the update template will work as follows:

- for each file modified by one task within the task list, the update will retrieve the associated file version. If two tasks refer two parallel versions of the same file, the update will retrieve the version of the file associated to the last of the two tasks, and a warning is displayed.
- for all the other files, not modified by any task within the taks list, the update will take the baseline version

An update template can be of 3 kinds:
- "task based": the task list is defined manually by a selection in a list
- "insulated": the task list is dynamic and only contains the list of tasks (opened and closed) by the caller for the target release
- "collaborative": the task list is also dynamic, but contains the list of tasks closed by everyone for the target release plus the open tasks of the caller user.

When creating task based update templates, the default view only shows the list of tasks attached to the target release. But the user can override this by selecting the "Use following baseline tasks" radio button: the tasks of a closed baseline can then be selected.
Updating the client repository may override working files. To avoid data loss, working files under the folder to be updated are always saved onto the server repository before the update starts: if the update brings older version than the version of the working file, the content of the working file version is stored in the server repository and can be retrieved through a "use" action.
Updating the client repository takes in account the user's open tasks, provided he selected an insulated or collaborative update template. In case of conflict on two tasks refering parallel versions of a given file, one of which being the user working file, the update will always retrieve the working version. However, a particular case exists: if the parent folder has parallel versions, one containing the user's working file, and the other not, depending on the tasks' close date, the user working file may or may not be retrieved during update. If not, the "use" action can be used to retreive the working file, since its content has been saved automatically before the update.

Freezing a target release means changing the target release into a baseline. This is a sort of facility to ease next release: you will then only have to define an update template based on this new baseline, and select the tasks closed for the next target release, instead of choosing a list of task from the very beginning of the project life. Thanks to this, the update is not always longer with the time, and the task list does not grow indefinitely, rendering the template usage difficult.

Only task based templates can be used to freeze a project because insulated and collaborative templates are dynamic, and their content may change at any time, even when freezing the project. The project manager can freeze a dynamic template to remove its dynamic property. It becomes then a "task based" template, and can be used to freeze a project. When doing so, check the template task list with the "view" feature before freezing the project !

Project freeze shall lead to warnings in a next release, when the task list defined in the template used lead to conflicts, as it will be when updating the client repository.

5) Manage Scripts

This feature allows AVS server running user defined scripts either every day or on specific events. As of version 2.0.3, supported events are the following:
- task closed
- change request closed
For daily launch, the user must select the days in the week from Monday to Sunday, and the time at which the script should run. This feature enabled nightly build, excludingfor instance off days.

To create a script, the user must define a command line, which will be executed by the server.

This command line can include special keywords which will be interpreted by the server before launch.

%EVENT_TYPE% : identifies which event has launched the script, can take following values: "TASK", "CR" and "DAILY"
%TASK_ID% : identifies the task which has been closed
%TASK_NAME% : gives the name of the task
%CR_ID% : identifies the change request which has been updated to the "in test" state
%CR_NAME% : gives the name of the change request
%PROJECT_ID% : identifies the project on which a task has been closed, or a change request updated in state "in test"
%USER_ID% : identifies the user who has closed the task or update the change request in state "in test"
%USER_NAME% : gives the user name
%USER_MAIL% : gives the user mail address

User scripts are launched by the server as independant processes, then monitored to avoid launching them more than once at a time. Process exit value is then stored with the exite date.
Windows
Under Windows, these scripts are launched through Windows "run as" feature. Hence, when creating a script, the user must define a user and password which will be used by AVS server perform a Win32 logon user before launching the script. This account should be configured by the system administrator to have restricted access in order to keep AVS server free from any kind of malicious script.
The user name can include the domain if authentication is not performed on AVS server host itself. To do this, add the domain name in the user name as follows: user@domain.
To let a restricted user execute a ".bat" file, access must be granted to the profile the script is programmed to use. To do this, right click on the file to be launched, select the "Properties" menu, and the "Security" tab. Then click on the "Add" button, and add the desired user. This user can be authenticated by the network domain.
This can only be achieved by the system administrator of the host on which AVS server is running.
Linux/Unix
Under Linux/Unix, scripts are launched with "sudo -u user -S command", which is the equivalent of Windows "run as" feature. To have this feature working, the user used to launch the script must be defined within the "sudoers" file within AVS server host.
This can only be achieved by the root user of the host on which AVS server is running.

6) Batch client

A batch client has been implemented to work with script. This tool is packaged in a java archive file, named "script.jar", located under the "tools" sub folder of AVS installation folder. It will need a JRE to launch it, and you can use the version embedded with AVS server: "AVS installation folder\jre1.5.0_09\bin\java.exe".
This batch client will return 0 in case of success, -1 otherwise. It enables following features:

1/ retrieving the files attached to a task

To run this feature, the jar should be launched as follows: java.exe -cp "AVS installation folder/tools/script.jar" com.spamworks.sourcemanager.util.CommandLine -task task_uid output_path user_name user_password server_address

+ task_uid : the unique identifier of the task which files you want to retrieve
+ output_path : the path of the folder in which the files will be copied
+ user_name : the user name to use to login onto the server for the file retrieval operation
+ user_password : the user password
+ server_address : the server address (for instance '192.168.1.10:8090')

task_uid can be found in the change request history, or in the task explorer within AVS repository browser.
Example: "Task #1", here the uid is '1'
To launch this script on task close event, create a batch script and select "launch on task close event". In the command line, put the path to your batch file, and add the %TASK_ID% parameter. This parameter will be usable in the batch file as %1.
Example with a batch file located in the "tools" folder of AVS server:
..\jre1.5.0_09\bin\java.exe -cp "script.jar" com.spamworks.sourcemanager.util.CommandLine -task %1 output_path user password 127.0.0.1:8090
The user/password should belong to a special AVS user created to run scripts, since userq cannot be logged twice on the system. This user will only need the AVS "Manage file" access right.
Please note that in this example, the batch file is located in a folder of AVS server. Since scripts are launched with the Windows "run as" feature, the system administrator should restrict to "read only" the access to AVS folders to the "run as" system user. Hence, batch files used to run scripts should actually be located in dedicated folders, in which this system user will have the "write access" right.
This command line can be used to launch a subsequent script that will check the task's changed files to perform quality analysis, for instance.

2/ retrieving all the files under a given folder id of the given project and update template

To run this feature, the jar should be launched as follows: java.exe -cp "AVS installation folder/tools/script.jar" com.spamworks.sourcemanager.util.CommandLine -update folder_uid template_uid output_path user_name user_password server_address

+ folder_uid : the unique identifier of the folder you want to retrieve
+ template_uid : the unique identifier of the template to use to perform the file version selection
+ output_path : the path of the folder in which the files will be copied
+ user_name : the user name to use to login onto the server for the file retrieval operation
+ user_password : the user password
+ server_address : the server address

folder_uid can be found using the "properties" contextual menu on any folder within AVS client repository browser, it is the "Uid" field.

template_uid can be found using the "update template" contextual menu within AVS repository browser, it is the number in front of any template name in the list.
Example: "#1 Collaborative template for 'beta' version" => here, the template uid is '1'

In the command line to launch this script, if some parameter, such as output_path, contains spaces, you must add quotes around to have them correctly handled.
Example: java.exe cp "script.jar" com.spamworks.sourcemanager.util.CommandLine -task 1 "c:/my output path/" user password 127.0.0.1:8090
This command line can be used to launch a subsequent script that will perform automatic compilation, and even packaging.

7) Manage change requests

The main concept is that only the user assigned to a change request can create attached development tasks.
Users having the "Auto assign CR" but not the "Assign CR" can create change requests either not assigned, or assigned to themselves.
When the user has on the change request right access, he has the "Change Request" tab in the client application. This tab allows to make queries on the existing change request, and modify the change requests issued by the query. The query can be saved to define a set of frequently used queries: they become available in the "Saved" sub tab.

The user may create change requests, if he has the right to do so. He may be able to create tasks on an opened change request, provided the change request is assigned to him. The new task will be added to the list of current tasks within the "Repository" tab of the client application.

When the user has finished his job on the task he created for a given change request, he may change the change request state to put it "in test". For the moment, no warning is displayed when changing a change request state while associated tasks are still open.

A mail notification is sent to the assigned user when a change request is assigned or re-assigned. In a future release of AVS, other kind of notification will appear.