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:

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.
As stated in the license agreement, IBM provides fixes only for the current release and the two previous releases.
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 function 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
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 z/OS Connect Designer is enhanced to support the PL/I language when creating CICS and IMS z/OS Assets. For more information, see Importing CICS PL/I data structures and Importing IMS PL/I data structures. z/OS Connect Designer now includes a notifications panel where users can view and manage their notifications. 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 The tutorial Creating a z/OS Connect API requester and z/OS application is updated to describe how to call an OpenAPI 3.0 API endpoint from your z/OS applications. For more information, see Invoking the API requester from a z/OS application. A new topic describes a manual migration process that you can use to move your existing APIs running on an IBM z/OS Connect OpenAPI 2 server to an IBM z/OS Connect OpenAPI 3 server without changing the exposed API. See Migrating a CICS provider API from IBM z/OS Connect OpenAPI 2 to OpenAPI 3.
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 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 The z/OS Connect documentation is enhanced to include converting from z/OS Connect Simultaneous Instance to z/OS Connect Unlimited. For more information, see Converting from z/OS Connect Simultaneous Instance license to z/OS Connect Unlimited license.
July 2023
V3.0.71 (APAR PH55091) z/OS Connect server update	Enhancements z/OS Connect API requester is enhanced to support PassTicket authentication from CICS to a z/OS Connect server. For more information, see API requester PassTicket authentication to IBM z/OS Connect. The JSON object for request mapping is enhanced with a new field `requestMetadata`. This field contains a pointer to a JSON object that contains metadata about the API request that the server received. For more information, see How the z/OS Connect server JSON object is created for mapping.
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 The z/OS Connect documentation is enhanced with a new Disaster Recovery (DR) section. For more information, see Preparing for disaster recovery. The procedure in the Developing APIs topic has been updated for z/OS Connect Designer in Red Hat® OpenShift® Wazi Dev Spaces. For more information, see Create and edit an IBM z/OS Connect API project in Red Hat OpenShift Container Platform.
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 The procedure in the Developing APIs topic has been updated for z/OS Connect Designer in Red Hat OpenShift Dev Spaces. z/OS Connect Designer requires Red Hat OpenShift Dev Spaces Operator V3.6.0 or later. For more information, see Create and edit an IBM z/OS Connect API project in Red Hat OpenShift Container Platform.
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 When configuring an API requester, the parameters described for the API in the OpenAPI document can now include parameters described as cookies. For more information, see Map the API request to the z/OS Asset The z/OS Connect images are now signed and the signature can be verified. The z/OS Connect documentation is updated to include how to verify the signatures on the images. For more information, see Verify a z/OS Connect image signature (Optional). The IBM z/OS Connect API requester Gradle plug-in is updated to V1.0.2. For more information, see Generating the artifacts for an API requester. 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 New documentation is available to describe the download and installation of this documentation for offline use. For more information, see Introducing IBM Documentation Offline and How to use this documentation.
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 'How to' instructions to create an IMS z/OS Asset in z/OS Connect Designer, configure z/OS Connect connections to IMS and secure with basic authentication and AT-TLS. For more information see Creating an IMS z/OS Asset, Configuring connections to IMS and Configuring security for IMS connections. A new tutorial to create an API project to call the example IMS Phonebook program. Then, test your z/OS Connect API project with the built-in Liberty REST client. For more information, see Getting Started tutorial: Creating an IMS z/OS Connect API. The API requester tutorial project is available on GitHub and can be downloaded from here https://github.com/zosconnect/sample-oas3-requester or by using the link in the API requester tutorial. For more information, see Downloading the tutorial structure, prerequisites and downloading the tutorial.
February 2023
V3.0.66 (APAR PH52022) z/OS Connect server update	Enhancements IBM z/OS Connect is enhanced to support the generation of a JSON Web Token (JWT) for authentication with an API requester API endpoint. The subject claim in the JWT is set to the z/OS Connect authenticated user ID for the request. For more information, see Calling an API secured with a locally generated JWT. The version of Liberty that is embedded in IBM z/OS Connect is upgraded to V22.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 IBM z/OS Connect API provider Gradle plug-in that is shipped as part of z/OS Connect Designer is updated to V1.0.2. For more information, see Building z/OS Connect APIs with Gradle. The IBM z/OS Connect API requester Gradle plug-in is updated to V1.0.1. For more information, see Generating the artifacts for an API requester. The z/OS Connect Operator is updated to V1.0.4 and the CASE bundle file is updated to V1.0.5. For more information, see Install the IBM z/OS Connect Operator. 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 a z/OS Connect API requester 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 From IBM z/OS Connect V3.0.65.0, you can generate and deploy IBM z/OS Connect API requesters to your z/OS Connect native server so your CICS COBOL applications can call RESTful APIs through IBM z/OS Connect. For more information, see Calling APIs from z/OS applications. The z/OS Connect Operator Operator is enhanced to include Red Hat OpenShift Routes and native Kubernetes Ingress support. For more information, see Configure Transport Layer Security (TLS) in a Container Platform (Optional).
z/OS Connect Documentation	Enhancements The IBM z/OS Connect documentation now has 'How to' instructions to generate, deploy, and configure IBM z/OS Connect API requesters artifacts to a z/OS Connect native server. For more information, see Calling APIs from z/OS applications ‘How to’ instructions for secure networking (TLS) configuration options with Routes and Ingress for a z/OS Connect API deployed to a Container Platform with the z/OS Connect Operator. For more information, see Configure Transport Layer Security (TLS) in a Container Platform (Optional).
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 The IBM z/OS Connect documentation has 2 new tutorials and a new topic in Developing APIs on creating and enhancing OpenAPI 3 definitions. For more information, see Creating and updating OpenAPI 3 documents for z/OS Connect
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 IBM z/OS Connect is enhanced to enable the z/OS Connect Operator to be installed in Red Hat OpenShift OperatorHub. For more information, see Install the IBM Operator Catalog in Red Hat OpenShift.
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 z/OS Connect Designer

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