Debugging a UDP

Products

• CA Harvest Software Change Manager
• CA Harvest Software Change Manager - OpenMake Meister

Issue/Introduction

When you execute a User Defined Process (UDP) from SCM Workbench, and it fails or does not produce the result you were expecting, how is it possible to find the problem and fix it?

Environment

CA Harvest SCM all versions and platforms

Resolution

A User Defined Process is a process set up within a specific project and state that runs a command or script.  When your UDP is not working as expected, the first thing to do is find the properties for the UDP so that you can see what script or command it is executing. 

For example, in the example illustration below, when we right click on the "Development" state in the "SampleProject" project, we see an example process available called "My Test UDP".  Looking at the list of processes in the same project and state using the Administrator Tool, we can see the same example process defined there. 

To see the properties for the above example "My Test UDP" process, in the Administrator Tool right click on the process name and select "Properties" from the menu.

The properties window for the example "My Test UDP" looks like this:

Two important thing to notice are

• The "Program" field.  This will tell you the exact command or script the example "My Test UDP" is executing.  
• The "Type" field.  This will tell you if this command or script runs on the broker machine (Server) or on the machine where Workbench is running (Client).

In the above example, the command the UDP is running is

C:\Scripts\MyTestScript.bat [broker] [project] [state]

In the above example, C:\Scripts\MyTestScript.bat is the example custom script that is being run by the "My Test UDP" process, and the rest of the information in the Program field lists options or parameters (specific data values) being passed into the script.  (The "C:\Scripts\MyTestScript.bat" file in the above example is meant to be a placeholder.  Its contents aren't relevant except to demonstrate how to identify which user-developed script the UDP process is calling and where to find it.  "C:\Scripts\MyTestScript.bat" is just an example and you should substitute your script name and location there.)

If you see options or parameters in the Program field surrounded by square brackets, these are "Harvest System Variables".  They are not the operating system variables you would define outside of Harvest.  Instead these allow you to pass context-relevant information to the command or script such as the broker name, project or state, package, user, etc.  In the above example we are passing the broker name, the project name, and the state name into the script.

You should be able to execute the command or script you see in the Program field from a command prompt window.  If the "Type" field says "Server" it will run from a command prompt on the broker machine.  If the "Type" field says "Client" it will run on the machine where Workbench is running.  A good first test when diagnosing a problem with the UDP is to try to run it from the command prompt window, after substituting actual values for any "Harvest System Variables" specified on in the Program field.  For the above example, the command we will use to test is:

C:\Scripts\MyTestScript.bat <brokername> SampleProject Development

When I execute this example on my test system, I see:

In this example case the command worked as expected, but if, in your case the command the UDP is using does not work, the next step would be to locate the script and troubleshoot any problems it might be having.  For this you will need to have programming experience, or someone with this type of training to debug your script to find any problems and correct those.  When the script is able to run successfully from a command prompt window, try it from Workbench again to confirm the problem is resolved.

The above scenario is offered as an example only.  The name of your project, state, and UDP process, as well as the location and name of the script or command it calls will be different.

Additional Information

You can read more about User Defined Processes here:Define a User-Defined Process

You can read more about System Variables here: Use the System Variables