Automatic Zowe CLI Service Configuration Using API Mediation Layer
{Core} Since ancient times, The Open Mainframe Project’s Zowe Command Line Interface (CLI) has had its fair share of intricacies for storing connection details and sharing configuration information. The CLI Squad has implemented a new command to the Zowe vNext version, which is available as @next on public NPM. Introducing:
zowe config auto-init
Process, Benefits, and Usage
The auto-init command was built thanks to one of the latest features introduced by the APIML squad. Said feature allows for client applications to obtain information about the available API services on the instance. For more information about this feature, see APIML Service Information: API Endpoints
This command automatically sets all connection properties for you, providing a more streamlined configuration with an API Mediation Layer (APIML) instance. It also creates a configuration file that is ready to be consumed by other CLI commands and other client applications, as well as a schema file based on the plugins installed on your client machine.
What can be expected from the command?
The config auto-initcommand prompts for credentials as well as information about the APIML instance that you are trying to configure. Also, it has options to influence its behavior. For example: --dry-run for displaying the outcome of the command without saving,--user-config for saving the contents in a user config layer, --overwrite for replacing any existing configuration, and many more. Here is an example of the command in its most basic form:
$ zowe config auto-init
Enter the host name of your API Mediation Layer: myHost.example.com
Enter the port number for your API Mediation Layer: 12345
Enter user name: myUserID
Enter password : *******************After the command ends, you will end up with two files (zowe.config.json and zowe.schema.json) created in the directory in which you ran the command. It is possible for the generated config file to contain plugin-specific profiles based on appropriate CLI plugin configuration and APIML service availability. Here is a zowe.config.json file which contains a CICS profile as an example:
{
"$schema": "./zowe.schema.json",
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"basePath": "/zosmf/api/v1"
}
},
"ibmzosmf": {
"type": "zosmf",
"properties": {
"basePath": "/ibmzosmf/api/v1"
}
},
"ibmcics": {
"type": "cics",
"properties": {
"basePath": "/ibmcics/api/v1"
}
},
"my_base": {
"type": "base",
"properties": {
"host": "myHost.example.com",
"port": 12345
},
"secure": [
"authToken"
]
}
},
"defaults": {
"cics": "ibmcics",
// Multiple services were detected.
// Uncomment one of the lines below to set a different default.
//"zosmf": "ibmzosmf",
"zosmf": "zosmf",
"base": "my_base"
}
}What can be done with the output files?
You can open this file in your editor of choice or run zowe config auto-init --edit
which will open the config file in your default editor. You should be able to add new services or change any default profiles generated. For example, you may want to switch the default zosmf profile to the ibmzosmf profile in the above file.
You can also make this your global configuration by manually moving the config and schema files to your ~/.zowe folder or running the same command with the global config option like:zowe config auto-init --global-config
For more information about the command options, run zowe config auto-init --help
Developer Notes and Usage
As a developer of a client application (e.g. CLI plugin, VS Code extension, Web App) and/or REST API service connecting to APIML, it is important to take into consideration the following items in order for these features to work. Said considerations are: The minimum versions, the REST API configuration, and the plugin configuration.
Minimum Versions
The earliest version in which these features can properly be used are:
- Zowe CLI: >=
7.0.0-next.202107131230 - Zowe Imperative: >=
5.0.0-next.202107122104 - Zowe REST API SDK: >=
1.5.1 - Zowe APIML: >=
1.19.0
REST API Configuration
When it comes to REST API Service configuration, there are many properties in the application.yml file to consider, however it is imperative that the service is configured properly with the apiId property.
# …
apiInfo:
- apiId: apiml.sample.service # Very important
version: 1.0.0
gatewayUrl: api/v1
# …
- apiId: apiml.sample.service # Don't forget it
version: 2.0.0
gatewayUrl: api/v2
defaultApi: true
# …
# …For more information, see Configuring Your Service.
CLI Plugin Configuration
Whether you are still developing your plugin for @zowe-v1-lts or have already released a Zowe vNext compatible version, it is important to think about supporting the automatic configuration of your zowe.config.json file using APIML. For this, we have introduced a new Imperative configuration property named apimlConnLookup, which is a collection of APIML Service Attributes containing apiId, gatewayUrl, and connProfType. See Imperative API Reference or Imperative vNext API Reference (requires login credentials) for more information.
{
// …
"apimlConnLookup": [
{
"apiId": "place_the_cics_apiId_here",
"gatewayUrl": "api/v1",
"connProfType": "cics"
}
]
}Summary
The new zowe config auto-init command provides an easier configuration with your API Mediation Layer instance by looking at the available Zowe vNext Conformant APIML Services to automatically create profiles based on the Zowe vNext Conformant plugins that you have installed.
Learn More:
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.
Zowe is owned and managed by the Open Mainframe Project which is a Linux Foundation project.
