Deprecated User Profiles
The following functionality is deprecated. It remains available to provide a transition period. It may be removed in a future release. Warning messages will be displayed from Zowe-cli profile commands stating that the commands are deprecated. The commands will still work successfully.
However, if you place a team configuration file (zowe.config.json) into operation, you are opting-into the team configuration environment. The old style profile commands will then return an error and will not perform their functions. You can return the old style profile commands to a merely deprecated (but operational) state by removing or renaming your zowe.config.json file.
You can access the users profiles using the Basic Profile Manager.
Imperative provides a mechanism to define user configuration profiles. Profiles are simple configuration documents (stored in YAML format) that are intended to persist user configuration properties. A common use case for user profiles is storing multiple sets of connection details (for example, host, port, and credentials) to a remote host (for example, sessions in Putty).
Once Imperative has loaded the required/optional profiles for a command, they are passed to the command handler on the handler parameters object. You can get the loaded profiles by type using params.profiles.get().
Assume the command issued is: fruit eat --banana-profile tasty
Example Handler:
export default class Handler implements ICommandHandler {
public async process(params: IHandlerParameters): Promise<void> {
const banana = params.profiles.get("banana");
params.response.console.log(banana.name);
}
}The handler prints tasty to the console/terminal.
Outside of a CLI (from a client app or IDE/Editor extension), you may want to access the users profiles. You can access the users profiles using the Basic Profile Manager.
Example Profile Load:
The following example illustrates the instantiation of the Basic Profile Manager (BasicProfileManager.ts). You must supply the directory of the CLI's profiles and a type.
Note: The example assumes that the users "Fruit-CLI" profiles are stored in their home directory (Imperative automatically generates the hidden CLI directory and the /profiles/ directory).
const tastyProfile = await new BasicProfileManager({
profileRootDirectory: require("os").homedir() + "/.fruit-cli/profiles/",
type: "banana"
}).load({name: "tasty"});
Unless explicitly disabled, Imperative CLI Framework generates a set of profile management commands automatically. You disable auto-generated profile commands by specifying autoGenerateProfileCommands: false in your Imperative configuration.
For each type of profile defined in your Imperative configuration, one of each of the below types of commands will be generated. For instance, if you have strawberry and banana profile types defined, a profiles create strawberry-profile command and a profiles create banana-profile command will be generated for you.
The user of your CLI uses these commands to create new profiles. In the schema property of your profile configuration, you can specify an optionDefinition field for properties that you would like to be exposed. For most simple profiles, options specified by the user can be automatically mapped to fields in the resulting profile fields.
Example Schema:
{
type: "strawberry",
schema: {
type: "object",
title: "The strawberry command profile schema",
description: "The strawberry command profile schema",
properties: {
age: {
optionDefinition: {
description: "Amount of strawberries",
type: "number",
name: "amount", aliases: ["a"],
required: true
},
type: "number",
},
ripe: {
optionDefinition: {
description: "The strawberries are ripe",
type: "boolean",
name: "ripe", aliases: ["c"],
required: true,
},
type: "boolean",
},
},
required: ["age", "ripe"],
}
}
If you specify optionDefinitions instead of optionDefinition to map multiple option definitions to a single profile field, or if you need to transform the options provided by the user, you will need to specify a createProfileFromArgumentsHandler in your profile configuration. The handler is the same type as any other command handler for your CLI, but it should output the completed profile object by calling commandParameters.response.data.setObj(yourNewProfile). If you do implement a createProfileFromArgumentsHandler, the resulting profile will still be automatically written to the user's disk.
sample-cli profiles create --helpsample-cli profiles create banana-profile old-banana --age 100000
Example createProfileFromArgumentsHandler specification:
profiles: [
{
type: "banana",
createProfileFromArgumentsHandler: "lib/profiles/CreateBananaProfileHandler"
// ...
}]The profiles list commands list profiles that the user created. They can also display the contents of each profile if the –show-contents option is specified.
sample-cli profiles list --helpsample-cli profiles list banana-profiles
The following commands let users delete existing profiles.
sample-cli profiles delete --helpsample-cli profiles delete banana-profile old-banana
The following commands let users update particular fields of their existing profiles.
Similar to the profiles create command, you can specify a custom updateProfileFromArgumentsHandler on your profile configuration if you need special logic for updating the profile. Otherwise, the contents of the new and old profiles will automatically be merged together, with the new profile fields taking precedence over the old ones in case of conflict.
sample-cli profiles update --helpsample-cli profiles update banana-profile old-banana --color blue
Example updateProfileFromArgumentsHandler specification:
profiles: [
{
type: "banana",
updateProfileFromArgumentsHandler: "lib/profiles/UpdateBananaProfileHandler"
// ...
}]The following commands let users check the validity of their existing profiles. For more information, see Validate Profiles.
sample-cli profiles validate --helpsample-cli profiles validate banana-profile old-banana
Imperative CLI Framework contains profile validation infrastructure that lets you (command line developers and users) test the profiles that you create. You can use the infrastructure (for example) after you use the auto-generated profiles commands or your own custom-generated commands to create new configuration profiles.
To use the profile validation infrastructure, build an object that corresponds to the structure of the IProfileValidationPlan interface. The plan contains a list of tasks to perform against the user’s profile to test its validity. Each task, when finished, provides a result (Success, Warning, or Failure), a description of the result, and a list of any associated REST endpoints for the task. Having these specific tasks can make it easier for you to safely test credentials, URLS, file paths, and other data that is stored in the profile before the user starts using your CLI.
Example:
The following example illustrates how to provide a file name that contains a profile validation plan on your profile configuration:
"profiles": [
{
"type": "banana",
"validationPlanModule": "lib/profiles/banana/ValidationPlan"
When you specify a validationPlanModule on the profile configuration, and you also let profiles commands generate automatically, a profiles validate banana-profile command is generated when you call Imperative.init(). CLI users can issue the validate profile command to generate a report that contain the results of the tasks listed in the validation plan. Users can use the report to correct any problems with their profile and run the validation again to confirm the changes.
Users can also issue the command with the --print-plan-only option to generate a table that details which tasks are contained in the plan without actually executing them.