Properties

CloudBees CD/RO provides a powerful data model based around the notion of a property.

A property is a string value with a name.
Properties can have arbitrary names and values.
You can attach properties to any object in the CloudBees CD/RO system, such as a project, procedure, or job.
After a property is created, it is stored in the CloudBees CD/RO database.
You can retrieve and modify the property value later.
You can delete properties that you no longer need.

Properties are used extensively throughout the CloudBees CD/RO system and provide a flexible and powerful mechanism to manage data about your builds.

Property use case examples

When a job starts, it computes a unique identifier for that build and saves it in a property. Later build steps can retrieve the property value to embed the build number in binaries generated during the job.
When a build executes, it can set a property on the procedure to identify the source code version used for the build (for example, a tag or timestamp from your source code control system). The next time the build executes, it can retrieve the property value from the procedure and use it to extract information from your source code control system about the files that changed since the last run.
Suppose you have a collection of machines for testing, and some machines have older test hardware and some machines have newer hardware with slightly different characteristics. You can set a property on each test machine resource to indicate which version of test hardware is available on which machine. Later, when a test executes, the test can retrieve the property for the machine where it ran and configure tests appropriately for that hardware. If you upgrade test hardware on a machine, all you need to do is change the property on that resource to reflect the new version.
You can set job properties to indicate the build status produced by that job. For example, if your QA team finds fatal flaws in a build, it can mark the job accordingly. Builds that need to be preserved (release candidates or builds undergoing beta testing at customer sites) can be marked with properties so those builds are not deleted.
When a job executes, properties are set for its job steps that hold metrics such as how many files compiled during a build step, how many tests executed during a test step, or how many errors were detected in the step. These property values are included in reports and can be examined later to compute trends over time. You can define additional properties for metrics useful to you.

CloudBees CD/RO provides intrinsic properties and allows you to create custom properties. This topic enumerates intrinsic properties available within CloudBees CD/RO, distinguishes between relative and absolute property paths, and describes property hierarchies.

Intrinsic properties: These properties represent attributes that describe the object to which they are attached, and are provided automatically by CloudBees CD/RO for each similar type object. For example, every project has a Description property that can be referenced with a non-local property path such as /projects/Examples/description.
Custom properties: These properties are identical to intrinsic properties and when placed on the same object, are referenced in the same manner, and behave in every way like an intrinsic object-level property with one exception: they are not created automatically when the object is created. Instead, custom properties can be added to objects already in the database before a job is started, or created dynamically by procedure steps during step execution.

Intrinsic properties are case-sensitive. Custom properties, like all other object names in the CloudBees CD/RO system, are "case-preserving," but not case-sensitive.

Creating or modifying properties

The examples below show how to set a property value via the automation platform web interface, the ectool command-line application, and the Perl API. This is a subset of the methods; refer to the CloudBees CD/RO APIs for more ways to use the API.

Using the web interface, via tables labeled Custom Properties on the pages that display details for projects, procedures, and so on. Click Create New Property to create a new property for that object, or click on an existing property to change its value.
Using the ectool application, set a property value with a command like:
```
ectool setProperty /myJob/installStatus complete▼
```
This command sets the property named /myJob/installStatus to the value complete, and creates the property if it did not already exist (the meaning of property names like /myJob/installStatus is explained below). You can use ectool from within one job step to set properties accessed by later steps in the same job.

Using the Perl API, you can use an external script or a script in a step with ec-perl as the shell. A Perl code example:

use ElectricCommander;
my $ec = new ElectricCommander();
$ec->setProperty("/myJob/installStatus", "complete", {jobStepId => $ENV{COMMANDER_JOBSTEPID})▼

Using the Perl API may yield better performance if you are requesting multiple API calls in one step.

This is a subset of the methods; refer to the CloudBees CD/RO APIs for more ways to use the API.

Using property values

A job step can access a property value by two methods. The first method is substitution, using the $[ ] notation. Suppose you enter the following text as a command for a step:

make PLATFORM=$[platform]▼

Before running the step, CloudBees CD/RO finds the property named platform and substitutes its value in the command string in place of $[platform]. For example, if the property contains the value windows, the actual command executed is:

make PLATFORM=windows▼

The substitution method can be used for a command in a step and for any step fields, such as the resource or working directory. This method allows you to compute configuration information in an early step of a job, then use that configuration information to control later steps in the job.

Another way for a step to access the property value is with the ectool getProperty command. For example, the following command returns the property value named platform :

ectool getProperty platform▼

Property sheets and intrinsic properties

A property value can be a simple string or a nested property sheet containing its own properties. Property sheets can be nested to any depth, which allows you to create hierarchical collections of information.

Most objects have an associated property sheet that contains custom properties created by user scripts. The property sheet is an intrinsic property of the containing object called property sheet, so to reference a project custom property branchName, you could specify /projects/aProject/propertySheet/branchName.

As a convenience, CloudBees CD/RO allows the property sheet path element to be omitted and the path written as /projects/aProject/branchName. If there is no intrinsic property with the same name, the path finds the property on the property sheet.

Custom properties in a property sheet can be one of two types: string property or a property sheet property. String properties hold simple text values. Property sheet properties hold nested properties. Nested properties are accessed via the property sheet property of their containing sheet.

For example:

/projects/aProject/propertySheet/topSheet/propertySheet/propB▼

/projects/aProject/topSheet/propB▼

All information managed by CloudBees CD/RO exists in the form of properties and property sheets and your own custom-created properties. For example, each project, procedure, and step is represented internally as a property sheet—the command for a step is actually a property associated with the step, and so on. Every value in the CloudBees CD/RO system can be accessed as a property, using the naming facilities described below. These properties are called intrinsic properties.

CloudBees CD/RO enforces some restrictions on intrinsic property values, whereas custom properties can have any value you choose.

To learn more about intrinsic properties defined for an object by CloudBees CD/RO, refer to Use the CloudBees CD/RO Perl API. For example, to learn about intrinsic properties associated with each project, find the documentation for the getProject ectool command. The result of running this command is an XML document whose field names and values represent the properties for the project.

See Intrinsic properties listed by object type for further information.

Property names and paths

Properties are named using multi-level paths such as first/second/third, which refers to a property named third in a property sheet named second in a property sheet named first. CloudBees CD/RO also supports an equivalent notation using brackets instead of slashes. In this format, slashes are not considered separators when they appear between brackets.

For example, first[second]/third and first[second][third] both refer to the same property as first/second/third. The bracket [] notation is based on matching brackets. For example, steps[build[1]] refers to a property named build[1] inside a property sheet named steps; it does not treat build as a property sheet containing a property named 1.

Property names/paths have two forms: absolute and relative .

Absolute property paths

Absolute property paths are referenced by a fully-qualified path syntax that begins with a slash character (/) followed by a top-level name. This path syntax is similar to a file system path specification. The first component after the slash must be one of several reserved words that select a starting location to look up the property name. For example, consider the property name /server/Electric Cloud/installDirectory. /server means lookup starts in the topmost property sheet associated with the CloudBees CD/RO server. This property name refers to the "installDirectory" property inside the server property sheet.

The system defines the following top-level absolute property names:

Absolute property path Description

/artifacts/…

Start in the property sheet containing all artifacts. For example, /artifacts/myGrp:myKey/prop1 refers to the prop1 property on the artifact whose name is myGrp:myKey.

/artifactVersions/…

Start in the property sheet containing all artifact versions. For example, /artifactVersions/myGrp:myKey:1.0-36/prop1 refers to the prop1 property on the artifact version whose name is myGrp:myKey:1.0-36.

Throughout the API, you can substitute groupId:artifactKey:version wherever an artifactVersionName argument can be specified. This is the same if the artifactVersionNameTemplate specified in the artifact is in the form groupId:artifactKey:version. When the template is different, it is convenient to be able to specify this tuple if you do not know the artifactVersionName.

/groups/…

Start in the property sheet containing all groups. For example, /groups[dev] refers to the group named dev.

/jobs/…

Start in the property sheet containing all jobs. For example, /jobs[ecloud.4096] refers to the job named ecloud.4096. You can name a job using either its name (as in the preceding example) or using the unique identifier assigned to it by CloudBees CD/RO.

/plugins/…

Start in the property sheet containing all plugins. For example, /plugins[EC-AgentManagement] refers to the currently promoted plugin named EC-AgentManagement and /plugins[EC-AgentManagement]/project/procedures[scpCopyFile] refers to a procedure named scpCopyFile in that plugin.

There is a subtle difference between:

ectool setProperty /plugins/EC-AgentManagement/project/foo bar▼

and

ectool setProperty /plugins/EC-AgentManagement/foo bar▼

The former places the property on the plugin’s project and can be referenced by $[/myProject/foo] while the latter places the property on the plugin object and will not be found via $[/myPlugin/foo].

/projects/…

Start in the property sheet containing all projects. For example, /projects[nightly] refers to the project named "nightly," and /projects[nightly]/procedures[main] refers to a procedure named "main" in that project.

/repositories/…

Start in the property sheet containing all artifact repositories. For example, /repositories/repo1/prop1 refers to the prop1 property on the repository whose name is repo1.

/resourcePools/…

Start in the property sheet containing all resource pools. For example, /resourcePools[linuxA] refers to the resource pool named "linuxA".

/resources/…

Start in the property sheet containing all resources. For example, /resources[linux1] refers to the resource named "linux1".

/server/…

Start in the top-level server property sheet. For example, /server/a refers to the server property named "a".

/users/…

Start in the property sheet containing all users. For example, /users[Bob] refers to the username "Bob".

/workspaces/…

Start in the property sheet containing all workspaces. For example, /workspaces[default] refers to the workspace named "default."

Relative property paths

Property names that do not begin with / are relative and looked up starting in the current context. For example, when executing a job step, the current context includes properties defined for the job step, parameters for the current procedure, and global properties on the current job.

Relative property paths are distinguished from absolute property paths because they do not begin with one of the top-level names. To avoid having to construct full property paths, CloudBees CD/RO supports the concept of a relative property path.

In use, the relative property path value is resolved by its context and a defined search order, which results in accessing the value of an absolute fully-specified property value. Contexts and search orders are as follows:

In a job step context, CloudBees CD/RO searches for relative property paths in the following order:

a property on the job step object
a property of the parent job step object, which includes parameters of the procedure on which the step is defined

a property on the job object

The search can be enabled or disabled by using the --extendedContextSearch option on the ectool getProperty or setProperty commands. When searching for a property value, disable the search by setting the --extendedContextSearch switch to false, requiring the property to exist on the job step object or return false. When writing a new value to a property, enable the search by setting the --extendedContextSearch switch to true, allowing the search for a property within the search order before creating a new one. New properties are created on the job step object.

Parameters for subprocedure calls from job steps are searched for in a job step context.
For procedure parameters for nested subprocedures, properties referenced by parameters are looked up as described [above] for job steps.

When expanding schedule parameters, CloudBees CD/RO searches the relative property path in the following order:
- A property on the procedure being called
- A property on the project on which the procedure being called is defined
- A property on the server
In a job name template context, CloudBees CD/RO searches for the relative property path as a property on the job.
In any other context, CloudBees CD/RO searches for the relative property path as a property on the context object.

jobSteps Paths

You can also specify a property on a job step as /jobSteps/parent/propertyName where:

parent is the root parent of the job step that is not visible on the CloudBees CD/RO UI.
propertyName is the name of the property.

Property name substitutions

Property names can contain references to other properties, which are then substituted into the property name before looking it up. For example, consider the following property name:

/myStep/$[/myProcedure/procedureName]▼

If the value of /myProcedure/procedureName is xyz, the property above is equivalent to /myStep/xyz.

Expandable properties

Property values can contain property references using the $[] notation.

For example:

Create a property named "foo" with a value of hello $[bar].
Create a property named "bar" with a value of world.
Reference "foo" (either using $[foo] or ectool getProperty foo ). The value "hello world" is returned.

If you want just the literal value of "foo" (useful in the UI, for example), you can use the expand option in ectool:

ectool getProperty foo --expand false▼

The value hello $[bar] is returned.

Properties are expanded by default when you use getProperty or getProperties.

If the value of a property contains $[] but you do not want it to be interpreted as a property reference, you can use the expandable option:

ectool setProperty symbols '$[!@]#' --expandable false▼

This option can be toggled in the web UI as well. Properties are expandable by default.

Because you cannot control where your expandable property might be referenced (and therefore which context is used during expansion), we recommend using absolute paths when referencing a property from the value of another property.

In the example above, if you define both foo and bar as properties on a project proj1, you might assume there is no problem with the value of foo. However, if you later reference foo from a job under proj1 (for example, $[/myProject/foo]), foo is referenced with the job step as its context. Therefore, when the value of foo is expanded, you get a PROPERTY_REFERENCE_ERROR because bar is not defined in the context of the job step.

Custom property names and values

The following properties are used by the standard CloudBees CD/RO UI, so you should use these property names whenever possible, and avoid using these names in ways that conflict with the definitions below.

compiles: the number of files compiled during the job step
diagFile: the filename in the top-level directory of the job’s workspace, containing diagnostics extracted from the step’s log file
errors: the number of errors (compilation failures, test failures, application crashes, and so on) that occurred during the job step. When property errors are set by postp, the step outcome is set to error also.
tests: the number of tests executed by the job step, including successes and failures
testsSkipped —the number of tests skipped during the job step
warnings: the number of warnings that occurred during the job step. When property warnings is set by postp, the step outcome is set to warning also.
preSummary: if this property exists, its value is displayed in the "Status" field (on the Job Details page) for this step. This property appears before whatever would normally be displayed for status. If the property contains multiple lines separated by newline characters, each line is displayed on a separate line in the status field.
postSummary: if this property exists, its value is displayed in the "Status" field (on the Job Details page) for this step. This property appears after whatever would normally be displayed for status. If the property contains multiple lines separated by newline characters, each line is displayed on a separate line in the status field.
summary: if this property exists, its value is displayed in the "Status" field (in the job reports) for this step, replacing whatever would normally be displayed for status. If the property contains multiple lines separated by newline characters, each line is displayed on a separate line in the status field.

The property hierarchy

All CloudBees CD/RO properties fall into a hierarchical structure, and you can reference any property using an absolute path from the root of the hierarchy. This includes properties you define and intrinsic properties defined by CloudBees CD/RO.

For example, each step contains a property resource that provides the resource name to use for that step. All steps of a procedure exist as property sheets underneath the procedure. All procedures in a project exist as property sheets underneath the project, and so on.

The examples below illustrate some nesting relationships between objects.

For example, the path notation /projects[projectName]/procedures[procedureName] (or equivalently, /projects/projectName/procedures/procedureName) means each project object contains a property sheet named procedures holding all procedures defined within that project. Within the procedure’s property sheet, there is a nested property sheet for each procedure, named after the procedure. Thus, the name /projects[a]/procedures[b] refers to a procedure named b contained in a project named a.

Each project may contain procedures, schedules, credential definitions, workflow definitions, workflows and numerous other object types:

/projects[projectName]/procedures[procedureName]
/projects[projectName]/schedules[scheduleName]
/projects[projectName]/credentials[credentialName]
/projects[projectName]/workflowDefinitions[workflowDefinitionsName]
/projects[projectName]/workflows[workflowName]▼

Each procedure contains steps and parameters. The parameters are formal parameters, meaning they specify parameter names the procedure accepts, whether each parameter is required, and so on: /projects[projectName]/procedures[procedureName]/steps[stepName], /projects[projectName]/procedures[procedureName]/formalParameters[parameterName]
Steps that invoke subprocedures contain parameter values for the subprocedure. These are called actual parameters because they provide actual values that are passed into the subprocedure: /projects[projectName]/procedures[procedureName]/steps[stepName]/actualParameters[parameterName]
Each job contains a collection of job step objects for steps in the outermost procedure, along with parameter values passed into the job when it was invoked: /jobSteps[jobStepId], /jobs[jobId]/actualParameters[actualParameterName]
If a job step invokes a nested subprocedure, its property sheet contains parameter values that were passed into the nested subprocedure, plus all job steps corresponding to that procedure: /jobs[jobId]/steps[stepName]/steps[stepName]/actualParameters[actualParameterName]
Schedules contain parameter values for the procedures they invoke. These are called actual parameters because they provide actual values passed into the procedure: /projects[projectName]/schedules[scheduleName]/actualParameters[parameterName]
Workflow definitions contain state definitions: /projects[projectName]/workflowDefinitions[workflowDefinitionName]/stateDefinitions[stateDefinitionName]
Transition definitions contain actual parameters: /projects[projectName]/workflowDefinitions[workflowDefinitionName]/transitionDefinition/actualParameters[parameterName]
State definitions contain transition definitions, actual parameters, and formal parameters: /projects[projectName]/workflowDefinitions[workflowDefinitionName]/stateDefinitions[stateDefinitionsName]/actualParameters[parameterName] stateDefinition/formalParameters[parameterName], /projects[projectName]/workflowDefinitions[workflowDefinitionName]/stateDefinitions[stateDefinitionsName]/transitionDefinitions[transitionDefinitionName]
Workflows contain states: /projects[projectName]/workflows[workflowName]/states[stateName]
Transitions contain actual parameters: /projects[projectName]/workflows[workflowName]/transitions[transitionName]/actualParameters[parameterName]
States contain transitions, actual parameters, and formal parameters: /projects[projectName]/workflows[workflowName]/states[stateName]/actualParameters[parameterName], /projects[projectName]/workflows[workflowName]/states[stateName]/formalParameters[parameterName], /projects[projectName]/workflows[workflowName]/states[stateName]/transitions[transitionName]

Special property references

CloudBees CD/RO also supports several special property reference forms that are described in the following subsections.

increment

Use this form to increment the value of an integer property before returning its value. For example, suppose property xyz has the value 43. The property reference $[/increment xyz] first increments the value of property xyz to 44, and then returns 44. If the property does not exist, it is created and set to the value 1.

timestamp

Use this form to generate a formatted timestamp value. For example, the property reference $[/timestamp yyyy-MMM-dd hh:mm] returns the current time in a form such as "2022-Jun-21 04:25". The pattern following /timestamp specifies how to format the time and defaults to yyyyMMddHHmm. The pattern follows conventions for the Java class SimpleDateFormat, where various letters are substituted with various current time elements. For more information about the SimpleDateFormat class, refer to https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html. Here are some of the supported substitutions:

y—Year, such as "2007" or "07"

M—Month, such as "April", Apr", or "04"

w—Week in year, such as "27"

W—Week in month, such as "3"

D—Day in year, such as "194"

d—Day in month, such as "18"

E—Day in the week, such as "Tuesday" or "Tue"

a—am/pm marker, such as "PM"

H—Hour in day (0-23), such as "7"

h—Hour in am/pm (1-12), such as "11"

m—Minute in hour, such as "30"

s—Second in minute, such as "15"

S—Millisecond, such as "908"

z—Time zone such as "Pacific Standard Time", "PST", or "GMT-08:00"

Z—Time zone such as "-0800"▼

Repeated letters cause longer forms to be substituted. For example, yy substitutes the last 2 digits of the current year, whereas yyyy substitutes the 4-digit year number. Single quotes can be used to substitute text directly without the above interpretations.

Javascript

This form executes a Javascript code fragment inside the CloudBees CD/RO server and returns the result computed by that code. For example, $[/javascript 4*2] returns "8.0". Javascript code can be arbitrarily long and include multiple statements. The value of the last statement is returned by the property reference.

Javascript code executes in an interpreter that provides access to CloudBees CD/RO properties and the CloudBees CD/RO API:

The normal way to access property values is through Javascript objects. Global Javascript objects named "server," "projects," and so on, exist and correspond to all top-level objects in an absolute property path. For example, there is a Javascript object named server that corresponds to the path /server, and a Javascript object named myJob that corresponds to the path /myJob. You can use either . or [] notation to access properties within the object. For a more complete list of top-level objects, refer to Absolute property paths. Examples:
- $[/javascript myJob.mightExist] is a safe way to refer to an optional parameter.
- $[/javascript (myJobStep.errors > 0) ? "step failed" : "no errors"] test a value and return another string based on the result.
- $[/javascript server.settings.ipAddress] refer to a property in a nested property sheet.
- $[/javascript server["CloudBees"].installDirectory] if the property name has spaces or other special characters, use the [""] notation.
  
  For example, $[/javascript projects["My Project"]["A Property sheet"].aPropertyName]. Note that there is no . in front of the [.
You can also call the getProperty function. It takes a property name as an argument and returns the value of that property. This is most useful when you want to access another special property reference. Examples:
- $[/javascript getProperty ("/timestamp yyyy-MMM-d hh:mm")] returns the current time.
- $[/javascript getProperty ("/increment /myJob/jsCount")] returns the incremented value of the property.
- $[/javascript (getProperty("/myJobStep/errors") > 0) ? "step failed" : "no errors"] returns "step failed" if the property "errors" on the current job step had a value greater than zero, and it returns "no errors" otherwise.
If calling the setProperty function, similar to getProperty, there are two variations on the function:
- A global function variation that uses the current context object. The global function takes 2 or 3 arguments. The 3-argument version takes a context object, a path, and a value. The 2-argument version omits the context object and uses the current context object (for example, job step ). Example: setProperty (myProject, "foo", "bar") would set the value of the "foo" property on the current project to "bar".
- An object function variation that can be called on objects, which uses that object as a context object. The object function takes two arguments: a "path" and a "value". Example: server.setProperty("aProp", "123") would set the aProp property on the server object to the value "123".
You can also make calls to any API. The APIs take a JavaScript key-value pair value array as an input, where the key is the API field name. For example:
- $[/javascript api.getResource({resourceName:"local"}).resource.hostName] returns the name of the host where the local agent is running. For the API field names and expected value types, refer to the ectool documentation.
- Property references can also be used for field values. For example, the following is valid if run in the context of a job step:
  $[/javascript api.getResource({resourceName:myJobStep.assignedResourceName}).resource.hostName]
- To view the API return data structure, you can use the JavaScript method JSON.stringify() or the command line ectool:
  ectool --format json getResource local