Resource wizard: Object type correlation

Last modified 26 Feb 2026 14:39 +01:00
Since 4.9
This functionality is available since version 4.9.
Table of Contents

This describes how to set up correlation rules for a resource in midPoint using the GUI resource wizard.

Overview

Correlation in midPoint links resource object shadows to existing focal objects through a configurable matching mechanism. It determines how midPoint identifies the owner of a resource object, which is essential for maintaining correct and up-to-date associations between resources and focal objects.

In practice, correlation allows midPoint to automatically find the appropriate user for a given resource account based on account attributes and defined correlation rules.

Before configuring correlation rules for a resource, it is recommended to define inbound mapping. While not strictly required before starting configuring correlation, inbound mapping allows you to reuse mapped attributes as correlation items. More importantly, this step helps you identify which attributes are suitable for correlation—specifically those that are stable and sufficiently unique for reliable matching. If you have not yet configured inbound mapping for correlation, you will be able to do so when configuring correlation.

The defined correlation rules are later used by synchronization processes to actually link resource accounts to their corresponding focal objects.

Refer to Correlation for more details on the topic.

Create correlation rules

correlation rules setup accounts configure menu
Figure 1. Configuration menu in resource accounts list as an entry point to the correlation rules wizard

  1. In  Resources >  All Resources, select your resource.

  2. In  Accounts, click  Configure >  Correlation.

  3. You can:

    • Create correlation rules manually - Click Create new and continue with this guide.

    • Use an artificial intelligence (AI) assistant to help you create correlation rules - See Use AI to generate correlation rules and then return here to continue modifying the AI suggested rules if needed.

  4. Define the general settings of the correlation rule:

    • Rule name - A descriptive name of the rule. This needs to be unique in the context of the resource.

    • Description - An optional detailed description of the rule.

    • Enabled - Set to true to enable the correlation rule. Set to false if you want to disable the correlation rule. This is useful if you want to temporarily stop using the rule without deleting it. Undefined is the same as False.

    • Tier - Tiers determine the order of rule processing. If a higher-tier rule does not provide a confident-enough match, the next tier is processed. Lower numbers mean higher tiers.

    • Weight - Signifies the rule confidence. 1.0 means 100% confidence. The weight is multiplied by the accumulated confidence of individual correlators within the rule to get the final confidence value of the rule.
      See Rule Composition for details.

    • Ignore if matched by - You can block the rule from evaluation if the correlator within the rule is matched in another rule already. This is useful to avoid getting skewed confidence values if multiple rules use the same correlator (e.g., surname), as they would add up and reach confidence over 100%.
      See Rule Composition for details.

      correlation rule example
      Figure 2. Example of a correlation rule with an employee number correlator. The rule has a weight of 1.0, which means that if the correlator matches, the rule will yield a confidence of 100%.

  5. Add correlation items, also referred to as correlators, for the rule.

  6. Click Confirm.

  7. To check that your correlation configuration works as expected, you can run a simulation.

  8. Click  Save correlation settings to save the rules and exit the wizard.

    correlation rules list
    Figure 3. List of configured correlation rules. The tier 5 rule will run only if the higher-tier rule fails to yield a result. The lower-level rule will always result in a correlation case because its confidence is <1.0.

Set up correlation items (correlators)

For each correlation rule, you need to add at least one correlation item, or correlator. Correlation items specify the values of which attributes are to be compared when matching resource and focal objects. In practical terms, these are inbound mappings that are stable and sufficiently unique for reliable matching.

You can have multiple correlation items for one correlation rule. For each correlation item, you specify an attribute for which you have an inbound mapping from the resource you are correlating.

For instance, if you have an HR system with employee numbers and an LDAP system that uses the same employee numbers, you may inbound-map the employee numbers to empnum in both resources and use the empnum attribute for correlation.

You can use correlation-only inbound mappings for target resources, where you normally do not use inbound mappings.

To add correlation items to correlation rules:

  1. Open the list of correlation rules in your resource via  Accounts >  Configure >  Correlation.

  2. In the list of correlation rules, click  Edit rule on a correlation rule for which you want to configure the correlation items.

  3. Add a correlation item by clicking:

    • Add existing if you have already defined an inbound mapping for the attribute you want to use for correlation.

      1. Select an attributes from the list of available attributes for correlation.

      2. Click Add mappings to add the mapping and to return to the correlation rule.

        correlation add existing mapping
        Figure 4. Add existing correlation item based on an already defined inbound mapping. This allows you to reuse the mapped attribute as a correlator.

    • Click Create new if you want to create a new correlator from an attribute for which you have not yet defined an inbound mapping.

      1. Configure the inbound mapping.

        Select Correlation in the Use for option if you are working with a resource that does not otherwise require inbound mappings, such as a target resource in a reconciliation scenario.

      2. Click Create mapping.

        correlation add new mapping
        Figure 5. Create a new correlation item. This allows you to create a correlator from an attribute for which you have not defined an inbound mapping yet.

  4. Configure the correlation item:

    1. Item - Selects an item to correlate. It refers to a midPoint property for which an inbound mapping exists. This will be used for correlation. For example, if you have an inbound mapping from AD’s sAMAccountName attribute to midPoint user’s name property, you would select name here.

    2. Resource attribute - Selects the attribute on the resource side that will be compared to the selected midPoint property.

    3. Search method:

      • Exact match: Values need to match exactly for the objects to correlate (get linked, in other words).

      • Levenshtein distance: Method of approximate matching with a threshold of the maximum permitted number of single-character edits. Refer to Levenshtein distance on Wikipedia for more details about the method.

      • Trigram similarity: Method of approximate matching using the ratio of common trigrams to all trigrams in compared strings. + For the fuzzy-search methods, define the Match threshold and whether the threshold value is Inclusive (in the mathematical sense).

    4. Optionally, click Edit mapping to define detailed settings for the correlation item.

  5. Click  Confirm to save the correlators.

correlation rules multiple correlator
Figure 6. List of correlators for one correlation rule. In this configuration, all three values must match exactly for the rule to gain the maximum confidence.

Use AI to generate correlation rules

To boost productivity and to configure correlation faster and more efficiently, use the midPoint’s AI assistant to generate correlation rules based on the actual data in your resource. This greatly simplifies the process of setting up correlation, especially for large and complex resources, by providing intelligent suggestions for correlation rules that are tailored to your specific resource data.

correlation use ai
Figure 7. Use AI to generate correlation rules based on the actual data in your resource.

  1. Make sure you toggle the Suggestions enabled on to enable the AI assistant. If you have not yet configured any correlation rules, this toggle will not be visible, and you can continue to the next step.

  2. Click the Generate suggestions button to generate correlation rule suggestions based on the actual data in your resource. The AI assistant will prompt you to select the data you want to analyze, such as your schema. To ensure maximum security, no authentication credentials or passwords are shared in the process.

  3. Inspect the generated suggestions. You can do so directly in the list of suggestions, or you can click View rule to see the details of the suggested correlation rules and their correlators.

  4. Take action on the generated suggestions:

    • Accept them so that you can open them for editing. If the new rule does not have any inbound mappings, i.e., correlation items, configured, you will be prompted to Accept and add them. By accepting at this point, you are only accepting the correlation rule suggestion, and you still remain in control as you will be able to review and modify the suggested rule and correlators before saving and deploying them.

    • Discard the suggestions if you do not want to use them at all.

      If you have discarded some suggestions by mistake, or have made changes you are not happy with, you can always remove the correlation rules and click Re-generate to get new suggestions.

    correlations regenerate
    Figure 8. Re-generate correlation rules suggestions if you are not happy with the current ones. This will not affect any of the rules you have already accepted.

  5. For the suggestions you have accepted, click Edit rule and continue modifying them as you would when creating new correlation rules manually.

Simulate correlation

After you set up your correlation rules, you can run a simulation to check how they work with the actual data in your resource.

correlation simulation
Figure 9. Run a correlation simulation

In your correlation rules list, at the bottom of the page:

  1. Click Simulate.

  2. Select the environment you want to run the simulation in, and click Next.

  3. Define the simulation parameters:

    • Sample size - How many resource objects to include in the simulation. The higher the number, the longer the simulation will take.

    • Query - You can target specific objects in the resource by defining a query. For example, you can target only accounts with a specific value in an attribute, or accounts created within a specific time range.

  4. Click Run simulation.

  5. Wait for the simulation to finish, and check the results. You can see how many resource objects were matched by each correlation rule, and which focal objects they were matched to.

    You can always review the simulation results in your correlation rules by clicking the dropdown menu for Simulate.

Troubleshooting

Generate suggestions button not visible

If the AI assistant is not available, make sure you toggle the Suggestions enabled on to enable the AI assistant.

correlations regenerate
Figure 10. Enable the AI assistant.

AI assistant not generating suggestions

If you experience issues with AI not generating suggestions:

  • Check that your resource is connected by going to Resources > All Resources > resource, and clicking Test connection.

  • Check that shadow caching is enabled on your resource.

  • Make sure object types are configured correctly on your resource.

Limitations

Resource wizard has several limitations, such as:

MidPoint resource wizard can’t show or edit these features but tolerates them and keeps them untouched if you configure them in XML.

See also

Here are additional resources to explore:

Was this page helpful?
YES NO
Thanks for your feedback