Skip to content
This repository has been archived by the owner on Nov 13, 2023. It is now read-only.

Defining and Programming Profiles

Jump to bottom
Timothy Johnson edited this page Feb 10, 2023 · 2 revisions

Overview

This document describes how programmers define profiles and how they access profile information when a Zowe operation is performed.

Defining profiles

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"
    }
}

Type property

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.

Schema property

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:

Additional configuration for a schema property

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.

Expose profile options with the optionDefinition property

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.

Include a property in a template team config file with includeInTemplate

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.

Store data securely with the secure 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.

Configure commands to load profiles

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": []
                }
            }
        ]
    }
}

Required property

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.

Optional property

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.

Suppress options property

An array of profile types for which Imperative will NOT auto-generate command options.

Profile dependencies

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.

API to access profiles from a CLI app

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.

API to access profiles from a GUI app

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.

IMPERATIVE

Clone this wiki locally