Properties in Build

Properties can be set for many different things, including projects, build configurations, process configurations, build requests, and the server. You can also set and retrieve agent properties.

The scripting API can be found at the following location:

server_url/tools/scripting/ibm-ucb-scripting/

The API documentation contains many useful scripting examples.

Properties can be referenced by processes and passed to other objects. Property values can be defined when a property is created, or at some other point. The following syntax is used to reference properties:

${p:property_name}

You can also use this syntax:

${property:property_name}

If the property is not in the current context or scope, you add a prefix to the name to identify the context. The following syntax is used to reference properties outside the current context:

${p:prefix/property_name

For example, you can refer to a project property named URL by using the following syntax:

${p:project/URL}

To retrieve the value of a specific property, you can use the @name= syntax. For example, to retrieve the value of a project property that is named specific.property, you can use the following syntax:

${p:project/properties[@name='specific.property'}

If you do not use a prefix, the property is resolved by the property order of precedence. The following table provides the property order of precedence and the prefix that is used for every context. The property is always resolved in the current context, if possible; otherwise, the property is resolved according to the property order of precedence. The order is resolved from top of the list to bottom.

For example, if you have a variable that is named URL in both the step and job contexts, both contexts can refer to its own property by using the property name:

${p:URL}

If either context refers to the property in the other context, the prefix can be used. For example, the job can refer to the step property by using this syntax:

${p:step/URL}

If a step and a request both have a property that is named URL, then if a job refers to the property without using a prefix, the property resolves to the step property value. In this instance, if you want the job to refer to the request context, you must use the prefix: ${p:request/URL}.

To retrieve the value of a property in another context that is itself retrieved from another context, you can chain prefixes. For example, to retrieve the project name from a build life, you might use this syntax:

${p:buildlife/workflow/project/name}

In most cases you can retrieve the project name with the more straightforward ${p:project/name}, but this example illustrates how you might handle complicated contexts.

Table 1. Property order of precedence and context prefixes
Context	Description
Step	Context: Plug-in job steps. Syntax: `${p:step/property_name}`.
Job	Context: jobs. Syntax: `${p:job/property_name}`.
Request	Context: build requests. Syntax: `${p:request/property_name}`.
Source configuration (source plug-in steps only)	Context: source configuration template steps. Syntax: `${p:source/property_name}`.
Source configuration	Context: source configurations. Syntax: `${p:process/sourceConfigs/properties[@name='property_name']}`. Source configurations are defined for build processes.
Process	Context: processes. Syntax: `${p:process/property_name}`.
Build life	Context: build life. Syntax: `${p:buildlife/property_name}`.
Build life	Context: build life. Syntax: `${p:buildlife/id}`. Returns the current build life ID. The Groovy equivalent is `${gvy:BuildLifeLookup.current.id}`
Build life build process	Context: build process. Syntax: `${p:originatingProcess/property_name}`.
Build life build request	Context: build request. Syntax: `${p:originatingRequest/property_name}`.
Project	Context: project. Syntax: `${p:project/property_name}`.
Server	Context: server. Syntax: `${p:property_name}`. Note: There is no context prefix for server properties. Ensure that the names of your server properties are not duplicated by properties in other scopes.

Agent properties

Agent properties have a separate context. You can access agent properties directly, and you can access the agent environment variables. To refer to an agent property, use the following syntax:

${property_name}

You can also use this syntax:

${a:property_name}

${agent:property_name}

To access an agent environment variable, use the following syntax:

${env/PATH}

Property options

Many property elements are scripts. The scripts can be written in JavaScript™, Groovy, and BeanShell script. Scripts usually return an object or a value. Property prefixes are scripts that are used to dynamically reference properties in other contexts or scopes. The following table describes the property syntax options.

Table 2. Property syntax options
Property	Description
`${p:property_name}`	If defined as a non-agent property, return the property value. If the property is not defined, leave the property expression.
`${p?:property_name}`	If defined as a non-agent property, return the property value. If the property is not defined, return an empty string.
`${property_name}`	If defined as an agent property, return the property value. If the property is not defined, leave the property expression. You can also use the following syntax: `${a:property_name}`, or `${agent:property_name}`.
`${?:property_name}`	If defined as an agent property, return the property value. If the property is not defined, return an empty string. You can also use the following syntax: `${a?:property_name}`, or `${agent?:property_name}`.
`${gvy:script_body}`	Run `script_body` as Groovy and replace it with the return value.
`${bsh:script_body}`	Run `script_body` as BeanShell and replace it with the return value.

The `startsWith`, `contains`, and `matches` functions

You can retrieve all property values based on a property name. To retrieve all values, use the startsWith, contains, or matches functions, as shown in the following code examples:

    ${p:fn:startsWith(project/properties, 'prefix')}
    ${p:fn:contains(project/properties, 'text')}
    ${p:fn:matches(project/properties, 'prefix.*')}

    ${p:fn:startsWith(originatingProcess/properties, 'prefix')}
    ${p:fn:contains(originatingProcess/properties, 'text')}
    ${p:fn:matches(originatingProcess/properties, 'prefix.*')}

    ${p:fn:startsWith(process/properties, 'prefix')}
    ${p:fn:contains(process/properties, 'text')}
    ${p:fn:matches(process/properties, 'prefix.*')}

    ${p:fn:startsWith(request/properties, 'prefix')}
    ${p:fn:contains(request/properties, 'text')}
    ${p:fn:matches(request/properties, 'prefix.*')}

    ${p:fn:startsWith(buildlife/properties, 'prefix')}
    ${p:fn:contains(buildlife/properties, 'text')}
    ${p:fn:matches(buildlife/properties, 'prefix.*')}

    ${p:fn:startsWith(agent/properties, 'prefix')}
    ${p:fn:contains(agent/properties, 'text')}
    ${p:fn:matches(agent/properties, 'prefix.*')}

Properties in Build

Agent properties

Property options

The startsWith, contains, and matches functions

The `startsWith`, `contains`, and `matches` functions