Upgrading to DBB 2.0
DBB 2.0 introduces some significant changes from previous DBB releases. These changes may require modifications to existing CI/CD pipeline scripts and existing DBB Groovy build scripts.
Public sample repository updates
IBM® Dependency Based Build provides two public samples repositories:
- DBB Community Repository provides samples on how to use DBB APIs when writing simple build scripts or pipeline stages such as deploying build outputs to artifact repositories.
- DBB zAppBuild Repository is a robust generic build solution for building z/OS® applications by using Apache Groovy build scripts and IBM Dependency Based Build (DBB) APIs.
These repositories have been updated to work with DBB v2.0. The following table shows which minimum version of the sample repository supports DBB v2.0.
| Sample Repository | Minimum Version |
|---|---|
| DBB Community Repository | DBB Community v2.0.0 |
| DBB zAppBuild Repository | zAppBuild v3.0.0 |
Additionally read the white paper DBB zAppBuild Introduction and Custom Version Maintenance Strategy for tips and strategies on how to customize zAppBuild to meet your build requirements and yet still be able to pull in new features and maintenance from later versions of the public GitHub zAppBuild repository.
DBB changes that require Groovy build script or CI/CD pipeline modification
Removal of the DBB Liberty Web Application
DBB v2.0 greatly simplifies the installation, customization, and usage of DBB by eliminating the Liberty web application component. So now DBB consists of a single component (previously referred to as the DBB Toolkit) that is installed on z/OS UNIX with SMPE. In earlier versions of DBB, the web application was required to be installed on a Linux® platform and provided both REST APIs and a Web UI to access DBB build metadata produced by the build process and stored in remote Db2® databases.
DBB v2.0 now uses direct Db2 connections from the DBB toolkit that is installed on z/OS UNIX. In addition to simplifying the installation and configuration as mentioned before, by eliminating the extra calls to the Liberty web application to access DBB build metadata, it increases the performance. Also, with the new toolkit metadata APIs, you now have total control over how the Db2 JDBC connections between the DBB toolkit and the Db2 server are configured. So, you can now use all the connection security mechanisms that are provided by IBM Db2 JDBC drivers.
Configuring additional environment variables to support direct Db2 connections
In addition to the existing required DBB environment variables DBB_HOME and DBB_CONF, the Db2 direct connections require modifications to at least the CLASSPATH environment variable as well as the STEPLIB and LIBPATH environment variables depending on the type of Db2 connection that is used. See DBB environment variables for more information on how to configure your z/OS UNIX environment
variables to use the direct Db2 connections.
DBB API package removal and replacement
With the removal of the Liberty web application, the DBB toolkit API package com.ibm.dbb.repository has been removed. This package contained the RepositoryClient and supporting classes that used to connect to the
Liberty web application and create, retrieve, update, and delete DBB build metadata artifacts like collections and build results.
This package has been replaced with the com.ibm.dbb.metadata package, which contains the MetadataStore and supporting classes that create and maintain direct Db2 connections to perform the same build metadata CRUD
operations mentioned above but directly against the Db2 server. For more information on how to use the new Metadata Store APIs see Metadata store.
DBB metadata command line interface (CLI)
As mentioned earlier, in addition to the REST API provided by the Liberty web application (now replaced with the DBB Toolkit metadata store APIs), the web application also came with a Web UI that was used to provide simple, easy-to-use access to the DBB build metadata without having to write and run custom DBB Groovy utility scripts. This capability has been replaced with a DBB CLI that runs on z/OS UNIX. The DBB CLI can be used interactively by logging in to z/OS UNIX or through CI/CD pipeline scripts using SSH to run CLI commands on z/OS UNIX. For a guide on how to use the DBB CLI, see Metadata store command-line interface.
Removal of deprecated DBB APIs
With the introduction of the new SearchPathDependencyResolver and SearchPathImpactFinder classes in DBB v1.1.2, a notice was added in the DBB v1.1.2 New and Noteworthy that the original DependencyResolver and ImpactResolver and their supporting classes were deprecated and would be removed in a later release. These classes have been removed in DBB v2.0. So, you must now use the
SearchPathDependencyResolver and SearchPathImpactFinder APIs if you have not already done so. For more information about these new APIs, see Resolving logical build dependencies to local physical files and Identifying programs impacted by changed copybooks, include files, and statically linked programs.
Build Report HTML file generation
DBB provides APIs to create and generate a build report that contains summary information of the build commands that are run during the build. The build report is saved as a JSON file on the local file system at the end of the build. It can also be generated as an HTML file that you can view in a web browser from a CI/CD server dashboard.
As it was originally designed, the generated HTML file used the DBB HTMLTransformer class that created a dynamic HTML file that read in the build report JSON file and created a summary table by using JavaScript. However, since
the release of DBB v1.0 in March 2018, some of the dynamic mechanisms used in the HTML file are now considered potential security risks and most web browsers and CI/CD servers disable the capabilities by default.
DBB v2.0 now generates a static HTML file. The HTMLTransformer class has been removed and is replaced by a simple new method located in the BuildReport class
public void generateHTML(File htmlFile) throws BuildException, IOException, Exception
Replacing the Apache Log4J with a new logging framework
DBB v2.0 replaces the previous Apache Log4J logging framework with the Simple Logging Facade for Java™ (SLF4J) technology. Though this change does not impact the DBB toolkit APIs or Groovy build scripts, the configuration and use of the new logging framework have changed. You might have to change the CI/CD pipeline scripts. For information on how to configure and use SLF4J, see Configuring the logging framework for more details.
Support for Java 11
In addition to continuing to support running on the IBM Java 8 64-bit JVM, DBB v2.0 now also supports IBM Semeru (Java 11) JVM. For more information, see Prerequisites.
DBB User Roles
Roles were used in the DBB web application to control access to the web application and what REST APIs can be used to manipulate data in the DBB database. The roles were defined and users and groups added to the roles in the Liberty configuration. DBB 2.0 now uses the RACF groups DBBADMNS, DBBUSERS, and DBBGUEST to define DBB roles. See Granting roles to users for more information on DBB roles and how they affect access to DBB data. Note that a user must belong to one of these groups to use DBB 2.0 with Db2.
DBB Db2 database
Although the Db2 database from the DBB 1.1.x web server can be used by DBB 2.0, there are some upgrading considerations.
DBB 2.0 requires the Db2 database to be at the 1.1.1 release level. If the DBB web application was earlier than version 1.1.1, the database needs to be upgraded. See Upgrading the database for more information.
In addition, some database considerations for collection and build result owner and teams may affect permissions and access to the data. As the database for DBB 2.0 is used from USS in a RACF environment instead of from the web server in an LDAP environment, collection and build result owners and teams may need to change. If the user IDs of the collection or build result owners have changed because of the change in authentication, use the following SQL to change an owner from the old user ID to the new user ID.
SET SCHEMA DBBZ;
Update PERMISSIONS set P_OWNER = '<newOwner>' WHERE P_OWNER = '<oldOwner>';
COMMIT ;
If the group names that represent teams have changed from the LDAP environment to the RACF environment, use the following SQL to change a team value.
SET SCHEMA DBBZ;
Update PERMISSIONS set P_TEAM = '<newTeam>' WHERE P_TEAM = '<oldTeam>';
COMMIT ;
See Setting Permissions to learn more about permission settings in DBB.