Capabilities

A connector informs how it wants data from the sync engine by defining capabilities. These are read when the connector is initially created.

You implement the capabilities in IMAExtensible2GetCapabilities or IMAExtensible2GetCapabilitiesEx. The latter is a later version and added to support more options without breaking backward compatibility with older ECMA2 implementations. It receives configuration parameters so it can take input from the administrator.

These interfaces are called when the connector is initially created. It should be assumed that the capabilities cannot be changed after the connector has been created, even though some actually would work. The capabilities page is not visible during reconfiguration of a connector, only during connector creation. But the method might still be called during connector reconfiguration so don't write your code assuming it is only called on creation.

These are the properties that can be returned from the methods:

These properties can be grouped into categories.

• Basic properties that are core to how the connector should behave
• Import/export properties that defines details for how import and export should behave.

Basic properties

ConcurrentOperation

This Boolean instructs the sync engine if any other ECMA2 can run at the same time as this connector. It is intended to be used when you have a dependency on a library that could only be invoked once. An example of this is the Lotus Domino connector. The Lotus Notes DLLs the connector is using can only be loaded once in memory and the sync engine can make sure only one Domino connector is running with this setting.

In ideal situations, this flag would only stop multiple instances of this ECMA2 connector, but it blocks all other ECMA2 connectors from starting.

The most common setting is going to be:

myCapabilities.ConcurrentOperation = True

DistinguishedNameStyle

The DN style can be set to the following possible values:

• None
• Generic
• Ldap

Read anchors and DNs for more information on the background of the concepts discussed in this section.

The value None indicates that there is only an immutable ID, the anchor, and that all other objects reference each other using this single value.

The value Generic indicates that the anchor and DN are different values. The DN is not hierarchical, but must follow the one-level DN standard CN=value. The connector might remove the CN= on export and add it on import if that is required. But in the sync engine, it should look like an LDAP style DN. The generic style implies only one partition (named "default") and no hierarchy.

The value LDAP indicates that the connector is having DN and anchor as different values. It also implies that the DN is hierarchical, allowing the connector to support partitions and hierarchies. Even though the name is LDAP, it does not have to follow any LDAP naming style, other than the generic component name = Value, component name = Value. The component name can be anything. It could be the well-known "CN, OU, DC" or something you make up. For example, the Generic SQL connector is using the LDAP style with the component name "OBJECT=". This allows it to use partitions (each object type is a partition).

As an example, this is how you might define this setting:

myCapabilities.DistinguishedNameStyle = MADistinguishedNameStyle.Ldap

IsDNAsAnchor

This Boolean is used together with DistinguishedNameStyle when the latter is set to LDAP. When the DN style is set to LDAP, it is assumed that the connected directory can return both an anchor value and a DN during delta import. Some LDAP directories cannot. For example, Open LDAP has a GUID, which normally is a good candidate for an anchor, on each object but when you read the delta change log, the anchor attribute is not present.

By setting this property, it informs the sync engine that it should not assume an anchor attribute. The DN attribute is the only identifier.

The downside with no anchor attribute present is that an object rename cannot be supported. When an object is moved from one OU to another, then it looks like a delete of one object and an add of a new object to the sync engine.

Unless you need this functionality, then there is no need to specify this property. It is assumed that if not defined, you have a "proper" LDAP behavior with anchors and DNs.

Normalizations

This property can have the following values:

• None
• RemoveAccents
• Uppercase

If the connected directory cannot preserve upper/lowercase or accented characters, then this property can be set. For example, it used to be that mainframes always provided data in upper case. When you exported data with lowercase, it came back in the confirming import as upper case causing an export-not-imported warning.

A workaround would have been to use an uppercase function on every export attribute flow. Setting this property allows the sync engine to do the conversion for you. A connector cannot change data provided in an attribute flow, but the controller can.

The RemoveAccents option is probably even less useful. It removes accented characters and replaces these with unaccented characters on every attribute. It is quite common that you would want it for a single attribute, such as the email address, but not for every attribute.

I have not seen any connected directory in the past decade that does not support Unicode and where you have to set this property. All connectors I've seen have always used:

myCapabilities.Normalizations = MANormalizations.None

This property is in ECMA2 to provide backward compatibility with ECMA1.

Import/export properties

DeleteAddAsReplace

This is a setting telling the controller if you want a delete/add-operation sent as a single replace operation instead. You can set this setting to true when the connected directory does not store any history and it allows you to update the anchor attribute.

The default behavior should be to receive it as two operations - one delete followed by an add.

myCapabilities.DeleteAddAsReplace = false

DeltaImport

This Boolean indicates that your connector supports delta import and that it should be possible to add delta import run profiles to the connector. If import is supported, then it is required to support full import so there is no setting for that option.

myCapabilities.DeltaImport = true

ExportPasswordInFirstPass

This Boolean indicates if you want the password in the first pass or second pass. Most systems can and want the password to be set in the same operation as the create operation. But if you have a system where you first must create the object and then update the password in a second operation, then you can set this to false. The connector then gets one call with the add, without the password, and then an update with only the password.

The default behavior is:

myCapabilities.ExportPasswordInFirstPass = true

ExportType

This property can have the following values:

• ObjectReplace
• AttributeReplace
• AttributeUpdate
• MultivaluedReferenceAttributeUpdate

It is one of the more important properties to get right. This setting tells the controller how you want an update to an object presented to the connector.

ObjectReplace gives you every attribute on the object regardless if it has changed or not. You would use this option when you drop the entire object and recreate it every time. It is also used when the connected directory wants to calculate the difference. For example, when you interact with a stored procedure in SQL, you probably need to send in all attributes for the object or it is treated as the attribute should be removed.

AttributeReplace gives you only attributes that have changed. The important difference compared to the next option is that for a multi-valued attribute, all values are present even when only one has changed. That is, even if a single member has changed in the member attribute, you receive all members every time.

AttributeUpdate only gives you updated attributes. For multi-valued attributes, you get deletes and adds for each value that has changed. If your directory can support it, this is usually the most effective option to use.

MultivaluedReferenceAttributeUpdate is a hybrid of the two previous options and was introduced to support the behavior in Azure AD. It only provides changed attributes. For non-reference attributes it provides AttributeReplace and for reference attributes it provides AttributeUpdate. Except for Azure AD I have not seen any directory with this behavior so it is unlikely you will use this option.

myCapabilities.ExportType = MAExportType.AttributeReplace

FullExport

This Boolean indicates that your connected directory wants a full export, that is, it wants all objects every time and not only changed objects. When this option is enabled the Full Export step type appears in the run profiles.

Most connectors should keep this to its default value to false. When you enable this option, the connected directory is usually expecting a full flat text file and you only use Full Export and not the default (delta) export.

One scenario where this is useful is when you need to deliver data to a human for review. As an example, I once had a customer who wanted daily lists of all employees with their phone numbers so it could be delivered to the person handling the billing for all phones. This option works great with the PowerShell connector from Microsoft for these scenarios.

Full Export should only be used when the remote system cannot handle the default delta export. It should not be used for data reconsolidation when export and import is supported by the connected directory. That is, you should not use this option as a replacement for the normal import-sync-export process.

The default value should be:

myCapabilities.FullExport = false

NoReferenceValuesInFirstExport

This Boolean indicates that you do not want any optimistically references in the first pass and references should only be sent as updates, never as part of an add operation.

In most cases you want the references to be part of the add operation, which is also the default. But in some cases that would complicate the scenarios in the remote system. The FIM Service connector has this option set to true so administrators only have to deal with reference attributes in updates and not in both adds and updates. It simplifies the MPR configuration in FIM/MIM Service.

Usually you want to keep this to its default value:

myCapabilities.NoReferenceValuesInFirstExport = false

ObjectConfirmation

This property can have the following values:

• Normal
• NoDeleteConfirmation
• NoAddAndDeleteConfirmation

Usually, the sync engine expects that after an export, it can read the object again in a confirming delta import. That is the normal behavior for the sync engine. But that is not always the case for all connected directories. Setting this option correctly makes sure no exported-change-not-reimported warning occurs in the confirming import.

NoDeleteConfirmation indicates that a deleted object does not appear in a confirming import. An example would be a row in a SQL table using a column to track delta changes. When a row has been deleted in an export, there is nothing a confirming import can read in the SQL table.

NoAddAndDeleteConfirmation is more uncommon and indicates that the connected directory can not present added or deleted objects in the delta import stream, but it can provide updated objects. An example of this is the SharePoint UserProfile store connector. Only updated objects can be read in the delta import stream from SharePoint.

The default option would be:

myCapabilities.ObjectConfirmation = MAObjectConfirmation.Normal

ObjectRename

This Boolean indicates if your connector supports the DN being changed (when not using MADistinguishedNameStyle.None) in an update.

Most directories allow the DN to be changed, but in some cases, it needs to be treated as an immutable attribute. When this is needed, this property can be set to false.

Most connectors would use:

myCapabilities.ObjectRename = true