acquireNamedLock
Retrieves the named lock.
| Arguments | Descriptions |
|---|---|
lockName |
Name of the lock. Argument type: String |
create |
< Boolean flag — When this argument is set to Argument type: Boolean |
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)
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 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 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 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 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 |
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 Argument type: String |
||
Optionals |
|||
disableProjectTracking |
(Optional) < Boolean flag — If set to 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 flag — Use this argument for large projects containing over 20,000 audited objects with Change Tracking enabled. When this argument is set to Set this argument to 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 ( Argument type: String |
||
credentialName |
(Optional) The name of the credential that can be specified in one of these formats: relative (for example, absolute (for example, 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 ( Argument type: String |
||
objectId |
(Optional) The object id as returned by 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 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.
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 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 Argument type: String |
||
systemObjectName |
(Optional) System object names include:
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' <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>countObjects
Returns the count of objects specified by the provided filter.
You must enter objectType.
| Arguments | Descriptions | ||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
objectType |
The type of object to count.
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:
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:
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:
Argument type: Collection |
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;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: Argument type: String |
filters |
(Optional) Specify filters in a space-separated list:
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: 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: Argument type: Collection |
maxIds |
(Optional) Argument type: Integer |
sorts |
(Optional) Specify "sorts" in a space-separated list: 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 Argument type: Collection |
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";describeObject
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 flag — If this argument is set to Argument type: Boolean |
objectType |
(Optional) Return the object structure for |
topLevelOnly |
(Optional) < Boolean flag — If this argument is set to Argument type: Boolean |
Response
Returns the specified CloudBees CD object structure as a structed set of <objectType> elements.
dumpHeap
dumpStatistics
Prints (emits) internal timing statistics.
| Arguments | Descriptions |
|---|---|
clearStatistics |
(Optional) < Boolean flag — If this argument is set to Argument type: Boolean |
dumpLapTimes |
(Optional) < Boolean flag — If this argument is set to 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 The default is . Argument type: String |
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 Argument type: String |
dslFile |
Path to the file on the client containing the DSL script. Either 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 flag — If this argument is set to Argument type: Boolean |
describe |
(Optional) < Boolean flag — If this argument is set to 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 Argument type: UUID |
overwrite |
(Optional) < Boolean flag — If this argument is set to 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 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 Argument type: String |
systemObjectName |
(Optional) System object names include:
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 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 |
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 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:
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 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 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 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 Argument type: String |
systemObjectName |
(Optional) System object names include: 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 |
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:SentryMonitorschedule and all project schedules.-
From the main menu, navigate to the Platform Home Page.
-
Select Electric Cloud from the Projects tab.
-
Select the Schedules tab and disable all schedules, including the
ECSCM-SentryMonitorschedule that runs theECSCM:ElectricSentryprocedure.
-
-
Make sure all jobs are stopped.
-
From the main menu, navigate to the Platform Home Page.
-
Select the Jobs tab.
-
Review the jobs list and take action to stop all jobs.
-
-
Disable all resources so that no new job steps can run.
-
From the main menu, navigate to the Resources list.
-
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 flag — 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.
Argument type: Boolean |
||
disableProjectTracking |
(Optional) < Boolean flag — If set to 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 |
||
download |
(Optional) < Boolean flag — If set to
Argument type: Boolean |
||
excludeJobs |
(Optional) < Boolean flag — If set to
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 flag — Setting this argument to Argument type: Boolean |
||
relocatable |
(Optional) < Boolean flag — If the 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
The Argument type: SafeMode |
||
withAcls |
(Optional) This argument modifies If the
Argument type: Boolean |
||
withNotifiers |
(Optional) This argument modifies If this flag is set to
Argument type: Boolean |
||
withVersionNumbers |
(Optional) < Boolean flag— If this flag is set to
Argument type: Boolean |
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:
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:
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:
Argument type: Collection |
firstResult |
(Optional) The first result to be retrieved, starting from 0 (zero). Argument type: Integer |
includeAccess |
(Optional) < Boolean flag — If set to Argument type: Boolean |
includeEntityRevisions |
(Optional) < Boolean flag — If set to Argument type: Boolean |
includeLatestRevision |
(Optional) < Boolean flag — If set to Argument type: Boolean |
maxIds |
(Optional) Argument type: Integer |
numObjects |
(Optional) 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 |
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 {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 {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'}]}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— If this argument is set to Argument type: Boolean |
deletedPostpLogFile |
(Optional) < Boolean flag— If this argument is set to 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 |
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 Argument type: Array |
suppressChildren |
(Optional) < Boolean flag — If set to Argument type: Boolean |
suppressDefaults |
(Optional) < Boolean flag — Argument type: Boolean |
suppressNulls |
(Optional) < Boolean flag — If set to Argument type: Boolean |
suppressParent |
(Optional) < Boolean flag — If set to Argument type: Boolean |
useFileReferences |
(Optional) < Boolean flag — If set to Argument type: Boolean |
withAcls |
(Optional) < Boolean flag — If set to Argument type: Boolean |
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 trueInclude the Default project and just its pipelines:
ectool generateDsl "/resources/local" --includeChildren "pipelines"Suppress default values:
ectool generateDsl "/resources/local" --suppressDefaults truegetObjects
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 flag — If set to Argument type: Boolean |
includeLatestRevision |
(Optional) < Boolean flag — If set to Argument type: Boolean |
objectIds |
(Optional) A list of one or more object IDs that were returned by a prior call to 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 |
ec-perl
syntax: $cmdr->getObjects({<optionals>});
Example 1
Code example for findObjects and getObjects :
# This example runs within a {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 {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 {CD}:\n" . $xPath-> findnodes_as_string("/") . "\n";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— If this argument is set to Argument type: Boolean |
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 < |