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/RO 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 Used to specify the name of a file containing multiple lines of values. Contents of the value file are read and stored in the value field of the property. This is an alternative argument for value and is useful if the value field spans multiple lines.

For example:

ectool setProperty /resources/foo/repositoryNames --valueFile repos.txt

Where repos.txt is a file that contains a list of values, one value in each line:

repository1
repository2
repository3

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

Positional arguments

propertyName

Response

An XML stream that echoes the new property, including its ID, which is assigned by the CloudBees CD/RO 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

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/RO 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/RO 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/RO looks for the property in the project where the procedure resides. If the object specifier is a job step, CloudBees CD/RO 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

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

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/RO 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/RO looks for the property in the project where the procedure resides.
If the object specifier is a job step, CloudBees CD/RO 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