Skip to main content

Config Store

The Config Store is an ObjectScript API for centralized management of configuration data. Access to configuration data is governed by the standard InterSystems IRIS resource-based security model, and all operations are audited.

API Overview

The Config Store API consists mainly of two types of objects:

The main operations on configuration data include:

  • Create — Create a configuration.

  • Use — Use the configuration according to the user-defined method in the descriptor.

  • Modify — Edit a configuration.

  • Delete — Delete a configuration.

  • Import/Export — Import or Export a configuration.

Creating Configurations

A configuration consists of the following:

  • Name — String, the name of the configuration, which has the form: area.type.subtype.logicalname. The subtype is optional.

    For example:

    • AI.MCP.MyServer (subtype omitted; MyServer is the logical name)

    • Integration.JDBC.PostgreSQL.MyConfig

  • Details — A JSON object or %DynamicObjectOpens in a new tab object, the actual configuration data. For example:

     Set configData = { "domain" : "example.com" }

To create and save a configuration to the Config Store, use %ConfigStore.Configuration.Create. This example shows how to use each field and creates a set of example resources to protect it from reads and writes:

 Set SampleConfigData = { "domain" : "example.com" }
 
 Do ##class(Security.Resources).Create("ExampleReadResource")
 Do ##class(Security.Resources).Create("ExampleEditResource")
 
 Do ##class(%ConfigStore.Configuration).Create("Area", "Type", "Subtype", "Example", SampleConfigData, "Example Configuration", "An example configuration", "ExampleReadResource", "ExampleEditResource", 1, 0)

Where (a * (asterisk) indicates that the argument is required):

 Do ##class(%ConfigStore.Configuration).Create(
    "Area",                      ; Area*
    "Type",                      ; Type*
    "Subtype",                   ; Subtype
    "Example",                   ; Logical name*
    SampleConfigData,            ; Details, either JSON or %DynamicObject*
    "Example Configuration",     ; Display name
    "An example configuration",  ; Description
    "ExampleReadResource",       ; Read resource; if omitted, automatically set to %Admin_ConfigStore
    "ExampleEditResource",       ; Edit resource; if omitted, automatically set to %Admin_ConfigStore
    1                            ; Enables the Configuration (default: 1)
    0                            ; Validates the Configuration with a descriptor (default: 1)
 )

For demonstration purposes, the final argument for validation is set to 0 (false) in the previous example. To enable validation for your configurations, see Descriptors.

If you want to verify the contents of the configuration or if you just need more direct access to the configuration data, use %ConfigStore.Configuration.GetDetails. This returns the configuration data as a %DynamicObjectOpens in a new tab:

 Set sc = ##class(%ConfigStore.Configuration).GetDetails("Area.Type.Subtype.Example", .data, 0, 0)
ZWRITE data

data={"domain":"example.com"}  ; <DYNAMIC OBJECT,refs=1></DYNAMIC>

Descriptors

Descriptors describe the data for configurations that share a area.type.subtype. These let you create a schema which validates the contents of a configuration. They also let you create a custom usage method by overriding ConfigStore.Descriptor.UseConfiguration; this method provides a more encapsulated interface for callers that want to use the configuration data compared to %ConfigStore.Configuration.GetDetails, which simply returns a %DynamicObjectOpens in a new tab.

For example, these two configurations share the area, type, and subtype MyApp.Config.Connection in their names and can therefore be described by a single descriptor:

%ZMyApp.Config.Connection.MyDB
%ZMyApp.Config.Connection.MyWebServer

Custom descriptor classes must be mapped to the IRISSYS database by starting their class names with Z, z, %Z, or %z.

The following example creates a simple schema for the domain and port for a server; the latter is not required, so the schema provides a default. This class also overrides ConfigStore.Descriptor.UseConfiguration, which, for demonstration purposes, simply prints out the contents of the configuration and the properties passed to it:

Class %ZSample.ExampleDescriptor Extends ConfigStore.Descriptor
{
    Parameter Area = "Remote";
    Parameter Type = "Server";
    Parameter Subtype = "Info";

    XData Schema [ MimeType = application/json ]
    {
        {
            "domain": {
                "type": "string",
                "required": true,
                "description": "Domain or IP address of the server."
            },
            "port": {
                "type": "string",
                "required": false,
                "default" : "80",
                "description": "Port number of the server."
            }
        }
    }

    ClassMethod UseConfiguration(details As %DynamicObject, ByRef properties) As %Status
    {
        Write "Contents of configuration: ", details.%ToJSON(), !
        Write "Additional arguments: ", properties.%ToJSON(), !
        
        Return $$$OK
    }
}

After defining the descriptor, creating a configuration whose name contains the prefix Remote.Server.Info is validated against the schema if the final argument to %ConfigStore.Configuration.Create() is 1, which indicates that the configuration should be validated:

Invalid data (domain not specified):

 Set invalidData = { "port" : "1234" }
 Set sc = ##class(%ConfigStore.Configuration).Create("Remote", "Server", "Info", "Invalid", invalidData, "Example Configuration", "An example configuration", "ExampleReadResource", "ExampleEditResource", 1, 1)
 
 Do $System.Status.DisplayError(sc)
 
 ERROR #26432: Configuration validation failed for 'Remote.Server.Info.Invalid': ERROR #26404: Required field missing: domain

Valid data:

 Set SampleData = { "domain" : "example.com"}
 Set sc = ##class(%ConfigStore.Configuration).Create("Remote", "Server", "Info", "Example", SampleData, "Example Configuration", "An example configuration", "ExampleReadResource", "ExampleEditResource", 1, 1)

You can then call %ConfigStore.Configuration.Use, passing in the fully-qualified name of your configuration and any other arguments needed to properly use the configuration. This method delegates to your descriptor's custom UseConfiguration method. The above example's implementation simply prints out the configuration information and the optional additional arguments (properties):

 Set sc = ##class(%ConfigStore.Configuration).Use("Remote.Server.Info.Example", { "path" : "v1/status" })
 
 Contents of configuration: {"domain":"example.com","port":"80"}
 Additional arguments: {"path":"v1/status"}

Note that the properties argument is used both for passing in arguments and returning values; if your UseConfiguration implementation needs to return something, it should use properties. This means that if you expect a return value but do not want properties to be mutated, you should make a defensive copy before passing it to %ConfigStore.Configuration.Use.

InterSystems IRIS includes some predefined descriptors, such as for AI Hub, which you can reference as examples:

  • %AI.ConfigStore.LLMDescriptor

  • %AI.ConfigStore.MCPDescriptor

Additional Fields

By default, descriptors enumerate in their Schema all possible keys accepted by a given configuration; fields not listed in the Schema are considered "unrecognized."

To allow unrecognized fields, you can set AllowUnrecognizedDetails:

 // Controls whether unrecognized fields in Details are allowed (default: 0)
 Parameter AllowUnrecognizedDetails As BOOLEAN = 1;

Secrets

To support fields with sensitive content such as API keys or passwords, the Config Store supports referencing secrets stored in the Secure Wallet; these secrets must use the CUSTOM usage type.

For demonstration purposes, this example creates a simple collection, its associated resources, and a secret containing a single API key:

 // Create resources and collection:
 Write ##class(Security.Resources).Create("CollUseResource")
 Write ##class(Security.Resources).Create("CollEditResource")
 Write ##class(%Wallet.Collection).Create("Credentials", {"UseResource" : "CollUseResource", "EditResource" : "CollEditResource"})
 
 // Create a secret containing API key
 Set secret = {"Usage": "CUSTOM", "Secret": {"apiKey": "abc-77461937382857"}}
 Set sc = ##class(%Wallet.KeyValue).Create("Credentials.APIKey", secret)

If you wanted to use this secret in your configurations, you can define a descriptor with a secret field to indicate that the contents of that particular field are a reference to the secret and not the data itself. This example's UseConfiguration method uses the fields defined by the schema to construct a simple HTTP request:

Class %ZSample.ExampleDescriptorWithSecret Extends ConfigStore.Descriptor
{
    Parameter Area = "Remote";
    Parameter Type = "Server";
    Parameter Subtype = "Connection";

    XData Schema [ MimeType = application/json ]
    {
        {
            "domain": {
                "type": "string",
                "required": true,
                "description": "Domain or IP address of the server."
            },
            "port": {
                "type": "string",
                "required": false,
                "default" : "80",
                "description": "Port number of the server."
            },
            "apiKey": {
                "type": "secret",
                "required": true,
                "description": "API key used to authenticate to the server."
            }
        }
    }

    // Error checking omitted for brevity
    ClassMethod UseConfiguration(details As %DynamicObject, ByRef properties) As %Status
    {
        Set http = ##class(%Net.HttpRequest).%New()
        
        Set http.Server = details.domain
        Set http.Port = details.port
        Set http.Https = 1
        Set http.SSLConfiguration = "DefaultSSL"
        
        Do http.SetHeader("Authorization", "Bearer " _ details.apiKey)

        Set properties = http
            
        Return $$$OK
    }
}

When you create the configuration, you can refer to the secret by providing a string in the following format:

secret://CollectionName.SecretName#fieldName

For example, to create a configuration with the above descriptor:

 // Set up config data with reference to secret
 Set SampleSecretData = { "domain": "api.example.com", "apiKey" : "secret://Credentials.APIKey#apiKey" }
 
 // Create the configuration using the secret
 Set sc = ##class(%ConfigStore.Configuration).Create("Remote", "Server", "Connection", "Example", SampleSecretData, "Example Configuration", "An example configuration with a  secret", "ExampleReadResource", "ExampleEditResource", 1, 1)

Editing a Configuration

To modify a configuration, you must have the Use permission on the configuration's EditResource (if it has one) and use %ConfigStore.Configuration.Modify. You can modify any of the properties of a Configuration except its name; the name is used to specify which Configuration to change:

 %ConfigStore.Configuration.Modify(
    name,             ; %String
    details,          ; JSON/%DynamicObject
    displayName,      ; %String
    description,      ; %String
    readResourceName, ; %String, modifying this requires %Admin_ConfigStore:U
    editResourceName, ; %String, modifying this requires %Admin_ConfigStore:U
    enabled           ; %Boolean
    validateDetails   ; %Boolean, whether to validate the configuration with a descriptor
 )

To not modify a particular field, leave it empty. For example, to only change the description:

 Set sc = ##class(%ConfigStore.Configuration).Modify(
    "Sample.Server.Info",,,"New description"
 )

Deleting a Configuration

To delete a configuration, use %ConfigStore.Configuration.Delete():

 Set sc = ##class(%ConfigStore.Configuration).Delete("Sample.Server.Info")

Importing and Exporting Configurations

To export configurations to a JSON file, use %ConfigStore.Configuration.ExportOpens in a new tab. This method lets you export the configurations that match your filter criteria. You can only export configurations that you have privileges to read.

 // Exports the single configuration given
 // by the fully-qualified name "Area.Type.SubType.Example"
 Set sc = ##class(%ConfigStore.Configuration).Export("myconfigs.json", .numExported, "Area", "Type", "Subtype", "Example", *, *)

Where:

 %ConfigStore.Configuration.Export(
    "myconfigs.json",  ; %String, Output file path
    .numExported       ; %Integer, the number of configurations exported
    "Area",            ; %String, the area name (* is a wildcard)
    "Type",            ; %String, the type name (* is a wildcard)
    "Subtype",         ; %String, the subtype name (* is a wildcard)
    "LogicalName",     ; %String, the logical name (* is a wildcard)
    *                  ; Filters for enabled (1), disabled (0), or both (*) configurations
    *                  ; Filters for valid (1), invalid (0), or both (*) configurations
 )

To export all enabled and valid configurations with with the area, type, and subtype "Remote.Server.Info":

 Set sc = ##class(%ConfigStore.Configuration).Export("myconfigs.json", .numExported, "Area", "Type", "Subtype", "*", 1, 1)

To import configurations, use %ConfigStore.Configuration.ImportOpens in a new tab:

 Set sc = ##class(%ConfigStore.Configuration).Import("myconfigs.json", .numImported, .numFailed, 0, .errors)

Where:

 %ConfigStore.Configuration.Import(
    "myconfigs.json",  ; %String, input file path
    .numImported       ; %Integer, the number imported
    .numFailed         ; %Integer, the number that could not be imported
    0                  ; %Boolean, whether to overwrite configurations with the same name (default: 0)
    .errors            ; %DynamicArray, errors during the import process, if any
 )

Privileges

Operations on the config store are protected by the following resources:

  • Create — Requires %Admin_ConfigStore:U

  • Modify or delete — Requires the Use permission on the configuration's Edit resource. If you want to change the Configuration's Edit or Read resource, you also need %Admin_ConfigStore:U.

  • Read or use — Requires the Use permission on the configuration's Read resource.

If you create a configuration without specifying a Read or Edit resource, they are both automatically set to %Admin_ConfigStore.

Auditing

Operations on the config store are audited using the following events:

  • %System/%Security/ConfigStoreChange: Triggered when a user creates, modifies, deletes, imports, or exports a configuration.

  • %System/%Security/ConfigStoreUse: Triggered when a user calls:

    • %ConfigStore.Configuration.Use

    • %ConfigStore.Configuration.UseConfiguration

    • %ConfigStore.Configuration.GetDetails

    • %ConfigStore.Configuration.CopyDetails

  • %System/%Security/AccessDenied: Triggered when a user attempts to use a configuration without the necessary privileges.

FeedbackOpens in a new tab