ConnId 1.x Connector Development Guide

You will have to choose some meta-data when creating the connector:

The connector class is (almost) simple Java class. For the class to work as a connector it must have:

ConnId annotations and connector interfaces are in org.identityconnectors.framework.spi package.

The connector class should look like this:

Configuration class is mostly simple Java bean. It should extend the org.identityconnectors.framework.spi.AbstractConfiguration abstract class. Every bean property in this class is a connector configuration property. Even a very simple Java bean will work. However there are usually annotations on the getter methods that provide additional meta-data. The usual configuration class looks like this:

The connector class should look like this:

When a new connector instance is needed the ConnId framework creates a new instance of connector class and configuration class. It then invokes the init(…​) method of the connector class.

The init(…​) method should open the connection to the resource and initialize it (e.g. authenticate). Or this may be done in a lazy way and the connection can be initialized on the first invocation of any other method. But opening the connection directly in the init(…​) method is often easier and it seems not to a problem as invocation of "normal" operation will follow immediately after the invocation of init(…​).

The initialized connection should be stored in a private field of the connector class. Other operations should use the connection stored in this private field. Other operations should not open a new connection unless the connection fails (e.g. due to timeout).

The TestOp interface defines test() operation. This is an operation that absolutely every connector should support if it can. This operation is very important for diagnosing connector configuration issues. This operation should try to use the connection and ideally execute some harmless operation (NOOP). The purpose is to make sure that the connector configuration is correct, so that the connector can connect to the resource, that there are no network obstacles (e.g. firewalls), that the connector can authenticate and that the authorizations are roughly OK. If there is existing open connection when the test() operation is invoked such connection should be closed and re-opened from scratch. This is important as a network conditions might have changed since the connection was opened. E.g. the username/password used to authenticate the existing connection may not work any more because someone have changed the password in the meantime.

Good error reporting is very important in this operation. Try hard to make messages in the exceptions meaningful. Any effort invested into this will pay off later when the connector will get deployed.

When connector instance is no longer needed then the ConnId framework invokes the dispose() method. The dispose() method should close all connections and release any other resources that the connector has allocated. Be very careful and make sure that everything is closed. Neglecting this connector disposal will lead to memory or resource leak. This kind of bugs is extremely difficult to diagnose. Therefore it is better to avoid creating such bugs in the first place.

There are two types of connectors: poolable and non-poolable. Non-poolable connectors implement the Connector interface. In this case the ConnId framework will always initialize new connector instance, execute the operations and the destroy the instance. This is fine for prototyping or for very simple cases. But in reality connection setup is usually quite an expensive operation. Therefore it is better to create a connection and then keep it ready to be used for a longer time. This is exactly what poolable connectors are supposed to do.

Poolable connectors implements the PoolableConnector interface. In this case the ConnId framework will create connector instance when needed, execute the operations, but it will not destroy the instance immediately. The framework will put the initialized instance into the pool. When a new request for a new operation comes the ConnId framework will take the initialized connector instance from the pool, execute another operation and then put it back to the pool. This is usually much more efficient behavior.

However, this means that the connector instance may remain in the pool for a long time. The connection that the connector instance maintains may time out or it may be closed by the remote peer in the meantime. Therefore the PoolableConnector interface defines checkAlive() method. The framework will invoke this method every time a connector instance is taken out of the pool. The checkAlive() method should check whether the connection is still alive. This should be a very fast and efficient check - as opposed to the test() method in which the check has to be thorough and can be slow. But the checkAlive() method should be fast because it is called often. If the connection is OK then the checkAlive() method returns normally. If the connection is not OK then the checkAlive() method should throw an exception. In that case the framework will destroy the connector instance and create a new one.

Connector instances are independent of each other. The connectors are designed just to keep the connection to the resource. This is easy to do when the connection is stored in the private field of the connector class. However if there is a need how to share information between connector instances then the options are very limited. Some information can be stored in static fields and this is shared among all the connectors of the specified type and version. This is given by the way how connector classloaders work. E.g. if LdapConnector 1.2.3 stores something in a static field, it will be shared by all the instances of LdapConnector version 1.2.3. But this is really shared by all the instances, even those that connect do different servers (connectors working for different LDAP resources). Therefore if there is a need to share a cached LDAP schema between all the instances that work with the same LDAP server there is currently no easy way how to do it.

The most important part of the schema are the attribute definitions (AttributeInfo) stored inside object class definitions (ObjectClassInfo). These significantly influence the way how midPoint will work with the attribute. Each attribute definition contains definition of:

ConnId framework has several pre-defined attributes that can be used in the schema. Some of these attributes are useful, as they define both attribute name and behavior. MidPoint will automatically recognize these attributes and use them in their proper place (e.g. as activation properties or credentials). It is recommended to use such attributes whenever possible:

There are also other pre-defined attributes in ConnId, namely __SHORT_NAME__, __DESCRIPTION__ and __GROUPS__. These attributes should not be used. They have very vague definition and they usually duplicate other existing attributes in the schema.

The concept of subtypes was introduced in the framework quite recently. Subtype is an optional property of attribute definition (AttributeInfo). It defines a subformat or provides more specific definition what the attribute contains. E.g. it may define that the attribute contains case-insensitive string, URL, LDAP distinguished name and so on.

The subtype may contain one of the pre-defined subtypes (a value form the Subtype enumeration). The subtype may also contain a URI that specifies a custom subtype that the connector recognizes and it is not defined in the pre-defined subtype enumeration. Predefined subtypes are:

The subtypes are translated to Matching Rules in midPoint.

The schema can be designed in many ways. Some of these are smarter than others. This section contains several suggestions how to create a schema that works well with midPoint.

ConnId has a couple of special names for object classes, such as __ACCOUNT__ and __GROUP__. In fact the __ACCOUNT__ object class is the default one that the ObjectClassInfoBuilder creates. This is a legacy approach that we have inherited from the Sun Microsystems past. We generally do not recommend to use these object classes - unless your resource is extremely simple and it does have only one or two object classes. But if the resource has any more object classes than just account and groups then use the object class names in the same format as they are used by the resource. E.g. LDAP connector is using LDAP object class names (inetOrgPerson, groupOfNames, etc.). Good database connector may names of the tables or views (USERS, GROUPS, etc.). Use the terminology that is used by the resource whenever possible.

The ConnId framework is hardcoded to use __UID__ and __NAME__ for all objects. This is something that is very difficult to change. It also means, that identifiers in midPoint appear as icfs:uid and icfs:name. Which is ugly, inconvenient and easy to confuse with native attribute names (e.g. in LDAP there is also uid attribute which is quite different from __UID__). Fortunately, there is relatively simple way how to fix that. Just add the definitions of __UID__ and __NAME__ explicitly to the schema and set their nativeName.

E.g. in LDAP the __UID__ maps to entryUUID and __NAME__ maps to dn. The following code wil make sure that midPoint will use entryUUID and dn instead of icfs:uid and icfs:name:

The ConnId framework schema was designed to work only with primitive data types. Although there is some support for Map as an attribute data type, this is not a systematic solution. There is no way how to describe what the map contains, what are the keys, what type are the keys, what type are the values and so on. As complete knowledge about a schema is very important for a proper operation of midPoint this Map data type is not supported by midPoint. To work around this limitation simply convert the complex attributes to simple attributes with composite attribute names. E.g. a complex attribute telephoneNumber that can have a number for home, work and mobile can be represented as three attributes: telephoneNumber.home, telephoneNumber.work and telephoneNumber.mobile.

Currently there is also no support for timestamp (date/time) data type in ConnId. The timestamps are usually represented as long, which is quite unfortunate. The support for better timestamp data type in ConnId is planned.

ConnId provides a logging facility that the connectors can use. The org.identityconnectors.common.logging.Log should be used as a logger. It can be used like this:

Connector logs are processed in the same way as any other midPoint log. The log levels are configured in system configuration, and the output goes to idm.log by default.

However, the connector log levels defined in org.identityconnectors.common.logging.Log.Level do not make much sense for a connector. MidPoint maps the log levels in a more sensible way. Therefore, we recommend following usage of the log levels:

Connector code has its own special logging facility to record log messages. However, the connectors often have dependencies, such as client or utility libraries. The dependencies may, in theory, be built to use any logging system. It is usually not feasible (and not even desirable) to rewrite the library to use ConnId logging facility. This is further complicated by the fact, that there are several established logging mechanisms in Java community. SLF4J and java.util.logging (JUL) are perhaps the two most widely known logging mechanisms.

MidPoint tries to set up ConnId framework in such a way, that logging in the connector is aligned with midPoint internal logging mechanism. MidPoint logging is based in SLF4J logging interface, implemented by logback on the back end. Native ConnId logging facility is bridged to SLF4J. Therefore, connectors that use ConnId logging and their dependencies that use SLF4J should work without problems. However, dependencies that use other logging mechanisms are usually problematic. Particularly libraries that rely on java.util.logging (JUL) and its variants, such as Tomcat "JULI". MidPoints sets up JUL-to-SLF4J logging bridge as part of its initialization. However, the JUL logging is ofter classloader-dependent. As connectors are using their own classloaders, JUL logging setup may not be properly applied to the connector and its dependencies.

In case of problems, it is often needed to explicitly set up logging bridge in the connector itself. In case of JUL and JULI, the simplest way to do this is to place logging.properties file in your connector package:

The logging.properties file needs to be placed in a root directory of the connector package (not in lib or any other directory) for the classloader to be able to locate it. This configuration will route all the JUL/JULI logging records to SLF4J interface. Strictly speaking, this is not entirely correct method. The correct method would be to bridge JUL/JULI logging to ConnId logging facade, which in turn will be bridged to SLF4J by midPoint. However, this would result in double bridging, and the JUL-to-ConnId bridge is not readily available anyway. The direct bridging method may not be entirely portable, but it works acceptably well for midPoint.

Ultimately, it is your responsibility as a connector developer to make sure log messages from your entire connector code properly routed to ConnId logging facility or SLF4J. That includes log messages from your dependencies. MidPoint tries to make it easier for you, but the ultimate responsibility is yours.

ConnId framework itself logs all connector operations. This can be easily enabled by using the following log configuration:

Or more specifically (with less logging noise - applicable only in midPoint 3.9 and later):

The ConnId operation traces look like this:

This is a very useful mechanism. It will log every operation of every connector. If you suspect that the connector is not executing the right operation this is the right place to check it. You can see what is the operation that the midPoint is passing to the connector.

See Troubleshooting Connectors page for more details about framework logging and log interpretation.

We recommend to use semantic versioning for the connector. In short we recommend to use connector version in the form of 1.2.3:

GuardedString data type is used by ConnId whenever there is a sensitive value that needs to be protected. This usually applies to passwords. The GuardedString is quite a strange animal. It will store the sensitive values in an encrypted form. However the key is stored in the same memory, therefore the encryption does not really make sense. The original purpose of the GuardedString seems to be to avoid accidental dump of the cleartext passwords into system logs - which is a very valid purpose. However, the GuardedString has gone a bit too far and it is one of the major nuisances while working with ConnId.

The value stored in the GuardedString can be accessed by using the access(…​) method that needs an instance of Accessor inner class. Use of anonymous class is probably the best way how to use it:

However it is difficult to get the clear value back from the anonymous class. The idea was probably to use the clear value only in the access(…​) method to avoid exposure. But the protocol libraries usually need the password in the cleartext and they do not have a trivial initialization. Therefore the Polygon project provides com.evolveum.polygon.common.GuardedStringAccessor class to make this easier.

Proper error handling is a very important aspect of the connector. Firstly a lot of issues with midPoint deployment is caused not by midPoint itself, but by network communication issues, protocol incompatibility, wrong permissions on the resource side and so on. If the connector correctly and clearly reports these issues then the problem diagnostics gets much easier.

But there is also another very important factor. MidPoint has a self-healing consistency mechanism. MidPoint can react a variety of situation and automatically "heal" it. E.g. if midpoint tries to modify an account that was accidentally deleted, midPoint can re-create the account and then re-try the modify operation. It can similarly react when it tries to create an account that is already there, when it does not find an account that was supposed to be there and so on. But for this to work the connector needs to properly indicate the nature of every problem. The connector must distinguish between a communication error, "object already exist" situation and a schema violation. This is not always a trivial task and it requires a lot of focused work and patience.

The key to proper error handling are the exceptions. The most important thing is to know which exception to throw in which situation. There is a set of pre-defined exceptions in org.identityconnectors.framework.common.exceptions package. And this is exactly the place where the original design done by Sun Microsystems makes it a bit difficult. The Sun engineers defined all the exceptions as runtime exceptions. Therefore it is not clear when to throw which exception and what it means. Therefore the following table provides a summary:

Those exception that are emphasized by bold font are those that are important for correct operation of midPoint consistency mechanism. If you are going to cut corners and only handle some situations that handle those. If it is still too much then handle only AlreadyExistsException and UnknownUidException. These are absolutely essential.

It is also very important to put good message in the exceptions thrown from the connector. There are somehow complex interactions with connector classloaders and exceptions, which may cause that the inner (wrapped) exceptions may not be accessible. Therefore make sure that the top-level exception throw from your code has a good message that clearly indicates what is the problem. That message may be the only thing that the administrator or user see and they will have to figure out what’s going on just from that message.

It is also good idea to throw certain provisoning exceptions as "soft" errors. Soft error will not block (unlike fatal error) processing of whole focus. Errors that are not harmful to the system and origin from data inconsistency (e.g. new department number is refused by the target system during user update) can throw InvalidAttributeValueException. This particular exception is recognized as "schema" problem by midPoint. In resource definition, you may label such problems as not critical (soft error):

The normal behavior of the executeQuery(…​) operation is to return all the objects that satisfy the query. If there is no such object than the executeQuery(…​) should not return any object (i.e. do not invoke the handler). But the executeQuery(…​) operation should not indicate any error in this case. It should not throw any exception. MidPoint will see empty result set and it will figure out that there is no such object.

However, there are (quite rare) cases when the search should throw UnknownUidException. One such case is when the container (base context) option is present in the operation arguments and the container object is not found. Then the search query cannot be executed and in fact we do not know whether the search objects exist or not. This condition is indicated by throwing UnknownUidException and this case should be interpreted differently than not returning any results at all.

All read and search operations are implemented in the connector by the executeQuery(…​) operation. The crucial argument to this operation is the filter (query). The ConnId framework has its own "language" for filters. These are trees of Java objects that are located in the org.identityconnectors.framework.common.objects.filter. However, resources typically have their own query language, such as SQL or LDAP filters. Therefore there is FilterTranslator interface that can be used to translate the ConnId filter to the resource-native query. There is also an AbstractFilterTranslator abstract class that can be used as base class for filter translators. This abstract class is prepared mostly for SQL-like query translation. The createFilterTranslator(…​) method is a factory method for the filter translator.

Resources sometimes have two different operations: one for read/get and one for search/list. However ConnId has just one executeQuery(…​) operation. If this is the case then the only option is to programmatically analyze the ConnId query filter. If it is a simple equals query for one of the identifiers then use read/get. Use search/list in other cases.

Sometimes there is a need to indicate some conditions that affect the entire search operation, e.g. whether all results were returned, paging cookie, etc. (see Advanced Features below). However the executeQuery(…​) operation has no return value. This is a historic issue. The Sun Microsystems engineer haven’t thought of that. As the ConnId SPI has to be backward compatible, we cannot add a return value there. The old connectors will break. Therefore there is a slightly inconvenient but compatible way how to indicate the search result.

Normally the object is returned from the search by invoking the handle(…​) method of ResultsHandler interface. The ConnId client (midPoint) that is capable of receiving an extended search result will pass an object that implements the SearchResultsHandler interface instead. This interface has additional method handleResult(…​) to indicate the result of the whole search operation. This method should be invoked at the end of the search:

There are two relared, but slightly distinct password operations:

We usually maintain each connector bundle as a separate project on github. This is quite easy, as connectors are simple single-module projects. We strongly recommend to publish the connectors under an open source license. Out choice is Apache License 2.0, but any OSI-approved license would do.

There is no special rename operation in the connector. Rename is just a simple update(…​) operation. However, the resources often handle renames in a special way. If that is the case then you have to detect that situation in the update() operation implementation and behave in a special way.

It is usually a change of the __NAME__ attribute that is considered to be a rename. But theoretically any attribute change may trigger rename.

The rename operation may in fact change __UID__. The __UID__ should be immutable in an ideal situation. But the situation is not always ideal. Therefore if __UID__ is changed during a rename then simply return new __UID__ value from the update(…​) operation.

There are resources that do not have __UID__ or any similar identifier. They just have a single mutable identifier (__NAME__). But ConnId framework insist that there has to be an __UID__. It is hardcoded into the framework. The __NAME__ also cannot be skipped as it is a mandatory attribute for create(…​) operations.

The solution is to formally present both __UID__ and __NAME__ attributes. But return the same value for them. This can be a bit confusing, but it works. MidPoint is designed to handle that situation. Ideally you should also put both the __UID__ and __NAME__ attribute definitions to the schema and use the same nativeName for them. That is an additional indication that these two attributes are the same and midPoint will handle them as a single attribute.

Some systems use names without enforcing their uniqueness, as from their perspective a single unique ID (used for __UID__) is enough. This situation is not a problem from ConnId perspective, as it does not mandate the __NAME__ to be unique. But for midPoint, the name is a secondary identifier - unless we instruct it otherwise. So this Gotcha is more about midPoint and resources than ConnId and connectors, but let’s talk about it.

Sometimes you can find another good unique name-like attribute on the system and use that one. Other times, even if there is a unique attribute, it may be unusable as a "name". For instance, opaque UUID or some Base64 encoded string is not a useful name that you’d like to see in midPoint when listing the resource objects. In that case, go with the non-unique name and let midPoint know that it should not use it as a secondary identifier.

This requires some resource configuration. At first, it may seem like the solution is to rewrite ra:secondaryIdentifier in the schema definition. But schema definition may be overwritten anytime when the schema is refreshed - so don’t bother changing it. Instead, go to the schemaHandling and inside the relevant objectType (the one with non-unique name) define the attribute for icfs:name like this:

The ConnId framework has several "handlers" that can be used to pre-process or post-process the data inside the framework: between midPoint and the connectors. The handlers are:

The handlers can be explicitly switched off in midPoint in resource configuration:

This is usually necessary in midPoint 4.5 and earlier. In midPoint 4.6 and later the handlers are turned off by default.

See also What are ConnId result handlers? FAQ and the ICF Issues page for more details about result handlers.

Some connectors need proprietary libraries to operate. These are often SDK libraries that come with the applications. These libraries cannot be distributed together with the connector because the library license does not allow it. In that case simply distribute the connector without the proprietary library and include instructions where the library needs to be placed for the connector to work.

The primary mechanism SPI for all the advanced features is the use of OperationOptions. OperationOptions is the last parameter to almost all connector operations. Simply speaking the OperationOptions is just a set of optional parameters for the operation.

The connector should indicate the support for operation options in the schema. E.g. the following code will indicate support for PAGE_SIZE option in the executeQuery(…​) operation (defined in the SearchOp SPI operation interface).

The ATTRS_TO_GET option specifies the attributes that the connector should return from the search operations. The reason is that some of the attributes may be expensive to retrieve (e.g. photo). Or maybe the resource is hardwired not to return all the attributes unless they are explicitly enumerated (e.g. LDAP operational attributes). If ATTRS_TO_GET option is not present, then the connector should return only those attributes that the resource returns by default. This is usually a set of attributes that can be retrieved efficiently. If ATTRS_TO_GET option is present then connector should return all the attributes specified in that set.

There is an companion option RETURN_DEFAULT_ATTRIBUTES. If this option is set, then the connector should return all the default attribute in addition to the attributes defined by ATTRS_TO_GET option. I.e. in this case the ATTRS_TO_GET option defines only the attributes that are "on top of" the default attributes. This is necessary to properly support searches over polymorphic data, e.g. data that use hierarchical object classes or data that are mixing several object classes in one search (e.g. LDAP directories).

The list of attributes that are returned by default is indicated in the schema:

Please take care to mark the attributes that are not returned by default properly in the schema. MidPoint depends on that. E.g. if midPoint gets an object that does not have an attribute which is supposed to be present by default then midPoint will assume that the attribute does not have any value. However that assumption may be wrong if the attribute in fact has an value but it was simply not returned from the search. If the attribute is properly marked in the schema then midPoint will not make such an assumption and it will explicitly request the value when needed.

Some resources returns only a limited number of results when searching for objects. E.g. LDAP servers typically have a size limit for searches. So if the search would return more than 3000 objects such search is stopped when that limit is reached. The alternative is to use paging (see below). But paging is usually quite a costly operation. And in fact vast majority of searches are below that limit and they are even OK with incomplete results. Therefore there is an ALLOW_PARTIAL_RESULTS option that can indicate, that it is OK to return partial results. I.e. this option indicates that we prefer efficient and fast search and we are willing to sacrifice completeness.

If the search results are incomplete the connector should indicate that by setting the appropriate flag in the SearchResult class and pass that as a result using the SearchResultsHandler interface (see above).

Paging and sorting options are very important to make the connector usable and scalable. The paging options limit the query to return the results page-by-page. This is very important for GUI. There is no point for GUI to display thousands of objects at once. Also the GUI cannot store all the results in memory. Therefore it needs to get the results page-by-page. For most resource such search would be very inefficient or they will not even allow to list all the objects without paging. There are two supported methods for paging:

The offset/pageSize method is used by the GUI as the user may randomly skip from page to page, list the pages backwards and so on. The cookie/pageSize method is not used often and midPoint support for this feature is not yet completed. Therefore we recommend to support the offset/pageSize method.

Please note that if there are no paging options at all then it is expected that the connector returns all the objects. This is important, because this is what the reconciliation and import do. They simply list all the objects and they rely on the fact that all of the objects will be in the search results. Therefore if the resource has search limits for non-paged searches (such as LDAP servers) then the connector must internally execute paged search even if no paging was explicitly requested.

For offset-based paging to work properly the results must be sorted. If they are not sorted then the results may be returned in arbitrary order and therefore the offset numbers may not match between search queries. For the user it will look like the search results moving randomly between GUI pages. Therefore it is recommended to always use (server-side) sorting when doing offset-based paging. There is an SORT_KEYS option that midPoint can use to indicate sorting by a specific attribute, e.g. if users wants to sort the results by a specific column in the GUI. However even if no SORT_KEYS option is specified then the connector should use some default sorting mechanism to ensure continuity of the offsets.

Connectors have an option to discover additional configuration properties from the connected system at runtime. The discovery usually works like this:

Configuration discovery is mediated by DiscoverConfigurationOp interface. Connectors implementing this interface have to implement two methods:

Please see documentation (javadoc) of the DiscoverConfigurationOp interface for further details.

While DiscoverConfigurationOp is an optional operation, it brings significant ease-of-use for system administration. It is more than recommended to consider implementation of this interface in your connector.

Sometimes the resource returns only a subset of values in the object. E.g. an object that represents a big group only returns a partial list of members, because the fill list of members is too long. It is important for midPoint to know about this situation, so midPoint will not interpret that value as a full value. E.g. if Active Directory return only first 1000 members of the group, midPoint could interpret that as the members beyond 1000 were removed from the group. And this is obviously wrong.

Therefore there is an ALLOW_PARTIAL_ATTRIBUTE_VALUES option that allows connector to return partial attribute values. Similarly to the ALLOW_PARTIAL_RESULTS option it indicates that we prefer efficiency over completeness. If the ALLOW_PARTIAL_ATTRIBUTE_VALUES option is set then the connector can use efficient operation and only return partial attribute values. If the option is not set then the connector must use even inefficient operation but it has to make sure that all the attribute values are returned.

If case that some attribute value is not complete then the connector should use the attributeValueCompleteness property of the Attribute class that the connector can use to indicate that the value is not complete. If the connector knows that the Attribute contains only a partial list of values then it should set this property to INCOMPLETE.

This functionality allows to have an efficient GUI. E.g. if midPoint GUI just lists the groups, it will set the ALLOW_PARTIAL_ATTRIBUTE_VALUES flag. There is no need to fetch complete attribute values if all we want is just render a single line in group list in the GUI. And we want that operation to be very fast. Getting all members of large groups will certainly slow that down. But when user clicks on the group details then we do not set ALLOW_PARTIAL_ATTRIBUTE_VALUES flag. Therefore a complete list of group members is displayed.

Every ConnId object belongs to exactly one (structural) object class. This object class defines the basic structure of the object: whether it is account, group or organizational unit. But some resources also have additional object classes that can extend the objects with additional attributes. We refer to these additional object classes as auxiliary object classes. ConnId object must have exactly one structural (primary) object class, but it may have any number of auxiliary object classes. The normal behaviour is that the objects have zero auxiliary object classes and vast majority of connectors do not need to deal with them at all. But there are some connectors where auxiliary object classes are really useful, e.g. LDAP and Active Directory connectors.

There is a pre-defined attribute __AUXILIARY_OBJECT_CLASS__ in the PredefinedAttributeInfos class. This attribute can be used to indicate auxiliary object classes in create and update operations. The same attribute is used when reading the auxiliary object classes. Auxiliary object classes should be specified in the schema and marked as auxiliary. But that’s all that is needed to use auxiliary object classes in midPoint.

Some resources do not have a flat representation of the data with object classes completely separated. E.g. there are directory servers that have hierarchical representation of data and individual object classes may be mixed together in the same part of the tree. To support these resources there are advanced search options:

Identity discovery is midPoint’s feature to automatically detect and link existing account in certain situations. Good example is situation when account already exists in the resource but midPoint is unaware of it. MidPoint does not have shadow and if user is assigned with the resource, reconciliation tries to create account with very same name/identifier. When discovery is configured properly, provisioning ends with handled error, account being linked to focus and shadow created in midPoint. If discovery is not configured properly, provisioning usually ends with fatal error (account name duplicity). Support for discovery increases robustness of the connector and comes very handy in various maintenance and data migration tasks.

To support discovery in your custom connector and ResourceType, make sure:

To test discovery feature, pick focus (user) with existing account and resource assigned. Then go to Repository Objects and delete account shadow for the user, remember its OID, go to user xml and delete linkref to this OID. Then go to user profile, you should not see any account projection. Turn reconcile checkbox ON and click Save, you should see handled error on the resource and projection being linked. If something goes wrong try debugging your connector, create operation should raise AlreadyExistsException, and is followed by executeQuery method call (with query set on username).

Connectors have their configuration and in the common case that is all that the connector needs to do its job. But sometimes it is useful for a connector to know more about the environment in which it operates. For example it is useful for a connector to know human-readable name of the system that it connects to. This can be used in the logfiles and other diagnostic output. However, ConnId framework haven’t had any mechanism for that. Such mechanism was added in ConnId framework 1.5.0.0. Now the connector can simply implement InstanceNameAware interface. In that case the framework will invoke setInstanceName(…​) method on the connector to set a human-readable name of the connector instance. In midPoint this is used to set name of the resource to the connector. Then connector can use it in log messages and other diagnostic output.

Vast majority of connectors do not need ConnId framework result handlers. However the handlers are turned on by default. The handlers may affect performance and may interfere with normal operation. The handlers are especially nasty with case-insensitive resources. Simply turn the handlers off (see above).

Those "result handlers" are an artifact of an original Identity Connector Framework over-engineering. The handlers are supposed to assist connectors by implementing "mechanism" that the connector or resource does not support - such as search result filtering, data normalization and so on. However, those handler are generic and they know nothing about the particulars of the resource that the connector connects to. Therefore in vast majority of cases those handlers just get into the way and they distort the data. Good connectors usually do not need those handlers at all. Unfortunately, these handler are enabled by default and there is no way for a connector to tell the framework to turn them off. The handlers needs to be explicitly disabled in the resource configuration.

There are cases when we have a large number of changed objects in our sync(…​) method executions. When there are no issues with the data, the IAM handles the objects and updates its "SyncToken" value based on the last successfully processed object, next execution of the method would start with tokens "younger" than this one.

But there are situations when this does not happen. When an error occurs among the processed objects, midPoint re-tries the sync operation based on the SyncToken value with which it originally executed the operation. So even if there were successfully processed objects in the first execution.

The reason is, to ensure consistency in cases when the SyncToken value could be potentially same for multiple objects. (i.e. timestamp is the same for more objects than one, because they were changed at the "same time").

Yet if we know that our system returns unique token values (consistency is assured), or we will assure consistency via additional ad-hoc checks (Reconciliation) we can persuade midPoint via the "preciseTokenValue" configuration option to rather than re-try the whole bulk, continue from the last successfully processed token.

For an example please see: Resource Capabilities

A specific problem might occur in the case of distributed systems. Quite often create operations might be executed successfully yet a subsequent get of the created object might return empty because of delays in the propagation of changes between the nodes of a distributed system (e.q. a read from nodes where the data was not yet written). In this case, midPoint does not know if the missing object is such a delayed create operation or if the object was deleted right after it was created. If the connector can reliably decide that the case is a delayed create operation, for instance, a remote system indicates this via an exception, the reaction could be wrapping the original exception and throwing a RetryableException. MidPoint handles this exception as a communication exception, not marking the previously created shadow as “dead”. A subsequent reconciliation would fix any consistency issues.

There are also cases when the get operation might be postponed because of some rate limit (e.g. throttling). If the limit is lifted in a reasonable amount of time (a remote system might communicate this as a part of the returned exception) implementing a loop might be a possible solution. In such a case, you should make sure that the connector configuration contains fields for the maximum wait period and the maximum number of attempts of such operation (with reasonable defaults set up).

In general the connector should communicate with the same node of the target system or some sort of session stickiness should be used in case of multiple nodes of an application cluster (load balancing).