Resource Schema Handling and Synchronization: Changes in MidPoint 4.6

Last modified 28 Mar 2023 12:38 +02:00

Since 4.6

This functionality is available since version 4.6.

Table of Contents

Introduction
Changes in Object Type Definitions
Object Class Definition Adaptation
Defaults for Kind and Intent

Introduction

In midPoint 4.6, the configuration of schema handling and synchronization was greatly streamlined. These parts are now merged together and restructured for easier comprehensibility and maintainability. The ability to adapt object class definitions was added as well.

Changes in Object Type Definitions

Since the beginning of midPoint, the synchronization-related settings were separated from the definitions of the respective object types. Starting with 4.6, they are finally merged into one configuration entity.

Listing 1. Sample combined object type definition

<resource>
    <!-- ... -->
    <schemaHandling>
        <objectType>
            <kind>account</kind>
            <displayName>Default Account</displayName>
            <default>true</default>
            <delineation>
                <objectClass>ri:user</objectClass>
                <classificationCondition>...</classificationCondition> (1)
                <!-- ... -->
            </delineation>
            <focus>
                <type>UserType</type> (1)
                <!-- ... -->
            </focus>
            <attribute>
                <ref>ri:dn</ref>
                <!-- ... -->
            </attribute>
            <!-- ... -->
            <correlation>...</correlation> (1)
            <synchronization>...</synchronization> (1)
        </objectType>
        <!-- ... -->
    </schemaHandling>
</resource>

1	All this information was originally part of the separate `objectSynchronization` configuration.

The original synchronization/objectSynchronization item is marked as deprecated.

Resource Object Type Delineation

A new section, called delineation, is used to specify the set of resource objects that comprise the given resource object type.

The following basic example defines the type of entitlement/unixGroup that consists of all objects having the class of groupOfNames on a given resource.

Listing 2. The most simple example of object type delineation

<objectType>
    <kind>entitlement</kind>
    <intent>unixGroup</intent>
    <delineation>
        <objectClass>ri:groupOfNames</objectClass>
    </delineation>
</objectType>

Now let us extend the definition to include the base context.

The following configuration restricts the entitlement/unixGroup type to objects of groupOfNames class that reside within ou=unixgroups,dc=example,dc=com organizational unit.

Listing 3. Object type delineation with a base context restriction

<objectType>
    <kind>entitlement</kind>
    <intent>unixGroup</intent>
    <delineation>
        <objectClass>ri:groupOfNames</objectClass>
        <baseContext>
            <objectClass>ri:organizationalUnit</objectClass>
            <filter>
                <q:equal>
                    <q:path>attributes/dn</q:path>
                    <q:value>ou=unixgroups,dc=example,dc=com</q:value>
                </q:equal>
            </filter>
        </baseContext>
    </delineation>
</objectType>

The base context is used to search for objects of entitlement/unixGroup type by adding the base context condition to the search query. However, it can be used also as a classification rule that helps to determine whether an incoming object of groupOfNames class belongs to the entitlement/unixGroup type or not.

The use of the base context for classification is new in 4.6. It has some restrictions, namely:

The base context root must be specified by equal filter with a single value of the type of "LDAP distinguished name". The fact that it is a distinguished name is determined by the presence of distinguishedName matching rule for it.
The shadow being classified must have a primary or secondary identifier, again with the distinguishedName matching rule set.

See DelineationMatcher for more information.

All delineation configuration items are summarized in the following table.

Table 1. List of delineation configuration items
Item	Description
`objectClass`	Object class (like `ri:inetOrgPerson`) for this resource object type.
`auxiliaryObjectClass` (multivalued)	The reference to additional object classes for this object. The reference should point to object class definition and this definition should be marked as auxiliary. Definitions of attributes from these classes are "imported" to the object type. However, currently these auxiliary object classes are not used for classification; i.e. the classification decision is not based on their presence in the specific resource object.
`baseContext`	The definition of base context (resource object container). This object will be used as a base for searches for objects of this type. Usually only the objects that are hierarchically below the `baseContext` are returned by such a search. E.g. this is used to specify LDAP `organizationalUnit` that contains users or groups of particular type. This information is used for object classification as well. See also `baseContextClassificationUse` property.
`searchHierarchyScope`	Definition of search hierarchy scope. It specifies how "deep" the search should go into the object hierarchy. It is only applicable to resources that support hierarchical organization of objects (e.g. LDAP resources). This information is used for object classification (along with `baseContext`) as well. See also `baseContextClassificationUse` property.
`filter` (multivalued)	A filter that defines the object set. Used for both searching and classification. Filter(s) specified for a subtype are appended to any filter(s) defined in the supertype.
`classificationCondition`	Expression that is evaluated to check whether a resource object is of given type. It is assumed to return a boolean value. (If no condition is present then it is assumed to be always true, i.e. the classification is done using the other means.) It is preferable to use declarative means for classification, i.e. base context and filter(s). Note: This was the primary mechanism for classification used before 4.6.
`classificationOrder`	In what order should this delineation specification be used for classification? No value means it should be used at the end.
`baseContextClassificationUse`	How should be the base context used for the classification? (See below.)

Table 2. The values for `baseContextClassificationUse` property
Value	Description
`required`	The base context must be used (if it’s present in the delineation). If it cannot be applied, the delineation is considered as non-matching.
`ifApplicable`	If the base context is not applicable, it is used. Otherwise, it is ignored. This is the default setting.
`ignored`	The base context is not used for classification.

Resource Object Classification

The classification means determining the object type (i.e. kind and intent) for a resource object that is seen by midPoint.

The normal course of action is that the first time an object is seen, it is classified. There are special cases, however, when classification criteria are being developed. It is common to do objects classification and re-classification, until the criteria are stabilized. See also Simple Simulation Tutorial (since 4.7).

The overall classification algorithm is the following:

First, candidate object types with classification order specified are tried - in their respective order. The first matching one is used.
Then, candidate object types without order are tried. Matching ones are collected.
- If there is a default object type ("default for object class") among matching ones, it is used.
- If there is exactly one matching type, it is used.
- If there is no matching type, the classification is unsuccessful.
- If there are multiple (non-default) matching types, a special heuristic is executed: the first one with the legacy synchronization section present is returned. Otherwise, arbitrary one is used. (This may be changed in the future.)

The details can be seen in the source code.

The original items auxiliaryObjectClass, baseContext, searchHierarchyScope are marked as deprecated. The objectClass property has a mixed meaning (the delineation in object type definition and the identifier in object class definition - see below), so it is formally not deprecated here. But in object type definitions it should be specified with the delineation item.

Here is an (artificial) example of using advanced resource object type delineation.

Listing 4. Example of resource object type delineation

<schemaHandling>

    <objectType>
        <kind>account</kind>
        <intent>employee</intent>
        <documentation>
            Standard employee account. Resides in `employees` OU. Representative: `alice-employee.ldif`.
        </documentation>
        <delineation>
            <objectClass>ri:inetOrgPerson</objectClass>
            <baseContext>
                <objectClass>ri:organizationalUnit</objectClass>
                <filter>
                    <q:equal>
                        <q:path>attributes/dn</q:path>
                        <q:value>ou=employees,dc=example,dc=com</q:value>
                    </q:equal>
                </filter>
            </baseContext>
        </delineation>
    </objectType>

    <objectType>
        <kind>account</kind>
        <intent>special</intent>
        <documentation>
            An account devoted to special duties. It resides in `special` OU.
            This type is abstract, and has two subtypes: `admin` and `tester`.
        </documentation>
        <abstract>true</abstract>
        <delineation>
            <objectClass>ri:inetOrgPerson</objectClass>
            <baseContext>
                <objectClass>ri:organizationalUnit</objectClass>
                <filter>
                    <q:equal>
                        <q:path>attributes/dn</q:path>
                        <q:value>ou=special,dc=example,dc=com</q:value>
                    </q:equal>
                </filter>
            </baseContext>
        </delineation>
    </objectType>

    <objectType>
        <kind>account</kind>
        <intent>admin</intent>
        <documentation>
            Account used for administration. Resides in `special` OU (defined in the supertype).
            Additional filtering condition: `businessCategory` is `admin`. Representative: `jim-admin.ldif`.
        </documentation>
        <super>
            <kind>account</kind>
            <intent>special</intent>
        </super>
        <delineation>
            <!-- baseContext is inherited -->
            <filter>
                <q:equal>
                    <q:path>attributes/businessCategory</q:path>
                    <q:value>admin</q:value>
                </q:equal>
            </filter>
        </delineation>
    </objectType>

    <objectType>
        <kind>account</kind>
        <intent>tester</intent>
        <documentation>
            Account used for testing. Resides in `special` OU (defined in the supertype).
            Additional filtering condition: `businessCategory` is `tester`. Representative: `ann-tester.ldif`.
        </documentation>
        <super>
            <kind>account</kind>
            <intent>special</intent>
        </super>
        <delineation>
            <!-- baseContext is inherited -->
            <filter>
                <q:equal>
                    <q:path>attributes/businessCategory</q:path>
                    <q:value>tester</q:value>
                </q:equal>
            </filter>
        </delineation>
    </objectType>

</schemaHandling>

Listing 5. Alice, an employee

dn: uid=alice,ou=employees,dc=example,dc=com
uid: alice
cn: Alice Green
sn: Green
givenName: Alice
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson

Listing 6. Jim, an admin

dn: uid=jim,ou=special,dc=example,dc=com
uid: jim
cn: Jim Admin
sn: Admin
givenName: Jim
businessCategory: admin
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson

Listing 7. Ann, a tester

dn: uid=ann,ou=special,dc=example,dc=com
uid: ann
cn: Ann the Tester
sn: Tester
givenName: Ann
businessCategory: tester
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson

Focus Objects For Given Resource Object Type

Before 4.6, the connection to focus objects was specified in the synchronization section. Now it is pulled up into a distinct place withing the object type definition.

Listing 8. Specifying focus objects

<objectType>
    <kind>entitlement</kind>
    <intent>unixGroup</intent>
    <delineation>
        <objectClass>ri:groupOfNames</objectClass>
    </delineation>
    <focus>
        <type>OrgType</type>
        <archetypeRef oid="be2c817e-387c-441a-82d0-e5a15e7cefcd"/> <!-- Unix Group Archetype -->
    </focus>
</objectType>

There are two configuration items available:

Table 3. List of focus connection configuration items
Item	Description	Default value
`type`	Type of the focus objects.	`UserType`
`archetypeRef`	Focus archetype corresponding to this resource object type. If specified, the value is enforced upon focus objects that have a projection of this object type linked. It is also used during correlation, i.e. when correlating a resource object of this type, midPoint looks for focus objects having specified archetype.	no archetype (all objects of given type)

The archetype specification is a feature that is new in 4.6.

Notes/limitations:

The archetype must be currently a structural one. In the future, we may consider allowing multiple (i.e. structural and/or auxiliary) archetypes here.
The enforcement means that if the focus has no archetype, the archetype is added to the focus. If it has a different archetype, a policy violation exception is raised. This behavior may change in the future, e.g. it may become configurable.
The enforcement is done for all projections, i.e. not only for ones being synchronized into midPoint, but also for the ones that are created by midPoint. But beware of the timing: if a projection is added during the clockwork run, and that projection enforces an archetype, the effects of this enforcement may be limited during the current clockwork run. For example, if the archetype induces some projections, they might not be created because of the processing in waves. Generally speaking, it is safer to set the focus archetype explicitly (e.g. by primary delta or in the object template) in these cases.

Correlation

Correlation is the process of finding a focus object (or determining there is none yet) for given resource object. In 4.6, it was significantly reworked. It is described in a separate document.

Synchronization

The synchronization section in the object type definition is the simplification of the legacy objectSynchronization definition. Basically, only the synchronization reactions (with a couple of related settings) are kept there.

Table 4. New synchronization configuration items
Item	Description
`reaction` (multivalued)	Reaction(s) to individual synchronization situation(s). This is the core of the configuration.
`defaultSettings`	Settings that are applied to all clockwork-based actions defined here.
`opportunistic`	If set to true midPoint will try to link and synchronize objects whenever possible. E.g. it will link accounts in a case if an account with a conflicting account is found and correlation expression matches. MidPoint can be quite aggressive in this mode therefore this switch is used to turn it off. It is on by default.

An example:

Listing 9. Sample synchronization reactions

<objectType>
    <!-- ... -->
    <synchronization>
        <defaultSettings>
            <limitPropagation>true</limitPropagation>
        </defaultSettings>
        <reaction>
            <situation>linked</situation>
            <actions>
                <synchronize/>
            </actions>
        </reaction>
        <reaction>
            <situation>deleted</situation>
            <actions>
                <unlink/>
            </actions>
        </reaction>
        <reaction>
            <situation>unlinked</situation>
            <actions>
                <link/>
            </actions>
        </reaction>
        <reaction>
            <situation>unmatched</situation>
            <actions>
                <addFocus/>
            </actions>
        </reaction>
    </synchronization>
</objectType>

Synchronization Reactions

This part is the core of the synchronization configuration. For each synchronization situation there is a synchronization action specified. (In theory, there can be more of them, but usually there is exactly one action defined for each situation.)

Each reaction may have the following configuration items:

Table 5. Synchronization reaction configuration items
Item	Description
`name`	The name of the reaction. Just for documentation purposes.
`description`	The description of the reaction. Just for documentation purposes.
`documentation`	The documentation of the reaction.
`order`	Order in which this reaction is to be evaluated. (Related to other reactions.) Smaller numbers go first. Reactions with no order go last.
`situation` (multivalued)	Defines a particular synchronization situation or situations.
`channel` (multivalued)	If present, limits the applicability of this reaction to given synchronization channel or channels.
`condition`	Expression that is evaluated to check whether this reaction is applicable in a particular context. It is assumed to return a boolean value. If it returns 'true' then this reaction will be applied. If it returns 'false' it will be ignored.
`actions`	Action or actions to be executed in the given situation.

The following synchronization actions are available. The local part of the legacy action URI or URIs is specified for the migration purposes.

Table 6. Synchronization actions
Action	Description	Legacy action URI (part)
`synchronize`	The data from the resource objects are "synchronized into" the focus object, via mappings and similar means.	`#synchronize`, `#modifyUser`
`link`	Links resource object to its owning focus.	`#link`, `#linkAccount`
`unlink`	Unlinks resource object from its owning focus.	`#unlink`, `#unlinkAccount`
`addFocus`	Creates an owning focus for the resource object.	`#addFocus`, `#addUser`
`deleteFocus`	Deletes the owning focus for the resource object.	`#deleteFocus`, `#deleteUser`
`inactivateFocus`	Inactivates (disables) the owning focus for the resource object.	`#inactivateFocus`, `#disableUser`
`deleteResourceObject`	Deletes the resource object.	`#deleteShadow`, `#deleteAccount`
`inactivateResourceObject`	Inactivates (disables) the resource object.	`#inactivateShadow`, `#disableAccount`
`createCorrelationCase`	Creates (or updates) a correlation case for resource object - typically in "disputed" synchronization state, i.e. one whose owner cannot be reliably determined.	none

Each action may have the following configuration items:

Table 7. Configuration items for a synchronization action
Item	Description	Default value
`name`, `description`, `documentation`	For documentation purposes
`order`	Order in which this action is to be executed, if there are more of them. (Related to other actions for given reaction.) Smaller numbers go first. Entries with no order go last. Usually not needed, because single action is typically present.
`synchronize`	If set to false, the full clockwork processing will not run. So e.g. linking and unlinking will be done in "fast" way.	`true`
`reconcile`	If `true`, the focus and the projection being synchronized will be reconciled while executing changes.	`true` for situations when there is no known object delta - i.e. change information - coming from the resource
`reconcileAll`	If set to `true`, applicable synchronization reactions will attempt to reconcile the real attributes from all resources with the state of the midPoint repository. This may require additional read and recompute, therefore may be slightly less efficient.	`false`
`limitPropagation`	Option to limit change computation and execution only for the source resource.	`false`
`objectTemplateRef`	Object template used in case the focus object is created or modified.	template defined in archetype or system configuration
`executeOptions` (experimental)	Model execute options that will be used when invoking this reaction. Options explicitly specified here take precedence over any options derived from the context or other parameters (like "recompute"). So please use with care.	derived from the context or other parameters

The synchronize option and the ones below it are not applicable to createCorrelationCase action.

Default Synchronization Action Settings

This item contains the default values for reconcile, reconcileAll, limitPropagation, objectTemplateRef, and executeOptions configuration items. These are applied to all reactions, unless overridden.

Migrating The Legacy Synchronization Section

The configuration items have the following new places:

Table 8. New places for legacy synchronization settings
Original item	New place	Path
`kind` and `intent`	object type identification	`kind` and `intent`
`objectClass`	object type delineation	`delineation/objectClass`
`focusType`	focus specification	`focus/type`
`enabled`	indirectly replaceable via conditions in classification and synchronization	`delineation/classificationCondition` and `synchronization/reaction[xxx]/condition`
`condition`	condition in the delineation	`delineation/classificationCondition`
`correlation`	owner filter in the `filter` correlator	`correlation/correlators/filter/ownerFilter`
`confirmation`	confirmation expression in the `filter` correlator	`correlation/correlators/filter/confirmation`
`correlationDefinition` (experimental in 4.5)	correlation definition	`correlation`
`objectTemplateRef`, `reconcile`, `limitPropagation`	default settings for synchronization reactions	`synchronization/defaultSettings/objectTemplateRef`, `…/reconcile`, `…/limitPropagation`
`opportunistic`	synchronization settings	`synchronization/opportunistic`
`reaction`	synchronization reactions (new syntax)	`synchronization/reaction`

Note that synchronizationSorter is still at the original place. The reason is that it is not connected to any specific object type.

Object Type Inheritance

An object type can inherit parts of its definition from so-called supertype. This feature is new in 4.6, and is described in a separate document.

Object Class Definition Adaptation

There may be situations when you want to override some settings (for example, attribute values cardinality, protected objects, or attribute fetch strategy) not only for selected object type(s), but for all objects in a given object class. For example, you may need to specify fetch strategy for specific attribute of groupOfUniqueNames object class, and apply this consistently to all search operations over this object class. To do so, special schemaHandling/objectClass definition can be used.

This is something that had been achieved by setting default=true for a selected object type definition. However, the use of object class refinement is more focused and (in a sense) more clear way how to achieve this.

Beware: Although the XSD type is formally ResourceObjectTypeDefinitionType (primarily because of implementation reasons), not all elements of ResourceObjectTypeDefinitionType are supported here. For example, it’s not possible to specify kind, intent, nor super-type here. Because of a limitation of XSD language we are not able to express these restrictions without changing the order of XML elements in complying documents (because the typical solution: deriving both ResourceObjectTypeDefinitionType and something like ResourceObjectClassDefinitionType from a common ancestor would mean that the order of XML elements in resulting documents would be different from what it is now).

We also advise to avoid specification of pure object-type concepts (like mappings) in these definitions. It is better to create a special (abstract) object type to do this.

Defaults for Kind and Intent

In midPoint 4.4.x and before, the effects of not specifying kind and intent values (at various places in the configuration) were not clearly defined. In 4.5 and 4.6 we gradually clarified this.

Starting from 4.6, the behavior is driven by defaultForKind and defaultForObjectClass properties in the object type definition in the following way.

"Default for Kind" Property

This property specifies whether the given resource object type is the default one for given kind of objects, i.e. for accounts, entitlements or "generic objects".

Only one type can be the default one for given kind. Setting this flag to true for more than one type is an error.

There are two specific places where this is used.

Resource Object Construction

When a resource object construction is assigned to a focus object (for example, to a user), there are the following defaults:

if kind is not specified, the account is assumed;
if intent is not specified, the "default for kind" intent is assumed - for the given kind.

Search for Resource Objects

There are situations when midPoint searches for resource objects. The most prominent are searches done as part of import or reconciliation activities. The use of projectionDiscriminator in associationFromLink results in a search operation as well. (See sample constructions below.)

When searching for resource objects without providing object class name, the following applies:

kind must be specified;
if intent is not specified, the "default for kind" intent is assumed - for the given kind.

An Example

Let us have the following configuration of object types:

Listing 10. Sample configuration

<objectType>
    <!-- no kind nor intent specified --> (1) (2)
    <displayName>Default account</displayName>
    <defaultForKind>true</defaultForKind>
    <!-- ... -->
</objectType>
<objectType>
    <kind>account</kind>
    <intent>testing</intent>
    <displayName>Testing account</displayName>
    <!-- ... -->
</objectType>
<objectType>
    <kind>entitlement</kind>
    <intent>group</intent>
    <displayName>Standard group</displayName>
    <defaultForKind>true</defaultForKind>
    <!-- ... -->
</objectType>
<objectType>
    <kind>entitlement</kind>
    <intent>other</intent>
    <displayName>Some other entitlement</displayName>
    <!-- ... -->
</objectType>

1	If kind is not specified in the definition, `account` is assumed.
2	If intent is not specified in the definition, `default` (literally) is assumed.

Listing 11. Sample resource object constructions

<role xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
    <!-- ... -->
    <assignment>
        <construction>
            <resourceRef oid="0e5b7304-ea5c-438e-84d1-2b0ce40517ce"/>
            <kind>entitlement</kind>
            <!-- no intent specified --> (1)
        </construction>
    </assignment>
    <inducement>
        <construction>
            <resourceRef oid="0e5b7304-ea5c-438e-84d1-2b0ce40517ce"/>
            <!-- no kind nor intent specified --> (2)
            <association>
                <ref>ri:groups</ref>
                <outbound>
                    <expression>
                        <associationFromLink>
                            <projectionDiscriminator>
                                <kind>entitlement</kind>
                                <!-- no intent specified --> (3)
                            </projectionDiscriminator>
                        </associationFromLink>
                    </expression>
                </outbound>
            </association>
        </construction>
    </inducement>
</role>

1	`group` intent is assumed, as it is marked as "default for kind" for entitlements (see Resource Object Construction)
2	`account` kind is assumed, and within it, `default` intent, as it is marked as "default for kind" for accounts (see Resource Object Construction)
3	`group` intent is assumed, as it is marked as "default for kind" for entitlements, and we are doing a search for entitlements here (see Search for Resource Objects)

"Default for Object Class" Property

This property specifies whether the given resource object type is the default one for its object class, e.g. for ri:AccountObjectClass or ri:inetOrgPerson.

Only one type can be the default one for given object class. Setting this flag to true for more than one type is an error.

There are two specific places where this is used.

Classifying the Resource Objects

When classifying resource objects, we often use the type marked as "default for object class" as a "catch-all" type when no other type matches. However, this functionality can be achieved - perhaps more cleanly - also using classificationOrder property of object type delineation. See the classification algorithm description.

Looking for Default Definitions

This applies when searching for resource objects, typically in import or reconciliation activities, and using only the object class name. For example:

Listing 12. Importing accounts by object class name

<task>
    <!-- ... -->
    <activity>
        <work>
            <import>
                <resourceObjects>
                    <resourceRef oid="2696334a-c3d1-4aa6-b147-ff16cd387a0f"/>
                    <objectclass>ri:inetOrgPerson</objectclass>
                </resourceObjects>
            </import>
        </work>
    </activity>
</task>

There are definitions that should be applied when the query against the resource (looking for all inetOrgPerson objects) is issued. For example, midPoint needs to specify attributes to return or the base context. When defaultForObjectClass is used in a type definition that refers to inetOrgPerson class, that type definition is used to provide the necessary information. (Note that midPoint still attempts to synchronize all members of inetOrgPerson.)

However, since 4.6, the preferred way to provide such object-class-level definitions that should be applicable to all objects of given object class (e.g. inetOrgPerson) is to use Object Class Definition Adaptation, i.e. to provide schemaHandling/objectClass refinement for ri:inetOrgPerson. Therefore, it’s no longer necessary nor recommended to specify default object type for object class just for this purpose.

Overall, it is better to avoid defaultForObjectClass setting, and hence also default setting.

"Default" Property

This is a shorthand for specifying both defaultForKind and defaultForObjectClass. The behavior should be similar to the one in 4.4.x and before, although there may be subtle differences caused by the fact that the implementation was significantly reworked.

These three properties, defaultForKind, defaultForObjectClass and default, may be changed or even removed in the future.

Was this page helpful?

YES NO

Thanks for your feedback