Groovy API reference

Miscellaneous Management

37 minute readReference

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/RO 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/RO 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/RO 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' <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.

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/RO 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/RO 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/RO 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/RO 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/RO 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/RO 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/RO 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/RO 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/RO 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

archiveConnectorName

(Optional) The name of the archive connector of the property sheet that owns the property.

Argument type: String

artifactName

(Optional) Name of the artifact.

Argument type: String

artifactVersionName

(Optional) Name of the artifact version.

Argument type: String

catalogName

(Optional) The name of the catalog of the property sheet that owns the property.

Argument type: String

clientFiles

(Optional) Path to the client directory that contains .jar files and classes to be added to the classpath as well as local DSL files referenced in the input DSL code.

Argument type: String

clusterName

(Optional) The name of the cluster that owns the property sheet.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) Name of the email configuration.

Argument type: String

containerName

(Optional) The container name; must be unique within the project or service.

Argument type: String

credentialName

(Optional) The name of the credential.

Argument type: String

dashboardName

(Optional) The name of the dashboard of the property sheet that owns the property.

Argument type: String

dataRetentionPolicyName

(Optional) The name of the data retention policy of the property sheet that owns the property.

Argument type: String

debug

(Optional)

< Boolean flag0|1|true|false >

If this argument is set to true or 1, CloudBees CD/RO 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/RO 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 container of the property sheet that owns the property.

Argument type: String

flowRuntimeId

(Optional) The primary key or name of the flowRuntime container of the property sheet that owns the property.

Argument Type: String

flowRuntimeName

(Optional) The name of the flow runtime container of the property sheet that owns the property.

Argument Type: String

flowRuntimeStateId

(Optional) The primary key or name of the flowRuntimeState container of the property sheet that owns the property.

Argument Type: String

flowRuntimeStateName

(Optional) The name of the flow state container of the property sheet that owns the property.

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

gateType

(Optional) The type of the gate that owns the property sheet.

Argument type: String

gatewayName

(Optional) The name of the gateway container of the property sheet.

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/RO 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/RO .

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

reportName

(Optional) The name of the report of the property sheet that owns the property.

Argument type: String

reportObjectTypeName

(Optional) The name of the report object type of the property sheet that owns the property.

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

serviceAccountName

(Optional) The name of the service account container of the property sheet.

Argument type: String

serviceName

(Optional) The name of the service. Use applicationName or serviceName.

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

widgetName

(Optional) The name of the widget of the property sheet that owns the property.

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/RO 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