KBEC-00034 - Pruning jobs from the database and workspace using Perl

Article ID:360033194891
3 minute readKnowledge base


As you run ElectricCommander over a long period of time, you may find that the number of jobs and workspace directories becomes cumbersome. The number of jobs may cause clutter that makes it difficult to pinpoint the jobs that you are really interested in. The number of workspace directories may fill up your disk capacity or slow down your file system access.

You can use Perl code to prune unused jobs from the database and disk.


  1. Create a Procedure and add the following Perl code to a step. This code is sample code that deletes jobs and their workspaces based on completed jobs with a particular project name and procedure name.

     use strict;
     use ElectricCommander;
     use File::Path;
     $| = 1;
     # Create a single instance of the Perl access to ElectricCommander
     my $ECommander;
     if (defined $ENV{COMMANDER_SERVER}) {
         $ECommander = new ElectricCommander->new();
     #  Demonstration version of main function
     #  Finds all previously completed job runs based on
     #       project name and procedure name
     #       Parameters
     #           cleanupProjectName      -   passed as a Commander parameter
     #           cleanupProcedureName    -   passed as a Commander parameter
         #  Assign Commander parameters to variables
         my $cleanupProjectName = "$[cleanupProjectName]";
         my $cleanupProcedureName = "$[cleanupProcedureName]";
         #  NOTE - Modify these filters if you want the "delete" based on
         #         different criteria, for example, the job age.
         #         You can also search on custom properties you put on the job.
         my @filterList;
         push (@filterList, {"propertyName" => "projectName",
                             "operator" => "equals",
                             "operand1" => "$cleanupProjectName"});
         push (@filterList, {"propertyName" => "procedureName",
                             "operator" => "equals",
                             "operand1" => "$cleanupProcedureName"});
         push (@filterList, {"propertyName" => "status",
                             "operator" => "equals",
                             "operand1" => "completed"});
         my ($success, $xPath) = InvokeCommander("SuppressLog", "findObjects", "job",
                                                 {filter => \@filterList });
         # Check for the OS Type
         my $osIsWindows = $^O =~ /MSWin/;
         # Loop over all returned jobs
         my $nodeset = $xPath->find('//job');
         foreach my $node ($nodeset->get_nodelist)
             #  Find the workspaces (there may be more than one if some steps
             #  were configured to use a different workspace)
             my $jobId = $xPath->findvalue('jobId', $node);
             my $jobName = $xPath->findvalue('jobName', $node);
             my ($success, $xPath) = InvokeCommander("SuppressLog", "getJobInfo",
             my $wsNodeset = $xPath->find('//job/workspace');
             foreach my $wsNode ($wsNodeset->get_nodelist) {
                 my $workspace;
                 if ($osIsWindows)
                     $workspace = $xPath->findvalue('./winUNC', $wsNode);
                     $workspace =~ s'/'\\'g;
                     $workspace = $xPath->findvalue('./unix', $wsNode);
                 # Delete the workspace (after checking its name as a sanity test)
                 # look for "job_nnn" or "Procedure-nnn"
                 if ($workspace =~ /[-_][\d]+$/)
                     use File::Path;
                     #  Remove the comment to actually delete the workspace
                     #### rmtree ([$workspace]);
                     print "Deleted workspace - $workspace\n";
             # Delete the job
             #  Remove the comment to actually delete the job
             #### InvokeCommander("SuppressLog", "deleteJob", $jobId);
             print "Deleted job - $jobName\n";
     #  Run an ElectricCommander function using the Perl API
     #  Params
     #       optionFlags - "AllowLog" or "SuppressLog" or "SuppressResult"
     #                     combined with "IgnoreError"
     #       commanderFunction
     #       Variable Parameters
     #           The parameters required by the ElectricCommander function
     #           according to the Perl API. See the ElectricCommander
     #           Help system for more information.
     #               (the functions and paramenter are based on "ectool" - run it for documentation)
     #  Returns
     #       success     - 1 if no error was detected
     #       xPath       - an XML::XPath object with the result.
     #       errMsg      - a message string extracted from Commander on error
     sub InvokeCommander {
         my $optionFlags = shift;
         my $commanderFunction = shift;
         my $xPath;
         my $success = 1;
         my $bSuppressLog = $optionFlags =~ /SuppressLog/i;
         my $bSuppressResult = $bSuppressLog || $optionFlags =~ /SuppressResult/i;
         my $bIgnoreError = $optionFlags =~ /IgnoreError/i;
         #  Run the command
         print "Request to Commander: $commanderFunction\n" unless ($bSuppressLog);
         $ECommander->abortOnError(0) if $bIgnoreError;
         $xPath = $ECommander->$commanderFunction(@_);
         $ECommander->abortOnError(1) if $bIgnoreError;
         # Check for error return
         my $errMsg = $ECommander->checkAllErrors($xPath);
         if ($errMsg ne "") {
             $success = 0;
         if ($xPath) {
             print "Return data from Commander:\n" .
                    $xPath->findnodes_as_string("/") . "\n"
                 unless $bSuppressResult;
         # Return the result
         return ($success, $xPath, $errMsg);
  2. Set the shell to "ec-perl" to call ElectricCommander’s Perl. (For Windows, this requires ElectricCommander version 3.0 or higher.)

  3. Modify the Perl code in the step above to set the filter parameters to your specific needs. For example, to specify a time range for the filter, use code similar to the following:

     push (@filterList, {"propertyName" => "finish",
                             "operator" => "between",
                             "operand1" => "2008-10-20T18:36:00.000Z",
                             "operand2" => "2008-10-20T18:38:00.000Z",
    Time is specified in UTC, not local time, and time must be specified using the exact UTC format, including the milliseconds and the Z.
  4. Run the procedure. As it is defined, nothing will be deleted, only a log of what it would do will be displayed.

  5. When the log looks OK, uncomment the lines that do the deletions.

EC-Admin Plugin

A plugin has been developed by one of our Sales Engineers, EC-Admin is available to assist in cleanup of jobs and workspaces. The plugin is available on our GitHub community, at:

Applies to

  • Product versions: ElectricCommander

  • OS versions: Linux and Windows