BuildForge Help

Step Properties

Step properties specify how to execute a step, handle its output, and what to do upon completion. A step command can also execute another project or library.

If a step property is not set explicitly, its value is inherited from the project.

Figure 1. Step Details Form, Showing Step Properties

Step properties include:
Name
The name of the step; a label for the step within the system.
Active
By default, all steps are enabled. To disable a step, select Disabled. A disabled step is not used when the system runs the project; it does not appear in the list of available steps if a user manually starts the project and selects specific steps to include or exclude. Use this feature to prevent an unfinished step from being executed, or to temporarily remove a problem step from a project.
Access
Choose an Access Group to define which users are allowed to use the step. You can use this property to restrict access to specific steps within a project. When a user who is not a member of the Access Group for a step launches the project that contains the step, the step is skipped.

Choosing Project Default causes the step to inherit the access properties of the project.

Directory and Path
The Directory field sets the final portion of the path for step command execution. By default, the Path is relative to the project path created on the server. The system automatically creates a unique directory for every job, and most steps should execute there. The Directory field provides a convenient way to execute commands in directories your project has constructed during a job. (Build Forge does not construct directories mentioned in the Directory field.)
The Absolute option for the Path field allows a step to ignore the project and job directories and access directories relative to the server's Path field.
  • If Relative is selected for thePath field, then step commands are executed in a path found by adding together the server, project, job, and step directories.
  • If Absolute is selected for the Path field, then step commands are executed in a path found by adding together the server and step directories. This option allows you to launch applications which are permanently installed on a server, separate from the project directory structure.
Command

Enter one or more operating system commands, subject to the following guidelines:

  • Separate individual commands by placing them on separate lines.

  • All the commands in a single step are executed on one server. If you want to be able to thread commands across multiple servers, you must place those commands in separate steps.

  • If you use more than one command in step, you may want to use command filters as the step's Result property. When you use the default Exit Code setting for the Result property of your step, the success or failure of the entire step is determined by the last command in the step. Earlier commands may succeed or fail, but the system only looks at the exit code of the last command. When you use a filter, you can catch failures in earlier commands.

  • You can enter multiple commands.

  • You can use the #! directive to specify the shell to be used to execute the command(s). This works on Windows® as well as Linux® and UNIX® systems (the Windows agent handles passing the commands to the specified interpreter). To send the commands from your step to a copy of Perl in c:\perl\bin on Windows, use #!c:\perl\bin\perl.exe If you use the Windows agent with Cygwin, but need to direct a command to the Windows shell cmd.exe, you can use the following line, which takes advantage of Windows implicit paths:
    #!cmd.exe /C
    Note that the /C option is required for cmd.exe as otherwise it waits for additional commands after your step commands are delivered to it. You might use the #!/bin/perl command on a UNIX or Linux machine.
    Note: When you use the #! command on Linux or UNIX systems, the system does not change to the standard default directory (the path constructed from a combination of the server path, project, name, and step path field) because it cannot predict the required syntax; you must include your own directory-changing command. Use special environment variables created by the system, such as BF_SERVER_ROOT and BF_PROJECTNAME_PHYS, to do this.
Environment

Environment: Choose an environment. The system applies the values in the environment you select before it runs the command. The final environment depends on inheritance from the server and project variables as well as the step variables.

Choosing Project Default causes the step to inherit the environment of the project.

Selector
The name of the selector to use when choosing a server for this project. You can leave this field blank to use the project's selector.
Broadcast
Check this box to run the step on every server that matches the step's selector. At run time, the system replaces a broadcast step with a series of steps, one for each server, and executes them serially or in parallel, depending on the broadcast step's Thread property.
Timeout
Specifies how long the system should wait for the current command to produce output. If the timeout value is reached, the system fails the project at the current step (unless the step is set to continue on fail).
Result
The Result property determines how the system judges whether a step succeeded or failed. Use the default value of Exit Code to determine success based on an exit code returned by the command shell. Or, choose a filter which examines the command output to determine success.
On Fail
The On Fail property determines whether the system Halts or Continues with the following step if the step fails. By default, the system halts and does not continue if the step fails.
Thread

Set this property to Yes to allow threading of this step (running the step in parallel with other steps). Set the property to No to avoid threading. Set the property to Join to separate threaded blocks of steps. The first set of steps must complete before the next set of threaded steps following the Join step can start.

Inline
Specifies a project to run inline with the current project (an inline chain), after the current step.
Pass Notify
This property specifies an access group to be notified if the step passes.
Pass Chain
Specifies a project to launch on the success of the current step. The system displays the chained steps as indented steps in the Jobs reports.
Pass Wait
If this box is checked, the system suspends the current project until the pass chained project completes.
Fail Notify
Specifies an access group to be notified if the step fails.
Fail Chain
Specifies a project to launch on the failure of the current step. The system displays the chained steps as indented steps in the Jobs reports.
Fail Wait
If this box is checked, the system suspends the current project until the fail chained project completes.

Related concepts
Creating a Log Filter
Access Group
Working Directories for Jobs
Timeout
How the System Applies Environments to Steps
Chaining Projects Together
Threading: Running Steps in Parallel
Selectors
Broadcasting a Step to Multiple Servers
Setting Notification Properties of Projects and Steps