purecm admin guide

PureCM Administrator Guide

Table of Contents

Glossary .............................................................................................................. x1. Getting Started ................................................................................................ 1

Introduction .................................................................................................. 1Register a Server ......................................................................................... 2Select a Repository ..................................................................................... 6Working With Views ..................................................................................... 7Creating a Repository .................................................................................. 8Adding Files & Folders .............................................................................. 11Import a Repository ................................................................................... 12

2. Stream Administration ................................................................................... 14About Streams ........................................................................................... 14Creating a Stream ..................................................................................... 15Deleting a Stream ...................................................................................... 20Moving or Renaming a Stream .................................................................. 21Creating a Stream Folder .......................................................................... 22Stream Tab Views ..................................................................................... 25Stream Permissions .................................................................................. 26

3. Merging .......................................................................................................... 28About Merging ........................................................................................... 28

4. Components .................................................................................................. 30About Stream Components ....................................................................... 30

5. Issue Management & Workflow ..................................................................... 32About Issue Management .......................................................................... 32Enabling Issue Management ..................................................................... 33Creating an Issue Type ............................................................................. 34Issue Fields ............................................................................................... 40Issue States ............................................................................................... 44Issue Actions ............................................................................................. 48Issue State Transition Matrix ..................................................................... 52Issue Form Editor ...................................................................................... 53Stream Issue Requirements ...................................................................... 57Issue Views ............................................................................................... 59Workflow .................................................................................................... 61Configuring Workflow ................................................................................ 62Extending Workflow ................................................................................... 64

6. Users & Groups ............................................................................................. 67About Users & Groups ............................................................................... 67Creating a Group ....................................................................................... 68Creating a User ......................................................................................... 71

7. Policy Administration ..................................................................................... 76About Policy Administration ....................................................................... 76Creating a Policyset ................................................................................... 77Defining a Policyset ................................................................................... 80List of Policies ............................................................................................ 82

8. File Permissions ............................................................................................ 87About File Permissions .............................................................................. 87

9. File Types ...................................................................................................... 89About File Types ........................................................................................ 89

iv

Creating, Editing and Deleting File Types ................................................. 90File Type Flags .......................................................................................... 93

10. File Locking ................................................................................................. 96About File Locking ..................................................................................... 96Mandatory File Locking ............................................................................. 97Automatic File Locking .............................................................................. 98Manual File Locking ................................................................................... 99Stream Locking ........................................................................................ 100Tracking Developer Changes and Deleting File Locks ............................ 101

11. View Server Connections .......................................................................... 103About Connections .................................................................................. 103Connection Entries .................................................................................. 104

12. Event Log .................................................................................................. 106About the Event Log ................................................................................ 106Event Log Entries .................................................................................... 107

13. Reporting ................................................................................................... 109About Reports .......................................................................................... 109Creating a New Report ............................................................................ 110Running a Report .................................................................................... 115Creating a Report Folder ......................................................................... 116General Reports ...................................................................................... 118Issue Reports .......................................................................................... 121Issue Trend Reports ................................................................................ 127Customising a Report .............................................................................. 129Report Permissions ................................................................................. 131

14. Using Scripts ............................................................................................. 133About Scripts ........................................................................................... 133Installing Python (Windows) .................................................................... 134Python Server Triggers ............................................................................ 136Python Repository Triggers ..................................................................... 137PureCM Server Functions ....................................................................... 138PureCM Repository Functions ................................................................. 139

15. Backup & Restore ...................................................................................... 142About Backup & Restore ......................................................................... 142Backing Up the PureCM Data Files ......................................................... 144Create a Snapshot ................................................................................... 145Restoring a Snapshot .............................................................................. 146Archiving the Log File .............................................................................. 147Applying the Log File ............................................................................... 148Resetting Policies .................................................................................... 149

16. Administrator Command Line Tool ............................................................ 151General .................................................................................................... 151

17. License Keys ............................................................................................. 153About License Keys ................................................................................. 153Creating a License Key ........................................................................... 154License Keys Administration ................................................................... 155

A. Issue Templates .......................................................................................... 157Defect ...................................................................................................... 157Enhancement .......................................................................................... 158Simple Defect .......................................................................................... 159Simple Enhancement .............................................................................. 160


v

List of Figures

1.1. Register Admin Server Wizard - Details ....................................................... 21.2. Register Admin Server Wizard - Authentication Type .................................. 21.3. Register Admin Server Wizard - Password Authentication .......................... 31.4. Register Admin Server Wizard - Complete ................................................... 41.5. Repository Selection Dialog ......................................................................... 61.6. PureCM Views .............................................................................................. 71.7. Repository Wizard - Details .......................................................................... 81.8. Repository Properties - Change ID Format .................................................. 92.1. Stream Wizard - Stream Type .................................................................... 152.2. Stream Wizard - Stream Name and Description ........................................ 152.3. Stream Wizard - Changeset and Location .................................................. 162.4. Stream Wizard - Permissions ..................................................................... 172.5. Stream Wizard - Stream Permissions ........................................................ 172.6. Stream Wizard - Complete ......................................................................... 182.7. Stream - Move Rename ............................................................................. 212.8. Stream Folder Wizard - Name and Description .......................................... 222.9. Stream Folder Wizard - Permissions .......................................................... 222.10. Stream Folder Wizard - Stream Permissions ........................................... 232.11. Stream Folder Wizard - Complete ............................................................ 242.12. Stream Tabs - Normal .............................................................................. 252.13. Stream Tabs - Hierarchy .......................................................................... 255.1. Issue Type Wizard - Name and Description ............................................... 345.2. Issue Type Wizard - Details ........................................................................ 345.3. Issue Type Wizard - ID Format ................................................................... 355.4. Issue Type Wizard - Select Template ......................................................... 365.5. Issue Type Wizard - Group Mappings ........................................................ 375.6. Issue Type Wizard - Custom Field Values ................................................. 385.7. Issue Type Wizard - Complete ................................................................... 385.8. Issue Field Wizard - Details ........................................................................ 405.9. Issue Field Wizard - Text Properties .......................................................... 405.10. Issue Field Wizard - Number Properties ................................................... 415.11. Issue Field Wizard - Boolean Properties .................................................. 425.12. Issue Field Wizard - Custom Properties ................................................... 425.13. Issue Field Wizard - Complete ................................................................. 435.14. Issue State Wizard - Details ..................................................................... 445.15. Issue State Wizard - State Details ............................................................ 455.16. Issue State Wizard - Valid Fields .............................................................. 455.17. Issue State Wizard - Valid Actions ........................................................... 465.18. Issue Action Wizard - Name and Label .................................................... 485.19. Issue Action Wizard - Details .................................................................... 485.20. Issue Action Wizard - End Users .............................................................. 495.21. Issue Action Wizard - Operators ............................................................... 505.22. Issue Action Wizard - Mandatory Fields ................................................... 515.23. Issue State Transition Matrix .................................................................... 525.24. Issue Form Editor ..................................................................................... 535.25. Issue Form Editor ..................................................................................... 555.26. Stream Issue Requirements ..................................................................... 575.27. Issue View Wizard - Select Name ............................................................ 595.28. Issue View Wizard - Select Issues ........................................................... 59

vi

5.29. Workflow Issue State - State Details ........................................................ 625.30. Workflow Issue Action - Action Details ..................................................... 626.1. Group Wizard - Details ............................................................................... 686.2. Group Wizard - Select Users ...................................................................... 686.3. Group Wizard - Complete ........................................................................... 696.4. User Wizard - Details .................................................................................. 716.5. User Wizard - Authentication ...................................................................... 716.6. User Wizard - Groups ................................................................................. 726.7. User Wizard - Complete ............................................................................. 737.1. Policyset Wizard - Select Repository .......................................................... 777.2. Policyset Wizard - Select Stream ............................................................... 777.3. Policyset Wizard - Select User or Group .................................................... 787.4. Policyset Wizard - Specify Name ............................................................... 787.5. Policyset Wizard - Complete ...................................................................... 797.6. Policyset Properties - Empty ...................................................................... 807.7. Policyset Properties - Completed ............................................................... 807.8. Policyset Properties - Policy Setting ........................................................... 819.1. File Type Properties - General ................................................................... 909.2. File Type Properties - Description .............................................................. 919.3. File Type Properties - Flags ....................................................................... 9110.1. Local Changesets Folder ........................................................................ 10112.1. Event Log ............................................................................................... 10713.1. Report Wizard - Select Template ........................................................... 11013.2. Report Wizard - Details .......................................................................... 11013.3. Report Wizard - Issue View .................................................................... 11113.4. Report Wizard - Parameters ................................................................... 11213.5. Report Wizard - Permissions .................................................................. 11213.6. Report Wizard - Complete ...................................................................... 11313.7. Report Folder Wizard - General ............................................................. 11613.8. Report Folder Wizard - Permissions ....................................................... 11613.9. General Reports - Changeset ................................................................. 11813.10. General Reports - Changeset Items ..................................................... 11813.11. General Reports - Changeset Items by User ....................................... 11913.12. General Reports - Release Notes ........................................................ 11913.13. General Reports - Changeset Item Release Notes .............................. 12013.14. Issue Reports - Issue List ..................................................................... 12113.15. Issue Reports - Issue List by User ........................................................ 12113.16. Issue Reports - Issue List by State ....................................................... 12213.17. Issue Reports - Issue List by Custom Field .......................................... 12213.18. Issue Reports - Issue List with Time ..................................................... 12313.19. Issue Reports - Issue Action List .......................................................... 12313.20. Issue Reports - Issue Details ................................................................ 12413.21. Issue Reports - State Distribution ......................................................... 12413.22. General Reports - Issue Release Notes ............................................... 12513.23. Issue Trend Reports - Action Trend ..................................................... 12713.24. Issue Trend Reports - User Action Trend ............................................. 12713.25. Issue Trend Reports - User Issue Time Trend ..................................... 12813.26. Report Properties - Stream ................................................................... 12913.27. Report Properties - Components .......................................................... 13013.28. Report Permissions .............................................................................. 13117.1. License Key Entry ................................................................................... 154A.1. Issue Templates - Defect ......................................................................... 157


vii

A.2. Issue Templates - Enhancement ............................................................. 158A.3. Issue Templates - Simple Defect ............................................................. 159A.4. Issue Templates - Simple Enhancement ................................................. 160


viii

List of Tables

1.1. Repository Change ID Format ...................................................................... 92.1. Stream Permissions ................................................................................... 265.1. Issue ID Format .......................................................................................... 357.1. General Policies ......................................................................................... 827.2. Administration ............................................................................................. 837.3. Repository Admin ....................................................................................... 837.4. Setup .......................................................................................................... 837.5. Stream ........................................................................................................ 857.6. General Professional .................................................................................. 857.7. Issue Management ..................................................................................... 858.1. File and Folder Permissions ....................................................................... 879.1. Keywords .................................................................................................... 9315.1. PureCM Data Files ................................................................................. 14215.2. PureCM Snapshot Files .......................................................................... 14215.3. PureCM Log Files ................................................................................... 14317.1. License Key States ................................................................................. 155

ix

Glossary

Server

PureCM uses a client-server architecture with a centralized server. To get started withPureCM you need to install the PureCM Server and the PureCM Client (on the sameor different machines). Using the PureCM GUI or command line you then need tocreate a connection to server. Each server will contain one or more repositories.

Repository

This is the place where all your data is stored. You can put one or more projects into asingle repository as streams, allowing you to manage shared libraries easily. Note thatthe repository defines the context for the PureCM GUI, e.g. displaying all projects ofyour current repository in the Repository View.

Stream

A stream is used to define your code line, holding all data of a specific project. Youneed at least one high level stream to start working with PureCM, and all changes getapplied against this stream. From there, you can branch off streams for differentdevelopment stages and separate teams or to create snapshots.

Workspace

Each developer creates a workspace on their computer for a selected stream. Theworkspace will mirror the files stored on the server. File additions, deletions and editsare then performed in the workspace before being submitted to the server in achangeset. File consistency can be checked between the client and server versions offiles.

Changesets and Version Control

Change management allows version control of files and directories using achangeset-based approach. A 'changeset' is a related group of file additions, deletionsand edits, defined by the developer and annotated with a description on submission tothe server.

Issues

Issue management allows highly-configurable 'issues' to be captured and processedusing a workflow-based approach. Possible uses include defect tracking, changerequests and requirements management. Changesets can be tied to issues, so thatsubmissions to the server must be associated with one or more issues.

Workflow

The use of issues can be extended to control how the project is structured. Forinstance, the ability to review and approve the resolution to an issue may be assignedonly to certain developers, and issues may be assigned to developers for resolution.

Diff Tool

x

PureCM provides a tool allowing you to compare 2 versions of a file. Line differencesare colour highlighted.

Resolve Tool

PureCM provides a tool allowing you to resolve 2 versions of a file which have acommon base. Changes to different lines are automatically resolved but if the sameline is changed in the 2 versions then the conflict must be resolved manually.

File History

PureCM provides a tool allowing you to view all revisions of a file. When a changesetis submitted, a revision is created for each file. You can view each revision, compare2 revisions with the Diff Tool or even rollback a revision.

Annotated File History

PureCM provides a tool allowing you to view the history of each line within a file. Thisis useful if you find a bug in a particular line and want to isolate the changeset inwhich the bug was submitted.

Check Consistency

Checking the consistency of a workspace involves seeing if any files have beenedited, added or deleted without being checked out. An inconsistent workspace isdangerous because you may submit a partial change.

Shelving

Shelving is the ability to save unfinished work on the server as a shelveset. Thechanges can then be unshelved into a workspace. This is useful if you want to savework on the server or if you want to move a piece of work from one workspace toanother.

Client/Server Architecture over TCP/IP

TCP/IP is used to allow the client components on the developers' computers tocommunicate with the central server component. As well as password authentication,support is included for strong authentication using Windows domain authentication orcertificate authentication.

Concurrent Development

Before submitting files to the server the latest changes are downloaded to the clientand can then be integrated with your changes. In this way the same files can beedited simultaneously by different developers, with conflicts being handled by thePureCM Resolve tool. In addition, concurrent development is supported with two setsof developers working on separate developments in separate streams which will beintegrated at a later date.

Remote development

Support for remote development is built-in and the PureCM client can be run even

Glossary

xi

when a connection to the server is not available. For example a developer cancheckout files, make local checkins, view a file's revisions, or view issue summarieswhile working 'offline'.

Glossary

xii

Chapter 1. Getting Started

Introduction

If you are evaluating PureCM we recommend you first watch the online demonstration[http://www.purecm.com/videos.php].

The administration tasks are covered in this Administrator Guide and the dailydeveloper tasks are covered in the PureCM User Guide.

The PureCM Server will be installed with an 'Example' repository which contains someexample streams with example data. The user 'admin' will be created with thepassword supplied during the server installation (or blank on Linux). The users'LeadDeveloper1', 'Developer1' and 'Developer2' are also created with the password'secret'.

After installing the PureCM Client and Server you will first need to register the serveras described in the section called “Register a Server”. You will then want to create anew repository as described in the section called “Creating a Repository”.

If you are migrating from Visual SourceSafe, Perforce or CVS you can import yourdata as described in the section called “Import a Repository”. Otherwise you will needto create a workspace and submit your files as described in the section called “AddingFiles & Folders”.

By default PureCM will be installed without any security (any user can perform anyaction). You should create groups for each role (Administrators, Lead Developers,etc.) as described in the section called “Creating a Group”.

Setting up the file permissions (who can read, edit which files) is described inChapter 8, File Permissions.

To specify who can perform which actions in PureCM (e.g. who can create/deleterepositories) you need to create PolicySets for the relevant group. This is described inChapter 7, Policy Administration.

1

http://www.purecm.com/videos.php

Register a Server

After installing the PureCM Server and Client you will want to connect to the server asuser 'admin'. Lauching the PureCM GUI for the first time will launch the RegisterServer Wizard. You can also select 'Register Server' from the file menu.

Figure 1.1. Register Admin Server Wizard - Details

If the PureCM Server has been installed correctly on the domain it should appear inthe list. Alternatively you can enter the 'Server Name', either the DNS name or the IPaddress, and 'Server Port'.

The 'Connect to server on startup' option should be unchecked if you do not want toconnect to this server when the PureCM GUI is started.

The 'Keep trying to connect' option should be checked if you want to automaticallykeep trying to connect after the server has disconnected.

Press the <Next> button when completed.

Figure 1.2. Register Admin Server Wizard - Authentication Type

Getting Started

2

The administrator uses password authentication. Select the 'Password Authentication'radio button and press the <Next> button.

Figure 1.3. Register Admin Server Wizard - Password Authentication

Getting Started

3

The administrator user name is 'admin', the password was supplied when installingthe PureCM Server (or blank on Linux/Mac servers). Enter the details on the page andpress <Next> to continue.

NoteIf you have forgotten your admin password you can use the user'LeadDeveloper1' and the password 'secret'. You can then change thepassword for user 'admin'.

Figure 1.4. Register Admin Server Wizard - Complete

Getting Started

4

To complete the Administrator Server registration, check that the details are correcton the final page and press <Finish>. The new connection will appear under thePureCM tree.

Getting Started

5

Select a Repository

After connecting to the server you will be asked to select the 'active' repository.Expand a server to try and connect. If the connection is successful the repositoriesbelonging to that server will appear. Select the 'Example' repository to evaluatePureCM.

Figure 1.5. Repository Selection Dialog

You can change the active repository at any time by selecting 'Select Repository' fromthe File menu or using the 'Select Repository' toolbar button.

Getting Started

6

Working With Views

After selecting an active repository you will see that multiple views are available in theGUI. The PureCM administrator will determine which views are available to youaccording to which policies are enabled.

Figure 1.6. PureCM Views

The Workspaces View is described in the PureCM User Guide and is used bydevelopers. The Repository View is used to create, delete, edit or view streams asdescribed in Chapter 2, Stream Administration. The Merging View is used to mergechangesets between streams as described in Chapter 3, Merging. The Issues View isused to create, edit or view issues as described in Chapter 5, Issue Management &Workflow. The Reports View is used to generate reports on changesets or issues asdescribed in Chapter 13, Reporting.

The Administration View is used to perform administration tasks such as creatingusers, file permissions, etc. You can perform all tasks in PureCM using theAdministration view (as opposed to using the different views) but this will listeverything in a single tree which can be difficult to work with.

NoteSome of these views may not be available, depending on whether you areusing the Standard or Professional Edition and what policies you haveenabled. The Workspaces, Repository and Administration Views will always beavailable.

Getting Started

7

Creating a Repository

To evaluate PureCM you can use the 'Example' repository. When you are ready tostart working with PureCM you will want to create a new repository. To create arepository go to the Administration view and connect to the server by expanding it inthe tree. Right click the server and select the 'Create Repository' menu option. TheRepository Wizard will be launched.

NoteTypically you will only have one repository. If you have multiple projects it isusually better to create multiple streams in the same repository for the differentprojects. This will allow you to share code between the projects usingcomponents.

Figure 1.7. Repository Wizard - Details

The Details page allows you to choose a title for the repository and the default initialstream name can be changed.

Press <Next> to Finish. The new repository will be the active repository and willappear under the server in the Administration View.

After creating the repository you may want to modify the changeset reference. Bydefault, each submitted changeset in the repository will be called '[reposname]/[change number]'. You can change this by right-clicking the repository in theAdministration View and selecting 'Properties'.

Getting Started

8

Figure 1.8. Repository Properties - Change ID Format

The Change ID Format field allows for the format of changeset IDs to be customised.When a changeset (a group of changes to one or more files) is submitted to theserver, the ID specified here will be appended to it.

Table 1.1. Repository Change ID Format

Name Placeholder Definition

changes count $n Sequential number of changesets submitted tothe repository

day changescount

$N Sequential number of changesets submitted tothe repository that day (usually used inconjunction with $d$m$y)

streamchanges count

$t Sequential number of changesets submitted tothis stream in the repository

user name $u Name of the user submitting the changeset

user changescount

$U Sequential number of changesets submitted tothe repository by this user (usually used inconjunction with the above)

client $c Name of the machine submitting the changeset

stream name $s Name of the stream to which the changeset isbeing submitted

stream path $S Path and name of the stream to which thechangeset is being submitted

day $d DD

Getting Started

9


month $m MM

month $M Month

year $y YY

Getting Started

10

Adding Files & Folders

After connecting to the server and creating a new repository you will want to add yourfiles and folders. If you are currently using SourceSafe, Perforce or CVS then PureCMwill automatically import your files (with the full history) as described in the sectioncalled “Import a Repository”. If you are starting from scratch then you add your files asfollows:

1. Create a workspace as described in the PureCM User Guide. You can create theworkspace in a new folder and copy the files you want to add into this folder. Oryou can create the workspace in the folder where he files currently exist.

2. Select the workspace and select the 'Add' menu or toolbar button. This will launchthe Check Consistency Wizard as described in the User Guide. You can specifywhich files to include/exclude in the search.

3. When all the files and folders have been added, select the workspace and selectthe 'Submit' menu or toolbar. Enter a suitable description and select 'Submit' fromthe changeset toolbar. Submitting a changeset is described in more detail in theUser Guide.

4. The files and folders are then added to the stream. If the workspace was onlycreated for adding the first set of files and folders to the stream then it can bedeleted.

Getting Started

11

Import a Repository

A repository can be imported from another SCM package:

1. If necessary, create a new repository in PureCM as described above.

2. Right click on the new or an existing repository and select 'Import Repository'from the menu.

3. Select the type of repository to import and follow the on-screen wizard, which willvary according to the type of repository being imported.

NoteThe imported repository will be created as one or more streams within thePureCM repository. These streams can then be merged or otherwise amendedas described in the 'Stream Administration' chapter.

Getting Started

12

Getting Started

13

Chapter 2. Stream Administration

About Streams

Streams (aka 'branches') are used to indicate a precise point in the lifecycle of aproject. As the options indicate when creating a repository, streams are commonlydifferentiated as follows:

• Development. A stream of this type will usually be the main one for the project.There will usually only be one development stream for a project.

• Release. A stream of this type will indicate a point in the lifecycle of the projectwhen, for example:

a. The code was built and the program distributed.

b. The website was uploaded to the internet server.

A stream at this point will allow bug fixes to the current release whilst newdevelopment occurs in a separate stream. As detailed later in this chapter, thestreams can subsequently be merged.

• Testing. A stream of this type will be used when a major structural change is beingmade. If unsuccessful it will not affect the development stream and if successful itcan subsequently be merged, fully or in part, with the main development stream.

Though these are the most common uses, a stream can be created at any time andfor any reason.

NoteIf you are setting up PureCM for the first time, a stream will have been createdwith the repository as described in the section called “Creating a Repository”.

14

Creating a Stream

A new stream is usually created from an existing stream. Right click on the stream touse as the basis of the new one and select 'Create stream from...' on the menu.Alternatively a 'Component' stream (i.e. a stream which has no parent) can be createdby right clicking the stream folder you want to contain the new stream and selecting'Create new stream'.

Figure 2.1. Stream Wizard - Stream Type

Check 'Create Component Stream' if you want to create a new stream without aparent. Otherwise check 'Create Stream From' and select the parent stream from thestream tabs as described in the section called “Stream Tab Views”.

Figure 2.2. Stream Wizard - Stream Name and Description

Stream Administration

15

Enter a name and description for the new stream. The name and description shouldbe as clear as possible to avoid any confusion in the future, and you may choose touse a standard naming convention such as 'Release <Version> <Date>' or 'Test<Reason> <Date>'.

Figure 2.3. Stream Wizard - Changeset and Location

The new stream can start from the latest changeset or a previous one, selected byusing the radio buttons. The browse button <...> allows you to select a previouschangeset from a list.


16

In the lower pane select the folder in which the new stream should be stored. Press<Next> to continue.

Figure 2.4. Stream Wizard - Permissions

The Permissions page allows you to specify who can do what to the files within thestream. See Chapter 8, File Permissions for a full descriptions of file permissions. Bydefault the permissions are inherited from the parent folder. To change thepermissions uncheck the box. Press <Add> to introduce an existing user or group, or<Remove> to delete the currently highlighted user or group.

With a user or group highlighted in the top pane, the check boxes below can be usedto change the permissions. When finished press <Next> to continue.

Figure 2.5. Stream Wizard - Stream Permissions


17

The Stream Permissions page allows you to specify who can do what to the streamitself. By default the permissions are inherited from the parent stream. To change thepermissions uncheck the box. Press <Add> to introduce an existing user or group, or<Remove> to delete the currently-highlighted user or group.


Figure 2.6. Stream Wizard - Complete


18

Confirm that the details are correct on the completion page and press <Finish> tocreate the stream.

NoteThe new stream can now be mapped to a workspace, as outlined in the ClientConnection, Create the Workspace section of the PureCM User Guide.


19

Deleting a Stream

When a stream is no longer needed, for example if the changes have beensuccessfully merged or the stream was for an unsuccessful test, it can be deleted.

NoteDelete any workspaces mapped to the stream before deleting the stream itself.

Right click on the stream and select 'Delete' from the menu.


20

Moving or Renaming a Stream

To move or rename a stream, right click on it and select 'Move/Rename stream' fromthe menu.

Figure 2.7. Stream - Move Rename

To move the stream to a different folder, highlight the folder and press <Ok>.

To rename the stream, type a new name and press <Ok>.


21

Creating a Stream Folder

Stream folders are designed to help you organise your streams. Another use forstream folders is that file and stream permissions can be set from which all childstreams can inherit, as described in Chapter 8, File Permissions. When creating therepository the 'Development' and 'Release' stream folders are created by default asdescribed in the section called “Creating a Repository”.

To create a stream folder right click on the parent stream folder and select 'Createnew stream folder' from the menu.

Figure 2.8. Stream Folder Wizard - Name and Description

Enter a name and description for the new folder.

Figure 2.9. Stream Folder Wizard - Permissions


22

The Permissions page allows you to specify who can do what to the files within thechild stream. See Chapter 8, File Permissions for a full descriptions of filepermissions. By default the permissions are inherited from the parent folder. Tochange the permissions uncheck the box. Press <Add> to introduce an existing useror group, or <Remove> to delete the currently highlighted user or group.


Figure 2.10. Stream Folder Wizard - Stream Permissions


23

The Stream Permissions page allows you to specify who can do what to the streamfolder and child streams (if they inherit from parent). By default the permissions areinherited from the parent folder. To change the permissions uncheck the box. Press<Add> to introduce an existing user or group, or <Remove> to delete thecurrently-highlighted user or group.


Figure 2.11. Stream Folder Wizard - Complete

Confirm that the details are correct on the completion page and press <Finish> tocreate the stream folder.


24

Stream Tab Views

When viewing streams in different contexts the two stream tabs will become available.The easiest way to view the streams is to right click on either the repository or thestreams node and select 'Show Stream Hierarchy' from the menu.

Figure 2.12. Stream Tabs - Normal

The 'Normal' stream tab displays the repository at the root. Expanding the repositorywill reveal all root streams and stream folders. Expanding a stream folder will revealall streams and stream folders belonging to this folder.

Figure 2.13. Stream Tabs - Hierarchy

To view the 'Hierarchy' stream tab right click on the repository or the streams nodeand select 'Show Stream Hierarchy' from the menu. This displays the repository at theroot and expanding the repository will reveal all component streams. Expanding astream will reveal all streams created from the expanded stream (i.e. all childstreams).


25

Stream Permissions

Permissions can be set to configure who can read, create, move and deletestreams/stream folders.

The default permissions are set within the Global Properties. These can be changedby right-clicking the server tree item and selecting 'Global Properties...'. These can beoverridden within the properties of a repository, stream folder, or stream.

The following permissions can be checked or unchecked:

Table 2.1. Stream Permissions

Permission Definition

Read If checked the user is able to view thestream within the gui

Add If checked the user is able to createstreams within the folder [folders only]

Move If checked the user is able to move thestream to a different folder

Delete If checked the user is able to delete thestream

Folder Add If checked the user can create streamfolders within the folder [folder only]

Folder Delete If checked the user is able to deletestream folders [folder only]

Permissions If checked the user can change thepermissions for the stream/stream folder


26


27

Chapter 3. Merging

About Merging

The PureCM GUI provides several ways of merging changesets between streams.The Merging view provides a central location for organising and administering mergepaths, which will keep track of which changesets need to be merged or even attemptto automatically merge a changeset after it has been submitted.

For information about merging please refer to the PureCM Knowledge Base[http://support.purecm.com/index.php?pg=kb.chapter&id=34]

28

http://support.purecm.com/index.php?pg=kb.chapter&id=34

Merging

29

Chapter 4. Components

About Stream Components

Components are a great way of managing shared code which is used in manyprojects. They allow a single copy of the library to be accessed in many placed in yourrepository but also allow the library to be updated from any of those locations. Acomponent is made from a link between a two folders (usually in two differentstreams). Any files or folders inside the component folders are shared in the twoplaces. Any changes to a file in one part of the component will be replicated exactly toall of the other parts.

For more information about components please refer to the PureCM Knowledge Base[http://support.purecm.com/index.php?pg=kb.chapter&id=18]

30

http://support.purecm.com/index.php?pg=kb.chapter&id=18

Components

31

Chapter 5. Issue Management & Workflow

About Issue Management

The management of issues (enhancements, bug-fixes or anything else requiring achange) within PureCM is highly flexible, and can be configured anywhere from'unused' at one end the scale to 'mandatory in order to submit changes to the server'at the other.

When an administrator creates an issue type the following properties can be defined:

• The individual fields that describe the issue, such as description, version affectedand the time taken to resolve.

• The states that can be assigned to an issue, such as raised, assigned and cleared.

• The actions that can be performed on an issue, depending on its current state.These actions, which can be restricted to certain users or groups of users, willmove the issue from one state to another. The definition of these actions willdetermine the lifecycle of the issue.

• The forms used on-screen when creating, amending or clearing an issue.

Where linking changesets to issues is mandatory in order to submit, the stream mustbe configured to indicate which issue types must be used. Issue types shouldtherefore be created to cover all the reasons for a changeset e.g. Defect,Enhancement, Documentation etc. It is generally advisable to keep the number ofissue types to a minimum to avoid ambiguity over the reason for a changeset whensubmitting.

32

Enabling Issue Management

In order to use issue management in PureCM it must be enabled in the grouppolicysets.

NotePlease refer to the section called “Defining a Policyset” for more information.

Enable issue management as follows:

1. Highlight the Policy Admin node.

2. In the list on the right, double click 'Admin Policyset' and select the 'Policies' tabat the top of the page.

3. If 'Issue Administration' is not in the list then press <New> and highlight it in thelist. Press <Ok> to return to the Policies page.

4. Double click 'Issue Administration', select the 'Enabled' radio button and press<Ok>.

5. Repeat the above for the 'Issue Use' policy.

6. The 'Issue Use' policy will also need to be enabled in the policyset for thedevelopers themselves (in many cases this will be the 'Default Policyset').

Issue Management & Workflow

33

Creating an Issue Type

To create a new issue type, right click the 'Issue Admin' node and select 'New IssueType' from the menu.

Figure 5.1. Issue Type Wizard - Name and Description

A new issue can be created by:

1. Using one of the PureCM issue templates as a starting point.

2. Using an existing issue type, from the current or another repository, as thestarting point.

3. Creating the issue type from scratch.

This example will use one of the existing templates. Select the appropriate radiobutton and press <Next> to continue.

Figure 5.2. Issue Type Wizard - Details


34

Enter a name for the issue type and press <Next>.

Figure 5.3. Issue Type Wizard - ID Format

The Change ID Format page allows for the format of issue IDs to be customised.When a new issue of this type is raised the ID will be assigned to it.

Table 5.1. Issue ID Format


35


issue count $n Sequential number of this type of issue created

all issue count $g Sequential number of all issues created withinthis repository

global issuecount

$G Sequential number of this type of issue createdacross all repositories

daily issuecount

$N Sequential number of issues raised that day(usually used in conjunction with $d$m$y)

user name $u Name of the user creating the issue

user issuecount

$U Sequential number of issues created by this user(usually used in conjunction with the above)

client $c Name of the machine creating the issue

day $d DD

month $m MM

month $M Month

year $y YY

field value $f|field_name| The initial value of a field. This is useful if youwant to specify the reference when creating theissue.

The ID field can be edited directly or use the <Add> button to select from a list ofplaceholders. Press <Next> to continue.

Figure 5.4. Issue Type Wizard - Select Template


36

As this issue type is to be based on an existing template, select the template from thedrop down list.

NoteIf the issue was based on an existing issue type, rather than a template, similarpages allow you to select the repository and issue type from drop down lists.

Press <Next> to continue

Figure 5.5. Issue Type Wizard - Group Mappings


37

Where applicable, the template may contain groups with assigned actions that theycan perform during the lifecycle of the issue. For example, the Lead Developers groupmay be configured to review changes submitted by Developers.

NotePlease refer to Appendix A, Issue Templates for more information about thestandard templates included in PureCM.

These template groups must now be mapped to the groups present in yourinstallation. Highlight the template group and use the <Change Mapping> button tomake changes. Alternatively, select 'Create New' to create a new group with the samename as displayed. Press <Next> to continue.

Figure 5.6. Issue Type Wizard - Custom Field Values

Where applicable, select the values to be used in any custom fields.

NoteIf necessary, any unwanted fields can be removed completely once the issuetype has been created.

Use the <Change Values> button to make changes. Press <Next> to continue.

Figure 5.7. Issue Type Wizard - Complete


38

Confirm that the details are correct on the completion page and press <Finish> tocreate the new issue type.

The new issue type will appear under Issue Admin with options beneath it to specifyFields, States, Actions, State Transition Matrix and Forms, as described in thefollowing sections.


39

Issue Fields

The first step in defining the new issue is to specify the fields that must be completedeither when the issue is created or at a later stage in its lifecycle. These fields will thenbe used on the forms that are completed either when an issue is created or during itslifecycle, as explained later in this chapter.

If the issue has been created from an existing template or issue type then the fieldswill have been copied across and can be amended by double-clicking on the field.

To create a new field from scratch, right click on Fields and select 'New' from themenu.

Figure 5.8. Issue Field Wizard - Details

Enter a name for the field and a label. The label will appear as a description next tothe field name and type. Use the drop down box below to select the type of field fromthe list, as explained below. Press <Next> to continue:

Figure 5.9. Issue Field Wizard - Text Properties


40

Text Field. The following page allows you to set a default value, indicate if the text boxshould be multi-line and set a maximum number of characters. Uses of a text field willusually include short and long descriptions of the issue.

Figure 5.10. Issue Field Wizard - Number Properties

Number Field. The following page allows you to set default, minimum and maximumvalues. Uses of a number field may include estimated and actual numbers of hours toresolve an issue.


41

Figure 5.11. Issue Field Wizard - Boolean Properties

Boolean Field. Used to create a checkbox on the form, which can be checked orunchecked by default.

Figure 5.12. Issue Field Wizard - Custom Properties

Custom Field. Used to create a static list or a drop down list from which an option canbe chosen. Use the <New> button to add the options which will appear on the list. A


42

drop down list may be used, for example, to indicate the stream in which the issueshould be resolved or the version number of the software to which the issue refers.

When the properties page has been completed, which will vary according to the typeof field being created, press <Next> to continue.

Users Field. A users field is similar to a custom field where there is a value for eachuser and group within PureCM. You can then associate one or more users to an issueusing an edit, drop-down, list or button control.

Figure 5.13. Issue Field Wizard - Complete

Press <Finish> to complete. The new field will appear in the list.

Repeat the above for all the fields necessary to define the issue.


43

Issue States

Issue states and actions (as described in the next section) will define the lifecycle ofthe issue. The lifecycle may be very simple - e.g. Raised -> Cleared, or Raised ->Rejected - or a lot more complex, for example Raised -> Approved -> Submitted ->Checked -> Cleared.

NoteThe lifecycle should be defined in such a way that it reflects the processesused by your company. As importantly, it should be straightforward to followand not provide a barrier to the developers' day-to-day work.

If the issue has been created from an existing template or issue type then the stateswill have been copied across and can be amended by double-clicking on the state.

To create a new state from scratch, right click on States and select 'New' from themenu.

Figure 5.14. Issue State Wizard - Details

Enter a name for the state and a label. The label will appear as a description next tothe state name.

The 'Activation Action' is performed when an issue in this state is made active by auser. For example the activation action for 'Raised' might be 'Being Fixed'. In this waywhen a user activates a 'Raised' issue it will automatically perform the 'Begin Fix'action so the issue is 'Being Fixed'. Use the drop down list to choose the action toactivate this state.


44

From the list below select an image to be associated with the state (the image willappear next to the issue in My Issues). Press <Next> to continue.

Figure 5.15. Issue State Wizard - State Details

Check the 'State can be active' checkbox if you want developers to be able toassociate an issue in this state with a changeset. For example you might configure theissue setup so that 'Created' issues cannot be active, but when a manager assignsthe issue to a developer the issue is 'Being Fixed' which can be active. In general theonly issue states that you will want associated with a changeset are those that arework in progress, not an issue that has just been raised, cleared or rejected.

Check the 'Accept Changesets' checkbox if the changeset being reviewed should beaccepted when the issue goes into this state. See the section called “Workflow” for adescription of workflow. For example you might set the issue state 'Accept' to 'AcceptChangesets'.

Figure 5.16. Issue State Wizard - Valid Fields


45

If there are fields that can be edited when the issue is in this state press <New> andselect the field from the list. The <Delete> button can be used to remove fields. Forexample you might allow users to edit the estimated time when it is 'Being Analyzed'but not when it is 'Being Fixed'. Press <Next> to continue.

Figure 5.17. Issue State Wizard - Valid Actions

The lifecycle of an issue is defined by the states and allowable actions when in eachstate. For example, you may wish to specify that an issue cannot be cleared withoutthe changes being approved first. Use the <New> button to specify the actions that


46

are allowed for an issue in this state. Press <Next> to continue.

Press <Finish> to complete. The new state will appear in the list.


47

Issue Actions

Issue states (as described in the previous section) and actions will define the lifecycleof the issue. The lifecycle may be very simple - e.g. Raised -> Cleared or Raised ->Rejected - or a lot more complex, for example Raised -> Approved -> Submitted ->Checked -> Cleared.

NoteAs issue actions are closely tied to issue states, it is important to use astraightforward naming convention so that it is obvious to the developers whichaction will result in the issue being changed to which state, for example 'Raise'action -> 'Raised' state, 'Clear' action -> 'Cleared' state etc.

If the issue has been created from an existing template or issue type then the actionswill have been copied across and can be amended by double-clicking on the action.

To create a new action from scratch, right click on Actions and select 'New' from themenu.

Figure 5.18. Issue Action Wizard - Name and Label

Enter a name for the action and a label. The label will appear as a description next tothe action name.

Use the checkbox below if this action is the one used to initially create the issue.Press <Next> to continue.

Figure 5.19. Issue Action Wizard - Details


48

Use the first drop down list to select the state of the issue once the action has beenperformed. For instance, a Reject action should result in a Rejected state.

Use the second drop down list to determine whether, once the action has beenperformed, ownership of the issue should be individual users, groups or either.

The first checkbox is used to indicate if a description must be entered when the actionis performed. For example if the action is to reject the issue then a reason for therejection may be deemed necessary.

The second checkbox is used to indicate if the hours to complete the action must beentered when the action is performed. For example you may want to get developers toenter how long it took to fix a default when performing the 'Fix' action.

The third checkbox should be used if the changesets are to be discarded when thisaction is performed. A typical use for this might be a 'reject' action. See the sectioncalled “Workflow” for a description of workflow.

The fourth checkbox should be used if this action can only be performed whenassociated with a changeset. For example, the 'Fix' action might not make any senseif it is not associated with a changeset.

Press <Next> to continue.

Figure 5.20. Issue Action Wizard - End Users


49

Use the <New> button to select which users or groups can have ownership of theissue once the action has been performed. So when a user performs the action, theywill be asked to select the new issue owner from this list. For example, the 'Create'action might assign the issue to a manager while the 'Begin Fix' action might assignthe issue to a developer.

NoteIf you chose to restrict ownership of the issue to individual users on theprevious page, selecting a group at this point will mean that the issue must beassigned to an individual from the selected group and not the group as awhole.


Figure 5.21. Issue Action Wizard - Operators

Use the <New> button to select which users or groups can perform this action. Press<Next> to continue.


50

Figure 5.22. Issue Action Wizard - Mandatory Fields

If certain fields must be completed before performing this action, use the <New>button and select the fields from the list. For example, when raising an defect it maybe mandatory to specify the product version in which the fault occurred. Press <Next>to continue.

Press <Finish> to complete. The new action will appear in the list.


51

Issue State Transition Matrix

The state transition matrix provides an overview of the way actions are related tostates, and hence the possible lifecycles of an issue. The horizontal axis shows thecurrent state and the vertical axis shows the state after the chosen action.

NoteIf two actions can be used to perform the same state transition, only one willbe shown in the matrix.

Figure 5.23. Issue State Transition Matrix

The state transition matrix can also be used to create or amend the link betweenstates and actions by highlighting a cell in the grid and using the drop down box toselect an action.


52

Issue Form Editor

Using the form editor an administrator can customize how an issue will be displayed tothe user. To use the form editor select 'Form Editor' in the tree.

Figure 5.24. Issue Form Editor

NoteWith the 'XRC' tab you can modify the form by writing the XRC (xml-basedresource language) directly.

Sizers

The form editor is sizer-base to handle resizing and multiple platforms. All controlsmust be added to a sizer which determines how they are resized.

To add a sizer right-click on a sizer or panel and select 'Add | Sizers'. You can choosefrom:

• Vertical Sizer. Child controls will be positioned vertically.

• Horizontal Sizer. Child controls will be positioned horizontally.

• FlexGrid Sizer. Child controls will be positioned in a grid. You can specify thenumber of rows and columns within the properties. You can also specify whichcolumns and rows are 'growable' (i.e. as the issue dialog is resized which rowsshould be resized accordingly).

NoteFor a more detailed explanation of sizers please refer to the wxWidgetsdocumentation at www.wxwindows.org.

Controls

To add a control right-click on a sizer or control and select 'Add | Controls'. You canchoose from:


53

Static Text. This will create some plain text (label).

Edit Control. This will create an edit control (field). You can associate this with anissue field in the properties. The issue field must be of type text or number.

Rich Text Control. This will create a control similar to the 'Edit Control' but allowingtext and paragraph formatting. For example the user is able to specify the font, sizeand color or the alignment of the text. The user can right-click the control to specifythe formatting options.

Panel. This will create a panel from which child controls can be added. When createdfrom a 'Notebook' this will create a notebook page.

Notebook. This will create a tab control. You can add pages (tabs) by adding panels.

CheckBox. This will create a check box (tick box). You can associate this with anissue field in the properties. The issue field must be of type boolean.

ComboBox. This will create a drop-down. You can associate this with an issue field inthe properties. The issue field must be of type custom.

List Control. This will create a list control (single or multiple selection). You canassociate this with an issue field in the properties. The issue field must be of typecustom.

Button. This will create a button which can be associated with a custom field. Whenthe button is pressed a dialog is launched allowing the user to tick one or more valuesfrom the custom field. This is useful if you have a large number of choices, and wantto allow the user to select multiple items. In such situations the list control can take uptoo much space. A better solution might be to add an edit field which is associatedwith the custom field and then add a '...' button next to the edit control from which usescan select the values. Another advantage of the button control is that the user is ableto add, edit and remove custom field values within the button dialog. This is easierthan getting an Issue Administrator to edit the Issue Field Properties. A user musthave the 'Custom Action Administration' policy enabled to edit these values.

Date Picker. This will create a date picker control. You can associate this with anissue field in the properties. The issue field must be of type date.


54

History. This will create an issue history control. The issue history control shows allactions performed on an issue including the operator, description and time taken.

Files. This will create a file attachment control. This will allow users to attach files tothe issue.

Control/Sizer Properties

To edit the properties of a control or sizer right-click the tree item and select'Properties'.

Figure 5.25. Issue Form Editor


55

Some of the properties are generic for all controls/sizers (e.g. Styles) while others onlyapply to certain controls/sizers (e.g. PureCM). Most of the properties are selfexplanatory. For more detailed help on an individual property please refer to , thewxWidgets documentation[http://www.wxwindows.org/manuals/2.6.3/wx_sizeroverview.html#sizeroverview].


56

http://www.wxwindows.org/manuals/2.6.3/wx_sizeroverview.html#sizeroverview

http://www.wxwindows.org/manuals/2.6.3/wx_sizeroverview.html#sizeroverview

Stream Issue Requirements

PureCM can be configured so that the changesets can only be submitted whenassociated with one or more active issues.

NoteSubmitted changesets may also be associated with active issues on avoluntary basis, as outlined in the 'Working with Issues' chapter.

To enforce the link between submitted changesets and active issues, right click thestream, select 'Properties' and select the 'Issue Requirements' tab. Unless therequirements are inherited, uncheck the box and press the <Add> button. Select thegroup or user and press <Ok>.

Figure 5.26. Stream Issue Requirements

Highlight the group or user in the list and check the boxes below next to the issuetypes which can be associated with a changeset on submission. Repeat for eachgroup or user and press <Ok> when finished.

So the example above states that all users belonging to the 'Developers' group willneed to submit either a 'Defect' or 'Enhancement' when submitting a changeset.

The first checkbox should be checked when you do not require an issue to besubmitted when merging a changeset associated with one of these issues. The user istherefore able to submit a change which has merged either a defect or enhancement.See the Merging Changesets & Issues section of the PureCM User Guide for adescription of how to merge changes and issues between streams.


57

The second checkbox should be checked if you only accept merged issues when themerge change is fully merged, i.e. all files belonging to the original change areincluded in the new change. Otherwise the user must associate a new issue.


58

Issue Views

Issue views allows you to define a subset of all the issues to be displayed. A view may'overlap' with other views.

To create a new view, right click Issue Views and select 'New' from the menu.

NoteIf you will require the issue views to be separated into different folders, createthe folders first from the context menu and then create the views within thenew folders.

Figure 5.27. Issue View Wizard - Select Name

Enter a name for the view. Press <Next> to continue.

Figure 5.28. Issue View Wizard - Select Issues


59

A separate page will now be shown for each of the issue types present.

This page allows you to define an expression to describe the issues that are to bedisplayed in the view. The complete expression can be as simple or complex as yourequire. To see how the expression is defined, press the <New> button and use thedrop down lists or text boxes to select a criteria.

NoteThe 'Issue Field' and 'Value' will vary according to the way the issue wasdefined, as described earlier in this chapter.

If required, press the <New> button again and select a second criteria. When thesecond criteria has been specified, 'AND' appears in the AND/OR column. This can bechanged by double clicking in the field and selecting 'OR' from the drop down list. Inthe first case both criteria must be satisfied for the issue to appear in the view and inthe second case either criteria may be satisfied for the issue to appear in the view.

The expression can be made more complex by using brackets to definesub-expressions. Double click to the left or right of an expression to access the dropdown list of brackets (single, double or triple).

If no criteria are specified then all issues belonging to this type will be included.

Check the 'Exclude' checkbox if you don't want any issues of this type to appear in theissue view.

Press <Next> to continue and, where applicable, define the expressions for otherissue types. Press <Finish> when completed.

NoteOnce created an issue view can be exported as a CSV file by right clicking onthe view and selecting 'Export' from the menu.


60

Workflow

Workflow can be seen as an extension of issue management. Use of workflow addscontrol over the submitting of changesets to the issue lifecycle (as explained in earliersections on issue states and actions). Workflow can also be enhanced by the use ofscripts to generate event messages.

A typical issue using workflow will have a lifecycle that follows the example below:

NoteThis example uses the term 'developer' for those who make the code changesand 'manager' for those who approve the changes. In reality these roles aremore likely to be assigned to junior developers and senior developers (or teamleaders). See Chapter 6, Users & Groups for a description of how to setup theusers and groups.

1. An issue is raised and is assigned by a manager to a developer.

2. The issue is resolved by the developer and, with an associated changeset, isassigned back to the manager for approval. Note that, at this point, the changesetassociated with the issue have not been submitted to the repository.

3. The manager may then do one of the following:

a. Reject the proposed resolution. In this instance the changeset is notsubmitted to the server and the issue is reassigned to the developer. Notethat the changeset associated with the proposed resolution is not lost if theresolution is rejected.

b. Accept the proposed resolution. The changeset is submitted to the repositoryand the issue is then cleared.


61

Configuring Workflow

Configuring PureCM for the above example requires two specific settings beyond thestandard issue management configuration:

1. The developers must not be able to submit changesets.

This involves creating an issue action, and associated state, allowing the developersto 'assign for approval' or 'submit for checking'.

Figure 5.29. Workflow Issue State - State Details

Moreover, none of the issue states that can be actionned by the developers can havethe Accept Changesets option, as shown above, checked.

2. The managers must be able to reject changesets associated with an issue.

The managers will need issue actions, and associated states, allowing them to rejector accept the proposed issue resolution and associated changesets.

Figure 5.30. Workflow Issue Action - Action Details


62

The Reject option shown above must be checked to ensure that the 'reject' or 'retry'action does not submit the changesets to the repository.


63

Extending Workflow

The example scripts below can be used to trigger email notifications. In this way themanagers will be informed when there are proposed issue resolutions and thedevelopers will be informed about the result.

NotePlease refer to Chapter 14, Using Scripts for more information.

def OnReviewAssigned(review,email,description,issue):TEXT = "Description\r\n===========\r\n%s\r\n" % (description)ADDRESS_TO = [email]SMTP_SERVER = 'server.mycompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = '%s has been assigned to you' % (issue)MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)server.login('userid','password')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()return

def OnReviewAccepted(review,user,email,comments,issue):TEXT = "Reviewer Comments\r\n=================\r\n%s\r\n" % (comments)ADDRESS_TO = [email]SMTP_SERVER = 'server.mycompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = '%s has been accepted' % (issue)MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)server.login('userid','password')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()return

def OnReviewRejected(review,user,email,comments,issue):TEXT = "Reviewer Comments\r\n=================\r\n%s\r\n" % (comments)ADDRESS_TO = [email]SMTP_SERVER = 'server.mycompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = '%s has been rejected' % (issue)MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)server.login('userid','password')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()return

def OnReviewFailure(review,user,email,reason,issue):TEXT = "Error Log\r\n=========\r\n%s\r\n" % (reason)ADDRESS_TO = [email]SMTP_SERVER = 'server.mycompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = '%s has failed submission' % (issue)


64

MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)server.login('userid','password')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()return


65


66

Chapter 6. Users & Groups

About Users & Groups

PureCM users and groups are linked to the policysets outlined in Chapter 7, PolicyAdministration. The policyset will control the setup and allowed functions for the useror group.

NoteIf a policyset does not exist for a user or group then the default policyset willapply.

It is usually easiest to start by creating groups, or amending the existing groups, toreflect the structure within your company. The users can then be created and addedto the groups at the same time.

NoteWhere existing groups and users exist, they can be amended by doubleclicking on them (or right click and select 'Properties' from the menu).

67

Creating a Group

To create a new group, right click on Groups and select 'New' from the menu.

Figure 6.1. Group Wizard - Details

Enter a name for the group and a description. Press <Next> to continue.

Figure 6.2. Group Wizard - Select Users

Users & Groups

68

If the users are already created, place a tick in the box next to each user you wish toassign to the group.

NoteIf the users are not yet created, they can be assigned to one or more groupsduring set up.


Figure 6.3. Group Wizard - Complete

Users & Groups

69

Press <Finish> to create the new group. Repeat the above for all the groups required.

NoteSee Chapter 7, Policy Administration for details of creating the policysets forthe new groups.

Users & Groups

70

Creating a User

To create a new user, right click on Users and select 'New' from the menu.

Figure 6.4. User Wizard - Details

Enter a name for the user. An email address and a description - usually the full name -can also be specified.

The 'Locked' checkbox is used to disable a user. If a user is locked then they cannotconnect to the server.


Figure 6.5. User Wizard - Authentication

Users & Groups

71

Select the authentication requirements for the new user and enter the appropriatedetails. You will notice that you can specify multiple authetications for a single user.So for example you could enable 'Windows Domain Authentication' for when you arelogged on within the domain, and also enable 'Password Authentication' for when youare not. Press <Next> to continue.

NoteWhen using 'Domain Authentication' a user will automatically be created if the'Auto-Enroll Windows Domain Users' policy is enabled (the default). If youwant to use an existing user then you must change the user name to be'domain/user'.

Figure 6.6. User Wizard - Groups

Users & Groups

72

If the groups are already created, place a tick in the box next to each group to whichthe user should belong.

NoteIf the groups are not yet created, users can be assigned to groups during setup.


Figure 6.7. User Wizard - Complete

Users & Groups

73

Press <Finish> to create the new user. Repeat the above for all the users required.

NoteSee Chapter 7, Policy Administration for details of creating policysets for thenew users or groups.

Users & Groups

74

Users & Groups

75

Chapter 7. Policy Administration

About Policy Administration

A policyset is a collection of policy values controlling the setup and functions of arepository, stream, user or group of users

The default policyset is created automatically and can never be deleted. Furtherpolicysets can be created for a repository, a stream within the repository, a user or agroup. The order of precedence for policysets is:

• User-Stream. A policyset for a specific user, only applying to a specific streamwithin a specific repository.

• Group-Stream. A policyset for all users belonging to a specific group, only applyingto a specific stream within a specific repository.

• User-Repository. A policyset for a specific user, applying to all streams within aspecific repository.

• Group-Repository. A policyset for all users belonging to a specific group, applyingto all streams within a specific repository.

• User. A policyset for a specific user, applying to all streams within all repositories.

• Group. A policyset for all users belonging to a specific group, applying to allstreams within all repositories.

• Stream. A policyset for all users, only applying to a specific stream within a specificrepository.

• Repository. A policyset for all users, applying to all streams within a specificrepository.

• Default. A policyset for all users, applying to all streams within all repositories.

So if a policy value is set in a policyset applying to that user, and the policy value isalso set in a policyset applying to the stream, then the first policy value will be used.

NoteAn administrator can reset all policysets with the 'tdbutil resetpolicies'command. This can be useful in situations where no one has the 'PolicyAdministrator' policy enabled (e.g. you accidentally delete the administratoruser). 'tdbutil' is installed with the server. For help on using tdbutil type 'tdbutil'on a command prompt. You must stop the PureCM service before runningtdbutil commands.

76

Creating a Policyset

To create a new policyset, right click on Policy Admin and select 'New' from the menu.

Figure 7.1. Policyset Wizard - Select Repository

Select whether the policyset is to apply to all repositories or to a specific repository,chosen from the drop down list. Press <Next> to continue.

Figure 7.2. Policyset Wizard - Select Stream

Policy Administration

77

If the policyset is set to apply only to a specific repository then you can select whetherit should apply to all streams in the repository or only to a specific stream. Press<Next> to continue.

Figure 7.3. Policyset Wizard - Select User or Group

Use the radio buttons and drop down lists to select whether this policyset will apply toall users, a specific group or a specific user. Press <Next> to continue.

Figure 7.4. Policyset Wizard - Specify Name


78

Enter a name for the policyset and a description. Press <Next> to continue.

Figure 7.5. Policyset Wizard - Complete

Press <Finish> to create the policyset.

With the policyset created it will then need to be defined as described in the nextsection.


79

Defining a Policyset

To define the policies that should apply to a policyset, double click the policyset (orright click and select 'Properties' from the menu) and select the 'Policies' tab.

Figure 7.6. Policyset Properties - Empty

Press <Add> to add a policy from the list. The list of what policies are available inwhat category can be found in the section called “List of Policies”.

Figure 7.7. Policyset Properties - Completed


80

With the policy added, double click to change the value.

Figure 7.8. Policyset Properties - Policy Setting

Alternatively you can select the policies you want to change and right-click toenable/disable them.


81

List of Policies

The default policyset will contain all the policies, initially with the default values. Youcan enable/disable these policies in the default policyset - but you cannot delete them.After you create a new policyset it will initially be empty (i.e. contain no policies). Youare then free to add a policy which will override the default policyset.

NoteThe Administration and Setup categories are only available in the defaultpolicyset. It does not make sense to override these policies for an individualuser or repository.

The following policies are available:

Table 7.1. General Policies

Policy Value Definition

Multiple Checkout Enabled orDisabled

Check out files which are alreadychecked-out by other users

Automatic Merge Enabled orDisabled

Automatically merge when synchronisingor submitting a changeset

View ArchivedChangesets

Enabled orDisabled

View all previously submittedchangesets

View MyChangesets

Enabled orDisabled

View pending changesets

View LocalChangesets

Enabled orDisabled

View local changesets (developers'changesets being tracked on server)

NonlockableAccount

Enabled orDisabled

Specifies whether the user can belocked. Users are locked after thepassword expires or the maximumpassword attempts has been exceeded

Stream Locking Enabled orDisabled

Ability to lock the stream to prevent otherdevelopers submitting changes

Custom ActionUser

Enabled orDisabled

Ability to perform custom actions

Lock Files onDelete

Enabled orDisabled

Determines whether files areautomatically locked when deleted in aworkspace


82

Table 7.2. Administration


UserAdministration

Enabled orDisabled

Create, amend or delete users andgroups

PolicyAdministration

Enabled orDisabled

Create, amend or delete policysets

RepositoryAdministration

Enabled orDisabled

Create, amend or delete repositories

EventAdministration

Enabled orDisabled

View the event log

BackupAdministration

Enabled orDisabled

Start and end backups, and truncatelogs

ConnectionAdministration

Enabled orDisabled

View the connections list

LicenseAdministration

Enabled orDisabled

Add, modify or remove license keys

Table 7.3. Repository Admin


File TypeAdministration

Enabled orDisabled

Create, amend or delete the default filetypes

ChangesetAdministration

Enabled orDisabled

Delete local changesets (developers'changesets being tracked on server) andshelvesets

ScriptAdministration

Enabled orDisabled

Create, amend or delete scripts

Custom ActionAdministrator

Enabled orDisabled

Ability to create/edit/delete customactions and properties

File LockAdministration

Enabled orDisabled

Allow stream file locks to be removed

Table 7.4. Setup


83


Connection IPRange

IP address range Valid IP address range for a successfulconnection (see IP format note below)

Stored LogBackups

Number Number of old database log backups tobe kept before automatic deletion

Auto-EnrollWindows DomainUsers

Enabled orDisabled

Windows authentication users willautomatically be added as users

Auto-EnrollCertificate Users

Enabled orDisabled

Certificate authentication users willautomatically be added as users

Audit User Logins Enabled orDisabled

Write audit messages for every login

Address DenyMask

IP address range IP address range from which access isdenied (see IP format note below)

Address AllowMask

IP address range IP address range from which access isallowed (see IP format note below)

RetainedSnapshots

Number Number of old snapshots to be keptbefore automatic deletion

MaximumPasswordAttempts

Number Number of incorrect password attemptsuntil the user is locked

Password ExpiryDays

Number Number of days until the passwordexpires and the user is locked

Automatic LogTruncation

Enabled orDisabled

Automatically truncate the database log

SSL/TLSConnections only

Enabled orDisabled

Only allow SSL/TLS connections

Enable PythonScripting

Enabled orDisabled

This policy must be enabled in thedefault policyset to enable the Pythontriggers

NoteThe ip format uses the internet standard. For example if I wanted to deny all ipaddresses which match (10.0.0.* and 10.4.*) the value I would specify in the'Address Deny Mask IP address'would be '10.0.0.0/24;10.4.0.0/16'. You mustalways specify a valid ip address (i.e. I need to specify 10.4.0.0 even thoughI'm only interested in 10.4) and that the number after the slash refers to thenumber of bits of the ip address to use (8 for the first number, 16 for the firsttwo, 24 for the first three and 32 for the complete ip address). So if there was a


84

specific ip address I wanted to deny I would type '10.0.0.4/32'.

Table 7.5. Stream


SCC Status Paths File specifications Allows new extensions to be added tothe source code control interface

Ignore File Paths File specifications Specify file specifications to be ignoredby PureCM

Track Changes onServer

Enabled orDisabled

Developer file changes are tracked onthe server as a local changeset

Table 7.6. General Professional


Proxy ReferralConfiguration

String Specify how to refer clients to proxieslocal to them

Merge PathAdministration

Enabled orDisabled

Users with this policy are able tocreate/modify/delete merge paths

Enable MergePaths

Enabled orDisabled

Users with this policy can use mergepaths (i.e. the Merging View is available)

Enable Reports Enabled orDisabled

Users with this policy can use report (i.e.the Reports View is available)

Table 7.7. Issue Management


IssueAdministration

Enabled orDisabled

Create, amend or delete issue states,fields, actions and forms

Issue Use Enabled orDisabled

Create, amend or delete issues

Issue Field ValueAdministration

Enabled orDisabled

Ability to modify Issue Field CustomValues within the 'Button' Form ControlDialog


85


86

Chapter 8. File Permissions

About File Permissions

Permissions can be set to configure who can read, edit, create and delete files.

The default permissions are set within the Global Properties. These can be changedby right-clicking the server tree item and selecting 'Global Properties...'. These can beoverridden within the properties of a repository, stream folder, a stream, a folder withina stream or an individual file.

NoteIt is often convenient to create stream permissions for the stream folder andhave all streams inherit the permissions from the parent. For example, for thestream folder 'Development' you may specify that all 'Developers' can edit files.For the stream folder 'Release' however you may specify that only 'LeadDevelopers' are able to edit files. All streams within these folders will thereforeinherit the permissions. When you then move a stream from 'Development' into'Release' the permissions will automatically inherit from the new stream folder.

The following permissions can be checked or unchecked:

Table 8.1. File and Folder Permissions

Permission Definition

Read If checked the user is able to read filesand the files will be downloaded onupdate

Add If checked the user can add new files

Edit If checked the user can edit files

Rename If checked the user can rename files

Delete If checked the user can delete files

Folder Add If checked the user can add folders

Folder Delete If checked the user can delete folders

Folder Rename If checked the user can rename folders

Permissions If checked the user can change thepermissions

87

File Permissions

88

Chapter 9. File Types

About File Types

File types are used as a centralized way in which administrators can change settingsfor all files of a particular type. For example, an administrator can change theencoding of all files of a particular type. The change will then be applied to each userwhen they next update their workspace.

Each file belongs to one file type. The file type of a file can be changed by any userable to edit the file, as described in the Add, Edit & Submit section of the PureCMUser Guide.

89

Creating, Editing and Deleting File Types

To create a new file type or edit an existing file type you must have the 'File TypeAdministration' policy enabled, as described in the section called “Defining aPolicyset”.

To create a new global file type, right click the 'File Types' tree item under the servertree item and select the 'New' menu. This file types will apply to all repositories.

To create a new repository file type, right click the 'File Types' tree item under therepository tree item and select the 'New' menu. This file types will only apply to thisrepository.

NoteIf you create a repository with the same type and subtype as a global file type,then the repository file type will override the server file type. This can be usefulwhere you have a repository with a special case. For example, you mightgenerally want 'text/plain' files to be Ascii encoding, so a global 'text/plain' filetype will be created with Ascii encoding. You might, however, have a particularrepository where you want the encoding to be 'UTF-8'. So you will create arepository file type 'text/plain' with encoding 'UTF-8'.

To edit an existing file type right click the file type and select 'Properties'.

Figure 9.1. File Type Properties - General

File Types

90

Select the file type from the drop down and enter the file subtype in the edit box.These are used by users when setting their local file type options, as described in theClient Options section of the PureCM User Guide.

The list of file extensions is used to establish the default file type of a file when it isfirst added to the server. So in the example above, all files with the cpp extension willdefault to use the file type 'text/c++'. The default file type can be overridden by theuser when adding the file as described in the Add, Edit & Submit section of thePureCM User Guide..

Figure 9.2. File Type Properties - Description

Enter a description for the file type is required.

Figure 9.3. File Type Properties - Flags

File Types

91

Check the flags you want to enable for files belonging to this file type. See the sectioncalled “File Type Flags” for a description of the different flags.

Select the encoding of all files belonging to this file type. So in the example above allfiles belonging to the 'text/c++' file type will be encoded as Ascii when downloaded bya user into a workspace as described in the Client Connection, Update to Latestsection of the PureCM User Guide.

To delete file types select them in the list and right-click 'Delete'. You cannot deletebase file types. Base file types are used by PureCM as a fall back if a more specificfile type cannot be found. The list of base file types includes 'text/plain', 'text/utf-8','text/utf-16' and 'application/generic'.

File Types

92

File Type Flags

The following flags can be enabled for each file type.

Keyword Expansion

If this is enabled then the following keywords will be expanded:

Table 9.1. Keywords

Keyword Expanded To

$Revision:$ The revision of the file

$Date:$ The date this revision was submitted

$ID:$ A unique id for this file revision in thisstream

$NoKeywords:$ Any following keywords will not beexpanded

NoteIf you specify a double colon then the space between the last colon and the $will never be exceeded. For example '$Date:: $' will expand to '$date: 08/$'trimming off the remaining date.

Always writable

If this is enabled then the workspace file will never become read-only. If this isdisabled then all checked-in files will be read-only, unless otherwise specified whencreating the workspace (see the Client Connection, Create the Workspace section ofthe PureCM User Guide.).

Automatically Lock when Checking Out

If this is enabled then the file is automatically locked when a user checks a file out andthey are connected to the server. See Chapter 10, File Locking for a description of filelocks. This is useful when concurrent development doesn't make sense for certainfiles, so the file is automatically locked preventing 2 users from checking the file outsimultaneously. For example, you might disable this for 'text/c++' files where changescan be merged, but you might enable it for 'image/generic' files where changes cannotbe merged.

Restore Modification Time

This is used to determine the modification times of the files when they aredownloaded to the user as described in the Client Connection, Update to Latestsection of the PureCM User Guide. If enabled, the modification time will match thedate and time of when the file was last submitted. If not enabled, the modification time

File Types

93

will be the date and time the file is created/updated on the local machine.

Force this File Type to be Used

On the 'General Page' you can specify which file extensions to use for this file type.So if a user adds a file in a workspace, PureCM will see if the file extension matchesany file type extensions.

If this is unchecked, PureCM will read the file to determine the encoding of the file. Ifthe file extension and encoding matches the file type then this file type is used.

If this is checked then the encoding is not checked. So the file will be added as this filetype if the extension matches, regardless of what encoding the file is.

Disable Writing of Unicode Identifier

To recognise the encoding of files it can be necessary for the file to contains a BOM,which individual applications use to determine the encoding/endian. If this is notrequired then the flag should be enabled.

File Types

94

File Types

95

Chapter 10. File Locking

About File Locking

File locks are used to prevent multiple users editing the same file at the same time.There are four ways in which file locking can be achieved:

1. Disable the 'Multiple Checkouts' policy to lock a file whenever it is being edited.This will prevent two users editing the same file at the same time. This isdescribed in the section called “Mandatory File Locking”.

2. Set the 'Automatically lock when checking out' flag on the file type. This will warnthe user when attempting to edit a file which someone else has locked. The userwill not be able to submit a change to the file until the lock has been released.This is described in the section called “Automatic File Locking”.

3. Let the user manually lock a file. Other users will not be able to submit a changeto the file until then lock has been released. This is described in the section called“Manual File Locking”.

4. Let the user lock the stream. Other users will not be able to submit any changesto the stream until the lock has been released. This is described in the sectioncalled “Stream Locking”.

96

Mandatory File Locking

If you don't want to support concurrent development for some users then disable the'Multiple Checkouts' policy as described in the section called “Defining a Policyset”.When a user edits a file the file will be automatically locked. When another userattempts to edit the file he/she will be unable to 'checkout' the file until the lock hasbeen released.

The advantage of this is that the user will never have to merge another user'schanges with their own. The disadvantage is that users will be unable to work on a filewhile another user is working on the file.

NoteUsers without the 'Multiple Checkouts' policy set will be unable to checkoutand delete files when not connected to the server.

File Locking

97

Automatic File Locking

If you don't want to encourage concurrent development on files belonging to a file typethen the 'Automatically Lock when Checking Out' flag should be set as described inthe section called “File Type Flags”. When a user edits a file the file will beautomatically locked. When another user attempts to edit the file he/she will bewarned that another user has locked the file. Other users will not be able to submit anedit to the file until the lock has been released.

This is useful for file types where merging is not supported. An example might beimage files, which would belong to the 'image/generic' file type.

File Locking

98

Manual File Locking

If there is a particular situation where a user does not want other users to edit a filethen the user can select the 'All Tasks | Lock' menu on the file. When another userattempts to edit the file he/she will be warned that another user has locked the file.Other users will not be able to submit an edit to the file until the lock has beenreleased.

This is useful if a user is dramatically restructuring a file and therefore doesn't want tomerge other edits when finished.

File Locking

99

Stream Locking

If a user wants to prevent other users making any changes to an entire stream theuser can lock the stream. To do so right click on the stream and select 'Lock' from themenu.

An example of where stream locking might be useful is when submitting changes. Inlarge projects after making some changes the developer may be required to 'UpdateTo Latest' to integrate everyone else's changes. He/she may then be required to runmany unit tests and acceptance tests before the changes can be submitted. It wouldbe very frustrating if after doing all this another user had made another submit so thewhole procedure needed to be repeated. In this situation the user might lock thestream before the 'Update to Latest' and unlock it after the submit.

File Locking

100

Tracking Developer Changes and Deleting File Locks

Figure 10.1. Local Changesets Folder

To track changes for developers the 'Track Changes on Server' policy must beenabled as described in the section called “Defining a Policyset”.

Users can view local changes if they have the 'View Local Changesets' policyenabled. The local changes folder will show all changesets within each workspace.Clicking on a local changeset node will display all files being added, edited or deletedwithin that changeset. The 'Lock Type' column shows whether the file is locked(Exclusive) or not (Normal).

Users can delete local changes if they have the 'Local Changesets Administration'policy enabled. If any of the files within the local changeset were locked (Exclusive)then the lock will be released.

NoteDeleting a local changeset on the server does not actually delete the localchangeset within the workspace. The next time the developer 'checks in' or'checks out' a file the local changeset item will be recreated.

File Locking

101

File Locking

102

Chapter 11. View Server Connections

About Connections

Connections displays the user name, client and IP address of those accessing theserver. When a client disconnects the date and time is displayed. The list displayedcan be sorted by clicking on the column headings.

NoteAn IP address range can be specified for connection to the server - see thePolicy Administration chapter for further information.

103

Connection Entries

User Name

The name of the user currently connected. Where domain authentication is in usethen the format will be 'domain/username', where password authentication is in usethen just the user name will be displayed.

Client

The name of the computer from which the connection is made.

IP Address

The IP address of the computer from which the connection is made.

Time Disconnected

Will display 'Connected' or the time of the last disconnect.

Connection Count

Will display the number of connections this user has to the server from this computer.

View Server Connections

104

View Server Connections

105

Chapter 12. Event Log

About the Event Log

The event log records every significant happening in PureCM. Clicking on the columnheadings at the top allow the events to be displayed according to type, date, user ordescription.

NoteEvents are also recorded in the Windows NT Event Viewer (Control Panel ->Administrative Tools -> Computer Management -> System Tools-> EventViewer -> Application). This allows the events to be reported by remotemanagement tools.

Events can be deleted with the ClearEventLog() trigger function as described in thesection called “PureCM Server Functions”.

106

Event Log Entries

Figure 12.1. Event Log

Event log entries are divided into three different types:

Information. This type of entry is used to record that an event has occurred e.g. achangeset submission.

Warning. This type of entry is used to indicate that an action could not be completed,and will usually indicate the solution e.g. trying to submit a file without the latestrevision being present.

Fatal Error. Where the cause is not immediately obvious please contact PureCMsupport for resolution.

Event Log

107

Event Log

108

Chapter 13. Reporting

About Reports

The PureCM reporting function creates on-screen reports, printouts or documentsshowing usage of the software, allowing you to accurately monitor individuals orgroups. Moreover, trends can be spotted regarding the number and type of issuesraised and resources allocated accordingly.

PureCM reports are XML-based and customisable with a knowledge of XSLT.

109

Creating a New Report

NoteThe following example is based on the 'Issue List' template and theParameters page will differ if another template is selected. See the sectioncalled “General Reports” for a summary of the different templates.

Figure 13.1. Report Wizard - Select Template

Select the template category and template to be used as the basis of the report usingthe drop down lists and press <Next> to continue. See the section called “GeneralReports” for a summary of the different templates.

Figure 13.2. Report Wizard - Details

Reporting

110

Enter a name and description for the new report, or use the defaults, and press<Next> to continue.

Figure 13.3. Report Wizard - Issue View

This page will not appear for 'General' reports.

For Issue reports you can filter the issues reported on according to an issue view. Soif you only wanted to report on 'Cleared' issues you would create an issue view

Reporting

111

filtering on the state 'Cleared' and then select this view. See the section called “IssueViews” for a full description of issue views. You can choose to select the issue viewdynamically before generating the report or for the report to always use the specifiedview.

Figure 13.4. Report Wizard - Parameters

This page will differ depending on which report template you selected. Each templaterequires different parameters. See the section called “General Reports” for a summaryof the different templates.

Each issue type has a corresponding tab along the top. Check the 'Include' checkboxif you want issues belonging to this type to be reported on. Use the <New> and<Delete> buttons to select the fields to be included in the report. Each field will berepresented as a column within the report

With a field highlighted on the right the arrow buttons can be used to change the orderof the fields. Highlight each issue type in turn, make any required amendments, andpress <Next> to continue.

NoteThe <Preview> button can be used to see the report format before continuing.

Figure 13.5. Report Wizard - Permissions

Reporting

112

The permissions for the report can be set here. See the section called “ReportPermissions” for a full description of setting report permissions.

Figure 13.6. Report Wizard - Complete

Press <Finish> to create the report.

NoteTo make amendments to the report, right click the report and select

Reporting

113

'Properties' from the menu. See the section called “Customising a Report” for afull description on how to modify a report.

Reporting

114

Running a Report

To run a report at any time, right click the report and select one of the following:

• 'Generate' will display the report on screen, from where it can be printed ifrequired. Double-clicking the report will also display the report on screen.

• 'Generate to file' will allow you to save the report in HTML format.

• 'Generate XML to file' will save the generated XML to a file. See the section called“Customising a Report” for a description on how to manually edit the XSLT whichwill be applied to this XML for advanced customizations.

Reporting

115

Creating a Report Folder

Report folders are used to organize you reports. They can also be used to setup thereport permissions as described in the section called “Report Permissions”.

To create a new report folder right click the parent report folder and select 'New |Folder'.

Figure 13.7. Report Folder Wizard - General

Enter a name and description for the new report folder.

Figure 13.8. Report Folder Wizard - Permissions

Reporting

116

Set the permissions for the report or select 'Inherit from Parent'. See the section called“Report Permissions” for a description of report permissions.

Reporting

117

General Reports

Figure 13.9. General Reports - Changeset

The Changeset report provides a list of submitted changesets. The report can becustomized by specify a date range for the submitted changesets and by specifyingwhat to display within each column.

Figure 13.10. General Reports - Changeset Items

The Changeset Items report is the same as the Changeset report only with an

Reporting

118

additional changeset items column. The changeset items column displays all files andfolders changed within the changeset along with what the change was (Added, Editedor Deleted).

Figure 13.11. General Reports - Changeset Items by User

The Changeset Items by User report is the same as the Changeset Items report onlylisting the changesets submitted by individual users/groups separately.

Figure 13.12. General Reports - Release Notes

Reporting

119

The release notes report allows users to compare two streams and show changesmade between them. It will list all submitted issues thus creating a Release Notespage.

Figure 13.13. General Reports - Changeset Item Release Notes

This type of report lists change items submitted in the target stream which have notbeen submitted in the base stream.

Reporting

120

Issue Reports

Issue reports can be associated with an issue view to filter the issues reported on. Soif you only wanted to report on 'Cleared' defects you would create an issue view whichonly displayed 'Cleared' defects and associate the report with this view. See thesection called “Issue Views” for a full description of issue views.

Figure 13.14. Issue Reports - Issue List

The Issue List report provides a list of issues. The report can be customized byspecifying what to display within each column.

Figure 13.15. Issue Reports - Issue List by User

Reporting

121

The Issue List by User report is the same as the Issue List report, only listing theissues according to who owns the issue.

Figure 13.16. Issue Reports - Issue List by State

The Issue List by State report is the same as the Issue List report, only listing theissues according to what state the issue is in.

Figure 13.17. Issue Reports - Issue List by Custom Field

Reporting

122

The Issue List by Custom Field report is the same as the Issue List report, only listingthe issues according to a specified custom field.

Figure 13.18. Issue Reports - Issue List with Time

The Issue List with Time report is the same as the Issue List report, only with an extra'Total Time' column. The total time is the sum of hours taken for all actions performedon the issue. The hours taken to perform an action are specified when performing theaction, as described in the Working with Issues section of the PureCM User Guide.

Figure 13.19. Issue Reports - Issue Action List

Reporting

123

The Issue Action List report provides a list of actions performed. The report can becustomized by specifying which actions to report on and what to display within eachcolumn.

Figure 13.20. Issue Reports - Issue Details

The Issue Details report provides a detailed description of each issue. The report canbe customized by specifying which issue fields to include.

Figure 13.21. Issue Reports - State Distribution

Reporting

124

The State Distribution report provides a summary of how many issues are in aparticular state at a specified time. So the example above shows that at midnight on28th January there was a total of 2 issues and both issues were cleared. One weeklater however there was a total of 7 issues (so 5 issues had been created) and 2 ofthese were live.

The report can be customized by first specifying the time interval. The time interval forthe example above is 'days' but you can specify 'weeks', 'fortnights', 'months' or even'years'. The report can be customized by specifying the start and end dates. Finallythe report can be customized by specifying which states to include within eachcolumn. In the example above the 'live' column contains the 'Created', 'Being Fixed'and 'Pending Review' issue states.

The State Distribution report is particularly useful when looking at the trend of aproduct's life. For example you might expect the number of 'live' issues to significantlyreduce when the product is close to completion. Similarly you would expect thenumber of 'live' issues to increase during a testing period.

Figure 13.22. General Reports - Issue Release Notes

Reporting

125

This report will list issues submitted in the target stream which have not beensubmitted in the base stream.

Reporting

126

Issue Trend Reports

Issue Trend reports are designed to show trends regarding the number and type ofissues raised and resources allocated accordingly.

Figure 13.23. Issue Trend Reports - Action Trend

The Issue Action Trend report shows the number of actions performed within a giventime period. So the example above shows that 2 issues were raised and two issueswere cleared on the 28th January.

The report can be customized by first specifying the time interval. The time interval forthe example above is 'days' but you can specify 'weeks', 'fortnights', 'months' or even'years'. The report can be customized by specifying the start and end dates. Finallythe report can be customized by specifying which actions to include within eachcolumn.

Figure 13.24. Issue Trend Reports - User Action Trend

Reporting

127

The Issue Action Trend report shows the number of actions performed within a giventime period by individual users or groups of users. So the example above shows thatDave fixed two defects/enhancements on 28th January.

The report can be customized by first specifying the time interval. The time interval forthe example above is 'days' but you can specify 'weeks', 'fortnights', 'months' or even'years'. The report can be customized by specifying the start and end dates. Thereport can be customized by specifying which users and groups to include. Finally thereport can be customized by specifying which actions to include.

Figure 13.25. Issue Trend Reports - User Issue Time Trend

The User Issue Time Trend report shows the number of hours spent performingactions within a given time period by individual users or groups of users. So theexample above shows that Dave spent 6 hours fixing defects/enhancements on 28thJanuary. The hours taken to perform an action are specified when performing theaction, as described in the Working with Issues section of the PureCM User Guide.

The report can be customized by first specifying the time interval. The time interval forthe example above is 'days' but you can specify 'weeks', 'fortnights', 'months' or even'years'. The report can be customized by specifying the start and end dates. Thereport can be customized by specifying which users and groups to include. Finally thereport can be customized by specifying which actions to include.

Reporting

128

Customising a Report

Right click the report and select 'Properties' from the menu to modify the report. Seethe section called “Creating a New Report” for details of each page.

NoteYou can easily change the logo on the report by replacing the file'reportlogo.png' found in the client installation folder (usually \ProgramFiles\PureCM\Client).

For some reports you may wish to restrict the report to a particular stream. Forexample, for a Changeset report you might only want to report on Changesetsbelonging to a particular stream. Select 'Properties' on the report to specify the reportstream.

Figure 13.26. Report Properties - Stream

If you want to restrict the report to an individual stream, press the radio button andselect the stream from the tree tabs as described in the section called “Stream TabViews”.

There may however be times when you want to specialize a report specific to yourrequirements. This can be achieved with a knowledge of XSLT.

The easiest way to customize a report is to generate the XML by selecting 'GenerateXML to File...'. Select 'Modify XSLT...' and copy this into an .xslt file. Edit the XSLT inan external tool (like XMLSpy) and ensure the generated report is correct. Finally copythe new XSLT into the editor after selecting 'Modify XSLT...'.

NoteIf required, the XML schema file - purecm.xsd - can be found in the clientinstallation folder (usually \Program Files\PureCM\Client). The schema fileshould not be amended.

If a report supports intermediary transformations (e.g. the Trend Reports) then the

Reporting

129

intermediary transformation is first applied to the generated XML, and the defaulttransformation is then applied to this output. To enable intermediary transformationscheck the checkbox on the report properties.

If you need to change the XML being generated by the server then modify the'Components' page on the report properties.

Figure 13.27. Report Properties - Components

The 'Components' determine what XML the server sends down to the client whengenerating the report. For performance reasons you should limit the generated xml towhat you need.

Reporting

130

Report Permissions

The administrator can configure the report permissions to determine who can create,read, edit delete and change permissions on a report. These are set against therepository, report folders and specific reports.

Figure 13.28. Report Permissions

The default report permissions are set against the repository and can be modified viathe repository properties. By default all root report folders will then inherit thepermissions from the repository, unless the 'Inherit Permissions' check is unchecked.Report subfolders and reports will by default inherit from their parent folder.

Examples of how you might use permissions include:

• Allow 'Everyone' read access but only Administrators 'Create', 'Edit', 'Delete' and'Permissions' access.

• Create a private report folder for a specific user. Allow the user to 'Create', 'Edit'and 'Delete' reports within the folder. Don't allow anyone else to even read theprivate folder, except the Administrator.

• Create a report folder which only certain groups can read. This might be usefulwhere you have reports which you don't want people to read.

Reporting

131

Reporting

132

Chapter 14. Using Scripts

About Scripts

To enable Python scripting you will need to enable the 'Enable Python Scripting' policyin the default policyset. You will need to restart the server after enabling this policy.

If Python is not already installed on the server machine then you will need to installthe Python programming language as described in the section called “InstallingPython (Windows)”.

To amend the scripts you will need to enable the 'Script Administration' policy, asdescribed in the section called “Defining a Policyset”. When this is enabled you willsee the 'Scripts' node in the Administration view under the server and each repository.Select the 'Scripts' node to launch the editor allowing you to amend the scripts.

NoteThe Python website at www.python.org has links to a whole host of tutorialsand user groups.

PureCM has one script for the server and one for each repository. Once Python isinstalled these can be amended as described later in this chapter.

133

Installing Python (Windows)

PureCM supports versions 2.3, 2.4 and 2.5 of Python which can be downloaded fromwww.python.org.

1. Once downloaded, double click the executable to begin installation. As with allinstallations, if not signed on as an Administrator right click on the executable anduse 'Run as'.

2. Select a destination folder and press <Next> to continue.

3. Select whether or not to backup replaced files and press <Next> to continue.

4. Ensure all components are checked and press <Next> to continue.

5. Choose a name for the program group and press <Next> to continue.

6. Press <Next> to begin the installation.

7. Press <Finish> when the installation completes.

8. You may be prompted to reboot to complete the installation. This can be left untilafter the following instructions so press <Cancel>.

The Python installation folder will now need to be added to the path.

1. In the Control Panel double click the System option (if not signed in as anAdministrator, hold down the Shift key and right click System to access the 'Runas' option).

2. On the 'Advanced' tab press the 'Environment Variables' button.

3. In the lower pane highlight the 'Path' variable and press the 'Edit' button.

4. In the 'Variable value' field add the installation folder, e.g. 'C:\Python23' or'C:\Program Files\Python23', to the end of the string. Use a semi-colon toseparate it from the previous value.

5. Press <Ok> three times to close the System dialogues.

6. Reboot the computer.

When the computer restarts, test that scripting is working in PureCM by editing theserver script or a repository script. If it isn't working then try the following:

1. From a command prompt in the Python installation folder run 'python' to ensure itinstalled correctly.

Using Scripts

134

2. At a command prompt run 'path' and check that the Python installation folder ispresent and correctly specified.

3. Ensure that the 'Enable Python Scripting' policy is enabled in the default policysetand the 'Script Administration' policy is enabled in the current policyset.

Using Scripts

135

Python Server Triggers

The following triggers are available in the server script:

# OnStart is called when the Server startsdef OnStart():

return

# OnStop is called when the Server stopsdef OnStop():

return

# OnClientConnect is called when a client connects. Return a warning string to preventdef OnClientConnect(user,client,ipaddress):

return

# OnEveryMinute is called every minute and can be used for schedule itemsdef OnEveryMinute(hour,minute):

return

# OnEveryQuarterHour is called every 15 minutes and can be used for schedule itemsdef OnEveryQuarterHour(hour,minute):

return

# OnEveryHour is called every hour and can be used for schedule itemsdef OnEveryHour(hour):

return

Using Scripts

136

Python Repository Triggers

The following triggers are available in the repository script:

# OnPreSubmitChange is called before submit. Return a warning string to preventdef OnPreSubmitChange(stream,change,user,client,comment):

return

# OnPostSubmitChange is called after a change is submitteddef OnPostSubmitChange(stream,change,user,client,comment):

return

# OnEveryMinute is called every minute and can be used for schedule itemsdef OnEveryMinute(hour,minute):

return

# OnEveryQuarterHour is called every 15 minutes and can be used for schedule itemsdef OnEveryQuarterHour(hour,minute):

return

# OnEveryHour is called every hour and can be used for schedule itemsdef OnEveryHour(hour):

return

# OnReviewAssigned is called when a change is assigned to one or more users for reviewdef OnReviewAssigned(review,email,description,issue):

return

# OnReviewAccepted is called after a change review has been accepteddef OnReviewAccepted(review,user,email,comments,issue):

return

# OnReviewRejected is called after a change review has been rejecteddef OnReviewRejected(review,user,email,reason,issue):

return

# OnReviewFailure is called after a change review has been accepted but the submit faileddef OnReviewFailure(review,user,email,reason,issue):

return

# OnIssueAction is called when an action is being performed on an issuedef OnIssueAction(issue,action,user,email,description):

return

NoteFor an example of using repository scripts please refer to the section called“Extending Workflow”.

Using Scripts

137

PureCM Server Functions

As well as all standard Python functions, PureCM provides some useful utilityfunctions which can be called within the server triggers.

• void MakeDatabaseSnapshots ( )

Creates a snapshot of each database as described in Chapter 15, Backup &Restore.

The example below is used to create database snapshots twice a day.

def OnEveryHour(hour):if hour == 13 or hour == 18:

MakeDatabaseSnapshots( )return

• void ClearEventLog ( number Days )

Deletes events from the event log as described in Chapter 12, Event Log. TheDays specifies the number of days in which events should not be deleted.

The example below is used to clear all events which are more than 30 days old.

def OnEveryHour(hour):if hour == 2:

ClearEventLog( 30 )return

• void TruncateDatabaseLogs ( )

Creates a log archive and clear the active log. This should be performed aftermaking a backup to stop the active log file getting too big.

The example below is used to archive the log every night.


TruncateDatabaseLogs( )return

Using Scripts

138

PureCM Repository Functions

As well as all standard Python functions, PureCM provides some useful utilityfunctions which can be called within the repository triggers.

• [number ErrorCount,string ErrorText] PerformDatabaseChecks ( )

The repository database structure is checked for corruptions.

The example below is used to send an email to two recipients following an hourlycheck of the database.

def OnEveryHour(hour):if hour == 9 or hour == 12 or hour == 15 or hour == 17:

results = PerformDatabaseChecks()if results[0] > 0:

TEXT = results[1]ADDRESS_TO = ['[email protected]','[email protected]']SMTP_SERVER = 'MyServer.MyCompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = 'purecm database checks (%d errors)' % (results[0])MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)server.login('purecm','secret')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()

return

• [number ErrorCount,string ErrorText] PerformReposChecks ( )

Complements PerformDatabaseChecks() by checking the integrity and referentialintegrity of the repository database as well as the data structure. This will takeconsiderably longer than PerformDatabaseChecks().

The example below is used to send an email to two recipients following an hourlycheck of the database.


results = PerformReposChecks()if results[0] > 0:

TEXT = results[1]ADDRESS_TO = ['[email protected]','[email protected]']SMTP_SERVER = 'MyServer.MyCompany.com'ADDRESS_FROM = '[email protected]'SUBJECT = 'purecm repository checks (%d errors)' % (results[0])MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)server = smtplib.SMTP(SMTP_SERVER)

Using Scripts

139

server.login('purecm','secret')server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)server.quit()

return

Using Scripts

140

Using Scripts

141

Chapter 15. Backup & Restore

About Backup & Restore

The PureCM database files are stored in the location specified when installingPureCM (typically PureCM\data). The following files will be found in the directory:

Table 15.1. PureCM Data Files

Name Extension Description

Data File tdf Contains all non-binarydata

Binary Data File tbf Contains all binary data

If you want to backup the PureCM data files using a backup program such asNTBackup on Windows or 'tar' on Unix see the section called “Backing Up thePureCM Data Files”. Although this is the simplest solution, it is recommended that youcreate database snapshots and back these up. Snapshots are compressed andtherefore take up less space than the actual data files.

The PureCM snapshot files are stored in the location specified when installingPureCM (typically PureCM\snapshots). The following files will be found in thedirectory:

Table 15.2. PureCM Snapshot Files


Snapshot File tds A compressed copy of thedata files which can berestored

See the section called “Create a Snapshot” for a description of how to createsnapshots. See the section called “Restoring a Snapshot” for a description of how torestore the snapshot.

If the PureCM database you are backing up is large then you typically wouldn't want tocreate more than one or two snapshots a day. While the snapshots are being createdother users cannot use the tool, and the amount of storage required for manysnapshots will soon mount up.

If you want to perform many backups during the day, a better solution is to backup thelog file as described in the section called “Applying the Log File”. To recover thedatabase you would first recover the snapshot and then apply each log file asdescribed in the section called “Applying the Log File”.

142

The PureCM log files are stored in the location specified when installing PureCM(typically PureCM\logs). The active log files will be found under the logs directory. Anyarchived log files will be found in the subdirectory 'archive' (e.g. PureCM\logs\archive).

Table 15.3. PureCM Log Files


Log Commands File tlf Contains the log of allcommands

Log Pre-Image File tpf Contains the binary dataused by the commandsfile

Backup & Restore

143

Backing Up the PureCM Data Files

The PureCM directory (typically C:\PureCM) can be backed up using a backupprogram such as NTBackup on Windows or 'tar' on Unix. If the server is running, youmust run the 'begin-backup' command before taking a copy of the directory and'end-backup' when finished from the command line. This will ensure a consistentbackup is taken.

Backup & Restore

144

Create a Snapshot

The location of the snapshots was set during the server installation (typicallyPureCM\snapshots). The number of stored snapshots before the oldest one is deletedis set in the 'Retained Snapshots' policy as described in the section called “Defining aPolicyset”. The snapshots can then be backed up using a backup program such asNTBackup on Windows or 'tar' on Unix. Restoring a snapshot is described in thesection called “Restoring a Snapshot”.

NoteAfter making a backup of PureCM you should run the TruncateDatabaseLogs()server function as described in the section called “PureCM Server Functions”.This will prevent the log file becoming huge.

Snapshots can be created automatically with the MakeDatabaseSnapshots() servertrigger function as described in the section called “PureCM Server Functions”.

Snapshots can be created manually by a user who has the 'Backup Administration'policy set as described in the section called “Defining a Policyset”. To create a manualbackup the user will need to run the make-snapshots command from the commandline.

Backup & Restore

145

Restoring a Snapshot

To restore a database snapshot you will need to use the 'tdbutil' utility which will havebeen installed with the server (typically 'Program Files\PureCM\Server').

• Open a command prompt in the server executables directory.

• Type 'tdbutil import <snapshot> <database>'. For example if you have a repositorycalled 'Test1'. The snapshot file will be called 'r_Test1_1.xml.gz'. In this instanceyou would type 'tdbutil import r_Test1.xml.gz r_Test1'. This will create thecorresponding r_Test1.tdf, r_Test1.tbf, r_Test1.tlf and r_Test1.tpf files. These filesshould then be copied into the PureCM data directory (typically PureCM\data).

Backup & Restore

146

Archiving the Log File

The location of the log files was set during the server installation (typicallyPureCM\logs). The number of stored log backups before the oldest one is deleted isset in the 'Stored Log Backups' policy as described in the section called “Defining aPolicyset”. The log files can then be backed up using a backup program such asNTBackup on Windows or 'tar' on Unix. Applying a log file to recreate the database isdescribed in the section called “Applying the Log File”.

Log files can be archived using with the TruncateDatabaseLogs() server triggerfunction as described in the section called “PureCM Server Functions”.

Backup & Restore

147

Applying the Log File

To apply the log files you will need to use the 'tdbutil' utility which will have beeninstalled with the server (typically 'Program Files\PureCM\Server').


• Type 'tdbutil applylog <database path> <logfile base name>'.

Backup & Restore

148

Resetting Policies

If for any reason you have editted your Policy sets incorrectly ( EG. Disabling 'PolicyAdmin' from your last policyset then this command will reset all policies, deleting themand recreating the default policyset.

To use the command you will need to use the 'tdbutil' utility which will have beeninstalled with server (typically 'Program Files\PureCM\Server').


• Type 'tdbutil resetpolicies <server path>'

Backup & Restore

149

Backup & Restore

150

Chapter 16. Administrator Command Line Tool

General

Much of PureCM's administrator functionality can be performed using the commandline tool as an alternative to the GUI. The executable 'pcm.exe' is run as follows:

pcm [(option)] (command)

To see the available options type 'pcm help' from the command line.

151

Administrator Command Line Tool

152

Chapter 17. License Keys

About License Keys

License keys determine how many users can connect to the server at any one time. Ifyou want to increase the number of concurrent users you will need to purchase alicense code from www.purecm.com [http://www.purecm.com/purchase]. You can thencreate a new license key using the code, as described in the section called “Creatinga License Key”.

153

http://www.purecm.com/purchase

Creating a License Key

To create a license key right click the 'License Keys' folder and select 'New'.

Figure 17.1. License Key Entry

Enter your company name in the 'Registered Name' edit box. Enter the license codepurchased through www.purecm.com [http://www.purecm.com/purchase].

NoteThe Registered Name must match the name supplied when purchasing thelicense code. It is recommended that you copy and paste both the 'RegisteredName' and 'License Key' values from the email sent by PureCM.

License Keys

154

http://www.purecm.com/purchase

License Keys Administration

A license key is in one of the following states:

Table 17.1. License Key States

State Description

Normal The license key is valid

Invalid The license code is invalid

Expired The license key has expired

To delete a license key, right click on the license key and select the 'Delete' menu.

License Keys

155

License Keys

156

Appendix A. Issue Templates

Defect

Figure A.1. Issue Templates - Defect

157

Enhancement

Figure A.2. Issue Templates - Enhancement

Issue Templates

158

Simple Defect

Figure A.3. Issue Templates - Simple Defect

Issue Templates

159

Simple Enhancement

Figure A.4. Issue Templates - Simple Enhancement

Issue Templates

160

Issue Templates

161

purecm admin guide

Documents