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 2.0 and Z Open Editor 2.0.2 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 v2.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 via 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 via 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.

Installing Zowe CLI

The prerequisites for installing Zowe CLI are as follows:

Client: Install Node.jsopen in new window version 14, 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

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.

Installing IBM RSE API Plug-in for Zowe CLI

Prerequisites

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

Installing 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.1.1 or 3.2, which is the prerequisite of the RSE API host component.
The RSE API host component, 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 about installing and configuring 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.

Installing the IBM RSE API Plug-in for Zowe CLI

After installing and configuring 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 to install locally, or do an online installation from the public repository at npmjs.com, which is the repository from which you installed Zowe CLI itself.

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. You will be prompted 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 will find various files in the archive including the Z Open Editor archive as well as a file named ibm-rse-api-for-zowe-cli-v.r.m.tgz.
Optionally, follow the instructions in the included README.txt file to verify the code signature to ensure the file was signed against a trusted IBM certificate.
Install the RSE CLI plug-in by entering the following command in the terminal:
```
zowe plugins install path/to/download/ibm-rse-api-for-zowe-cli-v.r.m.tgz
```
1
where path/to/download/ibm-rse-api-for-zowe-cli-v.r.m.tgz should be defined with your own file path.

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

Validating 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.

Getting help

After installing 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.

Updating 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.

Moving 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 will pull from npmjs.com.

Setting log levels for IBM RSE CLI plug-in

Setting up log levels for the RSE CLI plug-in follows 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

Managing credentials securely

Storing 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.

Managing 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 will update ~/.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 via command line operations as well as operations done within IBM Z Open Editor and Zowe Explorer's z/OS integrations. Learn more about obtaining JSON Web Tokens (JWT) from the RSE API host component with the RSE CLI plug-in or via Zowe Explorer.

Example team configuration file with RSE profiles using API Mediation Layer for authentication:

{
    "$schema": "./zowe.schema.json",
    "profiles": {
        "rse": {
            "type": "rse",
            "properties": {
                "port": 7554,                 #API ML Port
                "basePath": ibmrse/api/v1     #API ML base path to registered RSE API
            }
        },
        "base": {
            "type": "base",
            "properties": {
                "host": "host.com",
                "rejectUnauthorized": true
            },
            "secure": [
              "tokenValue"
            ]
        }
    },
    "defaults": {
        "rse": "rse",
        "base": "base"
    },
    "autoStore": true
}

Known Issues

If any issues or concerns arise during installation or while working 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

# Installing Zowe CLI

# Installing IBM RSE API Plug-in for Zowe CLI

# Prerequisites

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

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

# Option 1: Download install package from IBM

# Option 2: Install from npmjs.com

# Validating installation

# Getting help

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

# Update previous npmjs.com install

# Update previous .tgz install

# Moving from .tgz install to npmjs.com install

# Setting log levels for IBM RSE CLI plug-in

# Authentication using Zowe

# Managing credentials securely

# Managing credentials unsecured

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

# Known Issues