HomeGeneralPrinter Friendly Version

General

General concepts and usability questions

1. FAQs

1.1. What is the Difference between the Standard and Professional Editions?

The Professional Edition contains all the functionality of the Standard Edition plus the following views:

  1. Merge Paths
  2. Issues
  3. Reporting
  4. Projects

If you have a professional license then you can enable these views by enabling the respective policy in the default policyset.

1.2. Is it possible to automate some PureCM operations?

There are various ways in which PureCM operations can be automated.

For simple tasks you can write a Python Script using our Scripts. Within the Scripts you can use our Command Line Client (pcm) to perform operations.

For more complicated operations we recommend you use either our .NET API or Java API. You can define Triggers from which you can perform PureCM operations.

A final way of automating PureCM tasks is to write a script (e.g. Batch Script) which calls our Command Line Client (pcm).

1.3. How do I clean my PC from a previous PureCM installation?

Uninstalling PureCM will never remove any data - it will just remove the executables.

If you want to start afresh with the server you should:

  • Stop the PureCM service
  • Delete your data and logs directories (C:\PureCM\Data & C:\PureCM\Logs by default)
  • Start the PureCM service

This will then create the initial data based on the installed templates (C:\PureCM\Templates).

If you want to start afresh with your clients you should:

  • Open the GUI
  • Open the 'Tools | Options | General' page
  • The workspace database field will show the location of the connection database and all workspace databases:

  • Close all clients (GUI, Visual Studio, Eclipse, etc.)
  • Delete all files within the workspace database directory

The next time you launch the GUI you should see that there are no existing connections to the server. It will launch the 'Register Server Wizard' by default.

2. Repositories

2.1. Can I share code between repositories?

No. It is a core belief in PureCM that repositories are self contained.

If you are working on multiple projects which might require the same code then you should create each project as separate streams within the same repositoy.

2.2. How do I rename a repository?

In the 2009/2 release or later you can rename the repository within the GUI by right-clicking the repository and selecting 'Rename'.

For prior releases you need to follow these instructions...

Renaming a repository will invalidate all existing workspaces.

To delete a repository you need to:

1) Delete the repository in PureCM (note that this will not actually delete the repository files).

2) Stop the PureCM service.

3) Rename the repository database files. For example if you have a repository called 'Example' you will have some files C:\PureCM\Data\r_Exaple.*. You need to rename the 'Example' to the new repository name.

4) Start the PureCM service.

5) Add a new repository in PureCM with the new repository name. This will link to the existing files and everything will work as normal.

2.3. Import a Repository

A repository can be imported from another SCM package:

  1. If necessary, create a new repository in PureCM.
  2. Right click on the new or an existing repository and select 'Import Repository' from the menu.
  3. Select the type of repository to import and follow the on-screen wizard, which will vary according to the type of repository being imported.

 The imported repository will be created as one or more streams within the PureCM repository.

See the links below for the relevant database type.

2.4. Import a Visual SourceSafe database

Path to srcsafe.ini : This is the full path to the srcsafe.ini file in your SourceSafe installation.

Username : The name of the user you wish to use to log on to SourceSafe with. 

Password : The user's password

SourceSafePath : The location within Sourcesafe of your database.

Base Stream Name : Force the name of the base stream to be what you want.

Create Streams for Labels : Do you want to create a new stream for each SourceSafe label that is found?

Assume Shares may be branches : By making this assumption streams will be created for the 'Shares' found.

Check Streams for pinned and shared files : With this set to 'Yes', the pinned version of a file (SourceSafe's way of marking versions as the stable one) is handled as are shared files.

2.5. What is the active repository?

The active repository is a way to simplify navigating and making choices inside PureCM. As most users will only work in a single repository at a time, all workspace tasks are filtered by the active repository.

Changing your active repository

Whether you are working in the PureCM Gui, explorer client or visual studio client you will have access to change your active repository Active Repository Icon

Selecting the relavant option will launch the Select Active Repository Wizard. This will display all of your registered connections as well as all of the repositories stored inside them

Select Active Repository 

3. Streams

3.1. How do I create a label?

PureCM uses the concept of a Stream for both a 'Development Branch' and a 'Label'. So if you want to label a release you should just create a new stream from the development stream. Because PureCM does not copy the files when creating a stream the creation will be instantaneous and will not increase the database size.

To stop other people editing the files within a release stream we recommend you copy the release to a stream folder where the permissions are setup to only give everyone read permission. So for example you could create a stream folder 'Release' where everyone has read permission only. You can set the permissions for a stream folder by right-clicking the folder and selecting 'Properties'.

 

This will prevent anyone from submitting changes to the release. Alternatively you could let 'LeadDevelopers' submit changes, but exclude 'Developers' if this fits with your process.

After creating the release stream, the stream will appear in the development stream's 'Submitted Changesets' to show when the stream was created in relation to when changes were submitted.

 

When you view a file's history the release streams will also appear if you check the 'Show Child Streams' checkbox. So you can see what version went into which release.

3.2. How do I make a release containing only selected issues/changesets?

When we make a release we would like to be able to consider which (solved) issues we want to include. For example, we might want to include one fix, but not yet include some other fix. It's not clear to me how this can be done with PureCM.

It is possible to create a new stream based on an existing one and then hand pick which changes are merged into the new stream.

So you will initially create a release stream and a development stream. Lots of changes get submitted against the development stream. When it is time to create a release you can go the development stream in the GUI, open the 'Submitted Changesets', select the changes you want to merge (note that you can select multiple changes) and right-click 'Merge Changes To'. You then need to select the destination stream (in this case the release stream).

Alterntaively you can select the release stream and select 'Merge Changes'. This will allow you to select the source stream (in this case the development stream) and then select the changes you want to merge. Note that the list of changes available for selection is intelligent. If a change has already been merged then it will not appear in this list. So if you know exactly which changes you want to merge I suggest the first method. Otherwise I suggest this method.

Note that you cannot perform 'Quick Merge' if the base of all files in the changeset are not the same in both streams. In this case you must create a workspace for the destination stream (in this case the release stream). You can then right-click the workspace and select 'Merge Changes'. Like above this will ask you to select the source stream and the changesets from an intelligent list of unmerged changesets. You will then need to submit your merged changes the same as any other submit.

Note that 'Quick Merge' merges each changeset individually, so there is a direct 1-1 mapping. 'Manual Merge' will merge all changesets as one changeset. If this is an issue you can choose to manually merge 1 changeset at a time.

3.3. Is it possible to remove a file in PureCM?

When deleting a file in PureCM, the file data is not deleted. This is so you can reinstate the file at a later date - or even if you just want to look at it.

The only time PureCM will delete the actual file data is if you delete the stream the file belongs to or if you delete the entire repository. So you could create a new stream from the original stream and then delete the original stream - but this will also delete your file history in the original stream.

3.4. Renaming a Stream does not Update my Workspace.

If I create workspace and then rename the stream from which the workspace is based, the workspace stream path is not updated.

The workspace stream identifier will be updated the next time you do an 'Update to Latest' in the workspace.

3.5. Importing, Exporting and organising Streams using .Net or Java API.

Using either PureCM's .net or java API, it is possible to write your own code to export data from a third party system, and import into a PureCM repository.


In our Examples (see the  Examples.zip link), for both java and .net, there is an ExportImport example. This example recreates an existing stream in the same PureCM repository. By using this code as a starting point you could alter the export part to work with a third party system.

So to use the .net example, create a C# Console Application in Visual Studio, add a reference to PureCM.Client and copy the C# files from the ExportImport example, into your project.

 

Alternatively, it is also possible to export an existing stream from a PureCM repository and import to another system. Alter the import part of the ExportImport example to import to your destination system.

 

This example is also a good starting point for writing some code to re-organise your existing PureCM repositories and streams.

 

See the 'Related Pages' below for help with the APIs.

4. Submitting Changesets

4.1. Is it possible for multiple users to submit changes at the same time?

It is not possible for 2 users to submit changes to the same repository at the same time. When a user submits a changeset it creates a lock on many of the repository database tables. So the other user will have to wait until the first submit has finished.

This applies to any operation which requires a database write (e.g. creating a new user). So 2 users would not be able to create a user at the same time. However, one user would be able to create a user while another user submits without any problems. This is because the 2 operations are using different database tables.

4.2. Is there any way to filter the changesets submitted by me?

When you view the submitted changesets of a stream, you can click the 'client' column title, and the list will be grouped into changesets submitted by user - making it easy to see a user's changesets together.

 

Alternatively you can use PureCM's Filter Toolbar to filter the changeset list you for. You can change the filterbar to only filter the 'Client' column so that only changeset submitted by you will be listed.

4.3. Why do some 'Submitted Changesets' appear blue and others gray?

Submitted changesets will appear gray if they were either part of a merge of another changeset or part of a component. Otherwise they will appear blue.

4.4. E0727 Error when Submitting a Changeset

The E0727 error message appears when you try and submit a changeset but the file is not up to date. In this case you need to 'Update to Latest' in the workspace.

4.5. How do I exclude all files of a particular type (e.g. *.o)?

When adding files in PureCM you can specify the include/exclude filter. So you can specify that *.o files are not added to PureCM when you select 'Add' on a workspace folder.

This is the best solution because you are not wasting time adding files to your workspace as controlled files which will never be submitted. However, it is error prone because it relies on the user to specify the correct include/exclude filters.

It is also possible to exlude files via the 'Ignore File Paths' policy. Just add this to your policy set, and specify the file specifications to be ignored by PureCM. Policy sets can be applied to streams, repositories, groups/users or to all.

We therefore recommend you implement both these solutions.

4.6. How do I prevent files in certain directories being added

If you want to prevent certain common temporary or other non-versionable files being added to a PureCM Workspace, you can use the 'Ignore File Paths' policy.

As an administrator, you can access this from the 'Policy Admin' node in the PureCM Client. In the 'Default Policyset' properties, there should already be or you can otherwise add the 'Ignore File Paths' policy. By default this is set to :-

*CVS/*;*.cvsignore;*.vsscc

Which means :-

  1. Ignore anything in a folder ending with CVS.
  2. Ignore any files that end with .cvsignore
  3. Ignore any files that end with .vsscc

If you, for example, you want to ignore all files in a folder beginning with a period (a Unix convention for hidden folders) you could change the policy value to :-

*CVS/*;*.cvsignore;*.vsscc;*/.*/*

After applying this policy it should apply to all user workspace after they next do an 'Update to Latest' (or create a new workspace). You could equally apply different settings to different repositories by creating a custom Policyset for each repository for example.

 

From PureCM 2009-2c onwards, users can automatically create a project specific ignore file path policy when adding a project to PureCM. Any file/folder that has been detected in a workspace location but hasn't been added to PureCM yet appears in red. To exclude this folder from being added or picked up as a change, right click on the folder and select 'Exclude':

 Exclude folder in workspace

This will change the colour of the folder and its content to grey, signalling that the folder is excluded from source control on purpose.

As an administrator, you can check the created policy from the same location as above. Note that it is stream or project specific, based on the stream the workspace was based on.

 Created ignore file path policy

As before, this policy it should apply to all user workspace after they next do an 'Update to Latest' (or create a new workspace). To add the folder at a later point in time, simply delete the policy.

 

4.7. Can I change the changeset description after it has been submitted?

You can change the description for a Submitted Changeset provided you have the 'Changeset Administration' policy enabled.

In the GUI expand the relevant stream to see the 'Submitted Changesets' tree item. Open this to launch the Changeset Dialog with the change details. You can now enter a new description in the 'Description' edit field and press the 'Save' button.

 

Note that this will not update the description for workspaces which have already been created. The workspace 'Integrated Changesets' description will remain the same. But if you create a new workspace, or look at the Submitted Changeset on the server the description will be different.

5. Merging Changesets

5.1. How do I merge changesets from one stream to another

There are several available approaches to merging between streams with PureCM. The Merging Perspective is a central location where users can quickly perform merging tasks between all streams. Here you can also create Merge Paths to automate the merging process.

Previous versions of the tool had a concept of 'Quick merging'. This enabled direct stream merging, but only if the base of all files was the same in both streams. Now, this concept has been expanded, and conflicting merges are now handled using the 'Resolve' tool.

If you prefer to test any changes prior to merging to a stream, then Workspace Merging provides this capability. Workspace Merge requires a workspace for the stream you are merging into. In this case you select the changesets you want to merge and this applies the changes to 'My Changes'. You then submit the changes the same as any other changeset. An advantage with this method is you can merge multiple changesets as one changeset - if this is important. The obvious disadvantage is that it requires a workspace for the destination stream and involves more work.

5.2. Merging Perspective

The new Merging Perspective provides a central location where users can easily see which changesets have been merged between streams as well being able to carry out required merges. From here users can create new merge paths and see all existing ones. The 'Merge Path Administration' policy is required for users to use merge paths.

Merge Paths

The 'My Pending Merges' shows only the pending merges that were submited by the current user. This facility does not require the 'Merge Path Administration' policy to be set. The pending changesets can be merged from here by right clicking and selecting 'Merge Changes'.

'All Pending Merges' is a convenient way for all of the pending merges for all paths to be accessible from one place. Again the pending changesets can be merged from here.

You can choose to perform one off merges form the Merging perspective by clicking the 'Launch Merge Wizard button'.  This launches the Merge Wizard, allowing the source and destination streams to be selected.

5.3. Merge Rules

Merge Rules allow for the organisation and automation of merging between many streams. Each consists of a source stream, a destination stream and some options about automation. 

A merge rule is made up of 4 nodes:

Merged Changesets – Here you can see which changes have been merged from the source stream to the destination stream.

Pending Changesets – Changes that have failed the quick merge process will end up here, allowing you to carry out a full merge, resolving any conflicts. Changesets can be moved here directly, from ‘Unchanged Changesets’ or all changesets could be moved here for certain types of merge rules. There's an option that forces all changes to become pending for the rule. So for example if you have created a child stream and you know you want all the changes that will be submitted to the parent then it makes sense to make all the changesets pending.

Unmerged Changesets – All changes that have been submitted to the source stream, but have not yet been merged to the destination stream are shown here, with functionality to carry out the merge, move to pending, or move to excluded.

Excluded Changesets – When a changeset should not be merged to the destination stream, it can be placed here, helping other users to avoid performing unwanted merges.

Creating the Merge Rule..

 

Automatic merging optionally takes place when changes are submitted to a stream. So for example, if multiple feature streams exist that are based on one ‘main’ stream, and it is important that these streams are kept up to date with Main, then a merge rule could be created for each of these (in fact such a merge rule is created automatically when creating a 'feature' in PureCM Professional 2010-1 and newer).

This would result in the submitted changes being merged to the other streams at the time of the submit. If the quick merge fails due to conflicts, the changesets would then appear under the Merge Path node as a pending change. Select the 'Make submitted changesets pending' option to force submits to go directly to 'pending' instead of trying to merge them.

5.4. Automatic Merge Rule Creation

It is possible for Merge Rules to be created automatically when a new stream (which is based on another stream) is created. This is defined in the Stream folder that the new stream belongs to.

Note: From PureCM Professional 2010-1 onwards, PureCM automatically creates merge rules from parent to child versions and from the parent version to a feature.

To customise these settings, navigate to the properties of the stream folder in the Administration view and open up the 'Merge Rules' page ..

 

Merge Rules can be created (both ways) between the parent stream and the new stream. The same options available when manually creating a merge rule are available here.

All streams ( of type 'Create from stream..') added in this folder will have merge rules automatically created, based on the selected options on this page.

5.5. Stream Pending Merges

As well as using the Merging Perspective to merge any pending changesets to a target stream, you can navigate to the target stream, in the Streams perspective, locate the 'Pending Merges' node, and perform a merge of any outstanding changesets there..

Simply right click the changeset and select 'Merge Change'. This will merge the changeset directly into the stream, providing the opportunity to resolve any conflicts if necessary.

5.6. What is 'Quick Merge'?

Quick Merge allows you to merge changesets from one stream to another in the easiest and most convenient way possible.

Prior to 2009/1, Quick Merge will only work if the base of all files is the same in both streams. For example suppose you have streams Version1 and Version2 with the same version of file1.txt. Within Version1 you submit an edit to file1.txt in change1 and edit it again in change2. You will be able to Quick Merge change1 because file1.txt is the same in Version2 and the base of change1. You will not be able to Quick Merge change2 because file1.txt is different in Version2 and the base of change2 (it will have the change1 edit in the base of change2). The Quick Merge will fail with warning W0213:

 

You will be able to Quick Merge change1 and change2 together because Quick Merge will merge each change in chronological order when selecting multiple changes.

Prior to 2009/1, if the bases of a file do not match then you will need to perform a Workspace Merge.

There are 2 ways of performing Quick Merge using the GUI. The first way is to list the submitted changes for the source stream (the stream you are merging from). You can then select the changesets you want to merge and right-click 'Merge Changes To'.

This will launch the Stream Selection Dialog allowing you to select the stream you want to merge the changesets into.

 

After selecting the destination stream you will recieve the N0001 notification message for each changeset which was successfully merged.

For each changeset which was not successfully merged you will recieve the W0213 warning and the merge will fail.

You can also Quick Merge by right-clicking the destination stream (the stream you want to merge into) and select 'Merge Changes'. This will launch a wizard asking you to select the source stream (the stream you want to merge from) and check any changes you want to merge.

Note that you can view the changeset by double-clicking on it. This will launch the changeset dialog showing the adds, edits, deletes, etc.

 

5.7. What is 'Workspace Merge'?

Workspace Merge might be preferable because you update a workspace first and then submit the merge. So it gives you the chance to check the merge compiles, passes any automated tests and make any necessary changes before submitting.

To perform a workspace merge you need to right-click a workspace for the stream you want to merge into and select 'Merge Changes'. This will launch the Merge Wizard where you will first select the source stream (the stream you are merging from).

After selecting the source stream you will be asked whether you want to merge all changesets, selected changesets or to remerge selected changesets.

If you select to 'Merge All Changesets' and press Finish all changesets from the source stream will be merged into the workspace as a single changeset. If you select to 'Merge Selected Changesets' you will be presented with a list of changesets.

The list of changesets will not include changesets which have already been merged - PureCM keeps track of what has been merged where. You can double-click a changeset to open it's Changeset Dialog. Tick the changesets you want to merge and press Finish.

After pressing Finish all merged files will be checked out in the selected workspace. When you are satisfied with the merge you can submit it the same as any other changeset.

5.8. How to apply changes to non-conflicting file edits when merging

There are times when you are merging an edit to a file, but you need to modify the edit. For example, suppose you had versions 1 and 2 of a product (V1 and V2) both with a method M1.

In V2 you change the signature for M1 so it takes in an extra argument.

In V1 you make a call to M1 within another method. You then want to merge this change into V2. The problem is that you need to modify the new call to M1 to include the extra argument.

Prior to the 2009/2 release you would need to perform the merge within a workspace. After merging the changeset you can edit the file to add the new argument and then submit the file.

In 2009/2 we introduced the ability to launch the Resolve Tool for all file edits. To do this merge the changeset as normal and selecting for PureCM to NOT automatically merge the changeset. This will launch the changeset dialog and clicking on the file will show the edits made in V1.

You can now right-click on the file and select 'Resolve Interactively'. This will launch the Resolve Tool which should be familiar. You can double-click either side to use those changes, or we can hand edit the bottom pane. In this case I will add the new argument in the bottom pane.

When I have completed the edits for this file, I press the Save button. I am then taken back to the changeset dialog where I can see my changes have been applied.

After I have checked all the other files, I can save the Changeset Dialog. This will apply these changes to the server the same as any other merge.

 

5.9. Can I merge multiple changesets as a single changeset?

Yes. You have always been able to do this with workspace merge:

  • Create a workspace for the stream you want to merge the changesets into.
  • Right-click the workspace in the tree and select 'Merge Changes'.
  • After selecting the source stream you can choose to either 'Merge all changesets' or 'Merge selected changesets'.
  • If you choose to 'Merge all changesets' then all changesets which have not already been merged into the workspace stream will be merged into your workspace as a local changeset. The description will include all the descriptions of the changesets you are merging.
  • If you choose to 'Merge selected changesets' then you can choose which changesets you want to merge by checking them. Note that we only advise this when the merges are trivial. Merging non-consecutive changesets with complex changes can become very complicated and result in partially merged changesets. The selected changesets will be merged into your workspace as a local changeset.
  • You then need to submit the local changeset the same as any other submit.

With the 2009/2 release we also introduced the ability to merge multiple changesets directly on the server - without needing a workspace.

Simply go to a stream's 'Submitted Changesets', select the changes you want to merge and select 'Merge Changes To'. You will then be asked if you want to preview the changeset. If you do not preview the merge then PureCM will merge each changeset individually. If you select to preview the merge then all the changesets will be grouped together as one changeset which you will preview and potentially resolve any conflicts.

Alternatively you can right-click the destination stream and select 'Merge Changes'. This will prompt for the source stream and then allow you select one or more changeset. The same as before this will ask whether you want to preview the merge. If you do not preview the merge then each changeset will be merged individually. If you preview the merge then the preview will contain all the changes as one.

A final way of performing this is with merge paths. You can select 'Pending Changesets' or 'Unmerged Changesets'. This will follow the same logic where you should preview the merge if you want it to bulk merge the changesets.

5.10. I get W0207 when I try and merge a changeset

You can only 'Quick Merge' a changeset when all the files are the same in both the source and destination streams. So if you have StreamA, create StreamB, and submit ChangeB1 to StreamB. In this case you will be able to 'Quick Merge' ChangeB1 to StreamA. But if you submit ChangeA1 to StreamA which modifies the same files as ChangeB1 in StreamB then the merge will fail with the warning W0207.

In this case you must perform a manual merge. Create a workspace for the destination stream and select 'Merge Changes'.

5.11. What are 'Partially Integrated Changesets'?

When merging changes using Quick Merge or Workspace Merge you are asked to select the changesets you want to merge. Typically these changesets will have the status 'Not Integrated' - meaning the changeset has not been merged into the destination stream. Sometimes a changeset will have the status 'Partially Integrated'.

Partially Integrated means that some of the file changes within the changeset have been merged but some of the file changes have not. For example, suppose I submit a changeset (change1) in my Version1 stream with changes to file1.txt and file2.txt. If I perform a workspace merge in my Version2 workspace, change1 appears as 'Not Integrated'. After selecting change1 in the Workspace Merge Wizard the 2 files are checked out and the edits applied in my workspace. I then decide that the changes in file2.txt do not apply to the Version2 stream so I revert file2.txt. I submit the changes to file1.txt in my Version2 workspace.

If I perform a workspace merge in my Version2 workspace, change1 now appears as 'Partially Integrated'. After selecting change1 in the Workspace Merge Wizard only file2.txt is checked out and the edits applied - because the file1.txt changes have already been merged. In this case if I want to get rid of the 'Partially Integrated' status - so change1 does not appear in the list at all - I should go the file history, restore the file back to its previous revision (so it is checked out without any changes) and submit the empty edit.

The 'Partially Integrated' status often appears when the changeset contains edits to files which do not appear in the destination stream. So in the example above if the Version2 stream did not contain the file file2.txt, then change1 will always appear as partially integrated.

It is typical practice therefore to ignore the changesets which are 'Partially Integrated' when selecting which changesets to merge. It generally means that the changeset has already been merged - but for one reason or another the merge did not include all file changes.

5.12. 'Enable Baseless Merges' Option

When merging one or more changesets within a workspace one of the options is to 'Enable Baseless Merges'.

 

'Enable Baseless Merges' is a workaround for the situation where the same file has been added in 2 streams without a merge. So for example, in stream Version1 a developer adds the file File1.txt and submits the add. To get the file into Version2 a user should merge the submitted changeset. However, suppose the developer does not know how PureCM works and wants the file in Version2. The developer copies the file from the Version1 workspace into the Version2 workspace and submits it as a file add. As far as PureCM is concerned these files are completely unrelated - they just happen to share the same name. The developer then submits an edit to the file in Version1 and wants to merge this edit into Version2. Attempting to merge this edit will error with the message:

This is correct because PureCM is saying that it can't merge an edit to a file which has not been added. In order to resolve this issue a developer needs to tell PureCM that file.txt in Version1 is related to file1.txt in Version2.

To do this you must merge the original changeset which added file1.txt into a Version2 workspace and check the 'Enable Baseless Merge' option. This will then bring up the Resolve tool allowing you to select the Version1 revision or Version2 revision. After this merge has been submitted in Version2 PureCM knows that the files are related and you can merge the edit changeset without any problems.

5.13. 'Attempt to Merge Non-Consecutive Revisions' Option

When merging one or more changesets within a workspace one of the options is to 'Attempt to merge non-consecutive revisions'.

This option applies when you are trying to merge multiple changesets, which includes two revisions of a file which are not consecutive. This option is not applicable if you are merging an individual changeset, all changesets, or consecutive changesets.

For example, you submit the add of file1.txt in change1, you submit an edit to file1.txt in change2, and another edit to file1.txt in change3. Within a workspace you then try and merge change1 and change3 into a child stream. Without this option checked the merge will fail with warning W0143.

If the edits in change2 and change3 are on different lines and the 'merge non-consecutive revisions' option is checked then the merge will succeed. PureCM will automatically merge the two changesets and allow you to resolve this merge with your local version of the file in the Resolve tool. If the edits in change2 and change3 are on the same line then merge will still fail with W0143. In this case you need to merge change1 and change3 as separate changesets.

5.14. 'Allow Merge Conflicts in Base' Option

When merging one or more changesets within a workspace one of the options is to 'Allow merge conflicts in base'.

This option relates to merging non-consecutive revisions. As an example suppose you are merging non-consecutive revisions. You add file1.txt in change1 and edit the same line in change2 and change3. You tick the 'Attempt to merge non-consecutive revisions' option and attempt to merge change1 and change3. This will fail with W0143 as described in the non-consecutive revisions article.

However, if you tick the 'Allow merge conflicts in base' option the merge will succeed. If this option is checked then PureCM will use the change3 version of file1.txt as the server file in the Resolve Tool. This may not be what you want, because you have effectively merged the change2 edit.

Note that we do not recommend merging non-consecutive changes. We believe it is better to keep merging simple. If possible you should therefore merge individual changes using Quick Merge.

6. Rolling Back a Changeset

6.1. How do I rollback/revert a changeset which has already been submitted?

There are 2 ways to rollback a changeset.

The first way is using a workspace:

  • Create a workspace for the stream in which the changeset was submitted.
  • Right-click the changeset you want to rollback in the 'Submitted Changesets' list.
  • Select 'Rollback Changeset'.
  • This will launch the Resolve Tool where you can preview the rollback and resolve any potential conflicts.
  • After saving the Resolve Tool a local changeset will be created containing the rolled backed changes.
  • You then submit the local changeset the same as any other.

In the 2009/2 release we introduced the ability to rollback a changeset directly on the server - without needing to create a workspace:

  • In the 'Repository' view expand the stream and find the changeset under 'Submitted Changesets'. Right-click the changeset and select 'Rollback'.
  • This will launch the Resolve Tool where you can preview the rollback and resolve any potential conflicts.
  • After saving the changes will be applied to the server and a new changeset will have been submitted.

6.2. After rolling back a changeset is it deleted from the Submitted Changesets audit trail?

No. The Original Submitted Changeset will still appear in the Submitted Changesets list.

The rollback will create a new changeset containing the reverse edits. This ensures that the history of the stream is not compromised.

7. File History

7.1. Will the file history remain after a file is moved?

Yes. Moving a file will create a new version of the file which can be viewed with all previous versions of the file.

8. File Locking

8.1. Why is this file locked by me?

There are four ways in which a file can be locked:

1) If you disable the 'Multi Checkout' policy then whenever a file is checked out it is locked (this is to stop two people changing the same file at the same time).

2) If the file type has the 'Automatically Lock when Checking Out' checked then the file will lock whenever the file is checked out. So for example it does not make sense for 2 people to edit the same binary file at the same time.

3) A developer who has checked out a file in a workspace can right-click and select 'Advanced | Lock'. You would typically do this if you were restructuring a file and wanted to stop other people making changes temporarily.

4) A developer has deleted a file within a workspace and the 'Lock Files on Delete' policy is enabled (this is the default).

8.2. How do I unlock a file which is locked?

The lock should always be removed when you submit a changeset, revert the file or delete the workspace. There are however occassions where you want to manually remove the lock on a file. For example a developer may have locked a bunch of files before going on vacation for 2 weeks!

To manually remove the locks you need to have the 'File Lock Adminstration' policy enabled.

Using the GUI navigate to the relevant stream and expand the 'Current Changesets' node. This shows which files
are currently being changed by which developers. There should be a current changeset containing the file lock. You need to delete this current changeset by right-clicking and selecting 'Delete'.

 

Alternatively you can navigate to a specific file in the stream, right-click and select 'Unlock'.

 

This will remove the lock for this particular file but not the other files in that developer's current changeset.

8.3. If I manually remove a lock is the file reverted in the developer's workspace?

No. If you delete a current changeset item (which is required to manually remove a lock) the file is not reverted. The server will no longer know that this file is being changed in this workspace, but the file will remain checked-out. Other workspaces will see that the file is no longer locked (or even checked out).

8.4. Force workspace file lock removal

If you encounter problems with file locking in your workspace where you find that a file is locked but you can't find the associated 'Current Changeset' in the Stream, please contact us by submitting a request. We believe all such problems are now fixed but would appreciate hearing about any future problems.

You can override such problems using 'pcm admin reset-locks' on the command line.

8.5. Why can I not checkout a file offline?

If you have the 'Multiple Checkout' policy disabled then you cannot checkout a file offline (i.e. when disconnected from the server). If PureCM allowed this then multiple users would be able to checkout the same file, if either of them was working offline.

If you want file locking but also want the ability to work offline then you should enable the 'Multiple Checkout' policy. You should then go through each file type and enable the 'Automatically Lock When Checking Out' flag.

9. Components

9.1. What are Components?

Components 

Components are a great way of managing shared code which is used in many projects. They allow a single copy of a code library to be viewed and modified in many places in your repository.

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.

9.2. Why would I use components?

If you have a library or collection of code that is used in many different places, whether you have an internal code library that is used in many of your projects or you use a third party library, components can greatly reduce your daily workload while also making the administration of these shared libraries very simple.

 

Components provide many administrative advantages when maintaining these shared code libraries over simply having multiple copies of them spread throughout your system and submitting any changes in multiple places.

  • Firstly a component takes up less space on the server as each linked folder references the same file data in the PureCM database.
  • Components are also very easy to set up allowing you to create in seconds a link to your library in a new location in the project.
  • Components are managed directly on the server meaning administrators do not need to worry about creating workspace to manage components.
  • Components provide greater visibility as to which project is using each version of your code library. This makes it easier to see what projects will be affected when changes are made.
  • Any changes made to a library are instantly made in all linked folders so you no longer need to worry about whether a change or a fix has been made to all of the projects that need it. This also saves a lot of time over having to submit the same changes multiple times.
  • Upgrading your project to use a later version of a library is also made extremely simple as you can instantly swap each component to point at the latest stable version.

9.3. Manage Components Dialog

The Manage Component Dialog is the easiest way to view and modify components on a specific stream.

You can open the manage component dialog by right clicking on a stream and selecting 'Manage' from the 'Components' sub menu.

 

Manage Component Menu

 

This will open the manage component dialog as either a tab or a window (depending on your choice in the main options menu)

 

Manage Component Dialog

 

This will show you a list of all of the current components in this stream. The example above shows a component in the folder 'Lib1' which is linked to the root folder of the Shared Libraries/Releases/Lib1 v1' stream. Each component can be expanded to show a tree view of the components that this folder links to. For more information on this see the 'Expanding component items while Managing Components'.

 

You also get 3 options in the toolbar.

Add Component will let you add a new component to this stream. For more information see the 'How do I add a new component?' article.

Delete Component will let you delete the selected component.  This can either completely remove the the component link and the files in this stream or it can be used to break the link between the two folders.

Update Component will let you change which folder the current component folder is linked to. For more information see the 'How do I update a component?' article'.

9.4. Expanding component items while Managing Components

The manage component dialog provides a list of all component links that directly access the selected stream. However each component item can also be expanded to show which components that folder is linked with.

 

Manage Component

 

The example above shows the component links for the 'Release/1.8.2' stream. There is only one component in this stream, the folder 'Lib1' is linked with the root folder of the stream 'Shared Libraries/Releases/Lib1 v1'. When you expand this top level node you are given a child node that represents this link. This node represents the folder that the top level component is linked to.

This folder (the root of the stream 'Shared Libraries/Releases/Lib1 v1') is linked to two more folders. These links are to the 'Lib1' folder in the 'Release/1.8.1' and the 'Release/1.8.0' streams. This is demonstrated when you expand this node (as shown in the picture above) by two child nodes.

 

The first major advantage this gives is it allows you to see which other folders are linked to your folder and what component links are used to achieve this.

 

Component Links

 

In the example above the main stream has two components pointing at the same stream 'Shared Libraries/Releases/Lib1 v1'. The first points to the folder 'Folder2' and the second points to the folder 'Folder2/Folder3' which is a subfolder of the first component. When the links are expanded we see how these links are visualised.

This component is linked to 'Folder2' inside the 'Shared Libraries/Releases/Lib1 v1' stream, which in turn is linked to four other folders.

Three of these are the components shown earlier which all link to the root of the 'Shared Libraries/Releases/Lib1 v1' stream. As these components are greater than the link (that it is linked with more that just the folder of the component we are viewing) it is given a green component icon.

The other component link is to the second component in the 'Development/Main' stream which is linked to a subfolder of this component. As this component is less than the link (that it is only a part of the component folder we are looking at) is it given a yellow component icon.

All exact links are given blue icons.

 

The second advantage the links give you is that you can modify linked components without having to open the component dialog for their stream. A way this can be very useful is updating components to use a new version of a library from the component dialog of the old version. This makes it a lot quicker as all of the components linked to the old library can be viewed in one place.

9.5. How do I add a component?

To add a component you first need to open the 'Manage Component. dialog and select 'Create Component'.

 

Manage Component 1

 

This will open up the 'Create Component Wizard'. On the first page you will need to select a folder to become linked with another folder inside your repository. You can either create a new folder to become the link or select an existing folder.

 

Create Component Dst Page 

 

If you create a new folder you will need to select the new folders parent in the tree and press the 'Create Folder' button. This will prompt you for a name of the new folder. (note: you can create multiple levels of folders to place the component into.)

If you select an existing folder all current files and folders inside it will be deleted. This can be useful if you want to make a folder into a component which used to be manually copied or merged. If files exist that are in the new component they will keep all previous history after the component has been made.

Once the destination for the new component has been selected you need to select the folder which will be linked to this new folder. You can either select the root folder of a stream by selecting the stream or you can select the subfolder of a stream.

 

Create Component Src Page 

 

If the component is successfully created a new changeset will be added to the stream for users to download the new files and the component will be added to the 'Manage Components' dialog.

 

Manage Component 2

9.6. How do I update a component?

Updating a component will allow you to change what the component folder is linked to. This can be useful for upgrading a shared library to point at a later version.

 

To upgrade a component you first will need to open up the Manage Component dialog for that stream and select 'Update Component'. Alternatively you can navigate to the folder in the streams list and select 'Update Component' from its menu.

 

Manage Component 1 

 

This will launch a Wizard which will require you to select the new folder that this component will be linked with.

 

Select Folder 

 

Updating the component will delete any files which are not in the new component folder and will add or modify files from the new component.

 

Manage Component 2

 

 

9.7. How can I stop my component receiving updates?

If you want to finalise a release so that it is no longer changed or you simply want to lock a component at a set point you can break the link between the two folders in the component. Breaking the link means you can modify the files at one side of the component without changing other streams using the same shared code.

 

To do this you need to open the manage component dialog, select the component you wish modify and press delete component.

 

 Manage Component Delete

 

This will open a dialog to confirm the component delete. This dialog will also include a check box asking if you wish to delete the folder from the current stream. To break the component link you need to make sure that this is not checked.

 

 Confirm Delete Prompt

 

This will then delete the component record and it will no longer be listed in the manage component dialog. However the files will be left in both streams as a direct copy of each other at the time the component was broken. You can then change or modify the files without changing the files it used to be linked too.

 

However this is not always the best way of managing releases as you can no longer tell which version of the shared library the new release is using. For an alternative to this see 'Managing Component Releases with streams'.

9.8. How do I know which files my file is linked to?

If you are going to submit changes to a file it can be useful to see which streams your changes will affect. The best way to do this is by navigating to the correct folder on the stream list. From the stream node any folders which are part of a component will have a yellow puzzle icon instead of the usual folder icon. To view which other folders are linked to this folder you need to select the 'Show Links' option from it's menu.

 

Show Links Menu

 

This will open up a window listing all of the folders that are directly linked to this one.

 

Show Links

9.9. Setting up component permissions

There are two Stream Security permissions which control the access to components inside PureCM. These can be configured either from the Global Properties found on the connection node or from individual stream, stream folder or repository properties.

 

Component Permissions 1

 

Component Permissions 2

 

Create Component From

The 'Create Component From' permission allows users to create a link to this stream from another stream. This can be used to control not only who can make components but which streams can be used to create components. For example this can be used to ensure that only release streams are used as components. For more detail on how this can help your work flow see Managing Component Releases with Streams.

 

Modify Components

The 'Modify Components' permission gives users the right to add, update and delete components on this stream. This permission also control who has access to the manage components dialog.

 

For a user to add a component they will need the 'Modify Components' permission for the stream they are adding the component to and the 'Create Component From' permission for the stream they are creating the link to.

9.10. Managing Component Releases with Streams

Simply creating a development stream for your library and including it into all of your projects is the quickest way to get working with components. This would mean that all projects always had the latest version of the library and when you create release streams for your projects you would simply need to break the component links to stop the release stream receiving any more updates.

 

However in some working patterns such as parallel development this is not always the best as you may not want all of your projects to use the same version of the library, but also may not want to break the component links as any bugs found would still need to be fixed in the older version of the library.

 

This can be managed by creating a system of library releases. This can work very well for third party libraries which are updated as their developer releases new versions. Each time a new version is released you can create a new release stream for that version. Any projects that you wish to use the latest changes can be updated to point at the new release stream.

 

This gives you a number of advantages.

  • Any problems found with that version of the library can be fixed in all of the projects that reference it.
  • You can easily see which projects are using each version of the library through the manage component dialog or by viewing the links from the stream node.
  • Several versions of the same library can be kept and used at the same time.

 

To further aid the control of which streams are able to be made into a component you can set the Create Component From permission only for a Release folder which you set up. This way only releases will be able to be made into components.

9.11. Quickly updating your projects to use a new library

When a later version of a software library has been released you can update each project in turn by navigating to their own stream and updating these components individually.

 

However when lots of components need to be updated it can often be quicker to update these components from the old version of the library.

 

Manage Components 1

 

In the example we want to update the component 'Lib1' in the three release streams '1.8.0', '1.8.1' and '1.8.2' to use a new version of the library. By expanding one of these components we can see the three folders we want to update. By selecting these here rather than the top level component we can update each one of them to point at the new library.

Select each one in turn and press update component and select the new library location.

 

Update component

 

Selecting the component you are looking at last will stop you having to reselect a different component after the update has removed the link.

9.12. Sharing Individual Files/File Level Components

I need to share 2 files among different streams in the same repository. The files are in a folder which contains 100+ files but I only need to share 2 of them. I could make a component of the whole folder but I’d be downloading a lot of files which I don't need. Is there a way to do what I need?

PureCM only supports sharing folders. We intentionally did not support individual file sharing because it can get very complicated (I know when we used to use VSS we got in a real mess with file sharing). There is a big question in the CM community on whether the file sharing ability of VSS is a feature or a bug.

If this is a big problem we recommend you restructure your folders so the shared files are put in a different folder.

9.13. Can't re-use component folder name before 2008-2

If you add a component to a stream and then remove the component, you are currently unable to then re-add the component in the same place with the same name.

This has been fixed in the 2008/2 server release.

9.14. What has happened to all of my static components in 2008-3

For the 2008-3 release static components have been removed from PureCM. You will no longer be able to create new static components and any old static component will be automatically migrated when you install the 2008-3 server.

 

Instead of static components you now simply break the link between the two folders. This means that they will no longer be shown inside the Manage Component Dialog but it will provide you with greater flexibility when managing your releases. One major advantage of this change is that you will now be able to modify your files to make any last minute amendments for the release stream that you did not want to apply to the main library.

9.15. Why can I not see any of my components using a pre 2008-3 client or server

In the 2008-3 release the way the component information is accessed on the server has changed. The 2008-3 client will not detect any components on an older server and an older client will not detect any components on the 2008-3 server.

Both client and server will need to be upgraded to 2008-3 or later to make use of the component enhancements.

10. Shelving

10.1. What is 'Shelving'?

The purpose of shelving is to enable unfinished changes, such as work in progress, to be sent to the server without needing to submit a changeset. Shelving a changeset, to create a shelveset, is useful in the following scenarios:

Backing-up changes to the server

When the changeset is shelved the changes are saved on the server. If the workspace changes are lost the user can create a new workspace and unshelve the shelveset.

Shelvesets include the concept of ownership. In this situation other users will not be able to unshelve the shelveset unless an administrator removes ownership.

Handing changes over to another user

A user may implement some of the changes and then hand it over to another user for completion. To do this the user will shelve the changeset, removing ownership. The second user is then able to unshelve the shelveset into their workspace, take ownership, and complete the changes.

Another user testing changes

A user may implement the changes but want another user to test them (or want to test them on a different platform) before submitting. To do this the user will shelve the changeset removing ownership. The tester is then able to unshelve the shelveset, without taking ownership, into their workspace. After the changes have been tested the original user can unshelve the changeset back into their own workspace and either submit it or make further changes.

Transferring a changeset to a different workspace or stream

In certain situations a series of changes may be started in one place but a decision is made to implement them in another. For instance, moving them to an earlier or later release stream. The user shelves the changeset in the original stream and unshelves it in the new stream.

10.2. How do I view Shelvesets?

In the GUI, after creating a shelvset, 'My Shelvesets' should appear within the repository.

If you select this it will list all shelvesets belonging to you. You can double-click a shelveset to view the changes in the Shelveset Dialog. You can also right-click the shelveset and select 'Remove Ownership'. This will allow another user to 'Take Ownership' of the shelveset. Finally you can delete the shelveset. You can always delete your own shelvesets.

Alternatively, if you want to view other people's shelvesets navigate to the stream in the GUI and you will see 'Submitted Changesets' in the tree.

Expand this to reveal all shelevsets for this stream.

This will only be available if you have the 'View Current Changesets' policy enabled. You can double-click a shelveset to view the changes.

If you have the 'Changeset Administrator' policy enabled you are also able to 'Remove Ownership' and 'Delete' other people's shelvesets.

10.3. Is it possible to checkpoint my changes?

It is a common scenario when working to reach a point where you want to save the changes you have made, but they are not ready to be submitted. Perhaps you want to try a new way of doing something - safe in the knowledge that you can always revert back to this previous state.

The best way of doing this with PureCM is to shelve your changes. See the User Guide 'Shelving | Shelving Changes' for more details. Note that this will also backup your work on the server - so the changes will not be lost if something happens to your PC.

If you shelve a current changeset twice then the initial shelveset will be updated - so the original checkpoint will be lost. If you want to keep the original checkpoint and create a new checkpoint then you should create a new current changeset and shelve that. See the User Guide 'Adding & Editing Files | Working on Multiple Changes' section for details on creating a new current changeset.

10.4. Unshelving into a Different Stream

In the PureCM 2008/2 release we added the ability to unshelve into a different release. This therefore gives you the ability to start a change in one stream, but unshelve it into another stream if you later decide you are implementing it in the wrong stream.

For example, suppose you get a bug report for what looks like a trivial change in the live release. You start working on a fix in the development stream for the live release. But after implementing some of the changes you realise the change is not as trivial as you first thought and it is therefore deemed too risky to put into the live release. In this situation you can now shelve your current changes selecting to revert the changes. You can then unshelve it into a development stream for the active development release. If there are any conflicts (e.g. some of the files have already been changed in the active development release) then you can easily merge them using the familiar PureCM Resolve Tool. So this is a lot quicker and less error prone than having to copy your files across to the new stream and potentially loosing someone elses changes!

To unshelve into a different stream right-click a workspace for the destination stream and select 'All Tasks | Unshelve'. This will launch the Unshelve Dialog.

 

Select the stream in which the shelveset was created on the left tree. This will list all the shelvesets currently existing for this stream. You can always right-click one of these shelvesets and select 'Properties' if you want to see what changes the shelveset contains. When you have established which shelveset you want unshelve select it either by double-clicking or selecting it and pressing 'OK'.

10.5. I get warning W0193 when a try to unshelve a changeset

W0193 - Unable to read base revision of file '<FILE NAME>'

In older versions of the PureCM client, if you created a shelveset that contained a file that had been checked out but not changed you would recieve this warning when you try and unshelve the file. If this was the case this has not caused any problems with the shelveset as no data was ever stored for the unchanged file.

This should no longer happen for any shelvesets created with 2009-2b client or later.

11. File Types

11.1. What Are File Types?

When you add a file to PureCM it will be associated with a file type. PureCM will try and 'guess' the correct file type to use when adding the file.

File types are useful because you can set flags against the file type, which will then effect all files which use it. For example if you decide that all xml files should use UTF-8 encoding rather than local encoding then all you need to do is change the encoding on the 'text/xml' file type to be UTF-8. If a user now creates a new workspace all 'text/xml' files will now use UTF-8 encoding. See the Administrator Guide 'File Types | File Type Flags' section for a description of the various file types.

File types are also useful on the client because you can specify options according to the file type. So for example you can specify that editing all 'text/*' files should use the PureCM Editor, but all 'application/msword' files should use your default editor (presumably Word). See the User Guide 'Client Options | File Preferences' section for a description of the settings you can associate with a file type.

11.2. Why are the file types I've added on the server not available in my workspace?

After changing the file types on the server you need to run 'Update to Latest' in the workspace to incorporate the changes. You can test whether the the changes have been incorporated by selecting 'Properties' on a file and seeing if the new file types are available in the drop-down.

11.3. Why does 'File Types' appear in my repository and at the root?

In general you should not add file types to the repository. If a file type setting does not exist for the repository then PureCM will use the root file type settings. You will find that the root contains many file type setting for different types of files.

There are however occassions where you want to make an exception for a repository. For example, you might create a new repository for your web site where you want all 'text/xml' files to use UTF-8 encoding. But you do not want to change all 'text/xml' files in the other repositories to be UTF-8. In this case you can leave the root 'text/xml' file type to be local encoding. You should then create ''text/xml' as a repository file type and set the encoding to be UTF-8. This will override the root settings.

11.4. What algorithm does PureCM use to 'guess' the initial file type when adding a file?

When adding a file to PureCM the file will automatically be assigned a file type. You can manually change the file type, but if adding a lot of files it can be a laborious process to go through checking each file. The algorithm PureCM uses to determine the file type is described below.

1) If the file matches a filter for a file type with the 'Force this File Type to be Used' then this file type will be used. So if you have created a file type 'text/xml', set its filter to be '*.xml' and set the 'Force this File Type to be Used' flag then the file file1.xml will always use the 'text/xml' file type.

Otherwise...

2) PureCM will read the first chunk of the file to determine the encoding of the file. If the 'Options | General | Read entire file to determine file type when adding' is set then the whole file is read, otherwise the first chunk of the file is read. This can be important because some files (e.g. pdf files) may appear to be ordinary text files initially, but actually have some binary content at the end of the file. But if adding lots of files it is obviously quicker to only read the first chunk of the file (rather than read the whole file). Note that if you can identify which files cause this problem you could just set the 'Force this File Type to be Used' flag and continue to only read the first chunk.

3) Iterate through each file type to find one with a filter which matches the file path and the encoding which matches the file type encoding. So for example if you have an file type 'text/xml' with a filer '*.xml' and encoding UTF-8. This will not be used for the file file1.xml which uses UTF-16 encoding - because they have different encodings. Also note that when detecting the encoding it is not always possible to distinguish between local encoding and UTF-8 encoding. In this case the algorithm will search for file types with either encoding.

If no file type matched then...

4) If the encoding was local use 'text/plain'. If the encoding was UTF-8 use 'text/utf8'. If the encoding was UTF-16 use 'text/utf16'. Otherwise use 'application/generic'.

11.5. After adding a new file type, how do I get all my files to use it?

You can change the file types of existing files using the 'pcm workspace editfiletypes' command. So for example to change all header and cpp files you would type:

    pcm workspace editfiletypes text/plain -r *.cpp *.c *.h

This will checkout every file matching these filters and change the file type to 'text/plain'. You then need to submit these changes just like any other changeset.

11.6. Why do my files get re-encoded to UTF-8 after submitting them as local encoding?

This is the behavior you would expect if the file type was set to UTF-8 encoding. To find out what file type a file is using you need to right-click the file and select 'Properties' (you can do this in a workspace or under the stream). This will launch the 'File Properties' where the file type is displayed on the General page.

A user with the 'File Type Administrator' policy enabled (as explained in this article) can then go and view this file type by selecting the 'File Types' tree item and opening the relevant file type (in this case 'text/plain'). You should check if the file type exists within the repository otherwise you should update the root file type (as explained in this article). The 'Flags' page of the File Type Properties will display the encoding.

You can select the encoding you want to use from the drop-down. Note that this will not update existing workspaces.  In an existing workspace any new files will be added with the correct encoding - but old files will keep the old encoding until they are edited. If you create a new workspace then all files will incorporate the change.

11.7. E0072 - Unknown file type Event

This error implies that one or more files are using a file type which has been deleted.

If you do not know which files are using this file type then the quickest way of finding out is to export the repository database to an xml file and search for the file type string within the xml file.

If you need to change the filetypes for many files then it is quicker to use the 'pcm workspace editfiletypes' command.

11.8. How to restore the default file types

It is possible to import the default PureCM file types again..

When installing the server you will have also installed the database utility tool 'tdbutil' (e.g. 'C:\Program Files\PureCM\Server\tdbutil.exe'). This has an export/import facility...

- First of all stop the PureCM service.

- Make a backup of the C:\PureCM\data folder - incase of any problems.

If you just want to install the default file types again (overwiriting any current ones) you can import the file 'server@mime.xml' located in C:\PureCM\templates. ie..

- tdbutil import c:\PureCM\templates\server@mime.xml c:\PureCM\data\server

If you want to keep your existing file types, and add the default ones, then you need to export the MIME table from your server database, to an xml file, manually merge the file types from 'server@mime.xml', and then import the merged file. ie..

- tdbutil export c:\PureCM\data\server c:\PureCM\temp.xml --table="MIME" --indent

- merge the file types from 'server@mime.xml' into this file.

- tdbutil import c:\PureCM\temp.xml c:\PureCM\data\server

- restart the PureCM service.

12. Security/Policysets

12.1. Can I prevent users from seeing certain respositories?

If a user does not have read permission for the repository then the repository will not appear. We use this so developers do not have access to the company accounts for example.

The file permissions determine who can read/add/edit/delete files/folders in a stream. Note that if a user does not have read permission for a folder/file then the file(s) will not be downloaded into the workspace.

When you create a stream it will default to inheriting it's file permissions from the parent (the stream folder or repository). So generally you set the file permissions for the repository and all streams use these permissions.

Note that you can set file permissions for a repository, stream folder, stream, folder or specific file. So you can create some sophisticated permissions if required.

For example we have our repository permissions allowing Developers to edit files. But in the 'Release' stream folder we override the permissions so only 'Lead Developers' can edit files.

We use the 'repository administration' policyset to allow users to add or delete repositories. The idea is that an Administrators can add or delete repositories but will not necessarily be able to edit the files (typically it is Developers who can edit files).

12.2. How do I specify who can create a new repository?

The ability to create a delete a repository is specified by the 'Repository Administration' policy. So you should create a group for the users who are able to add repositories (e.g. Administrators). You should then create a policyset for the group 'Administrators' which enabled the 'Repository Administration' policy. You should then disable the 'Repository Administration' policy in the default policyset.

12.3. How do I hide the administration nodes for some users?

You can specify who can perform administrative tasks (and therefore who can see the administration nodes) by disabling the relevant administration policy.

So, if you only wanted administrators to see the 'Users' node you would:

Create a new policyset which applies to the 'Administrators' group. You can do this by right-clicking the 'Policy Admin' node and selecting new. Specify that the policyset applies to all repositories but the group 'Administrators.

Name the policyset 'Administrators' and 'Finish' the wizard. The 'Administrators' policyset should now appear with the 'Default' when selecting the 'Policy Admin' tree item.

Double-click the 'Administrators' policyset and go to the 'Policies' page to see what policies have been defined. Initially this will be empty.

Press the 'New' button and select the 'User Administration' policy.

Press OK to add this policy to the policyset. As you will see, initially the value for this is 'False'.

For the 'Administrators' policyset we want to set this to true (so that administrators) are able to add/edit/delete users. Double-click the 'User Administration' policy to open the 'Policy Setting' dialog and set the value to be Enabled.

After pressing OK you will see that the Value is now 'True'. Press 'OK' to save the changes to the 'Administrators' policyset.

So we have specified that 'Administrators' are able to add/edit/delete users. We now need to specify that everyone else is not able to add/edit/delete users. Double-click the 'Default Policyset' to open the policyset. If you go to the 'Polcies' page for the 'Default Policyset' you will see that many policies have been specified by default. One of these is 'User Administration' which has a value of True. Double-click the policy and disable it to set its value to False.

After you have pressed 'OK' to save the changes you should find that users belonging to the 'Administrators' group are able to see the 'Users' tree item. They are able to add/edit and delete the users as before. Users who do not belong to the 'Administrators' group do not see the 'Users' tree item. If they attempt to add/edit/delete users (using the command line or SDK) the command will fail.

12.4. Separate User/Group Administration from other Administration

We have a request from our IT department to investigate the ability to create a separation of the user account management (adds and deletes) from other admin level capabilities. If we can do this then the user admin can be relegated to IT and the tool admin can remain within my group for all other admin items. This is in alignment with Sarbanes/Oxley guidelines according to our IT guys who live and breathe this stuff.

Let me know if this is possible and likely in a future release so we can plan accordingly. It would greatly reduce admin hassles and tool management for our organization.

-------------------------

1) Create a new group 'User Administrators'.

2) Create a new policy set which applies to the 'User Administrators' group only.

3) Ensure that this policy set only has 'User Administration' set to true. Everything else should be set to false.

4) In the properties for any Repository, ensure the new group does not have any Permissions in File security or Stream security.

With this in place, any user that only belongs to the 'User Administrators' group will only be able to add, amend or delete users or groups.

12.5. Is it possible to reset the PureCM policies?

There are situtations where you need to reset your policies. For example, if only the Administrators group has the 'Policy Admin' policy enabled and you delete the 'Administrators' group. Noone will ever be able to change the policies again!

You can reset the policies with the 'tdbutil resetpolicies' command.

13. Connections

13.1. When does a connection use up one of the license quotas?

Why is it If I open the Web Client and the GUI Client from the same machine machine the server views it a 2 connections butI can have the GUI GUI Client and Visual Studio or GUI Client and issue commands from the command line viewed as 1 connection?

Connecting to a PureCM server via the web client uses a different IP address therefore is handled as a different connection to that of the gui/SCC/command line, which all connect from the same client.

You can only have multiple connections using one quota if you are connecting as the same user on the same machine. So if you are using the Visual Studio Plug-In and the GUI on a machine this will only use one connection. But if you work on a different machine this will use another connection (even if the user is the same).

13.2. When I try and connect to the PureCM Server I get an "Unable to initialise connection to server..." error

If unable to connect to the server these are the things to try:

    1) Can you connect using a client on the same machine (i.e. localhost)?

If this is not possible then check that the username/password is correct and your connection quota is not full.

If this is possible but a connection from another client fails then try:

    2) Is the server running a Firewall? If so then you must enable the PureCM port (default 2010).

    3) Is this a domain issue? Could you try entering the server IP address directly rather than machine name.

14. Scripts

14.1. When should I use scripts as opposed to the .NET/Java triggers?

The Python scripts are great if you want to do something simple. For example if you want to create a snaphot at a specified time every day the quickest way to implement this is to write some python in the OnEveryHour() function.

If you need to do something more complicated then you will need to use the .NET or Java triggers. Using the Python scripts you only have the information passed into the function. Within the .NET/Java triggers you can use the API which will give you access to a wealth of information within PureCM.

14.2. What version of Python does PureCM support?

PureCM supports versions 2.3, 2.4 and 2.5 of Python.

14.3. How do I send an email when a review has been accepted/rejected?

The 'OnIssueAction' repository script could be used to send an email when handling issues. OnIssueAction() is called whenever an action is performed on an issue.Here is an example of how we send e-mails from a repository script ..

import smtplib

def OnIssueAction(issue,action,user,email,description):
     TEXT = "Description\r\n===========\r\n%s\r\n" % (description)
    ADDRESS_TO = [email]
    SMTP_SERVER = 'mailscanner.purecm.com'
    ADDRESS_FROM = 'purecm@purecm.com'
    SUBJECT = '[%s] %s has been assigned to you' % (gethostname(),issue)
    MESSAGE = "From: %s\r\nTo: %s\r\nSubject:%s\r\n%s\r\n" % (ADDRESS_FROM, ADDRESS_TO, SUBJECT, TEXT)
    server = smtplib.SMTP(SMTP_SERVER)
    server.login('user','password')
    server.sendmail(ADDRESS_FROM, ADDRESS_TO, MESSAGE)
    server.quit()
    return

If you only want to send an email for specific actions you can check the 'action' parameter which is the action name.

If you want to do more complex processing (e.g. send an email to all users within the group) then you should use a trigger with either the .NET or Java API.

 

14.4. Does Python Need to be Installed on all Clients to Use Scripts?

Python needs to be installed on any client machine that will edit a python script. You need Python on the server if server scripts are to be used.

14.5. How do I Run Scripts on the Client Machines?

PureCM does not support client-side scripts. This functionality was taken out of the 2005/4 release because of major security implications. If a malicious user was able to edit the script he was able to run any Python code on every client machine. To run client triggers it also required that all clients had Python installed. PureCM therefore only supports server-side scripts.

15. Licenses

15.1. Can I mix both PureCM Standard and Professional licenses on the same server?

No. If you have active licenses for both PureCM Standard and Professional, the Standard licenses will be invlid. For example, if you have 5 standard licenses and add 5 professional licenses, you will be able to use the 5 Professional licenses only.

This is most likely to happen if you add purchased Standard licenses while your Trial license is still active. In that case, simply delete the Trial license to validate your purchased Standard licenses.

15.2. Do I have to reinstall PureCM when upgrading from Standard to Professional?

No. You can simply contact us to get your upgrade licenses. Add them to PureCM, which will automatically override your Standard licenses with the Professional licenses. Then, go to "Policy Admin" to activate the professional features you want to use, e.g. issue tracking or reporting.

Note that upgrading will fully preserve your changeset history or current workspaces, as upgrading only unlocks Professional features.

15.3. There are no downgrade licenses. How do I do so?

We are sorry to hear that you intend to do so. Downgrading with ongoing support and maintenance is only possible upon expiry of your current Professional licenses. Simply contact our sales team, which will provide you with Standard licenses for the cost of a regular Standard license renewal.

You will need to delete your Professional licenses after you have added your received Standard licenses to complete your downgrading. This will remove access to Professional features, such as Issue Management, Reporting or managing Merge Paths. Note that any settings for Professional features will be preserved for the case of a later upgrade back to PureCM Professional.

Downgrading will not affect your data, changeset history or existing workspaces, which will be fully preserved.

15.4. What is a Non-Developer Licence?

A non-developer licence is cheaper than a full licence but does have some restrictions. Non-developer users cannot perform workspace actions such as checking out and modifying files or submitting changes to your stream.

15.5. How can I specify a user as a Non-Developer?

A user is a Non-Developer if they have the 'View My Changesets' policy disabled.

The best way to achieve this is to set up a PureCM group for non-developers.

Create a group for Non-Developers

Once you have created the new group you need to add to it any users you wish to be non-developers.

Next create a policyset for the Non-Developer users.

Make the policyset for all repositories

This should be over all repositories.

Make this policyset for the Non-Developer group

Set this new policyset to appy to the new Non-Developer group.

Give a name to the policyset 

Open this new policyset once it is created. In the policies tab click new and select 'View My Changesets' and click OK. Double click the new policy to change its value and set it to false from the menu.

Set the policy to false

Now all users you add to this group will take a Non-Developer licence if there is one avaliable.

Note:

Remeber to check that 'View My Changesets' is not included in the default policyset. This defaults to true and so does not need to be set for normal users.

15.6. Why does my renewal license appear 'Unused'?

The renewal license requires the original license to work. So you need to add your original (non-renewal) license back (I assume this has been deleted). If you do not have the details for your original license please email sales@purecm.com. This functionality is intentional so that users can only use a renewal license if they initially purchased a ‘full’ license.

Alternatively the renewal licenses will appear as 'unused' if the support period has not yet started. So say you have some licenses for the 2008/2 release. From July 2008 you will receive the prompt that your licenses will expire on 30th September 2008. If you purchase the renewal licenses they will appear as unused until October 2008/2 - at which time the existing licenses will appear as expired.

Note that the expiry message will continue to appear until you check the 'Don't Show Again' checkbox. If you check the 'Don't Show Again' checkbox the message will appear the next time your licenses are expiring (July 2009).

16. Users

16.1. How to change user passwords

The command line command 'pcm server changepassword' can be used to change the password of the current user. This does not require the 'User Administration' policy to be enabled.

eg. pcm server changepassword [--username=<user-name>]

Not specifying the user will use the current default connection's user. You will be prompted for the existing and new passwords.

Alternatively user administrators can use the gui to change the password of any user without requiring knowledge of the existing password. Click on the 'Users' node, right click on the relevant user in the list, and select 'properties'.