Packaging z/OS extensions

You can extend Zowe in multiple ways. You may extend Zowe with microservices, which may start a new service within Zowe. You can also create Zowe App Framework plug-ins to provide users with a UI.

Before you start, review the following terms:

• component

  Component refers to the most generic way to describe a program which can work within Zowe. It can be a microservice, a Zowe App Framework plug-in, or even just a shared program to be used by other Zowe components. This is also the generic word when referring to both Zowe core components and extensions. In most of the cases described in this topic, this terminology does not include programs running on the client side, like Zowe CLI plug-in or Zowe Explorer (VSCode extension).

• extension

  Extension is similar to component but excludes Zowe core components. It is recommended that you install all Zowe extensions into a shared extension directory.

Zowe server component package format

You can package Zowe components (extensions) into various formats. You can package them as a stand-alone PAX, ZIP, or TAR file. You can also bundle and ship your Zowe extension(s) within another product.

A typical component package consists of the following files and directories:

+-- manifest.yaml
|-- apiml-static-registration.yaml.template
|-- schema.json
|-- bin/
    |-- configure.sh
    |-- component-1.0.0-boot.jar
    |-- start.sh
    |-- validate.sh

• manifest.yaml

  Refers to the Zowe component manifest file. You can find detailed definition of manifest in Server Component Manifest File Reference.

  For examples of manifests thoughout Zowe GitHub repositories, see the following links:

  • API Catalog manifest.yaml
  • Sample Node API and API Catalog extension manifest.yaml
  • Sample Zowe App Framework extension manifest.yaml

• schema.json

  An example filename of the json schema file specified by the manifest property schemas.configs as detailed in Server Component Manifest File Reference. The file details the parameters that are valid for the component's configuration within Zowe server configuration files. See documentation on server component schema files for more information.

• apiml-static-registration.yaml.template

  Refers to a supporting file that instructs the Zowe launch script how to register this extension service to the API Mediation Layer Discovery service. In this case, this file is referred in the manifest.yaml apimlServices.static[0].file field. This file is optional depending on the function of the component. You can change and customize the file name in the manifest file.

• bin/(configure|start|validate).sh

  This file contains the Zowe component lifecycle scripts. You may not need these files depending on the function of the component. You can find detailed definition of lifecycle scripts in Zowe component runtime lifecycle.

It is also suggested that you put the following files into the package:

• README.md

  This file is a brief introduction to your extension in Markdown format, including how it should be installed, configured, verified, and so on.

• LICENSE

  This is the full license text file.

If you decide to bundle and ship Zowe extensions within another product, you can put the whole directory structure presented previously into your product package as subdirectories. Take the following structure as an example.

+-- <my-product-root>
    |-- <other-directories-and-files>
    |-- zowe-extension-A
        |-- manifest.yaml
        |-- bin/
            |-- start.sh
    |-- zowe-extension-B
        |-- manifest.yaml
        |-- bin/
            |-- start.sh

Packaging default YAML properties

If you package a YAML file that follows the Zowe YAML file schema, you can have users include them in their configuration list to reduce setup actions. The Zowe STC job "ZWESLSTC" contains instructions on how to add such files to the user's overall configuration list.