Skip to main content

%SYS.ConfigStore.Configuration

abstract persistent class %SYS.ConfigStore.Configuration extends %Library.Persistent, %JSON.Adaptor

SQL Table Name: %SYS_ConfigStore.Configuration

Persistent storage for configuration items in the ConfigStore framework.

Each configuration represents a named set of parameters for a specific area/type/subtype combination (e.g., AI.LLM.OpenAI.MyConfig).

Configurations support:

Naming Rules for Area, Type, Subtype, and Name:

Access Control:
Configurations use a two-tier permission model:
Secret References:
Configuration details can reference secrets stored in the Wallet using the format: Note: Only "CUSTOM" type secrets are supported. If you need to call the Use method of a secret, use plain text instead of secret references.

Validation:
Configurations are automatically validated against their descriptor's schema on save. The Valid property indicates validation status, and ValidationError contains details if validation fails.

Usage:
Do not use this class directly. Users should interact with configurations through the %ConfigStore.Configuration class, which provides the public API for configuration management.

Property Inventory

Method Inventory

Parameters

parameter %JSONIGNOREINVALIDFIELD = 1;
Inherited description: The %JSONIGNOREINVALIDFIELD parameter allows the programmer to control handling of unexpected fields in the JSON input. The default (%JSONIGNOREINVALIDFIELD = 0) will treat an unexpected field as an error. If %JSONIGNOREINVALIDFIELD is set = 1, then unexpected fields will be ignored.

Properties

property Area as %String (MAXLEN = 100) [ Required ];
Area classification (AI, SQL, Integration, etc.)
Must follow naming rules: letters, numbers, hyphens, underscores only
Property methods: AreaDisplayToLogical(), AreaGet(), AreaIsValid(), AreaLogicalToDisplay(), AreaLogicalToOdbc(), AreaNormalize(), AreaSet()
property CreatedAt as %TimeStamp (%JSONINCLUDE = "OUTPUTONLY") [ InitialExpression = $ZDATETIME($ZTIMESTAMP, 3) , Required ];
Creation timestamp (UTC)
Property methods: CreatedAtDisplayToLogical(), CreatedAtGet(), CreatedAtIsValid(), CreatedAtLogicalToDisplay(), CreatedAtLogicalToXSD(), CreatedAtNormalize(), CreatedAtOdbcToLogical(), CreatedAtSet(), CreatedAtXSDToLogical()
property Description as %String (MAXLEN = 2000);
Human-readable description
Property methods: DescriptionDisplayToLogical(), DescriptionGet(), DescriptionIsValid(), DescriptionLogicalToDisplay(), DescriptionLogicalToOdbc(), DescriptionNormalize(), DescriptionSet()
property Details as %DynamicObject (%JSONINCLUDE = "NONE") [ InitialExpression = {} , Required ];
Configuration details (non-secret parameters and secret references)
Secret references use the format: secret://CollectionName.SecretName or secret://CollectionName.SecretName#key.path for nested JSON values
Property methods: DetailsGet(), DetailsGetObject(), DetailsGetObjectId(), DetailsGetSwizzled(), DetailsIsValid(), DetailsNewObject(), DetailsSet(), DetailsSetObject(), DetailsSetObjectId(), DetailsUnSwizzle()
property DisplayName as %String (MAXLEN = 500);
Display name for UI presentation
Property methods: DisplayNameDisplayToLogical(), DisplayNameGet(), DisplayNameIsValid(), DisplayNameLogicalToDisplay(), DisplayNameLogicalToOdbc(), DisplayNameNormalize(), DisplayNameSet()
property EditResource as %String (MAXLEN = 64) [ InitialExpression = $$$AdminConfigStoreResourceName ];
Resource required to edit this configuration
Format: ResourceName or ResourceName:Permission (e.g., "MyResource" or "MyResource:WRITE"). Default permission is WRITE if not specified
An empty string makes the configuration publicly editable
Property methods: EditResourceDisplayToLogical(), EditResourceGet(), EditResourceIsValid(), EditResourceLogicalToDisplay(), EditResourceLogicalToOdbc(), EditResourceNormalize(), EditResourceSet()
property Enabled as %Boolean [ InitialExpression = 1 , Required ];
Enabled flag - can be toggled by administrators
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledNormalize(), EnabledSet()
property FullyQualifiedName as %String (MAXLEN = 512) [ Required ];
Fully qualified name - unique identifier: Area.Type.Subtype.Name or Area.Type.Name
Property methods: FullyQualifiedNameCompute(), FullyQualifiedNameDisplayToLogical(), FullyQualifiedNameGet(), FullyQualifiedNameIsValid(), FullyQualifiedNameLogicalToDisplay(), FullyQualifiedNameLogicalToOdbc(), FullyQualifiedNameNormalize(), FullyQualifiedNameSQLCompute(), FullyQualifiedNameSet(), FullyQualifiedNameSetT()
property ModifiedAt as %TimeStamp (%JSONINCLUDE = "OUTPUTONLY");
Last modification timestamp (UTC)
Property methods: ModifiedAtDisplayToLogical(), ModifiedAtGet(), ModifiedAtIsValid(), ModifiedAtLogicalToDisplay(), ModifiedAtLogicalToXSD(), ModifiedAtNormalize(), ModifiedAtOdbcToLogical(), ModifiedAtSet(), ModifiedAtXSDToLogical()
property Name as %String (MAXLEN = 200) [ Required ];
Simple name (last component of fully qualified name)
Cannot contain dots (.) as they are used as separators in FQN Must follow naming rules: letters, numbers, hyphens, underscores only
Property methods: NameDisplayToLogical(), NameGet(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property ReadResource as %String (MAXLEN = 64) [ InitialExpression = $$$AdminConfigStoreResourceName ];
Resource required to read/use this configuration
Format: ResourceName or ResourceName:Permission (e.g., "MyResource" or "MyResource:READ"). Default permission is READ if not specified
An empty string makes the configuration publicly readable
Property methods: ReadResourceDisplayToLogical(), ReadResourceGet(), ReadResourceIsValid(), ReadResourceLogicalToDisplay(), ReadResourceLogicalToOdbc(), ReadResourceNormalize(), ReadResourceSet()
property Subtype as %String (MAXLEN = 100);
Optional subtype for provider-level refinements
Must follow naming rules: letters, numbers, hyphens, underscores only
Property methods: SubtypeDisplayToLogical(), SubtypeGet(), SubtypeIsValid(), SubtypeLogicalToDisplay(), SubtypeLogicalToOdbc(), SubtypeNormalize(), SubtypeSet()
property Type as %String (MAXLEN = 100) [ Required ];
Type within area (LLM, MCP, JDBC, etc.)
Must follow naming rules: letters, numbers, hyphens, underscores only
Property methods: TypeDisplayToLogical(), TypeGet(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize(), TypeSet()
property Valid as %Boolean (%JSONINCLUDE = "OUTPUTONLY") [ InitialExpression = 0 ];
Validation status - stored and updated on save or explicit validation
Property methods: ValidDisplayToLogical(), ValidGet(), ValidIsValid(), ValidLogicalToDisplay(), ValidNormalize(), ValidSet()
property ValidationError as %String (%JSONINCLUDE = "OUTPUTONLY", MAXLEN = 2000);
Validation error message - stores the reason for validation failure
Property methods: ValidationErrorDisplayToLogical(), ValidationErrorGet(), ValidationErrorIsValid(), ValidationErrorLogicalToDisplay(), ValidationErrorLogicalToOdbc(), ValidationErrorNormalize(), ValidationErrorSet()

Methods

classmethod BuildFQN(area As %String, type As %String, subtype As %String = "", name As %String) as %String
Build fully qualified name from components

Constructs an FQN in the format Area.Type.Name or Area.Type.Subtype.Name

Parameters:
  • area - Area component
  • type - Type component
  • subtype - Optional subtype component
  • name - Name component

Returns:
%String - The fully qualified name
method CopyDetails(Output details As %DynamicObject, resolveSecrets As %Boolean = 1) as %Status
Get configuration details with optional secret resolution

Returns a new dynamic object with configuration details. When resolveSecrets is enabled (default), secret references are replaced by actual secret values retrieved from the Wallet. Secret references use the format: secret://CollectionName.SecretName or secret://CollectionName.SecretName#key.path

Parameters:
  • details - Output parameter containing details with optionally resolved secrets
  • resolveSecrets - If 1 (default), resolve secret references to actual values; if 0, return references as-is

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Create(area As %String, type As %String, subtype As %String, name As %String, details As %DynamicObject, displayName As %String = "", description As %String = "", readResource As %String = $$$AdminConfigStoreResourceName, editResource As %String = $$$AdminConfigStoreResourceName, enabled As %Boolean = 1, validateDetails As %Boolean = 1) as %Status
Create a new configuration

Creates and saves a new configuration with the specified parameters. Validates all inputs and checks permissions before creation. Requires %Admin_ConfigStore:USE permission.

Parameters:
  • area - Area classification (e.g., "AI", "SQL")
  • type - Type within area (e.g., "LLM", "JDBC")
  • subtype - Optional subtype for provider-level refinements
  • name - Simple name for the configuration
  • details - Configuration details as %DynamicObject
  • displayName - Optional display name for UI
  • description - Optional human-readable description
  • readResource - Optional resource for read/use operations (format: ResourceName or ResourceName:Permission, default permission: READ). If omitted, defaults to %Admin_ConfigStore; pass an empty string to make the configuration publicly readable
  • editResource - Optional resource for write operations (format: ResourceName or ResourceName:Permission, default permission: WRITE). If omitted, defaults to %Admin_ConfigStore; pass an empty string to make the configuration publicly editable
  • enabled - Optional enabled flag (default: 1)
  • validateDetails - If 1 (default), validate details against descriptor schema before saving; if validation fails, the operation is rejected with a ConfigStoreValidationFailed error

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Delete(fqn As %String) as %Status
Delete a configuration

Deletes an existing configuration by its fully qualified name. Requires %Admin_ConfigStore:USE permission.

Parameters:
  • fqn - Fully qualified name of the configuration to delete

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Exists(fqn As %String) as %Boolean
Check if a configuration exists

Checks whether a configuration with the specified fully qualified name exists.

Parameters:
  • fqn - Fully qualified name of the configuration to check

Returns:
%Boolean - 1 if configuration exists, 0 otherwise
classmethod Export(file As %String, Output numExported As %Integer, area As %String = "*", type As %String = "*", subtype As %String = "*", name As %String = "*", enabled As %String = "*", valid As %String = "*") as %Status
Export configurations to file (class method)

Exports configurations to a JSON file based on filter criteria. The number of configurations exported is returned by numExported. Only exports configurations the user has permission to read. Use "*" to match all values for a filter parameter.

Parameters:
  • file - File path to export to
  • numExported - Output parameter with count of exported configurations
  • area - Filter by area (comma-separated or "*" for all)
  • type - Filter by type (comma-separated or "*" for all)
  • subtype - Filter by subtype (comma-separated or "*" for all)
  • name - Filter by name (comma-separated or "*" for all)
  • enabled - Filter by enabled status ("*", "0", or "1")
  • valid - Filter by validation status ("*", "0", or "1")

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod ExportToStream(ByRef stream As %Stream.Object, Output numExported As %Integer, area As %String = "*", type As %String = "*", subtype As %String = "*", name As %String = "*", enabled As %String = "*", valid As %String = "*") as %Status
Export configurations to stream (class method)

Exports configurations to a JSON stream based on filter criteria. Only exports configurations the user has permission to read. Use "*" to match all values for a filter parameter.

Parameters:
  • stream - Stream to write JSON array to
  • numExported - Output parameter with count of exported configurations
  • area - Filter by area (comma-separated or "*" for all)
  • type - Filter by type (comma-separated or "*" for all)
  • subtype - Filter by subtype (comma-separated or "*" for all)
  • name - Filter by name (comma-separated or "*" for all)
  • enabled - Filter by enabled status ("*", "0", or "1")
  • valid - Filter by validation status ("*", "0", or "1")

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Get(fqn As %String, Output config As %ConfigStore.Configuration) as %Status
Get a configuration by fully qualified name

Opens and returns a configuration object by its FQN. Checks READ permission before returning the configuration.

Parameters:
  • fqn - Fully qualified name of the configuration
  • config - Output parameter containing the configuration object

Returns:
%Status - $$$OK if successful, error status otherwise
method GetDescriptorClass(Output descriptorClass As %String) as %Status
Get the descriptor class for this configuration

Parameters:
  • descriptorClass - Output parameter containing the descriptor class name

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod GetDetails(fqn As %String, Output details As %DynamicObject, checkValid As %Boolean = 1, resolveSecrets As %Boolean = 0) as %Status
Get configuration details with optional secret resolution

Retrieves configuration details, optionally resolving secret references to their actual values. Verifies that the configuration exists, is enabled (if checkValid=1), and the user has READ permission.

Parameters:
  • fqn - Fully qualified name of the configuration
  • checkValid - If 1, require configuration to be enabled and valid (default: 1)
  • resolveSecrets - If 1, resolve secret references to actual values (default: 0)
  • details - Output parameter containing configuration details

Returns:
%Status - $$$OK if successful, error status otherwise
method GetSchema(Output schema As %DynamicObject) as %Status
Get the schema for this configuration

Parameters:
  • schema - Output parameter containing the JSON schema

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Import(file As %String, Output numImported As %Integer, Output numFailed As %Integer, overwrite As %Boolean = 0, Output errors As %DynamicArray) as %Status
Import configurations from file

Imports configurations from a JSON file. The file should contain a JSON array of configuration objects. Each configuration will be validated and saved.

Parameters:
  • file - File path to import from
  • numImported - Output parameter with count of successfully imported configurations
  • numFailed - Output parameter with count of failed imports
  • overwrite - If 1, overwrite existing configurations; if 0, fail on existing (default: 0)
  • errors - Output parameter containing array of error messages for failed imports

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod ImportFromStream(ByRef stream As %Stream.Object, Output numImported As %Integer, Output numFailed As %Integer, overwrite As %Boolean = 0, Output errors As %DynamicArray) as %Status
Import configurations from stream

Imports configurations from a JSON stream. The stream should contain a JSON array of configuration objects. Each configuration will be validated and saved.

Parameters:
  • stream - Stream containing JSON array of configurations
  • numImported - Output parameter with count of successfully imported configurations
  • numFailed - Output parameter with count of failed imports
  • overwrite - If 1, overwrite existing configurations; if 0, fail on existing (default: 0)
  • errors - Output parameter containing array of error messages for failed imports

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Modify(fqn As %String, details As %DynamicObject, displayName As %String, description As %String, readResource As %String, editResource As %String, enabled As %String, validateDetails As %Boolean = 1) as %Status
Modify an existing configuration

Updates an existing configuration's mutable properties. Area, Type, Subtype, and Name cannot be modified after creation. Only provided parameters will be updated; omitted parameters remain unchanged. Requires permission on the configuration's EditResource to modify details, displayName, description, and enabled. Requires %Admin_ConfigStore:USE permission to modify ReadResource or EditResource.

Parameters:
  • fqn - Fully qualified name of the configuration to modify
  • details - New configuration details (optional)
  • displayName - New display name (optional)
  • description - New description (optional)
  • readResource - New resource for read/use operations (optional, format: ResourceName or ResourceName:Permission, requires %Admin_ConfigStore:USE). An empty string makes the configuration publicly readable
  • editResource - New resource for write operations (optional, format: ResourceName or ResourceName:Permission, requires %Admin_ConfigStore:USE). An empty string makes the configuration publicly editable
  • enabled - New enabled status (optional)
  • validateDetails - If 1 (default), validate details against descriptor schema before saving; if validation fails, the operation is rejected with a ConfigStoreValidationFailed error

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod ParseFQN(fqn As %String, Output area As %String, Output type As %String, Output subtype As %String, Output name As %String) as %Status
Parse fully qualified name into components

Parses an FQN in the format Area.Type.Name or Area.Type.Subtype.Name into its components.

Parameters:
  • fqn - Fully qualified name to parse
  • area - Output parameter for area component
  • type - Output parameter for type component
  • subtype - Output parameter for subtype component (empty if not present)
  • name - Output parameter for name component

Returns:
%Status - $$$OK if successful, error status otherwise
method SaveChange() as %Status
Save changes to an existing configuration

This method saves modifications made to a configuration object. It performs validation, applies default values, and updates timestamps. Requires WRITE permission on the configuration's RequiredResource.

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod Use(fqn As %String, ByRef properties As %Any, test As %Boolean = 0) as %Status
Use a configuration

Verifies that a configuration exists, is enabled, is valid, and the user has permission to use it. Calls the descriptor's UseConfiguration method to perform descriptor-specific operations with the resolved configuration details.

Parameters:
  • fqn - Fully qualified name of the configuration
  • properties - Output parameter for descriptor-specific data returned by UseConfiguration
  • test - If 1, perform test/validation only without actual use (default: 0)

Returns:
%Status - $$$OK if successful, error status otherwise
method UseConfiguration(ByRef properties As %Any, test As %Boolean = 0) as %Status
Use configuration through descriptor's UseConfiguration method

Verifies the configuration is enabled and valid, then delegates to the descriptor's UseConfiguration method.

Parameters:
  • properties - Input/Output parameter for descriptor-specific data
  • test - If 1, perform test/validation only without actual use (default: 0)

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod ValidateAll() as %Status
Validate all configurations in the system

Re-validates all configurations against their current descriptor schemas. Updates the Valid and ValidationError properties for each configuration. Useful after descriptor schema changes to identify configurations that need updates.

Returns:
%Status - $$$OK if successful, error status otherwise
method ValidateDetails(Output errorMessage As %String) as %Boolean
Validate configuration against descriptor rules

Parameters:
  • errorMessage - Output parameter containing validation error message if validation fails

Returns:
%Boolean - 1 if valid, 0 if validation fails
classmethod ValidateDetailsByFQN(fqn As %String, details As %DynamicObject, Output errorMessage As %String) as %Boolean
Validate configuration details against descriptor rules (class method)

This class method validates configuration details without requiring an instance. Useful for validating details before creating a configuration.

Parameters:
  • fqn - Fully qualified name of the configuration (e.g., "AI.LLM.OpenAI.MyConfig")
  • details - Configuration details as %DynamicObject to validate
  • errorMessage - Output parameter containing validation error message if validation fails

Returns:
%Boolean - 1 if valid, 0 if validation fails

Queries

query List(area As %String, type As %String, subtype As %String, name As %String, enabled As %Boolean, valid As %Boolean)
Selects FullyQualifiedName As %String, Name As %String, DisplayName As %String, Description As %String, Area As %String, Type As %String, Subtype As %String, Enabled As %Boolean, Valid As %Boolean, ValidationError As %String, ReadResource As %String, EditResource As %String, CreatedAt As %TimeStamp, ModifiedAt As %TimeStamp
Query to list configurations with filtering and access control

Supports comma-separated values for filters. Empty string means match all.

Parameters:
  • area - Filter by area (comma-separated or "*" for all)
  • type - Filter by type (comma-separated or "*" for all)
  • subtype - Filter by subtype (comma-separated or "*" for all)
  • name - Filter by name (comma-separated or "*" for all)
  • enabled - Filter by enabled status ("*", "0", or "1")
  • valid - Filter by validation status ("*", "0", or "1")

Indexes

index (FQNIndex on FullyQualifiedName) [IdKey, Type = key];
Unique index on fully qualified name
Index methods: FQNIndexCheck(), FQNIndexDelete(), FQNIndexExists(), FQNIndexOpen(), FQNIndexSQLCheckUnique(), FQNIndexSQLExists(), FQNIndexSQLFindPKeyByConstraint(), FQNIndexSQLFindRowIDByConstraint()
index (ItemIndex on Area,Type,Subtype,Name) [Unique];
Index on area/type/subtype/name for efficient filtering and hierarchy queries
Index methods: ItemIndexCheck(), ItemIndexDelete(), ItemIndexExists(), ItemIndexOpen(), ItemIndexSQLCheckUnique(), ItemIndexSQLExists(), ItemIndexSQLFindPKeyByConstraint(), ItemIndexSQLFindRowIDByConstraint()

Triggers

trigger OnDelete (BEFORE event DELETE);

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab