<task> <name>Shadow refresh</name> ... <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/shadowRefresh/handler-3</handlerUri> <recurrence>recurring</recurrence> <schedule> <interval>10</interval> </schedule> </task>
Shadow Refresh Task
Since 3.9This functionality is available since version 3.9.
There are situations, when shadow objects do not entirely reflect the reality. Such situations are to be expected, as those "shadows" are actually copies of the data that originate from other systems. The shadow objects also contain pending operation data that naturally change in time. And there are also cases when the data model evolves and data in the "shadows" need to be updated.
All such situations mean that shadow objects need to refreshed. Refresh means that midPoint makes sure that a shadow is internally consistent and to execute all operations that need to be executed in order to re-gain consistency. Shadow refresh will try to finish pending operations, e.g. re-try failed operations. Refresh will update the status of manual operations. And so on. Refresh task will also make sure that application-level indexes for shadow objects are right. Therefore it can be useful in migration scenarios or in cases that system configuration was changed and stored data need to be updated.
Refresh and reconciliation
Refresh is not the same thing as reconciliation. Reconciliation is quite heavy-weight, trying to get the object from the resources, checking mappings and policies and so on. On the other hand, refresh is designed to a lightweight task. Refresh is going to execute operations that are easy and efficient, such as check whether shadow indexes are correct. When it comes to operations with the resources, refresh will only execute those operations that need to be executed. E.g. failed operations will be re-tried, but only if the re-try time was reached. Refresh is meant to set the shadow objects right, nothing more. It will not fix data on the resource, neither will it run the mappings to modify data of focal objects. The purpose of refresh is to make sure that shadow objects are right.
Shadow refresh happens during normal operation of midPoint, e.g. it will happen during reconciliation process. However, sometimes it is preferable to execute just the refresh operation in a controlled manner. This may be achieved by shadow refresh task.
Shadow refresh task is a lightweight task that executes shadow refresh on selected shadows. Refresh task is very simple:
Such refresh task will look for shadow objects that contain pending operations. The reason is that those are the objects that most likely need to be refreshed, e.g. failed operation has to be retried or the status of manual operation needs to be checked. This is a reasonable default for sustained operation of midPoint.
There are cases when refresh task needs to be run explicitly on a selected group of shadows (e.g. migration scenarios). In that case the search filter may be explicitly specified in the refresh task:
<task> <name>Forced Shadow refresh</name> <extension> <modelext:objectQuery> <q:filter> <q:and> <q:ref> <q:path>resourceRef</q:path> <q:value> <q:oid>10000000-0000-0000-0000-000000000004</q:oid> </q:value> </q:ref> <q:exists> <q:path>pendingOperation</q:path> </q:exists> </q:and> </q:filter> </modelext:objectQuery> </extension> ... <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/shadowRefresh/handler-3</handlerUri> <recurrence>single</recurrence> </task>
<task> <name>Forced Shadow refresh</name> <extension> <modelext:objectQuery> <q:filter> <q:ref> <q:path>resourceRef</q:path> <q:value> <q:oid>10000000-0000-0000-0000-000000000004</q:oid> </q:value> </q:ref> </q:filter> </modelext:objectQuery> </extension> ... <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/shadowRefresh/handler-3</handlerUri> <recurrence>single</recurrence> </task>
Whenever you specify query, it overrides the default query (all shadows on all resources with pending operations).
Refresh task is quite lightweight and efficient. Therefore it can usually be scheduled for quite a frequent execution, usually executing every few minutes.