Properties Connector

Directory Integrator, Version 7.1.1

Properties Connector

Tivoli® Directory Integrator solutions are packaged into one or more Tivoli Directory Integrator configuration files (XML format) that contain the settings for end point connections, data flow and a host of other features. Although a configuration file can hold everything you need to create a solution, you often may need to use data sources external to the configuration file to modify the behavior of the configuration, such as standard Java properties, Tivoli Directory Integrator external properties and Tivoli Directory Integrator System Store properties.

Property stores are used to hold configuration information in the format of key=value. The Properties connector is used to work with such stores, performing operations of reading/writing of properties and encryption/decryption of certain property values. The familiar global.properties and solution.properties are examples of such property stores.

Individual property stores can be encrypted with individual Certificates, by means of the Property Key and Encrypt parameters. This allows a certificate that is different from the server certificate to be used for encrypting and decrypting both properties in the file, and the entire file if wanted. This may be useful when multiple developers are working on a project, and credentials cannot be shared.

This Connector uses an internal memory buffer to hold all properties in a properties file. The Connector can also be used to access the JavaVM system properties object.

The Connector supports Iterator, AddOnly, Update, Lookup and Delete mode.

Configuration

The Properties Connector uses the following parameters:

Collection Path/URL: Specifies the properties file to read/write when collection type if File/URL. This parameter is required if the collection type is File/URL.
Create: Checkbox, when checked (which is the default), it will automatically create the file. If this checkbox is empty and the file is missing an exception is thrown.
Encrypt: Check to cause this collection of properties to be encrypted using the Password entered. Default value is unchecked, i.e. "false".
Cipher Alg.: The cipher algorithm to use when either Encryption=TRUE or the stream contains individually encrypted values. Specify "server" to use Tivoli Directory Integrator server encryption. The Default cipher provided in global.properties or solution.properties in property com.ibm.di.server.encryption.transformation.
When the Property Key parameter is specified, this parameter specifies the algorithm to use with that key. If keyalias is not specified, this parameter specifies the algorithm to use when encrypting the entire file. In this case the word "server" means to use Tivoli Directory Integrator server encryption, anything else uses the password from the Password parameter as a key for the algorithm.
Password: The secret key to use when encrypting/decrypting the stream/property values.
Only used if Property Key is not specified, Encrypt is checked, and Cipher Alg. is not "server".
Property Key: The name of the Certificate in the server keystore that should be used to encrypt or decrypt individually encrypted values in the Properties File. If the Encrypt parameter is set to true, this certificate will also be used to encrypt or decrypt the entire Properties file. Note that if this parameter is set, it overrides the values of the Password parameter.
This parameter is a dropdown list; the dropdown list is automatically filled with the names found in the server keystore.
AutoRewrite: If true, the Connector will write back the contents if any auto-encrypted values were found.
If this parameter is set to true, the collection will immediately be written back if any value was automatically encrypted. If a property is marked with "{protect}-" in front of the property name, the value will be automatically encrypted if it is not encrypted. If this parameter is not set to true, the collection must be written back by programmatic means.
Detailed Log: Checking this box will cause additional log messages to be generated.

Using the Connector

The Property Connector is used to connect to standard .property files, Java Properties or the System Store User Property Store. It provides encryption/decryption of the stores being read/written.

The typical behavior of this connector is to connect to a .property file specified by its URL. This can be achieved by setting the collection parameter of the connector, and constitutes "User-Defined" properties.

However, you can also access the system-defined property stores: JVM ("java") properties, User Property Store, global.properties and solution.properties. In order to do this, you need to set the collectionType property of the connector. It is not exposed in the configuration screen but can be set with the following script (for example, put in the Prolog -> Before Initialize hook):

JVM Properties: thisConnector.connector.setParam("collectionType", "Java-Properties");
User Property Store: thisConnector.connector.setParam("collectionType", "System-Properties");
global.properties: thisConnector.connector.setParam("collectionType", "Global-Properties");
solution.properties: thisConnector.connector.setParam("collectionType", "Solution-Properties");

Note:

These property collections are those that show up in the "Properties" folder in the Config Browser for a given configuration file. These can be modified using the Config Editor, and this may make it unneccesary to use this Connector to access or alter any of the properties in these property collections at runtime.

All of these stores are shared within the same JavaVM, which means that an AssemblyLine writing to the System Store will affect all other AssemblyLines in the JavaVM reading from the same store.

All of the properties in the global and solution stores are propagated to the Java property store by the Tivoli Directory Integrator server at startup in that order. The point to make here is that the global and solution stores can now be discretely addressed and modifications to these files, if permitted, can also be made. Each property store is given a unique name that is unique within the confines of a configuration instance. If a Tivoli Directory Integrator server runs multiple configuration instances, they will share the Java, global, solution and all System-Store property stores (for example, system) but all others are local to the configuration instance.

Note:

When using the Connector to deal with external properties, the Auto-Rewrite parameter should be set to true if you want to automatically write back encrypted properties without calling an explicit "commit".

The link criteria for the Properties Connector can only be a single criteria in the form 'key equals keyvalue', where keyvalue is the key value to be found. More advanced searches are not possible.

Properties File Format

# comment
' comment
// comment
!include filename
!merge filename

[{protect}-]keyword <colon | equals> [{encr}]value

Notes:

The optional {protect}- prefix indicates that the value either is or should be encrypted. When the value starts with the character sequence {encr} it means that the value is already encrypted.
"!include" reads an external file/URL with properties which are written unconditionally to the current property map.
"!merge" reads an external file/URL with properties which are written to the current property map if the property does not already exist (non-destructive write).
TDI currently uses the equal sign "=" or colon ":" as the separator in key/value pairs property files, whichever is first. Using equal signs or colons in property names and property values is therefore not supported. The property file key/value separator in TDI V6.0 and earlier was only the ":" character; therefore, property files migrated from V6.0 and earlier may require editing.

Syntax checking is used on properties files that are read in directly by the Properties Connector, the Tivoli Directory Integrator Server and the CE. If any nonblank line does not adhere to the properties file format, an Exception will be thrown.

Headers in the Property file

The first one or two lines in a Property File will be lines beginning with this String

##{PropertiesConnector}

This signifies that this line is a header that is rewritten every time the Property File is written.

The first line will look like this

##{PropertiesConnector} savedBy=user, saveDate=date

where user is the name of the user that saved the file and date is the date the file was saved.

If the Property Key parameter was specified when writing the file, the next line will look like this

##{PropertiesConnector} encryptionKey=keyAlias

where keyAlias is the value of the Property Key parameter.