Version 2.0.0 (April 2022)
Version 2.0.0 (April 2022)
Welcome to the Version 2.0.0 release of Zowe!
Version 2.0 introduced breaking changes and a number of new features.
- If you are upgrading from V1 to V2, review the Breaking changes first.
- See New features and enhancements for a full list of changes to the functionality.
- See Bug fixes for a list of V1 issues addressed in this release.
- See Conformance and release compatibility for V2 Conformance Criteria updates and compatibility with v1.
Download v2.0.0 build: Want to try new features as soon as possible? You can download the V2.0.0 build from Zowe.org.
v2 office hours videos: Zowe held a series of v2 LTS office hours for extenders and consumers to introduce all the V2 changes. Watch the videos to learn more about the new features.
Release blog: Read this blog Welcome Zowe version 2 LTS written by Joe Winchester for a deeper dive of the major enhancements and changes for this release.
#
Breaking changes#
Zowe installation- You must pass
-ppx
when you unpax the Zowe convenience build to preserve extended file attributes. - All utility scripts, like
zowe-install.sh
,zowe-install-xmem.sh
,zowe-install-proc.sh
,validate-directory-is-accessible.sh
, are removed and migrated to the newzwe
server command format. - If you rely on some of the scripts, find the alternative new
zwe
command or shell library functions. ZWESVSTC
is removed andZWESLSTC
will replace it to start Zowe.instance.env
is deprecated and replaced byzowe.yml
.- In V2, you use the
P
command to terminate Zowe instead of theC
cancel command. - Zowe now allows fine-grained customization of log, workspace, and configuration directories. By default, these directories remain grouped under an
instance
directory (same as Zowe v1). - Environment variables are reorganized to better describe itself. All
zowe.yaml
configuration entries will be automatically converted to environment variables for easy consumption. Check with the community what the new alternative variable names are. - During Zowe configuration, redundant
ip
fields will be removed or consolidated in favor ofhostname
ordomains
. - Component or extension manifest is mandatory. You must use the
zwe components install
command to install the extension.
#
API Mediation Layer- Removed the support for the old path pattern (#1770). This includes the changes to the endpoints used in ZAAS client. If your application uses ZAAS client, please verify whether the configuration properties use the new path pattern (
/gateway/api/v1
instead of/api/v1/gateway
). - Removed the support for different authentication schemas for different instances of service (#1051).
#
Zowe Application FrameworkSome configuration, such as port and IP values, are different by default in V2 but can be reconfigured to old values. However, some application framework extensions may not work in V2 without enhancements.
zLUX App Manager
Due to new library versions, native apps such as Angular and React apps written for Zowe v1 may not work in Zowe v2. Rebuilding the apps with the same versions and the latest webpack build scripts is recommended.
zLUX Server Framework
- The list of properties sent back from the /server/environment has changed to reflect the different environment values present in Zowe v2
- Adjusted the server to respect ZSS's new cookie format in which the port or HA instance ID is a suffix of the ZSS cookie. This means that the server may not work properly when paired with a v1 ZSS and works best with v2 ZSS.
zLUX Editor
The app now uses angular 12, making it compatible with Zowe v2 desktop and incompatible with v1 desktop.
Basic VT Terminal Emulator
Upgrade to Angular 12, Typescript 4, and Corejs 3 to match Desktop libraries in Zowe v2. This app may no longer work in the Zowe v1 Desktop, and v2 should be used instead.
Basic TN3270 Display Emulator
Upgrade to Angular 12, Typescript 4, and Corejs 3 to match Desktop libraries in Zowe v2. This app may no longer work in the Zowe v1 Desktop, and v2 should be used instead.
Sample angular app
The app now uses angular 12, making it compatible with Zowe v2 desktop and incompatible with v1 desktop.
#
Zowe CLIBreaking changes for Zowe CLI end users:
zowe config
no longer manages app settings (Imperative and CLI)fail-on-error
default changed to true forzowe plugins validate
(Imperative and CLI)- Default Imperative and CLI log level changed from DEBUG to WARN (Imperative and CLI), which potentially changes troubleshooting steps for providing information to support.
Breaking changes that could prevent a V1 plug-in or SDK from working in V2
- CLI package should be removed as a plug-in peer dep (Imperative)
AbstractRestClient.mDecode
defaults to true so any plug-in with custom RestClient implementation that adds gzip decompression may break- The return value for
PluginManagementFacility.requirePluginModuleCallback
changed. Application and plug-in developers requiring a module from a plug-in's relative path using therequirePluginModuleCallback
function no longer need to provide the plug-in name in a separate variablethis.pluginNmForUseInCallback = pluginName
before binding the classthis.requirePluginModuleCallback.bind(this)
. Instead they can callthis.requirePluginModuleCallback(pluginName)
.- Previously in V1:
this.pluginNmForUseInCallback = pluginNameConfigurationLoader.load(null,pkgJsonData,this.requirePluginModuleCallback.bind(this))
- In V2:
pluginConfig = ConfigurationLoader.load(null,pkgJsonData,this.requirePluginModuleCallback(pluginName))
- Previously in V1:
Breaking changes for Zowe CLI and Imperative plug-in developers
These changes only impact early adopters of @next as these are breaking changes made during the technical preview validation phase. Thanks to the community for the feedback.
tokenType
andtokenValue
were combined intoauthToken
, which later was reverted (Imperative and CLI)- Options in
zowe config
group are renamed:--user
is renamed to--user-config
, and--global
to--global-config
. Zowe.schema.json
format changed a few times (version 2, version 3):ConfigSchemas.loadProfileSchemas
is changed toConfigSchemas.loadSchema
Config.set
no longer coerces string values to other types unlessparseString = true
which might impact the SDK instead of CLI plug-ins.
#
New features and enhancements#
Zowe installation- Introduced a new server command
zwe
to balance between simplification and flexibility on installation and configuration.- Almost all Zowe utility scripts in V1 are consolidated into new
zwe
server command. This new command defines consistent help messages, logging options, and so on. See the ZWE Command Reference for more information. - Provides shell function library to help extensions to achieve common tasks. For example, execute TSO command, operator command, submit job and check job completion, and so on.
- Keep away from commands/functions marked as experimental and internal.
- Almost all Zowe utility scripts in V1 are consolidated into new
- Installation / Configuration changes
- During installation, no new runtime directory will be created.
- A
zowe.yaml
file can be used to centralize all configuration options. This configuration is compatible with all Zowe use cases (including high availability and containerization). - For almost all Zowe configuration steps, an automation option
zwe init
command is provided. You can still choose to run all steps one by one. - Provides the
--security-dry-run
mode that allows you to generate security commands and pass along to your system admin. - You can run all steps from USS now.
- A Zowe component or extension can use
manifest.yaml
to define how it interacts with Zowe and other components.- The component or extension must define a
manifest.yaml
ormanifest.json
file to describe itself. The manifest allows you to define how to register on Zowe API ML Discovery, how to register under Zowe Desktop, and whether it’s Java extension library for API ML, and so on. - Components can define their own
configs
inmanifest.yaml
which shows you how to customize this component and provides default values if they are not defined. This option is compatible with Zowe running in high availability mode.
- The component or extension must define a
- Introduced new data sets to better organize the contents.
- Added
SZWEEXEC
to contain few utility tools. - You can customize your own PARMLIB, APF Authorized LOADLIB and APF-authorized ZIS plug-ins library.
CUST.JCLIB
is a data set where Zowe will store temporary JCLs.
- Added
#
Zowe API Mediation Layer- There is now the option to change your password via the Catalog UI (#2035) (139a231), closes #2035
- Discovery service can be configured to modify the service ID at registration time (#2229) (63f6fde), closes #2229
- There is now the option to specify base packages for the extensions loader(#2081) (9a4be5a), closes #2081
- There is a new design of the logout panel in the Catalog dashboard (#2102) (1382f24), closes #2102
- Add missing tooltips to all onboarding options (#2194) (5446fd5), closes #2194
- Migrate API Catalog to the Material UI library (2c595d5, 0da7f15, 95da488, c60371d, 537fa34, 81ab2ed), closes #1169
- Made various improvements to the onboarding wizard (#1772) (20dd70b), closes #1772
#
Zowe Application FrameworkzLUX App Manager
- New desktop library versions are Angular 6->12, Corejs 2->3, Typescript 2->4, and so on. For more information, visit https://www.zowe.org/vnext.
- The web-browser and admin-desktop-notification apps now contains a manifest file so that it can be installed with zwe components install.
zLUX App Server
- Renamed
ZLUX_
environment variables toZWED_
for consistency. Backwards compatible with old environment variables. - Added support for new
logDirectory
variable specification inzowe.yaml
- Added support for reading from
zowe.yaml
instead ofserver.json
- Renamed
zLUX Server Framework
- Added support for reading
zowe.yaml
directly, as opposed toserver.json
. - The server can now support checks on the existence and version of APIML if a plug-in states a dependency on APIML in the "requirements.components" section of its plug-in definition.
- The list of parameters for server configuration is now documented in json-schema for validation, you can find this in the zlux repository
- Added support for reading
ZSS Package
New configuration option that allows to run 64-bit ZSS
zLUX Editor
Cookie name now has a suffix which includes the port or if in an HA instance, the HA ID.
Basic VT Terminal Emulator
The app now contains a manifest file so that it can be installed with zwe components install
Sample angular app
The app now contains a manifest file so that it can be installed with zwe components install
USS Explorer
USS-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe environment, this will result in less processes but does break links about getting to the explorer via APIML routes. The explorer is now available via the app-server's APIML route.
JES Explorer
JES-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe environment, this will result in less processes but does break links about getting to the explorer via APIML routes. The explorer is now available via the app-server's APIML route.
MVS Explorer
MVS-explorer no longer uses explorer-ui-server, but now depends on app-server. In a standard Zowe environment, this will result in less processes but does break links about getting to the explorer via APIML routes. The explorer is now available via the app-server's APIML route.
#
Zowe CLIZowe CLI contains the following enhancements and changes:
Team Configuration:
Team configuration significantly improves the configuration/onboarding experience and provides the ability to easily share configuration information with others in an organization.
Automatic Team Configuration:
Automatic team configuration leverages the Zowe API Mediation Layer to automatically configure connections for conformant API ML services that also have a CLI plug-in.
Daemon Mode:
Daemon Mode significantly improves the performance of Zowe CLI by not requiring separate node processes to be spawned for every command.
Secure by Default:
Secure by default provides a secure out-of-the-box experience by including the secure credential store feature, previously offered as a plug-in in V1, as part of the core Zowe CLI package.
Migrating to Zowe V2 Team Configuration:
After installing
@zowe/cli@zowe-v2-lts
and all desired plug-ins@zowe-v2-lts
, you can easily migrate to Zowe V2 team configuration by issuing the following command:zowe config convert-profiles
Note: For more information, see Using Profiles.
#
Zowe CLI Plug-insZowe maintained CLI plug-ins are Zowe V2 LTS conformant. As such, they integrate with Team configuration, daemon mode, and the team configuration migration utility. For information about enhancements and bug fixes, see the changelogs for the following plug-ins:
- IBM CICS Plug-in for Zowe CLI
- IBM Db2 Database Plug-in for Zowe CLI
- IBM z/OS FTP Plug-in for Zowe CLI
- IBM IMS Plug-in for Zowe CLI
- IBM MQ Plug-in for Zowe CLI
#
Imperative CLI FrameworkImperative is the infrastructure on which various Zowe technologies are built. For information about enhancements and bug fixes, see the Imperative CLI Framework changelog.
#
Nodejs SDKThe Nodejs SDK packages were updated to make use of key Zowe V2 features, including Team Configuration. For information about enhancements and bug fixes, see the changelogs for the following packages:
- Core Package
- Provisioning Package
- z/OS Console Package
- z/OS Files Package
- z/OS Jobs Package
- z/OS Logs Package
- z/OS Management Facility Package
- z/OS TSO Package
- z/OS USS Package
- z/OS Workflows Package
#
Zowe ExplorerZowe Explorer makes use of Team Configuration and is secure by default. For information about enhancements and bug fixes, see the following changelogs:
#
Bug fixes#
Zowe API Mediation Layer- Caching service logging (#2222) (5ff64d9), closes #2222
- Add x509 Authentication information to the API Documentation of the API Gateway (#2142) (072ad23), closes #2142
- Authorization provider set empty as default (#2107) (aa77926), closes #2107
- Update URL of the API Catalog to work with the V2 version of the Zowe Desktop (6f4257a), closes #2022
#
Zowe Application FrameworkzLUX Server Framework
When paired with the Zowe server infrastructure, the app-server will now automatically register and de-register plug-ins at startup depending on each plug-in's component enabled status.
ZSS Package
- Do not use "tee" when log destination is /dev/null
- Cookie name now has a suffix which includes the port or if in an HA instance, the HA ID.
#
Conformance and release compatibility#
Backward compatibilityZowe v1 conformant extensions/plug-ins are not guaranteed to be compatible with Zowe v2 and therefore may not be operable. In general, plug-ins/extensions which leverage v2 APIs that have known breaking changes are at high risk of incompatibility and unpredictable results.
Recommendation: All v1 extenders test with Zowe v2, identify any issues, and disclose results to consumers to clearly indicate backward compatibility status in the extension documentation. If unable to test, clearly document as such.
#
Forward compatibilityZowe v2 conformant (planning to earn conformance) extensions/plug-ins are not guaranteed to be compatible with Zowe v1 LTS. In general, plug-ins/extensions with no known dependency on any newly introduced Zowe v2 functions are at minimum risk.
Recommendation: All v2 extenders test with Zowe v1 LTS, identify any issues, and disclose results to consumers to clearly indicate forward compatibility status in the extension documentation. If unable to test, clearly document as such.
#
Conformance compatibilityZowe v1 conformant extensions/plug-ins are likely to require changes to meet Zowe v2 conformance criteria. All extensions (regardless of v1 conformance status) must apply for v2 conformance and satisfy all required v2 testing criteria. You can find the V2 Conformance Criteria here.
Recommendation: All extenders interested in earning v2 conformance review the v2 conformance criteria, determine if technical changes are necessary, make appropriate modifications and prepare to apply for v2 conformance.
Need help? For assistance with reviewing or completing the Zowe Conformance Zowe v2 application, reach out to members of the Zowe Onboarding Squad on Slack at https://slack.openmainframeproject.org in the #zowe-onboarding
channel.