Explorer for Endevor
The Explorer for Endevor VS Code extension modernizes the way you interact with Endevor, offering a user-friendly and convenient way to work with elements and inventory locations. Explorer for Endevor includes the following features:
- Add an element
- View an element
- Retrieve an element with dependencies
- View element details
- Create Endevor profiles, including Endevor inventory location profiles
- Use Zowe CLI base profiles
- Perform an Edit action
- Perform a Generate action
- Print a listing
Explorer for Endevor is a part of the Che4z open-source project. The extension is also part of Code4z, an all-round package that offers a modern experience for mainframe application developers, including extensions for language support, data editing, testing, and source code management.
Table of Contents
Prerequisites
Ensure that you meet the following prerequisites before you use Explorer for Endevor:
Client-side prerequisites:
- Access to Endevor.
- Install Visual Studio Code version 1.58 or higher.
Host-side prerequisites:
- Install either Endevor version 18.0.12 with the SO09580 and SO09581 PTFs or Endevor version 18.1 with the SO15978 PTF.
- Install Endevor Web Services.
Getting Started
Create an Endevor profile and inventory location profile and review use cases to see how you can use the full potential of Explorer for Endevor.
Add an Endevor Profile to the Endevor tree
Explorer for Endevor uses the Endevor Plug-in for Zowe CLI endevor and endevor-location profiles to access Endevor inventory locations on the mainframe and work with elements. If you already have an Endevor plug-in Zowe CLI profile, you can add it to the Endevor tree.
Follow these steps:
- Click the Add a New Profile button to add an Endevor profile.
- Select one of the existing profiles listed in the menu.
Your Zowe CLI profile is now available in the Endevor tree.
If you do not have a profile, you can create one in Explorer for Endevor.
Follow these steps:
Click the Add a New Profile button to add a new Endevor profile.
Select Create a new Endevor Profile.
Enter a name for your profile.
Enter your Endevor URL in the http(s)://host:port/basePath format.
Notes:
- Depending on the Endevor services you use, your can inlcude
EndevorService/api/v1, EndevorService/rest or EndevorService/api/v2 in basePath. If basePath is omitted the default is EndevorService/api/v2.
- Explorer for Endevor checks if the specified URL is accessible. If not, you will be prompted to either change the specified value or proceed without changing the value.
- You might be prompted to either accept or reject connections with self-signed certificates if the extension encounters an issue with the server certificate issuer validation in the connection testing phase. If no issues are found, the prompt does not appear and the value is set to
reject.
(Optional) Enter your username and password to add your mainframe credentials to the profile.
Adding your credentials to your profile lets you access different Endevor locations without having to enter your credentials more than once.
Notes:
- If your profile does not include credentials during the first session of Explorer for Endevor, you are prompted to provide credentials.
- Passwords with 9 or more characters are treated as a passphrase by the server and are case-sensitive.
Your new profile is now available in the tree. You can also reuse the same Endevor profile in Zowe CLI.
Create Endevor Location Profile
Once you have an Endevor profile, you need to add an Endevor location profile. Endevor location profiles consist of Endevor instance, Endevor path that includes environment, system, subsystem, stage number, and element type, CCID, and Comment. Endevor location profiles let you view and work with elements of specified Endevor locations.
Follow these steps:
Click the + icon next to your Endevor profile to add a new location profile.
Create a name for the Endevor location profile and press Enter.
Select an instance from the drop-down menu and press Enter.
Enter the Endevor path and press Enter.
The path has the environment/stagenumber/system/subsystem/type format.
Note: If you are unsure about the system, subsystem, or type parameters, you can substitute any of these parameters with a * wildcard.
(Optional) Enter CCID and press Enter.
(Optional) Enter comment and press Enter.
Notes:
- If you want to skip the CCID and/or comment step, you can leave the inputs blank by pressing Enter.
- You can cancel the creation of Endevor location profile at any step by pressing Escape.
You successfully created an Endevor profile.
If an existing endevor-location profile that you created in Zowe CLI does not have the instance, environment, and stage numbers parameters specified, the extension cannot reach the inventory location. In this case, recreate an inventory location profile with the entire location path so that Explorer for Endevor can access elements in the specified inventory.
Use Cases
Review the following use cases to familiarize yourself with the basic Explorer for Endevor features:
- Add an element: You can upload an element from your workstation to a chosen Endevor location.
- View an element: You can view the contents, summary report, and source level information of the selected element.
- View details: You can view the details of a chosen element. The details include the environment, stage, system, subsystem, element type, and the name and extension of the element.
- Retrieve an element: You can download the selected element.
- Retrieve an element with dependencies: You can download the selected element with dependencies.
- Edit: The Edit action enables you to download an element to your workspace, edit and upload the selected element step by step. All you need to do is edit an element and press CTRL+S or Command+S to upload the edited element back.
- Generate: You can call the Generate action for an element to invoke the Generate Processor that creates an executable form of the element.
- Print listing: You can reveal the output of the performed Generate action.
- Sign out: You can lock an Endevor element so that the element is only editable by you.
- Sign in: Let you unlock a locked element. You can only unlock the elements that were locked by you.
Add an Element
You can upload a new element to your Endevor location. The uploaded element appears under the selected type in the tree.
Follow these steps:
Hover over an Endevor location in the tree.
The Add an Element icon appears on the right side of the panel.
Click the Add an Element icon to upload a new element.
The Explorer dialog appears. You can now select an element that you want to upload from your workstation.
Select an element that you want to upload from your workstation.
View an Element
You can view the contents, summary, and source level information of an element by clicking on the element in the tree. The chosen element appears in the editor area. Viewing the contents of the element allows you to determine if you want to retrieve and work with the element.
Follow these steps:
Hover over an element that you want to view.
Click the element to see the contents of the element.
The contents of the element appear in the editor area.
View Details
The details of an element you want to view appear in the editor area in a separate tab.
Follow these steps:
Right-click an element.
Select the View Details option.
The details of the element appear in the editor area.
Retrieve an Element
You can download an element to your workspace and work with the element locally.
Follow these steps:
Right-click an element.
Select the Retrieve option.
The extension downloads and places the element into your workspace. The contents of the element appear in the editor area. You can find the element in the workspace folder.
You successfully retrieved the element.
Retrieve an Element with Dependencies
You can download an element with dependencies to your workspace and work with the element and the dependencies locally.
Follow these steps:
Right-click an element.
Select the Retrieve with dependencies option.
The extension downloads and places the element with dependencies into your workspace. The contents of the element appear in the editor area.
You successfully retrieved the element with dependencies.
Edit
The Edit action lets you download an element, edit, and upload the element back.
Follow these steps:
Right-click an element.
Select the Edit option.
The contents of the element appear in the editor area. You can now edit the element.
Press CTLR+S or Command+S when you want to save and upload the edited element back.
Specify any accessible Endevor path and a name for the element.
Enter a CCID.
Enter a comment.
(Optional) Resolve conflicts between the element versions if necessary.
Notes:
The behavior of the conflict resolution feature differs in Theia.
(Theia only) When you resolve a conflict, open the Command Palette by pressing CTRL+SHIFT+P or CMD+SHIFT+P, and use of the two commands: Accept changes or Discard changes.
You successfully edited, saved, uploaded the element.
Generate
The Generate action creates an executable form of the element, together with any associated outputs such as listings, and has the following available options:
Generate in Place enables you to generate the selected element in the same location where the element resides.
Generate with Copyback enables you to copy the selected element back from up the map to the target location first and then generate the element in that location.
Generate with No Source enables you to generate an element in the target location, using the source of the selected element from up the map. In this case, the source is not fetched to the target location and the sourceless element is created.
You can use the Generate in Place, Generate with Copyback, or Generate with No Source context menu options to perform the Endevor Generate action for a selected element.
Follow these steps:
Select one of the following options:
Right-click an element and select the Generate in Place option.
Right-click an element from up the map and select the Generate with Copy back option.
Right-click an element from up the map and select the Generate with No Source option.
A successfully-performed Generate action shows a notification pop-up with the Print listing and Cancel options and the following message:
Successfully generated the elements: ... Would you like to see the listing?
(Optional) Click Print listing to see the Generate output.
Alternatively, click Cancel.
Note: You can always review the Generate output by selecting the Print listing option.
You successfully performed the Generate action.
If Generate fails to process an element, a listing is displayed automatically.
Print Listing
The Print listing option enables you to display the most recently created listing.
Follow these steps:
Right-click an element.
Select the Print listing option.
The contents of the listing appear in the editor area.
You successfully printed the listing.
Sign Out
The Sign out option enables you to lock an element, which prevents other user from editing the element.
Follow these steps:
- Right-click an element.
- Select the Sign out option.
- Enter a CCID.
- Enter a comment.
You successfully signed out the element.
Sign In
The Sign in option enables you to unlock an element that earlier was signed out by you.
Follow these steps:
- Right-click an element.
- Select the Sign in option.
You successfully signed in the element.
Base Profiles
You can use your Zowe CLI default base profile in Explorer for Endevor if you do not have an Endevor profile. To make your default base profile work in the extension, ensure that you specify such parameters as username, password, host, port, and rejectUnauthorized in the base profile. You can run the zowe profiles list base-profiles --sc in the CLI to check if you have a base profile that you can use. If you do not have a base profile and want to create one, run the following Zowe CLI command:
zowe profiles create base <baseprofileName> --user <myusername123> --password<mypassword123> --host <myhost> --port <portnumber> --reject-unauthorized false
Ensure that you set your newly-created base profile as the default base profile. To do so, run the following command:
zowe profiles set-default base-profile <baseprofileName>
For more information, see the Base Profile section on Zowe Docs.
Manage your Profiles
You can perform the following actions to manage your profiles:
Edit a profile: You can edit a profile or update your credentials, using the Zowe CLI and the zowe profiles update endevor-profile <profileName> and zowe profiles update endevor-location-profile <profileName> command. The commands enable you to update the details of existing profiles. If you use the CLI commands to update your profile, ensure that you click the refresh button in the extension so that the changes take effect.
Hide a profile: If you do not want to have some of your profiles in the tree, you can hide such profiles. To hide a profile, right-click the profile and select Hide a Profile option.
Note: The Hide a Profile action does not permanently delete the profile.
Delete a profile: You can permanently delete your profile from the extension. To delete a profile, issue the CLI command zowe profiles delete endevor-profile <profilename>.
Environment Variables
You can define environment variables to execute Zowe CLI commands more efficiently. For more information, see Using Environment Variables on Zowe Docs.
You can configure the following settings of the extension:
The location where the Edit command stores elements locally
Endevor locations that are loaded at startup
The number of parallel HTTP requests supported by Endevor
Automatic Signout. The signout function locks elements for you. If the option is enabled, retrieved or edited elements are signed out to you. If an element is signed out to somebody else, a notification asking whether to override the signout pops up. If the option is not enabled, the extension just retrieves or edits an element without signout.
Telemetry level. You can disable or configure data that is collected by Telemetry in the VS Code Settings. Navigate to Settings > Application > Telemetry > Telemetry Level to do so. For more information, see Disable Telemetry in the VS Code documentation.
Note: This setting applies not only to Explorer for Endevor but to all extensions in your VS Code.
To access the Explorer for Endevor settings, click Manage (the cog icon on the activity bar) > Settings > Extensions > Explorer for Endevor.
List of Limitations
This section lists notable limitations in the current version of Explorer for Endevor.
Searching elements by comment and CCID is not supported.
You can search using the instance, environment, stageNumber, system, subsystem, and type parameters.
Zowe CLI Secure Credential Store is not supported.
If you have SCS-enabled Endevor profiles, you need to recreate the profiles to successfully use them in Explorer for Endevor.
Only the UTF-8 character encoding is currently supported.
Known Issues
The following topics contain information that can help you troubleshoot problems when you encounter unexpected behavior while using Explorer for Endevor:
Topic 1 — Removed profile persists in the tree.
Symptoms:
The deleted profile does not disappear from the tree after the deletion.
Cause:
This behavior occurs if you use the CLI command to delete your profile but do not delete the profile from the Explorer for Endevor settings.json file.
Solution:
To permanently delete the profile from the tree, use the extension settings.
Follow these steps:
- Navigate to the VS Code settings.
- Open Explorer for Endevor Settings and edit the settings.json file.
- Delete the
service and elementLocations properties of the profile you want to delete from the tree.
- Save the settings.json file.
You successfully deleted your profile from the extension.
Contribute to Explorer for Endevor
We encourage you to contribute to Explorer for Endevor.
How can you improve Explorer for Endevor? Open an issue in our Git repository
Eclipse Che4z
Explorer for Endevor is included with Eclipse Che version 7.6.0 and above. For more information, see the Eclipse Che4z webpage.
Privacy Notice
The extensions for Visual Studio Code developed by Broadcom Inc., including its corporate affiliates and subsidiaries, ("Broadcom") are provided free of charge, but in order to better understand and meet its users’ needs, Broadcom may collect, use, analyze and retain anonymous users’ metadata and interaction data, (collectively, “Usage Data”) and aggregate such Usage Data with similar Usage Data of other Broadcom customers. Please find more detailed information in License and Service Terms & Repository.
This data collection uses built-in Microsoft VS Code Telemetry, which can be disabled, at your sole discretion, if you do not want to send Usage Data.
The current release of Explorer for Endevor collects anonymous data for the following events:
- Extension commands, such as Add, Retrieve, Sign in, Sign out, Edit, Generate, etc.
- Build the tree view, refresh the tree view
- Internal and Endevor errors
Note Any sensitive information is filtered, so the extension gets only anonymous error messages and Endevor REST API error codes. The Endevor REST API error codes are collected for the purposes of determining errors in the extension lifecycle.
Each such event is logged with the following information:
- Event time
- Operating system and version
- Country or region
- Anonymous user and session ID
- Version numbers of Microsoft VS Code and Explorer for Endevor
Technical Assistance and Support for Explorer for Endevor
The Explorer for Endevor extension is made available to customers on the Visual Studio Code Marketplace in accordance with the terms and conditions contained in the provided End-User License Agreement (EULA).
If you are on active support for Endevor, you get technical assistance and support in accordance with the terms, guidelines, details, and parameters that are located within the Broadcom Working with Support guide.
This support generally includes:
- Telephone and online access to technical support
- Ability to submit new incidents 24x7x365
- 24x7x365 continuous support for Severity 1 incidents
- 24x7x365 access to Broadcom Support
- Interactive remote diagnostic support
Technical support cases must be submitted to Broadcom in accordance with guidance provided in “Working with Support”.
Note: To receive technical assistance and support, you must remain compliant with “Working with Support”, be current on all applicable licensing and maintenance requirements, and maintain an environment in which all computer hardware, operating systems, and third party software associated with the affected Broadcom software are on the releases and version levels from the manufacturer that Broadcom designates as compatible with the software. Changes you elect to make to your operating environment could detrimentally affect the performance of Broadcom software and Broadcom shall not be responsible for these effects or any resulting degradation in performance of the Broadcom software. Severity 1 cases must be opened via telephone and elevations of lower severity incidents to Severity 1 status must be requested via telephone.
Copyright © 2022 Broadcom. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
