To use Grace for orchestrating jobs on z/OS, you need a way for Grace to communicate with your mainframe. This is primarily handled through Zowe, an open-source framework for z/OS. Grace specifically leverages Zowe CLI profiles to connect to z/OSMF (for submitting jobs, managing datasets, etc.) and potentially other z/OS services.

This guide will walk you through:

1. Installing and configuring Zowe CLI.
2. Creating Zowe CLI profiles for z/OSMF.
3. Understanding how Grace uses these profiles in your grace.yml configuration.

Prerequisites

• Access to a z/OS system with z/OSMF configured and running.
• Appropriate credentials (username/password or other authentication methods supported by your z/OSMF instance).
• Node.js and npm installed on your local machine (for Zowe CLI installation).
• Grace CLI installed.

1. Install Zowe CLI

If you haven't already installed Zowe CLI, you can do so via npm. We recommend installing the Zowe v3 LTS (Long-Term Support) version for compatibility.

npm install -g @zowe/cli@zowe-v3-lts

After installation, verify it by running:

zowe --version

You should see output indicating the Zowe CLI version.

After installing Zowe CLI, be sure to install the following plugins. These provide necessary functionality for Grace and Hopper subprocesses to interact with z/OS services.

The following plugins provide support for CICS, DB2, MQ, and z/OS FTP calls, and are assumed to be installed by Grace.

zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts

2. Configure Zowe CLI profiles

Zowe CLI uses profiles to store connection details for your z/OS systems. Grace primarily needs a zosmf profile to interact with z/OS jobs and files.

There are two main ways to configure Zowe profiles:

A. Using zowe config init (recommended for new users)

This interactive command guides you through creating a global Zowe V2 configuration (zowe.config.json) and setting up your first profiles.

1. Initialize global Zowe configuration:

zowe config init --global-config

Follow the prompts. You'll likely want to enable plugin validation.

2. Create a z/OSMF profile:

You can create a zosmf profile that stores your z/OSMF server details (host, port) and credentials.

zowe profiles create zosmf-profile [your-profile-name] \
    --host [zosmf-host] \
    --port [zosmf-port] \
    -u [username] \
    -p [password] \
    --ru false

Replace your-profile-name, zosmf-host, zosmf-port, username, and password with your actual values.

--ru false (reject unauthorized false) might be needed if your z/OSMF uses a self-signed SSL certificate. Use with caution and consult your security administrator.

B. Manually editing configuration files

You may want to directly edit the Zowe configuration files:

• Global team config: Typically at ~/.zowe/zowe.config.json
• User-specific config: ~/.zowe/zowe.config.user.json can override or extend the team config

A minimal zosmf profile entry in zowe.config.json might look like this:

{
  "$schema": "./zowe.schema.json",
  "profiles": {
    "myzos": {
      // ^ This is your profile name
      "type": "zosmf",
      "properties": {
        "host": "mymainframe.example.com",
        "port": 10443
      },
      "secure": [
        // Fields to be stored securely (e.g., in OS credential manager)
        "user",
        "password"
      ]
    }
    // Potentially other profiles like "tso", "base"
  },
  "defaults": {
    "zosmf": "myzos", // Sets 'myzos' as the default zosmf profile
    "tso": "myzos" // Example if 'myzos' also serves for TSO
  },
  "autoStore": true // Automatically store secure properties
}

You would then need to set the secure credentials:

zowe config set "profiles.myzos.properties.user" "[your_username]" --secure
zowe config set "profiles.myzos.properties.password" "[your_password]" --secure --user-config

Test your Zowe profile

After creating a profile, test its connection to z/OSMF:

zowe zosmf check status --zosmf-profile [your_profile_name]

Or, if you set it as the default zosmf profile:

zowe zosmf check status

You should receive a success message indicating connectivity to your z/OSMF instance.

3. Grace configuration (grace.yml)

Once your Zowe CLI profile is set up and working, you can tell Grace which profile to use for your workflow.

config:
  profile: myzos # This must match the Zowe CLI profile name you configured
  # ... other Grace configurations ...
 
datasets:
  jcl: MYUSER.GRACE.JCL
  src: MYUSER.GRACE.SRC
  loadlib: MYUSER.PROJ.LOADLIB
 
jobs:
  # ... job definitions ...

config.profile is the key field. Grace will use the Zowe CLI profile specified here for all its interactions with z/OS (submitting jobs, crawling datasets, uploading files, etc).

When Grace runs, it invokes Zowe APIs in the background, and Zowe uses the connection details stored in the named profile.

Important considerations:

• Security: Be mindful of how you store credentials for your Zowe profiles. Using the Zowe secure credential store is recommended over plain text passwords in configuration files.

• Profile scope: You can have multiple Zowe profiles for different LPARs, different user IDs, or different purposes. Choose the appropriate profile for each Grace workflow.

• z/OSMF dependencies: Grace's core z/OS job and dataset operations rely on z/OSMF being active and accessible through the configured Zowe profile.

• Shell jobs: If you use Grace's shell job type to execute Zowe commands directly (e.g., zowe cics get region), those commands will also use the Zowe CLI's active/default profiles or can be targeted with --profile-name options within your shell script.

With Zowe CLI and your Grace config.profile correctly set up, you're ready to start orchestrating mainframe workflows with Grace!

Next steps: