Merge pull request #4152 from zowe/user/zlatnikp/apimlwfdoc

User/zlatnikp/apimlwfdoc

docs/user-guide/apf-authorize-load-library.md

@@ -20,8 +20,8 @@ The following command presents an example of running `zwe init apfauth`:
 -------------------------------------------------------------------------------
 >> APF authorize load libraries
 
-APF authorize IBMUSER.ZWEV2.SZWEAUTH
-APF authorize IBMUSER.ZWEV2.CUST.ZWESAPL
+APF authorize IBMUSER.ZWEV3.SZWEAUTH
+APF authorize IBMUSER.ZWEV3.CUST.ZWESAPL
 
 >> Zowe load libraries are APF authorized successfully.
 #>
@@ -31,8 +31,8 @@ If you do not have permissions to update your security configurations, append th
 :::
 
 ```
-  SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.SZWEAUTH,SMS
-  SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV2.CUST.ZWESAPL,SMS
+  SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV3.SZWEAUTH,SMS
+  SETPROG APF,ADD,DSNAME=IBMUSER.ZWEV3.CUST.ZWESAPL,SMS
 ```
 
 ### Making APF auth be part of the IPL
@@ -41,13 +41,13 @@ Add one of the following to your active `PROGxx` PARMLIB member, for example `SY
 
 - If the load library is not SMS-managed, add the following lines, where `${volume}` is the name of the volume that holds the data set:
   ```
-  APF ADD DSNAME(IBMUSER.ZWEV2.SZWEAUTH) VOLUME(${volume})
-  APF ADD DSNAME(IBMUSER.ZWEV2.CUST.ZWESAPL) VOLUME(${volume})
+  APF ADD DSNAME(IBMUSER.ZWEV3.SZWEAUTH) VOLUME(${volume})
+  APF ADD DSNAME(IBMUSER.ZWEV3.CUST.ZWESAPL) VOLUME(${volume})
   ```
 - If the load library is SMS-managed, add the following line:
   ```
-  APF ADD DSNAME(IBMUSER.ZWEV2.SZWEAUTH) SMS
-  APF ADD DSNAME(IBMUSER.ZWEV2.CUST.ZWESAPL) SMS
+  APF ADD DSNAME(IBMUSER.ZWEV3.SZWEAUTH) SMS
+  APF ADD DSNAME(IBMUSER.ZWEV3.CUST.ZWESAPL) SMS
   ```
 
 The PDS member `SZWESAMP(ZWESIPRG)` contains the SETPROG statement and PROGxx update for reference.

docs/user-guide/configure-apiml-zosmf-workflow.md

@@ -0,0 +1,112 @@
+# Configuring API ML with z/OSMF Workflows
+
+After you install Zowe, you can register and execute the z/OSMF workflows in the web interface to perform a range of
+API ML/Zowe configuration tasks. The **Stand-alone Zowe API ML Configuration** workflow simplifies configuration of Zowe API Mediation Layer and does not require the level of
+expertise that is needed to perform manual API ML/Zowe configuration. The **Stand-alone Zowe API ML Configuration** workflow also runs the `zwe install` and `zwe init` command to initialize Zowe z/OS runtime.
+
+:::info Required role: system programmer
+:::
+
+Ensure that you meet the following requirements before you start your Zowe configuration:
+
+- Install and configure z/OSMF
+- Install Zowe with an SMP/E build, PSWI, or a convenience build
+
+The following components are automatically enabled after performing the **Stand-alone Zowe API ML Configuration** workflow:
+
+- API Gateway
+- ZAAS
+- API Catalog
+- Discovery service
+- Caching service
+
+The following components are automatically disabled:
+
+- Application server
+- ZSS component
+- JES Explorer
+- MVS Explorer
+- USS Explorer
+
+:::note
+These components can be enabled by performing manual changes in the yaml file, but making such changes to the yaml file is not recommended for simplified and optimized configuration of API ML.
+:::
+
+You can execute the API ML/Zowe configuration workflow either from a PSWI during deployment or later from a created software
+instance in z/OSMF. Alternatively, you can execute the configuration workflow z/OSMF during the workflow registration process.
+
+The configuration workflow described in this article is executed directly from a deployment of the Zowe PSWI.
+
+## Execute Stand-alone Zowe API ML Configuration workflow from PSWI
+
+In the PSWI deployment phase, you are presented with a checklist that helps guide you during the deployment process.
+
+![Deployment Checklist](../images/zosmf/perform-workflows.png)
+
+The **Perform Workflows** step enables you to run either all attached workflows or just the
+post-deployment workflow for mounting, which is required.
+
+After you successfully performed the Zowe Mount workflow, you can start the **Stand-alone Zowe API ML Configuration** workflow.
+When you select this workflow from the list of Workflow Definition Files, the following screen displays: 
+
+![Stand-alone Zowe API ML Configuration workflow](../images/zosmf/workflow-APIMLConfiguration.png)
+
+You can see the workflow details by expanding the Workflow details panel.
+This workflow has three main steps:
+
+### 1. **Define variables**
+
+This workflow step includes the list of Zowe variables.
+When you expand this step, the following screen displays: 
+
+First, define the main variables for your configuration. 
+
+![Step1.1: Define variables](../images/zosmf/workflow-APIMLdefineMainVariables.png)
+
+After you complete defining the main variables for your configuration, define all ports for automatically enabled API ML services.  
+
+![Step1.2: Ports](../images/zosmf/workflow-APIMLdefinePorts.png)
+
+Perform the following steps to execute each sub-step individually:
+
+1. Click the title of the sub-step.
+2. Select the **Perform** tab.
+3. Review the step contents and update the variables that are marked by a red asterisk based on your mainframe environment.
+4. Select **Next**. 
+5. Repeat the previous two steps to complete all items until the **Finish** option is available.
+
+:::note
+A basic validation is supported in many fields. Validation includes proper path structure, dataset name conventions, or numeric size.
+The workflow, however, does not check, for example, whether a target dataset exists, or a directory has sufficient space.
+:::
+
+After both sub-steps, **Define the main variables** and **Ports** are completed, the step **Define variables** is marked as Complete.
+
+### 2. **Create configuration**
+
+Execute this step to create a configuration zowe.yaml file with the variable setup that was defined in the previous step. 
+In this step you can review your configurations and, if necessary, make further changes directly in the JCL. 
+When you are done, click **Finish**. The zowe.yaml file is ready, and the step is marked as Complete.
+
+:::note
+The **Create configuration** step is mandatory. A valid zowe.yaml is required to execute the **Zowe installation** step.
+:::
+
+### 3. **Zowe Installation**
+
+This step consumes the zowe.yaml configuration file you created in the previous step. It contains two sub-steps:
+
+1. **Run the Zowe install** to run the `zwe install` command.
+2. **Run the Zowe init** to run `zwe init mvs` and `zwe init stc` commands.
+
+:::note
+If you did not set up security prior this installation, you can alternatively submit the `ZWESECUR` JCL. For details, see [Configuring security](configuring-security.md).
+:::
+
+For more information about `zwe install` and `zwe init` commands, see the following articles:
+* [zwe install command](../appendix/zwe_server_command_reference/zwe/zwe-install.md)
+* [Configuring Zowe with zwe init](initialize-zos-system.md)
+
+The **Stand-alone Zowe API ML Configuration** workflow strictly follows the Zowe v3 install and configuration schema. This workflow generates the zowe.yaml file and runs the Zowe `zwe` CLI tool.
+After completing the workflow execution, you can return to the **Deployment Checklist** for the Zowe PSWI. 
+After you complete the steps in the checklist you are ready to start your Zowe instance with optimized setup for Zowe API Mediation Layer.

docs/user-guide/configure-xmem-server.md

@@ -111,13 +111,13 @@ For the cross memory server to be started, you must move the JCL PROCLIB `ZWESIS
 
 You need to update the `ZWESISTC` member in the JES concatenation path with the location of the load library that contains the load module `ZWESIS01` by editing the STEPLIB DD statement of `ZWESISTC`.  Edit the PARMLIB DD statement to point to the location of the PDS that contains the `ZWESIP00` member.  
 
-For example, the sample JCL below shows `ZWESISTC` where the APF-authorized PDSE containing `ZWESIS01` is `IBMUSER.ZWEV2.SZWEAUTH(ZWESIS01)` and the PDS PARMLIB containing `ZWESIP00` is `IBMUSER.ZWEV2.SZWESAMP(ZWESIP00)`.  
+For example, the sample JCL below shows `ZWESISTC` where the APF-authorized PDSE containing `ZWESIS01` is `IBMUSER.ZWEV3.SZWEAUTH(ZWESIS01)` and the PDS PARMLIB containing `ZWESIP00` is `IBMUSER.ZWEV3.SZWESAMP(ZWESIP00)`.  
 
 ```cobol
 //ZWESIS01 EXEC PGM=ZWESIS01,REGION=&RGN,
 //         PARM='NAME=&NAME,MEM=&MEM'
-//STEPLIB  DD   DSNAME=IBMUSER.ZWEV2.SZWEAUTH,DISP=SHR
-//PARMLIB  DD   DSNAME=IBMUSER.ZWEV2.SZWESAMP,DISP=SHR
+//STEPLIB  DD   DSNAME=IBMUSER.ZWEV3.SZWEAUTH,DISP=SHR
+//PARMLIB  DD   DSNAME=IBMUSER.ZWEV3.SZWESAMP,DISP=SHR
 //SYSPRINT DD   SYSOUT=*
 ```
 

docs/user-guide/configure-zowe-runtime.md

@@ -40,4 +40,6 @@ Another option to initialize Zowe z/OS runtime is to configure Zowe with z/OSMF
 
 You can execute the Zowe configuration workflow either from a PSWI during deployment, or later from a created software instance in z/OSMF. Alternatively, you can execute the configuration z/OSMF workflow during the workflow registration process.
 
-For more information about this z/OS runtime initialization method, see [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow).
+For more information about this z/OS runtime initialization method, see [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow).
+
+For details about API ML optimized initialization, see [Configuring API ML with z/OSMF Workflows](./configure-apiml-zosmf-workflow).

docs/user-guide/configure-zowe-zosmf-workflow.md

@@ -13,7 +13,7 @@ Ensure that you meet the following requirements before you start your Zowe confi
 - Install and configure z/OSMF
 - Install Zowe with an SMP/E build, PSWI, or a convenience build
 
-You can complete the following tasks with the **Configuration of Zowe 3.0** workflow:
+You can complete the following tasks with the **Full Zowe server-side configuration for Zowe 3.0** workflow:
 
 - Configure the Zowe instance
 - Enable the API Gateway
@@ -33,7 +33,7 @@ process.
 
 The configuration workflow described in this article is executed directly from a deployment of the Zowe PSWI.
 
-## Execute Configuration of Zowe 3.0 workflow from PSWI
+## Execute Full Zowe server-side configuration for Zowe 3.0 workflow from PSWI
 
 In the PSWI deployment phase, you are presented with a checklist that helps guide you during the deployment process.
 
@@ -42,10 +42,10 @@ In the PSWI deployment phase, you are presented with a checklist that helps guid
 The **Perform Workflows** step enables you to run either all attached workflows or just the
 post-deployment workflow for mounting, which is required.
 
-After you successfully performed the Zowe Mount workflow, you can start the **Configuration of Zowe 3.0** workflow.
+After you successfully performed the Zowe Mount workflow, you can start the **Full Zowe server-side configuration for Zowe 3.0** workflow.
 When you select this workflow from the list of Workflow Definition Files, the following screen displays: 
 
-![Configuration of Zowe 3.0 workflow](../images/zosmf/workflow-zoweConfiguration.png)
+![Full Zowe server-side configuration for Zowe 3.0 workflow](../images/zosmf/workflow-zoweConfiguration.png)
 
 You can see the workflow details by expanding the Workflow details panel.
 This workflow has three main steps:
@@ -111,6 +111,6 @@ For more information about `zwe install` and `zwe init` commands, see the follow
 * [zwe install command](../appendix/zwe_server_command_reference/zwe/zwe-install.md)
 * [Configuring Zowe with zwe init](initialize-zos-system.md)
 
-The **Configuration of Zowe 3.0** workflow strictly follows the Zowe v3 install and configuration schema. This workflow generates the zowe.yaml file and runs the Zowe zwe CLI tool.
+The **Full Zowe server-side configuration for Zowe 3.0** workflow strictly follows the Zowe v3 install and configuration schema. This workflow generates the zowe.yaml file and runs the Zowe zwe CLI tool.
 After completing the workflow execution, you can return to the **Deployment Checklist** for the Zowe PSWI. 
 After you complete the steps in the checklist you are ready to start your Zowe instance.

docs/user-guide/configuring-overview.md

@@ -33,7 +33,10 @@ You can configure Zowe by directly customizing JCLs. The Zowe Runtime Dataset `S
 * **Option 3: Configure Zowe with z/OSMF workflows**  
 You can execute the Zowe configuration workflow either from a PSWI during deployment, or later from a created software instance in z/OSMF. Alternatively, you can execute the configuration workflow z/OSMF during the workflow registration process.
 
-    For more information, see [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md).
+    For more information about configuring all Zowe server-side components, see [Configuring Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md). 
+
+    To simplify configuration for Zowe API Mediation Layer, see 
+[Configuring API ML with z/OSMF Workflows](./configure-apiml-zosmf-workflow.md).
 
 ## Configuring the z/OS system for Zowe
 

docs/user-guide/generate-certificates.md

@@ -226,7 +226,7 @@ After you configure the `zowe.yaml`, use the following procedure to generate a J
 
    `zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config`
 
-    When the command is run, a customized JCL member name is created in the `CUST.JCLLIB` data set. The PDS name is defined in the `zowe.setup.dataset.jcllib` property. In the following example output, the PDS member `USER.ZWEV2.CUST.JCLLIB(ZW101431)` is created that contains the security manager commands, and then submitted as a job ID: `ZWEKRING(JOB03054)`.
+    When the command is run, a customized JCL member name is created in the `CUST.JCLLIB` data set. The PDS name is defined in the `zowe.setup.dataset.jcllib` property. In the following example output, the PDS member `USER.ZWE3.CUST.JCLLIB(ZW101431)` is created that contains the security manager commands, and then submitted as a job ID: `ZWEKRING(JOB03054)`.
 
 The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted.
 
@@ -237,8 +237,8 @@ The following command output shows the generation of a JCERACFKS certificate usi
 >> Generate Zowe certificate in keyring
 
 >>>> Modify ZWEKRING
-    - IBMUSER.ZWEV2.CUST.JCLLIB(ZW101431) is prepared
->>>> Submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW101431)
+    - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared
+>>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431)
     - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED).
 >> Certificate is generated in keyring successfully.
 

docs/user-guide/initialize-mvs-datasets.md

@@ -21,7 +21,7 @@ zowe:
       prefix: IBMUSER.ZWE
       parmlib: IBMUSER.ZWE.CUST.PARMLIB
       jcllib: IBMUSER.ZWE.CUST.JCLLIB
-      authLoadlib: IBMUSER.ZWEV2.SZWEAUTH
+      authLoadlib: IBMUSER.ZWEV3.SZWEAUTH
       authPluginLib: IBMUSER.ZWE.CUST.ZWESAPL
 ```
 
@@ -49,15 +49,15 @@ Here is an example of running `zwe init mvs`.
 >> Initialize Zowe custom data sets
 
 Create data sets if they are not exist
-Creating IBMUSER.ZWEV2.CUST.PARMLIB
-Creating IBMUSER.ZWEV2.CUST.JCLLIB
-Creating IBMUSER.ZWEV2.SZWEAUTH
-Creating IBMUSER.ZWEV2.CUST.ZWESAPL
+Creating IBMUSER.ZWEV3.CUST.PARMLIB
+Creating IBMUSER.ZWEV3.CUST.JCLLIB
+Creating IBMUSER.ZWEV3.SZWEAUTH
+Creating IBMUSER.ZWEV3.CUST.ZWESAPL
 
-Copy IBMUSER.ZWEV2.SZWESAMP(ZWESIP00) to USER.ZWEV2.CUST.PARMLIB(ZWESIP00)
-Copy components/zss/LOADLIB/ZWESIS01 to USER.ZWEV2.SZWEAUTH(ZWESIS01)
-Copy components/zss/LOADLIB/ZWESAUX to USER.ZWEV2.SZWEAUTH(ZWESAUX)
-Copy components/launcher/bin/zowe_launcher to USER.ZWEV2.SZWEAUTH(ZWELNCH)
+Copy IBMUSER.ZWEV3.SZWESAMP(ZWESIP00) to USER.ZWEV3.CUST.PARMLIB(ZWESIP00)
+Copy components/zss/LOADLIB/ZWESIS01 to USER.ZWEV3.SZWEAUTH(ZWESIS01)
+Copy components/zss/LOADLIB/ZWESAUX to USER.ZWEV3.SZWEAUTH(ZWESAUX)
+Copy components/launcher/bin/zowe_launcher to USER.ZWEV3.SZWEAUTH(ZWELNCH)
 
 >> Zowe custom data sets are initialized successfully.
 #>
@@ -67,5 +67,5 @@ Copy components/launcher/bin/zowe_launcher to USER.ZWEV2.SZWEAUTH(ZWELNCH)
 
 If this step is successful, there will be three custom data sets matching the values in `zowe.setup.dataset.parmlib`, `zowe.setup.dataset.jcllib` and `zowe.setup.dataset.authPluginLib` in the `zowe.yaml` file. The member `ZWESIP00` will exist in the `CUST.PARMLIB` and the `JCLLIB` and `ZWESAPL` will be empty.
 
-In addition to the three custom data sets, the PDS `SZWEAUTH` is created. This may already exist. In this case, you will receive the error message `Error ZWEL0158E: IBMUSER.ZWEV2.SZWEAUTH already exists`. You can ignore this message, or you can use the `--allow-overwritten` option on the command. For example, `zwe init mvs -c zowe.yaml --allow-overwritten`.
+In addition to the three custom data sets, the PDS `SZWEAUTH` is created. This member may already exist. In this case, you will receive the error message `Error ZWEL0158E: IBMUSER.ZWEV3.SZWEAUTH already exists`. You can ignore this message, or you can use the `--allow-overwritten` option on the command. For example, `zwe init mvs -c zowe.yaml --allow-overwritten`.
 

docs/user-guide/initialize-security-configuration.md

@@ -36,10 +36,10 @@ Specify the parameter `--security-dry-run` to construct a JCL member containing
 >> Run Zowe security configurations
 
 Modify ZWESECUR
-- IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) is prepared
+- IBMUSER.ZWEV3.CUST.JCLLIB(ZW134428) is prepared
 
 Dry-run mode, security setup is NOT performed on the system.
-Please submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW134428) manually.
+Please submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW134428) manually.
 >> Zowe security configurations are applied successfully.
 
 #>

docs/user-guide/install-zos.md

@@ -106,7 +106,8 @@ The steps to prepare the z/OS environment to launch Zowe are the same for all in
 
 Choose from the following methods to configure the Zowe runtime: 
 - [Use a combination of JCL and the zwe command `zwe init`](./initialize-zos-system.md)
-- [Use z/OSMF Workflows](./configure-zowe-zosmf-workflow.md)
+- [Use Zowe z/OSMF Workflows](./configure-zowe-zosmf-workflow.md)
+- [Use API ML optimized z/OSMF Workflows](./configure-apiml-zosmf-workflow.md)
 
 :::tip
 We recommend you open the links to this configuration procedure in new tabs.

docs/user-guide/install-zowe-pswi-address-requirements.md

@@ -42,4 +42,4 @@ To download and unpack the pax file, you need free space that is approximately 3
 
 Configure SMP/E Internet Service Retrieval to receive and download maintenance on a regular cadence or build custom maintenance packages (order PTFs, APARs, critical, recommended, all, or just HOLDDATA). This step is our recommended best practice when installing maintenance and is required to use the z/OSMF Software Update. For configuration details, see the Mainframe Common Maintenance Procedures documentation.	
 
-After these requirements have been addressed, you are ready to [acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire/#download-the-portable-software-instance-from-zowe-downloads) or [Configure Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md).
+After these requirements have been addressed, you are ready to [acquire a z/OSMF Portable Software Instance](./install-zowe-pswi-acquire/#download-the-portable-software-instance-from-zowe-downloads) or [Configure Zowe with z/OSMF Workflows](./configure-zowe-zosmf-workflow.md) or [Configuring API ML with z/OSMF Workflows](./configure-apiml-zosmf-workflow.md).