Migrating Zowe CLI Plug-ins for v2 Conformance

{Core} The Open Mainframe Project’s Zowe v2 is planned to be released at the end of February and Zowe CLI plug-in developers are beginning to prepare their software for v2 conformance. As Version 2 will be the next Long-Term Support (LTS) release (see Zowe v1 LTS announcement here), updating conformant plug-ins demonstrates an ongoing commitment to and support for the Zowe framework. Any existing plug-in that loads Zowe v1 profiles likely needs to be migrated. If you want to join the flock in migrating to Version 2, this blog can help you make the appropriate adjustments to achieve v2 conformance.

Team Config

In order for your plug-in to be compatible with team config, a few changes may be required. If you’re not familiar with team config, it’s the new recommended way to store profiles in Zowe v2. Profiles can now be stored globally or for individual projects in zowe.config.json files (see Mike’s blog about it).

In this article we use the term “v1 profile” to mean a profile that was created using the zowe profiles create command in Zowe v1 LTS and is stored in the “~/.zowe/profiles” directory. Zowe v2 is compatible with v1 profiles, but deprecates them in favor of “v2 profiles” which are stored in a config JSON file and managed using the zowe config command group.

v1 profiles are deprecated

To load profile properties, you no longer rely on the profiles.get method provided by the IHandlerParameters interface. This method supports loading only v1 profiles and is deprecated in Zowe v2. The following example shows how a command handler for checking z/OSMF status might have been implemented for Zowe v1:

export default class MyHandler implements ICommandHandler {
    public async process(params: IHandlerParameters): Promise<void> {
        const profile = params.profiles.get("zosmf");
        const session = ZosmfSession.createBasicZosmfSession(profile);
        const response = await CheckStatus.getZosmfInfo(session);
        // Remaining handler code omitted for brevity
    }
}

The following methods no longer function in Zowe v2:

• The params.profiles.get("zosmf") call fails when no v1 profiles exist. In some cases, your plug-in might supply an additional false parameter (for example params.profiles.get("zosmf", false)) which indicates the profile is optional, so it will not throw an error if the v1 profile doesn’t exist. Regardless, params.profiles.get cannot load properties from v2 profiles.
• The ZosmfSession.createBasicZosmfSession method was removed in Zowe v2 and replaced with ZosmfSession.createSessCfgFromArgs . This change is specific to z/OSMF and likely does not apply to your plug-in.

v2 profiles are easy to support

In Zowe v2, the new way to populate a session is by loading profile properties from the params.arguments object, as shown in the following example:

export default class MyHandler implements ICommandHandler {
    public async process(params: IHandlerParameters): Promise<void> {
        const sessCfg: ISession = {};
        const sessCfgWithCreds = await ConnectionPropsForSessCfg.addPropsOrPrompt(sessCfg, params.arguments, { doPrompting: true, parms: params });
        const session = new Session(sessCfgWithCreds);
        const response = await CheckStatus.getZosmfInfo(session);
        // Remaining handler code does not need to change
    }
}

The ConnectionPropsForSessCfg.addPropsOrPrompt method processes CLI arguments and stores them in an ISession object. Additionally, it prompts for properties that are missing like host, port, user, and password, and automatically stores them in the zowe.config.json file for future use. This method is also implemented in v1 LTS of Zowe CLI, so making this change to your plug-in should not break compatibility with Zowe v1.

To take advantage of the auto-prompt and auto-store features, remove the required: true property from the option definitions for host, port, user, and password for your plug-in. As long as properties like host are required, running your plug-in’s commands without specifying --host as a CLI argument or defining it in a profile will result in the following error:

Syntax Error:
Missing Required Option:
--host (-H)

Once you rebuild your plug-in with the --host option updated to no longer be required, the auto-prompt behavior will work. For more information about removing the required: true properties from profiles options, see Gene’s blog about token handling.

v2 profiles have customizable templates

If you have not tried Zowe v2 yet, follow the steps on docs.zowe.org to install the Zowe CLI @next version. After you install the CLI, you can run the command zowe config init to create a new zowe.config.json file.

You may notice that the “zosmf” and “base” profiles have default values filled in for properties like host and port. But your plug-in’s profile probably has an empty properties object like the following:

    "cics": {
        "type": "cics",
        "properties": {},
        "secure": []
    }

To populate your properties object with default values, add the includeInTemplate: true property to your plug-in’s option definitions for those profile properties. For the above example using the CICS plug-in:

    port: {
        type: "number",
        optionDefinition: { ... },
        includeInTemplate: true  // Add this line
    }

Running zowe config init again now adds the port property to your plug-in’s profile in the zowe.config.json template.

If your plug-in connects to a single sign-on API ML compliant REST service, see Fernando’s blog to learn how your plug-in can automatically generate v2 profiles with the zowe config auto-init command.

Performance Improvements

1. Test that your plug-in works in daemon mode, which is available as part of the Zowe v2 technical preview. The daemon server caches Zowe CLI as a background process in memory, which can make commands run much faster if the CLI is slow to load on your system. For information about how to install CLI in daemon mode, see docs.zowe.org. After installing it, you can run the daemon executable in place of the regular zowe command:

$ zowe --version
Starting a background process to increase performance ...
7.0.0-next.202112081943

2. Reduce the number of imports in your Imperative configuration file to be as few and specific as possible. The location of your Imperative configuration file is defined in package.json under the imperative.configurationModule property, and is often lib/imperative.js.

You can test the load time of your plug-in by running the following command in the root directory of your plug-in project. The command caches Imperative in memory and evaluates how long it takes to load your plug-in:

node -e "require('@zowe/imperative'); console.time(); require('./lib/imperative.js'); console.timeEnd();"

On a high performance computer, we expect the results of the command to be fairly low; less than 25ms.

An example of making imports more specific is a change that was made in the DB2 plug-in for Zowe CLI. The following change reduced the load time from nearly 200ms to only 2ms, since Node.js no longer has to import the entire directory structure at load time:

- import { Constants } from "./";
+ import { Constants } from "./Constants";

3. Remove the @zowe/cli peer dependency from the package.json for your plug-in, unless your plug-in source code contains import statements that depend on @zowe/cli. In Zowe v2, the requirement to include @zowe/cli as a peer dependency was dropped, due to changes NPM made to how they handle peer dependencies.

Recent versions of NPM (≥7) automatically install missing peer dependencies, unlike older versions which would issue only a warning. If anyone installs your plug-in into their NPM project (independent of zowe plugins install), @zowe/cli is pulled in as an unnecessary dependency when you do not remove it from the peer dependency list.

In this article, we discussed the most common tasks that plug-in developers need to address when migrating to Zowe v2. Review the Zowe v2 conformance criteria published at zowe.org/vnext to help ensure that your plug-in meets all of the criteria. If you have any questions about the criteria, feel free to reach out in the zowe-cli channel on OMP Slack.

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.