Updating z/OS Connect API project files
To use the z/OS Connect capabilities, API project mapping files must be updated by using the appropriate version of the z/OS Connect Gradle plug-ins or z/OS Connect Designer. Gradle-based projects can be rebuilt with the required plug-in version, while the z/OS Connect Designer automatically updates mapping files when newer features are detected. Compatibility between mapping file versions and the z/OS Connect Designer or z/OS Connect Server release is essential as mismatches can result in deployment errors, which must be resolved by aligning tool versions or reverting changes by using source control.
zosConnect-3.0 Applies to zosConnect-3.0.
Containers Applies to z/OS Connect container deployments.
Updating z/OS Connect mapping files with the z/OS Connect Gradle plug-ins
For API projects created by using the Gradle plug-in, you can rebuild your WAR files by using the required Gradle plug-in version to have the generated mapping files contain the latest capabilities. As with all API project changes, they should be tested, then the changes stored in the API project files in source control management (SCM).
Updating z/OS Connect mapping files with the z/OS Connect Designer
With z/OS Connect Designer, when an API project is loaded into a z/OS Connect Designer that has newer capabilities, an informational dialog is displayed to inform you that the API projects files will be automatically updated. The informational dialog displays when at least one mapping file has an older version within it.
API project mapping file versions not supported by the release
The z/OS Connect Designer can process only supported versions of the mapping files for previous releases and for that version of the z/OS Connect Designer. API projects that contain mapping file versions that are more recent than the maximum versions supported in the release of z/OS Connect Designer in use, cannot be edited. For more information about supported mapping files and z/OS Connect release versions, see zosConnect-3.0 API project file compatibility.
For example, ibm-zcon-designer:3.0.86 produces mapping files version 1.0 and
cannot process mapping files with version 1.1 or later. ibm-zcon-designer:3.0.87
produces mapping files version 1.1 and cannot process mapping files with version 1.2 or later. When
the API WAR file has been built with ibm-zcon-designer:3.0.87,
it can be deployed to a z/OS Connect Server that is a
minimum release version 3.0.87. The API WAR file cannot be deployed to a z/OS Connect Server by using version 3.0.86 as this
version cannot process version 1.1 mapping files. The simplest method to avoid these compatibility
issues is to always use a z/OS Connect Designer and z/OS Connect Server version that are at the same z/OS Connect release version. If an API project contains
mapping file versions that are not supported by the release version of z/OS Connect Designer, the following error message is produced by the server.
BAQR1717E: File %2Fexample/get/request.yaml contains a version which is not supported at this level. Maximum supported version 1.1. Requested version 1.2.To resolve this error, update the version of z/OS Connect Designer. If upgrading the z/OS Connect Designer version is not possible, revert the changes by using SCM and then refresh the browser tab to reload the updated API files. This enables you to use a corresponding version of z/OS Connect Designer to continue with development.
After building an API project into a WAR file and deploying that WAR file to a z/OS Connect Server, if the API contains mapping file versions that are not supported by the z/OS Connect Server, the following message BAQR1717E is written to messages.log.
To resolve this error, update the version of the z/OS Connect Server or revert the changes by using SCM and then refresh the browser tab to reload the updated API files for using a corresponding version of the z/OS Connect Designer for development