<policyConstraints>
<executionTime>
<!-- <below>PT15M</exceeds> -->
<exceeds>PT1H</exceeds>
</executionTime>
</policyConstraints>Activity policies
|
Since 4.10
This functionality is available since version 4.10.
|
Introduction
Activity policy rules provide a way to define actions to certain situations happening during activity execution. These situations are defined by policy constraints, while reactions are defined by policy actions. Each policy can have one or more constraints and one or more actions.
Activity policies are primarily intended to be used to improve task reliability and resilience. They are defined per activity, so different activities in the same task may have different policies.
If policy has to evaluate object that is being processed by clockwork (like provisioning, reconciliation, etc.), then thresholds or global policy rules with proper constraints should be used instead.
Currently, focus policy rule constraints cannot be used in activity policies.
Policies are collected during activity initialization from activity definition and parent activity definitions (in case of composite activity). Policies are evaluated after each item of iterative activity is processed.
High level overview of activity policy processing is following:
-
If constraint is not triggered, nothing happens
-
If constraint is triggered
-
If policy has threshold defined
-
Counter for the policy is incremented.
-
If threshold is reached, policy actions are executed.
-
-
If policy doesn’t have threshold defined
-
Policy actions are executed.
-
-
Policy trigger and message are stored in activity state along with reference to specific policy.
-
Policy constraints
Policy constraints define conditions when policy should be triggered.
Execution time
The execution time constraint checks the activity execution time.
If the activity is distributed to multiple worker tasks, midPoint measures the time when at least one worker task is executing.
The time measurement is not restarted when related tasks are suspended and resumed.
Only when the activity is restarted via restartActivity policy action (see below), the time measurement starts from zero.
When the exceeds element is specified, constraint will trigger if the task execution time exceeds the specified value.
When the below element is specified, constraint will trigger if the task execution time is below the specified value.
Both elements can be specified together to define a time range when the constraint should be triggered.
Execution time for composite activities (like reconciliation) is computed as sum of execution times of child activities.
Example of execution time constraint using
exceedsExecution attempts
The execution attempts constraint checks the number of execution attempts for given activity.
Execution attempts represents number for activity realizations.
The counter is increased by restartActivity policy action (see below).
Suspending and resuming the activity (more precisely, its task) doesn’t increase the number of execution attempts.
When the exceeds element is specified, constraint will trigger if the number of attempts exceeds the specified value.
When the below element is specified, constraint will trigger if the number of attempts is below the specified value.
Both elements can be specified together to define a range when the constraint should be triggered.
Example of policy constraint that is triggered after 3 execution attempts.
<policyConstraints>
<executionAttempts>
<exceeds>3</exceeds>
</executionTime>
</policyConstraints>Item processing result
Item processing result constraint evaluates the result of the processing of an item (object) by the activity. The constraint contains two parameters:
-
status— operation result status to match. It can be eitherPARTIAL_ERRORorFATAL_ERROR. If not present, we decide solely on error category. If error categories are not specified, any error matches. -
errorCategory— error category (network, security, policy, …) to match. If not present, we decide solely on the status.Some errors are not propagated to the level where they can be recognized by this selector.
Example of item processing result constraint
<policyConstraints>
<itemProcessingResult>
<status>partial_error</status>
<errorCategory>network</errorCategory>
</itemProcessingResult>
</policyConstraints>And/or/not
Logical constraints are implemented to help with combining multiple constraints into one.
By default, and is used to combine constraints defined directly under policyConstraints element.
Policy actions
Policy actions are the configured reactions that the system executes when a policy constraint is triggered. They define what should happen (immediately or after a threshold) to an activity or task. Typical actions include sending a notification or suspending the task.
Notification
Notification policy action uses the standard notification mechanism, so it can be configured in the system configuration.
Part of system configuration object with the default activity policy notifier
<systemConfiguration xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
<!-- Other system configuration elements -->
<notificationConfiguration>
<handler>
<simpleActivityPolicyRuleNotifier>(1)
<transport>mail</transport>
</simpleActivityPolicyRuleNotifier>
</handler>
</notificationConfiguration>
<!-- Example to redirect email notification to file -->
<messageTransportConfiguration>
<mail>
<name>mail</name>
<redirectToFile>~/mail.txt</redirectToFile>
<defaultFrom>idm@example.com</defaultFrom>
</mail>
</messageTransportConfiguration>
</systemConfiguration>| 1 | Activity policy notifier using default configuration for to, cc, bcc, body, etc. |
Notification action configuration in activity policy
<policyActions>
<notification/>
</policyActions>Suspend task
Suspend task policy action will immediately suspend the whole task or task tree that executes the activity.
Task will be suspended with FATAL_ERROR result.
Restart activity
Restart activity action restarts the current activity realization. As a result, the activity starts processing from the beginning. This action is useful when activity processing fails due to temporary problems (like network issues).
Restart of the activity happens in two steps.
First, the current activity realization is stopped by suspending the task.
Then the task is resumed, which causes the activity to start from the beginning.
Restart of the task may be delayed using delay parameter, which is specified XML duration.
The default delay parameter value is 5 seconds.
Actual delay is taken as a random number between 0 and delay * (2 ^ (n - 1)), where n is number of execution attempts of the activity but 11 at most.
If the delay is set to 0, the task will be resumed immediately.
Example of restart activity action with delay
<policyActions>
<restartActivity>
<!-- 10 minutes delay -->
<delay>PT10M</delay>
</restartActivity>
</policyActions>Skip activity
Skip activity policy action stops the current activity realization immediately. No further items of that activity should be processed. (There are some limitations regarding multi-node activities. Not all workers may react immediately.)
The execution continues with the next activity (if any) in the activity tree. If the skipped activity was the last one, the task completes normally, but with fatal error in operation result as policy was triggered.
If task is suspended and resumed later, the skipped activity is not executed again.
Example of the skip activity action
<policyActions>
<skipActivity/>
</policyActions>User interface
Activity policies are configured in activity definition XML only.
All activity policies may be enabled or disabled via user interface in task details. This is useful when user wants to force task to finish even when some policies prevent it from doing so (e.g. there’s a triggered policy that suspends the task).
Task details UI also allows user to clear all activity policy triggers and counters, while keeping the policies and activity state untouched.
Figure 1. Activity policies options in task details
Limitations
-
Activity policies are evaluated only for iterative (plain iterative or search based) activities. Activity policies are not supported in:
-
Non-iterative scripting
-
Role analysis clustering
-
Role analysis pattern detection
-
Repartition
-
Cleanup
-
Custom composite activities
-
-
Focus policy constraints currently can’t be used in activity policies
-
User interface support is limited to XML configuration only
Examples
Simple policy that will suspend the task if activity runs for more than 30 minutes and sends notification
<policies xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ActivityPoliciesType">
<policy>
<name>Suspend the task after 30 minutes, send notification</name>
<policyConstraints>
<executionTime>
<exceeds>PT30M</exceeds>
</executionTime>
</policyConstraints>
<policyActions>
<notification/>
<suspendTask/>
</policyActions>
</policy>
</policies>Restart activity if it runs more than 30 minutes, after 3 restarts suspend the task
<policies xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ActivityPoliciesType">
<!--
Restart activity if it runs more than 30 minutes, after three restarts, suspend the task and send the notification.
-->
<policy>
<name>Restart activity if it runs more than 30 minutes</name>
<policyConstraints>
<executionTime>
<exceeds>PT30M</exceeds>
</executionTime>
</policyConstraints>
<policyActions>
<restartActivity/>
</policyActions>
</policy>
<policy>
<name>Activity restarts, suspend task</name>
<policyConstraints>
<executionAttempts>
<exceeds>3</exceeds>
</executionAttempts>
</policyConstraints>
<policyActions>
<notification/>
<suspendTask/>
</policyActions>
</policy>
</policies>Policy rule that restarts activity with delay if there was a network error and skips activity after three restarts attempts
<policies xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ActivityPoliciesType">
<policy>
<name>Restart activity if there's network error for 5 processed objects</name>
<policyConstraints>
<itemProcessingResult>
<!-- <status>fatal_error</status> -->
<errorCategory>network</errorCategory>
</itemProcessingResult>
</policyConstraints>
<policyThreshold>
<!--
When there are 5 objects that failed to be processed because of network error,
restart the activity with a delay.
-->
<lowWaterMark>
<count>5</count>
</lowWaterMark>
</policyThreshold>
<policyActions>
<restartActivity>
<!-- restart in ~10 minutes -->
<delay>PT10M</delay>
</restartActivity>
</policyActions>
</policy>
<policy>
<name>Notification about restart policy</name>
<policyConstraints>
<executionAttempts>
<below>4</below>
<exceeds>1</exceeds>
</executionAttempts>
</policyConstraints>
<policyActions>
<notification/>
</policyActions>
</policy>
<policy>
<name>Notification and skip if policy was restarted 3 times</name>
<policyConstraints>
<executionAttempts>
<exceeds>3</exceeds>
</executionAttempts>
</policyConstraints>
<policyActions>
<notification/>
<skipActivity/>
</policyActions>
</policy>
</policies>See also
-
Related issue MID-10411
Was this page helpful?
YES
NO
Thanks for your feedback