What's new in IBM z/OS Connect OpenAPI 3

Use this information to discover the enhancements in each refresh of IBM z/OS Connect OpenAPI 3.
Note:
  1. This documentation describes the latest release of IBM z/OS Connect that supports the OpenAPI 3.0 specification. If you have an earlier release, some of the capabilities that are described in this documentation might not be available. To use IBM z/OS Connect to create APIs that conform to the OpenAPI 2.0 specification, see the z/OS Connect (OpenAPI 2) documentation.
  2. As stated in the license agreement, IBM provides fixes only for the current release and the two previous releases.
  3. Best practice is to apply the latest release as soon as it is available, but some releases are the minimum that are required to resolve specific issues. Similarly, statically linked API requester programs must be relinked to pick up new functions and fixes.
Table 1. Enhancements and fixes.

The following table lists the maintenance level and the changes in each refresh of IBM z/OS Connect.

Maintenance level Enhancements and fixes
April 2024
3.0.80 (APAR PH60397)

z/OS Connect server update

Enhancements
  • z/OS Connect server is now supported on z/OS/s390x with IBM z/OS Container Platform. For more information, see Installing and uninstalling an IBM z/OS Connect server image with Podman.
  • IBM z/OS Connect Operator is updated to 1.0.8 and the z/OS Connect CASE package bundle file is updated to 1.0.9. The Pods that are created by the IBM z/OS Connect Operator are annotated with productName, productID, and productMetric to allow the IBM License Service to recognize the z/OS Connect Pods should IBM License Service be required by other IBM products that are installed into the same cluster. For more information, see Create a ZosConnect Custom Resource (CR) instance.
  • The version of the API provider Gradle plug-in is upgraded to 1.4.3.
  • The version of the API requester Gradle plug-in is upgraded to 1.1.4.
Fixes
  • PH60401 - Message IFA104I REGISTRATION HAS BEEN DENIED is reported and the z/OS Connect OpenAPI 3 native server does not start.
  • PH60630 - Message SRVE0777E java.net.URLDecoder.decode is reported when the BAQ-API-PATH value is greater than 70 characters.
March 2024
3.0.79 (APAR PH59752)

z/OS Connect server update

Enhancements
  • The version of the API provider Gradle plug-in is upgraded to 1.4.2.
  • The version of the API requester Gradle plug-in is upgraded to 1.1.3.
Fixes
  • PH59106 - A z/OS Connect API requester receives HTTP status code 401 when using a cached token.
  • PH60040 - Describes a problem that was found in z/OS Connect 3.0.78 and fixed by Liberty APAR PH59374. The Liberty fix is included in z/OS Connect 3.0.79. For more information, see PH59374 on the IBM Support page for WebSphere® Application Server for z/OS Liberty.
z/OS Connect Documentation Enhancements
  • The z/OS Connect documentation has been updated to include an IBM z/OS Connect Operator and CASE version compatibility table. This table shows which z/OS Connect releases included which versions of the IBM z/OS Connect Operator and the CASE version. For more information, see IBM z/OS Connect Operator and CASE version compatibility.
February 2024
V3.0.78 (APAR PH59261)

z/OS Connect server update

Enhancements
  • Support is provided for the PL/I programming language for API requester CICS TS and z/OS applications, along with API provider API First. For more information about using PL/I support for API requester, see Linking by dynamic calls.
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V23.0.0.12. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
  • The version of the API provider Gradle plug-in is upgraded to V1.4.1.
  • The version of the API requester Gradle plug-in is upgraded to V1.1.2.
Fixes
  • PH59592 - Message SRVE0321E is reported in the z/OS Connect OpenAPI 3 server's messages.log file when the configuration includes a web-ext element that exposes the server's configuration directory as a web application.
  • PH56143 - Data transformation fails and message BAQR1138E is reported when a colon is included in an element name.
  • PH54217 - The CICS® API provider support for z/OS Connect OpenAPI 3 incorrectly returned HTTP status code 500 when a request timed out.
January 2024
V3.0.77 (APAR PH58769)

z/OS Connect server update

Enhancements
  • The version of the API requester Gradle plug-in is upgraded to V1.1.1.
Fixes
  • PH58776 - Using oneOf in the OpenAPI 3 document for an API requester results in incomplete data being received.
z/OS Connect Documentation Enhancements
  • The z/OS Connect documentation has been updated to include an OpenAPI 3 artifact compatibility table. This table shows which z/OS Connect releases included which z/OS Connect Gradle plug-ins to understand which z/OS Connect server version the z/OS Connect OpenAPI 3 artifacts can be deployed to. For more information, see OpenAPI 3.0 artifact compatibility.
  • The z/OS Connect documentation has been updated to include details about the IBM Documentation search feature at the top of each page to optimize your search results. For more information, see Using the IBM Documentation search feature.
December 2023
V3.0.76 (APAR PH58281)

z/OS Connect server update

Enhancements
  • The OpenAPI 2 interceptor interfaces for API requester are now available in OpenAPI 3 native servers for real time monitoring of requests, with the exception that requests failing early cannot be monitored, this includes authentication and authorization failures. For more information, see Using a real-time monitoring or transaction tracking product. IBM Z OMEGAMON for JVM requires APAR OA65632 for version 550 and APAR OA65643 for version 610 to monitor z/OS Connect native servers with the zosConnect-3.0 feature.
  • The audit interceptor can be configured in an IBM z/OS Connect native server to capture SMF 123 subtype 2 V2 records for API requester. Records cannot be captured for requests failing early due, for example, to authentication or authorization failures. In the SMF 123 subtype 2 V2 record, the server section version SMF123_SERVER_SECT_VERSION is updated to 2 and the IBM z/OS Connect major and minor feature versions are output in a previously reserved field. Existing products that process SMF 123 subtype 1 records can be used to format these records, but the feature version data will not be available unless the product has been updated to support it. For more information, see API requester data from SMF type 123 subtype 2 version 2 records.
  • IBM z/OS Connect now includes additional server templates that you can use to create z/OS Connect servers to run the completed API provider tutorials. For more information, see Supplied server templates.
  • The version of the API provider Gradle plug-in is upgraded to V1.4.0.
  • The version of the API requester Gradle plug-in is upgraded to V1.1.0.
Fixes
  • PH58357 - Messages BAQR1801E and IWAA1110E are reported when CCSID 1390 or 1399 are specified in Designer.
November 2023
V3.0.75 (APAR PH57677)

z/OS Connect server update

Enhancements
  • COBOL applications running on z/OS (but not in IMS) can now call API endpoints using an API requester deployed to an IBM z/OS Connect server. For more information, see Configuring other z/OS applications to access IBM z/OS Connect for API calls.
  • The IBM z/OS Connect API requester Gradle plug-in is upgraded to V1.0.6 and enhanced to use the full operation ID for storing generated artifacts. The full operation ID is also now included as a comment in the generated API info language structure.
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V23.0.0.9. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
Fixes
  • PH57249 - When building an OpenAPI 3 API requester using the Gradle API requester plug-in V1.0.4 on Windows, some of the Japanese messages are not displayed correctly. Messages up to BAQP0010I are displayed as expected, but messages from BAQG1023W and onward are not displayed correctly.
  • PH57209 - The abendCode field is not populated in the response from a CICS z/OS Asset.
z/OS Connect Designer Enhancements Fixes
  • PH57708 - At V3.0.72.0 the z/OS Connect containerized images changed from using an IBM Java SE Runtime to an IBM Semeru Runtime Open Edition Java. Many codepages that were provided with IBM Java SE Runtime are no longer available in IBM Semeru Runtime Open Edition Java. This resulted in the reported error messages being issued.

    This issue affects both z/OS Connect Designer and server images, but does not affect the z/OS Connect V3 native server.

z/OS Connect Documentation Enhancements
October 2023
V3.0.74 (APAR PH56974)

z/OS Connect server update

Enhancements
  • The OpenAPI 2 interceptor interfaces for API provider are now available in OpenAPI 3 native servers for real time monitoring of requests. For more information, see Using a real-time monitoring or transaction tracking product. IBM OMEGAMON® for JVM requires APAR OA65632 for V5.5.0 and APAR OA65643 for V6.1.0 to monitor z/OS Connect native servers with the zosConnect-3.0 feature.
  • The audit interceptor can be configured in a z/OS Connect native server to capture SMF 123 subtype 1 V2 records for API provider. In the SMF 123 subtype 2 V2 record, the server section version SMF123_SERVER_SECT_VERSION is updated to 2 and the z/OS Connect major and minor feature versions are output in a previously reserved field. Existing products that process SMF 123 subtype 1 records can be used to format these records, but the feature version data will not be available unless the product has been updated to support it. See Using SMF records to monitor requests.
  • IBM z/OS Connect Operator is updated to V1.0.7 and the z/OS Connect CASE package bundle file is updated to V1.0.8. For more information, see Install the IBM z/OS Connect Operator.
  • The IBM z/OS Connect API provider Gradle plug-in is updated to V1.3.0. For more information, see System requirements.
z/OS Connect Documentation Enhancements
  • The IBM z/OS Connect server image topics in the z/OS Connect documentation are restructured and enhanced with more content on Planning, Installing (building and deploying APIs) in online and offline environments, and new content for upgrading online and offline deployments and uninstalling. For more information, see IBM z/OS Connect server image.
September 2023
V3.0.73 (APAR PH56451)

z/OS Connect server update

Enhancements
  • The version of the API provider Gradle plug-in is upgraded to V1.2.0.
  • The version of the API requester Gradle plug-in is upgraded to V1.0.5.
Fixes
  • PH56374 - The IBM z/OS Connect OpenAPI 3 API requester Gradle plug-in does not allow an API key header named Authorization.
August 2023
V3.0.72 (APAR PH55842)

z/OS Connect server update

Enhancements
  • z/OS native support for OpenAPI 3 is now extended to the Simultaneous Instance license 5655-CE3. This provides users with the ability to run native OpenAPI 3 server instances on z/OS, in addition to existing OpenAPI 2 server instances. For more information, see IBM z/OS Connect capabilities.
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V23.0.0.6. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
z/OS Connect Documentation Enhancements
July 2023
V3.0.71 (APAR PH55091)

z/OS Connect server update

Enhancements
z/OS Connect Designer Enhancements
  • z/OS Connect Designer is enhanced to import updated OpenAPI 3 documents to an existing API project. For more information, see Updating an OpenAPI document.
  • The IBM z/OS Connect API provider Gradle plug-in is updated to V1.1.2 and the IBM z/OS Connect API requester Gradle plug-in is updated to V1.0.4. For more information, see System requirements.
Fixes
  • PH54414 - A condition-type JSONata expression in the response_mapping.yaml file does not appear in designer and shows a warning icon.
z/OS Connect Documentation Enhancements
June 2023
V3.0.70 (APAR PH54460)

z/OS Connect server update

Enhancements
  • JWT support for the IBM z/OS Connect API requester is enhanced with the following capabilities:
    • The IBM z/OS Connect server can authenticate with the authentication server by sending the client ID and client secret in separate named HTTP headers. For example, X-IBM-Client-ID and X-IBM-Client-Secret. For more information, see Format of authentication server request for a JWT in Calling an API secured with a third-party JWT.
    • The z/OS application can set additional custom HTTP headers to send on the request to the authentication server. For more information, see BAQR-TOKEN-CUSTOM-HEADERS in JWT parameters.
    • The z/OS application can set additional custom parameters that are substituted into the request body to send on the request to the authentication server. For more information, see BAQR-TOKEN-CUSTOM-PARMS in JWT parameters.
    • A new optional attribute, tokenRefreshRate on the zosconnect_authToken configuration element, specifies a period of time after which an attempt is made to obtain a new JWT even if there is a non-expired cached JWT. For more information, see zosconnect_authToken.
  • z/OS Connect Operator is updated to V1.0.6 and the z/OS Connect CASE package bundle file is updated to V1.0.7. For more information, see Install the IBM Operator Catalog in Red Hat OpenShift.
  • The IBM z/OS Connect API provider Gradle plug-in is updated to V1.1.1. For more information, see System requirements.
z/OS Connect Documentation Enhancements
May 2023
V3.0.69 (APAR PH53896)

z/OS Connect server update

Enhancements
  • IBM z/OS Connect is enhanced to support an API-First development approach for API provider. From an OpenAPI 3.0 specification document, you can use this new capability to generate the API provider project, war file, and copybooks required to implement a CICS COBOL application. For more information, see Developing APIs with Gradle.
  • A new value of JWT is added to the responseFormat attribute on the zosconnect_authToken > tokenResponse element. For more information see zosconnect_authToken > tokenResponse in the Reference section.
  • Query parameters of type ‘array’ are processed to a JSON array for request mapping in the server. For more information, see How the z/OS Connect server JSON object is created for mapping.
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V23.0.0.3. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
  • The IBM z/OS Connect API provider Gradle plug-in is updated to V1.1.0. For more information, see System requirements.
  • The IBM z/OS Connect API requester Gradle plug-in is updated to V1.0.3. For more information, see System requirements.
Fixes
  • PH47770 - The IBM z/OS Connect OpenAPI 3 functions use the default CCSID of the platform that the product is running on. For z/OS Connect running on Linux this causes the container received in CICS to be in CCSID 437, but for z/OS Connect running on z/OS the container CCSID is 1208.
  • PH48024 - Query parameters of type Array are processed to a JSON array for request mapping in the server.
  • PH53008 - When obtaining a third-party JWT from an authentication server, the Content-type header is incorrectly set to "application/json;charset=UTF-8" on the HTTP request to the authentication server. It was also not possible to set the accept header to "application/jwt".
z/OS Connect Designer Fixes
  • PH47770 - The IBM z/OS Connect OpenAPI 3 functions use the default CCSID of the platform that the product is running on. For z/OS Connect running on Linux this causes the container received in CICS to be in CCSID 437, but for z/OS Connect running on z/OS the container CCSID is 1208.
April 2023
V3.0.68 (APAR PH53266)

z/OS Connect server update

Enhancements Fixes
  • PH52820 - Message DFHIS1023 Conversation error (code X'062A') is reported on an IPIC connection with z/OS Connect.
z/OS Connect Designer Enhancements
  • z/OS Connect Designer is enhanced to use HTTPS. Previous releases supported HTTP only.
z/OS Connect Documentation Enhancements
March 2023
V3.0.67 (APAR PH52418)

z/OS Connect server update

Enhancements
  • z/OS Connect is enhanced to support IMS COBOL applications, mapping from OpenAPI 3.0 operations to message segments or Large Data Structures.
z/OS Connect Designer Enhancements
  • You can now develop API projects in z/OS Connect Designer to map OpenAPI 3.0 operations to IMS COBOL applications.
z/OS Connect Documentation Enhancements
February 2023
V3.0.66 (APAR PH52022)

z/OS Connect server update

Enhancements Fixes
  • PH48233 - BAQR1153W HTTP status code 400 is reported when a message greater than 4 KB is sent to an API endpoint.
  • PH51224 - Sending an OAuth 2.0 access token to an endpoint failed because it could not be sent in a custom header.
z/OS Connect Documentation Enhancements
  • The IBM z/OS Connect documentation now has a new Getting Started tutorial for API requester that provides steps on how to write a CICS COBOL application to call a remote an OpenAPI 3.0 RESTful API endpoint, process multiple HTTP response codes and manage dynamic length arrays that are described by the OpenAPI 3 document. For more information, see Creating an IBM z/OS Connect API requester project and z/OS application.
  • The IBM z/OS Connect documentation is now available offline with the IBM Documentation Offline tool. For more information, see IBM z/OS Connect Offline documentation.
January 2023
V3.0.65 (APAR PH51617)

z/OS Connect server update

Enhancements
z/OS Connect Documentation Enhancements

The IBM z/OS Connect documentation now has

December 2022
V3.0.64 (APAR PH51090)

z/OS Connect Designer

Enhancements
  • z/OS Connect Designer is now available on s390x and amd64 architecture.
z/OS Connect Documentation Enhancements

The IBM z/OS Connect documentation now has

  • 3 new "how-to" videos enhancing the "Creating and updating OpenAPI 3 documents for z/OS Connect" getting started tutorials.
  • 10 new "how-to" videos demonstrating the wide set of capabilities available in the z/OS Connect Designer that are now accessible from Developing APIs with the z/OS Connect Designer.
  • A new topic linking to the z/OS Connect Community for sharing samples, use cases, experiences, best practices, and asking your questions.
  • The "What is JSONata?" topic relocated to the Concepts section with JSONata sample expressions and limitations.
November 2022
V3.0.63 (APAR PH50283)

z/OS Connect server update

Enhancements
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V22.0.0.9. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
Fixes
  • PH39444 - Solidus characters (/) are escaped in the JSON payload response.
    Note: This APAR is canceled because the JSON specification allows a solidus character in a string field to be escaped. If the solidus character is included in a string field of the response, it should be processed on the client side of the JSON response.
z/OS Connect Documentation Enhancements
  • The IBM z/OS Connect documentation is enhanced with a new tutorial that shows you how to update an OpenAPI 3 document in the z/OS Connect API project files by using an integrated development environment (IDE) of your choice.
October 2022
V3.0.62 (APAR PH49486)

z/OS Connect server update

Enhancements
  • IBM z/OS Connect is enhanced so that you can now install and configure the z/OS Connect Operator in an air gap environment by using a bastion host. For more information, see What is an offline (air-gap) installation.
z/OS Connect Designer Enhancements
  • The z/OS Connect Designer Test button has been enhanced to show when an API project build is currently running or has failed. This makes it easier to know when the API is ready to test within the z/OS Connect Designer. For more information, see Testing an API with z/OS Connect Designer.
z/OS Connect Documentation Enhancements
September 2022
V3.0.61 (APAR PH48652)

Server code update

Maintenance release only
Note: After applying this update, some diagnostic information is written to the messages.log to aid analysis if a problem occurs. This information is not returned to the client.
August 2022
V3.0.60 (APAR PH48008)

Server code update

Enhancements
July 2022
V3.0.59 (APAR PH47276)

Server code update

Enhancements
  • IBM z/OS Connect now supports cloud deployment on Intel architecture. This capability expands the opportunities for providing access to data on Z systems so you can manage all your APIs on the same platform. IBM z/OS Connect can be deployed into your existing cloud environment, to make use of your existing investment and manage the product in familiar ways.
  • IBM z/OS Connect is enhanced to support workload distribution of requests across a group of CICS regions, by using a single connection reference. Workload distribution is configured with a new zosconnect_cicsConnectionGroup element. Groups can include other groups and the distribution of requests can be weighted. For more information, see CICS IPIC workload distribution.
Fixes
  • PH44647 BAQR1084E: The authorization server token endpoint has an invalid prefix is reported when tokenEndpoint specifies "http".
  • PH45822 - The order of fields in the response JSON object does not match the input open API specification document when a new field is added.
z/OS Connect Designer update Fixes
  • PH46753 - An API response displays integer values in exponential format when they are mapped to string fields.
June 2022
V3.0.58 (APAR PH46461)

Server code update

Enhancements
  • Based on customer feedback, new examples of JSONata expressions are added to showcase the wide variety of capabilities that you can use when mapping your z/OS Assets to transform JSON data. For more information, see Sample JSONata expressions.
May 2022
V3.0.57 (APAR PH45674)

Server code update

Enhancements
  • The IBM z/OS Connect messages output by the CICS IPIC HA reconnection mechanism are enhanced. In addition, a new keyword of “local” can be set for the preferredSpecificHost attribute to specify a CICS region that is on the same LPAR as the IBM z/OS Connect server. For more information, see CICS IPIC high availability.
  • The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V22.0.0.3. For more information, see What is new in this release of Liberty in the WebSphere Application Server for z/OS Liberty documentation.
z/OS Connect Designer update Fixes
  • PH46003 - Message CWPMI2005W is reported after clearing a field causes an empty object in response_xxx.yaml.
April 2022
V3.0.56 (APAR PH45219)

Server code update

Enhancements
  • IBM z/OS Connect provides a CICS IPIC HA reconnection mechanism to enable automatic re-balancing of HA connections. This capability is enabled by specifying a reconnect interval for the reconnectInterval attribute of the zosconnect_cicsIpicConnection element. Optionally, a preferred CICS region can be specified by using the preferredSpecificHost and preferredSpecificPort attributes. For more information, see CICS IPIC high availability.
Fixes
  • PH42084 - Message GMOSR0013E: An unexpected error occurred processing service is reported after updating to V3.0.45.0 or later.
March 2022
V3.0.55 (APAR PH43628)

Server code update

Enhancements
  • IBM z/OS Connect is enhanced to support the OpenAPI 3.0 specification. This capability is described in this documentation.

    To use IBM z/OS Connect to create APIs that conform to the OpenAPI 3.0 specification, you need an Unlimited license or an IBM Z & Modernization Stack license.

    Note: You can continue to work with OpenAPI 2.0 specification APIs by using the documentation at z/OS Connect (OpenAPI 2).
z/OS Connect Designer IBM z/OS Connect V3.0.55 introduces the z/OS Connect Designer, a user interface (UI) that you can use to develop, test, and manage your APIs. For more information, see Developing APIs with the IBM z/OS Connect Designer

For updates before V3.0.55, see the change history for z/OS Connect (OpenAPI 2)