Installation And User's Guide Zowe User

User Manual:

Open the PDF directly: View PDF .
Page Count: 102

Download
Open PDF In Browser	View PDF

Open Beta for Zowe

Installation and User's Guide

Contents
About this documentation................................................................................... vii
Who should read this documentation.......................................................................................................vii
How to send your feedback on this documentation................................................................................ vii
Sending a GitHub pull request.............................................................................................................vii
Opening an issue for the documentation............................................................................................ vii

Release notes for Open Beta................................................................................ ix

Version 0.9.1 (October 2018).................................................................................................................... ix
What's new............................................................................................................................................ ix
What's changed...................................................................................................................................... x
Version 0.9.0 (August 2018)...................................................................................................................... xi
What's new............................................................................................................................................ xi
What's changed..................................................................................................................................... xi
What's removed..................................................................................................................................... xi
Known issues......................................................................................................................................... xi

Chapter 1. Zowe overview.....................................................................................1

Zowe Application Framework..................................................................................................................... 1
Explorer server.............................................................................................................................................2
Zowe CLI...................................................................................................................................................... 2
Zowe CLI capabilities.............................................................................................................................2
Zowe CLI Third-Party software agreements.........................................................................................3
API Mediation Layer.................................................................................................................................... 4
Key features............................................................................................................................................4
API Mediation Layer architecture..........................................................................................................4
Components............................................................................................................................................5
Zowe API Mediation Layer Third-Party software agreements............................................................. 6

Chapter 2. Installing Zowe.................................................................................... 9

Installation roadmap................................................................................................................................... 9
System requirements................................................................................................................................ 10
z/OSMF requirements.......................................................................................................................... 10
System requirements for the Zowe Application Framework, explorer server, and API Mediation
Layer................................................................................................................................................ 13
System requirements for Zowe CLI.................................................................................................... 14
Obtaining installation ﬁles........................................................................................................................ 16
Installing the Zowe Application Framework, explorer server, and API Mediation Layer........................ 18
Installing the Zowe runtime on z/OS..................................................................................................18
Starting and stopping the Zowe runtime on z/OS.............................................................................. 20
Verifying installation............................................................................................................................ 21
Installing Zowe CLI................................................................................................................................... 23
Methods to install Zowe CLI............................................................................................................... 23
Creating a Zowe CLI proﬁle.................................................................................................................24
Testing Zowe CLI connection to z/OSMF............................................................................................25
Troubleshooting the installation............................................................................................................... 25
Troubleshooting installing the Zowe runtime.....................................................................................25
Troubleshooting installing Zowe CLI...................................................................................................28
Uninstalling Zowe...................................................................................................................................... 30
Uninstalling the Zowe Application Framework...................................................................................30
Uninstalling explorer server................................................................................................................ 30
Uninstalling API Mediation Layer........................................................................................................ 31
iii

Uninstalling Zowe CLI..........................................................................................................................32

Chapter 3. Conﬁguring Zowe............................................................................... 35

Zowe Application Framework (zLUX) conﬁguration.................................................................................35
Setting up terminal application plug-ins............................................................................................ 35
Conﬁguring the zLUX Proxy Server and ZSS.......................................................................................35
Zowe Application Framework logging.................................................................................................37
Conﬁguring Zowe CLI................................................................................................................................ 38
Setting environment variables for Zowe CLI...................................................................................... 38

Chapter 4. Using Zowe........................................................................................ 41

Using the Zowe Desktop........................................................................................................................... 41
Navigating the Zowe Desktop............................................................................................................. 41
Using Explorers within the Zowe Application Framework................................................................. 41
Zowe Application Framework application plug-ins............................................................................ 42
Using the Workflows application plug-in............................................................................................43
Using APIs................................................................................................................................................. 44
Using explorer server REST APIs........................................................................................................45
Programming explorer server REST APIs........................................................................................... 48
Using explorer server WebSocket services........................................................................................ 50
API Catalog................................................................................................................................................ 50
View Service Information and API Documentation in the API Catalog............................................. 50
Using Zowe CLI..........................................................................................................................................52
Display Zowe CLI help.........................................................................................................................52
Zowe CLI command groups................................................................................................................ 53

Chapter 5. Extending the Zowe Application Framework (zLUX)............................. 57

Creating application plug-ins.................................................................................................................... 57
Setting the environment variables for plug-in development............................................................. 57
Using the sample application plug-in................................................................................................. 57
zLUX plug-ins deﬁnition and structure.....................................................................................................58
Application plug-in ﬁlesystem structure.............................................................................................58
Location of plug-in ﬁles....................................................................................................................... 59
Plug-in deﬁnition ﬁle........................................................................................................................... 59
Plug-in attributes................................................................................................................................. 60
zLUX dataservices..................................................................................................................................... 61
Deﬁning a dataservice......................................................................................................................... 61
Dataservice API....................................................................................................................................62
Zowe Desktop and window management................................................................................................ 63
Loading and presenting application plug-ins..................................................................................... 64
Plug-in management............................................................................................................................64
Application management.....................................................................................................................64
Windows and Viewports...................................................................................................................... 64
Viewport Manager................................................................................................................................ 65
Injection Manager................................................................................................................................ 65
Conﬁguration Dataservice......................................................................................................................... 67
Resource Scope................................................................................................................................... 67
REST API.............................................................................................................................................. 68
Application API.................................................................................................................................... 70
Internal and bootstrapping................................................................................................................. 70
Plug-in deﬁnition..................................................................................................................................71
Aggregation policies.............................................................................................................................71
URI Broker................................................................................................................................................. 72
Accessing the URI Broker................................................................................................................... 72
Functions.............................................................................................................................................. 72
Application-to-application communication..............................................................................................73
Why use application-to-application communication?........................................................................73

Actions.................................................................................................................................................. 74
Recognizers.......................................................................................................................................... 75
Dispatcher............................................................................................................................................ 76
Registry................................................................................................................................................. 77
Pulling it all together in an example...................................................................................................77
Error reporting UI...................................................................................................................................... 77
ZluxPopupManagerService.................................................................................................................. 77
ZluxErrorSeverity..................................................................................................................................78
ErrorReportStruct................................................................................................................................. 78
Implementation....................................................................................................................................78
Logging utility.............................................................................................................................................79
Logging objects.................................................................................................................................... 80
Logger IDs............................................................................................................................................ 80
Accessing logger objects..................................................................................................................... 80
Logger API............................................................................................................................................ 80
Component Logger API........................................................................................................................81
Log Levels.............................................................................................................................................81
Logging verbosity................................................................................................................................. 82

Chapter 6. Extending Zowe CLI........................................................................... 83

Installing plug-ins......................................................................................................................................83
Setting the registry.............................................................................................................................. 83
Meeting the prerequisites....................................................................................................................83
Installing plug-ins................................................................................................................................ 83
Validating plug-ins............................................................................................................................... 84
Updating plug-ins.................................................................................................................................84
Uninstalling plug-ins............................................................................................................................ 85
Zowe CLI Plug-in for IBM CICS................................................................................................................ 85
Use cases............................................................................................................................................. 85
Prerequisites.........................................................................................................................................86
Installing...............................................................................................................................................86
Setting up proﬁles................................................................................................................................86
Commands............................................................................................................................................87

About this documentation
This documentation describes how to install, conﬁgure, use, and extend Open Beta for Zowe.

Who should read this documentation
This documentation is intended for system programmers who are responsible for installing and
conﬁguring Zowe, application developers who want to use Zowe to improve z/OS user experience, and
anyone who wants to understand how Zowe works or is interested in extending Zowe to add their own
plug-ins or applications.
The information provided assumes that you are familiar with the mainframe and z/OSMF conﬁguration.

How to send your feedback on this documentation
We value your feedback. If you have comments about this documentation, you can use one of the
following ways to provide feedback:
• Send a GitHub pull request to provide a suggested edit for the content by clicking the Propose content
change in GitHub link on each documentation page.
• Open an issue in GitHub to request documentation to be updated, improved, or clariﬁed by providing a
comment.

Sending a GitHub pull request
You can provide suggested edit to any documentation page by using the Propose content change in
GitHub link on each page. After you make the changes, you submit updates in a pull request for the Zowe
content team to review and merge.
Follow these steps:
1. Click Propose content change in GitHub on the page that you want to update.
2.

Click the Edit the ﬁle icon

3. Make the changes to the ﬁle.
4. Scroll to the end of the page and enter a brief description about your change.
5. Optional: Enter an extended description.
6. Select Propose ﬁle change.
7. Select Create pull request.

Opening an issue for the documentation
You can request the documentation to be improved or clariﬁed, report an error, or submit suggestions and
ideas by opening an issue in GitHub for the Zowe content team to address. The content team tracks the
issues and works to address your feedback.
Follow these steps:
1. Click the GitHub link at the top of the page.
2. Select Issues.
3. Click New issue.
4. Enter a title and description for the issue.
5. Click Submit new issue.

viii Open Beta for Zowe: Installation and User's Guide

Release notes for Open Beta
Learn about what is new, changed, removed, and known issues in Open Beta for Zowe.
Zowe Open Beta includes the following releases:
• Version 0.9.1 (October 2018)
• Version 0.9.0 (August 2018)

Version 0.9.1 (October 2018)
Version 0.9.1 contains the following changes since the last version.

What's new
New in the Zowe Application Framework
The Workflows application plug-in was added to the Zowe Application Framework (zLUX).
The API Catalog plug-in was added to the Zowe Application Framework. This plug-in lets you view API
services that have been discovered by the API Mediation Layer.
Angular application plug-ins can be internationalized utilizing the ngx-i18n library.
New in Zowe CLI
Zowe CLI contains the following new features:
• Zowe CLI Plug-in for IBM® CICS®
The new plug-in lets you extend Zowe CLI to interact with CICS programs and transactions. It uses the
IBM CICS Management Client Interface (CMCI) API to achieve the interaction with CICS.
As an application developer, you can use the plug-in to perform various CICS-related tasks, such as the
following:
– Deploy code changes to CICS applications that were developed with COBOL.
– Deploy changes to CICS regions for testing or delivery.
– Automate CICS interaction steps in your CI/CD pipeline with Jenkins Automation Server or TravisCI.
For more information, see Zowe CLI Plug-in for IBM CICS.
• zos-jobs and zos-files commands and command options
Zowe CLI contains the following new commands and command options:
– zowe zos-jobs delete job command: Lets you cancel a job and purge its output by providing
the JOB ID.
– zowe zos-files upload file-to-uss command: Lets you upload a local ﬁle to a ﬁle on USS.
– zowe zos-files download uss-file command: Lets you download a ﬁle on USS to a local ﬁle.
– zowe zos-jobs submit local-file command: Lets you submit a job contained in a local ﬁle on
your PC rather than a data set.
– zowe zos-jobs download output command: Lets you download the complete spool output for a
job to a local directory on your PC.
– The zowe zos-jobs submit data-set command and the zowe zos-jobs submit localfile command now contain a --view-all-spool-content option. The option lets you submit a
job and view its complete spool output in one command.

New in API Mediation Layer
You can now view the status of API Mediation Layer from the Zowe Desktop App (zLUX plug-in).
Enhanced JES Explorer
A full-screen job output view is now available. You can view a single job output ﬁle in a full-screen text
area, which removes the need to navigate via the job tree. Note that this view is currently only available
via direct access to the explorer. It is not accessible via the Zowe Desktop app in this release. To open a
ﬁle in full screen, you can use the following URL/parameters: https://host:explorerSecurePort/explorerjes/#/?jobName=SAMPLEJOB&jobId=JOB12345&ﬁleId=102

What's changed
Naming
MVD is renamed to Zowe Desktop.
JES Explorer
Fixed an issue where text would fall out of line in the content viewer caused by special characters. This ﬁx
includes migration to the orion-editor-component as the content viewer.
MVS Explorer
Fixed an issue where deletion of a dataset member fails.
Zowe CLI
Important! Zowe CLI in Version 0.9.1 contains breaking changes. A breaking change can cause problems
with existing functionality when you upgrade to Zowe CLI Version 0.9.1. For example, scripts that you
wrote previously might fail, user proﬁles might become invalid, and the product might not integrate with
plug-ins properly.
You will be impacted by the following changes if you update your version of Zowe to Version 0.9.1:
• The home directory for Zowe CLI, which contains the Zowe CLI logs, proﬁles, and plug-ins, was changed
from ~/.brightside to ~/.zowe. The character "~" denotes your home directory on your computer,
which is typically C:/Users/ on Windows operating systems. When you update to
Zowe CLI Version 0.9.1 and issue zowe commands, the proﬁles that you created previously will not be
available.
To correct this behavior and migrate from an older version Zowe CLI, complete the following steps:
1. Issue any bright command to create the ~/.zowe home directory.
2. After you create the directory, copy the complete contents of the ~/.brightside directory to the
newly created ~/.zowe directory. Copying the contents of the ~/.brightside directory to the
~/.zowe directory restores the proﬁles you created previously.
3. To help ensure that your plug-ins function properly, reinstall the plug-ins that you installed with older
versions of Zowe CLI.
• The environment variables that control logging and the location of your home directory were previously
preﬁxed with BRIGHTSIDE_. They are now preﬁxed with ZOWE_. If you were not using the environment
variables before this change, no action is required. If you were using the environment variables, update
any usage of the variables.
The following environment variables are affected:
– BRIGHTSIDE_CLI_HOME changed to ZOWE_CLI_HOME
– BRIGHTSIDE_IMPERATIVE_LOG_LEVEL changed to ZOWE_IMPERATIVE_LOG_LEVEL
– BRIGHTSIDE_APP_LOG_LEVEL changed to ZOWE_APP_LOG_LEVEL

x Open Beta for Zowe: Installation and User's Guide

Version 0.9.0 (August 2018)
Version 0.9.0 is the ﬁrst Open Beta version for Zowe. This version contains the following changes since
the last Closed Beta version.

What's new
New component - API Mediation Layer
Zowe now contains a component named API Mediation Layer. You install API Mediation Layer when you
install the Zowe runtime on z/OS. For more information, see API Mediation Layer and Installing the Zowe
Application Framework, explorer server, and API Mediation Layer.

What's changed
Naming
• The project is now named Zowe.
• Zoe Brightside is renamed to Zowe CLI.
Installation
• The System Display and Search Facility (SDSF) of z/OS is no longer a prerequisite for installing explorer
server.
• The name of the PROC is now ZOWESVR rather than ZOESVR.
zLUX
The mainframe account under which the ZSS server runs must have UPDATE permission on the
BPX.DAEMON and BPX.SERVER facility class proﬁles.
Explorer server
The URL to access the explorer server UI is changed from https://:/
ui/#/ to the following ones:
• https://:/explorer-jes/#/
• https://:/explorer-mvs/#/
• https://:/explorer-uss/#/

What's removed
Removed all references to SYSLOG.

Known issues
Security message when you open the Zowe Desktop
When you initially open the Zowe Desktop, a security message alerts you that you are attempting to
open a site that has an invalid HTTPS certiﬁcate. Other applications within the Zowe Desktop might also
encounter this message. To prevent this message, add the URLs that you see to your list of trusted sites.
Note: If you clear the browser cache, you must add the URL to your trusted sites again.
Message ICH408I during runtime
During runtime, the information message ICH408I may present identifying insufﬁcient write authority to a
number of resources, these resources may include:
• zowe/explorer-server/wlp/usr/servers/.pid/Atlas.pid
• zowe/zlux-example-server/deploy/site/plugins/
• zowe/zlux-example-server/deploy/instance/plugins/
Release notes for Open Beta xi

Note: This should not affect the runtime operations of Zowe. This is a known issue and will be addressed
in the next build.
Zowe Application Framework APIs
Zowe Application Framework APIs exist but are under development. Features might be reorganized if it
simpliﬁes and clariﬁes the API, and features might be added if applications can beneﬁt from them.

xii Open Beta for Zowe: Installation and User's Guide

Chapter 1. Zowe overview
Zowe offers modern interfaces to interact with z/OS and allows you to work with z/OS in a way that is
similar to what you experience on cloud platforms today. You can use these interfaces as delivered or
through plug-ins and extensions that are created by clients or third-party vendors.
Zowe consists of the following main components.
• Zowe Application Framework: Contains a Web user interface (UI) that provides a full screen interactive
experience. The Web UI includes many interactions that exist in 3270 terminals and web interfaces
such as IBM z/OSMF.
• Explorer server: Provides a range of APIs for the management of jobs, data sets and z/OS UNIX System
Services ﬁles.
• API Mediation Layer: Provides an API abstraction layer through which APIs can be discovered,
catalogued, and presented uniformly.
• Zowe CLI: Provides a command-line interface that lets you interact with the mainframe remotely
and use common tools such as Integrated Development Environments (IDEs), shell commands, bash
scripts, and build tools for mainframe development. It provides a set of utilities and services for
application developers that want to become efﬁcient in supporting and building z/OS applications
quickly.
For details of each component, see the corresponding section.

Zowe Application Framework
The Zowe Application Framework modernizes and simpliﬁes working on the mainframe. With the Zowe
Application Framework, you can create applications to suit your speciﬁc needs. The Zowe Application
Framework contains a web UI that has the following features:
• The web UI works with the underlying REST APIs for data, jobs, and subsystem, but presents the
information in a full screen mode as compared to the command line interface.
• The web UI makes use of leading-edge web presentation technology and is also extensible through web
UI plug-ins to capture and present a wide variety of information.
• The web UI facilitates common z/OS developer or system programmer tasks by providing an editor for
common text-based ﬁles like REXX or JCL along with general purpose data set actions for both Unix
System Services (USS) and Partitioned Data Sets (PDS) plus Job Entry System (JES) logs.
The Zowe Application Framework consists of the following components:
• Zowe Desktop
The desktop, accessed through a browser.
• Zowe Application Server
The Zowe Application Server runs the Zowe Application Framework. It consists of the Node.js server
plus the Express.js as a webservices framework, and the proxy applications that communicate with the
z/OS services and components.
• ZSS Server
The ZSS Server provides secure REST services to support the Zowe Application Server.
• Application plug-ins
Several application-type plug-ins are provided. For more information, see Using the Zowe Application
Framework application plug-ins.

Explorer server
The explorer server is a z/OS® RESTful web service and deployment architecture for z/OS microservices.
The server is implemented as a Liberty Proﬁle web application that uses z/OSMF services to provide a
range of APIs for the management of jobs, data sets and z/OS UNIX™ System Services (USS) ﬁles.
These APIs have the following features:
• These APIs are described by the Open API Speciﬁcation allowing them to be incorporated to any
standard-based REST API developer tool or API management process.
• These APIs can be exploited by off-platform applications with proper security controls.
Any client application that calls RESTful APIs directly can use the explorer server.
As a deployment architecture, the explorer server accommodates the installation of other z/Tool
microservices into its Liberty instance. These microservices can be used by explorer server APIs and
client applications.

Zowe CLI
Zowe CLI is a command-line interface that lets application developers interact with the mainframe in a
familiar format. Zowe CLI helps to increase overall productivity, reduce the learning curve for developing
mainframe applications, and exploit the ease-of-use of off-platform tools. Zowe CLI lets application
developers use common tools such as Integrated Development Environments (IDEs), shell commands,
bash scripts, and build tools for mainframe development. It provides a set of utilities and services for
application developers that want to become efﬁcient in supporting and building z/OS applications quickly.
Zowe CLI provides the following beneﬁts:
• Enables and encourages developers with limited z/OS expertise to build, modify, and debug z/OS
applications.
• Fosters the development of new and innovative tools from a PC that can interact with z/OS.
• Ensure that business critical applications running on z/OS can be maintained and supported by existing
and generally available software development resources.
• Provides a more streamlined way to build software that integrates with z/OS.
The following sections explain the key features and details for Zowe CLI:
Note: For information about prerequisites, software requirements, installing and upgrading Zowe CLI, see
Installing Zowe.

Zowe CLI capabilities
With Zowe CLI, you can interact with z/OS remotely in the following ways:
• Interact with mainframe ﬁles: Create, edit, download, and upload mainframe ﬁles (data sets) directly
from Zowe CLI.
• Submit jobs: Submit JCL from data sets or local storage, monitor the status, and view and download the
output automatically.
• Issue TSO and z/OS console commands: Issue TSO and console commands to the mainframe directly
from Zowe CLI.
• Integrate z/OS actions into scripts: Build local scripts that accomplish both mainframe and local
tasks.
• Produce responses as JSON documents: Return data in JSON format on request for consumption in
other programming languages.
For more information about the available functionality in Zowe CLI, see Zowe CLI Command Groups.

2 Open Beta for Zowe: Installation and User's Guide

Zowe CLI Third-Party software agreements
Zowe CLI uses the following third-party software:
Third-party Software

Version

File name

chalk

2.3.0

Legal_Doc_00002285_56.pdf

cli-table2

0.2.0

Legal_Doc_00002310_5.pdf

dataobject-parser

1.2.1

Legal_Doc_00002310_36.pdf

ﬁnd-up

2.1.0

Legal_Doc_00002310_33.pdf

glob

7.1.1

Legal_Doc_00001713_45.pdf

js-yaml

3.9.0

Legal_Doc_00002310_16.pdf

jsonﬁle

4.0.0

Legal_Doc_00002310_40.pdf

jsonschema

1.1.1

Legal_Doc_00002310_17.pdf

levenshtein

1.0.5

See UNLICENSE

log4js

2.5.3

Legal_Doc_00002310_37.pdf

merge-objects

1.0.5

Legal_Doc_00002310_34.pdf

moment

2.20.1

Legal_Doc_00002285_25.pdf

mustache

2.3.0

Legal_Doc_mustache.pdf

node.js

6.11.1

Legal_Doc_nodejs.pdf

node-ibm_db

2.3.1

Legal_Doc_00002310_38.pdf

node-mkdirp

0.5.1

Legal_Doc_00002310_35.pdf

node-progress

2.0.0

Legal_Doc_00002310_7.pdf

prettyjson

1.2.1

Legal_Doc_00002310_22.pdf

rimraf

2.6.1

Legal_Doc_00002310_8.pdf

Semver

5.5.0

Legal_Doc_00002310_42.pdf

stack-trace

0.0.10

Legal_Doc_00002310_10.pdf

string-width

2.1.1

Legal_Doc_00002310_39.pdf

wrap-ansi

3.0.1

Legal_Doc_00002310_12.pdf

yamljs

0.3.0

Legal_Doc_00002310_13.pdf

yargs

8.0.2

Legal_Doc_00002310_1.pdf

Note: All trademarks, trade names, service marks, and logos referenced herein belong to their respective
companies.
To read each complete license, navigate to the GitHub repository and download the ﬁle named
Zowe_CLI_TPSRs.zip. The .zip ﬁle contains the licenses for all of the third-party components that Zowe
CLI uses.
More Information:
• System requirements for Zowe CLI
• Installing Zowe CLI

Zowe overview 3

API Mediation Layer
The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer
offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery,
consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates
secure communication across loosely coupled microservices through the API Gateway. The API Mediation
Layer includes an API Catalog that provides an interface to view all discovered microservices, their
associated APIs, and Swagger documentation in a user-friendly manner. The Discovery Service makes it
possible to determine the location and status of microservice instances running inside the ecosystem.
More Information: - Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer Using API Catalog

Key features
• High availability of services in which application instances on a failing node are distributed among
surviving nodes
• Microservice UIs available through the API Gateway and API Catalog by means of reverse proxying
• Support for standardization and normalization of microservice URLs and routing to provide API
Mediation Layer users with a consistent way of accessing microservices.
• Minimal effort to register a microservice with the gateway (conﬁguration over code)
• Runs on Windows, Linux, and z/OS (target platform)
• Written in Java utilizing Spring Boot (2.x), Angular 5, and the Netflix CloudStack
• Supports multiple client types for discovery (including Spring Boot, Java, and NodeJS)
• Contains enablers that allow for easy discovery and exposure of REST APIs and Swagger documentation
for each microservice

API Mediation Layer architecture
The following diagram illustrates the single point of access with the API Gateway and the interactions
between the API Gateway, API Catalog, and the Discovery Service:

4 Open Beta for Zowe: Installation and User's Guide

Components
The API Layer consists of the following key components:
API Gateway
The microservices that are contained within the ecosystem are located behind a reverse proxy. Clients
interact with the gateway layer (reverse proxy). This layer forwards API requests to the appropriate
corresponding service through the microservice endpoint UI. The gateway is built using Netflix Zuul and
Spring Boot technology.
Discovery Service
The Discovery service is the central point in the API Gateway infrastructure that accepts "announcements
of REST services" and serves as a repository of active services. Back-end microservices register with this
service either directly by using a Eureka client. Non-Spring Boot applications register with the Discover
Service indirectly through a Sidecar. The Discovery Service is built on Eureka and Spring Boot technology.
API Catalog
The API Catalog is the catalog of published APIs and their associated documentation that are
discoverable or can be available if provisioned from the service catalog. The API documentation is
visualized using the Swagger UI. The API Catalog contains APIs of services available as product versions.
A service can be implemented by one or more service instances, which provide exactly the same service
for high-availability or scalability.
Zowe overview 5

More Information: - Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer Using API Catalog

Zowe API Mediation Layer Third-Party software agreements
Zowe API Mediation Layer uses the following third-party software:
Third-party Software

Version

File name

angular

5.2.0

Legal_Doc_00002377_15.pdf

angular2-notiﬁcations

0.9.5

Legal_Doc_00002499_11.pdf

Apache Tomcat

8.0.39

Legal_Doc_00001505_6.pdf

Bootstrap

3.0.3

Legal_Doc_12955_5.pdf

Bootstrap

3.3.7

Legal_Doc_00001682_11.pdf

bootstrap-submenu

2.0.4

Legal_Doc_00001456_44.pdf

Commons Validator

1.6.0

Legal_Doc_00002105_1.pdf

copy-webpack-plugin

4.4.1

Legal_Doc_00002499_13.pdf

core-js

2.5.3

Legal_Doc_corejs_MIT.pdf

eureka-client

1.8.6

Legal_Doc_00002499_3.pdf

eventsource

1.0.5

Legal_Doc_00002499_9.pdf

google-gson

2.8.2

Legal_Doc_00002252_4.pdf

Guava

23.2-jre

Legal_Doc_00002499_22.pdf

1.4.196

Legal_Doc_00002499_19.pdf

hamcrest

1.3

Legal_Doc_00001170_33.pdf

httpclient

4.5.3

Legal_Doc_00001843_2.pdf

jackson

2.9.2

Legal_Doc_00002259_6.pdf

jackson

2.9.3

Legal_Doc_00001505_16.pdf

javamail

1.4.3

Legal_Doc_00000439_22.pdf

javax servlet api

3.1.0

Legal_Doc_00002499_23.pdf

javax.validation

2.0.1.Final

Legal_Doc_00002499_27.pdf

Jersey

2.26

Legal_Doc_00002499_2.pdf

Jersey Media JSON Jackson

2.26

Legal_Doc_00002019_68.pdf

jquery

2.0.3

Legal_Doc_00000379_69.pdf

JSON Web Token

0.8.0

Legal_Doc_00002499_21.pdf

json-path

2.4.0

Legal_Doc_00001454_30.pdf

lodash

4.17.5

Legal_Doc_00002499_8.pdf

Logback

1.0.1

Legal_Doc_00002499_1.pdf

lombok

1.16.20

Legal_Doc_00002499_18.pdf

mockito

2.15.0

Legal_Doc_00002499_28.pdf

netflix-inﬁx

0.3.0

Legal_Doc_00002499_4.pdf

6 Open Beta for Zowe: Installation and User's Guide

Third-party Software

Version

File name

ng2-cookies

1.0.12

Legal_Doc_00002499_15.pdf

ng2-destroy-subscribers

0.0.28

Legal_Doc_00002499_16.pdf

ng2-simple-timer

1.3.3

Legal_Doc_00002499_17.pdf

NPM

5.6.0

Legal_Doc_00002499_10.pdf

powermock

1.7.3

Legal_Doc_00002499_25.pdf

reactor-core

3.0.7.RELEASE

Legal_Doc_00001938_51.pdf

Roaster

2.20.1.Final

Legal_Doc_00002499_20.pdf

RxJS

5.5.6

Legal_Doc_rxjs_Apache.pdf

Spring Cloud Conﬁg

2.0.0.M9

Legal_Doc_00002499_33.pdf

Spring Hateoas

0.23.0.RELEASE

Legal_Doc_00002377_10.pdf

Spring Retry

1.2.2

Legal_Doc_00002499_14.pdf

spring security

5.0.3.RELEASE

Legal_Doc_00002499_29.pdf

spring-boot

2.0.0.RELEASE

Legal_Doc_spring_boot_Apache.pdf

Spring-Cloud-Netflix

2.0.0.M8

Legal_Doc_00002499_30.pdf

Springfox

2.8.0

Legal_Doc_00002499_31.pdf

spring-ws

3.0.0.RELEASE

Legal_Doc_00002499_32.pdf

swagger-core

1.5.18

Legal_Doc_00002499_24.pdf

swagger-jersey2-jaxrs

1.5.17

Legal_Doc__00001528_32.pdf

swagger-schema-ts

2.0.8

Legal_Doc_00002499_12.pdf

zone.js

0.8.20

Legal_Doc_zonejs_MIT.pdf

Note: All trademarks, trade names, service marks, and logos referenced herein belong to their respective
companies.
To read each complete license, navigate to the GitHub repository and download the ﬁle named
Zowe_APIML_TPSRs.zip. The .zip ﬁle contains the licenses for all of the third-party components that
Zowe API Mediation Layer uses.

Zowe overview 7

8 Open Beta for Zowe: Installation and User's Guide

Chapter 2. Installing Zowe
Zowe consists of four main components: the Zowe Application Framework (zLUX), the explorer server, API
Mediation Layer, and Zowe CLI. You install the Zowe Application Framework, the explorer server, and API
Mediation on z/OS and install Zowe CLI on PC. The installations on z/OS and on PC are independent.

To get started with installing Zowe, review the Installation roadmap topic.

Installation roadmap
Installing Zowe involves several steps that you must complete in the appropriate sequence. Review the
following installation roadmap that presents the task-flow for preparing your environment and installing
and conﬁguring Zowe before you begin the installation process.
Tasks

Description

1. Prepare your environment to meet the
installation requirements.

See System requirements.

2. Obtain the Zowe installation ﬁles.

The Zowe installation ﬁles are released in a PAX
ﬁle format. The PAX ﬁle contains the runtimes and
the scripts to install and launch the z/OS runtime,
as well as the Zowe CLI package. For information
about how to download, prepare, and install the
Zowe runtime, see Obtaining the installation ﬁles.

3. Allocate enough space for the installation.

The installation process requires approximately
1 GB of available space. Once installed on z/
OS, API Mediation Layer requires approximately
150MB of space, the Zowe Application Framework
requires approximately 50 MB of space before
conﬁguration, and explorer server requires
approximately 200 MB. Zowe CLI requires
approximately 200 MB of space on your PC.

4. Install components of Zowe.

To install Zowe runtime (Zowe Application
Framework, explorer server, and API Mediation
Layer) on z/OS, see Installing the Zowe runtime
on z/OS. To install Zowe CLI on PC, see Installing
Zowe CLI.

Tasks

Description

5. Verify that Zowe is installed correctly.

To verify that the Zowe Application Framework,
explorer server, and API Mediation Layer are
installed correctly, see Verifying installation. To
verify that Zowe CLI is installed correctly, see
Testing connection to z/OSMF.

6. Optional: Troubleshoot problems that occurred
during installation.

See Troubleshooting the installation.

To uninstall Zowe, see Uninstalling Zowe.

System requirements
Before installing Zowe, ensure that your environment meets all of the prerequisites.
1. Ensure that IBM z/OS Management Facility (z/OSMF) is installed and conﬁgured correctly. z/OSMF is
a prerequisite for the Zowe microservice that must be installed and running before you use Zowe. For
details, see z/OSMF requirements.
2. Review component speciﬁc requirements.
• System requirements for the Zowe Application Framework, explorer server, and API Mediation
• System requirements for Zowe CLI

z/OSMF requirements
The following information contains procedures and tips for meeting z/OSMF requirements. For complete
information, go to IBM Knowledge Center and read the following documents.
• IBM z/OS Management Facility Conﬁguration Guide
• IBM z/OS Management Facility Help
z/OS requirements
Ensure that the z/OS system meets the following requirements:
Requirements

Description

Resources in IBM Knowledge
Center

AXE (System REXX)

z/OS uses AXR (System REXX)
component to perform Incident
Log tasks. The component
enables REXX executable ﬁles to
run outside of conventional TSO
and batch environments.

System REXX

Common Event Adapter (CEA)
server

The CEA server, which is a
Customizing for CEA
co-requisite of the Common
Information Model (CIM) server,
enables the ability for z/OSMF to
deliver z/OS events to C-language
clients.

Common Information Model
(CIM) server

z/OSMF uses the CIM server to
Reviewing your CIM server setup
perform capacity-provisioning
and workload-management
tasks. Start the CIM server before
you start z/OSMF (the IZU*
started tasks).

10 Open Beta for Zowe: Installation and User's Guide

Requirements

Description

Resources in IBM Knowledge
Center

CONSOLE and CONSPROF
commands

The CONSOLE and CONSPROF
commands must exist in the
authorized command table.

Customizing the CONSOLE and
CONSPROF commands

IBM z/OS Provisioning Toolkit

The IBM® z/OS® Provisioning
Toolkit is a command line utility
that provides the ability to
provision z/OS development
environments. If you want
to provision CICS or Db2
environments with the Zowe CLI,
this toolkit is required.

What is IBM Cloud Provisioning
and Management for z/OS?

Java level

IBM® 64-bit SDK for z/OS®, Java
Technology Edition V7.1 or later
is required.

Software prerequisites for z/
OSMF

TSO region size

To prevent exceeds maximum
region size errors, verify that the
TSO maximum region size is a
minimum of 65536 KB for the z/
OS system.

N/A

User IDs

User IDs require a TSO segment N/A
(access) and an OMVS segment.
During workflow processing
and REST API requests, z/
OSMF might start one or more
TSO address spaces under the
following job names: userid;
substr(userid, 1, 6) CN (Console).

Conﬁguring z/OSMF
1. From the console, issue the following command to verify the version of z/OS:
/D IPLINFO

Part of the output contains the release, for example,
RELEASE z/OS 02.02.00.

2. Conﬁgure z/OSMF.
z/OSMF is a base element of z/OS V2.2 and V2.3, so it is already installed. But it might not be
conﬁgured and running on every z/OS V2.2 and V2.3 system.
In short, to conﬁgure an instance of z/OSMF, run the IBM-supplied jobs IZUSEC and IZUMKFS, and
then start the z/OSMF server. The z/OSMF conﬁguration process occurs in three stages, and in the
following order: - Stage 1 - Security setup - Stage 2 - Conﬁguration - Stage 3 - Server initialization
This stage sequence is critical to a successful conﬁguration. For complete information about how to
conﬁgure z/OSMF, see Conﬁguring z/OSMF if you use z/OS V2.2 or Setting up z/OSMF for the ﬁrst time if
V2.3.
Note: In z/OS V2.3, the base element z/OSMF is started by default at system initial program load (IPL).
Therefore, z/OSMF is available for use as soon as you set up the system. If you prefer not to start z/OSMF
automatically, disable the autostart function by checking for START commands for the z/OSMF started
procedures in the COMMNDxx parmlib member.
Installing Zowe 11

The z/OS Operator Consoles task is new in Version 2.3. Applications that depend on access to the
operator console such as Zowe CLI's RestConsoles API require Version 2.3.
1. Verify that the z/OSMF server and angel processes are running. From the command line, issue the
following command:
/D A,IZU*

If jobs IZUANG1 and IZUSVR1 are not active, issue the following command to start the angel process:
/S IZUANG1

After you see the message ""CWWKB0056I INITIALIZATION COMPLETE FOR ANGEL"", issue the
following command to start the server:
/S IZUSVR1

The server might take a few minutes to initialize. The z/OSMF server is available when the message
""CWWKF0011I: The server zosmfServer is ready to run a smarter planet."" is displayed.
2. Issue the following command to ﬁnd the startup messages in the SDSF log of the z/OSMF server:
f IZUG349I

You could see a message similar to the following message, which indicates the port number:
IZUG349I: The z/OSMF STANDALONE Server home page can be accessed at https://
mvs.hursley.ibm.com:443/zosmf after the z/OSMF server is started on your system.

In this example, the port number is 443. You will need this port number later.
Point your browser at the nominated z/OSMF STANDALONE Server home page and you should see its
Welcome Page where you can log in.
z/OSMF REST services for the Zowe CLI
The Zowe CLI uses z/OSMF Representational State Transfer (REST) APIs to work with system resources
and extract system data. Ensure that the following REST services are conﬁgured and available.
z/OSMF REST services

Requirements

Resources in IBM knowledge
Center

Cloud provisioning services

Cloud provisioning services
are required for the Zowe CLI
CICS and Db2 command groups.
Endpoints begin with /zosmf/
provisioning/

Cloud provisioning services

TSO/E address space services

TSO/E address space services
are required to issue TSO
commands in the Zowe CLI.
Endpoints begin with /zosmf/
tsoApp

TSO/E address space services

z/OS console services

z/OS console services are
required to issue console
commands in the Zowe CLI.
Endpoints begin with /zosmf/
restconsoles/

z/OS console

12 Open Beta for Zowe: Installation and User's Guide

z/OSMF REST services

Requirements

Resources in IBM knowledge
Center

z/OS data set and ﬁle REST
interface

z/OS data set and ﬁle REST
z/OS data set and ﬁle interface
interface is required to work
with mainframe data sets and
UNIX System Services ﬁles in the
Zowe CLI. Endpoints begin with /
zosmf/restfiles/

z/OS jobs REST interface

z/OS jobs REST interface is
required to use the zos-jobs
command group in the Zowe CLI.
Endpoints begin with /zosmf/
restjobs/

z/OS jobs interface

z/OSMF workflow services

z/OSMF workflow services is
required to create and manage
z/OSMF workflows on a z/OS
system. Endpoints begin with /
zosmf/workflow/

z/OSMF workflow services

Zowe uses symbolic links to the z/OSMF bootstrap.properties,
jvm.security.override.properties, and ltpa.keys ﬁles. Zowe reuses SAF, SSL, and LTPA
conﬁgurations; therefore, they must be valid and complete.
For more information, see Using the z/OSMF REST services in IBM z/OSMF documentation.
To verify that z/OSMF REST services are conﬁgured correctly in your environment, enter the REST
endpoint into your browser. For example: https://mvs.ibm.com:443/zosmf/restjobs/jobs
Note:
• Browsing z/OSMF endpoints requests your user ID and password for defaultRealm; these are your TSO
user credentials.
• The browser returns the status code 200 and a list of all jobs on the z/OS system. The list is in raw JSON
format.

System requirements for the Zowe Application Framework, explorer server, and API
Mediation Layer
The Zowe Application Framework, explorer server, and API Mediation Layer are installed together. Before
the installation, make sure your system meets the following requirements:
• z/OS® Version 2.2 or later.
• 64-bit Java™ 8 JRE or later.
• 833 MB of HFS ﬁle space.
• Supported browsers:
– Chrome 54 or later
– Firefox 44 or later
– Safari 11 or later
– Microsoft Edge
• Node.js Version 6.11.2 or later on the z/OS host where you install the Zowe Application Server.
1. To install Node.js on z/OS, follow the procedures at https://developer.ibm.com/node/sdk/ztp. Note
that installation of the C/C++ compiler is not necessary for running the Zowe Application Framework.
2. Set the NODE_HOME environment variable to the directory where Node.js is installed. For example,
NODE_HOME=/proj/mvd/node/installs/node-v6.11.2-os390-s390x.
Installing Zowe 13

• npm 5.4 or later for building Zowe Application Framework applications.
To update npm, issue the following command:
npm install -g npm
Planning for installation
The following information is required during the installation process. Make the decisions before the
installtion.
• The HFS directory where you install Zowe, for example, /var/zowe.
• The HFS directory that contains a 64-bit Java™ 8 JRE.
• The z/OSMF installation directory that contains derby.jar, for example, /usr/lpp/zosmf/lib.
• The z/OSMF conﬁguration user directory that contains the following z/OSMF ﬁles:
– /bootstrap.properties
– /jvm.security.override.properties
– /resources/security/ltpa.keys
• The HTTP and HTTPS port numbers of the explorer server. By default, they are 7080 and 7443.
• The API Mediation Layer HTTP and HTTPS port numbers. You will be asked for 3 unique port numbers.
• The user ID that runs the Zowe started task.
Tip: Use the same user ID that runs the z/OSMF IZUSVR1 task, or a user ID with equivalent
authorizations.
• The mainframe account under which the ZSS server runs must have UPDATE permission on the
BPX.DAEMON and BPX.SERVER facility class proﬁles.

System requirements for Zowe CLI
Before you install Zowe CLI, make sure your system meets the following requirements:
Supported platforms
You can install Zowe CLI on any Windows or Linux operating system. For more information about known
issues and workarounds, see Troubleshooting installing Zowe CLI.
Important!
• Zowe CLI is not ofﬁcially supported on Mac computers. However, Zowe CLI might run successfully on
some Mac computers.
• Oracle Linux 6 is not supported.
Free disk space
Zowe CLI requires approximately 100 MB of free disk space. The actual quantity of free disk space
consumed might vary depending on the operating system where you install Zowe CLI.
Prerequisite software
Zowe CLI is designed and tested to integrate with z/OSMF running on IBM z/OS Version 2.2 or later.
Before you can use Zowe CLI to interact with the mainframe, system programmers must install and
conﬁgure IBM z/OSMF in your environment. This section provides supplemental information about Zowe
CLI-speciﬁc tips or requirements that system programmers can refer to.
Before you install Zowe CLI, also install the following prerequisite software depending on the system
where you install Zowe CLI:
Note: It's highly recommended that you update Node.js regularly to the latest Long Term Support (LTS)
version.

14 Open Beta for Zowe: Installation and User's Guide

Windows operating systems
Windows operating systems require the following software:
• Node.js V8.0 or later
Click here to download Node.js.
• Node Package Manager (npm) V5.0 or later
Note: npm is included with the Node.js installation.
• Python V2.7
The command that installs C++ Compiler also installs Python on Windows.
• C++ Compiler (gcc 4.8.1 or later)
From an administrator command prompt, issue the following command:
npm install --global --production --add-python-to-path windows-build-tools

Mac operating systems
Mac operating systems require the following software:
• Node.js V8.0 or later
Click here to download Node.js.
• Node Package Manager (npm) V5.0 or later
Note: npm is included with the Node.js installation.
Tip: If you install Node.js on a macOS operating system, it's highly recommended that you follow the
instructions on the Node.js website (using package manager) to install nodejs and nodejs-legacy.
For example, you can issue command sudo apt install nodejs-legacy to install nodejslegacy. With nodejs-legacy, you can issue command node rather than nodejs.
• Python V2.7
Click here to download Python 2.7.
• C ++ Compiler (gcc 4.8.1 or later)
The gcc compiler is included with macOS. To conﬁrm that you have the compiler, issue the command
gcc –help.
Linux operating systems
Linux operating systems require the following software:
• Node.js V8.0 or later
Click here to download Node.js.
• Node Package Manager (npm) V5.0 or later
Note: npm is included with the Node.js installation.
Tip: If you install Node.js on a Linux operating system, it's highly recommended that you follow the
instructions on the Node.js website (using package manager) to install nodejs and nodejs-legacy.
For example, you can issue command sudo apt install nodejs-legacy to install nodejslegacy. With nodejs-legacy, you can issue command node rather than nodejs.
• Python V2.7
Included with most Linux distributions.
• C ++ Compiler (gcc 4.8.1 or later)
Gcc is included with most Linux distributions. To conﬁrm that gcc is installed, issue the command gcc
–version.
Installing Zowe 15

To install gcc, issue one of the following commands:
– Red Hat
sudo yum install gcc

– Debian/Ubuntu
sudo apt-get update
sudo apt-get install build-essential

– Arch Linux
sudo pacman -S gcc

• Libsecret
To install Libsecret, issue one of the following commands:
– Red Hat
sudo yum install libsecret-devel

– Debian/Ubuntu
sudo apt-get install libsecret-1-dev

– Arch Linux
sudo pacman -S libsecret

• Make
Make is included with most Linux distributions. To conﬁrm that Make is installed, issue the command
make –-version.
To install Make, issue one of the following commands:
– Red Hat
sudo yum install devtoolset-7

– Debian/Ubuntu
sudo apt-get install build-essential

– Arch Linux
sudo pacman -S base-devel

Obtaining installation ﬁles
The Zowe installation ﬁles are distributed as a PAX ﬁle that contains the runtimes and the scripts to install
and launch the z/OS runtime and the runtime for the command line interface. For each release, there is a
PAX ﬁle named zowe-v.r.m.pax, where
• v indicates the version
• r indicates the release number
• m indicates the modiﬁcation number
The numbers are incremented each time a release is created so the higher the numbers, the later the
release. Use your web browser to download the PAX ﬁle by saving it to a folder on your desktop.
16 Open Beta for Zowe: Installation and User's Guide

You can download the PAX ﬁle from the Zowe website. After you obtain the PAX ﬁle, verify the PAX ﬁle and
prepare it to install the Zowe runtime.
Follow these steps:
1. Verify the downloaded PAX ﬁle.
After you download the PAX ﬁle, verify the integrity of the PAX ﬁle to ensure that the ﬁle you download
is ofﬁcially distributed by the Zowe project.
Notes:
• The commands in the following steps are tested on both Mac OS X V10.13.6 and Ubuntu V16.04 and
V17.10.
• Ensure that you have GPG installed. Click here to download and install GPG.
• The v.r.m in the commands of this step is a variable. You must replace it with the actual PAX ﬁle
version, for example, 0.9.0.
a. Verify the hash code.
Download the hash code ﬁle zowe-v.r.m.pax.sha512 from the Zowe website. Then, run the
following commands to check:
(gpg --print-md SHA512 zowe-v.r.m.pax > zowe-v.r.m.pax.sha512.my) && diff
zowe-v.r.m.pax.sha512.my zowe-v.r.m.pax.sha512 && echo matched || echo "not
match"
When you see "matched", it means the PAX ﬁle that you download is the same one that is ofﬁcially
distributed by the Zowe project. You can delete the temporary "zowe-v.r.m.pax.sha512.my" ﬁle.
You can also use other commands such as sha512, sha512sum, or openssl dgst -sha512
to generate SHA512 hash code. These hash code results are in a different format from what Zowe
provides but the values are the same.
b. Verify with signature ﬁle.
In addition to the SHA512 hash, the hash is also veriﬁable. This is done by digitally signing the hash
text ﬁle with a KEY from one of the Zowe developers.
Follow these steps:
a. Download the signature ﬁle zowe-v.r.m.pax.asc from Zowe website, and download the public
key KEYS from https://github.com/zowe/release-management/.
b. Import the public key with command gpg --import KEYS.
c. If you never use gpg before, generate keys with command gpg --gen-key.
d. Sign the downloaded public key with command gpg --sign-key DC8633F77D1253C3.
e. Verify the ﬁle with command gpg --verify zowe-v.r.m.pax.asc zowe-v.r.m.pax.
f. Optional: You can remove the imported key with command: gpg --delete-key
DC8633F77D1253C3.
When you see output similar to the followin one, it means the PAX ﬁle that you download is the same
one that is ofﬁcially distributed by the Zowe project.
gpg: Signature made Tue 14 Aug 2018 08:29:46 AM EDT gpg: using RSA key
DC8633F77D1253C3 gpg: Good signature from "Matt Hogstrom (CODE SIGNING KEY)
" [full]
2. Transfer the PAX ﬁle to z/OS.
a. Open a terminal in Mac OS/Linux, or command prompt in Windows OS, and navigate to the directory
where you downloaded the Zowe PAX ﬁle.
b. Connect to z/OS using SFTP. Issue the following command:
sftp
Installing Zowe 17

If SFTP is not available or if you prefer to use FTP, you can issue the following command instead:
ftp
Note: When you use FTP, switch to binary ﬁle transfer mode by issuing the following command:
bin
c. Navigate to the target directory that you wish to transfer the Zowe PAX ﬁle into on z/OS.
Note: After you connect to z/OS and enter your password, you enter into the Unix ﬁle system. The
following commands are useful:
• To see what directory you are in, type pwd.
• To switch directory, type cd.
• To list the contents of a directory, type ls.
• To create a directory, type mkdir.
d. When you are in the directory you want to transfer the Zowe PAX ﬁle into, issue the following
command:
put .pax
Where pax-ﬁle-name is a variable that indicates the full name of the PAX ﬁle you downloaded.
Note: When your terminal is connected to z/OS through FTP or SFTP, you can prepend commands with
l to have them issued against your desktop. To list the contents of a directory on your desktop, type
lls where ls will list contents of a directory on z/OS.
3. When the PAX ﬁle is transferred, expand the PAX ﬁle by issuing the following command in an ssh
session:
pax -ppx -rf .pax

Where pax-ﬁle-name is a variable that indicates the name of the PAX ﬁle you downloaded.
This will expand to a ﬁle structure.
/files
/install
/scripts
...

Note: The PAX ﬁle will expand into the current directory. A good practice is to keep the installation
directory apart from the directory that contains the PAX ﬁle. To do this, you can create a directory
such as /zowe/paxes that contains the PAX ﬁles, and another such as /zowe/builds. Use SFTP
to transfer the Zowe PAX ﬁle into the /zowe/paxes directory, use the cd command to switch into
/zowe/builds and issue the command pax -ppx -rf ../paxes/.pax. The /
install folder will be created inside the zowe/builds directory from where the installation can be
launched.

Installing the Zowe Application Framework, explorer server, and API
Mediation Layer
You install the Zowe Application Framework, explorer server, and API Mediation Layer on z/OS.
Before you install the runtime on z/OS, ensure that your environment meets the requirements. See
System requirements.

Installing the Zowe runtime on z/OS
To install API Mediation Layer, the Zowe Application Framework, and explorer server, you install the Zowe
runtime on z/OS.
18 Open Beta for Zowe: Installation and User's Guide

Follow these steps:
1. Navigate to the directory where the installation archive is extracted. Locate the /install directory.
/install
/zowe-install.sh
/zowe-install.yaml

2. Review the zowe-install.yaml ﬁle which contains the following properties:
• install:rootDir is the directory that Zowe will be installed into to create a Zowe runtime. The
default directory is ~/zowe/0.9.1. The user's home directory is the default value to ensure that the
installing user has permission to create the directories that are required for the install. If the Zowe
runtime will be maintained by multiple users it might be more appropriate to use another directory,
such as /var/zowe/v.r.m.
You can run the installation process multiple times with different values in the zowe-install.yaml
ﬁle to create separate installations of the Zowe runtime. The directory that Zowe is installed into must
be empty. The install script exits if the directory is not empty and creates the directory if it does not
exist.
• API Mediation Layer has three ports - two HTTP ports and one HTTPS port, each for a micro-service.
• Explorer-server has two ports - one for HTTP and one for HTTPS. The liberty server is used for the
explorer-ui components.
• zlux-server has three ports - the HTTP and HTTPS ports that are used by the Zowe Application
Server, and the port that is used by the ZSS Server.
install:
rootDir=/var/zowe/0.9.1
api-mediation:
catalogHttpPort=7552
discoveryHttpPort=7553
gatewayHttpsPort=7554
explorer-server:
httpPort=7080
httpsPort=7443
# http and https ports for the node server
zlux-server:
httpPort=8543
httpsPort=8544
zssPort=8542

If all of the default port values are acceptable, then you do not need to change them. The ports must
not be in use for the Zowe runtime servers to be able to allocate them.
To determine which ports are not available, follow these steps:
• To display a list of ports that are in use, issue the following command:
TSO NETSTAT

• To display a list of reserved ports, issue the following command:
TSO NETSTAT PORTLIST

The zowe-install.yaml also contains the telnet and SSH port with defaults of 23 and 22. If your
z/OS LPAR is using different ports, edit the values. This is to allow the TN3270 terminal desktop
application to connect as well as the VT terminal desktop application. Unlike the ports needed by the
Zowe runtime for its Zowe Application Framework and explorer server which must be unused, the
terminal ports are expected to be in use.
# Ports for the TN3270 and the VT terminal to connect to
terminals:
sshPort=22

Installing Zowe 19

telnetPort=23

3. Execute the zowe-install.sh script.
With the current directory being the /install directory, execute the script zowe-install.sh by
issuing the following command:
zowe-install.sh

You might receive the following error that the ﬁle cannot be executed.
zowe-install.sh: cannot execute

The error is due to that the install script does not have execute permission. To add execute permission,
issue the following command:
chmod u+x zowe-install.sh.

4. Conﬁgure Zowe as a started task.
The ZOWESVR must be conﬁgured as a started task (STC) under the IZUSVR user ID.
• If you use RACF, issue the following commands:
RDEFINE STARTED ZOWESVR.* UACC(NONE) STDATA(USER(IZUSVR) GROUP(IZUADMIN) PRIVILEGED(NO)
TRUSTED(NO) TRACE(YES))
SETROPTS REFRESH RACLIST(STARTED)

• If you use CA ACF2, issue the following commands:
SET CONTROL(GSO)
INSERT STC.ZOWESVR LOGONID(IZUSVR) GROUP(IZUADMIN) STCID(ZOWESVR)
F ACF2,REFRESH(STC)

• If you use CA Top Secret, issue the following commands:
TSS ADDTO(STC) PROCNAME(ZOWESVR) ACID(IZUSVR)

5. Add the users to the required groups, IZUADMIN for administrators and IZUUSER for standard users.
• If you use RACF, issue the following command:
CONNECT (userid) GROUP(IZUADMIN)

• If you use CA ACF2, issue the following commands:
ACFNRULE TYPE(TGR) KEY(IZUADMIN) ADD(UID() ALLOW)
F ACF2,REBUILD(TGR)

• If you use CA Top Secret, issue the following commands:
TSS ADD(userid)
TSS ADD(userid)

PROFILE(IZUADMIN)
GROUP(IZUADMGP)

When the zowe-install.sh script runs, it performs a number of steps broken down into sections.
These are covered more in the section Troubleshooting the installation.

Starting and stopping the Zowe runtime on z/OS
Zowe has three runtime components on z/OS, the explorer server, the Zowe Application Server, and API
Mediation Layer. When you run the ZOWESVR PROC, it starts all these components. The Zowe Application
Server startup script also starts the zSS server, so starting the ZOWESVR PROC starts all the four servers,
and stopping it stops all four.

20 Open Beta for Zowe: Installation and User's Guide

Starting the ZOWESVR PROC
To start the ZOWESVR PROC, run the zowe-start.sh script at the Unix Systems Services command
prompt:
cd $ZOWE_ROOT_DIR/scripts
./zowe-start.sh

where $ZOWE_ROOT_DIR is the directory where you installed the Zowe runtime. This script starts the
ZOWESVR PROC for you so you don't have to log on to TSO and use SDSF.
Note: The default startup allows self signed and expired certiﬁcates from the Zowe Application
Framework proxy data services such as the explorer server.
If you prefer to use SDSF to start Zowe, start ZOWESVR by issuing the following operator command in
SDSF:
/S ZOWESVR

By default, Zowe uses the runtime version that you most recently installed. To start a different runtime,
specify its server path on the START command:
/S ZOWESVR,SRVRPATH='$ZOWE_ROOT_DIR/explorer-server'

To test whether the explorer server is active, open the URL https://:7443/explorermvs.
The port number 7443 is the default port and can be overridden through the zowe-install.yaml ﬁle
before the zowe-install.sh script is run. See Installing Zowe runtime on z/OS.
Stopping the ZOWESVR PROC
To stop the ZOWESVR PROC, run the zowe-stop.sh script at the Unix Systems Services command
prompt:
cd $ZOWE_ROOT_DIR/scripts
./zowe-stop.sh

If you prefer to use SDSF to stop Zowe, stop ZOWESVR by issuing the following operator command in
SDSF:
/C ZOWESVR

Either of the methods will stop the explorer server, the Zowe Application Server, and the zSS server.
When you stop the ZOWESVR, you might get the following error message:
IEE842I ZOWESVR DUPLICATE NAME FOUND- REENTER COMMAND WITH 'A='

This is because there is more than one started task named ZOWESVR. To resolve the issue, stop the
required ZOWESVR instance by issuing the following commands:
/C ZOWESVR,A=asid

You can obtain the asid from the value of A=asid when you issue the following commands:
/D A,ZOWESVR

Verifying installation
After you complete the installation of API Mediation, Zowe Application Framework, and explorer server,
use the following procedures to verify that the components are installed correctly and are functional.

Installing Zowe 21

Verifying Zowe Application Framework installation
If the Zowe Application Framework is installed correctly, you can open the Zowe Desktop from a
supported browser.
From a supported browser, open the Zowe Desktop at https://myhost:httpsPort/ZLUX/plugins/
com.rs.mvd/web/index.html
where:
• myHost is the host on which you installed the Zowe Application Server.
• httpPort is the port number that is assigned to node.http.port in zluxserver.json.
• httpsPort is the port number that is assigned to node.https.port in zluxserver.json. For example, if
the Zowe Application Server runs on host myhost and the port number that is assigned to node.http.port
is 12345, you specify https://myhost:12345/ZLUX/plugins/com.rs.mvd/web/index.htm.
Verifying explorer server installation
After explorer server is installed and the ZOWESVR procedure is started, you can verify the installation
from an Internet browser by using the following case-sensitive URL:
https://:/Atlas/api/system/version
where your.server is the host name or IP address of the z/OS® system where explorer server is installed,
and atlasport is the port number that is chosen during installation. You can verify the port number in
the server.xml ﬁle that is located in the explorer server installation directory, which is /var/zowe/
explorer-server/wlp/usr/servers/Atlas/server.xml by default. Look for the httpsPort
assignment in the server.xml ﬁle, for example: httpPort="7443".
This URL sends an HTTP GET request to the Liberty Proﬁle explorer server. If explorer server is installed
correctly, a JSON payload that indicates the current explorer server application version is returned. For
example:
{ "version": "V0.0.1" }

Note: The ﬁrst time that you interact with the explorer server, you are prompted to enter an MVS™ user ID
and password. The MVS user ID and password are passed over the secure HTTPS connection to establish
authentication.
After you verify that explorer server is successfully installed, you can access the UI at the following URLs:
• https://:/explorer-jes/#/
• https://:/explorer-mvs/#/
• https://:/explorer-uss/#/
If explorer server is not installed successfully, see Troubleshooting installation for solutions.
Verifying the availability of explorer server REST APIs
To verify the availability of all explorer server REST APIs, use the Liberty Proﬁle's REST API discovery
feature from an internet browser with the following URL. This URL is case-sensitive.
https://:/ibm/api/explorer
With the discovery feature, you can also try each discovered API. The users who verify the availability
must have access to their data sets and job information by using relevant explorer server APIs. This
ensures that your z/OSMF conﬁguration is valid, complete, and compatible with the explorer server
application. For example, try the following APIs:
Explorer server: JES Jobs APIs
GET /Atlas/api/jobs
This API returns job information for the calling user.
Explorer server: Data set APIs
22 Open Beta for Zowe: Installation and User's Guide

GET /Atlas/api/datasets/userid.**
This API returns a list of the userid.** MVS data sets.
Verifying API Mediation installation
Use your preferred REST API client to review the value of the status variable of the API Catalog service
that is routed through the API Gateway using the following URL:
https://hostName:basePort/api/v1/apicatalog/application/state

The hostName is set during install, and basePort is set as the gatewayHttpsPort parameter.
Example:
The following example illustrates how to use the curl utility to invoke API Mediation Layer endpoint and
the grep utility to parse out the response status variable value
$ curl -v -k --silent https://hostName:basePort/api/v1/apicatalog/application/state 2>&1 | grep
-Po '(?<=\"status\"\:\")[^\"]+'
UP

The response UP conﬁrms that API Mediation Layer is installed and is running properly.

Installing Zowe CLI
As a systems programmer or application developer, you install Zowe CLI on your PC.

Methods to install Zowe CLI
You can use either of the following methods to install Zowe CLI. - Install Zowe CLI from local package Install Zowe CLI from Bintray registry
Installing Zowe CLI from local package
Install Zowe CLI on PCs that are running a Windows, Linux, or macOS operating system.
Follow these steps:
1. Address the prerequisites.
2. Obtain the Zowe installation ﬁles, which includes the zowe-cli-bundle.zip ﬁle. Use FTP to distribute the
zowe-cli-bundle.zip ﬁle to client workstations.
3. Open a command line window. For example, Windows Command Prompt. Browse to the directory
where you downloaded the Zowe CLI installation bundle (.zip ﬁle). Issue the following command to
unzip the ﬁles:
unzip zowe-cli-bundle.zip

The command expands four TGZ packages into your working directory - Zowe CLI, one plug-in, and the
odbc_cli folder.
4. Issue the following command to install Zowe CLI on your PC:
npm install -g zowe-cli-2.0.0-next.201809251404

Note: On Windows, you must run as an Administrator to install the product and plug-ins.
Note: On Linux, you might need to prepend sudo to your npm commands so that you can issue the
install and uninstall commands. For more information, see Troubleshooting installing Zowe CLI.
Zowe CLI is installed on your PC. See Installing Plug-ins for information about the commands for
installing plug-ins from the package.
5. Create a zosmf proﬁle so that you can issue commands that communicate with z/OSMF.
Installing Zowe 23

Note: For information about how to create a proﬁle, see Creating a Zowe CLI proﬁle.
Tip: Zowe CLI proﬁles contain information that is required for the product to interact with remote
systems. For example, host name, port, and user ID. Proﬁles let you target unique systems, regions, or
instances for a command. Most Zowe CLI command groups require a Zowe CLI zosmf proﬁle.
After you install and conﬁgure Zowe CLI, you can issue the zowe --help command to view a list of
available commands. For more information, see Display Help.
Installing Zowe CLI from Bintray registry
If your PC is connected to the Internet, you can use the following method to install Zowe CLI from an npm
registry.
Follow these steps:
1. Issue the following command to set the registry to the Zowe CLI scoped package on Bintray. In
addition to setting the scoped registry, your non-scoped registry must be set to an npm registry that
includes all of the dependencies for Zowe CLI, such as the global npm registry:
npm config set @brightside:registry https://api.bintray.com/npm/ca/brightside

2. Issue the following command to install Zowe CLI from the registry:
npm install -g @brightside/core@next

Note: On Windows, you must run as an Administrator to install the product and plug-ins.
Zowe CLI is installed on your PC. For information about plug-ins for Zowe CLI, see Extending Zowe CLI.
3. (Optional) To install all available plug-ins to Zowe CLI, issue the following command:
bright plugins install @brightside/cics@next

4. Create a zosmf proﬁle so that you can issue commands that communicate with z/OSMF. For
information about how to create a proﬁle, see Creating a Zowe CLI proﬁle.
Tip: Zowe CLI proﬁles contain information that is required for the product to interact with remote
systems. For example, host name, port, and user ID. Proﬁles let you target unique systems, regions, or
instances for a command. Most Zowe CLI command groups require a Zowe CLI zosmf proﬁle.
After you install and conﬁgure Zowe CLI, you can issue the zowe --help command to view a list of
available commands. For more information, see How to display Zowe CLI help.
Note: You might encounter problems when you attempt to install Zowe CLI depending on your operating
system and environment. For more information and workarounds, see Troubleshooting installing Zowe
CLI.

Creating a Zowe CLI proﬁle
Proﬁles are a Zowe CLI functionality that let you store conﬁguration information for use on multiple
commands. You can create a proﬁle that contains your username, password, and connection details for a
particular mainframe system, then reuse that proﬁle to avoid typing it again on every command. You can
switch between proﬁles to quickly target different mainframe subsystems.
Important! A zosmf proﬁle is required to issue most Zowe CLI commands. The ﬁrst proﬁle that you
create becomes your default proﬁle. When you issue any command that requires a zosmf proﬁle, the
command executes using your default proﬁle unless you specify a speciﬁc proﬁle name on that command.
Follow these steps:
1. To create a zosmf proﬁle, issue the following command. Refer to the available options in the help text
to deﬁne your proﬁle:
zowe profiles create zosmf-profile --help

24 Open Beta for Zowe: Installation and User's Guide

Note: After you create a proﬁle, verify that it can communicate with z/OSMF. For more information, see
(#Testing Zowe CLI connection to z/OSMF).

Testing Zowe CLI connection to z/OSMF
After you conﬁgure a Zowe CLI zosmf proﬁle to connect to z/OSMF on your mainframe systems, you
can issue a command at any time to receive diagnostic information from the server and conﬁrm that your
proﬁle can communicate with z/OSMF.
Tip: In this documentation we provide command syntax to help you create a basic proﬁle. We recommend
that you append --help to the end of commands in the product to see the complete set of commands
and options available to you. For example, issue zowe profiles --help to learn more about how to
list proﬁles, switch your default proﬁle, or create different proﬁle types.
After you create a proﬁle, run a test to verify that Zowe CLI can communicate properly with z/OSMF. You
can test your default proﬁle and any other Zowe CLI proﬁle that you created.
Default proﬁle
• Verify that you can use your default proﬁle to communicate with z/OSMF by issuing the following
command:
zowe zosmf check status

Speciﬁc proﬁle
• Verify that you can use a speciﬁc proﬁle to communicate with z/OSMF by issuing the following
command:
zowe zosmf check status --zosmf-profile

The commands return a success or failure message and display information about your z/OSMF server.
For example, the z/OSMF version number and a list of installed plug-ins. Report any failure to your
systems administrator and use the information for diagnostic purposes.

Troubleshooting the installation
Review the following troubleshooting tips if you have problems with Zowe installation.

Troubleshooting installing the Zowe runtime
1. Environment variables
To prepare the environment for the Zowe runtime, a number of ZFS folders need to be located for
prerequisites on the platform that Zowe needs to operate. These can be set as environment variables
before the script is run. If the environment variables are not set, the install script will attempt to locate
default values.
• ZOWE_ZOSMF_PATH: The path where z/OSMF is installed. Defaults to /usr/lpp/zosmf/lib/
defaults/servers/zosmfServer
• ZOWE_JAVA_HOME: The path where 64 bit Java 8 or later is installed. Defaults to /usr/lpp/java/
J8.0_64
• ZOWE_EXPLORER_HOST: The IP address of where the explorer servers are launched from. Defaults
to running hostname -c
The ﬁrst time the script is run if it has to locate any of the environment variables, the script will add
lines to the current user's home directory .profile ﬁle to set the variables. This ensures that the
next time the same user runs the install script, the previous values will be used.
Note: If you wish to set the environment variables for all users, add the lines to assign the variables
and their values to the ﬁle /etc/.profile.
Installing Zowe 25

If the environment variables for ZOWE_ZOSMF_PATH, ZOWE_JAVA_HOME are not set and the install
script cannot determine a default location, the install script will prompt for their location. The install
script will not continue unless valid locations are provided.
2. Expanding the PAX ﬁles
The install script will create the Zowe runtime directory structure using the install:rootDir value
in the zowe-install.yaml ﬁle. The runtime components of the Zowe server are then unpaxed into
the directory that contains a number of directories and ﬁles that make up the Zowe runtime.
If the expand of the PAX ﬁles is successful, the install script will report that it ran its install step to
completion.
3. Changing Unix permissions
After the install script lay down the contents of the Zowe runtime into the rootDir, the next step is to
set the ﬁle and directory permissions correctly to allow the Zowe runtime servers to start and operate
successfully.
The install process will execute the ﬁle scripts/zowe-runtime-authorize.sh in the Zowe
runtime directory. If the script is successful, the result is reported. If for any reason the script fails
to run because of insufﬁcient authority by the user running the install, the install process reports
the errors. A user with sufﬁcient authority should then run the zowe-runtime-authorize.sh. If
you attempt to start the Zowe runtime servers without the zowe-runtime-authorize.sh having
successfully completed, the results are unpredictable and Zowe runtime startup or runtime errors will
occur.
4. Creating the PROCLIB member to run the Zowe runtime
Note: The name of the PROCLIB member might vary depending on the standards in place at each z/OS
site, however for this documentation, the PROCLIB member is called ZOWESVR.
At the end of the installation, a Unix ﬁle ZOWESVR.jcl is created under the directory where the
runtime is installed into, $INSTALL_DIR/files/templates. The contents of this ﬁle need to
be tailored and placed in a JCL member of the PROCLIB concatenation for the Zowe runtime to be
executed as a started task. The install script does this automatically, trying data sets USER.PROCLIB,
other PROCLIB data sets found in the PROCLIB concatenation and ﬁnally SYS1.PROCLIB.
If this succeeds, you will see a message like the following one:
PROC ZOWESVR placed in USER.PROCLIB
Otherwise you will see messages beginning with the following information:
Failed to put ZOWESVR.JCL in a PROCLIB dataset.
In this case, you need to copy the PROC manually. Issue the TSO oget command to copy the
ZOWESVR.jcl ﬁle to the preferred PROCLIB:
oget '$INSTALL_DIR/files/templates/ZOWESVR.jcl' 'MY.USER.PROCLIB(ZOWESVR)'
You can place the PROC in any PROCLIB data set in the PROCLIB concatenation, but some data sets
such as SYS1.PROCLIB might be restricted, depending on the permission of the user.
You can tailor the JCL at this line
//ZOWESVR PROC SRVRPATH='/zowe/install/path/explorer-server'
to replace the /zowe/install/path with the location of the Zowe runtime directory that contains
the explorer server. Otherwise you must specify that path on the START command when you start
Zowe in SDSF:
/S ZOWESVR,SRVRPATH='$ZOWE_ROOT_DIR/explorer-server'
Troubleshooting installing the Zowe Application Framework
To help Zowe research any problems you might encounter, collect as much of the following information as
possible and open an issue in GitHub with the collected information.
26 Open Beta for Zowe: Installation and User's Guide

• Zowe version and release level
• z/OS release level
• Job output and dump (if any)
• Javascript console output (Web Developer toolkit accessible by pressing F12)
• Log output from the Zowe Application Server
• Error message codes
• Screenshots (if applicable)
• Other relevant information (such as the version of Node.js that is running on the Zowe Application
Server and the browser and browser version).
Troubleshooting installing explorer server
If explorer server REST APIs do not function properly, check the following items:
• Check whether your Liberty explorer server is running.
You can check this in the Display Active (DA) panel of SDSF under ISPF. The ZOWESVR started task
should be running. If the ZOWESVR task is not running, start the explorer server by using the following
START operator command:
/S ZOWESVR

You can also use the operator command /D A,ZOWESVR to verify whether the task is active, which
alleviates the need for the DA panel of SDSF. If the started task is not running, ensure that your
ZOWESVR procedure resides in a valid PROCLIB data set, and check the task’s job output for errors.
• Check whether the explorer server is started without errors.
In the DA panel of SDSF under ISPF, select the ZOWESVR job to view the started task output. If the
explorer server is started without errors, you can see the following messages:
CWWKE0001I: The server Atlas has been launched.
CWWKF0011I: The server Atlas is ready to run a smarter planet.

If you see error messages that are preﬁxed with "ERROR" or stack traces in the ZOWESVR job output,
respond to them.
• Check whether the URL that you use to call explorer server REST APIs is correct. For example: https://
your.server:atlasport/Atlas/api/system/version. The URL is case-sensitive.
• Ensure that you enter a valid z/OS® user ID and password when initially connecting to the explorer
server.
• If testing the explorer server REST API for jobs information fails, check the z/OSMF IZUSVR1 task
output for errors. If no errors occur, you can see the following messages in the IZUSVR1 job output:
CWWKE0001I : The server zosmfServer has been launched.
CWWKF0011I: The server zosmfServer is ready to run a smarter planet.

If you see error messages, respond to them.
For RESTJOBS, you can see the following message if no errors occur:
CWWKZ0001I: Application IzuManagementFacilityRestJobs started in n.nnn seconds.

You can also call z/OSMF RESTJOBS APIs directly from your Internet browser with a URL, for example,
https://your.server:securezosmfport/zosmf/restjobs/jobs
where the securezosmfport is 443 by default. You can verify the port number by checking the
izu.https.port variable assignment in the z/OSMF bootstrap.properties ﬁle.
Installing Zowe 27

You might get error message IZUG846W, which indicates that a cross-site request forgery (CSRF) was
attempted. To resolve the issue, update your browser by adding the X-CSRF-ZOSMF-HEADER HTTP
custom header to every cross-site request. This header can be set to any value or an empty string ("").
For details, see the z/OSMF documentation. If calling the z/OSMF RESTJOBS API directly fails, ﬁx z/
OSMF before explorer server can use these APIs successfully.
• If testing the explorer server REST API for data set information fails, check the z/OSMF IZUSVR1 task
output for errors and conﬁrm that the z/OSMF RESTFILES services are started successfully. If no errors
occur, you can see the following message in the IZUSVR1 job output:
CWWKZ0001I: Application IzuManagementFacilityRestFiles started in n.nnn seconds.

You can also call z/OSMF RESTFILES APIs directly from your internet browser with a URL, for example,
https://your.server:securezosmfport/zosmf/restﬁles/ds?dslevel=userid.**
where the securezosmfport is 443 by default. You can verify the port number by checking the
izu.https.port variable assignment in the z/OSMF bootstrap.properties ﬁle.
You might get error message IZUG846W, which indicates that a cross-site request forgery (CSRF) was
attempted. To resolve the issue, update your browser by adding the X-CSRF-ZOSMF-HEADER HTTP
custom header to every cross-site request. This header can be set to any value or an empty string ("").
For details, see the z/OSMF documentation. If calling the z/OSMF RESTFILES API directly fails, ﬁx z/
OSMF before explorer server can use these APIs successfully.
Tip: The z/OSMF installation step of creating a valid IZUFPROC procedure in your system PROCLIB
might be missed. For more information, see the z/OSMF Conﬁguration Guide.
The IZUFPROC member resides in your system PROCLIB, which is similar to the following sample:
//IZUFPROC
//IZUFPROC
//SYSEXEC
//
//SYSPROC
//
//ISPLLIB
//ISPPLIB
//ISPTLIB
//
//ISPSLIB
//ISPMLIB
//ISPPROF
//
//IZUSRVMP
//SYSOUT
//CEEDUMP
//SYSUDUMP
//

PROC ROOT='/usr/lpp/zosmf' /* zOSMF INSTALL ROOT
*/
EXEC PGM=IKJEFT01,DYNAMNBR=200
DD DISP=SHR,DSN=ISP.SISPEXEC
DD DISP=SHR,DSN=SYS1.SBPXEXEC
DD DISP=SHR,DSN=ISP.SISPCLIB
DD DISP=SHR,DSN=SYS1.SBPXEXEC
DD DISP=SHR,DSN=SYS1.SIEALNKE
DD DISP=SHR,DSN=ISP.SISPPENU
DD RECFM=FB,LRECL=80,SPACE=(TRK,(1,0,1))
DD DISP=SHR,DSN=ISP.SISPTENU
DD DISP=SHR,DSN=ISP.SISPSENU
DD DISP=SHR,DSN=ISP.SISPMENU
DD DISP=NEW,UNIT=SYSDA,SPACE=(TRK,(15,15,5)),
DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
DD PATH='&ROOT./defaults/izurf.tsoservlet.mapping.json'
DD SYSOUT=H
DD SYSOUT=H
DD SYSOUT=H

Note: You might need to change paths and data sets names to match your installation.
A known issue and workaround for RESTFILES API can be found at TSO SERVLET EXCEPTION
ATTEMPTING TO USE RESTFILE INTERFACE.
• Check your system console log for related error messages and respond to them.
If the explorer server cannot connect to the z/OSMF server, check the following item:
By default, the explorer server communicates with the z/OSMF server on the localhost address. If your
z/OSMF server is on a different IP address to the explorer server, for example, if you are running z/OSMF
with Dynamic Virtual IP Addressing (DVIPA), you can change this by adding a ZOSMF_HOST parameter to
the server.env ﬁle. For example: ZOSMF_HOST=winmvs27.

Troubleshooting installing Zowe CLI
The following topics contain information that can help you troubleshoot problems when you encounter
unexpected behavior using Zowe CLI.

28 Open Beta for Zowe: Installation and User's Guide

npm install -gCommand Fails Due to an EPERM Error
Valid on Windows
Symptom:
This behavior is due to a problem with Node Package Manager (npm). There is an open issue on the npm
GitHub repository to ﬁx the defect.
Solution:
If you encounter this problem, some users report that repeatedly attempting to install Zowe CLI yields
success. Some users also report success using the following workarounds:
• Issue the npm cache clean command.
• Uninstall and reinstall Zowe CLI. For more information, see Install Zowe CLI.
• Add the --no-optional flag to the end of the npm install command.
Sudo syntax required to complete some installations
Valid on Linux
Symptom:
The installation fails on Linux.
Solution:
Depending on how you conﬁgured Node.js on Linux or Mac, you might need to add the preﬁx sudo before
the npm install -g command or the npm uninstall -g command. This step gives Node.js write
access to the installation directory.
npm install -g command fails due to npm ERR! Cannot read property 'pause' of undeﬁned error
Valid on Windows or Linux
Symptom:
You receive the error message npm ERR! Cannot read property 'pause' of undefined when
you attempt to install the product.
Solution:
This behavior is due to a problem with Node Package Manager (npm). If you encounter this problem,
revert to a previous version of npm that does not contain this defect. To revert to a previous version of
npm, issue the following command:
npm install npm@5.3.0 -g

Node.js commands do not respond as expected
Valid on Windows or Linux
Symptom:
You attempt to issue node.js commands and you do not receive the expected output.
Solution:
There might be a program that is named *node* on your path. The Node.js installer automatically
adds a program that is named *node* to your path. When there are pre-existing programs that are
named *node* on your computer, the program that appears ﬁrst in the path is used. To correct this
behavior, change the order of the programs in the path so that Node.js appears ﬁrst.
Installation fails on Oracle Linux 6
Valid on Oracle Linux 6
Symptom:
Installing Zowe 29

You receive error messages when you attempt to install the product on an Oracle Linux 6 operating
system.
Solution:
Install the product on Oracle Linux 7 or another Linux or Windows OS. Zowe CLI is not compatible with
Oracle Linux 6.

Uninstalling Zowe
You can uninstall Zowe if you no longer need to use it. Follow these procedures to uninstall each Zowe
component.
• Uninstalling the Zowe Application Framework
• Uninstalling explorer server
• Uninstalling API Mediation Layer
• Uninstalling Zowe CLI

Uninstalling the Zowe Application Framework
Follow these steps:
1. The Zowe Application Server (zlux-server) runs under the ZOWESVR started task, so it should
terminate when ZOWESVR is stopped. If it does not, use one of the following standard process signals
to stop the server:
• SIGHUP
• SIGTERM
• SIGKILL
2. Delete or overwrite the original directories. If you modiﬁed the zluxserver.json ﬁle so that it points
to directories other than the default directories, do not delete or overwrite those directories.

Uninstalling explorer server
Follow these steps:
1. Stop your Explorer Liberty server by running the following operator command:
C ZOWESVR

2. Delete the ZOWESVR member from your system PROCLIB data set.
To do this, you can issue the following TSO DELETE command from the TSO READY prompt or from
ISPF option 6:
delete 'your.zowe.proclib(zowesvr)'

Alternatively, you can issue the TSO DELETE command at any ISPF command line by preﬁxing the
command with TSO:
tso delete 'your.zowe.proclib(zowesvr)'

To query which PROCLIB data set that ZOWESVR is put in, you can view the SDSF JOB log of ZOWESVR
and look for the following message:
IEFC001I PROCEDURE ZOWESVR WAS EXPANDED USING SYSTEM LIBRARY your.zowe.proclib

If no ZOWESVR JOB log is available, issue the /$D PROCLIB command at the SDSF COMMAND INPUT
line and BROWSE each of the DSNAME=some.jes.proclib output lines in turn with ISPF option 1,

30 Open Beta for Zowe: Installation and User's Guide

until you ﬁnd the ﬁrst data set that contains member ZOWESVR. Then issue the DELETE command as
shown above.
3. Remove RACF® (or equivalent) deﬁnitions with the following command:
RDELETE STARTED (ZOWESVR.*)
SETR RACLIST(STARTED) REFRESH
REMOVE (userid) GROUP(IZUUSER)

where userid indicates the user ID that is used to install Zowe.
4. Delete the z/OS® UNIX™ System Services explorer server directory and ﬁles from the explorer server
installation directory by issuing the following command:
rm -R /var/zowe #*Explorer Server Installation Directory*

Or
rm -R /var/zowe/ #*Explorer Server Installation Directory*

Where indicates the package version such as 0.9.0.
Notes:
• You might need super user authority to run this command.
• You must identify the explorer server installation directory correctly. Running a recursive remove
command with the wrong directory name might delete critical ﬁles.

Uninstalling API Mediation Layer
Note: Be aware of the following considerations:
• You might need super-user authority to run this command.
• You must identify the API Mediation installation directory correctly. Running a recursive remove
command with the incorrect directory name can delete critical ﬁles.
Follow these steps:
1. Stop your API Mediation Layer services using the following command:
C ZOWESVR

Alternatively, you can issue the TSO DELETE command at any ISPF command line by preﬁxing the
command with TSO:
tso delete 'your.zowe.proclib(zowesvr)'

If no ZOWESVR JOB log is available, issue the /$D PROCLIB command at the SDSF COMMAND INPUT
line and BROWSE each of the DSNAME=some.jes.proclib output lines in turn with ISPF option 1,
until you ﬁnd the ﬁrst data set that contains member ZOWESVR. Then issue the DELETE command as
shown above.

Installing Zowe 31

3. Remove RACF® (or equivalent) deﬁnitions using the following command:
RDELETE STARTED (ZOWESVR.*)
SETR RACLIST(STARTED) REFRESH
REMOVE (userid) GROUP(IZUUSER)

where userid indicates the user ID that is used to install Zowe.
4. Delete the z/OS® UNIX™ System Services API Mediation Layer directory and ﬁles from the API
Mediation Layer installation directory using the following command:
rm -R /var/zowe_install_directory/api-mediation #*Zowe Installation Directory*

Uninstalling Zowe CLI
Important! The uninstall process does not delete the proﬁles and credentials that you created when
using the product from your PC. To delete the proﬁles from your PC, delete them before you uninstall
Zowe CLI.
The following steps describe how to list the proﬁles that you created, delete the proﬁles, and uninstall
Zowe CLI.
Follow these steps:
1. Open a command line window.
Note: If you do not want to delete the Zowe CLI proﬁles from your PC, go to Step 5.
2. List all proﬁles that you created for a Command Group by issuing the following command:
zowe profiles list

Example:
$ zowe profiles list zosmf
The following profiles were found for the module zosmf:
'SMITH-123' (DEFAULT)
smith-123@SMITH-123-W7 C:\Users\SMITH-123
$

3. Delete all of the proﬁles that are listed for the command group by issuing the following command:
Tip: For this command, use the results of the list command.
Note: When you issue the delete command, it deletes the speciﬁed proﬁle and its credentials from
the credential vault in your PC's operating system.
zowe profiles delete --force

Example:
zowe profiles delete zosmf SMITH-123 --force

4. Repeat Steps 2 and 3 for all Zowe CLI command groups and proﬁles.
5. Uninstall Zowe CLI by issuing one of the following commands:
• If you installed Zowe CLI from the package, issue the following command
npm uninstall --global @brightside/core

• If you installed Zowe CLI from the online registry, issue the following command:
npm uninstall --global brightside

The uninstall process removes all Zowe CLI installation directories and ﬁles from your PC.

32 Open Beta for Zowe: Installation and User's Guide

6. Delete the C:\Users\\.brightside directory on your PC. The directory contains the
Zowe CLI log ﬁles and other miscellaneous ﬁles that were generated when you used the product.
Tip: Deleting the directory does not harm your PC.
7. If you installed Zowe CLI from the online registry, issue the following command to clear your scoped
npm registry:
npm config set @brightside:registry

Installing Zowe 33

34 Open Beta for Zowe: Installation and User's Guide

Chapter 3. Conﬁguring Zowe
Follow these procedures to conﬁgure the components of Zowe.

Zowe Application Framework (zLUX) conﬁguration
After you install Zowe, you can optionally conﬁgure the terminal application plug-ins or modify the Zowe
Application Server (zLUX Proxy Server) and ZSS conﬁguration, if needed.

Setting up terminal application plug-ins
Follow these optional steps to conﬁgure the default connection to open for the terminal application plugins.
Setting up the TN3270 mainframe terminal application plug-in
_defaultTN3270.json is a ﬁle in tn3270-ng2/, which is deployed during setup. Within this ﬁle, you
can specify the following parameters to conﬁgure the terminal connection:

}

"host":
"port":
“security”: {
type: <”telnet” or “tls”>

Setting up the VT Terminal application plug-in
_defaultVT.json is a ﬁle in vt-ng2/, which is deployed during setup. Within this ﬁle, you can specify
the following parameters to conﬁgure the terminal connection:
“host”:
“port”:
“security”: {
type: <”telnet” or “ssh”>
}

Conﬁguring the zLUX Proxy Server and ZSS
Conﬁguration ﬁle
The zLUX Proxy Server and ZSS rely on many parameters to run, which includes setting up networking,
deployment directories, plug-in locations, and more.
For convenience, the zLUX Proxy Server and ZSS read from a JSON ﬁle with a common structure. ZSS
reads this ﬁle directly as a startup argument, while the zLUX Proxy Server as deﬁned in the zlux-proxyserver repository accepts several parameters, which are intended to be read from a JSON ﬁle through
an implementer of the server, such as the example in the zlux-example-server repository, the
js/zluxServer.js ﬁle. This ﬁle accepts a JSON ﬁle that speciﬁes most, if not all, of the parameters
needed. Other parameters can be provided through flags, if needed.
An example JSON ﬁle can be found in the zlux-example-server repository, in the zluxserver.json in
the config directory.
Note: All examples are based on the zlux-example-server repository.
Network conﬁguration
Note: The following attributes are to be deﬁned in the server's JSON conﬁguration ﬁle.

The zLUX Proxy Server can be accessed over HTTP, HTTPS, or both, provided it has been conﬁgured for
either (or both).
HTTP
To conﬁgure the server for HTTP, complete these steps:
1. Deﬁne an attribute http within the top-level node attribute.
2. Deﬁne port within http. Where port is an integer parameter for the TCP port on which the server will
listen. Specify 80 or a value between 1024-65535.
HTTPS
For HTTPS, specify the following parameters:
1. Deﬁne an attribute https within the top-level node attribute.
2. Deﬁne the following within https:
• port: An integer parameter for the TCP port on which the server will listen. Specify 443 or a value
between 1024-65535.
• certiﬁcates: An array of strings, which are paths to PEM format HTTPS certiﬁcate ﬁles.
• keys: An array of strings, which are paths to PEM format HTTPS key ﬁles.
• pfx: A string, which is a path to a PFX ﬁle which must contain certiﬁcates, keys, and optionally Certiﬁcate
Authorities.
• certiﬁcateAuthorities (Optional): An array of strings, which are paths to certiﬁcate authorities ﬁles.
• certiﬁcateRevocationLists (Optional): An array of strings, which are paths to certiﬁcate revocation list
(CRL) ﬁles.
Note: When using HTTPS, you must specify pfx, or both certiﬁcates and keys.
Network example
In the example conﬁguration, both HTTP and HTTPS are speciﬁed:
"node": {
"https": {
"port": 8544,
//pfx (string), keys, certificates, certificateAuthorities, and certificateRevocationLists
are all valid here.
"keys": ["../deploy/product/ZLUX/serverConfig/server.key"],
"certificates": ["../deploy/product/ZLUX/serverConfig/server.cert"]
},
"http": {
"port": 8543
}
}

Deploy conﬁguration
When the zLUX Proxy Server is running, it accesses the server's settings and reads or modiﬁes the
contents of its resource storage. All of this data is stored within the Deploy folder hierarchy, which is
spread out into a several scopes:
• Product: The contents of this folder are not meant to be modiﬁed, but used as defaults for a product.
• Site: The contents of this folder are intended to be shared across multiple zLUX Proxy Server
instances, perhaps on a network drive.
• Instance: This folder represents the broadest scope of data within the given zLUX Proxy Server
instance.
• Group: Multiple users can be associated into one group, so that settings are shared among them.
• User: When authenticated, users have their own settings and storage for the application plug-ins that
they use.
These directories dictate where the Conﬁguration Dataservice stores content.
36 Open Beta for Zowe: Installation and User's Guide

Deploy example
// All paths relative to zlux-example-server/js or zlux-example-server/bin
// In real installations, these values will be configured during the installation process.
"rootDir":"../deploy",
"productDir":"../deploy/product",
"siteDir":"../deploy/site",
"instanceDir":"../deploy/instance",
"groupsDir":"../deploy/instance/groups",
"usersDir":"../deploy/instance/users"

Application plug-in conﬁguration
This topic describes application plug-ins that are deﬁned in advance.
In the conﬁguration ﬁle, you can specify a directory that contains JSON ﬁles, which tell the server what
application plug-in to include and where to ﬁnd it on disk. The backend of these application plug-ins use
the server's plug-in structure, so much of the server-side references to application plug-ins use the term
plug-in.
To include application plug-ins, deﬁne the location of the plug-ins directory in the conﬁguration ﬁle,
through the top-level attribute pluginsDir.
Note: In this example, the directory for these JSON ﬁles is /plugins. Yet, to separate conﬁguration
ﬁles from runtime ﬁles, the zlux-example-server repository copies the contents of this folder into /
deploy/instance/ZLUX/plugins. So, the example conﬁguration ﬁle uses the latter directory.
Plug-ins directory example
// All paths relative to zlux-example-server/js or zlux-example-server/bin
// In real installations, these values will be configured during the install process.
//...
"pluginsDir":"../deploy/instance/ZLUX/plugins",

Logging conﬁguration
For more information, see Logging Utility.
ZSS conﬁguration
Running ZSS requires a JSON conﬁguration ﬁle that is similar or the same as the one used for the zLUX
Proxy Server. The attributes that are needed for ZSS, at minimum, are:*rootDir*, productDir, siteDir,
instanceDir, groupsDir, usersDir, pluginsDir and zssPort. All of these attributes have the same meaning as
described above for the server, but if the zLUX Proxy Server and ZSS are not run from the same location,
then these directories can be different.
The zssPort attribute is speciﬁc to ZSS. This is the TCP port on which ZSS listens in order to be contacted
by the zLUX Proxy Server. Deﬁne this port in the conﬁguration ﬁle as a value between 1024-65535.
Connecting the zLUX Proxy Server to ZSS
When you run the zLUX Proxy Server, specify the following flags to declare which ZSS instance the Zowe
Application Framework will proxy ZSS requests to:
• -h: Declares the host where ZSS can be found. Use as "-h "
• -P: Declares the port at which ZSS is listening. Use as "-P "

Zowe Application Framework logging
The Zowe Application Framework log ﬁles contain processing messages and statistics. The log ﬁles are
generated in the following default locations:
• Zowe Proxy Server: zlux-example-server/log/nodeServer-yyyy-mm-dd-hh-mm.log
• ZSS: zlux-example-server/log/zssServer-yyyy-mm-dd-hh-mm.log

Conﬁguring Zowe 37

The logs are timestamped in the format yyyy-mm-dd-hh-mm and older logs are deleted when a new log is
created at server startup.
Controlling the logging location
The log information is written to a ﬁle and to the screen. (On Windows, logs are written to a ﬁle only.)
ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR environment variables
To control where the information is logged, use the environment variable ZLUX_NODE_LOG_DIR, for the
zLUX Proxy Server, and ZSS_LOG_DIR, for ZSS. While these variables are intended to specify a directory, if
you specify a location that is a ﬁle name, Zowe will write the logs to the speciﬁed ﬁle instead (for example:
/dev/null to disable logging).
When you specify the environment variables ZLUX_NODE_LOG_DIR and ZSS_LOG_DIR and you specify
directories rather than ﬁles, Zowe will timestamp the logs and delete the older logs that exceed the
ZLUX_NODE_LOGS_TO_KEEP threshold.
ZLUX_NODE_LOG_FILE and ZSS_LOG_FILE environment variables
If you set the log ﬁle name for the zLUX Proxy Server by setting the ZLUX_NODE_LOG_FILE environment
variable, or if you set the log ﬁle for ZSS by setting the ZSS_LOG_FILE environment variable, there will only
be one log ﬁle, and it will be overwritten each time the server is launched.
Note: When you set the ZLUX_NODE_LOG_FILE or ZSS_LOG_FILE environment variables, Zowe will not
override the log names, set a timestamp, or delete the logs.
If the directory or ﬁle cannot be created, the server will run (but it might not perform logging properly).
Retaining logs
By default, the last ﬁve logs are retained. To specify a different number of logs to retain, set
ZLUX_NODE_LOGS_TO_KEEP (zLUX Proxy Server logs) or ZSS_LOGS_TO_KEEP (ZSS logs) to the number of
logs that you want to keep. For example, if you set ZLUX_NODE_LOGS_TO_KEEP to 10, when the eleventh
log is created, the ﬁrst log is deleted.

Conﬁguring Zowe CLI
After you install Zowe, you can optionally perform Zowe CLI conﬁgurations.

Setting environment variables for Zowe CLI
You can set environment variables on your operating system to modify Zowe CLI behavior, such as the log
level and the location of the .brightside directory, where the logs, proﬁles, and plug-ins are stored. Refer
to your PC operating system documentation for information about how to set environmental variables.
Setting log levels
You can set the log level to adjust the level of detail that is written to log ﬁles:
Important! Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For
example, command line arguments will be logged when TRACE is set.
Environment Variable

Description

Values

Default

BRIGHTSIDE\_APP
\_LOG\_LEVEL

Zowe CLI logging level

Log4JS log levels (OFF,
TRACE, DEBUG, INFO,
WARN, ERROR, FATAL)

DEBUG

BRIGHTSIDE
\_IMPERATIVE\_LOG
\_LEVEL

Imperative CLI
Log4JS log levels (OFF,
Framework logging level TRACE, DEBUG, INFO,
WARN, ERROR, FATAL)

DEBUG

38 Open Beta for Zowe: Installation and User's Guide

Setting the .brightside directory
You can set the location on your PC where Zowe CLI creates the .brightside directory, which contains log
ﬁles, proﬁles, and plug-ins for the product:
Environment Variable

Description

Values

Default

BRIGHTSIDE\_CLI
\_HOME

Zowe CLI home
directory location

Any valid path on your
PC

Your PC default home
directory

Conﬁguring Zowe 39

40 Open Beta for Zowe: Installation and User's Guide

Chapter 4. Using Zowe
After you install and start Zowe, you can perform tasks with each component. See the following sections
for details.

Using the Zowe Desktop
You can use the Zowe Application Framework to create application plug-ins for the Zowe Desktop. For
more information, see Exending the Zowe Application Framework.

Navigating the Zowe Desktop
From the Zowe Desktop, you can access Zowe applications.
Accessing the Zowe Desktop
From a supported browser, open the Zowe Desktop at https://myhost:httpsPort/ZLUX/plugins/
com.rs.mvd/web/index.html
where:
• myHost is the host on which you are running the Zowe Application Server.
• httpsPort is the value that was assigned to node.https.port in zluxserver.json. For example, if
you run the Zowe Application Server on host myhost and the value that is assigned to node.https.port
in zluxserver.json is 12345, you would specify https://myhost:12345/ZLUX/plugins/
com.rs.mvd/web/index.html.
Logging in and out of the Zowe Desktop
1. To log in, enter your mainframe credentials in the Username and Password ﬁelds.
2. Press Enter. Upon authentication of your user name and password, the desktop opens.
To log out, click the the avatar in the lower right corner and click Sign Out.
Pinning applications to the task bar
1. Click the Start menu.
2. Locate the application you want to pin.
3. Right-click the on the application icon and select Pin to taskbar.

Using Explorers within the Zowe Application Framework
The explorer server provides a sample web client that can be used to view and manipulate the Job Entry
Subsystem (JES), data sets, z/OS UNIX System Services (USS), and System log.
The following views are available from the explorer server Web UI and are accessible via the explorer
server icon located in the application draw of Zowe Desktop (Navigation between views can be performed
using the menu draw located in the top left corner of the explorer server Web UI):
JES Explorer
Use this view to query JES jobs with ﬁlters, and view the related steps, ﬁles, and status. You can also
purge jobs from this view.
Data set Explorer
Use this view to browse the MVS™ ﬁle system by using a high-level qualiﬁer ﬁlter. With the Dataset
Explorer, you can complete the following tasks:

• List the members of partitioned data sets.
• Create new data sets using attributes or the attributes of an existing data set ("Allocate Like").
• Submit data sets that contain JCL to Job Entry Subsystem (JES).
• Edit sequential data sets and partitioned data set members with basic syntax highlighting and content
assist for JCL and REXX.
• Conduct basic validation of record length when editing JCL.
• Delete data sets and members.
• Open data sets in full screen editor mode, which gives you a fully qualiﬁed link to that ﬁle. The link is
then reusable for example in help tickets.
UNIX ﬁle Explorer
Use this view to browse the USS ﬁles by using a path. With the UNIX ﬁle Explorer, you can complete the
following tasks:
• List ﬁles and folders.
• Create new ﬁles and folders.
• Edit ﬁles with basic syntax highlighting and content assist for JCL and REXX.
• Delete ﬁles and folders.

Zowe Application Framework application plug-ins
Application plug-ins are applications that you can use to access the mainframe and to perform various
tasks. Developers can create application plug-ins using a sample application as a guide. The following
application plug-ins are installed by default:
Hello World Sample
The Hello World sample application plug-in for developers demonstrates how to create a dataservice and
how to create an application plug-in using Angular.
IFrame Sample
The IFrame sample application plug-in for developers demonstrates how to embed pre-made webpages
within the desktop as an application and how an application can request an action of another application
(see the source code for more information).
z/OS Subsystems
This z/OS Subsystems plug-in helps you ﬁnd information about the important services on the mainframe,
such as CICS, Db2, and IMS.
TN3270
This TN3270 plug-in provides a 3270 connection to the mainframe on which the Zowe Application Server
runs.
VT Terminal
The VT Terminal plug-in provides a connection to UNIX System Services and UNIX.
API Catalog
The API Catalog plug-in lets you view API services that have been discovered by the API Mediation
Layer. For more information about the API Mediation Layer, Discovery Service, and API Catalog, see API
Mediation Layer Overview.
Workflows
From the Workflows application plug-in you can create, manage, and use z/OSMF workflows to manage
your system.
42 Open Beta for Zowe: Installation and User's Guide

Using the Workflows application plug-in
The Workflows application plug-in is available from the Zowe Deskstop Start menu. To launch Workflows,
click the Start menu in the lower-left corner of the desktop and click the Workflows application plug-in
icon. The Users/Tasks Workflows window opens.
To refresh the display, click the circular arrow in the upper right corner of the window.
Conﬁguration
From the Conﬁguration tab, you can view, add, and remove servers.
Adding a z/OSMF server
Complete these steps to add a new z/OSMF server:
1. Click the Conﬁguration tab.
2. Click the plus sign (+) on the left side of the window.
3. In the Host ﬁeld, type the name of the host.
4. In the Port ﬁeld, type the port number.
5. Click OK.
To test the connection, click Test. When the server is online the Online indicator next to the server Host
and Port is green.
Setting a server as the default z/OSMF server
Complete these steps to set a default z/OSMF server:
1. Click Set as default.
2. Enter your user ID and password.
3. Click Sign in.
Note: You must specify a default server.
Removing a server
To remove a server, click x next to the server in the list that you want to remove.
Workflows
Click the Workflows tab to display all workflows on the system.
Tip: To search for a particular workflow, type the search string in the search box in the upper right portion
of the tab.
The following information is displayed on the Workflows tab.
Workflow
The name of the workflow.
Description
The description of the workflow.
Version
The version number.
Owner
The user ID of the workflow owner.
System
The system identiﬁer.
Using Zowe 43

Status
The status of the workflow (for example, In progress, Completed, and so on.)
Progress
Progress indicator.
Deﬁning a workflow
Complete these steps to deﬁne a workflow: 1. From the Workflows tab, click Action in the upper left
corner of the tab. 2. Click New workflow. 3. Specify the Name, Workflow deﬁnition ﬁle, System, and
Owner. 4. Click OK.
Viewing tasks
To view your tasks, click the My Tasks tab. This tab displays Workflow tasks that belong to you. You can
choose to view Pending, Completed, or All tasks. Workflows that have tasks that are assigned to you are
shown on the left side of the window. For each workflow, you can click the arrow to expand or collapse
the task list. Your assigned tasks display below each workflow. Hovering over each task displays more
information about the task, such as the status and the owner.
Each task has a indicator of PERFORM (a step needs to be performed) or CHECK (Check the step that was
performed). Clicking CHECK or PERFORM opens a work area on the right side of the window.
Note: When a task is complete, a green clipboard icon with a checkmark is displayed.
Hovering over the task description in the title bar of the work area window on the right side displays more
information corresponding workflow and the step description.
Task work area
When you click CHECK or PERFORM a work area on the right side of the window is displayed.
• When you click CHECK, you can view the JESMSGLG, JESJCL, JESYSMSG, or SYSTSPRT that is
associated with the selected task.
• When you click PERFORM, you can use the work area to perform the steps associated with the selected
task. Click Next to advance to the next step for the task.
Viewing warnings
Click the Warnings tab to view any warning messages that were encountered.
The following information is displayed on the Warnings tab.
Message Code
The message code that is associated with the warning.
Description
A description of the warning.
Date
The date of the warning.
Corresponding Workflow
The workflow that is associated with the warning.

Using APIs
Access and modify your z/OS resources such as jobs, data sets, z/OS UNIX System Services ﬁles by using
APIs.

44 Open Beta for Zowe: Installation and User's Guide

Using explorer server REST APIs
Explorer server REST APIs provide a range of REST APIs through a Swagger deﬁned description, and a
simple interface to specify API endpoint parameters and request bodies along with the response body
and return code. With explorer server REST APIs, you can see the available API endpoints and try the
endpoints within a browser. Swagger documentation is available from an Internet browser with a URL, for
example, https://your.host:atlas-port/ibm/api/explorer.
Data set APIs
Use data set APIs to create, read, update, delete, and list data sets. See the following table for the
operations available in data set APIs and their descriptions and prerequisites.
REST API

Description

Prerequisite

GET /Atlas/api/datasets/
{filter}

Get a list of data sets by ﬁlter.
Use this API to get a starting
list of data sets, for example,
userid.**.

z/OSMF restﬁles

GET /Atlas/api/datasets/
{dsn}/attributes

Retrieve attributes of a data
set(s). If you have a data set
name, use this API to determine
attributes for a data set name.
For example, it is a partitioned
data set.

z/OSMF restﬁles

GET /Atlas/api/datasets/
{dsn}/members

Get a list of members for a
partitioned data set. Use this
API to get a list of members of a
partitioned data set.

z/OSMF restﬁles

GET /Atlas/api/datasets/
{dsn}/content

Read content from a data set
z/OSMF restﬁles
or member. Use this API to
read the content of a sequential
data set or partitioned data set
member. Or use this API to return
a checksum that can be used
on a subsequent PUT request to
determine if a concurrent update
has occurred.

PUT /Atlas/api/datasets/
{dsn}/content

Write content to a data set or
z/OSMF restﬁles
member. Use this API to write
content to a sequential data set
or partitioned data set member.
If a checksum is passed and it
does not match the checksum
that is returned by a previous GET
request, a concurrent update has
occurred and the write fails.

POST /Atlas/api/datasets/ Create a data set. Use this API to z/OSMF restﬁles
{dsn}
create a data set according to the
attributes that are provided. The
API uses z/OSMF to create the
data set and uses the syntax and
rules that are described in the z/
OSMF Programming Guide.

Using Zowe 45

REST API

Description

POST /Atlas/api/datasets/ Create a data set by using the
{dsn}/{basedsn}
attributes of a given base data
set. When you do not know the
attributes of a new data set, use
this API to create a new data set
by using the same attributes as
an existing one.
DELETE /Atlas/api/
datasets/{dsn}

Prerequisite
z/OSMF

Delete a data set or member. Use z/OSMF restﬁles
this API to delete a sequential
data set or partitioned data set
member.

Job APIs
Use Jobs APIs to view the information and ﬁles of jobs, and submit and cancel jobs. See the following
table for the operations available in Job APIs and their descriptions and prerequisites.
REST API

Description

GET /Atlas/api/jobs

Get a list of jobs. Use this API to z/OSMF restjobs
get a list of job names that match
a given preﬁx, owner, or both.

GET /Atlas/api/jobs/
{jobName}/ids

Get a list of job identiﬁers for a
given job name. If you have a list
of existing job names, use this
API to get a list of job instances
for a given job name.

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
steps

Get job steps for a given job. With z/OSMF restjobs
a job name and job ID, use this
API to get a list of the job steps,
which includes the step name,
the executed program, and the
logical step number.

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
steps/{stepNumber}/dds

Get data set deﬁnitions (DDs)
z/OSMF restjobs
for a given job step. If you know
a step number for a given job
instance, use this API to get a list
of the DDs for a given job step,
which includes the DD name, the
data sets that are described by
the DD, the original DD JCL, and
the logical order of the DD in the
step.

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
files

Get a list of output ﬁle names
for a job. Job output ﬁles have
associated DSIDs. Use this API
to get a list of the DSIDs and
DD name of a job. You can use
the DSIDs and DD name to read
speciﬁc job output ﬁles.

46 Open Beta for Zowe: Installation and User's Guide

Prerequisite

z/OSMF restjobs

REST API

Description

Prerequisite

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
files/{fileId}

Read content from a speciﬁc job
output ﬁle. If you have a DSID or
ﬁeld for a given job, use this API
to read the output ﬁle's content.

z/OSMF restjobs

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
files/{fileId}/tail

Read the tail of a job's output ﬁle. z/OSMF restjobs
Use this API to request a speciﬁc
number of records from the tail of
a job output ﬁle.

GET /Atlas/api/jobs/
{jobName}/ids/{jobId}/
subsystem

Get the subsystem type for a job. z/OSMF restjobs
Use this API to determine the
subsystem that is associated with
a given job. The API examines the
JCL of the job to determine if the
executed program is CICS®, Db2®,
IMS™, or IBM® MQ.

POST /Atlas/api/jobs

Submit a job and get the job ID
back. Use this API to submit a
partitioned data set member or
UNIX™ ﬁle.

z/OSMF restjobs

DELETE /Atlas/api/jobs/
{jobName}/{jobId}

Cancel a job and purge its
associated ﬁles. Use this API to
purge a submitted job and the
logged output ﬁles that it creates
to free up space.

z/OSMF Running Common
Information Model (CIM) server

System APIs
Use System APIs to view the version of explorer server. See the following table for available operations
and their descriptions and prerequisites.
REST API

Description

Prerequisite

GET /Atlas/api/system/
version

Get the current explorer server
version. Use this API to get the
current version of the explorer
server microservice.

None

USS File APIs
Use USS File APIs to create, read, update, and delete USS ﬁles. See the following table for the available
operations and their descriptions and prerequisites.
REST API

Description

Prerequisite

POST /Atlas/api/uss/files Use this API to create new USS
directories and ﬁles.

z/OSMF restﬁles

DELETE /Atlas/api/uss/
files{path}

Use this API to delete USS
directories and ﬁles.

z/OSMF resﬁles

GET /Atlas/api/files/
{path}

Use this API to get a list of ﬁles in z/OSMF restﬁles
a USS directory along with their
attributes.

GET /Atlas/api/files/
{path}/content

Use this API to get the content of
a USS ﬁle.

z/OSMF restﬁles

Using Zowe 47

REST API

Description

Prerequisite

PUT /Atlas/api/files/
{path}/content

Use this API to update the
content of a USS ﬁle.

z/OSMF resﬁles

z/OS System APIs
Use z/OS system APIs to view information about PARMLIB, SYSPLEX, and USER. See the following table
for available operations and their descriptions and prerequisites.
REST API

Description

Prerequisite

GET /Atlas/api/zos/
parmlib

Get system PARMLIB
information. Use this API to
get the PARMLIB data set
concatenation of the target z/OS
system.

None

GET /Atlas/api/zos/
sysplex

Get target system sysplex and
system name. Use this API to get
the system and sysplex names.

None

GET /Atlas/api/zos/
username

Get current userid. Use this API
to get the current user ID.

None

Programming explorer server REST APIs
You can program explorer server REST APIs by referring to the examples in this section.
Sending a GET request in Java
Here is sample code to send a GET request to explorer server in Java™.
public class JobListener implements Runnable {
/*
*
Perform an HTTPs GET at the given jobs URL and credentials
*
targetURL e.g "https://host:port/Atlas/api/jobs?owner=IBMUSER&prefix=*"
*
credentials in the form of base64 encoded string of user:password
*/
private String executeGET(String targetURL, String credentials) {
HttpURLConnection connection = null;
try {
//Create connection
URL url = new URL(targetURL);
connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", credentials);
//Get Response
InputStream inputStream = connection.getInputStream();
BufferedReader bufferedReader = new BufferedReader(new
InputStreamReader(inputStream));
StringBuilder response = new StringBuilder();
String line;
//Process the response line by line
while ((line = bufferedReader.readLine()) != null) {
System.out.println(line);
}
//Cleanup
bufferedReader.close();
//Return the response message
return response.toString();
} catch (Exception e) {
//handle any error(s)
} finally {
//Cleanup
if (connection != null) {

48 Open Beta for Zowe: Installation and User's Guide

}

connection.disconnect();

Sending a GET request in JavaScript
Here is sample code written in JavaScript™ using features from ES6 to send a GETrequest to explorer
server.
const BASE_URL = 'hostname.com:port/Atlas/api';
// Call the jobs GET api to get all jobs with the userID IBMUSER
function getJobs(){
let parameters = "prefix=*&owner=IBMUSER";
let contentURL = `${BASE_URL}/jobs?${parameters}`;
let result = fetch(contentURL, {credentials: "include"})
.then(response => response.json())
.catch((e) => {
//handle any error
console.log("An error occoured: " + e);
});
return result;
}

Sending a POST request in JavaScript
Here is sample code written in JavaScript™ using features from ES6 to send a POST request to explorer
server.
// Call the jobs POST api to submit a job from a data set (ATLAS.TEST.JCL(TSTJ0001))
function submitJob(){
let payload = "{\"file\":\"'ATLAS.TEST.JCL(TSTJ0001)'\"}";
let contentURL = `${BASE_URL}/jobs`;
let result = fetch(contentURL,
{
credentials: "include",
method: "POST",
body:
payload
})
.then(response => response.json())
.catch((e) => {
//handle any error
console.log("An error occoured: " + e);
});
return result;
}

Extended API sample in JavaScript
Here is an extended API sample that is written using JavaScript™ with features from ES62015 (map).
/////////////////////////////////////////////////////////////////////////////
// Extended API Sample
// This Sample is written using Javascript with features from ES62015 (map).
// The sample is also written using JSX giving the ability to return HTML elements
// with Javascript variables embedded. This sample is based upon the codebase of the
// sample UI (see- hostname:port/explorer-mvs) which is written using Facebook's React, Redux,
// Router and Google's material-ui
/////////////////////////////////////////////////////////////////////////////
// Return a table with rows detailing the name and jobID of all jobs matching
// the specified parameters
function displayJobNamesTable(){
let jobsJSON = getJobs("*","IBMUSER");
return (
{jobsJSON.map(job => {
return
})}
{job.name} {job.id});
}
// Call the jobs GET api to get all jobs with the userID IBMUSER

Using Zowe 49

}

return result;

});

Using explorer server WebSocket services
The explorer server provides WebSocket services that can be accessed by using the WSS scheme. With
explorer server WebSocket services, you can view the system log in the System log UI that is refreshed
automatically when messages are written. You can also open a JES spool ﬁle for an active job and view its
contents that refresh through a web socket.
Server Endpoint

Description

Prerequisites

/api/sockets/jobs/
{jobname}/ids/{jobid}/
files/{fileid}

Tail the output of an active job.
Use this WSS endpoint to read
the tail of an active job's output
ﬁle in real time.

z/OSMF restjobs

API Catalog
As an application developer, use the API Catalog to view what services are running in the API Mediation
Layer. Through the API Catalog, you can also view the associated API documentation corresponding
to a service, descriptive information about the service, and the current state of the service. The tiles
in the API Catalog can be customized by changing values in the mfaas.catalog-ui-tile section deﬁned
in the application.yml of a service. A microservice that is onboarded with the API Mediation Layer and
conﬁgured appropriately, registers automatically with the API Catalog and a tile for that service is added
to the Catalog.
Note: For more information about how to conﬁgure the API Catalog in the application.yml, see: Add API
Onboarding Conﬁguration.

View Service Information and API Documentation in the API Catalog
Use the API Catalog to view services, API documentation, descriptive information about the service, the
current state of the service, service endpoints, and detailed descriptions of these endpoints.
Note: Verify that your service is running. At least one started and registered instance with the Discovery
Service is needed for your service to be visible in the API Catalog.
Follow these steps:
1. Use the search bar to ﬁnd the service that you are looking for. Services that belong to the same product
family are displayed on the same tile.
Example: Sample Applications, Endevor, SDK Application
2. Click the tile to view header information, the registered services under that family ID, and API
documentation for that service.
Notes:
• The state of the service is indicated in the service tile on the dashboard page. If no instances of the
service are currently running, the tile displays a message displays that no services are running.
• At least one instance of a service must be started and registered with the discovery service for it to
be visible in the API Catalog. If the service that you are onboarding is running, and the corresponding
50 Open Beta for Zowe: Installation and User's Guide

API documentation is displayed, this API documentation is cached and remains visible even when
the service and all service instances stop.
• Descriptive information about the service and a link to the home page of the service is displayed.
Example:

3. Expand the endpoint panel to see a detailed summary with responses and parameters of each
endpoint, the endpoint description, and the full structure of the endpoint.
Example:

Notes:
• If a lock icon is visible on the right side of the endpoint panel, the endpoint requires authentication.
Using Zowe 51

• The structure of the endpoint is displayed relative to the base URL.
• The URL path of the abbreviated endpoint relative to the base URL is displayed in the following
format:
Example:
/api/v1/{yourServiceId}/{endpointName}
The path of the full URL that includes the base URL is also displayed in the following format:
https://hostName:basePort/api/v1/{yourServiceId}/{endpointName}
Both links target the same endpoint location.

Using Zowe CLI
This section contains the following articles about using Zowe CLI.

Display Zowe CLI help
Zowe CLI contains a help system that is embedded directly into the command-line interface. When you
want help with Zowe CLI, you issue help commands that provide you with information about the product,
syntax, and usage.
Display top-level help
To begin using the product, open a command line window and issue the following command to view the
top-level help descriptions:
zowe --help

Tip: The command zowe initiates the product on a command line. All Zowe CLI commands begin
with zowe.
Help structure
The help displays the following types of information:
• Description: An explanation of the functionality for the command group, action, or option that you
speciﬁed in a --help command.
• Usage: The syntax for the command. Refer to usage to determine the expected hierarchical structure of
a command.
• Options: Flags that you can append to the end of a command to specify particular values or booleans.
For example, the volume size for a data set that you want to create.
• Global Options: Flags that you can append to any command in Zowe CLI. For example, the --help flag
is a global option.
Displaying command group, action, and object help
You can use the --help global option get more information about a speciﬁc command group, action,
or object. Use the following syntax to display group-level help and learn more about speciﬁc command
groups (for example, zos-jobs and zos-ﬁles):
zowe --help
zowe zos-files create --help

52 Open Beta for Zowe: Installation and User's Guide

Zowe CLI command groups
Zowe CLI contains command groups that focus on speciﬁc business processes. For example, the zosfiles command group provides the ability to interact with mainframe data sets. This article provides you
with a brief synopsis of the tasks that you can perform with each group. For more information, see Display
Zowe CLI Help.
The commands available in the product are organized in a hierarchical structure. Command groups (for
example, zos-files) contain actions (for example, create) that let you perform actions on speciﬁc
objects (for example, a speciﬁc type of data set). For each action that you perform on an object, you can
specify options that affect the operation of the command.
Important! Before you issue these commands, verify that you completed the steps in Create a Zowe CLI
proﬁle and Test Connection to z/OSMF to help ensure that Zowe CLI can communicate with z/OS systems.
Zowe CLI contains the following command groups:
plugins
The plugins command group lets you install and manage third-party plug-ins for the product. Plug-ins
extend the functionality of Zowe CLI in the form of new commands.
With the plugins command group, you can perform the following tasks:
• Install or uninstall third-party plug-ins.
• Display a list of installed plug-ins.
• Validate that a plug-in integrates with the base product properly.
Note: For more information about plugins syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe plugins -h

proﬁles
The proﬁles command group lets you create and manage proﬁles for use with other Zowe CLI command
groups. Proﬁles allow you to issue commands to different mainframe systems quickly, without specifying
your connection details with every command.
With the proﬁles command group, you can perform the following tasks:
• Create, update, and delete proﬁles for any Zowe CLI command group that supports proﬁles.
• Set the default proﬁle to be used within any command group.
• List proﬁle names and details for any command group, including the default active proﬁle.
Note: For more information about profiles syntax, actions, and options, open Zowe CLI, and issue the
following command:
zowe profiles -h

provisioning
The provisioning command group lets you perform IBM z/OSMF provisioning tasks with templates and
provisioned instances from Zowe CLI.
With the provisioning command group, you can perform the following tasks:
• Provision cloud instances using z/OSMF Software Services templates.
• List information about the available z/OSMF Service Catalog published templates and the templates
that you used to publish cloud instances.
• List summary information about the templates that you used to provision cloud instances. You can ﬁlter
the information by application (for example, DB2 and CICS) and by the external name of the provisioned
instances.
Using Zowe 53

• List detail information about the variables used (and their corresponding values) on named, published
cloud instances.
Note: For more information about provisioning syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe provisioning -h

zos-console
The zos-console command group lets you issue commands to the z/OS console by establishing an
extended Multiple Console Support (MCS) console.
With the zos-console command group, you can perform the following tasks: Important! Before you issue
z/OS console commands with Zowe CLI, security administrators should ensure that they provide access
to commands that are appropriate for your organization. - Issue commands to the z/OS console. - Collect
command responses and continue to collect solicited command responses on-demand.
Note: For more information about zos-console syntax, actions, and options, open Zowe CLI and issue
the following command:
zowe zos-console -h

zos-ﬁles
The zos-ﬁles command group lets you interact with data sets on z/OS systems.
With the zos-ﬁles command group, you can perform the following tasks:
• Create partitioned data sets (PDS) with members, physical sequential data sets (PS), and other types of
data sets from templates. You can specify options to customize the data sets you create.
• Download mainframe data sets and edit them locally in your preferred Integrated Development
Environment (IDE).
• Upload local ﬁles to mainframe data sets.
• List available mainframe data sets.
• Interact with VSAM data sets directly, or invoke Access Methods Services (IDCAMS) to work with VSAM
data sets.
Note: For more information about zos-files syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe zos-files -h

zos-jobs
The zos-jobs command group lets you submit jobs and interact with jobs on z/OS systems.
With the zos-jobs command group, you can perform the following tasks:
• Submit jobs from JCL that resides on the mainframe or a local ﬁle.
• List jobs and spool ﬁles for a job.
• View the status of a job or view a spool ﬁle from a job.
Note: For more information about zos-jobs syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe zos-jobs -h

zos-tso
The zos-tso command group lets you issue TSO commands and interact with TSO address spaces on z/OS
systems.
54 Open Beta for Zowe: Installation and User's Guide

With the zos-tso command group, you can perform the following tasks:
• Excecute REXX scripts
• Create a TSO address space and issue TSO commands to the address space.
• Review TSO command response data in Zowe CLI.
Note: For more information about zos-tso syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe zos-tso -h

zosmf
The zosmf command group lets you work with Zowe CLI proﬁles and get general information about z/
OSMF.
With the zosmf command group, you can perform the following tasks:
• Create and manage your Zowe CLI zosmf proﬁles. You must have at least one zosmf proﬁle to issue
most commands. Issue the zowe help explain profiles command in Zowe CLI to learn more
about using proﬁles.
• Verify that your proﬁles are set up correctly to communicate with z/OSMF on your system. For more
information, see Test Connection to z/OSMF.
• Get information about the current z/OSMF version, host, port, and plug-ins installed on your system.
Note: For more information about zosmf syntax, actions, and options, open Zowe CLI and issue the
following command:
zowe zosmf -h

Using Zowe 55

56 Open Beta for Zowe: Installation and User's Guide

Chapter 5. Extending the Zowe Application
Framework (zLUX)
You can create plug-ins to extend the capabilities of the Zowe Application Framework.

Creating application plug-ins
An application plug-in is an installable set of ﬁles that present resources in a web-based user interface, as
a set of RESTful services, or in a web-based user interface and as a set of RESTful services.
Before you build an application plug-in, you must set the UNIX environment variables that support the
plug-in environment.

Setting the environment variables for plug-in development
To set up the environment, the node must be accessible on the PATH. To determine if the node is already
on the PATH, issue the following command from the command line:
node --version

If the version is returned, the node is already on the PATH.
If nothing is returned from the command, you can set the PATH using the NODE_HOME variable. The
NODE_HOME variable must be set to the directory of the node install. You can use the export command
to set the directory. For example:
export NODE_HOME=node_installation_directory

Using this directory, the node will be included on the PATH in nodeServer.sh. (nodeServer.sh is
located in zlux-example-server/bin).

Using the sample application plug-in
You can experiment with the sample application plug-in called sample-app that is provided.
To build the sample application plug-in, node and npm must be included in the PATH. You can use the
npm run build or npm start command to build the sample application plug-in. These commands are
conﬁgured in package.json.
Note:
• If you change the source code for the sample application, you must rebuild it.
• If you want to modify sample-app, you must run _npm install_ in the Zowe Desktop and the
sample-app/webClient. Then, you can run _npm run build_ in sample-app/webClient.
• Ensure that you set the MVD_DESKTOP_DIR system variable to the Zowe Desktop plug-in location. For
example: /zlux-app-manager/virtual-desktop.
1. Add an item to sample-app. The following ﬁgure shows an excerpt from app.component.ts:
export class AppComponent { items = ['a', 'b', 'c', 'd'] title = 'app';
helloText: string; serverResponseMessage: string;
2. Save the changes to app.component.ts.
3. Issue one of the following commands:
• To rebuild the application plug-in, issue the following command: npm run build

• To rebuild the application plug-in and wait for additional changes to app.component.ts, issue the
following command: npm start
4. Reload the web page.
5. If you make changes to the sample application source code, follow these steps to rebuild the
application:
a. Navigate to the sample-app subdirectory where you made the source code changes.
b. Issue the following command: npm run build
c. Reload the web page.

zLUX plug-ins deﬁnition and structure
The zLUX Application Server (zlux-proxy-server) enables extensiblity with application plug-ins.
Application plug-ins are a subcategory of the unit of extensibility in the server called a plug-in.
The ﬁles that deﬁne a plug-in are located in the pluginsDir directory.

Application plug-in ﬁlesystem structure
An application plug-in can be loaded from a ﬁlesystem that is accessible to the zLUX Application Server,
or it can be loaded dynamically at runtime. When accessed from a ﬁlesystem, there are important
considerations for the developer and the user as to where to place the ﬁles for proper build, packaging,
and operation.
Root ﬁles and directories
The root of an application plug-in directory contains the following ﬁles and directories.
pluginDeﬁnition.json
This ﬁle describes an application plug-in to the zLUX Application Server. (A plug-in is the unit of
extensibility for the zLUX Application Server. An application plug-in is a plug-in of the type "Application",
the most common and visible type of plug-in.) A deﬁnition ﬁle informs the server whether the application
plug-in has server-side dataservices, client-side web content, or both.
Dev and source content
Aside from demonstration or open source application plug-ins, the following directories should not be
visible on a deployed server because the directories are used to build content and are not read by the
server.
nodeServer
When an application plug-in has router-type dataservices, they are interpreted by the zLUX Application
Server by attaching them as ExpressJS routers. It is recommended that you write application plug-ins
using Typescript, because it facilitates well-structured code. Use of Typescript results in build steps
because the pre-transpilation Typescript content is not to be consumed by NodeJS. Therefore, keep
server-side source code in the nodeServer directory. At runtime, the server loads router dataservices
from the lib directory.
webClient
When an application plug-in has the webContent attribute in its deﬁnition, the server serves static
content for a client. To optimize loading of the application plug-in to the user, use Typescript to write the
application plug-in and then package it using Webpack. Use of Typescript and Webpack result in build
steps because the pre-transpilation Typescript and the pre-webpack content are not to be consumed by
the browser. Therefore, separate the source code from the served content by placing source code in the
webClient directory.

58 Open Beta for Zowe: Installation and User's Guide

Runtime content
At runtime, the following set of directories are used by the server and client.
lib
The lib directory is where router-type dataservices are loaded by use in the zLUX Application Server. If
the JS ﬁles that are loaded from the lib directory require NodeJS modules, which are not provided by
the server base (the modules ZLUX-proxy-server requires are added to NODE_PATH at runtime), then
you must include these modules in lib/node_modules for local directory lookup or ensure that they
are found on the NODE_PATH environment variable. nodeServer/node_modules is not automatically
accessed at runtime because it is a dev and build directory.
web
The web directory is where the server serves static content for an application plug-in that includes the
webContent attribute in its deﬁnition. Typically, this directory contains the output of a webpack build.
Anything you place in this directory can be accessed by a client, so only include content that is intended to
be consumed by clients.

Location of plug-in ﬁles
The ﬁles that deﬁne a plug-in are located in the pluginsDir directory.
pluginsDir directory
At startup, the server reads from the pluginsDir directory. The server loads the valid plug-ins that are
found by the information that is provided in the JSON ﬁles.
Within the pluginsDir directory are a collection of JSON ﬁles. Each ﬁle has two attributes, which serve
to locate a plug-in on disk:
location: This is a directory path that is relative to the server's executable (such as zlux-exampleserver/bin/nodeServer.sh) at which a pluginDefinition.json ﬁle is expected to be found.
identiﬁer: The unique string (commonly styled as a Java resource) of a plug-in, which must match what is
in the pluginDefinition.json ﬁle.

Plug-in deﬁnition ﬁle
pluginDefinition.json is a ﬁle that describes a plug-in. Each plug-in requires this ﬁle, because it
deﬁnes how the server will register and use the backend of an application plug-in (called a plug-in in
the terminology of the proxy server). The attributes in each ﬁle are dependent upon the pluginType
attribute. Consider the following pluginDefinition.json ﬁle from sample-app:
{

"identifier": "com.rs.mvd.myplugin",
"apiVersion": "1.0",
"pluginVersion": "1.0",
"pluginType": "application",
"webContent": {
"framework": "angular2",
"launchDefinition": {
"pluginShortNameKey": "helloWorldTitle",
"pluginShortNameDefault": "Hello World",
"imageSrc": "assets/icon.png"
},
"descriptionKey": "MyPluginDescription",
"descriptionDefault": "Base MVD plugin template",
"isSingleWindowApp": true,
"defaultWindowStyle": {
"width": 400,
"height": 300
}
},
"dataServices": [
{
"type": "router",
"name": "hello",

Extending the Zowe Application Framework (zLUX) 59

}

]

}

"serviceLookupMethod": "external",
"fileName": "helloWorld.js",
"routerFactory": "helloWorldRouter",
"dependenciesIncluded": true

Plug-in attributes
There are two categories of attributes: General and Application.
General attributes
identiﬁer
Every application plug-in must have a unique string ID that associates it with a URL space on the server.
apiVersion
The version number for the pluginDeﬁnition scheme and application plug-in or dataservice requirements.
The default is 1.0.0.
pluginVersion
The version number of the individual plug-in.
pluginType
A string that speciﬁes the type of plug-in. The type of plug-in determines the other attributes that are
valid in the deﬁnition.
• application: Deﬁnes the plug-in as an application plug-in. Application plug-ins are composed of a
collection of web content for presentation in the zLUX web component (such as the Zowe Desktop), or a
collection of dataservices (REST and websocket), or both.
• library: Deﬁnes the plug-in as a library that serves static content at a known URL space.
• node authentication: Authentication and Authorization handlers for the zLUX Application Server.
Application attributes
When a plug-in is of pluginType application, the following attributes are valid:
webContent
An object that deﬁnes several attributes about the content that is shown in a web UI.
dataServices
An array of objects that describe REST or websocket dataservices.
conﬁgurationData
An object that describes the resource structure that the application plug-in uses for storing user, group,
and server data.
Application web content attributes
An application that has the webContent attribute deﬁned provides content that is displayed in a zLUX web
UI.
The following attributes determine some of this behavior:
framework
States the type of web framework that is used, which determines the other attributes that are valid in
webContent.
• angular2: Deﬁnes the application as having an Angular (2+) web framework component. This is the
standard for a "native" framework zLUX application.
60 Open Beta for Zowe: Installation and User's Guide

• iframe: Deﬁnes the application as being external to the native zLUX web application environment, but
instead embedded in an iframe wrapper.
launchDeﬁnition
An object that details several attributes for presenting the application in a web UI.
• pluginShortNameDefault: A string that gives a name to the application when i18n is not present. When
i18n is present, i18n is applied by using the pluginShortNameKey.
• descriptionDefault: A longer string that speciﬁes a description of the application within a UI. The
description is seen when i18n is not present. When i18n is present, i18n is applied by using the
descriptionKey.
• imageSrc: The relative path (from /web) to a small image ﬁle that represents the application icon.
defaultWindowStyle
An object that details the placement of a default window for the application in a web UI.
• width: The default width of the application plug-in window, in pixels.
• height: The default height of the application plug-in window, in pixels.
IFrame application web content
In addition to the general web content attributes, when the framework of an application is "iframe", you
must specify the page that is being embedded in the iframe. To do so, incude the attribute startingPage
within webContent. startingPage is relative to the application's /web directory.
Specify startingPage as a relative path rather than an absolute path because the
pluginDefinition.json ﬁle is intended to be read-only, and therefore would not work well when the
hostname of a page changes.
Within an IFrame, the application plug-in still has access to the globals that are used by zLUX for
application-to-application communication; simply access window.parent.RocketMVD.

zLUX dataservices
Dataservices are a dynamic component of the backend of a zLUX application. Dataservices are optional,
because the proxy server might only serve static content for a particular application. However, when
included in an application, a dataservice deﬁnes a URL space for which the server will run the extensible
code from the application. Dataservices are primarily intended to be used to create REST APIs and
Websocket channels.

Deﬁning a dataservice
Within the sample-app repository, in the top directory, you will ﬁnd a pluginDefinition.json ﬁle.
Each zLUX application requires this ﬁle, because it deﬁnes how the server registers and uses the backend
of an application (called a plug-in in the terminology of the proxy server).
Within the JSON ﬁle, there is a top level attribute, dataServices:
"dataServices": [
{
"type": "router",
"name": "hello",
"serviceLookupMethod": "external",
"fileName": "helloWorld.js",
"routerFactory": "helloWorldRouter",
"dependenciesIncluded": true
}
]

Dataservices deﬁned in pluginDeﬁnition
The following attributes are valid for each dataservice in the dataServices array:
Extending the Zowe Application Framework (zLUX) 61

type
Specify one of the following values:
• router: Router dataservices are dataservices that run under the proxy server, and use ExpressJS
Routers for attaching actions to URLs and methods.
• service: Service dataservices are dataservices that run under ZSS, and utilize the API of ZSS
dataservices for attaching actions to URLs and methods.
name
The name of the service that must be unique for each pluginDefinition.json ﬁle. The name is used
to reference the dataservice during logging and it is also is used in the construction of the URL space that
the dataservice occupies.
serviceLookupMethod
Specify external unless otherwise instructed.
ﬁleName
The name of the ﬁle that is the entry point for construction of the dataservice, relative to the application's
/lib directory. In the case of sample-app, upon transpilation of the typescript code, javascript ﬁles are
placed into the /lib directory.
routerFactory (Optional)
When you use a router dataservice, the dataservice is included in the proxy server through a require()
statement. If the dataservice's exports are deﬁned such that the router is provided through a factory of a
speciﬁc name, you must state the name of the exported factory using this attribute.
dependenciesIncluded
Must be true for anything in the pluginDefinition.json ﬁle. (This setting is false only when adding
dataservices to the server dynamically.)

Dataservice API
The API for a dataservice can be categorized as Router-based or ZSS-based, and Websocket or not.
Note: Each Router dataservice can safely import express, express-ws, and bluebird without requiring
the modules to be present, because these modules exist in the proxy server's directory and the
NODE_MODULES environment variable can include this directory.
Router-based dataservices
HTTP/REST router dataservices
Router-based dataservices must return a (bluebird) Promise that resolves to an ExpressJS router upon
success. For more information, see the ExpressJS guide on use of Router middleware: Using Router
Middleware.
Because of the nature of Router middleware, the dataservice need only specify URLs that stem from a
root '/' path, as the paths speciﬁed in the router are later prepended with the unique URL space of the
dataservice.
The Promise for the Router can be within a Factory export function, as mentioned in the
pluginDefinition speciﬁcation for routerFactory above, or by the module constructor.
An example is available in sample-app/nodeServer/ts/helloWorld.ts
Websocket router dataservices
ExpressJS routers are fairly flexible, so the contract to create the Router for Websockets is not
signiﬁcantly different.

62 Open Beta for Zowe: Installation and User's Guide

Here, the express-ws package is used, which adds websockets through the ws package to ExpressJS. The
two changes between a websocket-based router and a normal router are that the method is 'ws', as in
router.ws(,), and the callback provides the websocket on which you must deﬁne
event listeners.
See the ws and express-ws topics on www.npmjs.com for more information about how they work, as the
API for websocket router dataservices is primarily provided in these packages.
An example is available in zlux-proxy-server/plugins/terminal-proxy/lib/
terminalProxy.js
Router dataservice context
Every router-based dataservice is provided with a Context object upon creation that provides deﬁnitions
of its surroundings and the functions that are helpful. The following items are present in the Context
object:
serviceDeﬁnition
The dataservice deﬁnition, originally from the pluginDefinition.json ﬁle within a plug-in.
serviceConﬁguration
An object that contains the contents of conﬁguration ﬁles, if present.
logger
An instance of a zLUX Logger, which has its component name as the unique name of the dataservice
within a plug-in.
makeSublogger
A function to create a zLUX Logger with a new name, which is appended to the unique name of the
dataservice.
addBodyParseMiddleware
A function that provides common body parsers for HTTP bodies, such as JSON and plaintext.
plugin
An object that contains more context from the plug-in scope, including:
• pluginDef: The contents of the pluginDefinition.json ﬁle that contains this dataservice.
• server: An object that contains information about the server's conﬁguration such as:
– app: Information about the product, which includes the productCode (for example: ZLUX).
– user: Conﬁguration information of the server, such as the port on which it is listening.

Zowe Desktop and window management
The Zowe Desktop is a web component of Zowe, which is an implementation of MVDWindowManagement,
the interface that is used to create a window manager.
The code for this software is in the zlux-app-manager repository.
The interface for building an alternative window manager is in the zlux-platform repository.
Window Management acts upon Windows, which are visualizations of an instance of an application plugin. Application plug-ins are plug-ins of the type "application", and therefore the Zowe Desktop operates
around a collection of plug-ins.
Note: Other objects and frameworks that can be utilized by application plug-ins, but not related to
window management, such as application-to-application communication, Logging, URI lookup, and Auth
are not described here.

Extending the Zowe Application Framework (zLUX) 63

Loading and presenting application plug-ins
Upon loading the Zowe Desktop, a GET call is made to /plugins?type=application. The GET call
returns a JSON list of all application plug-ins that are on the server, which can be accessed by the user.
Application plug-ins can be composed of dataservices, web content, or both. Application plug-ins that
have web content are presented in the Zowe Desktop UI.
The Zowe Desktop has a taskbar at the bottom of the page, where it displays each application plug-in as
an icon with a description. The icon that is used, and the description that is presented are based on the
application plug-in's PluginDefinition's webContent attributes.

Plug-in management
Application plug-ins can gain insight into the environment in which they were spawned through the Plugin
Manager. Use the Plugin Manager to determine whether a plug-in is present before you act upon the
existence of that plug-in. When the Zowe Desktop is running, you can access the Plugin Manager through
RocketMVD.PluginManager
The following are the functions you can use on the Plugin Manager:
• getPlugin(pluginID: string)
• Accepts a string of a unique plug-in ID, and returns the Plugin Deﬁnition Object
(DesktopPluginDeﬁnition) that is associated with it, if found.

Application management
Application plug-ins within a Window Manager are created and acted upon in part by an Application
Manager. The Application Manager can facilitate communication between application plug-ins, but
formal application-to-application communication should be performed by calls to the Dispatcher. The
Application Manager is not normally directly accessible by application plug-ins, instead used by the
Window Manager.
The following are functions of an Application Manager:
Function

Description

spawnApplication(plugin:
DesktopPluginDefinition,
launchMetadata: any):
Promise;

Opens an application instance into the Window
Manager, with or without context on what actions it
should perform after creation.

killApplication(plugin:ZLUX.Plugin,
appId:MVDHosting.InstanceId): void;

Removes an application instance from the Window
Manager.

showApplicationWindow(plugin:
DesktopPluginDefinitionImpl): void;

Makes an open application instance visible within
the Window Manager.

isApplicationRunning(plugin:
Determines if any instances of the application are
DesktopPluginDefinitionImpl): boolean; open in the Window Manager.

Windows and Viewports
When a user clicks an application plug-in's icon on the taskbar, an instance of the application plug-in is
started and presented within a Viewport, which is encapsulated in a Window within the Zowe Desktop.
Every instance of an application plug-in's web content within Zowe is given context and can listen on
events about the Viewport and Window it exists within, regardless of whether the Window Manager
implementation utilizes these constructs visually. It is possible to create a Window Manager that only
displays one application plug-in at a time, or to have a drawer-and-panel UI rather than a true windowed
UI.
When the Window is created, the application plug-in's web content is encapsulated dependent upon its
framework type. The following are valid framework types:
64 Open Beta for Zowe: Installation and User's Guide

• "angular2": The web content is written in Angular, and packaged with Webpack. Application plug-in
framework objects are given through @injectables and imports.
• "iframe": The web content can be written using any framework, but is included through an iframe tag.
Application plug-ins within an iframe can access framework objects through parent.RocketMVD and
callbacks.
In the case of the Zowe Desktop, this framework-speciﬁc wrapping is handled by the Plugin Manager.

Viewport Manager
Viewports encapsulate an instance of an application plug-in's web content, but otherwise do not add
to the UI (they do not present Chrome as a Window does). Each instance of an application plug-in is
associated with a viewport, and operations to act upon a particular application plug-in instance should be
done by specifying a viewport for an application plug-in, to differentiate which instance is the target of an
action. Actions performed against viewports should be performed through the Viewport Manager.
The following are functions of the Viewport Manager:
Function

Description

createViewport(providers:
ResolvedReflectiveProvider[]):
MVDHosting.ViewportId;

Creates a viewport into which an application plugin's webcontent can be embedded.

registerViewport(viewportId:
MVDHosting.ViewportId, instanceId:
MVDHosting.InstanceId): void;

Registers a previously created viewport to an
application plug-in instance.

destroyViewport(viewportId:
MVDHosting.ViewportId): void;

Removes a viewport from the Window Manager.

getApplicationInstanceId(viewportId:
MVDHosting.ViewportId):
MVDHosting.InstanceId | null;

Returns the ID of an application plug-in's instance
from within a viewport within the Window Manager.

Injection Manager
When you create Angular application plug-ins, they can use injectables to be informed of when an action
occurs. iframe application plug-ins indirectly beneﬁt from some of these hooks due to the wrapper acting
upon them, but Angular application plug-ins have direct access.
The following topics describe injectables that application plug-ins can use.
Plug-in deﬁnition
@Inject(Angular2InjectionTokens.PLUGIN_DEFINITION) private pluginDefinition:
ZLUX.ContainerPluginDefinition

Provides the plug-in deﬁnition that is associated with this application plug-in. This injectable can be used
to gain context about the application plug-in. It can also be used by the application plug-in with other
application plug-in framework objects to perform a contextual action.
Logger
@Inject(Angular2InjectionTokens.LOGGER) private logger: ZLUX.ComponentLogger

Provides a logger that is named after the application plug-in's plugin deﬁnition ID.
Launch Metadata
@Inject(Angular2InjectionTokens.LAUNCH_METADATA) private launchMetadata: any

Extending the Zowe Application Framework (zLUX) 65

If present, this variable requests the application plug-in instance to initialize with some context, rather
than the default view.
Viewport Events
@Inject(Angular2InjectionTokens.VIEWPORT_EVENTS) private viewportEvents:
Angular2PluginViewportEvents

Presents hooks that can be subscribed to for event listening. Events include:
resized: Subject<{width: number, height: number}>
Fires when the viewport's size has changed.
Window Events
@Inject(Angular2InjectionTokens.WINDOW_ACTIONS) private windowActions:
Angular2PluginWindowActions

Presents hooks that can be subscribed to for event listening. The events include:
Event

Description

maximized: Subject

Fires when the Window is maximized.

minimized: Subject

Fires when the Window is minimized.

restored: Subject

Fires when the Window is restored from a
minimized state.

moved: Subject<{top: number, left:
number}>

Fires when the Window is moved.

resized: Subject<{width: number,
height: number}>

Fires when the Window is resized.

titleChanged: Subject

Fires when the Window's title changes.

Window Actions
@Inject(Angular2InjectionTokens.WINDOW_ACTIONS) private windowActions:
Angular2PluginWindowActions

An application plug-in can request actions to be performed on the Window through the following:
Item

Description

close(): void

Closes the Window of the application plug-in
instance.

maximize(): void

Maximizes the Window of the application plug-in
instance.

minimize(): void

Minimizes the Window of the application plug-in
instance.

restore(): void

Restores the Window of the application plug-in
instance from a minimized state.

setTitle(title: string):void

Sets the title of the Window.

setPosition(pos: {top: number,
left: number, width: number, height:
number}): void

Sets the position of the Window on the page and
the size of the window.

66 Open Beta for Zowe: Installation and User's Guide

Item

Description

spawnContextMenu(xPos: number, yPos:
number, items: ContextMenuItem[]):
void

Opens a context menu on the application plug-in
instance, which uses the Context Menu framework.

registerCloseHandler(handler: () =>
Promise): void

Registers a handler, which is called when the
Window and application plug-in instance are
closed.

Conﬁguration Dataservice
The Conﬁguration Dataservice is an essential component of the zLUX framework, which acts as a
JSON resource storage service, and is accessible externally by REST API and internally to the server by
dataservices.
The Conﬁguration Dataservice allows for saving preferences of applications, management of defaults and
privileges within a zLUX ecosystem, and bootstrapping conﬁguration of the server's dataservices.
The fundamental element of extensibility of the zLUX framework is a plug-in. The Conﬁguration
Dataservice works with data for plug-ins. Every resource that is stored in the Conﬁguration Service is
stored for a particular plug-in, and valid resources to be accessed are determined by the deﬁnition of each
plug-in in how it uses the Conﬁguration Dataservice.
The behavior of the Conﬁguration Dataservice is dependent upon the Resource structure for a plug-in.
Each plug-in lists the valid resources, and the administrators can set permissions for the users who can
view or modify these resources.

Resource Scope
Data is stored within the Conﬁguration Dataservice according to the selected Scope. The intent of Scope
within the Dataservice is to facilitate company-wide administration and privilege management of zLUX
data.
When a user requests a resource, the resource that is retrieved is an override or an aggregation of the
broader scopes that encompass the Scope from which they are viewing the data.
When a user stores a resource, the resource is stored within a Scope but only if the user has access
privilege to update within that Scope.
Scope is one of the following:
Product
Conﬁguration defaults that come with the product. Cannot be modiﬁed.
Site
Data that can be used between multiple instances of the zLUX Server.
Instance
Data within an individual zLUX Server.
Group
Data that is shared between multiple users in a group.
User
Data for an individual user.
Note: While Authorization tuning can allow for settings such as GET from Instance to work without login,
User and Group scope queries will be rejected if not logged in due to the requirement to pull resources
from a speciﬁc user. Because of this, User and Group scopes will not be functional until the Security
Framework is available.
Extending the Zowe Application Framework (zLUX) 67

Where Product is the broadest scope and User is the narrowest scope.
When you specify Scope User, the service manages conﬁguration for your particular username, using the
authentication of the session. This way, the User scope is always mapped to your current username.
Consider a case where a user wants to access preferences for their text editor. One way they could do this
is to use the REST API to retrieve the settings resource from the Instance scope.
The Instance scope might contain editor defaults set by the administrator. But, if there are no defaults in
Instance, then the data in Group and User would be checked.
Therefore, the data the user receives would be no broader than what is stored in the Instance scope, but
might have only been the settings they saved within their own User scope (if the broader scopes do not
have data for the resource).
Later, the user might want to save changes, and they try to save them in the Instance scope. Most likely,
this action is rejected because of the preferences set by the administrator to disallow changes to the
Instance scope by ordinary users.

REST API
When you reach the Conﬁguration Service through a REST API, HTTP methods are used to perform the
desired operation.
The HTTP URL scheme for the conﬁguration dataservice is:
/plugins/com.rs.configjs/services/data////
?
Where the resources are one or more levels deep, using as many layers of subresources as needed.
Think of a resource as a collection of elements, or a directory. To access a single element, you must use
the query parameter "name="
REST query parameters
Name (string)
Get or put a single element rather than a collection.
Recursive (boolean)
When performing a DELETE, speciﬁes whether to delete subresources.
REST HTTP methods
Below is an explanation of each type of REST call.
Each API call includes an example request and response against a hypothetical application called the
"code editor".
GET
GET /plugins/com.rs.configjs/services/data///?
name=
• This returns JSON with the attribute "content" being a JSON resource that is the entire conﬁguration
that was requested. For example:
/plugins/com.rs.configjs/services/data/org.openmainframe.zowe.codeeditor/user/
sessions/default?name=tabs
The parts of the URL are:
• Plugin: org.openmainframe.zowe.codeeditor
• Scope: user
• Resource: sessions
68 Open Beta for Zowe: Installation and User's Guide

• Subresource: default
• Element = tabs
The response body is a JSON conﬁg:
{

"_objectType" : "com.rs.config.resource",
"_metadataVersion" : "1.1",
"resource" : "org.openmainframe.zowe.codeeditor/USER/sessions/default",
"contents" : {
"_metadataVersion" : "1.1",
"_objectType" : "org.openmainframe.zowe.codeeditor.sessions.tabs",
"tabs" : [{
"title" : "TSSPG.REXX.EXEC(ARCTEST2)",
"filePath" : "TSSPG.REXX.EXEC(ARCTEST2)",
"isDataset" : true
}, {
"title" : ".profile",
"filePath" : "/u/tsspg/.profile"
}
]
}

}

GET /plugins/com.rs.configjs/services/data///
This returns JSON with the attribute content being a JSON object that has each attribute being another
JSON object, which is a single conﬁguration element.
GET /plugins/com.rs.configjs/services/data///
(When subresources exist.)
This returns a listing of subresources that can, in turn, be queried.
PUT
PUT /plugins/com.rs.configjs/services/data///?
name=
Stores a single element (must be a JSON object {...}) within the requested scope, ignoring aggregation
policies, depending on the user privilege. For example:
/plugins/com.rs.configjs/services/data/org.openmainframe.zowe.codeeditor/user/
sessions/default?name=tabs
Body:
{

}

"_metadataVersion" : "1.1",
"_objectType" : "org.openmainframe.zowe.codeeditor.sessions.tabs",
"tabs" : [{
"title" : ".profile",
"filePath" : "/u/tsspg/.profile"
}, {
"title" : "TSSPG.REXX.EXEC(ARCTEST2)",
"filePath" : "TSSPG.REXX.EXEC(ARCTEST2)",
"isDataset" : true
}, {
"title" : ".emacs",
"filePath" : "/u/tsspg/.emacs"
}
]

Response:
{

}

"_objectType" : "com.rs.config.resourceUpdate",
"_metadataVersion" : "1.1",
"resource" : "org.openmainframe.zowe.codeeditor/USER/sessions/default",
"result" : "Replaced item."

Extending the Zowe Application Framework (zLUX) 69

DELETE
DELETE /plugins/com.rs.configjs/services/data///?
recursive=true
Deletes all ﬁles in all leaf resources below the resource speciﬁed.
DELETE /plugins/com.rs.configjs/services/data///?
name=
Deletes a single ﬁle in a leaf resource.
DELETE /plugins/com.rs.configjs/services/data///
• Deletes all ﬁles in a leaf resource.
• Does not delete the directory on disk.
Administrative access and group
By means not discussed here, but instead handled by the server's authentication and authorization code,
a user might be privileged to access or modify items that they do not own.
In the simplest case, it might mean that the user is able to do a PUT, POST, or DELETE to a level above
User, such as Instance.
The more interesting case is in accessing another user's contents. In this case, the shape of the URL is
different. Compare the following two commands:
GET /plugins/com.rs.configjs/services/data//user/
Gets the content for the current user.
GET /plugins/com.rs.configjs/services/data//users//
Gets the content for a speciﬁc user if authorized.
This is the same structure that is used for the Group scope. When requesting content from the Group
scope, the user is checked to see if they are authorized to make the request for the speciﬁc group. For
example:
GET /plugins/com.rs.configjs/services/data//group//

Gets the content for the given group, if the user is authorized.

Application API
Retrieves and stores conﬁguration information from speciﬁc scopes.
Note: This API should only be used for conﬁguration administration user interfaces.
ZLUX.UriBroker.pluginConfigForScopeUri(pluginDefinition: ZLUX.Plugin, scope:
string, resourcePath:string, resourceName:string): string;
A shortcut for the preceding method, and the preferred method when you are retrieving conﬁguration
information, is simply to "consume" it. It "asks" for conﬁgurations using the User scope, and allows the
conﬁguration service to decide which conﬁguration information to retrieve and how to aggregate it. (See
below on how the conﬁguration service evaluates what to return for this type of request).
ZLUX.UriBroker.pluginConfigUri(pluginDefinition: ZLUX.Plugin,
resourcePath:string, resourceName:string): string;

Internal and bootstrapping
Some dataservices within plug-ins can take conﬁguration that affects their behavior. This conﬁguration is
stored within the Conﬁguration Dataservice structure, but it is not accessible through the REST API.

70 Open Beta for Zowe: Installation and User's Guide

Within the deploy directory of a Zowe installation, each plug-in might optionally have an _internal
directory. An example of such a path is:
deploy/instance/ZLUX/pluginStorage//_internal
Within each _internal directory, the following directories might exist:
• services/: Conﬁguration resources for the speciﬁc service.
• plugin: Conﬁguration resources that are visible to all services in the plug-in.
The JSON contents within these directories are provided as Objects to dataservices through the
dataservice context Object.

Plug-in deﬁnition
Because the Conﬁguration Dataservices stores data on a per-plug-in basis, each plug-in must deﬁne their
resource structure to make use of the Conﬁguration Dataservice. The resource structure deﬁnition is
included in the plug-in's pluginDefinition.json ﬁle.
For each resource and subresource, you can deﬁne an aggregationPolicy to control how the data of
a broader scope alters the resource data that is returned to a user when requesting a resource from a
narrower scope.
For example:
"configurationData": { //is a direct attribute of the pluginDefinition JSON
"resources": { //always required
"preferences": {
"locationType": "relative", //this is the only option for now, but later absolute paths
may be accepted
"aggregationPolicy": "override" //override and none for now, but more in the future
},
"sessions": { //the name at this level represents the name used within a URL, such as /
plugins/com.rs.configjs/services/data/org.openmainframe.zowe.codeeditor/user/sessions
"aggregationPolicy": "none",
"subResources": {
"sessionName": {
"variable": true, //if variable=true is present, the resource must be the only
one in that group but the name of the resource is substituted for the name given in the REST
request, so it represents more than one
"aggregationPolicy": "none"
}
}
}
}
}

Aggregation policies
Aggregation policies determine how the Conﬁguration Dataservice aggregates JSON objects from
different Scopes together when a user requests a resource. If the user requests a resource from the User
scope, the data from the User scope might replace or be merged with the data from a broader scope such
as Instance, to make a combined resource object that is returned to the user.
Aggregation policies are deﬁned by a plug-in developer in the plug-in's deﬁnition for the Conﬁguration
Service, as the attribute aggregationPolicy within a resource.
The following policies are currently implemented:
• NONE: If the Conﬁguration Dataservice is called for Scope User, only user-saved settings are sent,
unless there are no user-saved settings for the query, in which case the dataservice attempts to send
data that is found at a broader scope.
• OVERRIDE: The Conﬁguration Dataservice obtains data for the resource that is requested at the
broadest level found, and joins the resource's properties from narrower scopes, overriding broader
attributes with narrower ones, when found.

Extending the Zowe Application Framework (zLUX) 71

URI Broker
The URI Broker is an object in the application plug-in web framework, which facilitates calls to the zLUX
Application Server by constructing URIs that use the context from the calling application plug-in.

Accessing the URI Broker
The URI Broker is accessible independent of other frameworks involved such as Angular, and is also
accessible through iframe. This is because it is attached to a global when within the Zowe Desktop. For
more information, see Zowe Desktop and window management. Access the URI Broker through one of
two locations:
Natively:
window.RocketMVD.uriBroker
In an iframe:
window.parent.RocketMVD.uriBroker

Functions
The URI Broker builds the following categories of URIs depending upon what the application plug-in is
designed to call.
Accessing an application plug-in's dataservices
Dataservices can be based on HTTP (REST) or Websocket. For more information, see zLUX dataservices.
HTTP Dataservice URI
pluginRESTUri(plugin:ZLUX.Plugin, serviceName: string, relativePath:string):
string
Returns: A URI for making an HTTP service request.
Websocket Dataservice URI
pluginWSUri(plugin: ZLUX.Plugin, serviceName:string, relativePath:string):
string
Returns: A URI for making a Websocket connection to the service.
Accessing application plug-in's conﬁguration resources
Defaults and user storage might exist for an application plug-in such that they can be retrieved through
the Conﬁguration Dataservice.
There are different scopes and actions to take with this service, and therefore there are a few URIs that
can be built:
Standard conﬁguration access
pluginConfigUri(pluginDefinition: ZLUX.Plugin, resourcePath:string,
resourceName?:string): string
Returns: A URI for accessing the requested resource under the user's storage.
Scoped conﬁguration access
pluginConfigForScopeUri(pluginDefinition: ZLUX.Plugin, scope: string,
resourcePath:string, resourceName?:string): string
Returns: A URI for accessing a speciﬁc scope for a given resource.

72 Open Beta for Zowe: Installation and User's Guide

Accessing static content
Content under an application plug-in's web directory is static content accessible by a browser. This can be
accessed through:
pluginResourceUri(pluginDefinition: ZLUX.Plugin, relativePath: string): string
Returns: A URI for getting static content.
For more information about the web directory, see Application plug-in ﬁlesystem structure.
Accessing the application plug-in's root
Static content and services are accessed off of the root URI of an application plug-in. If there are other
points that you must access on that application plug-in, you can get the root:
pluginRootUri(pluginDefinition: ZLUX.Plugin): string
Returns: A URI to the root of the application plug-in.
Server queries
A client can ﬁnd different information about a server's conﬁguration or the conﬁguration as seen by the
current user by accessing speciﬁc APIs.
Accessing a list of plug-ins
pluginListUri(pluginType: ZLUX.PluginType): string
Returns: A URI, which when accessed returns the list of existing plug-ins on the server by type, such as
"Application" or "all".

Application-to-application communication
zLUX application plug-ins can opt-in to various application framework abilities, such as the ability to have
a Logger, use of a URI builder utility, and more. One ability that is unique to a zLUX environment with
multiple application plug-ins is the ability for one application plug-in to communicate with another. The
application framework provides constructs that facilitate this ability. The constructs are: the Dispatcher,
Actions, Recognizers, Registry, and the features that utilize them such as the framework's Context menu.
1. Why use application-to-application communication?
2. Actions
3. Recognizers
4. Dispatcher

Why use application-to-application communication?
When working with a computer, people often use multiple applications to accomplish a task, for example
checking a dashboard before digging into a detailed program or checking email before opening a bank
statement in a browser. In many environments, the relationship between one program and another is not
well deﬁned (you might open one program to learn of a situation, which you solve by opening another
and typing or pasting in content). Or perhaps a hyperlink is provided or an attachment, which opens
program by using a lookup table of which the program is the default for handling a certain ﬁle extension.
The application framework attempts to solve this problem by creating structured messages that can
be sent from one application plug-in to another. An application plug-in has a context of the information
that it contains. You can use this context to invoke an action on another application plug-in that is better
suited to handle some of the information discovered in the ﬁrst application plug-in. Well-structured
messages facilitate knowing what application plug-in is "right" to handle a situation, and explain in detail
what that application plug-in should do. This way, rather than ﬁnding out that the attachment with the
extension ".dat" was not meant for a text editor, but instead for an email client, one application plugin might instead be able to invoke an action on an application plug-in, which can handle opening of an

Extending the Zowe Application Framework (zLUX) 73

email for the purpose of forwarding to others (a more speciﬁc task than can be explained with ﬁlename
extensions).

Actions
To manage communication from one application plug-in to another, a speciﬁc structure is needed. In the
application framework, the unit of application-to-application communication is an Action. The typescript
deﬁnition of an Action is as follows:
export class Action implements ZLUX.Action {
id: string;
// id of action itself.
i18nNameKey: string; // future proofing for I18N
defaultName: string; // default name for display purposes, w/o I18N
description: string;
targetMode: ActionTargetMode;
type: ActionType;
// "launch", "message"
targetPluginID: string;
primaryArgument: any;
constructor(id: string,
defaultName: string,
targetMode: ActionTargetMode,
type: ActionType,
targetPluginID: string,
primaryArgument:any) {
this.id = id;
this.defaultName = defaultName;
// proper name for ID/type
this.targetPluginID = targetPluginID;
this.targetMode = targetMode;
this.type = type;
this.primaryArgument = primaryArgument;
}

}

getDefaultName():string {
return this.defaultName;
}

An Action has a speciﬁc structure of data that is passed, to be ﬁlled in with the context at runtime, and
a speciﬁc target to receive the data. The Action is dispatched to the target in one of several modes, for
example: to target a speciﬁc instance of an application plug-in, an instance, or to create a new instance.
The Action can be less detailed than a message. It can be a request to minimize, maximize, close, launch,
and more. Finally, all of this information is related to a unique ID and localization string such that it can be
managed by the framework.
Action target modes
When you request an Action on an application plug-in, the behavior is dependent on the instance of the
application plug-in you are targeting. You can instruct the framework how to target the application plug-in
with a target mode from the ActionTargetMode enum:
export enum ActionTargetMode {
PluginCreate,
// require pluginType
PluginFindUniqueOrCreate,
// required AppInstance/ID
PluginFindAnyOrCreate,
// plugin type
//TODO PluginFindAnyOrFail
System,
// something that is always present
}

Action types
The application framework performs different operations on application plug-ins depending on the type
of an Action. The behavior can be quite different, from simple messaging to requesting that an application
plug-in be minimized. The types are deﬁned by an enum:
export enum ActionType {
Launch,
Focus,
Route,
Message,

//
//
//
//
//

not all actions are meaningful for all target modes
essentially do nothing after target mode
bring to fore, but nothing else
sub-navigate or "route" in target
"onMessage" style event to plugin

74 Open Beta for Zowe: Installation and User's Guide

}

Method,
Minimize,
Maximize,
Close,

// Method call on instance, more strongly typed
// may need to call a "close handler"

Loading actions
Actions can be created dynamically at runtime, or saved and loaded by the system at login.
Dynamically
You can create Actions by calling the following Dispatcher method: makeAction(id: string,
defaultName: string, targetMode: ActionTargetMode, type: ActionType,
targetPluginID: string, primaryArgument: any):Action
Saved on system
Actions can be stored in JSON ﬁles that are loaded at login. The JSON structure is as follows:
{

}

"actions": [
{
"id":"org.zowe.explorer.openmember",
"defaultName":"Edit PDS in MVS Explorer",
"type":"Launch",
"targetMode":"PluginCreate",
"targetId":"org.zowe.explorer",
"arg": {
"type": "edit_pds",
"pds": {
"op": "deref",
"source": "event",
"path": [
"full_path"
]
}
}
}
]

Recognizers
Actions are meant to be invoked when certain conditions are met. For example, you do not need to open
a messaging window if you have no one to message. Recognizers are objects within the application
framework that use the context that the application plug-in provides to determine if there is a condition
for which it makes sense to execute an Action. Each recognizer has statements about what condition to
recognize, and upon that statement being met, which Action can be executed at that time. The invocation
of the Action is not handled by the Recognizer; it simply detects that an Action can be taken.
Recognition clauses
Recognizers associate a clause of recognition with an action, as you can see from the following class:
export class RecognitionRule {
predicate:RecognitionClause;
actionID:string;

}

constructor(predicate:RecognitionClause, actionID:string){
this.predicate = predicate;
this.actionID = actionID;
}

A clause, in turn, is associated with an operation, and the subclauses upon which the operation acts. The
following operations are supported:
export enum RecognitionOp {
AND,
OR,

Extending the Zowe Application Framework (zLUX) 75

}

NOT,
PROPERTY_EQ,
SOURCE_PLUGIN_TYPE,
// syntactic sugar
MIME_TYPE,
// ditto

Loading Recognizers at runtime
You can add a Recognizer to the application plug-in environment in one of two ways: by loading from
Recognizers saved on the system, or by adding them dynamically.
Dynamically
You can call the Dispatcher method, addRecognizer(predicate:RecognitionClause,
actionID:string):void
Saved on system
Recognizers can be stored in JSON ﬁles that are loaded at login. The JSON structure is as follows:
{

}

"recognizers": [
{
"id":"",
"clause": {

}
}
]

clause can take on one of two shapes:
"prop": ["", <"valueString">]

Or,
"op": "",
"args": [
{}
]

Where this one can again, have subclauses.
Recognizer example
Recognizers can be simple or complex. The following is an example to illustrate the mechanism:
{

}

"recognizers":[
{
"id":"org.zowe.explorer.openmember",
"clause": {
"op": "AND",
"args": [
{"prop":["sourcePluginID","com.rs.mvd.tn3270"]},{"prop":["screenID","ISRUDSM"]}
]
}
}
]

In this case, the Recognizer detects whether it is possible to run the org.zowe.explorer.openmember
Action when the TN3270 Terminal application plug-in is on the screen ISRUDSM (an ISPF panel for
browsing PDS members).

Dispatcher
The dispatcher is a core component of the application framework that is accessible through the Global
ZLUX Object at runtime. The Dispatcher interprets Recognizers and Actions that are added to it at
76 Open Beta for Zowe: Installation and User's Guide

runtime. You can register Actions and Recognizers on it, and later, invoke an Action through it. The
dispatcher handles how the Action's effects should be carried out, acting in combination with the Window
Manager and application plug-ins themselves to provide a channel of communication.

Registry
The Registry is a core component of the application framework, which is accessible through the Global
ZLUX Object at runtime. It contains information about which application plug-ins are present in the
environment, and the abilities of each application plug-in. This is important to application-to-application
communication, because a target might not be a speciﬁc application plug-in, but rather an application
plug-in of a speciﬁc category, or with a speciﬁc featureset, or capable of responding to the type of Action
requested.

Pulling it all together in an example
The standard way to make use of application-to-application communication is by having Actions and
Recognizers that are saved on the system. Actions and Recognizers are loaded at login, and then later,
through a form of automation or by a user action, Recognizers can be polled to determine if there is an
Action that can be executed. All of this is handled by the Dispatcher, but the description of the behavior
lies in the Action and Recognizer that are used. In the Action and Recognizer descriptions above, there are
two JSON deﬁnitions: One is a Recognizer that recognizes when the Terminal application plug-in is in a
certain state, and another is an Action that instructs the MVS Explorer to load a PDS member for editing.
When you put the two together, a practical application is that you can launch the MVS Explorer to edit a
PDS member that you have selected within the Terminal application plug-in.

Error reporting UI
The zLUX Widgets repository contains shared widget-like components of the Zowe Desktop, including
Button, Checkbox, Paginator, various pop-ups, and others. To maintain consistency in desktop styling
across all applications, use, reuse, and customize existing widgets to suit the purpose of the application's
function and look.
Ideally, a program should have little to no logic errors. Once in a while a few occur, but more commonly an
error occurs from misconﬁgured user settings. A user might request an action or command that requires
certain prerequisites, for example: a proper ZSS-Server conﬁguration. If the program or method fails, the
program should notify the user through the UI about the error and how to ﬁx it. For the purposes of this
discussion, we will use the Workflow application plug-in in the zlux-workflow repository.

ZluxPopupManagerService
The ZluxPopupManagerService is a standard popup widget that can, through its reportError()
method, be used to display errors with attributes that specify the title or error code, severity,
text, whether it should block the user from proceeding, whether it should output to the logger,
and other options you want to add to the error dialog. ZluxPopupManagerService uses both
ZluxErrorSeverity and ErrorReportStruct.
`export declare class ZluxPopupManagerService {`
eventsSubject: any;
listeners: any;
events: any;
logger: any;
constructor();
setLogger(logger: any): void;
on(name: any, listener: any): void;
broadcast(name: any, ...args: any[]): void;
processButtons(buttons: any[]): any[];
block(): void;
unblock(): void;
getLoggerSeverity(severity: ZluxErrorSeverity): any;
reportError(severity: ZluxErrorSeverity, title: string, text: string, options?: any):
Rx.Observable;

Extending the Zowe Application Framework (zLUX) 77

`}`

ZluxErrorSeverity
ZluxErrorSeverity classiﬁes the type of report. Under the popup-manager, there are the following
types: error, warning, and information. Each type has its own visual style. To accurately indicate the type
of issue to the user, the error or pop-up should be classiﬁed accordingly.
`export declare enum ZluxErrorSeverity {`

`}`

ERROR = "error",
WARNING = "warning",
INFO = "info",

ErrorReportStruct
ErrorReportStruct contains the main interface that brings the speciﬁed parameters of
reportError() together.
`export interface ErrorReportStruct {`

`}`

severity: string;
modal: boolean;
text: string;
title: string;
buttons: string[];

Implementation
Import ZluxPopupManagerService and ZluxErrorSeverity from widgets. If you are using
additional services with your error prompt, import those too (for example, LoggerService to print to the
logger or GlobalVeilService to create a visible semi-transparent gray veil over the program and pause
background tasks). Here, widgets is imported from node_modules\@zlux\ so you must ensure zLUX
widgets is used in your package-lock.json or package.json and you have run npm install.
import { ZluxPopupManagerService, ZluxErrorSeverity } from '@zlux/widgets';
Declaration
Create a member variable within the constructor of the class you want to use it for. For example,
in the Workflow application plug-in under \zlux-workflow\src\app\app\zosmf-serverconfig.component.ts is a ZosmfServerConfigComponent class with the pop-up manager service
variable. To automatically report the error to the console, you must set a logger.
`export class ZosmfServerConfigComponent {`

`}`

constructor(
private popupManager: ZluxPopupManagerService, )
{ popupManager.setLogger(logger); } //Optional

Usage
Now that you have declared your variable within the scope of your program's class, you are ready to use
the method. The following example describes an instance of the reload() method in Workflow that
catches an error when the program attempts to retrieve a conﬁguration from a configService and set
it to the program's this.config. This method fails when the user has a faulty zss-Server conﬁguration
and the error is caught and then sent to the class' popupManager variable from the constructor above.
`reload(): void {`
this.globalVeilService.showVeil();
this.configService
.getConfig()

78 Open Beta for Zowe: Installation and User's Guide

.then(config => (this.config = config))
.then(_ => setTimeout(() => this.test(), 0))
.then(_ => this.globalVeilService.hideVeil())
.catch(err => {
this.globalVeilService.hideVeil()
let errorTitle: string = "Error";
let errorMessage: string = "Server configuration not found. Please check your zss
server.";
const options = {
blocking: true
};
this.popupManager.reportError(ZluxErrorSeverity.ERROR, errorTitle.toString()+":
"+err.status.toString(), errorMessage+"\n"+err.toString(), options);
});
`}`

Here, the errorMessage clearly describes the error with a small degree of ambiguity as to account
for all types of errors that might occur from that method. The speciﬁcs of the error are then generated
dynamically and are printed with the err.toString(), which contains the more speciﬁc information
that is used to pinpoint the problem. The this.popupManager.report() method triggers
the error prompt to display. The error severity is set with ZluxErrorSeverity.ERROR and the
err.status.toString() describes the status of the error (often classiﬁed by a code, for example:
404). The optional parameters in options specify that this error will block the user from interacting with
the application plug-in until the error is closed or it until goes away on its own. globalVeilService is
optional and is used to create a gray veil on the outside of the program when the error is caused. You must
import globalVeilService separately (see the zlux-workflow repository for more information).
HTML
The ﬁnal step is to have the recently created error dialog display in the application plug-in. If you do
this.popupManager.report() without adding the component to your template, the error will not be
displayed. Navigate to your component's .html ﬁle. On the Workflow application plug-in, this ﬁle will be
in \zlux-workflow\src\app\app\zosmf-server-config.component.html and the only item left
is to add the popup manager component alongside your other classes.

So now when the error is called, the new UI element should resemble the following:

The order in which you place the pop-up manager determines how the error dialog will overlap in your
UI. If you want the error dialog to overlap other UI elements, place it at the end of the .html ﬁle. You can
also create custom styling through a CSS template, and add it within the scope of your application plug-in.

Logging utility
The zlux-shared repository provides a logging utility for use by dataservices and web content for an
application plug-in.

Extending the Zowe Application Framework (zLUX) 79

Logging objects
The logging utility is based on the following objects:
• Component Loggers: Objects that log messages for an individual component of the environment, such
as a REST API for an application plug-in or to log user access.
• Destinations: Objects that are called when a component logger requests a message to be logged.
Destinations determine how something is logged, for example, to a ﬁle or to a console, and what
formatting is applied.
• Logger: Central logging object, which can spawn component loggers and attach destinations.

Logger IDs
Because Zowe application plug-ins have unique identiﬁers, both dataservices and an application plug-in's
web content are provided with a component logger that knows this unique ID such that messages that are
logged can be preﬁxed with the ID. With the association of logging to IDs, you can control verbosity of logs
by setting log verbosity by ID.

Accessing logger objects
Logger
The core logger object is attached as a global for low-level access.
App Server
NodeJS uses global as its global object, so the logger is attached to:
global.COM_RS_COMMON_LOGGER
Web
Browsers use window as the global object, so the logger is attached to:
window.COM_RS_COMMON_LOGGER
Component logger
Component loggers are created from the core logger object, but when working with an application plugin, allow the application plug-in framework to create these loggers for you. An application plug-in's
component logger is presented to dataservices or web content as follows.
App Server
See Router Dataservice Context in the topic zLUX dataservices.
Web
(Angular App Instance Injectible). See Logger in Zowe Desktop and window management.

Logger API
The following constants and functions are available on the central logging object.
Attribute

Type

makeComponentLogger function

80 Open Beta for Zowe: Installation and User's Guide

Description

Arguments

Creates a component
logger - Automatically
done by the application
framework for
dataservices and web
content

componentIDString

Attribute

Type

setLogLevelForComponentName
function

Description

Arguments

Sets the verbosity of
an existing component
logger

componentIDString,
logLevel

Component Logger API
The following constants and functions are available to each component logger.
Attribute

Type

Description

Arguments

SEVERE

const

Is a const for logLevel

WARNING

const

Is a const for logLevel

INFO

const

Is a const for logLevel

FINE

const

Is a const for logLevel

FINER

const

Is a const for logLevel

FINEST

const

Is a const for logLevel

log

function

Used to write a log,
specifying the log level

logLevel,
messageString

severe

function

Used to write a SEVERE
log.

messageString

warn

function

Used to write a
WARNING log.

messageString

info

function

Used to write an INFO
log.

messageString

debug

function

Used to write a FINE log. messageString

makeSublogger

function

Creates a new
component logger with
an ID appended by the
string given

componentNameSuffix

Log Levels
An enum, LogLevel, exists for specifying the verbosity level of a logger. The mapping is:
Level

Number

SEVERE

WARNING

INFO

FINE

FINER

FINEST

Note: The default log level for a logger is INFO.

Extending the Zowe Application Framework (zLUX) 81

Logging verbosity
Using the component logger API, loggers can dictate at which level of verbosity a log message should be
visible. You can conﬁgure the server or client to show more or less verbose messages by using the core
logger's API objects.
Example: You want to set the verbosity of the org.zowe.foo application plug-in's dataservice, bar to show
debugging information.
logger.setLogLevelForComponentName('org.zowe.foo.bar',LogLevel.DEBUG)
Conﬁguring logging verbosity
The application plug-in framework provides ways to specify what component loggers you would like to set
default verbosity for, such that you can easily turn logging on or off.
Server startup logging conﬁguration
The server conﬁguration ﬁle allows for speciﬁcation of default log levels, as a top-level attribute
logLevel, which takes key-value pairs where the key is a regex pattern for component IDs, and the value
is an integer for the log levels.
For example:
"logLevel": {
"com.rs.configjs.data.access": 2,
//the string given is a regex pattern string, so .* at the end here will cover that service
and its subloggers.
"com.rs.myplugin.myservice.*": 4
//
// '_' char reserved, and '_' at beginning reserved for server. Just as we reserve
// '_internal' for plugin config data for config service.
// _unp = universal node proxy core logging
//"_unp.dsauth": 2
},

For more information about the server conﬁguration ﬁle, see Zowe Application Framework (zLUX)
conﬁguration.

82 Open Beta for Zowe: Installation and User's Guide

Chapter 6. Extending Zowe CLI
You can install plug-ins to extend the capabilities of Zowe CLI. Plug-ins add functionality to the product in
the form of new command groups, actions, objects, and options.
Important! Plug-ins can gain control of your CLI application legitimately during the execution of every
command. Install third-party plug-ins at your own risk. We make no warranties regarding the use of thirdparty plug-ins.
Note: For information about how to install, update, and validate a plug-in, see Installing Plug-ins.
The following plug-ins are available:
CA Brightside Plug-in for IBM® CICS®
The Zowe CLI Plug-in for IBM CICS lets you extend Zowe CLI to interact with CICS programs and
transactions. The plug-in uses the IBM CICS® Management Client Interface (CMCI) API to achieve
the interaction with CICS. For more information, see CICS management client interface on the IBM
Knowledge Center.
For more information, see CA Brightside Plug-in for IBM CICS.

Installing plug-ins
Use commands in the plugins command group to install and manage plug-ins for Zowe CLI.
Important! Plug-ins can gain control of your CLI application legitimately during the execution of every
command. Install third-party plug-ins at your own risk. We make no warranties regarding the use of thirdparty plug-ins.
You can install the following plug-ins: - Zowe CLI Plug-in for IBM CICS Use @brightside/cics in your
command syntax to install, update, and validate the plug-in.

Setting the registry
If you installed Zowe CLI from the zowe-cli-bundle.zip distributed with the Zowe PAX media, proceed to
the Install step.
If you installed Zowe CLI from a registry, conﬁrm that NPM is set to target the registry by issuing the
following command:
npm config set @brightside:registry https://api.bintray.com/npm/ca/brightside

Meeting the prerequisites
Ensure that you meet the prerequisites for a plug-in before you install the plug-in to Zowe CLI. For
documentation related to each plug-in, see Extending Zowe CLI.

Installing plug-ins
Issue an install command to install plug-ins to Zowe CLI. The install command contains the
following syntax:
zowe plugins install [plugin...] [--registry ]

Note: On Windows, you must run as an Administrator to install the product and plug-ins.
• [plugin...] (Optional) Speciﬁes the name of a plug-in, an npm package, or a pointer to a (local or
remote) URL. When you do not specify a plug-in version, the command installs the latest plug-in version
and speciﬁes the preﬁx that is stored in npm save-preﬁx. For more information, see npm save preﬁx.

For more information about npm semantic versioning, see npm semver. Optionally, you can specify a
speciﬁc version of a plug-in to install. For example, zowe plugin install pluginName@^1.0.0.
Tip: You can install multiple plug-ins with one command. For example, issue zowe plugin install
plugin1 plugin2 plugin3
• [--registry ] (Optional) Speciﬁes a registry URL from which to install a plug-in when
you do not use npm config set to set the registry initially.
Examples: Install plug-ins
• The following example illustrates the syntax to use to install a plug-in that is distributed with the zowecli-bundle.zip. If you are using zowe-cli-bundle.zip, issue the following command for each plug-in .tgz
ﬁle:
zowe plugins install ./zowe-cli-db2-1.0.0-next.20180531.tgz

• The following example illustrates the syntax to use to install a plug-in that is named "my-plugin" from a
speciﬁed registry:
zowe plugins install @brightside/my-plugin

• The following example illustrates the syntax to use to install a speciﬁc version of "my-plugins"
zowe plugins install @brightside/my-plugin@"^1.2.3"

Validating plug-ins
Issue the plug-in validation command to run tests against all plug-ins (or against a plug-in that you
specify) to verify that the plug-ins integrate properly with Zowe CLI. The tests conﬁrm that the plug-in
does not conflict with existing command groups in the base application. The command response provides
you with details or error messages about how the plug-ins integrate with Zowe CLI.
Perform validation after you install the plug-ins to help ensure that it integrates with Zowe CLI.
The validate command has the following syntax:
zowe plugins validate [plugin]

• [plugin] (Optional) Speciﬁes the name of the plug-in that you want to validate. If you do not specify
a plug-in name, the command validates all installed plug-ins. The name of the plug-in is not always the
same as the name of the NPM package.
Examples: Validate plug-ins
• The following example illustrates the syntax to use to validate a speciﬁed installed plug-in:
zowe plugins validate @brightside/my-plugin

• The following example illustrates the syntax to use to validate all installed plug-ins:
zowe plugins validate

Updating plug-ins
Issue the update command to install the latest version or a speciﬁc version of a plug-in that you installed
previously. The update command has the following syntax:
zowe plugins update [plugin...] [--registry ]

• [plugin...]

84 Open Beta for Zowe: Installation and User's Guide

Speciﬁes the name of an installed plug-in that you want to update. The name of the plug-in is not always
the same as the name of the NPM package. You can use npm semantic versioning to specify a plug-in
version to which to update. For more information, see npm semver.
• [--registry ]
(Optional) Speciﬁes a registry URL that is different from the registry URL of the original installation.
Examples: Update plug-ins
• The following example illustrates the syntax to use to update an installed plug-in to the latest version:
zowe plugins update @brightside/my-plugin@latest

• The following example illustrates the syntax to use to update a plug-in to a speciﬁc version:
zowe plugins update @brightside/my-plugin@"^1.2.3"

Uninstalling plug-ins
Issue the uninstall command to uninstall plug-ins from a base application. After the uninstall process
completes successfully, the product no longer contains the plug-in conﬁguration.
Tip: The command is equivalent to using npm uninstall to uninstall a package.
The uninstall command contains the following syntax:
zowe plugins uninstall [plugin]

• [plugin] Speciﬁes the plug-in name to uninstall.
Example: Uninstall plug-ins
• The following example illustrates the syntax to use to uninstall a plug-in:
zowe plugins uninstall @brightside/my-plugin

Zowe CLI Plug-in for IBM CICS
The Zowe CLI Plug-in for IBM® CICS® lets you extend Zowe CLI to interact with CICS programs and
transactions. The plug-in uses the IBM CICS® Management Client Interface (CMCI) API to achieve the
interaction with CICS.For more information, see CICS management client interface on the IBM Knowledge
Center.
• Use Cases
• Prerequisites
• Installing
• Setting up proﬁles
• Commands

Use cases
As an application developer, you can use Zowe CLI Plug-in for IBM CICS to perform the following tasks:
• Deploy code changes to CICS applications that were developed with COBOL.
• Deploy changes to CICS regions for testing or delivery. See the deﬁne command for an example of how
you can deﬁne programs to CICS to assist with testing and delivery.
• Automate CICS interaction steps in your CI/CD pipeline with Jenkins Automation Server or TravisCI.
• Deploy build artifacts to CICS regions.
• Alter, copy, deﬁne, delete, discard, and install CICS resources and resource deﬁnitions.
Extending Zowe CLI 85

Prerequisites
Before you install the plug-in, meet the following prerequisites:
• Install Zowe CLI on your PC.
• Verify that IBM® CICS® Management Client Interface (CMCI) API is installed and conﬁgured on your
mainframe systems.

Installing
There are two methods that you can use to install the Zowe CLI Plug-in for IBM CICS - install from Bintray
or install from the Zowe package.
Installing from Bintray
If you installed Zowe CLI from Bintray, complete the following steps:
1. Open a command line window and issue the following command:
zowe plugins install @brightside/cics
1. After the command execution completes, issue the following command to validate that the installation
completed successfully.
zowe plugins validate cics
Successful validation of the IBM CICS plug-in returns the response: Successfully validated.
To validate that the plug-in installed successfully, issue the following command:
zowe plugins validate @brightside/cics

Note: For detailed information about how to install multiple plug-ins, update to a speciﬁc version of a
plug-ins, and install from speciﬁc registries, see Install Plug-ins.
Installing from local package
If you downloaded the Zowe installation package from Github, complete the following steps:
1. Open a command line window and change the directory to the location where you extracted the zowecli-bundle.zip ﬁle. If you do not have the zowe-cli-bundle.zip ﬁle, see the topic Install Zowe
CLI from local package in Installing Zowe CLI for information about how to obtain and extract it.
2. Issue the following command to install the plug-in:
zowe plugins install zowe-cli-cics-1.1.0-next.201809271925.tgz

3. After the command execution completes, issue the following command to validate that the installation
completed successfully.
zowe plugins validate cics

Successful validation of the IBM Db2 plug-in returns the response: Successfully validated.

Setting up proﬁles
A cics proﬁle is required to issue commands in the CICS group that interact with CICS regions. The cics
proﬁle contains your host, port, username, and password for the IBM CMCI server of your choice. You can
create multiple proﬁles and switch between them as needed.
Issue the following command to create a cics proﬁle:
zowe profiles create cics -H -P -u -p

86 Open Beta for Zowe: Installation and User's Guide

Note: For more information about the` syntax, actions, and options, for aproﬁles create`
command, open Zowe CLI and issue the following command:
zowe profiles create cics -h

The result of the command displays as a success or failure message. You can use your proﬁle when you
issue commands in the cics command group.

Commands
The Zowe CLI Plug-in for IBM CICS adds the following commands to Zowe CLI:
• Deﬁning resources to CICS
• Deleting CICS resources
• Discarding CICS resources
• Getting CICS resources
• Installing resources to CICS
• Refreshing CICS programs
Deﬁning resources to CICS
The deﬁne command lets you deﬁne programs and transactions to CICS so that you can deploy and test
the changes to your CICS application. To display a list of possible objects and options, issue the following
command:
zowe cics define -h

Example:
Deﬁne a program named myProgram to the region named myRegion in the CICS system deﬁnition (CSD)
group myGroup:
zowe cics define program myProgram myGroup --region-name myRegion

Deleting CICS resources
The delete command lets you delete previously deﬁned CICS programs or transactions to help you deploy
and test the changes to your CICS application. To display a list of possible objects and options, issue the
following command:
zowe cics delete -h

Example:
Delete a program named PGM123 from the CICS region named MYREGION:
zowe cics delete program PGM123 --region-name MYREGION

Discarding CICS resources
The discard command lets you remove existing CICS program or transaction deﬁnitions to help you
deploy and test the changes to your CICS application. To display a list of possible objects and options,
issue the following command:
zowe cics discard -h

Example:
Discard a program named PGM123 from the CICS region named MYREGION:
zowe cics discard program PGM123 --region-name MYREGION

Extending Zowe CLI 87

Getting CICS resources
The get command lets you get a list of programs and transactions that are installed in your CICS region so
that you can determine if they were installed successfully and deﬁned properly. To display a list of objects
and options, issue the following command:
zowe cics get -h

Example:
Return a list of program resources from a CICS region named MYREGION:
zowe cics get resource CICSProgram --region-name MYREGION

Installing resources to CICS
The install command lets you install resources, such as programs and transactions, to a CICS region so
that you can deploy and test the changes to your CICS application. To display a list of possible objects and
options, issue the following command:
zowe cics install -h

Example:
Install a transaction named TRN1 to the region named MYREGION in the CSD group named MYGRP:
zowe cics install transaction TRN1 MYGRP --region-name MYREGION

Refreshing CICS programs
The refresh command lets you refresh changes to a CICS program so that you can deploy and test the
changes to your CICS application. To display a list of objects and options, issue the following command:
zowe cics refresh -h

Example:
Refresh a program named PGM123 from the region named MYREGION:
zowe cics refresh PGM123 --region-name MYREGION

88 Open Beta for Zowe: Installation and User's Guide

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Page Count                      : 102
Profile CMM Type                : Little CMS
Profile Version                 : 2.1.0
Profile Class                   : Display Device Profile
Color Space Data                : RGB
Profile Connection Space        : XYZ
Profile Date Time               : 1998:02:09 06:49:00
Profile File Signature          : acsp
Primary Platform                : Microsoft Corporation
CMM Flags                       : Not Embedded, Independent
Device Manufacturer             : Hewlett-Packard
Device Model                    : sRGB
Device Attributes               : Reflective, Glossy, Positive, Color
Rendering Intent                : Perceptual
Connection Space Illuminant     : 0.9642 1 0.82491
Profile Creator                 : Little CMS
Profile ID                      : 0
Profile Copyright               : Copyright (c) 1998 Hewlett-Packard Company
Profile Description             : sRGB IEC61966-2.1
Media White Point               : 0.95045 1 1.08905
Media Black Point               : 0 0 0
Red Matrix Column               : 0.43607 0.22249 0.01392
Green Matrix Column             : 0.38515 0.71687 0.09708
Blue Matrix Column              : 0.14307 0.06061 0.7141
Device Mfg Desc                 : IEC http://www.iec.ch
Device Model Desc               : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc               : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant         : 19.6445 20.3718 16.8089
Viewing Cond Surround           : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type    : D50
Luminance                       : 76.03647 80 87.12462
Measurement Observer            : CIE 1931
Measurement Backing             : 0 0 0
Measurement Geometry            : Unknown
Measurement Flare               : 0.999%
Measurement Illuminant          : D65
Technology                      : Cathode Ray Tube Display
Red Tone Reproduction Curve     : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve   : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve    : (Binary data 2060 bytes, use -b option to extract)
XMP Toolkit                     : Adobe XMP Core 5.6-c015 84.159810, 2016/09/10-02:41:30
Format                          : application/pdf
Title                           : Installation and User's Guide
Language                        : en-US
Date                            : 2018:10:03 22:41:59+08:00
Producer                        : Apache FOP Version 2.2
PDF Version                     : 1.4
Creator Tool                    : DITA Open Toolkit
Metadata Date                   : 2018:10:03 22:43:14+08:00
Create Date                     : 2018:10:03 22:41:59+08:00
Modify Date                     : 2018:10:03 22:43:14+08:00
Document ID                     : uuid:4a6ae5c3-75c5-4321-8425-b73da795c438
Instance ID                     : uuid:9ca37fb5-74cc-4a6a-8817-5a80917ef99b
Page Mode                       : UseOutlines
Creator                         : DITA Open Toolkit

EXIF Metadata provided by EXIF.tools

Installation And User's Guide Zowe User

Navigation menu

Versions of this User Manual:

Views

Navigation