Purecm Admin Guide

PureCM Administrator Guide
PureCM Administrator Guide
Table of Contents
Glossary .............................................................................................................. x 1. Getting Started ................................................................................................ 1 Introduction .................................................................................................. 1 Register a Server ......................................................................................... 2 Select a Repository ..................................................................................... 6 Working With Views ..................................................................................... 7 Creating a Repository .................................................................................. 8 Adding Files & Folders .............................................................................. 11 Import a Repository ................................................................................... 12 2. Stream Administration ................................................................................... 14 About Streams ........................................................................................... 14 Creating a Stream ..................................................................................... 15 Deleting a Stream ...................................................................................... 20 Moving or Renaming a Stream .................................................................. 21 Creating a Stream Folder .......................................................................... 22 Stream Tab Views ..................................................................................... 25 Stream Permissions .................................................................................. 26 3. Merging .......................................................................................................... 28 About Merging ........................................................................................... 28 4. Components .................................................................................................. 30 About Stream Components ....................................................................... 30 5. Issue Management & Workflow ..................................................................... 32 About Issue Management .......................................................................... 32 Enabling Issue Management ..................................................................... 33 Creating an Issue Type ............................................................................. 34 Issue Fields ............................................................................................... 40 Issue States ............................................................................................... 44 Issue Actions ............................................................................................. 48 Issue State Transition Matrix ..................................................................... 52 Issue Form Editor ...................................................................................... 53 Stream Issue Requirements ...................................................................... 57 Issue Views ............................................................................................... 59 Workflow .................................................................................................... 61 Configuring Workflow ................................................................................ 62 Extending Workflow ................................................................................... 64 6. Users & Groups ............................................................................................. 67 About Users & Groups ............................................................................... 67 Creating a Group ....................................................................................... 68 Creating a User ......................................................................................... 71 7. Policy Administration ..................................................................................... 76 About Policy Administration ....................................................................... 76 Creating a Policyset ................................................................................... 77 Defining a Policyset ................................................................................... 80 List of Policies ............................................................................................ 82 8. File Permissions ............................................................................................ 87 About File Permissions .............................................................................. 87 9. File Types ...................................................................................................... 89 About File Types ........................................................................................ 89 iv
PureCM Administrator Guide Creating, Editing and Deleting File Types ................................................. 90 File Type Flags .......................................................................................... 93 10. File Locking ................................................................................................. 96 About File Locking ..................................................................................... 96 Mandatory File Locking ............................................................................. 97 Automatic File Locking .............................................................................. 98 Manual File Locking ................................................................................... 99 Stream Locking ........................................................................................ 100 Tracking Developer Changes and Deleting File Locks ............................ 101 11. View Server Connections .......................................................................... 103 About Connections .................................................................................. 103 Connection Entries .................................................................................. 104 12. Event Log .................................................................................................. 106 About the Event Log ................................................................................ 106 Event Log Entries .................................................................................... 107 13. Reporting ................................................................................................... 109 About Reports .......................................................................................... 109 Creating a New Report ............................................................................ 110 Running a Report .................................................................................... 115 Creating a Report Folder ......................................................................... 116 General Reports ...................................................................................... 118 Issue Reports .......................................................................................... 121 Issue Trend Reports ................................................................................ 127 Customising a Report .............................................................................. 129 Report Permissions ................................................................................. 131 14. Using Scripts ............................................................................................. 133 About Scripts ........................................................................................... 133 Installing Python (Windows) .................................................................... 134 Python Server Triggers ............................................................................ 136 Python Repository Triggers ..................................................................... 137 PureCM Server Functions ....................................................................... 138 PureCM Repository Functions ................................................................. 139 15. Backup & Restore ...................................................................................... 142 About Backup & Restore ......................................................................... 142 Backing Up the PureCM Data Files ......................................................... 144 Create a Snapshot ................................................................................... 145 Restoring a Snapshot .............................................................................. 146 Archiving the Log File .............................................................................. 147 Applying the Log File ............................................................................... 148 Resetting Policies .................................................................................... 149 16. Administrator Command Line Tool ............................................................ 151 General .................................................................................................... 151 17. License Keys ............................................................................................. 153 About License Keys ................................................................................. 153 Creating a License Key ........................................................................... 154 License Keys Administration ................................................................... 155 A. Issue Templates .......................................................................................... 157 Defect ...................................................................................................... 157 Enhancement .......................................................................................... 158 Simple Defect .......................................................................................... 159 Simple Enhancement .............................................................................. 160
List of Figures
1.1. Register Admin Server Wizard - Details ....................................................... 2 1.2. Register Admin Server Wizard - Authentication Type .................................. 2 1.3. Register Admin Server Wizard - Password Authentication .......................... 3 1.4. Register Admin Server Wizard - Complete ................................................... 4 1.5. Repository Selection Dialog ......................................................................... 6 1.6. PureCM Views .............................................................................................. 7 1.7. Repository Wizard - Details .......................................................................... 8 1.8. Repository Properties - Change ID Format .................................................. 9 2.1. Stream Wizard - Stream Type .................................................................... 15 2.2. Stream Wizard - Stream Name and Description ........................................ 15 2.3. Stream Wizard - Changeset and Location .................................................. 16 2.4. Stream Wizard - Permissions ..................................................................... 17 2.5. Stream Wizard - Stream Permissions ........................................................ 17 2.6. Stream Wizard - Complete ......................................................................... 18 2.7. Stream - Move Rename ............................................................................. 21 2.8. Stream Folder Wizard - Name and Description .......................................... 22 2.9. Stream Folder Wizard - Permissions .......................................................... 22 2.10. Stream Folder Wizard - Stream Permissions ........................................... 23 2.11. Stream Folder Wizard - Complete ............................................................ 24 2.12. Stream Tabs - Normal .............................................................................. 25 2.13. Stream Tabs - Hierarchy .......................................................................... 25 5.1. Issue Type Wizard - Name and Description ............................................... 34 5.2. Issue Type Wizard - Details ........................................................................ 34 5.3. Issue Type Wizard - ID Format ................................................................... 35 5.4. Issue Type Wizard - Select Template ......................................................... 36 5.5. Issue Type Wizard - Group Mappings ........................................................ 37 5.6. Issue Type Wizard - Custom Field Values ................................................. 38 5.7. Issue Type Wizard - Complete ................................................................... 38 5.8. Issue Field Wizard - Details ........................................................................ 40 5.9. Issue Field Wizard - Text Properties .......................................................... 40 5.10. Issue Field Wizard - Number Properties ................................................... 41 5.11. Issue Field Wizard - Boolean Properties .................................................. 42 5.12. Issue Field Wizard - Custom Properties ................................................... 42 5.13. Issue Field Wizard - Complete ................................................................. 43 5.14. Issue State Wizard - Details ..................................................................... 44 5.15. Issue State Wizard - State Details ............................................................ 45 5.16. Issue State Wizard - Valid Fields .............................................................. 45 5.17. Issue State Wizard - Valid Actions ........................................................... 46 5.18. Issue Action Wizard - Name and Label .................................................... 48 5.19. Issue Action Wizard - Details .................................................................... 48 5.20. Issue Action Wizard - End Users .............................................................. 49 5.21. Issue Action Wizard - Operators ............................................................... 50 5.22. Issue Action Wizard - Mandatory Fields ................................................... 51 5.23. Issue State Transition Matrix .................................................................... 52 5.24. Issue Form Editor ..................................................................................... 53 5.25. Issue Form Editor ..................................................................................... 55 5.26. Stream Issue Requirements ..................................................................... 57 5.27. Issue View Wizard - Select Name ............................................................ 59 5.28. Issue View Wizard - Select Issues ........................................................... 59 vi
PureCM Administrator Guide 5.29. Workflow Issue State - State Details ........................................................ 62 5.30. Workflow Issue Action - Action Details ..................................................... 62 6.1. Group Wizard - Details ............................................................................... 68 6.2. Group Wizard - Select Users ...................................................................... 68 6.3. Group Wizard - Complete ........................................................................... 69 6.4. User Wizard - Details .................................................................................. 71 6.5. User Wizard - Authentication ...................................................................... 71 6.6. User Wizard - Groups ................................................................................. 72 6.7. User Wizard - Complete ............................................................................. 73 7.1. Policyset Wizard - Select Repository .......................................................... 77 7.2. Policyset Wizard - Select Stream ............................................................... 77 7.3. Policyset Wizard - Select User or Group .................................................... 78 7.4. Policyset Wizard - Specify Name ............................................................... 78 7.5. Policyset Wizard - Complete ...................................................................... 79 7.6. Policyset Properties - Empty ...................................................................... 80 7.7. Policyset Properties - Completed ............................................................... 80 7.8. Policyset Properties - Policy Setting ........................................................... 81 9.1. File Type Properties - General ................................................................... 90 9.2. File Type Properties - Description .............................................................. 91 9.3. File Type Properties - Flags ....................................................................... 91 10.1. Local Changesets Folder ........................................................................ 101 12.1. Event Log ............................................................................................... 107 13.1. Report Wizard - Select Template ........................................................... 110 13.2. Report Wizard - Details .......................................................................... 110 13.3. Report Wizard - Issue View .................................................................... 111 13.4. Report Wizard - Parameters ................................................................... 112 13.5. Report Wizard - Permissions .................................................................. 112 13.6. Report Wizard - Complete ...................................................................... 113 13.7. Report Folder Wizard - General ............................................................. 116 13.8. Report Folder Wizard - Permissions ....................................................... 116 13.9. General Reports - Changeset ................................................................. 118 13.10. General Reports - Changeset Items ..................................................... 118 13.11. General Reports - Changeset Items by User ....................................... 119 13.12. General Reports - Release Notes ........................................................ 119 13.13. General Reports - Changeset Item Release Notes .............................. 120 13.14. Issue Reports - Issue List ..................................................................... 121 13.15. Issue Reports - Issue List by User ........................................................ 121 13.16. Issue Reports - Issue List by State ....................................................... 122 13.17. Issue Reports - Issue List by Custom Field .......................................... 122 13.18. Issue Reports - Issue List with Time ..................................................... 123 13.19. Issue Reports - Issue Action List .......................................................... 123 13.20. Issue Reports - Issue Details ................................................................ 124 13.21. Issue Reports - State Distribution ......................................................... 124 13.22. General Reports - Issue Release Notes ............................................... 125 13.23. Issue Trend Reports - Action Trend ..................................................... 127 13.24. Issue Trend Reports - User Action Trend ............................................. 127 13.25. Issue Trend Reports - User Issue Time Trend ..................................... 128 13.26. Report Properties - Stream ................................................................... 129 13.27. Report Properties - Components .......................................................... 130 13.28. Report Permissions .............................................................................. 131 17.1. License Key Entry ................................................................................... 154 A.1. Issue Templates - Defect ......................................................................... 157 vii
PureCM Administrator Guide A.2. Issue Templates - Enhancement ............................................................. 158 A.3. Issue Templates - Simple Defect ............................................................. 159 A.4. Issue Templates - Simple Enhancement ................................................. 160
viii
List of Tables
1.1. Repository Change ID Format ...................................................................... 9 2.1. Stream Permissions ................................................................................... 26 5.1. Issue ID Format .......................................................................................... 35 7.1. General Policies ......................................................................................... 82 7.2. Administration ............................................................................................. 83 7.3. Repository Admin ....................................................................................... 83 7.4. Setup .......................................................................................................... 83 7.5. Stream ........................................................................................................ 85 7.6. General Professional .................................................................................. 85 7.7. Issue Management ..................................................................................... 85 8.1. File and Folder Permissions ....................................................................... 87 9.1. Keywords .................................................................................................... 93 15.1. PureCM Data Files ................................................................................. 142 15.2. PureCM Snapshot Files .......................................................................... 142 15.3. PureCM Log Files ................................................................................... 143 17.1. License Key States ................................................................................. 155
ix
Glossary
Server PureCM uses a client-server architecture with a centralized server. To get started with PureCM you need to install the PureCM Server and the PureCM Client (on the same or different machines). Using the PureCM GUI or command line you then need to create 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 a single repository as streams, allowing you to manage shared libraries easily. Note that the repository defines the context for the PureCM GUI, e.g. displaying all projects of your current repository in the Repository View. Stream A stream is used to define your code line, holding all data of a specific project. You need at least one high level stream to start working with PureCM, and all changes get applied against this stream. From there, you can branch off streams for different development stages and separate teams or to create snapshots. Workspace Each developer creates a workspace on their computer for a selected stream. The workspace will mirror the files stored on the server. File additions, deletions and edits are then performed in the workspace before being submitted to the server in a changeset. File consistency can be checked between the client and server versions of files. Changesets and Version Control Change management allows version control of files and directories using a changeset-based approach. A 'changeset' is a related group of file additions, deletions and edits, defined by the developer and annotated with a description on submission to the server. Issues Issue management allows highly-configurable 'issues' to be captured and processed using a workflow-based approach. Possible uses include defect tracking, change requests and requirements management. Changesets can be tied to issues, so that submissions 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. For instance, the ability to review and approve the resolution to an issue may be assigned only to certain developers, and issues may be assigned to developers for resolution. Diff Tool x
Glossary
PureCM provides a tool allowing you to compare 2 versions of a file. Line differences are colour highlighted. Resolve Tool PureCM provides a tool allowing you to resolve 2 versions of a file which have a common base. Changes to different lines are automatically resolved but if the same line 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 changeset is submitted, a revision is created for each file. You can view each revision, compare 2 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. This is useful if you find a bug in a particular line and want to isolate the changeset in which the bug was submitted. Check Consistency Checking the consistency of a workspace involves seeing if any files have been edited, added or deleted without being checked out. An inconsistent workspace is dangerous because you may submit a partial change. Shelving Shelving is the ability to save unfinished work on the server as a shelveset. The changes can then be unshelved into a workspace. This is useful if you want to save work on the server or if you want to move a piece of work from one workspace to another. Client/Server Architecture over TCP/IP TCP/IP is used to allow the client components on the developers' computers to communicate with the central server component. As well as password authentication, support is included for strong authentication using Windows domain authentication or certificate authentication. Concurrent Development Before submitting files to the server the latest changes are downloaded to the client and can then be integrated with your changes. In this way the same files can be edited simultaneously by different developers, with conflicts being handled by the PureCM Resolve tool. In addition, concurrent development is supported with two sets of developers working on separate developments in separate streams which will be integrated at a later date. Remote development Support for remote development is built-in and the PureCM client can be run even xi
Glossary
when a connection to the server is not available. For example a developer can checkout files, make local checkins, view a file's revisions, or view issue summaries while working 'offline'.
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 daily developer tasks are covered in the PureCM User Guide. The PureCM Server will be installed with an 'Example' repository which contains some example streams with example data. The user 'admin' will be created with the password 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 server as described in the section called Register a Server. You will then want to create a new repository as described in the section called Creating a Repository. If you are migrating from Visual SourceSafe, Perforce or CVS you can import your data as described in the section called Import a Repository. Otherwise you will need to create a workspace and submit your files as described in the section called Adding Files & Folders. By default PureCM will be installed without any security (any user can perform any action). 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 in Chapter 8, File Permissions. To specify who can perform which actions in PureCM (e.g. who can create/delete repositories) you need to create PolicySets for the relevant group. This is described in Chapter 7, Policy Administration.
Getting Started
Register a Server
After installing the PureCM Server and Client you will want to connect to the server as user 'admin'. Lauching the PureCM GUI for the first time will launch the Register Server 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 in the list. Alternatively you can enter the 'Server Name', either the DNS name or the IP address, and 'Server Port'. The 'Connect to server on startup' option should be unchecked if you do not want to connect to this server when the PureCM GUI is started. The 'Keep trying to connect' option should be checked if you want to automatically keep 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
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
The administrator user name is 'admin', the password was supplied when installing the PureCM Server (or blank on Linux/Mac servers). Enter the details on the page and press <Next> to continue. Note If you have forgotten your admin password you can use the user 'LeadDeveloper1' and the password 'secret'. You can then change the password for user 'admin'. Figure 1.4. Register Admin Server Wizard - Complete
Getting Started
To complete the Administrator Server registration, check that the details are correct on the final page and press <Finish>. The new connection will appear under the PureCM tree.
Getting Started
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 repositories belonging to that server will appear. Select the 'Example' repository to evaluate PureCM. Figure 1.5. Repository Selection Dialog
You can change the active repository at any time by selecting 'Select Repository' from the File menu or using the 'Select Repository' toolbar button.
Getting Started
Working With Views

After selecting an active repository you will see that multiple views are available in the GUI. The PureCM administrator will determine which views are available to you according to which policies are enabled. Figure 1.6. PureCM Views
The Workspaces View is described in the PureCM User Guide and is used by developers. The Repository View is used to create, delete, edit or view streams as described in Chapter 2, Stream Administration. The Merging View is used to merge changesets between streams as described in Chapter 3, Merging. The Issues View is used 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 as described in Chapter 13, Reporting. The Administration View is used to perform administration tasks such as creating users, file permissions, etc. You can perform all tasks in PureCM using the Administration view (as opposed to using the different views) but this will list everything in a single tree which can be difficult to work with. Note Some of these views may not be available, depending on whether you are using the Standard or Professional Edition and what policies you have enabled. The Workspaces, Repository and Administration Views will always be available.
Getting Started
Creating a Repository
To evaluate PureCM you can use the 'Example' repository. When you are ready to start working with PureCM you will want to create a new repository. To create a repository go to the Administration view and connect to the server by expanding it in the tree. Right click the server and select the 'Create Repository' menu option. The Repository Wizard will be launched. Note Typically you will only have one repository. If you have multiple projects it is usually better to create multiple streams in the same repository for the different projects. This will allow you to share code between the projects using components. Figure 1.7. Repository Wizard - Details
The Details page allows you to choose a title for the repository and the default initial stream name can be changed. Press <Next> to Finish. The new repository will be the active repository and will appear under the server in the Administration View. After creating the repository you may want to modify the changeset reference. By default, each submitted changeset in the repository will be called '[repos name]/[change number]'. You can change this by right-clicking the repository in the Administration View and selecting 'Properties'.
Getting Started
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 the server, the ID specified here will be appended to it. Table 1.1. Repository Change ID Format Name changes count day changes count stream changes count user name user changes count client stream name stream path day Placeholder $n $N Definition Sequential number of changesets submitted to the repository Sequential number of changesets submitted to the repository that day (usually used in conjunction with $d$m$y) Sequential number of changesets submitted to this stream in the repository Name of the user submitting the changeset Sequential number of changesets submitted to the repository by this user (usually used in conjunction with the above) Name of the machine submitting the changeset Name of the stream to which the changeset is being submitted Path and name of the stream to which the changeset is being submitted DD 9
$t $u $U
$c $s $S $d
Getting Started
Name month month year
Placeholder $m $M $y
Definition MM Month YY
10
Getting Started
Adding Files & Folders
After connecting to the server and creating a new repository you will want to add your files and folders. If you are currently using SourceSafe, Perforce or CVS then PureCM will automatically import your files (with the full history) as described in the section called Import a Repository. If you are starting from scratch then you add your files as follows: 1. Create a workspace as described in the PureCM User Guide. You can create the workspace in a new folder and copy the files you want to add into this folder. Or you can create the workspace in the folder where he files currently exist. Select the workspace and select the 'Add' menu or toolbar button. This will launch the Check Consistency Wizard as described in the User Guide. You can specify which files to include/exclude in the search. When all the files and folders have been added, select the workspace and select the 'Submit' menu or toolbar. Enter a suitable description and select 'Submit' from the changeset toolbar. Submitting a changeset is described in more detail in the User Guide. The files and folders are then added to the stream. If the workspace was only created for adding the first set of files and folders to the stream then it can be deleted.
2.
3.
4.
11
Getting Started
Import a Repository
A repository can be imported from another SCM package: 1. 2. 3. If necessary, create a new repository in PureCM as described above. Right click on the new or an existing repository and select 'Import Repository' from the menu. Select the type of repository to import and follow the on-screen wizard, which will vary according to the type of repository being imported. Note The imported repository will be created as one or more streams within the PureCM repository. These streams can then be merged or otherwise amended as described in the 'Stream Administration' chapter.
12
Getting Started
13
Chapter 2. Stream Administration

About Streams
Streams (aka 'branches') are used to indicate a precise point in the lifecycle of a project. As the options indicate when creating a repository, streams are commonly differentiated 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 project when, for example: a. b. The code was built and the program distributed. The website was uploaded to the internet server.
A stream at this point will allow bug fixes to the current release whilst new development occurs in a separate stream. As detailed later in this chapter, the streams can subsequently be merged. Testing. A stream of this type will be used when a major structural change is being made. If unsuccessful it will not affect the development stream and if successful it can 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 and for any reason. Note If you are setting up PureCM for the first time, a stream will have been created with the repository as described in the section called Creating a Repository.
14
Stream Administration
Creating a Stream
A new stream is usually created from an existing stream. Right click on the stream to use 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 created by 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 a parent. Otherwise check 'Create Stream From' and select the parent stream from the stream tabs as described in the section called Stream Tab Views. Figure 2.2. Stream Wizard - Stream Name and Description
15
Enter a name and description for the new stream. The name and description should be as clear as possible to avoid any confusion in the future, and you may choose to use 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 by using the radio buttons. The browse button <...> allows you to select a previous changeset 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 the stream. See Chapter 8, File Permissions for a full descriptions of file permissions. By default the permissions are inherited from the parent folder. To change the permissions 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 used to 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 stream itself. By default the permissions are inherited from the parent stream. To change the permissions 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 used to change the permissions. When finished press <Next> to continue. Figure 2.6. Stream Wizard - Complete
18
Confirm that the details are correct on the completion page and press <Finish> to create the stream. Note The new stream can now be mapped to a workspace, as outlined in the Client Connection, 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 been successfully merged or the stream was for an unsuccessful test, it can be deleted. Note Delete 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' from the 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 for stream folders is that file and stream permissions can be set from which all child streams can inherit, as described in Chapter 8, File Permissions. When creating the repository the 'Development' and 'Release' stream folders are created by default as described in the section called Creating a Repository. To create a stream folder right click on the parent stream folder and select 'Create new 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 the child stream. See Chapter 8, File Permissions for a full descriptions of file permissions. By default the permissions are inherited from the parent folder. To change the permissions 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 used to change the permissions. When finished press <Next> to continue. Figure 2.10. Stream Folder Wizard - Stream Permissions
23
The Stream Permissions page allows you to specify who can do what to the stream folder and child streams (if they inherit from parent). By default the permissions are inherited from the parent folder. To change the permissions 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 used to change the permissions. When finished press <Next> to continue. Figure 2.11. Stream Folder Wizard - Complete
Confirm that the details are correct on the completion page and press <Finish> to create 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 the streams 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 repository will reveal all root streams and stream folders. Expanding a stream folder will reveal all 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 node and select 'Show Stream Hierarchy' from the menu. This displays the repository at the root and expanding the repository will reveal all component streams. Expanding a stream will reveal all streams created from the expanded stream (i.e. all child streams).
25
Stream Permissions
Permissions can be set to configure who can read, create, move and delete streams/stream folders. The default permissions are set within the Global Properties. These can be changed by right-clicking the server tree item and selecting 'Global Properties...'. These can be overridden within the properties of a repository, stream folder, or stream. The following permissions can be checked or unchecked: Table 2.1. Stream Permissions Permission Read Add Move Delete Folder Add Folder Delete Permissions Definition If checked the user is able to view the stream within the gui If checked the user is able to create streams within the folder [folders only] If checked the user is able to move the stream to a different folder If checked the user is able to delete the stream If checked the user can create stream folders within the folder [folder only] If checked the user is able to delete stream folders [folder only] If checked the user can change the permissions 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 merge paths, which will keep track of which changesets need to be merged or even attempt to 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
Merging
29
Chapter 4. Components
About Stream Components
Components are a great way of managing shared code which is used in many projects. They allow a single copy of the library to be accessed in many placed in your repository but also allow the library to be updated from any of those locations. A component is made from a link between a two folders (usually in two different streams). Any files or folders inside the component folders are shared in the two places. Any changes to a file in one part of the component will be replicated exactly to all 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
Components
31
Chapter 5. Issue Management & Workflow

About Issue Management
The management of issues (enhancements, bug-fixes or anything else requiring a change) 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 affected and 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, will move the issue from one state to another. The definition of these actions will determine 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 must be configured to indicate which issue types must be used. Issue types should therefore be created to cover all the reasons for a changeset e.g. Defect, Enhancement, Documentation etc. It is generally advisable to keep the number of issue types to a minimum to avoid ambiguity over the reason for a changeset when submitting.
32
Issue Management & Workflow
Enabling Issue Management

In order to use issue management in PureCM it must be enabled in the group policysets. Note Please refer to the section called Defining a Policyset for more information.
Enable issue management as follows: 1. 2. 3. 4. 5. 6. Highlight the Policy Admin node. In the list on the right, double click 'Admin Policyset' and select the 'Policies' tab at the top of the page. If 'Issue Administration' is not in the list then press <New> and highlight it in the list. Press <Ok> to return to the Policies page. Double click 'Issue Administration', select the 'Enabled' radio button and press <Ok>. Repeat the above for the 'Issue Use' policy. The 'Issue Use' policy will also need to be enabled in the policyset for the developers themselves (in many cases this will be the 'Default Policyset').
33
Creating an Issue Type
To create a new issue type, right click the 'Issue Admin' node and select 'New Issue Type' from the menu. Figure 5.1. Issue Type Wizard - Name and Description
A new issue can be created by: 1. 2. 3. Using one of the PureCM issue templates as a starting point. Using an existing issue type, from the current or another repository, as the starting point. Creating the issue type from scratch.
This example will use one of the existing templates. Select the appropriate radio button 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
Name issue count all issue count global issue count daily issue count user name user issue count client day month month year field value
Placeholder $n $g $G $N $u $U $c $d $m $M $y $f|field_name|
Definition Sequential number of this type of issue created Sequential number of all issues created within this repository Sequential number of this type of issue created across all repositories Sequential number of issues raised that day (usually used in conjunction with $d$m$y) Name of the user creating the issue Sequential number of issues created by this user (usually used in conjunction with the above) Name of the machine creating the issue DD MM Month YY The initial value of a field. This is useful if you want to specify the reference when creating the issue.
The ID field can be edited directly or use the <Add> button to select from a list of placeholders. 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 the drop down list. Note If the issue was based on an existing issue type, rather than a template, similar pages 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 they can perform during the lifecycle of the issue. For example, the Lead Developers group may be configured to review changes submitted by Developers. Note Please refer to Appendix A, Issue Templates for more information about the standard templates included in PureCM. These template groups must now be mapped to the groups present in your installation. Highlight the template group and use the <Change Mapping> button to make changes. Alternatively, select 'Create New' to create a new group with the same name 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. Note If necessary, any unwanted fields can be removed completely once the issue type 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> to create the new issue type. The new issue type will appear under Issue Admin with options beneath it to specify Fields, States, Actions, State Transition Matrix and Forms, as described in the following sections.
39
Issue Fields
The first step in defining the new issue is to specify the fields that must be completed either when the issue is created or at a later stage in its lifecycle. These fields will then be used on the forms that are completed either when an issue is created or during its lifecycle, as explained later in this chapter. If the issue has been created from an existing template or issue type then the fields will 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 the menu. Figure 5.8. Issue Field Wizard - Details
Enter a name for the field and a label. The label will appear as a description next to the field name and type. Use the drop down box below to select the type of field from the 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 box should be multi-line and set a maximum number of characters. Uses of a text field will usually 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 maximum values. Uses of a number field may include estimated and actual numbers of hours to resolve 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 or unchecked 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 can be 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 issue should 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 type of field being created, press <Next> to continue. Users Field. A users field is similar to a custom field where there is a value for each user and group within PureCM. You can then associate one or more users to an issue using 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 of 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. Note The lifecycle should be defined in such a way that it reflects the processes used by your company. As importantly, it should be straightforward to follow and 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 states will 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 the menu. Figure 5.14. Issue State Wizard - Details
Enter a name for the state and a label. The label will appear as a description next to the state name. The 'Activation Action' is performed when an issue in this state is made active by a user. For example the activation action for 'Raised' might be 'Being Fixed'. In this way when 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 to activate this state. 44
From the list below select an image to be associated with the state (the image will appear 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 to associate an issue in this state with a changeset. For example you might configure the issue setup so that 'Created' issues cannot be active, but when a manager assigns the issue to a developer the issue is 'Being Fixed' which can be active. In general the only issue states that you will want associated with a changeset are those that are work in progress, not an issue that has just been raised, cleared or rejected. Check the 'Accept Changesets' checkbox if the changeset being reviewed should be accepted when the issue goes into this state. See the section called Workflow for a description of workflow. For example you might set the issue state 'Accept' to 'Accept Changesets'. 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> and select the field from the list. The <Delete> button can be used to remove fields. For example 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 each state. For example, you may wish to specify that an issue cannot be cleared without the 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 lifecycle of 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. Note As issue actions are closely tied to issue states, it is important to use a straightforward naming convention so that it is obvious to the developers which action 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 actions will 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 the menu. 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 to the 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 been performed. For instance, a Reject action should result in a Rejected state. Use the second drop down list to determine whether, once the action has been performed, 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 action is performed. For example if the action is to reject the issue then a reason for the rejection may be deemed necessary. The second checkbox is used to indicate if the hours to complete the action must be entered when the action is performed. For example you may want to get developers to enter 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 this action is performed. A typical use for this might be a 'reject' action. See the section called Workflow for a description of workflow. The fourth checkbox should be used if this action can only be performed when associated with a changeset. For example, the 'Fix' action might not make any sense if 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 the issue once the action has been performed. So when a user performs the action, they will 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 assign the issue to a developer. Note If you chose to restrict ownership of the issue to individual users on the previous page, selecting a group at this point will mean that the issue must be assigned to an individual from the selected group and not the group as a whole. Press <Next> to continue. 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 may be 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 to states, and hence the possible lifecycles of an issue. The horizontal axis shows the current state and the vertical axis shows the state after the chosen action. Note If two actions can be used to perform the same state transition, only one will be 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 between states and actions by highlighting a cell in the grid and using the drop down box to select an action.
52
Issue Form Editor

Using the form editor an administrator can customize how an issue will be displayed to the user. To use the form editor select 'Form Editor' in the tree. Figure 5.24. Issue Form Editor
Note With the 'XRC' tab you can modify the form by writing the XRC (xml-based resource language) directly. Sizers The form editor is sizer-base to handle resizing and multiple platforms. All controls must 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 choose from: 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 the number of rows and columns within the properties. You can also specify which columns and rows are 'growable' (i.e. as the issue dialog is resized which rows should be resized accordingly). Note For a more detailed explanation of sizers please refer to the wxWidgets documentation at www.wxwindows.org. Controls To add a control right-click on a sizer or control and select 'Add | Controls'. You can choose 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 an issue 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 allowing text and paragraph formatting. For example the user is able to specify the font, size and color or the alignment of the text. The user can right-click the control to specify the formatting options.
Panel. This will create a panel from which child controls can be added. When created from 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 an issue 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 in the properties. The issue field must be of type custom.
List Control. This will create a list control (single or multiple selection). You can associate this with an issue field in the properties. The issue field must be of type custom.
Button. This will create a button which can be associated with a custom field. When the button is pressed a dialog is launched allowing the user to tick one or more values from the custom field. This is useful if you have a large number of choices, and want to allow the user to select multiple items. In such situations the list control can take up too much space. A better solution might be to add an edit field which is associated with the custom field and then add a '...' button next to the edit control from which uses can select the values. Another advantage of the button control is that the user is able to add, edit and remove custom field values within the button dialog. This is easier than getting an Issue Administrator to edit the Issue Field Properties. A user must have the 'Custom Action Administration' policy enabled to edit these values.
Date Picker. This will create a date picker control. You can associate this with an issue 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 all actions 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 to the 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 only apply to certain controls/sizers (e.g. PureCM). Most of the properties are self explanatory. For more detailed help on an individual property please refer to , the wxWidgets documentation [http://www.wxwindows.org/manuals/2.6.3/wx_sizeroverview.html#sizeroverview].
56
Stream Issue Requirements

PureCM can be configured so that the changesets can only be submitted when associated with one or more active issues. Note Submitted changesets may also be associated with active issues on a voluntary basis, as outlined in the 'Working with Issues' chapter.
To enforce the link between submitted changesets and active issues, right click the stream, select 'Properties' and select the 'Issue Requirements' tab. Unless the requirements are inherited, uncheck the box and press the <Add> button. Select the group 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 issue types which can be associated with a changeset on submission. Repeat for each group or user and press <Ok> when finished. So the example above states that all users belonging to the 'Developers' group will need 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 be submitted when merging a changeset associated with one of these issues. The user is therefore 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 a description of how to merge changes and issues between streams. 57
The second checkbox should be checked if you only accept merged issues when the merge change is fully merged, i.e. all files belonging to the original change are included 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. Note If you will require the issue views to be separated into different folders, create the folders first from the context menu and then create the views within the new 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 be displayed in the view. The complete expression can be as simple or complex as you require. To see how the expression is defined, press the <New> button and use the drop down lists or text boxes to select a criteria. Note The 'Issue Field' and 'Value' will vary according to the way the issue was defined, as described earlier in this chapter. If required, press the <New> button again and select a second criteria. When the second criteria has been specified, 'AND' appears in the AND/OR column. This can be changed by double clicking in the field and selecting 'OR' from the drop down list. In the first case both criteria must be satisfied for the issue to appear in the view and in the 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 define sub-expressions. Double click to the left or right of an expression to access the drop down 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 the issue view. Press <Next> to continue and, where applicable, define the expressions for other issue types. Press <Finish> when completed. Note Once created an issue view can be exported as a CSV file by right clicking on the view and selecting 'Export' from the menu.
60
Workflow
Workflow can be seen as an extension of issue management. Use of workflow adds control over the submitting of changesets to the issue lifecycle (as explained in earlier sections on issue states and actions). Workflow can also be enhanced by the use of scripts to generate event messages. A typical issue using workflow will have a lifecycle that follows the example below: Note This example uses the term 'developer' for those who make the code changes and 'manager' for those who approve the changes. In reality these roles are more likely to be assigned to junior developers and senior developers (or team leaders). See Chapter 6, Users & Groups for a description of how to setup the users and groups. 1. 2. An issue is raised and is assigned by a manager to a developer. The issue is resolved by the developer and, with an associated changeset, is assigned back to the manager for approval. Note that, at this point, the changeset associated with the issue have not been submitted to the repository. The manager may then do one of the following: a. Reject the proposed resolution. In this instance the changeset is not submitted to the server and the issue is reassigned to the developer. Note that the changeset associated with the proposed resolution is not lost if the resolution is rejected. Accept the proposed resolution. The changeset is submitted to the repository and the issue is then cleared.
3.
b.
61
Configuring Workflow
Configuring PureCM for the above example requires two specific settings beyond the standard issue management configuration: 1. The developers must not be able to submit changesets. This involves creating an issue action, and associated state, allowing the developers to '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 have the 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 reject or 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 the managers will be informed when there are proposed issue resolutions and the developers will be informed about the result. Note Please 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 = 'purecm@mycompany.com' SUBJECT = '%s has been assigned to you' % (issue) MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, 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 = 'purecm@mycompany.com' SUBJECT = '%s has been accepted' % (issue) MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, 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 = 'purecm@mycompany.com' SUBJECT = '%s has been rejected' % (issue) MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, 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 = 'purecm@mycompany.com' SUBJECT = '%s has failed submission' % (issue) 64
MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, 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, Policy Administration. The policyset will control the setup and allowed functions for the user or group. Note If a policyset does not exist for a user or group then the default policyset will apply. It is usually easiest to start by creating groups, or amending the existing groups, to reflect the structure within your company. The users can then be created and added to the groups at the same time. Note Where existing groups and users exist, they can be amended by double clicking on them (or right click and select 'Properties' from the menu).
67
Users & Groups
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
68
Users & Groups
If the users are already created, place a tick in the box next to each user you wish to assign to the group. Note If the users are not yet created, they can be assigned to one or more groups during set up. Press <Next> to continue. Figure 6.3. Group Wizard - Complete
69
Users & Groups
Press <Finish> to create the new group. Repeat the above for all the groups required. Note See Chapter 7, Policy Administration for details of creating the policysets for the new groups.
70
Users & Groups
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 cannot connect to the server. Press <Next> to continue. Figure 6.5. User Wizard - Authentication
71
Users & Groups
Select the authentication requirements for the new user and enter the appropriate details. 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 are logged on within the domain, and also enable 'Password Authentication' for when you are not. Press <Next> to continue. Note When using 'Domain Authentication' a user will automatically be created if the 'Auto-Enroll Windows Domain Users' policy is enabled (the default). If you want to use an existing user then you must change the user name to be 'domain/user'. Figure 6.6. User Wizard - Groups
72
Users & Groups
If the groups are already created, place a tick in the box next to each group to which the user should belong. Note If the groups are not yet created, users can be assigned to groups during set up. Press <Next> to continue. Figure 6.7. User Wizard - Complete
73
Users & Groups
Press <Finish> to create the new user. Repeat the above for all the users required. Note See Chapter 7, Policy Administration for details of creating policysets for the new users or 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 a repository, stream, user or group of users The default policyset is created automatically and can never be deleted. Further policysets can be created for a repository, a stream within the repository, a user or a group. The order of precedence for policysets is: User-Stream. A policyset for a specific user, only applying to a specific stream within a specific repository. Group-Stream. A policyset for all users belonging to a specific group, only applying to a specific stream within a specific repository. User-Repository. A policyset for a specific user, applying to all streams within a specific repository. Group-Repository. A policyset for all users belonging to a specific group, applying to 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 all streams within all repositories. Stream. A policyset for all users, only applying to a specific stream within a specific repository. Repository. A policyset for all users, applying to all streams within a specific repository. 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 is also set in a policyset applying to the stream, then the first policy value will be used. Note An administrator can reset all policysets with the 'tdbutil resetpolicies' command. This can be useful in situations where no one has the 'Policy Administrator' policy enabled (e.g. you accidentally delete the administrator user). 'tdbutil' is installed with the server. For help on using tdbutil type 'tdbutil' on a command prompt. You must stop the PureCM service before running tdbutil commands.
76
Policy Administration
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
77
If the policyset is set to apply only to a specific repository then you can select whether it 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 to all 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 next section.
79
Defining a Policyset
To define the policies that should apply to a policyset, double click the policyset (or right 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 in what 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 to enable/disable them.
81
List of Policies
The default policyset will contain all the policies, initially with the default values. You can 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). You are then free to add a policy which will override the default policyset. Note The Administration and Setup categories are only available in the default policyset. It does not make sense to override these policies for an individual user or repository. The following policies are available: Table 7.1. General Policies Policy Multiple Checkout Automatic Merge View Archived Changesets View My Changesets View Local Changesets Nonlockable Account Value Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Definition Check out files which are already checked-out by other users Automatically merge when synchronising or submitting a changeset View all previously submitted changesets View pending changesets View local changesets (developers' changesets being tracked on server) Specifies whether the user can be locked. Users are locked after the password expires or the maximum password attempts has been exceeded Ability to lock the stream to prevent other developers submitting changes Ability to perform custom actions Determines whether files are automatically locked when deleted in a workspace
Stream Locking Custom Action User Lock Files on Delete
Enabled or Disabled Enabled or Disabled Enabled or Disabled
82
Table 7.2. Administration Policy User Administration Policy Administration Repository Administration Event Administration Backup Administration Connection Administration License Administration Value Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Definition Create, amend or delete users and groups Create, amend or delete policysets Create, amend or delete repositories View the event log Start and end backups, and truncate logs View the connections list Add, modify or remove license keys
Table 7.3. Repository Admin Policy File Type Administration Changeset Administration Script Administration Custom Action Administrator File Lock Administration Value Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Enabled or Disabled Definition Create, amend or delete the default file types Delete local changesets (developers' changesets being tracked on server) and shelvesets Create, amend or delete scripts Ability to create/edit/delete custom actions and properties Allow stream file locks to be removed
Table 7.4. Setup
83
Policy Connection IP Range Stored Log Backups Auto-Enroll Windows Domain Users Auto-Enroll Certificate Users Audit User Logins Address Deny Mask Address Allow Mask Retained Snapshots Maximum Password Attempts Password Expiry Days Automatic Log Truncation SSL/TLS Connections only Enable Python Scripting
Value IP address range Number Enabled or Disabled Enabled or Disabled Enabled or Disabled IP address range IP address range Number Number
Definition Valid IP address range for a successful connection (see IP format note below) Number of old database log backups to be kept before automatic deletion Windows authentication users will automatically be added as users Certificate authentication users will automatically be added as users Write audit messages for every login IP address range from which access is denied (see IP format note below) IP address range from which access is allowed (see IP format note below) Number of old snapshots to be kept before automatic deletion Number of incorrect password attempts until the user is locked Number of days until the password expires and the user is locked Automatically truncate the database log Only allow SSL/TLS connections This policy must be enabled in the default policyset to enable the Python triggers
Number Enabled or Disabled Enabled or Disabled Enabled or Disabled
Note The ip format uses the internet standard. For example if I wanted to deny all ip addresses 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 must always specify a valid ip address (i.e. I need to specify 10.4.0.0 even though I'm only interested in 10.4) and that the number after the slash refers to the number of bits of the ip address to use (8 for the first number, 16 for the first two, 24 for the first three and 32 for the complete ip address). So if there was a 84
Policy Administration specific ip address I wanted to deny I would type '10.0.0.4/32'. Table 7.5. Stream Policy SCC Status Paths Ignore File Paths Track Changes on Server Value File specifications File specifications Enabled or Disabled Definition Allows new extensions to be added to the source code control interface Specify file specifications to be ignored by PureCM Developer file changes are tracked on the server as a local changeset
Table 7.6. General Professional Policy Proxy Referral Configuration Merge Path Administration Enable Merge Paths Enable Reports Value String Enabled or Disabled Enabled or Disabled Enabled or Disabled Definition Specify how to refer clients to proxies local to them Users with this policy are able to create/modify/delete merge paths Users with this policy can use merge paths (i.e. the Merging View is available) Users with this policy can use report (i.e. the Reports View is available)
Table 7.7. Issue Management Policy Issue Administration Issue Use Issue Field Value Administration Value Enabled or Disabled Enabled or Disabled Enabled or Disabled Definition Create, amend or delete issue states, fields, actions and forms Create, amend or delete issues Ability to modify Issue Field Custom Values within the 'Button' Form Control Dialog
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 changed by right-clicking the server tree item and selecting 'Global Properties...'. These can be overridden within the properties of a repository, stream folder, a stream, a folder within a stream or an individual file. Note It is often convenient to create stream permissions for the stream folder and have all streams inherit the permissions from the parent. For example, for the stream folder 'Development' you may specify that all 'Developers' can edit files. For the stream folder 'Release' however you may specify that only 'Lead Developers' are able to edit files. All streams within these folders will therefore inherit 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 Read Definition If checked the user is able to read files and the files will be downloaded on update If checked the user can add new files If checked the user can edit files If checked the user can rename files If checked the user can delete files If checked the user can add folders If checked the user can delete folders If checked the user can rename folders If checked the user can change the permissions
Add Edit Rename Delete Folder Add Folder Delete Folder Rename Permissions
87
File Permissions
88
Chapter 9. File Types

About File Types
File types are used as a centralized way in which administrators can change settings for all files of a particular type. For example, an administrator can change the encoding of all files of a particular type. The change will then be applied to each user when they next update their workspace. Each file belongs to one file type. The file type of a file can be changed by any user able to edit the file, as described in the Add, Edit & Submit section of the PureCM User Guide.
89
File Types
Creating, Editing and Deleting File Types

To create a new file type or edit an existing file type you must have the 'File Type Administration' policy enabled, as described in the section called Defining a Policyset. To create a new global file type, right click the 'File Types' tree item under the server tree 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 the repository tree item and select the 'New' menu. This file types will only apply to this repository. Note If 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 useful where you have a repository with a special case. For example, you might generally want 'text/plain' files to be Ascii encoding, so a global 'text/plain' file type will be created with Ascii encoding. You might, however, have a particular repository where you want the encoding to be 'UTF-8'. So you will create a repository 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
90
File Types
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 the Client 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 is first added to the server. So in the example above, all files with the cpp extension will default to use the file type 'text/c++'. The default file type can be overridden by the user when adding the file as described in the Add, Edit & Submit section of the PureCM 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
91
File Types
Check the flags you want to enable for files belonging to this file type. See the section called 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 all files belonging to the 'text/c++' file type will be encoded as Ascii when downloaded by a user into a workspace as described in the Client Connection, Update to Latest section of the PureCM User Guide. To delete file types select them in the list and right-click 'Delete'. You cannot delete base file types. Base file types are used by PureCM as a fall back if a more specific file type cannot be found. The list of base file types includes 'text/plain', 'text/utf-8', 'text/utf-16' and 'application/generic'.
92
File Types
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 $Revision:$ $Date:$ $ID:$ $NoKeywords:$ Expanded To The revision of the file The date this revision was submitted A unique id for this file revision in this stream Any following keywords will not be expanded
Note If 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 is disabled then all checked-in files will be read-only, unless otherwise specified when creating the workspace (see the Client Connection, Create the Workspace section of the 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 and they are connected to the server. See Chapter 10, File Locking for a description of file locks. This is useful when concurrent development doesn't make sense for certain files, so the file is automatically locked preventing 2 users from checking the file out simultaneously. For example, you might disable this for 'text/c++' files where changes can be merged, but you might enable it for 'image/generic' files where changes cannot be merged. Restore Modification Time This is used to determine the modification times of the files when they are downloaded to the user as described in the Client Connection, Update to Latest section of the PureCM User Guide. If enabled, the modification time will match the date and time of when the file was last submitted. If not enabled, the modification time 93
File Types
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 matches any file type extensions. If this is unchecked, PureCM will read the file to determine the encoding of the file. If the 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 file type 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 not required then the flag should be enabled.
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 is described in the section called Mandatory File Locking. Set the 'Automatically lock when checking out' flag on the file type. This will warn the user when attempting to edit a file which someone else has locked. The user will 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. Let the user manually lock a file. Other users will not be able to submit a change to the file until then lock has been released. This is described in the section called Manual File Locking. Let the user lock the stream. Other users will not be able to submit any changes to the stream until the lock has been released. This is described in the section called Stream Locking.
2.
3.
4.
96
File Locking
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 user attempts to edit the file he/she will be unable to 'checkout' the file until the lock has been released. The advantage of this is that the user will never have to merge another user's changes with their own. The disadvantage is that users will be unable to work on a file while another user is working on the file. Note Users without the 'Multiple Checkouts' policy set will be unable to checkout and delete files when not connected to the server.
97
File Locking
Automatic File Locking

If you don't want to encourage concurrent development on files belonging to a file type then the 'Automatically Lock when Checking Out' flag should be set as described in the section called File Type Flags. When a user edits a file the file will be automatically locked. When another user attempts 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 been released. This is useful for file types where merging is not supported. An example might be image files, which would belong to the 'image/generic' file type.
98
File Locking
Manual File Locking

If there is a particular situation where a user does not want other users to edit a file then the user can select the 'All Tasks | Lock' menu on the file. When another user attempts 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 been released. This is useful if a user is dramatically restructuring a file and therefore doesn't want to merge other edits when finished.
99
File Locking
Stream Locking
If a user wants to prevent other users making any changes to an entire stream the user can lock the stream. To do so right click on the stream and select 'Lock' from the menu. An example of where stream locking might be useful is when submitting changes. In large projects after making some changes the developer may be required to 'Update To Latest' to integrate everyone else's changes. He/she may then be required to run many unit tests and acceptance tests before the changes can be submitted. It would be very frustrating if after doing all this another user had made another submit so the whole procedure needed to be repeated. In this situation the user might lock the stream before the 'Update to Latest' and unlock it after the submit.
100
File Locking
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 be enabled as described in the section called Defining a Policyset. Users can view local changes if they have the 'View Local Changesets' policy enabled. 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 deleted within 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. Note Deleting a local changeset on the server does not actually delete the local changeset within the workspace. The next time the developer 'checks in' or 'checks out' a file the local changeset item will be recreated.
101
File Locking
102
Chapter 11. View Server Connections

About Connections
Connections displays the user name, client and IP address of those accessing the server. When a client disconnects the date and time is displayed. The list displayed can be sorted by clicking on the column headings. Note An IP address range can be specified for connection to the server - see the Policy Administration chapter for further information.
103
View Server Connections
Connection Entries
User Name The name of the user currently connected. Where domain authentication is in use then the format will be 'domain/username', where password authentication is in use then 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.
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 column headings at the top allow the events to be displayed according to type, date, user or description. Note Events are also recorded in the Windows NT Event Viewer (Control Panel -> Administrative Tools -> Computer Management -> System Tools-> Event Viewer -> Application). This allows the events to be reported by remote management tools. Events can be deleted with the ClearEventLog() trigger function as described in the section called PureCM Server Functions.
106
Event Log
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. a changeset 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 latest revision being present.
Fatal Error. Where the cause is not immediately obvious please contact PureCM support for resolution.
107
Event Log
108
Chapter 13. Reporting

About Reports
The PureCM reporting function creates on-screen reports, printouts or documents showing usage of the software, allowing you to accurately monitor individuals or groups. Moreover, trends can be spotted regarding the number and type of issues raised and resources allocated accordingly. PureCM reports are XML-based and customisable with a knowledge of XSLT.
109
Reporting
Creating a New Report

Note The following example is based on the 'Issue List' template and the Parameters page will differ if another template is selected. See the section called 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 using the drop down lists and press <Next> to continue. See the section called General Reports for a summary of the different templates. Figure 13.2. Report Wizard - Details
110
Reporting
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. So if you only wanted to report on 'Cleared' issues you would create an issue view 111
Reporting
filtering on the state 'Cleared' and then select this view. See the section called Issue Views for a full description of issue views. You can choose to select the issue view dynamically before generating the report or for the report to always use the specified view. Figure 13.4. Report Wizard - Parameters
This page will differ depending on which report template you selected. Each template requires different parameters. See the section called General Reports for a summary of the different templates. Each issue type has a corresponding tab along the top. Check the 'Include' checkbox if 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 be represented as a column within the report With a field highlighted on the right the arrow buttons can be used to change the order of the fields. Highlight each issue type in turn, make any required amendments, and press <Next> to continue. Note The <Preview> button can be used to see the report format before continuing. Figure 13.5. Report Wizard - Permissions
112
Reporting
The permissions for the report can be set here. See the section called Report Permissions for a full description of setting report permissions. Figure 13.6. Report Wizard - Complete
Press <Finish> to create the report. Note To make amendments to the report, right click the report and select 113
Reporting 'Properties' from the menu. See the section called Customising a Report for a full description on how to modify a report.
114
Reporting
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 if required. 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 which will be applied to this XML for advanced customizations.
115
Reporting
Creating a Report Folder

Report folders are used to organize you reports. They can also be used to setup the report 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
116
Reporting
Set the permissions for the report or select 'Inherit from Parent'. See the section called Report Permissions for a description of report permissions.
117
Reporting
General Reports
Figure 13.9. General Reports - Changeset
The Changeset report provides a list of submitted changesets. The report can be customized by specify a date range for the submitted changesets and by specifying what 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 118
Reporting
additional changeset items column. The changeset items column displays all files and folders changed within the changeset along with what the change was (Added, Edited or Deleted). Figure 13.11. General Reports - Changeset Items by User
The Changeset Items by User report is the same as the Changeset Items report only listing the changesets submitted by individual users/groups separately. Figure 13.12. General Reports - Release Notes
119
Reporting
The release notes report allows users to compare two streams and show changes made between them. It will list all submitted issues thus creating a Release Notes page. Figure 13.13. General Reports - Changeset Item Release Notes
This type of report lists change items submitted in the target stream which have not been submitted in the base stream. 120
Reporting
Issue Reports
Issue reports can be associated with an issue view to filter the issues reported on. So if you only wanted to report on 'Cleared' defects you would create an issue view which only displayed 'Cleared' defects and associate the report with this view. See the section 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 by specifying what to display within each column. Figure 13.15. Issue Reports - Issue List by User
121
Reporting
The Issue List by User report is the same as the Issue List report, only listing the issues 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 the issues according to what state the issue is in. Figure 13.17. Issue Reports - Issue List by Custom Field
122
Reporting
The Issue List by Custom Field report is the same as the Issue List report, only listing the 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 performed on the issue. The hours taken to perform an action are specified when performing the action, as described in the Working with Issues section of the PureCM User Guide. Figure 13.19. Issue Reports - Issue Action List
123
Reporting
The Issue Action List report provides a list of actions performed. The report can be customized by specifying which actions to report on and what to display within each column. Figure 13.20. Issue Reports - Issue Details
The Issue Details report provides a detailed description of each issue. The report can be customized by specifying which issue fields to include. Figure 13.21. Issue Reports - State Distribution
124
Reporting
The State Distribution report provides a summary of how many issues are in a particular state at a specified time. So the example above shows that at midnight on 28th January there was a total of 2 issues and both issues were cleared. One week later however there was a total of 7 issues (so 5 issues had been created) and 2 of these were live. The report can be customized by first specifying the time interval. The time interval for the 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. Finally the report can be customized by specifying which states to include within each column. 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 a product's life. For example you might expect the number of 'live' issues to significantly reduce when the product is close to completion. Similarly you would expect the number of 'live' issues to increase during a testing period. Figure 13.22. General Reports - Issue Release Notes
125
Reporting
This report will list issues submitted in the target stream which have not been submitted in the base stream.
126
Reporting
Issue Trend Reports

Issue Trend reports are designed to show trends regarding the number and type of issues 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 given time period. So the example above shows that 2 issues were raised and two issues were cleared on the 28th January. The report can be customized by first specifying the time interval. The time interval for the 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. Finally the report can be customized by specifying which actions to include within each column. Figure 13.24. Issue Trend Reports - User Action Trend
127
Reporting
The Issue Action Trend report shows the number of actions performed within a given time period by individual users or groups of users. So the example above shows that Dave fixed two defects/enhancements on 28th January. The report can be customized by first specifying the time interval. The time interval for the 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. The report can be customized by specifying which users and groups to include. Finally the report 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 performing actions within a given time period by individual users or groups of users. So the example above shows that Dave spent 6 hours fixing defects/enhancements on 28th January. The hours taken to perform an action are specified when performing the action, 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 for the 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. The report can be customized by specifying which users and groups to include. Finally the report can be customized by specifying which actions to include.
128
Reporting
Customising a Report
Right click the report and select 'Properties' from the menu to modify the report. See the section called Creating a New Report for details of each page. Note You can easily change the logo on the report by replacing the file 'reportlogo.png' found in the client installation folder (usually \Program Files\PureCM\Client). For some reports you may wish to restrict the report to a particular stream. For example, for a Changeset report you might only want to report on Changesets belonging to a particular stream. Select 'Properties' on the report to specify the report stream. Figure 13.26. Report Properties - Stream
If you want to restrict the report to an individual stream, press the radio button and select the stream from the tree tabs as described in the section called Stream Tab Views. There may however be times when you want to specialize a report specific to your requirements. This can be achieved with a knowledge of XSLT. The easiest way to customize a report is to generate the XML by selecting 'Generate XML to File...'. Select 'Modify XSLT...' and copy this into an .xslt file. Edit the XSLT in an external tool (like XMLSpy) and ensure the generated report is correct. Finally copy the new XSLT into the editor after selecting 'Modify XSLT...'. Note If required, the XML schema file - purecm.xsd - can be found in the client installation folder (usually \Program Files\PureCM\Client). The schema file should not be amended. If a report supports intermediary transformations (e.g. the Trend Reports) then the 129
Reporting
intermediary transformation is first applied to the generated XML, and the default transformation is then applied to this output. To enable intermediary transformations check 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 when generating the report. For performance reasons you should limit the generated xml to what you need.
130
Reporting
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 the repository, report folders and specific reports. Figure 13.28. Report Permissions
The default report permissions are set against the repository and can be modified via the repository properties. By default all root report folders will then inherit the permissions 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 the private folder, except the Administrator. Create a report folder which only certain groups can read. This might be useful where you have reports which you don't want people to read.
131
Reporting
132
Chapter 14. Using Scripts

About Scripts
To enable Python scripting you will need to enable the 'Enable Python Scripting' policy in 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 install the Python programming language as described in the section called Installing Python (Windows). To amend the scripts you will need to enable the 'Script Administration' policy, as described in the section called Defining a Policyset. When this is enabled you will see 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. Note The Python website at www.python.org has links to a whole host of tutorials and user groups. PureCM has one script for the server and one for each repository. Once Python is installed these can be amended as described later in this chapter.
133
Using Scripts
Installing Python (Windows)

PureCM supports versions 2.3, 2.4 and 2.5 of Python which can be downloaded from www.python.org. 1. Once downloaded, double click the executable to begin installation. As with all installations, if not signed on as an Administrator right click on the executable and use 'Run as'. Select a destination folder and press <Next> to continue. Select whether or not to backup replaced files and press <Next> to continue. Ensure all components are checked and press <Next> to continue. Choose a name for the program group and press <Next> to continue. Press <Next> to begin the installation. Press <Finish> when the installation completes. You may be prompted to reboot to complete the installation. This can be left until after the following instructions so press <Cancel>.
2. 3. 4. 5. 6. 7. 8.
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 an Administrator, hold down the Shift key and right click System to access the 'Run as' option). On the 'Advanced' tab press the 'Environment Variables' button. In the lower pane highlight the 'Path' variable and press the 'Edit' button. 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 to separate it from the previous value. Press <Ok> three times to close the System dialogues. Reboot the computer.
2. 3. 4.
5. 6.
When the computer restarts, test that scripting is working in PureCM by editing the server 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 it installed correctly.
134
Using Scripts
2. 3.
At a command prompt run 'path' and check that the Python installation folder is present and correctly specified. Ensure that the 'Enable Python Scripting' policy is enabled in the default policyset and the 'Script Administration' policy is enabled in the current policyset.
135
Using Scripts
Python Server Triggers

The following triggers are available in the server script:
# OnStart is called when the Server starts def OnStart(): return # OnStop is called when the Server stops def OnStop(): return # OnClientConnect is called when a client connects. def OnClientConnect(user,client,ipaddress): return
Return a warning strin
# OnEveryMinute is called every minute and can be used for schedule items def OnEveryMinute(hour,minute): return
# OnEveryQuarterHour is called every 15 minutes and can be used for schedul def OnEveryQuarterHour(hour,minute): return # OnEveryHour is called every hour and can be used for schedule items def OnEveryHour(hour): return
136
Using Scripts
Python Repository Triggers

The following triggers are available in the repository script:
# OnPreSubmitChange is called before submit. Return a warning string to pr def OnPreSubmitChange(stream,change,user,client,comment): return # OnPostSubmitChange is called after a change is submitted def OnPostSubmitChange(stream,change,user,client,comment): return # OnEveryMinute is called every minute and can be used for schedule items def OnEveryMinute(hour,minute): return
# OnEveryQuarterHour is called every 15 minutes and can be used for schedul def OnEveryQuarterHour(hour,minute): return # OnEveryHour is called every hour and can be used for schedule items def OnEveryHour(hour): return
# OnReviewAssigned is called when a change is assigned to one or more users def OnReviewAssigned(review,email,description,issue): return # OnReviewAccepted is called after a change review has been accepted def OnReviewAccepted(review,user,email,comments,issue): return # OnReviewRejected is called after a change review has been rejected def OnReviewRejected(review,user,email,reason,issue): return
# OnReviewFailure is called after a change review has been accepted but the def OnReviewFailure(review,user,email,reason,issue): return # OnIssueAction is called when an action is being performed on an issue def OnIssueAction(issue,action,user,email,description): return
Note For an example of using repository scripts please refer to the section called Extending Workflow.
137
Using Scripts
PureCM Server Functions

As well as all standard Python functions, PureCM provides some useful utility functions 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. The Days 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 after making a backup to stop the active log file getting too big. The example below is used to archive the log every night.
def OnEveryHour(hour): if hour == 23: TruncateDatabaseLogs( ) return
138
Using Scripts
PureCM Repository Functions

As well as all standard Python functions, PureCM provides some useful utility functions 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 hourly check 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 = ['Dave@MyCompany.com','Sam@MyCompany.com'] SMTP_SERVER = 'MyServer.MyCompany.com' ADDRESS_FROM = 'purecm@MyCompany.com' SUBJECT = 'purecm database checks (%d errors)' % (results[0]) MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADD 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 referential integrity of the repository database as well as the data structure. This will take considerably longer than PerformDatabaseChecks(). The example below is used to send an email to two recipients following an hourly check of the database.
def OnEveryHour(hour): if hour == 4: results = PerformReposChecks() if results[0] > 0: TEXT = results[1] ADDRESS_TO = ['Dave@MyCompany.com','Sam@MyCompany.com'] SMTP_SERVER = 'MyServer.MyCompany.com' ADDRESS_FROM = 'purecm@MyCompany.com' SUBJECT = 'purecm repository checks (%d errors)' % (results[0 MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADD server = smtplib.SMTP(SMTP_SERVER) 139
Using Scripts
server.login('purecm','secret') server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE) server.quit() return
140
Using Scripts
141
Chapter 15. Backup & Restore

About Backup & Restore
The PureCM database files are stored in the location specified when installing PureCM (typically PureCM\data). The following files will be found in the directory: Table 15.1. PureCM Data Files Name Data File Binary Data File Extension tdf tbf Description Contains all non-binary data Contains all binary data
If you want to backup the PureCM data files using a backup program such as NTBackup on Windows or 'tar' on Unix see the section called Backing Up the PureCM Data Files. Although this is the simplest solution, it is recommended that you create database snapshots and back these up. Snapshots are compressed and therefore take up less space than the actual data files. The PureCM snapshot files are stored in the location specified when installing PureCM (typically PureCM\snapshots). The following files will be found in the directory: Table 15.2. PureCM Snapshot Files Name Snapshot File Extension tds Description A compressed copy of the data files which can be restored
See the section called Create a Snapshot for a description of how to create snapshots. See the section called Restoring a Snapshot for a description of how to restore the snapshot. If the PureCM database you are backing up is large then you typically wouldn't want to create more than one or two snapshots a day. While the snapshots are being created other users cannot use the tool, and the amount of storage required for many snapshots will soon mount up. If you want to perform many backups during the day, a better solution is to backup the log file as described in the section called Applying the Log File. To recover the database you would first recover the snapshot and then apply each log file as described in the section called Applying the Log File. 142
Backup & Restore
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. Any archived log files will be found in the subdirectory 'archive' (e.g. PureCM\logs\archive). Table 15.3. PureCM Log Files Name Log Commands File Log Pre-Image File Extension tlf tpf Description Contains the log of all commands Contains the binary data used by the commands file
143
Backup & Restore
Backing Up the PureCM Data Files

The PureCM directory (typically C:\PureCM) can be backed up using a backup program such as NTBackup on Windows or 'tar' on Unix. If the server is running, you must 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 consistent backup is taken.
144
Backup & Restore
Create a Snapshot
The location of the snapshots was set during the server installation (typically PureCM\snapshots). The number of stored snapshots before the oldest one is deleted is set in the 'Retained Snapshots' policy as described in the section called Defining a Policyset. The snapshots can then be backed up using a backup program such as NTBackup on Windows or 'tar' on Unix. Restoring a snapshot is described in the section called Restoring a Snapshot. Note After 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() server trigger 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 manual backup the user will need to run the make-snapshots command from the command line.
145
Backup & Restore
Restoring a Snapshot
To restore a database snapshot you will need to use the 'tdbutil' utility which will have been 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 repository called 'Test1'. The snapshot file will be called 'r_Test1_1.xml.gz'. In this instance you would type 'tdbutil import r_Test1.xml.gz r_Test1'. This will create the corresponding r_Test1.tdf, r_Test1.tbf, r_Test1.tlf and r_Test1.tpf files. These files should then be copied into the PureCM data directory (typically PureCM\data).
146
Backup & Restore
Archiving the Log File

The location of the log files was set during the server installation (typically PureCM\logs). The number of stored log backups before the oldest one is deleted is set in the 'Stored Log Backups' policy as described in the section called Defining a Policyset. The log files can then be backed up using a backup program such as NTBackup on Windows or 'tar' on Unix. Applying a log file to recreate the database is described in the section called Applying the Log File. Log files can be archived using with the TruncateDatabaseLogs() server trigger function as described in the section called PureCM Server Functions.
147
Backup & Restore
Applying the Log File

To apply the log files you will need to use the 'tdbutil' utility which will have been installed with the server (typically 'Program Files\PureCM\Server'). Open a command prompt in the server executables directory. Type 'tdbutil applylog <database path> <logfile base name>'.
148
Backup & Restore
Resetting Policies
If for any reason you have editted your Policy sets incorrectly ( EG. Disabling 'Policy Admin' from your last policyset then this command will reset all policies, deleting them and recreating the default policyset. To use the command you will need to use the 'tdbutil' utility which will have been installed with server (typically 'Program Files\PureCM\Server'). Open a command prompt in the server executables directory. Type 'tdbutil resetpolicies <server path>'
149
Backup & Restore
150
Chapter 16. Administrator Command Line Tool

General
Much of PureCM's administrator functionality can be performed using the command line 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. If you want to increase the number of concurrent users you will need to purchase a license code from www.purecm.com [http://www.purecm.com/purchase]. You can then create a new license key using the code, as described in the section called Creating a License Key.
153
License Keys
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 code purchased through www.purecm.com [http://www.purecm.com/purchase]. Note The Registered Name must match the name supplied when purchasing the license code. It is recommended that you copy and paste both the 'Registered Name' and 'License Key' values from the email sent by PureCM.
154
License Keys
License Keys Administration

A license key is in one of the following states: Table 17.1. License Key States State Normal Invalid Expired Description The license key is valid The license code is invalid The license key has expired
To delete a license key, right click on the license key and select the 'Delete' menu.
155
License Keys
156
Appendix A. Issue Templates

Defect
Figure A.1. Issue Templates - Defect
157
Issue Templates
Enhancement
Figure A.2. Issue Templates - Enhancement
158
Issue Templates
Simple Defect
Figure A.3. Issue Templates - Simple Defect
159
Issue Templates
Simple Enhancement
Figure A.4. Issue Templates - Simple Enhancement
160
Issue Templates
161

Purecm Admin Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Purecm Admin Guide

Uploaded by

Copyright:

Available Formats

PureCM Administrator Guide

PureCM Administrator Guide

Chapter 1. Getting Started

Working With Views

Figure 1.8. Repository Properties - Change ID Format

Name month month year

Adding Files & Folders

Chapter 2. Stream Administration

Moving or Renaming a Stream

Creating a Stream Folder

Stream Tab Views

Chapter 5. Issue Management & Workflow

Issue Management & Workflow

Enabling Issue Management

Issue Management & Workflow

Creating an Issue Type

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Figure 5.11. Issue Field Wizard - Boolean Properties

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Figure 5.22. Issue Action Wizard - Mandatory Fields

Issue Management & Workflow

Issue State Transition Matrix

Issue Management & Workflow

Issue Form Editor

Issue Management & Workflow

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

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Stream Issue Requirements

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Issue Management & Workflow

Chapter 6. Users & Groups

Users & Groups

Users & Groups

Users & Groups

Users & Groups

Users & Groups

Users & Groups

Users & Groups

Users & Groups