Skip to main content

ConfigStore.Descriptor

abstract class ConfigStore.Descriptor extends %Library.RegisteredObject

Base class for configuration descriptors in the ConfigStore framework

This abstract class provides the foundation for defining configuration schemas and validation logic for different types of configurations (AI, SQL, Integration, etc.).

Usage for Customers:
Customers must create subclasses in the %SYS namespace (IRISSYS database) with package names starting with Z, z, %Z, or %z. This ensures the descriptors are properly registered in the ConfigStore framework while preventing them from being overwritten during upgrades.

Example Subclass: 
  Class ZConfigStore.MyJDBCDescriptor Extends ConfigStore.Descriptor
  {
      Parameter Area = "Integration";
      Parameter Type = "JDBC";
      Parameter Subtype = "PostgreSQL";
      
      XData Schema [ MimeType = application/json ]
      {
      {
          "jdbcUrl": {
              "type": "string",
              "required": true,
              "description": "JDBC connection URL"
          },
          "credentials": {
              "type": "object",
              "required": true,
              "description": "Database credentials",
              "properties": {
                  "username": {
                      "type": "string",
                      "required": true,
                      "description": "Database username"
                  },
                  "password": {
                      "type": "secret",
                      "required": true,
                      "description": "Database password (stored in Wallet)"
                  }
              }
          },
          "servers": {
              "type": "array",
              "required": false,
              "description": "List of database servers",
              "items": {
                  "type": "object",
                  "properties": {
                      "host": {
                          "type": "string",
                          "required": true
                      },
                      "port": {
                          "type": "integer",
                          "required": true
                      }
                  }
              }
          }
      }
      }
  }

Key Concepts:
- Area: High-level classification (AI, SQL, Integration, etc.)
- Type: Specific type within the area (LLM, MCP, JDBC, etc.)
- Subtype: Optional provider-level refinement (OpenAI, PostgreSQL, etc.)
- Schema: JSON definition of configuration fields with validation rules

Automatic Registration:
Descriptors are automatically registered via the DescriptorProjection when compiled.

Method Inventory

Parameters

parameter AllowUnrecognizedDetails = 0;
Allow unrecognized fields in Details that are not defined in the schema
parameter Area;
Area classification (AI, SQL, Integration, etc.)
parameter Subtype;
Optional subtype for provider-level refinements
parameter Type;
Type within area (LLM, MCP, JDBC, etc.)

Methods

classmethod GetSchema(Output schema As %DynamicObject) as %Status


Parses the Schema XData block and returns it as a %DynamicObject for programmatic access to field definitions.

Parameters:
  • schema - Output parameter containing the schema as %DynamicObject

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod TestConfiguration(details As %DynamicObject, ByRef properties) as %Status
Test configuration without actually using it

This method validates that a configuration can be used without performing the actual operation. Subclasses can override to implement test-specific logic. By default, this method returns an error indicating it is not implemented.

Parameters:
  • details - Configuration details with secrets resolved (%DynamicObject)
  • properties - Input/Output parameter for passing additional context and returning test results. When called via the REST API, this is a %DynamicObject.

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod UseConfiguration(details As %DynamicObject, ByRef properties) as %Status
Use configuration details to perform descriptor-specific operations

This method is called by applications to utilize a configuration. Subclasses MUST override this method to implement their specific logic for using the configuration details (e.g., establishing connections, initializing clients, etc.).

Parameters:
  • details - Configuration details with secrets resolved (%DynamicObject)
  • properties - Input/Output parameter for passing additional context and returning descriptor-specific data (e.g., connection object, client instance, etc.). When called via the REST API, this is a %DynamicObject.

Returns:
%Status - $$$OK if successful, error status otherwise
classmethod ValidateDetails(details As %DynamicObject, Output errorMessage As %String) as %Boolean
Validate configuration details against the descriptor's schema

This method validates the Details property of a configuration object against the schema definition. It performs:
  • Validates that all required fields defined in the schema are present
  • Validates field types match the schema definition
  • Checks secret reference format for fields with type "secret"
  • Validates nested objects and arrays recursively

Overriding in Subclasses:
Subclasses can override this method to add custom validation logic. When overriding, always call ##super() first to ensure base validation is performed.
Parameters:
  • details - The details object to validate (%DynamicObject)
  • errorMessage - Output parameter containing detailed error message if validation fails

Returns:
1 (true) if validation passes, 0 (false) if validation fails

Inherited Members

Inherited Methods

FeedbackOpens in a new tab