<%@ page isELIgnored="true" %> <%@ taglib uri="cms" prefix="cms" %> Properties

Properties

AnthillPro properties use the syntax ${property:[property_name]} to pass property values to commands being executed by AnthillPro. Often, properties are used to manage variables passed into commands, agent filters, and custom stamping algorithm templates.

For example, if a workflow has a property named platform passed into a Nant script via the Nant integration, something similar to PlatProp=${property:platform} would be set on the Nant Properties tab. At the command line, this would translate to the flag -D:PlatProp:x86 if the value of the property was 'x86'. Here, the property is used as if it was passed to the Nant executable on the command line.

Properties are resolved from the smallest scope to the most general scope (e.g., Job properties are resolved before project properties, which in turn are resolved before system properties).

Property Resolution Order:

  1. Job Instance and Job Iteration Property. Configured in the settings of an iterating job, they set the parameters for a single job that is run many times. See Job Instance and Job Iteration Properties.

  2. Build Request Property. When set as a workflow property as shown below, the property will get pushed to the build request before the build begins. See Build Request Properties.

  3. Workflow Property. Used to specify a property for a given execution of a workflow. Workflow properties are also used to send a build to a particular platform when writing native code for multiple platforms, etc. See Workflow Properties. See also:

  4. Build Life Property. See Build Life Properties.

  5. Build Life Originating Workflow Request Property. When set as a workflow property, the value will get pushed to the Build Life originating workflow before the build begins. See Build Life Originating Workflow Request Properties.

  6. Project Environment Property. Used to customize deployments based on the environment they are deployed to. Project Environment properties are automatically placed as environment variables for all commands run in the target environment. See Project Environment Properties.

  7. Project Property. Used for all workflows regardless of the target environment. See Project Properties.

  8. Environment Property. Environment properties are used to set default values for a particular environment. Other property types, except system properties, always override the environment-level properties See Environment Properties.

  9. System Property. Used to set default values for a particular property for all workflows and projects system wide. See System Properties.

In addition, AnthillPro has two other property types, which are resolved separately from those listed above. See Specialized Builder Properties and Agent Properties.

Property Resolution

Below is a general outline of property resolution used throughout the AnthillPro system:

PropertyResolution

${property:<property-name>}

or

${p:<property-name>}		Return the non-agent property value if defined. If not defined, return the given expression.

${property-:<property-name>}

or

${p-:<property-name>}		Return the non-agent property value if defined. If not defined, return null.

${property?:<property-name>}

or

${p?:<property-name>}		If defined as a non-agent property, replace with the value. If not defined, replace the expression source.

${agent:<property-name>}

or

${a:<property-name>}		Return the agent property value if defined. If not defined, return the given expression.

${agent?:<property-name>}

or

${a?:<property-name>}

or

${?:<property-name>}

If defined as an agent property, replace with the value. If not defined, replace the expression source.

${<property-name>}

or

${<property-name>}		Return the agent property value if defined. If not defined, return null.

Empty Values in Properties

Empty-value properties enable users to set a standard for the available attributes a user can provide when executing a resource. For example, using an empty-value property (for both user-overridable and non-overridable properties) will allow the same library job to be reused across a large number of projects, even if different projects require different values. If most projects using the same library job need to pass parameters at run time, but some of them don't, using a empty-value property gives users the option to define a required value or simply pass a blank value that AnthillPro will effectively ignore. Used in this way, empty-value properties can be used to create standardized templates for creating new projects.

Example usage for resolving empty properties using a simple echo use case. If nothing follows "echo," that means empty has been returned.

PropertyResolution
echo ${property:property}

When "property" is not defined:

echo ${property:property}

When "property" is defined on project as "value":

echo value

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo ${property:property}

echo ${p:property}

When "property" is not defined:

echo ${p:property}

When "property" is defined on project as "value":

echo value

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo ${p:property}

echo ${property?:property}

When "property" is not defined:

echo

When "property" is defined on project as "value":

echo value

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo

echo ${p?:property}

When "property" is not defined:

echo

When "property" is defined on project as "value":

echo value

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo

echo ${agent:property}

When "property" is not defined:

echo ${agent:property}

When "property" is defined on project as "value":

echo ${agent:property}

When "property" is defined on project as "":

echo ${agent:property}

When "property" is defined on agent as "value":

echo value

echo ${a:property}

When "property" is not defined:

echo ${a:property}

When "property" is defined on project as "value":

echo ${a:property}

When "property" is defined on project as "":

echo ${a:property}

When "property" is defined on agent as "value":

echo value

echo ${agent?:property}

When "property" is not defined:

echo

When "property" is defined on project as "value":

echo

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo value

echo ${a?:property}

When "property" is not defined:

echo

When "property" is defined on project as "value":

echo

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo value

echo ${?:property}

When "property" is not defined:

echo

When "property" is defined on project as "value":

echo

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo value

echo ${property}

When "property" is not defined:

echo ${property}

When "property" is defined on project as "value":

echo ${property}

When "property" is defined on project as "":

echo ${property}

When "property" is defined on agent as "value":

echo value

echo ${bsh:ProjectLookup.getCurrent().getName()}

When "property" is not defined:

echo Resolve to Null Test

When "property" is defined on project as "value":

echo Resolve to Null Test

When "property" is defined on project as "":

echo Resolve to Null Test

When "property" is defined on agent as "value":

echo Resolve to Null Test

echo ${bsh:PropertyLookup.get("property")}

When "property" is not defined:

echo ${bsh:PropertyLookup.get("property")}

When "property" is defined on project as "value":

echo value

When "property" is defined on project as "":

echo

When "property" is defined on agent as "value":

echo ${bsh:PropertyLookup.get("property")}

Setting Default Properties

Properties are commonly used to enforce conventions across the system, environment, project, workflow, and/or job. To control how a group of related resources act, a property is set at the lower property-resolution level: For example, to set a default property for every workflow within a project, you would set a project property. Likewise, if most projects require a specific tool when deploying, then setting a system property will help ensure that all projects deploy correctly. For the odd projects that don't conform to the default patterns, the property may be overridden at a level closer to the job execution (i.e., if you have a system default property, it may be overridden at the project, workflow, or job levels on a as-needed basis).

Consider this common scenario: A team stores most of their build scripts for almost every project in a folder called "build" under the root of their project. There are a number of ways (and places) to configure a property that can act as a default for most projects, ensuring the correct script is used when building: Basic AnthillPro configuration suggests creating either a project or workflow property called build.dir and reference the property in the configuration that kicks off the build script(s). This works for all but the corner cases, but can include a lot of configuration if you have a lot of projects and/or workflows. For setting these types of standards, however, it's usually easier to create a system level property (System > Properties) and only specify the build.dir property on the odd projects/workflows that don't conform to the common pattern. In this case, the System level property would be "build". If an absolute path is needed for some reason, System Properties can reference runtime properties. So a System Property of ${property:work.dir.path}/build would result in the absolute path to the same build sub-folder. A workflow that set the build.dir to /some/other/path would use that -- completely ignoring the System level setting because properties set closer to the execution of a step always override properties set at higher levels.

Job Instance and Job Iteration Properties

Job iteration properties are configured after iterating a job. They are typically used to set the parameters for a single job that is run many times, with a slightly different parameter each time. For example, a job iteration property might include variations such as "module to compile", "test to run", etc.

Typically, properties set on the job iteration are used by a scripted agent selection (filter) script that you must create yourself. The script evaluates the property when the job is requested, and then runs each iteration on the agent(s) that have the appropriate (i.e., corresponding) property-value pair. For example, if you set a property called "my_property" with a value of "1" on iteration one, the agent selection script will only run iteration one on the agent(s) that have "my_property" with a value of "1" set on it/them. (More at Tools > anthill3-dev-kit.zip > Scripting > Example: Select Agents Based on Job-iteration Properties).

Job Iteration Properties Prerequisites

  • You must have AnthillPro administrative privileges to set job properties. See Manage Security.

  • A Project with an originating workflow and at least one job must already be active.

  • The job must already be iterated. See Iterate a Job.

  • If you are planning on using job-iteration properties to determine which agent each iteration will run on, you will need to create a new Agent Filter Script. See Tools > anthill3-dev-kit.zip > Scripting > Example: Select Agents Based on Job-iteration Properties.

  • Corresponding properties must be set on the agent(s) so that when the agent filter script runs, it will select the correct agent(s). See Configure and Edit Agent Filters.

Setting Job Iteration Properties

Properties are set in the name=value format. For example, to iterate a job to run two different test suites, you can set a property (with a name of dir-location) that has two values (/temp/test1 and /temp/test2), with each value corresponding to a single iteration of a job:

Once you configure the names and properties of each job iteration, AnthillPro will set the iteration name and iteration number as job properties during each job iteration. The iteration name is set as: anthill.job.iteration.name and the iteration number is set as: anthill.job.iteration. Once the job has run, you can view this on the Build Life.

In addition, corresponding properties must be set on the appropriate agent(s) if you want AnthillPro to select an agent based on job-iteration properties. See Configure and Edit Agent Filters.

  1. See Tools > anthill3-dev-kit.zip > Scripting > Example: Select Agents Based on Job-iteration Properties before continuing.

  2. Go to Administration and select the workflow that contains the iterated job. See Iterate a Job.

  3. On the workflow page, select the Definition tab.

  4. Click the iterated job and select Iteration Properties from the menu.

  5. Iteration Properties page. The iterations you already set (see Iterate a Job) are populated with a default name (e.g., Iteration 1 , Iteration 2, etc.). If you want to change the name of an iteration, click the name and type the new name.

    To add a new property name, give the name of the iteration property (e.g., dir-location) and click Set. (Note you may have to scroll to the bottom of the page, depending on how large the browser window is.) When that is done, you can create iteration values (e.g., /temp/test1 and /temp/test2) for each property by clicking the appropriate cell and typing.

    You can also include a value when creating the property name. When created in this way, the same value (e.g., /temp/test1), will be added to each iteration property. So, if you have a number of iterations that require the same property value, you only have to type it once if you configure the property in this manner.

  6. Click Save.

  7. When done, click Cancel to exit the Iteration Properties page.

Build Request Properties

When set as a workflow property as shown below, the property will get pushed to the build request before the build begins.

Example Build Request Property:

import com.urbancode.anthill3.runtime.scripting.helpers.*;
import com.urbancode.anthill3.domain.buildrequest.*;

//look up the current build request

BuildRequest br = BuildRequestLookup.getCurrent();

//set the property

br.setProperty("myProperty", "myValue");

Workflow Properties

Workflow properties are used to specify a property for a given execution of a workflow (see Managing Properties). A common example of a workflow property is the tag (or label, or baseline) used in a "Build From Label" workflow that checks out a particular version of the source code from source control and performs a build.

Workflow properties are also used to send a build to a particular platform when writing native code for multiple platforms, etc. Workflow properties may be either optional or required, may have default values, may be locked so that end users can't change the default, or dynamic (i.e., AnthillPro generates the property value based on user-defined criteria). Once a workflow property is created, the display type may be changed by selecting the Change icon on the configuration page.

Additionally, use the Operations menu (on the workflow's Properties tab) to (a.) determine the order of properties; (b.) edit a configured property; and (c.) delete a property.

There are six different workflow property types to choose from. They range from the simple Checkbox type to the Text Area type, which can pass small scripts:

  • Checkbox. Use to require a user to check the box in order to run a workflow.

  • Multi-Select. Use to set pre-defined values where multiple values can be selected.

  • Select. Use to present a selection of pre-defined values where one value can be selected.

  • Text. Use to present a text input where a value can be entered. The Text property type may be scripted.

  • Text (secure). Use to present a text input where a secure value must be entered. The value is obfuscated in any output.

  • Text Area. Use to present a text area input where a longer value can be entered. The Text Area property type may be scripted.

See also Using Workflow Properties for Build Life Notes and Cascading Workflow Properties.

Workflow Properties Prerequisites

  • You must have AnthillPro administrative privileges. See Manage Security.

  • A Project with an originating workflow and at least one job must already be active.

Using Checkbox Workflow Properties

Use the checkbox workflow property to require a user to check the box in order to run a workflow. The Checkbox property displays a checkbox and sets a value of true if checked or false if not checked. By default, the property is selected; however the administrator may choose not to have the property set as a default. To run the workflow without the property, the administrator must allow users to override the default. For example, the user can run the workflow even though no value is selected. See Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Checkbox form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays a checkbox for the user when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. If unchecked, and the User Can Enter Value option is configured, the user can run the workflow without checking the box. When the default value is set but the user can't override the value, the property will not be visible to the user.

    • User Can Enter Value. To allow users to specify a non-default value when running this workflow, check the box. If the user may override the default property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name (defined above) as the Label.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value, or options are to be generated by a job that executes on an agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name (defined above) as the Label.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value, or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns Boolean. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name (defined above) as the Label.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

Using Multi-select Workflow Properties

Use the multi-select workflow property to set pre-defined values where multiple values can be selected. Once set, all selected values will become values of the property in one comma-separated value. See Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Multi-select form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays options for the user (either the property name or default value) when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. The default value must be a value from the allowed values list configured below if more than one value will be allowed.

    • User Can Enter Value. To allow users to enter a new value when running this workflow, check the box. If the user may override the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Allowed Values. Give the values users will select from when running the workflow. Each value must be input on a separate line. If any value is given, you must also define a default value above.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value or options are to be generated by a job that executes on a agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns string array or collection. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

Using Select Workflow Properties

Use the select workflow property to present a selection of pre-defined values where one value can be selected. See Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Select form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays choices for the user (either the property name or default value) when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. The default value must be a value from the allowed values list configured below if more than one value will be allowed.

    • User Can Enter Value. To allow users to specify a new value when running this workflow, check the box. If the user may override the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Allowed Values. Give the values users may provide for this property. Each value must be input on a separate line.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value or options are to be generated by a job that executes on an agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns string array or collection. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

Using Text Workflow Properties

Use the text workflow property to present a text input where a value can be entered. The Text property type may be scripted. See Scripting and Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Text form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays a text input for the user (either the property name or default value) when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. The default value must be a value from the allowed values list configured below if more than one value will be allowed.

    • User Can Enter Value. To allow users to specify a new value when running this workflow, check the box. If the user may override the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value or options are to be generated by a job that executes on an agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns a string value. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

See also Using Workflow Properties for Build Life Notes.

Using Text (secure) Workflow Properties

Use to present a text input where a secure value must be entered. The value is obfuscated in any output (i.e., all strings matching secure value are replaced with **** in the output). The Text (secure) property type may be scripted. See Scripting and Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Text-secure form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays a secured field for the user (either the property name or default value) when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. If unchecked, the user must manually check the value when executing the workflow.

      • Confirm. Re-enter the secure value.

    • User Can Enter Value. To allow users to specify a new value when running this workflow, check the box. If the user may override the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value or options are to be generated by a job that executes on an agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns a string value. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

Using Text Area Workflow Properties

Use the text area workflow property to present a text area input where a longer value can be entered. The Text Area property type may be scripted. See Scripting and Setting Properties.

  1. Go to Administration and select the workflow to add properties to.

  2. On the workflow page, select the Properties tab.

  3. Click New Property, select Text Area form the drop-down menu, click Select, and provide the following:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Description. Provide an optional description for this property. If given, the description will be shown when prompting users for a value.

  4. Value. Select the value type. Choose either Defined (see Item 5), Job Execution (see Item 6), or Scripted (see Item 7).

  5. Defined-value property. Basic property type. Displays a text area for the user (either the property name or default value) when running a build. To configure, give the following:

    • Default Value. Check the box to make this a default value. The default value must be a value from the allowed values list configured below if more than one value will be allowed.

    • User Can Enter Value. To allow users to specify a new value when running this workflow, check the box. If the user may override the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  6. Job-execution property. Use this property type if the value, default value or options are to be generated by a job that executes on an agent.

    • Agent Filter. Select the agent filter script to be used when determining the value of this property. See Agent Filter (Selection) Scripts.

    • Job. Select the job to execute that will set the property value using this property name. Either project or library jobs may be used. When this job runs, the value of this property will be set.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  7. Scripted property. Scripted value properties are properties where the value, default value or options are generated by a script that is executed before workflow execution.

    • Value Script. Give a BeanShell script that returns string value. The BeanShell script will be passed the following implicit variables when applicable: project, workflow, Build Life, environment.

    • User Can Enter Value. To allow users to enter a value when running this workflow, check the box. If the user may enter a value for the property, give the following:

      • Label. Give a label for this property to be shown when prompting users for value. Leave blank to use the Name as the Label.

      • Is Required. Check the box to require the user to select a value for this property when the workflow is run.

    • Click Save and go to Item 8.

  8. To use Workflow properties run a build.

Workflow Request Properties

Workflow request properties are configured when a user adds input fields to a workflow (showing on the dashboard for build workflows and the secondary process pop-up for secondaries). For example, a workflow request property could be "clean vs. incremental build" or "Branch to build from". See Setting Properties.

Workflow Properties (from Originating-build Workflow)

The workflow property (from originating-build workflow) is similar to the Workflow Request Property; however, it is a secondary process resolving the variables from a previous Workflow. See Setting Properties.

Cascading Workflow Properties

If you have properties set on a workflow (e.g., parent workflow) that are also required when kicking off a child workflow (i.e., a deployment workflow), you can configure your job to pass the configured properties to the child workflow. Cascading properties is commonly accomplished when using the Run Another Workflow step. To cascade properties when kicking off another workflow:

  1. Go to your job and select the Insert After icon of the step immediately preceding where the Run Another Workflow step is to be included. Typically, this step is added near the end of a job.

  2. Open the Miscellaneous folder, select Run Another Workflow, and click Select.

  3. Configure step:

    • Name the step.

    • Description. Give an optional description.

    • Workflow. Select the workflow you want AnthillPro to run. Only secondary workflows available to this project will appear in the drop-down. Click Set.

    • Environment. Select the environment the child workflow is going to run in. If you don't see the environment you want, that is because the workflow you selected does not participate in that environment.

    • Wait for Workflow. Checking the box will force AnthillPro to wait for the parent workflow to complete before kicking off the child workflow. If checked, this step will not run if any previous job steps fail. Note that while waiting for the parent workflow to complete, the child workflow holds any Lockable Resource and counts as running on an agent.

    • Pass Properties. Select one of the options to cascade the properties from the parent workflow to the child workflow.

      • Do not pass properties. This is AnthillPro's default behavior. No request properties defined on the parent workflow will cascade to the child workflow.

      • Only properties with matching names. A request property on the parent workflow will cascade to the child if and only if the child workflow defines a property of the same name. For example, if both the parent workflow and the child workflow are configured with a property named 'agents', that property (including the value set on the parent workflow) will be passed to the child when this step executes. However, if the parent workflow has a property named 'Linux' configured but the child workflow does not, the 'Linux' property will not cascade to the child workflow.

      • Pass all properties. Pass all request properties from the current originating workflow to the child workflow, even if no matching property name is configured on the child workflow. For example, if both the parent workflow and the child workflow are configured with a property named 'agents', but have different values, the value set on the parent workflow will be used when running the child workflow. If a particular property is configured on the parent workflow, but not on the child, that property -- including its value -- will be passed to the child workflow at run time.

    • Show Additional Options (optional; advanced). Select the Show Additional Options link to configure more options.

      • Is Active. Select No to temporarily deactivate the step without deleting it; otherwise select Yes.

      • Pre-Condition Script. From the drop down menu, select the condition which must be met for the step to continue. Before editing an existing script or creating a new one, see Step Pre-Condition Scripts.

      • Ignore Failures. Select Yes if this step should not effect the determination for step continuation or the status determination of the job.

      • PostProcessingScript. Select a script for determining when commands should count as fail or succeed. See Post Processing Scripts.

      • Timeout. Enter the time in minutes after the start of the step when AnthillPro will consider the step as timed out and abort it.

  4. Click Save.

Dynamic Workflow Properties

The exercise below shows how dynamic workflow properties can be used to control which agents will be targeted for deployment. Configuration consists of creating a scripted multi-select workflow property, a scripted agent filter, and adding the run another workflow step to a job.

  1. Go to your build job (originating workflow) and set the iterations to -1 and unique agents. When set to -1, AnthillPro will iterate a job equal to the number of agents returned by the agent selection filter (discussed below). Selecting Unique Agents will cause AnthillPro to run each iteration on a separate agent.

  2. Create a new Agent Filter script (see Configure and Edit Agent Filters for more) that will return all agents that are referenced in the property value discussed below. The property name in the example is 'agents'. The property name in this script should be the name of the workflow property you will add in subsequent steps. Here is the script:

    import com.urbancode.anthill3.domain.agent.Agent;
import java.util.*;

return new Where() {
  public Agent[] filter(Agent[] agents) {
      agentNames = PropertyLookup.get("agents");
      nameArray = agentNames.split(",");
      agentList = new ArrayList();
      for (int a=0; a<agents.length; a++) {
          for (int n=0; n<nameArray.length; n++) {
              if (agents[a].getName().equals(nameArray[n])) {
                  agentList.add(agents[a]);
              }
          }
      }
      agents = agentList.toArray(new Agent[agentList.size()]);
      return agents;
  }
};

  3. On your workflow, create a scripted multi-select property. In the example, It is named 'agents'. The Agent Filter script created above must use the same name. When configuring the property, it should be user overridable and required. The script for value is:

    import com.urbancode.anthill3.services.agent.AgentManager;
import com.urbancode.anthill3.domain.agent.AgentFactory;

endpoints = AgentManager.getInstance().getOnLineEndpointArray(environment);
values = new String[endpoints.length];
for (int i=0; i<endpoints.length; i++) {
  agent = AgentFactory.getInstance().restoreByEndpoint(endpoints[i]);
  values[i] = agent.getName();
}
return values;

  4. Save your settings.

The next time the build runs, the user will be prompted to select an agent that was dynamically selected. The workflow will only be run if the user selects an agent form the list.

Build Life Properties

Set Build Life properties on originating workflows using an Evaluate Script job step. Build Life properties are typically used to hold variable data for builds (such as compiler version, etc.) or to create an audit trail. Once the property is set, and the build has run, the Build Life property will be visible on the Build Life page.

To use a Build Life property, add the Evaluate Script step to the job -- typically after the Populate Workspace and Get Change Log steps of the typical job. Once set on the originating workflow, Build Life properties are available to all secondary workflows (such as deployments, etc.) run on the Build Life, and are unique to the Build Life.

  • For originating workflows, use: BuildLifeLookup.getCurrent().setProperty("name", "value") to set the property at build time.

  • For secondary workflows, use: ${bsh: BuildLifeLookup.getCurrent().get(name)} to resolve the property when the workflow is run.

For more information on AnthillPro scripting, see Scripting Basics.

Build Life Originating Workflow Request Property

When set as a workflow property, the value will get pushed to the Build Life originating workflow before the build begins. This can be useful if you set user-overridable properties on the build workflow. See Workflow Properties to set the property.

Project-Environment Properties

Project environment properties may be used to customize deployments based on the environment they are deployed to. Project Environment properties are automatically placed as environment variables for all commands run in the target environment. This eases their use in shell scripts, Perl scripts, and make commands. They can also be looked up using the ${property:..} syntax (see Scripting). They are set on the properties tab on the Administration page.

In a J2EE project, for example, a typical deployment might involve deploying an EAR file to a server with a specific environment, user name, and password. These properties may be marked as secured. If secured, the value of the properties will appear in the UI and logs as '*****', and the properties will be encrypted in the database. The secured option guards against the leak of information (such as database passwords) to those permitted to configure a project or read a project log, but who are not permitted to deploy to some environments.

Most projects participate in multiple environments. Because each environment is different, project environment properties must be set for each environment the project is associated with. The process is the same for each environment; however, depending on the environment the property may be different. See Setting Properties.

Project Environment Properties Prerequisites

  • You must have AnthillPro administrative privileges. See Manage Security.

  • A Project with an originating workflow and at least one job must already be active.

Set Project Environment Properties

  1. Go to Administration and select the project to add properties to.

  2. On the project page, select the Properties tab.

    Use the ALL sub-tab to set properties for this project (see Project Properties). Any property set here will be set in every environment this project participates in.

    The environments this project participates in are listed as sub-tabs. To set an environment-specific property, select an environment. These properties are typically unique to the environment.

  3. Select a specific environment. Click the Add Property link on the Project Properties page. If the project is part of multiple environments, each environment will be listed separately. Set the project environment property for one environment then proceed to the others.

  4. Set property:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Value. Give the value, often a number or other value used to manage variables passed into commands, agent filters, and custom algorithm templates. See also Empty Values in Properties.

    • Secure. If using password properties and secure properties, check Yes. If the value does not need to be secure, check No. The value will be obfuscated in output and the UI.

    • Pass to Builders. Select Yes to pass this property to the builder. For example, if using Ant, AnthillPro typically calls the build.xml file for a build. However, if you select Yes, you can use AnthillPro to pass a property to the build script. The call would look something like ant build.xml -Dproperty. See Specialized Builder Properties.

    • Set in Environment. Select Yes to automatically set this property in the environment. This will allow the property to be passed to SCM steps and any other step that uses a shell command.

  5. To add another property, select the Add Property link again. Click Save when done.

  6. Repeat Items 3-5 to set project environment properties for other environments.

Project Properties

Project properties may be used for all workflows regardless of the target environment. They are set on the Properties tab on the Project's Administration page, and may be looked up by integration points and e-mail notifiers.

Project Properties Prerequisites

  • You must have AnthillPro administrative privileges. See Manage Security.

  • A Project with an originating workflow and at least one job must already be active.

Using Project Properties

  1. Go to Administration and select the project to add properties to.

  2. On the project page, select the Properties tab.

  3. Select the ALL sub-tab. Click the Add Property link on the Project Properties page. Any property set here will be set in every environment this project participates in.

    If the project is part of multiple environments, each environment will be listed separately. Set the project environment property for one environment then proceed to the others. See Project Environment Properties.

  4. Set property:

    • Name. Give the name of the property: the property <name> will be accessed as ${property:<name>}.

    • Value. Give the value, often a number or other value used to manage variables passed into commands, agent filters, and custom algorithm templates. See also Empty Values in Properties.

    • Secure. If using password properties and secure properties, check Yes. If the value does not need to be secure, check No. The value will be obfuscated in output and the UI.

    • Pass to Builders. Select Yes to pass this property to the builder. For example, if using Ant, AnthillPro typically calls the build.xml file for a build. However, if you select Yes, you can use AnthillPro to pass a property to the build script. The call would look something like ant build.xml -Dproperty. See Specialized Builder Properties.

    • Set in Environment. Select Yes to automatically set this property in the environment. This will allow the property to be passed to SCM steps and any other step that uses a shell command.

  5. To add another property, select the Add Property link again. Click Save when done.

Environment Property

Environment properties are used to set default values for a particular environment. Other property types, except system properties, always override the environment-level properties. To set an environment property:

  1. Go to Agents > Environment.

  2. On the Environments Page, select the environment you want to set a property for.

  3. Click Add Property.

  4. Configure settings:

    • Name the property.

    • Value. Give the value of the property.

    • Description. Give an optional description.

  5. Click Done.

System Properties

System properties are used to set default values for a particular property for all workflows and projects system wide. A frequently used default property name is useful when setting values for multiple projects. Other property types always override the system-level properties.

  1. Go to System > Properties under the Server menu.

  2. Click the Add Property button.

  3. Configure settings:

    • Name the property.

    • Value. Give the value of the property. A frequently used default property name is useful when setting values for multiple projects. If using a server property, all other property types may override the server property. See also Empty Values in Properties.

    • Description. Give an optional description.

  4. Click Done.

Specialized Builder Properties

Specialized 'builder' steps for tools like Ant, Maven, and Nant have a properties tab (these are properties as those tools understand them) available through the AnthillPro UI. Properties are then passed into the tools at the command line, using the tools specific format (usually -D.... ). Values for the properties may be one of the other property types or even a one-line BeanShell script.

Many users employ a builder property that looks up a job's stamp and then pass the stamp to a version property. In BeanShell, it would look like this: ${bsh:WorkfspaceVersion.get()}. For more scripting, see Tools > Development Kit Bundle > Scripting.

Agent Properties

Agent properties can be used when the behavior of a command needs to change depending on the particular server it is running on. Agent properties are also typically used to identify where build or testing tools are installed on a particular agent, etc.

To lookup an agent property in the configuration of a step, no special identifier need be used. Just use the syntax ${[agent_variable]}. For example, the Ant installation directory for version 1.7.2 of Ant might be looked up using ${ANT_HOME_1_7_2}. For more scripting, see Tools > Development Kit Bundle > Scripting.

The agent properties (go to Agents > Agent > select an agent) are stored on the server. When the agent starts up, it passes all of its properties to the server, which then stores it. If a property is added or changed, or the agent is upgraded, etc., the properties will be automatically updated on the server.

Note that there are four groupings of agent properties, but you can only configure Agent Properties. The other three categories are set by the AnthillPro system and are not configurable via the UI.

See Manage Agents, Configure Agent(s), and Setting Properties.

AnthillPro Properties

AnthillPro has a number of properties automatically set by the system. A number of the properties are used in conjunction with integrations, and are automatically set during configuration or at runtime. Most users will not need to modify the AnthillPro properties once they are set.

Agent PropertiesDescription
codestation.cache.dirLocation of the agent Codestation cache. Default is the agent user's home directory plus '.codestation'.
codestation.cache.timeToLiveNumber of days to keep something in the cache. Default is never.
codestation.noCacheControl over agent Codestation caching.
codestation.secondaryCache.dirLocation of secondary cache. Default is not enabled.
codestation.suppress.bomControl over whether .bom bill of materials files should be created when artifacts are resolved. Default is true.
lab.manager.<configuration>Identifies an agent as the agent installed in the <configuration> on VMware Lab Manager.
Build Life PropertiesDescription
anthill3.baseline.infoSet by ClearCase UCM Get ChangeLog and Rebase steps.
maven.lastUpdatedIdentifies when a Codestation Build Life was downloaded from a external Maven 2 repository.
maven.proxiedRepositoryIdentifies which external Maven 2 repository a Codestation Build Life was downloaded from.
maven.versionIdentifies an AnthillPro Build Life as a version to Maven 2.
Build Request PropertyDescription
anthill.buildlife.labelValue applied by a SCM Label step.
Job PropertiesDescription
anthill.job.iterationNumber of the job iteration being executed. Only available to iterated jobs.
anthill.job.iteration.nameUser-defined name of the job iteration being executed. Only available to iterated jobs.
git-revisionRevision retrieved during the Git Populate Workspace step.
mercurial-revisionRevision retrieved during the Mercurial Populate Workspace step.
synergySessionTokenSynergy session token set by all Synergy steps.
work.dir.pathSet/updated to the current working directory of the job on the agent.
workspace.dateSet to the actual workspace date of the Build Life (which is the date of the source used). Formatted 'yyyy-MM-dd hh:mm:ss.S a z'.
workspace.versionLatest Build Life stamp applied during the job
Maven PropertiesDescription
maven.artifactIdIdentifies a Codestation project, AnthillPro project or AnthillPro workflow with the Maven 2 artifactId.
maven.groupIdIdentifies a Codestation project, AnthillPro project or AnthillPro workflow with the Maven 2 groupId.