Implementing the Configuration Interface

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The ICF 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, that enables the connector to 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, see "The Connector Messages Object".
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) enables you to add custom meta information to properties. The ICF 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	Enables you to change the default help message key	`propertyName.help`	`help_propertyName`
displayMessageKey	Enables you to change the default display message key	propertyName.display	display_propertyName
groupMessageKey	Enables you to 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#.

Stateless Configuration Implementation (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;
    }
}

Stateful Configuration Implementation (Java)

public class SampleConfiguration extends AbstractConfiguration
    implements StatefulConfiguration {

    /**
     * {@inheritDoc}
     */
    public void release() {
    }

    /**
     * {@inheritDoc}
     */
    public void validate() {
    }
}

Stateless Configuration Implementation (C#)

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();
        }
    }

Stateful Configuration Implementation (C#)

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

@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

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 ICF framework supports a limited number of configuration property types. This limitation is necessary, because ICF 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 ICF 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`.

ConfigurationClass Annotation in Java

@ConfigurationClass(ignore = { "privateProperty", "internalProperty" }, skipUnsupported = true)

ConfigurationClass Attribute in C#

[ConfigurationClass(Ignore = { "privateProperty", "internalProperty" }, SkipUnsupported = true)]