Building IBM z/OS Connect APIs with Gradle

• com.ibm.zosconnect.gradle for API provider. For reference see, IBM z/OS Connect API provider Gradle Plugin.
• com.ibm.zosconnect.requester for API requester. For reference, see IBM z/OS Connect API requester Gradle Plugin.

• A z/OS Connect project is available. Ideally, the API project source is checked into a Source Code Management (SCM) repository.
• Gradle 7.6.1 or higher is installed on the machine running the builds. For more information about supported Gradle versions, see IBM z/OS Connect system requirements.
• For API provider projects, the z/OS Connect API provider Gradle plug-in, com.ibm.zosconnect.gradle that is automatically downloaded in an online environment, must be available to build the API provider project WAR files. For more information, see maven central repository - com.ibm.zosconnect.provider
• For API requester projects, the z/OS Connect API requester Gradle plug-in, com.ibm.zosconnect.requester that is automatically downloaded in an online environment, is available to build the API requester project WAR files. For more information, see maven central repository - com.ibm.zosconnect.requester.
• Choose one of the following options for the directory where the API project WAR files are deployed.

  The drop-ins directory

  The drop-ins directory, /config/dropins is a special directory that is supported by WebSphere® Application Server Liberty. It allows WAR files to be deployed and dynamically loaded into the running z/OS Connect Server with no additional definitions that are required in the configuration file.

  By default, z/OS Connect Designer deploys the API project WAR file to this directory. Using the same directory in your API container image simplifies the creation of that image because the configuration remains the same. This option simplifies the DevOps pipeline by using this deployment method when developing the API project. A production system would not use this option.

  A directory other than drop-ins

  This is required in any of the following situations:

  • The APIs OpenAPI definition servers: section contains an entry for the context root value of the API, which is not just /.
    Note: The API project WAR file is generated with a context root of /.
  • Multiple APIs are to be deployed to the same z/OS Connect Server. Because the API project WAR file is generated with a context root of /, and multiple API WAR files in the same server must have unique context root values, you need to include a unique context root value (not /) in the APIs OpenAPI definition servers: section. For example, to use a context root of /EmployeesApi.

    openapi: 3.0.0
       ...
       servers:
          url: https://localhost:9443/EmployeesApi
       ...

  These API project WAR files are typically deployed into the /config/apps directory. You must create this directory but you can choose a different name.

  You also need to configure a webApplication element in the server.xml configuration file. For example,

  <webApplication location="/config/apps/EmployeesApi.war" name="EmployeesApi" contextRoot="/EmployeesApi"/>

  Where:

  • location is the fully qualified path to the deployed API WAR file.
  • name is an optional attribute that is used in log messages to identify the API.
  • contextRoot value must match the context root value that is specified in the servers: entry of the OpenAPI definition servers: section.

1. Extract the z/OS Connect API project from your Source Code Management (SCM) solution.
2. Start the Gradle build process. Use the gradle build command to run a build task that packages the API project as a Web Application archive (WAR) file. When defining this task in your DevOps pipeline you can use the build.gradle, and settings.gradle file found in the API project. For more information about the Gradle plug-ins and their requirements, see Using the API provider Gradle plug-in and Using the API requester Gradle plug-in.
   Note: Started task

   Each API requester project WAR file must have a unique name. For more information about the apiName property in the API requester Gradle plug-in properties and options, see The API requester Gradle plug-in properties and options.

   Important:

   For multiple API project WAR files to function when deployed to a single z/OS Connect Server, you must ensure that your OpenAPI specification includes a contextRoot defined within the servers section. The contextRoot attribute specifies the entry point of the deployed application. For example, to use a contextRoot of /myContextRoot in the APIs OpenAPI definition servers section:

   openapi: 3.0.0
   ...
   servers:
   url: "https://localhost:9443/myContextRoot"
   ... 

   This definition must match the contextRoot attribute value of the webApplication element in your server.xml file. An example of the configuration might be:

   <webApplication location="${server.config.dir}/apps/api.war" name="EmployeesApi" contextRoot="/myContextRoot"/>

   If the server entry in the server section of the OpenAPI definition includes a contextRoot value, then this value must be specified in the contextRoot attribute of the corresponding webApplication element, even when only a single API is deployed to the z/OS Connect Server.

   Each API deployed to the same z/OS Connect Server requires a unique contextRoot. For example to deploy two APIs named sample-db2-api and sample-ims-api:

   <webApplication location="${server.config.dir}/apps/sample-db2-api.war" name="sample-db2-api" contextRoot="/sampleDb2Api"/>

   <webApplication location="${server.config.dir}/apps/sample-ims-api.war" name="sample-ims-api" contextRoot="/sampleImsApi"/>

3. Identify the appropriate configuration for the environment for which the image is built. For example, your API project might require different property substitutions that relate to the z/OS Connect Designer environment variables, such as CICS_USER, DB2_USER, CICS_PASSWORD, CICS_HOST and CICS_PORT or extra security configuration is needed.

pluginManagement {
    repositories {
        maven {
            url '<dir>/gradleLibs'
        }
    }
}

1. Set the following environment variables before starting Gradle.

   LANG=en_US.UTF-8

   GRADLE_OPTS="-Dfile.encoding=UTF-8"

   _BPXK_AUTOCVT=ON

2. If using the Gradle Wrapper, then ensure the gradlew file in the root of the project is tagged as ASCII.

   chtag -tc ISO8859-1 ./gradlew

3. If using an installation of Gradle, then ensure that the Gradle shell script is tagged as ASCII. For example, extract the installation with the correct environment variables to have the tagging automatically applied:

   _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG)" unzip gradle-X.Y-bin.zip

   Alternatively, if unzip is unavailable, you can use jar to extract the installation and then manually tag the script and set it executable.

   jar -xvf ../gradle-X.Y-bin.zip
   chtag -tc ISO8859-1 <Gradle installation>/bin/gradle
   chmod +x <Gradle installation>/bin/gradle