Property Management

createProperty

Creates a regular string or nested property sheet using a combination of property path and context.

You must specify a propertyName and locator arguments to define where (or on which object) you are creating this property.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

propertyName

The name of the property that must be unique within the property sheet.

It can be a relative or absolute property path, including "my" paths such as "/myProject/prop1".

Argument type: String

applicationName

(Optional) The name of the application container of the property sheet which owns the property. The name must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier container of the property sheet which owns the property.

Argument type: String

artifactName

(Optional) The name of the artifact container of the property sheet which owns the property.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) The name of the component container of the property sheet which owns the property.

Argument type: String

configName

(Optional) The name of the email configuration container that owns the property.

Argument type: String

counter

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

If 1 or true, the property is used as a counter.

Argument type: Boolean

credentialName

(Optional) The name of the credential container of the property sheet which owns the property.

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

credentialProtected

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

If 1 or true, permissions required for modify privileges on the property sheet will also require execute privileges on the credentials attached to the property sheet owner.

Argument type: Boolean

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

environmentName

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

Argument type: String

environmentTemplateName

(Optional) The name of the environment template container of the property sheet that owns the property.

Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier container of the property sheet that owns the property.

environmentTierName

(Optional) The name of the environment tier container of the property sheet that owns the property.

Argument type: String

expandable

(Optional) Whether or not the property is recursively expandable.

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

This determines whether the property value will undergo property expansion when it is fetched. The default is true.

Argument type: Boolean

extendedContextSearch

(Optional) For simple property names, whether or not to search objects in the hierarchy to find the desired property.

Argument type: Boolean

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 container of the property sheet.

Argument type: String

groupName

(Optional) The name of the group container of the property sheet which owns the property.

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: UUID

objectId

(Optional) The object identifier returned by findObjects and getObjects.

Argument type: String

path

(Optional) Property path string.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

The name of the plugin container of the property sheet which owns the property.

Argument type: String

procedureName

The name of the procedure container of the property sheet which owns the property. When using this argument, you must also enter 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) The name of the project container of the property sheet which owns the property. The name must be unique among all projects.

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

propertyType

(Optional) Type of property: < string|sheet >

This indicates whether to create a string property or a sub-sheet. The default is string.

Argument type: PropertyType

releaseName

(Optional) The name of the release container of the property sheet which owns the property.

Argument type: String

repositoryName

(Optional) The name of the repository container of the property sheet which owns the property. Use the repository for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource container of the property sheet which owns the property. You define the new property in this resource.

Argument type: String

resourcePoolName

(Optional) The name of the resource pool (with one or more resources) container of the property sheet that owns the property.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template container of the property sheet that owns the property.

Argument type: String

scheduleName

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

If you use a schedule name to define the location for the new property, you must also enter 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 container of the property sheet which owns the property.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition container of the property sheet which owns the property.

stateName

(Optional) The name of the state container of the property sheet which owns the property

Argument type: String

stepName

(Optional) The name of the step container of the property sheet which owns the property.

If you use a step name to define the location for the new property, you must also enter projectName and procedureName.

Argument type: String

suppressValueTracking

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

If 1 or true, then suppress tracking into the change history of modifications where the only change was to the value of this property. Setting it to 1 or true is useful where an automated process (such as a job step, pipeline stage, or workflow transition) makes numerous value-only changes.

Setting this flag is strongly recommended for properties that are used as build counters, most recent build or artifact names, or are used to store runtime output from jobs, pipelines, or workflows into a property attached to a change-tracked non-runtime entity. Otherwise, these will rapidly fill the change history with numerous irrelevant events.

This flag has no effect if the property is not change tracked or if change tracking is disabled.

Setting this flag also modifies the behavior of the ectool export --revisionNumber revision_number option for exporting previous states of entities containing properties where this flag was unset. The current value of the property is exported, so that immediately reimporting it does not reset the property value.

See the KBEC-00422 - Locating and Fixing Properties with Excessive Unwanted Change History Generated by Automated Processes KB article for details about locating properties for which this should have been done (but was not) and thus have a large change history.

In the GUI, the equivalent to this flag is a checkbox named Track Changes to Value, and its Boolean truth value is inverted.

Argument type: Boolean

systemObjectName

(Optional) The name of the special system object. In this context, only server is legal.

Argument type: SystemObjectName

taskName

(Optional) The name of the task in a pipeline stage.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition container of the property sheet which owns the property.

Argument type: String

transitionName

(Optional) The name of the transition container of the property sheet which owns the property.

Argument type: String

userName

(Optional) The name of the user container of the property sheet which owns the property.

Argument type: String

value

(Optional) For a string property (see propertyType ), this is the value of the property. For a sheet property, this argument is invalid.

Argument type: String

valueFile

(Optional) The contents of the valuefile is read and stored in the "value" field for a string property. This is an alternative argument for value and is useful if the “value” field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not a part of the XML protocol.

workflowDefinitionName

(Optional) The name of the workflow definition container of the property sheet which owns the property.

Argument type: String

workflowName

(Optional) The name of the workflow container of the property sheet which owns the property.

Argument type: String

workspaceName

(Optional) The name of the workspace container of the property sheet

Argument type: String

zoneName

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

Argument type: String

Positional arguments

propertyName

Response

An XML stream that echoes the new property, including its ID, which is assigned by the CloudBees CD server.

ec-perl

syntax: $cmdr->createProperty(<propertyName>, {<optionals>});

Examples

$cmdr->createProperty('/myJob/Runtime Env/PATH', {value => 'c:\bin'});

$cmdr->createProperty('Runtime Env/PATH', {value => 'c:\bin', …});

ectool

syntax: ectool createProperty <propertyName> [optionals]

Examples

ectool createProperty "/myJob/Runtime Env/PATH" --value "c:\bin"

ectool createProperty "Runtime Env/PATH" --value "c:\bin" --jobId 4fa765dd-73f1-11e3-b67e-b0a420524153

ectool createProperty "Saved Variables" --propertyType sheet --jobId 4fa765dd-73f1-11e3-b67e-b0a420524153

deleteProperty

Deletes a property from a property sheet.

You must specify a propertyName and you must specify locator arguments to find the property you want to delete.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

propertyName

The name of the property that must be unique within the property sheet.

Argument type: String

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) Whether or not the property is recursively expandable.

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

extendedContextSearch

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

For simple property names, whether or not to search objects in the hierarchy to find the desired property. If set, and there is an object specifier in the command, CloudBees CD first looks for the property in that object specifier, but also searches in other locations if not found, according to the following rules:

  • If the object specifier is a procedure, CloudBees CD looks for the property in the project where the procedure resides.

  • If the object specifier is a job step, CloudBees CD looks in the actual parameters of the procedure to which it belongs, and then looks at the job properties.

The d efault setting is true.

Argument type: Boolean

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 that contains this property.

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) Property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of a plugin that may contain a property you want to delete.

Argument type: String

procedureName

(Optional) The name of the procedure containing the property you want to delete. 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) The name of the project that contains the property you want to delete.

Argument type: String

propertySheetId

(Optional) The unique identifier for a property sheet, 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 the resource that contains the property you want to delete.

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 the schedule containing the property you want to delete. 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.

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 containing the property you want to delete. Also requires projectName and procedureName.

Argument type: String

systemObjectName

(Optional) The name of a special system object. Only "server" is valid in this context.

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 username that contains this 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.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

propertyName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteProperty(<propertyName>, {<optionals>});

Example

$cmdr->deleteProperty("/projects/Sample project/Changeset ID", {pipelineName => "Q2 Summary"});

ectool

syntax: ectool deleteProperty <propertyName> [optionals]

Example

ectool deleteProperty "/projects/Sample project/Changeset ID" --pipelineName "Q2 Summary"

expandString

Expands property references in a string, in the current context.

You must specify a value and a context in which to perform the expansion or a valueFile option.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

value

The string value to expand in the given 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. Note: An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD server interprets either name form correctly.

Argument type: String

componentName

(Optional) 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 container of the property sheet which owns the property.

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) Name of the environment template.

Argument type: String

environmentTemplateTierName

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

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 expand a string.

Argument type: String

procedureName

(Optional) The name of a procedure where you might need to expand a string. 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) The name of the project that contains the string to expand.

Argument type: String

propertySheetId

(Optional) The unique identifier for a property sheet that 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 expand a string.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) 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 string you might be expanding. 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) 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

valueFile

(Optional) Contents of the valuefile is read and stored in the "value" field. This is an alternative argument for value and is useful if the value field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

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 a workspace where you may need to expand the string.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

value

Response

The expanded string value.

ec-perl

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

Examples

$cmdr->expandString('$[fullUserName]', {userName => "admin"})->findvalue('//value')->value();

$cmdr->expandString('$[/myWorkspace/agentUncPath]/$[logFileName]',
   {jobStepId => 5da765dd-73f1-11e3-b67e-b0a420524153})->findvalue('//value')->value();

ectool

syntax: ectool expandString <value> [optionals]

Examples

ectool expandString '$[fullUserName]' --userName admin

ectool expandString '$[/myWorkspace/agentUncPath]/$[logFileName]'
   --jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153

findProperties

Returns the properties of the specified object.

You must specify object locators for the properties you want to find.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) 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 containing the properties to retrieve.

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) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

expand

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

The default value is 1 ( true ), and the value of each property will be expanded.

A value of 0 ( false ) will cause the unexpanded value of each property to be returned.

Argument type: Boolean

filters

(Optional)A list of zero or more filter criteria definitions used to define objects to find. See the findObjects API for complete description for using filters.

Argument type: Collection

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 containing the properties to retrieve.

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

maxIds

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

Argument type: Integer

notifierName

(Optional) The name of the email notifier.

Argument type: String

numObjects

(Optional) <full object count> Specifies the number of full objects (not just the IDs) returned from the findObjects request. This option allows selecting a limited number of full objects to be returned in the initial request. The returned "full objects" correspond to the objects from the beginning of the list of object IDs.

If numObjects is not specified, all full objects in the list of object IDs are returned. Any and all objects can be retrieved using the getObjects command.

Argument type: Integer

objectId

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

Argument type: String

path

(Optional) The path to the property sheet containing the properties to retrieve. If the full path to the property sheet is specified, no additional object locators are needed.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin containing the properties to retrieve.

Argument type: String

procedureName

The name of the procedure containing the properties to retrieve. 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) The name of the project containing the properties to retrieve.

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 the resource containing the properties to retrieve.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule containing the properties to retrieve. Also requires projectName.

Argument type: String

snapshotName

(Optional) The name of the snapshot.

Argument type: String

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

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 containing the properties to retrieve. Also requires projectName and procedureName.

Argument type: String

systemObjectName

(Optional) The name of the system object containing the properties to retrieve. Only "server" is supported.

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 containing the properties to retrieve.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

workflowName

(Optional) The name of the workflow. Also requires projectName.

Argument type: String

workspaceName

(Optional) The name of the workspace containing the properties to retrieve.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

Arguments to locate the property, beginning with the top-level object.

Response

One or more property elements for the object.

ec-perl

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

Examples

$cmdr->findProperties({resourceName => "Web Server"});

ectool

syntax: ectool findProperties [optionals]

Examples

ectool findProperties --resourceName "Web Server"

getProperties

Retrieves all properties associated with an object, along with the property sheet identifier for the object’s property sheet.

You must specify object locators for the properties you want to retrieve.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) 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 containing the properties to retrieve.

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) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

expand

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

The default value is 1 ( true ), and the value of each property will be expanded.

A value of 0 ( false ) will cause the unexpanded value of each property to be returned.

Argument type: Boolean

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 containing the properties to retrieve.

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 path to the property sheet containing the properties to retrieve. If the full path to the property sheet is specified, no additional object locators are needed.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin containing the properties to retrieve.

Argument type: String

procedureName

The name of the procedure containing the properties to retrieve. 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) The name of the project containing the properties to retrieve.

Argument type: String

propertyName

(Optional) Name of a nested property sheet.

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

recurse

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

The default value is 0 ( false ), and properties of nested sheets will not be included in the response.

If you want the properties from all nested sheets to be retrieved, use the value of 1 for true.

Argument type: Boolean

releaseName

(Optional) The name of the release container of the property sheet which owns the property.

Argument type: String

repositoryName

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

Argument type: String

resourceName

(Optional) The name of the resource containing the properties to retrieve.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule containing the properties to retrieve. 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.

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 containing the properties to retrieve. Also requires projectName and procedureName.

Argument type: String

systemObjectName

(Optional) The name of the system object containing the properties to retrieve. Only "server" is supported.

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 containing the properties to retrieve.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

workflowName

(Optional) The name of the workflow. Also requires projectName.

Argument type: String

workspaceName

(Optional) The name of the workspace containing the properties to retrieve.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

Arguments to locate the property, beginning with the top-level object.

Response

A propertySheet element, which contains zero or more property elements and nested propertySheet elements.

ec-perl

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

Examples

$cmdr->getProperties({resourceName => "r2"});

ectool

syntax: ectool getProperties [optionals]

Examples

ectool getProperties --resourceName "r2"

getProperty

Retrieves the specified property value.

You must specify a propertyName.

This specification can be the full path to the property or it can be relative to an object, which then requires appropriate object locators.
Arguments Descriptions

propertyName

The name or path for the property to retrieve. The name must be unique within the property sheet.

The names " properties " and " project " are not valid property names.

Argument type: String

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) 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 containing the property to retrieve.

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 container that must be unique among all projects.

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) The name of the environment tier.

Argument type: String

expand

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

The default value is 1 ( true ), and the value of each property will be expanded.

A value of 0 ( false ) will cause the unexpanded value of each property to be returned.

Argument type: Boolean

extendedContextSearch

(Optional) For simple property names, whether or not to search objects in the hierarchy to find the desired property.

< Boolean flag — 0|1|true|false > If set, and there is an object locator in the command, CloudBees CD first looks for the property in that object locator, but also searches in other locations if not found, according to the following rules:

  • If the object locator is a procedure, CloudBees CD looks for the property in the project where the procedure resides.

  • If the object locator is a job step, CloudBees CD looks in the actual parameters of the procedure to which it belongs, and then looks at the job properties.

Default setting is true.

Argument type: Boolean

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 containing the property to retrieve.

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: String

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 path to the property sheet containing the properties to retrieve. If the full path to the property sheet is specified, no additional object locators are needed.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin containing the property to retrieve.

Argument type: String

procedureName

(Optional) The name of the procedure containing the property to retrieve. 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) The name of the project containing the property to retrieve.

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 container of the property sheet which owns the property.

Argument type: String

repositoryName

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

Argument type: String

resourceName

(Optional) The name of the resource containing the property to retrieve.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule containing the property to retrieve. 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.

stateName

(Optional) The name of the state.

stepName

(Optional) The name of the step containing the property to retrieve. Also requires projectName and procedureName

systemObjectName

(Optional) The name of the system object containing the property to retrieve. Only "server" is supported.

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 containing the property to retrieve.

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 containing the property to retrieve.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

propertyName

Response

A property sheet or a text string containing the value of the property. Property value example: 35491

ec-perl

syntax: $cmdr->getProperty(<propertyName>, {<optionals>});

Examples

use XML::XPath;
$cmdr->getProperty("/myProject/changeset ID")->findvalue('//value')->value();

$cmdr->getProperty("Changeset ID", {projectName => "Sample Project"})->findvalue('//value')->value();

ectool

syntax: ectool getProperty <propertyName> [optionals]

Examples

ectool getProperty "/myProject/changeset ID"
ectool getProperty "Changeset ID" --projectName "Sample Project"
# Retrieve the /users//providerName property.
ectool getProperty --objectID  --propertyName "/users//providerName"

incrementProperty

Increments the specified property value by the incrementBy amount. If the property does not exist, it will be created with an initial value of the incrementBy amount.

This API call is atomic. This means that the actions of reading the property, incrementing the value, and writing the new value to the property cannot be interrupted, and thus the call is parallel or thread-safe.

You must specify a propertyName and incrementBy.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

propertyName

Name for the property that must be unique within the property sheet.

Argument type: String

incrementBy

The amount by which to increment the property, which can be a positive or negative integer.

Argument type: Integer

applicationName

(Optional) The name of the application.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The 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) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

extendedContextSearch

(Optional) For simple property names, whether or not to search objects in the hierarchy to find the desired property.

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

If this argument is set to 1 or true, and there is an object specified in the command, CloudBees CD first looks for the property in that object specifier, but also searches in other locations if not found, according to the following rules:

  • If the object specifier is a procedure, CloudBees CD looks for the property in the project where the procedure resides.

  • If the object specifier is a job step, CloudBees CD looks in the actual parameters of the procedure to which it belongs, and then looks at the job properties.

The default setting is true.

Argument type: Boolean

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 containing the property to increment.

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) Path to the property.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin containing a property to increment.

procedureName

(Optional) The name of the procedure containing this property. 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

The name of the project containing this property. Also requires procedureName.

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 containing this property.

Argument type: String

repositoryName

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

Argument type: String

resourceName

(Optional) The name of the resource containing this property.

Argument type: String

resourcePoolName

The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule containing this property. 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 containing this property. Also requires projectName and procedureName.

Argument type: String

systemObjectName

(Optional) Only server is a valid system object for this API.

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 containing this 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 containing this property.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

propertyName, incrementBy

Response

A text string containing the updated numeric property value.

ec-perl

syntax: $cmdr->incrementProperty(<propertyName> , <incrementBy>, {<optionals>});

Examples

$cmdr->incrementProperty("Build Number", 1, {procedureName => "Delay", projectName => "Sample Project");

$cmdr->incrementProperty("/projects/Sample Project/procedures/Delay/Build Number", 1);

$cmdr->incrementProperty("procedures/Delay/Build Number", 1,{projectName => "Sample Project"});

ectool

syntax: ectool incrementProperty <propertyName> <incrementBy> [optionals]

Examples

ectool incrementProperty "Build Number" 1 --procedureName "Delay" --projectName "Sample Project"

ectool incrementProperty "/projects/Sample Project/procedures/Delay/Build Number" 1

ectool incrementProperty "procedures/Delay/Build Number" 1 --projectName "Sample Project"

modifyProperty

Modifies a regular string or nested property sheet using a combination of property path and context.

You must specify a propertyName.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

propertyName

The name of the property that must be unique within the property sheet.

This argument can be a path.

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.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

counter

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

If set to true or 1, this property is used as a counter.

Argument type: Boolean

credentialName

(Optional) credentialName can be one of two 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

credentialProtected

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

If 1 or true, permissions required for modify privileges on the property sheet will also require execute privileges on the credentials attached to the property sheet owner.

Argument type: Boolean

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

environmentName

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

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) The name of the environment tier.

Argument type: String

expandable

(Optional) < Boolean flag - 0|1|true|false >–Determines whether the property will undergo property expansion when it is retrieved. The default is true.

Argument type: Boolean

extendedContextSearch

(Optional) For simple property names, whether or not to search objects in the hierarchy to find the desired property.

< Boolean flag— 0|1|true|false >– If set, and there is an object specified in the command, CloudBees CD first looks for the property in that object specifier, but also searches in other locations if not found, according to the following rules:

  1. If the object specifier is a procedure, CloudBees CD looks for the property in the project where the procedure resides.

  2. If the object specifier is a job step, CloudBees CD looks in the actual parameters of the procedure to which it belongs, and then looks at the job properties. The default setting is true.

Argument type: Boolean

flowName

(Optional) 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) Name of the flow state.

Argument type: String

flowTransitionName

(Optional) Name of the flow transition.

Argument type: String

gatewayName

(Optional) Name of the gateway.

Argument type: String

groupName

(Optional) 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, which is assigned automatically when the job step is created.

Argument type: UUID

newName

(Optional) New name of the property.

Argument type: String

notifierName

(Optional) Name of the email notifier.

Argument type: String

objectId

(Optional) An object identifier returned by findObjects and getObjects.

Argument type: String

path

(Optional) Path to the property.

Argument type: String

pipelineName

(Optional) Name of the pipeline.

Argument type: String

pluginName

(Optional) Name of the plugin.

Argument type: String

procedureName

(Optional) Name of the procedure. Also requires projectName.

Argument type: String

processName

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

Argument type: String

processStepName

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

Argument type: String

projectName

(Optional) Name of the project. The property may be on the project itself or on the object, which is indicated by other arguments.

Argument type: String

propertySheetId

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

Argument type: UUID

propertyType

(Optional) <string|sheet> – Indicates whether to create a string property or a sub-sheet. The default is string.

Argument type: PropertyType

releaseName

(Optional) Name of the release.

Argument type: String

repositoryName

(Optional) Name of the repository for artifact management.

Argument type: String

resourceName

(Optional) Name of the resource.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) Name of the schedule. 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) Name of the state definition.

Argument type: String

stateName

(Optional) Name of the state.

Argument type: String

stepName

Name of the step containing the property to be modified. Also requires projectName and procedureName.

Argument type: String

suppressValueTracking

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

If 1 or true, then suppress tracking into the change history of modifications where the only change was to the value of this property. Setting it to 1 or true is useful where an automated process (such as a job step, pipeline stage, or workflow transition) makes numerous value-only changes.

Setting this flag is strongly recommended for properties that are used as build counters, most recent build or artifact names, or are used to store runtime output from jobs, pipelines, or workflows into a property attached to a change-tracked non-runtime entity. Otherwise, these will rapidly fill the change history with numerous irrelevant events.

This flag has no effect if the property is not change tracked or if change tracking is disabled.

Setting this flag also modifies the behavior of the ectool export --revisionNumber revision_number option for exporting previous states of entities containing properties where this flag was unset. The current value of the property is exported, so that immediately reimporting it does not reset the property value.

See the KBEC-00422 - Locating and Fixing Properties with Excessive Unwanted Change History Generated by Automated Processes KB article for details about locating properties for which this should have been done (but was not) and thus have a large change history.

In the GUI, the equivalent to this flag is a checkbox named Track Changes to Value, and its Boolean truth value is inverted.

Argument type: Boolean

systemObjectName

System objects include: admin|artifactVersions|directory|emailConfigs|log|plugins| server|session|workspaces.

Argument type: SystemObjectName

taskName

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

Argument type: String

value

(Optional) Value of the property.

Argument type: String

valueFile

(Optional) The contents of the valuefile is read and stored in the "value" field. This is an alternative argument for value and is useful if the "value" field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

workflowDefinitionName

(Optional) Name of the workflow definition.

Argument type: String

workflowName

(Optional) Name of the workflow.

Argument type: String

workspaceName

(Optional) Name of the workspace.

Argument type: String

zoneName

(Optional) Name of the zone.

Argument type: String

Positional arguments

propertyName

Response

An XML stream that echoes the modified property.

ec-perl

syntax: $cmdr->modifyProperty(<propertyName>, {<optionals>});

Example

$cmdr->modifyProperty("Saved Variables", {description =>
     "Starting configuration of name/value pairs", jobId => 4fa765dd-73f1-11e3-b67e-b0a420524153});

ectool

syntax: ectool modifyProperty <propertyName> [optionals]

Example

ectool modifyProperty "Saved Variables" --description "Starting configuration
    of name/value pairs" --jobId 4fa765dd-73f1-11e3-b67e-b0a420524153

setProperty

Sets the value for the specified property.

You must specify the propertyName and value arguments. The property name can be the full path to the property or it can be relative to an object, which then means you must use object locators to specify the property.

The names " properties " and " project " are not valid property names.
Arguments Descriptions

propertyName

The name or path of the property that must be unique within the property sheet.

This argument can be a path.

Argument type: String

value

The value of the property.

Argument type: String

valueFile

Contents of the valuefile is read and stored in the "value" field. This is an alternative argument for value and is useful if the value field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

applicationName

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

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

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

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

counter

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

If the argument is set to 1 or true, the property is used as a counter. The default is 0 ( false ).

Argument type: Boolean

credentialName

(Optional) The name of the credential containing the property you want to set.

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.

Also requires projectName.

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

environmentName

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

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) The name of the environment tier.

Argument type: String

expandable

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

The default is 1 ( true ),and the property value will be expanded when referenced.

If you do not want the property to expand, use the value of 0 ( false ).

Argument type: Boolean

extendedContextSearch

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

If set, and there is an object specified in the command, CloudBees CD first looks for the property in the object specified, but also searches in other locations if not found, according to the following rules:

If the object specified is a procedure, CloudBees CD looks for the property in the project where the procedure resides.

If the object specified is a job step, CloudBees CD looks in the actual parameters of the procedure to which it belongs, and then looks at the job properties.

The default setting is false.

Argument type: Boolean

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 containing the property that you want to set.

Argument type: String

groupName

(Optional) The name of the group containing the property you want to set.

Argument type: String

jobId

(Optional) The name of the job containing the property you want to set. include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional)The name of the job step containing the property that you want to set. The unique identifier for a job step, 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 path to the property.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin containing the property you want to set.

Argument type: String

procedureName

(Optional) The name of the procedure containing the property that you want to set. Also requires projectName.(Optional)

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) The name of the project containing the property that you want to set.

Argument type: String

propertySheetId

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

Argument type: String

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 the resource containing the property that you want to set.

Argument type: String

resourcePoolName

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

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule containing the property you want to set. 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 containing the property you want to set. Also requires projectName and procedureName.

Argument type: String

suppressValueTracking

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

If 1 or true, then suppress tracking into the change history of modifications where the only change was to the value of this property. Setting it to 1 or true is useful where an automated process (such as a job step, pipeline stage, or workflow transition) makes numerous value-only changes.

Setting this flag is strongly recommended for properties that are used as build counters, most recent build or artifact names, or are used to store runtime output from jobs, pipelines, or workflows into a property attached to a change-tracked non-runtime entity. Otherwise, these will rapidly fill the change history with numerous irrelevant events.

This flag has no effect if the property is not change tracked or if change tracking is disabled.

Setting this flag also modifies the behavior of the ectool export --revisionNumber revision_number option for exporting previous states of entities containing properties where this flag was unset. The current value of the property is exported, so that immediately reimporting it does not reset the property value.

See the KBEC-00422 - Locating and Fixing Properties with Excessive Unwanted Change History Generated by Automated Processes KB article for details about locating properties for which this should have been done (but was not) and thus have a large change history.

In the GUI, the equivalent to this flag is a checkbox named Track Changes to Value, and its Boolean truth value is inverted.

Argument type: Boolean

systemObjectName

(Optional) The name of the system object containing the property you want to set. System objects include: admin|artifactVersions|directory|emailConfigs|log|plugins| server|session|workspaces

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 containing the property you want to set.

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 containing the property that you want to set.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

propertyName

Response

An XML stream that echoes the property.

ec-perl

syntax: $cmdr->setProperty(<propertyName>, {<optionals>});

Examples

$cmdr->setProperty("Changeset ID", {value => "14992", projectName => "Sample Project"});

$cmdr->setProperty("/myResource/Application Path", "c:\Program Files\Application");

$cmdr->setProperty("Application Path", "c:\Program Files\Application",
   {resourceName => "r2"});

ectool

syntax: ectool setProperty <propertyName> [optionals]

Examples

ectool setProperty "Changeset ID" --value "14992" --projectName "Sample Project"
ectool setProperty "/myResource/Application Path" "c:\Program Files\Application"
ectool setProperty "Application Path" "c:\Program Files\Application"
   --resourceName "r2"