diff --git a/packages/zowe-explorer/README.md b/packages/zowe-explorer/README.md index e17f8b8ee2..4b5f5e6d55 100644 --- a/packages/zowe-explorer/README.md +++ b/packages/zowe-explorer/README.md @@ -47,6 +47,200 @@ Review the following use cases and their procedures to understand how to work wi - [Submit a JCL](#submit-a-jcl): You can submit a jcl from a chose data set. - [Allocate Like](#allocate-like): Create a copy of a chosen data set with the same parameters. +## Prerequisite tasks + +- 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.html#z-os-requirements). +- Create a Zowe Explorer profile. + +## Getting started + +This section includes steps for the tasks you need to complete to get started using Zowe Explorer. + +Configure Zowe Explorer, create a [team configuration file](#create-a-team-configuration-file) or a [v1 profile (deprecated)](#create-a-v1-profile) for profile manangement, review the [sample use cases](#sample-use-cases) to familiarize yourself with the capabilities of Zowe Explorer, and you are ready to use Zowe Explorer. + +### Configuring Zowe Explorer + +You can configure Zowe Explorer by changing the extension settings. For more information, see [Configuring Zowe Explorer](https://docs.zowe.org/stable/user-guide/ze-install#configuring-zowe-explorer). + +When environment conditions do not support the Zowe CLI built-in Credential Manager, see [Modifying the Secure Credentials Enabled Setting](https://docs.zowe.org/stable/user-guide/ze-install#modifying-the-secure-credentials-enabled-setting). + +### Multifactor authentication support (MFA) + +Zowe Explorer supports the use of MFA tokens for authentication. When using zOSMF profiles it is required to connect through the Zowe API Mediation Layer (API ML). Suggested use case for MFA authentication using Zowe Explorer is by logging into the API ML via the right-click login action in Zowe Explorer and when prompted for password enter the MFA token in place of user password, the API will return a JSON token (JWT) that will be used for further authentication. + +You can find more information regarding MFA support in Zowe's documentation on [integrating with API Mediation Layer](https://docs.zowe.org/stable/user-guide/cli-using-integrating-apiml/). + +### Create a team configuration file + +1. Navigate to the **Side Bar**. +2. Hover over **DATA SETS**, **USS**, or **JOBS**. +3. Click the **+** icon. +4. Select **Create a New Team Configuration File**. +5. If no workspace is open, a global configuration file is created. If a workspace is open, chose either a global configuration file or a project-level configuration file. +6. Edit the config file to include the host and other connection information, and save. + +Your team configuration file appears either in your .zowe folder if you chose the global configuration file option, or in your workspace directory if you chose the project-level configuration file option. The notification message that shows in VS Code after config file creation includes the path of the created file. + +### Create a v1 profile + +> v1 profiles are deprecated and planned to be removed in Zowe Explorer v3.0.0. + +**Note:** If a team configuration file is in place, v1 profile creation and use will not be available. + +1. Navigate to the **Side Bar**. +2. Hover over **DATA SETS**, **USS**, or **JOBS**. +3. Click the **+** icon. +4. Select **Create a New Connection to z/OS**. The user name and password fields are optional. +5. Follow the instructions, and enter all required information to complete the profile creation. + +![New Connection](/docs/images/ZE-newProfiles.gif?raw=true "New Connection") +

+ +You can now use all the functionalities of the extension. + +### Using profiles for the first time + +The first time profiles are used you will be prompted for user name and password for the profile's connection. The term password is used loosely to represent all supported authentication secrets like passphrases, passtickets, Multifactor Authentication (MFA) tokens, etc. + +### Updating securely stored credentials + +Securing credentials for v1 profiles and secure fields in the team configuration file are handled by the Zowe Imperative dependency. To update securely stored user names and passwords in Zowe Explorer, the user can right click the profile and select **Update Credentials**. This prompts the user for the new credentials and the secure credentials vault is updated. + +### Editing team configuration file + +1. Navigate to the **Side Bar**. +2. Hover over **DATA SETS**, **USS**, or **JOBS**. +3. Click the **+** icon. +4. If team configuration file is in place, the **Edit Team Configuration File** option displays. + ![Edit Team Configuration File](/docs/images/ZE-edit-config.png) +

+5. If only a global or project level config is in place, it opens to be edited. If both a global and project level config are in place, the user must select which file to edit. + ![Edit Config Location Option](/docs/images/ZE-edit-options.png) +

+ +### Profile validation + +**Note:** The following information applies to Zowe CLI V1 profiles (one yaml file for each user profile) and Zowe CLI team profiles (Zowe CLI V2). + +Zowe Explorer includes the profile validation feature that helps to ensure that the specified connection to z/OS is successfully established and your profile is ready for use. If a profile is valid, the profile is active and can be used. + +By default, this feature is automatically enabled. You can disable the feature by right-clicking on your profile and selecting the **Disable Validation for Profile** option. Alternatively, you can enable or disable the feature for all profiles in the VS Code settings + +1. In VS Code, navigate to **Settings**. +2. Navigate to Zowe Explorer settings. +3. Check the **Automatic Profile Validation** checkbox to enable the automatic validation of profiles option. Uncheck to disable. +4. Restart VS Code. + +### Use base profile and token with existing profiles + +As a Zowe user, you can leverage the base profile functionality to access multiple services through Single Sign-on. Base profiles enable you to authenticate using the Zowe API Mediation Layer (API ML). You can use base profiles with more than one service profile. For more information, see [Base Profiles](https://docs.zowe.org/stable/user-guide/cli-using-using-profiles/#base-profiles). + +**Note:** Before using the base profile functionality with v1 profiles, ensure that you have [Zowe CLI](https://docs.zowe.org/stable/user-guide/cli-installcli.html) v6.0.0 or higher installed. + +1. Zowe Explorer has a right click action for profiles to log in and log out of the authentication service for existing Base profiles. If a v1 Base profile hasn't been created, open a terminal and run the following Zowe CLI command: `zowe auth login apiml`. +2. Follow the instructions to complete the login. + A local base profile is created that contains your token. + + **Note:** For more information about the process, see [Token Management](https://docs.zowe.org/stable/user-guide/cli-using-integrating-apiml/#how-token-management-works). + +3. Open VS Code and select the **Zowe Explorer** icon in the **Side Bar**. + +4. Hover over **DATA SETS**, **USS**, or **JOBS**. + +5. Click the **+** icon. + +6. Select the profile you use with your base profile with the token. + + The profile appears in the tree and you can now use this profile to access z/OSMF via the API Mediation Layer. + +For more information, see [Integrating with API Mediation Layer](https://docs.zowe.org/stable/user-guide/cli-using-integrating-apiml). + +#### Log in to the Authentication Service + +If the token for your base profile is no longer valid, you can log in again to get a new token with the **Log in to Authentication Service** feature. + +**Notes:** + +- The feature is only available for base profiles. +- The feature supports only API Mediation Layer at the moment. Other extenders may use a different authentication service. + +1. Open VS Code and select the Zowe Explorer icon in the **Side Bar**. +2. Right-click your profile. +3. Select the **Log in to Authentication Service** option. + + You are prompted to enter your username and password. + +The token is stored in the corresponding base profile file, YAML file for v1 Profiles, or the team configuration file. + +If you do not want to store your token, you can request the server to end your session token. Use the **Log out from Authentication Service** feature to invalidate the token: + +1. Open Zowe Explorer. +2. Hover over **DATA SETS**, **USS**, or **JOBS**. +3. Click the **+** icon. +4. Right-click your profile. +5. Select the **Log out from Authentication Service** option. + +Your token has been successfully invalidated. + +## Usage tips + +- Use the **Add to Favorite** feature to permanently store chosen data sets, USS files, and jobs in the **Favorites** folder. Right-click on a data set, USS file or jobs and select **Add Favorite**. + +- **Syntax Highlighting:** Zowe Explorer supports syntax highlighting for data sets. You can search for and install such extensions in VS Code Marketplace. + +- **Update a profile**: Right-click a profile, select the **Update Profile** option, and modify the information inside the profile. + +- **Delete a profile**: For Zowe V1 profiles, right-click a profile and select the **Delete Profile** option to permanently delete the profile and delete the profile from your `.zowe` folder. + + For Zowe V2 profiles, **Delete Profile** opens the `zowe.config.json` file for the user to delete the profile manually: + + ![Delete a V2 profile](/docs/images/ZE-v2-delete-profile.gif) + +- **Hide a profile**: You can hide a profile from the profile tree by right-clicking the profile and selecting the **Hide Profile** option. To unhide the profile, click the **+** button and select the profile from the quick pick list. + +- **Open recent members**: Zowe Explorer lets you open a list of members you worked on earlier. You can access the list by pressing `Ctrl`+`Alt`+`R` (Windows) or `Command`+`Option`+`R` (Mac). + +For the comprehensive Zowe Explorer documentation that also includes information about USS and Jobs interactions, see [the Zowe Explorer documentation](https://docs.zowe.org/stable/user-guide/ze-install.html) in Zowe Docs. + +## Keyboard Shortcuts + +- Restart Zowe Explorer + + - Windows: `ctrl`+`alt`+`z` + - Mac: `⌘`+`⌥`+`z` + +- Open Recent Member + + - Windows: `ctrl`+`alt`+`r` + - Mac: `⌘`+`⌥`+`r` + +- Search in all Loaded Items + - Windows: `ctrl`+`alt`+`p` + - Mac: `⌘`+`⌥`+`p` + +## Extending Zowe Explorer + +You can add new functionalities to Zowe Explorer by creating your own extension. For more information, see [Extensions for Zowe Explorer](https://github.com/zowe/vscode-extension-for-zowe/blob/main/docs/README-Extending.md). + +**Tip:** View an example of a Zowe Explorer extension: [Zowe Explorer FTP extension documentation](https://github.com/zowe/zowe-explorer-ftp-extension#zowe-explorer-ftp-extension). + +## Known Issues + +### Bidirectional languages + +Files written in languages primarily read from right to left (Arabic, Hebrew, many Asian languages) can include portions of text that are written and read left to right, such as numbers. + +These bidirectional (BiDi) languages are not currently supported in Visual Studio Code. (See [Issue #86667](https://github.com/microsoft/vscode/issues/86667) for more information.) + +As a result, VS Code extensions like Zowe Explorer, Zowe Explorer CICS Extension, and Zowe Explorer FTP Extension are not able to support BiDi languages in files. + +## More information + +- For the complete Zowe Explorer documentation, see [Zowe Docs](https://docs.zowe.org/stable/user-guide/ze-install.html). +- Join the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) to stay in touch with the Zowe community. + +## Sample use cases extended + ### View data sets and use multiple filters 1. Navigate to the **Side Bar**. @@ -61,6 +255,10 @@ Review the following use cases and their procedures to understand how to work wi ![View Data Set](/docs/images/ZE-multiple-search.gif?raw=true "View Data Set")

+[Back to sample list](#sample-use-cases) + +--- + ### View data sets with member filters 1. Navigate to the **Side Bar**. @@ -74,11 +272,19 @@ Review the following use cases and their procedures to understand how to work wi **Note:** You cannot favorite a data set or member that includes a member filter search pattern.

+[Back to sample list](#sample-use-cases) + +--- + ### Refresh the list of data sets 1. Navigate to the **Side Bar**. 2. Click **Refresh All** button (circular arrow icon) on the right of the **DATA SETS** explorer bar. +[Back to sample list](#sample-use-cases) + +--- + ### Rename data sets 1. Navigate to the **Side Bar**. @@ -90,6 +296,10 @@ Review the following use cases and their procedures to understand how to work wi ![Rename Data Set](/docs/images/ZE-rename.gif?raw=true "Rename Data Set")

+[Back to sample list](#sample-use-cases) + +--- + ### Copy data set members 1. Navigate to the **Side Bar**. @@ -102,6 +312,10 @@ Review the following use cases and their procedures to understand how to work wi ![Copy Data Set](/docs/images/ZE-copy-member.gif?raw=true "Copy Data Set")

+[Back to sample list](#sample-use-cases) + +--- + ### Edit and upload a data set member 1. Navigate to the **Side Bar**. @@ -123,6 +337,10 @@ Review the following use cases and their procedures to understand how to work wi ![Edit](/docs/images/ZE-edit-upload.gif?raw=true "Edit")

+[Back to sample list](#sample-use-cases) + +--- + ### Use the save option to prevent merge conflicts 1. Navigate to the **Side Bar**. @@ -138,6 +356,10 @@ Review the following use cases and their procedures to understand how to work wi ![Save](/docs/images/ZE-safe-save.gif?raw=true "Save")

+[Back to sample list](#sample-use-cases) + +--- + ### Create a new data set and add a member 1. Navigate to the **Side Bar**. @@ -150,6 +372,10 @@ Review the following use cases and their procedures to understand how to work wi 8. Enter a name for your new data set member and press the `Enter` key. The member is created and opened in the workspace. +[Back to sample list](#sample-use-cases) + +--- + ### Create data sets and specify the parameters 1. Navigate to the **Side Bar**. @@ -204,6 +430,10 @@ Review the following use cases and their procedures to understand how to work wi ![Parameters](/docs/images/ZE-set-params.gif?raw=true "Parameters")

+[Back to sample list](#sample-use-cases) + +--- + ### Delete data sets and data set members 1. Navigate to the **Side Bar**. @@ -221,6 +451,10 @@ Review the following use cases and their procedures to understand how to work wi ![Delete Data Sets and Members](/docs/images/ZE-delete-ds2.gif?raw=true "Delete Data Sets and Members")

+[Back to sample list](#sample-use-cases) + +--- + ### View and access multiple profiles simultaneously 1. Navigate to the **Side Bar**. @@ -230,6 +464,10 @@ Review the following use cases and their procedures to understand how to work wi ![Add Profile](/docs/images/ze-access-multiple-profiles-simultaneously.gif?raw=true "Add Profile") +[Back to sample list](#sample-use-cases) + +--- + ### Submit a JCL 1. Navigate to the **Side Bar**. @@ -243,6 +481,10 @@ Review the following use cases and their procedures to understand how to work wi ![Submit a JCL](/docs/images/ZE-submit-jcl.gif?raw=true "Submit a JCL") +[Back to sample list](#sample-use-cases) + +--- + ### Allocate Like 1. Navigate to the **Side Bar**. @@ -252,182 +494,4 @@ Review the following use cases and their procedures to understand how to work wi ![Allocate Like](/docs/images/ZE-allocate.gif?raw=true "Allocate Like") -## Prerequisite tasks - -- 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.html#z-os-requirements). -- Create a Zowe Explorer profile. - -## Getting started - -This section includes steps for the tasks you need to complete to get started using Zowe Explorer. - -Configure Zowe Explorer, create a [v1 profile](#create-a-v1-profile) or a [team configuration file](#create-a-team-configuration-file) for profile manangement, review the [sample use cases](#sample-use-cases) to familiarize yourself with the capabilities of Zowe Explorer, and you are ready to use Zowe Explorer. - -### Configuring Zowe Explorer - -You can configure Zowe Explorer by changing the extension settings. For more information, see [Configuring Zowe Explorer](https://docs.zowe.org/stable/user-guide/ze-install#configuring-zowe-explorer). - -When environment conditions do not support the Zowe CLI built-in Credential Manager, see [Modifying the Secure Credentials Enabled Setting](https://docs.zowe.org/stable/user-guide/ze-install#modifying-the-secure-credentials-enabled-setting). - -### Create a v1 profile - -**Note:** If a team configuration file is in place, v1 profile creation and use will not be available. - -1. Navigate to the **Side Bar**. -2. Hover over **DATA SETS**, **USS**, or **JOBS**. -3. Click the **+** icon. -4. Select **Create a New Connection to z/OS**. The user name and password fields are optional. -5. Follow the instructions, and enter all required information to complete the profile creation. - -![New Connection](/docs/images/ZE-newProfiles.gif?raw=true "New Connection") -

- -You can now use all the functionalities of the extension. - -### Create a team configuration file - -1. Navigate to the **Side Bar**. -2. Hover over **DATA SETS**, **USS**, or **JOBS**. -3. Click the **+** icon. -4. Select **Create a New Team Configuration File**. -5. If no workspace is open, a global configuration file is created. If a workspace is open, chose either a global configuration file or a project-level configuration file. -6. Edit the config file to include the host and other connection information, and save. - -Your team configuration file appears either in your .zowe folder if you chose the global configuration file option, or in your workspace directory if you chose the project-level configuration file option. The notification message that shows in VS Code after config file creation includes the path of the created file. - -### Updating securely stored credentials - -Securing credentials for v1 profiles and secure fields in the team configuration file are handled by the Zowe Imperative dependency. To update securely stored user names and passwords in Zowe Explorer, the user can right click the profile and select **Update Credentials**. This prompts the user for the new credentials and the secure credentials vault is updated. - -### Editing team configuration file - -1. Navigate to the **Side Bar**. -2. Hover over **DATA SETS**, **USS**, or **JOBS**. -3. Click the **+** icon. -4. If team configuration file is in place, the **Edit Team Configuration File** option displays. - ![Edit Team Configuration File](/docs/images/ZE-edit-config.png) -

-5. If only a global or project level config is in place, it opens to be edited. If both a global and project level config are in place, the user must select which file to edit. - ![Edit Config Location Option](/docs/images/ZE-edit-options.png) -

- -### Profile validation - -**Note:** The following information applies to Zowe CLI V1 profiles (one yaml file for each user profile) and Zowe CLI team profiles (Zowe CLI V2). - -Zowe Explorer includes the profile validation feature that helps to ensure that the specified connection to z/OS is successfully established and your profile is ready for use. If a profile is valid, the profile is active and can be used. - -By default, this feature is automatically enabled. You can disable the feature by right-clicking on your profile and selecting the **Disable Validation for Profile** option. Alternatively, you can enable or disable the feature for all profiles in the VS Code settings - -1. In VS Code, navigate to **Settings**. -2. Navigate to Zowe Explorer settings. -3. Check the **Automatic Profile Validation** checkbox to enable the automatic validation of profiles option. Uncheck to disable. -4. Restart VS Code. - -### Use base profile and token with existing profiles - -As a Zowe user, you can leverage the base profile functionality to access multiple services through Single Sign-on. Base profiles enable you to authenticate using the Zowe API Mediation Layer (API ML). You can use base profiles with more than one service profile. For more information, see [Base Profiles](https://docs.zowe.org/stable/user-guide/cli-using-using-profiles/#base-profiles). - -**Note:** Before using the base profile functionality with v1 profiles, ensure that you have [Zowe CLI](https://docs.zowe.org/stable/user-guide/cli-installcli.html) v6.0.0 or higher installed. - -1. Zowe Explorer has a right click action for profiles to log in and log out of the authentication service for existing Base profiles. If a v1 Base profile hasn't been created, open a terminal and run the following Zowe CLI command: `zowe auth login apiml`. -2. Follow the instructions to complete the login. - A local base profile is created that contains your token. - - **Note:** For more information about the process, see [Token Management](https://docs.zowe.org/stable/user-guide/cli-using-integrating-apiml/#how-token-management-works). - -3. Open VS Code and select the **Zowe Explorer** icon in the **Side Bar**. - -4. Hover over **DATA SETS**, **USS**, or **JOBS**. - -5. Click the **+** icon. - -6. Select the profile you use with your base profile with the token. - - The profile appears in the tree and you can now use this profile to access z/OSMF via the API Mediation Layer. - -For more information, see [Integrating with API Mediation Layer](https://docs.zowe.org/stable/user-guide/cli-using-integrating-apiml). - -#### Log in to the Authentication Service - -If the token for your base profile is no longer valid, you can log in again to get a new token with the **Log in to Authentication Service** feature. - -**Notes:** - -- The feature is only available for base profiles. -- The feature supports only API Mediation Layer at the moment. Other extenders may use a different authentication service. - -1. Open VS Code and select the Zowe Explorer icon in the **Side Bar**. -2. Right-click your profile. -3. Select the **Log in to Authentication Service** option. - - You are prompted to enter your username and password. - -The token is stored in the corresponding base profile file, YAML file for v1 Profiles, or the team configuration file. - -If you do not want to store your token, you can request the server to end your session token. Use the **Log out from Authentication Service** feature to invalidate the token: - -1. Open Zowe Explorer. -2. Hover over **DATA SETS**, **USS**, or **JOBS**. -3. Click the **+** icon. -4. Right-click your profile. -5. Select the **Log out from Authentication Service** option. - -Your token has been successfully invalidated. - -## Usage tips - -- Use the **Add to Favorite** feature to permanently store chosen data sets, USS files, and jobs in the **Favorites** folder. Right-click on a data set, USS file or jobs and select **Add Favorite**. - -- **Syntax Highlighting:** Zowe Explorer supports syntax highlighting for data sets. You can search for and install such extensions in VS Code Marketplace. - -- **Update a profile**: Right-click a profile, select the **Update Profile** option, and modify the information inside the profile. - -- **Delete a profile**: For Zowe V1 profiles, right-click a profile and select the **Delete Profile** option to permanently delete the profile and delete the profile from your `.zowe` folder. - - For Zowe V2 profiles, **Delete Profile** opens the `zowe.config.json` file for the user to delete the profile manually: - - ![Delete a V2 profile](/docs/images/ZE-v2-delete-profile.gif) - -- **Hide a profile**: You can hide a profile from the profile tree by right-clicking the profile and selecting the **Hide Profile** option. To unhide the profile, click the **+** button and select the profile from the quick pick list. - -- **Open recent members**: Zowe Explorer lets you open a list of members you worked on earlier. You can access the list by pressing `Ctrl`+`Alt`+`R` (Windows) or `Command`+`Option`+`R` (Mac). - -For the comprehensive Zowe Explorer documentation that also includes information about USS and Jobs interactions, see [the Zowe Explorer documentation](https://docs.zowe.org/stable/user-guide/ze-install.html) in Zowe Docs. - -## Keyboard Shortcuts - -- Restart Zowe Explorer - - - Windows: `ctrl`+`alt`+`z` - - Mac: `⌘`+`⌥`+`z` - -- Open Recent Member - - - Windows: `ctrl`+`alt`+`r` - - Mac: `⌘`+`⌥`+`r` - -- Search in all Loaded Items - - Windows: `ctrl`+`alt`+`p` - - Mac: `⌘`+`⌥`+`p` - -## Extending Zowe Explorer - -You can add new functionalities to Zowe Explorer by creating your own extension. For more information, see [Extensions for Zowe Explorer](https://github.com/zowe/vscode-extension-for-zowe/blob/main/docs/README-Extending.md). - -**Tip:** View an example of a Zowe Explorer extension: [Zowe Explorer FTP extension documentation](https://github.com/zowe/zowe-explorer-ftp-extension#zowe-explorer-ftp-extension). - -## Known Issues - -### Bidirectional languages - -Files written in languages primarily read from right to left (Arabic, Hebrew, many Asian languages) can include portions of text that are written and read left to right, such as numbers. - -These bidirectional (BiDi) languages are not currently supported in Visual Studio Code. (See [Issue #86667](https://github.com/microsoft/vscode/issues/86667) for more information.) - -As a result, VS Code extensions like Zowe Explorer, Zowe Explorer CICS Extension, and Zowe Explorer FTP Extension are not able to support BiDi languages in files. - -## More information - -- For the complete Zowe Explorer documentation, see [Zowe Docs](https://docs.zowe.org/stable/user-guide/ze-install.html). -- Join the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) to stay in touch with the Zowe community. +[Back to sample list](#sample-use-cases)