<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>
Resource Schema Handling and Synchronization: Changes in MidPoint 4.6
Since 4.6
This functionality is available since version 4.6.
|
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
Integration of Synchronization-Related Settings
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.
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.
<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.
<objectType>
<kind>entitlement</kind>
<intent>unixGroup</intent>
<delineation>
<objectClass>ri:groupOfNames</objectClass>
<baseContext>
<objectClass>ri:organizationalUnit</objectClass>
<filter>
<q:text>attributes/dn = "ou=unixgroups,dc=example,dc=com"</q:text>
</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:
See DelineationMatcher for more information. |
All delineation configuration items are summarized in the following table.
Item | Description |
---|---|
|
Object class (like |
|
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. |
|
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 |
|
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 |
|
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. |
|
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. |
|
In what order should this delineation specification be used for classification? No value means it should be used at the end. |
|
How should be the base context used for the classification? (See below.) |
Value | Description |
---|---|
|
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. |
|
If the base context is not applicable, it is used. Otherwise, it is ignored. This is the default setting. |
|
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.
<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:text>attributes/dn = "ou=employees,dc=example,dc=com"</q:text>
</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:text>attributes/dn = "ou=special,dc=example,dc=com"</q:text>
</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:text>attributes/businessCategory = "admin"</q:text>
</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:text>attributes/businessCategory = "tester"</q:text>
</filter>
</delineation>
</objectType>
</schemaHandling>
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
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
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.
<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:
Item | Description | Default value |
---|---|---|
|
Type of the focus objects. |
|
|
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.
Item | Description |
---|---|
|
Reaction(s) to individual synchronization situation(s). This is the core of the configuration. |
|
Settings that are applied to all clockwork-based actions defined here. |
|
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:
<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:
Item | Description |
---|---|
|
The name of the reaction. Just for documentation purposes. |
|
The description of the reaction. Just for documentation purposes. |
|
The documentation of the reaction. |
|
Order in which this reaction is to be evaluated. (Related to other reactions.) Smaller numbers go first. Reactions with no order go last. |
|
Defines a particular synchronization situation or situations. |
|
If present, limits the applicability of this reaction to given synchronization channel or channels. |
|
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. |
|
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.
Action | Description | Legacy action URI (part) |
---|---|---|
|
The data from the resource objects are "synchronized into" the focus object, via mappings and similar means. |
|
|
Links resource object to its owning focus. |
|
|
Unlinks resource object from its owning focus. |
|
|
Creates an owning focus for the resource object. |
|
|
Deletes the owning focus for the resource object. |
|
|
Inactivates (disables) the owning focus for the resource object. |
|
|
Deletes the resource object. |
|
|
Inactivates (disables) the resource object. |
|
|
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:
Item | Description | Default value |
---|---|---|
|
For documentation purposes |
|
|
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. |
|
|
If set to false, the full clockwork processing will not run. So e.g. linking and unlinking will be done in "fast" way. |
|
|
If |
|
|
If set to |
|
|
Option to limit change computation and execution only for the source resource. |
|
|
Object template used in case the focus object is created or modified. |
template defined in archetype or system configuration |
|
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:
Original item | New place | Path |
---|---|---|
|
object type identification |
|
|
object type delineation |
|
|
focus specification |
|
|
indirectly replaceable via conditions in classification and synchronization |
|
|
condition in the delineation |
|
|
owner filter in the |
|
|
confirmation expression in the |
|
|
correlation definition |
|
|
default settings for synchronization reactions |
|
|
synchronization settings |
|
|
synchronization reactions (new syntax) |
|
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.
See also Resource Object Set Specification.
An Example
Let us have the following configuration of object types:
<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. |
<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:
<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.