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.
- 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.