Integrating DBB with Jenkins

This section describes setting up a remote Jenkins agent on USS and creating a new Jenkins build project for Mortgage Application.

Setting up a remote Jenkins agent on USS

Before you begin

Gather the following information to configure the agent:

SSH port for the USS machine (usually 22)
Full Java executable path installed on USS (example: /var/java18_64/J8.0_64/bin/java )

Procedure

On the main Jenkins Dashboard, click the "Build Executor Status" link.
Click the "New Node" link.
Provide a name of the remote agent and check the "Permanent Agent" option and click "OK".
Complete the required fields:
- Number of executors: 1
- Remote root directory : The USS directory where the Jenkins remoting.jar file and project workspaces used by this remote agent will be created
- Usage : Select "Use this node as much as possible"
- Launch Method : Select "Launch agents on via SSH"
  - Host: Host name of the USS machine (example: mvs255.rtp.raleigh.ibm.com)
  - Credentials: Add an appropriate credential for your USS connection
  - Port: SSH port gathered earlier (usually 22)
  - JavaPath: Full path of Java executable installed on USS gathered earlier
  - JVM Options: Use the following options because this is a z/OS system:
```
 -Dfile.encoding=utf-8 -Xnoargsconversion
```
  - Prefix Start Agent Command:
    - The full path to the gitenv.sh file
    - Set and export the BPX_JOBNAME environment variable
    - Set and export the JAVA_HOME environment variable
    - Set and export the IBM_JAVA_ENABLE_ASCII_FILETAG environment variable
    - Invoke the Jenkins server environment variables
    - For example:
```
. /usr/lpp/IBM/dbb/conf/gitenv.sh && export BPX_JOBNAME=BGZJENK && export JAVA_HOME=/usr/lpp/java/J8.0_64/ && export IBM_JAVA_ENABLE_ASCII_FILETAG=ON && env &&
```
  - Suffix Start Agent Command: -text
    
    Note: Ensure that there is a space before -text.
  - Availability : Select "Keep this agent online as much as possible"
  - Node Properties: Check "Tool Locations"
    - Click the "Add" button next to "List of tool locations".
    - In the Name field, select the Git tool.
    - In the Home field, add the absolute path to the git-jenkins.sh script located in the DBB Toolkit sample directory.
      - For example: /usr/lpp/IBM/dbb/bin/git-jenkins.sh
      - Note: Git commands issued by Jenkins via the remoting.jar file residing on USS will fail with an "FATAL: Invalid id" error usually followed by a string of invalid characters. This is because one of the commands generates ASCII characters. We have found that piping the Jenkins Git commands through ICONV resolves the problem. The git-jenkins.sh sample shell script is provided for this purpose.
Save the new node.

Validating the remote agent on USS setup

The remote root directory is created on USS (if it does not already exist).
The remoting.jar file is uploaded to the root directory.

Setting up a Jenkins build project for MortgageApplication

Procedure

Verify that there the Groovy plugin is installed on Jenkins
- On the main Jenkins dashboard click the "Manage Jenkins" link
- Click the "Manage Plugins" link
- Click the "Installed" tab
- Verify that there is a Groovy plugin installed
  - If not click on the "Available" tab
  - Install the Groovy plugin
Add a Jenkins Groovy installation for the Groovy installation that is included in the DBB Toolkit
- On the main Jenkins dashboard click the "Manage Jenkins" link
- Click the "Global Tool Configuration" link
- Click the "Groovy Installations..." link under the Groovy section
- Click the "Add Groovy" link
  - Provide a name for the Groovy Installation: DBB_Groovy
  - Uncheck the "Install Automatically" option
  - Provide the Groovy Home for the DBB Groovy installation (example: /usr/lpp/IBM/dbb/groovy-2.4.12)
- Click Save
On the main Jenkins dashboard click the "New Item" link
- Enter a name (example: MortgageApplication)
- Choose the "Freestyle" project and click "OK"
- Configure the new build project
  - General Tab
    - Check "Restrict where this project can be run"
    - Label Expression : Enter the name of Jenkins remote USS agent that was created earlier
  - Source Code Management Tab
    - Check "Git"
    - Repository URL - the URL of the central repository that contains MortgageApplication project
      - NOTE: You can use the filepath of a local repo. This may result in a connection error message in the project configuration but that can be ignored as long as the remote agent can access the local repo.
    - Credentials - Create or add the appropriate credentials for the Git repo
    - Branches to build - set the branch or leave blank for any.
  - Build Triggers - Set any build triggers desired. Or leave blank if you only plan to "launch" the builds manually
  - Build Tab
    - Add an "Execute Groovy Script" build step
      - Groovy Version: Select the DBB Groovy installation configured earlier
      - Select "Groovy script file" from the drop down widget and enter the path to the Mortgage Application main build file i.e. build.groovy
        
        NOTE: Jenkins provides an environment variable called WORKSPACE which is the project work space. The build git repo is cloned and/or pulled to this location at the beginning of the build
        
        example: ${WORKSPACE}/MortgageApplication/build/build.groovy
      - Click "Advanced"
      - Groovy Parameters : Leave blank
      - Classpath : All of the required JAR files are in the DBB installation (use '*' to indicate all files in lib) (example: /usr/lpp/IBM/dbb/lib/*)
      - Script parameters : The Mortgage Application main Groovy script (build.groovy) is expecting a number of parameters.
        
        Note: Refrain from using newline characters to format the parameters in the text area as they will prevent the parameters from being parsed correctly
        
        sourceDir (optional): Absolute path to source directory. The Jenkins Git client will load the source files to project work space (example: --sourceDir ${WORKSPACE})
        
        workDir (optional): Absolute path to the build output directory. Jenkins provides an environment variable called BUILD_NUMBER that is useful to differentiate work directories (example: --workDir ${WORKSPACE}/BUILD-${BUILD_NUMBER} ).
        
        hlq (optional): High-level qualifier for input and output partition data sets (example: --hlq USR1.MORTGAGE)
        
        repo (optional): DBB repository URL (example: --repo https://zoot.rtp.raleigh.ibm.com:9443/dbb)
        
        id (optional): DBB repository id (example: --id ADMIN)
        
        pwFile (optional): Absolute path to file containing DBB password (example: --pwFile ${WORKSPACE}/MortgageApplication/build/ADMIN.pw)
        
        collection (optional): Name of the dependency data collection (example: --collection MortgageApplication)
        
        logEncoding (optional): Encoding of output logs. Default is EBCDIC. To display correctly from the Jenkins dashboard they should be UTF-8 (example: --logEncoding UTF-8)
        
        buildFile (required): Relative path (from sourceDir) of the file to build. If file is *.txt then assumed to be buildlist file containing a list of relative path files to build and/or scan. Build list file can be absolute or relative (from sourceDir) path. The MortgageApplication sample provides a file list. (example: ${WORKSPACE}/MortgageApplication/build/files.txt)
      - Properties : Leave blank
      - Java Options: You will need to add a Java option to point to the DBB toolkit lib directory which contains a necessary .so file (example: -Djava.library.path=/usr/lpp/IBM/dbb/lib:/usr/lib/java_runtime64)
- Click Save

Validating the MortgageApplication Jenkins build project setup

Before you begin

DBB generates a build report HTML page as a summary of the build. This page contains inline JavaScript. To display this page in the Jenkins workspace, you might need to modify the Content Security Policy rule to allow inline JavaScript to work by modifying the Jenkins configuration (On Redhat Linux: /etc/sysconfig/jenkins) to add the following to JENKINS_JAVA_OPTIONS.

-Dhudson.model.DirectoryBrowserSupport.CSP=\"unsafe-inline;\"

Procedure

Click "Build Now" on the main Jenkins dashboard click the Mortgage Application project
- Monitor the build progress in the "Build History" section
- Verify that the build finished successfully.
  - Result should have a blue dot icon
  - Click on the result and then click on "Console Output"
  - Scroll to the botton of the output and verify it states:
    - Build State : CLEAN
    - Total files processed : 9 (or 10 if IMS build is enabled) Finished: SUCCESS
  - Return to the Mortgage Application project page and click on "Workspace"
    - There should be a folder link with the name "BUILD- " if the workDir earlier was defined as --workDir ${WORKSPACE}/BUILD-${BUILD_NUMBER}
    - Click on the folder link
    - Verify that there are eight (or nine if IMS build is enabled) build logs
      - DFSIV1.log (optional IMS build)
      - EPSCMORT.log
      - EPSCSMRD.log
      - EPSCSMRT.log
      - EPSMLIS.log
      - EPSMLIST.log
      - EPSMORT.log
      - EPSMPMT.log
      - EPSNBRVL.log
    - Click on the link for each log file and verify that the compile/link-edit logs completed successfully
    - Verify that there is a BuildReport.json and a BuildReport.html file
    - Click on the BuildReport.html file and verify that the contents are correct