PingOne Advanced Identity Cloud

Configure advanced sync correlation

Correlation rules determine how Advanced Identity Cloud matches source objects to existing target objects during reconciliation, so that updates are applied to the correct records and duplicates are avoided. In an advanced sync mapping, you configure a correlation query that looks up potential target matches based on one or more fields.

A well-designed correlation query typically uses a single, unique, and preferably immutable identifier. It directly influences the situation that is evaluated for each record, for example, Found, Ambiguous, or Absent.

Learn more in Correlate source objects with existing target objects.

Configure a correlation query

To configure a correlation query for a mapping:

  1. In the Advanced Identity Cloud admin console, open the Advanced Sync editor.

  2. In the Advanced Sync editor, open the mapping you want to configure.

  3. On the Correlation Query tab, click Configure to open the Edit Correlation modal.

  4. Add your correlation query following the suggestions in Best practices for designing reliable correlation queries. You can use the commented out example query as a starting point.

  5. Click Save.

    The correlation query is saved with the name Custom.

After you’ve saved a correlation query, click the Ellipsis icon () and select Edit to edit the query, if needed.

Best practices for designing reliable correlation queries

When matching source and target objects, identify a single, unique, and ideally immutable identifier. Although usernames or emails are common, they can change over time.

  • Prioritize immutable IDs: Whenever possible, use immutable identifiers that are less likely to change, such as employee IDs or UUIDs. These provide a stable reference for correlation.

  • Case sensitivity: Make sure that both sides of your query use a consistent case format. For example, if your source mail is mixed case but your target email is always lowercase, normalize case before comparing. You can use a transformation script to convert both values to lowercase before correlation.

  • Validate for uniqueness: A correlation query should ideally return exactly one result. If a query returns multiple matches, for example, two users with the same email, Advanced Identity Cloud identified this as an Ambiguous situation. Make sure your target system enforces uniqueness on the correlation field (for example, with a unique index) to prevent this.

  • Handle orphaned data carefully: If a match isn’t found, the system might create a new record depending on your situation rules. For sensitive targets, start with Report or No Report actions so you can audit the results before enabling automatic Link or Create actions.

  • Optimize performance: Correlation queries run for every record during reconciliation, so they should be as efficient as possible. Make sure to index the fields used in the correlation query on the target system, and avoid complex transformations or functions that could slow down the query.

Example: Correlate by email

When correlating accounts, you typically select a unique property to match, such as a username or an email address. For example, in an account-to-user mapping, you can use the email address as the matching criteria. If the target system stores this in a field named mail while the source system uses Email, you would configure a correlation query to check the target’s mail field for a value that matches the source’s Email field. Advanced Identity Cloud then performs the specific action defined in your situation rules based on whether a match is found.

For example, a scripted correlation query might look like this:

var qry = {'_queryFilter': 'mail eq "' + source.Email + '"'}; qry

All situation rules have the Async action by default. A common action for a successful 1:1 match is to link the matched source and target, which means to set the Found situation rule with the Link action. Learn more in Advanced sync situation rules and in Advanced sync rule action types.