Build Forge uses a simple set of
objects to construct descriptions of process automation.
This section gives you an overview of key concepts and objects
and how they are related. Links to more detailed explanations are
included for convenience.
Users and roles
To access Build Forge, users
need to have a user object set up for them. In production systems,
this is done by configuring Build Forge to access an identity management
system, LDAP.
Build Forge uses an authorization system to control
user access to all objects. Access group objects
contain lists of permissions. A user belongs
to one or more access groups.
You can create your own access
groups or modify the ones provided. The access groups defined in the
system are:
- Build Engineer - defines processes (creates projects and steps)
- System Manager - administers servers and other system-wide features
- Security - administers users, access, and security
- Developer - helps develop processes, runs jobs, views results
- Operator - copies projects, runs jobs, views results
- Guest - copies projects, runs jobs, views results
Servers
A server object
defines a place where projects and steps can run. Projects and steps
can use the same server or select one independently.
Server
objects represent hosts where work is performed. The host must be
running a Build Forge agent to receive the work from the system and
return results.
Other objects are related to servers and need
to be set up before defining projects and steps:
- Server Authentications: a server
authentication stores login information for the server
to use to access the host specified by the server. A server authentication
must be created before creating the server that uses it. In the server
definition, choose the server authentication from the list of all
server authentications defined in the system.
- Collectors: a collector object
gathers specified properties of a server. The data is stored in a manifest. Servers have a default set of
properties assigned. These built-in properties include information
about the host architecture, network connections, and resources (CPU,
memory, load). You can add other properties by defining collector
objects. A collector must be created before adding it to the server.
In the server definition, choose the collector from the list of all
collectors defined in the system.
- Selectors: a selector object
defines how a server is selected for use by a project or step. A selector
must be created before adding it to the project that uses it. In the
project definition, choose the selector from the list of all selectors
defined in the system.
- Environments: an environment object is a set
of variables that can be used by a step. During a job, the variables
are set on the server host before the step is run. Environments can
be associated with server objects, project objects, and step objects.
When the same variable is set to different values in different environments,
an inheritance scheme determines which value is
used. An environment must be created before adding it to a server,
project, or step. In those object definitions, choose the environment
from the list of all environments defined in the system.
Environments
An environment is a
set of variables. Environments can be specified for server, project,
and step objects. When a step runs, environments set at each of those
objects are combined to provide variables for the step to use. See About environments.
Variables
can be changed as a step runs. See Changing variable values during step execution.) The scope of the change can
be local to the step, local to the project, or permanent (the variable
is changed in the stored environment.
Predefined system variables are available as well as variables
you define.
Projects
A project defines
work to be done in a process. When a project is started, it runs as
a job.
The work to be done is contained in the list of steps.
Other
objects are related to projects:
- Selectors: a selector determines where
the project will be started. If a selector is not specified for the
project, then it cannot run independently and is called a library. The selector must already be defined
to assign it to a job.
- Environments: an environment object is a set
of variables that can be used by a step. During a job, the variables
are set on the server host before the step is run. Environments can
be associated with server objects, project objects, and step objects.
An inheritance scheme determines which values are
used if the same variable is set to different values. An environment
must be created before creating the server, project, or step that
uses it. In those object definitions, choose the environment from
the list of all environments defined in the system.
- Notification templates: a notification
template defines how to send out notifications about job
activity (job start, job pass, job fail, others). A notification object
defines who to notify through access groups. You specify the location
of your SMTP server in a system setting.
- Classes: a class object is used to
group projects for maintenance purposes. Typically classes are used
to purge or archive completed jobs periodically. All jobs that have
run using the project are affected by the class.
- Adaptors: an adaptor defines an integration
with an external system, typically a source code management system.
Several sample templates are provided
as a starting point. You need to configure them further to manage
the connection and perform specified actions in the system.
- Adaptor links: an adaptor
link defines the relationship between an adaptor and the
project that uses it.
Steps
A step defines the smallest
unit of work to be done. (See About steps.) Its key component is its Command
property, which includes a command to be run on the selected server.
The
Command property can also be used to run dot commands.
Dot commands are commands that run on the process engine and provide
additional functionality.
Other objects are related to projects:
- Selectors: a step can have its own selector.
If not specified it uses the selector of its project.
- Environments: a step can have its own environment.
The environments provided by the server, the project, and the step
are combined. By default they are applied in that order, so that any
variables defined by the step's environment take precedence over
definitions of the same variable. Precedence can be controlled in
system settings.
- Log Filters: a step can be assigned a log filter in its Result
property. A log filter object is used
to specify conditions that indicate if the step passes or fails. When
running a Perl engine, you use regular expressions to scan the log
for a particular pattern. When running a Java engine, you also use
regular expressions to scan the log for a particular pattern. Normally
the exit status of the command is used, but log filters provide an
alternate means. A log filter must be created before specifying it
in a step. In the Result property for the step, you choose the log
filter from the list of all log filters defined in the system.
- Notification templates: a notification
template defines how to send out notifications about step
activity (step start, step pass, step fail, others). A notification
object defines who to notify through access groups. You specify the
location of your SMTP server in a system setting.
- Build Catalyst: a step can run rafmake, the key utility in Build
Catalyst. Build Catalyst provides the means to accelerate make-based
builds. Build Catalyst must be installed on the same host where the
make builds are run, in addition to a Build Forge agent.
Jobs
A job is
a running project. When the job is started,
the process engine queues it and then runs it. You can check its status
in the Jobs panel. When it completes, the following information is
available:
- Results: you can review the results of
all steps by opening the job. You can also open a running job to monitor
its progress.
- Step log: the step log records extensive information about how
a step was run, including information about the manifest and environment
settings as well as execution results. Click the step results link
in the Results page to view the log.
- Bill of Materials: the Bill of
Materials (BOM) contains information about job steps and step
manifests. You can use the .bom dot command to format additional
information for the BOM and write data to it. You can use the .scan dot
command to add baselines and checkpoints to the BOM.
You can cancel and restart jobs. You can add projects to the Schedule to
have them run at scheduled times.