Constructor for ProfileInfo class.
The name of the application (like "zowe" in zowe.config.json)
whose configuration you want to access.
Options that will control the behavior of ProfileInfo.
Cache of profile schema objects mapped by profile type and config path if applicable. Examples of map keys:
Returns whether a valid schema was found (works for v1 and v2 configs)
Returns an indicator of whether we are using a team configuration or old-school profiles.
You must call ProfileInfo.readProfilesFromDisk() before calling this function.
True when we are using a team config. False means old-school profiles.
Adds a profile type to the loaded Zowe config.
The profile type must first be added to the schema using addProfileTypeToSchema.
The profile type to add
true if added to the loaded config; false otherwise
Adds a profile type to the schema, and tracks its contribution in extenders.json.
NOTE: readProfilesFromDisk must be called at least once before adding new profile types.
The new profile type to add to the schema
Type metadata for the profile type (schema, source app., optional version)
the result of adding the profile type to the schema
Get arg data type from a "typeof" string. Arg data types can be basic types like string, number, and boolean. If they are any other type or a union of types, their type will be represented simply as object.
The type of a profile property
Given a profile name and type, compute the profile location object containing OS location.
Name of an old school profile (e.g., LPAR1)
Type of an old school profile (e.g., zosmf)
Given a profile name and property name, compute the profile location object containing OS and JSON locations.
Set of options that allow this method to get the profile location
Builds the entire schema based on the available profile types and application sources.
A config schema containing all applicable profile types
Ensures that ProfileInfo.readProfilesFromDisk() is called before an operation that requires that information.
The long form JSON path of the profile we are searching for.
The long form JSON path of the profile we are searching for.
A string array containing the location of all files containing the specified team profile
Get all of the typed profiles in the configuration.
Limit selection to only profiles of the specified type.
If not supplied, the names of all typed profiles are returned.
An array of profile attribute objects. In addition to the name, you get the profile type, an indicator of whether the profile is the default profile for that type, and the location of that profile.
If no profile exists for the specified type (or if
no profiles of any kind exist), we return an empty array
ie, length is zero.
Get the default profile for the specified profile type.
The type of profile of interest.
The default profile. If no profile exists for the specified type, we return null;
Gather information about the paths in osLoc
Profile attributes gathered from getAllProfiles
a list of all available profile types
Returns the schema object belonging to the specified profile type.
The profile type to retrieve the schema from
The schema object provided by the specified profile type
Get the Config object used to manipulate the team configuration on disk.
Our current market direction is to encourage customers to edit the team configuration files in their favorite text editor.
If you must ignore this recommended practice, you must use the Config class to manipulate the team config files. This class has a more detailed and therefore more complicated API, but it does contain functions to write data to the team configuration files.
You must call ProfileInfo.readProfilesFromDisk() before calling this function.
An instance of the Config class that can be used to manipulate the team configuration on disk.
Get all of the subprofiles in the configuration.
The short form profile name dotted path
The long form profile dotted path
The profiles object from the parent profile.
Contains the subprofiles to search through.
Limit selection to only profiles of the specified type.
If not supplied, the names of all typed profiles are returned.
An array of profile attribute objects. In addition to the name, you get the profile type, an indicator of whether the profile is the default profile for that type, and the location of that profile.
If no profile exists for the specified type (or if
no profiles of any kind exist), we return an empty array
ie, length is zero.
Perform a rudimentary initialization of some Imperative utilities. We must do this because VSCode apps do not typically call imperative.init.
The short form profile name dotted path
Limit selection to profiles of the specified type
A boolean true if the profile is a default profile, and a boolean false if the profile is not a default profile
Helper function to identify if the existing config is secure or not
true if the teamConfig is storing credentials securely, false otherwise
Load any profile schema objects found on disk and cache them. For team config, we check each config layer and load its schema JSON if there is one associated. For old school profiles, we load the meta YAML file for each profile type if it exists in the profile root directory.
Load the cached schema object for a profile type. Returns null if schema is not found in the cache.
Profile attributes object
Load value of secure argument from the vault.
Secure argument object
Merge all of the available values for arguments defined for the specified profile. Values are retrieved from the following sources. Each successive source will override the previous source.
The profile whose arguments are to be merged.
Options to use when merging arguments.
This parameter is not required. Defaults will be used.
An object that contains an array of known profile argument values and an array of required profile arguments which have no value assigned. Either of the two arrays could be of zero length, depending on the user's configuration and environment.
We will return null if the profile does not exist
in the current Zowe configuration.
Merge all of the available values for arguments defined for the specified profile type. See mergeArgsForProfile() for details about the merging algorithm. The intended use is when no profile of a specific type exists. The consumer app can prompt for values for missing arguments and then perform the desired operation.
The type of profile of interest.
Options to use when merging arguments.
This parameter is not required. Defaults will be used.
The complete set of required properties;
Given a profile name and type, return the OS location of the associated YAML file.
Type of an old school profile (e.g., zosmf)
Name of an old school profile (e.g., LPAR1)
This helper function removes all command-related properties from the given schema properties object and returns it. This is so we can easily compare schemas from disk with those that are registered with type ICommandProfileSchema. It's also been added to avoid a breaking change (as we currently allow ICommandProfileSchema objects to be registered).
The properties object from the schema
The properties object, but with all of the command-related properties removed
Override values in a merged argument object with values found in environment variables. The choice to override enviroment variables is controlled by an option on the ProfileInfo constructor.
On input, this must be an object containing merged arguments
obtained from configuration settings. This function will override
values in mergedArgs.knownArgs with values found in environment
variables. It will also move arguments from mergedArgs.missingArgs
into mergedArgs.knownArgs if a value is found in an environment
variable for any missingArgs.
Read either the new team configuration files (if any exist) or read the old-school profile files.
The optional choices used when reading a team configuration.
This parameter is ignored, if the end-user is using old-school
profiles.
Remove a known property from the ProfileInfo class
This method will call the updateKnownProperty method with a value set to undefined and serves as a helper function
to make is easier to understand when a known property is removed.
Set of options required to remove a known property
Returns a boolean indicating if the property has been removed
Update a given property with the value provided. This function only works for properties that can be found in the config files (including secure arrays). If the property cannot be found, this function will resolve to false This function supports v1 profiles
Set of options required to update a known property
Update a given property regardless of whether it's found in the config file or not This function supports v1 profiles
Set of options needed to update a given property
Updates the schema of the provided config layer to contain the new profile type.
The profile type to add into the schema
The config layer that matches the schema to update
true if added to the schema; false otherwise
Create a session from profile arguments that have been retrieved from ProfileInfo functions.
An array of profile arguments.
Options that alter our actions. See IOptionsForAddConnProps.
The connOpts parameter need not be supplied.
Default properties may be added to any supplied connOpts.
The only option values used by this function are:
connOpts.requestToken
connOpts.defaultTokenType
A session that can be used to connect to a remote host.
Initialize a session configuration object with the arguments from profArgs
An array of profile argument attributes.
An array of argument names to load from the profile. Defaults to
all arguments that have an associated ISession property.
A session containing all of the supplied profile argument attributes that are relevant to a session.
Convert an IProfAttrs object into an IProfileLoaded objects This is a convenience function. IProfileLoaded was frequently passed among functions. This conversion function allows existing code to acquire values in the IProfAttrs structure but pass those values around in the older IProfileLoaded structure. The IProfAttrs properties will be copied as follows:
IProfileLoaded.name <-- IProfAttrs.profName
IProfileLoaded.type <-- IProfAttrs.profType
IProfileLoaded.profile <-- profAttrs
A profile attributes object.
A JSON object containing additional names from IProfileLoaded for
which a value should be supplied. IProfileLoaded contains more
properties than IProfAttrs. The items in this object will be
placed into the resulting IProfileLoaded object.
We use type "any" because all of the required properties of
IProfileLoaded will not be supplied by dfltProfLoadedVals.
If dfltProfLoadedVals is not supplied, only the following minimal
set if hard-coded properties will be added to the IProfileLoaded object.
IProfileLoaded.message <-- "" (an empty string)
IProfileLoaded.failNotFound <-- false
An IProfileLoaded object;
Reads the extenders.json file from the CLI home directory.
Called once in readProfilesFromDisk and cached to minimize I/O operations.
Attempts to write to the extenders.json file in the CLI home directory.
true if written successfully; false otherwise
Generated using TypeDoc
This class provides functions to retrieve profile-related information. It can load the relevant configuration files, merge all possible profile argument values using the Zowe order-of-precedence, and access desired profile attributes from the Zowe configuration settings.
Pseudocode examples:
// Construct a new object. Use it to read the profiles from disk. // ProfileInfo functions throw a ProfInfoErr exception for errors. // You can catch those errors and test the errorCode for known // values. We are only showing the try/catch on the function // below, but it applies to any ProfileInfo function. profInfo = new ProfileInfo("zowe"); try { await profInfo.readProfilesFromDisk(); } catch(err) { if (err instanceof ProfInfoErr) { if (err.errcode == ProfInfoErr.CANT_GET_SCHEMA_URL) { youTakeAnAlternateAction(); } else { // report the error } } else { // handle other exceptions } } // Maybe you want the list of all zosmf profiles let arrayOfProfiles = profInfo.getAllProfiles("zosmf"); youDisplayTheListOfProfiles(arrayOfProfiles); // Maybe you want the default zosmf profile let zosmfProfile = profInfo.getDefaultProfile("zosmf"); youUseTheProfile(zosmfProfile); // Maybe you want the arg values for the default JCLCheck profile let jckProfile = profInfo.getDefaultProfile("jclcheck"); let jckMergedArgs = profInfo.mergeArgsForProfile(jckProfile); let jckFinalArgs = youPromptForMissingArgsAndCombineWithKnownArgs( jckMergedArgs.knownArgs, jckMergedArgs.missingArgs ); youRunJclCheck(jckFinalArgs); // Maybe no profile of type "zosmf" even exists. let zosmfProfiles = profInfo.getAllProfiles("zosmf"); if (zosmfProfiles.length == 0) { // No zosmf profile exists // Merge any required arg values for the zosmf profile type let zosmfMergedArgs = profInfo.mergeArgsForProfileType("zosmf"); // Values of secure arguments must be loaded separately. You can // freely log the contents of zosmfMergedArgs without leaking secure // argument values, until they are loaded with the lines below. zosmfMergedArgs.knownArgs.forEach((arg) => { if (arg.secure) arg.argValue = profInfo.loadSecureArg(arg); }); let finalZosmfArgs = youPromptForMissingArgsAndCombineWithKnownArgs( zosmfMergedArgs.knownArgs, zosmfMergedArgs.missingArgs ); youRunSomeZosmfCommand(finalZosmfArgs); } // So you want to write to a config file? You must use your own // old-school techniques to write to old-school profiles. // You then use alternate logic for a team config. // You must use the Config API to write to a team configuration. // See the Config class documentation for functions to set // and save team config arguments. // Let's save some zosmf arguments from the example above. let yourZosmfArgsToWrite: IProfArgAttrs = youSetValuesToOverwrite( zosmfMergedArgs.knownArgs, zosmfMergedArgs.missingArgs ); if (profInfo.usingTeamConfig { let configObj: Config = profInfo.getTeamConfig(); youWriteArgValuesUsingConfigObj( configObj, yourZosmfArgsToWrite ); } else { youWriteOldSchoolProfiles(yourZosmfArgsToWrite); }