Build Forge Quick Tips

Using Build Forge variables to choose a step path at run time

Include a variable for the directory in which you want the Build Forge step to execute in your environment. Use a default value, or make it a “must change” variable. Place the variable in the step path, i.e. $var_name. Using drop-down variables to limit users to a pre-selected choice of paths is another option.

Using Build Forge variables to choose selectors or servers at run time .

Include variables for the Build Forge servers and/or selectors in your environment. Using drop-down variable is generally the best choice, as no one, including yourself is likely to remember the names of available servers and selectors. Use the .bset dot command to assign different servers and/or selectors for different steps.
.bset server $server_variable
.bset selector $selector_variable

Create classes that can’t be created by the GUI

Using Build Forge’s GUI, create a retention class. Then, update the Build Forge data base to any arbitrary count or days for that class.  See a more complete explanation here.

Block execution of selected projects for users that have overall execution permissions without blocking visibility.

To prevent users from executing specific projects, while still maintaining their ability to see the projects and jobs and to evaluate execution results, choose a Build Forge selector, environment, or servers to which they do not have access. Continue to allow access to all other parts of the project. You can see a fuller explanation of how to accomplish this here.  A deeper discussion of using Build Forge groups can be found here.


Access Groups: A Practical Approach

Build Forge Access Groups are designed to allow very granular control over permissions and access . However, the system is not very intuitive, and the best implementation not always obvious.

There are a few things that must be understood before developing any plan to control permissions:

  1. Individual users can never receive permissions directly. Permissions can only be granted to access groups. Individual users inherit their permissions from the group by virtue of their membership in it.
  2. An individual user can be a member of multiple access groups, but their permissions will always reflect, exactly, the combined permissions of those groups to which they belong. As a result, there is no way to set different permissions for the same user based on context. If they have a permission in one context, they have that permission in all contexts.
  3. Every artifact in Build Forge is controlled by one, and only one group. If a user is not a member of the object’s controlling group, then that user cannot even see, let alone act upon, objects controlled by that group.

There are two main approaches to managing permissions within this framework.

  1. Assign an object’s controlling group as one with minimal permissions and then create child groups with increasingly greater permissions. Users are then assigned to these groups.
  2. Assign an object’s controlling group with no permissions, and create separate groups which do contain permissions, but which never inherit from and are never assigned to any group which controls a Build Forge artifact.

The first method is fine, as long as the number of users and projects is limited. It quickly becomes unwieldy, however, as the number of projects increases. The more projects and other artifacts to which a user has access, the greater the number of places that will need to be considered when changes need to be made.

The advantage of the second method is that it completely separates the actions a user can take from the objects upon which those actions can be taken. Users can easily be granted or denied access to projects, servers, environments and other Build Forge artifacts by adding or deleting them from the controlling groups. If permissions for that user need adjusting, all that is needed is to change the permission group to which they belong.

As noted earlier, a user has the combined permissions of all the groups to which he or she belongs. If, for example, s/he is a member of several groups, and has delete access in one of them, s/he will have delete access in all of them. If a user’s permissions are defined in one place, it is less likely that something will be overlooked when changes are made. By the same token, it becomes very simple to control which users are associated with which artifacts. Continue reading

Assign User Permissions by Project

While the short, official answer to how you can assign the same user different permissions on different Build Forge projects is “you can’t”, in truth, there is almost always a way that you can. All it takes is thoughtful use of different access group assignments to different parts of the project.

One example is to allow a user visibility to a large group of projects and job results, while allowing them to actually run only a subset of those projects.

This is useful when you have deployment or build projects in multiple environments. You may want developers to be able to run the projects in unit test environments, but limit this ability to only specially authorized personnel in more controlled environments. At the same time, you might want the developers to see the job output for a variety of reasons.

Consider the following example:

Set  up 3 groups as follows:

Group Name



ViewA View permissions only Mary, James, Henry
ViewB View permissions only Mary
RunPermissions All permissions needed to run projects Mary, James, Henry

Now create two projects, Project_1 and Project_2. For Project_1, assign the project, steps, server, selector and all other objects to the Build Forge access group “ViewA”

In Project_2, you will also assign all Build Forge objects to “ViewA” except for the selector. Assign the selector to the group “ViewB”

The result will be that Mary, James, and Henry will all be able to run and view Project_1. All three can see the project and all of it’s artifacts, and all 3 have permissions to run any project they can see.

Only Mary will be able to run Project_2, however, since she is the only person with access to the selector. James and Henry will still have access to view the projects and any associated job runs, but if they attempt to run it, will fail with the Build Forge error “unable to select a server.”

There are several other ways to achieve this same objective. I will leave it as an exercise for the reader to think of some variations on this theme.

A deeper discussion of Build Forge access groups may be found in the post titled: “Access Groups:  A Practical Approach.”

In the Schema Things

Understanding the Build Forge Schema

One of the bigger mysteries of Rational Build Forge® is the back end database and how it is organized. Behold, an interlinked schema to answer your data questions:

This indexed and cross-referenced version of the schema is a bit much to fit in a post, so I’ve set up a full page version here:

Also available for download is an entity relationship diagram in PDF format. Like the Build Forge Schema itself, it is huge, consisting of 299 letter sized pages. They are arranged in such a way that matching them to create a full diagram is pretty easy, just arrange left to right, top to buttom, but it is obviously going to take some space. The PDF printer assumes you are printing a rectangular shape, which with this hierarchical diagram is not true. As a result, about 1/2 of the pages are blank. Further, many printers allow you to reduce the size, and print 2 or more pdf pages to one letter sized page, so if you feel like working, you can get the Schema down to about 50 pages or less. You can find it here:

Finally, a less well integrated version of the schema can be generated from Build Forge itself, using the bfschema -g command. This version, linked below, has some additional information about columns, but does not feature the easy navigation of the version linked above. You can take a look at the generated version here here: