HomeThird Party Plug-InsPrinter Friendly Version

Third Party Plug-Ins

Installation instructions and tips on using Third Party tools with PureCM

1. Cruise Control.NET

1.1. What is CruiseControl.NET?

CruiseControl.Net

CruiseControl.NET is an Automated Continuous Integration server which will monitor your PureCM repositories and validate any submits made to them.

This is done by checking that all of the software projects still build correctly and that all of the automatic tests still pass.  This means that problem submits can be quickly identified and the relevant developers notified so they can fix the problems.

1.2. Which Version of CruiseControl.NET Should I Use?

The PureCM CruiseControl.NET Plugin is built against CruiseControl.NET-1.3 although later versions have been used successfully (1.4).

1.3. Getting Set Up

Getting the DLL 
  1. To use the CruiseControl.net PureCM plug-in you will need to install the PureCM Client (2008-3c or later) onto the same machine as your CruiseControl.net server.
  2. You then need to get the latest CruiseControl.net plug-in DLL (ccnet.PureCMSvr.plugin.dll).
  3. This DLL then needs to be placed into the 'CruiseControl.net/server' directory (This is typically 'C:\Program Files\CruiseControl.NET\server' or where ever you chose while installing Cruise Control).
  4. You need to copy the PureCM.Net Client DLL (C:\Program Files\PureCM\Client\PureCM.Client.dll by default) into the 'CruiseControl.net/server' directory.
Creating a PureCM user (optional)

You will need to connect to PureCM using a PureCM user with 'Password' enabled. This can be done using any of your current PureCM users but it can be useful to create a new user for running CruiseControl.NET. This gives you better visibility on what is using your PureCM Licences and also will give you better control over security. As the cruise control user will never need to submit to the server you can limit the permissions of that user to only have read access for the streams you need. At a minimum you can add it to the 'Developer' group to ensure read access but no access to administrator functions.

Setting up the 'ccnet.config' file

For each stream you want CruiseControl.net to manage you will need to set up a new project in the 'ccnet.config'. To get this to work with PureCM you will need to add a 'source control' block as shown below.

<sourcecontrol type="purecm">

    <server>localhost</server>

    <port>2010</port>

    <
user>CruiseControl</user>

    <password>secret</password>

    <
repository>Example</repository>

    <stream>Development\Main</stream>

    <
workspace>C:\Program Files\CruiseControl.NET\server\workspaces\Example\Main</workspace>

</sourcecontrol>

The <server> element stores the name of the PureCM server you wish to connect to.

The <port> element stores the port you wish to use on the PureCM server.

The <user> element stores the user name of the PureCM user you wish to connect with.

The <password> element stores the password of the PureCM user you are connecting with.

The <repository> element stores the name of the repository you are using.

The <stream> element stores the path to the stream you are using.

The <workspace> element will need to point at a workspace that will be created purely for CruiseControl.net. This location needs to be somewhere where the windows user running CC.net(usually 'Local System') has permission to write files.

You can download an example 'ccnet.config' file from the bottom of this page which has one project that builds a single Visual Studio solution in both release and debug modes.

No need to create a workspace!

In previous versions of the CruiseControl plugin you needed to create a workspace before running the service. Now all workspaces will be created for you meaning all you need to do is set up the config file and start the service!

Running CruiseControl.Net

You can run CruiseControl.Net in one of two ways, each with their advantages and disadvantages. As PureCM relies on a  'Connections Database' to handle server connections you cannot usually switch between the two easily. Running the CruiseControl.Net service will use the windows user 'Local System' which will register any workspaces created to it's Database. Running on the console will generally run as the current logged in user and register its workspaces to it's database. 

Running CruiseControl.Net from the console.

To do this in windows explorer you need to navigate to the Cruise Control server directory (typically 'C:\Program Files\CruiseControl.NET\server') and run the ccnet.exe executable. To run this from a command prompt you need to change the directory to the Cruise Control server directory (cd "C:\Program Files\CruiseControl.NET\server") and run the ccnet executable (ccnet.exe).

note: Running the command "C:\Program Files\CruiseControl.NET\server\ccnet.exe" from another location will not work as it looks for files in the location the command was run from.

1.4. Troubleshooting

Cruise Control.Net Log File

If you are having problems running the CruiseControl.Net service the first place you should look is the 'ccnet.log' file located in the server directory (typically 'C:\Program Files\CruiseControl.NET\server').

This file logs all of the operations of cruise control as well as logging all of the PureCM operations. For full log details you will need to make sure cruise control is configured to display DEBUG information. You can do this by stopping the service and loading the 'ccnet.exe.config' file. You need to set the <level> elements value to equal DEBUG as shown below.

The full list of supported values are DEBUG, INFO, WARNING, ERROR and OFF.

<log4net>

    <root>

        <level value="DEBUG"/>

        <appender-ref ref="Console"/>

        <appender-ref ref="RollingFileAppender"/>

    </root>

If this log file does not give you any indication of what the problem is please email it together with a detailed description of the problem to support@purecm.com.

Make sure PureCM is on the Path

The cruise control service needs to access the PureCM libraries located in the PureCM Client install location (typically 'C:\Program Files\PureCM\Client'). Often any problems related to Cruise Control not being able to find PureCM libraries is because the PureCM Client Directory needs to be added to the global list of directories. This can be found in System Properties - Advanced - Environment Variables.

2. OnTime Bridge

2.1. What is OnTime?

OnTime is a project management suite developed by Axosoft. It's used for bug tracking, scrum process automation, requirements management, project visibility, a wiki, and a help desk.

Why not just use the PureCM Issue Tracking functionality?

The PureCM Issue Tracking functionality is good for development teams raising bugs/enhancements, assigning these to developers, submitting against these issues with a review, and keeping the association between the issue and the changeset.

So PureCM issues are good within the development process, but it is often not the developers who are raising bugs/issues. There might be a separate help desk who are responsible for raising the bugs/enhancements reported by customers. Or some companies might want to give customers a portal where they can raise bugs/enhancements which get fed straight into the system.

Obviously help desk workers or customers do not want to use the PureCM GUI to raise issues. One option would be to update your website to allow peole to create PureCM issues using the PureCM .Net or Java APIs. But if you want an out of the box solution then OnTime is a good choice.

2.2. What is the PureCM OnTime Bridge?

The PureCM OnTime Bridge is a Windows Service which periodically synchronises OnTime defects, enhancements, and incidents with PureCM issues. So when a defect is assigned to a developer, a PureCM issue is automatically created. When the developer submits his/her work associating the PureCM issue, the OnTime defect is automatically updated.

OnTime defects, enhancements and incidents are all handled the same way but I will only refer to the defect.

You configure the OnTime Bridge to specify when the PureCM issue is created for a corresponding OnTime defect. You also configure when the OnTime defect is updated following an action on the PureCM issue.

 

And the OnTime Bridge will also update the PureCM issue if the defect is updated.

The examples above illustrate the most simple case. You can configure OnTime to have many more states before the PureCM issue is created and after it is completed. Similarly you can configure PureCM to have many more states between being created and completed.

2.3. Installing the OnTime Bridge

To install the OnTime Bridge you need to download the MSI from the PureCM website.

After agreeing to the license agreement the installer will ask you where you want to put the files. This will default to 'C:\Program Files\PureCM\OnTime Bridge'.

You then need to click 'Install' to install the files.

After installation you will notice that the 'Start | All Programs | PureCM OnTime Bridge' folder has been created. This will contain 3 entries:

  • 'Help' will launch a web browser taking you to this knowledge base.
  • 'Configure OnTime Bridge' will open the PCMOnTimeBridge.xml file in your default xml editor. This is the first thing you will need to do and is described in the next section 'Configuring the OnTime Bridge'.
  • 'Test OnTime Bridge' will run the OnTime Bridge in a command prompt so you can easily see any warnings/errors you are getting if it is not configured properly. You should run this with the LogLevel set to 'info' in the config file so you can see if it is working correctly.

After you are happy the OnTime Bridge is working correctly in the test environment you should close the command prompt and start the PureCM OnTime Bridge windows service. You will see that the installer has installed the 'PureCM OnTime Bridge' service but it is not started. Any warning/errors will be shows in the event viewer when running the service.

 

2.4. Setting Up PureCM and OnTime

After installing the PureCM OnTime Bridge you will need to setup OnTime and PureCM before configuring the OnTime Bridge.

Ensure you have installed the OnTime 2008 SDK. The OnTime Bridge uses these web services. 

Within OnTime you need to create a CustomField to store the PureCM Issue Reference. You do this by selecting the 'Tools | Manage | Custom Fields' menu within OnTime. Go to the Defects tab (and/or Features and Incidents if you want to synchronise these). Add a new Custom Field giving it a name like 'PCMREF'. You will need to remember the name of this Custom Field so you can specify it in the OnTime Bridge configuration file.

If you are already using PureCM issues then you will need to go the Issue Type and create a new text field which will store the OnTime reference calling it something like 'OTREF'. Again you will need to remember the name of this for the OnTime Bridge configuration file.

If you have not used PureCM issues before then you have a choice. You can either add a new issue type from the templates provided and create the new field as discussed above. You will notice that the templates provided by PureCM include a simple/complex workflow (depending on which template you choose) which will include reviews/etc. If this is what you want then carry on.

Alternatively I have attached a new template which you could use. The purpose of the attached template is that it provides the absolute minimum workflow required for the PureCM issue. The PureCM issue is 'Created' (where it is being worked on by a developer), 'Completed' (where the developer has submitted the change) or 'Rejected' (where the developer could not complete the task).

If you are just starting out then I recommend you use the attached template initially and configure the OnTime Bridge to get it all working. Then when it is all working you can expand the workflow to your liking.

To use the attached template you should download the zip file into your 'C:\PureCM\Templates' directory. Within PureCM when you create a new Issue Type 'OnTime' should appear in the list of available templates.

2.5. Configuring the OnTime Bridge

To configure the PureCM OnTime Bridge service you need to edit the 'PCMOnTimeBridge.xml' file which has been installed to the location you specified in the installer. For convenience you can select 'All Programs | PureCM OnTime Bridge | Configure OnTime Bridge' from the Start menu to open this file in your default xml editor.

The elements of the xml (PureCMOnTimeSync.xml) are described below. An example file is attached for you to download. 

 

<PureCMConnection> 

This element contains attributes that are used to connect to the PureCM Server. All the attributes of this element are required.

 

The attributes are:

  
Attribute Description

PureCMServer

Name or IP address of the PureCM server

Port

Port number of PureCM server

Username

Username of PureCM server

Password

Password of PureCM server

  

For example:

 <PureCMConnection PureCMServer="dev.purecm.com" Port="2010"      Username="Developer" Password="password"/>

 

 

<Log> 

The Log element is used to set the log level and an optional file path where logging information is recorded.

 

The attributes are:

    
Attribute Description

LogLevel

Level of logging ('debug', 'info', 'warning', 'error' or 'none')

FilePath

Path of file where logging information is written 

   

For example:

 

 <Log LogLevel="info" FilePath="C:\Program Files\PureCM OnTime Bridge\Log.txt"/>

  

 

Both these parameters are optional (if not specified the log level will be 'error'). Note that when the OnTime Bridge is run in the test environment by selecting 'Start | All Programs | PureCM OnTime Bridge | Test OnTime Bridge' then the messages appropriate to the log level selected will appear in the command prompt.

 

We recommend that you begin by setting the LogLevel to 'info' and run the OnTime Bridge in the test environment. When you are satisfied that it is all working and there are no warnings or errors you can set the LogLevel to 'warning' and start the service. 

 

 

 

 <Interval>

 

This element is used to specify the time interval for the service to run. This is the number of seconds between each synchronisation. So if this value is set to 60 then every minute the OnTime Bridge will check to see if any items have been added in OnTime and whether any issues have been changed in PureCM.

  

The attributes are:

 

Attribute

Description

ServiceInterval

Time interval in seconds

 

This attribute is optional (if not specified it will wait 5 minutes)

 

For example:

   <Interval ServiceInterval="60" />  

Will synchronise OnTime with PureCM every minute.

 

<OTConnection> 

In this element the user specifies the details of the OnTime web service. It has the following attributes:

 

Attribute Description

URL 

The URL of the OnTime web service. 

GUID

The security token provided when installing the OnTime web service.

  

For example:

<OTConnection URL="http://ontime.purecm.com/ontime2008sdk/" GUID="{D876CBDB-3777-FFFF-BED2-0CE6370123A5}"/> 

 

<Mappings> 

A Mapping is where you configure which PureCM repository will be synchronised with which OnTime project. You can specify multiple Mapping elements under Mappings so you can synchronise multiple OnTime projects.

 

Each mapping has the following attributes:

 

 

Attribute Description

repos 

The name of the PureCM repository 

project

The name of the OnTime project

 

For example:

 

<Mapping repos="purecm" project="My Project">

 

 

Note that the same PureCM repository and OnTime project can be specified in multiple Mapping elements.

 

 

Within each Mapping you can specify Defects if you want to synchronise OnTime defects, Features if you want to synchronise OnTime features and Incidents if you want to synchronise OnTime incidents. You can include all 3 in one mapping or just include 1 - depending on what OnTime items you want to synchronise.

The <Defects>, <Features> and <Incidents> elements all have the same attributes which are:

Attribute

Description

PCMIssueTypeName

PureCM Issue Type Name

PCMRefField4OTDefect

The name of the field in PureCM which will contain the reference to the OnTime item 

PCMDescField

The name of the field in PureCM which will contain the OnTime description of the item 

OTCreationState

The OnTime state which the item must be in before the corresponding PureCM issue is created 

OTRefField4PCMIssue

The name of the field in OnTime which will contain the reference to the PureCM issue 

 

Note that the PureCM issue is only created if the OnTime item is in the specified state and it has an assigned user which is mapped to a PureCM user (see below). So for example the OTCreationState could be 'Open'. Initially the defect is created and put in the state 'Open' but this will not create the PureCM issue. It is only after the manager assigns the defect to a developer that the PureCM issue is created and assigned to the same developer.

Each mapping will contain one or more actions. Each action associates a PureCM Action with an OnTime workflow step and an OnTime state. So when the specified PureCM action is performed on an issue, the corresponding OnTime defect will be updated to the specified workflow step and state. Equally when the OnTime defect is put into the specified state, the corresponding PureCM issue will have the specified action performed on it.

The Mapping Action attributes are:

Attribute Description

PCMAction

The name of the PureCM action

OTWorkStep

The name of the OnTime workflow step

OTStatus

The name of the OnTime status

OTPercentComplete

A number (0-100) which the percent complete will be set to after the PureCM action has been performed

 

The OTPercentComplete  attribute only applies to Defects and Features. It is not used for Incidents.

For example:

 

<Mapping repos="purecm" project="My Project"> 

    <Defects PCMIssueTypeName="OnTime" PCMRefField4OTDefect="OTRef"  PCMDescField="Summary" OTCreationState="Open" OTRefField4PCMIssue="PCMREF">

        <Actions>         

            <Action PCMAction="Reject" OTWorkStep="Defect Closed - Rejected" OTStatus="Closed" OTPercentComplete="1"/>         

            <Action PCMAction="Complete" OTWorkStep="Defect Closed - Fixed" OTStatus="Closed" OTPercentComplete="100"/>

        </Actions>         

    </Defects>      

</Mapping>  

 

<PCMOTUsers> 

In this element PureCM and OnTime Users are specified. PCMOTUsers element has zero or more sub-elements <User>. The <User> element has the following attributes.

  

Attribute

Description

PCMUser

PureCM user name 

OTUser

OnTime user 'Login Id'

  

If an association between the OnTime user and the PureCM user cannot be found then the OnTime Bridge will see if a user in PureCM exists with the same name as the OnTime user. If there is no user with the same name then the OnTime defect will not be synchronised in PureCM.

For example:

 <PCMOTUsers>

    <User PCMUser="Developer1" OTUser="tonyab"/>   

    <User PCMUser="Developer2" OTUser="davidr"/> 

</PCMOTUsers>  

2.6. Testing the OnTime Bridge

You can test the OnTime Bridge by selecting 'All Programs | PureCM OnTime Bridge | Test OnTime Bridge' from the start menu.

 

This will launch a command prompt and run the OnTime Bridge. The advantage of running it in the console window is that all information/warning/error messages will be displayed.

We recommend that you begin by putting the LogInfo level to 'info'. When you have fully configured the OnTime Bridge without any warnings or errors we then recommend you set the LogLevel to 'warning' and start the 'OnTime Bridge' windows service.

On Vista it may be necessary to open a Command Prompt as Administrator due to permissions. Simply cd to the install directory ('C:\Program Files\PureCM\OnTime Bridge') and run 'PCMOnTimeBridge.exe'. This will mirror what the Test start menu operation performs.

3. Gemini Issue Tracking

3.1. What is Gemini?

Countersoft's Gemini is a flexible and easy to use release planning, issue tracking and defect management tool. It's mainly web-based and offers a flexible setup to support both agile and more traditional workflows.

Why not just use the PureCM Professional Task Tracking functionality?

The PureCM task tracking functionality is excellent for development teams scheduling tasks, assigning these to developers, submitting against these task, and keeping the association between the task and the changes made.

So PureCM issues are well suited within the development process, but it is often not the developers who are raising bugs/issues. There might be a separate help desk who are responsible for raising the bugs/enhancements reported by customers. Or some companies might want to give customers a portal where they can raise bugs/enhancements which get fed straight into the system. This is when Gemini can be a good solution.

Please visit www.countersoft.com to learn more about the tool.

3.2. What does the Gemini plugin?

The Gemini plugin is a very simple solution to add a reference to a Gemini issue into the changeset submit dialogue. So unlinke the OnTime Bridge, the issue is not created in PureCM, but merely referenced as part of the changeset comment.

 Submit comment in PureCM

The plugin will then listen for that link and automatically add the changeset information as a comment to the relevant issue in Gemini:

Corresponding Gemini comment

Note that the simple implementation doesn't include any checks, e.g. to verify that issue numbers match or whether a reference to a Gemini issue was included in the Changeset comments.

3.3. Adding the Gemini plugin

The Gemini plugin is released as open source and can be downloaded from the PureCM Plugins webpage.

It includes a standard config file that can be modified to match the installation paths. Once it has been built and added to the application files, users can start adding the 'GEM' reference to any changeset comment to link it to a Gemini issue.

4. Deployment Service

4.1. What is the Deployment Service?

It is often necessary to deploy/upload files stored in a PureCM stream onto a server which cannot have the PureCM client installed.

For example, if you develop a website using PureCM then each developers will typically have a private workspace to make their changes. The usual way of uploading these changes to the server would be to create a workspace on the server machine and 'Update to Latest'.

However, it is often not practical to have the PureCM client installed on the server machine for security reasons. There is also the problem of how to trigger the 'Update to Latest'. This can involve a manager having to logon to the server machine and doing a manual 'Update to Latest'. This has further security implications and is also time consuming.

The 'Deployment Service' is a Windows service which runs on any machine that can connect to the PureCM Server. The first time it is run it will create a local workspace for the specified stream and ftp/sftp all the files to an ftp site. The Deployment Service will then listen for submits to the PureCM Server. Whenever a changeset is submitted it will update its local workspace and upload the relevant files to the ftp site.

So in the example above you would install an ftp server on your web-server and create an ftp site for your website.

4.2. General Requirements

The PureCM Deployment Service must be run on a Windows machine with the PureCM client installed and enough space to create workspaces for each of the streams that the user wishes to FTP or SFTP. This doesn’t have to be on the same machine as the PureCM Server.

The user needs to specify different workspace paths for each stream. Currently it is not supported to do file transfer from one workspace for multiple streams.

 

4.3. Installing the Deployment Service

To install the Deployment Service you need to download the MSI from the PureCM website.

After agreeing to the license agreement the installer will ask you where you want to put the files. This will default to 'C:\Program Files\PureCM\Deployment'.

You then need to click 'Install' to install the files.

After installation you will notice that the 'Start | All Programs | PureCM Deployment Service' folder has been created. This will contain 3 entries:

 

  • 'Help' will launch a web browser taking you to this knowledge base.
  • 'Configure Deployment' will open the PureCMDeployment.xml file in your default xml editor. This is the first thing you will need to do and is described in the next section 'Configuring the Deployment Service'.
  • 'Test Deployment' will run the Deployment Service in a command prompt so you can easily see any warnings/errors you are getting if it is not configured properly. You should run this with the LogLevel set to 'debug' in the config file so you can see if it is working correctly.

After you are happy the Deployment Service is working correctly in the test environment you should close the command prompt and start the PureCM Deployment Service windows service. You will see that the installer has installed the 'PureCM Deployment Service' service but it is not started. Any warning/errors will be shows in the event viewer when running the service.

4.4. Configuring the Deployment Server

To configure the PureCM Deployment Service you need to edit the 'PureCMDeployment.xml' file which has been installed to the location you specified in the installer. For convenience you can select 'All Programs | PureCM Deployment Service | Configure Deployment' from the Start menu to open this file in your default xml editor.

The elements of the xml (PureCMDeployment.xml) are described below. An example file is attached for you to download.

<Connection>

This is where you specify the PureCM Server details. Note that the Deployment Service can only deploy streams from one PureCM Server. If you need to deploy streams from multiple PureCM Servers then you will need to install multiple PureCM Deployment Services.

Attribute Description

server

Name or IP address of the PureCM server

port

Port number of PureCM server

username

Username of PureCM server

password

Password of PureCM server

  

<Links>

This is where you specify the PureCM stream and the FTP details for the upload. You can upload multiple streams to different ftp sites by creating multiple links. Each stream will have its own workspace.

Attribute Description

repository

The PureCM repository name

stream

The PureCM stream name 

workspace_path

The local path where a workspace will be created

ftp_name

Name or IP address of the ftp server

  ftp_type   'ftp' or 'sftp'
  ftp_path   The path in the ftp site to upload. If blank then the files will be uploaded to the root.
  ftp_port   The port which the ftp server is using
  ftp_username   An ftp user which has write access to the ftp site
  ftp_password   The password for the ftp user
  ftp_passive   Whether to use active ftp ('false') or passive ftp ('true')
  forcesync

  When this is 'true' all the files in the workspace will be uploaded to the ftp site on startup. This is useful as a one off if the ftp files have been changed outside of PureCM.

 

<Log>

When setting up the Deployment Service it is useful to get lots of deugging information about how the Deployment Service is working.

Attribute Description

level

Specify 'debug', 'info', 'warning', 'error' or 'none'. 'debug' provides the most logging information.

file 

Optionally specify a file where all logging information will be recorded. 

4.5. Testing the Deployment Service

You can test the Deployment Service by selecting 'All Programs | PureCM Deployment Service| Test Deployment' from the start menu.

 

This will launch a command prompt and run the Deployment Service. The advantage of running it in the console window is that all information/warning/error messages will be displayed.

We recommend that you begin by putting the LogInfo level to 'debug'. When you have fully configured the Deployment Service without any warnings or errors we then recommend you set the LogLevel to 'warning' and start the 'Deployment Service' windows service.

On Vista it may be necessary to open a Command Prompt as Administrator due to permissions. Simply cd to the install directory ('C:\Program Files\PureCM\Deployment') and run 'PureCMDeployment.exe'. This will mirror what the Test start menu operation performs.