You are here: ectool and the Commander API > API Commands - listed by group and in alphabetical order > Miscellaneous Management

FAPI Commands - Miscellaneous Management


acquireNamedLock
changeOwner
clone
countObjects
deleteObjects
dumpHeap
dumpStatistics
export
findObjects
finishCommand
FAPI Commands - Miscellaneous Management
getObjects
graphStateMachine
import
releaseNamedLock

acquireNamedLock

Gets the named lock.

Arguments Descriptions
lockName

Name of the lock.

Argument type: String

create

<Boolean flag  - 0|1|true|false>

When this argument is set to true or 1, the system will create a lock if it does not exist.

Argument type: Boolean

Positional arguments

lockName, create

Response

None or a status OK message.

ec-perl

syntax:$cmdr->acquireNamedLock(<lockName>, <create>);

Example
$cmdr->acquireNamedLock ("Group2", true); 
ectool

syntax:ectool acquireNamedLock <lockName> <create>

Example
ectool acquireNamedLock "Group 2" true 

Back to Top

changeOwner

Changes the owner of an object.

You must specify an object name.

Note: The modify privilege on the "admin" system ACL is required to change the owner of an object.
For email notifiers, the owner can be changed if the current user has sufficient privileges to
delete and recreate the object.


Arguments Descriptions
applicationName

The name of the application.

Argument type: String

applicationTierName

The name of the application tier.

Argument type: String

componentName

The name of the component.

Argument type: String

configName

The name of the email configuration.

Argument type: String

credentialName

credentialName can be in one of these formats:

  • relative
    (for example, "cred1") - the credential is assumed to be in the project that contains the request target object. Requires a qualifying project name.
  • absolute
    (for example, "/projects/BuildProject/credentials/cred1") - the credential can be from any specified project, regardless of the target object’s project.

Argument type: String

environmentName

The name of an environment.

Argument type: String

environmentTierName

The name of an environment tier.

Argument type: String

groupName

The full name of a group. For Active Directory and LDAP, this is a full domain name.

Argument type: String

newOwnerName

The name of the new owner for this object. This defaults to the current user.

Argument type: String

notifierName

The name of the email notifier.

Argument type: String

pluginName

The name of the plugin. This is the plugin key for a promoted plugin or a plugin key and version for an unpromoted plugin.

Argument type: String

procedureName The name of the procedure. It can be a path to the procedure. When using this argument, you must also enter the projectName.

Argument type: String

processName

The name of a process. It can be a path to the process.

Argument type: String

processStepName

The name of a process step. It can be a path to the process step.

Argument type: String

projectName

The name of the project. It can be a path to the project. The project name is ignored for credentials, procedure, steps, and schedules when it is specified as a path.

Argument type: String

propertySheetId

The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

Argument type: UUID

resourceName

The name of the resource.

Argument type: String

scheduleName The name of the schedule. It can be be a path to the schedule. When using this argument, you must also use projectName.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

stepName

The name of the step. It can be a path to the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

transitionDefinitionName

The name of the transition definition.

Argument type: String

userName

The full name of the user. For Active Directory and LDAP, the name can be user@domain.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workspaceName

The name of the workspace.

Argument type: String

Positional arguments

None

Response

Returns the modified object.

ec-perl

syntax: $cmdr->changeOwner({...});

Example
$cmdr->changeOwner ({"projectName"=>"Sample Project"}); 
ectool

syntax: ectool changeOwner ...

Example
ectool changeOwner –-projectName "Sample Project" 

Back to Top

clone

Makes a copy of an existing ElectricCommander object. For example: credential, directory provider, email configuration, email notifier, project, procedure, property sheet, resource, resource pool, schedule, state definition, step, transition definition, workflow definition, and workspace.

Note: You cannot clone parameters.

IMPORTANT:
To find the entity you want to clone, you must specify the following arguments:
- A new name for the cloned object (cloneName)
- Locator arguments

For example, if you want to clone a project, you must specify the name of the project that you want to clone.


Arguments Descriptions
Naming
cloneName The cloneName specifies the path to the new object, possibly in an alternate location.
If no container path is specified, the new object is created inside the same container as the original.
If no name is specified, the server will generate a name.
Locators
applicationName

The name of the application that is unique among all projects.

Argument type: String

applicationTierName

The name of the application tier.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

artifactVersionName

The name of the artifact version.

Argument type: String

cloneName

The new name of the cloned copy of an object.

Argument type: String

componentName

The name of the component.

Argument type: String

configName

The name of the email configuration.

Argument type: String

credentialName

The name of the credential that can be specified in one of these formats:

relative
(for example, "cred1")–The credential is assumed to be in the project that contains the target object.

absolute(for example, "/projects/BuildProject/credentials/cred1")–Tthe credential can be from any specified project, regardless of the project with the target object.

Argument type: String

environmentName

The name of the environment that must be unique among all projects.

Argument type: String

environmentTierName

The name of the environment tier.

Argument type: String

gatewayName

The name of the gateway.

Argument type: String

groupName

The name of the group.

Argument type: String

jobId The unique Commander-generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template.

Argument type: UUID

jobStepId

The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

notifierName

The name of the email notifier.

Argument type: String

objectId

The object id as returned by findObjects.

Argument type: String

path

The property path for the object.

Argument type: String

pluginName

The name of the plugin.

Argument type: String

procedureName

The name of the procedure that you want to clone. When using this argument, you must also enter the projectName.

Argument type: String

processName

The name of the process.

Argument type: String

processStepName

The name of the process step.

Argument type: String

projectName

The name of the project that you want to clone.

Argument type: String

propertySheetId The unique identifier for a property sheet that is assigned automatically when the property sheet is created.
providerName

The unique name of the directory provider, such as the LDAP or Active Directory provider name.

Argument type: String

repositoryName

The name of the repository used for artifact management.

Argument type: String

resourceName

The name of the resource that you want to clone.

Argument type: String

resourcePoolName

The name of a pool containing one or more resources.

Argument type: String

scheduleName The name of the schedule that you want to clone. When using this argument, you must also enter projectName.

Argument type: String

snapshotName The name of the snapshot that you want to clone.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

stateName

The name of the state.

Argument type: String

stepName

The name of the step that you want to clone. When using this argument, you must also enter projectName and procedureName.

Argument type: String

systemObjectName

System object names include:

admin|artifacts|directory|emailConfigs|forceAbort|licensing|log|
plugins|priority|projects|repositories|resources|server|session|
workspaces|zonesAndGateways

Argument type: SystemObjectName

transitionDefinitionName

The name of the transition definition.

Argument type: String

transitionName

The name of the transition.

Argument type: String

userName

The name of the user where you may need to expand the string.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

workspaceName

The name of the workspace that you want to clone.

Argument type: String

zoneName

The name of the zone.

Argument type: String

Positional arguments

None.

Response

Returns the name of the new cloned object.

Using the clone command successfully depends on the context of the locator arguments in your system. The command works when the arguments are specified correctly.

 

ec-perl

syntax: $cmdr->clone ...;

Examples
# Create a copy of a procedure, as though you clicked the "Copy"
# button in the UI.

$xPath = $cmdr->clone(
    {  
        projectName => "EC-Examples",
        procedureName => "set Property"
    }
);
 
# Create a copy of a procedure providing a name for the copy.

$xPath = $cmdr->clone(
    {  
        projectName   => "EC-Examples",
        procedureName => "set Property",
        cloneName     => "set Property 2"
    }
);
 
# Create a copy of a procedure step.

$xPath = $cmdr->clone(
    {  
        projectName   => "EC-Examples",
        procedureName => "set Property",
        cloneName     => "set Property 2",
        stepName      => 'setProperty'
    }
);
# Copy a step using the path.

$xPath = $cmdr->clone(
    {  
        path =>
          '/projects/EC-Examples/procedures/set Property/steps/setProperty'
    }
);
ectool

syntax: ectool clone ...

Examples
# Create a copy of a procedure, as though you clicked the "Copy"
# button in the UI.

$ ectool clone --projectName 'EC-Examples' --procedureName 'set Property'
<response requestId="1" nodeId="192.168.16.238">
<cloneName>Set Property copy</cloneName>
</response>
# Create a copy of a procedure providing a name for the copy.

$ ectool clone --projectName 'EC-Examples' --procedureName 'set Property' --cloneName 'set Property 2' <response requestId="1" nodeId="192.168.16.238">
<cloneName>set Property 2</cloneName>
</response>
# Create a copy of a procedure step.

$ ectool clone --projectName 'EC-Examples' --procedureName 'set Property' --stepName 'setProperty <response requestId="1" nodeId="192.168.16.238">
<cloneName>setProperty copy</cloneName>
</response>
# Create a copy of a procedure step using the full path.

$ ectool clone --path '/projects/EC-Examples/procedures/set Property/steps/setProperty' <response requestId="1" nodeId="192.168.16.238">
<cloneName>setProperty copy</cloneName>
</response>

Back to Top

countObjects

Returns the count of objects specified by the provided filter.

You must enter objectType.

Arguments Descriptions
objectType

The type of object to count.

Values include:

artifact
artifactVersion
credential
directoryProvider
emailconfig
emailNotifier
formalParameter
job
jobStep
logEntry
plugin
procedure
procedureStep
project
property
repository
resource
resourcePool
schedule
state
stateDefinition
transition
transitionDefinition
workflow
workflowDefinition
workspace

Argument type: String

filter A list of zero or more filter criteria definitions used to define objects to find.

Each element of the filter list is a hash reference containing one filter criterion. You can specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the ElectricCommander Perl API.

Two types of filters:
"property filters" - used to select objects based on the value of the object's intrinsic or custom property

"boolean filters" ("and", "or", "not") - used to combine one or more filters using boolean logic.

Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by Commander or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property.

Property filter operators are:

between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual (1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)


A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter.

Boolean operators are:

not (1 operand)
and (2 or more operands)
or (2 or more operands)

Argument type: Collection

Positional arguments

objectType

Response

Returns the number of filtered objects.

ec-perl

syntax: $cmdr->countObjects(<objectType>, {<optionals>});

Example
use ElectricCommander();
my @artifactNameFilters; 
# Create the filter list for filtering on artifact name 
    push (@artifactNameFilters,
           {"propertyName"=>"artifactName",
                "operator"=>"contains",
                "operand1"=>"groupId:installer-windows",
           );                                                  
    my $cmdr = new ElectricCommander(); 
    # Perform the countObjects query
    my $reference=$cmdr->countObjects("artifactVersion",
         { filter=>
              {operator=>"and",
               filter=>[
                   { propertyName=>"modifyTime" ,
                     operator=>"greaterOrEqual",# Give me all dates after or equal arbinary date
                     "operand1"=>"2014-03-25T14:48:55.286Z",
                    }
                    ,
                    {
                     operator => 'or', # apply 'or' for the filters in the list
                     filter => \@artifactNameFilter


                    }
                   ]
          }
           });


my $jobs=$reference->find('//response/count');
print $jobs;


ectool

Not supported.

Back to Top

deleteObjects

Deletes objects specified by the provided filters.

Because of the complexity of specifying filter criteria, this API is not supported by ectool. However, all of its capabilities
are supported through the Perl API.

You must specify an objectType and at least one filter.

Note: Currently, this API supports deleting artifact, artifactVersion, job, logEntry, project, repository,
and workflow.


Arguments Descriptions
objectType This argument specifies the type of object to find.
Values include:
artifact|artifactVersion|job|logEntry|project|
repository|workflow

Argument type: String

filters Specify filters in a space-separated list: filter1 filter2 ...
A list of zero or more filter criteria definitions used to define objects to find.

Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the ElectricCommander Perl API.

Two types of filters:
"property filters" - used to select objects based on the value of the object's intrinsic or custom property
"boolean filters" ("and", "or", "not") - used to combine one or more filters using boolean logic.

Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by Commander or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property.

Property filter operators are:
between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual(1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)

A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter.

Boolean operators are:
not (1 operand)
and (2 or more operands)
or (2 or more operands)

Argument type: Collection

maxIds

<id count>
The maximum number of objects that will be deleted. The default is all objects that match the filter.

Argument type: Integer

sorts

Specify "sorts" in a space-separated list: sort1 sort2 ...

An ordered list of sort criteria. Each list entry consists of a property name and a sort order--either an ascending or descending sort order.

If you specify more than one sort criterion, the sorts are applied according to the order they appear in the list.

The first item in the list is the primary sort key.

Each item in the list is a hash reference.

See the code example below for instructions about forming the list and passing it to the Commander Perl API.

The sort order affects which objects are deleted if a maxIds value limits the number of objects returned by the filter.

Argument type: Collection

Positional arguments

objectType

Response

Returns a list of object references.

ec-perl

syntax: $cmdr->deleteObjects(<objectType>, {<optionals>});

Example

This code example illustrates using a Boolean filter for the deleteObjects command to find jobs matching
either of two patterns for the job name.


 my @filterList; 
 push (@filterList, {"propertyName" => "jobName",
                         "operator" => "like",
                         "operand1" => "%-branch-%"});
 push (@filterList, {"propertyName" => "jobName",
                         "operator" => "like",
                         "operand1" => "branch-%"}); 
 my $result = $cmdr->deleteObjects('job',
       {filter => [
    { operator => 'or',
        filter => \@filterList,
    }
  ]}
);
print "result = " . $result-> findnodes_as_string("n"). "\n";
ectool

Not supported.

Back to Top

dumpHeap

Captures a Java heap dump.

Arguments Descriptions
fileName

Name of the file to which the heap dump is written.

Argument type: String

Positional arguments

fileName

Response

None or a status OK message.

ec-perl

syntax:$cmdr->dumpHeap (<fileName>);

Example
$cmdr->dumpHeap ('$[/myWorkspace/data]/$[JavaFileName]'); 
ectool

syntax:ectool dumpHeap <fileName>

Example
ectool dumpHeap '$[/myWorkspace/data]/$[JavaFileName]' 

Back to Top

dumpStatistics

Prints (emits) internal timing statistics.



Arguments Descriptions
clearStatistics

<Boolean flag  - 0|1|true|false>

If this argument is set to true, the system clears the statistics after logging them.

Argument type: Boolean

dumpLapTimes

<Boolean flag  - 0|1|true|false>

If this argument is set to true, the system dumps lap times.

If this argument is set to false, the system dumps global times.

Argument type: Boolean

fileName

If you specify a file name with a path, the output is redirected to this file.

When the path is relative, the file is written relative to the working directory of the server.

Argument type: String

format

Format of the output.

Valid values are text or xml.

The default is text.

Argument type: String

Positional arguments

None

Response

None or a status OK message.

ec-perl

syntax:$cmdr->dumpStatistics ({<optionals>);

Example
$cmdr->dumpStatistics ({clearStatistics=>true, format=>xml}); 
ectool

syntax:ectool dumpStatistics [<optionals> ... ]

Example
ectool dumpStatistics --clearStatistics true --format xml

Back to Top

evalDsl

Evaluates an ElectricCommander DSL script.

Arguments Descriptions
dsl

The DSL text.

Argument type: String

Positional arguments

dsl

Response

None or a status OK message.

ec-perl

syntax:$cmdr->evalDsl(<dsl>);

Example
$cmdr->evalDsl ("Interoperability performance test cases"); 
ectool

syntax:ectool evalDsl <dsl>

Example
ectool evalDsl "Interoperability performance test cases" 

Back to Top

export

Exports part or all server data to an XML file. By default, all data in the system is exported, although the "path"
option can be used to limit the output to a single tree of objects.

If a relative file name is specified, the file is created relative to the ElectricCommander server's data directory, which
by default is located:

For Windows:   C:\Documents and Settings\All Users\Application Data\Electric Cloud\
            ElectricCommander

For Linux:  /opt/electriccloud/electriccommander


You must specify a fileName.

The default timeout is 10800 seconds (180 minutes or 3 hours).

Note: A full export/import preserves job IDs, but a partial import preserves names only, not IDs.


Arguments Descriptions
fileName

<remoteFileName> The specified directory for the file must already exist in the system. If the path is local, it will be created on the server. If it is a network path, it must be accessible by the server and the server user.

Argument type: String

compress

<Boolean flag - 0|1|true|false>  Use this argument to compress XML output. If set to 1, the file will be compressed using the “gzip” format and a “.gz” file extension will be added to the filename. The default behavior is to compress the output.

Note: This is true for full exports only, not a partial export.

Argument type: Boolean

excludeJobs

<Boolean flag - 0|1|true|false> If set to 1, no job information will be exported. This argument can be used to reduce the size of the export file.

Argument type: Boolean

path

<property path>  Specifies the path for an object to be exported. Any single object can be exported if it is specified using property path syntax. The object and its sub-objects are exported.

Argument type: String

relocatable

<Boolean flag - 0|1|true|false>   If the --relocatable flag is set to "true", a partial export (for example, with --path) will not include object IDs, ACLs, system property sheets, create/modify times, owners, email notifiers or lastModifiedBy information, and the export file result will be much smaller than a normal export. When this file is imported, the result should show one or more objects owned by the importing user as if they were newly created.

Note: The relocatable argument only works with a partial export. This argument is silently ignored during a full export.

Argument type: String

safeMode The safeMode argument determines whether the server will be quiesced before a full export begins and if yes, whether or not the server will shutdown and  restarted after the export completes. Values are:
  • none (default) - Do not quiesce the server during export.
  • shutdown - Quiesce the server and shutdown when complete.
  • restart - Quiesce the server and restart when complete.

Note: The safeMode argument has no effect on partial exports.

Argument type: SafeMode

withAcls

This argument modifies relocatable.  
<Boolean flag  - 0|1|true|false>  If the withAcls flag is set to "true", a relocatable partial export will include ACLs.

Argument type: Boolean

withNotifiers

This argument modifies relocatable.
<Boolean flag  - 0|1|true|false> If the withNotifiers flag is set to "true", a relocatable partial export will include email notifiers.

Argument type: Boolean

Positional arguments

fileName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->export(<fileName>, {<optionals>});

Examples
$cmdr->export("c:\CommanderBackup\Mar 15 2007.xml");

$cmdr->export("c:\CommanderBackup\Test Proj.xml", 
                     {path => "/projects[Test Proj]",
               relocatable => "true", 
             withNotifiers => "true"});
ectool

syntax: ectool export <fileName> ...

Examples
ectool export "c:\CommanderBackup\Mar 15 2007.xml"

ectool export "c:\CommanderBackup\Test Proj.xml" --path "/projects[Test Proj]"
   --relocatable true --withNotifiers true

Back to Top

findObjects

This command returns a sorted list of Commander objects based on an object type and a set of filter
criteria. This API can be used to find many, but not all, types of Commander objects and is used by the
Commander web interface to implement the Commander "Search" feature.

Because of the complexity of specifying filter criteria, this API is not supported by ectool. However, all
of its capabilities are supported through the Perl API.

You must specify an objectType.


Arguments Descriptions
objectType The type of object to find.
Values include:
application
artifact
artifactVersion
component
credential
directoryProvider
emailconfig
emailNotifier
environment
formalParameter
job
jobStep
logEntry
plugin
procedure
procedureStep
process
processStep
project
property
repository
resource
resourcePool
schedule
state
stateDefinition
transition
transitionDefinition
workflow
workflowDefinition
workspace

Argument type: String


filters A list of zero or more filter criteria definitions used to define objects to find.

Each element of the filter list is a hash reference containing one filter criterion. You can specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the ElectricCommander Perl API.

Two types of filters:
"property filters" - used to select objects based on the value of the object's intrinsic or custom property

"boolean filters" ("and", "or", "not") - used to combine one or more filters using boolean logic.

Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by Commander or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property.

Property filter operators are:

between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual (1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)


A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter.

Boolean operators are:

not (1 operand)
and (2 or more operands)
or (2 or more operands)

Argument type: Collection

includeAccess <Boolean flag - 0|1|true|false> If set to true, this command also returns access maps for the objects.

Argument type: Boolean

includeLatestRevision <Boolean flag - 0|1|true|false> If set to true, this command also returns the latest revision data for versioned objects.

Argument type: Boolean

maxIds

<id count>
The maximum number of object IDs that will be returned. If omitted, default behavior returns IDs for the first 1000 objects matching the query. If "0" is specified, the ID of every matching object is returned.

Argument type: Integer

numObjects

<full object count>
Specifies the number of full objects (not just the IDs) returned from the findObjects request. This option allows selecting a limited number of full objects to be returned in the initial request. The returned "full objects" correspond to the objects from the beginning of the list of object IDs. If numObjects is not specified, all full objects in the list of object IDs are returned. Any and all objects can be retrieved using the getObjects command.

Argument type: Integer

selects

This is an unordered list of property names that specify additional top-level properties to return for each object. See the code example below for instructions on forming the list and passing it to the ElectricCommander Perl API.

Argument type: Collection

sorts

This is an ordered list of sort criteria. This option works only when you specify a property name.

Each list entry consists of a property name and a sort order—either an ascending or descending sort order.

If you specify more than one sort criterion, the sorts are applied according to the order they appear in the list. The first item in the list is the primary sort key. Each item in the list is a hash reference.

See the code example below for instructions on forming the list and passing it to the ElectricCommander Perl API.

Argument type: Collection

Positional arguments

objectType

Response

This command returns a list of object references. These references can be used in a subsequent call to the
getObjects command. The command can also return full objects from the result list.

ec-perl

syntax: $cmdr->findObjects(<objectType>, {<optionals>});

Example 1

This example shows how to use a Boolean filter for the findObjects command to find jobs matching either
of two patterns for the job name.

my @filterList;
push (@filterList, {"propertyName" => "jobName",
                        "operator" => "like",
                        "operand1" => "%-branch-%"});
push (@filterList, {"propertyName" => "jobName",
                        "operator" => "like",
                        "operand1" => "branch-%"});
my $result = $cmdr->findObjects('job',
        {filter => [
     { operator => 'or',
         filter => \@filterList,
    }
  ]}
);
print "result = " . $result->findnodes_as_string("/"). "\n";

Example 2

This example uses findObjects and getObjects to manage large result sets, and also uses
select to return the values of two properties in the returned objects.

# Search for the first 10 matching objects and retrieve the first 2
my $xPath = $cmdr->findObjects("schedule",
        {maxIds    => "10",
        numObjects => "2",
           filter  => [{propertyName => "createTime",
                        operator => "greaterOrEqual",
                        operand1 => "2007-01-20T00:00:00.000Z"},
                   {propertyName => "lastModifiedBy",
                        operator => "like",
                        operand1 => "adm%"}],
          sort => [{propertyName => "projectName",
                           order => "ascending"},
                   {propertyName => "createTime",
                           order => "descending"}],
        select => [{propertyName => 'prop1'},
                      {propertyName => 'prop2'}]
        });
print "Return data from Commander:\n" . $xPath-> findnodes_as_string("/"). "\n";
# Build a list of all the object id's
my @allObjectsList;
my $nodeset = $xPath->find('//response/objectId');
foreach my $node ($nodeset->get_nodelist)
        {
        my $objectId = $node-> string_value();
        push (@allObjectsList, $objectId);
        }
# Retrieve the second 2 objects
my @objectList = @allObjectsList[2..3];
$xPath = $cmdr->getObjects(
        {objectId => \@objectList});
print "Return data from Commander:\n" . $xPath->findnodes_as_string("/"). "\n";

Example 3

This example shows how to make filters with or and and for finding artifacts matching either of two
patterns for the artifact name and modifyTime before a specified date.

# Create the filter list for filtering on artifact name. 
my @artifactNameFilters; 
    push (@artifactNameFilters,
           {"propertyName" => "artifactName",
                "operator" => "equals",
                "operand1" => "groupId:installer-windows"},
             {propertyName => "artifactName",
                  operator => "equals",
                  operand1 => "groupId:installer-linux"
           }); 
    # Perform the findObjects query
    my $result = $cmdr->findObjects('artifactVersion',
         {filter =>
              {operator => "and", # 'and' the different filters below
                 filter => [
                   #filter 1
                   {
                       propertyName => "modifyTime",
                           operator => "lessOrEqual", # Give me all dates before
                           operand1 => "2011-11-10T00:00:00.000Z" # Arbitrary date
                   },
                   #filter 2
                   {
                       operator => 'or', # apply 'or' for the filters in the list
                         filter => \@artifactNameFilters
                   }
               ]
              }
         }
     );
    print "result = " . $result-> findnodes_as_string("/") . "\n"; 
    # Top-level filters are implicitly 'and'ed, so the above findObjects query 
    # could also be written like this: 
    $result = $cmdr->findObjects('artifactVersion',
           {filter => [
              #filter 1
              {
                  propertyName => "modifyTime",
                      operator => "lessOrEqual", # Give me all dates before
                      operand1 => "2011-11-10T00:00:00.000Z" # Arbitrary date
              },
              #filter 2
              {
                  operator => 'or', # apply 'or' for the filters in the list
                    filter => \@artifactNameFilters
              }
          ]
         }
     );

 

Example 4

This example shows how to find a project with a name containing "foo" and with the description "bar".

$commander->findObjects('project', {
    filter => {operator => 'and',
	filter => [{propertyName => 'projectName',
	    operator     => 'contains',
	    operand1     => 'foo'},
	   {propertyName => 'description',
	    operator     => 'equals',
	    operand1     => 'bar'}]}});

Example 5

This example shows how to find a procedure with the project name "foo" and with the procedure name "bar" or not "bat". (The top level filters are implicitly combined with "and".)

$commander->findObjects('procedure', {
    filter => [{propertyName => 'projectName',
	operator     => 'equals',
 	operand1     => 'foo'},
      {operator => 'or',
       filter   => [{propertyName => 'procedureName',
		operator     => 'equals',
		operand1     => 'bar'},
	       {operator     => 'not',
		filter       => {propertyName => 'procedureName',
			operator     => 'equals',
			operand1     => 'bat'}}]}]});

Example 6

This example shows how to find a project with certain property values.

$commander->findObjects("project", {
    filter => {operator => 'or',
	filter => [{propertyName => 'prop1',
		operator     => 'equals',
		operand1     => 'value1'},
	    {propertyName => 'prop2',
		operator     => 'equals',
		operand1     => 'value2'},
	    {propertyName => 'prop3',
		operator     => 'isNull'}]}
ectool

Not supported.

Back to Top

finishCommand

The agent uses this command to indicate that a command has been run.

Arguments Descriptions
agentRequestId

Request ID of the command.

Argument type: String

status

Status of the command.

Argument type: Integer

deletedLogFile

<Boolean flag - 0|1|true|false>

 If this argument is set to 1 or true, the agent is deleted or the step log file is not created.

Argument type: Boolean

deletedPostpLogFile

<Boolean flag - 0|1|true|false>

 If this argument is set to 1 or true, the agent is deleted or the postp log file is not created.

Argument type: Boolean

elapsedTime

Elapsed time that the command runs.

Argument type: Double

errorMessage

Error message from the agent.

Argument type: String

exit

Exit code of the command.

Argument type: Integer

maxProtocolVersion

Maximum protocol version that the agent supports.

Argument type: Integer

minProtocolVersion

Minimum protocol version that the agent supports.

Argument type: Integer

pingToken

Current ping token.

Argument type: Long

postpExit

Exit code of postp.

Argument type: Integer

protocolVersion

Current agent protocol version.

Argument type: Integer

version

Current agent version.

Argument type: String

Positional arguments

agentRequestId, status

Response

None or a status OK message.

ec-perl

syntax examples:  $cmdr->finishCommand (<agentRequestId>, <status>, {<optionals>});

Examples
$cmdr->finishCommand ("30f14c6c1fc85cba12bfd093aa8f90e3", 1);
ectool

syntax examples: ectool finishCommand <agentRequestId> <status> [optionals...]

Examples
ectool finishCommand "30f14c6c1fc85cba12bfd093aa8f90e3", 1

Back to Top

getObjects

The getObjects command retrieves a list of full objects based on object IDs returned by findJobSteps or
findObjects. All requested objects must be of the same objectType. See findObjects for a list of object types.

You must specify objectIds.


Arguments Descriptions
objectIds

A list of one or more object IDs that were returned by a prior call to findObjects. Each list element is a string containing the ID. See the code example below for instructions on forming the list and passing it to the Commander Perl API.

Argument Type: Collection

includeAccess <Boolean flag - 0|1|true|false> If set to true, this command also returns access maps for the objects.

Argument type: Boolean

includeLatestRevision <Boolean flag - 0|1|true|false> If set to true, this command also returns the latest revision data for versioned objects.

Argument type: Boolean

selects

This is an unordered list of projection definitions. Each list entry consists of a property name identifying a top-level custom property to return in addition to the rest of the object elements. See the code example below for instructions on forming the list and passing it to the Commander Perl API.

Argument type: Collection

Positional arguments

objectIds

Response

A list of full objects for the requested type.

ec-perl

syntax: $cmdr->getObjects({<optionals>});

Example 1

Code example for findObjects and getObjects:

# This example runs within a Commander step, so a "login" is not needed.
use strict;
use ElectricCommander;
my $cmdr = ElectricCommander->new();

# Search for the first 10 matching objects and retrieve the first 2
my $xPath = $cmdr->findObjects("schedule",
        {maxIds    => "10",
        numObjects => "2",
        filter => [{propertyName => "createTime",
                        operator => "greaterOrEqual",
                        operand1 => "2010-01-20T00:00:00.000Z"},
                   {propertyName => "lastModifiedBy",
                        operator => "like",
                        operand1 => "adm%"}],
          sort => [{propertyName => "projectName",
                           order => "ascending"},
                   {propertyName => "createTime",
                           order => "descending"}],
        select => [{propertyName => 'prop1'},
                   {propertyName => 'prop2'}]
        });
print "Return data from Commander:\n" . $xPath-> findnodes_as_string("/"). "\n";
# Build a list of all the object id's
my @allObjectsList;
my $nodeset = $xPath->find('//response/objectId');
foreach my $node ($nodeset->get_nodelist)
        {
        my $objectId = $node-> string_value();
        push (@allObjectsList, $objectId);
        }
# Retrieve the second 2 objects
my @objectList = @allObjectsList[2..3];
$xPath = $cmdr->getObjects(
        {objectId => \@objectList});
print "Return data from Commander:\n" . $xPath-> findnodes_as_string("/") . "\n";

Example 2

Code example using a Boolean filter:

my $xpath = $N->findObjects('project', {
        filter => {operator => 'and',
               filter => [{propertyName => 'projectName',
                               operator => 'contains',
                               operand1 => $projectBase},
                          {propertyName => 'description',
                               operator => 'equals',
                               operand1 => 'foo'}]}});
ectool

Not supported.

Back to Top

graphStateMachine

Generates a graph element with a state machine DOT graph as CDATA content.

You must specify a jobId .

Arguments Descriptions
jobId

The unique Commander-generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template.

Argument type: UUID

cluster

<Boolean flag - 0|1|true|false>

 If this argument is set to 1 or true, the graphs are clustered.

Argument type: Boolean

Positional arguments

jobId

Response

CDATA content.

ec-perl

syntax examples:  $cmdr->graphStateMachine (<jobId>, ({<optionals>});

Examples
$cmdr->graphStateMachine (jobId => 5da765dd-73f1-11e3-b67e-b0a420524153);
ectool

syntax examples: ectool graphStateMachine <jobId> ...

Examples
ectool graphStateMachine 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

import

Imports data from an XML export file.

You must specify either file or fileName.

The default timeout is 10800 seconds (180 minutes or 3 hours).

Note: A full export/import preserves job IDs, but a partial import preserves names only, not IDs.
Use the preserveId option for a partial import if you need to retain the same (existing) job or workflow ID number.

Arguments Descriptions
fileName

Name of the file to import:

<remoteFileName> This is the name of a file on the server to import. The file path name must be accessible to the server process on the server host.

<localFileName>  This is the path to a file on the client to import.
The file is uploaded from the client to the server. The specified <file> value is sent as an attachment to the import API request. The server detects the presence of the attachment and reads the attached file instead of looking for a file on the server. The maximum file size specified by file is determined by the maximum upload-size server setting.
By default the limit is 50MB, so this option should be used only for individually exported objects, not a full system export.

Argument type: String

batchSize

<batch size>  The number of objects imported before committing a transaction in the database. This argument limits the object batch size during import. Default value is 50 objects. If your objects are unusually large, you can throttle this number down to 1, depending on your available memory.

Note: The batchSize argument applies only to full import operations.

Argument type: Integer

disableSchedules

<Boolean flag - 0|1|true|false>  If set to 1, imported schedules will be disabled. This argument can modify imported schedules after import and before they are used to start a job.

Argument type: Boolean

force

<Boolean flag - 0|1|true|false> If set to true, an existing object is replaced during a single-object import. This argument can be used to replace a single object if it already exists at the specified property path.

Argument type: Boolean

path

<property path>  Use this argument to import a single object to a new location. For example, if a procedure was exported from "project A", this argument allows you to import it into "project B", but only if the export also used the path option.

Argument type: String

preserveId

<Boolean flag - 0|1|true|false> If set to true, this command tries to preserve the objectID during a single-object import. If you are doing a partial import, using this option preserves the original job ID or workflow ID.

Argument type: Boolean

Positional arguments

fileName

Response

None or a status OK message.

ec-perl

syntax examples:  $cmdr->import(<fileName>, {...});

$cmdr->import({file => <localFileName>, ...);

Examples
$cmdr->import("/opt/TestProg.xml");
 
$cmdr->import({file => "c:\r.xml", path => "/projects[Test]");
ectool

syntax examples:  ectool import <remoteFileName> ...

          ectool import <localFileName>

Examples
ectool import /mnt/backups/fullBackkup.xml

ectool "c:\project.xml" --path "/projects[Test]"

Back to Top

logStatistic

Prints (emits) a statistics value to StatsD.

Arguments Descriptions
name

The name of the statistic.

Argument type: String

type

The type of statistic.

Argument type: StatisticType

value

The value of the statistic.

Argument type: Long

Positional arguments

name, type, value

Response

None or a status OK message.

ec-perl

syntax:$cmdr->logStatistic (<name>, <type>, <value>);

Example
$cmdr->logStatistic("Interoperability performance test cases", "counters", 7); 
ectool

syntax:ectool logStatistic <name> <type> <value>

Example
ectool logStatistic "Interoperability performance test cases" "counters" 7

Back to Top

releaseNamedLock

Releases the named lock that synchronizes the name of an object.

Arguments Descriptions
lockName

Name of the lock.

Argument type: String

delay

Number of seconds to delay releasing the lock.

Argument type: Integer

Positional arguments

lockName

Response

None or a status OK message.

ec-perl

syntax examples:  $cmdr->releaseNamedLock (<lockName>, {<optionals>});

Examples
$cmdr->releaseNamedLock ("group1", {delay => 5});
ectool

syntax examples: ectool releaseNamedLock <lockName> [optionals...]

Examples
ectool releaseNamedLock "group1" --delay 5

Back to Top

of