About steps

A step is a component of a project. When the project is run as a job, each step is issued in order. A step contains one or more commands and has step properties that affect its behavior.

Note: You need to purge the old jobs regularly. This is because a large number of log lines in a single step affect the performance of engine, agent and database due to the I/O process cost. Besides, log lines might not display normally when the number of log lines in a single step exceeds 5000. To ensure that the log lines display normally, you can also reduce the step output or redirect the step output to a separate file.

About the Steps panel

Details tab

Step properties specify how to run a step, handle its output, and what to do when the step completes. A step can also run another project or library.

To view step properties, select a step within a project. The Details tab is shown by default. It displays the step properties.

If a step property is not set explicitly, its value is inherited from the project. Step properties set for a step override inherited values.

Step properties include:
Name
The name of the step. It is used as a label for the step in the system and the log.
Active
Specifies whether the step is run. By default a step is Enabled. Select Disabled to prevent the step from running. A disabled step is not available to be run in a job.
Directory
Sets the location where step commands run. The system automatically creates a unique directory for every job. The Directory field provides a convenient way to run commands in directories your project has constructed during a job. (Build Forge does not construct directories mentioned in the Directory field.)
Path
Specifies whether Directory is an absolute or a relative path.
  • Relative: Step commands are run in a path found by adding together the server, project, job, and step directories.
  • Absolute: Step commands are run in a path found by adding together the server and step directories. This option allows you to access directories that are not in the project directory structure. Example: It can be used to launch applications permanently installed on the server.
Step Type
Determines how the step is run. This property affects the contents of Command and the project specified in Inline, if any.
  • Regular: The step is run once.
  • Conditional: The step is run once if the expression in the Condition property evaluates to true. Selecting conditional causes the Condition, Else Inline, and Else Command properties to be shown. If the Condition property evaluates to false, then the Command and Inline are not run. Instead, the Else Command and Else Inline are run if they are specified.
  • While Loop: The step can be run multiple times. It is run until the expression in the Condition property is false or until the maximum number of iterations is reached. Selecting While Loop causes the Condition and Max Iterations properties to be shown.

    The selector is evaluated each iteration of the While Loop to determine the server to use for the iteration.

Inline
Specifies a project or library to run inline with the current project. The steps from the project or library are run using the environment and most of the properties of the current project. However, the system uses the inline project's selector as the default selector for the steps of the inline. The behavior is as if the steps in the specified project are copied after the current step.
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.

Step Provider
The implementation of step command execution. The default step provider is MJC Step Provider. It provides as-expected legacy behavior of executing the command text on the endpoint agent machine
Max Iterations
Shown only if Step Type is While Loop. Specifies the maximum number of iterations that the step can be run in a loop. The system-imposed default is 100. The step is shown as completed successfully (passed) in the step log. Use Fail step if max reached, to make the step fail when Max Iterations is reached.

When jobs are executing, the read-only variable BF_ITERATION contains the number of iterations entered successfully. If a job is stopped and then restarted, it is restarted at the iteration in BF_ITERATION.

Fail step if max reached
If Yes, a While Loop step fails if Max Iterations is reached. If No, the step passes.
Else Inline
Shown only if Step Type is conditional. Specifies a project to be run inline if the specified condition is false. Default is No.
Command

One or more commands. The commands can be operating system commands, dot commands, or a combination of both. See How steps run.

Condition
Shown only if you have selected a step type of Conditional or While Loop.
  • Conditional: the command is run if the condition evaluates to true.
  • While Loop: the command can be run multiple times as long as the condition evaluates to true. You can set the limit using Max Iterations.

A condition can be a function or a command to be run on the selected server resource.

  • A function, if used, must be used at the beginning of the Condition field. It is evaluated by the Build Forge engine. It is not sent to the server resource. For a list of the functions and instructions about how to use them, see Condition functions.
  • A command is run on the selected server. Any command used here must be valid in the agent's shell environment. The return code from execution determines whether the condition passes or fails.

Build Forge variables for the project are available to use in a condition expression. See Interpretation of variables in steps for more information about how variables can be expressed and how they are evaluated.

Else command
Shown only if you have selected a step type of Conditional. Specifies a command to run if condition evaluates to false.
Environment

Specifies an environment to apply before executing the commands. Values in this environment override any values inherited from the server environment, project environment, and step variables.

Selector
Specifies a selector to use to choose a server for this step. If left as Default, the step runs on the server determined by the project's selector.
Broadcast
If checked, runs the step on every server matching the current selector (the step selector if specified, otherwise the project selector). At run time, the system replaces a broadcast step with a series of steps, one for each server, and runs them serially or in parallel, depending on the broadcast step's Thread property.

Broadcast step behavior on restarts: When a broadcast step is restarted, it does not broadcast. That setting applies only to new starts of the step. Upon restart the engine picks a single server at random for the step.

Timeout in minutes
Specifies how many minutes the system waits for the current command to produce output (default is 5 minutes). A value of 0 means that the step does not timeout if the step properly connects to the agent. If the timeout value is reached, the system fails the step. The project also fails 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. You may also choose a Log Filter that examines the command output. To select a Log Filter, you must first create it.
On Fail
Specifies whether to halt or continue the job if the step fails. By default, the system halts the job.
Thread
If Yes, runs this step in parallel with other steps. 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.
Pass Notify
Specifies the access group to be notified if the step passes.
Pass Chain
Specifies a project to launch if the current step passes. (A step with a "Warning" status is counted as passing and will launch a pass chain).
Pass Wait
If checked, the system suspends the current project until the pass chained project completes. If this step (or its project) is canceled, the chained project is also canceled. If it is not checked, the chained project is started asynchronously and the current project continues to the next step.
Fail Notify
Specifies the access group to be notified if the step fails.
Fail Chain
Specifies a project to launch on the failure of the current step. (A step set to continue on failure is counted as failing, and will launch any fail chains assigned to the step.)
Fail Wait
If checked, the system suspends the current project until the fail chain project completes. If this step (or its project) is canceled, the chained project is also canceled.

Notes tab

The Notes tab contains a time-stamped list of notes made about the step. You create notes manually. It does not automatically record edits to the step itself. The tab shows the current number of notes, for example Notes (2).

To add a note:
  1. Click the Notes tab.
  2. Write the new note in the text field.
  3. Click Submit.
To edit a note:
  1. Click the Notes tab.
  2. Click the Edit icon Edit icon next to the note you want to edit. Make your edits.
  3. Click Submit.
To delete a note:
  1. Click the Notes tab.
  2. Click the Trash icon Trash icon. A prompt asks if you are sure that you want to delete the note.
  3. Click OK.

Feedback