A Sync Class defines how a single class or type of entry (e.g. user entries) are synchronized in a Sync Pipe.
A Sync Class allows different types of entries to be synchronized differently. For example, some types of entries might have different attribute mappings, different DN construction, or different types of operations synchronized (e.g. modifies but not creates). A Sync Class can also be used to completely exclude certain types of entries from synchronization by setting the synchronize-creates, synchronize-modifies, and synchronize-deletes properties set to false.
When a change to an entry is first detected in a Sync Source, the Sync Pipe evaluates the inclusion criteria (i.e. include-base-dn and include-filter) to find the first matching Sync Class according to the evaluation-order-index. If a change does not match any Sync Class, then it is discarded. Otherwise, the attribute mapping and whether that type of change is synchronized is determined by the settings in the matching Sync Class.
Note: If operational attributes are specified in any of the include filters, attribute mappings, DN mappings, auto-mapped source attribute lists, or destination correlation attributes lists, they must be modifiable at the Sync Destination; that is, they cannot have the 'NO-USER-MODIFICATION' clause in their syntax. Attributes in these lists will automatically become part of the default '-all-' group for synchronization. This can be avoided by adding these types of attributes to the 'excluded-auto-mapped-source-attributes' list on the Sync Class.
↓Relations from This Component
↓Relations to This Component
↓Properties
↓dsconfig Usage
The following components have a direct composition relation from Sync Classes:
The following components have a direct aggregation relation from Sync Classes:
The following components have a direct composition relation to Sync Classes:
The properties supported by this managed object are as follows:
| Description | A description for this Sync Class |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | When multiple Sync Classes are defined in a Sync Pipe, it is possible for multiple classes to match any given change. This property defines the evaluation order for determining the correct Sync Class to apply to a detected change. Within a Sync Pipe, values of this property must be unique but not necessarily contiguous, and Sync Classes with a smaller value will be evaluated first to determine if they match a detected change. The matching Sync Class with the lowest evaluation-order-index will be used to process the change. If the inclusion criteria (e.g. type of change, base DN, or filter) of the Sync Classes are non-overlapping, i.e. no entry will match more than one Sync Class, then the values for this property are irrelevant. However, if the inclusion criteria are overlapping, then they should be ordered to ensure that less inclusive Sync Classes are evaluated first. For example, if one Sync Class includes all entries under ou=people,dc=example,dc=com and another includes all entries under dc=example,dc=com, then the ou=people,dc=example,dc=com Sync Class should be ordered first. |
| Default Value | 9999 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the base DNs for the branches of the Sync Source that can be in this Sync Class. Along with the include filter property, this property determines whether a source entry is included in this Sync Class. If the Sync Source entry has a native DN (i.e. it's an LDAP source and not a database source), then this Sync Class can apply only to entries in the branch specified by this property. If no DNs are specified, then only the include filter property is used to determine if an entry is in this Sync Class. |
| Default Value | The location of the entry in the Sync Source is not taken into account when determining whether an entry is part of this Sync Class. |
| Allowed Values | A valid DN. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The set of filters that define the source entries that should be included in this Sync Class. The filter is represented as an LDAP filter, but it can be used with any type of Sync Source. Along with the base DN property, this property determines whether a source entry is included in this Sync Class. If the include-base-dn property does not exclude an entry, then it will be included if it matches any of the filters specified here. If no filters are specified, then only the base DN property is used to determine if an entry is in this Sync Class. Sync Class matching is done before attributes are mapped, so the attributes specified in the filter must be source attributes. For example, to only include user entries when synchronizing from an LDAP source, you could specify (objectclass=user) as the filter. applies to an entry. |
| Default Value | All entries are included in this Sync Class. |
| Allowed Values | A valid LDAP search filter |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The attribute map to use for the Sync Class. Multiple attribute maps can be specified as long as no destination attribute is specified in more than one attribute map. This property works in conjunction with the auto-mapped-source-attribute and excluded-auto-mapped-source-attributes properties. See the description of these properties for more information. |
| Default Value | No attribute map is used. |
| Allowed Values | The DN of any Attribute Map. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | If the DN values at the Sync Destination differ from the DN values at the Sync Source, a DN map can be used to construct the destination DN value using components of the source DN and attributes from the source entry. Multiple DN maps can be specified if source DNs might match different DN patterns. The most specific patterns should be specified first. |
| Default Value | No dn map is used. |
| Allowed Values | The DN of any DN Map. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The set of source attribute names that should be automatically mapped to a destination attribute with the same name. An attribute map converts attributes whose names or formats differ at the Sync Source and Sync Destination. To have attributes synchronized without any change to their name or value, simply list the attributes here. If an explicit mapping for a destination attribute exists, then an automatic mapping is not added for that attribute. You can use the special values '-all-' to auto-map every Sync Source attribute, and '-none-' to not auto-map any Sync Source attributes. A value of '-all-' is recommended when synchronizing between endpoints that have the same schema, such as when migrating from a legacy LDAP directory server to Ping Identity Directory Server. This property works in conjunction with the attribute-map and excluded-auto-mapped-source-attributes properties. See the description of these properties for more information. |
| Default Value | None |
| Allowed Values | The name of the source attribute to include in synchronization. |
| Multi-Valued | Yes |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
excluded-auto-mapped-source-attributes
| Description | The set of source attribute names that should not be automatically mapped to a destination attribute with the same name. When the auto-mapped-source-attribute property is set to '-all-', this attribute allows a subset of attributes to be explicitly excluded from synchronization. If a source attribute list is explicitly mapped in an attribute map, then it will still be synchronized even if the attribute appears in this list. This property works in conjunction with the attribute-map and auto-mapped-source-attribute properties. See the description of these properties for more information. |
| Default Value | None |
| Allowed Values | The name of the source attribute to exclude from synchronization |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
excluded-auto-mapped-source-attribute-regex
| Description | A set of regular expressions that match source attribute names that should not be automatically mapped to a destination attribute with the same name. When the auto-mapped-source-attribute property is set to '-all-', this attribute allows a subset of attributes to be excluded from synchronization. If a source attribute list is explicitly mapped in an attribute map, then it will still be synchronized even if the attribute matches this regular expression. This property works in conjunction with the attribute-map and auto-mapped-source-attribute properties. See the description of these properties for more information. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
destination-correlation-attributes
| Description | Each value of this property is a comma separated list of destination attribute names that are used to correlate a source entry to a destination entry. When multiple attribute lists are provided, the server iterates through the attribute lists and uses the first one that matches a single entry. Note that if the destination-correlation-attributes-on-delete property is set, then only those attributes will be used when correlating a deleted entry. Since the attribute names that are specified are destination attribute names, the attributes in the detected change are first mapped from source to destination attribute names using the attribute maps defined in this Sync Class. For LDAP servers, the attribute 'dn' can be used even though technically it is not an attribute of an entry, and as with attributes, the dn values are mapped using the DN maps defined in the Sync Class. To prevent incorrect matches, the most restrictive attribute lists--those that will never match the wrong entry--should be first in the list, followed by less restrictive attribute lists, which will only be used when the earlier lists fail. The server will issue AND searches using the format specific to the destination resource, and it is the administrator's responsibility to ensure that these searches are properly indexed in the destination resource. If a source attribute has more than one value, then the operation will succeed if any of the values match a destination attribute value. As an example, when synchronizing user entries between two identical LDAP servers (i.e. no attribute or DN maps), the values of this property could be 'dn,uid', 'uid,employeeNumber', and 'cn,employeeNumber'. In this case, the server would first look for a corresponding entry that had the same 'dn' and 'uid' values. If that returned no results, it would then search for an entry with the same 'uid' and 'employeeNumber', and if that failed, it would finally check for an entry with the same 'cn' and 'employeeNumber'. If none of these matched, then the synchronization change would be aborted and a message logged. Note: when synchronizing delete operations, take special care when configuring this property list because by default not all attributes in the source entry are available after it is deleted. For Ping Identity LDAP servers, the changelog-deleted-entry-include-attribute property of the Changlog Backend controls which attributes of the deleted entry are stored in corresponding changelog entry. Likewise, for Sun DS servers, the deletedEntryAttrs configuration attribute of the RetroChangelog controls which attributes of the deleted entry are stored in corresponding RetroChangelog entry. Likewise, the UnboundID trigger that generates the changelog in a relational database can also be configured to store values of selected attributes when an entry is deleted. For Ping Identity LDAP destination servers JSON fields within JSON attributes may be specified by appending '.' and then the JSON field to match. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be matched then 'ubidEmailJSON.value' could be specified. |
| Default Value | dn |
| Allowed Values | A comma separated list of attribute names |
| Multi-Valued | Yes |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | This property controls whether or not the creation of a new entry at the Sync Source should be synchronized to the Sync Destination. If set to true, the creation will be synchronized, and otherwise the change will be dropped. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | This property controls whether or not the modification of an entry at the Sync Source should be synchronized to the Sync Destination. If set to true, the modify will be synchronized, and otherwise the change will be dropped. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | This property controls whether or not the deletion of an entry at the Sync Source should be synchronized to the Sync Destination. If set to true, the corresponding entry in the destination will be deleted, and otherwise the change will be dropped. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | This property controls whether a rename of an entry (e.g. moddn in LDAP) should be allowed at the destination in the process of synchronizing a modify operation. If this property is set to false, then destination entries will not be renamed under any circumstance. In the case of an LDAP-based destination, no moddn operations will be performed, and if an attribute is used in the RDN of the entry, no changes to that attribute will be synchronized. When synchronizing between two LDAP resources, this property should typically be set to true since both sides natively store a DN, but if synchronizing from an RDBMS to an LDAP directory, then setting it to false will guarantee that no change in the database will result in a change to the entry's DN. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the attribute comparison method that will be used for comparing the difference between source and destination entries. |
| Default Value | syntax-based |
| Allowed Values | syntax-based - Attributes will be compared based on their syntax. For instance, if the attribute syntax is case-insensitive, then attributes at the destination will not be updated if they differ only by case. byte-for-byte - Attribute values will be compared byte-for-byte. Any destination attribute value that does not exactly match a source attribute value will be replaced. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
destination-correlation-attributes-on-delete (Advanced Property)
| Description | Each value of this property is a comma separated list of destination attribute names that are used to correlate a deleted source entry to a destination entry. This property is present to allow a separate set of correlation attributes to be used when synchronizing DELETE operations. This may be necessary in environments where entries are often re-created with the same DN or other key attributes. When multiple attribute lists are provided, the server iterates through the attribute lists and uses the first one that matches a single entry. If this property is not specified, then the destination-correlation-attributes property will be used to correlate all types of entries. Since the attribute names that are specified are destination attribute names, the attributes in the detected change are first mapped from source to destination attribute names using the attribute maps defined in this Sync Class. For LDAP servers, the attribute 'dn' can be used even though technically it is not an attribute of an entry, and as with attributes, the dn values are mapped using the DN maps defined in the Sync Class. To prevent incorrect matches, the most restrictive attribute lists--those that will never match the wrong entry--should be first in the list, followed by less restrictive attribute lists, which will only be used when the earlier lists fail. The server will issue AND searches using the format specific to the destination resource, and it is the administrator's responsibility to ensure that these searches are properly indexed in the destination resource. If a source attribute has more than one value, then the operation will succeed if any of the values match a destination attribute value. As an example, when synchronizing user entries between two identical LDAP servers (i.e. no attribute or DN maps), the values of this property could be 'dn,uid', 'uid,employeeNumber', and 'cn,employeeNumber'. In this case, the server would first look for a corresponding entry that had the same 'dn' and 'uid' values. If that returned no results, it would then search for an entry with the same 'uid' and 'employeeNumber', and if that failed, it would finally check for an entry with the same 'cn' and 'employeeNumber'. If none of these matched, then the synchronization change would be aborted and a message logged. Note: Take special care when configuring this property list because by default not all attributes in the source entry are available after it is deleted. For Ping Identity LDAP servers, the changelog-deleted-entry-include-attribute property of the Changlog Backend controls which attributes of the deleted entry are stored in corresponding changelog entry. Likewise, for Sun DS servers, the deletedEntryAttributes configuration attribute of the RetroChangelog controls which attributes of the deleted entry are stored in corresponding RetroChangelog entry. Likewise, the UnboundID trigger that generates the changelog in a relational database can also be configured to store values of selected attributes when an entry is deleted. For Ping Identity LDAP destination servers JSON fields within JSON attributes may be specified by appending '.' and then the JSON field to match. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be matched then 'ubidEmailJSON.value' could be specified. |
| Default Value | None |
| Allowed Values | A comma separated list of attribute names |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
destination-create-only-attribute (Advanced Property)
| Description | Each value of this property is a destination attribute name that is only set when an entry is created and not when it is modified. Certain attributes should only be set when an object is created and then never updated. For instance, when synchronizing from a database to an LDAP directory, it's often advisable to include the 'objectclass' attribute here. |
| Default Value | None |
| Allowed Values | An attribute name |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
attribute-synchronization-mode (Advanced Property)
| Description | Specifies the types of diff that will be performed between the source and destination entries on a MODIFY operation. This determines the scope of attributes that may be modified on the destination. |
| Default Value | modified-attributes-only |
| Allowed Values | all-attributes - All attributes from the source entry will be considered, even if they were not modified as part of the original change. This means that destination attributes that are not affected by the originally modified source attributes may still be modified. modified-attributes-only - Only the source attributes that were originally modified, as well as any destination attributes that depend on these original source attributes (via Attribute Mappings), will be considered. This limits the Data Sync Server to only modifying destination attributes that would have been affected by changes to the attributes originally modified at the source. This value works in conjunction with the sync-on-every-update property on a Attribute Mapping. The target attribute of a Attribute Mapping that is set to sync-on-every-update will always qualify as a "modified attribute" for the purposes of this property. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
ignore-zero-length-values (Advanced Property)
| Description | Indicates whether to ignore attribute values that would result in an empty (zero-length) value being written to the Sync Destination. If set to true, the Data Sync Server will remove these changes from the set of modifications to be applied at the destination server. This property allows you to explicitly prevent writes to the destination server that include empty attribute values since some servers do not allow this behavior. Other attribute values and changes will still be applied, but it will appear as if the empty value did not exist at the source. This behavior applies to realtime sync, the resync command, and the translate-ldif command. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
replace-all-attr-values (Advanced Property)
| Description | Indicates whether to use the ADD and DELETE modification types (reversible), or the REPLACE modification type (non-reversible) for modifications to destination entries. If set to true, REPLACE will be used; otherwise, ADD and DELETE will be used. This property is safe to use with multi-valued attributes; if a single value changes, the difference is computed and a REPLACE is issued with a list of all the resulting values. This property controls the way that modifications will be performed on destination entries. If using the ADD and DELETE modification types, it is possible to reconstruct the source entry from the target and the resulting set of modifications, but the modification is more likely to fail if the entry is altered between the time the entry was retrieved for calculating the diff and the attempt to apply the modifications. The REPLACE modification type is not reversible. It is also more likely to succeed, but may silently lose information if the entry has been altered between the time the entry was retrieved and the modifications were applied. If the replace-all-attr-values-limit is set to a non-zero value, it is possible for a modification to use ADD and DELETE modifications instead of a REPLACE, due to a modification replacing more values than the number replace-all-attr-values-limit is set to. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
replace-all-attr-values-limit (Advanced Property)
| Description | If replace-all-attr-values is set to true and this is set, then a change that replaces more values than the number this is set to will be converted to an ADD/DELETE modification instead of a REPLACE modification. This attribute only applies in cases where the Sync Destination is an LDAP server. This property is used to avoid the creation of large entries in the recent changes database, particularly when dealing with large static groups. This property is only considered when the Sync Destination is an LDAP server. If set to zero, REPLACE modifications will not be converted to an ADD/DELETE. Typically, when making a modification to an attribute with a lot of values, the values are not replaced with a completely different set of values, so doing ADD and DELETE modifications can be more efficient than replacing the entire set. If the set of values being replaced is large, it requires extra bandwidth, extra processing time, and additional disk space (in the changelog, replication database, recent changes database, and the data recovery log), and extra memory to cache the recent changes, meaning it would be more efficient to do ADD and DELETE modifications than a REPLACE modification. If the set of values being replaced is small, network bandwidth, disk space, and memory are less of a concern, so it is fine to use a REPLACE modification in this case. |
| Default Value | 100 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
modifies-as-creates (Advanced Property)
| Description | If set to true, this property allows the Data Sync Server to process a modify operation as a create operation if the destination entry happens to not exist. Normally when this happens, an error will occur because the Data Sync Server attempts to modify an entry that does not exist. As a remedy, this option will cause the Data Sync Server to translate the modify operation into a create, so that it can be successfully applied to the destination server. This setting is not used during resync since the current entry contents (as opposed to a specific change) are always used to determine what changes are needed at the destination. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
creates-as-modifies (Advanced Property)
| Description | If set to true, this property allows the Data Sync Server to process a create operation as a modify operation if the destination entry happens to already exist. Normally when this happens, an error will occur because the Data Sync Server attempts to create an entry that already exists. As a remedy, this option will cause the Data Sync Server to translate the create operation into a modify, so that it can be successfully applied to the destination server. This setting is not used during resync since the current entry contents (as opposed to a specific change) are always used to determine what changes are needed at the destination. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies sync pipe plugins that should be applied to operations that are synchronized by this Sync Class. Plugins defined here are appended to the list of plugins defined on the parent sync pipe. If multiple plugins are provided, then they will be invoked in the order they are specified after any plugins provided by the parent sync pipe. |
| Default Value | None |
| Allowed Values | The DN of any Sync Pipe Plugin. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured Sync Classes:
dsconfig list-sync-classes
[--property {propertyName}] ...
To view the configuration for an existing Sync Class:
dsconfig get-sync-class-prop
--class-name {name}
--pipe-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Sync Class:
dsconfig set-sync-class-prop
--class-name {name}
--pipe-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Sync Class:
dsconfig create-sync-class
--class-name {name}
--pipe-name {name}
--set auto-mapped-source-attribute:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Sync Class:
dsconfig delete-sync-class
--class-name {name}
--pipe-name {name}