Zowe Conformance Program Explained

Published in

Zowe

6 min readOct 15, 2019

Zowe is a highly innovative open source software project targeting the IBM Z Mainframe server platform. Its primary objective is to change the way we interact with the mainframe, making it easier to work with, just like any other platform. The project consists of a multitude of extensible sub-projects that co-create a synergy for users when leveraged together.

The Mainframe is the system of record for most Fortune 1000 companies, housing customer data that can’t be compromised and business processes that must be available at all times. The mainframe platform is behind just about every critical user experience in business today. For this reason, every company shares common concerns about the security of their customer data and the compatibility and performance of the applications that drive their business. The introduction of open source tooling to this most critical platform is a non-starter if it adds to any of these concerns. In order to ensure compatibility, security and an overall unified experience, Zowe provides conformance programs for selected sub-projects with plug-in/add-on architecture. As of October 2019, conformance programs are available for the Zowe API Mediation Layer, Zowe Command Line Interface and Zowe Application Framework.

For engineers who aspire to create conformant extensions to Zowe, they can quickly learn what they need to know by visiting the Zowe Conformance Program home page. They will find guidance, terms and conditions and a participation form for when they are ready to have their extension evaluated for conformance. Once a plug-in/add-on is certified for a particular sub-project as conformant, it will be published on the Zowe Conformance Program landing page and the product information materials can use the Zowe Conformant logo. The certification process itself is facilitated by the Linux Foundation.

Once again, for those of you who might be thinking about building a conformant extension to Zowe, the remainder of this blog post will take you through some of the highlights of the program.

Zowe API ML Conformance

The Zowe API Mediation Layer test evaluation guide states the requirements for REST API services and UIs in order to become Zowe API Mediation Layer conformant. It consists of nine main technical sections which cover a range of topics including:

service ID requirements,
discoverability of the REST API service,
formats of requests, responses and API documentation,
gateway URL conventions,
need for semantic versioning model and
requirements related to WebSockets usage.

The anticipated result is that the end users of the API Mediation Layer can expect key benefits such as a unified configuration and usage experience. For example, the service ID is a textual identifier of a REST API provider. The conformance criteria states that this identifier should be lowercase, and the service creator should use the organization name as a service ID prefix so it is easily recognizable during configuration time. The service creator should also allow for the customization of the service ID by the system administrator.

There are two levels of API Mediation Layer conformance — Minimum and Preferred. In order for the service to achieve the Preferred level of conformance, the service must meet the following criteria:

accept Zowe JWT token in the cookie (basic authentication is required for Minimum conformance)
support dynamic registration (static definition is required for Minimum conformance)

The API Mediation Layer conformance criteria may be updated over time to reflect newly added functionality. For example, there is currently a demand for the API Mediation Layer to support absolute URLs. To enable this, each service would need to provide transformation metadata for the Gateway service. A preview of the anticipated updates to the API ML conformance criteria is available in the docs folder of the API ML GitHub.

In order for the service to become conformant, the requester must consent to undergo re-certification within 60 days of conformance criteria updates.

*Zowe API Mediation Layer 2019 conformance badge*

Zowe CLI Conformance

The Zowe Test Evaluation Guide describes the requirements of a Zowe CLI conformant plug-in. The criteria is broken down into four key categories: infrastructure, installation, naming, and profiles.

The infrastructure category ensures that all Zowe CLI conformant plug-ins make use of the same supported framework and integrate into the broader solution. Within Zowe, the CLI Squad has contributed the Imperative CLI Framework, upon which the core CLI and all conformant plug-ins are built. The framework is intended to enable the rapid development of CLI plug-ins and to promote code reuse so that the community can continuously improve upon the same underlying framework for the benefit of all.

The installation category ensures that the user install and uninstall experience is consistent across all plug-ins. It also ensures that the plug-in management facility of the core CLI can manage all conformant plug-ins effectively.

The naming category ensures that commands introduced by new conformant plug-ins do not conflict with existing commands offered by the core CLI and existing conformant plug-ins.

The profiles category helps to ensure a consistent user experience across all plug-in configurations. In the CLI, profiles allow users to store information so they do not need to provide it every time they run a command. To provide a superior user experience, all conformant plug-ins that introduce unique connection details to a particular service are expected to introduce a profile that allows the user to store such details for repeated use.

Although not required, it is recommended that all profile options are exposed on each command so they can be overridden on the command line. This is valuable if the user wishes to quickly submit a command with a slight modification to an existing profile. This is also required for profile-less command execution, which is particularly useful in a Jenkins pipeline run. Connection details can be stored as Jenkins secrets and do not need to be stored in the form of a profile. Environment variables can also influence command options. For more details on the CLI option order of precedence, check out our docs. To view a pipeline that makes use Jenkins secrets and environment variables to influence commands, check out this sample.

Zowe App Framework Conformance

The Zowe Test Evaluation Guide describes the requirements of a Zowe App Framework conformant application. There are two main categories of Zowe App Framework conformant applications; applications that are run in an IFrame and applications that are built on the Web Desktop framework.

Web UI IFrame criteria applies to an already existing web application that you would like to expose via a Zowe Desktop IFrame. An example of such an application is available here.

Web UI Non-IFrame criteria applies to a “native” web application that runs and uses Web Desktop capabilities. Examples of such applications are sample-angular-app and sample-react-app.

App Server criteria applies to a backend data service that supports these Web UIs.

Additional conformance criteria are related to:

Packaging — defines versioning, directory structure and layout of source code
Web UIs ALL — overall criteria for both Web UI IFrame and Web UI Non-IFrame
UI Design — application should follow UI Design guidelines
Localization and Internationalization (I10n and I18n) — defines what needs to be done for I10n and I18n
Documentation — for example, every HTTP API must be documented in Swagger 2.0
Logging — defines what and where log messages should be written
Storage — specifies where to store user preferences

Additional information about the Zowe App Framework is available in the official documentation.

*Zowe App Framework 2019 conformance badge*

Closing remarks

The Zowe Conformance Program was established to ensure compatibility, security and an overall unified experience for Zowe users. It is intended to enhance the adoption, scalability, and reliability of the IBM Z Mainframe platform.