9.3. Configuring Connectors

Connectors are configured through the OpenICF provisioner service. Each connector configuration is stored in a file in the openidm/conf/ folder or under the same URL respectively. Configuration files are named openidm/conf/provisioner.openicf-name where name corresponds to the name of the connector. Do not include dash characters ( - ) in the connector name. A number of sample connectors are available in the openidm/samples/provisioners directory. To use these connectors, edit the configuration files as required, and copy them to the openidm/conf directory.

The following example shows an OpenICF provisioner service configuration for an XML file resource. 

{
 "name"                    : "xml",
 "connectorRef"            : connector-ref-object,
 "poolConfigOption"        : pool-config-option-object,
 "operationTimeout"        : operation-timeout-object,
 "configurationProperties" : configuration-properties-object,
 "objectTypes"             : object-types-object,
 "operationOptions"        : operation-options-object
}

Connector Reference

The following example shows a connector reference object.

{
  "bundleName"       : "org.forgerock.openicf.connectors.file.xml",
  "bundleVersion"    : "",
  "connectorName"    : "com.forgerock.openicf.xml.XMLConnector",
  "connectorHostRef" : "host"
}
bundleName

string, required

The ConnectorBundle-Name of the OpenICF connector.

bundleVersion

string, required

The ConnectorBundle-Version of the OpenICF connector.

connectorName

string, required

The Connector implementation class name.

connectorHostRef

string, optional

The name of the RemoteConnectorServer object.

  • If the connector server is local and the connector .jar is installed in openidm/bundle/ (currently not recommended), then the value must be "osgi:service/org.forgerock.openicf.framework.api.osgi.ConnectorManager".

  • If the connector server is local and the connector .jar is installed in openidm/connectors/, then the value must be "#LOCAL". This is currently the default location.

Pool Configuration Option

The following example shows a pool configuration option object for the connection pool between OpenIDM and the OpenICF connector server. 

{
  "maxObjects"                 : 10,
  "maxIdle"                    : 10,
  "maxWait"                    : 150000,
  "minEvictableIdleTimeMillis" : 120000,
  "minIdle"                    : 1
}
maxObjects

Maximum number of idle and active objects.

maxIdle

Maximum number of idle objects

maxWait

The maximum time in milliseconds which the pool waits for an object before timing out. Zero means never time out.

minEvictableIdleTimeMillis

Maximum time in milliseconds an object can be idle before it is removed. Zero means never time out.

minIdle

The minimum number of idle objects.

Operation Timeout

This configuration sets the timeout per operation type.

{
  "CREATE"              : -1,
  "TEST"                : -1,
  "AUTHENTICATE"        : -1,
  "SEARCH"              : -1,
  "VALIDATE"            : -1,
  "GET"                 : -1,
  "UPDATE"              : -1,
  "DELETE"              : -1,
  "SCRIPT_ON_CONNECTOR" : -1,
  "SCRIPT_ON_RESOURCE"  : -1,
  "SYNC"                : -1,
  "SCHEMA"              : -1
}
operation-name

Timeout in milliseconds

A value of -1 disables the timeout.

Configuration Properties

This object contains the configuration for the connection between the connection server and the resource, and is therefore resource specific.

The following example shows a configuration properties object for the default XML sample resource connector. 

{
  "xsdIcfFilePath": "samples/sample1/data/resource-schema-1.xsd",
  "xsdFilePath": "samples/sample1/data/resource-schema-extension.xsd",
  "xmlFilePath": "samples/sample1/data/xmlConnectorData.xml"
 }
property

Individual properties depend on the type of connector.

Object Types

This configuration object specifies the supported object types. The property name defines the objectType used in the URI: system/$systemName/$objectType

The configuration is based on JSON Schema with extensions described below.

Attribute names which start and/or end with __ are resource type specific attributes used by OpenICF for particular purposes, such as __NAME__ as the naming attribute for objects on a resource. 

{
  "account" :
  {
    "$schema" : "http://json-schema.org/draft-03/schema",
    "id" : "__ACCOUNT__",
    "type" : "object",
    "nativeType" : "__ACCOUNT__",
    "properties" :
    {
      "name" :
      {
        "type" : "string",
        "nativeName" : "__NAME__",
        "nativeType" : "JAVA_TYPE_PRIMITIVE_LONG",
        "flags" :
        [
          "NOT_CREATABLE",
          "NOT_UPDATEABLE",
          "NOT_READABLE",
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },
      "groups" :
      {
        "type" : "array",
        "items" :
        {
          "type" : "string",
          "nativeType" : "string"
        },
        "nativeName" : "__GROUPS__",
        "nativeType" : "string",
        "flags" :
        [
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },                
      "givenName" : {
         "type" : "string",
         "nativeName" : "givenName",
         "nativeType" : "string"
         },
    }
  }
}
Object Level Extensions
nativeType

string, optional

The native OpenICF object type.

Property Level Extensions
nativeType

string, optional

The native OpenICF attribute type.

nativeName

string, optional

The native OpenICF attribute name.

flags

string, optional

The native OpenICF attribute flags. The required and multivalued flags are defined by the JSON schema. 

required = "required" : true
multivalued = "type" : "array"
[Note] Note

Avoid using the dash character ( - ) in property names, like last-name, as dashes in names make JavaScript syntax more complex. If you cannot avoid the dash, then write source['last-name'] instead of source.last-name in the java script scripts.

Operation Options

Operation options define how to act on specified operations. You can for example deny operations on specific resources to avoid OpenIDM accidentally updating a read-only resource during a synchronization operation. 

{
  "SYNC" :
  {
    "denied" : true,
    "onDeny" : "DO_NOTHING",
    "objectFeatures" :
    {
      "__ACCOUNT__" :
      {
        "denied" : true,
        "onDeny" : "THROW_EXCEPTION",
        "operationOptionInfo" :
        {
          "$schema" : "http://json-schema.org/draft-03/schema",
          "id" : "FIX_ME",
          "type" : "object",
          "properties" :
          {
            "_OperationOption-float" :
            {
               "type" : "number",
               "nativeType" : "JAVA_TYPE_PRIMITIVE_FLOAT"
            }
          }
        }
      },
      "__GROUP__" :
      {
        "denied" : false,
        "onDeny" : "DO_NOTHING"
      }
    }
  }
}

The list of operations is as follows.

denied

boolean, optional

This property prevents operation execution if the value is true.

onDeny

string, optional

If denied is true, then the service uses this value. Default value: DO_NOTHING.

  • DO_NOTHING: On operation the service does nothing.

  • THROW_EXCEPTION: On operation the service throws a ForbiddenException exception.