CloudBees Flow Glossary

This glossary is a reference topic containing short descriptions for CloudBees Flow objects, terms, and concepts.

Term Description

access control

An access control list (ACL) determines if a particular user can perform a particular operation on a specified object. The list contains access control entries (ACEs), each of which specifies a user or group and indicates whether certain operations are allowed or denied for that user or group. Using access control provides security for CloudBees Flow system use.

ACE (Access Control Entry)

Determines if a particular user can perform a particular operation on a specified object. The list contains ACEs.

ACL (Access Control List)

A list of ACEs.

actual parameter

An actual parameter is an object that provides the value for a parameter, which is passed to a procedure when it is invoked. Actual parameters can be provided for jobs and nested subprocedures within a job. Actual parameters are different from "formal parameters": formal parameters define parameters a procedure is expecting, and actual parameters provide values to use at run-time.

admin

"admin" is a special built-in user that has universal CloudBees Flow access. If you log in as admin, you can perform any operation in the system, regardless of access control limitations.

agent

An agent is a CloudBees Flow component that runs on each machine where job steps can execute. The agent works under the CloudBees Flow server’s control to execute job steps, monitor their progress, and record information about their completion. A single agent process can manage multiple job steps executing concurrently on a single machine.

See the Web Interface Help > Resources topic for more information.

artifact

An artifact is a top-level object containing artifact versions, a name template for published artifact versions, artifact specific properties, and access control entries to specify privileges.

artifact key

An artifact key is an identifier for an artifact and the "key" component of the artifact name.

artifact repository

See the Artifact Management > Artifact objects > Repository topic for more information.

artifact version

An artifact version is a collection of 0 to N files that were published to an artifact repository.

backing store

The backing store is the directory on the repository server where artifact versions are stored. By default, the backing store is the <datadir>/repository-data directory in the repository installation—this default setting can be changed.

child step

A nested step that appears as a substep in the Job Details page when a step is either of the following:

A subprocedure step
A step that dynamically creates subordinate (“child”) steps using the createJobStep API command

For details about the createJobStep API command, see createJobStep .

compression

Compression reduces transfer time when publishing an artifact. However, compression also adds overhead when computing the compressed data. If files included in the artifact version are primarily text files or are another highly compressible file format, the benefit of reduced transfer time outweighs the cost of computing compressed data.

continuous integration

Using continuous integration means a build is launched every time code changes are checked into a Source Control Management (SCM) system.

The CloudBees Flow ElectricSentry component is the engine for continuous integration, while the CI Continuous Integration Dashboard is the front-end user interface for ElectricSentry.

credential

A credential is an object that stores a user name and password for later use. You can use credentials for user impersonation and saving passwords for use inside steps. Two credential types are available: stored or dynamic .

custom property

Custom properties are identical to intrinsic properties and when placed on the same object, are referenced in the same manner and behave in every way like an intrinsic object-level property with one exception: they are not created automatically when the object is created. Instead, custom properties can be added to objects already in the database before a job is started, or created dynamically by procedure steps during step execution.

Custom properties in a property sheet can be one of two types: string property or a property sheet property. String properties hold simple text values. Property sheet properties hold nested properties. Nested properties are accessed by way of the property sheet property of their containing sheet.

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">\https://www.google.com</a>.
</span>
</p>▼

renders as follows:

_Note:_ For more information about the *abc* object, see \https://www.google.com.▼

diagnostic extract

A diagnostic extract is a log file portion from a job step, typically describing an error or interesting condition, extracted by a postprocessor and saved for reporting. The postprocessor usually places this information in an XML file in the top-level job workspace directory, and then sets a property that contains the file name. The CloudBees Flow postp postprocessor uses file names like diag-2770.xml, where "2770" is the unique identifier for the step. Other postprocessors you may use can have a different file name configuration.

dynamic credential

Dynamic credentials are captured when a job is created. Dynamic credentials are stored on the server temporarily until the job completes and then discarded.

ec-perl

ec-perl is a small wrapper program installed as part of CloudBees Flow. When the ec-perl wrapper runs, it sets up the environment, finds, and calls CloudBees Flow’s copy of Perl, passing all of its parameters to Perl.

ectool

ectool is the CloudBees Flow command-line application that provides control over the CloudBees Flow system if you prefer using a command-line interface rather than the CloudBees Flow web interface. Most functions that can be invoked through the CloudBees Flow web interface can be invoked using ectool.

CloudBees Accelerator

ElectricAccelerator is a software build accelerator that dramatically reduces software build times by distributing the build over a large cluster of inexpensive servers. Using a patented dependency management system, ElectricAccelerator identifies and fixes problems in real time that would break traditional parallel builds. ElectricAccelerator plugs into existing Make-based infrastructures seamlessly and includes web-based management and reporting tools.

ElectricSentry

ElectricSentry is the CloudBees Flow engine for continuous integration, integrating with numerous Source Control Management (SCM) systems. ElectricSentry is installed automatically with CloudBees Flow and is contained in a plugin named ECSCM and in the CloudBees project.

The CI Continuous Integration Dashboard is the front-end user interface for ElectricSentry.

email configuration

Before you can send an email notifier, you must set up and email configuration, which establishes communication between the CloudBees Flow server and your mail server.

email notifier

After setting up the CloudBees Flow server and your mail server to communicate, you can send email notifications (notifiers). You can attach email notifiers to procedures, procedure steps, and state definitions.

Event log

See log.

Everyone

A special intrinsic access control group that includes all users.

filter

Two filter categories:

Intrinsic filters—these filters provide a convenient way to access certain well-defined fields for jobs.
Custom filters—these filters allow you to access a much broader range of values, including custom properties. Any values accessible through an intrinsic filter can be checked using a custom filter also (though not as conveniently).

formal parameter

A formal parameter is an object that defines a parameter expected by a procedure, including its name, a default value, and an indication of whether the parameter is required. Formal parameters are different from "actual parameters": formal parameters define the kinds of parameters a procedure is expecting, and actual parameters provide values to use at run-time.

gateway

To communicate with a resource, workspace, or artifact repository server in another zone, a "gateway" must be created.

A gateway object contains two resource (agent) machines. For example, GatewayResource1 and GatewayResource2 are each configured to communicate with the other. One gateway resource resides in the source zone and the other in the target zone.

A gateway is bidirectional and informs the CloudBees Flow server that each gateway machine is configured to communicate with its other gateway machine (in another zone).

group

A group defines a collection of users for access control purposes. A group can be defined externally in an LDAP or Active Directory repository, or locally in the CloudBees Flow server.

See the CloudBees Flow Help > Web Interface Help > Users and Groups > Groups topic for more information.

impersonation

Impersonation is a mechanism that allows a job step to execute under a particular login account (the CloudBees Flow agent "impersonates" a particular user during the execution of that step). Impersonation is implemented using credentials .

inheritance

A feature of the CloudBees Flow access control mechanism where access to a particular object is determined by the access control list for that object, and also by the access control lists of the object’s parent and other ancestors. Each object can be configured to enable or disable inheritance from its ancestors.

intrinsic property

Intrinsic properties represent attributes that describe the object to which they are attached. CloudBees Flow automatically provides intrinsic properties for each similar type object within CloudBees Flow. For example: Every project has a description property that can be referenced with a non-local property path such as /projects/Examples/description.

job

A job is the output associated with invoking a CloudBees Flow procedure. A new job is created each time you run (execute) a procedure.

job configuration

A job configuration is an object containing all parameter and credential information needed to run a procedure. A Job Configuration section is provided as part of the CloudBees Flow Home page to make it easy for you to invoke your favorite configurations with a single mouse click. You can create job configurations in three ways:

From the Job Details page for a previously invoked job, click the Save Configuration link at the top of the page. Your saved job configuration will be displayed on your Home page.
Create a job configuration from "scratch" by clicking the Create link in the Job Configurations section (on the Home page). In the Create Configuration pop-up menu, select the project and procedure you want to use for creating this configuration.
On the page for editing a schedule, click the Save Configuration link at the top of the page. Your saved configuration will be displayed on your Home page.

job name template

This is the template used to determine the default name for jobs launched from the procedure. You can create a Job Name Template when you create a procedure. For example: In the Job Name Template field, you might enter:

$[projectName]_$[/increment /myproject/jobCounter]_$[timestamp] which produces a name like: projectFoo_1234_20140102130321 You can enter any combination of elements to create procedure names more meaningful to you. For example, you could choose to include the build number and procedure name.

jobs quick view

A Jobs Quick View section is one of the facilities provided on the CloudBees Flow Home page. This section allows you to define a category of jobs interesting to you (such as all running jobs or all jobs for a particular product version). Your Home page can display the last several jobs in each category you define.

job step

After a procedure is executed, the resulting job contains one job step for each step in the original procedure. The job step records information about the procedure step execution, such as the command executed, the resource where it executed, execution time, and error information.

job workspace

A directory (containing all files and subdirectories) allocated by CloudBees Flow for a particular job. Each job workspace is allocated as the child of a workspace root directory. See workspace .

local group

A group defined inside CloudBees Flow, as opposed to a group defined in an external repository. A local group can refer to both local and remote users, whereas a group in an external repository refers to users in that repository only. See group .

local user

A user defined inside CloudBees Flow, as opposed to a user defined in an external repository. If a user defined in an external repository has the same name as a local user, the external user is not accessible. Local users are not visible outside CloudBees Flow. We recommend using external accounts whenever available, but you may need to create local users if you do not have a shared directory service or if you need special accounts to use for CloudBees Flow only. See user .

log

CloudBees Flow provides a log for events generated anywhere in the system, including jobs and workflows.

To see only events for a single workflow, select the Workflows tab, then a workflow Name to go to the Workflow Details page and click the View Log link at the top of the page.
To see only events for a single job, select the Jobs tab, then the Job name to go to the Job Details page and click the View Log link at the top of the page.
To see only events for a specific object, select the Search tab to go to the Define Search page. For example: You can select the Object Type, "Log Entry", then click the Add Intrinsic Filter link. Select the down-arrow where you see "Container" auto-populated and select "Container Type. Use the "equals" operator, then select the next down-arrow to choose an object. Click OK to start the search. See the Event Log topic for more information.

From the Administration tab, the default view for the Event Log page is the warning (WARN) level. For workflow and job event logs, the default view from their respective pages is the information (INFO) level.

matcher

A matcher controls the postp postprocessor. Use matchers to extend postp with additional patterns if you find useful patterns in your log files undetected by postp. A matcher contains a pattern that matches lines in a step’s log and actions to carry out if/when the pattern matches.

Microservice

A variant of the service-oriented architecture (SOA) architectural style, which structures an application as a collection of loosely-coupled services. In a microservices architecture, services should be fine-grained, and the protocols should be lightweight.

Decomposing an application into smaller services improves modularity and makes the application easier to understand, develop, and test. It also parallelizes development by letting small autonomous teams develop, deploy, and scale their respective services independently. It also lets the architecture of an individual service emerge through continuous refactoring.

Microservices-based architectures enable continuous delivery and deployment.

misfire policy

A misfire policy allows you to manage how a schedule resumes in cases where the normal scheduled time is interrupted. Available options are skip (all misfires are ignored and the job runs at the next scheduled time) and run once (after one or more misfires, the job runs at the soonest time that occurs within an active region). See schedule .

parameter

A property value passed into a procedure when it is invoked (at run time), and used by the procedure to change its behavior. Two types of parameters: actual and formal .

plugin

A plugin is a collection of one or more features, or a third-party integration or tool that can be added to CloudBees Flow. Plugins are delivered as a JAR file containing the functional implementation. When a plugin is installed, the CloudBees Flow server extracts the JAR contents to disk into a configurable plugins directory. A plugin has an associated project that can contain procedures and properties required by the implementation. A plugin can provide one or more new pages for the web interface and may also provide a configuration page so you can provide additional information that may be necessary to implement the plugin.

polling frequency

The polling frequency is how often the ElectricSentry continuous integration engine is set to look for new code check-ins. The default is set to every 5 minutes, but this number can be adjusted.

pool

Also known as "resource pool". A pool is a collection of resources. If a step specifies a pool name as its resource, CloudBees Flow can choose any available resource within that pool.

postp

postp is a postprocessor included with CloudBees Flow. postp uses regular expression patterns to detect interesting lines in a step log. postp is already configured with patterns to handle many common cases such as error messages and warnings from gcc , gmake , cl , junit , and cppunit , or any error message containing the string "error." postp also supports several useful command-line options, and it can be extended using "matchers" to handle environment-specific errors. See matcher .

postprocessor

A postprocessor is a command associated with a particular procedure step. After a step executes, the postprocessor runs to analyze its results. Typically, a postprocessor scans the step log file to check for errors and warnings. Also, it records useful metrics such as the number of errors in properties on the job step, and extracts step log portions that provide useful information for reporting. CloudBees Flow includes a standard postprocessor called postp for your use and you can "extend" postp. See matcher .

preflight build

A preflight build provides a way to build and test a developer’s changes before those changes are committed. A "post-commit" source tree is simulated by creating a clean source snapshot and overlaying the developer’s changes on top of it. These sources are then passed through the production build procedure to validate the changes work successfully. Developers are allowed to commit their changes only if the preflight build is successful. Because developer changes are built and tested in isolation, many common reasons for broken production builds are eliminated.

privileges

CloudBees Flow supports four privilege types (for access control and security) for each object:

Read—Allows object contents to be viewed.
Modify—Allows object contents (but not its permissions) to be changed.
Execute—If an object is a procedure or it contains procedures (for example, a project ), this privilege allows object procedures to be invoked as part of a job. For resource objects, this privilege determines who can use this resource in job steps.
Change Permissions—Allows object permissions to be modified.

procedure

A procedure defines a process to automate one or more steps. A procedure is the CloudBees Flow unit you execute ( run ) to carry out a process. A step in one procedure can call another procedure (in the same or different project), and this procedure then becomes known as a "subprocedure" (also known as a "nested" procedure). The step can pass arguments to the subprocedure.

project

A project is a top-level container for related procedures, workflows, schedules, jobs, and properties, which is used to isolate different user groups or functions, and also encapsulate shared facilities.

Projects have two purposes:

Projects let you create separate work areas for different purposes or groups of people so they do not interfere with each other.

For example, different projects can reuse the same names internally without conflict, and each project has its own access control that determines who can use and modify the project.

In a small organization, you might choose to keep all work in a single project, but in a large organization, you might want to use projects to organize information and simplify management.
Projects simplify sharing.

You can create library projects containing shared procedures and invoke these procedures from other projects. After creating a library project, you can copy it easily to other CloudBees Flow servers to create uniform processes across your organization.

project principal

Project principal is a special user ID associated with each project. If a project name is "xyz," the project principal for that project is "project: xyz" (with an embedded space). This principal is used when procedures within the project are run, so you can create access control entries for this principal to control runtime behavior.

property

A property is a ` name-value` pair associated with CloudBees Flow objects to provide additional information beyond what is already built into the system. Built-in data is accessible through the property mechanism also. Two types of properties: intrinsic and custom . CloudBees Flow provides Intrinsic properties and allows you to create Custom properties.

Intrinsic properties are case-sensitive. Custom properties, like all other object names in the CloudBees Flow system, are case-preserving, but not case-sensitive.

Intrinsic properties These properties represent attributes that describe the object to which they are attached, and are automatically added by CloudBees Flow for each similar type object. For example, every project has a Description property that can be referenced with a non-local property path such as /projects/Examples/description.
Custom properties Custom properties are identical to intrinsic properties and when placed on the same object, are referenced in the same manner, and behave in every way like an intrinsic object-level property with one exception: they are not created automatically when the object is created. Instead, custom properties can be added to objects already in the database before a job is started, or created dynamically by procedure steps during step execution.

property sheet

A property sheet is a collection of properties that can be nested to any depth. The property value can be a string or a nested property sheet. Most objects have an associated "property sheet" that contains custom properties created by user scripts.

proxy agent

A proxy agent is an agent on a supported Linux or Windows platform, used to proxy commands to an otherwise unsupported agent platform. Proxy agents have limitations, such as the inability to work with plugins or communicate with ectool commands.

publisher

A publisher is the job that completes the operation for an artifact version.

quiet time

An inactivity period before starting a build within a continuous integration system. This time period allows developers to make multiple, coordinated check-ins to ensure a build does not start with some of the changes only—assuming all changes are checked-in within the specified inactivity time period. This time period also gives developers an opportunity to "back-out" a change if they realize it is not correct. Using ElectricSentry, the inactivity time period can be configured globally for all projects or individually for a single project.

resource

A resource specifies an agent machine where job steps can be executed. Resources can be grouped into a "pool", also know as a "resource pool." CloudBees Flow supports two types of resources:

Standard— specifies a machine running the CloudBees Flow agent on one of the supported agent platforms
Proxy— requires SSH keys for authentication. You can create proxy resources (agents and targets) for CloudBees Flow to use on numerous other remote platforms/hosts that exist in your environment.

Schedule

An object used to execute procedures automatically in response to system events. For example, a schedule can specify executing a procedure at specific times on specific days. Three types of schedules are available: Standard, Continuous Integration, and Custom (custom schedules are typically continuous integration schedules that do not use the ECSCM plugin).

Sentry schedule

A continuous integration schedule created using the ElectricSentry engine for continuous integration or the CI Continuous Integration Dashboard, which is an easy- to-use front-end user interface for the ElectricSentry engine.

Service

See Microservice .

shortcut

One type of shortcut is part of the CloudBees Flow Home page facility and records the location of a page you visit frequently (either inside or outside of CloudBees Flow), so you can return to that page with a single click from the Home page. Another type of shortcut is a context-relative shortcut to property paths. This shortcut can be used to reference a property without knowing the exact name of the object that contains the property. You might think of a shortcut as another part of the property hierarchy. These shortcuts resolve to the correct property path even though its path elements may have changed because a project or procedure was renamed. Shortcuts are particularly useful if you do not know your exact location in the property hierarchical tree.

state

Workflows always have a single active state . Each state in a workflow, when it becomes active, can perform an action. A state can run a procedure to create a subjob or run a workflow definition to create a subworkflow—in the same way that procedures can call other procedures. One or more states can be designated as "starting" states to provide multiple entry points into the workflow. See state definition .

state definition

Workflow objects are split into two types: Definition objects and Instance objects. Definition objects provide the template for a running workflow instance. You create a new workflow by defining a Workflow Definition along with its State Definition and Transition Definition objects. When you run the workflow definition, the system creates a new Workflow object with an equivalent set of State and Transition objects that represent the run-time instances of the workflow definition.

We omit the "Instance" qualifier for brevity in the API and the UI.

Each workflow can contain one or more state objects. Defining states for a workflow is analogous to defining steps for a procedure.

stored credential

Stored credentials are given a name and stored in encrypted form in the database. Each project contains a list of stored credentials it owns. These credentials are managed from the Project Details page.

subprocedure

Creating subprocedures is a way of "nesting" procedures. A step (from any procedure) can call a procedure from another project or the same project. The procedure called by the step then becomes a subprocedure.

system object

This is a special object whose access control lists are used to control access to some CloudBees Flow internals. System objects are: admin, artifactVersions, directory, emailConfigs, forceAbort, licensing, , plugins, priority, projects, repositories, resources, server, session, and workspaces.

tag

A way to categorize a project to identify its relationship to one or more other projects or groups. You can edit a project to add a tag. Enter a tag if you want to categorize or "mark" a project to identify its relationship to one or more other projects or groups. For example, you might want to tag a group of projects as "production" or "workflow", or you might want to use your name so you can quickly sort the project list to see only those projects that are useful to you.

transition definition

We omit the "Instance" qualifier for brevity in the API and the UI.

Each state can contain one or more transition objects. The transition definition object requires a name for the transition. This transition name will appear on the Workflow Definition Details page for quick reference and also on the State Definition Details page when you select the Transition Definitions tab. You can define one or more transitions for each state, depending on which transition options you want to apply to a particular state.

user

A user defines an account used to log into the system and control access to CloudBees Flow objects. A user can be defined externally in an LDAP or Active Directory repository, or locally in CloudBees Flow. See local user .

workflow

You can use a workflow to design and manage processes at a higher level than individual jobs. For example, workflows allow you to combine procedures into processes to create build-test-deploy lifecycles. A workflow contains and transitions you define to provide complete control over your workflow process. The CloudBees Flow Workflow feature allows you to define an unlimited range of large or small lifecycle combinations to meet your needs. See workflow definition .

workflow definition

We omit the "Instance" qualifier for brevity in the API and the UI.

workflow name template

This is the template used to determine the default name of jobs launched from the workflow definition. For example:

$[projectName]_$[/increment /myproject/workflowCounter]_$[timestamp]

(substitute your values for the names above)

Produces a workflow name such as: projectName_123_20140102130321

Workspace

A subtree of files and directories where job file data is stored. The term "workspace" typically refers to the top-level directory in this subtree.

workspace root

A directory in which CloudBees Flow allocates job workspace directories. Each workspace root has a logical name used to refer to it in steps and procedures.

zone

A zone is a way to partition a collection of agents to secure them from use by other groups—similar to creating multiple top-level networks. For example, you might choose to create a developers zone, a production zone, and a test zone—agents in one zone cannot directly communicate with agents in another zone.

A default zone is created during CloudBees Flow installation. The server implicitly belongs to the default zone, which means all agents in this zone can communicate with the server directly (without the use of a gateway).