Configuring and executing the zOSConnect task

1. Create an application configuration and configure sources (optional)

Create an application configuration named dbb-app.yaml in the root directory of your zOSConnect application.

If you are unfamiliar with application configuration, read the step Define application-specific behavior in dbb-app.yaml in Building the MortgageApplication sample, and the Application configuration concept reference.

By default, this task processes all sources in the source list unless the configSources variable is configured. If you want to filter the files processed, you can find examples of source file patterns from zAppBuild in the example below. The OpenAPI V3 version of this task only processes src/main/api/openapi.yaml files by nature regardless of the files in the source list, so this step is typically not necessary.

version: 1.0.3
application:
  name: ApplicationName
  tasks:
    - task: zOSConnect 
      variables:  
        - name: configSources
          value: 
            - "**/openapi.yaml"

2. Install Bash

Gradle requires Bash to run on z/OS UNIX. If you do not already have a valid installation of Bash, you can acquire one from IBM Open Enterprise Foundation for z/OS (IBM OEF)

If your Bash executable is not found at the default path bash, then you must add it as a variable to the application configuration like so:

variables:  
  - name: shellEnvironment
    value: bash

3. Install z/OS Connect Gradle

zOSConnect OpenAPI V3 uses Gradle to build its projects. If you do not already have a setup of z/OS Connect Gradle, you can follow the steps in Building IBM z/OS Connect zosConnect-3.0 APIs with Gradle.

If your Gradle executable is not found at the default path /var/gradle/bin/gradle, then you must add it as a variable to the application configuration like so:

variables:  
  - name: gradlePath
    value: /var/gradle/bin/gradle

4. Run build lifecycle

Change into the root directory of your project and execute a full build via the DBB CLI command dbb build full. If you want to execute a file build, ensure that the src/main/api/openapi.yaml file found in each project you want to build is included in the source list, as looking for that file is how this task calculates its project directories.

5. Troubleshooting Tips

If your build fails you can activate Gradle debug messages by enabling the variable for it in your application configuration like so:

variables:
  - name: gradleDebug
    value: true

6. View artifacts

Upon build completion, the api.war file will be copied to a zCEE3 directory inside your output directory. The build report contains a record for this task's UNIX execution and stores the exact path in its outputs field.

If you do not set an output directory, this task will use your logs directory as defined by the Start task instead.

1. Create an application configuration and configure sources

Create an application configuration named dbb-app.yaml in the root directory of your zOSConnect application.

If you are unfamiliar with application configuration, read the step Define application-specific behavior in dbb-app.yaml in Building the MortgageApplication sample, and the Application configuration concept reference.

By default, this task processes all sources in the source list unless the configSources variable is configured. If you want to filter the files processed, you can find examples of source file patterns from zAppBuild in the following example.

version: 1.0.3
application:
  name: ApplicationName
  tasks:
    - task: zOSConnect 
      variables:  
        - name: configSources
          value: 
            - "**/zosconnect_artefacts/apis/**/*.*"
            - "**/zosconnect_artefacts/services/**/*.*"
            - "**/zosconnect_artefacts/apis/**/.project"
            - "**/zosconnect_artefacts/services/**/.project"
            - "**/zosconnect_artefacts/apiRequester/*.properties"
            - "**/zosconnect_artefacts/SAR/*.properties"

2. Configure OpenAPI V2

By default this task uses OpenAPI V3. In order to use V2 you must set the configuration variable for the API version in your application configuration like so:

variables:
  - name: openAPIVersion
    value: 2

3. Configure the path to your zconbt binary

If you are building a z/OS Connect project by using OpenAPI V2, it is required that you set the configuration variable for the path to your zconbt binary like the following example. This binary can be located in your z/OS Connect installation bin directory.

variables:
  - name: zconbtPath
    value: path/to/zconbt

4. Configure input types (optional)

This task provides different handling depending on what type of path is passed in to build. By default, each file in the source list is built on its own. By configuring a file's input type to project, this task searches through its directory hierarchy for the .project file to calculate the root of its project. It then builds the entire project instead of just the file. This task only builds each project once even if multiple build files from the same project are specified in this way. If the project is not in a directory with a .project file, then it is skipped.

You can apply input types to groups of files by using four file patterns, as well as configure the default input type for files like so:

variables:
  - name: defaultInputType
    value: null
  - name: inputType
    value: project
    forFiles: **/projectDir/**

5. Enable ARA artifact packaging (optional)

If you have an ARA properties file, this task can create a directory structure in accordance to it and copy source files to it. You can enable this by configuring the input type of your ARA properties file to ARA.

variables:
  - name: inputType
    value: ARA
    forFiles: **/ara.properties
  - name: doPackageAraArtifacts
    value: true

6. Run build lifecycle

Change into the root directory of your project and execute a full build via the DBB CLI command dbb build full to build it.

7. View artifacts

Upon build completion, all build artifacts are copied to a zCEE2 directory inside your output directory. The build report contains a record for this task's UNIX execution and stores the exact path in its outputs field.

If you do not set an output directory, this task uses your logs directory as defined by the Start task instead.