Mainframe Storage

 View Only

How to use IBM Copy Services Manager Rest API on System Z

By Thomas Luther posted Mon February 21, 2022 12:31 PM


Storage automation on System Z for cross platform environments

Experienced System Z programmers and storage administrators are familiar with batch jobs, JCL and other program languages such as REXX for enhanced scripting and automation of storage solutions. Traditionally however, they might not be familiar with OMVS shell scripting or OMVS applications providing native Command Line Interfaces that may have to be integrated into the System Z automation capabilities. Enhanced automated mainframe storage management might be desired for fast disaster recovery or cyber resiliency protection with automated Cyber Vaults, which perform regular recovery of Safeguarded Backups for data validation in physical or air gap Cyber Resiliency solutions.

Integration of System Z with distributed platform automation

In order to simplify integration of System Z with distributed platform automation interfaces such as Ansible, which is usually build on Python modules, z/OS provides various libraries and utilities: Those utilities enable complex, customized cross platform automation capabilities on System Z, especially for administrators that have deep distributed platform / Linux skills.

Native HTTP and JSON services on System Z

If you just need simplified integration of HTTP Rest API interfaces and parsing of JSON constructs into the program language of choice on your IBM Z platform for customized automation, you should have a look to the z/OS TSO Web Enablement Toolkit capabilities, which is included in z/OS 2.2 and later. It provides HTTP and JSON services that are callable through various program languages. The IBM Open Source examples on Github for the z/OS Web Enablement Toolkit give you an idea how you can integrate those existing services into your program language of choice and your batch automation if required.

How to use IBM Copy Services Manager Rest API on System Z

Inspired by those examples, an Open Source Rexx framework was developed to demonstrate the z/OS TSO Web Enablement Toolkit capabilities in a simplified manner for utilizing the IBM Copy Services Manager Rest API interface. The Rexx framework enables IBM Z System Programmers and Storage Administrators to interact with IBM Copy Services Manager without installing the CSM CLI for z/OS in OMVS. It provides functions and procedures to quickly utilize the web enablement toolkit services in Rexx executables or batch jobs. It does not only provide necessary HTTP request handling and JSON response parsing, but also other additional features that greatly simplify its usage for the CSM Rest API.

The benefit of using the CSM Rest API instead of the CSM CLI in a System Z environment is that you can avoid runtime overhead that is usually involved when starting the Java Runtime Environment in OMVS, which is required by the CSMCLI for each CLI call you issue from Rexx or the batch environment.
The disadvantage of Rest API is that HTTP service applications usually do not provide an encrypted credentials vault for server authentication. The z/OS Rexx framework for CSM Rest API therefore has a built in server credential management capability to avoid that human readable credentials (username/password or token) have to be specified for CSM Rest API requests via the framework. The encrypted credentials file has to be setup just once, and the framework will use them to automatically request an actual token from the CSM server for the Rest API requests. The last valid token will also be saved in the credentials file, so it can be directly reused for subsequent requests while not expired.
The framework also has built in CSM_ functions to demonstrate how CSM Rest API JSON responses can be parsed to obtain desired information from the server response. Those CSM_ functions of the framework can be used directly to query standard information from the CSM server and display them in a table with customizable formatting options. Beside those standard CSM_ functions, individual Rest API requests are supported via framework execution parameters.

The z/OS Rexx framework for CSM Rest API and more detailed documentation is available in the IBM Open Source Github repository CSM-Rexx-Collection.

Simplify CSMCLI integration and automation on System Z

If you are looking for a simplified integration of the IBM Copy Services Manager CLI running in OMVS for your TSO / Rexx and batch environment, you may also have a look to the Rexx-CSMCLI-Wrapper program in the CSM-Rexx-Collection Github repository.
The Rexx is a wrapper for the CSMCLI executable program. Its primary goal is to provide a reliable program return code for the issued CSMCLI command, in order to simplify automation integration and easier validation whether a CSMCLI command was completed successfully, or has resulted in any type of CLI error or any Warning/Error message code returned from the CSM server.