Optional Config instance ID in a Config file

You can use the information provided here to work with Optional Config instance ID in a Config file.

The Config Instance is representing a configuration loaded on the IBM Security Directory Integrator Server and the associated Server object. Each AssemblyLine is running in the context of a Config Instance. Through a Config Instance you can query the configuration of AssemblyLines, Connectors, Parsers, Functional Components, start AssemblyLines, get access to running AssemblyLines and query their log files.

Solution Name and Run Name - the Configuration Instance ID:

When a configuration file is loaded by the IBM Security Directory Integrator Server, it becomes a running configuration instance. Each configuration instance has its own configuration ID. No two configuration instances running at the same time are allowed to have the same configuration ID (a configuration ID uniquely identifies a running configuration instance within the IBM Security Directory Integrator Server).

When a configuration instance is started off a configuration file, the IBM Security Directory Integrator Server first checks if the configuration file has a defined Solution Name (a configuration field of the Solution Interface configuration screen). If the Solution Name is present and non-emtpy, the Server uses this name as the configuration instance ID. If the Solution Name is missing or empty, the IBM Security Directory Integrator Server automatically generates a configuration ID.

For example if a configuration file with an absolute file name "C:/IBM/TDI/configs/rs.xml" is loaded into the IBM Security Directory Integrator Server and the file has a Solution Name set to "mysoluname", then the ID of the created configuration instance is "mysoluname". If the same configuration had no Solution Name defined, the configuration instance ID would be something like "C__IBM_TDI_configs_rs.xml".

Note: The clients of the IBM Security Directory Integrator Server API must perceive the automatically generated configuration instance ids as transparent entities – they must not try to guess how these ids are generated, because the algorithm is subject to change in the future. The only guarantee is that if a configuration instance once existed under some automatically generated configuration ID, then certain artifacts such as tombstones and system logs can be accessed later using the same configuration ID. There is no guarantee, however, that if the same configuration file is run again, the newly created configuration instance will have the same automatically generated ID as before.

Generally if the client specifies nothing more than the path to the configuration file while starting a configuration instance, the configuration ID is based solely on the attributes of the configuration file (the Solution Name, if any, or the absolute file name). As a result, if no additional information is provided, a configuration file can be loaded as a configuration instance only once (otherwise there is a conflict of configuration instance ids).

If it is necessary to load multiple configuration instances from the same configuration file, the client needs to provide a unique Run Name for each of the instances. If a run name is supplied when starting a configuration instance, that run name is used as the configuration instance ID of the instance. Consequently a Run Name must not coincide with any of the ids of already running configuration instances.

Each Solution Name and each Run Name must be a valid file name on the platform on which the IBM Security Directory Integrator Server is currently running. The reason for this restriction is that the configuration instance ID (which derives from the Solution Name or the Run Name) is used when storing certain configuration-instance-specific information, such as the System Logs. To avoid file system problems, IBM Security Directory Integrator forbids the following symbols to appear inside a Run Name or a Solution Name: \ / : * " < > | ?

Note:

If a configuration instance is started with a Solution Name that has any of the above symbols in it, the IBM Security Directory Integrator Server will automatically replace that problem symbols with underscores and will log a warning. If a client attempts to start a configuration instance with a Run Name that contains any of the above symbols, the API invocation will fail with an exception.
Avoiding the above symbols is not enough to guarantee that a Run Name (or a Solution Name) will be a valid file name, because the definition of a valid file name differs between file systems. The policy of the Server API to forbid such symbols should be regarded as a best-effort check rather than an absolute protection. As a result it is still possible to start a configuration instance whose Run Name (or Solution Name) is not a valid file name. Such instances will run into file system related problems if they rely on features like the System Log.

Another consequence is that Solution Names and Run Names must appear in the User Registry instead of absolute file-system paths, for configuration instances which use such names.

Suppose that you have a configuration file with absolute file name "C:/IBM/TDI/configs/rs.xml". The table below describes how to refer to configuration instances launched from that file in the User Registry; the table takes into account whether the configuration file has a Solution Name and whether the configuration instance is started with a Run Name:

Solution Name	Run Name	Section in the User Registry
-	-	[CONFIG]:C:/IBM/TDI/configs/rs.xml
-	myrunname	[CONFIG]:myrunname
mysoluname	-	[CONFIG]:mysoluname
mysoluname	myrunname	[CONFIG]:myrunname

It is important to note that permissions in the User Registry are assigned per configuration instance and not per configuration file.

Using Solution Name instead of Config file path:

Note: Only the configuration files placed in this folder can be edited using the Server API.

In IBM Security Directory Integrator 6.1 and previous releases starting a config instance as well as the check-in/check-out functionality of the Server API required the URL (file path) of the config file to be provided. This is no longer necessary in the current version of IBM® Security Directory Integrator, because the same Server API interface methods can be passed the corresponding Solution Name instead. This is a user convenience as Server API clients like the AMC and CLI now accept user-friendly Solution Names instead of cryptic config file paths.

The config file path has a higher priority than the Solution Name. This means that if the method for starting a config instance (for example) is passed a string (either a config file path or the corresponding Solution Name) and it is a valid config file path then the method treats this value as referring to this config file. If there is a config file and a Solution Name which are identical as strings then the config file path takes precedence. This behavior ensures compatibility with earlier versions of IBM Security Directory Integrator when there were no Solution Names.

At IBM Security Directory Integrator Server startup time, only Configs residing in the IBM Security Directory Integrator configs folder (as specified by the global.properties or solution.properties file parameter api.config.folder) as well as those residing in the Solution Directory can be referred to by their Solution Name.

Scanning the configs folder for Solution Names:

At startup the IBM Security Directory Integrator Server scans the configs folder (specified by the api.config.folder property in global.properties or solution.properties) for the Solution Names of the config files located in the configs folder. The Server then builds an internal map which maps Solution Names to config file paths so that Solution Names can be used in place of config file paths.

The following rules are used when scanning the configs folder:

If the file name has an extension of ".cfg" – return the file name (these would be very old-style Configs)
If a config can be loaded successfully by the config driver, then check for solution name
If a config can not be loaded by the config driver,
1. if the file name has an extension of ".xml" – return the file name
2. different extension – ignore the file and do not return anything

This would lead to the following situations depending on how the IBM Security Directory Integrator server is started:

IBM Security Directory Integrator server in Secure mode	IBM Security Directory Integrator server in Normal mode
PKI-encrypted config – solution name displayed (if existing)	PKI-encrypted config – file name displayed (if extension is .cfg or .xml)
unencrypted config – file name displayed (if extension is .cfg or .xml)	Unencrypted config –IBM Security Directory Integrator solution name displayed (if existing)
password-encrypted config – file name displayed (if extension is .cfg or .xml)	Password-encrypted config – file name displayed (if extension is .cfg or .xml)
non-SDI config file (other, text or binary data) – file name displayed (if extension is .cfg or .xml)	Non-SDI config file (other, text or binary data) – file name displayed (if extension is .cfg or .xml)

We do not recommend that you store files other than valid Config files (XML format or cfg file format) in the configs folder. During attempts to parse any non-config file, errors may be reported and the file is ignored – this does not affect the proper operation of the Server.