diff --git a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md index 0e5946bc19..8b38e6115a 100644 --- a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md +++ b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md @@ -7,17 +7,18 @@ In this article, OIDC is often referred to as the provider, while the token-rela Zowe API ML can be configured to authenticate users by accepting Access Tokens issued by an external OIDC/OAuth2 provider. This configuration is useful in advanced deployments of Zowe where client applications need to access mainframe as well as enterprise/distributed systems while simultaneously offering single sign-on (SSO) across system boundaries. -This article details the API ML OIDC authentication functionality, and how to configure the OIDC Authentication feature. +This article details the API ML OIDC authentication functionality, and how to configure the OIDC Authentication feature. - [Usage](#usage) - [Authentication flow](#authentication-flow) - [Prerequisites](#prerequisites) - * [OIDC provider](#oidc-provider) - * [ESM configuration](#esm-configuration) + - [OIDC provider](#oidc-provider) + - [ESM configuration](#esm-configuration) - [API ML configuration](#api-ml-oidc-configuration) - [Troubleshooting](#troubleshooting) ## Usage + The OIDC protocol is used by API ML client applications to verify the identity of a user with a distributed OIDC provider trusted by the mainframe security manager. After successful user login, the OIDC provider grants the client application a JWT Access Token along with an (JWT) Identity Token. The client application can pass this Access Token with subsequent requests to mainframe services routed through the API ML Gateway. @@ -26,20 +27,25 @@ The API ML Gateway can then create mainframe user credentials (JWT or a Passtick The request is routed to the target API services with correct mainframe user credentials. ## Authentication Flow + The following diagram illustrates the interactions between the participants of the OIDC/OAuth2 based API ML authentication process. ![APIML OIDC Workflow](../../images/api-mediation/apiml-oidc-auth-seq.png) -* When a user wants to access mainframe resources or services using the client application without a valid authentication / access token, the client redirects the user agent to the login end-point of the distributed OIDC provider. -* The user is asked to provide valid credentials (authentication factors). -* After successful validation of all authentication factors, the OIDC provider grants the client an Access Token. -* The client can then request from API ML Gateway the needed mainframe resources presenting the access token in the request. -* The Gateway validates the access token at the provider's OIDC/introspection end-point. If the access token is validated, the outcome is cached for a short time (20 sec by default). -* In subsequent calls with the same token, the Gateway reuses the cached validation outcome. As such, round trips to the OIDC /introspection end-point are not required between short intervals, when the client needs to access multiple resources in a row to complete a unit of work. The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access. -* The API ML Gateway fetches the distributed user identity from the distributed access token and maps this user identity to the user mainframe identity using SAF. -* The API ML Gateway calls the requested mainframe service/s with mainframe user credentials (Zowe, SAF JWT, or pass-ticket) which are expected by the target mainframe service. +- When a user wants to access mainframe resources or services using the client application without a valid authentication or an access token, the client redirects the user agent to the login end-point of the distributed OIDC provider. +- The user is asked to provide valid credentials (authentication factors). +- After successful validation of all authentication factors, the OIDC provider grants the client an Access Token. +- The client can then request from API ML Gateway the needed mainframe resources presenting the access token in the request. +- The Gateway validates the access token by comparing the key id of the token against the key ids obtained from the authorization server's JWK keys endpoint. +- The URL to specific authorization server's JWK keys end point should be set using the property `jwks_uri`. If the access token is validated, the outcome is cached for a short time (20 sec by default). +- The JWK Keys obtained from the authorization server's endpoint are cached for a while to prevent repeated calls to the endpoint. The interval can be set using the property `jwks.refreshInternalHours` (The default value is one hour). +- In subsequent calls with the same token, the Gateway reuses the cached validation outcome. As such, round trips to the OIDC authorization server for JWK keys and JWT Token validation are not required between short intervals when the client needs to access multiple resources in a row to complete a unit of work. The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access. +- The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access. +- The API ML Gateway fetches the distributed user identity from the distributed access token and maps this user identity to the user mainframe identity using SAF. +- The API ML Gateway calls the requested mainframe service/s with mainframe user credentials (Zowe, SAF JWT, or pass-ticket) which are expected by the target mainframe service. ## Prerequisites + 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. @@ -54,54 +60,60 @@ Ensure that the following prerequisites are met: 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. + **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. + 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 + The user identity mapping is defined as a distributed user identity filter, which is maintained by the System Authorization Facility (SAF) / External Security Manager (ESM). A distributed identity consists of two parts: -* A distributed identity name -* A trusted registry which governs that identity +- A distributed identity name +- A trusted registry which governs that identity -API ML provides a Zowe CLI plugin to help administrators to generate a JCL for creating the mapping filter specific for the ESM installed on the target mainframe system. +API ML provides a Zowe CLI plugin to help administrators to generate a JCL for creating the mapping filter specific for the ESM installed on the target mainframe system. See the [Identity Federation cli plugin](#) documentation for details about how to use the plugin tool to set up the mapping in the ESM of your z/OS system. Alternatively, administrators can use the installed ESM functionality to create, delete, list, and query a distributed identity filter/s: - - For RACF consult [RACMAP command](https://www.ibm.com/docs/en/zos/2.3.0?topic=rcs-racmap-create-delete-list-query-distributed-identity-filter). - - For CA Top Secret use the [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 CA ACF2 use [IDMAP User Profile Data Records](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-acf2-for-z-os/16-0/administrating/administer-records/user-profile-records/idmap-user-profile-records.html). + +- For RACF, consult the [RACMAP command](https://www.ibm.com/docs/en/zos/2.3.0?topic=rcs-racmap-create-delete-list-query-distributed-identity-filter). +- For CA Top Secret, use the [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 CA ACF2, use [IDMAP User Profile Data Records](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-acf2-for-z-os/16-0/administrating/administer-records/user-profile-records/idmap-user-profile-records.html). ## API ML OIDC configuration + Use the following procedure to enable the feature to use an OIDC Access Token as the method of authentication for the API Mediation Layer Gateway. In the zowe.yaml file, configure the following properties: - - * **`components.gateway.apiml.security.oidc.enabled`** + +- **`components.gateway.apiml.security.oidc.enabled`** Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality. - * **`components.gateway.apiml.security.oidc.clientId`** +- **`components.gateway.apiml.security.oidc.clientId`** Specifies the value of the client identification (`client_id`) assigned by the OIDC provider to the API ML Gateway. - - * **`components.gateway.apiml.security.oidc.clientSecret`** - Specifies the client secret assigned by the OIDC provider to the API ML Gateway. This parameter is used in combination with the `client_id` in Access Token validation requests at the `/introspect` endpoint of the OIDC provider. - - * **`components.gateway.apiml.security.oidc.registry`** + +- **`components.gateway.apiml.security.oidc.clientSecret`** + Specifies the client secret assigned by the OIDC provider to the API ML Gateway. This parameter is used in combination with the `client_id` to obtain JWKs from jwks.uri of the OIDC provider. + +- **`components.gateway.apiml.security.oidc.registry`** Specifies the SAF registry used to group the identities recognized as having a OIDC identity mapping. The registry name is the string used during the creation of the mapping between the dustributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration). - * **`components.gateway.apiml.security.oidc.introspectUrl`** - Specifies the full URL to the introspect endpoint of the OIDC provider. The OIDC token is sent to the provider's introspect endpoint for external validation. +- **`components.gateway.apiml.security.oidc.jwks.uri`** + Specifies the URI obtained from the authorization server's metadata where the Gateway will query for the JWK used to sign and verify the access tokens. + +- **`components.gateway.apiml.security.oidc.jwks.refreshInternalHours`** + Specifies the frequency in hours to refresh the JWK keys from the OIDC provider. Defaults to one hour. - * **`components.gateway.apiml.security.oidc.identityMapperUser`** - (Optional) If the userId is different from the default Zowe runtime userId (`ZWESVUSR`), specify the `identityMapperUser` userId to configure API ML access to the external user identity mapper. +- **`components.gateway.apiml.security.oidc.identityMapperUser`** + (Optional) If the userId is different from the default Zowe runtime userId (`ZWESVUSR`), specify the `identityMapperUser` userId to configure API ML access to the external user identity mapper. - **Note** User authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. + **Note:** User authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. - * **`apiml.security.oidc.identityMapperUrl`** - Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID. +- **`apiml.security.oidc.identityMapperUrl`** + Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID. This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe. You can provide your own API to perform the mapping. In this case, it is necessary to customize this value. The following URL is the default value for Zowe and ZSS: @@ -112,35 +124,6 @@ Use the following procedure to enable the feature to use an OIDC Access Token as ## Troubleshooting -### API ML fails to validate the OIDC access token due to Identity Provider introspect endpoint misconfiguration - -**Symptom** -The Gateway log contains a WARNING with the following message: -`Missing or invalid introspectUrl configuration. Cannot proceed with token validation.` - -**Explanation** -`introspectUrl` is not configured in the API ML Gateway or does not contain the full URL for the Identity Provider introspect end-point. - -**Solution** -Configure `introspectUrl` properly to contain the full URL of the Identity Provider introspect end-point. - -### API ML cannot validate the OIDC access token due to misconfiguration of the Identity Provider certificate - -**Symptom** - -The following error is thrown: - -`ZWESVUSR ERROR (o.z.a.g.s.s.t.OIDCTokenProvider) Failed to validate the OIDC access token.` - - `javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h: PKIX path building failed: com.ibm.security.cert.IBMCertPathBuilderException: unable to find valid certification path to requested target` - -**Explanation** -API ML is sending the OIDC token to the `/introspect` API of the identity provider for validation. Successful connection to the identity provider requires that API ML knows and trusts the root certificate of the identity provider. - -**Solution** -Include the root certificate in the truststore or keyring used by API ML. - - ### API ML fails to validate the OIDC access token due to missing clientID and/or clientSecret **Symptom** @@ -160,17 +143,17 @@ The Gateway log contains the following ERROR message: `Failed to validate the OIDC access token. Unexpected response: XXX.` where: -* _XXX_ +- _XXX_ is the HTTP status code returned by the Identity Provider. **Explanation** -The HTTP code is one from the 40X variants to provide the reason of the failure. +The HTTP code is one of the 40X variants that provides the reason for the failure. **Solution** Correct the Gateway configuration according to the code returned by the OIDC Identity Provider. -### The access token validation fails with HTTP error +### The access token validation fails with HTTP error **Symptom** @@ -182,4 +165,3 @@ The client application is not properly configured in the API ML Gateway. **Solution** Check that the `client_id` and `client_secret` configured in the API ML Gateway correspond to the `client_id` and `client_secret` of the client application as configured in the OIDC provider. - \ No newline at end of file diff --git a/docs/getting-started/release-notes/v2_12_0.md b/docs/getting-started/release-notes/v2_12_0.md index 172a6ac96c..44f5fc9b5f 100644 --- a/docs/getting-started/release-notes/v2_12_0.md +++ b/docs/getting-started/release-notes/v2_12_0.md @@ -16,10 +16,7 @@ Zowe Version 2.12.0 contains the enhancements that are described in the followin ### Zowe API Mediation Layer -* Added a Central API ML registry endpoint to the Cloud Gateway to access an aggregated view of all services from all domains. ([#3076](https://github.com/zowe/api-layer/issues/3076)) -* It is now possible to forward the client certificate from Central Gateway to Domain Gateway in the request header. ([#3046](https://github.com/zowe/api-layer/issues/3046)) -* You can now register the Gateway to an additional Discovery service. Clients outside of the API ML cluster can now know about other gateways to facilitate routing to clusters and domains. ([#3068](https://github.com/zowe/api-layer/issues/3068) and [#3044](https://github.com/zowe/api-layer/issues/3044)) -* You can now verify service SSO support from API ML. ([#3054](https://github.com/zowe/api-layer/issues/3054)) +### Zowe Explorer ## Bug fixes @@ -31,11 +28,6 @@ Zowe Version 2.12.0 contains the bug fixes that are described in the following t ### Zowe API Mediation Layer -* Fixed normalization of `baseUrl` in ZAAS client. ([#3123](https://github.com/zowe/api-layer/issues/3123)) -* Added the JVM heap configuration to `zowe.yaml`. ([#3087](https://github.com/zowe/api-layer/issues/3087)) -* Fixed an error preventing the Catalog UI to load when a service does not have a required parameter. ([#3050](https://github.com/zowe/api-layer/issues/3050)) -* Fixed a navigation issue in the Catalog when using the browser back button. ([#3135](https://github.com/zowe/api-layer/issues/2998)) - ### Zowe CLI #### Zowe CLI (Core) @@ -44,12 +36,14 @@ Zowe Version 2.12.0 contains the bug fixes that are described in the following t - Bumped Imperative to Version `5.18.2` to fix issues with normalizing newlines on file uploads. ([#1815](https://github.com/zowe/zowe-cli/issues/1815)) -- Bumped Secrets SDK to Version `7.18.6` to use `core-foundation-rs` instead of the now-archived `security-framework` crate; to include the edge-case bug fix for Linux; and to resolve build failures for FreeBSD users. ([#1811](https://github.com/zowe/zowe-cli/pull/1811)) +- Bumped Secrets SDK to Version `7.18.6` to use `core-foundation-rs` instead of the now-archived `security-framework` crate; to include the edge-case bug fix for Linux; and to resolve build failures for FreeBSD users. #### Zowe CLI Imperative Framework - Fixed normalization on stream chunk boundaries. ([#1815](https://github.com/zowe/zowe-cli/issues/1815)) +### Zowe Explorer + ### Vulnerabilities fixed Zowe discloses fixed vulnerabilities in a timely manner giving you sufficient time to plan your upgrades. Zowe does not disclose the vulnerabilities fixed in the latest release as we respect the need for at least 45 days to decide when and how you upgrade Zowe. When a new release is published, Zowe publishes the vulnerabilities fixed in the previous release. For more information about the Zowe security policy, see the [Security page](https://www.zowe.org/security.html) on the Zowe website. @@ -59,4 +53,4 @@ The following security issues were fixed by the Zowe security group in version 2 - CVE-2023-33546 (BDSA-2023-1535) - CVE-2023-34462 (BDSA-2023-1556) - BDSA-2023-1804 -- CVE-2023-26136 +- CVE-2023-26136 \ No newline at end of file diff --git a/docs/images/ze/ZE-filtering-a-specific-PDS.gif b/docs/images/ze/ZE-filtering-a-specific-PDS.gif deleted file mode 100644 index 4c6b1b839f..0000000000 Binary files a/docs/images/ze/ZE-filtering-a-specific-PDS.gif and /dev/null differ diff --git a/docs/images/ze/ZE-filtering-profile-PDS-members.gif b/docs/images/ze/ZE-filtering-profile-PDS-members.gif deleted file mode 100644 index e4483375be..0000000000 Binary files a/docs/images/ze/ZE-filtering-profile-PDS-members.gif and /dev/null differ diff --git a/docs/images/ze/ZE-sorting-a-specific-PDS.gif b/docs/images/ze/ZE-sorting-a-specific-PDS.gif deleted file mode 100644 index 171fe03ad2..0000000000 Binary files a/docs/images/ze/ZE-sorting-a-specific-PDS.gif and /dev/null differ diff --git a/docs/images/ze/ZE-sorting-jobs.gif b/docs/images/ze/ZE-sorting-jobs.gif deleted file mode 100644 index 1861a96c1c..0000000000 Binary files a/docs/images/ze/ZE-sorting-jobs.gif and /dev/null differ diff --git a/docs/images/ze/ZE-sorting-profile-PDS-members.gif b/docs/images/ze/ZE-sorting-profile-PDS-members.gif deleted file mode 100644 index c3e7e46ce4..0000000000 Binary files a/docs/images/ze/ZE-sorting-profile-PDS-members.gif and /dev/null differ diff --git a/docs/user-guide/configure-zowe-zosmf-workflow.md b/docs/user-guide/configure-zowe-zosmf-workflow.md index 1e97b8f258..de6e147641 100644 --- a/docs/user-guide/configure-zowe-zosmf-workflow.md +++ b/docs/user-guide/configure-zowe-zosmf-workflow.md @@ -1,11 +1,8 @@ -# Configuring Zowe with z/OSMF Workflows +# Configure Zowe 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 Zowe configuration tasks. z/OSMF helps to simplify the Zowe configuration tasks and does not require the level of expertise that is needed to perform manual Zowe configuration. This configuration method also runs the `zwe init` command to initialize Zowe z/OS runtime. +As a system programmer, after you install Zowe, you can register and execute the z/OSMF workflows in the web interface to complete the Zowe configuration. z/OSMF helps to simplify the Zowe configuration tasks and reduce the level of expertise that is needed for Zowe configuration. -:::info**Required role:** system programmer -::: - -Ensure that you meet the following requirements before you start your Zowe configuration: +Ensure that you meet the following requirements before you start the Zowe configuration: - Install and configure z/OSMF - Install Zowe with an SMP/E build, PSWI, or a convenience build @@ -170,7 +167,3 @@ z/OSMF workflow simplifies the procedure to configure and start Zowe. Execute th 11. Select **Finish**. After you execute each step, the step is marked as Complete. The workflow is executed. - -## Next step - -After you successfully execute the workflow, you are ready to [configure the z/OS system for Zowe](./configure-zos-system.md). \ No newline at end of file diff --git a/docs/user-guide/ze-use-cases.md b/docs/user-guide/ze-use-cases.md index 37a71dda90..e63001e7ae 100644 --- a/docs/user-guide/ze-use-cases.md +++ b/docs/user-guide/ze-use-cases.md @@ -1,8 +1,8 @@ -# Sample use cases +# Sample Use Cases The following use cases demonstrate the various functionalities available in Zowe Explorer. -## Working with data sets +## Working with Data Sets ### Viewing data sets and using multiple filters @@ -162,77 +162,6 @@ The following use cases demonstrate the various functionalities available in Zow ![Add Profile](../images/ze/ZE-mult-profiles.gif) -### Filtering data set members - -Filter partitioned data set members in the **DATA SETS** tree view by **Date Modified** or **User ID**. - -#### Filtering all data set members under a specific profile - -1. In the **DATA SETS** tree, click on the **Filter** icon to the right of a profile, or right-click on a profile and select the **Filter PDS members…** option. - - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: - - **Date Modified** - - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. - - Expanded data sets display a filtered list of members under the selected profile in the **DATA SETS** tree. - - ![Filtering all PDS members under a specific profile](../images/ze/ZE-filtering-profile-PDS-members.gif) - -#### Filtering members for a single data set - -1. In the **DATA SETS** tree, right-click on a data set and select the **Filter PDS members…** option. - - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: - - **Date Modified** - - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. This overrides any *profile* filter preferences that might be in effect for the single data set. - - The selected data set displays a filtered list of members in the **DATA SETS** tree. - - ![Filtering PDS members for a single PDS](../images/ze/ZE-filtering-a-specific-PDS.gif) - -### Sorting data set members - -Sort partitioned data set members in the **DATA SETS** tree view by member **Name**, **Date Modified**, or **User ID**. - -#### Sorting all data set members under a specific profile - -1. In the **DATA SETS** tree, click on the **Sort** icon to the right of a profile, or right-click on a profile and select the **Sort PDS members…** option. - - The sorting selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: - - **Name** - - **Date Modified** - - **User ID** -4. Enter a valid value for the selected sort type. -5. Press the `Enter` key to confirm the sort type. - - Expanded data sets display a sorted list of members under the selected profile in the **DATA SETS** tree. - - ![Sorting all PDS members in a profile ](../images/ze/ZE-sorting-profile-PDS-members.gif) - -#### Sorting members for a single data set - -1. In the **DATA SETS** tree, right-click on a data set and select the **Sort PDS members…** option. - The sort selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: - - **Name** - - **Date Modified** - - **User ID** -4. Enter a valid value for the selected sort type. -5. Press the `Enter` key to confirm the sort type. This overrides any *profile* sort preferences that might be in effect for the single PDS. - - The selected data set displays a sorted list of members in the **DATA SETS** tree. - - ![Sorting a single PDS](../images/ze/ZE-sorting-a-specific-PDS.gif) - ### Submiting a JCL 1. Expand **DATA SETS** in the **Side Bar**. diff --git a/docs/user-guide/ze-working-with-data-sets.md b/docs/user-guide/ze-working-with-data-sets.md deleted file mode 100644 index 0f36b68db3..0000000000 --- a/docs/user-guide/ze-working-with-data-sets.md +++ /dev/null @@ -1,259 +0,0 @@ -# Working with data sets - -## Viewing data sets and using multiple filters - -1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. -2. Click the **Search** icon. -3. Use the **picker** field to select or enter the patterns you want to apply as filters. - - The data sets that match your pattern(s) display in the **Side Bar**. - - :::tip - - To use multiple filters, separate individual entries with a comma. You can append or postpend any filter with an \* to indicate a wildcard search. You cannot enter an \* as the entire pattern. - - ::: - ![View Data Set](../images/ze/ZE-multiple-search.gif) - -## Viewing data sets with member filters - -1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. -2. Click the **Search** icon. -3. In the **picker** field, enter or select a search pattern in the `HLQ.ZZZ.SSS(MEMBERNAME)` format to filter out and display the specified member in the **Side Bar**. - - ![View Data Set With Member Pattern](../images/ze/ZE-member-filter-search.gif) - -## Refreshing the list of data sets - -1. Hover over **DATA SETS** in the **Side Bar**. -2. Click the **Refresh All** icon. - -## Renaming data sets - -1. Expand **DATA SETS** in the **Side Bar**, and select the data set you want to rename. -2. Right-click the data set and select the **Rename Data Set** option. -3. Enter the new name of the data set in the **picker** field. - - ![Rename Data Set](../images/ze/ZE-rename.gif) - -## Copying data set members - -1. Expand **DATA SETS** in the **Side Bar**, and select the member you want to copy. -2. Right-click the member and select the **Copy Member** option. -3. Right-click the data set where the member is to be contained and select the **Paste Member** option. -4. In the **picker** field, enter the name of the copied member. - - ![Copy Data Set Member](../images/ze/ZE-copy-member.gif) - -## Editing and uploading a data set member - -1. Expand **DATA SETS** in the **Side Bar**, and select a profile to open it. -2. Open the data set with the member you want to edit. -3. Click on the member name to display it in an **Editor** tab. -4. Edit the document. -5. Press `Ctrl`+`S` or `Command`+`S` to save the changes and upload the data set to the mainframe. - - :::note - - If someone else has made changes to the data set member while you were editing, you can merge your changes before uploading to the mainframe. See [Preventing merge conflicts](#preventing-merge-conflicts) for more information. - - ::: - - ![Edit and upload a data set member](../images/ze/ZE-edit-upload.gif) - -## Preventing merge conflicts - -1. Expand **DATA SETS** in the **Side Bar**, and navigate to the member you want to edit. -2. Edit the document in the **Editor** tab. -3. Press `Ctrl`+`S` or `Command`+`S` to save the changes. - - If the original content in your local version no longer matches the same file in the mainframe, a warning message displays advising the user to compare both versions. -4. If necessary, use the editor tool bar to resolve merge conflicts. - - ![Prevent merge conflicts](../images/ze/ZE-save.gif) - -## Creating data sets and specifying parameters - -1. Expand **DATA SETS** in the **Side Bar**. -2. Right-click the profile you want to create a data set with and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create and press `Enter`. -5. Select **Edit Attributes** in the **picker** drop-down menu and press `Enter`. - - The attributes list for the data set displays. You can edit the following attributes: - - - Allocation Unit - - - Average Block Length - - - Block Size - - - Data Class - - - Device Type - - - Directory Block - - - Data Set Type - - - Management Class - - - Data Set Name - - - Data Set Organization - - - Primary Space - - - Record Format - - - Record Length - - - Secondary Space - - - Size - - - Storage Class - - - Volume Serial - -6. Select the attribute you want to edit, provide the value in the **picker** field, and press `Enter`. -7. (Optional) Edit the parameters of your data set. -8. Select the **+ Allocate Data Set** option to create the data set and list it in the **Side Bar**. - - ![Set Parameters](../images/ze/ZE-set-params.gif) - -## Creating data sets and data set members - -1. Expand **DATA SETS** in the **Side Bar**. - -2. Right-click on the profile where you want to create a data set and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create. -5. Select **+Allocate Data Set** to create your data set. -6. In the **Side Bar**, right-click your newly-created data set and select **Create New Member**. -7. Enter a name for your new data set member in the **picker** field and press **Enter**. - The member is created and opened in an **Editor** tab. - -## Deleting a data set member and a data set - -1. Expand **DATA SETS** in the **Side Bar**. -2. Open the profile and data set containing the member you want to delete. -3. Right-click the member and select **Delete Member**. -4. Confirm the deletion by selecting **Delete** on the **picker** drop-down menu. -5. To delete a data set, right-click the data set and select **Delete Data Set**, then confirm the deletion. - - :::note - - You can delete a data set before you delete its members. - - ::: - - ![Delete](../images/ze/ZE-delete-ds.gif) - -## Viewing data set, member attributes - -1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. -2. Select the **Search** icon. -3. In the **picker** field, enter or select a search pattern to filter search results in the **Side Bar**. -4. Right-click a data set or member and select the **Show Attributes** option. - - The attributes display in an **Editor** tab. - - ![View Data Set, Member Attributes](../images/ze/ZE-show-attributes.gif) - -## Viewing and accessing multiple profiles simultaneously - -1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. -2. Select the profiles from the **picker** drop-down to add them to the **Side Bar**. -3. Click the **Search** icon for each profile to search and select associated data sets. - - ![Add Profile](../images/ze/ZE-mult-profiles.gif) - -## Filtering partitioned data set members - -Filter partitioned data set members in the **DATA SETS** tree view by **Date Modified** or **User ID**. - -### Filtering all partitioned data set members under a specific profile - -1. In the **DATA SETS** tree, click on the **Filter** icon to the right of a profile. - - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: - - **Date Modified** - - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. - - Expanded data sets display a filtered list of members under the selected profile in the **DATA SETS** tree. - - ![Filtering all PDS members under a specific profile](../images/ze/ZE-filtering-profile-PDS-members.gif) - -### Filtering members for a single partitioned data set - -1. In the **DATA SETS** tree, right-click on a data set and select the **Filter PDS members…** option. - - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: - - **Date Modified** - - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. This overrides any *profile* filter preferences that might be in effect for the single data set. - - The selected data set displays a filtered list of members in the **DATA SETS** tree. - - ![Filtering PDS members for a single PDS](../images/ze/ZE-filtering-a-specific-PDS.gif) - -## Sorting partitioned data set members - -Sort partitioned data set members in the **DATA SETS** tree view by member **Name**, **Date Modified**, or **User ID**. - -### Sorting all partitioned data set members under a specific profile - -1. In the **DATA SETS** tree, click on the **Sort** icon to the right of a profile. - - The sorting selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: - - **Name** - - **Date Modified** - - **User ID** - - Expanded data sets display a sorted list of members under the selected profile in the **DATA SETS** tree. - - ![Sorting all PDS members in a profile ](../images/ze/ZE-sorting-profile-PDS-members.gif) - -### Sorting members for a single partitioned data set - -1. In the **DATA SETS** tree, right-click on a data set and select the **Sort PDS members…** option. - The sort selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: - - **Name** - - **Date Modified** - - **User ID** - - This overrides any *profile* sort preferences that might be in effect for the single PDS. The selected data set displays a sorted list of members in the **DATA SETS** tree. - - ![Sorting a single PDS](../images/ze/ZE-sorting-a-specific-PDS.gif) - -## Submiting a JCL - -1. Expand **DATA SETS** in the **Side Bar**. -2. Select the data set or data set member you want to submit. -3. Right-click the data set or member and select the **Submit Job** option. - - :::note - - Click on the hyperlink on the notification pop-up message to view the job. - - ::: - - ![Submit a JCL](../images/ze/ZE-submit-jcl.gif) - -## Allocate like - -1. Expand **DATA SETS** in the **Side Bar**. -2. Right-click a data set and select the **Allocate Like (New File with Same Attributes)** option. -3. Enter the new data set name in the **picker** field and press `Enter`. - - ![Allocate Like](../images/ze/ZE-allocate.gif) \ No newline at end of file diff --git a/docs/user-guide/ze-working-with-jobs.md b/docs/user-guide/ze-working-with-jobs.md deleted file mode 100644 index 7d6459424e..0000000000 --- a/docs/user-guide/ze-working-with-jobs.md +++ /dev/null @@ -1,115 +0,0 @@ -# Working with jobs - -### Viewing a job - -1. Expand **JOBS** in the **Side Bar**. -2. Open a directory with JCL files. -3. Right-click on the JCL file you want to view, and select the **Get JCL** option. - - ![View JOB](../images/ze/ZE-jobs-get-jcl.gif) - -## Downloading spool content - -1. Expand **JOBS** in the **Side Bar**. -2. Open a directory with JCL files. -3. Click the **Download** icon next to a folder with the spool content. -4. Save the file on your computer. - - ![Download Spool](../images/ze/ZE-jobs-download-spool.gif) - -## Issuing MVS commands - -1. Expand **JOBS** in the **Side Bar**. -2. Right-click on your profile and select the **Issue MVS Command** option. - - Alternatively, press the `F1` key to open the **Command Pallette**, and then select the **Zowe Expolorer: Issue MVS Command** option. - -3. In the **picker** field, enter a new command or select a saved command. -4. Press `Enter` to execute the command. - - ![Issue a MVS command](../images/ze/ZE-Jobs-Issue-TSO-Command.gif) - -## Issuing TSO commands - -1. Expand **JOBS** in the **Side Bar**. -2. Right-click on your profile and select the **Issue TSO Command** option. - - Alternatively, press the `F1` key to open the **Command Pallette**, then select the **Zowe Explorer: Issue TSO Command** option. - -3. In the **picker** field, enter a new command or select a saved command. -4. Press `Enter` to execute the command. - - The output displays in the **Output** panel. - - ![Issue a TSO command](../images/ze/ZE-TSO-Command.gif) - -## Polling a spool file - -Users can periodically refresh a spool file during long-running jobs to get the latest job outputs. This avoids having to close and reopen a spool file to get the latest job outputs. - -There are two main ways to poll a spool file — automatically at set intervals or manually on demand. - -### **Defining a default interval for polling spool files** -
- -1. Click on the **Settings** icon on the **Activity Bar** and select **Settings**. -2. In either the **User** or **Workspace** tab, click on the **Extensions** option to open the menu. -3. Select **Zowe Explorer**. -4. In the **Jobs: Poll Interval** field, enter a valid time interval, in milliseconds. - - Value must be greater than or equal to 1000 ms (1 second). -5. Press **Enter** to start the polling action. - -### **Polling a spool file at set intervals** -
- -1. Expand **JOBS** in the **Side Bar**. -2. Navigate to the spool file by expanding its corresponding profile and job folder. -3. Right click the spool file and select **Start Polling**. - - Repeat this step with additional spool files to poll multiple files simultaneously. -4. The **Poll interval (in ms) for: <spoolfilename>** field displays the current interval value. - - The default value is set to 5000 ms. - - Change the value by entering a different number (must be greater than or equal to 1000 ms). -5. Press **Enter** to confirm the interval time and start the polling action. - - The poll request is added to the poller, and the selected spool file is marked with a "**P**" in the **Side Bar** and any corresponding **Editor** tabs. - - ![Start polling a spool file at set intervals](../images/ze/ZE-start-polling-V2.gif) - -
- -### **Stopping spool file polling** -
- -1. In the **Side Bar**, select a spool file that is being polled. - - Spool files being polled are marked with a "**P**" in the **Side Bar**. - -2. Right click the spool file and select **Stop Polling**. - - The poll request is removed from the poller, and the selected spool file is no longer marked with a "**P**" in the **Side Bar** and any corresponding **Editor** tabs. - -### **Polling a spool file manually** - -
A spool file can be polled on demand by using a designated keyboard shortcut. - -To manually poll a spool file: - -1. In the **Side Bar**, double click a spool file to open it in an **Editor** tab. -2. With the spool file in an active tab, press the keyboard shortcut. - - See [Configuring the keyboard shortcut for manual polling](#Configuring-the-keyboard-shortcut-for-manual-polling) to set the keyboard shortcut. - -
- - The spool file is updated and "**Polling...**" displays in the bottom status bar. - -### **Configuring the keyboard shortcut for manual polling** -
- -1. Click on the **Settings** icon on the **Activity Bar** and select **Keyboard Shortcuts**. - -2. Navigate to **Zowe Explorer: Poll Content in Active Editor**. -3. Select the **Edit** icon to designate a different keyboard shortcut. - - The default shortcut is the `F5` key. -
- - The entered key(s) can be used to activate polling. diff --git a/docs/user-guide/ze-working-with-uss-files.md b/docs/user-guide/ze-working-with-uss-files.md deleted file mode 100644 index 74bfb98c91..0000000000 --- a/docs/user-guide/ze-working-with-uss-files.md +++ /dev/null @@ -1,91 +0,0 @@ -# Working with USS files - -## Viewing Unix System Services (USS) files - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Hover over the profile you want to search and click the **Search** icon. -3. In the **picker** field, enter or select the path that you want as the root of your displayed tree and press `Enter`. - - All child files and directories of that path display in the **Side Bar**. - - :::note - - You cannot expand directories or files to which you are not authorized. - - ::: - - ![Enter Path](../images/ze/ZE-path.gif) - - -## Refreshing the list of files - -1. Hover over **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Click the **Refresh All** button. - - ![Refresh All](../images/ze/ZE-refreshUSS.gif) - -## Renaming USS files - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. - -2. Select a USS file you want to rename. -3. Right-click the USS file and select the **Rename USS file** option. -4. In the **picker** field, change the name of the USS file and press `Enter`. - -## Downloading, editing, and uploading existing USS files - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Navigate to the file you want to download and click on the file name. - - This displays the file in an **Editor** tab. - - :::note - - If you define file associations with syntax coloring, the suffix of your file is marked up. - - ::: - -3. Edit the document. -4. Press `Ctrl`+`S` or `Command`+`S` to save the changes and upload the USS file to the mainframe. - - ![Edit](../images/ze/ZE-editUSS.gif) - -## Creating and deleting USS files and directories - -### Creating a directory - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. - -2. Right-click the directory where you want to add the new directory. -3. Select the **Create Directory** option and enter the directory name in the **picker** field. -4. Press `Enter` to create the directory. - -### Creating a file - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. - -2. Right-click the directory to which you want to add the new file. -3. Select the **Create File** option and enter the file name in the **picker** field. -4. Press `Enter` to create the file. - -### Deleting a file - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. - -2. Right-click the file you want to remove. -3. Select the **Delete** option and click **Delete** again to confirm and delete the file. - -### Deleting a directory - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Right-click the directory you want to remove. -3. Select the **Delete** button and click **Delete** again to confirm and delete the directory and all its child files and directories. - - ![Create and Delete](../images/ze/ZE-CreateDelete.gif) - -## Viewing and accessing multiple USS profiles simultaneously - -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**, and click the **+** icon. -2. Select or enter a profile in the **picker** drop-down menu to add it to the **Side Bar**. - - ![View Profiles](../images/ze/ZE-profile2.gif) diff --git a/sidebars.js b/sidebars.js index 716cd13710..48ab491dc8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -490,9 +490,7 @@ module.exports = { label: "Using Zowe Explorer", link: {type:"doc", id:"user-guide/ze-usage"}, items: [ - "user-guide/ze-working-with-data-sets", - "user-guide/ze-working-with-uss-files", - "user-guide/ze-working-with-jobs", + "user-guide/ze-use-cases", { type: "category", label: "Zowe Explorer extensions",