How it works: CICS bundle deployment API

The CICS® management client interface (CMCI) supports deploying CICS bundles into a single region through the CICS bundle deployment API. The API is supported by the CMCI JVM server that is configured either in the WUI region of the target region's CICSplex, or in the target region itself if it's a CICS System Management Single Server (SMSS).

Table of contents
Overview How the API works Security model of the API How to make CICS bundle deployment API requests What's next

Overview

The API is used at development time for Java™ developers to check their application changes in a running CICS region within seconds. The API also supports the CICS-provided Maven and Gradle plug-ins that can be used to integrate CICS bundle build and deployment into a developer's toolchain. For more information about CICS support for Maven and Gradle, see Java support in CICS.

Note: CICS supports bundle installation from the CICS system definition data set (CSD) to a single region.

The CICS bundle deployment API enables Java developers to deploy bundles whilst the system programmer retains control. This is achieved by removing the need for developers to write bundles to zFS through FTP, or to install bundles from CSD. These actions are taken by the API, by using a functional ID or another user ID with sufficient access.

The diagram shows a typical scenario where multiple application developers push bundles to the API, which is configured in the WUI region of a CICSplex. For an SMSS environment, the API is configured in the CMCI JVM server of the target region.

Diagram showing multiple developers pushing bundles to the API — Figure 1. Multiple developers pushing bundles to API

This REST API receives a CICS bundle that contains the developer's application as a zip file over HTTP. The bundle will be unzipped, installed into, and enabled in the appropriate CICS region automatically. If a CICS bundle with the same name already exists, it will be disabled and discarded before the new bundle is installed.

Typically, the system programmer provides the Java developer with necessary parameters, for example, the CICSplex, CICS Region, CSD Group, and name of the BUNDLE definition. The system programmer then creates the BUNDLE definition, configured with the correct bundle directory attribute for the application that is being developed.

How the API works

As described before, the API manages the bundle lifecycle and interacts with zFS on behalf of the developer after receiving the bundle. Usually the API is driven by a client such as the CICS-provided cics-bundle-maven-plugin or com.ibm.cics.bundle.

The API is configured with a bundles directory. This is a location on zFS that should be dedicated for the use of the API in managing bundles. Bundles pushed to the API are unzipped into the bundles directory and accessed by the CICS target region. This is transparent to developers and managed by the system programmer. Developers using this API do not need to interact with bundles on zFS.

For each application a developer is working on, the system programmer creates a BUNDLE definition in the CSD. The BUNDLE definition's BUNDLEDIR attribute must be configured with a path to the right version of the application uploaded to the bundles directory, for example, /u/path/to/bundles/dir/ApplicationName_1.0.0. The system programmer provides the BUNDLE definition name and CSD group for the developer to drive the API. Developers using this API do not need to install, disable, or discard the CICS BUNDLE resource.

The diagram shows a bundle's lifecycle from the time when it's published by an application developer until it gets installed into a CICS region. It's handled by the API automatically without users' intervention.

Diagram showing a bundle's lifecycle in the API — Figure 2. Bundle's lifecycle in the API

: 1 The application developer publishes the application bundle through the CICS bundle deployment API.
Validate: 2 The CMCI JVM server finds the BUNDLE definition in the target region's CSD and checks that the BUNDLE definition's bundle directory (BUNDLEDIR) attribute value is within the API's configured bundles directory.
Uninstall: 3 The CMCI JVM server checks whether any previously installed bundle with the same name as the BUNDLE definition specified exists in the target region. Such a bundle is disabled and discarded as required.; 4 The CMCI JVM server deletes any previous bundle with the same name and version from the bundles directory on zFS. Then, it unpacks the published bundle to the bundles directory.
Install: 5 The CMCI JVM server initiates a CSD install of the BUNDLE definition.; 6 The target region reads the bundle from zFS and installs it.

Security model of the API

A functional ID is introduced to ensure controlled access. As a result, application developers are able to deploy bundles through specific access to the CICS bundle deployment API, and without general access to manipulate bundles. Different users IDs are involved in the API's workflow as follows:

The application developer is authenticated as normal, to make sure their user ID has access to the API.
The task switches from the application developer's user ID to a configured deployment functional ID.
The deployment functional ID writes the bundle to zFS and initiates a CSD install of the bundle to the target region.
The region user ID of the target region reads the bundle from zFS during installation.

The security mechanism of the API requires additional configurations for the API to work:

The system programmer must configure SAF correctly to enable bundle deployment using the API.
The API works only in regions configured as SEC=YES.

For instructions, see Configuring the CMCI JVM server for the CICS bundle deployment API.

How to make CICS bundle deployment API requests

CICS provides a Maven and a Gradle plug-in that uses this API to publish bundles to CICS. Java developers can use it for bundle deployment at development time. For instructions, see cics-bundle-maven. Alternatively, if you want to write your own tooling, the API can be invoked by using any standard REST client.

The format of API requests is based on HTTP/1.1. The API uses the POST request only, and accepts multipart form data. A Content-Type: multipart/form-data header must be sent. String parameters and the zipped bundle file are accepted as form data parts in the payload.

The API returns an HTTP response code and a JSON description of the outcome of the request. A response code of 4xx indicates that a user has incorrectly addressed the API. A response code of 5xx indicates that the system is set up incorrectly.

The API endpoint is served alongside your standard CMCI interface. For example, if your CMCI interface is available at mycicshost.com on port 4444, your API endpoint URL would be https://mycicshost.com:4444/managedcicsbundles.

Call the API with these parameters:

cicsplex: Required only for a CICSPlex® SM environment. The name of the CICSplex that the target region belongs to.
region: Required only for a CICSPlex SM environment. The name of the region that the bundle should be installed into.
csdgroup: The name of the CSD group where the source BUNDLE definition exists.
bunddef: The name of the BUNDLE definition.
bundle: The zip file that contains the bundle contents, as content-type application/zip. The META-INF directory should be in the root of the zip file.

For example, to call the API from your local workstation using the command-line tool cURL, your command line might look like this:

curl -i -X POST -u MYUSER -F cicsplex=MYPLEX -F region=MYREGION -F csdgroup=CSDGRP -F bunddef=MYBUND -F bundle=@c:/path/to/bundle_0.0.1.zip https://mycicshost.com:4444/managedcicsbundles

The CICS bundle deployment API unzips the content of the uploaded zip file without performing any codepage conversion. Each file in the bundle must be encoded in the correct codepage prior to being zipped.

What's next

Configure your CMCI JVM server to enable the API. See Configuring the CMCI JVM server for the CICS bundle deployment API