-
Notifications
You must be signed in to change notification settings - Fork 86
Defining and Programming Profiles
This document describes how programmers define profiles and how they access profile information when a Zowe operation is performed.
- Defining profiles
- Configure commands to load profiles
- Profile dependencies
- API to access profiles from a CLI app
- API to access profiles from a GUI app
CLI programmers define profiles by populating the profiles property on an Imperative configuration document. You can define as many profile types as you need.
Example Configuration:
{
"profiles": [
{
type: "banana",
schema: {
type: "object",
title: "The Banana command profile schema",
description: "The Banana command profile schema",
properties: {
age: {
type: "number",
},
color: {
type: "string",
includeInTemplate: true
},
},
required: ["age", "color"],
},
}
]
}Example banana profile contents:
"RipeBanana": {
"type": "banana",
"properties": {
"age": 15,
"color": "yellow"
}
}
The profile type property is a string identifier for the profile and its structure (schema). You use the type property to organize profiles on disk (placed in their respective type directories), build profile commands/options, and indicate the types of profiles that should be loaded for a command.
The schema document describes the structure of the respective profile type. The profile schema follows the JSON Schema standard. Imperative uses the schema when saving, loading, and validating profiles to help ensure that the contents of a profile conforms to its type requirements.
More information:
- For an in-depth look at schema, see JSON Schema.
You can specify the following properties of a schema to further refine the functionality of a profile:
Refer to the code comments in the IProfileProperty interface for more information.
To expose a profile property to CLI users, you must specify an optionDefinition for the property. Define an optionDefinition if users will need to provide input on that property.
For information about how you apply optionDefinition in a profile schema, see Auto-generated Create Profile Command.
The zowe config init command creates a template team config file for the user. That command will create a set of important profile properties (with empty values) in the team config to give the user a starting point. CLI and plug-in programmers can specify which properties of the profiles that they define should be included when such a template is created by setting the includeInTemplate property to true within the definition of that profile property.
If your application manages sensitive information, such as user passwords or other important data, the Imperative CLI Framework provides a mechanism (secure credential manager) to store the data securely.
You can specify secure: true as a profile schema property to indicate that you want the data in that field to be stored securely. For example:
Note: If you do not specify a value for secure, or if you specify false for secure, the data is stored in plain text.
myParent: {
type: "object",
properties: {
securedProperty: {
type: "object",
properties: {
myUnsecuredChild: {
optionDefinition: {
description: "The unsecured-secured property",
type: "string",
name: "sec1",
required: true
},
secure: false,
type: "string"
},
mySecuredJson: {
optionDefinition: {
description: "The secured JSON",
type: "json",
name: "secJson",
required: true
},
secure: true,
type: "json"
},
mySecuredString: {
optionDefinition: {
description: "The secured string",
type: "string",
name: "secString",
required: true
},
secure: true,
type: "string"
},For more information on how to manage secure property values, see Managing Secure Properties.
After you define the profile types on your configuration document, you specify the profile type (or types) that you want the command to load in the profiles property in the command definition document.
By default, when you specify a profile that your command uses, the framework automatically adds options that let you specify which profile of that type you want to use (unless the command definition requests that the option be suppressed). The options are in the form --<type>-profile.
Example Command:
{
"definitionTree": {
"name": "fruit",
"description": "Work with fruits",
"type": "group",
"children": [
{
"name" : "eat",
"type" : "command",
"handler": "/handlers/eat",
"profile": {
"required": ["banana"],
"optional": ["strawberry"],
"suppressOptions": []
}
}
]
}
}An array of required profile types. Required implies that a command will fail (before invoking the handler) if no profile of the required type (or types) are available.
An array of optional profile types. Optional implies that a command can proceed (the handler will be in invoked) if a profile of the optional type (or types) is not available.
An array of profile types for which Imperative will NOT auto-generate command options.
You can configure a profile type to be dependent on another profile type (or types).
Example:
The following example illustrates a profile type configuration with the dependencies property. In this example, a profile of type "bunch" requires that a dependency be listed for a "banana" profile and can optionally specify a dependency of type "strawberry".
{
type: "bunch",
schema: {
type: "object",
title: "The fruit bunch",
description: "The fruit bunch schema",
properties: {
},
required: [],
},
dependencies: [{
type: "banana",
required: true
}, {
type: "strawberry",
required: false
}]
}
Dependencies are loaded automatically when the profile that contains the dependencies property is loaded.
Once Imperative has loaded the required/optional profiles for a command, they are passed to the command handler on the handler parameters object. Typically, CLI commands do not have to directly access profiles. Values specified within profiles are automatically merged with command-line parameters and environment variables before the CLI command's command handler is invoked by imperative. The params: IHandlerParameters argument of a command handler contains a set of values that have already been merged appropriately. See Command Option Precedence for details on how the appropriate values are determined.
You may want to access the user's profiles from apps other than command-line apps (like a client GUI app or IDE/Editor extension). You can access the users profiles using the ProfileInfo API.
An introductory article on the ProfileInfo API is located on medium.com : An API to simplify retrieval of Zowe Profile Information.
Detailed documentation for the entire Zowe CLI SDK is available on-line. For this topic, you should start with Class ProfileInfo.
-
Core Features
- Imperative Configuration
- Defining Commands
- Command Handlers
- Command Option Precedence
- Environment Variables
- Help Generator
- Experimental Commands
- Creating Commands Using Chained Handlers
- Configuring Logging
- Working with Team Configuration
- Defining and Programming Profiles
- Managing Secure Properties
- Deprecated User Profiles
- Consuming REST APIs Using the REST Client
- Implementing Progress Bars
- Plugins