Setting up integrations to interact with z/OS

You can use IBM Z® Open Editor on your computer without connecting to a z/OS® system and download files manually by using an FTP command or similar method. However, you can augment the capabilities of IBM Z Open Editor and enjoy a seamless integration of z/OS with IBM® Remote System Explorer API (RSE API) or the Zoweopen in new window open source project. The Zowe™ project provides great tools that work perfectly with the IBM Z Open Editor.

Note, that with Zowe Explorer 3.0 and Z Open Editor 5.0.0 some changes were introduced to the way this integration is configured that might require some migration from older versions. See the Getting started with Zowe Explorer v3.0 for an overview.

When using IBM Z Open Editor, you can choose how to interact with z/OS with regard to the following aspects:

Use RSE API or the Zowe default z/OSMF as the host component
Use the command line or graphical interface to interact with z/OS

Next, you can use the following client-side tools based on your decision:

Available host component	To use command line, install...	To use graphical interface, install...
RSE API	Zowe CLI, and IBM RSE API Plug-in for Zowe CLI	Zowe Explorer
z/OSMF	Zowe CLI	Zowe Explorer

Detailed information about these tools is as follows:

IBM RSE API Plug-in for Zowe CLI (RSE CLI plug-in) enables you to interact with z/OS remotely through command line by using RSE API instead of using the Zowe default z/OSMF. See Installing IBM RSE API Plug-in for Zowe CLI to get started. To use RSE API on your client, see Using RSE API in Zowe Explorer and Using RSE CLI plug-in commands.
Zowe CLI enables you to interact with z/OS remotely through command line. After installation, as described in Installing Zowe CLI, you must create a Zowe CLI z/OSMF user profile that stores your personal connection information. To use Zowe CLI with IBM Z Open Editor, see Using Zowe CLI z/OSMF commands.
The Zowe Explorer VS Code extension (Zowe Explorer) provides you with graphical views to explore MVS, z/OS UNIX System Services, and JES remotely. When you install IBM Z Open Editor from the VS Code Marketplace into your VS Code, the latest version of the Zowe Explorer VS Code extension is automatically co-installed. For more information about its capabilities and usage, see Zowe Explorer in the VS Code Marketplaceopen in new window and Zowe Docsopen in new window. To use Zowe Explorer with IBM Z Open Editor, see Using the Zowe Explorer views.

Install Zowe CLI

The prerequisites to install Zowe CLI are as follows:

Client: Install Node.jsopen in new window version 20, or a later version
Host (select one or both):
- Configure z/OSMF if you plan to use Zowe CLI without RSE CLI plug-in
- Install and configure IBM Remote System Explorer API if you plan to use Zowe CLI along with RSE CLI plug-in to extend Zowe CLI. Version 1.1.6 or higher is the suggested RSE Rest API version.

You can install Zowe CLI using one of the methods below:

Follow the Zowe documentation on Installing Zowe CLIopen in new window to install Zowe CLI from the Zowe.orgopen in new window website or the npmjs.comopen in new window npm package registry.
Alternatively, you can get a certified IBM Zowe distribution from IBM Mainframe DEVopen in new window. You can also purchase technical support for Zowe from IBM for this distribution.

Install IBM RSE API Plug-in for Zowe CLI

Prerequisites

Before you install IBM RSE API Plug-in for Zowe CLI on your development machine, you must install Zowe CLI 8.0.0 or later. For more information on how to install Zowe CLI, see Installing Zowe CLI.

Install the requisite IBM RSE API z/OS host component

Confirm with your system administrator that the following host components are installed and configured on the z/OS host system:

The host component of z/OS Explorer 3.3 or 3.4, which is the prerequisite of the RSE API host component.
The RSE API host component version 1.1.6 or higher is suggested, which provides a collection of REST APIs that allow a client to work with various components on the z/OS host system, including MVS data sets, z/OS UNIX files and commands, JES jobs, and more.

For information on how to install and configure the RSE API host component, see RSE API documentationopen in new window.

Note: Even if your system administrator has previously installed RSE on your z/OS, an update is needed to get the capabilities described here.

Install the IBM RSE API Plug-in for Zowe CLI

After you install and configure the prerequisites and the host component, follow these steps to install the RSE CLI plug-in. You can choose to download the plug-in from

IBM as a code-signed archive file for local and even air-gapped installations, that does not require an internet connection to public domains.
a public repository at npmjs.com for a more convenient online installation. This repository is the same from which you might have installed Zowe CLI following instructions from the Zowe docs.

Option 1: Download install package from IBM

Navigate to the Mainframe DEVopen in new window website.
Click More info on the IBM Wazi Developer for Red Hat CodeReady Workspaces tab.
In the Code row, click VSCode.
You are then redirected to the Software License Agreement page. Review the License Agreement and click I Agree. It prompts you to save or open a compressed .zip file in your browser.
Save the compressed .zip file to your workstation.
Extract the compressed .zip file on your workstation. You find various files in the archive, including two different RSE API Plugin for Zowe CLI .tgz files, ibm-rse-api-for-zowe-cli-v.r.m.tgz and ibm-rse-api-for-zowe-cli-airgap-v.r.m.tgz. The ibm-rse-api-for-zowe-cli-airgap-v.r.m.tgz package has all dependencies included in the bundle for environments without network access.
Optionally, follow the instructions in the included README.txt file to verify the code signatures to ensure the files were signed against a trusted IBM certificate.
Install the desired RSE CLI plug-in variant by entering the following command in the terminal:
```
zowe plugins install path/to/download/ibm-rse-api-for-zowe-cli-pkg.tgz
```
1
where path/to/download/ibm-rse-api-for-zowe-cli-pkg.tgz should be defined with your own file path to install the package.

Option 2: Install from npmjs.com

Install the RSE CLI plug-in by entering the following command in the terminal:
```
zowe plugins install @ibm/rse-api-for-zowe-cli
```
1

Validate installation

If the installation was successful, you can see the following message printed in the terminal:

Installed plugin name = '@ibm/ibm-rse-api-for-zowe-cli'

_____ Validation results for plugin '@ibm/ibm-rse-api-for-zowe-cli' _____
This plugin was successfully validated. Enjoy the plugin.

Get help

After you install the RSE CLI plug-in, you can see all the command options of the plug-in by entering the command zowe rse --help into the terminal.

Update the IBM RSE API Plug-in for Zowe CLI

Update previous npmjs.com install

If the previous installation of the RSE CLI plug-in was from npmjs.com, run the following command to update to the latest version available on npmjs.com:

zowe plugins update @ibm/rse-api-for-zowe-cli

Update previous .tgz install

Uninstall the older version of RSE CLI plug-in:
- If the original .tgz file of the older version is still in the original location from the installation, run the following command.
```
zowe plugins uninstall @ibm/rse-api-for-zowe-cli
```
  1
- If the original .tgz file is no longer in the original location from the installation, complete the following procedure:
  1. Use the file explorer to open the .zowe folder in the home directory.
  2. Within the .zowe directory, go to the plugins/installed/node_modules/@ibm directory and delete the rse-api-for-zowe-cli folder.
  3. Navigate to the .zowe/plugins directory, open the plugins.json file in edit mode and remove the @ibm/rse-api-for-zowe-cli section as shown below and save the file.
```
"@ibm/rse-api-for-zowe-cli": {
  "package": "@ibm/rse-api-for-zowe-cli",
  "registry": "installation/location",
  "version": "1.0.0"
}
```
    1
    2
    3
    4
    5
Verify the uninstallation.
Run the command zowe plugins list. The list of plug-ins should no longer contain @ibm/rse-api-for-zowe-cli upon a successful uninstallation.
Delete rse_meta.yaml file from the .zowe/profiles/rse directory.
Install the new version of RSE CLI plug-in.
Refer back to Installing the IBM RSE API Plug-in for Zowe CLI to install the new .tgz download of IBM RSE API Plug-in for Zowe CLI.

Move from .tgz install to npmjs.com install

Follow step 1 - 3 of Update previous .tgz install.
Run command zowe plugins install @ibm/rse-api-for-zowe-cli, which pulls from npmjs.com.

Set log levels for IBM RSE CLI plug-in

To Set up log levels for the RSE CLI plug-in, follow the same method used to set Zowe CLI log levelsopen in new window, and logs are written to the log file location /.zowe/zowe/logs/zowe.log. You can set the log level to adjust the level of detail that is written to the log file.

Important! Setting the log level to TRACE or ALL may result in "sensitive" data being logged.

Environment Variable	Description	Values	Default
`ZOWE_APP_LOG_LEVEL`	Zowe CLI and RSE CLI plug-in logging level	Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)	DEBUG

Authentication using Zowe

Manage credentials securely

Store username and password securely is Zowe CLI's default behavior. Upon installation of Zowe CLI, a file is created in the ~/.zowe/settings directory called imperative.json that holds the value of the Credential Manager to be used. By default this value is @zowe/cli.

Manage credentials unsecured

In some cases or environments the default Credential Manager is not supported. Zowe Explorer provides an option to disable secure credentials. We do not recommend disabling secure credentials unless your environment does not support it. To disable secure credentials set Zowe Explorer VS Code user setting zowe.security.secureCredentialsEnabled to false. Setting secureCredentialsEnabled to false updates ~/.zowe/settings/imperative.json like the example below:

{
  "overrides": {
    "CredentialManager": false
  }
}

Single sign-on support for IBM RSE CLI plug-in

RSE CLI plug-in has single sign-on (SSO) support using JSON Web Tokens (JWT) that are issued by the RSE API host component to the RSE profile. If the RSE API host component is configured and registered with the Zowe API Mediation Layer (API ML)open in new window, the RSE CLI plug-in also supports SSO using a JWT that is issued to a Zowe CLI base profileopen in new window by the API ML. The JWTs can be used for authentication with the RSE API host component through command line operations as well as operations done within IBM Z Open Editor and Zowe Explorer's z/OS integrations. Learn more about how to obtain JSON Web Tokens (JWT) from the RSE API host component with the RSE CLI plug-in or through Zowe Explorer.

Example Zowe configurations

Multi-Factor Authenticatioin (MFA) support

Zowe Profiles used with Zowe CLI, the RSE CLI plug-in, IBM Z Open Editor, and Zowe Explorer support Multi-Factor Authentication (MFA). MFA authentication can work with via 2 different scenarios, the first being the use of the MFA token stored as a password for the session time and the second is using the MFA token as the password during a login to retrieve a JSON Web Token (JWT) for continued authentication.

Zowe zosmf profile types require an API ML connection for MFA support. Zowe rse profile types can use both scenarios, the API ML route if RSE API host components are registered or via direct RSE API connection. The direct connection to RSE API only supports MFA using the MFA token as the password during a login to retrieve a JWT.

More information regarding MFA support for Zowe CLI and API Meditation Layeropen in new window.

Proxy support

RSE CLI plug-in supports proxy servers using environment variables and VS Code proxy settings. If using rse profiles for both CLI and in VS Code setting the environment variables are used in the same manner across both platforms. These environment variables include HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. If using the rse profile in just the VS Code environment, VS Code proxy settings can be used in place of environment variables. More information regarding setting up proxy servers with Zowe in the Zowe Explorer wiki for Working with Proxy Serversopen in new window.

Zowe Explorer requires the http.proxySupport setting to be set to on for other proxy settings to be recognized. VS Code proxy settings recognized by Zowe Explorer include http.noProxy, http.proxy, http.proxyAuthorization, and http.proxyStrictSSL.

Known Issues

If any issues or concerns arise during installation or while you work with the RSE CLI plug-in, refer to the known issues documentation for the RSE CLI plug-in here.

# Setting up integrations to interact with z/OS

# Install Zowe CLI

# Install IBM RSE API Plug-in for Zowe CLI

# Prerequisites

# Install the requisite IBM RSE API z/OS host component

# Install the IBM RSE API Plug-in for Zowe CLI

# Option 1: Download install package from IBM

# Option 2: Install from npmjs.com

# Validate installation

# Get help

# Update the IBM RSE API Plug-in for Zowe CLI

# Update previous npmjs.com install

# Update previous .tgz install

# Move from .tgz install to npmjs.com install

# Set log levels for IBM RSE CLI plug-in

# Authentication using Zowe

# Manage credentials securely

# Manage credentials unsecured

# Single sign-on support for IBM RSE CLI plug-in

# Multi-Factor Authenticatioin (MFA) support

# Proxy support

# Known Issues