Miscellaneous Management

acquireNamedLock

Retrieves the named lock.

Arguments Descriptions

lockName

Name of the lock.

Argument type: String

create

< Boolean flag0|1|true|false >

When this argument is set to true or 1, the system creates 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

changeOwner

Changes the owner of an object.

You must specify an object name. You must also specify the new owner name if it is not the current user.

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

(Optional) The name of the application.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) 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

dashboardName

(Optional) The name of a dashboard.

Argument type: String

environmentName

(Optional) The name of an environment.

Argument type: String

environmentTemplateName

(Optional) The name of an environment template.

Argument type: String

environmentTierName

(Optional) The name of an environment tier.

Argument type: String

groupName

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

Argument type: String

newOwnerName

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

Argument type: String

notifierName

(Optional) The name of the email notifier.

Argument type: String

pluginName

(Optional) 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

(Optional) 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

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

Argument type: String

processStepName

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

Argument type: String

projectName

(Optional) 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

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

Argument type: UUID

reportName

(Optional) The name of a report.

Argument type: String

reportObjectTypeName

(Optional) The name of a report object type.

Argument type: String

resourceName

(Optional) The name of the resource.

Argument type: String

scheduleName

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

Argument type: String

serviceName

(Optional) The name of the service.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stepName

(Optional) 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

(Optional) The name of the transition definition.

Argument type: String

userName

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

Argument type: String

widgetName

(Optional) The name of a widget.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workspaceName

(Optional) The name of the workspace.

Argument type: String

Positional arguments

None

Response

Returns the modified object.

ec-perl

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

Examples

The following example changes the owner of the default project to the current user:

$cmdr->changeOwner ({"projectName" => "Default"});

The following example changes the owner of a project named Q2Release to a new owner named hjindal:

$cmdr->changeOwner ({"newOwnerName" => "hjindal", "projectName" => "Q2Release"});

ectool

syntax: ectool changeOwner [optionals]

Examples

The following example changes the owner of the default project to the current user:

ectool changeOwner –-projectName "Default"

The following example changes the owner of a project named Q2Release to a new owner named hjindal:

ectool changeOwner --newOwnerName "hjindal" –-projectName "Q2Release"

clone

Makes a copy of an existing CloudBees CD object.

You cannot clone parameters, artifacts, or artifact versions.
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 the objects that can be cloned 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

(Optional) New name of the cloned copy of an object. 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.

Argument type: String

Optionals

disableProjectTracking

(Optional) < Boolean flag0|1|true|false >

If set to true, when copying a project, even if Change Tracking is enabled for the original project, Change Tracking is disabled for the new copy of the project from its creation.

If you do not need to track changes for the new copy, this avoids the Change Tracking overhead that would otherwise slow down the copying operation, and also saves having to subsequently disable Change Tracking for the new copy of the project.

Argument type: Boolean

reducedDetailChangeHistory

(Optional) < Boolean flag0|1|true|false >

Use this argument for large projects containing over 20,000 audited objects with Change Tracking enabled.

When this argument is set to true or 1, CloudBees CD automatically decreases the amount of Change History indexing information that it saves in a large project, which reduces the level of detail for Change Tracking-intensive operations in the change history. This can make it harder to revert an object to a specific state and to find information in the change history when you troubleshoot or debug an issue.

Set this argument to false or 0 to suppress this behavior so that CloudBees CD does not change the amount of indexing information for a large project. This causes the operation to take longer and put more load on the database, but the change history will have the full details of the entities owned by objects in the project.

Argument type: Boolean

Locators

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration ( emailConfig ).

Argument type: String

credentialName

(Optional) 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)—The credential can be from any specified project, regardless of the project with the target object.

Argument type: String

environmentName

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

Argument type: String

environmentTemplateName

(Optional) The name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) Name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) Name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

Name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

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

Argument type: UUID

notifierName

(Optional) The name of the email notifier ( emailNotifier ).

Argument type: String

objectId

(Optional) The object id as returned by findObjects.

Argument type: String

path

(Optional) The property path for the object.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin.

Argument type: String

procedureName

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

Argument type: String

processName

(Optional) The name of the process.

Argument type: String

processStepName

(Optional) The name of the process step.

Argument type: String

projectName

(Optional) The name of the project that you want to clone.

When an application, a pipeline, or a release is cloned across different projects, you might need to fix the references after the objects are cloned. For example, if a pipeline with an application reference in the "default" project is cloned to a different project, the application reference needs to be fixed after the pipeline is cloned.

Argument type: String

propertySheetId

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

providerName

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

Argument type: String

releaseName

(Optional) The name of the Release which owns the property.

Argument type: String

repositoryName

(Optional) The name of the repository used for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource that you want to clone.

Argument type: String

resourcePoolName

(Optional) The name of a resource pool.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

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

Argument type: String

snapshotName

(Optional) The name of the snapshot that you want to clone.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

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

Argument type: String

systemObjectName

(Optional) System object names include:

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

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

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

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace that you want to clone.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

None.

To clone an existing entity, you must specify the following arguments:

  • A new name for the cloned object ( cloneName )

  • Locator arguments for the objects that can be cloned

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 ({<optionals>});

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 [optionals]

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'     Set Property copy
# Create a copy of a procedure providing a name for the copy.$ ectool clone --projectName 'EC-Examples' --procedureName 'set Property'
--cloneName 'set Property 2'
    set Property 2
# Create a copy of a procedure step.$ ectool clone --projectName 'EC-Examples' --procedureName 'set Property'
--stepName 'setProperty
    setProperty copy
# Create a copy of a procedure step using the full path.$ ectool clone --path '/projects/EC-Examples/procedures/set Property/steps/setProperty'
    setProperty copy

countObjects

Returns the count of objects specified by the provided filter.

You must enter objectType.

Arguments Descriptions

objectType

The type of object to count.

application

process

applicationTier

processDependency

artifact

processStep

artifactVersion

project

component

property

credential

release

deployerApplication

repository

deployerConfiguration

resource

directoryProvider

resourcePool

emailConfig

resourceTemplate

emailNotifier

schedule

environment

snapshot

environmentTemplate

stage

environmentTemplateTier

state

environmentTier

stateDefinition

formalParameter

task

job

tierMap

jobStep

transition

logEntry

transitionDefinition

pipeline

workflow

plugin

workflowDefinition

procedure

workspace

procedureStep

Argument type: String

filter

(Optional) 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 CloudBees CD 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 CloudBees CD 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.

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.

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

(Optional) 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 CloudBees CD 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 CloudBees CD 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

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

Argument type: Integer

sorts

(Optional) 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 CloudBees CD 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.

describeObject

Returns a list of intrinsic properties for an object.

You must specify an objectName.

Arguments Descriptions

objectName

Specifies the name of the object.

Argument type: String

Positional arguments

objectName

Response

Returns a list of intrinsic properties for the object.

ec-perl

syntax: $cmdr->describeObject (<objectName>);

Example

$cmdr->describeObject application

ectool

syntax: ectool describeObject <objectName>

Example

ectool describeObject application

describeObjectTypeStructure

Returns the CloudBees CD object structure of top-level objects including all nested objects, parameters, and custom properties, subject to arguments passed in with the command. If not specified, the entire object structure is returned.

Use information returned from this command to aide in constructing arguments for generateDsl . See Using the CloudBees CD DSL for more information.

Arguments Descriptions

includeChildrenWithFileRef

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or true, include file references for child elements in the returned structure.

Argument type: Boolean

objectType

(Optional) Return the object structure for objectType.

topLevelOnly

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or true, return just top-level objects, subject to objectType.

Argument type: Boolean

Positional arguments

None.

Response

Returns the specified CloudBees CD object structure as a structed set of <objectType> elements.

ec-perl

syntax: $cmdr->describeObjectTypeStructure (<optionals>);

Example

Return the object structure for pipelines:

$cmdr->describeObjectTypeStructure ({objectType=>pipeline});

ectool

syntax: ectool describeObjectTypeStructure <optionals>

Example

Return the object structure for pipelines:

ectool describeObjectTypeStructure --objectType pipeline

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]'

dumpStatistics

Prints (emits) internal timing statistics.

Arguments Descriptions

clearStatistics

(Optional) < Boolean flag0|1|true|false >

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

Argument type: Boolean

dumpLapTimes

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or true, the system dumps lap times. If this argument is set to 0 or false, the system dumps global times.

Argument type: Boolean

fileName

(Optional) 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

(Optional) Format of the output.

Valid values are text or xml.

The default is .

Argument type: String text

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

evalDsl

Evaluates and runs a CloudBees CD domain-specific language (DSL) script.

You must enter either the dsl or the dslFile argument.

Arguments Descriptions

dsl

The DSL text.

Either dsl or dslFile must be specified.

Argument type: String

dslFile

Path to the file on the client containing the DSL script.

Either dsl or dslFile must be specified.

Argument type: String

applicationName

(Optional) Name of the application.

Argument type: String

applicationTierName

(Optional) Name of the application tier.

Argument type: String

artifactName

(Optional) Name of the artifact.

Argument type: String

artifactVersionName

(Optional) Name of the artifact version.

Argument type: String

componentName

(Optional) Name of the component.

Argument type: String

configName

(Optional) Name of the email configuration.

Argument type: String

credentialName

(Optional) Name of the credential.

Argument type: String

debug

(Optional)

< Boolean flag0|1|true|false >

If this argument is set to true or 1, CloudBees CD generates debug output as the DSL script is evaluated.

Argument type: Boolean

describe

(Optional)

< Boolean flag0|1|true|false >

If this argument is set to true or 1, CloudBees CD prints a description of the DSL text.

Argument type: Boolean

environmentName

(Optional) Name of the environment.

Argument type: String

environmentTemplateName

(Optional) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) Name of the environment tier.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

flowTransitionName

(Optional) The name of the flow transition.

Argument type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group.

Argument type: String

jobId

(Optional) The primary key or name of the job.

Argument type: UUID

jobStepId

(Optional) The primary key or name of the job step.

Argument type: UUID

notifierName

(Optional) The name of the notifier.

Argument type: UUID

objectId

(Optional) The object ID returned by the findObjects call.

Argument type: UUID

overwrite

(Optional)

< Boolean flag0|1|true|false >

If this argument is set to true or 1, clear elements under the root element that don’t already exist in dsl or dslFile. If not specified, 0 | false is used–do not clear elements.

Argument type: Boolean

parameters

(Optional) Parameters are passed to the script by CloudBees CD as JSON text.

Argument type: String

parametersFile

(Optional) Path to the file on the client containing parameters as JSON text that should be passed to the DSL script by CloudBees CD .

Argument type: String

path

(Optional) The property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin.

Argument type: String

procedureName

(Optional) The name of the procedure.

Argument type: String

processName

(Optional) The name of the process if the container is a process or process step.

Argument type: String

processStepName

(Optional) The name of the process step if the container is a process step.

Argument type: String

projectName

(Optional) The name of the project.

Argument type: String

propertySheetId

(Optional) The primary key or name of the property sheet.

Argument type: UUID

releaseName

(Optional) The name of the Release.

Argument type: String

repositoryName

(Optional) The name of the repository.

Argument type: String

resourceName

(Optional) The name of the resource.

Argument type: String

resourcePoolName

(Optional) The name of the resource pool.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule.

Argument type: String

serverLibraryPath

(Optional) Path to the server directory that contains .jar files and classes to be added to the classpath when evaluating the DSL text.

Argument type: String

sessionPassword

(Optional)The session user’s password that is used to reverify the user’s identity before changing user passwords in the system.

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of the snapshot that you want to clone.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) 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

(Optional) System object names include:

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

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

timeout

(Optional) The maximum duration of execution for the specified DSL, in seconds. This defaults to maxDslDuration server setting. The default timeout is 5 minutes.

Argument type: Long

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

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

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace that you want to clone.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

dsl or dslFile

Response

None or a status OK message.

ec-perl

syntax: $cmdr->evalDsl(<dsl or dslFile>, {<optionals>});

Example

When specifying the DSL text ( <dsl> ):

$cmdr->evalDsl "project 'My WAR file' "

When specifying the path to the DSL script on the client ( <dslFile> :

$cmdr->evalDsl ({dslFile => c:/dslScripts/myWarFile.dsl});

ectool

syntax: ectool evalDsl <dsl> [optionals]

Example

When specifying the DSL text ( <dsl> ):

ectool evalDsl "project 'My WAR file' "

When specifying the path to the DSL script on the client ( <dslFile> :

ectool evalDsl --dslFile c:/dslScripts/myWarFile.dsl

evalScript

Evaluates a script in the specified context.This API is similar to expandString except that it evaluates the value argument as a Javascript block, without performing any property substitution on either the script or the result. The string value of the final expression in the script is returned as the value element of the response.

You must specify a value.

Arguments Descriptions

value

The script to evaluate in the specified context.

Argument type: String

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD server interprets either name form correctly.

Argument type: String

componentName

(Optional) Name of the component.

Argument type: String

configName

(Optional) Name of the email configuration.

Argument type: String

credentialName

(Optional) Name of the credential in one of these forms:

  • Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.

  • 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

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

Argument type: String

environmentTemplateName

(Optional) The name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

flowTransitionName

(Optional) The name of the flow transition.

Argument type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of a group where you might evaluate a script.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

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

Argument type: UUID

notifierName

(Optional) The name of the email notifier.

Argument type: String

objectId

(Optional) This is an object identifier returned by findObjects and getObjects.

Argument type: String

path

(Optional) The property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of a plugin where you might evaluate a script.

Argument type: String

procedureName

(Optional) The name of a procedure where you might need to evaluate a script. Also requires projectName.

Argument type: String

processName

(Optional) The name of the process when the container is a process or process step.

Argument type: String

processStepName

(Optional) The name of the process step when the container is a process step.

Argument type: String

projectName

(Optional) Name of the project that contains the script to evaluate.

Argument type: String

propertySheetId

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

Argument type: UUID

releaseName

(Optional) The name of the Release.

Argument type: String

repositoryName

(Optional) The name of the repository for artifact management.

Argument type: String

resourceName

(Optional) The name of a resource where you might evaluate a script.

Argument type: String

resourcePoolName

(Optional) The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

(Optional)The name of a schedule within this project. Also requires projectName.

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of the snapshot.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the step whose script you might evaluate. Also requires projectName and procedureName.

Argument type: String

systemObjectName

(Optional) System object names include: admin|directory|log|priority|projects| resources|server|session|workspaces.

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) Name of the transition definition.

Argument type: String

transitionName

(Optional) Name of the transition.

Argument type: String

userName

(Optional) Name of the user where you may need to evaluate a script.

Argument type: String

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of the workflow.

Argument type: String

workspaceName

(Optional) Name of a workspace where you may need to evaluate a script.

Argument type: String

zoneName

(Optional) Name of the zone.

Argument type: String

Positional arguments

value

Response

The string value of the final expression in the Javascript block inside a value element.

ec-perl

syntax: $cmdr->evalScript (<value>, {<optionals>});

Examples

my $result = $ec->evalScript (q{"ip=" + server.hostIP+", name=" + server.hostName})->findvalue("//value");

my $result = $ec->evalScript (q{myProject.projectName}, {jobId => '4fa765dd-73f1-11e3-b67e-b0a420524153'});

ectool

syntax: ectool evalScript <value> [optionals]

Examples

ectool evalScript '"ip=" + server.hostIP+", name=" + server.hostName'

ectool evalScript 'myProject.projectName' --jobId 4fa765dd-73f1-11e3-b67e-b0a420524153
   --jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153

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.

The export is executed by the CloudBees CD service user.

Before you perform an export, ensure that the CloudBees CD server is inactive (meaning that it cannot accept jobs) by completing the following steps on the server:

  • Disable the ECSCM:SentryMonitor schedule and all project schedules.

    1. From the main menu, navigate to the Platform Home Page.

    2. Select Electric Cloud from the Projects tab.

    3. Select the Schedules tab and disable all schedules, including the ECSCM-SentryMonitor schedule that runs the ECSCM:ElectricSentry procedure.

  • Make sure all jobs are stopped.

    1. From the main menu, navigate to the Platform Home Page.

    2. Select the Jobs tab.

    3. Review the jobs list and take action to stop all jobs.

  • Disable all resources so that no new job steps can run.

    1. From the main menu, navigate to the Resources list.

    2. Disable each resource by clearing its state from the Enabled column.

A quiescent database ensures a complete XML database file is exported.

When you specify the path, this is the path relative to the server process on the server host. The export operation is run using the server’s process ID that must have write permission to this path.

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

  • For Windows: C:\Documents and Settings\All Users\Application Data\CloudBees\ ElectricCommander

  • For Linux: ` /opt/electriccloud/ElectricCommander`

You must specify a fileName.

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

A full export/import preserves job IDs, but a partial import preserves names only, not IDs.
When you export a project while a pipeline is in progress, only the full export includes flow runtimes that have been completed. If you want to include in-progress pipeline runs in the path-to-production view and the visual indicators showing their percentage completed in the Release Dashboard, set the excludeJobs argument to 0 or false in the export command. When the XML file is imported, the in-progress pipeline runs in the imported project are displayed in the path-to-production view and the Release Dashboard. The jobs might be incomplete once the XML is imported.
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

(Optional) < Boolean flag0|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 file name. The default behavior is to compress the output.

This is true only for full exports.

Argument type: Boolean

disableProjectTracking

(Optional) < Boolean flag0|1|true|false >

If set to 1 or true when importing or exporting a project, even if the original project had Change Tracking enabled, make Change Tracking of the newly imported or exported project be disabled from its creation.

If you do not need to track changes to the new project, this avoids the Change Tracking overhead that would otherwise slow down the import operation, and also saves having to subsequently disable change tracking of the re-imported project.

This is true only for partial exports.

Argument type: Boolean

download

(Optional) < Boolean flag0|1|true|false >

If set to 1 or true, the exported file can be downloaded.

This is true for full and partial exports.

Argument type: Boolean

excludeJobs

(Optional) < Boolean flag0|1|true|false >

If set to 1 or true, no job information is exported. This argument can be used to reduce the export file size. This argument is also useful if it is not be feasible to run a full XML export regularly (such as nightly). So if jobs are running, in order to speed up the full export (and to help prevent issues with importing the data later), you should use this argument.

This is true only for full exports.

Argument type: Boolean

objectId

(Optional) ID of the object ID. This triggers a partial export.

Argument type: UUID

objectType

(Optional) The object type. This triggers a partial export.

Argument type: String

path

(Optional) < property path > Specifies the path relative to the server process 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. This triggers a partial export.

Argument type: String

reducedDetailChangeHistory

(Optional) < Boolean flag0|1|true|false >

Setting this argument to 0 or false prevents importing a large project that has change tracking enabled from automatically reducing the level of detail that it tracks for the change history of the import. This will make the import operation take longer and put more load on the database, but will allow the Change History feature to still show the full detail of entities owned by the imported project that were created by the import operation.

Argument type: Boolean

relocatable

(Optional) < Boolean flag0|1|true|false >

If the --relocatable flag is set to 1 or 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.

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

Argument type: Boolean

revisionNumber

(Optional) Revision number of the file. This triggers a partial export.

Argument type: Integer

safeMode

(Optional) 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.

The safeMode argument affects only full imports.

Argument type: SafeMode

withAcls

(Optional) This argument modifies relocatable. < Boolean flag0|1|true|false >

If the withAcls flag is set to 1 or true, a relocatable partial export will include ACLs.

This is true only for partial exports.

Argument type: Boolean

withNotifiers

(Optional) This argument modifies relocatable. < Boolean flag0|1|true|false >

If this flag is set to 1 or true, a relocatable partial export will include email notifiers.

This is true only for partial exports.

Argument type: Boolean

withVersionNumbers

(Optional) < Boolean flag— 0|1|true|false >

If this flag is set to 1 or true, version numbers are issued during the export operation (they are ignored on import).

This is true only for partial exports.

Argument type: Boolean

Positional arguments

fileName

Response

None or a status OK message.

ec-perl

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

Examples

$cmdr->export("c:\ElectricCommander\Aug 15 2015.xml");

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

ectool

syntax: ectool export <fileName> [optionals]

Examples

ectool export "c:\ElectricCommanderBackup\Aug 15 2015.xml"

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

findObjects

This command returns a sorted list of CloudBees CD 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 CloudBees CD objects and is used by the CloudBees CD web interface to implement the CloudBees CD pSearch 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. See the following table for the list of object types in CloudBees CD.

Object Types

application
applicationDependency
applicationServiceMapping
applicationTier
artifact
artifactVersion
catalog
catalogItem
cluster
component
container
credential
dashboard
deployerApplication
deployerConfiguration
deployerService
devOpsInsightServerConfiguration
directoryProvider
emailConfig
emailNotifier
entityChange
environment
environmentInventoryItem
environmentMap
environmentTemplate
environmentTemplateTier
environmentTemplateTierMap
environmentTier
environmentVariable
eventSubscription
gate
gateway
hook
formalParameter
flow
flowState
flowRuntime
job
jobStep
logEntry
note
pipeline
plugin
port
procedure
procedureStep
process
processDependency
processStep
project
property
release
report
reportObjectAssociation
reportObjectAttribute
reportObjectType
reportingFilter
repository
reservation
resource
resourcePool
resourceTemplate
retrievedArtifact
rollingDeployPhase
schedule
service
serviceClusterMapping
serviceDependency
serviceMapDetail
snapshot
stage
state
stateDefinition
step
task
tierMap
transition
transitionDefinition
utilityResource
waitDependency
widget
workflow
workflowDefinition
workspace
zone
Arguments Descriptions

objectType

The type of object to find. See Object Types for the list of possible values.

Argument type: String

filters

(Optional) 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 CloudBees CD 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 CloudBees CD 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

firstResult

(Optional) The first result to be retrieved, starting from 0 (zero).

Argument type: Integer

includeAccess

(Optional) < Boolean flag0|1|true|false >

If set to 1 ` or `true, this command also returns access maps for the objects.

Argument type: Boolean

includeEntityRevisions

(Optional) < Boolean flag0|1|true|false >

If set to 1 ` or `true, this command also returns the version and/or entity revision if the object is in the search results.

Argument type: Boolean

includeLatestRevision

(Optional) < Boolean flag0|1|true|false >

If set to 1 ` or `true, this command also returns the latest revision data for versioned objects.

Argument type: Boolean

maxIds

(Optional) <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

(Optional) <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

(Optional) 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 CloudBees CD Perl API.

Argument type: Collection

sorts

(Optional) 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 CloudBees CD 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 CloudBees CD:\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 CloudBees CD :\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".

$cmdr->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".)

$cmdr->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.

$cmdr->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.

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

(Optional) < 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

(Optional) < 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

(Optional) Elapsed time that the command runs.

Argument type: Double

errorMessage

(Optional) Error message from the agent.

Argument type: String

exit

(Optional) Exit code of the command.

Argument type: Integer

maxProtocolVersion

(Optional) Maximum protocol version that the agent supports.

Argument type: Integer

minProtocolVersion

(Optional) Minimum protocol version that the agent supports.

Argument type: Integer

pingToken

(Optional) Current ping token.

Argument type: Long

postpExit

(Optional) Exit code of postp.

Argument type: Integer

protocolVersion

(Optional) Current agent protocol version.

Argument type: Integer

version

(Optional) 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

generateDsl

Generates a domain-specific language (DSL) script for the specified object including all nested objects, parameters, and custom properties, subject to arguments passed in with the command.

You must specify the path argument.

Arguments Descriptions

path

A property path indicating a single object for which DSL is to be generated.

Argument type: String

includeChildren

(Optional) A comma-separated list of child object types in path to include in the result. If not specified all children objects are returned.

Argument type: Array

suppressChildren

(Optional) < Boolean flag0|1|true|false >

If set to true, suppress child objects in the generated DSL. If not specified, 0 | false is used–children are returned. Ignored if the --includeChildren argument is specified.

Argument type: Boolean

suppressDefaults

(Optional) < Boolean flag0|1|true|false > If set to true, suppress properties with default values in the generated DSL. If not specified, 0 | false is used–all properties are returned, subject to --suppressNulls argument.

Argument type: Boolean

suppressNulls

(Optional) < Boolean flag0|1|true|false >

If set to true, suppress properties with null values in the generated DSL. If not specified, 0 | false is used –all properties are returned, subject to --suppressDefaults argument.

Argument type: Boolean

suppressParent

(Optional) < Boolean flag0|1|true|false >

If set to true, suppress parent references in the generated DSL. If not specified, 0 | false is used –parent references are returned.

Argument type: Boolean

useFileReferences

(Optional) < Boolean flag0|1|true|false >

If set to true, a file reference, containing the resulting DSL, is returned in the response. If not specified, 0 | false is used –DSL is returned.

Argument type: Boolean

withAcls

(Optional) < Boolean flag0|1|true|false >

If set to true, the generated DSL includes ACLs for the object and all nested objects.

Argument type: Boolean

Positional arguments

path

Response

Content for the DSL script is based on object types in the request. For an example, see Getting Started with DSL .

ec-perl

syntax: $cmdr->generateDsl(<path>, {<optionals>});

Examples

Include ACLs for the parent and all nested objects:

$cmdr->generateDsl("/resources/local", {withAcls => true});

Include the Default project and just its pipelines:

$cmdr->generateDsl("/projects/Default", {includeChildren => "pipelines"});

Suppress default values:

$cmdr->generateDsl("/resources/local", {suppressDefaults => true});

ectool

syntax: ectool generateDsl <path> [optionals]

Example

Include ACLs for the parent and all nested objects:

ectool generateDsl "/resources/local" --withAcls true

Include the Default project and just its pipelines:

ectool generateDsl "/resources/local" --includeChildren "pipelines"

Suppress default values:

ectool generateDsl "/resources/local" --suppressDefaults true

getObjects

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.

Arguments Descriptions

includeAccess

(Optional) < Boolean flag0|1|true|false >

If set to 1 or true, this command also returns access maps for the objects.

Argument type: Boolean

includeLatestRevision

(Optional) < Boolean flag0|1|true|false >

If set to 1 or true, this command also returns the latest revision data for versioned objects.

Argument type: Boolean

objectIds

(Optional) 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 CloudBees CD Perl API.

Argument Type: Collection

selects

(Optional) 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 CloudBees CD Perl API.

Argument type: Collection

Positional arguments

None

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 CloudBees CD 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 CloudBees CD:\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 CloudBees CD:\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.

graphStateMachine

Generates a graph element with a stateMachine DOT graph as CDATA content.

You must specify a jobId.

Arguments Descriptions

jobId

The unique CloudBees CD -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

(Optional) < 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> [optionals]

Examples

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

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.

When you export a project while a pipeline is in progress, only the full export includes flow runtimes that have been completed. If you want to include in-progress pipeline runs in the path-to-production view and the visual indicators showing their percentage completed in the Release Dashboard, set the excludeJobs argument to 0 or false in the export command. When the XML file is imported, the in-progress pipeline runs in the imported project are displayed in the path-to-production view and the Release Dashboard. The jobs might be incomplete once the XML is imported.
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

(Optional) < 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.

The batchSize argument applies only to full import operations.

Argument type: Integer

disableProjectTracking

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or true when importing or exporting a project, even if the original project had Change Tracking enabled, this makes Change Tracking of the newly imported or exported project disabled from its creation.

If you do not need to track changes to the new project, this avoids the Change Tracking overhead that would otherwise slow down the import operation, and also saves having to subsequently disable change tracking of the re-imported project.

Argument type: Boolean

disableSchedules

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or true, 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

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or 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

(Optional) < 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

(Optional) < Boolean flag0|1|true|false >

If this argument is set to 1 or 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

reducedDetailChangeHistory

(Optional) < Boolean flag0|1|true|false >

Use this argument for large projects containing over 20,000 audited objects with Change Tracking enabled.

When this argument is set to true or 1, CloudBees CD automatically decreases the amount of Change History indexing information that it saves in a large project, which reduces the level of detail for Change Tracking-intensive operations in the change history. This can make it harder to revert an object to a specific state and to find information in the change history when you troubleshoot or debug an issue.

Set this argument to false or 0 to suppress this behavior so that CloudBees CD does not change the amount of indexing information for a large project. This causes the operation to take longer and put more load on the database, but the change history will have the full details of the entities owned by objects in the project.

Argument type: Boolean

Positional arguments

fileName

Response

None or a status OK message.

ec-perl

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

$cmdr->import({file ⇒ <localFileName>, {<optionals>});

Examples

$cmdr->import("/opt/TestProg.xml");

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

ectool

syntax examples: ectool import <remoteFileName> [optionals]

ectool import <localFileName> [optionals]

Examples

ectool import /mnt/backups/fullBackkup.xml

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

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

releaseNamedLock

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

Arguments Descriptions

lockName

Name of the lock.

Argument type: String

delay

(Optional) 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 ("Group 1", {delay => 5});

ectool

syntax examples: ectool releaseNamedLock <lockName> [optionals]

Examples

ectool releaseNamedLock "Group 1" --delay 5