FIM 2010 R2 - MA Capabilities

  • Article

Last week, while writing a Management Agent. I was looking out for information on MA Capabilities. What each property meant and which one is the right one for my Management Agent. There is information on https://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.macapabilities_members(v=vs.100).aspx but it’s very brief. Having not found a detailed information on it at one place, I thought I'd put one together.

 

 MACapabilities class represents a management agent capabilities object. Following is a list of members exposed by the type:  

  • ConcurrentOperation: Gets or sets a value indicating whether the sync engine supports concurrent operation of multiple instances of the management agent.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.ConcurrentOperation = true;

 

  • DeleteAddAsReplace: Gets or sets a value indicating whether the management agent supports Delete-Adds. If true, all delete-adds will be exported as object replacements.

An object has an anchor that uniquely identifies that object within a connector space. If an anchor changes, it is assumed that the object is no longer the same object it was before. Thus a delete-add is triggered: deletion of the original object with the old anchor and an addition of a new object with the new anchor. However during export, you don’t always need to process this as delete and an add. You can either choose to export this type of object change as a delete operation followed by an addition operation (2 operations) OR you can choose to export this as an object replace (single operation).

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.DeleteAddAsReplace = true;

 

  • DeltaImport: Gets or sets a value indicating whether the management agent supports Delta Import.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.DeltaImport= false;

 

  • DistinguishedNameStyle: Gets or sets a value indicating whether the distinguished name style is supported by the management agent.

Type: MADistinguishedNameStyle

Values: Generic- Generic distinguished name is supported.

              Ldap- Ldap-Style distinguished name is supported.

                        None- No distinguished name supported.

 

 The following characters are encoded and shouldn't be used in anchor fields when DistinguishedNameStyle is set to None:

  1. '\' is the escape character
  2. ',' has special meaning to the store layer
  3. '+' separates multiple values in the DN
  4. '#' is used to indicate hex encoding of a binary value
  5. ' ' - space, only when located at the end of anchor value
  6. All control characters with code less than 0x20 (SPACE), except allowed:

-          0x0 (null)

-          0x9 (TAB)

-          0xA (LF)

-          0xD (CR)

 When there is need to support these characters, DistinguishedNameStyle = MADistinguishedNameStyle.Generic should be used.

 

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.DistinguishedNameStyle = MADistinguishedNameStyle.None;

 

  • ExportPasswordInFirstPass: Gets or sets a value indicating whether the management agent supports exporting the passwords in the first pass.

If the password attribute export_password has been set during provisioning then the default behavior is that the password will not be provided to this method and that SetPassword is instead called to set the password after the object has been created. If the password should be provided to this method then set the ExportPasswordInFirstPass to true. Note: It is the responsibility of the developer to verify that the connection is secure in this case so the password isn’t exported over a clear text channel.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.ExportPasswordInFirstPass= false;

 

  • ExportType: Gets or sets a value indicating whether the sync engine should create object replacements, objects with attribute replacements or objects with attribute updates during export.

Objects can be provided in three different variants: “Object Replace”, “Attribute Replace”, and “Attribute Update”. With “Object Replace” all attributes for an object is always provided regardless if a particular attribute has changed or not. This is useful for connected directories where the existing object is effectively dropped before a new is created. For “Attribute Replace” only attributes which has changed will be provided. For multi-valued attributes a full representation of all values will be provided. If using “Attribute Update” the difference from Attribute Replace is that multi-valued attributes are provided as a list of values to be added and values to be removed from the list.

 

Type: MAExportType

Values: AttributeReplace- Export entry requires attribute replacements for changed attributes.

                  AttributeUpdate- Export entry requires attribute updates for changed attributes.

                    ObjectReplace- Export entry requires object replacements for changed objects.

Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.ExportType = MAExportType.AttributeUpdate;

 

  • FullExport: Gets or sets a value indicating whether the management agent supports Full Export.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.FullExport= true;

 

  • NoReferenceValuesInFirstExport: Gets or sets a value indicating whether the management agent requires that exported objects not contain reference values in the first export attempt.

An object can appear several times in one export run. The engine divides an export into several passes. During an export the engine will sort all objects in the order which will be most efficient for reference attributes. As a rule of thumb all objects with no references will appear first in export and objects with many references, e.g. groups with many members, will appear last. If an object has references to objects which have not yet been exported then reference attributes will be suppressed by the engine and the object will be marked for a retry. The other way to mark an object for retry is by returning RetryRefenceAttributes. When all objects have been exported once, all objects marked for retry will see an update to the object with only reference attributes. In the UI this move from one pass to the next can be seen by the completion moving from 100% back to 0% and the process start over again. The engine will determine how many passes should be tried for an export. If reference attributes should not be provided in the first pass, then set the NoReferenceValuesInFirstExport to false. Reference attributes will only be provided in the second pass when this setting is set.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.NoReferenceValuesInFirstExport = false;

 

  • Normalizations: Gets or sets a value indicating whether the management agent should normalize certain characters prior to reimport.

 If your management agent will perform direct export attribute flow of string attributes, it may be necessary to normalize certain characters prior to reimport. To convert lowercase characters to uppercase characters, select Convert lowercase characters to uppercase (Uppercase). To replace accented characters with non-accented variant characters, select Replace accented characters with non-accented variants (RemoveAccents).

 

Type: MANormalizations

Values: None- Identifiers are not normalized.

       RemoveAccents- Identifiers are normalized remove accent characters.

       Uppercase- Identifiers are normalized to uppercase.

Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.Normalizations = MANormalizations.None;

 

  • ObjectConfirmation: Gets or sets a value indicating what the management agent supports object export confirmation.

It is assumed that an exported change can be confirmed by an import. If a particular attribute cannot be confirmed, make sure it is marked as ExportOnly in the schema. If object delete operations cannot be confirmed in a delta import then set the ObjectConfirmation to NoDeleteConfirmation. If the object is reported as successfully deleted during export then the engine will automatically confirm the delete.

Type: MAObjectConfirmation

Values: NoDeleteConfirmation- Exporting object deletion does not need import confirmation.

                   Normal- Object confirmation is as normal.

Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.ObjectConfirmation= MAObjectConfirmation.NoDeleteConfirmation;

 

  • ObjectRename: Gets or Sets a value indicating whether the management agent supports renames. If you want to allow object rename, set Distinguished Name Style to Generic or Ldap.

Type: Boolean

 Example: MACapabilities myCapabilities = new MACapabilities();
myCapabilities.ObjectRename= false;