Interface SzConfigManager

Namespace: Senzing.Sdk

Assembly: Senzing.Sdk.dll

Defines the C# interface to the Senzing config management functions.

public interface SzConfigManager

Examples

An SzConfigManager instance is typically obtained from an SzEnvironment instance via the GetConfigManager() method as follows:

// How to obtain an SzConfigManager instance
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to get SzConfigManager.", e);
}

Methods

CreateConfig()

Creates a new SzConfig instance from the template configuration definition.

SzConfig CreateConfig()

Returns

SzConfig: A newly created SzConfig instance representing the template configuration definition.

Examples

Usage:

// How to create an SzConfig instance representing the template configuration
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // create the config from the template
    SzConfig config = configMgr.CreateConfig();

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to create new SzConfig from the template.", e);
}

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

Code Snippet: Initialize Config

CreateConfig(long)

Creates a new SzConfig instance for a configuration ID.

SzConfig CreateConfig(long configID)

Parameters

configID long: The configuration ID of the configuration to retrieve.

Returns

SzConfig: A newly created SzConfig instance representing the configuration definition that is registered with the specified config ID.

Examples

Usage:

// How to get a config definition by its configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get a valid configuration ID (will vary by application)
    long configID = configMgr.GetDefaultConfigID();

    // get the config definition for the config ID
    SzConfig config = configMgr.CreateConfig(configID);

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to Create SzConfig from config ID.", e);
}

Remarks

If the configuration ID is not found the an exception is thrown.

Exceptions

SzException: If a failure occurs.

CreateConfig(string)

Creates a new SzConfig instance from a configuration definition.

SzConfig CreateConfig(string configDefinition)

Parameters

configDefinition string: The definition for the Senzing configuration.

Returns

SzConfig: A newly created SzConfig representing the specified configuration definition.

Examples

Usage:

// How to create an SzConfig instance representing a specified config definition
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // obtain a JSON config definition (varies by application)
    string configDefinition = ReadConfigFile();

    // create the config using the config definition
    SzConfig config = configMgr.CreateConfig(configDefinition);

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to create a new SzConfig from a definition.", e);
}

Exceptions

SzException: If a failure occurs.

GetConfigRegistry()

Gets the configuration registry.

string GetConfigRegistry()

Returns

string: The JSON object string describing the configurations registered in the repository with their identifiers, timestamps and comments.

Examples

Usage:

// How to get a JSON document describing all registered configs
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get the config definition for the config ID
    string registry = configMgr.GetConfigRegistry();
    demoResult = registry; // @replace
    // do something with the returned JSON (e.g.: parse it and extract values)
    JsonObject? jsonObj = JsonNode.Parse(registry)?.AsObject();

    JsonArray? jsonArr = jsonObj?["CONFIGS"]?.AsArray();

    // iterate over the registered configurations
    if (jsonArr != null)
    {
        for (int index = 0; index < jsonArr.Count; index++)
        {
            JsonObject? configObj = jsonArr[index]?.AsObject();

            long? configID = configObj?["CONFIG_ID"]?.GetValue<long>();
            string? createdOn = configObj?["SYS_CREATE_DT"]?.GetValue<string>();
            string? comment = configObj?["CONFIG_COMMENTS"]?.GetValue<string>();

            . . .

        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to get configurations.", e);
}

Example Result: (formatted for readability)

{
  "CONFIGS": [
    {
      "CONFIG_ID": 2005896641,
      "CONFIG_COMMENTS": "Data Sources: VIPS",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 2194250130,
      "CONFIG_COMMENTS": "Data Sources: EMPLOYEES",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 2397021790,
      "CONFIG_COMMENTS": "Initial config with COMPANIES",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 2421907142,
      "CONFIG_COMMENTS": "Added CUSTOMERS data source",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 2623051006,
      "CONFIG_COMMENTS": "Added PASSENGERS data source",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 2994598643,
      "CONFIG_COMMENTS": "Data Sources: WATCHLIST",
      "SYS_CREATE_DT": "2025-08-29T19:45:12Z"
    },
    {
      "CONFIG_ID": 3075461135,
      "CONFIG_COMMENTS": "Initial Config",
      "SYS_CREATE_DT": "2025-08-29T19:45:11Z"
    }
  ]
}

Remarks

The registry contains the original timestamp, original comment and configuration ID of all configurations ever registered with the repository.

NOTE: Registered configurations cannot be unregistered.

Exceptions

SzException: If a failure occurs.

GetDefaultConfigID()

Gets the default configuration ID for the repository.

long GetDefaultConfigID()

Returns

long: The current default configuration ID, or zero (0) if the default configuration has not been set.

Examples

Usage:

// How to get the registered default configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get the default configuration ID
    long configID = configMgr.GetDefaultConfigID();

    // check if no default configuration ID is registered
    if (configID == 0)
    {
        // handle having no registered configuration ID
        . . .

    }
    else
    {
        // do something with the configuration ID
        . . .

    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to get the default configuration ID.", e);
}

Remarks

Unless an explicit configuration ID is specified at initialization, the default configuration ID is used.

NOTE: The default configuration ID may not be the same as the active configuration ID.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

RegisterConfig(string)

Registers a configuration definition in the repository with an auto-generated comment.

long RegisterConfig(string configDefinition)

Parameters

configDefinition string: The configuration definition to register.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

Usage:

// How to register a configuration with the Senzing repository
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // obtain a JSON config definition (will vary by application)
    string configDefinition = CreateConfigWithDataSources("EMPLOYEES");

    // register the config (using an auto-generated comment)
    long configID = configMgr.RegisterConfig(configDefinition);

    // do something with the config ID
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to register configuration.", e);
}

Remarks

NOTE: Registered configurations do not become immediately active nor do they become the default. Further, registered configurations cannot be unregistered.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

RegisterConfig(string, string)

Registers a configuration definition in the repository.

long RegisterConfig(string configDefinition, string configComment)

Parameters

configDefinition string: The configuration definition to register.
configComment string: The comments for the configuration.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

Usage:

// How to register a configuration with the Senzing repository
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // obtain a JSON config definition (will vary by application)
    string configDefinition = CreateConfigWithDataSources("CUSTOMERS");

    // register the config with a custom comment
    long configID = configMgr.RegisterConfig(configDefinition, "Added CUSTOMERS data source");

    // do something with the config ID
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to register configuration.", e);
}

Remarks

NOTE: Registered configurations do not become immediately active nor do they become the default. Further, registered configurations cannot be unregistered.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

ReplaceDefaultConfigID(long, long)

Replaces the existing default configuration ID with a new configuration ID.

void ReplaceDefaultConfigID(long currentDefaultConfigID, long newDefaultConfigID)

Parameters

currentDefaultConfigID long: The configuration ID that is believed to be the current default configuration ID.
newDefaultConfigID long: The new configuration ID for the repository.

Examples

Usage:

// How to replace the registered default configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    do
    {
        // get the current default configuration ID
        long oldConfigID = configMgr.GetDefaultConfigID();

        // Create a new config (usually modifying the current -- varies by application)
        string configDefinition = AddDataSourcesToConfig(oldConfigID, "PASSENGERS");
        long newConfigID = configMgr.RegisterConfig(configDefinition, "Added PASSENGERS data source");

        try
        {
            // replace the default config ID with the new config ID
            configMgr.ReplaceDefaultConfigID(oldConfigID, newConfigID);

            // if we get here then break out of the loop
            break;

        }
        catch (SzReplaceConflictException)
        {
            // race condition detected
            // do nothing so we loop through and try again
        }

    } while (true);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to replace default configuration ID.", e);
}

Remarks

The change is prevented (with an SzReplaceConflictException being thrown) if the current default configuration ID value is not as expected. Use this in place of SetDefaultConfigID(long) to handle race conditions.

Exceptions

SzReplaceConflictException: If the default configuration ID was not updated to the specified new value because the current default configuration ID found in the repository was not equal to the specified expected current default configuration ID value.
SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

SetDefaultConfig(string)

Registers a configuration in the repository and then sets its ID as the default for the repository with an auto-generated comment.

long SetDefaultConfig(string configDefinition)

Parameters

configDefinition string: The configuration definition to register as the default.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

Usage:

// How to set the registered default configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get the configuration ID (varies by application)
    string configDefinition = CreateConfigWithDataSources("VIPS");

    // set the default config (using an auto-generated comment)
    long configID = configMgr.SetDefaultConfig(configDefinition);

    // do something with the registered config ID
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to set default configuration.", e);
}

Remarks

This is a convenience method for RegisterConfig(string) followed by SetDefaultConfigID(long).

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

SetDefaultConfig(string, string)

Registers a configuration in the repository and then sets its ID as the default for the repository.

long SetDefaultConfig(string configDefinition, string configComment)

Parameters

configDefinition string: The configuration definition to register as the default.
configComment string: The comments for the configuration.

Returns

long: The identifier for referencing the config in the entity repository.

Examples

Usage:

// How to set the registered default configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get the configuration ID (varies by application)
    string configDefinition = CreateConfigWithDataSources("COMPANIES");

    // set the default config (using a specific comment)
    long configID = configMgr.SetDefaultConfig(configDefinition, "Initial config with COMPANIES");

    // do something with the registered config ID
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to set default configuration.", e);
}

Remarks

This is a convenience method for RegisterConfig(string, string) followed by SetDefaultConfigID(long).

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

SetDefaultConfigID(long)

Sets the default configuration ID.

void SetDefaultConfigID(long configID)

Parameters

configID long: The configuration ID to set as the default configuration.

Examples

Usage:

// How to set the registered default configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get the configuration ID (varies by application)
    string configDefinition = CreateConfigWithDataSources("WATCHLIST");
    long configID = configMgr.RegisterConfig(configDefinition);

    // set the default config ID
    configMgr.SetDefaultConfigID(configID);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to set default configuration ID.", e);
}

Remarks

Usually this method is sufficient for setting the default configuration ID. However in concurrent environments that could encounter race conditions, consider using ReplaceDefaultConfigID(long, long) instead.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Initialize Config

Table of Contents

Interface SzConfigManager

Examples

Methods

CreateConfig()

Returns

Examples

Exceptions

CreateConfig(long)

Parameters

Returns

Examples

Remarks

Exceptions

CreateConfig(string)

Parameters

Returns

Examples

Exceptions

GetConfigRegistry()

Returns

Examples

Remarks

Exceptions

GetDefaultConfigID()

Returns

Examples

Remarks

Exceptions

RegisterConfig(string)

Parameters

Returns

Examples

Remarks

Exceptions

RegisterConfig(string, string)

Parameters

Returns

Examples

Remarks

Exceptions

ReplaceDefaultConfigID(long, long)

Parameters

Examples

Remarks

Exceptions

SetDefaultConfig(string)

Parameters

Returns

Examples

Remarks

Exceptions

SetDefaultConfig(string, string)

Parameters

Returns

Examples

Remarks

Exceptions

SetDefaultConfigID(long)

Parameters

Examples

Remarks

Exceptions