Configure Endevor and Web Services for External Clients
In Endevor Web Services, the Modernization Launchpad, David McNierney details the wide variety of modern development workflows that you can make available to your developers simply by setting up Web Services. This blog details some of the configuration options and cleanup approaches you can take to best prepare your developers for concurrent development in Endevor and in clients of Web Services such as Bridge for Git and Explorer for Endevor.
When your developers access their Endevor source code via Web Services, ensure that they are able to find and access their elements easily, that the elements are fully defined for code editors to recognize them, and that the element content is correctly read and maintained.
Get your Endevor Elements in Order!
When a developer works with elements outside of Endevor, they will typically see the elements organized in the inventory location by type. Such clients of web services as Bridge for Git and Explorer for Endevor provide methods of filtering to narrow the scope of an inventory.
However, one of the common issues we have seen with customers is that they have a lot of old elements and element types that are really not used for anything anymore. As such, developers may end up seeing a lot of elements that they know nothing about and that will clutter their workspace.
While it may seem obvious, we encourage some simple housekeeping. Clean up your inventory of elements and element types that are no longer needed or used. Similarly, if you find that there are groups of elements that fall under one type, perhaps consider the creation of a new type or types to contain them.
Clearly Define your Element Types
In addition to simply cleaning up your Endevor inventory, ensure that you check your type definitions so that they have all the relevant information for external clients. One of the overlooked configuration options for a type is setting a file extension.
When developers open the elements in a code editor such as Visual Studio Code, having the proper file extension will enable the reading of the file by extensions like those provided in the Code4z extension pack. This means that developers can leverage such capabilities as autocomplete, syntax highlighting, and diagnostic features when working with their elements.
Without file extensions set, developers can still get such features if they go through their own configuration steps in their code editor, but why push the effort to them? Set the extension as part of the type definition and your developers will be able to get on with their development! Note that you be sure to set the type definition consistently throughout your Endevor map.
As an example, consider your COBOL elements. The COBOL Language Support extension that is part of Code4z recognizes files with the extensions .cob, .cbl, and .cobol. At the same time, it will provide syntax coloring for Copybooks that use either .cpy or .copy as their extension. For more information on file extensions and all configuration parameters for types, see Defining Types.
One point to reiterate here is the cleanup and potentially defining new types. We worked with a customer who was cleaning up their Endevor inventory and determined that they effectively had two kinds of copybooks that used the same file extension, .cpy.
Some of these were procedural copybooks that were actually managed outside of Endevor and were meant for editing only with the external tool, while the others were normal data copybooks. Moreover, the developers at the customer site were meant to use a particular naming convention with the procedural copybooks by placing “P” in the third position of the element name.
Unfortunately, the convention was not fully followed, and they ended up with a mess. With our guidance, they decided to evaluate all copybooks and split them into two types with different extensions, .cpy (for editing in Endevor or clients) and .cobcopy (meant to be edited in the external tool).
¦ $ ה What about Encoding? 丢 £ ¦
One thing that is especially important to consider when configuring Web Services is what character set your developers are using. Do your developers comment on programs with diagrams that use certain shapes like broken pipes ¦ ¦ ? Do you have conventions that use pound £ signs in element names? Do your developers make comments in the local language and expect them to be properly synchronized to all clients? All these scenarios are affected by the configuration of code page and character set.
When developers access and work with elements via a client of Web Services, it is essential that the element content, written within a specific code page, is mapped to the correct character set. Then the content can be correctly displayed/read in a code editor. In the configuration for Web Services, first ensure that you specify the proper CodePage. The default for the configuration file is cp01140, but the setting can vary depending on location and language. Ensure that it matches the code page your developers use in their 3270 emulator settings when working with Endevor elements.
Then also specify the CharacterSet. As of Endevor version 19, the default which is UTF-8, is also the recommended setting. Importantly, in previous versions of Endevor the default was ISO8859–1. We strongly recommend that you change the setting to UTF-8 if it is different. Using UTF-8 will provide your developers with a better working experience, particularly when they access their Endevor source in a code editor such as VS Code. Please note that if you are already using clients such as Bridge for Git or the Endevor plug-in for Zowe CLI, you should keep your current configuration.
For more information on these parameters, see Step 8: Create the Web Services Configuration File.
Ease of Access with the Zowe API Mediation Layer
A more advanced optional configuration task, but one of great benefits for all users, is to register Web Services with the Zowe API Mediation Layer and enable PassTickets for advanced authentication. This allows for single sign-on (SSO) and the use of certificates and personal access tokens (PATs).
The Zowe API Mediation layer by itself provides a great number of benefits to any organization, such as high availability, encrypted communication for API services, and scalability of services. But the advanced authentication and single sign-on experience are key for clients of Endevor Web Services.
Rather than have your developers store their mainframe credentials within a client application, they can simply provide credentials to the API Mediation Layer and receive a personal access token that will be used for their sessions. This relieves developers of the burden of needing to enter or maintain credentials in yet another application and will provide a greater level of security to their workflows.
For a great overview, read Elliot Jalley’s blog Two Peas in a Pod — Endevor and the Zowe API Mediation Layer. For a technical overview of the integration with Web Services, see Integrate REST API with the Zowe API Mediation Layer.
What’s Next after Configuration?
You should now have a good idea of some of the configuration tasks to complete in order to best prepare your developers to work with elements outside of Endevor. If you are not familiar with them already, have a look at some more information about products that leverage Endevor Web Services:
Or take another look at our DevOps Modernization Roadmap toolkit.
Once you have more developers taking advantage of these clients and producing more of a load against Web Services, you can look at the more advanced steps, such as scaling up and managing STC pooling, JVM memory settings, the temporary DASD space, and leveraging the load balancing of API Mediation Layer. We will cover these topics in a future blog.
Thanks for reading, and, as always, follow the Modern Mainframe space here on Medium for more articles about the above solutions and more.
*Shout out to Michal Vahala and Michal Vasak for their contributions!
