![view]({require("../../images/common/SampleMicroservesLook.png").default})
-
-:::tip
-Make sure to set file transfer mode to binary before the transfer.
-After transferring the WAR file, check the permission on the file by running
-ls -la
-If the read permission is not set, turn on the read permission by running,
-chmod +r javazos-sample.war
-:::
diff --git a/docs/extend/extend-api/libertyAPI.md b/docs/extend/extend-api/libertyAPI.md
deleted file mode 100644
index 0837ca9525..0000000000
--- a/docs/extend/extend-api/libertyAPI.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# Creating a RestAPI with Swagger documentation using Liberty
-
-This tutorial will show you how to develop your own Zowe API's with Swagger notation. Although the resulting War file is "dropped into" a Liberty server, the same principles can be applied for other JEE servers.
-
-The source repo for the project can be found at the [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample).
-This document describes how we can add new function and UI's to run alongside Zowe.
-
-So for example, as a team with an established z/OS application we may want to provide wider access to that functionality so that it can be exploited by different applications and organizations. This can include making functionality available to company DevOps processes or for inclusion in UI's.
-
-## Prerequisite skills
-
-Developers should be familiar with the following technologies:
-
-- Java
-- Git and GitHub
-- Maven
-
-Knowledge of the following development technologies is beneficial:
-
-- J2E
-- Liberty or WebSphere Application Server
-- Eclipse/z/OS Explorer
-- RestAPI's
-- zSystems development
-
-## Zowe API Architecture Overview
-
-Much of the Zowe infrastructure builds upon functionality provided by different applications and systems in z/OS some of which are microservices deployed on a Liberty server running on the Z system. As an example Zowe can access z/OSMF services that are aggregated with other functionality that provides new or more comprehensive functionality that allows new services to be created that also benefit from single-sign using **Lightweight Third Party** Authentication (LTPA) keys and centralized logging functions.
-
-The API for Zowe is written in Java utilizing JAX-RS: Java API for RESTful Web Services (JAX-RS). JAX-RS uses Java annotations to simplify the development and deployment of web service clients and endpoints and ultimately become rendered into swagger interfaces.
-
-## Building your own Microservice
-
-There are many publications and blogs regarding Microservice design
-available and it's beyond our scope to attempt to cover here. Fundamentally, however you have most likely already performed an analysis of your product and have identified several notional business
-areas or components that you are most interested in. One of the recommendations in developing Microservices is not to have one massive service but several services that represent component areas. One reason
-would be Microservices that are not used or function is considered restricted can be excluded without affecting other function.
-
-Once you have identified areas of the functionality Microservices for the API's can be designed. Once again there are an
-enormous amount of guidelines, Best practices, strict rules and design guides out there and I won't be prescriptive how you do this except to
-say that you will spend a lot of time teasing out your API object names and considering how the REST functions (GET, PUT, POST and DELETE) apply
-to these objects. Once ready or as long as we have the most basic Get Object API defined we can make a start at coding.
-
-An example below is intended to show how we apply the definitions of
-the Rest API as Java Annotations around a Java method.
-
-```java
- @PUT
- @Path(value = "{attribute}")
- @Produces(MediaType.APPLICATION_JSON)
- @ApiOperation(value = "Updates the value of an existing environment variable",
- notes = "This API uses JZOS to perform the process.")
- @ApiResponses({
- @ApiResponse(code = 200, message = "Updated the environment variable")})
- public Response update(
- @ApiParam(value = "Environment variable name", required = true) @PathParam("attribute") String attribute,
- @ApiParam(value = "Value of an environmental variable") ValueParameter parameter)
- {
- jzosService.updateProperty(attribute, parameter) ;
- return Response.status(Status.OK).build();
- }
-```
-
-Within the Liberty server we have configured a function "APIDiscovery" which at run time converts this into swagger format.
-
-
-
-## Anatomy of a project
-
-Using [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample) as a guide. Create a Dynamic web project (don't specify it as part of an EAR if using the wizard), or if using a
-Maven archetype choose one containing a simplified sample J2EE application.
-
-_Alternatively, use the project as a template. Download the code, rename it and use as the basis of your new project._
-
-The image below indicates the type of structure you should be seeing although this contains more files and folders than you will have
-initially it should give you the general idea. Don't worry about git or target at this stage they will appear later as you develop your project.
-
-
-
-Your project should be developed as a standalone war file and deployed either to a local server if you have no z dependencies (Hint: good to
-start with). If using Eclipse and not yet using z/OS specific functionality consider setting up a test server within Eclipse and
-automatically deploying your war to it. Fantastic for debugging.
-
-The alternative is to drop the war into the Dropins folder of an existing Zowe installation.
-
-It is possible to debug remotely using Eclipse but personally I have found this can lead to issues such as corrupt process locks in z/OS
-requiring SysProg intervention. If you have quick access to SysProg rights you may be comfortable with this but often good old sysout is the
-best debug support
-
-The example project uses Maven for its build process which will run locally or as part of a Jenkins build process.
-
-Further examples of implementations can be found looking at the code for the Zowe microservice.
-
-### Eclipse hint..
-
-Using Maven to build in an Eclipse environment can leave your files full of red x's. Generally this is caused because the Eclipse compiler
-mechanism has no visibility of dependencies described in the pom.xml file. There is a magic function to help with this. Right click on your
-project and select the Maven Update option. This will allow the Eclipse project to be updated and get rid of many of the x's.
-
-
-
-### Generic jar files
-
-It is likely that the Zowe team will provide utility jar files that will either be present on the server or require specific inclusion as
-described in 'Additional Jars'. Currently generic jar files such as Zowe utilities should be included in your war file. This may be revised
-later based upon future requirements.
-
-## Unit Testing
-
-Aim for 100% coverage. In many cases it may be impossible or impractical to achieve either because code is auto-generated or covered in other
-tests. Use Jacoco to highlight where there are gaps.
-
-Note the references to Jacoco in the atlas-jzos-sample pom.xml file. Remember it operates in two phases, initializing before the unit tests
-are run and reporting afterwards.
-
-Examples of unit testing, the use of Mockito and PowerMock are in the src/test/java folder for the jzos sample.
-
-### FV testing
-
-For the purpose of testing applications in a live fully configured environment scenario it is necessary to create another testing specific
-project. You will notice that only the src/main/tests folder is populated. When running a Maven build the tests contained here are
-exercised.
-
-- Using the maven-archetype-quickstart as your Maven template or by creating a new Java project and adding the pom.xml file in Eclipse,
- create a project to contain FV and/or Integration tests.
-
-- Alternatively, you can always download the code, rename it and use as the basis of your new project.
diff --git a/docs/extend/extend-apiml/api-mediation-components-of-URL.md b/docs/extend/extend-apiml/api-mediation-components-of-URL.md
deleted file mode 100644
index e4f3d9c7d1..0000000000
--- a/docs/extend/extend-apiml/api-mediation-components-of-URL.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Components of a URL
-
-This page provides definitions and a diagram to make sure everyone is using the same terms. To maintain consistency of the structure of URLs, Zowe seeks to establish standards around URLs and the elements that make up a URL. This article presents the standard terminology used in Swagger documentation.
-
-## Definitions
-
-REST APIs have a _baseUrl_ to which the endpoint paths are appended. The base URL is defined by _scheme_, _host_, _port_ and _basePath_
-
-where:
-
-- **`baseUrl`**
-Specifies an absolute URL prefix that is different for each instance of the service, or when the service is accessed via the API Gateway.
-
-The endpoint paths are relative paths that follow the documentation of the REST API.
-
-- **`scheme`**
-Specifies the transfer protocols used by the API. API ML supports the `http`, `https`, and WebSocket schemes - `ws` and `wss`.
-
-- **`host`**
-Specifies the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without a scheme or sub-paths.
-
-- **`basePath`**
-Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`. If basePath is not specified then all endpoint paths start at the host root.
-
-When a service is accessed without the API Gateway then the format the `basePath` depends on the service. It can be empty or have several parts (e.g. `/fileMasterPlus/api/v1`).
-
-When a service is accessed via the API Gateway, the format of the URL is standardized in one of the following formats:
-
-- Using `serviceId`, service type (`t`) and major version (`v`)
-- Using `serviceId` and service type (`t`)
-
-where:
-
-- **`serviceId`**
-Specifies a unique name of the service that is set during the installation of the service.
-
-- **`t`**
-Specifies the type of the service. It can be `api`, `ui`, or `ws`
-
-- **`v`**
-Specifies the major version the REST API.
-
- **Example:** `v1`, `v2`. It is optional since some existing services can have versioning in the endpoint path.
-
-The fundamental principle is that by changing the base URL you can access different services with the same API because the structure after the base URL is the same.
-
-The base URL is the parameter the can be set in Zowe CLI in order to access the service. The endpoint path is prepared by the Zowe CLI plug-in but the base URL needs to be provided by the user based on installation of the REST API service.
-
-## Examples
-
-### URL to a service endpoint without API gateway
-
-```markup
-http://ca11.ca.com:19876/fileMasterPlus/api/v1/mvs/dataSets/test/ping
-\_____/\_______________/\____________________/\_____________________/
-scheme host basePath endpointPath
-\____________________________________________/
- baseUrl
-```
-
-### URL with empty basePath
-
-```markup
-https://ca32.ca.com:1443/zosmf/info
-\_____/\_______________/\_________/
-scheme host endpointPath
-\______________________/
- baseUrl
-```
-
-### URL to a service endpoint via API gateway
-
-```markup
-https://ca3x.ca.com:10310/cafilemasterplus/api/v1/mvs/dataSets/test/ping
-\______/\_______________/\______________________/\_____________________/
-scheme host basePath endpointPath
- \______________/\__/\/
- serviceId t v
-
-\_______________________________________________/
- baseUrl
-
-```
-
-### URL to a service endpoint via API gateway without version
-
-```markup
-https://ca3x.ca.com:10310/zosmfca32/api/zosmf/info
-\_____/\________________/\____________/\_________/
-scheme host basePath endpointPath
- \________/\_/
- serviceId t
-
-\______________________/
- baseUrl
-```
-
-### Resources
-
-- For more information, see the documentation for [swagger specifications](https://swagger.io/docs/specification/2-0/api-host-and-base-path/) in the Swagger product documentation.
diff --git a/docs/extend/extend-apiml/api-mediation-infinispan.md b/docs/extend/extend-apiml/api-mediation-infinispan.md
index 763c882af0..d7ae690b77 100644
--- a/docs/extend/extend-apiml/api-mediation-infinispan.md
+++ b/docs/extend/extend-apiml/api-mediation-infinispan.md
@@ -1,7 +1,9 @@
# Using Infinispan as a storage solution through the Caching service
-As an API developer, you can configure Infinispan as a storage solution through the Caching service. This article describes how to configure your storage solution for Infinispan.
-You can configure Infinispan for high availability as well as to replicate data to provide data durability and availability.
+:::info Required roles: system administrator, security administrator
+:::
+
+You can configure Infinispan as a storage solution through the Caching service, as well as configure Infinispan for high availability to replicate data to provide data durability and availability.
- [Using Infinispan as a storage solution through the Caching service](#using-infinispan-as-a-storage-solution-through-the-caching-service)
- [Understanding Infinispan](#understanding-infinispan)
@@ -31,23 +33,35 @@ Configure Infinispan as a storage solution through the Caching service by settin
This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be
either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`.
- either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`.
-
* **`zowe.components.caching-service.storage.infinispan.persistence.dataLocation`**
- The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store.
- The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store).
+ The path where the service keeps its data files for the Infinispan Soft-Index Cache Store.
+ The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the data property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store).
+
+
+* **`zowe.components.caching-service.storage.infinispan.persistence.indexLocation`**
+
+ The path where the service keeps its index data for the Infinispan Soft-Index Cache Store.
+ The default value is `index`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the index property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store).
* **`zowe.components.caching-service.storage.infinispan.jgroups.port`**
- The port number used by Infinispan to synchronise data among cahing-service instances.
+ (OPTIONAL)The default value is `7098`. The port number used by Infinispan to synchronise data among cahing-service instances.
+
+* **`zowe.components.caching-service.storage.infinispan.jgroups.host`**
+
+ (OPTIONAL)The default value is taken from zowe hostname. The hostname used by Infinispan to synchronise data among cahing-service instances.
+
+
+* **`zowe.components.caching-service.storage.infinispan.keyExchange.port`**
+
+ (OPTIONAL)The default value is `7118`. The port number used by Infinispan to exchange encryption key among cahing-service instances.
**Example of Caching service HA configuration using Infinispan:**
```yaml
- zowe
haInstances:
lpar1:
components:
@@ -55,11 +69,10 @@ Configure Infinispan as a storage solution through the Caching service by settin
storage:
mode: infinispan
infinispan:
- initialHosts: lpar2[7099]
- jgroups:
- port: 7098
+ initialHosts: lpar2[7098]
persistence:
dataLocation: /global/zowe/workspace/caching-service/data01
+ indexLocation: /global/zowe/workspace/caching-service/index01
lpar2:
components:
caching-service:
@@ -67,8 +80,7 @@ Configure Infinispan as a storage solution through the Caching service by settin
mode: infinispan
infinispan:
initialHosts: lpar1[7098]
- jgroups:
- port: 7099
persistence:
dataLocation: /global/zowe/workspace/caching-service/data02
+ indexLocation: /global/zowe/workspace/caching-service/index02
```
\ No newline at end of file
diff --git a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md
index 9d2761772f..d637198844 100644
--- a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md
+++ b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md
@@ -10,5 +10,5 @@ The `Dummy Authentication Provider` implements simple authentication for develop
Use the following property of the API Gateway to enable the `Dummy Authentication Provider`:
```
-components.gateway.security.auth.provider: dummy
+components.gateway.apiml.security.auth.provider: dummy
```
diff --git a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md
index a0c08c1763..0f3bfb88c0 100644
--- a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md
+++ b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md
@@ -13,6 +13,9 @@ This configuration is useful in advanced deployments of Zowe where client applic
This article details the API ML OIDC authentication functionality, and describes how to configure the OIDC Authentication feature.
+:::note
+There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, use the recommended internal API ML mapper described in the [API ML OIDC configuration](#api-ml-oidc-configuration) section.
+:::
- [Usage](#usage)
- [Authentication flow](#authentication-flow)
@@ -84,7 +87,22 @@ Ensure that the following prerequisites are met:
- Users who require access to mainframe resources using OIDC authentication have a mainframe identity managed by SAF/ESM.
- SAF/ESM is configured with mapping between the mainframe and distributed user identities. For details, see the section [ESM configuration](#esm-configuration-prerequisites) in this topic.
-
+- If you are using Zowe release 2.14 or a later release, ensure that the API ML Gateway is configured to use the internal mapper functionality. For information about enabling the API ML mapper, see [Configure internal API ML mapper](../../user-guide/api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper). Alternatively, enable ZSS in the Zowe installation, however using the internal mapper is the recommended method. ZSS is enabled by default.
+
+### OIDC provider prerequisites
+
+- **Client Application configuration in the OIDC provider**
+
+ Depending on the OIDC provider and client application capabilities, configuration of the OIDC provider varies.
+For example, web applications with a secure server side component can use `code grant authorization flow` and can be granted a Refresh Token, whereas a Single Page Application running entirely in the User Agent (browser) is more limited regarding its security capabilities.
+
+ :::tip
+ Consult your OIDC provider documentation for options and requirements available for your type of client application.
+ :::
+
+- **Users have been assigned to the Client Application**
+
+ To access mainframe resources, users with a distributed authentication must either be directly assigned by the OIDC provider to the client application, or must be part of group which is allowed to work with the client application.
### ESM configuration prerequisites
@@ -96,14 +114,19 @@ A distributed identity consists of two parts:
Administrators can use the installed ESM functionality to create, delete, list, and query a distributed identity mapping filter or filters.
+Ensure that all the security configuration prerequisites are met by following the steps described in [configure the main Zowe server to use distributed identity mapping](../../user-guide/configure-zos-system.md#configure-main-zowe-server-to-use-distributed-identity-mapping).
+
Use the commands specific to your ESM to create a distributed identity mapping filter.
:::note
User specified parameters are presented in the section [Parameters in the ESM commands](#parameters-in-the-esm-commands).
:::
-
-
Click here for command details for RACF.
+**For RACF** + +
+
-Click here for RACF configuration details.
+ ```markup RACMAP ID(userid) MAP USERDIDFILTER(NAME('distributed-identity-user-name')) REGISTRY(NAME('distributed-identity-registry-name' )) WITHLABEL('label-name') @@ -115,8 +138,10 @@ User specified parameters are presented in the section [Parameters in the ESM co
-
-### How can I get started with Zowe IntelliJ plug-in?
+### How can I get started with Zowe Explorer plug-in for IntelliJ IDEA?
-### How do I get help with using Zowe IntelliJ plug-in?
+### How do I get help with using Zowe Explorer plug-in for IntelliJ IDEA?
-### How can I create, edit and delete z/OSMF connection?
+### How can I contribute to Zowe Explorer plug-in for IntelliJ IDEA?
-
-### How can I contribute to Zowe IntelliJ plug-in?
-
- "https://:/" --header "X-CSRF-ZOSMF-HEADER;" --insecure --user ":"
```
-**NOTE:** Some terminals may require single quotes rather than double quotes.
+:::note
+
+Some terminals might require single quotes rather than double quotes.
+
+:::
### `--location`
@@ -32,21 +36,31 @@ When the server attempts to redirect and `--location` is not included in the com
Use `--request` to identify the API method (such as `POST`, `GET`, `PUT`, `DELETE`). Not necessary when the API method is `GET`.
-- ``: Specifies the API method used in the request.
+- ``
+
+ Specifies the API method used in the request.
### `"https://:/"`
Indicates the protocol and URL.
-- ``: Specifies the host name where the z/OSMF services are running.
-- ``: Specifies the REST port number. If not specified, defaults to 443 for HTTPS.
-- ``: Specifies the API endpoint used in the request.
+- ``
+
+ Specifies the host name where the z/OSMF services are running.
+- ``
+
+ Specifies the REST port number. If not specified, defaults to 443 for HTTPS.
+- ``
+
+ Specifies the API endpoint used in the request.
### `--header "X-CSRF-ZOSMF-HEADER;"`
Required to establish communication with z/OSMF. Specifies that the client is sending a cross-site request to the REST interface.
-- `;`: Indicates that the header has no value. (Not all commands require a value.)
+- `;`
+
+ Indicates that the header has no value. (Not all headers require a value.)
To pass an additional header with a value, use a colon to separate the key and value. For example: `--header "X-IBM-Data-Type: binary"`.
@@ -60,10 +74,18 @@ For example, this bypasses SSL certificate verification for servers with self-si
Required and displays as plain text. Also possible to [use an environment variable](../../user-guide/cli-using-using-environment-variables.md).
-- ``: Specifies the z/OSMF user identification.
-- ``: Specifies the user password for z/OSMF.
+- ``
+
+ Specifies the z/OSMF user identification.
+- ``
+
+ Specifies the user password for z/OSMF.
+
+:::note
+
+To be prompted for a password instead of displaying it in plain text, omit the password from the command and enter `--user ""`.
-**NOTE:** To be prompted for a password instead of displaying it in plain text, omit the password from the command and enter `--user ""`.
+:::
## Comparing commands
diff --git a/docs/troubleshoot/cli/known-cli.md b/docs/troubleshoot/cli/known-cli.md
index bd913e1565..aaa651b249 100644
--- a/docs/troubleshoot/cli/known-cli.md
+++ b/docs/troubleshoot/cli/known-cli.md
@@ -12,7 +12,6 @@ After you install Zowe CLI, and the installation appears to complete successfull
- `zowe config init`
- `zowe config secure`
-- `zowe profiles create`
- Most Zowe commands that access your mainframe environment
This behavior occurs under the following conditions:
@@ -25,14 +24,14 @@ This behavior occurs under the following conditions:
1. Define the `npm_config_global` environment variable. Issue the command that corresponds with your operating system:
- - **Windows Command Prompt:** `set npm_config_global=true`
- - **Windows PowerShell:** `$env:npm_config_global="true"`
- - **macOS/Linux Bash:** `export npm_config_global=true`
+ - Windows Command Prompt: `set npm_config_global=true`
+ - Windows PowerShell: `$env:npm_config_global="true"`
+ - macOS/Linux Bash: `export npm_config_global=true`
2. Install or reinstall Zowe CLI using your preferred installation method.
3. After the Zowe CLI installation completes, reset the `npm_config_global` environment variable. Issue the command that corresponds with your operating system:
- - **Windows Command Prompt:** `set npm_config_global=`
- - **Windows PowerShell:** `$env:npm_config_global=""`
- - **macOS/Linux Bash:** `export npm_config_global=`
+ - Windows Command Prompt: `set npm_config_global=`
+ - Windows PowerShell: `$env:npm_config_global=""`
+ - macOS/Linux Bash: `export npm_config_global=`
4. Continue configuring Zowe CLI. Or, reissue a Zowe command that returned an error message. You should no longer get an error message.
## Chain commands fail in a batch script
@@ -81,9 +80,9 @@ To correct this behavior, verify the following:
- Node.js and NPM are installed.
- PATH contains the correct path to the NodeJS folder.
-**More Information:** [System requirements for Zowe CLI](../../user-guide/systemrequirements-cli.md)
+For more information, see [System requirements for Zowe CLI](../../user-guide/systemrequirements-cli.md).
-## EACCESS error when issing `npm install` command
+## EACCESS error when issuing `npm install` command
**Valid on Windows, Mac, or Linux**
@@ -137,28 +136,10 @@ report success using the following workarounds:
- Issue the `npm cache clean` command.
- - Uninstall and reinstall Zowe CLI. For more information,
- see [Install Zowe CLI](../../user-guide/cli-installcli.md).
+ - Uninstall and reinstall Zowe CLI. For instructions,
+ see the [Zowe CLI installation checklist](../../user-guide/cli-install-cli-checklist.md).
- - `Add the --no-optional` flag to the end of the `npm install` command.
-
-## `npm install -g` command fails due to `npm ERR! Cannot read property 'pause' of undefined` 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
-```
+ - Add the `--no-optional` flag to the end of the `npm install` command.
## Paths converting in Git Bash
@@ -178,7 +159,11 @@ If a command includes a path similar to the following example:
```
A:/ibmuser/my_dir
```
- **Note:** Depending on the root directory, the Git Bash conversion can add other directories it assumes to be included in the path.
+ :::note
+
+ Depending on the root directory, the Git Bash conversion can add other directories it assumes to be included in the path.
+
+ :::
**Solutions:**
@@ -214,3 +199,44 @@ The installation fails on Linux or macOS.
**Solution:**
Depending on how you configured Node.js on Linux or macOS, you might need to add the prefix `sudo` before the `npm install -g` command or the `npm uninstall -g` command. This step gives Node.js write access to the installation directory.
+
+## Missing data set search results with `--mainframe-search` option
+
+**Valid on Windows, Mac, or Linux**
+
+**Symptom:**
+
+When the `zowe zos-files search data-sets` command is issued with the `--mainframe-search` option, results can omit data sets that are in binary format.
+
+**Solution:**
+
+Issue the `zowe files search ds` command without the `--mainframe-search` option. This returns results that include data sets in binary format.
+
+## Error message with PowerShell scripts
+
+**Valid on Windows**
+
+**Symptom:**
+
+PowerShell users on Windows can encounter an error when they try to run Zowe CLI with certain execution policies in place.
+
+Example of an error message:
+
+```
+PS C:\> zowe
+zowe : File C:\Users\user\AppData\Roaming\npm\zowe.ps1 cannot be loaded because running scripts is disabled on this
+system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
+At line:1 char:1
++ zowe
++ ~~~~
+ + CategoryInfo : SecurityError: (:) [], PSSecurityException
+ + FullyQualifiedErrorId : UnauthorizedAccess
+```
+
+**Solutions:**
+
+- Update developer settings in Windows to enable running local scripts without signing:
+
+
+
+- Run PowerShell as an administrator and use the `Set-ExecutionPolicy` command to change the execution policy to a less-restrictive setting, for example: `Set-ExecutionPolicy RemoteSigned -scope CurrentUser`.
diff --git a/docs/troubleshoot/cli/mustgather-cli.md b/docs/troubleshoot/cli/mustgather-cli.md
index 64bb039a42..c381f90512 100644
--- a/docs/troubleshoot/cli/mustgather-cli.md
+++ b/docs/troubleshoot/cli/mustgather-cli.md
@@ -40,7 +40,6 @@ zowe config list --locations
The output provides a brief overview with the following information:
- Configuration file locations
-
- Profile names and types
- Profile type defaults
- All property values (host, port, etc.)
@@ -61,7 +60,7 @@ The output provides a list of configuration files that affect your Zowe commands
Add the `--show-inputs-only` option to any Zowe command.
-For example, if you want to check the command to list a data set, you add the option to the following command:
+For example, if you want to check the command to list a data set, add the option to the following command:
```
zowe zos-files list data-set "SYS1.PARMLIB*" --show-inputs-only
diff --git a/docs/troubleshoot/cli/troubleshoot-cli-credentials.md b/docs/troubleshoot/cli/troubleshoot-cli-credentials.md
index 76e45c09e9..c8c36dc0cd 100644
--- a/docs/troubleshoot/cli/troubleshoot-cli-credentials.md
+++ b/docs/troubleshoot/cli/troubleshoot-cli-credentials.md
@@ -12,15 +12,15 @@ You can troubleshoot a failed log-in to a mainframe service by reviewing the aut
Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with.
-However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply.
+However, some services can accept multiple methods of authentication. When multiple methods are provided (in a configuration profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply.
-To find the authentication methods used for different services and their order of precedence, see the table in [Authentication mechanisms](../../extend/extend-cli/cli-devTutorials.md#authentication-mechanisms).
+To find the authentication methods used for different services and their order of precedence, see the table in [Authentication mechanisms](../../extend/extend-cli/cli-authentication-mechanisms.md).
### PEM certificate files
PEM certificate files are used by Zowe CLI to authenticate to the API Mediation Layer. To be accepted, these certificate files must first be recorded in the service's keyring/trust-store on the mainframe before they are used by Zowe CLI.
-Some users choose to secure PEM certificates by placing them in a password protected container, such as a PGP file, a ZIP file, or a password protected PKCS12 file (a.k.a. a PFX file). However, Zowe CLI does not currently support any certificate files that require a password for use.
+Some users choose to secure PEM certificates by placing them in a password protected container, such as a PGP file, a ZIP file, or a password protected PKCS12 file (or a PFX file). However, Zowe CLI does not currently support any certificate files that require a password for use.
:::note
diff --git a/docs/troubleshoot/cli/troubleshoot-cli.md b/docs/troubleshoot/cli/troubleshoot-cli.md
index 5170eea053..ed5a507712 100644
--- a/docs/troubleshoot/cli/troubleshoot-cli.md
+++ b/docs/troubleshoot/cli/troubleshoot-cli.md
@@ -19,8 +19,11 @@ These instructions apply to Zowe CLI installed on Windows, Mac OS X, and Linux s
Collect the following information to help diagnose the issue:
- Zowe CLI version installed.
+ - Issue the [Zowe CLI](../troubleshoot-check-your-zowe-version.md#zowe-cli) command to get the version number.
- List of plug-ins installed and their version numbers.
+ - Issue the [Zowe CLI plug-ins](../troubleshoot-check-your-zowe-version.md#zowe-cli-plug-ins) command to get the version number(s).
- Node.js and NPM versions installed.
+ - Issue the [Node.js and npm](../../troubleshoot/cli/use-individual-troubleshoot-commands.md#nodejs-and-npm) commands to get the version numbers.
- List of environment variables in use.
For instructions on using commands to collect this information, see [Gathering information to troubleshoot Zowe CLI](mustgather-cli.md) or [Using individual commands for troubleshooting](use-individual-troubleshoot-commands).
diff --git a/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md b/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md
index 920107d837..1c886af030 100644
--- a/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md
+++ b/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md
@@ -2,7 +2,7 @@
As part of the IBM Db2 Database Plug-in installation, the ODBC driver is automatically installed. The driver is required to connect to Db2, but installation can fail due to security restrictions.
-When the ODBC driver installation fails, Zowe CLI displays an error message. To resolve this, the user can manually download and install the driver.
+When the ODBC driver installation fails, Zowe CLI displays an error message. To resolve the error, the user can manually download and install the driver.
**Symptom:**
diff --git a/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md b/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md
index 33462543fe..817e34f2ba 100644
--- a/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md
+++ b/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md
@@ -10,15 +10,15 @@ Issue the following command:
zowe -V
```
-The exact Zowe CLI version may vary depending upon if the `@latest` or `@zowe-v1-lts`, or `@zowe-v2-lts` version is installed.
+The exact Zowe CLI version may vary depending upon if the `@latest`, `@zowe-v1-lts`, `@zowe-v2-lts`, or `@zowe-v3-lts` version is installed.
-You can also display the version of your globally-installed Zowe CLI through the following NPM command:
+Display the version of your globally-installed Zowe CLI through the following NPM command:
```
npm list -g @zowe/cli
```
-More information regarding versioning conventions for Zowe CLI and plug-ins is located in [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md).
+More information regarding versioning conventions for Zowe CLI and plug-ins is located in [Zowe CLI Releases](https://github.com/zowe/zowe-cli/blob/master/RELEASE_HISTORY.md#zowe-v3x-lts-releases).
## Identify the currently installed versions of plug-ins
@@ -28,24 +28,29 @@ Issue the following command:
zowe plugins list
```
-The output describes version and the registry information.
+The output includes the plug-in version number and registry information.
## Environment variables
-The following settings are configurable via environment variables:
+The following settings are configurable with environment variables:
### Log levels
Environment variables are available to specify logging level and the CLI home directory.
-**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.
+:::warning
+
+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.
+
+:::
For more information about logging and environment variables, see [Setting CLI log levels](../../user-guide/cli-configuringcli-ev.md#setting-cli-log-levels).
### CLI daemon mode
-By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home directory resides on a network drive and has poor file performance. For information about how to change the location that the daemon uses, see [Setting CLI daemon mode properties](../../user-guide/cli-configuringcli-ev#setting-cli-daemon-mode-properties).
+By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. One example of this would be when the home directory resides on a network drive and has poor file performance. In this case, changing the file location would improve performance time.
+For information about how to change the location that the daemon uses, see [Setting CLI daemon mode properties](../../user-guide/cli-configuringcli-ev#setting-cli-daemon-mode-properties).
### Home directory
@@ -59,26 +64,19 @@ The values for these variables can be **echo**ed.
## Home directory structure
-
+
-### Location of logs
+### Location and types of logs
-There are two sets of logs to be aware of:
+Zowe client logs are located in the `~/.zowe/logs` directory:
-- Imperative CLI Framework log, which generally contains installation and configuration information.
-
-- Zowe CLI log, which contains information about interaction between CLI and the server endpoints.
+- **Imperative CLI Framework log**, `imperative.log`
+ - Generally contains installation and configuration information
+- **Zowe CLI log**, `zowe.log`
+ - Contains information about interaction between the CLI and the server endpoints
Analyze these logs for any information relevant to your issue.
-### Profile configuration
-
-The `profiles` folder stores connection information.
-
-**Important\!** The profile directory might contain "sensitive" information, such as your mainframe password. You should obfuscate any sensitive references before providing configuration files.
-
-**Note:** While the profile directory can still be used in Zowe CLI v2, it has been deprecated in favor of v2 [team configuration](https://docs.zowe.org/stable/user-guide/cli-using-using-team-profiles) files.
-
## Node.js and npm
Zowe CLI is compatible with the currently supported Node.js LTS versions. For an up-to-date list of supported LTS versions, see [Node.js.org](https://nodejs.org/en/download/releases/).
@@ -90,28 +88,28 @@ npm --version
```
### npm configuration
-If you are having trouble installing Zowe CLI from an npm registry, gather your npm configuration to help identify issues with registry settings, global install paths, proxy settings, etc...
+If you are having trouble installing Zowe CLI from an npm registry, gather your npm configuration to help identify issues with registry settings, global install paths, proxy settings, etc.:
```
npm config ls -l
```
### npm log files
-In case of errors, npm creates log files in the `npm_cache\_logs` location. To get the `npm_cache` location for a specific OS, run the following command:
+In case of errors, npm creates log files in the `npm_cache\_logs` location. To get the `npm_cache` location for a specific OS:
```
npm config get cache
```
-By default, npm keeps only 10 log files, but sometimes more are needed. Increase the log count by issuing the following command:
+By default, npm keeps only 10 log files, but sometimes more are needed. To increase the log count:
```
npm config set logs-max 50
```
-This command increases the log count to 50, so that more log files will be stored on the system. Now you can run tests multiple times and not lose the log files. The logs can be passed to Support for analysis.
+ - This command increases the log count to 50, so that more log files will be stored on the system. Now you can run tests multiple times and not lose the log files. The logs can be passed to Support for analysis.
-As the log files are created only when an npm command fails, but you are interested to see what is executed, you can increase the log level of npm. Issue the following command:
+By default, log files are created only when an npm command fails. To see what is executed, increase the log level of npm:
```
npm config set loglevel verbose
@@ -120,7 +118,16 @@ npm config set loglevel verbose
- With this change, you can see all actions taken by npm on the stdout. If the command is successful, it still does not generate a log file.
- The available log levels are:
-"silent", "error", "warn", "notice", "http", "timing", "info", "verbose", "silly", and "notice". "Notice" is the default.
+ - `silent`
+ - `error`
+ - `warn`
+ - `notice`
+ - `http`
+ - `timing`
+ - `info`
+ - `verbose`
+ - `silly`
+ - `notice`
-- Alternatively, you can pass `--loglevel verbose` on the command line, but this only works with npm related commands. By setting log level in the config, it also works when you issue some `zowe` commands that use npm (for example, `zowe plugins install @zowe/cics`).
+- Alternatively, pass `--loglevel verbose` on the command line. This only works with npm related commands. By setting log level in the config, it also works when you issue some `zowe` commands that use npm (for example, `zowe plugins install @zowe/cics`).
diff --git a/docs/troubleshoot/cli/zosmf-cli.md b/docs/troubleshoot/cli/zosmf-cli.md
index 16c699ca7d..e016e4e660 100644
--- a/docs/troubleshoot/cli/zosmf-cli.md
+++ b/docs/troubleshoot/cli/zosmf-cli.md
@@ -1,14 +1,16 @@
# z/OSMF troubleshooting
-The core command groups use the z/OSMF REST APIs which can experience any number of problems.
+
+The core command groups use the z/OSMF REST APIs, which can experience any number of problems.
If you encounter HTTP 500 errors with the CLI, consider gathering the following information:
-1. The IZU* (IZUSVR and IZUANG) joblogs (z/OSMF server)
-2. z/OSMF USS logs (default location: /global/zosmf/data/logs - but may change depending on installation)
+- The IZU* (IZUSVR and IZUANG) joblogs (z/OSMF server)
+- z/OSMF USS logs (default location: /global/zosmf/data/logs, but may change depending on installation)
If you encounter HTTP 401 errors with the CLI, consider gathering the following information:
-1. Any security violations for the TSO user in SYSLOG
+- Any security violations for the TSO user in SYSLOG
+
+## Alternate methods
-## Alternative methods
At times, it may be beneficial to test z/OSMF outside of the CLI. You can use the CLI tool `curl` or a REST tool such as "Postman" to isolate areas where the problem might be occurring (CLI configuration, server-side, etc.).
Example `curl` command to `GET /zosmf/info`:
diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md
index 930a93154a..afc28f1444 100644
--- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md
+++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md
@@ -79,6 +79,18 @@ The following error message codes may appear on logs or API responses. Use the f
Further connections will be queued until there is room in the connection pool. You may also increase the total connection limit via the gateway start-up script by setting the Gateway configuration for maxTotalConnections.
+### ZWEAO400E
+
+ The structure of the request is invalid: %s
+
+ **Reason:**
+
+ A value in the request is missing or contains an invalid value.
+
+ **Action:**
+
+ Fix the request and try again.
+
### ZWEAO401E
Unknown error in HTTPS configuration: '%s'
@@ -91,6 +103,62 @@ The following error message codes may appear on logs or API responses. Use the f
Start the service again in debug mode to get a more descriptive message. This error indicates it is not a configuration issue.
+### ZWEAO402E
+
+ The request has not been applied because it lacks valid authentication credentials.
+
+ **Reason:**
+
+ The accessed resource requires authentication. The request is missing valid authentication credentials or the token expired.
+
+ **Action:**
+
+ Review the product documentation for more details about acceptable authentication. Verify that your credentials are valid and contact security administrator to obtain valid credentials.
+
+### ZWEAO404E
+
+ The service can not find the requested resource.
+
+ **Reason:**
+
+ **Action:**
+
+### ZWEAO405E
+
+ The request method has been disabled and cannot be used for the requested resource.
+
+ **Reason:**
+
+ **Action:**
+
+### ZWEAO415E
+
+ The media format of the requested data is not supported by the service, so the service has rejected the request.
+
+ **Reason:**
+
+ **Action:**
+
+### ZWEAO500E
+
+ The service has encountered a situation it doesn't know how to handle. Please contact support for further assistance. More details are available in the log under the provided message instance ID
+
+ **Reason:**
+
+ **Action:**
+
+### ZWEAO503E
+
+ The server is not ready to handle the request: %s
+
+ **Reason:**
+
+ The service is not ready to handle the request, it is being initialized or waiting for another service to start.
+
+ **Action:**
+
+ Repeat the request later. Please contact support for further assistance.
+
## Common service core messages
### ZWEAM100E
@@ -546,9 +614,9 @@ The following error message codes may appear on logs or API responses. Use the f
Failed to get trusted certificates from the Gateway. Unexpected response from %s endpoint. Status code: %s. Response body: %s
**Reason:**
-
- The response status code is different from the expected 200 OK.
-
+
+ The response status code is different from expected 200 OK.
+
**Action:**
Ensure that the parameter apiml.security.x509.certificatesUrls is correctly configured with the complete URL to the Gateway certificates endpoint. Test the URL manually.
@@ -562,19 +630,19 @@ The following error message codes may appear on logs or API responses. Use the f
The parameter apiml.security.x509.certificatesUrls is not correctly configured with the complete URL to the Gateway certificates endpoint.
**Action:**
-
- Ensure that the parameter apiml.security.x509.certificatesUrls is correctly configured.
+
+ Ensure that the parameter apiml.security.x509.certificatesUrl is correctly configured.
### ZWEAT503E
An error occurred during retrieval of trusted certificates from the Gateway. Certificate endpoint is %s. Error message: %s
**Reason:**
-
- The communication with the cloud gateway got interrupted or an error occurred while processing the response.
-
+
+ The communication with the gateway got interrupted or an error occurred during processing the response.
+
**Action:**
-
+
Check the provided error message. Contact the support.
### ZWEAT504E
@@ -661,40 +729,40 @@ The following error message codes may appear on logs or API responses. Use the f
Provide a list of services for which this token will be valid
-### ZWEAT607E
+### ZWEAT608E
- Body in the revoke request is not valid.
+ Error mapping between distributed and mainframe identity. Reason: %s %s
**Reason:**
- The request body is not valid
+ Unexpected error occurred when mapping between distributed and mainframe identity
**Action:**
- Use a valid body in the request. Format of a message: `{userId: string, (optional)timestamp: long}` or `{serviceId: string, (optional)timestamp: long}`.
+ Contact Broadcom support.
-### ZWEAT608E
+### ZWEAT609W
- Error mapping between distributed and mainframe identity. Reason: %s %s
+ Mapping between distributed and mainframe identity failed. Reason: %s
**Reason:**
- Unexpected error occurred when mapping between distributed and mainframe identity
+ Mapping between distributed and mainframe identity failed.
**Action:**
- Contact Broadcom support.
+### ZWEAT610E
-### ZWEAT609W
-
- Mapping between distributed and mainframe identity failed. Reason: %s
+ Missing registry name configuration.
**Reason:**
- Mapping between distributed and mainframe identity failed.
+ The registry name configuration is required to correctly map distributed user name from the OIDC access token.
**Action:**
+ Make sure that 'components.gateway.apiml.security.oidc.registry' is correctly set in 'zowe.yaml'.
+
## Security client messages
### ZWEAS100E
@@ -829,7 +897,7 @@ The following error message codes may appear on logs or API responses. Use the f
**Action:**
- When this error occurs it is necessary to get a new JWT token.
+ When this error occurs it is necessary to get a new JWT token.
### ZWEAS120E
@@ -877,7 +945,7 @@ The following error message codes may appear on logs or API responses. Use the f
**Action:**
- Log the message from the exception and then handle the exception based on the information provided there.
+ Log the message from the exception and then handle the exception based on the information provided there.
### ZWEAS400E
@@ -999,7 +1067,7 @@ The following error message codes may appear on logs or API responses. Use the f
**Action:**
- Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support.
+ Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support.
### ZWEAD401E
@@ -1011,7 +1079,7 @@ The following error message codes may appear on logs or API responses. Use the f
**Action:**
- Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support.
+ Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support.
### ZWEAD700W
@@ -1091,29 +1159,25 @@ The following error message codes may appear on logs or API responses. Use the f
## Gateway service messages
-### ZWEAG500E
+### ZWEAG111E
- Client certificate is missing in request.
+ The service has encountered a situation it doesn't know how to handle. Please contact support for further assistance. More details are available in the log under the provided message instance ID
**Reason:**
- No client certificate is present in the HTTPS request.
-
**Action:**
- Properly configure client to send client certificate.
-
-### ZWEAG700E
+### ZWEAG501E
- No instance of the service '%s' found. Routing will not be available.
+ The connection is not secure.
**Reason:**
- The Gateway could not find an instance of the service from the Discovery Service.
+ AT-TLS is not properly configured.
**Action:**
- Check that the service was successfully registered to the Discovery Service and wait for Spring Cloud to refresh the routes definitions.
+ Review AT-TLS documentation and make sure your configuration is correct for this service.
### ZWEAG701E
@@ -1139,185 +1203,13 @@ The following error message codes may appear on logs or API responses. Use the f
Contact the system administrator and request enablement of encoded slashes in the Gateway.
-### ZWEAG704E
-
- Configuration error '%s' when trying to read the public and private key for signing JWT: %s
-
- **Reason:**
-
- A problem occurred while trying to read the certificate-key pair from the keystore.
-
- **Action:**
-
- Review the mandatory fields used in the configuration such as the keystore location path, the keystore and key password, and the keystore type.
-
-### ZWEAG705E
-
- Failed to load public or private key from key with alias '%s' in the keystore '%s'. Gateway is shutting down.
-
- **Reason:**
-
- Failed to load a public or private key from the keystore during JWT Token initialization.
-
- **Action:**
-
- Check that the key alias is specified and correct. Verify that the keys are present in the keystore.
-
-### ZWEAG706E
-
- RequestContext is not prepared for load balancing.
-
- **Reason:**
-
- Custom Ribbon load balancing is not in place before calling Ribbon.
-
- **Action:**
-
- Contact Broadcom support.
-
-### ZWEAG707E
-
- The request to the URL '%s' aborted without retrying on another instance. Caused by: %s
-
- **Reason:**
-
- The request to the server instance failed and will not be retried on another instance.
-
- **Action:**
-
- Refer to 'Caused by' details for troubleshooting.
-
-### ZWEAG708E
-
- The request to the URL '%s' failed after retrying on all known service instances. Caused by: %s
-
- **Reason:**
-
- Request to the server instance could not be executed on any known service instance.
-
- **Action:**
-
- Verify the status of the requested instance.
-
-### ZWEAG709E
-
- Service is not available at URL '%s'. Error returned: '%s'
-
- **Reason:**
-
- The service is not available.
-
- **Action:**
-
- Make sure that the service is running and is accessible by the URL provided in the message.
-
-### ZWEAG710E
-
- Load balancer does not have available server for client: %s
-
- **Reason:**
-
- The service is not available. It might be removed by the Circuit Breaker or by requesting specific instance that is not available.
-
- **Action:**
-
- Try the request later, or remove the request for the specific instance.
-
-### ZWEAG711E
-
- The principal '%s' is missing queried authorization.
-
- **Reason:**
-
- The principal does not have the queried access to the resource name within the resource class.
-
- **Action:**
-
- No action is needed.
-
-### ZWEAG712E
-
- The URI '%s' is an invalid format
-
- **Reason:**
-
- The URI does not follow the format `/{serviceId}/{type}/{version}/{endpoint}` or `/{type}/{version}/{serviceId}/{endpoint}`.
-
- **Action:**
-
- Use a properly formatted URI.
-
-### ZWEAG713E
-
- Configuration error when trying to establish JWT producer. Events: %s
-
- **Reason:**
-
- A problem occurred while trying to make sure that there is a valid JWT producer available. A possible cause of the problem is that API ML does not recognize the authentication type used by z/OSMF.
-
- **Action:**
-
- Based on the specific information in the message, verify that the key configuration is correct, or alternatively, that z/OSMF is available. If z/OSMF is available, specify the authentication type used by z/OSMF in your configuration settings.
-
- Use the following configuration format:
- ```
- apiml:
- security:
- auth:
- zosmf:
- jwtAutoconfiguration:
- ```
- Apply one of the following values:
-
- * **jwt**
- Signifies that z/OSMF supports JWT (APAR PH12143 is applied)
-
- * **ltpa**
- Signifies that z/OSMF does not support JWT
-
-### ZWEAG714E
-
- Unknown error occurred while retrieving the used public key
-
- **Reason:**
-
- An unknown problem occurred when retrieving the used public key. This should never occur.
-
- **Action:**
-
- Try again later.
-
-### ZWEAG715E
-
- The wrong amount of keys retrieved. The amount of retrieved keys is: %s
-
- **Reason:**
-
- There are too many keys in the JWK set. As such, it is not possible to choose the correct one.
-
- **Action:**
-
- Verify the configuration of the z/OSMF to make sure that z/OSMF provides only one used key.
-
-### ZWEAG716E
-
- The system does not know what key should be used.
-
- **Reason:**
-
- Typically z/OSMF is either unavailable or offline.
-
- **Action:**
-
- Verify that z/OSMF is available, accessible by the Gateway service, and online.
-
### ZWEAG717E
The service id provided is invalid: '%s'
**Reason:**
- The provided id is not valid under the conformance criteria.
+ The provided id is not valid under conformance criteria.
**Action:**
@@ -1329,15 +1221,15 @@ The following error message codes may appear on logs or API responses. Use the f
**Reason:**
- Metadata are not accessible.
+ Metadata aren't accessible
**Action:**
- Verify that the metadata are accessible and not empty.
+ Verify that the metadata are accessible and not empty
### ZWEAG719I
- The service id provided is invalid: '%s'
+ The service is not conformant: %s
**Reason:**
@@ -1345,19 +1237,7 @@ The following error message codes may appear on logs or API responses. Use the f
**Action:**
- Verify the conformance criteria, provide valid service id.
-
-### ZWEAG100E
-
- Authentication exception: '%s' for URL '%s'
-
- **Reason:**
-
- A generic failure occurred during authentication.
-
- **Action:**
-
- Refer to the specific authentication exception details for troubleshooting.
+ Verify the conformance criteria.
### ZWEAG101E
@@ -1371,42 +1251,6 @@ The following error message codes may appear on logs or API responses. Use the f
Use the correct HTTP request method supported by the URL.
-### ZWEAG102E
-
- Token is not valid
-
- **Reason:**
-
- The JWT token is not valid.
-
- **Action:**
-
- Provide a valid token.
-
-### ZWEAG103E
-
- The token has expired
-
- **Reason:**
-
- The JWT token has expired.
-
- **Action:**
-
- Obtain a new token by performing an authentication request.
-
-### ZWEAG104E
-
- Authentication service is not available at URL '%s'. Error returned: '%s'
-
- **Reason:**
-
- The authentication service is not available.
-
- **Action:**
-
- Make sure that the authentication service is running and is accessible by the URL provided in the message.
-
### ZWEAG105E
Authentication is required for URL '%s'
@@ -1419,234 +1263,6 @@ The following error message codes may appear on logs or API responses. Use the f
Provide valid authentication.
-### ZWEAG106W
-
- Login endpoint is running in dummy mode. Use credentials '%s'/'%s' to log in. Do not use this option in the production environment.
-
- **Reason:**
-
- The authentication is running in dummy mode.
-
- **Action:**
-
- Ensure that this option is not being used in a production environment.
-
-### ZWEAG107W
-
- Incorrect value: apiml.security.auth.provider = '%s'. The authentication provider is not set correctly. The default 'zosmf' authentication provider is being used.
-
- **Reason:**
-
- An incorrect value of the apiml.security.auth.provider parameter is set in the configuration.
-
- **Action:**
-
- Ensure that the value of apiml.security.auth.provider is set either to 'dummy' if you want to use dummy mode, or to 'zosmf' if you want to use the z/OSMF authentication provider.
-
-### ZWEAG108E
-
- z/OSMF instance '%s' not found or incorrectly configured. Gateway is shutting down.
-
- **Reason:**
-
- The Gateway could not find the z/OSMF instance from the Discovery Service or it could not communicate with the provided z/OSMF instance.
-
- **Action:**
-
- Ensure that the z/OSMF instance is configured correctly and that it is successfully registered to the Discovery Service and that the API Mediation Layer can communicate with the provided z/OSMF instance. The default timeout is 5 minutes. On a slower system, add the variable components.gateway.apiml.security.jwtInitializerTimeout:... and the value in minutes into Zowe's configuration to override this value.
-
-### ZWEAG109E
-
- z/OSMF response does not contain field '%s'.
-
- **Reason:**
-
- The z/OSMF domain cannot be read.
-
- **Action:**
-
- Review the z/OSMF domain value contained in the response received from the 'zosmf/info' REST endpoint.
-
-### ZWEAG110E
-
- Error parsing z/OSMF response. Error returned: '%s
-
- **Reason:**
-
- An error occurred while parsing the z/OSMF JSON response.
-
- **Action:**
-
- Check the JSON response received from the 'zosmf/info' REST endpoint.
-
-### ZWEAG120E
-
- Invalid username or password for URL '%s'
-
- **Reason:**
-
- The username and/or password are invalid.
-
- **Action:**
-
- Provide a valid username and password.
-
-### ZWEAG121E
-
- Authorization header is missing, or the request body is missing or invalid for URL '%s'
-
- **Reason:**
-
- The authorization header is missing, or the request body is missing or invalid.
-
- **Action:**
-
- Provide valid authentication.
-
-### ZWEAS123E
-
- Invalid token type in response from Authentication service.
-
- **Reason:**
-
- Could not retrieve the proper authentication token from the Authentication service response.
-
- **Action:**
-
- Review your APIML authentication provider configuration and ensure your Authentication service is working.
-
-### ZWEAG130E
-
- Token is not valid for URL '%s'
-
- **Reason:**
-
- The token is not valid.
-
- **Action:**
-
- Provide a valid token.
-
-### ZWEAG131E
-
- No authorization token provided for URL '%s'
-
- **Reason:**
-
- No authorization token is provided.
-
- **Action:**
-
- Provide a valid authorization token.
-
-### ZWEAG150E
-
- SAF IDT generation failed. Reason: %s
-
- **Reason:**
-
- An error occurred during SAF verification. Review the reason in the error message.
-
- **Action:**
-
- Verify the Identity Token configuration.
-
-### ZWEAG151E
-
- SAF IDT is not generated because authentication or authorization failed. Reason: %s
-
- **Reason:**
-
- The user credentials were rejected during SAF verification. Review the reason in the error message.
-
- **Action:**
-
- Provide a valid username and password.
-
-### ZWEAG160E
-
- No authentication provided in the request
-
- **Reason:**
-
- The JWT token or client certificate was not provided with the request
-
- **Action:**
-
- Configure your client to provide valid authentication.
-
-### ZWEAG161E
-
- No user was found
-
- **Reason:**
-
- It was not possible to map provided token or certificate to the mainframe identity.
-
- **Action:**
-
- Ask your security administrator to connect your token or client certificate with your mainframe user.
-
-### ZWEAG162E
-
- Gateway service failed to obtain token.
-
- **Reason:**
-
- Authentication request to get token failed.
-
- **Action:**
-
- Contact your administrator.
-
-### ZWEAG163E
-
- Error occurred while parsing X509 certificate.
-
- **Reason:**
-
- %s
-
- **Action:**
-
- Configure your client to provide valid x509 certificate.
-
-### ZWEAG164E
-
- Error occurred while validating X509 certificate. %s
-
- **Reason:**
-
- X509 certificate cannot be validated or the certificate cannot be used for client authentication.
-
- **Action:**
-
- Configure your client to provide valid x509 certificate.
-
-### ZWEAG165E
-
- X509 certificate is missing the client certificate extended usage definition
-
- **Reason:**
-
- X509 certificate cannot be used for client authentication.
-
- **Action:**
-
- Configure your client to provide valid x509 certificate.
-
-### ZWEAG166E
-
- ZOSMF authentication scheme is not supported for this API ML instance.
-
- **Reason:**
-
- z/OSMF is not used as security provider for API ML.
-
- **Action:**
-
- Contact your administrator.
-
### ZWEAG167E
No client certificate provided in the request
@@ -1659,180 +1275,81 @@ The following error message codes may appear on logs or API responses. Use the f
Configure your client to provide valid certificate.
-### ZWEAG168E
-
- Invalid authentication provided in request
-
- **Reason:**
-
- The JWT token or client certificate is not valid
-
- **Action:**
-
- Configure your client to provide valid authentication.
-
-### ZWEAG169E
-
- Unexpected response from the external identity mapper. Status: %s body: %s
-
- **Reason:**
-
- The external identity mapper request failed with Internal Error
-
- **Action:**
-
- Verify that ZSS is responding.
-
-### ZWEAG170E
-
- Error occurred while trying to parse the response from the external identity mapper. Reason: %s
-
- **Reason:**
-
- The external identity mapper failed when trying to parse the response
-
- **Action:**
-
- Verify that the response is valid.
-
-### ZWEAG171E
-
- Configuration error. Failed to construct the external identity mapper URI. Reason: %s
-
- **Reason:**
-
- Failed to construct the external identity mapper URI
-
- **Action:**
-
- Verify that the external identity mapper URL specified in the configuration is valid.
-
-### ZWEAT607E
-
- Body in the revoke request is not valid.
-
- **Reason:**
-
- The request body is not valid
-
- **Action:**
-
- Use a valid body in the request. Format of a message: `{userId: string, (optional)timestamp: long}` or `{serviceId: string, (optional)timestamp: long}`.
-
-### ZWEAG180E
-
- There was an error while reading webfinger configuration
-
- **Reason:**
-
- Webfinger provider contains incorrect configuration.
-
- **Action:**
-
- Contact the administrator to validate webfinger configuration in gateway service.
-
-### ZWEAG181W
-
- z/OSMF service '%s' is either not registered or not online yet.
-
- **Reason:**
-
- z/OSMF service may not be properly onboarded to API ML.
-
- **Action:**
-
- Verify if z/OSMF is up and registered to Discovery Service.
-
-### ZWEAG182E
-
- SSL Misconfiguration, z/OSMF is not accessible.
- Message: %s
- Please verify the following:
- - CN (Common Name) and z/OSMF hostname match.
- - The certificate is valid
- - TLS version matches
- - z/OSMF server certificate is trusted in Zowe's truststore
- Enable debugging to see further details in stack trace.
-
- **Reason:**
-
- The z/OSMF connection is incorrectly configured.
-
- **Action:**
-
- Verify z/OSMF connection details. Verify z/OSMF can be accessed with HTTPS. Configure sslDebug to see SSL debugging messages.
-
-### ZWEAG183E
+### ZWEAM400E
- z/OSMF internal error
+ Error initializing SSL Context: '%s'
**Reason:**
- z/OSMF returned HTTP Status %s.
+ An error occurred while initializing the SSL Context.
**Action:**
- Review z/OSMF status and availability.
+ Refer to the specific message to identify the exact problem.
+ Possible causes include:
+ - Incorrect security algorithm
+ - The keystore is invalid or corrupted
+ - The certificate is invalid or corrupted
-### ZWEAG184E
+### ZWEAT403E
- Could not connect to z/OSMF: %s
+ The user is not authorized to the target resource: %s
**Reason:**
- There was a connection issue between the API Mediation Layer instance and z/OSMF.
+ The service has accepted the authentication of the user but the user does not have access rights to the resource.
**Action:**
- Verify z/OSMF is running. Verify connectivity to z/OSMF from this instance.
+ Contact your security administrator to give you access.
-### ZWEAG185W
+### ZWEAG510E
- The change password endpoint has failed with code %s
+ Request to the resource ended with unexpected status code.
**Reason:**
- The change password endpoint was not found.
+ The service did not respond properly.
**Action:**
- Ensure PTF for APAR PH34912 is applied. (https://www.ibm.com/support/pages/apar/PH34912)
+ Verify that the target service is healthy.
-### ZWEAG186E
+### ZWESG100W
- z/OSMF internal error attempting password change: %s
+ Cannot receive information about services on API Gateway with apimlId '%s' because: %s
**Reason:**
- z/OSMF informed of an internal error.
+ Cannot connect to the Gateway service.
**Action:**
- Verify z/OSMF error log.
+ Make sure that the external Gateway service is running and the truststore of the both Gateways contain the corresponding certificate.
-### ZWEAG187W
+### ZWESG101E
- The check of z/OSMF JWT authentication endpoint has failed. Using z/OSMF info endpoint as backup.
+ An internal exception occurred in ZAAS service %s.
**Reason:**
- z/OSMF JWT endpoint was not found.
+ ZAAS cannot process authentication required to finish the request.
**Action:**
- Ensure APAR PH12143 (https://www.ibm.com/support/pages/apar/PH12143) fix has been applied.
+ Make sure that the ZAAS is configured well and check all security requirements.
-### ZWEAG188W
+### ZWESG429E
- z/OSMF JWT builder endpoint call (%s) failed with %s
+ Request was denied access.
**Reason:**
- z/OSMF returned an error code when calling JWT endpoint.
+ Connections limit exceeded.
**Action:**
- Review z/OSMF status. Contact your system administrator.
+ Wait for the number of active connections to decrease before retrying your request.
## API Catalog messages
@@ -1896,6 +1413,18 @@ The following error message codes may appear on logs or API responses. Use the f
Check the status of the message for more information and the health of the Discovery Service.
+### ZWEAC105W
+
+ API Documentation not retrieved for service '%s' due to communication error, %s
+
+ **Reason:**
+
+ Unable to fetch API documentation.
+
+ **Action:**
+
+ Make sure the service documentation url or server transport encoding is configured correctly.
+
### ZWEAC700E
Failed to update cache with discovered services: '%s'
diff --git a/docs/troubleshoot/troubleshoot-apiml.md b/docs/troubleshoot/troubleshoot-apiml.md
index b1279b8d7f..10f5303728 100644
--- a/docs/troubleshoot/troubleshoot-apiml.md
+++ b/docs/troubleshoot/troubleshoot-apiml.md
@@ -381,7 +381,7 @@ The API ML services are running but they are in the DOWN state and not working p
See the following message for full exceptions.
```
-org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://USILCA32.lvn.broadcom.net:7553/eureka/apps/apicatalog": USILCA32.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net
+org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://system.lvn.broadcom.net:7553/eureka/apps/apicatalog": system.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net
.at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:732) ~Ýspring-web-5.0.8.RELEASE.jar!/:5.0.8.RELEASE¨
@@ -406,7 +406,7 @@ main¨ o.a.http.impl.client.DefaultHttpClient : Retrying connect to {s}->https
The Zowe started task needs to run under a user with sufficient privileges. As a workaround, you can try to run the started task under the same user ID as z/OSMF (typically IZUSVR).
-The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping USILCA32.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed to do network access.
+The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping system.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed network access.
You can fix it by setting up the security environment as described in the [Zowe documentation](../user-guide/configure-zos-system#configure-security-environment-switching).
diff --git a/docs/troubleshoot/troubleshoot-check-your-zowe-version.md b/docs/troubleshoot/troubleshoot-check-your-zowe-version.md
index c1bdb2b8b5..cd9c52015f 100644
--- a/docs/troubleshoot/troubleshoot-check-your-zowe-version.md
+++ b/docs/troubleshoot/troubleshoot-check-your-zowe-version.md
@@ -99,14 +99,6 @@ Find the version number of your Zowe release in the `manifest.json` file.
An **Editor** tab displays the Zowe Explorer extension's marketplace details. The version number is located next to the Zowe Explorer extension's name.
-### Zowe IntelliJ Plug-in
+### Zowe Explorer plug-in for IntelliJ IDEA
-1. Open the **File** menu and click **Settings**.
-
- The **Settings** window opens.
-2. Click **Plugins**, then click **Installed** tab.
-
- A list of the installed extensions displays.
-3. Search for, and select, `Zowe Explorer`.
-
- The Zowe Explorer marketplace details display on the right side of the window. The version number is located adjacent to the Zowe Explorer name.
+See the [guide](./troubleshoot-intellij) for instructions.
diff --git a/docs/troubleshoot/troubleshoot-intellij.md b/docs/troubleshoot/troubleshoot-intellij.md
index 59f7107f2a..11ee63b389 100644
--- a/docs/troubleshoot/troubleshoot-intellij.md
+++ b/docs/troubleshoot/troubleshoot-intellij.md
@@ -1,10 +1,39 @@
-# Troubleshooting Zowe IntelliJ plug-in
+# Troubleshooting Zowe Explorer plug-in for IntelliJ IDEA
-As a Zowe IntelliJ plug-in user, you may encounter problems with how the plug-in functions.
+As a Zowe Explorer plug-in for IntelliJ IDEA user, you may encounter problems both with the plug-in and the IntelliJ IDEA platform. Our support is open for any type of issues, related to this client-side component. See the next sections as an example of how to react on these problems.
-Before reaching out for support,
+## Troubleshooting IntelliJ IDEA platform issues
-1. Is there already a GitHub issue (open or closed) that covers the problem? Check [Zowe IntelliJ plug-in Issues](https://github.com/zowe/zowe-explorer-intellij/issues).
-2. Try searching using the Zowe Docs search bar.
+Sometimes there could be inconveniences in how your IDE works. Before trying to fix any problem:
+1. Go to **Help** > **About**
-When necessary, you can use [the Slack channel](https://openmainframeproject.slack.com/archives/C020BGPSU0M) to reach the Zowe IntelliJ squad for assistance.
+
+
+2. Click **Copy and Close** button and save this information somewhere for later
+
+
+
+After that, there are a few steps that could be possibly done to fix the issue:
+- **If the issue details are clear and IDE says, which component it is** - copy all the related information and send it to the component's developer
+- **If the issue is unclear** - try to reload IDE / your computer. If the problem persists, try to reinstall the IDE or install the newest one supported LTS version of the IDE you are using
+- **Ask for help or search for the related issue** - there is [an issue tracker](https://youtrack.jetbrains.com/issues/IDEA), related to the IntelliJ IDEA issues. Try to find something related or create a new one
+
+## Troubleshooting the plug-in
+
+If you have an issue with the plug-in:
+1. Click the **gear** button, select **Plugins...**
+
+
+
+2. Go to **Installed** tab, locate the plug-in, save **the exact version number**
+
+
+
+After these actions, you have some options to try:
+- **If the problem occurs for the plug-in in editor** - try to close the file you are editing, refresh the path and open it again
+- **If the problem occurs with displaying a mask or a filter** - try to hit refresh on a working set or try to recreate a connection and a working set
+- **If the problem occurs for some other issues related to Files Explorer or JES Explorer** - try to recreate a new connection, and a new working set for it
+- **If the problem occurs for TSO Console** - try to reopen the session, try to recreate a session entirely
+- **Other non-related issues, e.g. if the problem occurs for encoding or permissions or "Internal IDE error" notification appears constantly** - copy all the necessary information about the IDE you use and the plug-in's version, [create a new issue](https://github.com/zowe/zowe-explorer-intellij/issues) listing all the necessary information (like the steps to recreate the issue) as well as the versions, or search for the related issue in the repository and put a thumb-up for it, so we know that it should have a higher priority
+
+If you want a direct consulting, don't hesitate to visit our [Slack channel](https://openmainframeproject.slack.com/archives/C020BGPSU0M) and leave a message. Our team is always willing to help with any issues related to the platform or the plug-in, no matter the size of an issue or a question.
diff --git a/docs/troubleshoot/troubleshoot-zowe-release.md b/docs/troubleshoot/troubleshoot-zowe-release.md
index 65d73f72ad..ce99279140 100644
--- a/docs/troubleshoot/troubleshoot-zowe-release.md
+++ b/docs/troubleshoot/troubleshoot-zowe-release.md
@@ -1,29 +1,37 @@
# Understanding Zowe release versions
## Zowe releases
-Zowe uses semantic versioning for its releases, also known as SemVer. Each release has a unique ID made up of three numbers that are separated by periods.
+Zowe uses *semantic versioning* for its releases, also known as SemVer. In semantic versioning, each release has a unique ID made up of three numbers that are separated by periods:
```
..
```
Each time a new release is created, the release ID is incremented. Each number represents the content change since the previous release. For example:
+
- `2.5.0` represents the fifth minor release since the first major release.
- `2.5.1` represents the first patch to the `2.5.0` release.
- `2.6.0` is the first minor release to be created after `2.5.1`.
+To see the Zowe release schedule, see [Zowe PI Schedule and Releases](https://github.com/zowe/community/blob/master/Project%20Management/Schedule/Zowe%20PI%20%26%20Sprint%20Cadence.md).
+
### Major release
-A major release is required if changes are made to the public API and the code is no longer compatible with an earlier version.
-When Zowe is version one, it is associated with the Zowe v1 [conformance program](../extend/zowe-conformance-program.md). Offerings that extend Zowe and achieve the Zowe v1 conformance badge will remain compatible with Zowe throughout its version 1 lifetime. A major release increment because of incompatibility is sometimes referred to as a "breaking" change.
+Major releases are required for a *"breaking" change*, or a modification that requires updates to avoid disruptions in your applications. Major releases also can be used to indicate to the community a significant content update over and above what would be included in a minor release.
+
+#### Conformance programs
-The first SMP/E build for Zowe v2 has a Functional Module ID (FMID) of AZWE002, which was created with content from the 2.0.0 release. Each major release will be its own SMP/E FMID where the last digit is updated, for example AZWE00V where V represents the major version.
+Zowe V1 is associated with the Zowe V1 [conformance program](../extend/zowe-conformance-program.md). Offerings that extend Zowe and achieve the Zowe V1 conformance badge remain compatible with Zowe throughout its Version 1 lifetime. A major release increment because of incompatibility is sometimes referred to as a "breaking" change.
-Subsequent minor and patch releases to V2 are delivered as SMP/E PTF SYSMODs. Because of the size of the content, two co-requisite PTFs are created for each Zowe release.
+#### SMP/E builds
-While Major releases are required for a "breaking" change, they also can be used to indicate to the community a significant content update over and above what would be included in a minor release.
+Each major release has its own SMP/E Functional Module ID (FMID) in the format `AZWE00V`, where `V` represents the major version. The first SMP/E build for Zowe V3 has a Functional Module ID (FMID) of `AZWE003`, which was created with content from the 3.0.0 release.
+
+Subsequent minor and patch releases to V3 are delivered as SMP/E PTF SYSMODs. Because of the size of the content, two co-requisite PTFs are created for each Zowe release.
### Minor release
-A minor release indicates that new functionality is added but the code is compatible with an earlier version. The Zowe community works on two-week sprints and creates a minor release at the end of these, typically once per month although the frequency might vary.
+
+A minor release indicates that new functionality is added but the code is compatible with an earlier version.
### Patch
+
A patch is usually reserved for a bug fix to a minor release.
diff --git a/docs/troubleshoot/troubleshooting.md b/docs/troubleshoot/troubleshooting.md
index 51b79229f5..c68c8995cb 100644
--- a/docs/troubleshoot/troubleshooting.md
+++ b/docs/troubleshoot/troubleshooting.md
@@ -8,28 +8,29 @@ When you run into some issues and are looking for troubleshooting tips, the foll
1. Search the error message or error code in your error log by using the Search bar in the [Zowe Docs site](https://docs.zowe.org/). If there is an existing solution, follow the instructions to troubleshoot.
-
+ 
2. If no solution is available or the existing solutions cannot apply to your problem, you could search the keywords, error messages, or error code in the [Zowe GitHub repository](https://github.com/zowe). If you find a closed issue or pull request, try troubleshooting by using the information shared in the item's Conversation section. If the issue is still open, post your question or comment to prompt a discussion on your problem.
-
+ 
3. If your problem is not solved, try the following options:
-* Create an issue in the [Zowe GitHub repository](https://github.com/zowe) with a detailed description of the problem you have encountered.
+ * Create an issue in the [Zowe GitHub repository](https://github.com/zowe) with a detailed description of the problem you have encountered.
-* Bring up your questions to the corresponding channels as shown below:
+ * Bring up your questions to the corresponding channels as shown below:
- - [Zowe CLI Slack channel](https://openmainframeproject.slack.com/archives/CC8AALGN6)
- - [Zowe API ML Slack channel](https://openmainframeproject.slack.com/archives/CC5UUL005)
- - [Zowe Chat Slack channel](https://openmainframeproject.slack.com/archives/C03NNABMN0J)
- - [Zowe Documentation Slack channel](https://openmainframeproject.slack.com/archives/CC961JYMQ)
+ - [Zowe API ML Slack channel](https://openmainframeproject.slack.com/archives/CC5UUL005)
+ - [Zowe Chat Slack channel](https://openmainframeproject.slack.com/archives/C03NNABMN0J)
+ - [Zowe CLI Slack channel](https://openmainframeproject.slack.com/archives/CC8AALGN6)
+ - [Zowe Documentation Slack channel](https://openmainframeproject.slack.com/archives/CC961JYMQ)
+ - [Zowe Explorer for VS Code channel](https://openmainframeproject.slack.com/archives/CUVE37Z5F)
-* Reach out to your available Zowe support team for assistance.
+ * Reach out to your available Zowe support team for assistance.
## Known problems and solutions
-Some common problems with Zowe are documented, along with their solutions or workarounds. If you have a problem with Zowe installation and components, review the problem-solution topics to determine whether a solution is available to the problem that you are experiencing.
+Some common problems with Zowe are documented in the Zowe Docs **Troubleshoot** section, along with their solutions or workarounds. If you have a problem with Zowe installation and components, review the problem-solution topics to determine whether a solution is available to the problem that you are experiencing.
You can also find error messages and codes, must-gathers, and information about how to get community support in these topics.
@@ -40,19 +41,17 @@ You can also find error messages and codes, must-gathers, and information about
- [Troubleshooting API Mediation Layer](troubleshoot-apiml.md)
- [Troubleshooting Zowe Application Framework](./app-framework/app-troubleshoot.md)
-
### Troubleshooting Zowe client-side components
- [Troubleshooting Zowe CLI](./cli/troubleshoot-cli.md)
- [Troubleshooting Zowe Explorer](./ze/troubleshoot-ze.md)
- [Troubleshooting Zowe Chat](./zowe-chat-troubleshoot/troubleshooting.md)
-- [Troubleshooting Zowe IntelliJ plug-in](troubleshoot-intellij.md)
+- [Troubleshooting Zowe Explorer plug-in for IntelliJ IDEA](troubleshoot-intellij.md)
## Verifying a Zowe release's integrity
-Following a successful install of a Zowe release, the Zowe runtime directory should contain the code needed to launch and run Zowe. If the contents of the Zowe runtime directory have been modified then this may result in unpredictable behavior. To assist with this Zowe provides the ability to validate the integrity of a Zowe runtime directory, see [Verify Zowe runtime directory](./verify-fingerprint.md)
+Following a successful install of a Zowe release, the Zowe runtime directory should contain the code needed to launch and run Zowe. If the contents of the Zowe runtime directory have been modified, this may result in unpredictable behavior. To assist with this, Zowe provides the ability to validate the integrity of a Zowe runtime directory. See [Verify Zowe runtime directory](./verify-fingerprint.md) for more information.
## Understanding the Zowe release
-Knowing which version of Zowe you are running might help you isolate the problem. Also, the Zowe community who helps you will need to know this information. For more information, see [Understanding the Zowe release](troubleshoot-zowe-release.md).
-
+Knowing which version of Zowe you are running might help you isolate the problem. Also, the Zowe version number is needed by the Zowe community enlisted to help you. To learn how to find the version number, see [Understanding the Zowe release](troubleshoot-zowe-release.md).
diff --git a/docs/troubleshoot/ze/known-ze.md b/docs/troubleshoot/ze/known-ze.md
index 6c8554de48..d810d41a92 100644
--- a/docs/troubleshoot/ze/known-ze.md
+++ b/docs/troubleshoot/ze/known-ze.md
@@ -87,7 +87,7 @@ Detail: File seems to be binary and cannot be opened as text. This is likely cau
There is no solution or workaround at this time.
-## Theia mainframe connection error
+## Visual Studio Code mainframe connection error
**Symptom:**
@@ -101,6 +101,6 @@ When performing an action that requires a mainframe connection (such as searchin
**Solution:**
-In Theia settings, search for `proxy` and change the http.proxySupport setting to `off`, as in the following image:
+In VS Code settings, search for `proxy` and change the http.proxySupport setting to `off`, as in the following image:
diff --git a/docs/troubleshoot/ze/troubleshoot-ze.md b/docs/troubleshoot/ze/troubleshoot-ze.md
index 78153daf1a..3fb4d4fba2 100644
--- a/docs/troubleshoot/ze/troubleshoot-ze.md
+++ b/docs/troubleshoot/ze/troubleshoot-ze.md
@@ -10,12 +10,6 @@ As a Zowe Explorer user, you may encounter problems when using Visual Studio Cod
- The Zowe Explorer and Visual Studio Code versions installed
- See [Checking your Zowe version release number](../troubleshoot-check-your-zowe-version/#zowe-explorer-for-visual-studio-code) for information.
- Node.js and NPM versions installed
- - Whether you have Zowe CLI and the Secure Credential Store (SCS) Zowe CLI plug-in installed
-
- :::note
- Zowe CLI V2 does not require the SCS plug-in to manage security. Security is now managed by Zowe CLI core functionality.
- :::
-
- Your operating system
- Zowe Logs, which usually can be found in `C:\Users\userID\.vscode\extensions\zowe.vscode-extension-for-zowe-X.Y.Z\logs`
@@ -27,7 +21,7 @@ Use [the Slack channel](https://app.slack.com/client/T1BAJVCTY/CUVE37Z5F) to rea
## Connection issues with Zowe Explorer
-If you’re using Zowe Explorer at a site that uses an Internet proxy but cannot connect to a mainframe, ensure that the **Proxy Support** setting in Visual Studio Code is properly configured. Your system administrator can provide information on which option works best for your network environment.
+If you are using Zowe Explorer at a site that uses an Internet proxy but cannot connect to a mainframe, ensure that the **Proxy Support** setting in Visual Studio Code is properly configured. Your system administrator can provide information on which option works best for your network environment.
Note that Zowe Explorer cannot bypass this setting as it would circumvent the VS Code setting applied to all other extensions.
@@ -46,10 +40,7 @@ System administrators can also add IP addresses, IP ranges, or DNS hostnames for
A problem with a configuration file can make Zowe Explorer unable to read your configurations.
-Zowe Explorer displays an error message advising it cannot read the configuration file when either:
-
-- A Zowe v1 profile is invalid.
-- A Zowe v2 configuration file fails to load.
+Zowe Explorer displays an error message advising it cannot read the configuration file when a Zowe V3 configuration file fails to load.
Possible problems in the file could include a syntax error, or an invalid keyword or symbol.
diff --git a/docs/troubleshoot/ze/ze-issues.md b/docs/troubleshoot/ze/ze-issues.md
index 064ef9cd2b..912456edb4 100644
--- a/docs/troubleshoot/ze/ze-issues.md
+++ b/docs/troubleshoot/ze/ze-issues.md
@@ -1,6 +1,6 @@
# Raising a Zowe Explorer issue on GitHub
-You can raise GitHub issues against [the Zowe Explorer repository](https://github.com/zowe/zowe-explorer-vscode/issues). It is suggested that you use either the bug or feature request.
+When necessary, raise a GitHub issue in the [Zowe Explorer for Visual Studio Code repository](https://github.com/zowe/zowe-explorer-vscode/issues). It is suggested that you use either the bug or feature request.
## Raising a bug report
diff --git a/docs/troubleshoot/ze/ze-known-limits.md b/docs/troubleshoot/ze/ze-known-limits.md
index e9e6fbd16b..2bdd5f15e0 100644
--- a/docs/troubleshoot/ze/ze-known-limits.md
+++ b/docs/troubleshoot/ze/ze-known-limits.md
@@ -1,24 +1,24 @@
# Known Zowe Explorer limitations
-### Mismatched credentials when using Zowe Explorer and Zowe CLI
+## Mismatched credentials when using Zowe Explorer and Zowe CLI
-#### **Limitation**
+### Limitation
Mismatching credentials can potentially lock you out from using Zowe CLI and Zowe Explorer in Visual Studio Code with either Windows Subsystem for Linux (WSL) or Remote Secure Shell (SSH).
-WSL allows developers to run a Linux environment on Windows without the need for a separate virtual machine or dual booting. When using Zowe Explorer with WSL, two parallel processes take place: VS Code runs on the Windows operating system, while code execution and tooling happen within the Linux environment.
+WSL allows developers to run a Linux environment on Windows without the need for a separate virtual machine or dual booting. When using Zowe Explorer with WSL, two parallel processes take place: VS Code runs on the Windows operating system, while code execution and tooling happen within the Linux environment.
-With Remote SSH, the network protocol provides users with a secure connection to a remote computer. When using this protocol with Zowe Explorer, you can securely connect to a remote machine or a remote development environment.
+With Remote SSH, the network protocol provides users with a secure connection to a remote computer. When using this protocol with Zowe Explorer, you can securely connect to a remote machine or a remote development environment.
Both WSL and Remote SSH provide more tools for mainframe developers, but they also have limitations when it comes to credentials.
-Authentication information used in Zowe Explorer — such as usernames and passwords, SSH keys, API Mediation Layer tokens — resides on the developer’s local machine, not the Linux environment or the remote server or virtual machine. This is because credential storage is managed by VS Code, which stores them using the host's operating system credential manager.
+Authentication information used in Zowe Explorer — such as usernames and passwords, SSH keys, and API Mediation Layer tokens — resides on the developer’s local machine, provided the developer is not connected to a remote environment through VS Code. If you are connected to a remote environment through VS Code, your secure credentials are stored on the remote system.
Using the VS Code integrated terminal with virtual machines does not include access to the credentials stored by Zowe Explorer in the local machine. Zowe CLI, for example, is not able to retrieve credentials saved on a developer’s PC when accessing the mainframe. Instead, Zowe CLI attempts to use any credentials stored in the virtual machine.
This can lead to confusion and inconsistencies when authenticating and accessing resources.
-#### **Workaround**
+### Workaround
It is crucial to ensure that credentials are carefully managed between the local machine and the remote server to maintain proper authentication.
diff --git a/docs/user-guide/ZE-install-checklist.md b/docs/user-guide/ZE-install-checklist.md
new file mode 100644
index 0000000000..5f0a4e74f8
--- /dev/null
+++ b/docs/user-guide/ZE-install-checklist.md
@@ -0,0 +1,34 @@
+# Zowe Explorer installation checklist
+
+This checklist outlines the required steps for a first-time installation of Zowe Explorer.
+
+:::info Required roles: systems administrator, devops architect, security administrator, systems programmer
+:::
+
+The checklist includes a brief description of the steps required for installation of Zowe Explorer. The checklist also identifies the roles that are typically required to complete the step, which enables the pre-installation planning team to focus on the tasks for which they are responsible.
+
+For a printable version of this checklist, click here.
+
+## Preparing for installation
+
+| Step | Description | Role | Time Estimate |
+| ----------- | ----------- | ---------- | ------------- |
+|[Addressing Zowe Explorer system requirements](../getting-started/ZE-system-reqs.md) | Check the following items:
Required step when using a z/OSMF profile connection. | Systems programmer | 40 min. | +| (Optional) [Configuring z/OSMF security](../user-guide/cli-install-configure-zosmf-security.md) | Configure security for:
+
+
+The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs.
+
+Install the extension directly to [VSCode](https://code.visualstudio.com/) to enable the extension within the GUI. Working with data sets and USS files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI experience. The extension provides the following benefits:
+
+- Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe.
+- Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe.
+- Provides a more streamlined way to access data sets, USS files, and jobs.
+- Lets you create, edit, and delete Zowe CLI `zosmf` compatible profiles.
+
+**Note:** Zowe Explorer is a subcomponent of [Zowe](https://zowe.org/home/). The extension demonstrates the potential for plug-ins powered by Zowe.
+
+## Software Requirements
+
+Ensure that you meet the following prerequisites before you use the extension:
+
+- Get access to z/OSMF.
+- Install [Visual Studio Code](https://code.visualstudio.com/).
+- Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](https://docs.zowe.org/stable/user-guide/systemrequirements-zosmf#z-os-requirements).
+- Create a Zowe CLI `zosmf` profile so that the extension can communicate with the mainframe.
+- For development, install [Node.js](https://nodejs.org/en/download/) v14.0 or later.
+
+### Profile notes:
+
+- You can use existing Zowe CLI `zosmf` profiles created with Zowe CLI v.2.0.0 or later.
+
+- Zowe CLI `zosmf` profiles that are created in Zowe Explorer can be interchangeably used in Zowe CLI.
+
+- *Optionally*, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see [Working with Zowe Explorer profiles](https://docs.zowe.org/stable/user-guide/ze-profiles#working-with-zowe-explorer-profiles).
+
+## Installing Zowe Explorer
+
+Use the following steps to install Zowe Explorer:
+
+1. Address [the software requirements](#software-requirements).
+2. Open Visual Studio Code, and navigate to the **Extensions** tab on the **Activity Bar**.
+3. Type `Zowe Explorer` in the **Search** field.
+
+ Zowe Explorer appears in the list of extensions in the **Side Bar**.
+
+4. Click the green **Install** button to install the extension.
+5. Restart Visual Studio Code.
+
+The extension is now installed and available for use.
+
+* **Note:** For information about how to install the extension from a `VSIX` file and run system tests on the extension, see the [Developer README](https://github.com/zowe/vscode-extension-for-zowe#build-locally).
+
+You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data sets.
+
+
+
+
+
+## Configuring Zowe Explorer
+
+Configure Zowe Explorer in the settings file of the extension.
+
+To access the extension settings, follow these steps:
+
+1. Click the **Settings** icon at the bottom of the **Activity Bar**.
+
+2. Select the **Settings** option.
+3. Open the **Extension** option listed in the **Commonly Used** menu.
+4. Select **Zowe Explorer** to access its settings.
+5. Scroll the list to find the setting that needs modification.
+
+### Modifying creation settings for data sets, USS files, and jobs
+
+Follow these steps:
+
+1. In Zowe Explorer settings, scroll to a data set, USS file, or job setting type.
+2. Click the setting's corresponding **Edit in settings.json** link.
+
+ This opens the `settings.json` file in an **Editor** tab. (The suggestions widget also opens if the functionality is enabled.)
+
+3. Edit the settings in the file as needed.
+4. Save the file to keep changes.
+
+ 
+
+### Modifying temporary file location settings
+
+Change the default folder location where temporary files are stored with the following steps:
+
+ 1. Navigate to Zowe Explorer settings.
+ 2. Under the data set, USS, or jobs settings that you want to edit, click the **Edit in settings.json** link.
+ 3. Modify the following definition in the file:
+
+ ```json
+ "zowe.files.temporaryDownloadsFolder": {
+ "folderPath": "/path/to/directory"
+ }
+ ```
+
+ Replace **/path/to/directory** with the new folder location.
+
+4. Save the file to keep the change.
+
+### Modifying the `Secure Credentials Enabled` setting
+
+When environment conditions do not support the Zowe CLI built-in Credential Manager, change the `Secure Credentials Enabled` setting with the following steps:
+
+ 1. Navigate to Zowe Explorer settings.
+ 2. Scroll to **Security: Secure Credentials Enabled**.
+ 3. Deselect the checkbox to disable secure credentials.
+
+ When disabled, if the `autoStore` setting in the `zowe.config.json` file is set to *true*, z/OS credentials are stored as text in the file.
+
+ If the `autoStore` setting is set to *false*, you are prompted for the missing credentials in Visual Studio Code. These are stored and used for the duration of the session.
+
+### Setting confirmation requirements for submitting jobs
+
+Submitting the wrong job can risk potential problems on your server. This can happen when the user enters the wrong job or inadvertently selects the **Submit Jobs** option.
+
+To help prevent this, enable the option to require confirmation before submitting a job. Once enabled, a dialog window asking for user confirmation displays when **Submit Jobs** is selected.
+
+
+
+To configure confirmation settings for submitting a job, follow these steps:
+
+1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor.
+
+2. Select the **User** or **Workspace** tab, depending on the settings you want to update.
+3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**.
+4. In the **Jobs: Confirm Submission** section, open the drop-down menu to select a different confirmation setting.
+ - If enabled, a confirmation dialog displays when a job matching the selected option is submitted.
+
+## Relevant Information
+
+In this section you can find useful links and other information relevant to Zowe Explorer that can improve your experience with the extension.
+
+- For information about how to develop for Eclipse Theia, see [Theia README](https://github.com/zowe/vscode-extension-for-zowe/wiki/Developing-for-Theia).
+- For information about how to create a VSCode extension for Zowe Explorer, see [VSCode extensions for Zowe Explorer](https://github.com/zowe/vscode-extension-for-zowe/wiki/Extending-Zowe-Explorer).
+
+- Visit the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) for questions and general guidance.
diff --git a/docs/user-guide/address-authentication-requirements.md b/docs/user-guide/address-authentication-requirements.md
index 48b2ba06f1..5534342e9e 100644
--- a/docs/user-guide/address-authentication-requirements.md
+++ b/docs/user-guide/address-authentication-requirements.md
@@ -15,8 +15,6 @@ Multi-factor authentication is provided by third-party products with which Zowe
To support the multi-factor authentication, it is necessary to apply z/OSMF APAR [PH39582](https://www.ibm.com/support/pages/apar/PH39582).
-For information about using MFA in Zowe Application Framework, see [Application Framework Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration).
-
:::important
Multi-factor authentication requires configuration with Single-Sign-On (SSO). Ensure that SSO is configured before you use MFA in Zowe.
@@ -24,14 +22,18 @@ Multi-factor authentication requires configuration with Single-Sign-On (SSO). En
## Single Sign On (SSO)
-Zowe has an SSO scheme with the goal that each time you use multiple Zowe components you should only be prompted to login once.
+Zowe has an SSO scheme with the goal that each time you use multiple Zowe components you should only be prompted to login once.
Requirements:
- IBM z/OS Management Facility (z/OSMF)
-For more information about single sign on (SSO), see [Zowe API Mediation Layer Single Sign On Overview](./api-mediation-sso).
+:::note Notes:
+- For more information about single sign on (SSO) for users, see [Zowe API Mediation Layer Single Sign On Overview](./api-mediation-sso.md).
+
+- For more information about single sign on (SSO) for extenders, see [Single Sign On Integration for Extenders](../extend/extend-apiml/api-medation-sso-integration-extenders.md).
+:::
## API Mediation Layer OIDC Authentication
diff --git a/docs/user-guide/address-network-requirements.md b/docs/user-guide/address-network-requirements.md
index 7ea8cd452a..16b94b1574 100644
--- a/docs/user-guide/address-network-requirements.md
+++ b/docs/user-guide/address-network-requirements.md
@@ -8,19 +8,57 @@ Values presented in the table are default values. You can change the values by u
For more information about variable names in the following table, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) in the References section.
+## Component Ports
+
+Most Components of Zowe are HTTPS servers. The ports of each and their default jobnames are listed below.
+The ports can be customized for each component by editing the value of `components..port` within the Zowe YAML file.
+Each Jobname has a default prefix of ZWE1, but that can be customized via the `zowe.job.prefix` value in the Zowe YAML file.
+
+| Port number | Category | Component | Default Jobname | Log Suffix | Purpose |
+|------|------|------|------|------|------|
+| 7552 | API Mediation Layer | api-catalog | ZWE1**AC** | AAC | Used to view API swagger / openAPI specifications for registered API services in the API Catalog.
+| 7553 | API Mediation Layer | discovery | ZWE1**AD** | ADS | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
+| 7554 | API Mediation Layer | gateway | ZWE1**AG** | AGW | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services. This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
+| 7555 | API Mediation Layer | caching-service | ZWE1**CS** | ACS | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
+| 7556 | App Framework | app-server | ZWE1**DS** & ZWE1SV | D | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
+| 7557 | App Framework | zss | ZWE1**SZ** | SZ | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
+| 7558 | API Mediation Layer | zaas | ZWE1**AZ** | AZ |
+
+## Application Server Jobname for Port
+The jobnames associated with the component "app-server" varies depending on whether cluster mode is enabled or not (default: enabled).
+
+| Cluster mode | Jobname for listener port | Jobname for worker processes |
+|---|---|---
+| Enabled (Default) | Name of STC (default: ZWE1SV) | `zowe.job.prefix` + DS (default: ZWE1**DS**) |
+| Disabled | `zowe.job.prefix` + DS (default: ZWE1**DS**) | Not Applicable |
+
+To enable or disable cluster mode, see the [Advanced Application Framework Configuration Guide](./mvd-configuration.md).
+
+## Caching Service Infinispan ports
+
+The Caching Service will use these additional ports if enabled (`zowe.components.caching-service.enabled: true`) and set to use infinispan (the default, `zowe.components.caching-service.storage.mode: infinispan`).
+
| Port number | zowe.yaml variable name | Purpose |
|------|------|------|
-| 2157 | NA | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
-| 7098 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
-| 7552 | zowe.components.api-catalog.port | Used to view API swagger / openAPI specifications for registered API services in the API Catalog.
-| 7553 | zowe.components.discovery.port | Discovery server port which dynamic API services can issue APIs to register or unregister themselves.
-| 7554 | zowe.components.gateway.port | The northbound edge of the API Gateway used to accept client requests before routing them to registered API services. This port must be exposed outside the z/OS network so clients (web browsers, VS Code, processes running the Zowe CLI) can reach the gateway.
-| 7555 | zowe.components.caching-service.port | Port of the caching service that is used to share state between different Zowe instances in a high availability topology.
-| 7556 | zowe.components.app-server.port | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers.
-| 7557 | zowe.components.zss.port | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop.
-| 7558 | zowe.components.jobs-api.port | Port of the service that provides REST APIs to z/OS jobs used by the JES Explorer.
-| 7559 | zowe.components.files-api.port | Port of the service that provides REST APIs to MVS and USS file systems.
-| N/A | zowe.components.explorer-jes | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop.
-| N/A | zowe.components.explorer-mvs | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop.
-| N/A | zowe.components.explorer-uss | Port of the USS Explorer GUI for working with USS in the Zowe Desktop.
+| 7601 | zowe.components.caching-service.storage.infinispan.jgroups.keyExchange.port | The port at which the key server in Infinispan is listening. If the port is not available, the next port is probed, up to port+5. Used by the key server (server) to create an SSLServerSocket and by clients to connect to the key server.
+| 7600 | zowe.components.caching-service.storage.infinispan.jgroups.port | Bind port for the socket that is used to form an Infinispan cluster.
+
+## IP Addresses
+
+Zowe's servers by default use the TCP IP address `0.0.0.0` which assigns the servers to be available on all network interfaces available to the jobs.
+
+If this default is not desired, it is recommended to use [TCPIP port assignment statements](https://www.ibm.com/docs/en/zos/2.4.0?topic=assignments-profiletcpip-port) to restrict the IP & ports of each server by their jobnames. The jobnames of each Zowe component is derived from the property `zowe.job.prefix` and `` as shown in the table prior.
+
+When `zowe.job.prefix` is "ZWE1", An example of port reservations with a fixed IP of "10.11.12.13" could be:
+
+```
+ 7552 TCP ZWE1AC BIND 10.11.12.13 ; Zowe API Catalog
+ 7553 TCP ZWE1AD BIND 10.11.12.13 ; Zowe Discovery
+ 7554 TCP ZWE1AG BIND 10.11.12.13 ; Zowe Gateway
+ 7555 TCP ZWE1CS BIND 10.11.12.13 ; Zowe Caching Service
+ 7556 TCP ZWE1DS BIND 10.11.12.13 ; Zowe App Server without Cluster
+ 7556 TCP ZWE1SV BIND 10.11.12.13 ; Zowe App Server with Cluster (Default)
+ 7557 TCP ZWE1SZ BIND 10.11.12.13 ; Zowe ZSS
+ 7558 TCP ZWE1AZ BIND 10.11.12.13 ; Zowe ZAAS
+```
diff --git a/docs/user-guide/address-storage-requirements.md b/docs/user-guide/address-storage-requirements.md
index 8c2c3a42e2..136537681b 100644
--- a/docs/user-guide/address-storage-requirements.md
+++ b/docs/user-guide/address-storage-requirements.md
@@ -7,11 +7,11 @@ Ensure that you have sufficient storage depending on the installation method. Re
## Installing with SMP/E
-Before installing Zowe SMP/E, review the [DASD storage requirements](../user-guide/install-zowe-smpe/#dasd-storage-requirements).
+Before installing Zowe SMP/E, review the [DASD storage requirements](../user-guide/install-zowe-smpe-overview.md#dasd-storage-requirements).
## Installing Zowe runtime from a convenience build
-Before installing Zowe runtime from a convenience build, see the [storage requirements associated with MVS datasets](../user-guide/install-zowe-zos-convenience-build/#step-5-install-the-mvs-data-sets).
+Before installing Zowe runtime from a convenience build, see the [storage requirements associated with MVS datasets](../user-guide/install-zowe-zos-convenience-build.md#about-the-mvs-data-sets).
### Memory requirements for API Mediation Layer
@@ -22,6 +22,5 @@ Component name | Memory usage
Gateway service | 256MB
Discovery service | 256MB
API Catalog | 512MB
-Metrics service | 512MB
Caching service | 512MB
diff --git a/docs/user-guide/apf-authorize-load-library.md b/docs/user-guide/apf-authorize-load-library.md
index f95c51b891..7a5a1d81b9 100644
--- a/docs/user-guide/apf-authorize-load-library.md
+++ b/docs/user-guide/apf-authorize-load-library.md
@@ -27,11 +27,9 @@ APF authorize IBMUSER.ZWEV2.CUST.ZWESAPL
#>
```
:::note
-If you do not have permissions to update your security configurations, use `security-dry-run`. We recommend you inform your security administrator to review your job content.
+If you do not have permissions to update your security configurations, append the flag `--security-dry-run` to have the command echo the commands that need to be run without executing the command. We recommend you inform your security administrator to review your job content.
:::
-Specify `--security-dry-run` to have the command echo the commands that need to be run without executing the command.
-
```
SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS
SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.CUST.ZWESAPL,SMS
diff --git a/docs/user-guide/api-mediation-change-password-via-catalog.md b/docs/user-guide/api-mediation-change-password-via-catalog.md
index c05cf3b24a..1d8ab29056 100644
--- a/docs/user-guide/api-mediation-change-password-via-catalog.md
+++ b/docs/user-guide/api-mediation-change-password-via-catalog.md
@@ -1,6 +1,6 @@
# Changing an expired password via API Catalog
-In case of expiration of a mainframe password, the API Catalog offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message:
+In case of expiration of a mainframe password, the API Catalog, when using SAF as authentication provider offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message:
![api refresh error]({require("../images/api-mediation/catalog-pass-expired-warn.png").default})
diff --git a/docs/user-guide/api-mediation-metrics-service.md b/docs/user-guide/api-mediation-metrics-service.md
deleted file mode 100644
index 2dc6f192c0..0000000000
--- a/docs/user-guide/api-mediation-metrics-service.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Using Metrics Service (Technical Preview)
-
-As a system administrator, use the Metrics Service to view information about the acitivty of services running in the API Mediation Layer.
-Currently, only HTTP metrics are displayed for core API Mediation Layer services.
-
-In order for the Metrics Service to run, you must set `components.metrics-service.enabled` in `zowe.yaml` to `true`. Additionally, for each APIML service you want to have metrics collected for, you must set `components..apiml.metrics.enabled` set to `true` in `zowe.yaml`, or `configs.apiml.metrics.enabled` set to `true` in the service's manifest. When metrics are enabled for the API Gateway, the Gateway homepage displays a link to the Metrics Service dashboard. The dashboard is available at `https://{gateway_host}:{gateway_port}/metrics-service/ui/v1`.`
-
-## API Mediation Layer Metrics Service Demo Video
-
-Watch this [video](https://youtu.be/KkuE6xADxPk) to see a demo of the Metrics Service.
-
-
-
-## View HTTP Metrics in the Metrics Service Dashboard
-
-Use the Metrics Service to view HTTP metrics such as number of requests, response times, and error rates. The below image describes the information provided in the Metrics Service dashboard.
-
-
-
-To view the HTTP metrics for a service, select the corresponding tab in the Metrics Service dashboard. Metrics are displayed for each endpoint of a service, aggregated from all service instances.
-
-**Example:**
-
-![discoverable client api v1]({require("../images/api-mediation/metrics-service-dashboard.png").default})
-
-Metrics are provided on a near real-time basis, so the display shows the current activity of the selected service. At this time there is no persistence for this information.
-
-Service instances expose their HTTP metrics at `https://:/application/hystrix.stream` using the Server-Sent-Events protocol. The Metrics Service collects these streams and aggregates them across service instances before displaying.
-
-**Note:** At this time, the `/application/hystrix.stream` endpoint for a service does not require authentication if metrics are enabled for that service. If metrics for that service are not enabled, `/application/hystrix.stream` is protected by authentication.
diff --git a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md b/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md
deleted file mode 100644
index 97d9256a24..0000000000
--- a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# API Gateway REST APIs
-
-The API Gateway provides different functionalities and implements several REST APIs to leverage these functionalities:
-
-* [Update User Password](api-mediation-update-password.md)
-* [JWT token refresh endpoint](api-mediation-jwt-token-refresh.md)
-* [Personal Access Tokens](../api-mediation/authenticating-with-personal-access-token)
diff --git a/docs/user-guide/api-mediation/api-mediation-caching-service.md b/docs/user-guide/api-mediation/api-mediation-caching-service.md
index 6078edb29d..aa1cc5cbe9 100644
--- a/docs/user-guide/api-mediation/api-mediation-caching-service.md
+++ b/docs/user-guide/api-mediation/api-mediation-caching-service.md
@@ -1,13 +1,14 @@
# Using the Caching Service
-As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless in two ways:
+As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless by using following backends:
-- Using VSAM to store key/value pairs for production
-
-- Using InMemory
+- Using Infinispan that is part of Caching Service
+- Using Redis running off-platform
+- \{Deprecated\} Using VSAM
+- \{Development Use Only\} Using InMemory
:::note
-In the current implementation of the Caching Service, VSAM is required for the storage of key/value pairs for production, as VSAM is a native z/OS solution for storing key/value pairs.
+In the current implementation of the Caching Service, Infinispan is recommended for the storage of key/value pairs for production, as it has the best performance characteristics without additional services.
:::
The Caching Service is available only for internal Zowe applications, and is not exposed to the internet. The Caching service supports a hot-reload scenario in which a client service requests all available service data.
@@ -15,7 +16,7 @@ The Caching Service is available only for internal Zowe applications, and is not
- [Architecture](#architecture)
- [Storage methods](#storage-methods)
- [Infinispan](#infinispan-recommended)
- - [VSAM](#vsam)
+ - [VSAM](#vsam-deprecated)
- [Redis](#redis)
- [InMemory](#inmemory)
- [How to start the service](#how-to-start-the-service)
@@ -30,12 +31,14 @@ A precondition to provide for High Availability of all components within Zowe is
REST APIs make it possible to create, delete, and update key-value pairs in the cache. Other APIs read a specific key-value pair or all key-value pairs in the cache.
Information from cached APIs is stored as a JSON in the following format:
+
```yml
{
“key”: “keyValue”,
“value”: “valueValue”
}
```
+
## Storage methods
The Caching Service supports the following storage solutions, which provide the option to add custom implementation.
@@ -48,7 +51,7 @@ Infinispan is a storage solution that can also run on the z/OS platform. It can
For more information about the Infinispan storage access method, see [Using Infinispan as a storage solution through the Caching service](../../extend/extend-apiml/api-mediation-infinispan.md).
-### VSAM
+### VSAM (deprecated)
VSAM can be used to organize records into four types of data sets: key-sequenced, entry-sequenced, linear, or relative record. Use VSAM as the storage solution for production. VSAM is used primarily for applications and is not used for source programs, JCL, or executable modules. ISPF cannot be used to display or edit VSAM files.
@@ -60,11 +63,10 @@ Redis is a common storage solution that runs outside of the z/OS platform. It ca
For more information about the Redis storage access method, see [Using Redis as a storage solution through the Caching Service](../../extend/extend-apiml/api-mediation-redis.md).
-
### InMemory
-The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production.
-The key/value pairs are stored only in the memory of a single instance of the service. As such, the key/value pairs do not persist.
+The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production.
+The key/value pairs are stored only in the memory of a single instance of the service. As such, the key/value pairs do not persist.
## How to start the Service
@@ -122,11 +124,13 @@ This parameter specifies service behavior when the limit of records is reached.
## Authentication
### Direct calls
+
The Caching Service requires TLS mutual authentication. This verifies authenticity of the client. Calls without a valid client certificate generate a `403` response code: `Forbidden`. This requirement is disabled when `VERIFY_CERTIFICATES=false` in `zowe-certificates.env` configuration file.
-The call must have a header `X-Certificate-DistinguishedName` containing information about the certificate's distinguished name. This header is added by the API Gateway. For a direct call, this header needs to be added manually. Calls without this header produce a `401` response code: `Unauthorized`.
+The call must have a header `X-Certificate-DistinguishedName` containing information about the certificate's distinguished name. This header is added by the API Gateway. For a direct call, this header needs to be added manually. Calls without this header produce a `401` response code: `Unauthorized`.
### Routed calls through API Gateway
+
Caching service registers with the following authentication scheme to Discovery service:
```yaml
diff --git a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
index b86b83fe66..794c764ac6 100644
--- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
+++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
@@ -2,83 +2,61 @@
Zowe supports management of multiple tenants, whereby different tenants can serve different purposes or different customers. The use case for multi-tenant support is when a service provider manages sysplexes/monoplexes for multiple customers. This configuration makes it possible to have a single access point for all customers, and properly route and authenticate across different domains.
-- [Multitenancy Configuration](#multitenancy-configuration)
- - [Overview of API MLs](#overview-of-api-mls)
- - [Multitenancy component enablement settings](#multitenancy-component-enablement-settings)
- - [Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain](#onboarding-a-gateway-service-in-one-domain-to-the-discovery-service-of-api-ml-in-another-domain)
- - [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml)
- - [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables)
- - [Validating successful configuration](#validating-successful-configuration)
- - [Establishing a trust relationship between the API MLs](#establishing-a-trust-relationship-between-the-api-mls)
- - [Commands to establish trust between the API MLs](#commands-to-establish-trust-between-the-api-mls)
- - [Using the `/registry` endpoint in the Gateway](#using-the-registry-endpoint-in-the-gateway)
- - [Configuration for `/registry`](#configuration-for-registry)
- - [Authentication for `/registry`](#authentication-for-registry)
- - [Authorization with `/registry`](#authorization-with-registry)
- - [Requests with `/registry`](#requests-with-registry)
- - [Response with `/registry`](#response-with-registry)
- - [Response with `/registry{apimlId}`](#response-with-registryapimlid)
- - [Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`](#response-with-get-gatewayapiv1registryapimlidapiidapiidserviceidserviceid)
- - [Validating successful configuration with `/registry`](#validating-successful-configuration-with-registry)
- - [Troubleshooting multitenancy configuration](#troubleshooting-multitenancy-configuration)
- - [ZWESG100W](#zwesg100w)
- (#no-debug-messages-similar-to-apiml1-completed-with-oncomplete-are-produced)
-
-## Overview of API MLs
+## Overview of API MLs
The following diagram illustrates communication between the API Mediation Layers and Zowe in multiple domains. Note that some API MLs may be running in a sysplex (HA), while others may be in a monoplex (non-HA).
- As represented in the example diagram of Multitenacy environement where the APIMLs in Domain(2-N) are registered to APIML in Domain-1. The APIML in Domain-1 may be running on z/OS, or off z/OS, for example in Kubernetes, this API ML serves as a single point of access to all API Mediation Layers registered in this and, by extension, to all services registered in those API MLs.
+The diagram illustrates a Multitenacy environment where the API MLs in Domain(2-N) are registered to API ML in Domain-1. The API ML in Domain-1 may be running on z/OS, or off z/OS, for example in Kubernetes. This API ML serves as a single point of access to all API Mediation Layers registered in this and, by extension, to all services registered in those API MLs.
-The APIMLs in Domain(2-N) are installed on z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are registered to APIML in Domain-1.
+The API MLs in Domain(2-N) are installed on z/OS systems with the standard Zowe API ML running either in HA (sysplex) or non-HA (monoplex). These API MLs are registered to API ML in Domain-1.
## Multitenancy component enablement settings
-In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one API ML (APIML in Domain-1 in our example diagram) that handles the discovery and registration as well as routing to the other API MLs (APIMLs in Domain(2-N) in our example diagram) installed in any other specific domains.
+In the multitenancy environment, certain Zowe components may be enabled, while others may be disabled. The multitenancy environment expects one API ML (for example API ML in Domain-1) that handles the discovery and registration as well as routing to the other API MLs (API MLs in Domain(2-N)) installed in any other specific domains.
## Onboarding a Gateway service in one domain to the Discovery service of API ML in another domain
-A Gateway from any domain can onboard Gateways of any domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration.
+A Gateway from any domain can onboard Gateways of any other domains. Onboarding this service can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration.
- [Dynamic configuration via zowe.yaml](#dynamic-configuration-via-zoweyaml)
- [Dynamic configuration via Environment variables](#dynamic-configuration-via-environment-variables)
### Dynamic configuration via zowe.yaml
-1. Set the following property for the Gateway of APIMLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1.
+1. In zowe.yml, set the following property for the Gateway of API MLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1:
`components.gateway.apiml.service.additionalRegistration`
- Use the following example as a template for how to set the value of this property in zowe.yml.
+Use the following example as a template for how to set the value of this property in zowe.yaml.
- **Example:**
- ```
- components.gateway.apiml.service.additionalRegistration:
- # APIML in Domain-1 (in HA, for non-HA mode use only 1 hostname)
- - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
- ```
+**Example:**
+```
+components.gateway.apiml.service.additionalRegistration:
+ # APIML in Domain-1 (in HA, for non-HA mode use only 1 hostname)
+ - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
+ ```
- :::note Notes:
- * Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
+:::note Notes:
+ * Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
- * We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
+ * We highly recommend to provide all available Discovery URLs in the value `discoveryServiceUrls`.
- * Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour.
+ * Always provide the direct address to the system. Do not use the DVIPA address. Using this DVIPA address could lead to unexpected behaviour.
- * Use hostnames `sys1` and `sys2` for the LPAR in the sysplex.
- :::
+ * Use hostnames `sys1` and `sys2` for the LPAR in the sysplex.
+:::
2. (Optional) Configure the Gateway to forward client certificates.
-Use this step to enable the domain(2-N) gateway to use this client certificate for authentication. .
-Set the `certificatesUrl` property to ensure that only Gateway-forwarded certificates are used for client certificate authentication. This URL returns a certificate chain from the gateway.
+Use this step to enable the domain(2-N) Gateway to use this client certificate for authentication.
+Set the `certificatesUrl` property to ensure that only Gateway-forwarded certificates are used for client certificate authentication. This URL returns a certificate chain from the Gateway.
- ```
- components.gateway.apiml.security.x509:
- # gateway port in domain-1
- certificatesUrl: https://{gatewayHost}:{gatewayPort}/gateway/certificates
- ```
+```
+components.gateway.apiml.security.x509:
+ # gateway port in domain-1
+ certificatesUrl: https://{gatewayHost}:{gatewayPort}/gateway/certificates
+```
### Dynamic configuration via Environment variables
@@ -88,11 +66,14 @@ The previous example can be substituted with the following variables:
```
ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_DISCOVERYSERVICEURLS=https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
+ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_GATEWAYURL=/
+ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/
```
+* **#**
+`#` in `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*` specifies the ID of API ML instance.
+
:::note Notes:
- * The number in the properties names (see position of `#` in `ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_#_*`)
- defines ID of API ML instance.
* Ensure that each API ML instance is defined in a separated record. Do not combine multiple API ML instances in a
single record. In the case of a high availability setup, the value `discoveryServiceUrls` may contain multiple URLs.
@@ -107,7 +88,7 @@ This Zowe configuration transforms the zowe.yaml configuration file into the env
### Validating successful configuration
-The corresponding Gateway service in domain(2-N) should appear in the Eureka console of the Discovery service in the domain-1 API ML.
+The corresponding Gateway service in domain(2-N) should appear in the Eureka console of the Discovery service in the domain-1 API ML.
To see details of all instances of the ‘GATEWAY’ application, perform a **GET** call on the following endpoint of the Discovery service in domain-1 API ML:
@@ -117,35 +98,36 @@ To see details of all instances of the ‘GATEWAY’ application, perform a **GE
## Establishing a trust relationship between the API MLs
-For routing to work in a multitenancy configuration, as represented in the example diagram above where "Domain APIML 2", "Domain APIML 3" are registered to "Domain APIML 1", the "Domain APIML 1" must trust the "Domain APIML 2", "Domain APIML 3" for successful registration into it's Discovery Service component.
-The "Domain APIML 2", "Domain APIML 3" must trust the "Domain APIML 1" Gateway where they are registered to, to accept routed requests.
-It is necessary that the root and, if applicable, intermediate public certificates be shared between these domain API Mediation Layers.
+For routing to work in a multitenancy configuration, as represented in the previous diagram where "Domain API ML 2" and "Domain API ML 3" are registered to "Domain API ML 1", "Domain API ML 1" must trust "Domain API ML 2" and "Domain API ML 3". This trust is required for successful registration into the Discovery Service component of Domain API ML 1.
+
+To accept routed requests, "Domain API ML 2" and "Domain API ML 3" must trust the "Domain API ML 1" Gateway where Domains API ML 2 and 3 are registered to.
+It is necessary that the root and, if applicable, intermediate public certificates are shared between these domain API Mediation Layers.
The following diagram shows the relationship between the API MLs.
-As presented in this example diagram, The API MLs are installed on systems X, Y and Z.
+As illustrated in this example diagram, The API MLs are installed on systems X, Y, and Z.
-To establish secure communications, "Domain APIML 2" and "Domain APIML 3" are using different private keys signed with different public keys. These API MLs do not trust each other.
+To establish secure communications, "Domain API ML 2" and "Domain API ML 3" use different private keys signed with different public keys. These API MLs do not trust each other.
-In order for all API MLs to register with an "Domain APIML 1" in multitenancy set up, it is necessary that the "Domain APIML 1" has all public keys from the certificate chains of all registered API MLs:
+In multitenancy set up, in order for all API MLs to register with "Domain API ML 1", it is necessary that "Domain API ML 1" has all public keys from the certificate chains of all registered API MLs:
* DigiCert Root CA
* DigiCert Root CA1
* DigiCert CA
-These public keys are required for the "Domain APIML 1" to establish trust with "Domain APIML 2" and "Domain APIML 3".
+These public keys are required for the "Domain API ML 1" to establish trust with "Domain API ML 2" and "Domain API ML 3".
-The "Domain APIML 1" uses a private key which is signed by the Local CA public key for secure communication.
+"Domain API ML 1" uses a private key which is signed by the local CA public key for secure communication.
-"Domain APIML 2" and "Domain APIML 3" require a Local CA public key in order to accept the routing requests from the "Domain APIML 1", otherwise the "Domain APIML 1" requests will not be trusted by the registered API MLs.
-The diagram indicates all of the added certificates inside the red dashed lines.
+"Domain API ML 2" and "Domain API ML 3" require a local CA public key to accept routing requests from "Domain API ML 1". Without these local CA public keys "Domain API ML 1" requests will not be trusted by the registered API MLs.
+All added certificates are indicated in the diagram inside the red dashed lines.
### Commands to establish trust between the API MLs
The following commands are examples of establishing a trust relationship between API MLs in Multitenancy Configuration for both PKCS12 certificates and when using keyrings.
-1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain APIML 2" , "Domain APIML 3" API MLs running on systems Y and Z into the truststore of the "Domain APIML 1" running on system X.
+1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain API ML 2" and "Domain API ML 3" API MLs running on systems Y and Z into the truststore of the "Domain API ML 1" running on system X.
- **PKCS12**
@@ -162,12 +144,11 @@ The following commands are examples of establishing a trust relationship between
- **Keyring**
- For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1":
-
-
Click here for command details for Top Secret.
+**For Top Secret** + +
+
@@ -125,12 +150,15 @@ User specified parameters are presented in the section [Parameters in the ESM co TSS REFRESH ``` - For more details about mapping a distributed identity username and a distributed registry name to a Top Secret ACID, see [IDMAP Keyword - Implement z/OS Identity Propagation Mapping](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/issuing-commands-to-communicate-administrative-requirements/keywords/idmap-keyword-implement-z-os-identity-propagation-mapping.html). +For more details about mapping a distributed identity username and a distributed registry name to a Top Secret ACID, see [IDMAP Keyword - Implement z/OS Identity Propagation Mapping](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/issuing-commands-to-communicate-administrative-requirements/keywords/idmap-keyword-implement-z-os-identity-propagation-mapping.html).
-Click here for Top Secret configuration details.
```markup TSS ADD(userid) IDMAP(ZWEDNMAP) IDMAPDN('distributed-identity-user-name') -@@ -125,12 +150,15 @@ User specified parameters are presented in the section [Parameters in the ESM co TSS REFRESH ``` - For more details about mapping a distributed identity username and a distributed registry name to a Top Secret ACID, see [IDMAP Keyword - Implement z/OS Identity Propagation Mapping](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/issuing-commands-to-communicate-administrative-requirements/keywords/idmap-keyword-implement-z-os-identity-propagation-mapping.html). +For more details about mapping a distributed identity username and a distributed registry name to a Top Secret ACID, see [IDMAP Keyword - Implement z/OS Identity Propagation Mapping](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-top-secret-for-z-os/16-0/administrating/issuing-commands-to-communicate-administrative-requirements/keywords/idmap-keyword-implement-z-os-identity-propagation-mapping.html).
-
-## Zowe IntelliJ plug-in FAQ
+## Zowe Explorer plug-in for IntelliJ IDEA FAQ
-### Why might I use Zowe IntelliJ plug-in versus a traditional ISPF interface to perform mainframe tasks?
+### Why would I use the plug-in versus a traditional ISPF interface to perform mainframe tasks?
Click here for command details for ACF2.
+ +**For ACF2** + +
+
com.your.package.ApiDiscoveryListener
@@ -683,13 +761,13 @@ The following steps outline the process of registering your service with API ML.
3. Load the service configuration.
- Load your service configuration from a file `service-configuration.yml` file.
- The configuration parameters are described in the preceding section, [Configuring your service](#configuring-your-service).
+ Load your service configuration from a file `service-configuration.yml` file.
+ The configuration parameters are described in the preceding section, [Configuring your service](#configuring-your-service).
+
+ Use the following code as an example of how to load the service configuration.
- Use the following code as an example of how to load the service configuration.
+ **Example:**
- **Example:**
-
```java
@Override
public void contextInitialized(ServletContextEvent sce) {
@@ -698,14 +776,14 @@ The following steps outline the process of registering your service with API ML.
ApiMediationServiceConfig config = new ApiMediationServiceConfigReader().loadConfiguration(configurationFile);
...
```
-
- **Note:** The `ApiMediationServiceConfigReader` class also provides other methods for loading the configuration from two files, `java.util.Map` instances, or directly from a string. Check the `ApiMediationServiceConfigReader` class JavaDoc for details.
+
+ **Note:** The `ApiMediationServiceConfigReader` class also provides other methods for loading the configuration from two files, `java.util.Map` instances, or directly from a string. Check the `ApiMediationServiceConfigReader` class JavaDoc for details.
4. Register with Eureka Discovery Service.
- Use the following call to register your service instance with Eureka Discovery Service:
+ Use the following call to register your service instance with Eureka Discovery Service:
- **Example:**
+ **Example:**
```java
try {
@@ -718,9 +796,9 @@ The following steps outline the process of registering your service with API ML.
5. Unregister your service.
- Use the `contextDestroyed` method to unregister your service instance from Eureka Discovery Service in the following format:
-
- **Example:**
+ Use the `contextDestroyed` method to unregister your service instance from Eureka Discovery Service in the following format:
+
+ **Example:**
```java
@Override
@@ -732,7 +810,7 @@ The following steps outline the process of registering your service with API ML.
apiMediationClient = null;
}
```
-
+
The following code block is a full example of a context listener class implementation.
**Example:**
@@ -818,11 +896,11 @@ public class ApiDiscoveryListener implements ServletContextListener {
Once you are able to build and start your service successfully, you can use the option of validating that your service is registered correctly with the API ML Discovery Service.
**Follow these steps:**
- 1. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml).
-
- 2. Check that you can access your API service endpoints through the Gateway.
+1. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml).
- 3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
+2. Check that you can access your API service endpoints through the Gateway.
+
+3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway.
Specific addresses and user credentials for the individual API ML components depend on your target runtime environment.
@@ -840,18 +918,18 @@ Wait for the Discovery Service to discover your service. This process may take a
#### Log messages during registration problems
-When an Enabler connects to the Discovery service and fails, an error message prints to the Enabler log. The default setting does not suppress these messages as they are useful to resolve problems during the Enabler registration. Possible reasons for failure include the location of Discovery service is not correct, the Discovery Service is down, or the TLS certificate is invalid.
+When an Enabler connects to the Discovery service and fails, an error message prints to the Enabler log. The default setting does not suppress these messages as they are useful to resolve problems during the Enabler registration. Possible reasons for failure include the location of Discovery service is not correct, the Discovery Service is down, or the TLS certificate is invalid.
-These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery Service.
+These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery Service.
To fully suppress these messages in your logging framework, set the log levels to `OFF` on the following loggers:
com.netflix.discovery.DiscoveryClient, com.netflix.discovery.shared.transport.decorator.RedirectingEurekaHttpClient
Some logging frameworks provide other tools to suppress repeated messages. Consult the documentation of the logging framework you use to find out what tools are available. The following example demonstrates how the Logback framework can be used to suppress repeated messages.
-**Example:**
+**Example:**
-Add the following code to your configuration file if you use XML configuration:
+Add the following code to your configuration file if you use XML configuration:
```
0
@@ -859,5 +937,5 @@ Add the following code to your configuration file if you use XML configuration:
```
:::note
-For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.
+For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.
:::
diff --git a/docs/extend/extend-apiml/onboard-static-definition.md b/docs/extend/extend-apiml/onboard-static-definition.md
index 55e7f98c29..7f2fb4e780 100644
--- a/docs/extend/extend-apiml/onboard-static-definition.md
+++ b/docs/extend/extend-apiml/onboard-static-definition.md
@@ -1,9 +1,9 @@
-# Onboarding a REST API without code changes required
+# Onboarding a REST or GraphQL API without code changes required
-As a user of Zowe™, onboard an existing REST API service to the Zowe™ API Mediation Layer without changing the code of the API service. This form of onboarding is also refered to as, "static onboarding".
+As a user of Zowe™, onboard an existing REST or GraphQL API service to the Zowe™ API Mediation Layer without changing the code of the API service. This form of onboarding is also refered to as, "static onboarding".
:::note
-When developing a new service, it is not recommended to onboard a REST service using this method, as this method is non-native to the API Mediation Layer. For a complete list of methods to onboard a REST service natively to the API Mediation Layer, see the [Onboarding Overview](onboard-overview.md#service-onboarding-guides).
+When developing a new service, it is not recommended to onboard a service using this method, as this method is non-native to the API Mediation Layer. For a complete list of methods to onboard a service natively to the API Mediation Layer, see the [Onboarding Overview](onboard-overview.md#service-onboarding-guides).
:::
The following procedure outlines the steps to onboard an API service through the API Gateway in the API Mediation Layer without requiring code changes.
@@ -31,31 +31,31 @@ The first step in API service onboarding is to identify the APIs that you want t
* Hostname
* Port
* (Optional) base path where the service is available.
- This URL is called the base URL of the service.
+ This URL is called the base URL of the service.
- **Example:**
+ **Example:**
- In the sample service described in the [Onboarding Overview](onboard-overview.md#sample-rest-api-service), the URL of the service is: `http://localhost:8080`.
+ In the sample service described in the [Onboarding Overview](onboard-overview.md#sample-rest-api-service), the URL of the service is: `http://localhost:8080`.
2. Identify the API of the service that you want to expose through the API Gateway.
- **Example:**
+ **Example:**
- The API provided by the sample service is a second version of the Pet Store API. All the endpoints to be onboarded are available
- through `http://localhost:8080/v2/` URL. This REST API is therefore available at the path `/v2` relative to base URL of the service.
- There is no version 1 in this case.
+ The API provided by the sample service is a second version of the Pet Store API. All the endpoints to be onboarded are available
+ through `http://localhost:8080/v2/` URL. This API is therefore available at the path `/v2` relative to base URL of the service.
+ There is no version 1 in this case.
3. Choose the `service ID` of your service. The `service ID` identifies the service uniquely in the API Gateway. The `service ID` is an alphanumeric string in lowercase ASCII.
- **Example:**
+ **Example:**
- In the sample service, the `service ID` is `petstore`.
+ In the sample service, the `service ID` is `petstore`.
4. Decide which URL to use to make this API available in the API Gateway. This URL is referred to as the gateway URL and is composed of the API type and the major version. The usually used types are: `api`, `ui` and `ws` but you can use any valid URL element you want.
- **Example:**
+ **Example:**
- In the sample service, we provide a REST API. The first segment is `/api` as the service provides only one REST API. To indicate that this is version 2, the second segment is `/v2`. This version is required by the Gateway. If your service does not have a version, use `v1` on the Gateway.
+ In the sample service, we provide a REST API. The first segment is `/api` as the service provides only one REST API. To indicate that this is version 2, the second segment is `/v2`. This version is required by the Gateway. If your service does not have a version, use `v1` on the Gateway.
## Define your service and API in YAML format
@@ -107,7 +107,7 @@ In this example, a suitable name for the file is `petstore.yml`.
* There are more examples of API definitions at this [link](https://github.com/zowe/api-layer/tree/master/config/local/api-defs).
* For more details about how to use YAML format, see this [link](https://learnxinyminutes.com/docs/yaml/).
-:::
+ :::
## Route your API
@@ -145,7 +145,7 @@ To access resource `pets` of the `petstore` version 2 API, gateway URL will be:
```
https://gateway:port/petstore/api/v2/pets
```
-It will be routed to:
+It will be routed to:
```
https://localhost:8080/v2/pets
```
@@ -158,6 +158,7 @@ This method enables you to access the service through a stable URL, and move the
This part contains a more complex example of the configuration and an explanation of all the possible parameters:
+**REST API**
```yaml
services:
- serviceId: petstore
@@ -192,6 +193,45 @@ catalogUiTiles:
title: Static API services
description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions
+additionalServiceMetadata:
+ - serviceId: petstore
+ mode: UPDATE # How to update UPDATE=only missing, FORCE_UPDATE=update all set values
+ authentication:
+ scheme: bypass
+```
+**GraphQL API**
+
+```yaml
+services:
+ - serviceId: petstore
+ catalogUiTileId: static
+ title: Petstore Sample Service
+ description: This is a sample server Petstore service
+ instanceBaseUrls:
+ - http://localhost:8080
+ homePageRelativeUrl: /home # Normally used for informational purposes for other services to use it as a landing page
+ statusPageRelativeUrl: /application/info # Appended to the instanceBaseUrl
+ healthCheckRelativeUrl: /application/health # Appended to the instanceBaseUrl
+ routes:
+ - gatewayUrl: api/v2
+ serviceRelativeUrl: /v2
+ authentication:
+ scheme: httpBasicPassTicket
+ applid: ZOWEAPPL
+ apiInfo:
+ - apiId: io.swagger.petstore
+ gatewayUrl: api/v2
+ graphqlUrl: http://localhost:8080/v2/graphql
+ customMetadata:
+ yourqualifier:
+ key1: value1
+ key2: value2
+
+catalogUiTiles:
+ static:
+ title: Static API services
+ description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions
+
additionalServiceMetadata:
- serviceId: petstore
mode: UPDATE # How to update UPDATE=only missing, FORCE_UPDATE=update all set values
@@ -201,14 +241,14 @@ additionalServiceMetadata:
* **serviceId**
- This parameter specifies the service instance identifier that is registered in the API Mediation Layer installation.
- The service ID is used in the URL for routing to the API service through the Gateway.
- The service ID uniquely identifies the service in the API Mediation Layer.
- The system administrator at the customer site defines this parameter.
+ This parameter specifies the service instance identifier that is registered in the API Mediation Layer installation.
+ The service ID is used in the URL for routing to the API service through the Gateway.
+ The service ID uniquely identifies the service in the API Mediation Layer.
+ The system administrator at the customer site defines this parameter.
- :::caution
- Ensure that the service ID is set properly with the following considerations:
- :::
+ :::caution
+ Ensure that the service ID is set properly with the following considerations:
+ :::
* When two API services use the same service ID, the API Gateway considers the services to be clones (i.e. two instances for the same service). An incoming API request can be routed to either of them.
* The same service ID should be set only for multiple API service instances for API scalability.
@@ -216,138 +256,138 @@ additionalServiceMetadata:
* The service ID cannot contain more than 40 characters.
* The service ID is linked to security resources. Changes to the service ID require an update of security resources.
- **Examples:**
+ **Examples:**
* If the customer system administrator sets the service ID to `monitoringpr1`,
- the API URL in the API Gateway appears as the following URL:
+ the API URL in the API Gateway appears as the following URL:
- `https://gateway:port/monitoringpr1/api/v1/...`
+ `https://gateway:port/monitoringpr1/api/v1/...`
* If customer system administrator sets the service ID to `authenticationprod1`,
- the API URL in the API Gateway appears as the following URL:
+ the API URL in the API Gateway appears as the following URL:
+
+ `http://gateway:port/authenticationprod1/api/v1/...`
- `http://gateway:port/authenticationprod1/api/v1/...`
+* **title**
- * **title**
+ This parameter specifies the human readable name of the API service instance (for example, `Monitoring Prod` or `systemInfo LPAR1`). This value is displayed in the API catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator.
- This parameter specifies the human readable name of the API service instance (for example, `Monitoring Prod` or `systemInfo LPAR1`). This value is displayed in the API catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator.
+ **Tip:** We recommend that you provide a specific default value of the `title`.
+ Use a title that describes the service instance so that the end user knows the specific purpose of the service instance.
- **Tip:** We recommend that you provide a specific default value of the `title`.
- Use a title that describes the service instance so that the end user knows the specific purpose of the service instance.
+* **description**
- * **description**
+ This parameter specifies a short description of the API service.
- This parameter specifies a short description of the API service.
+ **Examples:**
- **Examples:**
-
- - `Monitoring Service - Production Instance`
- - `System Info Service running on LPAR1`
+ - `Monitoring Service - Production Instance`
+ - `System Info Service running on LPAR1`
- This value is displayed in the API Catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator.
+ This value is displayed in the API Catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator.
- :::tip
- Describe the service so that the end user knows the function of the service.
- :::
+ :::tip
+ Describe the service so that the end user knows the function of the service.
+ :::
* **instanceBaseUrls**
- This parameter specifies a list of base URLs to your service's REST resource. It will be the prefix for the following URLs:
+ This parameter specifies a list of base URLs to your service's resource. It will be the prefix for the following URLs:
* **homePageRelativeUrl**
* **statusPageRelativeUrl**
* **healthCheckRelativeUrl**
- **Examples:**
+ **Examples:**
* `- http://host:port/ftpservice` for an HTTP service
* `- https://host:port/source-code-mngmnt` for an HTTPS service
- You can provide one URL if your service has one instance. If your service provides multiple instances for the high-availability then you can provide URLs to these instances.
+ You can provide one URL if your service has one instance. If your service provides multiple instances for the high-availability then you can provide URLs to these instances.
- **Examples:**
+ **Examples:**
* `- https://host1:port1/source-code-mngmnt`
* `- https://host2:port2/source-code-mngmnt`
-
+
* **homePageRelativeUrl**
- This parameter specifies the relative path to the homepage of your service. The path should start with `/`.
- If your service has no homepage, omit this parameter. The path is relative to the instanceBaseUrls.
+ This parameter specifies the relative path to the homepage of your service. The path should start with `/`.
+ If your service has no homepage, omit this parameter. The path is relative to the instanceBaseUrls.
- **Examples:**
+ **Examples:**
* `homePageRelativeUrl: /` The service has homepage with URL `${baseUrl}/`
* `homePageRelativeUrl: /ui/` The service has homepage with URL `${baseUrl}/ui/`
* `homePageRelativeUrl: ` The service has homepage with URL `${baseUrl}`
* **statusPageRelativeUrl**
- This parameter specifies the relative path to the status page of your service.
- Start this path with `/`. If you service doesn't have a status page, omit this parameter.
- The path is relative to the instanceBaseUrls.
+ This parameter specifies the relative path to the status page of your service.
+ Start this path with `/`. If you service doesn't have a status page, omit this parameter.
+ The path is relative to the instanceBaseUrls.
+
+ **Example:**
+
+ `statusPageRelativeUrl: /application/info`
- **Example:**
+ the result URL will be:
- `statusPageRelativeUrl: /application/info`
-
- the result URL will be:
-
- `${baseUrl}/application/info`
+ `${baseUrl}/application/info`
* **healthCheckRelativeUrl**
- This parameter specifies the relative path to the health check endpoint of your service.
- Start this URL with `/`. If your service does not have a health check endpoint, omit this parameter.
- The path is relative to the instanceBaseUrls.
+ This parameter specifies the relative path to the health check endpoint of your service.
+ Start this URL with `/`. If your service does not have a health check endpoint, omit this parameter.
+ The path is relative to the instanceBaseUrls.
- **Example:**
+ **Example:**
- `healthCheckRelativeUrl: /application/health`
-
- This results in the URL:
+ `healthCheckRelativeUrl: /application/health`
- `${baseUrl}/application/health`
+ This results in the URL:
+
+ `${baseUrl}/application/health`
* **routes**
- The following parameters specify the routing rules between the Gateway service and your service. Both specify how the API endpoints are mapped to the API Gateway endpoints.
+ The following parameters specify the routing rules between the Gateway service and your service. Both specify how the API endpoints are mapped to the API Gateway endpoints.
* **routes.gatewayUrl**
- The _gatewayUrl_ parameter sets the target endpoint on the Gateway. This is the portion of the final URL that is Gateway specific.
-
- **Example:**
-
- For the petstore example, the full Gateway URL would be:
+ The _gatewayUrl_ parameter sets the target endpoint on the Gateway. This is the portion of the final URL that is Gateway specific.
+
+ **Example:**
+
+ For the petstore example, the full Gateway URL would be:
- `https://gatewayUrl:1345/petstore/api/v2/pets/1`
-
- In this case, the URL that will be called on the service is:
+ `https://gatewayUrl:1345/petstore/api/v2/pets/1`
- `http://localhost:8080/v2/pets/1`
+ In this case, the URL that will be called on the service is:
+
+ `http://localhost:8080/v2/pets/1`
* **routes.serviceRelativeUrl**
- The _serviceRelativeUrl_ parameter points to the target endpoint on the service. This is the base path on the service called through the Gateway.
-
+ The _serviceRelativeUrl_ parameter points to the target endpoint on the service. This is the base path on the service called through the Gateway.
+
* **authentication**
- The information about the possible ways to integrate authentication are available in [Single Sign On Integration for Extenders](./api-medation-sso-integration-extenders.md) article.
+ The information about the possible ways to integrate authentication are available in [Single Sign On Integration for Extenders](./api-medation-sso-integration-extenders.md) article.
* **apiInfo**
- This section defines APIs that are provided by the service. Currently, only one API is supported.
+ This section defines APIs that are provided by the service. Currently, only one API is supported.
* **apiInfo.apiId**
- This parameter specifies the API identifier that is registered in the API Mediation Layer installation. The API ID uniquely identifies the API in the API Mediation Layer.
- The same API can be provided by multiple services. The API ID can be used to locate the same APIs that are provided by different services.
-
- The creator of the API defines this ID.
- The API ID needs to be a string of up to 64 characters
- that uses lowercase alphanumeric characters and a dot: `.`.
-
- **Tip:** We recommend that you use your organization as the prefix.
+ This parameter specifies the API identifier that is registered in the API Mediation Layer installation. The API ID uniquely identifies the API in the API Mediation Layer.
+ The same API can be provided by multiple services. The API ID can be used to locate the same APIs that are provided by different services.
- **Examples:**
+ The creator of the API defines this ID.
+ The API ID needs to be a string of up to 64 characters
+ that uses lowercase alphanumeric characters and a dot: `.`.
+
+ **Tip:** We recommend that you use your organization as the prefix.
+
+ **Examples:**
- `zowe.file`
- `ca.sysview`
@@ -355,55 +395,61 @@ additionalServiceMetadata:
* **apiInfo.gatewayUrl**
- This parameter specifies the base path at the API Gateway where the API is available. Ensure that this path is the same as the _gatewayUrl_ value in the _routes_ sections.
+ This parameter specifies the base path at the API Gateway where the API is available. Ensure that this path is the same as the _gatewayUrl_ value in the _routes_ sections.
* **apiInfo.swaggerUrl**
- (Optional) This parameter specifies the HTTP or HTTPS address where the Swagger JSON document is available.
+ (Optional) This parameter specifies the HTTP or HTTPS address where the Swagger JSON document is available.
+
+ * **apiInfo.graphqlUrl**
+
+ (Optional) This parameter specifies the HTTP or HTTPS address where GraphQL server is available.
+
+ _Specific for REST API_
* **apiInfo.documentationUrl**
- (Optional) This parameter specifies a URL to a website where external documentation is provided.
- This can be used when _swaggerUrl_ is not provided.
+ (Optional) This parameter specifies a URL to a website where external documentation is provided.
+ This can be used when neither _swaggerUrl_ not _graphqlUrl_ are provided.
* **apiInfo.version**
- (Optional) This parameter specifies the actual version of the API in [semantic versioning](https://semver.org/) format. This can be used when _swaggerUrl_ is not provided.
+ (Optional) This parameter specifies the actual version of the API in [semantic versioning](https://semver.org/) format. This can be used when _swaggerUrl_ is not provided.
* **apiInfo.defaultApi**
-
- (Optional) This parameter specifics that the API is the default one to show in the API Catalog. If this not set to true for any API, or multiple APIs have it set to true,
- then the default API becomes the API with the highest major version as seen in `apiInfo.version`.
-
+
+ (Optional) This parameter specifics that the API is the default one to show in the API Catalog. If this not set to true for any API, or multiple APIs have it set to true,
+ then the default API becomes the API with the highest major version as seen in `apiInfo.version`.
+
* **apiInfo.codeSnippet** (Optional)
- specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing
- the request using the *Try it out* functionality.
- When specifying this configuration, you need to provide the following parameters:
+ specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing
+ the request using the *Try it out* functionality. This can be used when swaggerUrl is not provided.
+ When specifying this configuration, you need to provide the following parameters:
* **`endpoint`**
- The endpoint that represents the API operation of the customized snippet
+ The endpoint that represents the API operation of the customized snippet
* **`language`**
- The language of the snippet
+ The language of the snippet
* **`codeBlock`**
- The content of the snippet to be displayed in the API Catalog
+ The content of the snippet to be displayed in the API Catalog
* **customMetadata**
- Custom metadata are described [here](custom-metadata.md).
-
+ Custom metadata are described [here](custom-metadata.md).
+
* **catalogUiTileId**
- This parameter specifies the unique identifier for the API services group.
- This is the grouping value used by the API Mediation Layer to group multiple API services
- together into "tiles".
- Each unique identifier represents a single API Catalog UI dashboard tile.
- Specify the value based on the ID of the defined tile.
+ This parameter specifies the unique identifier for the API services group.
+ This is the grouping value used by the API Mediation Layer to group multiple API services
+ together into "tiles".
+ Each unique identifier represents a single API Catalog UI dashboard tile.
+ Specify the value based on the ID of the defined tile.
* **catalogUiTile**
- This section contains definitions of tiles. Each tile is defined in a section that has its tile ID as a key.
- A tile can be used by multiple services.
+ This section contains definitions of tiles. Each tile is defined in a section that has its tile ID as a key.
+ A tile can be used by multiple services.
```yaml
catalogUiTiles:
@@ -416,42 +462,42 @@ additionalServiceMetadata:
```
* **catalogUiTile.\{tileId\}.title**
-
- This parameter specifies the title of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile title.
-
+
+ This parameter specifies the title of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile title.
+
* **catalogUiTile.\{tileId\}.description**
-
- This parameter specifies the detailed description of the API Catalog UI dashboard tile. This value is displayed in the API Catalog UI dashboard as the tile description.
+
+ This parameter specifies the detailed description of the API Catalog UI dashboard tile. This value is displayed in the API Catalog UI dashboard as the tile description.
* **additionalServiceMetadata**
- This section contains a list of changes that allows adding or modifying metadata parameters for the corresponding service.
-
+ This section contains a list of changes that allows adding or modifying metadata parameters for the corresponding service.
+
* **additionalServiceMetadata.serviceId**
-
- This parameter specifies the service identifier for which metadata is updated.
-
+
+ This parameter specifies the service identifier for which metadata is updated.
+
* **additionalServiceMetadata.mode**
-
- This parameter specifies how the metadata are updated. The following modes are available:
-
- **UPDATE**
-
- Only missing parameters are added. Already existing parameters are ignored.
-
- **FORCE_UPDATE**
-
- All changes are applied. Existing parameters are overwritten.
-
+
+ This parameter specifies how the metadata are updated. The following modes are available:
+
+ **UPDATE**
+
+ Only missing parameters are added. Already existing parameters are ignored.
+
+ **FORCE_UPDATE**
+
+ All changes are applied. Existing parameters are overwritten.
+
* **additionalServiceMetadata.\{updatedParameter\}**
-
- This parameter specifies any metadata parameters that are updated.
+
+ This parameter specifies any metadata parameters that are updated.
## Add and validate the definition in the API Mediation Layer running on your machine
After you define the service in YAML format, you are ready to add your service definition to the API Mediation Layer ecosystem.
-The following procedure describes how to add your service to the API Mediation Layer on your local machine.
+The following procedure describes how to add your service to the API Mediation Layer on your local machine.
**Follow these steps:**
@@ -474,7 +520,7 @@ The following procedure describes how to add your service to the API Mediation L
## Add a definition in the API Mediation Layer in the Zowe runtime
-After you define and validate the service in YAML format, you are ready to add your service definition to the API Mediation Layer running as part of the Zowe runtime installation on z/OS.
+After you define and validate the service in YAML format, you are ready to add your service definition to the API Mediation Layer running as part of the Zowe runtime installation on z/OS.
**Follow these steps:**
@@ -487,17 +533,17 @@ The `${zoweInstanceDir}` symbol is used in following instructions.
2. Add the fully qualified zFS path of your YAML file to `ZWE_STATIC_DEFINITIONS_DIR` in `zowe.yaml`.
- To hold your YAML file outside of the instance directory, add `ZWE_STATIC_DEFINITIONS_DIR` variable to the `zowe.environments` section of `zowe.yaml`. Append the fully qualified zFS path of the YAML file to the `ZWE_STATIC_DEFINITIONS_DIR` variable. You may specify multiple zFS paths, separating each path by a semicolon.
-
- - To place your YAML file within the instance directory, copy your YAML file to the `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory.
- :::note Notes:
+ - To place your YAML file within the instance directory, copy your YAML file to the `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory.
+
+ :::note Notes:
- The `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory is created the first time that Zowe starts. If you have not yet started Zowe, this directory might be missing.
- The user ID `ZWESVUSR` that runs the Zowe started task must have permission to read the YAML file.
- :::
+ :::
3. Ensure that your application that provides the endpoints described in the YAML file is running.
-4. Restart Zowe runtime or follow steps in section [(Optional) Reload the services definition after the update when the API Mediation Layer is already started](#optional-reload-the-services-definition-after-the-update-when-the-api-mediation-layer-is-already-started) which allows you to add your static API service to an already running Zowe.
+4. Restart Zowe runtime or follow steps in section [(Optional) Reload the services definition after the update when the API Mediation Layer is already started](#optional-reload-the-services-definition-after-the-update-when-the-api-mediation-layer-is-already-started) which allows you to add your static API service to an already running Zowe.
5. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml)
@@ -516,9 +562,9 @@ Static API definition file: /Users/user/workspace/api-layer/config/local/api-def
Adding static instance STATIC-localhost:petstore:8080 for service ID petstore mapped to URL http://localhost:8080
```
- :::note
- If these messages are not displayed in the log, ensure that the [API ML debug mode](https://docs.zowe.org/stable/troubleshoot/troubleshoot-apiml#enable-api-ml-debug-mode) is active.
- :::
+:::note
+If these messages are not displayed in the log, ensure that the [API ML debug mode](https://docs.zowe.org/stable/troubleshoot/troubleshoot-apiml#enable-api-ml-debug-mode) is active.
+:::
## (Optional) Reload the services definition after the update when the API Mediation Layer is already started
@@ -528,24 +574,24 @@ The following procedure enables you to refresh the API definitions after you cha
1. Use a REST API client to issue a `POST` request to the Discovery Service (port 10011):
- `http://localhost:10011/discovery/api/v1/staticApi`
+ `http://localhost:10011/discovery/api/v1/staticApi`
- The Discovery Service requires authentication by a client certificate. If the API Mediation Layer is running on your local machine, the certificate is stored at `keystore/localhost/localhost.pem`.
+ The Discovery Service requires authentication by a client certificate. If the API Mediation Layer is running on your local machine, the certificate is stored at `keystore/localhost/localhost.pem`.
- This example uses the [HTTPie command-line HTTP client](https://httpie.org) and is run with Python 3 installed:
+ This example uses the [HTTPie command-line HTTP client](https://httpie.org) and is run with Python 3 installed:
```
httpie --cert=keystore/localhost/localhost.pem --verify=keystore/local_ca/localca.cer -j POST https://localhost:10011/discovery/api/v1/staticApi
```
-
- Alternatively, it is possible to use curl to issue the POST call if it is installed on your system:
-
+
+ Alternatively, it is possible to use curl to issue the POST call if it is installed on your system:
+
```
curl -X POST --cert keystore/localhost/localhost.pem --cacert keystore/localhost/localhost.keystore.cer https://localhost:10011/discovery/api/v1/staticApi
```
2. Check if your updated definition is effective.
- :::note
- It can take up to 30 seconds for the API Gateway to pick up the new routing.
- :::
+ :::note
+ It can take up to 30 seconds for the API Gateway to pick up the new routing.
+ :::
\ No newline at end of file
diff --git a/docs/extend/extend-apiml/websocket.md b/docs/extend/extend-apiml/websocket.md
deleted file mode 100644
index 7139fcd47b..0000000000
--- a/docs/extend/extend-apiml/websocket.md
+++ /dev/null
@@ -1,27 +0,0 @@
-
-# Using WebSocket support in API Gateway
-
-The API Gateway includes a basic WebSocket proxy which enables the Gateway to access applications that use the WebSocket protocol together with a web UI and a REST API.
-
-The service defines which WebSocket endpoints are exposed by using Eureka metadata.
-
-**Example:**
-```
-eureka:
- instance:
- metadata-map:
- apiml:
- routes:
- ws_v1:
- gatewayUrl: "ws/v1"
- serviceUrl: /${serviceId}/ws
-```
-
-These metadata make it possible for requests from `wss://gatewayHost:gatewayPort/${serviceId}/ws/v1/path` to map to `wss://serviceHost:servicePort/${serviceId}/ws/v1/path`.
-
-* **`serviceId`**
- Specifies the service ID of the service.
-
-* **`path`**
- Specifies the remaining path segment in the URL.
-
diff --git a/docs/extend/extend-apiml/zaas-client.md b/docs/extend/extend-apiml/zaas-client.md
index 29c3f3c216..2b5448e670 100644
--- a/docs/extend/extend-apiml/zaas-client.md
+++ b/docs/extend/extend-apiml/zaas-client.md
@@ -33,6 +33,7 @@ public interface ZaasClient {
String login(String authorizationHeader) throws ZaasClientException;
ZaasToken query(String token) throws ZaasClientException;
ZaasToken query(HttpServletRequest request) throws ZaasClientException;
+ ZaasOidcValidationResult validateOidc(String token) throws ZaasClientException;
String passTicket(String jwtToken, String applicationId) throws ZaasClientException, ZaasConfigurationException;
void logout(String token) throws ZaasClientException, ZaasConfigurationException;
}
@@ -88,6 +89,21 @@ cookie or in an Authorization header. You then receive the `ZaasToken` Object in
ZaasToken query(HttpServletRequest request) throws ZaasClientException;
```
+### Validate the OIDC token (`validateOidc`)
+
+Use the `validateOidc` method to get the validity information about the OIDC token.
+
+Call the `validateOidc` method from your API in the following format:
+
+```java
+ZaasOidcValidationResult validateOidc(String token) throws ZaasClientException;
+```
+
+In return, you receive the `ZaasOidcValidationResult` Object in JSON format.
+
+This method automatically uses the truststore file to add a security layer, which you configured in the `ConfigProperties` class.
+
+
### Invalidate a JWT token (`logout`)
The `logout` method is used to invalidate the JWT token. The token must be provided in the Cookie header and must follow the format accepted by the API ML.
@@ -124,65 +140,75 @@ To use this library, use the procedure described in this section.
1. Add `zaas-client` as a dependency in your project.
You will need to specify the version of the `zaas-client` you want. `zaas-client` versioning following the semantic versioning format of `major.minor.patch`. For example, `1.22.0`.
+
2. API ML token
3. PEM certificate | +Db2,
FTP,
most other services | username, password +SSH | 1. SSH key
2. username, password + ZOSMF
direct connection | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md index 548a47f470..b93e3be1a8 100644 --- a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md +++ b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md @@ -1,40 +1,42 @@ # Creating plug-in lifecycle actions -As a developer, you may want your plug-in to perform certain tasks immediately after install and just before uninstall. +As a developer, you might want your plug-in to perform certain tasks immediately after install and just before uninstall. Many different types of tasks can make up these *plug-in lifecycle actions*, including the following examples: - Post-install actions: - - A sanity check + - An initial check - Additional setup - - Adding the plug-in as an override of Zowe CLI Credential Manager + - Adding the plug-in as an override of Zowe CLI's built-in credential manager - Pre-uninstall actions: - Revert specialized setup - - Removing the plug-in as an override of Zowe CLI Credential Manager + - Removing the plug-in as an override of Zowe CLI's built-in credential manager Creating and using lifecycle actions is optional, but they can be useful tools. Lifecycle actions can automate a manual process intended for the plug-in user to carry out. They can also avoid the need to create commands with uses limited to post-install and pre-uninstall tasks. -**Note:** When creating a plug-in to override Zowe CLI Credential Manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +:::note +When creating a plug-in to override Zowe CLI's built-in credential manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +::: -## Implenting lifeycyle actions +## Implementing lifecyle actions -Add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions. - -Follow these steps: +To add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions: 1. Navigate to the plug-in definition file. - This file is the value for the `configurationModule` property in the plug-in `package.json` file. - - See this [`IImperativeConfig.ts` file](https://github.com/zowe/imperative/blob/master/packages/imperative/src/doc/IImperativeConfig.ts) to view an example of the detailed format used in the plug-in definition file. + The path to this file is the value for the `configurationModule` property in the plug-in `package.json` file. 2. In the plug-in definition file, use the `pluginLifeCycle` property to add the path to the javascript file the plug-in uses to implement the class containing lifecycle functions. - This plug-in lifecycle functions class extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/imperative/blob/master/packages/imperative/src/plugins/AbstractPluginLifeCycle.ts). + The `pluginLifeCycle` property is defined in [this file](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/doc/IImperativeConfig.ts). + + The class defined by this property extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/plugins/AbstractPluginLifeCycle.ts). 3. In the plug-in lifecycle functions class you created, add instructions for both the `postInstall` and `preUninstall` functions. If implemented correctly, Zowe CLI calls the `postInstall` function of the plug-in immediately after the plug-in has been installed. Similarly, the `preUninstall` function is called immediately before the Zowe CLI uninstalls the plug-in. -**Note:** If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +:::note +If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +::: diff --git a/docs/extend/extend-cli/cli-devTutorials.md b/docs/extend/extend-cli/cli-devTutorials.md index f253652c41..bc41efbd1c 100644 --- a/docs/extend/extend-cli/cli-devTutorials.md +++ b/docs/extend/extend-cli/cli-devTutorials.md @@ -1,74 +1,50 @@ # Developing for Zowe CLI -You can extend Zowe™ CLI by developing plug-ins and contributing code to the base Zowe CLI or existing plug-ins. +Extend Zowe™ CLI by developing plug-ins and contributing code to Zowe CLI core or existing plug-ins. ## How to contribute -You can contribute to Zowe CLI in the following ways: -- Add new commands, options, or other improvements to the base CLI. + +Contribute to Zowe CLI in the following ways: +- Add new commands, options, or other improvements to the core CLI. - Develop a Zowe CLI plug-in. You might want to contribute to Zowe CLI to accomplish the following objectives: - Provide new scriptable functionality for yourself, your organization, or to a broader community. -- Make use of Zowe CLI infrastructure (profiles and programmatic APIs). +- Make use of Zowe CLI infrastructure (such as profiles and programmatic APIs). - Participate in the Zowe CLI community space. ## Getting started -If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). The [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in) is a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects. + +If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). To review a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects, see the [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in). ### Contribution guidelines + The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins. -The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly: +The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. | For more information about ... | See: | | ------------------------------ | ----- | -| General guidelines that apply to contributing to Zowe CLI and Plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | -| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| -| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | -| Guidelines for running tests on the plug-ins that you build| [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | -Versioning conventions for Zowe CLI and Plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | - - -### Tutorials -Follow these tutorials to get started working with the sample plug-in: -1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment. -2. [Installing a plug-in:](cli-installing-sample-plugin.md) Install the sample plug-in to Zowe CLI and run as-is. -3. [Extending a plug-in:](cli-extending-a-plugin.md) Extend the sample plug-in with a new by creating a programmatic API, definition, and handler. -4. [Creating a new plug-in:](cli-developing-a-plugin.md) Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets. -5. [Implementing user profiles:](cli-implement-profiles.md) Implement user profiles with the plug-in. +| General guidelines that apply to contributing to Zowe CLI and plug-ins | [Contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | +| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and plug-in guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| +| Guidelines for running tests on Zowe CLI | [Testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | +| Guidelines for running tests on the plug-ins that you build| [Plug-in testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | +Versioning conventions for Zowe CLI and plug-ins| [Versioning guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | ### Plug-in development overview -At a high level, a plug-in must have `imperative-framework` configuration [(sample here)](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. -A Zowe CLI plug-in will minimally contain the following: +At a high level, a plug-in must have `imperative-framework` configuration (see a [sample here](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts)). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. + +A Zowe CLI plug-in minimally contains the following: 1. Programmatic API: Node.js programmatic APIs to be called by your handler or other Node.js applications. 2. Command definition: The syntax definition for your command. 3. Handler implementation: To invoke your programmatic API to display information in the format that you defined in the definition. -The following guidelines and documentation will assist you during development: - -### Imperative CLI Framework documentation -[Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these supplementary documents during development to learn about specific features such as: +#### Imperative CLI Framework documentation +[Imperative CLI Framework documentation](https://github.com/zowe/zowe-cli/wiki) is a key source of information to learn about the features of Imperative CLI Framework, the code framework that you use to build plug-ins for Zowe CLI. Refer to these supplementary documents during development to learn about specific features such as: - Auto-generated help - JSON responses - User profiles -- Logging, progress bars, experimental commands, and more! +- Logging, progress bars, experimental commands, and more - Authentication mechanisms - -### Authentication mechanisms - -As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe. - -Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with. - -However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in. - -To learn the authentication methods used for different services and their order of precedence, refer to the following table: - -service | Zowe V1 order of precedence | Zowe V2 order of precedence -|:--- |:--- |:--- | -API ML | 1. username, password
2. API ML token | 1. username, password
2. API ML token
3. PEM certificate | -Db2,
FTP,
most other services | username, password | username, password -SSH | 1. SSH key
2. username, password | 1. SSH key
2. username, password - ZOSMF
direct connection | username, password | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-developing-a-plugin.md b/docs/extend/extend-cli/cli-developing-a-plugin.md index 290b098d52..0e635f74e7 100644 --- a/docs/extend/extend-cli/cli-developing-a-plugin.md +++ b/docs/extend/extend-cli/cli-developing-a-plugin.md @@ -1,21 +1,22 @@ # Developing a new Zowe CLI plug-in -Before you begin this tutorial, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. + +Before you begin, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. ## Overview + The advantage of Zowe CLI and of the CLI approach in mainframe development is that it allows for combining different developer tools for new and interesting uses. This tutorial demonstrates how to create a brand new Zowe CLI plug-in that uses Node.js to create a client-side API. -After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial will also show you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). +After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial also shows you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). If you are ready to create your own unique Zowe CLI plug-in, refer to the notes at the end of each tutorial step for guidance. If you are interested in creating a credential manager plug-in, see the [Zowe CLI secrets for kubernetes plug-in](https://github.com/zowe/zowe-cli-secrets-for-kubernetes) repository. ## Setting up the new sample plug-in project - Download the sample plug-in source and delete the irrelevant content to set up your plug-in project. - - Follow these steps: + + Download the sample plug-in source and delete the irrelevant content to set up your plug-in project: 1. Open a terminal and run the command `mkdir zowe-tutorial`. @@ -49,7 +50,11 @@ If you are interested in creating a credential manager plug-in, see the [Zowe CL If vulnerabilities are found in any of the installed dependencies, refer to [npm Docs](https://docs.npmjs.com/cli/v9/commands/npm-audit) for how to fix them. ::: -**To create a unique plug-in:** Change the `files-util` directory to a name applicable for your project. +:::tip To create a unique plug-in + +Change the `files-util` directory to a name applicable for your project. + +::: ## Updating `package.json` @@ -63,7 +68,11 @@ Open the `package.json` file in a text editor and replace the name field with th This tutorial uses `@zowe/files-util` as the tutorial plug-in name. -**To create a unique plug-in:** Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). +:::tip To create a unique plug-in + +Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). + +::: ## Adjusting Imperative CLI Framework configuration @@ -86,13 +95,15 @@ export = config; When successful, the `src/pluginDef.ts` file contains the new configurations. -**To create a unique plug-in:** Change the plug-in name, display name, and description according to your project. +:::tip To create a unique plug-in -## Adding third-party packages +Change the plug-in name, display name, and description according to your project. -Install third-party packages as dependencies for the plug-in's client-side API. +::: - Follow these steps: +## Adding third-party packages + +Install third-party packages as dependencies for the plug-in's client-side API: 1. Run `npm install --save-exact diff` to install the diff package (which includes methods for comparing text). @@ -100,12 +111,15 @@ Install third-party packages as dependencies for the plug-in's client-side API. When successful, the `diff` and `@types/diff` packages are added to the dependency list in the `package.json` file. -**To create a unique plug-in:** Instead of the `diff` package, install the package(s) that are required for your API, if any. +:::tip To create a unique plug-in + +Instead of the `diff` package, install the package(s) that are required for your API, if any. + +::: ## Creating a Node.js client-side API -Create a client-side API that compares the contents of two data sets on the mainframe. -Follow these steps: +Create a client-side API that compares the contents of two data sets on the mainframe: 1. In the `src/api` directory, create a file named `DataSetDiff.ts`. @@ -170,11 +184,15 @@ Follow these steps: When successful, the `index.ts` file contains the new code. -**To create a unique plug-in:** The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. +:::tip To create a unique plug-in + +The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. + +::: ## Building your plug-in source -To confirm that your project builds successfully: +Confirm that your project builds successfully: 1. Due to missing license headers, you will come across linting errors. Run `npm run lint:fix` to resolve the errors automatically. @@ -186,7 +204,11 @@ To confirm that your project builds successfully: The `lib` directory is configurable by modifying [this value](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/tsconfig.json#L12) in the `tsconfig.json` file. -**To create a unique plug-in:** Follow these same steps. +:::tip To create a unique plug-in + +Follow these same steps. + +::: ## Creating a Zowe CLI command @@ -275,17 +297,19 @@ If you are adding multiple commands to your CLI plug-in, consider moving the cod ::: -**To create a unique plug-in:** Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. +:::tip To create a unique plug-in + +Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. + +::: ## Trying your command Before you test your new command, confirm that you are able to connect to the mainframe. -In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Using profiles](../../user-guide/cli-using-using-team-profiles/) for information. +In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Team configurations](../../user-guide/cli-using-using-team-profiles/) for information. -Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time. - -Follow these steps: +Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time: 1. Repeat the steps in [Building your plug-in source](../extend-cli/cli-developing-a-plugin#building-your-plug-in-source). @@ -329,9 +353,13 @@ Follow these steps: When successful, the output displays plain text diffs of the entered data sets. -**To create a unique plug-in:** Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. +:::tip To create a unique plug-in -## Bringing together new tools! +Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. + +::: + +## Bringing together new tools You have created a simple CLI plug-in that provides plain text diffs of two data sets. But you may not want to end there. @@ -343,8 +371,6 @@ To help fix this, you can extend **Files Util Plug-in** to create a more visual |:--:| | Diff to HTML by [rtfpessoa](https://github.com/rtfpessoa)| -Follow these steps: - 1. Run `npm install --global diff2html-cli` to install `diff2html`. :::note diff --git a/docs/extend/extend-cli/cli-extending-a-plugin.md b/docs/extend/extend-cli/cli-extending-a-plugin.md index 9aad0e9832..bf2a8a7c65 100644 --- a/docs/extend/extend-cli/cli-extending-a-plugin.md +++ b/docs/extend/extend-cli/cli-extending-a-plugin.md @@ -1,86 +1,88 @@ # Extending a plug-in + Before you begin, be sure to complete the [Installing the sample plug-in](cli-installing-sample-plugin.md) tutorial. ## Overview -This tutorial demonstrates how to extend the plug-in that is bundled with this sample by: - -1. Creating a Typescript interface for the Typicode response data -2. Creating a programmatic API -3. Creating a command definition -4. Creating a command handler - -We'll do this by using `@zowe/imperative` infrastructure to surface REST API data on our Zowe™ CLI plug-in. +This tutorial uses the Typicode REST API as a guide for how to build a Zowe CLI plug-in that interacts with REST APIs on the mainframe. -Specifically, we're going to show data from [this URI](https://jsonplaceholder.typicode.com/todos) by [Typicode](https://jsonplaceholder.typicode.com/). -Typicode serves sample REST JSON data for testing purposes. +At the end of this tutorial, you are able to use the following new command from the Zowe CLI interface: -At the end of this tutorial, you will be able to use a new command from the Zowe CLI interface: `zowe zowe-cli-sample list typicode-todos` +``` +zowe zowe-cli-sample list typicode-todos +``` -Completed source for this tutorial can be found on the `typicode-todos` branch of the zowe-cli-sample-plugin repository. +The completed source for this tutorial can be found on the `typicode-todos` branch of the [`zowe-cli-sample-plugin`](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) repository. ### Creating a Typescript interface for the Typicode response data -First, we'll create a Typescript interface to map the response data from a server. +First, create a Typescript interface to map the response data from a server: -Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain our interface (sometimes referred to as a "document" or "doc"). Within the doc folder, create a file named `ITodo.ts`. +1. Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain the interface. The interface specifies the properties that we expect from the JSON response. -The `ITodo.ts` file will contain the following: +2. In the `doc` folder, create a file named `ITodo.ts`. -```typescript -export interface ITodo { - userId: number; - id: number; - title: string; - completed: boolean; -} -``` +3. Edit the `ITodo.ts` file to contain the following code: + + ```typescript + export interface ITodo { + userId: number; + id: number; + title: string; + completed: boolean; + } + ``` ### Creating a programmatic API -Next, we'll create a Node.js API that our command handler uses. This API can also be used in any Node.js application, because these Node.js APIs make use of REST APIs, Node.js APIs, other NPM packages, or custom logic to provide higher level functions than are served by any single API. +Next, create a Node.js API for the command handler to use. -Adjacent to the existing file named `zowe-cli-sample-plugin/src/api/Files.ts`, create a file `Typicode.ts`. +This API can also be used in any Node.js application. -`Typicode.ts`should contain the following: +1. Create a file named `Typicode.ts` in the `zowe-cli-sample-plugin/src/api` directory. -```typescript -import { ITodo } from "./doc/ITodo"; -import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; +2. Edit the `Typicode.ts` file to contain the following code: -export class Typicode { + ```typescript + import { ITodo } from "./doc/ITodo"; + import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; - public static readonly TODO_URI = "/todos"; + export class Typicode { - public static getTodos(session: AbstractSession): Promise {
- Logger.getAppLogger().trace("Typicode.getTodos() called");
- return RestClient.getExpectJSON(session, Typicode.TODO_URI);
- }
+ public static readonly TODO_URI = "/todos";
+
+ public static getTodos(session: AbstractSession): Promise {
+ Logger.getAppLogger().trace("Typicode.getTodos() called");
+ return RestClient.getExpectJSON(session, Typicode.TODO_URI);
+ }
- public static getTodo(session: AbstractSession, id: number): Promise {
- Logger.getAppLogger().trace("Typicode.getTodos() called with id " + id);
- ImperativeExpect.toNotBeNullOrUndefined(id, "id must be provided");
- const resource = Typicode.TODO_URI + "/" + id;
- return RestClient.getExpectJSON(session, resource);
+ public static getTodo(session: AbstractSession, id: number): Promise {
+ Logger.getAppLogger().trace("Typicode.getTodos() called with id " + id);
+ ImperativeExpect.toNotBeNullOrUndefined(id, "id must be provided");
+ const resource = Typicode.TODO_URI + "/" + id;
+ return RestClient.getExpectJSON(session, resource);
+ }
}
-}
-```
+ ```
-The `Typicode` class provides two programmatic APIs, `getTodos` and `getTodo`, to get an array of `ITodo` objects or a specific
-`ITodo` respectively. The Node.js APIs use `@zowe/imperative` infrastructure to provide logging, parameter validation,
-and to call a REST API. See the [Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) for more information.
+ The `Typicode` class provides two programmatic APIs, `getTodos` and `getTodo`, to get an array of `ITodo` objects or a specific `ITodo`, respectively.
-#### Exporting interface and programmatic API for other Node.js applications
+ The Node.js APIs use `@zowe/imperative` infrastructure to provide logging, parameter validation, and to call a REST API. See the [Imperative CLI Framework documentation](https://github.com/zowe/zowe-cli/wiki) for more information.
-Update [zowe-cli-sample-plugin/src/index.ts](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/index.ts) to contain the following:
+#### Exporting the interface and programmatic API for other Node.js applications
+
+Edit the [zowe-cli-sample-plugin/src/index.ts](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/index.ts) file to contain the following code:
```typescript
export * from "./api/doc/ITodo";
export * from "./api/Typicode";
```
-A sample invocation of your API might look similar to the following, if it were used by a separate, standalone Node.js application:
+This allows a separate, standalone Node.js application to use APIs from the sample Typicode plug-in to get data from the REST API at jsonplaceholder.typicode.com.
+
+The following code is an example of how a Node.js application could import classes from your API to interact with the Typicode REST API:
+
```typescript
import { Typicode } from "@zowe/zowe-cli-sample-plugin";
import { Session, Imperative } from "@zowe/imperative";
@@ -93,91 +95,116 @@ const session = new Session({ hostname: "jsonplaceholder.typicode.com"});
})();
```
-### Checkpoint one
+### Verify that you can build the programmatic API
-Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present. At this point in this tutorial, you have a programmatic API
-that will be used by your handler or another Node.js application. Next you'll define the command syntax for the command that will use your programmatic Node.js APIs.
+In your terminal, issue `npm run build` in your terminal to verify a clean compilation and confirm that no lint errors are present.
+
+At this point, you have a programmatic API that can be used by your handler or another Node.js application. Next, define the command syntax for the command that uses your programmatic Node.js APIs.
### Creating a command definition
-Within Zowe CLI, the full command that we want to create is `zowe zowe-cli-sample list typicode-todos`. Navigate to `zowe-cli-sample-plugin/src/cli/list` and create a folder
-`typicode-todos`. Within this folder, create `TypicodeTodos.definition.ts`. Its content should be as follows:
-```typescript
-import { ICommandDefinition } from "@zowe/imperative";
-export const TypicodeTodosDefinition: ICommandDefinition = {
- name: "typicode-todos",
- aliases: ["td"],
- summary: "Lists typicode todos",
- description: "List typicode REST sample data",
- type: "command",
- handler: __dirname + "/TypicodeTodos.handler",
- options: [
- {
- name: "id",
- description: "The todo to list",
- type: "number"
- }
- ]
-};
+This tutorial creates the following command in Zowe CLI:
+
+```
+zowe zowe-cli-sample list typicode-todos`
```
-This describes the syntax of your command.
-#### Defining command to list group
+#### Defining the syntax of your command
-Within the file `zowe-cli-sample-plugin/src/cli/list/List.definition.ts`, add the following code below other `import` statements near the top of the file:
-```typescript
-import { TypicodeTodosDefinition } from "./typicode-todos/TypicodeTodos.definition";
-```
+1. Navigate to `zowe-cli-sample-plugin/src/cli/list` and create a folder titled `typicode-todos`.
-Then add `TypicodeTodosDefinition` to the children array. For example:
-```
-children: [DirectoryContentsDefinition, TypicodeTodosDefinition]
-```
+2. In this folder, create a file named `TypicodeTodos.definition.ts`.
+
+ Edit the `TypicodeTodos.definition.ts` file to contain the following code:
+
+ ```typescript
+ import { ICommandDefinition } from "@zowe/imperative";
+ export const TypicodeTodosDefinition: ICommandDefinition = {
+ name: "typicode-todos",
+ aliases: ["td"],
+ summary: "Lists typicode todos",
+ description: "List typicode REST sample data",
+ type: "command",
+ handler: __dirname + "/TypicodeTodos.handler",
+ options: [
+ {
+ name: "id",
+ description: "The todo to list",
+ type: "number"
+ }
+ ]
+ };
+ ```
+
+ The `TypicodeTodos.definition.ts` file describes the syntax of your command.
+
+#### Adding a command to a command group
+
+Add the newly created `TypicodeTodosDefinition` to the `list` command group to enable users to list to-dos by running the `zowe zowe-cli-sample list typicode-todos` command.
+
+1. In `zowe-cli-sample-plugin/src/cli/list/List.definition.ts`, add the following code below other `import` statements near the top of the file:
+ ```typescript
+ import { TypicodeTodosDefinition } from "./typicode-todos/TypicodeTodos.definition";
+ ```
+
+2. To the children array, add `TypicodeTodosDefinition`.
+
+ For example:
+ ```
+ children: [DirectoryContentsDefinition, TypicodeTodosDefinition]
+ ```
+ The command is added to the `list` command group.
### Creating a command handler
-Also within the `typicode-todos` folder, create `TypicodeTodos.handler.ts`. Add the following code to the new file:
-```typescript
-import { ICommandHandler, IHandlerParameters, TextUtils, Session } from "@zowe/imperative";
-import { Typicode } from "../../../api/Typicode";
-export default class TypicodeTodosHandler implements ICommandHandler {
-
- public static readonly TYPICODE_HOST = "jsonplaceholder.typicode.com";
- public async process(params: IHandlerParameters): Promise {
-
- const session = new Session({ hostname: TypicodeTodosHandler.TYPICODE_HOST});
- if (params.arguments.id) {
- const todo = await Typicode.getTodo(session, params.arguments.id);
- params.response.data.setObj(todo);
- params.response.console.log(TextUtils.prettyJson(todo));
- } else {
- const todos = await Typicode.getTodos(session);
- params.response.data.setObj(todos);
- params.response.console.log(TextUtils.prettyJson(todos));
+1. In the `typicode-todos` folder, create the file `TypicodeTodos.handler.ts`.
+
+2. Add the following code to the `TypicodeTodos.handler.ts` file:
+ ```typescript
+ import { ICommandHandler, IHandlerParameters, TextUtils, Session } from "@zowe/imperative";
+ import { Typicode } from "../../../api/Typicode";
+ export default class TypicodeTodosHandler implements ICommandHandler {
+
+ public static readonly TYPICODE_HOST = "jsonplaceholder.typicode.com";
+ public async process(params: IHandlerParameters): Promise {
+
+ const session = new Session({ hostname: TypicodeTodosHandler.TYPICODE_HOST});
+ if (params.arguments.id) {
+ const todo = await Typicode.getTodo(session, params.arguments.id);
+ params.response.data.setObj(todo);
+ params.response.console.log(TextUtils.prettyJson(todo));
+ } else {
+ const todos = await Typicode.getTodos(session);
+ params.response.data.setObj(todos);
+ params.response.console.log(TextUtils.prettyJson(todos));
+ }
}
}
-}
-```
-The `if` statement checks if a user provides an `--id` flag. If yes, we call `getTodo`. Otherwise, we call `getTodos`. If the
-Typicode API throws an error, the `@zowe/imperative` infrastructure will automatically surface this.
+ ```
+
+ The `if` statement checks if a user provides an `--id` flag. If yes, the command handler calls `getTodo`. Otherwise, the command handler calls `getTodos`.
+
+ If the Typicoce API throws an error, the error is forwarded to `@zowe/imperative` to log the error and display an error message in the terminal.
-### Checkpoint two
+### Verify that you can build your plug-in
-Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present. You now have a handler, definition, and your command has been defined to the `list` group of the command.
+Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present.
+
+You now have a command definition, the command has been added to the `list` command group, and you have a handler.
## Using the installed plug-in
-Issue the command: `zowe zowe-cli-sample list typicode-todos`
+Issue the command `zowe zowe-cli-sample list typicode-todos`.
-Refer to `zowe zowe-cli-sample list typicode-todos --help` for more information about your command and to see how text in the command definition
-is presented to the end user. You can also see how to use your optional `--id` flag:
+Refer to `zowe zowe-cli-sample list typicode-todos --help` for more information about your command and to see how text in the command definition is presented to the end user. You can also see how to use your optional `--id` flag:
## Summary
You extended an existing Zowe CLI plug-in by introducing a Node.js programmatic API, and you created a command definition with a handler.
-For an official plugin, you would also add [JSDoc](https://jsdoc.app/) to your code and create automated tests.
+
+For an official Zowe CLI plug-in, you would also add [JSDoc](https://jsdoc.app/) to your code and create automated tests.
## Next steps
diff --git a/docs/extend/extend-cli/cli-implement-profiles.md b/docs/extend/extend-cli/cli-implement-profiles.md
index 973becca3e..16e707a4fc 100644
--- a/docs/extend/extend-cli/cli-implement-profiles.md
+++ b/docs/extend/extend-cli/cli-implement-profiles.md
@@ -1,74 +1,106 @@
# Implementing profiles in a plug-in
-You can use this profile template to create a profile for your product.
-
-The profile definition is placed in the `imperative.ts` file.
-
-The `type: "someproduct"` property represents the profile name that you might require on various commands to have credentials loaded
-from a secure credential manager and retain the host/port information, so that you can easily swap to different servers from the CLI.
-
- By default, if your plug-in that is installed into Zowe™ CLI contains a profile definition that is similar to the following example, a profile template is added automatically to team config JSON when you run the `zowe config init` command. Any properties for which `includeInTemplate` is true are included in the template. Additionally, commands that manage V1 profiles are created automatically under `zowe profiles`. For example, `create`, `validate`, `set-default`, `list`, and so on.
-
-
-```typescript
-profiles: [
- {
- type: "someproduct",
- schema: {
- type: "object",
- title: "Configuration profile for SOME PRODUCT",
- description: "Configuration profile for SOME PRODUCT ",
- properties: {
- host: {
- type: "string",
- optionDefinition: {
- type: "string",
- name: "host",
- alias:["H"],
- description: "Host name of your SOME PRODUCT REST API server"
- }
- },
- port: {
- type: "number",
- optionDefinition: {
- type: "number",
- name: "port",
- alias:["P"],
- includeInTemplate: true,
- description: "Port number of your SOME PRODUCT REST API server"
- }
- },
- user: {
- type: "string",
- optionDefinition: {
- type: "string",
- name: "user",
- alias:["u"],
- description: "User name to authenticate to your SOME PRODUCT REST API server"
- },
- secure: true
- },
- password: {
- type: "string",
- optionDefinition: {
- type: "string",
- name: "password",
- alias:["p"],
- description: "Password to authenticate to your SOME PRODUCT REST API server"
+
+Users of your plug-in communicate with the mainframe by specifying connection information in a configuration profile.
+
+For profiles to work with services other than z/OSMF, SSH, and TSO, developers must define profile types and the profile structure for their plug-in in a special file. This plug-in definition file ultimately allows an end user to add the plug-in profile — and its connection details — to their team configuration.
+
+When creating profile types for a plug-in, apply the following code as a template to the plug-in definition file. Modify the template as necessary by changing values and/or adding more properties.
+
+## Editing the plug-in definition file
+
+You can specify the plug-in definition file name and location in your plug-in's `package.json` file. For example:
+
+```
+"imperative": {
+ "configurationModule": "lib/pluginDef.js"
+ },
+```
+
+ - `pluginDef.js`
+
+ The runtime file
+
+ - `src/pluginDef.ts`
+
+ Location of your definition source
+
+Edit the `pluginDef.ts` file (or your equivalent) to define profile types for your plug-in:
+
+1. Use a text editor to open the `pluginDef.ts` file.
+
+2. In the `pluginDef.ts` file, add the following profile definition:
+
+ ```typescript
+ profiles: [
+ {
+ type: "someproduct",
+ schema: {
+ type: "object",
+ title: "Configuration profile for SOME PRODUCT",
+ description: "Configuration profile for SOME PRODUCT ",
+ properties: {
+ host: {
+ type: "string",
+ optionDefinition: {
+ type: "string",
+ name: "host",
+ alias:["H"],
+ description: "Host name of your SOME PRODUCT REST API server"
+ }
+ },
+ port: {
+ type: "number",
+ optionDefinition: {
+ type: "number",
+ name: "port",
+ alias:["P"],
+ includeInTemplate: true,
+ description: "Port number of your SOME PRODUCT REST API server"
+ }
+ },
+ user: {
+ type: "string",
+ optionDefinition: {
+ type: "string",
+ name: "user",
+ alias:["u"],
+ description: "User name to authenticate to your SOME PRODUCT REST API server"
+ },
+ secure: true
+ },
+ password: {
+ type: "string",
+ optionDefinition: {
+ type: "string",
+ name: "password",
+ alias:["p"],
+ description: "Password to authenticate to your SOME PRODUCT REST API server"
+ },
+ secure: true
+ },
},
- secure: true
},
- },
- },
- createProfileExamples: [
- {
- options: "spprofile --host zos123 --port 1234 --user ibmuser --password myp4ss",
- description: "Create a SOME PRODUCT profile named 'spprofile' to connect to SOME PRODUCT at host zos123 and port 1234"
}
- ]
- }
-]
-```
+ ]
+ ```
+3. Replace `someproduct` in `type: "someproduct"` with your plug-in profile name.
+
+ This property represents the name of the profile type option that might be required on commands that allow users to select a profile from their team configuration. (Zowe CLI has profile types for z/OSMF, SSH, and TSO.)
+
+ - For example, the `zowe zosmf check status --zosmf-profile` command includes an option that specifies a z/OSMF profile from the user's team configuration. For your plug-in, the profile type that you define can be used in a commands to specify a profile for your plug-in.
+
+ This value is used in team configuration to create a plug-in profile to connect to the mainframe.
+
+4. Update the title and description for your plug-in.
+
+5. Add any needed properties to allow users to configure plug-in settings.
+
+ Each option property in the template includes an `optionDefinition`. For a reference of `optionDefinition` attributes, see the [`ICommandOptionDefinition` interface](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/cmd/src/doc/option/ICommandOptionDefinition.ts).
+
+6. Set the `includeInTemplate` property to `true` to dictate that this property is included in any generated team configuration.
+
+ If set to `false` or not included, end users will have to add the property themselves when editing their team configuration.
-**Next steps**
+7. Set the `secure` property to `true` to ensure that any value the end user specifies for this property is stored by default in their secure credential store. Otherwise the value is stored as plain text.
-If you completed all previous tutorials, you now understand the basics of extending and developing plug-ins for Zowe CLI. Next, we recommend reviewing the project [contribution guidelines](cli-devTutorials.md#contribution-guidelines) and [Imperative CLI Framework documentation](cli-devTutorials.md#imperative-cli-framework-documentation) to learn more.
\ No newline at end of file
+ The profile has been defined as needed.
diff --git a/docs/extend/extend-cli/cli-installing-sample-plugin.md b/docs/extend/extend-cli/cli-installing-sample-plugin.md
index 8f7ec4f5fb..203f5b45e3 100644
--- a/docs/extend/extend-cli/cli-installing-sample-plugin.md
+++ b/docs/extend/extend-cli/cli-installing-sample-plugin.md
@@ -1,36 +1,48 @@
# Installing the sample plug-in
-Before you begin, [set up](cli-setting-up.md) your local environment to install a plug-in.
+This tutorial covers installing and running the [Zowe™ CLI sample plug-in](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in), which adds a command to the CLI to list the contents of a directory on your computer.
-## Overview
-This tutorial covers installing and running this bundled Zowe™ CLI plugin as-is (without modification), which adds a command to the CLI that lists the contents of a directory on your computer.
+Before you begin, [set up](cli-setting-up.md) your local environment to install a plug-in.
## Installing the sample plug-in to Zowe CLI
-To begin, `cd` into your `zowe-tutorial` folder. (See [Initial setup](cli-setting-up.md#initial-setup) for instructions on creating the `zowe-tutorial` folder.)
+To install the Zowe CLI sample plug-in:
+
+1. Open a terminal and enter `cd zowe-tutorial` to change directory into your `zowe-tutorial` folder.
+
+ See [Initial setup](cli-setting-up.md#initial-setup) for instructions on creating the `zowe-tutorial` folder.
+
+2. Issue the following command to install the sample plug-in to Zowe CLI:
-Issue the following commands to install the sample plug-in to Zowe CLI:
+ ```
+ zowe plugins install ./zowe-cli-sample-plugin
+ ```
-`zowe plugins install ./zowe-cli-sample-plugin`
+ The Zowe CLI Sample Plug-in is installed.
## Viewing the installed plug-in
-Issue `zowe --help` in the command line to return information for the installed `zowe-cli-sample` command group:
+
+Open a terminal and issue the `zowe --help`command to return information for the installed `zowe-cli-sample` command group:
## Using the installed plug-in
-To use the plug-in functionality, issue: `zowe zowe-cli-sample list directory-contents`:
+
+Open a terminal and issue the `zowe zowe-cli-sample list directory-contents` command:
## Testing the installed plug-in
-To run automated tests against the plug-in, `cd` into your `zowe-tutorial/zowe-cli-sample-plugin` folder.
-Issue the following command:
+1. Open a terminal and enter `cd zowe-tutorial/zowe-cli-sample-plugin` to run automated tests against the plug-in.
-```
-npm run test
-```
+2. Issue the following command:
+
+ ```
+ npm run test
+ ```
+ The command runs the automated unit and system tests defined in the `__tests__` folder. Test results are displayed in the terminal with the count of passed and failed tests. Failed tests are identified in the results.
## Next steps
-You successfully installed a plug-in to Zowe CLI! Next, try the [Extending a plug-in](cli-extending-a-plugin.md) tutorial to learn about developing new commands for this plug-in.
\ No newline at end of file
+
+You successfully installed a plug-in to Zowe CLI! Next, try the [Extending a plug-in](cli-extending-a-plugin.md) tutorial to learn about developing new commands for this plug-in.
diff --git a/docs/extend/extend-cli/cli-setting-up.md b/docs/extend/extend-cli/cli-setting-up.md
index e3fc70ec16..fd6e1e74d0 100644
--- a/docs/extend/extend-cli/cli-setting-up.md
+++ b/docs/extend/extend-cli/cli-setting-up.md
@@ -5,43 +5,36 @@ Before you follow the development tutorials for creating a Zowe™ CLI plug-
[Install Zowe CLI](../../user-guide/cli-installcli#methods-to-install-zowe-cli).
## Initial setup
-To create your development space, clone and build [zowe-cli-sample-plugin](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) from source.
-Before you clone the repository, create a local development folder named `zowe-tutorial`. You will clone and build all projects in this folder.
+### Clone and build your project
-## Branches
+1. Create a local development folder named `zowe-tutorial` to clone and build all projects in this folder.
-There are two branches in the repository that correspond to different Zowe CLI versions. You can develop two branches of your plug-in so that users can install your plug-in into `@latest` or `@zowe-v2-lts` CLI. Developing for both versions will let you take advantage of new core features quickly and expose your plug-in to a wider range of users.
+2. Clone [`zowe-cli-sample-plugin`](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) and build from source.
-The `master` branch of Sample Plug-in is compatible with the `@zowe-v2-lts` version of core CLI (Zowe LTS release).
+ Clone the repository into your development folder to match the following structure:
+ ```
+ zowe-tutorial
+ └── zowe-cli-sample-plugin
+ ```
-The `master` branch of Sample Plug-in is also compatible with the `@latest` version of core CLI (Zowe Active Development release) at this time.
+ 1. Open a terminal and enter `cd zowe-tutorial` to change directory into your `zowe-tutorial` folder.
+ 2. Enter `git clone https://github.com/zowe/zowe-cli-sample-plugin` to clone the `zowe-cli-sample-plugin` repository.
+ 3. Enter `cd zowe-cli-sample-plugin` to change directory into your `zowe-cli-sample-plugin` folder.
+ 4. Enter `npm install` to install all dependencies and modules for the project.
+ 5. Enter `npm run build` to create a production build.
-For more information about the versioning scheme, see [Maintainer Versioning](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) in the Zowe CLI repository.
+### Optional step: Run automated tests
-### Clone zowe-cli-sample-plugin and build from source
-Clone the repository into your development folder to match the following structure:
-```
-zowe-tutorial
-└── zowe-cli-sample-plugin
-```
-**Follow these steps:**
+We recommend running automated tests on all code changes.
-1. `cd` to your `zowe-tutorial` folder.
-2. `git clone https://github.com/zowe/zowe-cli-sample-plugin`
-3. `cd` to your `zowe-cli-sample-plugin` folder.
-4. `git checkout master`
-5. `npm install`
-6. `npm run build`
+To run automated tests:
-### (Optional) Run the automated tests
-We recommend running automated tests on all code changes. Follow these steps:
-
-1. `cd` to the `__tests__/__resources__/properties` folder.
-2. Copy `example_properties.yaml` to `custom_properties.yaml`.
-3. Edit the properties within `custom_properties.yaml` to contain valid system information for your site.
-4. `cd` to your `zowe-cli-sample-plugin` folder
-5. `npm run test`
+1. Use Visual Studio Code or your file explorer to copy the content in the `example_properties.yaml` file to the `custom_properties.yaml` file.
+2. Use a text editor to edit the properties within `custom_properties.yaml` to contain valid system information for your site.
+3. In a terminal, enter `cd zowe-cli-sample-plugin` to change directory into your `zowe-cli-sample-plugin` folder.
+4. Enter `npm run test` to run the automated test.
## Next steps
+
After you complete your setup, follow the [Installing the sample plug-in](cli-installing-sample-plugin.md) tutorial to install this sample plug-in to Zowe CLI.
diff --git a/docs/extend/extend-cli/cli-tutorials.md b/docs/extend/extend-cli/cli-tutorials.md
new file mode 100644
index 0000000000..fede8c1302
--- /dev/null
+++ b/docs/extend/extend-cli/cli-tutorials.md
@@ -0,0 +1,11 @@
+# Tutorials
+
+To better understand how to extend Zowe CLI and Zowe CLI plug-ins, read through the Extend tutorials.
+
+The following topics are covered in the tutorials:
+
+1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment.
+2. [Installing a plug-in:](cli-installing-sample-plugin.md) Install the sample plug-in to Zowe CLI and run as-is.
+3. [Extending a plug-in:](cli-extending-a-plugin.md) Extend the sample plug-in with a new command by creating a programmatic API, definition, and handler.
+4. [Creating a new plug-in:](cli-developing-a-plugin.md) Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets.
+5. [Implementing user profiles:](cli-implement-profiles.md) Implement user profiles with the plug-in.
\ No newline at end of file
diff --git a/docs/extend/extend-desktop/mvd-conda.md b/docs/extend/extend-desktop/mvd-conda.md
deleted file mode 100644
index 1b54a532da..0000000000
--- a/docs/extend/extend-desktop/mvd-conda.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# Using Conda to make and manage packages of Application Framework Plugins
-
-As Zowe is composed of components which can be extended by Plugins,
-a standardized and simple way to find, install, upgrade, and list Plugins in your Zowe environment
-is important to make it easy to get the most out of Zowe.
-
-Package management as a concept generally provides a way to find packages such as plugins,
-check and possible co-install dependencies the package has, and ultimately install the desired package.
-Post-install, management tasks such as upgrading and uninstalling are common.
-
-Conda is one such package manager, and if you are familiar with apt, yum, or npm, you will find
-that using Conda is very similar. But, there are some important abilities that make Conda stand out:
-
-* Very cross platform: Conda is available, and acts very similar on z/OS, Windows, Linux, macOS, and various Unix.
- Packages can state which platforms they support, so it easy to know what packages you can install.
-* Tagging: On z/OS, Conda packages can contain tagging information, to avoid issues around the difference between EBCDIC & ASCII.
-* Software neutrality: Language-specific package managers are becoming popular, but Conda does not assume the purpose of the package, so you can install almost anything.
-* Environments: If desired, every user can have a different set of packages, because Conda can install & manage packages in personal folders instead of system ones.
- A user can even have multiple such environments, and switch between them rapidly to work with different sets of related software without conflict.
-
-
-## Initial Conda setup
-
-If you have not installed Conda yet, it can be downloaded as an all-in-one package that has no extra dependencies, known as "miniconda".
-For Linux, Unix, macOS, and Windows, this can be downloaded at https://docs.conda.io/en/latest/miniconda.html
-For z/OS, Conda can be downloaded from Rocket Software at https://www.rocketsoftware.com/zos-open-source
-
-Conda will prompt during the install for certain setup options,
-and ultimately you'll want to put some Conda initialization content into your startup script
-so that whenever you open your terminal, Conda will be ready for your use.
-
-Once you have Conda downloaded and installed, you'll want to create your first Conda "environment"
-this can be done by providing a path or a nickname
-
-`conda create --prefix PATH`
-`conda create --name ENVIRONMENT`
-
-Either will work, but path helps you better separate your content from content others use by placing it in a folder that you can have stricter permissions on.
-
-If you need to know more about certain commands, you can use the help command for any.
-
-`conda create --help`
-
-Or, check the official documentation: https://docs.conda.io/en/latest/index.html
-
-Once you have an environment, you should activate it so that the actions you do are on that environment, as opposed to the base one.
-
-`conda activate PATH_OR_NAME`
-
-Conda will detect whether the parameter is a path or a nickname, so this command works for both.
-
-Finally, you can view the Conda environment and other information by checking "info"
-
-`conda info`
-
-## Managing Conda channels
-
-When downloading a package, such as a Zowe Plugin, the place that you download from is configurable.
-These are called "Channels", but are very similar to "Repositories" seen in other package managers.
-With Conda, you can install from:
-
-* A network channel (Internet or company internal)
-* A local channel (Collection of plugins on your computer)
-* Just an individual package, without a channel
-
-You can have multiple of each, and if a package is present in more than one location, you can specify which one to use.
-
-## Searching for packages
-
-Conda has a search utility that searches for all Channels,
-
-`conda search anything_you_want`
-
-but it's important to note that because any type of software can be installed through Conda, you probably want to search through a detailed view to help identify which ones are meant for Zowe, or use Channels that are distinctly for Zowe so that you can get packages that are strictly for Zowe.
-
-`conda search --info anything_you_want`
-
-## Using Conda with Zowe
-
-Zowe is not yet available in the form of Conda packages yet, so it must be installed separately.
-If you have Zowe installed on the same system as Conda, some Zowe Plugins installed through Conda will automatically register into Zowe.
-In order to do this, the Plugins must be able to find Zowe. You should set environment variables before trying to install the Plugins:
-
-### Setting environment variables temporarily:
-
-z/OS, Linux, Unix:
-```
-export ZOWE_INSTANCE_DIR=/path/to/zowe/instance
-export ZOWE_ROOT_DIR=/path/to/zowe/installation
-```
-
-Windows cmd.exe:
-```
-set ZOWE_INSTANCE_DIR=\path\to\zowe\instance
-set ZOWE_ROOT_DIR=\path\to\zowe\installation
-```
-
-`INSTANCE_DIR` and `ROOT_DIR` are also supported, but the `ZOWE_` prefix helps distinguish its purpose.
-
-### Setting environment variables persistently
-
-z/OS, Linux, Unix:
-You can put the `export` statements into the `.profile` file in your home directory to have them apply on login.
-
-Windows:
-There is a UI to set variables, but it varies depending on Windows version.
-Try typing 'environment variable' into the Windows search bar to get to the relevant menu.
-
-### Installing a Zowe plugin
-
-A Conda package could contain one or more Zowe Plugins, and a Conda package could contain non-Zowe code alongside Zowe Plugins.
-This is left up to the program vendor and regardless the install process is the same:
-
-`conda install package_name`
-
-If the Zowe environment variables are set, such a package may automatically register Plugins into the Zowe instance of your choice.
-
-### Zowe plugin configuration
-
-Aside from possible automation during install and uninstall, Conda does not manage Zowe, its configuration, or configuration of the Plugins.
-However, Conda does manage the package files, and therefore you can do additional Zowe tasks on the Plugins by going into the Conda environment.
-Zowe Plugins are intended to be found in a standardized location in the Conda environment,
-
-`/opt/zowe/plugins`
-
-This folder contains Plugins, which in turn contain sub-folders that are the Zowe components that they utilize.
-If a plugin uses multiple Zowe components, its contents could be found within multiple component folders.
-
-`/opt/zowe/plugins/my_plugin/app-server`
-`/opt/zowe/plugins/my_plugin/cli`
-
-### Zowe package structure
-
-Zowe Plugins packaged into Conda follow the structure outlined here: https://github.com/zowe/zowe-install-packaging/issues/1569
-This structure allows for plugin to have content meant for one or more Zowe components.
-The Conda packages extend this by allowing for more than one Plugin, or a mix of Zowe Plugins and other software to be within a single package.
-
-## Building Conda packages for Zowe
-
-This document is intended to be provided with example scripts by the Zowe community, which shows you how you can build a simple Zowe plugin into a Conda package.
-You can find the example scripts on the [Zowe zlux-build github repository.](https://github.com/zowe/zlux-build/tree/master/conda)
-This is not intended to be a one-size-fits-all set of scripts. If you have more advanced needs, you can use these scripts as a basis for writing your own scripts.
-
-To make a Conda package, you need conda-build, which you can install into a Conda environment:
-
-`conda install conda-build`
-
-Once you have it, you can build a package via
-
-`conda build path/to/build/scripts`
-
-However, first you must set up the build information.
-
-### Defining package properties
-
-Conda needs a metadata file, `meta.yaml` to state information about the package, such as dependencies, what OS it supports, its name and version.
-This information can be programmatically found, and Zowe provides examples of how to do this by reading Zowe's own metadata files into this one.
-
-### Creating build step
-
-It's recommended not to build your code from scratch to put into Conda.
-Rather, build your code however you want, and then just copy the contents into a Conda package. This keeps the Conda scripting small and simple.
-
-In the same folder as `meta.yaml`, Conda requires `build.sh` for building on Unix, Linux, or z/OS and `build.bat` for Windows.
-Except for z/OS, this script does not determine where your package can be used, it's just about where you are building it.
-z/OS is the exception because when you build on z/OS, unix file tagging information is preserved.
-So, it's highly recommended that you tag your files so that users do not have to deal with encoding issues.
-For code that works equally well on all platforms, a simple way to build for all is:
-1. Build your code on Linux
-1. Transfer the output to z/OS
-1. Run a Conda build on the output on Linux
-1. Run a Conda build on the output on z/OS
-1. Deliver the Linux package as 'noarch' content, and the z/OS package as 'zos-z' content.
-
-### Lifecycle scripts
-
-When a Conda package is installed or uninstalled, a script from the package can be run.
-For Zowe, the scripts `post-link.sh` and `pre-unlink.sh` can be important, and you must put them into the same folder as `meta.yaml` for building.
-
-#### Install automation
-
-`post-link.sh` runs at install, after Conda has put the package content onto the system.
-At this time, registration into Zowe is recommended if the Plugin does not require any information from the user for configuration.
-If the Plugin is okay to be automatically installed, we recommend putting a script into the package folder named `autoinstall.sh`
-Zowe's provided Conda examples will utilize `autoinstall.sh` to do any install steps your package needs, and provides Zowe information to make install simple.
-However, it's possible to do what you want in your own `post-link.sh` script instead.
-
-#### Uninstall automation
-
-`pre-unlink.sh` is the opposite of `post-link.sh`. It allows you to do anything you need to before the package is removed from the system.
-This is a good time to remove any package information from Zowe, but you should be careful because users may uninstall and later re-install,
-so you should not remove configuration information without consent.
-
-### Adding configuration to Conda packages
-
-As a package manager, Conda is not responsible for configuration. Your packages can include defaults to utilize,
-but if configuration is needed you should alert the user to perform a post-install task. `post-link.sh` could be used to print such an alert.
diff --git a/docs/extend/extend-desktop/mvd-configdataservice.md b/docs/extend/extend-desktop/mvd-configdataservice.md
index 02da7ce37c..d3995fa1e9 100644
--- a/docs/extend/extend-desktop/mvd-configdataservice.md
+++ b/docs/extend/extend-desktop/mvd-configdataservice.md
@@ -306,5 +306,5 @@ The following policies are currently implemented:
## Examples
- [zlux-app-manager](https://github.com/zowe/zlux-app-manager/tree/v2.x/master/bootstrap/src/uri/mvd-uri.ts)
- [VT Terminal App](https://github.com/zowe/vt-ng2/blob/v2.x/master/webClient/src/app/app.component.ts)
+ [zlux-app-manager](https://github.com/zowe/zlux-app-manager/tree/v3.x/master/bootstrap/src/uri/mvd-uri.ts)
+ [VT Terminal App](https://github.com/zowe/vt-ng2/blob/v3.x/master/webClient/src/app/app.component.ts)
diff --git a/docs/extend/extend-desktop/mvd-externals.md b/docs/extend/extend-desktop/mvd-externals.md
index f672df67d5..420175de42 100644
--- a/docs/extend/extend-desktop/mvd-externals.md
+++ b/docs/extend/extend-desktop/mvd-externals.md
@@ -1,27 +1,26 @@
-In the Zowe Desktop, multiple Apps can coexist but such Apps are treated as independent entities, and may be independently developed. To keep resources in check while allowing for Apps to depend on rich libraries, common libraries are deduplicated by having Apps refer to a collection of these libraries, considered the "Externals" bundle. This bundle is loaded on page load from `/ZLUX/plugins/org.zowe.zlux.ng2desktop/web/externals.js`. The current list of libraries that are present in this bundle is:
+In the Zowe Desktop, multiple Apps can coexist but such Apps are treated as independent entities, and may be independently developed. To keep resources in check while allowing for Apps to depend on rich libraries, common libraries are deduplicated by having Apps refer to a collection of these libraries, considered the "Externals" bundle. This bundle is loaded on page load from `/ZLUX/plugins/org.zowe.zlux.ng2desktop/web/main.js`. The current list of libraries that are present in this bundle is:
| Library | Version |
|---------|---------|
-| '@angular/animations' | 12.0.0 |
-| '@angular/cdk' | 12.0.0 |
-| '@angular/core' | 12.0.0 |
-| '@angular/common' | 12.0.0 |
-| '@angular/common/http' | 12.0.0 |
-| '@angular/forms' | 12.0.0 |
-| '@angular/platform-browser' | 12.0.0 |
-| '@angular/cdk/portal' | 12.0.0 |
-| '@angular/material' | 12.0.0 |
-| '@angular/router' | 12.0.0 |
-| 'angular-l10n' | 12.0.0 |
-| 'bootstrap' | 4.3.1 |
-| 'corejs' | 3.19.2 |
-| 'jquery' | 3.6.0 |
+| '@angular/animations' | 18.0.0 |
+| '@angular/cdk' | 18.0.0 |
+| '@angular/core' | 18.0.0 |
+| '@angular/common' | 18.0.0 |
+| '@angular/common/http' | 18.0.0 |
+| '@angular/forms' | 18.0.0 |
+| '@angular/platform-browser' | 18.0.0 |
+| '@angular/cdk/portal' | 18.0.0 |
+| '@angular/material' | 18.0.0 |
+| '@angular/router' | 18.0.0 |
+| 'angular-l10n' | 18.0.0 |
+| 'bootstrap' | 5.3.2 |
+| 'corejs' | 3.38.1 |
| 'popper.js' | 1.14.7 |
-| 'rxjs' | 6.6.0 |
+| 'rxjs' | 7.8.1 |
The above list is derived from 3 source files. Please consult them for up-to-date information:
-1) [package-lock.json](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/package-lock.json) for version information
-2) [externals.ts](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/src/externals.ts) which loads the libraries into the browser at page load
-3) [externals-main.ts](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/src/externals-main.ts) which imports libraries that were not loadable with the technique in #2
+1) [package-lock.json](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/package-lock.json) for version information
+2) [desktop.ts](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/src/desktop.ts) which loads the libraries into the browser at page load
+3) [webpack5.base.js](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/plugin-config/webpack5.base.js) which is an example of how a plugin may depend upon these libraries without including them, via the "externals" configuration object.
Apps that are not of type "iframe" should not use any other versions of these libraries, due to the chance for conflict to occur at runtime.
diff --git a/docs/extend/extend-desktop/mvd-iframecomm.md b/docs/extend/extend-desktop/mvd-iframecomm.md
index fba0d54281..ead4de3299 100644
--- a/docs/extend/extend-desktop/mvd-iframecomm.md
+++ b/docs/extend/extend-desktop/mvd-iframecomm.md
@@ -1,5 +1,5 @@
# Configuring IFrame communication
-The Zowe Application Framework provides the following shared resource functions through a [ZoweZLUX object](https://github.com/zowe/zlux-platform/blob/v2.x/master/interface/src/index.d.ts#L720): `pluginManager`, `uriBroker`, `dispatcher`, `logger`, `registry`, `notificationManager`, and `globalization`
+The Zowe Application Framework provides the following shared resource functions through a [ZoweZLUX object](https://github.com/zowe/zlux-platform/blob/v3.x/master/interface/src/index.d.ts#L720): `pluginManager`, `uriBroker`, `dispatcher`, `logger`, `registry`, `notificationManager`, and `globalization`
Like REACT and Angular apps, IFrame apps can use the ZoweZLUX object to communicate with the framework and other apps. To enable communication in an IFrame app, you must add the following javascript to your app, for example in your `index.html` file:
diff --git a/docs/extend/extend-desktop/mvd-logutility.md b/docs/extend/extend-desktop/mvd-logutility.md
index 327d4b4ba0..073a59e56c 100644
--- a/docs/extend/extend-desktop/mvd-logutility.md
+++ b/docs/extend/extend-desktop/mvd-logutility.md
@@ -2,22 +2,6 @@
The `zlux-shared` repository provides a logging utility for use by dataservices and web content for an application plug-in.
-1. [Logging Objects](#logging-objects)
-1. [Logger IDs](#logger-ids)
-1. [Accessing Logger Objects](#accessing-logger-objects)
- 1. [Logger](#logger)
- 1. [App Server](#app-server)
- 1. [Web](#web)
- 1. [Component Logger](#component-logger)
- 1. [App Server](#app-server-1)
-1. [Logger API](#logger-api)
-1. [Component Logger API](#component-logger-api)
-1. [Log Levels](#log-levels)
-1. [Logging Verbosity](#logging-verbosity)
- 1. [Configuring Logging Verbosity](#configuring-logging-verbosity)
- 1. [Server Startup Logging Configuration](#server-startup-logging-configuration)
-1. [Using log message IDs](#using-log-message-ids)
-
## Logging objects
@@ -57,7 +41,6 @@ Component loggers are created from the core logger object, but when working with
See **Router Dataservice Context** in the topic [Dataservices](mvd-dataservices.md).
-
## Logger API
The following constants and functions are available on the central logging object.
@@ -105,8 +88,11 @@ An enum, `LogLevel`, exists for specifying the verbosity level of a logger. The
| FINER | 4
| TRACE | 5
-**Note:** The default log level for a logger is **INFO**.
+:::note
+The default log level for a logger is **INFO**.
+
+:::
## Logging verbosity
@@ -123,9 +109,10 @@ The application plug-in framework provides ways to specify what component logger
#### Server startup logging configuration
-[The server configuration file](https://github.com/zowe/zlux/wiki/Configuration-for-zLUX-App-Server-&-ZSS) allows for specification 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.
+[The server configuration file](mvd-server-config.md) allows for specification 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,
@@ -138,9 +125,11 @@ For example:
//"_unp.dsauth": 2
},
```
+
For more information about the server configuration file, see [Zowe Application Framework (zLUX) configuration](../../user-guide/mvd-configuration#configuration-file).
## Using log message IDs
+
To make technical support for your application easier, create IDs for common log messages and use substitution to generate them. When you use IDs, people fielding support calls can identify and solve problems more quickly. IDs are particularly helpful if your application is translated, because it avoids users having to explain problems using language that the tech support person might not understand.
To use log message IDs, take the following steps:
@@ -178,7 +167,7 @@ To use log message IDs, take the following steps:
```
DATE TIME:TIME:TIME.TIME username INFO (org.zowe.app.name,:) A001 - Приложение создано.
```
-
+
### Message ID logging examples
Server core: https://github.com/zowe/zlux-server-framework/blob/v2.x/master/plugins/config/lib/assets/i18n/log/messages_en.json
diff --git a/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md b/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md
index 8405259e6d..f3a7d7c8c8 100644
--- a/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md
+++ b/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md
@@ -55,7 +55,9 @@ Every instance of an application's web content within Zowe is given context and
When the Window is created, the application's web content is encapsulated dependent upon its framework type. The following are valid framework types:
-- "angular2": The web content is written in Angular, and packaged with Webpack. Application framework objects are given through @injectables and imports.
+- "angular": The web content is written in Angular, and packaged with Webpack. Application framework objects are given through @injectables and imports.
+
+- "react": The web content is written in React, and packaged with Webpack. Application framework objects are given through `this.props`.
- "iframe": The web content can be written using any framework, but is included through an iframe tag. Applications within an iframe can access framework objects through `parent.ZoweZLUX` and callbacks.
diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md
index 76d46c0390..780f1ced26 100644
--- a/docs/extend/extend-desktop/mvd-server-config.md
+++ b/docs/extend/extend-desktop/mvd-server-config.md
@@ -1,16 +1,28 @@
+# Advanced Server Configuration
+
The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more.
-These parameters can be specified in multiple ways: configuration files, CLI arguments, or environment variables.
-Every configuration option and requirement is documented within the application framework [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zlux-config-schema.json)
+## Configuration file
+
+The servers use a YAML file for configuration. The [global schema](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/schemas/zowe-yaml-schema.json) describes the parts of configuration that are common between servers.
+
+The App Server specifically is configured by the `components.app-server` section of the YAML, and that section follows [this App-server schema](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json).
+
+ZSS is instead configured by the `components.zss` section, following [the ZSS schema](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json).
-# Configuration file
-In Zowe's server configuration file, app-server parameters can be specified within `components.app-server` as shown in the component [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zowe-schema.json), or `components.zss` for ZSS.
+The App server can additionally use environment variables to override the YAML file.
+
+## Environment variables (app-server only)
-# Environment variables
CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments.
-The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object.
-The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values.
+The format is `ZWED_key=value`, where `ZWED_` is a prefix for any configuration object.
+
+The attributes specified will be put within the `components.app-server` subsection of the Zowe configuration.
+
+The key maps to a JSON object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values.
+
For example:
+
```
node:
https:
@@ -26,7 +38,9 @@ logLevels:
org.zowe.terminal.tn3270.*: 5
```
+
In Environment variable format, this is specified as
+
```
ZWED_node_https_ipAddresses=0.0.0.0
ZWED_node_https_port=8554
@@ -37,70 +51,31 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5
```
**The key names are syntax sensitive.**
-* They are case-sensitive
-* All ascii characters except " are allowed in the object attribute names.
- * An encoding scheme is used for many symbols because environment variables can only have names with the characters A-Z, a-z, 0-9, `_`, `.`, and `-`
- * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A`
-* _ is used as the object separator, so an escape sequence is used if `_` is actually needed for the key.
- * Single leading and trailing _ are treated as literal `_`
- * __ will be maps to literal `_`
- * ___ maps to literal `-`
- * ____ maps to literal `.`
+* They are case-sensitive.
+* All ASCII characters except `"` are allowed in the object attribute names.
+ * An encoding scheme is used for many symbols because environment variables can only have names with the characters `A`-`Z`, `a`-`z`, `0`-`9`, `_`, `.`, and `-`.
+ * The scheme is _x followed by 2 hex numbers will be converted to the corresponding ASCII character, such as _x41 mapping to `A`.
+* `_` is used as the object separator, so an escape sequence is used if `_` is actually needed for the key.
+ * Single leading and trailing _ are treated as literal `_`.
+ * `__` will be maps to literal `_`
+ * `___` maps to literal `-`
+ * `____` maps to literal `.`
**The types of the values are syntax-sensitive.**
* Numbers are treated as numbers, not strings.
-* false & true are treated as boolean.
-* commas are for arrays. An array of length 1 has a comma at the end
-* strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string
-* objects are never values. They are the keys.
-
-## Friendly names for environment variables
-Some common configuration options have names that do not follow the above special syntax. These options get mapped to the special syntax when the server runs, so the same behavior can be configured in more than one way. Many of these values are listed here https://docs.zowe.org/stable/user-guide/configure-zowe-zosmf-workflow/#configure-the-zowe-instance-directory.
-
+* `false` and `true` are treated as boolean.
+* Commas are for arrays. An array of length 1 has a comma at the end.
+* Strings can have quotes, but otherwise everything that is not an array, boolean, or number is a string.
+* Objects are never values, they are the keys.
-Although overridden by both environment variables and CLI arguments, for convenience the App server and ZSS read from a configuration file with a common structure. ZSS reads this directly as a startup argument, while the App Server as defined in the [zlux-server-framework](https://github.com/zowe/zlux-server-framework) repository accepts several parameters which are intended to be read from a YAML file through an implementer of the server, such the default provided in the [zlux-app-server](https://github.com/zowe/zlux-app-server) repository, namely the [lib/zluxServer.js](https://github.com/zowe/zlux-app-server/blob/v2.x/master/lib/zluxServer.js) file. This file accepts a YAML file that specifies most if not all parameters needed, but some other parameters can be provided via flags if desired.
-
-# CLI arguments (app-server only)
-CLI arguments take precedence over environment variable and configuration files.
-The format is `--key=value`
-The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values.
-For example:
-```
-node:
- https:
- ipAddresses: 0.0.0.0
- port: 7556
- //pfx (string), keys, certificates, certificateAuthorities, and certificateRevocationLists are all valid here.
- keys: "../defaults/serverConfig/server.key"
- certificates: "../defaults/serverConfig/server.cert"
-
-```
-In CLI argument format, this is specified as
-```
-node.https.ipAddresses=0.0.0.0
-node.https.port=8554
-node.https.keys="../defaults/serverConfig/server.key"
-node.https.certificates="../defaults/serverConfig/server.cert"
-```
-
-**NOTE: ZSS does not support CLI arguments**
-
-**The key name is case-sensitive.**
-
-**The types of the values are syntax-sensitive.**
-* Numbers are treated as numbers, not strings.
-* false & true are treated as boolean.
-* commas are for arrays. An array of length 1 has a comma at the end
-* strings can have quotes, but otherwise everything that isn't an array, boolean, or number is a string
-* objects are never values. They are the keys.
-
-
-# Parameter Details
+## Parameter details
Below is some more detail on certain parameters than can be covered within the json-schema.
-## Configuration Directories
+### Configuration directories
+
When running, the App Server will access the server's settings and read/modify the contents of its resource storage.
+
All of this data is stored within a hierarchy of a few folders, which is correspond to scopes:
- Product: The contents of this folder are not meant to be modified, but used as defaults for a product.
- Site: The contents of this folder are intended to be shared across multiple App Server instances, perhaps on a network drive.
@@ -110,26 +85,32 @@ All of this data is stored within a hierarchy of a few folders, which is corresp
These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content.
-### Directories example
+#### Directories example
+
```
"productDir":"../defaults",
"siteDir":"/home/myuser/.zowe/workspace/app-server/site",
"instanceDir":"/home/myuser/.zowe/workspace/app-server",
"groupsDir":"/home/myuser/.zowe/workspace/app-server/groups",
"usersDir":"/home/myuser/.zowe/workspace/app-server/users",
-
```
+### App configuration
-## App configuration
This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance.
+
In the configuration file, a directory can be specified which contains JSON files which tell the server what App is to be included and where to find it on disk. The backend of these Apps use the Server's Plugin structure, so much of the server-side references to Apps use the term Plugin.
To include Apps, be sure to define the location of the Plugins directory in the configuration file, via the top-level attribute *pluginsDir*
-**NOTE: In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory.**
+:::note
+
+In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v3.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is `~/.zowe/workspace/app-server`. So, the example configuration file uses the latter directory.
+
+:::
+
+#### Plug-ins directory example
-### Plugins directory example
```
// All paths relative to zlux-app-server/lib
// In real installations, these values will be configured during the install.
@@ -137,23 +118,17 @@ To include Apps, be sure to define the location of the Plugins directory in the
"pluginsDir":"../defaults/plugins",
```
-## Logging configuration
+### Logging configuration
For more information, see [Logging Utility](mvd-logutility.md).
-## ZSS Configuration
-When running ZSS, it will require a configuration file similar or the same as the one used for the App Server. The attributes that are needed for ZSS, at minimum, are: *productDir*, *siteDir*, *instanceDir*, *groupsDir*, *usersDir*, *pluginsDir* and **agent**. All of these attributes have the same meaning as described above for the App server, but if the App server and ZSS are not run from the same location, then these directories may be different if desired.
+### ZSS Configuration
-### ZSS Networking
+ZSS is configured by the same Zowe YAML file used by the App server, within the `components.zss` section of the file. The [ZSS schema for components.zss be found here](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json). More information about the configuration can be found in its [README file](https://github.com/zowe/zss/#quick-run-how-to-start-zss).
-The attributes that control ZSS exclusively are within the **agent** object. ZSS uses HTTPS by default, but for those who wish to use AT-TLS instead of the built-in HTTPS support, ZSS can use HTTP as well. HTTP should never be used without [AT-TLS](../../user-guide/mvd-configuration#defining-the-at-tls-rule), as this is a security risk. The values `agent.https.port`, `agent.http.port` tell ZSS which ports to bind to, but also where the app-server can find ZSS. The values `agent.host` is used to tell app-server where to find ZSS as well, though `agent.https.ipAddresses` and `agent.http.ipAddresses` tell ZSS which addresses to bind to. For addresses, at this time only the first value of that array is used, and it may either be a hostname or an ipv4 address.
+#### Connecting ZSS to App Server
+
+The App Server can connect to ZSS either directly or through the API Mediation Layer Gateway when that is running.
+
+The connection information is stored within the object `components.app-server.agent`, which describes whether the Gateway is involved, or if not, on which host and port can ZSS be found. For more information, see the [agent section of the schema](https://github.com/zowe/zlux-app-server/blob/c22105381e129bd999c47e838b424679eba26aa6/schemas/app-server-config.json#L262)
-Example of the agent body:
-```
- agent:
- host: localhost
- https:
- ipAddresses: 0.0.0.0
- port: 7557
-
-```
diff --git a/docs/extend/extend-sdks.md b/docs/extend/extend-sdks.md
index 686f7a15b3..9929457626 100644
--- a/docs/extend/extend-sdks.md
+++ b/docs/extend/extend-sdks.md
@@ -2,8 +2,18 @@
The Zowe SDKs are open source. You can contribute to add features, enhancements, and bug fixes to the source code.
-The functionality is currently limited to the interfaces provided by IBM z/OSMF. As a plug-in developer, you can enhance the SDK by creating a packages that exposes programmatic APIs for your service.
+The functionality is currently limited to the interfaces provided by IBM z/OSMF. As a plug-in developer, you can enhance the SDK by creating a package that exposes programmatic APIs for your service.
+
+## Contributing to Zowe Client SDKs
For detailed contribution guidelines, see the following documents:
- [Node.js SDK guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/SDKGuidelines.md)
+- [Kotlin SDK guidelines](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md)
- **Coming soon! Python SDK guidelines**
+
+## Community resources
+
+- Join the [#zowe-cli Slack channel](https://openmainframeproject.slack.com/) to ask questions about Zowe CLI and Zowe SDKs, propose new ideas, and interact with the Zowe community.
+- You can join one of the [Zowe CLI squad meetings](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe) to discuss Zowe SDKs issues and contibute to Zowe SDKs.
+- Read a series of [blogs about Zowe](https://medium.com/zowe) on Medium to explore use cases, best practices, and more.
+- Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe).
diff --git a/docs/extend/extend-zowe-overview.md b/docs/extend/extend-zowe-overview.md
index 9dbb2adfd7..5942fa34e7 100644
--- a/docs/extend/extend-zowe-overview.md
+++ b/docs/extend/extend-zowe-overview.md
@@ -36,7 +36,7 @@ For more information about developing for Zowe Application Framework, see [Zowe
### Extend Zowe CLI
-Zowe CLI extenders can build plug-ins that provide new commands. Zowe CLI is built using Node.js and is typically run on a machine other than z/OS, such as a PC, where the CLI can be driven through a terminal or command prompt, or on an automation machine such as a DevOps pipeline orchestrator.
+Zowe CLI extenders can build plug-ins that provide new commands. Zowe CLI is built using Node.js and is typically run on a machine other than a mainframe, such as a PC, where the CLI can be driven through a terminal or command prompt, or on an automation machine such as a DevOps pipeline orchestrator.
For more information about extending the Zowe CLI, see [Developing a new plug-in](extend-cli/cli-developing-a-plugin.md). This article includes a sample plug-in that is provided with the tutorial; see [Installing the sample plug-in](extend-cli/cli-installing-sample-plugin.md).
diff --git a/docs/extend/k8s-extend.md b/docs/extend/k8s-extend.md
index d8a2232772..9fe2ef4153 100644
--- a/docs/extend/k8s-extend.md
+++ b/docs/extend/k8s-extend.md
@@ -18,8 +18,7 @@ An extension must have a container image to run in a Zowe container environment.
The core components define component Dockerfiles and use GitHub Actions to build images. For example,
-- `jobs-api` is a component which has built-in web service. To build the images, this component defines a Dockerfile at https://github.com/zowe/jobs/blob/v2.x/master/container/Dockerfile and defines a GitHub Actions workflow at https://github.com/zowe/jobs/tree/v2.x/master/.github/workflows.
-- `explorer-jes` is a Zowe App Server Framework plug-in but does not have a built-in web service. It follows Zowe's [container conformance criteria](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/containers/conformance.md). It defines a Dockerfile at https://github.com/zowe/explorer-jes/blob/v2.x/master/container/Dockerfile. Similar to `jobs-api`, it also defines a GitHub Actions workflow at https://github.com/zowe/explorer-jes/blob/v2.x/master/.github/workflows/build_test.yml to build the images.
+- `explorer-jes` is a Zowe App Server Framework plug-in but does not have a built-in web service. It follows Zowe's [container conformance criteria](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/containers/conformance.md). It defines a Dockerfile at https://github.com/zowe/explorer-jes/blob/v2.x/master/container/Dockerfile. It also defines a GitHub Actions workflow at https://github.com/zowe/explorer-jes/blob/v2.x/master/.github/workflows/build_test.yml to build the images.
The following GitHub Actions are used by the core components to build conformant images. They might not be completely reusable for you, but are provided as an example.
diff --git a/docs/extend/migrate-extensions.md b/docs/extend/migrate-extensions.md
index 65c71d362c..d6cadbc1bb 100644
--- a/docs/extend/migrate-extensions.md
+++ b/docs/extend/migrate-extensions.md
@@ -1,4 +1,4 @@
-# Migrating Zowe server component from V1 to V2
+# Migrating from Zowe V1 to Zowe V2
This doc guides you through migrating an existing Zowe server component from version 1 to version 2.
@@ -31,7 +31,7 @@ Review the following table for a detailed mapping of Zowe v1 and v2 variables.
| --- | --- | --- | --- |
| `APIML_ALLOW_ENCODED_SLASHES` | `components.gateway.apiml.service.allowEncodedSlashes` | `ZWE_components_gateway_apiml_service_allowEncodedSlashes` | |
| `APIML_CORS_ENABLED` | `components.gateway.apiml.service.corsEnabled` | `ZWE_components_gateway_apiml_service_corsEnabled` | |
-| `APIML_DEBUG_MODE_ENABLED` | `components.gateway.debug`, etc | `ZWE_components_gateway_debug`, etc | In v2, you can enable debug mode for APIML components separately. The `gateway` placeholder can be `discovery`, `api-catalog`, or `metrics-service`, and so on. |
+| `APIML_DEBUG_MODE_ENABLED` | `components.gateway.debug`, etc | `ZWE_components_gateway_debug`, etc | In v2, you can enable debug mode for APIML components separately. The `gateway` placeholder can be `discovery`, `api-catalog`, and so on. |
| `APIML_ENABLE_SSO` | Removed in v2 | Removed in v2 | |
| `APIML_GATEWAY_EXTERNAL_MAPPER` | `components.gateway.apiml.security.x509.externalMapperUrl` | `ZWE_components_gateway_apiml_security_x509_externalMapperUrl` | |
| `APIML_GATEWAY_INTERNAL_HOST` | Not configurable in v2 | Not configurable in v2 | |
@@ -48,12 +48,10 @@ Review the following table for a detailed mapping of Zowe v1 and v2 variables.
| `DISCOVERY_PORT` | `components.discovery.port` | `ZWE_components_discovery_port` | |
| `EXTERNAL_CERTIFICATE_AUTHORITIES` | `zowe.certificate.pem.certificateAuthorities` | `ZWE_zowe_certificate_pem_certificateAuthorities` | |
| `EXTERNAL_COMPONENTS` | Removed in v2 | Removed in v2 | Zowe v2 configuration does not distinguish core components and extensions on how to enable them. They use the same `components..enabled` configuration. |
-| `FILES_API_PORT` | `components.files-api.port` | `ZWE_components_files_api_port` | |
| `GATEWAY_PORT` | `components.gateway.port` | `ZWE_components_gateway_port` | |
| `INSTANCE_DIR` | Removed in v2 | `ZWE_zowe_workspaceDirectory` or `ZWE_zowe_logDirectory` | The instance directory is split into workspace and logs directory in v2. |
| `JAVA_HOME` | `java.home` | `JAVA_HOME` | |
| `JES_EXPLORER_UI_PORT` | Removed in v2 | Removed in v2 | In v2, explorer-jes reuses the web server provided by App Server. It does not start independent web server. |
-| `JOBS_API_PORT` | `components.jobs-api.port` | `ZWE_components_jobs_api_port` | |
| `KEY_ALIAS` | `zowe.certificate.keystore.alias` | `ZWE_zowe_certificate_keystore_alias` | |
| `KEYSTORE_CERTIFICATE_AUTHORITY` | `zowe.certificate.pem.certificateAuthorities` | `ZWE_zowe_certificate_pem_certificateAuthorities` | |
| `KEYSTORE_CERTIFICATE` | `zowe.certificate.pem.certificate` | `ZWE_zowe_certificate_pem_certificate` | |
diff --git a/docs/extend/packaging-zos-extensions.md b/docs/extend/packaging-zos-extensions.md
index b180f78d18..78a85168c8 100644
--- a/docs/extend/packaging-zos-extensions.md
+++ b/docs/extend/packaging-zos-extensions.md
@@ -4,7 +4,7 @@ You can extend Zowe in multiple ways. You may extend Zowe with microservices, wh
Before you start, review the following terms:
-- **component**:
+- **component**
Component refers to the most generic way to describe a program which can work within Zowe. It can be a microservice, a Zowe App Framework plug-in, or even just a shared program to be used by other Zowe components. This is also the generic word when referring to both Zowe core components and extensions. In most of the cases described in this topic, this terminology does not include programs running on the client side, like Zowe CLI plug-in or Zowe Explorer (VSCode extension).
- **extension**
@@ -15,7 +15,7 @@ Before you start, review the following terms:
You can package Zowe components (extensions) into various formats. You can package them as a stand-alone PAX, ZIP, or TAR file. You can also bundle and ship your Zowe extension(s) within another product.
-A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists of the following files and directories:
+A typical component package consists of the following files and directories:
```
+-- manifest.yaml
@@ -23,7 +23,7 @@ A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists
|-- schema.json
|-- bin/
|-- configure.sh
- |-- jobs-api-server-1.0.4-boot.jar
+ |-- component-1.0.0-boot.jar
|-- start.sh
|-- validate.sh
```
@@ -39,7 +39,8 @@ A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists
- `apiml-static-registration.yaml.template`
- Refers to a supporting file that instructs the Zowe launch script how to register this extension service to the API Mediation Layer Discovery service. In this case, this file is referred in the `manifest.yaml` `apimlServices.static[0].file` field. This file is optional depending on the function of the component and you can change and customize the file name in the manifest file.
+ Refers to a supporting file that instructs the Zowe launch script how to register this extension service to the API Mediation Layer Discovery service. In this case, this file is referred in the `manifest.yaml` `apimlServices.static[0].file` field. This file is optional depending on the function of the component. You can change and customize the file name in the manifest file.
+
- `bin/(configure|start|validate).sh`
This file contains the Zowe component lifecycle scripts. You may not need these files depending on the function of the component. You can find detailed definition of lifecycle scripts in [Zowe component runtime lifecycle](lifecycling-with-zwesvstc.md#zowe-component-runtime-lifecycle).
@@ -49,6 +50,7 @@ It is also suggested that you put the following files into the package:
- `README.md`
This file is a brief introduction to your extension in Markdown format, including how it should be installed, configured, verified, and so on.
+
- `LICENSE`
This is the full license text file.
@@ -77,6 +79,5 @@ Zowe extensions, as well as core components, can use a manifest file to describe
For examples of manifests thoughout Zowe GitHub repositories, see the following links:
- [API Catalog manifest.yaml](https://github.com/zowe/api-layer/blob/v2.x.x/api-catalog-package/src/main/resources/manifest.yaml)
-- [Jobs API manifest.yaml](https://github.com/zowe/jobs/blob/v2.x/master/jobs-zowe-server-package/src/main/resources/manifest.yaml)
- [Sample Node API and API Catalog extension manifest.yaml](https://github.com/zowe/sample-node-api/blob/master/manifest.yaml)
- [Sample Zowe App Framework extension manifest.yaml](https://github.com/zowe/sample-trial-app/blob/master/manifest.yaml)
diff --git a/docs/extend/server-schemas.md b/docs/extend/server-schemas.md
index eee8d60312..c455b041c6 100644
--- a/docs/extend/server-schemas.md
+++ b/docs/extend/server-schemas.md
@@ -1,6 +1,6 @@
# Server component schemas
-Starting with Zowe v2.0, each Component in Zowe must contain a [json schema](https://json-schema.org/) describing the configuration parameters that are valid for its component section in Zowe's server configuration. If a component does not have anything that can be configured, this file can just be boilerplate specifying that it fully inherits generic Component parameters and nothing more.
+Each Component in Zowe must contain a [json schema](https://json-schema.org/) describing the configuration parameters that are valid for its component section in Zowe's server configuration. If a component does not have anything that can be configured, this file can just be boilerplate specifying that it fully inherits generic Component parameters and nothing more.
The server infrastructure will utilize each components' schema files to validate a Zowe instance configuration every startup, so this requirement is enforced by code.
diff --git a/docs/extend/zowe-conformance-program.md b/docs/extend/zowe-conformance-program.md
index 350b975d3f..e75198dcb0 100644
--- a/docs/extend/zowe-conformance-program.md
+++ b/docs/extend/zowe-conformance-program.md
@@ -8,6 +8,13 @@ Conformance provides Independent Software Vendors (ISVs), System Integrators (SI
As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe, you are encouraged to get certified today.
+
+:::info find out more
+
+The [Zowe Conformance Program Explained](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) blog on Medium.com describes the conformance program in more detail.
+
+:::
+
## How to participate
To participate in the Zowe Conformance Program, follow the process on the [Zowe Conformance Program website](https://openmainframeproject.org/our-projects/zowe-conformance-program/). You can also find a list of products that have earned Zowe Conformant status.
diff --git a/docs/getting-started/ZE-system-reqs.md b/docs/getting-started/ZE-system-reqs.md
index d78c252936..d7a6c24dde 100644
--- a/docs/getting-started/ZE-system-reqs.md
+++ b/docs/getting-started/ZE-system-reqs.md
@@ -1,35 +1,44 @@
-# Zowe Explorer System Requirements
+# Zowe Explorer system requirements
Before installing Zowe Explorer, make sure that you meet the following requirements.
+:::info Required roles: systems administrator, devops architect
+:::
+
## Client side requirements
### Operating systems
+- macOS
+
+ :::note
+
+ Only Mac operating system versions supported by Apple.
-- MacOS 10.15 (Catalina), 11 (Big Sur), 12 (Monterey)
+ :::
- Unix-like:
- [CentOS](https://www.centos.org/) 8+
- [RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 8+
- [Ubuntu](https://ubuntu.com/) 20.04+
- Windows 10+
-### Integrated development environments:
+### Integrated development environments:
+
+- [Red Hat CodeReady Workspaces](https://www.redhat.com/en/technologies/jboss-middleware/codeready-workspaces)
+
+ :::note
-- [VS Code](https://code.visualstudio.com/) 1.53.2+
-- [Eclipse Che](https://www.eclipse.org/che/)
-- [Red Hat CodeReady Workspaces](https://www.redhat.com/en/technologies/jboss-middleware/codeready-workspaces)
-- [Theia](https://theia-ide.org/) 1.18+
+ Secure credentials are not supported in Red Hat CodeReady Workspaces as the keyring is not unlocked by default. However, you can use the [Kubernetes Secrets plug-in for Zowe CLI and Zowe Explorer](https://github.com/zowe/zowe-cli-secrets-for-kubernetes/blob/main/README.md) as an alternative, or you can create your own [Custom Credential Managers in Zowe Explorer and Zowe CLI](https://medium.com/zowe/custom-credential-managers-in-zowe-explorer-b37faeee4c29).
- - Zowe Explorer is compatible with Theia 1.18.0 or higher. However, we recommend using a [Theia community release](https://theia-ide.org/releases/) as Zowe Explorer could experience possible unexpected behaviors with the latest Theia releases.
+ :::
+- [VS Code](https://code.visualstudio.com/) 1.79.0+
## Server side requirements
- IBM z/OSMF is configured and running.
- - Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can run Zowe Explorer successfully.
- - z/OSMF enables the core capabilities, such as retrieving data sets, executing TSO commands, submitting jobs, and more.
+ - See [z/OSMF REST services for Zowe clients](../user-guide/systemrequirements-zosmf.md#zosmf-rest-services-for-zowe-clients) for a list of services that need configuration.
- Applicable plug-in services are configured and running on the mainframe.
- Plug-ins communicate with various mainframe services. The services must be configured and running on the mainframe before issuing plug-in commands.
- * See [Zowe Explorer CICS Extension system requirements](../user-guide/ze-using-zowe-explorer-cics-ext#system-requirements).
- * See [Zowe Explorer FTP Extension system requirements](../user-guide/ze-ftp-using-ze-ftp-ext#system-requirements).
+ * See [Zowe Explorer CICS Extension system requirements](./install-ze-extensions.md#zowe-explorer-cics-extension-system-requirements).
+ * See [Zowe Explorer FTP Extension system requirements](./install-ze-extensions.md#zowe-explorer-ftp-extension-system-requirements).
diff --git a/docs/getting-started/cli-getting-started.md b/docs/getting-started/cli-getting-started.md
index 55d60e748a..6cd4d64b49 100644
--- a/docs/getting-started/cli-getting-started.md
+++ b/docs/getting-started/cli-getting-started.md
@@ -25,7 +25,7 @@ npm install -g @zowe/cli@zowe-v2-lts
### Installing CLI plug-ins
```
-zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/ims-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts
+zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts
```
The command installs most open-source plug-ins, but the IBM Db2 plug-in requires [additional configuration to install](../user-guide/cli-db2plugin.md#installing).
diff --git a/docs/getting-started/install-ze-extensions.md b/docs/getting-started/install-ze-extensions.md
new file mode 100644
index 0000000000..542c6b19d7
--- /dev/null
+++ b/docs/getting-started/install-ze-extensions.md
@@ -0,0 +1,34 @@
+# Installing Zowe Explorer extensions
+
+To successfully install Zowe Explorer extensions, meet the following system requirements.
+
+## Zowe Explorer CICS Extension system requirements
+
+### Client side requirements
+
+- [Visual Studio Code](https://code.visualstudio.com/download)
+- [Zowe Explorer V3](../user-guide/ze-install#installing-zowe-explorer)
+
+### Server side requirements
+
+The following services must be installed, configured, and running on the mainframe:
+
+- CICS Management Client Interface (CMCI) APIs
+- z/OSMF (optional but recommended)
+
+## Zowe Explorer FTP Extension system requirements
+
+### Client side requirements
+
+- [Visual Studio Code](https://code.visualstudio.com/download)
+- [Zowe Explorer V3](../user-guide/ze-install#installing-zowe-explorer)
+
+### Server side requirements
+
+- Ensure that you can obtain remote access to a z/OS FTP service before using the extension.
+
+- Some functionality within the FTP extension requires the FTP server on the mainframe to be configured with the `JESINTERFACELevel` parameter set to `2`. For more information, see the [JESINTERFACELEVEL (FTP server) statement](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-jesinterfacelevel-ftp-server-statement).
+
+ The `JESINTERFACELevel` parameter can be found in multiple locations within the mainframe, depending on your site's security policies.
+
+ Contact your system administrator to determine if your FTP server is configured with the correct `JESINTERFACELevel`. For more information, see [FTP configuration statements in FTP.DATA](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-ftp-configuration-statements-in-ftpdata).
\ No newline at end of file
diff --git a/docs/getting-started/install-zowe-sdks.md b/docs/getting-started/install-zowe-sdks.md
new file mode 100644
index 0000000000..8311a615e4
--- /dev/null
+++ b/docs/getting-started/install-zowe-sdks.md
@@ -0,0 +1,140 @@
+# Zowe SDKs installation
+
+Leverage the Zowe Client Software Development Kits (SDKs) to build client applications and scripts that interface with the mainframe.
+
+The SDKs include programmatic APIs, each of which performs a particular mainframe task. For example, one API package provides the ability to upload and download z/OS data sets. You can leverage that package to rapidly build a client application that interacts with data sets.
+
+The following SDKs are available.
+- Zowe Client Java SDK
+- Zowe Client Kotlin SDK
+- Zowe Client Node.js SDK
+- Zowe Client Python SDK *technical preview*
+
+## Fundamentals
+
+- New to Zowe Client SDKs? This [Zowe Client SDK overview](overview.md#zowe-client-software-development-kits-sdks) briefly introduces the SDKs.
+
+- The blog [Zowe SDKs - Build z/OS Connected Applications Faster](https://medium.com/zowe/zowe-sdks-build-z-os-connected-applications-faster-b786ba7bb0d9) introduces Zowe SDKs and their benefits.
+
+## SDK documentation
+
+For detailed SDK documentation, see the following:
+- [Zowe Client Java SDK](https://github.com/Zowe-Java-SDK)
+- [Zowe Client Kotlin SDK](https://zowe.github.io/zowe-client-kotlin-sdk/)
+- [Zowe Client Node.js SDK](https://docs.zowe.org/stable/typedoc/index.html)
+- [Zowe Client Python SDK](https://zowe-client-python-sdk.readthedocs.io/en/latest/) *technical preview*
+- [Zowe SDK Sample Scripts](https://github.com/zowe/zowe-sdk-sample-scripts/)
+
+## SDK software requirements and dependencies
+
+### Java SDK
+
+Requires Java Runtime Environment (JRE) 17.
+
+To install this library in your project, use a build tool such as Maven, Gradle, or Ant. Get the necessary artifacts from the [Java SDK repository](https://mvnrepository.com/artifact/org.zowe.client.java.sdk/zowe-client-java-sdk).
+
+If you add the Java SDK as a dependency to your project, Maven or Gradle automatically downloads any additional dependencies needed to use the SDK.
+
+For a Maven project, add the SDK as a dependency by updating the `pom.xml` file:
+
+```
+
+ org.zowe.client.java.sdk
+ zowe-client-java-sdk
+ 2.2.0
+
+```
+
+For a Gradle project, add the SDK as a dependency by updating the `build.gradle` file:
+
+```
+implementation group: 'org.zowe.client.java.sdk', name: 'zowe-client-java-sdk', version: '2.2.0'
+```
+
+### Kotlin SDK
+
+Requires Java Runtime Environment (JRE) 17.
+
+For detailed information about how to install the library, refer to [the official installation guide for Zowe Client Kotlin SDK](https://zowe.github.io/zowe-client-kotlin-sdk/#installation)
+
+### Node.js
+
+If you install Node SDK packages from the [online registry](#installing-an-sdk-from-an-online-registry), the required dependencies are installed automatically.
+
+If you download Node SDK packages from Zowe.org, the downloaded folder contains dependencies that you must install manually. Extract the `TGZ` files from the folder, copy the files to your project, and issue the following commands to install the dependencies:
+
+```
+npm install imperative.tgz
+```
+
+```
+npm install core-for-zowe-sdk.tgz
+```
+
+### Python SDK *technical preview*
+
+If you install Python SDK packages from the [online registry](#installing-an-sdk-from-an-online-registry), the required dependencies are installed automatically.
+
+If you download the Python SDK packages from Zowe.org, the downloaded folder contains dependencies that you must install manually. Extract the `WHL` files from the folder, copy the files to your project, and issue the following command for each dependency:
+
+```
+pip install .whl
+```
+
+## Installing a Zowe Client SDK
+
+To get started, import the SDK package to your project. You can pull the packages from an online registry, or download the packages from Zowe.org to install locally.
+
+### Installing an SDK from an online registry
+
+Pull the packages from an online registry such as npm or PyPi:
+
+1. In command-line window, navigate to your project directory. Issue the following command to install a package from the registry:
+
+ - To import a Node.js package: `npm install `
+ - To import a Python package: `pip install `
+
+ - ``
+ The name of the SDK package that you want to install, such as `zos-files-for-zowe-sdk`.
+
+ The package is installed.
+
+ - Node packages are defined in `package.json` in your project.
+ - Python packages are installed by default to `$PYTHONPATH/Lib/site-packages` (Linux) or to the Python folder in your local `/AppData` folder (Windows).
+ - For the Java and Kotlin SDKs, Maven puts libraries in the `~/.m2/repository` directory and Gradle puts libraries in the `~/.gradle/caches/modules-2/files-2.1` directory, where `~` represents the path to the user's home directory.
+
+2. **(Optional)** You might want to automatically update the SDK version when updates become available, or you might want to prevent automatic updates.
+
+ - To define the versioning scheme for Node packages, use [semantic versioning](https://docs.npmjs.com/about-semantic-versioning).
+
+ - To define versioning for Python packages, specify versions or version ranges in a `requirements.txt` file checked-in to your project. For more information, see [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) in the pip documentation.
+
+ - To define versioning for Python packages, specify versions or version ranges in the `pom.xml` or `build.gradle` files checked-in to your project.
+
+ - In Maven, versioning ranges can be [specified in the `pom.xml` file](https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution#DependencyMediationandConflictResolution-DependencyVersionRanges).
+
+ - In Gradle, versioning ranges can be [specified in the `build.gradle` file](https://docs.gradle.org/current/userguide/single_versions.html).
+
+### Installing an SDK from a local package
+
+Download and install the packages:
+
+1. Navigate to [Zowe.org Downloads](https://www.zowe.org/download.html). Select your desired programming language in the **Zowe Client SDKs** section.
+
+ The SDK is downloaded to your computer.
+
+2. Unzip the SDK folder, which contains the packages for each set of functionality (such as z/OS Jobs). Copy each file that you want to install and paste them into your project directory.
+
+3. Install required dependencies, which are included in the bundle. See [Software requirements and dependencies](#sdk-software-requirements-and-dependencies) for more information.
+
+4. In a command-line window, navigate to your project directory. Issue *one* of the following commands.
+
+ - To install a Node.js package: `npm install .tgz`
+ - To install a Python package: `pip install .whl`
+
+ -``
+ The name of the package that you want to install, such as `zos-files-for-zowe-sdk`.
+
+5. Repeat the command for each package that you need.
+
+ Packages are now installed.
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index 16312abb8e..baaec03aaa 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -51,11 +51,7 @@ API ML consists of these core components: the API Gateway, the Discovery Service
- The API Gateway provides secure routing of API requests from clients to registered API services.
- The Discovery Service allows dynamic registration of microservices and enables their discoverability and status updates.
- The API Catalog provides a user-friendly interface to view and try out all registered services, read their associated APIs documentation in OpenAPI/Swagger format.
-- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data in-memory or using Redis, or VSAM storage.
-
-Core Zowe also provides out of the box services for working with MVS Data Sets, JES, as well as working with z/OSMF REST APIs.
-
-**Note:** The MVS datasets and JES services are deprecated and will not be available in Zowe V3.
+- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data using various backends. Recommended is usage of Inifinispan packaged with the Caching Service.
The API Mediation Layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and API documentation.
@@ -68,7 +64,7 @@ The API Mediation Layer offers enterprise, cloud-like features such as high-avai
* High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind.
* Caching Service: This feature is designed for Zowe components in a high availability configuration, and supports high availability of all components within Zowe. As such, components can remain stateless whereby the state of the component is offloaded to a location accessible by all instances of the service, including those which just started.
* Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration.
-* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility.
+* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner.
* Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services.
#### API Mediation Layer structural architecture
@@ -79,37 +75,39 @@ The following diagram illustrates the single point of access through the Gateway
#### Components
The API Layer consists of the following key components:
-**API Gateway**
+**Gateway Service**
-Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL. Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway is built using Netflix Zuul and Spring Boot technologies.
+Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API
+client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL.
+Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances
+can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway Service is built on Spring
+Cloud Gateway and Spring Boot technology.
**Discovery Service**
-The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology.
-
-**Discovery Service TLS/SSL**
-
-HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables heightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered.
+The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service
+continuously collects and aggregates service information and serves as a repository of active services. When a service is
+started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service.
+Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are
+available to help with service on-boarding of various application architectures including plain Java applications and
+Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology.
**API Catalog**
-The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability.
-
-**Catalog Security**
-
-Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the z/OSMF API.
+The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both
+the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component
+to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service
+instances, which provide exactly the same service for high-availability or scalability. API Catalog requires authentication
+from the accessing user.
**Caching Service**
-An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated with keys. The service can only be used by internal Zowe services and is not exposed to the internet.
-
-**Metrics Service (Technical Preview)**
-
-The Metrics Service provides a web user interface to visualize requests to API Mediation Layer services. HTTP metrics such as number of requests and error rates are displayed for
-each API Mediation Layer service. This service is currently in technical preview and is not ready for production.
+An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated
+with keys.
#### Onboarding APIs
-Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics to discover more about adding new APIs to the API Mediation Layer and using the API Catalog:
+Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics
+to learn more about adding new APIs to the API Mediation Layer and using the API Catalog:
* [Onboarding Overview](../extend/extend-apiml/onboard-overview.md)
* [Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer](../extend/extend-apiml/onboard-spring-boot-enabler.md)
@@ -216,6 +214,7 @@ The Zowe Client SDKs consist of programmatic APIs that you can use to build clie
- Zowe Node.js Client SDK
- Zowe Java Client SDK
+- Zowe Kotlin Client SDK
- Zowe Python Client SDK
For more information, see [Using the Zowe SDKs](../user-guide/sdks-using.md).
@@ -270,21 +269,21 @@ ZEBRA Provides re-usable and industry compliant JSON formatted RMF/SMF data reco
For more information, see the [ZEBRA documentation](https://github.com/zowe/zebra/tree/main/Documentation).
-### Zowe IntelliJ Plug-in
+### Zowe Explorer plug-in for IntelliJ IDEA
-Zowe IntelliJ plug-in for Intellij-based IDEs is a smart and interactive mainframe code editing tool that allows you to browse, edit, and create data on z/OS via z/OSMF REST API.
+Zowe Explorer plug-in for IntelliJ IDEA is a smart and interactive mainframe code editing tool that allows you to browse, edit, and create data on z/OS via z/OSMF REST API.
-Zowe IntelliJ plug-in helps you to:
-- Start working with z/OS easily with no complex configurations.
-- Organize datasets on z/OS, files on USS into working sets.
-- Allocate datasets, create members, files and directories with different permissions.
-- Perform operations like renaming, copying and moving data in a modern way.
-- Edit datasets, files and members. Smart auto-save keeps your content both in the editor and on the mainframe in-sync.
-- Create multiple connections to different z/OS systems.
-- Perform all available operations with jobs.
-- Highlight all IntelliJ supported languages automatically and recognize them once opened from the mainframe.
+The plug-in helps to:
+- Start working with z/OS easily with no complex configurations
+- Organize data sets on z/OS, files on USS into working sets
+- Allocate data sets, create members, files and directories with different permissions
+- Perform operations like renaming, copying and moving data in a modern way
+- Edit data sets, files and members. Smart auto-save keeps your content both in the editor and on the mainframe in sync
+- Create multiple connections to different z/OS systems
+- Perform all available operations with jobs
+- Work with TSO Console directly in the IDE
-For more information, see [Using Zowe IntelliJ plug-in](../user-guide/intellij-using.md).
+To learn more about the plug-in, you can start with [Zowe Explorer plug-in for IntelliJ IDEA use cases](../user-guide/intellij-use-cases.md).
## Zowe Bill of Materials
diff --git a/docs/getting-started/user-roadmap-apiml.md b/docs/getting-started/user-roadmap-apiml.md
index e61b37c5cc..54e19c4bb6 100644
--- a/docs/getting-started/user-roadmap-apiml.md
+++ b/docs/getting-started/user-roadmap-apiml.md
@@ -42,13 +42,9 @@ The following definition of skill levels about Zowe assist you with gathering th
- **Configuring API Mediation Layer**
- - [Configuring the Zowe APIs](../user-guide/configure-data-sets-jobs-api.md)
-
- This article explains how to configure security for the Zowe API Mediation Layer.
-
- - [Advanced Gateway features configuration](../user-guide/advanced-apiml-configuration.md)
+ - [Advanced API Mediation Layer features configuration](../user-guide/advanced-apiml-configuration.md)
- This article is for system programmers who want to configure advanced Gateway features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced Gateway features.
+ This article is for system programmers who want to configure advanced features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced features.
## Using Zowe API Mediation Layer
@@ -102,7 +98,8 @@ The following definition of skill levels about Zowe assist you with gathering th
This blog takes a deeper dive into the SSO feature of API ML.
-- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579)
+- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579)
+- [**Blog: CLI and Client Certificates](https://medium.com/zowe/zowe-cli-and-client-certificates-dae341f8f52a)
## Contributing to Zowe API Mediation Layer
diff --git a/docs/getting-started/user-roadmap-client-sdk.md b/docs/getting-started/user-roadmap-client-sdk.md
index 505e3458de..45c87525e2 100644
--- a/docs/getting-started/user-roadmap-client-sdk.md
+++ b/docs/getting-started/user-roadmap-client-sdk.md
@@ -2,84 +2,12 @@
This roadmap outlines information resources that are applicable to the various user roles who are interested in Zowe Client Software Development Kits (SDKs) which is a Zowe component still under development. These resources provide information about various subject areas, such as learning basic skills, installation, developing, and troubleshooting for Zowe Client SDKs.
-The following definition of skill levels about Zowe will help you gather most relevant resources for you.
-
-* Beginner: You are starting out and want to learn the fundamentals.
-* Intermediate: You have some experience but want to learn more in-depth skills.
-* Advanced: You have lots of experience and are looking to learn about specialized topics.
-
-## Fundamentals
-
-> Zowe skill level: Beginner
-
-- [**Zowe Client SDK overview**](overview.md#zowe-client-software-development-kits-sdks)
-
- New to Zowe Client SDKs? This overview topic briefly introduces what the SDK is.
-
-- [**Blog: Zowe SDKs - Build z/OS Connected Applications Faster**](https://medium.com/zowe/zowe-sdks-build-z-os-connected-applications-faster-b786ba7bb0d9)
-
- This blog introduces Zowe SDKs and their benefits.
-
-## Installing
-
-> Zowe skill level: Beginner
-
-- [**System requirements**](../user-guide/sdks-using.md#software-requirements)
-
- Review this topic to ensure that your system meets the requirements for installing Zowe Client SDKs.
-
-- [**Installing Zowe SDK**](../user-guide/sdks-using.md#getting-started)
-
- Follow the steps to install Zowe SDKs. You can pull the packages from an online registry, or download the packages from Zowe.org to install locally.
-
-## Using Zowe Client SDKs
-
-> Zowe skill level: Intermediate
-
-### Zowe Node.js SDK
-
-- [**Using Zowe Node.js SDKs**](../user-guide/sdks-using.md#using---nodejs)
-
- This information provides links to different pakcage Readmes that describes how to use the Zowe Node SDK.
-
-- **Docs: Node.js SDK reference guide**
-
- Refer to the following Zowe Client SDK reference guides for information about the API endpoints:
- - **[Browse Node SDK reference guide online](https://docs.zowe.org/stable/typedoc/index.html)**
- - **[Download SDK reference guide in ZIP format](https://docs.zowe.org/stable/zowe-nodejs-sdk-typedoc.zip)**
-
-- [**Zowe SDK Sample Scripts**](https://github.com/zowe/zowe-sdk-sample-scripts/)
-
- This repository contains some sample scripts that utilize various components of the Zowe SDKs organized by use cases.
-
-### Zowe Python SDK
-
-- [**Using Zowe Python SDKs**](https://zowe-client-python-sdk.readthedocs.io/en/latest/)
-
- This information provides links to different pakcage Readmes that describes how to use the Zowe Python SDK.
-
-- **Docs: Python SDK reference guide**
-
- Refer to the following Zowe Client SDK reference guides for information about the API endpoints:
- - **[Browse Python SDK reference guide online](https://zowe-client-python-sdk.readthedocs.io/en/latest/index.html)**
- - **[Download SDK reference guide in PDF format](https://zowe-client-python-sdk.readthedocs.io/_/downloads/en/latest/pdf/)**
-
-
-## Contributing to Zowe Client SDKs
-
-> Zowe skill level: Advanced
-
-- [**Contributing guidelines**](https://github.com/zowe/zowe-cli/blob/master/docs/SDKGuidelines.md)
-
- This document is a summary of guidelines for development within Zowe SDKs. You can contribute to add features, enhancements, and bug fixes to the source code.
-
## Troubleshooting and support
-- [**Sumit an issue**](https://github.com/zowe/zowe-cli/issues/new)
+- [**Submit an issue**](https://github.com/zowe/zowe-cli/issues/new/choose)
If you have an issue that is specific to Zowe SDKs, you can submit an issue against the `zowe-cli` repo.
-
## Community resources
- [**Slack channel**](https://openmainframeproject.slack.com/)
diff --git a/docs/getting-started/user-roadmap-zowe-explorer.md b/docs/getting-started/user-roadmap-zowe-explorer.md
index 733b3ab950..68ccef5902 100644
--- a/docs/getting-started/user-roadmap-zowe-explorer.md
+++ b/docs/getting-started/user-roadmap-zowe-explorer.md
@@ -1,106 +1,54 @@
-# Zowe Explorer
+# Installing Zowe Explorer
-The resources here provide information about various Zowe Explorer subject areas, such as learning basic skills, installation, developing, and troubleshooting.
+The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs.
-:::tip
+For a better understanding of Zowe Explorer, review the various reference materials that document the VS Code extension.
-To identify the resources most relevant for you, use the following definitions of Zowe Explorer skill levels.
+## About Zowe Explorer
-* Beginner: You're starting out and want to learn the fundamentals.
-* Intermediate: You have some experience but want to learn more in-depth skills.
-* Advanced: You have lots of experience and are looking to learn about specialized topics.
-:::
+- Check out [**Zowe release notes**](../whats-new/release-notes/release-notes-overview.md) to learn about the latest Zowe Explorer updates.
-## Fundamentals
-
-> Zowe skill level: Beginner
-
-* [**Zowe Explorer overview**](../user-guide/ze-install.md)
-
- New to Zowe Explorer? This overview topic introduces the key features, main components, and benefits of Zowe Explorer.
-
-* [**Zowe Explorer FAQs**](../getting-started/zowe_faq.md#zowe-explorer-faq)
-
- If you have a question, review the FAQ, which answers the most commonly asked questions about Zowe Explorer.
-
-* [**Blog: Visual Studio Code for Mainframe Via the Zowe Explorer Extension**](https://medium.com/zowe/visual-studio-code-for-mainframe-via-the-zowe-explorer-extension-b679054ffaf7)
-
- This Medium article outlines the basics of Zowe Explorer, including Getting Started videos.
+- If you have a question, review the [**Zowe Explorer FAQs**](../getting-started/zowe_faq.md#zowe-explorer-faq), which answer the most commonly asked questions about Zowe Explorer.
## Installing and configuring
-> Zowe skill level: Beginner
-
-* [**Installing Zowe Explorer**](../user-guide/ze-install.md#installing-zowe-explorer)
-
- This page includes the system requirements and steps for installing the Zowe Explorer.
-
-* [**Video: Getting started with Zowe Explorer (Part 1)**](https://youtu.be/G_WCsFZIWt4)
-* [**Video: Getting started with Zowe Explorer (Part 2)**](https://youtu.be/X4oSHrI4oN4)
-
- These videos help you to get started with Zowe Explorer and show the basic data set use cases.
-
-* [**Zowe Explorer Profiles**](../user-guide/ze-profiles.md)
+- Review the system requirements and steps for installing the Zowe Explorer in [**Installing Zowe Explorer**](../user-guide/ze-install.md).
- This page describes how to create and work with Zowe Explorer profiles. Having a profile enables you to use all functions of the extension, activate the Secure Credential Store plug-in to securely store credentials, and more.
+- Learn how to create and work with [**Zowe Explorer profiles**](../user-guide/ze-profiles.md). A profile enables you to connect to services running on a mainframe, integrate with the API Mediation Layer, and more.
-## Using Zowe Explorer
+## Getting the most out of Zowe Explorer
-> Zowe skill level: Intermediate
+- Review [**Using Zowe Explorer**](../user-guide/ze-usage.md) to go over how to use Zowe Explorer in a remote environment and managing credentials.
-* [**Using Zowe Explorer**](../user-guide/ze-usage.md)
+* Learn how to [**extend Zowe Explorer**](https://github.com/zowe/vscode-extension-for-zowe/wiki/Extending-Zowe-Explorer) to introduce new functionalities.
- This page includes usage tips and sample use cases for data sets, USS files, JOBs, and TSO commands. Familiarize yourself with the extension and make the best use of available options and features.
+- Add CICS functionality and the FTP protocol to the Zowe Explorer VS Code extension with the [**Zowe Explorer CICS Extension**](../user-guide/ze-using-zowe-explorer-cics-ext.md) and the [**Zowe Explorer FTP Extension**](../user-guide/ze-ftp-install-ze-ftp-ext.md).
-## Extending Zowe Explorer
+- Check out the [**Zowe Explorer GitHub repository**](https://github.com/zowe/vscode-extension-for-zowe#readme) to view the source code for Zowe Explorer and other Zowe Explorer-related extensions.
-> Zowe skill level: Advanced
+- Watch the following videos to learn how to get started with Zowe Explorer, and work with data sets:
-* [**Extend Zowe Explorer**](https://github.com/zowe/zowe-explorer-vscode/wiki/Extending-Zowe-Explorer)
+
- Learn how to create extensions for Zowe Explorer to introduce new functionalities.
-
-- [**Zowe Explorer CICS Extension**](../user-guide/ze-using-zowe-explorer-cics-ext.md)
-
- Learn how to install the CICS extension. The extension adds CICS functionality to the Visual Studio Code extension, which lets you interact with CICS regions and programs.
-
-* [**Zowe Explorer FTP Extension**](../user-guide/ze-ftp.md)
-
- Learn how to install and use the FTP extension. The extension adds the FTP protocol to the Zowe Explorer VS Code extension, which lets use z/OS FTP Plug-in for Zowe CLI profiles to connect and interact with z/OS USS.
-
-* [**Zowe Explorer repository**](https://github.com/zowe/zowe-explorer-vscode)
-
- The GitHub repository of contains the source code of Zowe Explorer and other Zowe Explorer-related extensions. Check out the landing page README in the repository to find out how to contribute to the extension.
-
-* [**Developing for Eclipse Theia**](https://github.com/zowe/zowe-explorer-vscode/wiki/Developing-for-Theia)
-
- This article contains information on how to develop for Eclipse Theia.
+
## Contributing to Zowe Explorer
-> Zowe skill level: Advanced
-
-* [**Contributing guidelines**](https://github.com/zowe/zowe-explorer-vscode/blob/master/CONTRIBUTING.md)
-
- This document is intended to be a living summary of conventions & best practices for development of the Visual Studio Code Extension for Zowe.
-
-* [**Conformance Program**](../extend/zowe-conformance-program.md)
-
- This topic introduces the Zowe Conformance Program. Conformance provides Independent Software Vendors (ISVs), System Integrators (SIs), and end users greater confidence that their software will behave as expected. As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe CLI, you are encouraged to get certified today.
+- Review the [**Contribution Guidelines**](https://github.com/zowe/vscode-extension-for-zowe/blob/master/CONTRIBUTING.md) for a summary of conventions and best practices for development of the Visual Studio Code Extension for Zowe.
-* [**Blog: Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea)
+## Zowe Explorer community resources
- This Medium article provide more details about the Conformance Program, including useful references.
+The Zowe ecosystem is more than a collection of applications and extensions. An entire community exists to work on enhancements, help answer questions, and discuss plans for the future of the open source project.
-## Troubleshooting and support
+- Join the [**#zowe-explorer-vscode**](https://app.slack.com/client/T1BAJVCTY/CUVE37Z5F) Slack channel to ask questions, propose new ideas, and interact with the Zowe community.
-* [**Troubleshooting Zowe Explorer**](../troubleshoot/ze/troubleshoot-ze.md)
+- You can join **Zowe Explorer squad meetings** to get involved. The meeting schedule is posted in the [Zowe calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe).
- Learn about the tools and techniques that are available to help you troubleshoot and resolve problems. You can also find the list of Zowe Explorer issues.
+- Read informative [**blog posts about Zowe**](https://medium.com/zowe) on Medium to explore use cases, best practices, and more.
-* [**Submit an issue**](https://github.com/zowe/zowe-explorer-vscode/issues)
+- **Discuss Zowe topics** in the [Open Mainframe Project community forums](https://community.openmainframeproject.org/c/zowe).
- If you have an issue that is specific to Zowe Explorer, you can submit an issue against the `vscode-extension-for-zowe` repository.
+- If you have an issue that is specific to Zowe Explorer, you can [**submit an issue**](https://github.com/zowe/zowe-explorer-vscode/issues/new/choose) in the `zowe-explorer-vscode` repository on GitHub.
## Community resources
diff --git a/docs/getting-started/zowe-architecture.md b/docs/getting-started/zowe-architecture.md
index 499269c73f..107e5bb266 100644
--- a/docs/getting-started/zowe-architecture.md
+++ b/docs/getting-started/zowe-architecture.md
@@ -31,10 +31,6 @@ The configuration entries of each LPAR in the `zowe.yaml` file control which com
The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex, are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so that each instance behaves similarly to the user irrespective of where their request is routed.
-For simplification of the preceding diagram, the Jobs and Files API servers are not shown as being started. If the user defines Jobs and Files API servers to be started in the `zowe.yaml` configuration file, these servers behave the same as the servers illustrated. In other words, these services register to their API discovery server which then communicates with other discovery servers on other Zowe instances on either the same or other LPARs. The API traffic received by any API Gateway on any Zowe instance is routed to any of the Jobs or Files API components that are available.
-
-To learn more about Zowe with high availability enablement, see [Configuring Sysplex for high availability](../user-guide/configure-sysplex.md).
-
## Zowe architecture when running in Kubernetes cluster
The following diagram illustrates the difference in locations of Zowe components when deploying Zowe into a Kubernetes cluster as opposed to running all components on a single z/OS system.
@@ -77,7 +73,17 @@ ZIS is a z/OS native, authorized cross-memory server that allows a secure and co
Unlike all of the servers described above which run under the `ZWESLSTC` started task as address spaces for USS processes, the Cross Memory server has its own separate started task `ZWESISTC` and its own user ID `ZWESIUSR` that runs the program `ZWESIS01`.
-## API Gateway
+## API Mediation Layer
+
+The API Mediation Layer is a collection of services for management and administration of APIs, and is comprised of the following components that are described in detail below:
+
+* API Gateway
+* API Catalog
+* API Discovery
+* Caching service
+* ZAAS
+
+### API Gateway
The API Gateway is a proxy server that routes requests from clients on its northbound or upstream edge, such as web browsers or the Zowe command line interface, to servers on its southbound (downstream) edge that are able to provide data to serve the request. The API Gateway is also responsible for generating the authentication token used to provide single sign-on (SSO) functionality. The API Gateway homepage is `https://:7554`. Following authentication, this URL enables users to navigate to the API Catalog.
@@ -86,17 +92,17 @@ The API Gateway is a proxy server that routes requests from clients on its north
When the API Gateway is running, this server is accessible at `https://:7554/`.
When running on z/OS, the server uses the jobname suffix of AG.
-## API Catalog
+### API Catalog
The API Catalog provides a list of the API services that have registered themselves as catalog tiles. These tiles make it possible to view the available APIs from Zowe's southbound (downstream) servers, as well as test REST API calls.
When the API Gateway is running, this server is accessible at `https://:7554/apicatalog/ui/v1`.
-When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog`
+When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog`
When running on z/OS, the server uses the jobname suffix of AC.
-## API Discovery
+### API Discovery
The API Discovery server acts as the registration service broker between the API Gateway and its southbound (downstream) servers. This server can be accessed through the URL `https://:7552` making it possible to view a list of registered API services on the API discovery homepage.
@@ -104,13 +110,13 @@ The API Discovery server acts as the registration service broker between the API
When running on z/OS, the server uses the jobname suffix of AD.
-## Caching service
+### Caching service
The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The Caching service URL is `https://:7555`.
For more information about the Caching service, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service).
When the API Gateway is running, this server is accessible at `https://:7554/cachingservice/api/v1`.
-When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`.
+When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`.
When running on z/OS, the server uses the jobname suffix of CS.
## Desktop Apps
@@ -118,13 +124,3 @@ When running on z/OS, the server uses the jobname suffix of CS.
Zowe provides a number of rich GUI web applications for working with z/OS. Such applications include the Editor for files and datasets, the JES Explorer for jobs, and the IP Explorer for the TCPIP stack. You can access them through the Zowe desktop.
-
-### File API and JES API
-
-The File API server provides a set of REST APIs for working with z/OS data sets and Unix files. These APIs can be enabled in Zowe server configuration.
-
-The JES API server provides a set of REST APIs for working with JES. These APIs can be enabled in Zowe server configuration.
-
-Both the File API and JES API servers are registered as tiles in the API Catalog, so users can view the Swagger definition and test API requests and responses.
-
-
diff --git a/docs/getting-started/zowe-high-availability.md b/docs/getting-started/zowe-high-availability.md
index e90cdaa827..adac3adfab 100644
--- a/docs/getting-started/zowe-high-availability.md
+++ b/docs/getting-started/zowe-high-availability.md
@@ -30,7 +30,7 @@ If you are running the Caching Service on z/OS, there are three storage methods
- Part of the Caching service
- Does not need separate processes
- Highly performant
-- [VSAM](../user-guide/configure-caching-service-ha.md#vsam)
+- [VSAM (*deprecated*)](../user-guide/configure-caching-service-ha.md#vsam-deprecated)
- Familiar to z/OS engineers
- Slow
- [Redis](../extend/extend-apiml/api-mediation-redis.md#redis-configuration)
diff --git a/docs/getting-started/zowe-office-hours.md b/docs/getting-started/zowe-office-hours.md
index 50d1915835..70fd0b24f0 100644
--- a/docs/getting-started/zowe-office-hours.md
+++ b/docs/getting-started/zowe-office-hours.md
@@ -1,4 +1,4 @@
-# Zowe V2 office hours videos
+# Zowe V2 Office Hours
Watch the series of Zowe office hours videos to learn more about the new features and enhancements in Zowe Version 2 release.
diff --git a/docs/getting-started/zowe-resources.md b/docs/getting-started/zowe-resources.md
index 79d47fcd41..cbf6ab5bdb 100644
--- a/docs/getting-started/zowe-resources.md
+++ b/docs/getting-started/zowe-resources.md
@@ -13,42 +13,43 @@ Want to contribute a blog? Details for how to contribute to the [Zowe blogs on M
-As well as [Zowe videos](https://www.youtube.com/embed?listType=playlist&list=PL8REpLGaY9QE_9d57tw3KQdwSVLKuTpUZ) owned and managed by the community, there are a number of external youtubers who host Zowe related content.
+As well as [Zowe videos](https://www.youtube.com/embed?listType=playlist&list=PL8REpLGaY9QE_9d57tw3KQdwSVLKuTpUZ) owned and managed by the community, there are a number of external YouTubers who host Zowe related content.
- [Zowe Demos playlist from Bill Pereira](https://www.youtube.com/playlist?list=PLM85SdWDWtebJ13Kww8rxKlDlWe72D7b3)
- [Mainframe Bytes channel from Jessielaine Punongbayan](https://www.youtube.com/channel/UCZrvxFwT1GpvJuFRyqc5uWg)
-
## Webinars
-Find out what's happening with Zowe in the Zowe Quarterly Update Webinar Series.
+Find out what is happening with Zowe in the Zowe Quarterly Update Webinar Series.
+- [Zowe Quarterly Update Webinar: May 2024](https://youtu.be/57IKsRfM_F0)
+- [Zowe Quarterly Update Webinar: February 2024](https://youtu.be/d9eA9eZRREI)
- [Zowe Quarterly Update Webinar: October 2021](https://youtu.be/b0Xo6WIy3vc)
- [Zowe Quarterly Update Webinar: July 2021](https://youtu.be/T3Z4hMwElII)
- [Zowe Quarterly Update Webinar: April 2021](https://youtu.be/9rQCcZGVDzQ)
- [Zowe Quarterly Update Webinar: January 2021](https://youtu.be/ZEwd8wZvbIw)
- [Zowe Quarterly Update Webinar: October 2020](https://youtu.be/GbAFO5vzBhw)
-The [OMP Youtube channel](https://www.youtube.com/channel/UC-WTXQQtz2m5iTflJLK59aw/videos) also offers other webinars about Zowe.
+The [OMP Youtube channel](https://www.youtube.com/channel/UC-WTXQQtz2m5iTflJLK59aw/videos) also offers other webinars about Zowe.
+
- [Treat Yourself to a Guided, Comprehensive Tour of Zowe Desktop Applications](https://youtu.be/cbEVbcsaGCs)
- [Zowe Webinar Feb. 22, 2019](https://youtu.be/XixEltbRmds)
- [Open Mainframe Project Webinar: Zowe Virtual Hackathon](https://youtu.be/zIPzaQK2bfU)
-
## Community
-**Join us on Slack**
+### Join us on Slack
- [Slack invite link](https://slack.openmainframeproject.org/)
- [Introduction to Zowe Slack channels](https://github.com/zowe/community/blob/master/README.md#slack)
-**Learn more about the community**
+### Learn more about the community
- [Zowe community GitHub repo](https://github.com/zowe/community/blob/master/README.md)
- Find out information about Zowe sub-projects, GitHub repos, mailing lists, community meeting minutes, contribution guidelines, and so on.
+ Find out information about Zowe sub-projects, GitHub repos, mailing lists, community meeting minutes, contribution guidelines, and so on.
-**Connect with the community through meetings**
+### Connect with the community through meetings
- [Zowe meeting calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe)
@@ -56,20 +57,8 @@ The [OMP Youtube channel](https://www.youtube.com/channel/UC-WTXQQtz2m5iTflJLK59
## Training
-**Courses**
+### Courses
- [Zowe Fundamentals](https://interskill.com/course/zowe-foundations/)
- Interskill Learning offers a free training course that introduces the components that comprise Zowe and the benefits of using Zowe and how its capabilities can be extended.
-
-**Trials**
-
-- [Zowe trial](https://early-access.ibm.com/software/support/trial/cst/welcomepage.wss?siteId=936&tabId=2216&w=1&mhsrc=ibmsearch_a&mhq=Zowe%20trial)
-
- The Zowe trial hosted by IBM is a fully configured z/OS environment with Zowe preinstalled and set up along with a set of integrated easy-to-follow tutorials that walk you through the basics of Zowe and gives you hands-on experience of extending Zowe. This no-charge trial is available in two hours for three days.
-
-- [Get started with the Zowe Web UI](https://developer.ibm.com/components/ibmz/tutorials/zowe-step-by-step-tutorial/)
-
- This online tutorial hosted by IBM guides you to add new apps to the Zowe Web UI. It provides a public hosted Zowe instance that allows you to perform the steps in a z/OS environment.
-
-
+ Interskill Learning offers a free training course that introduces the components that comprise Zowe and the benefits of using Zowe and how its capabilities can be extended.
diff --git a/docs/getting-started/zowe-security-authentication.md b/docs/getting-started/zowe-security-authentication.md
index eb0b1eef33..9da8b749db 100644
--- a/docs/getting-started/zowe-security-authentication.md
+++ b/docs/getting-started/zowe-security-authentication.md
@@ -4,7 +4,6 @@ The API Mediation Layer provides multiple methods which clients can use to authe
* [Authentication with JSON Web Tokens (JWT)](#authentication-with-json-web-tokensjwt)
* [Authentication with client certificates](#authentication-with-client-certificates)
* [Authentication with Personal Access Token (PAT)](#authentication-with-personal-access-token-pat)
-* [Authentication with SAF Identity Tokens](#authentication-with-saf-identity-tokens)
* [Multi-factor authentication (MFA)](#multi-factor-authentication-mfa)
* [Advanced Authentication Mainframe (AAM)](#advanced-authentication-mainframe-aam)
@@ -32,11 +31,6 @@ A Personal Access Token (PAT) is a specific scoped JWT with a configurable valid
For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token.md).
-## Authentication with SAF Identity Tokens
-The SAF Authentication Provider allows the API Gateway to authenticate the user directly with the z/OS SAF provider that is installed on the system.
-
-For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system.md#configure-signed-saf-identity-tokens-idt).
-
## Multi-factor authentication (MFA)
Multi-factor authentication is provided by third-party products which Zowe is compatible with. The following are known to work with Zowe:
@@ -46,8 +40,6 @@ Multi-factor authentication is provided by third-party products which Zowe is co
Additionally, Zowe API ML can be configured to accept OIDC/OAuth2 user authentication tokens. In this particular case, MFA support is built into the OIDC provider system.
It does not rely on the mainframe MFA technology, but is equally secure.
-For details about multi-factor authentication, see [the MFA documentation here](../user-guide/mvd-configuration.md#multi-factor-authentication-configuration).
-
## Advanced Authentication Mainframe (AAM)
To add a dynamic element to the authentication, you can configure the Advanced Authentication Mainframe to enable multi-factor authentication. For more information about AAM, see the [Advanced Authentication Mainframe documentation](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-advanced-authentication-mainframe/2-0.html).
diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md
index e0ead2e71c..5adacfcde8 100644
--- a/docs/getting-started/zowe-security-overview.md
+++ b/docs/getting-started/zowe-security-overview.md
@@ -3,7 +3,7 @@
Zowe implements comprehensive measures to secure mainframe services and data resources in transition and in rest:
- Digital certificates are used by Zowe to facilitate secure electronic communication and data exchange between people, systems, and devices online.
-- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, Multi-Factor Authentication (MFA), JWT, or Personal Access Token (PAT).
+- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, JWT, or Personal Access Token (PAT). Potentially with added Multi-Factor Authentication (MFA).
- User access is authorized by System Authorization Facility (SAF) / External Security Manager (ESM).
Before installation and use of Zowe server-side components, it is practical to first learn about the core security features built into the Zowe architecture.
@@ -28,11 +28,18 @@ A certificate contains an identity (a hostname, or an organization, or an indivi
A certificate can be self-signed or issued by a Certificate Authority (CA). A CA is a trusted organization which provides infrastructure for creation, validation and revocation of the certificates according to the contemporary security standards.
-**Note:**
-For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local CA, or even self-signed certificates issued by Zowe security tools specific for the target technology platform.
-Use of self-signed certificates, however, is not recommended for production environments.
+:::note
-**Tip:** Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates.
+For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local Certificate Authority (CA), or even certificates issued by Zowe security tools and signed by generated CA specific for the target technology platform.
+Use of certificates signed by generated CA, however, is not recommended for production environments.
+
+:::
+
+:::tip
+
+Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates.
+
+:::
### Digital certificates usage
Zowe uses digital certificates to secure the communication channel between Zowe components as well as between Zowe clients and Zowe services. Digital client certificates can also be used to validate that a client-user (the service user) identity is known to the mainframe security facility.
@@ -44,9 +51,9 @@ Zowe uses digital certificates to secure the communication channel between Zowe
## User Authentication
Zowe always authenticates the users accessing its interfaces and services.
-Zowe API ML implements a Singls-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid.
+Zowe API ML implements a Single-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid.
-API ML uses multiple authentication methods - from Basic Auth (username-password), to external Multi-Factor Authentication providers, and modern authentication protocols, such as OIDC/OAuth2.
+API ML uses multiple authentication methods - Basic Auth (username-password), OIDC/OAuth2, Client certificates and Personal Access Tokens with possibility of strengthening of the security by adding external Multi-Factor Authentication provider.
**Next steps:**
- For more details on the authentication methods used by Zowe, see the dedicated [API ML User Authentication](./zowe-security-authentication) article.
@@ -68,7 +75,7 @@ Access to a SAF resource is checked with the installed z/OS External Security Ma
For detailed information, see the [SAF resource checking documentation](../user-guide/api-mediation/configuration-saf-resource-checking).
## Additional resources
-For more information about getting started with certificates including dertermining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources:
+For more information about getting started with certificates including determining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources:
- [Use-case based certificates configuration scenarios](../user-guide/certificate-configuration-scenarios.md)
- [Generate certificates for Zowe servers](../user-guide/generate-certificates.md)
diff --git a/docs/getting-started/zowe-v2-overview.md b/docs/getting-started/zowe-v2-overview.md
new file mode 100644
index 0000000000..e396bfd8e3
--- /dev/null
+++ b/docs/getting-started/zowe-v2-overview.md
@@ -0,0 +1,27 @@
+# Important updates in Zowe V2
+
+Zowe V2 is now in maintenance state. Only [patch releases](https://github.com/zowe/community/blob/master/Project%20Management/Schedule/Zowe%20PI%20%26%20Sprint%20Cadence.md#v2) are planned until the Zowe V2 End of Service scheduled for early 2027.
+
+Review enhancements introduced in previous releases:
+
+- [Zowe v2.18.0 (August 2024)](../whats-new/release-notes/v2_18_0)
+- [Zowe v2.17.0 (July 2024)](../whats-new/release-notes/v2_17_0)
+- [Zowe v2.16.0 (May 2024)](../whats-new/release-notes/v2_16_0)
+- [Zowe v2.15.0 (March 2024)](../whats-new/release-notes/v2_15_0)
+- [Zowe v2.14.0 (January 2024)](../whats-new/release-notes/v2_14_0)
+- [Zowe v2.13.0 (December 2023)](../whats-new/release-notes/v2_13_0)
+- [Zowe v2.12.0 (October 2023)](../whats-new/release-notes/v2_12_0)
+- [Zowe v2.11.0 (September 2023)](../whats-new/release-notes/v2_11_0)
+- [Zowe v2.10.0 (July 2023)](../whats-new/release-notes/v2_10_0)
+- [Zowe v2.9.0 (June 2023)](../whats-new/release-notes/v2_9_0)
+- [Zowe v2.8.0 (April 2023)](../whats-new/release-notes/v2_8_0)
+- [Zowe v2.7.0 (March 2023)](../whats-new/release-notes/v2_7_0)
+- [Zowe v2.6.1 (February 2023)](../whats-new/release-notes/v2_6_1)
+- [Zowe v2.6.0 (January 2023)](../whats-new/release-notes/v2_6_0)
+- [Zowe v2.5.0 (December 2022)](../whats-new/release-notes/v2_5_0)
+- [Zowe v2.4.0 (October 2022)](../whats-new/release-notes/v2_4_0)
+- [Zowe v2.3.1 (September 2022)](../whats-new/release-notes/v2_3_1)
+- [Zowe v2.3.0 (September 2022)](../whats-new/release-notes/v2_3_0)
+- [Zowe v2.2.0 (July 2022)](../whats-new/release-notes/v2_2_0)
+- [Zowe v2.1.0 (June 2022)](../whats-new/release-notes/v2_1_0)
+- [Zowe v2.0.0 (April 2022)](../whats-new/release-notes/v2_0_0)
\ No newline at end of file
diff --git a/docs/getting-started/zowe_faq.md b/docs/getting-started/zowe_faq.md
index 476000dcf3..9ce6862d63 100644
--- a/docs/getting-started/zowe_faq.md
+++ b/docs/getting-started/zowe_faq.md
@@ -1,4 +1,4 @@
-# Zowe FAQ
+# Zowe FAQs
Check out the following FAQs to learn more about the purpose and function of Zowe™.
@@ -34,7 +34,7 @@ Zowe technology can be used by a variety of mainframe IT and non-IT professional
@@ -499,19 +499,19 @@ As a developer, you may contribute to Zowe Explorer in the following ways:
Click here for ACF2 configuration details.
```markup ACF @@ -306,7 +334,7 @@ Use the following curl command to make a REST request with the OIDC token to the curl --location 'https://"$HOSTNAME:$PORT"/gateway/api/v1/auth/oidc-token/validate --data '{"token": "$OIDC_TOKEN","serviceId": "$SERVICE_ID"}' ``` -An HTTP `200` code is returned if the validation passes. Failure to validate returns an HTTP `40x` error. +An HTTP `204` code is returned if the validation passes. Failure to validate returns an HTTP `40x` error. ::: :::note Azure Entra ID OIDC notes: diff --git a/docs/extend/extend-apiml/api-mediation-passtickets.md b/docs/extend/extend-apiml/api-mediation-passtickets.md index bf06738235..36369e33f9 100644 --- a/docs/extend/extend-apiml/api-mediation-passtickets.md +++ b/docs/extend/extend-apiml/api-mediation-passtickets.md @@ -1,6 +1,6 @@ # This article was changed and moved -The information that used to be in the article **Configuring Zowe to use PassTickets** has been reorganized and is available in following articles: +The information that used to be in the article **Configuring Zowe to use PassTickets** has been reorganized and is available in following articles: - For detailed information about configuring Zowe to use PassTickets, and to enable Zowe to use PassTickets to authenticate towards specific extending services, see [Enabling single sign on for extending services via PassTicket configuration](https://docs.zowe.org/stable/user-guide/api-mediation/configuration-extender-passtickets). diff --git a/docs/extend/extend-apiml/api-mediation-redis.md b/docs/extend/extend-apiml/api-mediation-redis.md index 2bf851af6e..61ce46b797 100644 --- a/docs/extend/extend-apiml/api-mediation-redis.md +++ b/docs/extend/extend-apiml/api-mediation-redis.md @@ -1,7 +1,9 @@ # Using Redis as a storage solution through the Caching service -As an API developer, you can configure Redis as a storage solution through the Caching service. This article describes how to configure your storage solution for Redis. -You can configure Redis for high availability as well as to replicate data to provide data durability and availability. +:::info Required roles: system administrator, security administrator +::: + +You can configure Redis as a storage solution through the Caching service, as well as configure Redis for high availability to replicate data to provide data durability and availability. - [Understanding Redis](#understanding-redis) - [Redis configuration](#redis-configuration) diff --git a/docs/extend/extend-apiml/api-mediation-versioning.md b/docs/extend/extend-apiml/api-mediation-versioning.md index dab593e30a..d97c0a99b6 100644 --- a/docs/extend/extend-apiml/api-mediation-versioning.md +++ b/docs/extend/extend-apiml/api-mediation-versioning.md @@ -24,7 +24,6 @@ Resource Identifier (URIs). The services are accessed via APIML gateway. Example of a URI: `https://host:10010/endevormfno/api/v1/ENWSQA01/packages/PACKAGETST (https://{gatewayHost}:{port}/{serviceName}/api/v{majorVersion}/{resource}`) - See [Components of URL](../extend-apiml/api-mediation-components-of-URL.md) for more information about the URL components of REST APIs. ## Data Model diff --git a/docs/extend/extend-apiml/api-mediation-vsam.md b/docs/extend/extend-apiml/api-mediation-vsam.md index 837de1e7ab..60cdafa621 100644 --- a/docs/extend/extend-apiml/api-mediation-vsam.md +++ b/docs/extend/extend-apiml/api-mediation-vsam.md @@ -1,7 +1,13 @@ -# Using VSAM as a storage solution through the Caching service +# Using VSAM as a storage solution through the Caching service **Deprecated** -As an API developer, you can configure VSAM as a storage solution through the Caching service. The procedure in this article -describes how to configure your storage solution for VSAM. Configuring VSAM ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage multiple caching services concurrently, whereby clients can retreive data through VSAM. +:::info Required roles: system administrator, security administrator +::: + +:::caution Important +VSAM as a storage solution is deprecated in Zowe V3, please use [Infinispan](./api-mediation-infinispan), which is packaged as part of the Caching Service. +::: + +In Zowe v2 or previous versions, it is possible to configure VSAM as a storage solution through the Caching service. Configuring VSAM ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage multiple caching services concurrently, whereby clients can retreive data through VSAM. - [Understanding VSAM](#understanding-vsam) - [VSAM configuration](#vsam-configuration) diff --git a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md index 6a7257c6c5..8ea0e707b0 100644 --- a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md +++ b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md @@ -231,7 +231,7 @@ by other technologies in Zowe (Node.js). As an alternative to using a keystore and truststore, API ML can read certificates from a _SAF keyring_. The user running the API ML must have rights to access the keyring. From the java perspective, the keyring behaves as the `JCERACFKS` keystore. The path to the keyring is specified as `safkeyring://user_id/key_ring_id`. The content of the SAF keyring is equivalent to the combined contents of the keystore and the truststore. :::note -When using JCEFACFKS as the keystore type, ensure that you define the class to handle the RACF keyring. Use the `-D` options to specify the `java.protocol.handler.pkgs property`: +When using JCERACFKS as the keystore type, ensure that you define the class to handle the RACF keyring. Use the `-D` options to specify the `java.protocol.handler.pkgs property`: -Djava.protocol.handler.pkgs=com.ibm.crypto.provider ::: diff --git a/docs/extend/extend-apiml/onboard-plain-java-enabler.md b/docs/extend/extend-apiml/onboard-plain-java-enabler.md index 30995dd652..c90704d743 100644 --- a/docs/extend/extend-apiml/onboard-plain-java-enabler.md +++ b/docs/extend/extend-apiml/onboard-plain-java-enabler.md @@ -1,6 +1,6 @@ -# Onboarding a REST API service with the Plain Java Enabler (PJE) +# Onboarding a REST or GraphQL API service with the Plain Java Enabler (PJE) -This article is part of a series of onboarding guides, which outline the process of onboarding REST API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built without a dependency on Spring Cloud, Spring Boot, or SpringFramework. +This article is part of a series of onboarding guides, which outline the process of onboarding REST or GraphQL API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a service with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built without a dependency on Spring Cloud, Spring Boot, or SpringFramework. :::tip For more information about onboarding API services with the API ML, see the [Onboarding Overview](onboard-overview.md). @@ -14,12 +14,12 @@ Zowe API ML is a lightweight API management system based on the following Netfli * Zuul - reverse proxy / API Gateway * Ribbon - load balancer -The API ML Discovery Service component uses Netflix/Eureka as a REST services registry. +The API ML Discovery Service component uses Netflix/Eureka as a services` registry. Eureka endpoints are used to register a service with the API ML Discovery Service. -The API ML provides onboarding enabler libraries. The libraries are JAR artifacts available through an artifactory. Using these libraries is the recommended approach to onboard a REST service with the API ML. +The API ML provides onboarding enabler libraries. The libraries are JAR artifacts available through an artifactory. Using these libraries is the recommended approach to onboard a REST or GraphQL service with the API ML. -The PJE library serves the needs of Java developers who are not using either [Spring Boot](https://spring.io/projects/spring-boot) or the [Spring Framework](https://spring.io/). If Spring Boot or the Spring framework are used in the project you would like to onboard, see the [Onboarding Overview](onboard-overview.md) for the corresponding enablers. +The PJE library serves the needs of Java developers who are not using either [Spring Boot](https://spring.io/projects/spring-boot) or the [Spring Framework](https://spring.io/). If Spring Boot or the Spring framework are used in the project you would like to onboard, see the [Onboarding Overview](onboard-overview.md) for the corresponding enablers. Additionally, this enabler is not intended for use in projects that depend on [Spring Cloud Netflix](https://spring.io/projects/spring-cloud-netflix) components. Configuration settings in the PJE and Spring Cloud Netflix Eureka Client are different. Using the two configuration settings in combination makes the result state of the discovery registry unpredictable. @@ -28,9 +28,9 @@ For more information about how to utilize another API ML enablers, see the docum the [Onboarding Overview](onboard-overview.md). ::: -## Onboarding your REST service with API ML +## Onboarding your REST or GraphQL service with API ML -The following steps outline the overall process to onboard a REST service with the API ML using the PJE. Each step is described in further detail in this article. +The following steps outline the overall process to onboard a service with the API ML using the PJE. Each step is described in further detail in this article. 1. [Prerequisites](#prerequisites) @@ -40,7 +40,7 @@ The following steps outline the overall process to onboard a REST service with t * [Maven build automation system](#maven-build-automation-system) 3. [Configuring your service](#configuring-your-service) - * [REST service identification](#rest-service-identification) + * [Service identification](#service-identification) * [Administrative endpoints](#administrative-endpoints) * [API info](#api-info) * [API routing information](#api-routing-information) @@ -61,17 +61,17 @@ The following steps outline the overall process to onboard a REST service with t Ensure that the prerequisites from the [Onboarding Overview](onboard-overview.md) are met. -* The REST API service to onboard is written in Java +* The REST or GraphQL API service to onboard is written in Java * The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured connection :::noteNotes: * This documentation is valid for API ML version `ZoweApimlVersion 1.3.0` and higher. We recommend that you check the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for the latest stable versions. -* Following this guide enables REST services to be deployed on a z/OS environment. Deployment to a z/OS environment, however, is not required. As such, you can first develop on a local machine before you deploy on z/OS. + * Following this guide enables REST or GraphQL services to be deployed on a z/OS environment. Deployment to a z/OS environment, however, is not required. As such, you can first develop on a local machine before you deploy on z/OS. * The API Mediation Layer provides the sample application using the Plain Java Enabler in the [api-layer repository](https://github.com/zowe/api-layer/tree/v2.x.x/onboarding-enabler-java-sample-app) -::: + ::: ## Configuring your project @@ -112,7 +112,7 @@ Use the following procedure to use _Gradle_ as your build automation system. implementation "org.zowe.apiml.sdk:onboarding-enabler-java:$zoweApimlVersion" implementation "org.zowe.apiml.sdk:common-service-core:$zoweApimlVersion" ``` - The published artifact from the Zowe Artifactory also contains the enabler dependencies from other software packages. If you are using an artifactory other than Zowe, add also the following dependencies in your service `build.gradle` script: + The published artifact from the Zowe Artifactory also contains the enabler dependencies from other software packages. If you are using an artifactory other than Zowe, add also the following dependencies in your service `build.gradle` script: ```gradle implementation "com.netflix.eureka:eureka-client:1.10.15" @@ -124,7 +124,7 @@ Use the following procedure to use _Gradle_ as your build automation system. compileOnly "org.projectlombok:lombok:1.18.20" ``` - **Notes:** + **Notes:** * You may need to add more dependencies as required by your service implementation. * The information provided in this file is valid for `ZoweApimlVersion 1.3.0` and higher. @@ -149,7 +149,7 @@ Use the following procedure if you use _Maven_ as your build automation system. ``` - **Tip:** If you want to use snapshot version, replace `libs-release` with `libs-snapshot` in the repository url and change snapshots->enabled to `true`. + **Tip:** If you want to use snapshot version, replace `libs-release` with `libs-snapshot` in the repository url and change snapshots->enabled to `true`. 2. Add the proper dependencies: ```xml @@ -181,6 +181,8 @@ are in `${parameterValue}` format. For your service configuration file, provide **Example:** +**REST API** + ```yaml serviceId: sampleservice title: Hello API ML @@ -205,7 +207,7 @@ authentication: scheme: httpBasicPassTicket applid: ZOWEAPPL - apiInfo: +apiInfo: - apiId: zowe.apiml.sampleservice version: 1.0.0 gatewayUrl: api/v1 @@ -217,14 +219,71 @@ authentication: swaggerUrl: http://${sampleServiceSwaggerHost}:${sampleServiceSwaggerPort}/sampleservice/api-doc?group=api-v2 documentationUrl: http:// defaultApi: true - catalog: +catalog: tile: id: sampleservice title: Hello API ML description: Sample application to demonstrate exposing a REST API in the ZOWE API ML version: 1.0.0 - ssl: +ssl: + enabled: true + verifySslCertificatesOfServices: true + protocol: TLSv1.2 + keyAlias: localhost + keyPassword: password + keyStore: keystore/localhost.keystore.p12 + keyStoreType: PKCS12 + keyStorePassword: password + trustStore: keystore/localhost.truststore.p12 + trustStoreType: PKCS12 + trustStorePassword: password + ``` + +**GraphQL API** + +```yaml + serviceId: sampleservice + title: Hello API ML + description: Sample API ML GraphQL Service + baseUrl: https://${samplehost}:${sampleport}/${sampleservice} + serviceIpAddress: ${sampleHostIpAddress} + preferIpAddress: false + + homePageRelativeUrl: /application/home + statusPageRelativeUrl: /application/info + healthCheckRelativeUrl: /application/health + + discoveryServiceUrls: + - https://${discoveryServiceHost1}:${discoveryServicePort1}/eureka + - https://${discoveryServiceHost2}:${discoveryServicePort2}/eureka + + routes: + - gatewayUrl: api/v1 + serviceUrl: /sampleservice/api/v1 + +authentication: + scheme: httpBasicPassTicket + applid: ZOWEAPPL + +apiInfo: + - apiId: zowe.apiml.sampleservice + version: 1.0.0 + gatewayUrl: api/v1 + graphqlUrl: http://${sampleServiceGraphQLHost}:${sampleServiceGraphQLPort}/sampleservice/graphql + - apiId: zowe.apiml.sampleservice + version: 2.0.0 + gatewayUrl: api/v2 + graphqlUrl: http://${sampleServiceGraphQLHost}:${sampleServiceGraphQLPort}/sampleservice/graphql + +catalog: + tile: + id: sampleservice + title: Hello API ML + description: Sample application to demonstrate exposing a GraphQL API in the ZOWE API ML + version: 1.0.0 + +ssl: enabled: true verifySslCertificatesOfServices: true protocol: TLSv1.2 @@ -238,6 +297,7 @@ authentication: trustStorePassword: password ``` + **Optional metadata section** The following snippet presents additional optional metadata that can be added. @@ -252,7 +312,7 @@ customMetadata: ``` The onboarding configuration parameters are broken down into the following groups: -- [REST service identification](#rest-service-identification) +- [Service identification](#service-identification) - [Administrative endpoints](#administrative-endpoints) - [API info](#api-info) - [API routing information](#api-routing-information) @@ -263,22 +323,22 @@ The onboarding configuration parameters are broken down into the following group - [Eureka Discovery Service](#eureka-discovery-service) - [Custom Metadata](#custom-metadata) -### REST service identification +### Service identification * **serviceId** - The `serviceId` uniquely identifies one or more instance of a microservice in the API ML and is used as part of the service URL path in the API ML Gateway address space. - Additionally, the API ML Gateway uses the `serviceId` for routing to the API service instances. - When two API services use the same `serviceId`, the API Gateway considers the services as clones of each other. - An incoming API request can be routed to either of them through utilized load balancing mechanism. + The `serviceId` uniquely identifies one or more instance of a microservice in the API ML and is used as part of the service URL path in the API ML Gateway address space. + Additionally, the API ML Gateway uses the `serviceId` for routing to the API service instances. + When two API services use the same `serviceId`, the API Gateway considers the services as clones of each other. + An incoming API request can be routed to either of them through utilized load balancing mechanism. - **Important!** Ensure that the `serviceId` is set properly with the following considerations: + **Important!** Ensure that the `serviceId` is set properly with the following considerations: * The same `servicedId` should only be set for multiple API service instances for API scalability. * The `servicedId` value must only contain lowercase alphanumeric characters. * The `servicedId` cannot contain more than 40 characters. - **Example:** + **Example:** * If the `serviceId` is `sampleservice`, the service URL in the API ML Gateway address space appears as the following path: ``` @@ -294,36 +354,36 @@ The onboarding configuration parameters are broken down into the following group * **description** - This parameter is a short description of the API service. This value is displayed in the API Catalog when a specific API service instance is selected. This parameter can be externalized and set by the customer system administrator. + This parameter is a short description of the API service. This value is displayed in the API Catalog when a specific API service instance is selected. This parameter can be externalized and set by the customer system administrator. **Tip:** Describe the service so that the end user understands the function of the service. * **baseUrl** - This parameter specifies the base URL for the following administrative endpoints: + This parameter specifies the base URL for the following administrative endpoints: * **homePageRelativeUrl** * **statusPageRelativeUrl** * **healthCheckRelativeUrl** - Use the following format to include your service name in the URL path: + Use the following format to include your service name in the URL path: - `protocol://host:port/servicename` + `protocol://host:port/servicename` - **Note:** Ensure that the `baseUrl` does not end with a trailing `/`. Inclusion of `/` causes a malformed URL if any of the above administrative endpoints begin with a `/`. It is expected that each administrative endpoint begins with a `/`. Warnings will be logged if this recommendation is not followed. + **Note:** Ensure that the `baseUrl` does not end with a trailing `/`. Inclusion of `/` causes a malformed URL if any of the above administrative endpoints begin with a `/`. It is expected that each administrative endpoint begins with a `/`. Warnings will be logged if this recommendation is not followed. * **serviceIpAddress** (Optional) - This parameter specifies the service IP address and can be provided by a system administrator in the externalized service configuration. - If this parameter is not present in the configuration file or is not set as a service context parameter, it is resolved from the hostname part of the `baseUrl`. + This parameter specifies the service IP address and can be provided by a system administrator in the externalized service configuration. + If this parameter is not present in the configuration file or is not set as a service context parameter, it is resolved from the hostname part of the `baseUrl`. * **preferIpAddress** (Optional) - Set the value of this parameter to `true` to advertise a service IP address instead of its hostname. + Set the value of this parameter to `true` to advertise a service IP address instead of its hostname. ### Administrative endpoints - The following snippet presents the format of the administrative endpoint properties: +The following snippet presents the format of the administrative endpoint properties: ```yaml homePageRelativeUrl: @@ -333,47 +393,49 @@ healthCheckRelativeUrl: /application/health * **homePageRelativeUrl** - Specifies the relative path to the home page of your service. - - Start this path with `/`. If your service has no home page, leave this parameter blank. + Specifies the relative path to the home page of your service. + + Start this path with `/`. If your service has no home page, leave this parameter blank. - **Examples:** + **Examples:** * `homePageRelativeUrl: ` This service has no home page * `homePageRelativeUrl: /` This service has a home page with URL `${baseUrl}/` * **statusPageRelativeUrl** - Specifies the relative path to the status page of your service. + Specifies the relative path to the status page of your service. - Start this path with `/`. + Start this path with `/`. - **Example:** + **Example:** - `statusPageRelativeUrl: /application/info` + `statusPageRelativeUrl: /application/info` - This results in the URL: - `${baseUrl}/application/info` + This results in the URL: + `${baseUrl}/application/info` * **healthCheckRelativeUrl** - Specifies the relative path to the health check endpoint of your service. + Specifies the relative path to the health check endpoint of your service. - Start this path with `/`. + Start this path with `/`. - **Example:** + **Example:** - `healthCheckRelativeUrl: /application/health` + `healthCheckRelativeUrl: /application/health` - This results in the URL: - `${baseUrl}/application/health` + This results in the URL: + `${baseUrl}/application/health` ### API info -REST services can provide multiple APIs. Add API info parameters for each API that your service wants to expose on the API ML. +Services can provide multiple APIs. Add API info parameters for each API that your service wants to expose on the API ML. The following snippet presents the information properties of a single API: +**REST API** + ``` apiInfo: - apiId: zowe.apiml.sampleservice @@ -392,36 +454,52 @@ apiInfo: codeBlock: | console.log('hello'); ``` +**GraphQL API** + +``` +apiInfo: + - apiId: zowe.apiml.sampleservice + version: 1.0.0 + gatewayUrl: api/v1 + graphqlUrl: http://localhost:10021/sampleservice/graphql +``` + * **apiInfo.apiId** - Specifies the API identifier that is registered in the API ML installation. - The API ID uniquely identifies the API in the API ML. - The `apiId` can be used to locate the same APIs that are provided by different service instances. The API developer defines this ID. - The `apiId` must be a string of up to 64 characters - that uses lowercase alphanumeric characters and a dot: `.` . + Specifies the API identifier that is registered in the API ML installation. + The API ID uniquely identifies the API in the API ML. + The `apiId` can be used to locate the same APIs that are provided by different service instances. The API developer defines this ID. + The `apiId` must be a string of up to 64 characters + that uses lowercase alphanumeric characters and a dot: `.` . * **apiInfo.version** - Specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API. + Specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API. * **apiInfo.gatewayUrl** - specifies the base path at the API Gateway where the API is available. - Ensure that this value is the same path as the `gatewayUrl` value in the `routes` sections that apply to this API. + specifies the base path at the API Gateway where the API is available. + Ensure that this value is the same path as the `gatewayUrl` value in the `routes` sections that apply to this API. * **apiInfo.swaggerUrl** (Optional) - Specifies the Http or Https address where the Swagger JSON document is available. + Specifies the Http or Https address where the Swagger JSON document is available. + +* **apiInfo.graphqlUrl** (Optional) + + Specifies the Http or Https address where the GraphQL server is available. + +_Specific for REST API_ * **apiInfo.documentationUrl** (Optional) - Specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation. + Specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation. * **apiInfo.defaultApi** (Optional) - Specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one - with the highest API `version`. + Specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one + with the highest API `version`. * **apiInfo.codeSnippet** (Optional) @@ -429,16 +507,16 @@ apiInfo: the request using the *Try it out* functionality. When specifying this configuration, you need to provide the following parameters: * **`endpoint`** - The endpoint that represents the API operation of the customized snippet + The endpoint that represents the API operation of the customized snippet * **`language`** - The language of the snippet + The language of the snippet * **`codeBlock`** - The content of the snippet to be displayed in the API Catalog + The content of the snippet to be displayed in the API Catalog ### API routing information -The API routing group provides the required routing information used by the API ML Gateway when routing incoming requests to the corresponding REST API service. -A single route can be used to direct REST calls to multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to rewrite the URL +The API routing group provides the required routing information used by the API ML Gateway when routing incoming requests to the corresponding API service. +A single route can be used to direct calls to multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to rewrite the URL in the Gateway address space. Currently, the routing information consists of two parameters per route: The `gatewayUrl` and `serviceUrl`. These two parameters together specify a rule for how the API service endpoints are mapped to the API Gateway endpoints. The following snippet is an example of the API routing information properties. @@ -457,21 +535,21 @@ routes: * **routes** - Specifies the container element for the route. + Specifies the container element for the route. * **routes.gatewayUrl** - The `gatewayUrl` parameter specifies the portion of the gateway URL which is replaced by the `serviceUrl` path part. + The `gatewayUrl` parameter specifies the portion of the gateway URL which is replaced by the `serviceUrl` path part. * **routes.serviceUrl** - The `serviceUrl` parameter provides a portion of the service instance URL path which replaces the `gatewayUrl` part. + The `serviceUrl` parameter provides a portion of the service instance URL path which replaces the `gatewayUrl` part. -**Examples:** +**Examples:** * ``` https://gateway:10010/sampleservice/api ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api ``` @@ -479,7 +557,7 @@ routes: ``` https://gateway:10010/sampleservice/api/v1 ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api/ver1 ``` @@ -487,17 +565,17 @@ routes: ``` https://gateway:10010/sampleservice/api/v1/api-doc ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api/api-doc ``` ### API Catalog information -The API ML Catalog UI displays information about discoverable REST services registered with the API ML Discovery Service. +The API ML Catalog UI displays information about discoverable services registered with the API ML Discovery Service. Information displayed in the Catalog is defined by the metadata provided by your service during registration. The following image is an example of a tile in the API Catalog: - -  + + The Catalog groups correlated services in the same tile if these services are configured with the same `catalog.tile.id` metadata parameter. @@ -516,34 +594,34 @@ The following code block is an example of configuration of a service tile in the * **catalog.tile.id** - Specifies the unique identifier for the product family of API services. - This is a value used by the API ML to group multiple API services into a single tile. - Each unique identifier represents a single API dashboard tile in the Catalog. + Specifies the unique identifier for the product family of API services. + This is a value used by the API ML to group multiple API services into a single tile. + Each unique identifier represents a single API dashboard tile in the Catalog. - **Tip:** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID. + **Tip:** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID. * **catalog.tile.title** - Specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title. + Specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title. * **catalog.tile.description** - The detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description. + The detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description. * **catalog.tile.version** - specifies the semantic version of this API Catalog tile. + specifies the semantic version of this API Catalog tile. - **Note:** Ensure that you increase the version number when you introduce changes to the API service product family details. + **Note:** Ensure that you increase the version number when you introduce changes to the API service product family details. ### Authentication parameters These parameters are not required. Default values are used when parameters are not specified. For more information, see [Authentication Parameters for Onboarding REST API Services](./authentication-for-apiml-services.md#authentication-parameters). - + ### API Security -REST services onboarded with the API ML act as both a client and a server. When communicating to API ML Discovery service, a REST service acts as a client. When the API ML Gateway is routing requests to a service, the REST service acts as a server. +Services onboarded with the API ML act as both a client and a server. When communicating to API ML Discovery service, a service acts as a client. When the API ML Gateway is routing requests to a service, the service acts as a server. These two roles have different requirements. The Zowe API ML Discovery Service communicates with its clients in secure Https mode. As such, TLS/SSL configuration setup is required when a service is acting as a server. In this case, the system administrator decides if the service will communicate with its clients securely or not. @@ -562,9 +640,9 @@ TLS/SSL configuration consists of the following parameters: * **protocol** - This parameter specifies the TLS protocol version currently used by Zowe API ML Discovery Service. + This parameter specifies the TLS protocol version currently used by Zowe API ML Discovery Service. - **Tip:** We recommend you use `TLSv1.2` as your security protocol + **Tip:** We recommend you use `TLSv1.2` as your security protocol * **keyAlias** @@ -577,9 +655,9 @@ TLS/SSL configuration consists of the following parameters: * **keyStore** This parameter specifies the keystore file used to store the private key. When using keyring, the value should be set to the SAF keyring location. For information about required certificates, see [Zowe API ML TLS requirements](https://github.com/zowe/api-layer/blob/v3.x.x/docs/api-ml-security-overview.md#zowe-api-ml-tls-requirements). - - If you have an issue with loading the keystore file in your environment, try to provide the absolute path to the keystore file. The sample keystore file for local deployment is in [api-layer repository](https://github.com/zowe/api-layer/tree/master/keystore/localhost) + +If you have an issue with loading the keystore file in your environment, try to provide the absolute path to the keystore file. The sample keystore file for local deployment is in [api-layer repository](https://github.com/zowe/api-layer/tree/master/keystore/localhost) * **keyStorePassword** @@ -637,22 +715,22 @@ An example is presented in the following snippet: ```yaml discoveryServiceUrls: -- https://localhost:10011/eureka -- http://...... + - https://localhost:10011/eureka + - http://...... ``` * **discoveryServiceUrls** - Specifies the public URL of the Discovery Service. The system administrator at the customer site defines this parameter. - It is possible to provide multiple values in order to utilize fail over and/or load balancing mechanisms. + Specifies the public URL of the Discovery Service. The system administrator at the customer site defines this parameter. + It is possible to provide multiple values in order to utilize fail over and/or load balancing mechanisms. ### Custom Metadata For information about custom metadata, see the topic [Custom Metadata](./custom-metadata.md). - + ## Registering your service with API ML -The following steps outline the process of registering your service with API ML. Each step is described in detail in this article. The process describes the integration with the usage of the Java application server. The guideline is tested with the Tomcat application server. The specific steps that apply for other application servers may differ. +The following steps outline the process of registering your service with API ML. Each step is described in detail in this article. The process describes the integration with the usage of the Java application server. The guideline is tested with the Tomcat application server. The specific steps that apply for other application servers may differ. 1. Add a web application context listener class 2. Register a web application context listener @@ -662,19 +740,19 @@ The following steps outline the process of registering your service with API ML. **Follow these steps:** -1. Implement and add a web application context listener class: +1. Implement and add a web application context listener class: - ```implements javax.servlet.ServletContextListener``` + ```implements javax.servlet.ServletContextListener``` - The web application context listener implements two methods to perform necessary actions at application start-up time as well as when the application context is destroyed: + The web application context listener implements two methods to perform necessary actions at application start-up time as well as when the application context is destroyed: - - The `contextInitialized` method invokes the `apiMediationClient.register(config)` method to register the application with API Mediation Layer when the application starts. - - The `contextDestroyed` method invokes the `apiMediationClient.unregister()` method when the application shuts down. This unregisters the application from the API Mediation Layer. + - The `contextInitialized` method invokes the `apiMediationClient.register(config)` method to register the application with API Mediation Layer when the application starts. + - The `contextDestroyed` method invokes the `apiMediationClient.unregister()` method when the application shuts down. This unregisters the application from the API Mediation Layer. 2. Register a web application context listener. - Add the following code block to the deployment descriptor `web.xml` to register a context listener: - + Add the following code block to the deployment descriptor `web.xml` to register a context listener: + ```xml
+
+
+ Click here for procedural details using Gradle.
+ **Gradle:** - 1. Create a `gradle.properties` file in the root of your project if one does not already exist. + 1. Create a `gradle.properties` file in the root of your project if one does not already exist. - 2. In the `gradle.properties` file, set the URL of the specific Artifactory containing the _SpringEnabler_ artifact. + 2. In the `gradle.properties` file, set the URL of the specific Artifactory containing the _SpringEnabler_ artifact. - ``` - # Repository URL for getting the enabler-java artifact - artifactoryMavenRepo=https://zowe.jfrog.io/zowe/libs-release/ - ``` + ``` + # Repository URL for getting the enabler-java artifact + artifactoryMavenRepo=https://zowe.jfrog.io/zowe/libs-release/ + ``` - 3. Add the following _Gradle_ code block to the `repositories` section of your `build.gradle` file: + 3. Add the following _Gradle_ code block to the `repositories` section of your `build.gradle` file: - ```gradle - repositories { - ... + ```gradle + repositories { + ... - maven { + maven { url artifactoryMavenRepo - } } - ``` + } + ``` - 4. Add the following _Gradle_ dependency: + 4. Add the following _Gradle_ dependency: - ```groovy - dependencies { - compile 'org.zowe.apiml.sdk:zaas-client:{{version}}' - } - ``` + ```groovy + dependencies { + compile 'org.zowe.apiml.sdk:zaas-client:{{version}}' + } + ``` + +
+
-
- libs-release
- libs-release
- https://zowe.jfrog.io/zowe/libs-release/
-
- false
-
-
-
- ```
+ 1. Add the following _XML_ tags within the newly created `pom.xml` file:
+
+ ```xml
+
+
+ libs-release
+ libs-release
+ https://zowe.jfrog.io/zowe/libs-release/
+
+ false
+
+
+
+ ```
**Tip:** If you want to use snapshot version, replace libs-release with libs-snapshot in the repository url and change snapshots->enabled to true.
- 2. Then add the following _Maven_ dependency:
+ 2. Then add the following _Maven_ dependency:
- ```xml
-
- org.zowe.apiml.sdk
- zaas-client
- {{version}}
-
- ```
+ ```xml
+
+ org.zowe.apiml.sdk
+ zaas-client
+ {{version}}
+
+ ```
+
+
2. In your application, create your Java class which will be used to create an instance of `ZaasClient`, which enables you to use its method to login, query, and to issue a PassTicket.
diff --git a/docs/extend/extend-cli/cli-authentication-mechanisms.md b/docs/extend/extend-cli/cli-authentication-mechanisms.md
new file mode 100644
index 0000000000..274d9e7b2a
--- /dev/null
+++ b/docs/extend/extend-cli/cli-authentication-mechanisms.md
@@ -0,0 +1,16 @@
+# Authentication mechanisms
+
+As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe.
+
+Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with.
+
+However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in.
+
+To learn the authentication methods used for different services and their order of precedence, refer to the following table.
+
+Service | Order of precedence
+|:--- |:--- |
+API ML | 1. username, passwordClick here for procedural details using Maven.
**Maven:** - 1. Add the following _XML_ tags within the newly created `pom.xml` file: - - ```xml -2. API ML token
3. PEM certificate | +Db2,
FTP,
most other services | username, password +SSH | 1. SSH key
2. username, password + ZOSMF
direct connection | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md index 548a47f470..b93e3be1a8 100644 --- a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md +++ b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md @@ -1,40 +1,42 @@ # Creating plug-in lifecycle actions -As a developer, you may want your plug-in to perform certain tasks immediately after install and just before uninstall. +As a developer, you might want your plug-in to perform certain tasks immediately after install and just before uninstall. Many different types of tasks can make up these *plug-in lifecycle actions*, including the following examples: - Post-install actions: - - A sanity check + - An initial check - Additional setup - - Adding the plug-in as an override of Zowe CLI Credential Manager + - Adding the plug-in as an override of Zowe CLI's built-in credential manager - Pre-uninstall actions: - Revert specialized setup - - Removing the plug-in as an override of Zowe CLI Credential Manager + - Removing the plug-in as an override of Zowe CLI's built-in credential manager Creating and using lifecycle actions is optional, but they can be useful tools. Lifecycle actions can automate a manual process intended for the plug-in user to carry out. They can also avoid the need to create commands with uses limited to post-install and pre-uninstall tasks. -**Note:** When creating a plug-in to override Zowe CLI Credential Manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +:::note +When creating a plug-in to override Zowe CLI's built-in credential manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +::: -## Implenting lifeycyle actions +## Implementing lifecyle actions -Add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions. - -Follow these steps: +To add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions: 1. Navigate to the plug-in definition file. - This file is the value for the `configurationModule` property in the plug-in `package.json` file. - - See this [`IImperativeConfig.ts` file](https://github.com/zowe/imperative/blob/master/packages/imperative/src/doc/IImperativeConfig.ts) to view an example of the detailed format used in the plug-in definition file. + The path to this file is the value for the `configurationModule` property in the plug-in `package.json` file. 2. In the plug-in definition file, use the `pluginLifeCycle` property to add the path to the javascript file the plug-in uses to implement the class containing lifecycle functions. - This plug-in lifecycle functions class extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/imperative/blob/master/packages/imperative/src/plugins/AbstractPluginLifeCycle.ts). + The `pluginLifeCycle` property is defined in [this file](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/doc/IImperativeConfig.ts). + + The class defined by this property extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/plugins/AbstractPluginLifeCycle.ts). 3. In the plug-in lifecycle functions class you created, add instructions for both the `postInstall` and `preUninstall` functions. If implemented correctly, Zowe CLI calls the `postInstall` function of the plug-in immediately after the plug-in has been installed. Similarly, the `preUninstall` function is called immediately before the Zowe CLI uninstalls the plug-in. -**Note:** If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +:::note +If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +::: diff --git a/docs/extend/extend-cli/cli-devTutorials.md b/docs/extend/extend-cli/cli-devTutorials.md index f253652c41..bc41efbd1c 100644 --- a/docs/extend/extend-cli/cli-devTutorials.md +++ b/docs/extend/extend-cli/cli-devTutorials.md @@ -1,74 +1,50 @@ # Developing for Zowe CLI -You can extend Zowe™ CLI by developing plug-ins and contributing code to the base Zowe CLI or existing plug-ins. +Extend Zowe™ CLI by developing plug-ins and contributing code to Zowe CLI core or existing plug-ins. ## How to contribute -You can contribute to Zowe CLI in the following ways: -- Add new commands, options, or other improvements to the base CLI. + +Contribute to Zowe CLI in the following ways: +- Add new commands, options, or other improvements to the core CLI. - Develop a Zowe CLI plug-in. You might want to contribute to Zowe CLI to accomplish the following objectives: - Provide new scriptable functionality for yourself, your organization, or to a broader community. -- Make use of Zowe CLI infrastructure (profiles and programmatic APIs). +- Make use of Zowe CLI infrastructure (such as profiles and programmatic APIs). - Participate in the Zowe CLI community space. ## Getting started -If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). The [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in) is a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects. + +If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). To review a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects, see the [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in). ### Contribution guidelines + The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins. -The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly: +The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. | For more information about ... | See: | | ------------------------------ | ----- | -| General guidelines that apply to contributing to Zowe CLI and Plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | -| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| -| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | -| Guidelines for running tests on the plug-ins that you build| [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | -Versioning conventions for Zowe CLI and Plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | - - -### Tutorials -Follow these tutorials to get started working with the sample plug-in: -1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment. -2. [Installing a plug-in:](cli-installing-sample-plugin.md) Install the sample plug-in to Zowe CLI and run as-is. -3. [Extending a plug-in:](cli-extending-a-plugin.md) Extend the sample plug-in with a new by creating a programmatic API, definition, and handler. -4. [Creating a new plug-in:](cli-developing-a-plugin.md) Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets. -5. [Implementing user profiles:](cli-implement-profiles.md) Implement user profiles with the plug-in. +| General guidelines that apply to contributing to Zowe CLI and plug-ins | [Contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | +| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and plug-in guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| +| Guidelines for running tests on Zowe CLI | [Testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | +| Guidelines for running tests on the plug-ins that you build| [Plug-in testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | +Versioning conventions for Zowe CLI and plug-ins| [Versioning guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | ### Plug-in development overview -At a high level, a plug-in must have `imperative-framework` configuration [(sample here)](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. -A Zowe CLI plug-in will minimally contain the following: +At a high level, a plug-in must have `imperative-framework` configuration (see a [sample here](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts)). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. + +A Zowe CLI plug-in minimally contains the following: 1. Programmatic API: Node.js programmatic APIs to be called by your handler or other Node.js applications. 2. Command definition: The syntax definition for your command. 3. Handler implementation: To invoke your programmatic API to display information in the format that you defined in the definition. -The following guidelines and documentation will assist you during development: - -### Imperative CLI Framework documentation -[Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these supplementary documents during development to learn about specific features such as: +#### Imperative CLI Framework documentation +[Imperative CLI Framework documentation](https://github.com/zowe/zowe-cli/wiki) is a key source of information to learn about the features of Imperative CLI Framework, the code framework that you use to build plug-ins for Zowe CLI. Refer to these supplementary documents during development to learn about specific features such as: - Auto-generated help - JSON responses - User profiles -- Logging, progress bars, experimental commands, and more! +- Logging, progress bars, experimental commands, and more - Authentication mechanisms - -### Authentication mechanisms - -As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe. - -Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with. - -However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in. - -To learn the authentication methods used for different services and their order of precedence, refer to the following table: - -service | Zowe V1 order of precedence | Zowe V2 order of precedence -|:--- |:--- |:--- | -API ML | 1. username, password
2. API ML token | 1. username, password
2. API ML token
3. PEM certificate | -Db2,
FTP,
most other services | username, password | username, password -SSH | 1. SSH key
2. username, password | 1. SSH key
2. username, password - ZOSMF
direct connection | username, password | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-developing-a-plugin.md b/docs/extend/extend-cli/cli-developing-a-plugin.md index 290b098d52..0e635f74e7 100644 --- a/docs/extend/extend-cli/cli-developing-a-plugin.md +++ b/docs/extend/extend-cli/cli-developing-a-plugin.md @@ -1,21 +1,22 @@ # Developing a new Zowe CLI plug-in -Before you begin this tutorial, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. + +Before you begin, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. ## Overview + The advantage of Zowe CLI and of the CLI approach in mainframe development is that it allows for combining different developer tools for new and interesting uses. This tutorial demonstrates how to create a brand new Zowe CLI plug-in that uses Node.js to create a client-side API. -After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial will also show you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). +After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial also shows you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). If you are ready to create your own unique Zowe CLI plug-in, refer to the notes at the end of each tutorial step for guidance. If you are interested in creating a credential manager plug-in, see the [Zowe CLI secrets for kubernetes plug-in](https://github.com/zowe/zowe-cli-secrets-for-kubernetes) repository. ## Setting up the new sample plug-in project - Download the sample plug-in source and delete the irrelevant content to set up your plug-in project. - - Follow these steps: + + Download the sample plug-in source and delete the irrelevant content to set up your plug-in project: 1. Open a terminal and run the command `mkdir zowe-tutorial`. @@ -49,7 +50,11 @@ If you are interested in creating a credential manager plug-in, see the [Zowe CL If vulnerabilities are found in any of the installed dependencies, refer to [npm Docs](https://docs.npmjs.com/cli/v9/commands/npm-audit) for how to fix them. ::: -**To create a unique plug-in:** Change the `files-util` directory to a name applicable for your project. +:::tip To create a unique plug-in + +Change the `files-util` directory to a name applicable for your project. + +::: ## Updating `package.json` @@ -63,7 +68,11 @@ Open the `package.json` file in a text editor and replace the name field with th This tutorial uses `@zowe/files-util` as the tutorial plug-in name. -**To create a unique plug-in:** Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). +:::tip To create a unique plug-in + +Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). + +::: ## Adjusting Imperative CLI Framework configuration @@ -86,13 +95,15 @@ export = config; When successful, the `src/pluginDef.ts` file contains the new configurations. -**To create a unique plug-in:** Change the plug-in name, display name, and description according to your project. +:::tip To create a unique plug-in -## Adding third-party packages +Change the plug-in name, display name, and description according to your project. -Install third-party packages as dependencies for the plug-in's client-side API. +::: - Follow these steps: +## Adding third-party packages + +Install third-party packages as dependencies for the plug-in's client-side API: 1. Run `npm install --save-exact diff` to install the diff package (which includes methods for comparing text). @@ -100,12 +111,15 @@ Install third-party packages as dependencies for the plug-in's client-side API. When successful, the `diff` and `@types/diff` packages are added to the dependency list in the `package.json` file. -**To create a unique plug-in:** Instead of the `diff` package, install the package(s) that are required for your API, if any. +:::tip To create a unique plug-in + +Instead of the `diff` package, install the package(s) that are required for your API, if any. + +::: ## Creating a Node.js client-side API -Create a client-side API that compares the contents of two data sets on the mainframe. -Follow these steps: +Create a client-side API that compares the contents of two data sets on the mainframe: 1. In the `src/api` directory, create a file named `DataSetDiff.ts`. @@ -170,11 +184,15 @@ Follow these steps: When successful, the `index.ts` file contains the new code. -**To create a unique plug-in:** The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. +:::tip To create a unique plug-in + +The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. + +::: ## Building your plug-in source -To confirm that your project builds successfully: +Confirm that your project builds successfully: 1. Due to missing license headers, you will come across linting errors. Run `npm run lint:fix` to resolve the errors automatically. @@ -186,7 +204,11 @@ To confirm that your project builds successfully: The `lib` directory is configurable by modifying [this value](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/tsconfig.json#L12) in the `tsconfig.json` file. -**To create a unique plug-in:** Follow these same steps. +:::tip To create a unique plug-in + +Follow these same steps. + +::: ## Creating a Zowe CLI command @@ -275,17 +297,19 @@ If you are adding multiple commands to your CLI plug-in, consider moving the cod ::: -**To create a unique plug-in:** Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. +:::tip To create a unique plug-in + +Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. + +::: ## Trying your command Before you test your new command, confirm that you are able to connect to the mainframe. -In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Using profiles](../../user-guide/cli-using-using-team-profiles/) for information. +In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Team configurations](../../user-guide/cli-using-using-team-profiles/) for information. -Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time. - -Follow these steps: +Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time: 1. Repeat the steps in [Building your plug-in source](../extend-cli/cli-developing-a-plugin#building-your-plug-in-source). @@ -329,9 +353,13 @@ Follow these steps: When successful, the output displays plain text diffs of the entered data sets. -**To create a unique plug-in:** Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. +:::tip To create a unique plug-in -## Bringing together new tools! +Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. + +::: + +## Bringing together new tools You have created a simple CLI plug-in that provides plain text diffs of two data sets. But you may not want to end there. @@ -343,8 +371,6 @@ To help fix this, you can extend **Files Util Plug-in** to create a more visual |:--:| | Diff to HTML by [rtfpessoa](https://github.com/rtfpessoa)| -Follow these steps: - 1. Run `npm install --global diff2html-cli` to install `diff2html`. :::note diff --git a/docs/extend/extend-cli/cli-extending-a-plugin.md b/docs/extend/extend-cli/cli-extending-a-plugin.md index 9aad0e9832..bf2a8a7c65 100644 --- a/docs/extend/extend-cli/cli-extending-a-plugin.md +++ b/docs/extend/extend-cli/cli-extending-a-plugin.md @@ -1,86 +1,88 @@ # Extending a plug-in + Before you begin, be sure to complete the [Installing the sample plug-in](cli-installing-sample-plugin.md) tutorial. ## Overview -This tutorial demonstrates how to extend the plug-in that is bundled with this sample by: - -1. Creating a Typescript interface for the Typicode response data -2. Creating a programmatic API -3. Creating a command definition -4. Creating a command handler - -We'll do this by using `@zowe/imperative` infrastructure to surface REST API data on our Zowe™ CLI plug-in. +This tutorial uses the Typicode REST API as a guide for how to build a Zowe CLI plug-in that interacts with REST APIs on the mainframe. -Specifically, we're going to show data from [this URI](https://jsonplaceholder.typicode.com/todos) by [Typicode](https://jsonplaceholder.typicode.com/). -Typicode serves sample REST JSON data for testing purposes. +At the end of this tutorial, you are able to use the following new command from the Zowe CLI interface: -At the end of this tutorial, you will be able to use a new command from the Zowe CLI interface: `zowe zowe-cli-sample list typicode-todos` +``` +zowe zowe-cli-sample list typicode-todos +``` -Completed source for this tutorial can be found on the `typicode-todos` branch of the zowe-cli-sample-plugin repository. +The completed source for this tutorial can be found on the `typicode-todos` branch of the [`zowe-cli-sample-plugin`](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) repository. ### Creating a Typescript interface for the Typicode response data -First, we'll create a Typescript interface to map the response data from a server. +First, create a Typescript interface to map the response data from a server: -Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain our interface (sometimes referred to as a "document" or "doc"). Within the doc folder, create a file named `ITodo.ts`. +1. Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain the interface. The interface specifies the properties that we expect from the JSON response. -The `ITodo.ts` file will contain the following: +2. In the `doc` folder, create a file named `ITodo.ts`. -```typescript -export interface ITodo { - userId: number; - id: number; - title: string; - completed: boolean; -} -``` +3. Edit the `ITodo.ts` file to contain the following code: + + ```typescript + export interface ITodo { + userId: number; + id: number; + title: string; + completed: boolean; + } + ``` ### Creating a programmatic API -Next, we'll create a Node.js API that our command handler uses. This API can also be used in any Node.js application, because these Node.js APIs make use of REST APIs, Node.js APIs, other NPM packages, or custom logic to provide higher level functions than are served by any single API. +Next, create a Node.js API for the command handler to use. -Adjacent to the existing file named `zowe-cli-sample-plugin/src/api/Files.ts`, create a file `Typicode.ts`. +This API can also be used in any Node.js application. -`Typicode.ts`should contain the following: +1. Create a file named `Typicode.ts` in the `zowe-cli-sample-plugin/src/api` directory. -```typescript -import { ITodo } from "./doc/ITodo"; -import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; +2. Edit the `Typicode.ts` file to contain the following code: -export class Typicode { + ```typescript + import { ITodo } from "./doc/ITodo"; + import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; - public static readonly TODO_URI = "/todos"; + export class Typicode { - public static getTodos(session: AbstractSession): Promise
-Zowe consists of several components. The primary languages are Java and JavaScript. Zowe CLI and Desktop are written in TypeScript. ZSS is written in C, while the cross memory server is written in metal C. +Zowe consists of several components. The primary languages for API Mediation Layer are Java and JavaScript. Zowe CLI, Explorer for VSCode, and Desktop are written in TypeScript. Zowe Explorer plug-in for IntelliJ IDEA is written in Kotlin, ZSS is written in C, while the cross memory server is written in metal C.
-Zowe IntelliJ plug-in allows you to access and work with data sets, members and jobs directly from your IntelliJ-based IDE. +Zowe Explorer plug-in for IntelliJ IDEA allows you to access and work with data sets, members and jobs directly from your IntelliJ-based IDE, such as IntelliJ IDEA, PyCharm, Android Studio, etc.
@@ -521,42 +521,32 @@ Install the plug-in in your IntelliJ-based IDE directly from marketplace or down
-### Where can I use Zowe IntelliJ plug-in?
+### Where can I use Zowe Explorer plug-in for IntelliJ IDEA?
-You can use it in any IntelliJ-based IDE. +You can use it in any IntelliJ-based IDE, such as IntelliJ IDEA, PyCharm, Android Studio, etc.
-You can read detailed user guide and find any information you need [here](https://plugins.jetbrains.com/plugin/18688-zowe-explorer/user-guide). Also, you can ask any questions in the Zowe Slack channel [#zowe-explorer-intellij](https://openmainframeproject.slack.com/archives/C020BGPSU0M). +You can start with the [Use cases](../user-guide/intellij-use-cases.md) section to learn about use cases and how to install and use the plug-in. Also, you can ask any questions in our [Zowe Slack channel (#zowe-explorer-intellij)](https://openmainframeproject.slack.com/archives/C020BGPSU0M).
-To create a connection, expand plug-in panel on an IDE sidebar (on the right side of your screen) and press the "wrench" pictogram, or go to **File** -> **Settings** (CTRL+ALT+S), select **Zowe Explorer (Zowe IntelliJ plugin)** and then switch to the **z/OSMF connection** tab. Press the “+” button and fill inn all necessary fields. - -
-
-
diff --git a/docs/getting-started/zowe_v2_faq.md b/docs/getting-started/zowe_v2_faq.md
index 5d498f42e1..5970d3c32e 100644
--- a/docs/getting-started/zowe_v2_faq.md
+++ b/docs/getting-started/zowe_v2_faq.md
@@ -1,8 +1,8 @@
-# Zowe V2 FAQ
+# Zowe V2 FAQs
## Where can I find the V1 and V2 LTS conformance criteria?
-The Zowe Squads have prepared XLS spreadsheets with conformance criteria for all Zowe extensions including: CLI, APIs, App Framework, and Explorer for VS Code. The spreadsheets clearly show the prior / V1 criteria alongside the new / V2 criteria. Please be aware, there are additions, deletions, and CHANGES to the criteria. In some cases the change is simply that a BEST PRACTICE has been deemed REQUIRED. Use the included fill color key to identify new changes for V2, reworded changes, or changes from V1 removed in V2. See the Changes to the [Conformance Criteria](https://www.zowe.org/vnext#conformance-changes) section at Zowe.org/vNext.
+The Zowe Squads have prepared XLS spreadsheets with conformance criteria for all Zowe extensions including: CLI, APIs, App Framework, and Explorer for VS Code. The spreadsheets clearly show the prior / V1 criteria alongside the new / V2 criteria. Please be aware, there are additions, deletions, and CHANGES to the criteria. In some cases, the change is simply that a BEST PRACTICE has been deemed REQUIRED. Use the included fill color key to identify new changes for V2, reworded changes, or changes from V1 removed in V2. See the Changes to the [Conformance Criteria](https://www.zowe.org/vnext#conformance-changes) section at Zowe.org/vNext.
## Whats the difference between "server.json" and "example-zowe.yaml"?
@@ -16,7 +16,7 @@ For more information on Zowe setup and the yaml configuration, run the following
## What are the new default ports?
-Four of the default Zowe ports have changed: the app server, zss, the jobs API, and the files API. The new default app server port is 7556 (previously 8544) and the new zss port is 7557 (previously 8542). The new jobs API port is 7558 (previously 8545) and the new files API is 7559 (previously 8547). The JES/USS/MVS Explorer UI servers have been removed and thus no longer require port configurations.
+Four of the default Zowe ports have changed for the app server, and ZSS. The new default app server port is 7556 (previously 8544) and the new ZSS port is 7557 (previously 8542). The JES/USS/MVS Explorer UI servers have been removed, and thus no longer require port configurations.
## How do I access Zowe through the API Mediation Layer in V2?
diff --git a/docs/images/api-mediation/api-catalog.png b/docs/images/api-mediation/api-catalog.png
index 68032a4c36..8a75cb1ba1 100644
Binary files a/docs/images/api-mediation/api-catalog.png and b/docs/images/api-mediation/api-catalog.png differ
diff --git a/docs/images/common/Zowe-HA-Architecture-View.pptx b/docs/images/common/Zowe-HA-Architecture-View.pptx
index 7ebf17304a..9db8061e33 100644
Binary files a/docs/images/common/Zowe-HA-Architecture-View.pptx and b/docs/images/common/Zowe-HA-Architecture-View.pptx differ
diff --git a/docs/images/common/zowe-architecture-docker.png b/docs/images/common/zowe-architecture-docker.png
index 05079762d5..979be6e39f 100644
Binary files a/docs/images/common/zowe-architecture-docker.png and b/docs/images/common/zowe-architecture-docker.png differ
diff --git a/docs/images/common/zowe-architecture-ha copy.png b/docs/images/common/zowe-architecture-ha copy.png
new file mode 100644
index 0000000000..07a4d8085c
Binary files /dev/null and b/docs/images/common/zowe-architecture-ha copy.png differ
diff --git a/docs/images/common/zowe-architecture-ha.png b/docs/images/common/zowe-architecture-ha.png
index 05ebdd4bd0..37dfa4339a 100644
Binary files a/docs/images/common/zowe-architecture-ha.png and b/docs/images/common/zowe-architecture-ha.png differ
diff --git a/docs/images/common/zowe-architecture-k8s.png b/docs/images/common/zowe-architecture-k8s.png
index 7a7ae39ce4..5fec1a6a2d 100644
Binary files a/docs/images/common/zowe-architecture-k8s.png and b/docs/images/common/zowe-architecture-k8s.png differ
diff --git a/docs/images/common/zowe-architecture.png b/docs/images/common/zowe-architecture.png
index 5f11f0b012..5f5493a45e 100644
Binary files a/docs/images/common/zowe-architecture.png and b/docs/images/common/zowe-architecture.png differ
diff --git a/docs/images/common/zowe-architecture.pptx b/docs/images/common/zowe-architecture.pptx
index 1378135378..6bae9d9b28 100644
Binary files a/docs/images/common/zowe-architecture.pptx and b/docs/images/common/zowe-architecture.pptx differ
diff --git a/docs/images/intellij/actions_download_artifact.png b/docs/images/intellij/actions_download_artifact.png
new file mode 100644
index 0000000000..bf531808ab
Binary files /dev/null and b/docs/images/intellij/actions_download_artifact.png differ
diff --git a/docs/images/intellij/actions_select_build.png b/docs/images/intellij/actions_select_build.png
new file mode 100644
index 0000000000..3eaa68a3f8
Binary files /dev/null and b/docs/images/intellij/actions_select_build.png differ
diff --git a/docs/images/intellij/actions_select_workflow.png b/docs/images/intellij/actions_select_workflow.png
new file mode 100644
index 0000000000..fb9b5f7d63
Binary files /dev/null and b/docs/images/intellij/actions_select_workflow.png differ
diff --git a/docs/images/intellij/connection_create.gif b/docs/images/intellij/connection_create.gif
index 2ce0944f5d..d0d3f4a972 100644
Binary files a/docs/images/intellij/connection_create.gif and b/docs/images/intellij/connection_create.gif differ
diff --git a/docs/images/intellij/connection_zowe_config_v2.gif b/docs/images/intellij/connection_zowe_config_v2.gif
deleted file mode 100644
index 999a7445e5..0000000000
Binary files a/docs/images/intellij/connection_zowe_config_v2.gif and /dev/null differ
diff --git a/docs/images/intellij/copy_cut_member_copy.png b/docs/images/intellij/copy_cut_member_copy.png
new file mode 100644
index 0000000000..324e80469a
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy.png differ
diff --git a/docs/images/intellij/copy_cut_member_copy_dialog.png b/docs/images/intellij/copy_cut_member_copy_dialog.png
new file mode 100644
index 0000000000..91ccea06f9
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_member_copy_result.png b/docs/images/intellij/copy_cut_member_copy_result.png
new file mode 100644
index 0000000000..42ab971e12
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_result.png differ
diff --git a/docs/images/intellij/copy_cut_member_copy_select_paste.png b/docs/images/intellij/copy_cut_member_copy_select_paste.png
new file mode 100644
index 0000000000..1d484a1b31
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_select_paste.png differ
diff --git a/docs/images/intellij/copy_cut_member_cut.png b/docs/images/intellij/copy_cut_member_cut.png
new file mode 100644
index 0000000000..6321619672
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut.png differ
diff --git a/docs/images/intellij/copy_cut_member_cut_dialog.png b/docs/images/intellij/copy_cut_member_cut_dialog.png
new file mode 100644
index 0000000000..dcdef7913c
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png b/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png
new file mode 100644
index 0000000000..76264f5fee
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png differ
diff --git a/docs/images/intellij/copy_cut_member_cut_result_source.png b/docs/images/intellij/copy_cut_member_cut_result_source.png
new file mode 100644
index 0000000000..b3fabea85f
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_result_source.png differ
diff --git a/docs/images/intellij/copy_cut_member_cut_select_paste.png b/docs/images/intellij/copy_cut_member_cut_select_paste.png
new file mode 100644
index 0000000000..f1a8e2f4be
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_select_paste.png differ
diff --git a/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png b/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png
new file mode 100644
index 0000000000..f1db0ecdae
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_member_to_uss_copy_result.png b/docs/images/intellij/copy_cut_member_to_uss_copy_result.png
new file mode 100644
index 0000000000..729b5044b0
Binary files /dev/null and b/docs/images/intellij/copy_cut_member_to_uss_copy_result.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png
new file mode 100644
index 0000000000..9e5060b46e
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png
new file mode 100644
index 0000000000..905148130e
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png
new file mode 100644
index 0000000000..c0cac766b1
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png
new file mode 100644
index 0000000000..07e1334649
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut.png b/docs/images/intellij/copy_cut_pds_to_uss_cut.png
new file mode 100644
index 0000000000..8018c7e0bf
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png b/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png
new file mode 100644
index 0000000000..39e7c995ef
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png b/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png
new file mode 100644
index 0000000000..336a4776ff
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png differ
diff --git a/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png b/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png
new file mode 100644
index 0000000000..cb4973c54b
Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy.png b/docs/images/intellij/copy_cut_ps_to_pds_copy.png
new file mode 100644
index 0000000000..f1461fbef1
Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy.png differ
diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png
new file mode 100644
index 0000000000..15491181ff
Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png differ
diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png
new file mode 100644
index 0000000000..880fd44c6d
Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png
new file mode 100644
index 0000000000..68bf2f662f
Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut.png b/docs/images/intellij/copy_cut_uss_to_pds_cut.png
new file mode 100644
index 0000000000..8701ef2de2
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png
new file mode 100644
index 0000000000..c50cc946f5
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png
new file mode 100644
index 0000000000..cb7962a590
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png
new file mode 100644
index 0000000000..d4f0bd1f87
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png
new file mode 100644
index 0000000000..65fd5560d0
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png b/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png
new file mode 100644
index 0000000000..235e62cc36
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png b/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png
new file mode 100644
index 0000000000..ff35dccdaa
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut.png b/docs/images/intellij/copy_cut_uss_to_uss_cut.png
new file mode 100644
index 0000000000..ee9dfae668
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png b/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png
new file mode 100644
index 0000000000..3b970b3e81
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png b/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png
new file mode 100644
index 0000000000..a811ef2936
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png differ
diff --git a/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png b/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png
new file mode 100644
index 0000000000..2e8a64b9bc
Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png differ
diff --git a/docs/images/intellij/copy_mem_to_uss.gif b/docs/images/intellij/copy_mem_to_uss.gif
deleted file mode 100644
index 6fbfd5ff88..0000000000
Binary files a/docs/images/intellij/copy_mem_to_uss.gif and /dev/null differ
diff --git a/docs/images/intellij/create_connection_plus.png b/docs/images/intellij/create_connection_plus.png
new file mode 100644
index 0000000000..840180d026
Binary files /dev/null and b/docs/images/intellij/create_connection_plus.png differ
diff --git a/docs/images/intellij/create_connection_settings.png b/docs/images/intellij/create_connection_settings.png
new file mode 100644
index 0000000000..9cb325af0f
Binary files /dev/null and b/docs/images/intellij/create_connection_settings.png differ
diff --git a/docs/images/intellij/create_connection_zowe_config_file.gif b/docs/images/intellij/create_connection_zowe_config_file.gif
new file mode 100644
index 0000000000..3b0d6dbb1a
Binary files /dev/null and b/docs/images/intellij/create_connection_zowe_config_file.gif differ
diff --git a/docs/images/intellij/create_connection_zowe_config_plus.gif b/docs/images/intellij/create_connection_zowe_config_plus.gif
new file mode 100644
index 0000000000..587ddca3d2
Binary files /dev/null and b/docs/images/intellij/create_connection_zowe_config_plus.gif differ
diff --git a/docs/images/intellij/create_plugins_connection_or_zowe_config.png b/docs/images/intellij/create_plugins_connection_or_zowe_config.png
new file mode 100644
index 0000000000..0a035a61af
Binary files /dev/null and b/docs/images/intellij/create_plugins_connection_or_zowe_config.png differ
diff --git a/docs/images/intellij/cross_system_copy.gif b/docs/images/intellij/cross_system_copy.gif
deleted file mode 100644
index 156b4233ed..0000000000
Binary files a/docs/images/intellij/cross_system_copy.gif and /dev/null differ
diff --git a/docs/images/intellij/datasets_sort.png b/docs/images/intellij/datasets_sort.png
new file mode 100644
index 0000000000..8e11b57e76
Binary files /dev/null and b/docs/images/intellij/datasets_sort.png differ
diff --git a/docs/images/intellij/datasets_sort_result.png b/docs/images/intellij/datasets_sort_result.png
new file mode 100644
index 0000000000..857bbdfe79
Binary files /dev/null and b/docs/images/intellij/datasets_sort_result.png differ
diff --git a/docs/images/intellij/download_intellij.png b/docs/images/intellij/download_intellij.png
new file mode 100644
index 0000000000..c4bb2094c3
Binary files /dev/null and b/docs/images/intellij/download_intellij.png differ
diff --git a/docs/images/intellij/download_plugin_marketplace.png b/docs/images/intellij/download_plugin_marketplace.png
new file mode 100644
index 0000000000..67e3fa3343
Binary files /dev/null and b/docs/images/intellij/download_plugin_marketplace.png differ
diff --git a/docs/images/intellij/download_plugin_releases.png b/docs/images/intellij/download_plugin_releases.png
new file mode 100644
index 0000000000..469c24d4a4
Binary files /dev/null and b/docs/images/intellij/download_plugin_releases.png differ
diff --git a/docs/images/intellij/download_uss_copy.png b/docs/images/intellij/download_uss_copy.png
new file mode 100644
index 0000000000..b0a45906fd
Binary files /dev/null and b/docs/images/intellij/download_uss_copy.png differ
diff --git a/docs/images/intellij/download_uss_copy_final_dialog.png b/docs/images/intellij/download_uss_copy_final_dialog.png
new file mode 100644
index 0000000000..9e3ddc6597
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_final_dialog.png differ
diff --git a/docs/images/intellij/download_uss_copy_name_conflicts.png b/docs/images/intellij/download_uss_copy_name_conflicts.png
new file mode 100644
index 0000000000..f0a0ca03a1
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_name_conflicts.png differ
diff --git a/docs/images/intellij/download_uss_copy_paste.png b/docs/images/intellij/download_uss_copy_paste.png
new file mode 100644
index 0000000000..083dca4bd4
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_paste.png differ
diff --git a/docs/images/intellij/download_uss_copy_result.png b/docs/images/intellij/download_uss_copy_result.png
new file mode 100644
index 0000000000..d65071f499
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_result.png differ
diff --git a/docs/images/intellij/download_uss_copy_security_warning.png b/docs/images/intellij/download_uss_copy_security_warning.png
new file mode 100644
index 0000000000..fbe90227b9
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_security_warning.png differ
diff --git a/docs/images/intellij/download_uss_copy_single_conflict.png b/docs/images/intellij/download_uss_copy_single_conflict.png
new file mode 100644
index 0000000000..a94c4b7244
Binary files /dev/null and b/docs/images/intellij/download_uss_copy_single_conflict.png differ
diff --git a/docs/images/intellij/get_plugin.png b/docs/images/intellij/get_plugin.png
new file mode 100644
index 0000000000..92a415066b
Binary files /dev/null and b/docs/images/intellij/get_plugin.png differ
diff --git a/docs/images/intellij/install_from_bin_from_disk.png b/docs/images/intellij/install_from_bin_from_disk.png
new file mode 100644
index 0000000000..236f3e6bce
Binary files /dev/null and b/docs/images/intellij/install_from_bin_from_disk.png differ
diff --git a/docs/images/intellij/install_from_bin_restart.png b/docs/images/intellij/install_from_bin_restart.png
new file mode 100644
index 0000000000..55e43c3757
Binary files /dev/null and b/docs/images/intellij/install_from_bin_restart.png differ
diff --git a/docs/images/intellij/install_from_bin_search_for_zip.png b/docs/images/intellij/install_from_bin_search_for_zip.png
new file mode 100644
index 0000000000..9df91c8b38
Binary files /dev/null and b/docs/images/intellij/install_from_bin_search_for_zip.png differ
diff --git a/docs/images/intellij/install_in_intellij_after_install.png b/docs/images/intellij/install_in_intellij_after_install.png
new file mode 100644
index 0000000000..a5747d96e2
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_after_install.png differ
diff --git a/docs/images/intellij/install_in_intellij_corner_change.png b/docs/images/intellij/install_in_intellij_corner_change.png
new file mode 100644
index 0000000000..fad743bb00
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_corner_change.png differ
diff --git a/docs/images/intellij/install_in_intellij_marketplace.png b/docs/images/intellij/install_in_intellij_marketplace.png
new file mode 100644
index 0000000000..5c30f5da81
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_marketplace.png differ
diff --git a/docs/images/intellij/install_in_intellij_plugins.png b/docs/images/intellij/install_in_intellij_plugins.png
new file mode 100644
index 0000000000..facba91f00
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_plugins.png differ
diff --git a/docs/images/intellij/install_in_intellij_restart.png b/docs/images/intellij/install_in_intellij_restart.png
new file mode 100644
index 0000000000..c7d8190aec
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_restart.png differ
diff --git a/docs/images/intellij/install_in_intellij_search_and_install.png b/docs/images/intellij/install_in_intellij_search_and_install.png
new file mode 100644
index 0000000000..8f0d0a0f4c
Binary files /dev/null and b/docs/images/intellij/install_in_intellij_search_and_install.png differ
diff --git a/docs/images/intellij/intellij-install.gif b/docs/images/intellij/intellij-install.gif
deleted file mode 100644
index 10c06fb377..0000000000
Binary files a/docs/images/intellij/intellij-install.gif and /dev/null differ
diff --git a/docs/images/intellij/intellij_open_uss_file.png b/docs/images/intellij/intellij_open_uss_file.png
new file mode 100644
index 0000000000..0b32036819
Binary files /dev/null and b/docs/images/intellij/intellij_open_uss_file.png differ
diff --git a/docs/images/intellij/jes_jcl_edit.png b/docs/images/intellij/jes_jcl_edit.png
new file mode 100644
index 0000000000..f0a923106b
Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit.png differ
diff --git a/docs/images/intellij/jes_jcl_edit_after_refresh.png b/docs/images/intellij/jes_jcl_edit_after_refresh.png
new file mode 100644
index 0000000000..569a63f0b8
Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_after_refresh.png differ
diff --git a/docs/images/intellij/jes_jcl_edit_console.png b/docs/images/intellij/jes_jcl_edit_console.png
new file mode 100644
index 0000000000..e12ea9e9ba
Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_console.png differ
diff --git a/docs/images/intellij/jes_jcl_edit_refresh.png b/docs/images/intellij/jes_jcl_edit_refresh.png
new file mode 100644
index 0000000000..29e267c385
Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_refresh.png differ
diff --git a/docs/images/intellij/jes_jcl_edit_run_button.png b/docs/images/intellij/jes_jcl_edit_run_button.png
new file mode 100644
index 0000000000..34134795f7
Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_run_button.png differ
diff --git a/docs/images/intellij/jes_purge_click_purge.png b/docs/images/intellij/jes_purge_click_purge.png
new file mode 100644
index 0000000000..ac0a9b30db
Binary files /dev/null and b/docs/images/intellij/jes_purge_click_purge.png differ
diff --git a/docs/images/intellij/jes_purge_dialog.png b/docs/images/intellij/jes_purge_dialog.png
new file mode 100644
index 0000000000..41986de1e6
Binary files /dev/null and b/docs/images/intellij/jes_purge_dialog.png differ
diff --git a/docs/images/intellij/jes_purge_job_create_filter.png b/docs/images/intellij/jes_purge_job_create_filter.png
new file mode 100644
index 0000000000..499faf1924
Binary files /dev/null and b/docs/images/intellij/jes_purge_job_create_filter.png differ
diff --git a/docs/images/intellij/jes_purge_job_filter_dialog.png b/docs/images/intellij/jes_purge_job_filter_dialog.png
new file mode 100644
index 0000000000..1e5956cd88
Binary files /dev/null and b/docs/images/intellij/jes_purge_job_filter_dialog.png differ
diff --git a/docs/images/intellij/jes_purge_success_notification.png b/docs/images/intellij/jes_purge_success_notification.png
new file mode 100644
index 0000000000..23cc7cdba8
Binary files /dev/null and b/docs/images/intellij/jes_purge_success_notification.png differ
diff --git a/docs/images/intellij/jes_sort.png b/docs/images/intellij/jes_sort.png
new file mode 100644
index 0000000000..f14fbd4724
Binary files /dev/null and b/docs/images/intellij/jes_sort.png differ
diff --git a/docs/images/intellij/jes_sort_sorted.png b/docs/images/intellij/jes_sort_sorted.png
new file mode 100644
index 0000000000..4877f9db80
Binary files /dev/null and b/docs/images/intellij/jes_sort_sorted.png differ
diff --git a/docs/images/intellij/jes_spool_console.png b/docs/images/intellij/jes_spool_console.png
new file mode 100644
index 0000000000..6b0091b4fe
Binary files /dev/null and b/docs/images/intellij/jes_spool_console.png differ
diff --git a/docs/images/intellij/jes_spool_console_shown.png b/docs/images/intellij/jes_spool_console_shown.png
new file mode 100644
index 0000000000..56dab8b1d9
Binary files /dev/null and b/docs/images/intellij/jes_spool_console_shown.png differ
diff --git a/docs/images/intellij/jes_spool_view.png b/docs/images/intellij/jes_spool_view.png
new file mode 100644
index 0000000000..220a12ec28
Binary files /dev/null and b/docs/images/intellij/jes_spool_view.png differ
diff --git a/docs/images/intellij/jes_spool_view_editor.png b/docs/images/intellij/jes_spool_view_editor.png
new file mode 100644
index 0000000000..e85b47b21d
Binary files /dev/null and b/docs/images/intellij/jes_spool_view_editor.png differ
diff --git a/docs/images/intellij/jes_spool_view_reveal.png b/docs/images/intellij/jes_spool_view_reveal.png
new file mode 100644
index 0000000000..07c7f56706
Binary files /dev/null and b/docs/images/intellij/jes_spool_view_reveal.png differ
diff --git a/docs/images/intellij/jes_status.png b/docs/images/intellij/jes_status.png
new file mode 100644
index 0000000000..93eb89afb5
Binary files /dev/null and b/docs/images/intellij/jes_status.png differ
diff --git a/docs/images/intellij/move_mem_to_ds.gif b/docs/images/intellij/move_mem_to_ds.gif
deleted file mode 100644
index 5814436b3d..0000000000
Binary files a/docs/images/intellij/move_mem_to_ds.gif and /dev/null differ
diff --git a/docs/images/intellij/move_uss_folder_to_uss_folder.gif b/docs/images/intellij/move_uss_folder_to_uss_folder.gif
deleted file mode 100644
index cfe62346bf..0000000000
Binary files a/docs/images/intellij/move_uss_folder_to_uss_folder.gif and /dev/null differ
diff --git a/docs/images/intellij/move_uss_to_pds.gif b/docs/images/intellij/move_uss_to_pds.gif
deleted file mode 100644
index 0633c186f8..0000000000
Binary files a/docs/images/intellij/move_uss_to_pds.gif and /dev/null differ
diff --git a/docs/images/intellij/pds_copy_move_ds.gif b/docs/images/intellij/pds_copy_move_ds.gif
deleted file mode 100644
index 26d42b7d3c..0000000000
Binary files a/docs/images/intellij/pds_copy_move_ds.gif and /dev/null differ
diff --git a/docs/images/intellij/pds_move_zos_to_uss.gif b/docs/images/intellij/pds_move_zos_to_uss.gif
deleted file mode 100644
index 6cfedd82fd..0000000000
Binary files a/docs/images/intellij/pds_move_zos_to_uss.gif and /dev/null differ
diff --git a/docs/images/intellij/plugin_all_configurations.png b/docs/images/intellij/plugin_all_configurations.png
new file mode 100644
index 0000000000..4c3cd38e26
Binary files /dev/null and b/docs/images/intellij/plugin_all_configurations.png differ
diff --git a/docs/images/intellij/plugin_create_dataset.png b/docs/images/intellij/plugin_create_dataset.png
new file mode 100644
index 0000000000..831b9100d0
Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset.png differ
diff --git a/docs/images/intellij/plugin_create_dataset_fields.png b/docs/images/intellij/plugin_create_dataset_fields.png
new file mode 100644
index 0000000000..072797d042
Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset_fields.png differ
diff --git a/docs/images/intellij/plugin_create_dataset_ok.png b/docs/images/intellij/plugin_create_dataset_ok.png
new file mode 100644
index 0000000000..5d71cfcd35
Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset_ok.png differ
diff --git a/docs/images/intellij/plugin_create_mask_or_skip.png b/docs/images/intellij/plugin_create_mask_or_skip.png
new file mode 100644
index 0000000000..6e4721fc62
Binary files /dev/null and b/docs/images/intellij/plugin_create_mask_or_skip.png differ
diff --git a/docs/images/intellij/plugin_dataset_presets.png b/docs/images/intellij/plugin_dataset_presets.png
new file mode 100644
index 0000000000..ce73928c44
Binary files /dev/null and b/docs/images/intellij/plugin_dataset_presets.png differ
diff --git a/docs/images/intellij/plugin_open_settings.png b/docs/images/intellij/plugin_open_settings.png
new file mode 100644
index 0000000000..7088ae4f0c
Binary files /dev/null and b/docs/images/intellij/plugin_open_settings.png differ
diff --git a/docs/images/intellij/plugin_other_settings.png b/docs/images/intellij/plugin_other_settings.png
new file mode 100644
index 0000000000..baded2dec6
Binary files /dev/null and b/docs/images/intellij/plugin_other_settings.png differ
diff --git a/docs/images/intellij/plugin_save_before_close.png b/docs/images/intellij/plugin_save_before_close.png
new file mode 100644
index 0000000000..1f017dfd30
Binary files /dev/null and b/docs/images/intellij/plugin_save_before_close.png differ
diff --git a/docs/images/intellij/plugin_sync_button.png b/docs/images/intellij/plugin_sync_button.png
new file mode 100644
index 0000000000..db9bd7d4a7
Binary files /dev/null and b/docs/images/intellij/plugin_sync_button.png differ
diff --git a/docs/images/intellij/select_compatibility_and_channel.png b/docs/images/intellij/select_compatibility_and_channel.png
new file mode 100644
index 0000000000..7c5c32556d
Binary files /dev/null and b/docs/images/intellij/select_compatibility_and_channel.png differ
diff --git a/docs/images/intellij/tso_cli.gif b/docs/images/intellij/tso_cli.gif
deleted file mode 100644
index c7171ca53c..0000000000
Binary files a/docs/images/intellij/tso_cli.gif and /dev/null differ
diff --git a/docs/images/intellij/tso_console_create.png b/docs/images/intellij/tso_console_create.png
new file mode 100644
index 0000000000..1daa4c9aa7
Binary files /dev/null and b/docs/images/intellij/tso_console_create.png differ
diff --git a/docs/images/intellij/tso_console_created_console.png b/docs/images/intellij/tso_console_created_console.png
new file mode 100644
index 0000000000..1c8c6268af
Binary files /dev/null and b/docs/images/intellij/tso_console_created_console.png differ
diff --git a/docs/images/intellij/tso_console_dialog.png b/docs/images/intellij/tso_console_dialog.png
new file mode 100644
index 0000000000..1525860666
Binary files /dev/null and b/docs/images/intellij/tso_console_dialog.png differ
diff --git a/docs/images/intellij/tso_sessions_add.png b/docs/images/intellij/tso_sessions_add.png
new file mode 100644
index 0000000000..15fb226403
Binary files /dev/null and b/docs/images/intellij/tso_sessions_add.png differ
diff --git a/docs/images/intellij/tso_sessions_add_dialog.png b/docs/images/intellij/tso_sessions_add_dialog.png
new file mode 100644
index 0000000000..ffe0ab737f
Binary files /dev/null and b/docs/images/intellij/tso_sessions_add_dialog.png differ
diff --git a/docs/images/intellij/tso_sessions_created.png b/docs/images/intellij/tso_sessions_created.png
new file mode 100644
index 0000000000..71e8006fd6
Binary files /dev/null and b/docs/images/intellij/tso_sessions_created.png differ
diff --git a/docs/images/intellij/tso_sessions_go_to_sessions.png b/docs/images/intellij/tso_sessions_go_to_sessions.png
new file mode 100644
index 0000000000..7873e766da
Binary files /dev/null and b/docs/images/intellij/tso_sessions_go_to_sessions.png differ
diff --git a/docs/images/intellij/tso_sessions_wrench.png b/docs/images/intellij/tso_sessions_wrench.png
new file mode 100644
index 0000000000..f5173631b6
Binary files /dev/null and b/docs/images/intellij/tso_sessions_wrench.png differ
diff --git a/docs/images/intellij/upload_file_to_pds_copy.png b/docs/images/intellij/upload_file_to_pds_copy.png
new file mode 100644
index 0000000000..637f6747cb
Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy.png differ
diff --git a/docs/images/intellij/upload_file_to_pds_copy_dialog.png b/docs/images/intellij/upload_file_to_pds_copy_dialog.png
new file mode 100644
index 0000000000..fa1970f16c
Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_dialog.png differ
diff --git a/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png b/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png
new file mode 100644
index 0000000000..c9eb8b1281
Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png differ
diff --git a/docs/images/intellij/upload_file_to_pds_copy_paste.png b/docs/images/intellij/upload_file_to_pds_copy_paste.png
new file mode 100644
index 0000000000..0bba9a2a97
Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_paste.png differ
diff --git a/docs/images/intellij/upload_file_to_pds_copy_result.png b/docs/images/intellij/upload_file_to_pds_copy_result.png
new file mode 100644
index 0000000000..61dc37c715
Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_result.png differ
diff --git a/docs/images/intellij/uss_click_properties.png b/docs/images/intellij/uss_click_properties.png
new file mode 100644
index 0000000000..cbd70c1830
Binary files /dev/null and b/docs/images/intellij/uss_click_properties.png differ
diff --git a/docs/images/intellij/uss_encoding_dialog.png b/docs/images/intellij/uss_encoding_dialog.png
new file mode 100644
index 0000000000..bc92d23e74
Binary files /dev/null and b/docs/images/intellij/uss_encoding_dialog.png differ
diff --git a/docs/images/intellij/uss_encoding_select_option.png b/docs/images/intellij/uss_encoding_select_option.png
new file mode 100644
index 0000000000..ac0bdc918c
Binary files /dev/null and b/docs/images/intellij/uss_encoding_select_option.png differ
diff --git a/docs/images/intellij/uss_encoding_warning_dialog.png b/docs/images/intellij/uss_encoding_warning_dialog.png
new file mode 100644
index 0000000000..453900ad42
Binary files /dev/null and b/docs/images/intellij/uss_encoding_warning_dialog.png differ
diff --git a/docs/images/intellij/uss_properties_change_owner_perms.png b/docs/images/intellij/uss_properties_change_owner_perms.png
new file mode 100644
index 0000000000..7ec4383c90
Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms.png differ
diff --git a/docs/images/intellij/uss_properties_change_owner_perms_ok.png b/docs/images/intellij/uss_properties_change_owner_perms_ok.png
new file mode 100644
index 0000000000..2666ab3239
Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms_ok.png differ
diff --git a/docs/images/intellij/uss_properties_change_owner_perms_select.png b/docs/images/intellij/uss_properties_change_owner_perms_select.png
new file mode 100644
index 0000000000..6b80e9fdc2
Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms_select.png differ
diff --git a/docs/images/intellij/uss_properties_possible_changes.png b/docs/images/intellij/uss_properties_possible_changes.png
new file mode 100644
index 0000000000..5f7c490d37
Binary files /dev/null and b/docs/images/intellij/uss_properties_possible_changes.png differ
diff --git a/docs/images/intellij/uss_props_general_tab.png b/docs/images/intellij/uss_props_general_tab.png
new file mode 100644
index 0000000000..175dc06985
Binary files /dev/null and b/docs/images/intellij/uss_props_general_tab.png differ
diff --git a/docs/images/intellij/uss_sort.png b/docs/images/intellij/uss_sort.png
new file mode 100644
index 0000000000..63fd7c2190
Binary files /dev/null and b/docs/images/intellij/uss_sort.png differ
diff --git a/docs/images/intellij/uss_sort_result.png b/docs/images/intellij/uss_sort_result.png
new file mode 100644
index 0000000000..0efca33b57
Binary files /dev/null and b/docs/images/intellij/uss_sort_result.png differ
diff --git a/docs/images/intellij/work_with_jes_jobs.gif b/docs/images/intellij/work_with_jes_jobs.gif
deleted file mode 100644
index 74aa2f535a..0000000000
Binary files a/docs/images/intellij/work_with_jes_jobs.gif and /dev/null differ
diff --git a/docs/images/troubleshoot/cli/PowerShell_developer_setting.png b/docs/images/troubleshoot/cli/PowerShell_developer_setting.png
new file mode 100644
index 0000000000..e25f909823
Binary files /dev/null and b/docs/images/troubleshoot/cli/PowerShell_developer_setting.png differ
diff --git a/docs/images/troubleshoot/cli/home_struc.png b/docs/images/troubleshoot/cli/home_struc.png
index cb1a774e24..0582982585 100644
Binary files a/docs/images/troubleshoot/cli/home_struc.png and b/docs/images/troubleshoot/cli/home_struc.png differ
diff --git a/docs/images/troubleshoot/cli/home_struc_2.png b/docs/images/troubleshoot/cli/home_struc_2.png
new file mode 100644
index 0000000000..0582982585
Binary files /dev/null and b/docs/images/troubleshoot/cli/home_struc_2.png differ
diff --git a/docs/images/troubleshoot/intellij/intellij-find-plugin.png b/docs/images/troubleshoot/intellij/intellij-find-plugin.png
new file mode 100644
index 0000000000..7724b4354c
Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-find-plugin.png differ
diff --git a/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png b/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png
new file mode 100644
index 0000000000..6aaee8b312
Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png differ
diff --git a/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png
new file mode 100644
index 0000000000..bccadf7661
Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png differ
diff --git a/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png
new file mode 100644
index 0000000000..7bad12896b
Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png differ
diff --git a/docs/images/ze/ZE-uss-drag-drop.gif b/docs/images/ze/ZE-uss-drag-drop.gif
new file mode 100644
index 0000000000..6a2ff711f3
Binary files /dev/null and b/docs/images/ze/ZE-uss-drag-drop.gif differ
diff --git a/docs/images/zosmf/perform-workflows.jpg b/docs/images/zosmf/perform-workflows.jpg
deleted file mode 100644
index d03c33515f..0000000000
Binary files a/docs/images/zosmf/perform-workflows.jpg and /dev/null differ
diff --git a/docs/images/zosmf/perform-workflows.png b/docs/images/zosmf/perform-workflows.png
new file mode 100644
index 0000000000..ae878096ad
Binary files /dev/null and b/docs/images/zosmf/perform-workflows.png differ
diff --git a/docs/images/zosmf/workflow-componentsVariables.png b/docs/images/zosmf/workflow-componentsVariables.png
new file mode 100644
index 0000000000..2fce8ad7f9
Binary files /dev/null and b/docs/images/zosmf/workflow-componentsVariables.png differ
diff --git a/docs/images/zosmf/workflow-defineVariables.png b/docs/images/zosmf/workflow-defineVariables.png
new file mode 100644
index 0000000000..a7327615eb
Binary files /dev/null and b/docs/images/zosmf/workflow-defineVariables.png differ
diff --git a/docs/images/zosmf/workflow-zoweConfiguration.png b/docs/images/zosmf/workflow-zoweConfiguration.png
new file mode 100644
index 0000000000..de6ba9462e
Binary files /dev/null and b/docs/images/zosmf/workflow-zoweConfiguration.png differ
diff --git a/docs/troubleshoot/cli/cli-issue.md b/docs/troubleshoot/cli/cli-issue.md
index 557988016e..789a3d5888 100644
--- a/docs/troubleshoot/cli/cli-issue.md
+++ b/docs/troubleshoot/cli/cli-issue.md
@@ -1,6 +1,6 @@
# Raising a CLI issue on GitHub
-When necessary, you can raise GitHub issues against the Zowe™ CLI repository [here](https://github.com/zowe/zowe-cli/issues). It is suggested that you use either the bug or enhancement template.
+When necessary, raise a GitHub issue in the [Zowe™ CLI repository](https://github.com/zowe/zowe-cli/issues). It is suggested that you use either the bug or enhancement template.
## Raising a bug report
diff --git a/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md b/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md
index 8fdf6175a7..b1e1b6ad46 100644
--- a/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md
+++ b/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md
@@ -19,7 +19,11 @@ Add cURL options to establish communication between Zowe CLI and z/OSMF, as in t
```
curl --location --request - -If you have something to introduce but there is no related issue in the project repo, then you can either create the issue by yourself or contact us to help you with it. See more information in the [CONTRIBUTION.md](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md) file. +If you have ideas on how to improve the plug-in, or have an issue/bug fix in mind, visit the [contribution guide](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md). Also, you can ask for help in our [Zowe Slack channel (#zowe-explorer-intellij)](https://openmainframeproject.slack.com/archives/C020BGPSU0M).
- your operating system
- development environments
Required step when using a z/OSMF profile connection. | Systems programmer | 40 min. | +| (Optional) [Configuring z/OSMF security](../user-guide/cli-install-configure-zosmf-security.md) | Configure security for:
- SAF access to REST endpoints
- z/OS console REST interface
- z/OS data set and file REST services
+
+
+The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs.
+
+Install the extension directly to [VSCode](https://code.visualstudio.com/) to enable the extension within the GUI. Working with data sets and USS files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI experience. The extension provides the following benefits:
+
+- Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe.
+- Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe.
+- Provides a more streamlined way to access data sets, USS files, and jobs.
+- Lets you create, edit, and delete Zowe CLI `zosmf` compatible profiles.
+
+**Note:** Zowe Explorer is a subcomponent of [Zowe](https://zowe.org/home/). The extension demonstrates the potential for plug-ins powered by Zowe.
+
+## Software Requirements
+
+Ensure that you meet the following prerequisites before you use the extension:
+
+- Get access to z/OSMF.
+- Install [Visual Studio Code](https://code.visualstudio.com/).
+- Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](https://docs.zowe.org/stable/user-guide/systemrequirements-zosmf#z-os-requirements).
+- Create a Zowe CLI `zosmf` profile so that the extension can communicate with the mainframe.
+- For development, install [Node.js](https://nodejs.org/en/download/) v14.0 or later.
+
+### Profile notes:
+
+- You can use existing Zowe CLI `zosmf` profiles created with Zowe CLI v.2.0.0 or later.
+
+- Zowe CLI `zosmf` profiles that are created in Zowe Explorer can be interchangeably used in Zowe CLI.
+
+- *Optionally*, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see [Working with Zowe Explorer profiles](https://docs.zowe.org/stable/user-guide/ze-profiles#working-with-zowe-explorer-profiles).
+
+## Installing Zowe Explorer
+
+Use the following steps to install Zowe Explorer:
+
+1. Address [the software requirements](#software-requirements).
+2. Open Visual Studio Code, and navigate to the **Extensions** tab on the **Activity Bar**.
+3. Type `Zowe Explorer` in the **Search** field.
+
+ Zowe Explorer appears in the list of extensions in the **Side Bar**.
+
+4. Click the green **Install** button to install the extension.
+5. Restart Visual Studio Code.
+
+The extension is now installed and available for use.
+
+* **Note:** For information about how to install the extension from a `VSIX` file and run system tests on the extension, see the [Developer README](https://github.com/zowe/vscode-extension-for-zowe#build-locally).
+
+You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data sets.
+
+
+
+
+
+## Configuring Zowe Explorer
+
+Configure Zowe Explorer in the settings file of the extension.
+
+To access the extension settings, follow these steps:
+
+1. Click the **Settings** icon at the bottom of the **Activity Bar**.
+
+2. Select the **Settings** option.
+3. Open the **Extension** option listed in the **Commonly Used** menu.
+4. Select **Zowe Explorer** to access its settings.
+5. Scroll the list to find the setting that needs modification.
+
+### Modifying creation settings for data sets, USS files, and jobs
+
+Follow these steps:
+
+1. In Zowe Explorer settings, scroll to a data set, USS file, or job setting type.
+2. Click the setting's corresponding **Edit in settings.json** link.
+
+ This opens the `settings.json` file in an **Editor** tab. (The suggestions widget also opens if the functionality is enabled.)
+
+3. Edit the settings in the file as needed.
+4. Save the file to keep changes.
+
+ 
+
+### Modifying temporary file location settings
+
+Change the default folder location where temporary files are stored with the following steps:
+
+ 1. Navigate to Zowe Explorer settings.
+ 2. Under the data set, USS, or jobs settings that you want to edit, click the **Edit in settings.json** link.
+ 3. Modify the following definition in the file:
+
+ ```json
+ "zowe.files.temporaryDownloadsFolder": {
+ "folderPath": "/path/to/directory"
+ }
+ ```
+
+ Replace **/path/to/directory** with the new folder location.
+
+4. Save the file to keep the change.
+
+### Modifying the `Secure Credentials Enabled` setting
+
+When environment conditions do not support the Zowe CLI built-in Credential Manager, change the `Secure Credentials Enabled` setting with the following steps:
+
+ 1. Navigate to Zowe Explorer settings.
+ 2. Scroll to **Security: Secure Credentials Enabled**.
+ 3. Deselect the checkbox to disable secure credentials.
+
+ When disabled, if the `autoStore` setting in the `zowe.config.json` file is set to *true*, z/OS credentials are stored as text in the file.
+
+ If the `autoStore` setting is set to *false*, you are prompted for the missing credentials in Visual Studio Code. These are stored and used for the duration of the session.
+
+### Setting confirmation requirements for submitting jobs
+
+Submitting the wrong job can risk potential problems on your server. This can happen when the user enters the wrong job or inadvertently selects the **Submit Jobs** option.
+
+To help prevent this, enable the option to require confirmation before submitting a job. Once enabled, a dialog window asking for user confirmation displays when **Submit Jobs** is selected.
+
+
+
+To configure confirmation settings for submitting a job, follow these steps:
+
+1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor.
+
+2. Select the **User** or **Workspace** tab, depending on the settings you want to update.
+3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**.
+4. In the **Jobs: Confirm Submission** section, open the drop-down menu to select a different confirmation setting.
+ - If enabled, a confirmation dialog displays when a job matching the selected option is submitted.
+
+## Relevant Information
+
+In this section you can find useful links and other information relevant to Zowe Explorer that can improve your experience with the extension.
+
+- For information about how to develop for Eclipse Theia, see [Theia README](https://github.com/zowe/vscode-extension-for-zowe/wiki/Developing-for-Theia).
+- For information about how to create a VSCode extension for Zowe Explorer, see [VSCode extensions for Zowe Explorer](https://github.com/zowe/vscode-extension-for-zowe/wiki/Extending-Zowe-Explorer).
+
+- Visit the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) for questions and general guidance.
diff --git a/docs/user-guide/address-authentication-requirements.md b/docs/user-guide/address-authentication-requirements.md
index 48b2ba06f1..5534342e9e 100644
--- a/docs/user-guide/address-authentication-requirements.md
+++ b/docs/user-guide/address-authentication-requirements.md
@@ -15,8 +15,6 @@ Multi-factor authentication is provided by third-party products with which Zowe
To support the multi-factor authentication, it is necessary to apply z/OSMF APAR [PH39582](https://www.ibm.com/support/pages/apar/PH39582).
-For information about using MFA in Zowe Application Framework, see [Application Framework Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration).
-
:::important
Multi-factor authentication requires configuration with Single-Sign-On (SSO). Ensure that SSO is configured before you use MFA in Zowe.
@@ -24,14 +22,18 @@ Multi-factor authentication requires configuration with Single-Sign-On (SSO). En
## Single Sign On (SSO)
-Zowe has an SSO scheme with the goal that each time you use multiple Zowe components you should only be prompted to login once.
+Zowe has an SSO scheme with the goal that each time you use multiple Zowe components you should only be prompted to login once.
Requirements:
- IBM z/OS Management Facility (z/OSMF)
-For more information about single sign on (SSO), see [Zowe API Mediation Layer Single Sign On Overview](./api-mediation-sso).
+:::note Notes:
+- For more information about single sign on (SSO) for users, see [Zowe API Mediation Layer Single Sign On Overview](./api-mediation-sso.md).
+
+- For more information about single sign on (SSO) for extenders, see [Single Sign On Integration for Extenders](../extend/extend-apiml/api-medation-sso-integration-extenders.md).
+:::
## API Mediation Layer OIDC Authentication
diff --git a/docs/user-guide/address-network-requirements.md b/docs/user-guide/address-network-requirements.md
index 7ea8cd452a..16b94b1574 100644
--- a/docs/user-guide/address-network-requirements.md
+++ b/docs/user-guide/address-network-requirements.md
@@ -8,19 +8,57 @@ Values presented in the table are default values. You can change the values by u
For more information about variable names in the following table, see the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) in the References section.
+## Component Ports
+
+Most Components of Zowe are HTTPS servers. The ports of each and their default jobnames are listed below.
+The ports can be customized for each component by editing the value of `components.
diff --git a/docs/user-guide/api-mediation-metrics-service.md b/docs/user-guide/api-mediation-metrics-service.md
deleted file mode 100644
index 2dc6f192c0..0000000000
--- a/docs/user-guide/api-mediation-metrics-service.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Using Metrics Service (Technical Preview)
-
-As a system administrator, use the Metrics Service to view information about the acitivty of services running in the API Mediation Layer.
-Currently, only HTTP metrics are displayed for core API Mediation Layer services.
-
-In order for the Metrics Service to run, you must set `components.metrics-service.enabled` in `zowe.yaml` to `true`. Additionally, for each APIML service you want to have metrics collected for, you must set `components.
-
-To view the HTTP metrics for a service, select the corresponding tab in the Metrics Service dashboard. Metrics are displayed for each endpoint of a service, aggregated from all service instances.
-
-**Example:**
-
-
-
-Metrics are provided on a near real-time basis, so the display shows the current activity of the selected service. At this time there is no persistence for this information.
-
-Service instances expose their HTTP metrics at `https://
-
+
2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z.
- **PKCS12**
@@ -244,12 +222,11 @@ The following commands are examples of establishing a trust relationship between
- **Keyring**
- For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs:
-
- Click here for command details for RACF.
+ For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1": - - **For RACF:** +
+
-
- Click here for command details for RACF.
+ - **For RACF:** ``` RACDCERT ADD('SHARE.SYSY.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert Root CA') TRUST @@ -177,17 +158,15 @@ The following commands are examples of establishing a trust relationship between SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH ``` - Verify: - ``` - RACDCERT LISTRING(ZoweKeyring) ID(ZWESVUSR) - ``` - -
-
- - **For ACF2:**
+ Click here for command details for ACF2.
+ Verify: + ``` + RACDCERT LISTRING(ZoweKeyring) ID(ZWESVUSR) + ``` +
+
-
- Click here for command details for ACF2.
+ - **For ACF2:** ``` ACF @@ -202,17 +181,16 @@ The following commands are examples of establishing a trust relationship between F ACF2,REBUILD(USR),CLASS(P),DIVISION(KEYRING) ``` - Verify: - ``` - SET PROFILE(USER) DIVISION(KEYRING) - LIST LIKE(ZWESVUSR.-) - ``` -
-
- - **For TopSecret:**
+ Click here for command details for Top Secret.
+ Verify: + ``` + SET PROFILE(USER) DIVISION(KEYRING) + LIST LIKE(ZWESVUSR.-) + ``` +
+
-
+ Verify:
+ ```
+ TSS LIST(ZWESVUSR) KEYRING(ZOWERING)
+ ```
+ Click here for command details for Top Secret.
+ - **For Top Secret:** ``` TSS ADD(CERTAUTH) DCDS(SHARE.SYSY.ROOTCA.CER) DIGICERT(SYSYROOT) LABLCERT('DigiCert Root CA') TRUST @@ -221,12 +199,12 @@ The following commands are examples of establishing a trust relationship between TSS ADD(ZWESVUSR) KEYRING(ZOWERING) RINGDATA(CERTAUTH,SYSZINTR) USAGE(CERTAUTH) ``` - Verify: - ``` - TSS LIST(ZWESVUSR) KEYRING(ZOWERING) - ``` -
-
-
- Click here for command details for RACF.
+ For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs: - - **For RACF:** +
+
- Click here for command details for RACF.
+ - **For RACF:** ``` RACDCERT ADD('SHARE.SYSX.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('Local CA') TRUST @@ -261,13 +238,11 @@ The following commands are examples of establishing a trust relationship between ``` RACDCERT LISTRING(ZoweKeyring) ID(ZWESVUSR) ``` +
-
+ Click here for command details for ACF2.
- - - **For ACF2:** +
+
- Click here for details for ACF2.
+ - **For ACF2:** ``` ACF @@ -285,13 +260,12 @@ The following commands are examples of establishing a trust relationship between SET PROFILE(USER) DIVISION(KEYRING) LIST LIKE(ZWESVUSR.-) ``` +
+
You completed certificates setup for multitenancy configuration, whereby registered API MLs can trust the API ML where they are registered and vice versa.
-## Using the `/registry` endpoint in the Gateway
+## Using the `/registry` endpoint in the Central Cloud Gateway
+The `/registry` endpoint provides information about services onboarded to all registered Gateways. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint.
The `/registry` endpoint provides information about services onboarded to all registered Gateways. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint.
### Configuration for `/registry`
+The `/registry` endpoint is disabled by default. Use the configuration property `apiml.gateway.registry.enabled=true` or
+environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this feature.
The `/registry` endpoint is disabled by default. Use the configuration property `apiml.gateway.registry.enabled=true` or
environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this feature.
@@ -336,19 +312,19 @@ Unsuccessful authorization returns a 403 error code.
There are two endpoints that provide information about services registered to the API ML. One endpoint is for all APIMLs, and the other endpoint is for the specific APIML. Choose from the following **GET** calls:
-* `GET /gateway/api/v1/registry`
-This request lists services in all APIMLs.
+* **`GET /gateway/api/v1/registry`**
+This request lists services in all API MLs.
-* `GET /gateway/api/v1/registry/{apimlId}`
-This request lists services in the APIML of the specific apimlId given.
+* **`GET /gateway/api/v1/registry/{apimlId}`**
+This request lists services in the API ML of the specific apimlId given.
-* `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`
- This request gets the specific service from the APIML in the specific apimlId.
+* **`GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`**
+ This request gets the specific service from the API ML in the specific apimlId.
### Response with `/registry`
Click here for command details for Top Secret.
-
-
+ Click here for command details for Top Secret.
- - - **For Top Secret:** + - **For Top Secret:** ``` TSS ADD(CERTAUTH) DCDS(SHARE.SYSX.ROOTCA.CER) DIGICERT(SYSXROOT) LABLCERT('Local CA') TRUST @@ -302,17 +276,19 @@ The following commands are examples of establishing a trust relationship between ``` TSS LIST(ZWESVUSR) KEYRING(ZOWERING) ``` - -
-
### Response with `/registry{apimlId}`
-This response should contain information about all services in an APIML with the specific apimlId.
+This response should contain information about all services in an API ML with the specific apimlId.
Click here for an example response with `/registry`.
+Click here for an example of the response with /registry
**Example:** @@ -399,15 +375,14 @@ This request lists services in the APIML of the specific apimlId given. } ] ``` -
-:7555`.
+For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service).
-## Caching service
+## Extending API ML by Onboarding new APIs
+The most important part of the ecosystem are the real API services that provide useful APIs. Use the following topics to understand what options you have for adding new APIs to the Mediation Layer:
-The Caching service aims to provide an API which offers the possibility to store, retrieve and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The URL of the Caching service is `https://:7555`.
-For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service).
+* [Onboarding Overview](../../extend/extend-apiml/onboard-overview.md)
diff --git a/docs/user-guide/api-mediation/api-mediation-update-password.md b/docs/user-guide/api-mediation/api-mediation-update-password.md
index 441ba50a9a..eb514234d2 100644
--- a/docs/user-guide/api-mediation/api-mediation-update-password.md
+++ b/docs/user-guide/api-mediation/api-mediation-update-password.md
@@ -51,8 +51,4 @@ Use the following request body format in the `POST` REST call against the URL `/
"password" : "",
"newPassword" : ""
}
-```
-
-:::note
-In order to use the password change functionality via z/OSMF, it is necessary to install the PTF for APAR PH34912.
-:::
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md
index 8826744317..42663d6946 100644
--- a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md
+++ b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md
@@ -6,6 +6,8 @@
You can use API Mediation Layer to generate, validate, and invalidate a **Personal Access Token (PAT)** that can enable access to tools such as VCS without having to use credentials of a specific person. The use of PAT does not require storing mainframe credentials as part of the automation configuration on a server during application development on z/OS.
Additionally, using a PAT makes it possible to limit access to specific services and users by means of token revocation when using a token.
+To enable the Personal Access Token functionality read: [Enable Personal Access Token](./configuration-personal-access-token.md)
+
Gateway APIs are available to both users as well as security administrators.
APIs for users can accomplish the following functions:
diff --git a/docs/user-guide/api-mediation/configuration-client-certificates.md b/docs/user-guide/api-mediation/configuration-client-certificates.md
index d3fc86a751..fa5ec70a03 100644
--- a/docs/user-guide/api-mediation/configuration-client-certificates.md
+++ b/docs/user-guide/api-mediation/configuration-client-certificates.md
@@ -6,9 +6,9 @@
You can authenticate against API ML onboarded APIs. This functionality is disabled by default. Follow the steps in this article to enable authentication against API ML onboarded APIs.
There are two methods to enable client certificate functionality:
-* The original and default method via ZSS
-* The newer and recommended method via the internal mapper component of API Mediation Layer
+* The default and recommended method via the internal mapper component of API Mediation Layer
The internal API ML mapper is simpler to configure and provides more functionality than ZSS.
+* The older and deprecated method via ZSS
Review this article to learn about the required configuration to authenticate with either method.
@@ -64,7 +64,7 @@ Ensure that you have the Issuer certificate imported in the truststore or in the
:::
:::tip
-There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, and are using Zowe v2.14 or a later version, use the recommended internal API ML mapper.
+There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, use the recommended internal API ML mapper.
:::
### Enabling zowe.yaml to use a client certificate
diff --git a/docs/user-guide/api-mediation/configuration-connection-limits.md b/docs/user-guide/api-mediation/configuration-connection-limits.md
index 93083dd415..b80a941b9c 100644
--- a/docs/user-guide/api-mediation/configuration-connection-limits.md
+++ b/docs/user-guide/api-mediation/configuration-connection-limits.md
@@ -33,8 +33,7 @@ zowe:
Use the following procedure to change the limits:
1. Open the file `zowe.yaml`.
-2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds).
-3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway will wait for the graceful stopping of the WebSocket connection. The default is 30 seconds (30000 milliseconds).
-4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds).
-5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds).
-6. Find or add the property `zowe.components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K.
+2. Find or add the property `components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds).
+3. Find or add the property `components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds).
+4. Find or add the property `components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds).
+5. Find or add the property `components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K.
diff --git a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md
index 1f167ab8c5..84591b468b 100644
--- a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md
+++ b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md
@@ -17,6 +17,7 @@ Specifies one of the following services:
- `discovery`
- `caching-service`
- `api-catalog`
+ - `zaas`
**Example with Gateway Service:**
diff --git a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md
index a08edb2bd5..715ed4a317 100644
--- a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md
+++ b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md
@@ -13,7 +13,3 @@ As a system programmer, you can customize your configuration for how API ML mana
* To customize the rate limit for each service, see [Customizing Gateway rate limiter](./customizing-gateway-rate-limiter.md).
- * Also see the following properties in API Gateway configuration parameters:
- * `server.maxTotalConnections`
- * `server.maxConnectionsPerRoute`
-
diff --git a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md
index e411f822ce..7658e54c8e 100644
--- a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md
+++ b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md
@@ -13,7 +13,7 @@ As a system administrator, you can customize the API Catalog UI to have a simila
It is possible to customize the logotype and selected style options directly in `zowe.yaml`.
1. Open the file `zowe.yaml`.
-2. Configure the following properties by setting them under `ZWE_configs_apiml_catalog_customStyles`:
+2. Configure the following properties by setting them under `configs.apiml.catalog.customStyles`:
- **logo**
Specifies the location of the logo that will replace the default Zowe logo in the API Catalog header. The supported image formats are: `svg`, `png` and `jpg/jpeg`.
@@ -68,9 +68,6 @@ Nothing is displayed on the Gateway home page and the Catalog is removed from `/
- **alternative-catalog**
An alternative to the API Catalog is displayed
-- **metrics-dashboard**
- A possible dashboard that could appear in place of the API Catalog
-
:::note Notes:
- If the application contains the `homePageUrl` and `statusPageRelativeUrl`, then the full set of information is displayed.
- If the application contains the `homePageUrl` the link is displayed without the `UP` information.
diff --git a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md
index 1a19517c58..fcd62fb230 100644
--- a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md
+++ b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md
@@ -3,7 +3,7 @@
:::info Role: system programmer
:::
-You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are reuqired to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups.
+You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are required to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups.
Use the following procedure to distribute the load balancer cache between instances of the API Gateway.
diff --git a/docs/user-guide/api-mediation/configuration-extender-passtickets.md b/docs/user-guide/api-mediation/configuration-extender-passtickets.md
index 1e154704a9..05646518bf 100644
--- a/docs/user-guide/api-mediation/configuration-extender-passtickets.md
+++ b/docs/user-guide/api-mediation/configuration-extender-passtickets.md
@@ -4,7 +4,7 @@ One option to enable single sign-on (SSO) to your extending REST API services is
:::info Required Role: security administrator
:::
-
+
## Overview of PassTickets
API clients can use various supported methods to access an API service such as a Zowe JWT token or a client certificate even if the API service itself does not support the JWT token or a client certificate. An intermediary for support of JWT or a client certificate can be through the use of PassTickets.
@@ -14,10 +14,10 @@ The API Gateway uses the PassTicket to access that API service. The API Gateway
## Configuring Zowe to use PassTickets
-Configuring Zowe to use PassTickets involves two processes:
+Configuring Zowe to use PassTickets involves two processes:
-- Enabling the use of PassTickets in your External Security Manager (ESM)
-- Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service
+1. Enabling the use of PassTickets in your External Security Manager (ESM)
+2. Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service
### Enabling the use of PassTickets in your External Security Manager (ESM)
@@ -29,87 +29,95 @@ Since the Zowe 2.17 release, it is no longer necessary to disable replay protect
This section applies to users who do not already have PassTickets enabled in the system, or users who need to define a PassTicket for a new APPLID. If you already have an APPLID that you intend to use to define your API service, skip to the section [Configuring security to allow the Zowe API Gateway to generate PassTickets for an API service](#configuring-security-to-allow-zowe-api-gateway-to-generate-passtickets-for-an-api-service).
:::tip
-To validate if a PassTicket is already defined, list the APPL and PKTDATA with a command corresponding to your ESM. Output indicates if a PassTicket is already defined. No results after issuing an ESM command indicates that a PassTicket is not defined. If a PassTicket is defined, the access of the zoweuser can be determined.
-
-- **Validating an existing PassTicket for ACF2**
+To validate if a PassTicket is already defined, list the APPL and PTKTDATA with a command corresponding to your ESM. Output indicates if a PassTicket is already defined. No results after issuing an ESM command indicates that a PassTicket is not defined. If a PassTicket is defined, the access of the ZWESVUSR can be determined.
- ADD(UID() ALLOW)
+ F ACF2,REBUILD(APL)
+ ```
+2. In your ESM command line interface or other security environment, define the application session key by entering the following commands if the session key is not already defined.
```acf2
- SET PROFILE(PTKTDATA) DIV(SSIGNON)
- INSERT SSKEY()
- F ACF2,REBUILD(PTK),CLASS(P)
+ SET PROFILE(PTKTDATA) DIV(SSIGNON)
+ INSERT SSKEY()
+ F ACF2,REBUILD(PTK),CLASS(P)
```
* **`applid`**
@@ -135,7 +150,7 @@ Specifies the application ID used for PassTicket validation to authenticate conn
* **`key-description`**
Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.
-2. Complete the PassTicket setup by entering the following commands:
+3. Complete the PassTicket setup by entering the following commands:
```acf2
F ACF2,REBUILD(PTK),CLASS(P)
@@ -143,7 +158,7 @@ Specifies the application ID used for PassTicket validation to authenticate conn
The PassTicket record is now active in the system.
-3. Enable the started task user ID to generate PassTickets for the application by entering commands similar to the following:
+4. Enable the started task user ID to generate PassTickets for the application by entering commands similar to the following:
```
SET RESOURCE(PTK)
@@ -164,7 +179,7 @@ You configured Zowe to use PassTickets for single sign on using ACF2.
) PTKTDATA(IRRPTAUTH)
```
-
+- **`department`**
+ Specifies the department for `PTKTDATA(IRRPTAUTH)`. The default department is `TSODEPT1`.
+
3. Define PassTicket for application ID _applid_:
```tss
@@ -245,14 +262,20 @@ Specifies the application ID used for PassTicket validation to authenticate conn
3. Define the profile for the application with the following command:
```
- RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED() APPLDATA('NO REPLAY PROTECTION')
+ RDEFINE PTKTDATA UACC(NONE) APPLDATA('NO REPLAY PROTECTION') SSIGNON(KEYMASKED())
```
* **`key-description`**
Specifies the secured sign-on hexadecimal application key of 16 hexadecimal digits (8-byte or 64-bit key). Each application key must be the same on all systems in the configuration and the values must be kept secret and secured.
4. Replace `key-description` with the application name defined previously.
-5. Allow the application ID (_applid_) to use PassTickets:
+5. Define the profile `IRRPTAUTH` in `PTKTDATA` class for the ``
+
+ ```racf
+ RDEFINE PTKTDATA IRRPTAUTH..* UACC(NONE)
+ ```
+
+6. Allow the application ID (_applid_) to use PassTickets:
```racf
PERMIT IRRPTAUTH.applid.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid)
@@ -261,7 +284,7 @@ Specifies the application ID used for PassTicket validation to authenticate conn
* **`userid`**
Specifies the value of the LDAP Server started task.
-6. Refresh the RACF PTKTDATA definition with the new profile:
+7. Refresh the RACF PTKTDATA definition with the new profile:
```
SETROPTS RACLIST(PTKTDATA) REFRESH
```
@@ -279,7 +302,7 @@ Specify the following variables when generating PassTickets for the API service
* **`applid`**
The APPLID value used by the API service for PassTicket support (for example, `OMVSAPPL`)
-* **`zowe-user-id`**
+* **`zowe-user-id`**
The Zowe started task user ID used during the Zowe installation
@@ -335,6 +358,7 @@ Grant the Zowe started task user ID permission to generate PassTickets for users
**Example:**
```racf
+ RDEFINE PTKTDATA IRRPTAUTH..* UACC(NONE)
PERMIT IRRPTAUTH..* CL(PTKTDATA) ID() ACCESS(UPDATE)
SETROPTS RACLIST(PTKTDATA) REFRESH
```
@@ -343,11 +367,21 @@ Grant the Zowe started task user ID permission to generate PassTickets for users
### Verifying your PassTicket Application
-In your ESM command line interface or other security environment, execute the following commands:
+In your ESM command line interface or other security environment, execute the commands that correspond to your ESM:
-```racf
- RLIST APPL ALL
- RLIST PTKTDATA IRRPTAUTH..* ALL
+#### Verifying PassTickets using ACF2
+
+.lo
- `discovery`
- `api-catalog`
- `caching-service`
- - `cloud-gateway`
- - `metrics-service`
+ - `zaas`
**Example with Gateway Service:**
diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md
index 2da06c406a..8a76a31ed0 100644
--- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md
+++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md
@@ -1,10 +1,9 @@
# Configuring routing in a multi-tenant environment
-In a multi-sysplex environment, both the domain-specific Discovery Service as well as one or more additional Discovery services may require registration with the Discovery Service in the domain which gathers information about all installed API Gateways in isolated sysplex environments.
+In a multi-sysplex environment, both the domain-specific Discovery Service as well as one or more additional Discovery Services may require registration with the Discovery Service in the domain which gathers information about all installed API Gateways in isolated sysplex environments.
The domain-specific Discovery Service is typically in the same LPAR in a multi-sysplex environment. However, the API Gateway in API ML in one domain (for example in Domain API ML 2) may also need to register with the API ML Discovery Service in a separate domain (for example in Domain API ML 1), which gathers information about all installed API Gateways in isolated sysplex environments. After registration, data from the Discovery Service in Domain API ML 1 can be used by the Gateway in Domain API ML 2 for routing to individual API Gateways.
-
Follow these steps to register with additional Discovery Services:
1. Open the `zowe.yaml` configuration file.
diff --git a/docs/user-guide/api-mediation/configuration-personal-access-token.md b/docs/user-guide/api-mediation/configuration-personal-access-token.md
index afe3a147da..890a9d7a71 100644
--- a/docs/user-guide/api-mediation/configuration-personal-access-token.md
+++ b/docs/user-guide/api-mediation/configuration-personal-access-token.md
@@ -10,18 +10,17 @@ Review this article for steps that enable single sign on via Personal Access Tok
To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution.
-To enable this storage method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section. For more information on these properties and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration).
+To enable this storage method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. For more information on other properties for infinispan and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration).
``` yaml
- zowe
- components:
- caching-service:
- storage:
- mode: infinispan
- infinispan:
- jgroups:
- port: 7098
+ components:
+ caching-service:
+ storage:
+ mode: infinispan
+ infinispan:
+ jgroups:
+ port: 7098
```
## Enabling Personal Access Tokens
diff --git a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md
index 59f962b5ac..0331445d2a 100644
--- a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md
+++ b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md
@@ -3,9 +3,9 @@
:::info Role: API service extender
:::
-As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix with Zowe v2.
+As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix.
For more information, see the following parameter in the article Discovery Service configuration parameters:
* **components.discovery.apiml.discovery.serviceIdPrefixReplacer**
- This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with v2, based on Zowe v2 conformance.
\ No newline at end of file
+ This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with.
\ No newline at end of file
diff --git a/docs/user-guide/api-mediation/configuration-unique-cookie-name-for-multiple-zowe-instances.md b/docs/user-guide/api-mediation/configuration-unique-cookie-name-for-multiple-zowe-instances.md
index f704fdc04a..681a65a3d6 100644
--- a/docs/user-guide/api-mediation/configuration-unique-cookie-name-for-multiple-zowe-instances.md
+++ b/docs/user-guide/api-mediation/configuration-unique-cookie-name-for-multiple-zowe-instances.md
@@ -8,11 +8,14 @@ To prevent overwriting of the default cookie name in the case of multiple Zowe i
Follow this procedure to configure a unique cookie name for the instances:
-1. Open the `zowe.yaml` configuration file.
-2. Find or add the property `components.gateway.apiml.security.auth.uniqueCookie`, and set it to `true`. A unique cookie name is generated as `apimlAuthenticationToken.cookieIdentifier`.
+1. Open the Zowe YAML configuration file.
+2. Find or add the property `components.gateway.apiml.security.auth.uniqueCookie`, and set it to `true`.
+3. Find the property `zowe.cookieIdentifier` and set it to any word or number that you wish to identify your Zowe instance.
+4. Restart Zowe.
+
+This sets a suffix for the API Gateway's cookie name based upon the value of `zowe.cookieIdentifier`.
**Example:**
- If this parameter is set to `true`, and the cookieIdentifier is `1`, the name of the cookie transforms to `apimlAuthenticationToken.1`.
- If this property is not set to `true`, the cookie name remains `apimlAuthenticationToken` by default.
+ If the `components.gateway.apiml.security.auth.uniqueCookie` parameter is set to `true` and `zowe.cookieIdentifier` is `1`, the cookie name is `apimlAuthenticationToken.1`.
+ If this property is not set to `true`, the cookie name remains the default value `apimlAuthenticationToken`.
-3. Restart Zowe.
\ No newline at end of file
diff --git a/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V2.svg b/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V2.svg
index fe3109729c..d053f15473 100644
--- a/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V2.svg
+++ b/docs/user-guide/api-mediation/diagrams/multi-domain_architecture_V2.svg
@@ -1 +1,1536 @@
-
\ No newline at end of file
+
+
+
\ No newline at end of file
diff --git a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png
index ddf6741773..65886a4144 100644
Binary files a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png and b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png differ
diff --git a/docs/user-guide/api-mediation/discovery-service-configuration.md b/docs/user-guide/api-mediation/discovery-service-configuration.md
index e5b50218e9..2b38398331 100644
--- a/docs/user-guide/api-mediation/discovery-service-configuration.md
+++ b/docs/user-guide/api-mediation/discovery-service-configuration.md
@@ -2,7 +2,7 @@
## Zowe runtime configuration parameters
-As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `/components/discovery/bin/start.sh` file:
+As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `zowe.yaml` file:
* **[API ML configuration](#api-ml-configuration)**
@@ -13,24 +13,24 @@ As an application developer who wants to run Zowe, set the following parameters
1. Open the file `zowe.yaml`.
2. Configure the following properties:
-* **apiml.service.hostname**
+* **haInstance.hostname**
- This property is used to set the Discovery Service hostname. The value can be set by defining the `ZWE_haInstance_hostname` property in the `zowe.yaml` file.
+ This property is used to set the Discovery Service hostname. The value can be set by defining the `haInstance.hostname` property in the `zowe.yaml` file.
-* **apiml.service.port**
+* **components.discovery.port**
- This property is used to set the Discovery Service port. The value can be set by defining the `ZWE_configs_port` property in the `zowe.yaml` file.
+ This property is used to set the Discovery Service port. The value can be set by defining the `components.discovery.port` property in the `zowe.yaml` file.
-* **apiml.discovery.staticApiDefinitionsDirectories**
+* **environments.ZWE_STATIC_DEFINITIONS_DIR**
- The value of `apiml.discovery.staticApiDefinitionsDirectories` can be set by defining the `ZWE_STATIC_DEFINITIONS_DIR` property in `zowe.yaml`. The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services.
+ The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services.
**Example:**
```yaml
- ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs
+ environments:
+ ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs
```
-* **apiml.discovery.allPeersUrls**
+* **environments.ZWE_DISCOVERY_SERVICES_LIST**
- The value of `apiml.discovery.allPeersUrls` can be set by defining the `ZWE_DISCOVERY_SERVICES_LIST` property in `zowe.yaml`.
This parameter contains the list of URLs of the Discovery Service in case of multiple instances of the service on different host.
**Example:**
```yaml
diff --git a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md
index a9bcb49c03..79d97e32f8 100644
--- a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md
+++ b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md
@@ -84,8 +84,6 @@ The configuration entries of each LPAR in the `zowe.yaml` file control which com
The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex, are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so that each instance behaves similarly to the user irrespective of where their request is routed.
-For simplification of the preceding diagram, the Jobs and Files API servers are not shown as being started. If the user defines Jobs and Files API servers to be started in the `zowe.yaml` configuration file, these servers behave the same as the servers that are illustrated. In other words, these services register to their API discovery server which then communicates with other discovery servers on other Zowe instances on either the same or other LPARs. The API traffic received by any API Gateway on any Zowe instance is routed to any of the Jobs or Files API components that are available.
-
To learn more about Zowe with high availability enablement, see [Configuring Sysplex for high availability](../configure-sysplex).
## API Versioning
diff --git a/docs/user-guide/api-mediation/use-graphql-api.md b/docs/user-guide/api-mediation/use-graphql-api.md
index f0c7f9d429..3ed3b5fa21 100644
--- a/docs/user-guide/api-mediation/use-graphql-api.md
+++ b/docs/user-guide/api-mediation/use-graphql-api.md
@@ -1,15 +1,18 @@
# Using GraphQL APIs
-GraphQL is a query language for APIs that provides descriptions of the data in your APIs, and allows for specific queries to facilitate API development. Routing for such APIs is possible within the Zowe ecosystem, however at the present time, Zowe itself does not provide any GraphQL APIs.
+GraphQL is a query language for APIs that provides descriptions of the data in your APIs, and allows for specific queries to facilitate API development. Routing for such APIs is possible within the Zowe ecosystem, however at the present time, Zowe itself does not provide any GraphQL APIs.
For more information about configuring routing to API ML, see the following articles:
+
* [Implementing routing to the Gateway](../../extend/extend-apiml/implementing-routing-to-the-api-gateway)
* [Routing Requests to REST API](./routing-requests-to-rest-apis)
:::tip
+
* For information about how to use GraphQL, see [GraphQL Best Practices](https://graphql.org/learn/best-practices/) in the GraphQL product documentation.
* For information about how to use HTTP to deliver the GraphQL interface, see [Serving over HTTP](https://graphql.org/learn/serving-over-http/) in the GraphQL product documentation.
+
:::
## Difference between GraphQL APIs and traditional REST APIs
@@ -67,10 +70,9 @@ GraphQL supports subscriptions, which allow clients to subscribe to real-time up
- **Strongly Typed**
GraphQL APIs are strongly typed so that every operation is checked and validated against the schema, leading to more reliable and predictable APIs.
-## Limitations for the API Mediation Layer
+## Displaying GraphQL in API Catalog
-The documentation for the GraphQL is not provided via the standard OpenAPI protocol, but rather, for the most part are living as a sandbox environment within the GraphQL applications.
+Since Zowe v3, it is possible to configure the service to display an interactive documentation UI inside the API Catalog services' detail page.
-:::tip
-The API Catalog currently does not support visualization of GraphQL APIs. As such, we recommend that extenders provide a link to the GraphQL endpoint via the Open API for the API Catalog.
-:::
\ No newline at end of file
+This capability is enabled in the API Catalog by default.
+It requires the service to onboard to the Discovery Service with `apiml.apiInfo.api-.graphqlUrl` set to the endpoint where the service exposes the GraphQL API.
diff --git a/docs/user-guide/api-mediation/using-api-mediation-layer.md b/docs/user-guide/api-mediation/using-api-mediation-layer.md
index 7109547051..c96d2c5f9b 100644
--- a/docs/user-guide/api-mediation/using-api-mediation-layer.md
+++ b/docs/user-guide/api-mediation/using-api-mediation-layer.md
@@ -68,6 +68,5 @@ There are various options for using the API Catalog:
### Additional use case when usig API Mediation Layer
-* [Using Metrics Service (Technical Preview)](../api-mediation-metrics-service)
* [SMF records](./api-mediation-smf)
diff --git a/docs/user-guide/api-mediation/using-multi-factor-authentication.md b/docs/user-guide/api-mediation/using-multi-factor-authentication.md
index 021216d115..0b11516171 100644
--- a/docs/user-guide/api-mediation/using-multi-factor-authentication.md
+++ b/docs/user-guide/api-mediation/using-multi-factor-authentication.md
@@ -25,7 +25,7 @@ Update the z/OSMF configuration with the following parameter:
`allowBasicAuthLookup="false"`
After applying this change, each authentication call results in generating a new JWT.
-For more information, see [Configuring z/OSMF](../systemrequirements-zosmf.md) to properly work with API ML, and [Multi-factor authentication configuration](../mvd-configuration.md#multi-factor-authentication-configuration) in Configuring Zowe Application Framework.
+For more information, see [Configuring z/OSMF](../systemrequirements-zosmf.md) to properly work with API ML.
### No Notification when Additional Input is Required
diff --git a/docs/user-guide/api-mediation/wto-message-on-startup.md b/docs/user-guide/api-mediation/wto-message-on-startup.md
new file mode 100644
index 0000000000..ada571d80a
--- /dev/null
+++ b/docs/user-guide/api-mediation/wto-message-on-startup.md
@@ -0,0 +1,108 @@
+# Configuring initial API Mediation Layer startup message for Syslog
+
+:::info Role: system programmer
+:::
+
+:::note Functionality of this feature is available from Zowe 2.18.
+:::
+
+Startup of the API Mediation Layer can be configured to present a message in the Syslog that the API Mediation Layer is started and ready. This setup is typically used in combination with Workload Automation tools to manage the lifecycle of Zowe.
+
+This functionality requires the following changes to the zowe.yaml:
+
+1. Change the property `zowe.sysMessages` by adding the value `- "ZWEAM001I"`
+ ```
+ zowe:
+ # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+ # You can define any Zowe message portions to be checked for and the message added to the
+ # system log upon its logging, truncated to 126 characters.
+ sysMessages:
+ - "ZWEAM001I"
+ ```
+ This property change ensures that the message containing `ZWEAM001I` is presented in the Syslog.
+
+ **Example of the Syslog:**
+
+ `2024-09-30 10:17:53.814 jb892003 INFO ((o.z.a.g.c.GatewayHealthIndicator)) ZWEAM001I API Mediation Layer started`
+
+2. Prepare custom logging configuration.
+ The current default logging implementation starts with information about the current time. This message content is unlike the message id which is typical in z/OS. To change this message behavior, it is necessary to change the logback.xml configuration. The following example shows the custom logback.xml which prepends the message with the first 9 characters of the message.
+
+ **Example:**
+
+ ```
+
+
+
+
+
+
+
+ 0
+
+
+
+
+
+
+ ${apimlLogPattern}
+
+
+
+
+
+ ${STORAGE_LOCATION}/${logbackServiceName}.log
+
+
+ ${STORAGE_LOCATION}/${logbackServiceName}.%i.log
+ ${MIN_INDEX}
+ ${MAX_INDEX}
+
+
+
+ ${MAX_FILE_SIZE}
+
+
+
+
+ ${apimlLogPattern}
+
+
+
+
+
+
+
+ ```
+ Custom configuration that changes the structure of the message to prepend 9 characters to the beginning is prepared.
+
+ :::tip
+ For detailed information about how to provide this changed configuration, see [Customizing Zowe API Mediation Layer logging](./configuration-logging.md).
+ :::
+
+3. Validate that API Mediation Layer properly uses this new configuration for the Gateway service, which issues the message that the API Mediation Layer started.
+
+ ```
+ components:
+ gateway:
+ logging:
+ config: /path/to/logback.xml
+ ```
+
+You successfully changed the structure of the log message if you see the message `ZWEAM001I` in the Syslog when the API Mediation Layer fully starts and is ready to handle requests.
+
+**Message example:**
+`ZWEAM001I 2024-09-30 10:17:53.814 jb892003 INFO ((o.z.a.g.c.GatewayHealthIndicator)) ZWEAM001I API Mediation Layer started`
diff --git a/docs/user-guide/assign-security-permissions-to-users.md b/docs/user-guide/assign-security-permissions-to-users.md
index 20323ddaac..700ede0f6c 100644
--- a/docs/user-guide/assign-security-permissions-to-users.md
+++ b/docs/user-guide/assign-security-permissions-to-users.md
@@ -15,16 +15,16 @@ The following user IDs run Zowe:
* **ZWESVUSR**
This is the started task ID of the Zowe runtime user who runs most of the Zowe core
- components.
- To work with USS, this user ID must have a valid OMVS segment. For more information about OMVS segments, see the
- article _The OMVS segment in user profiles_ in the IBM documentation. For detailed information about which permissions
- are
- required to run Zowe core services as well as specific individual components, see
- the [Security Permissions Reference Table](#security-permissions-reference-table) in this article.
+ components.
+
* **ZWESIUSR**
This user runs the cross memory server (ZIS). This is a started task ID used to run the PROCLIB `ZWESISTC` that
- launches the [cross memory server (ZIS)](./configure-xmem-server.md). This started task ID must have a valid OMVS
- segment.
+ launches the [cross memory server (ZIS)](./configure-xmem-server.md).
+
+:::caution Important!
+To work with USS, the user ID must have a valid OMVS segment. For more information about OMVS segments, see the article _The OMVS segment in user profiles_ in the IBM documentation. For detailed information about which permissions are required to run Zowe core services as well as specific individual components, see the [Security Permissions Reference Table](#security-permissions-reference-table) in this article.
+
+:::
The security administrator also assigns permissions to the security group **ZWEADMIN**. `ZWEADMIN` is a group
consisting of `ZWESVUSR` and `ZWESIUSR`. This group must have a valid OMVS segment.
@@ -58,8 +58,6 @@ see [zwe init security](../appendix/zwe_server_command_reference/zwe/init/zwe-in
| ZSS | CSFSERV | `Multiple` | READ | Generate symmetric keys using ICSF that is used by [Zowe Desktop cookies](./configure-zos-system.md#configure-an-icsf-cryptographic-services-environment). | The list of IDs to enable include `CSF1TRD` , `CSF1TRC` , `CSF1SKE` , `CSF1SKD`. The full list of IDs is described in the z/OS Cryptographic Services user guide for your z/OS release level: [2.2](https://www.ibm.com/docs/en/zos/2.2.0?topic=ssl-racf-csfserv-resource-requirements), [2.3](https://www.ibm.com/docs/en/zos/2.3.0?topic=ssl-racf-csfserv-resource-requirements), [2.4](https://www.ibm.com/docs/en/zos/2.4.0?topic=ssl-racf-csfserv-resource-requirements) and [2.5](https://www.ibm.com/docs/en/zos/2.5.0?topic=ssl-racf-csfserv-resource-requirements). | | | | | |
| Cross memory server (ZIS) | FACILITY | `ZWES.IS` | READ | Allow Zowe ZWESLSTC processes to access the Zowe ZIS cross memory server. | This parameter permits the Zowe main server to use ZIS cross memory server. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | - - ## Granting users permission to access z/OSMF Each TSO user ID that logs on to Zowe and uses Zowe services that use z/OSMF requires permission to access these z/OSMF services. It is necessary that every user ID be added to the group with the appropriate z/OSMF privileges, `IZUUSER` or `IZUADMIN` (default). @@ -75,12 +73,20 @@ You can skip this section if you use Zowe without z/OSMF. Zowe can operate with To grant permissions to the user ID to access z/OSMF, issue the command(s) that corresponds to your ESM. +. DSNAME('') LABEL(
Click here for an example response with `/registry{apimlId}`.
+Click here for an example response
**Example:** @@ -452,7 +427,7 @@ This response should contain information about all services in an APIML with the This response should contain information about a specific service in an APIML with the specific apimlId.
-
## Validating successful configuration with `/registry`
diff --git a/docs/user-guide/api-mediation/api-mediation-overview.md b/docs/user-guide/api-mediation/api-mediation-overview.md
index 5857138d42..0b12957d25 100644
--- a/docs/user-guide/api-mediation/api-mediation-overview.md
+++ b/docs/user-guide/api-mediation/api-mediation-overview.md
@@ -1,14 +1,14 @@
# 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 consists of three components: the Gateway, the Discovery Service, and the Catalog. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner.
+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 consists of four components: the Gateway, the Discovery Service, the Catalog and the Caching Service. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner. The Caching Service provides stateful storage of key/value pairs.
## Key features
* Consistent Access: API routing and standardization of API service URLs through the Gateway component provides users with a consistent way to access mainframe APIs at a predefined address.
-* Dynamic Discovery: The Discovery Service automatically determines the location and status of API services.
* High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind.
* Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration.
* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility.
* Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services.
+* Service registry: Registry of available services with the status of the services.
## API Mediation Layer architecture
The following diagram illustrates the single point of access through the Gateway, and the interactions between API ML components and services:
@@ -24,27 +24,21 @@ Services that comprise the API ML service ecosystem are located behind a gateway
### Discovery Service
-The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology.
-
-#### Discovery Service TLS/SSL
-
-HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables hightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered.
+The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology.
### API Catalog
-The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability.
+The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service.
-#### Catalog Security
-
Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the zOSMF API.
-## Onboarding APIs
-The most important part of the ecosystem are the real API services that provide useful APIs. Use the following topics to understand what options you have for adding new APIs to the Mediation Layer:
+### Caching service
-* [Onboarding Overview](../../extend/extend-apiml/onboard-overview.md)
+The Caching service aims to provide an API which offers the possibility to store, retrieve and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The URL of the Caching service is `https://Click here for an example of a response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}`.
+Click here for an example response
**Example:** @@ -467,7 +442,7 @@ This response should contain information about a specific service in an APIML wi "status": "UP", "customMetadata": { "zos.sysname": "sys2", - "zos.sysplex": "sysplex" + "zos.sysplex": "sysplex" }, "apiId": [ "zowe.apiml.catalog" @@ -478,7 +453,6 @@ This response should contain information about a specific service in an APIML wi } ] ``` -
+**Validating an existing PassTicket for ACF2**
-
-- **Validating an existing PassTicket for Top Secret**
+**Validating an existing PassTicket for Top Secret**
- Click here for command details about validating an existing PassTicket for ACF2.
+
- In your ESM command line interface or other security environment, execute the following commands:
+-)
+1. Issue a `SHOW CLASMAP` command in TSO ACF to verify if the APPL resource is defined in the GSO. Note the 3 character type code associated with APPL. If APPL does not appear in the `SHOW CLASMAP` listing, run the following commands:
- SET PROFILE(PTKTDATA) DIVISION(SSIGNON)
- LIST LIKE(-)
+ ```acf2
+ SET CONTROL(GSO)
+ INSERT CLASMAP.appl RESOURCE(APPL) RSRCTYPE(APL)
+ F ACF2,REFRESH(CLASMAP)
+ ```
- SET RESOURCE(PTK)
- LIST LIKE(IRRPTAUTH-)
+2. Replace 'APL' with the type code listed in the `SHOW CLASMAP` output:
+ ```
+ SET RESOURCE(APL)
+ LIST LIKE(-)
+ ```
+3. Verify if PTKTDATA is defined, by executing the following commands:
+ ```
+ SET PROFILE(PTKTDATA) DIVISION(SSIGNON)
+ LIST LIKE(-)
+ SET RESOURCE(PTK)
+ LIST LIKE(IRRPTAUTH-)
```
- - **`-`**
- A wildcard symbol that lists all resources
+- **`-`**
+ A wildcard symbol that lists all resources
- - **`-`**
- Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)
+- **`-`**
+ Lists everything related to specified applid in a resource (in this case, SAF), or specified in a profile (in this case, PTKTDATA)
-
+Click here for procedure details about validating an existing PassTicket for ACF2.
- ```acf2 - SET RESOURCE(SAF) - LIST LIKE(-) +In your ESM command line interface or other security environment, perform the following steps: - SET RESOURCE(SAF) - LIST LIKE(
+
-- **Validating an existing PassTicket for RACF**
+**Validating an existing PassTicket for RACF**
-
- )
- TSS WHOHAS PTKTDATA()
- TSS WHOHAS PTKTDATA(IRRPTAUTH..)
+ TSS WHOHAS APPL()
+ TSS WHOHAS PTKTDATA()
+ TSS WHOHAS PTKTDATA(IRRPTAUTH..)
```
+2. If APPL and PTKTDATA are not yet defined, follow the steps to create them as described in the [Enabling PassTickets with Top Secret](#enabling-passtickets-with-top-secret) section.
- - **`.`**
- A wildcard symbol that lists all resources
+- **`.`**
+ A wildcard symbol that lists all resources
- - **`IRRPTAUTH..`**
- Returns everything about the specified applid for IRRPTAUTH
+- **`IRRPTAUTH..`**
+ Returns everything about the specified applid for IRRPTAUTH
-
+Click here for command details about validating an existing PassTicket for Top Secret.
+Click here for command details about validating an existing PassTicket for Top Secret.
- In your ESM command line interface or other security environment, execute the following commands: +1. In your ESM command line interface or other security environment, execute the following commands: ```tss - TSS WHOHAS APPL(
+
:::
@@ -121,12 +129,19 @@ Follow these steps to enable PassTicket Support specific to your ESM.
- ALL
- RLIST PTKTDATA SSIGNON ALL
- RLIST PTKTDATA IRRPTAUTH..* ALL
+ RLIST APPL * ALL
+ RLIST APPL ALL
+ RLIST PTKTDATA SSIGNON ALL
+ RLIST PTKTDATA IRRPTAUTH..* ALL
```
- Ensure that you validate PKTDATA access for APPL.
+Ensure that you validate PTKTDATA access for APPL.
- - **`*`**
- A wildcard symbol that resturns all resources
+- **`*`**
+ A wildcard symbol that resturns all resources
- - **`RLIST PTKTDATA SSIGNON ALL`**
- Validates all applid for PTKDATA class
+- **`RLIST PTKTDATA SSIGNON ALL`**
+ Validates all applid for PTKDATA class
- - **`RLIST PTKTDATA IRRPTAUTH..* ALL`**
- Validates all applid permissions for PTKDATA class
+- **`RLIST PTKTDATA IRRPTAUTH..* ALL`**
+ Validates all applid permissions for PTKDATA class
-
+Click here for command details about validating an existing PassTicket for RACF.
+Click here for command details about validating an existing PassTicket for RACF.
- In your ESM command line interface or other security environment, execute the following commands: +In your ESM command line interface or other security environment, execute the following commands: ```racf - RLIST APPL * ALL - RLIST APPLClick here for command details about configuring Zowe to use PassTickets using ACF2.
-1. In your ESM command line interface or other security environment, define the application session key by entering the following commands, if the session key is not already defined. +1. Issue the `SHOW CLASMAP` command in TSO ACF to identity the 3 character type code associated with APPL. Replace 'APL' with the type code listed in the `SHOW CLASMAP` output: + + ```acf2 + SET RESOURCE(APL) + RECKEYClick here for command details about configuring Zowe to use PassTickets using Top Secret.
-Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUT`) have not already been defined as described in the previous tip. +Before you begin this procedure, verify that the `PTKTDATA` class and ownership for the PassTicket resource (`IRRPTAUTH`) have not already been defined as described in the previous tip. 1. Update the resource descriptor table (RDT) to define the `PTKTDATA` class by entering the following commands: @@ -181,11 +196,13 @@ Before you begin this procedure, verify that the `PTKTDATA` class and ownership Include `RESCODE(n)` in the range of 101 to 13F to make `PTKTDATA` a prefixed resource class. ::: -2. Assign ownership for the PassTicket resource (`IRRPTAUT`). Execute the following commands: +2. Assign ownership for the PassTicket resource (`IRRPTAUTH`). Execute the following commands: ``` - TSS ADDTO(department) PTKTDATA(IRRPTAUT) + TSS ADDTO(
+-)
+SET RESOURCE(PTK)
+LIST LIKE(IRRPTAUTH-)
```
* **`applid`**
@@ -355,6 +389,34 @@ Specifies the application ID used for PassTicket validation to authenticate conn
Successful execution of this validation command shows your application and the specific access of the application.
+
+
+#### Verifying PassTickets using Top Secret
+
+Click here for command details for ACF2.
+ +**ACF2:** + +Replace 'APL' with the type code listed in the `SHOW CLASMAP` output: +```acf2 +SET RESOURCE(APL) +LIST LIKE(
+)
+TSS WHOHAS PTKTDATA(IRRPTAUTH.)
+```
+
+
+
+#### Verifying PassTickets using RACF
+
+Click here for command details for Top Secret.
+ +**TSS:** +```tss +TSS WHOHAS APPL(
+ ALL
+ RLIST PTKTDATA IRRPTAUTH..* ALL
+```
+
+
+
**Output example:**
```
CLASS NAME
diff --git a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md
index 593ffb6cdf..0601201083 100644
--- a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md
+++ b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md
@@ -8,35 +8,22 @@ Use the following procedure to change the global timeout value for an API Mediat
1. Open the file `zowe.yaml`.
2. Configure the following properties:
- * **components.gateway.apiml.gateway.timeoutmillis**
- This property defines the global value for http/ws client timeout.
-
- :::note
- Ribbon configures the client that connects to the routed services.
- :::
- * **components.gateway.ribbon.connectTimeout**
+ * **components.gateway.apiml.connectTimeout**
Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used.
+ * **components.gateway.apiml.connection.idleConnectionTimeoutSeconds**
- * **components.gateway.ribbon.readTimeout**
- Specifies the time in milliseconds of inactivity between two packets in response from this service to API ML. If omitted, the default value specified in the API ML Gateway service configuration is used.
-
- * **components.gateway.ribbon.connectionManagerTimeout**
- The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP connection manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to persistent connections. Internally, the connections that are managed serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period during which managed connections with API ML should be established. The value is in milliseconds. If omitted, the default value specified in the API ML Gateway service configuration is used.
-
- * **components.gateway.httpclient.requestConnectionTimeout**
- Specifies the HTTP Client Request Connection Timeout for southbound services from the API Gateway. This setting defines the period that the API Gateway waits for a response from the southbound server before issuing a connection refused response. The value is in milliseconds. An example value of a 30 second connection timeout would be 30000.
+ * **components.gateway.apiml.connection.timeToLive**
**Example:**
```yaml
components:
gateway:
- ribbon:
+ apiml:
connectTimeout: 30000
- readTimeout: 60000
- connectionManagerTimeout: 45000
- httpclient:
- requestConnectionTimeout: 60000
+ connection:
+ idleConnectionTimeoutSeconds:
+ timeToLive:
```
3. Restart Zowe.
diff --git a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md
index 2e0c05e4ae..c1a7032f22 100644
--- a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md
+++ b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md
@@ -1,43 +1,48 @@
-# Configuring API Gateway Health Check Protection
+# Configuring Health Check Protection
:::info Role: system programmer
:::
-As a system programmer, you can configure the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. Enabling protection for the health check endpoint can enhance the security of the API Gateway by restricting access to sensitive status information about the Gateway.
+As a system programmer, you can disable the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. In Zowe V2, authentication was not required. Disabling protection for the health check endpoint can limit the security of the API Gateway by allowing access to sensitive status information about the Gateway.
Use the following procedure to set the value of the health check endpoint of the API Gateway:
1. Open the file `zowe.yaml`.
2. Configure the following property:
-* `components.gateway.apiml.gateway.health.protected`
+* `components.gateway.apiml.health.protected`
This property defines whether the health check endpoint is accessible with or without authentication.
:::note
-The default value of this parameter is `false`. We recommend setting this parameter to `true` for production environments.
+The default value of this parameter is `true`.
:::
**Example:**
```yaml
-zowe:
- components:
+components:
gateway:
- apiml:
- gateway:
- health:
- protected: true
+ apiml:
+ gateway:
+ health:
+ protected: true
```
-In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. This ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users.
+In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. Requiring authentication ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users.
To allow open access to the health check endpoint, set the parameter to `false`. Setting this parameter to `false` permits access to this endpoint without authentication. In this case, anyone can access the health check endpoint and obtain information about the status of the Gateway.
+* `components.discovery.apiml.health.protected`
+ This property defines whether the health check endpoint on Discovery service is accessible with or without authentication.
+* `components.apiCatalog.apiml.health.protected`
+ This property defines whether the health check endpoint on API Catalog is accessible with or without authentication.
+
+
## Environment Recommendations
When setting this parameter, we recommend applying the following values according to your environment:
* **In Production Environments**
-It is recommended to set `apiml.gateway.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status.
+It is recommended to set `components.*.apiml.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. This is the default.
* **In Development/Testing Environments**
- setting `apiml.gateway.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging.
+ setting `components.*.apiml.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging.
diff --git a/docs/user-guide/api-mediation/configuration-jwt.md b/docs/user-guide/api-mediation/configuration-jwt.md
index 02caa0cc4d..f85c5b81cd 100644
--- a/docs/user-guide/api-mediation/configuration-jwt.md
+++ b/docs/user-guide/api-mediation/configuration-jwt.md
@@ -5,10 +5,11 @@
As a system programmer, you can customize how JWT authentication is performed, the service that provides the JWT authentication token, whether it's possible to refresh JWT token and other characteristics of JWT for consumption.
-* [Using SAF as an authentication provider](#using-saf-as-an-authentication-provider)
-* [Enabling a JWT token refresh endpoint](#enabling-a-jwt-token-refresh-endpoint)
-* [Authorization](#authorization)
-* [Additional customizable properties when using JWT tokens](#additional-customizable-properties-when-using-jwt-tokens)
+- [Enabling single sign on for clients via JWT token configuration](#enabling-single-sign-on-for-clients-via-jwt-token-configuration)
+ - [Using SAF as an authentication provider](#using-saf-as-an-authentication-provider)
+ - [Enabling a JWT token refresh endpoint](#enabling-a-jwt-token-refresh-endpoint)
+ - [Authorization](#authorization)
+ - [Additional customizable properties when using JWT tokens](#additional-customizable-properties-when-using-jwt-tokens)
## Using SAF as an authentication provider
@@ -65,7 +66,7 @@ Authorization is used to set the access rights of an entity.
In the API ML, authorization is performed by any of the following z/OS security managers:
* [ACF2](https://www.broadcom.com/products/mainframe/identity-access/acf2)
* [IBM RACF](https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zsecurity/zsecc_042.htm)
-* [Top Secret](https://www.broadcom.com/products/mainframe/identity-access/top-secret).
+* [Top Secret](https://www.broadcom.com/products/mainframe/security/top-secret).
An authentication token is used as proof of valid authentication. The authorization checks, however, are always performed by the z/OS security manager.
@@ -74,7 +75,7 @@ An authentication token is used as proof of valid authentication. The authorizat
You can also customize the following properties when authenticating with a JWT token:
* **components.gateway.apiml.security.auth.zosmf.ServiceId**
- This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `zosmf`.
+ This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `ibmzosmf`.
* **components.gateway.apiml.security.auth.tokenProperties.expirationInSeconds**
This property is relevant only when the JWT is generated by the API Mediation Layer and specifies to the time before expiration.
diff --git a/docs/user-guide/api-mediation/configuration-logging.md b/docs/user-guide/api-mediation/configuration-logging.md
index 51c11f3b37..04c384e529 100644
--- a/docs/user-guide/api-mediation/configuration-logging.md
+++ b/docs/user-guide/api-mediation/configuration-logging.md
@@ -10,8 +10,7 @@ To change the default logback configuration file, set `components.Click here for command details for RACF
+ +**RACF:** +```racf + RLIST APPL• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | - - ## Granting users permission to access z/OSMF Each TSO user ID that logs on to Zowe and uses Zowe services that use z/OSMF requires permission to access these z/OSMF services. It is necessary that every user ID be added to the group with the appropriate z/OSMF privileges, `IZUUSER` or `IZUADMIN` (default). @@ -75,12 +73,20 @@ You can skip this section if you use Zowe without z/OSMF. Zowe can operate with To grant permissions to the user ID to access z/OSMF, issue the command(s) that corresponds to your ESM. +
+
+
+Click here for command details for RACF.
+ - If you use RACF, issue the following command: ``` CONNECT (userid) GROUP(IZUUSER) ``` +
+
+
+Click here for command details for ACF2.
+ - If you use ACF2, issue the following commands: ``` @@ -88,12 +94,18 @@ To grant permissions to the user ID to access z/OSMF, issue the command(s) that F ACF2,REBUILD(TGR) ``` +
+
## Next step
diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md
index a9d6b64a4e..82ee0ff344 100644
--- a/docs/user-guide/authenticating-with-client-certificates.md
+++ b/docs/user-guide/authenticating-with-client-certificates.md
@@ -3,42 +3,40 @@
:::info Required roles: system administrator, security administrator
:::
-Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through
-the API ML Gateway with client certificates. Client certification must be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).
+Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through
+the API ML Gateway with client certificates. This method of authentication requires client certification to be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).
:::note Notes:
+
* When calling the login endpoint with basic authentication credentials, as well as with client certificate, the basic
- authentication credentials take precedence and the client certificate is ignored.
+ authentication credentials take precedence and the client certificate is ignored.
* If you are calling a specific endpoint on one of the onboarded services, API Mediation Layer ignores Basic authentication. In this case, the Basic authentication is not part of the authenticated request.
:::
-## How the Gateway resolves authentication
+## How the Gateway resolves authentication
When sending a request to a service with a client certificate, the Gateway performs the following process to resolve authentication:
1. The client calls the service endpoint through the API ML Gateway with the client certificate.
2. The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway.
-3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper.
-4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service.
-
-:::note Notes:
-* Currently, ZSS is the default API that provides this mapping between the public part of the client certificate and SAF user ID. However, the recommended method is to use the internal API ML mapper. For information about the enabling the internal API ML mapper, see [Configure Internal API ML Mapper](./api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper) in the article _Enabling single sign on for clients via client certificate configuration_.
-* For information about ZSS, see the section Zowe runtime in the [Zowe server-side installation overview](./install-zos.md).
-:::
+3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate.
+4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service.
When sending a request to the login endpoint with a client certificate, the Gateway performs the following process to exchange the client certificate for an authentication token:
1. The client calls the API ML Gateway login endpoint with the client certificate.
2. The client certificate is verified to ensure this is a valid TLS client certificate against the trusted CAs of the Gateway.
-3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe release 2.14, the internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2.
+3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate.
4. The Gateway then performs the login of the mapped user and returns a valid JWT token.
-:::note
-ZSS is currently the default API that provides this mapping between the public part of the client certificate and SAF user ID. Using the internal API ML mapper is, however, the recommended method.
+:::note Notes:
+
+* As of Zowe release 3.0.0, the Internal API ML Mapper is the default API that provides this mapping between the public part of the client certificate and SAF user ID. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, with the noted exception when using ACF2, although we recommend using the internal API ML mapper.
+* For information about ZSS, see the section Zowe runtime in the [Zowe server-side installation overview](./install-zos.md).
:::
-The following diagram shows how routing works with ZSS.
+The following diagram shows how routing works with ZSS, in the case where the ZSS API is used for the identity mapping.
@@ -46,42 +44,124 @@ The following diagram shows how routing works with ZSS.
For more information, see the Medium blog post [Zowe client certificate authentication](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579).
:::
-## Configure your z/OS system to support client certificate authentication for a specific user
+## Configure your z/OS system to support client certificate authentication for specific users
+
+Register the client certificate with the user IDs in your ESM.
+
+The following commands show options for both the internal API ML mapper and ZSS.
+
+:::note
+
+If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format of the certificate's distinguished name as displayed.
+:::
+
+**RACF**
+Click here for command details for Top Secret.
+ - If you use Top Secret, issue the following commands: ``` TSS ADD(userid) PROFILE(IZUUSER) TSS ADD(userid) GROUP(IZUUSRGP) ``` +
+) MAP
+ SDNFILTER('')
+ WITHLABEL('
- `INSERT