--- title: Configuration interface description: Connectors continue to be released outside the IDM release. For the latest documentation, refer to the OpenICF documentation. component: pingidm version: 7.2 page_id: pingidm:connector-dev-guide:configuration-implementation canonical_url: https://docs.pingidentity.com/pingidm/7.2/connector-dev-guide/configuration-implementation.html section_ids: operation-validate: Validate operation ValidateApiOp-api-level-rules: ValidateApiOp validate-spi-level-rules: Validate SPI implementation configuration-properties-implementation: Supported configuration types --- # Configuration interface | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Connectors continue to be released outside the IDM release. For the latest documentation, refer to the [OpenICF documentation](https://docs.pingidentity.com/openicf/index.html). | The OpenICF connector framework uses the configuration interface implementation to build the *configuration properties* inside the API configuration. The configuration interface implementation includes the required information to enable the connector to connect to the target system, and to perform its operations. The configuration interface implements getters and setters for each of its defined properties. It also provides a validate method that your application can use to check whether all the required properties are available, and valid, before passing them to the connector. The configuration interface has three methods: * `setConnectorMessages(ConnectorMessages messages)` sets the message catalog instance, and lets the connector provide localized messages. The message catalog is defined in the file `Messages.properties`, and can be localized as required by appending the locale to the file name, for example, `Messages_fr.properties`. For more information on the message catalog, refer to [Connector messages object](message-catalog.html). * `getConnectorMessages()` returns the message catalog that is set by setConnectorMessages(ConnectorMessages). * `validate()` checks that all the required properties have been set and that their values are valid. The purpose of this method is to test that the configuration that the application provides to your connector is valid. Each property that is declared is not necessarily required. If a property is required, it must be included in the `ConfigurationProperty` annotation. The `ConfigurationProperty` annotation (Java) or attribute (.NET) lets you add custom meta information to properties. The OpenICF framework scans the meta information and collects this information to build the `ConfigurationProperties` object inside the `APIConfiguration`. The following meta information can be provided: | Element | Description | Implementation in Java | Implementation in C# | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------- | | order | The order in which this property is displayed | | | | helpMessageKey | Lets you change the default help message key | `propertyName.help` | `help_propertyName` | | displayMessageKey | Lets you change the default display message key | `propertyName.display` | `display_propertyName` | | groupMessageKey | Lets you change the default group message key | `propertyName.group` | `group_propertyName` | | confidential | Indicates that this is a confidential property and that its value should be encrypted by the application when persisted | | | | required | Boolean, indicates whether the property is required | | | | operations | The array of operations that require this property | | | The following examples show how the meta information is provided, in both Java and C#. * Java * C# Stateless Configuration Implementation (Java) ```java public class SampleConfiguration extends AbstractConfiguration { /** * {@inheritDoc} */ public void validate() { } @ConfigurationProperty( order = 1, helpMessageKey = "passwordFieldName.help", displayMessageKey = "passwordFieldName.display", groupMessageKey = "authenticateOp.group", confidential = false, required = false, operations = {AuthenticateOp.class,CreateOp.class} ) public String getPasswordFieldName() { return passwordFieldName; } public void setPasswordFieldName(String value) { passwordFieldName = value; } } ``` Stateless Configuration Implementation (C#) ```csharp public class ActiveDirectoryConfiguration : AbstractConfiguration { [ConfigurationProperty( Order = 1, HelpMessageKey = "help_PasswordFieldName", DisplayMessageKey = "display_PasswordFieldName", GroupMessageKey = "group_PasswordFieldName", Confidential = false, Required = false, OperationTypes = new[] { typeof(AuthenticateOp) }) ] public String PasswordFieldName { get; set; } public override void Validate() { throw new NotImplementedException(); } } ``` * Java * C# Stateful Configuration Implementation (Java) ```java public class SampleConfiguration extends AbstractConfiguration implements StatefulConfiguration { /** * {@inheritDoc} */ public void release() { } /** * {@inheritDoc} */ public void validate() { } } ``` Stateful Configuration Implementation (C#) ```csharp public class ActiveDirectoryConfiguration : AbstractConfiguration, StatefulConfiguration { public override void Validate() { throw new NotImplementedException(); } public void Release() { throw new NotImplementedException(); } } ``` ## Validate operation The validate operation validates the connector configuration. A valid configuration is one that is *ready to be used* by the connector. A configuration that is *ready*, has the following characteristics: * It is complete, that is, all required properties are present and have values. * All property values are well-formed, that is, they are in the expected range and have the expected format. ### ValidateApiOp The validate operation returns a `ConfigurationException` in the following situations: * The Framework version is not compatible with the connector. * The connector does not have the required attributes in `MANIFEST.MF`. * The `ConfigurationProperties` cannot be merged into the configuration. Implementation of the valid operation, at the API Level ```java @Test public void ValidateTest() { logger.info("Running Validate Test"); final ConnectorFacade facade = createConnectorFacade(BasicConnector.class, null); facade.validate(); } ``` ## Validate SPI implementation The `validate()` method of the configuration operation must return one of the following: * `RuntimeException` if the configuration is not valid. * `NullPointerException` if a required configuration property is null. * `IllegalArgumentException` if a required configuration property is blank. Implementation of the validate method ```java public void validate() { if (StringUtil.isBlank(host)) { throw new IllegalArgumentException("Host User cannot be null or empty."); } Assertions.blankCheck(remoteUser, "remoteUser"); Assertions.nullCheck(password, "password"); } ``` ## Supported configuration types The OpenICF framework supports a limited number of configuration property types. This limitation is necessary, because OpenICF must serialise and deserialize the configuration property values when sending them over the network. You can use any of the following types, or an array of these types. Lists of types are not supported. ``` String.class long.class Long.class char.class Character.class double.class Double.class float.class Float.class int.class Integer.class boolean.class Boolean.class URI.class File.class GuardedByteArray.class GuardedString.class Script.class ``` ``` typeof(string), typeof(long), typeof(long?), typeof(char), typeof(char?), typeof(double), typeof(double?), typeof(float), typeof(float?), typeof(int), typeof(int?), typeof(bool), typeof(bool?), typeof(Uri), typeof(FileName), typeof(GuardedByteArray), typeof(GuardedString), typeof(Script) ``` The framework introspects the implemented configuration class and adds all properties that have a `set/get` method to the `ConfigurationProperties` object. The `ConfigurationClass` annotation (Java) or attribute (.NET) provides additional information to the OpenICF framework about the configuration class. The following information is provided: | Element | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | privateProperty | If this is set, the property is hidden from the application, and the application cannot set the property through the `APIConfiguration`. | | skipUnsupported | If the type of an added property is not supported, the framework throws an exception. To avoid the exception, set the value of `skipUnsupported` to `true`. | * Java * C# ConfigurationClass Annotation (Java) ```java @ConfigurationClass(ignore = { "privateProperty", "internalProperty" }, skipUnsupported = true) ``` ConfigurationClass Attribute (C#) ```csharp [ConfigurationClass(Ignore = { "privateProperty", "internalProperty" }, SkipUnsupported = true)] ```