Simulation usage reference

Last modified 11 Sep 2026 10:04 UTC
Simulation feature
This page is an introduction to Simulation midPoint feature. Please see the feature page for more details.
Since 4.7
This functionality is available since version 4.7.
Table of Contents

Introduction

The simulation feature in midPoint provides a safe environment for conducting a "what-if" analysis before deploying configuration changes to production. Using the simulation feature, administrators and developers can preview the effects of configuration modifications or policy adjustments without risking damage to real data. By simulating effects of changes before applying them, midPoint enables thorough testing and validation while maintaining operational continuity.

Simulations leverage two complementary dimensions: execution mode and configuration to use.

  • Execution mode determines whether actions carried out by an activity have persistent effects or not. Any activity in midPoint can execute in either of the two modes.

    • In preview mode, changes are computed but not applied—they are written to the simulation result object instead, leaving the system state untouched. The simulation results object collects statistical and procedural information about the changes that would be applied.

    • In full execution mode, all computed changes are persistently applied to the midPoint repository and external resources, and recorded in the system audit log.

  • Configuration to use specifies whether the activity runs against production or development configuration.

    • Production configuration comprises all items engaged in regular operations and can be used for persistent effects.

    • Development configuration represents configuration that is being tested—e.g., new mapping rules, new object type, adjusted resource configuration, etc. The development configuration cannot be used in the full execution mode.

The production vs. development configuration is expressed using object lifecycle states in midPoint.

  • Objects with active and deprecated lifecycle states comprise production configuration.

  • Objects with proposed and active lifecycle states comprise development configuration.

  • Objects with draft, archived and any other lifecycle states are effectively disabled. They are not used by any mode and configuration combination.

Table 1. Allowed combinations of modes and configurations, their results, and related lifecycle states
Preview mode results Full mode results Works with lifecycle states

Development configuration

simulate

—

proposed, active

Production configuration

simulate

write to DB

active, deprecated

See also the diagram in Object Lifecycle.

There are some specialties like postponing resource operations either because of the resource unavailability (see Resource Maintenance State), or because of provisioning propagation. But none of these contradict the basic idea that all computed operations are going to be (eventually) applied.

Usual workflow with simulations and object lifecycle states

Simply put, an object typically goes through its lifecycle like this: draft → proposed → active → deprecated → archived.

With objects in the proposed lifecycle state, you can use simulations to test configuration of a new mapping, synchronization reaction, object type definition, or a whole resource, for example. The proposed state shows that the configuration is likely to be activated in the future. By setting an object as deprecated, you signify that it is going to be retired eventually. It is still used in production until the replacing proposed object is "deployed" (set as active).

To deploy the new replacing object and retire the old one:

  1. Set the new object from proposed to active, effectively enabling it in production

  2. Set the old object from deprecated to archived, effectively disabling it entirely.

This can be done simultaneously to achieve seamless transition.

Typical Simulation Scenarios

This section presents a couple of typical simulation-related scenarios.

See the tutorial where these scenarios are shown in more detail.

Introduction of a New Resource Configuration

When connecting a new source or target system to midPoint, we must create its resource definition. However, the first version of the definition is rarely completely correct, and usually there is a need to fine-tune it. MidPoint supports this by allowing us to evolve the definition safely using the proposed (or development) configuration so that potential mistakes will not cause any harm to production data in midPoint or on resources.

Processes directly supported in this area include:

  • classification of resource objects (e.g., accounts) into object types, like account/default or account/person;

  • correlation of resource objects to the so-called focus objects, like users, roles, and so on;

  • mapping of data between resource objects and focus objects.

Evolution of a Resource Configuration

Eventually, the first version of a resource configuration is completed and put into production use. Sooner or later, requirements for its evolution will emerge. The simulations feature supports such evolution by allowing the addition of pieces of the configuration (like new object types, attributes, associations, and mappings) first in the proposed configuration. After they have been developed and tested enough, they can be switched into production. Also, other items can be replaced by marking them as deprecated and adding analogous proposed items. Yet other items can be deprecated without replacement, effectively planning for their removal.

Specific Functionality

Switching Between Production and Development Mode

Various configuration items (such as a resource) can be switched between production and proposed configuration by changing their object lifecycle state. See the figure below.

Switching a resource between production and proposed configurations
Figure 1. Switching a resource between production and proposed configurations

Running the Simulation on Foreground

Simulation results and related objects can be displayed via the midPoint GUI. For more information, see Simulations UI.

Running the Simulation on Background

The simulations are typically executed in background tasks that host individual activities. There are three aspects that can be defined:

Execution Mode

From the simulations perspective, there are three relevant modes an activity can run in:

  • Full execution

  • Preview

  • Shadow management preview

Refer to Execution and Execution Mode for details about the execution modes.

Configuration Used

An activity can execute against production configuration or proposed configuration. (The latter cannot be used in the full execution mode.)

This configuration is driven by execution/configurationToUse parameter in the activity definition.

Refer to Execution and Execution Mode for more details.

Simulation Result

We can run the simulation with or without creating the simulation result. Furthermore, there are various options connected with the result itself, such as what metrics and event marks we should include in the result.

This configuration is driven by the reporting/simulationResult parameter in the activity definition.

For more information, see Configuring Simulation Results and activity simulation result definition.

An Example

Listing 1. An import task executing in simulation mode, over development configuration, and with creation of a simulation result
<task xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
      xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
      oid="8b169df3-3124-4e36-871f-83bb52acfd7b">
    <name>Simulated import from HR</name>
    <executionState>runnable</executionState>
    <activity>
        <work>
            <import>
                <resourceObjects>
                    <resourceRef oid="236dd5ca-47df-403c-82e1-9ce2f36be000"/>
                    <objectclass>ri:AccountObjectClass</objectclass>
                </resourceObjects>
            </import>
        </work>
        <execution>
            <mode>preview</mode> (1)
            <configurationToUse>
                <predefined>development</predefined> (2)
            </configurationToUse>
        </execution>
        <reporting>
            <simulationResult/> (3)
        </reporting>
    </activity>
</task>
1 The value of preview means we do not want to execute the actions in this task.
2 development means we want to use the development configuration in this task.
3 The presence of simulationResult means we want to create the simulation result object.

Displaying and Managing the Simulation Results

Simulation results and related objects can be displayed via midPoint GUI. For more information, see Simulation in GUI.

Configuring Simulation Results

Simulation results are configured in the system configuration and in individual simulation activities. Aspects that are configured include:

  • What metrics and event marks should be observed during the particular simulation?

  • Should a dedicated database partition be used for storing this simulation result?

See Simulation Result Definition for more information.

Reporting

Simulation results can be displayed interactively via the midPoint GUI, or their content can be exported using the reporting functionality.

There are the following built-in simulation reports.

Table 2. Built-in simulation reports
Report Description Typical use

Results

Lists simulation results without having a look at individual processed objects. Shows metadata and individual metrics.

overview, trends

Objects

Lists objects processed by a given simulation. One processed object corresponds to one report row.

high-level view of one simulation

Objects with Metrics

Lists objects processed by a given simulation along with metrics related to each object.

more detailed quantitative analysis of the simulation

Items Changed

Lists items changed within individual processed objects.

changes of items, suitable especially for single-valued ones

Values Changed

Lists values added or deleted within individual items in processed objects.

changes of items, suitable especially for multivalued ones with a larger number of values

Activities Supported

Simulations are currently supported by the following activities:

  • synchronization ones: import, reconciliation, live synchronization,

  • recomputation,

  • iterative and non-iterative scripting,

  • change execution.

When executing iterative or non-iterative scripting, make sure you use only model-level APIs to execute your actions. See Limitations below. Furthermore, avoid using notify, reencrypt, and resumeTask actions, as they are currently executed also in simulation mode. (See MID-8811, MID-8812, and MID-8813.)

For shadow management simulation, only synchronization activities (import, reconciliation, live synchronization) are supported.

Limitations

When implementing the simulation feature in midPoint 4.7, we chose the following architectural approach:

Simulated actions are executed using the same clockwork as persistent-effect ones. The main difference is present when computed operations are to be executed: While operations in persistent-effects mode are sent for real execution and audit, those in simulation mode are simply recorded without being executed.

There are some fundamental limitations stemming from this approach:

  1. Any operations invoked by the custom code that circumvent processing in the clockwork are really executed, even in simulation mode.

    These operations present a bad practice anyway and should be avoided regardless of whether simulation is used or not. Examples:

    1. direct actions invoked through internal midPoint APIs, like the repository, provisioning, case management, or notification APIs[1];

    2. direct manipulation of outside objects (files, sockets, and so on).

      If absolutely necessary, your code should check for the execution mode using task.getExecutionMode() and related methods and act accordingly.

      Note that calling methods like midpoint.addObject, midpoint.modifyObject, or midpoint.deleteObject is safe in this regard, as these methods invoke the standard clockwork processing. The majority of midpoint.* functions is safe, except for midpoint.executeAdHocProvisioningScript, midpoint.addRecomputeTrigger. When in doubt, inspect the method’s code.

  2. Create-on-demand scenarios are supported in a very limited way: The creation of missing assignment target objects is simulated but not remembered across boundaries represented by the processing of individual source items.

    For example, let us assume that there is an import from HR with a department object (referenced by an account attribute) that is created if it does not exist. If multiple accounts reference the same (non-existing) department object, its creation will be simulated multiple times.

    The reason is that the current implementation does not record the creation of the object in the repository, where it could be found while processing subsequent accounts.

  3. Provisioning-level operations are not captured.

    Some actions, like the application of pending operations in the provisioning module, are "under the radar" of the clockwork. Just like they are currently not audited, they are also not recorded in the simulation results.

  4. Shadows (or other objects) that do not enter clockwork processing are not captured.

    When simulating the execution of, e.g., an import task, the majority of shadows go through the clockwork and are hence correctly captured in the simulation result. However, the shadows that are not synchronized, for example, protected ones, are not mentioned in the simulation result. The exception is the (experimental) low-level shadow management simulation mode.

    This limitation includes any errors encountered before the clockwork is started (e.g., during shadow classification or correlation). Such errors and shadows are not visible in the simulation result. They are visible only in the task-level statistics, as for normal, non-simulation, tasks.

Alternative designs, for example, creating "simulated worlds" right in the repository, were seriously evaluated. They would provide better fidelity in simulations while keeping the simulated executions separate from the production ones and among themselves. However, we found no practical way of implementing these designs in the time available. Hence, the current implementation uses the approach described above, with its inherent limitations.

Other limitations, not principal but practical, are:

  1. Simulations in multi-node tasks are not supported yet.

  2. Handling of objects created on demand is limited slightly more than described above: Their creation is reported multiple times, even for a single item being processed. The delta visualization is not finished yet: midPoint shows OIDs instead of names. The assignments created with targets that are created on demand are not evaluated (because the targets do not really exist).

  3. Only selected activities are supported.

  4. Approvals are skipped in simulation mode: the execution commences as if no approvals were defined.

  5. Notifications are skipped in simulation mode: no notifications are sent (except where requested explicitly by the custom code).

Shadow Management Simulations

This is a special low-level simulation of shadow-management-related changes that are normally applied automatically. It has the following limitations:

  1. It is an experimental feature.

  2. There are often two simulation records for each processed shadow: one for classification and one for correlation.

  3. In this mode, higher-level processing (synchronization) is always skipped.

  4. Errors are not reported in this mode in the simulation result. They can be seen only in the respective task, just like they are visible in normal processing.

1. Avoid also using notify, reencrypt, and resumeTask actions, as they are currently executed also in simulation mode. See MID-8811, MID-8812, and MID-8813.

Compliance

This feature is related to the following compliance frameworks:

Was this page helpful?
YES NO
Thanks for your feedback