PingOne Advanced Identity Cloud

Manage advanced sync

On the Applications page, use the Provisioning tab to set up provisioning and configure Advanced Sync to create and manage mappings between an identity profile and a target application, between applications, or custom identity profiles.

In addition to mappings on the Mapping tab, the Advanced Sync tab lets you create as many mappings as you want between your current application/object type and another application or identity profile. The data can flow in either direction—​either to or from your current application and object type.

Swap the sync direction to change depending on if your current application is the source or target. The source and target determine if you’re sending or receiving data from:

  • Application to application

  • Application to identity profile (custom or default)

  • Identity profile (custom or default) to application

Configure advanced sync mappings

For each application, there are different object types and advanced sync is specific to each object type. For example, an application could have the Account and Group object type.

To create a new Advanced Sync mapping:

  1. In the Advanced Identity Cloud admin UI, go to Applications, select your application, then click the Provisioning tab and select an object type for a mapping.

  2. On the Advanced Sync tab, click + Sync Data.

    One half of the mapping is always the current application and the current object type, which can’t be changed.

  3. In the Add Sync Data modal:

    1. Set your source to Sync From an Application and the application Object type.

    2. Set your target to Sync To an Application and Object type, or to an Identity Profile.

      By default, you’re syncing from the current application and object type, and you choose to sync to an application and object type, or to an identity profile.

      If you created a custom identity profile through the IDM admin UI (native console), it’s available to select in the Identity Profile drop-down list. Learn more in Create and modify object types.
      To switch sync directions, click the arrow icon to reverse the sync source and target.

  4. Click Save to add the mapping.

Edit or delete an advanced sync mapping

To edit or delete an advanced sync mapping:

  1. On the Advanced Sync tab, click the ellipsis icon ( ) adjacent to the mapping to edit.

  2. Click Edit or click the row of the mapping to open the Mapping page where you Define the mapping rules and add properties, apply transformation scripts and conditional updates, and configure other advanced settings.

  3. Alternatively, click Delete to remove a mapping.

Define and preview mapping rules

To define mapping rules to reconcile the source with the target, add a property to the mapping:

  1. On the Mapping tab, click Add a property to open the Add a property modal, then select a target-property-name from the property drop-down list.

  2. From the next window of the property modal, select a source-property-name (optional) from the property list.

    It is optional to select a source-property-name if you’re defining a transformation script or adding a default value.

  3. (Optional) Select the Apply transformation script checkbox. Learn more about transformation scripts in Apply a transformation script to a mapping.

  4. (Optional) Click Show advanced settings and select:

    1. (Optional) Apply conditional update. Learn more about conditional updates in Apply a conditional update to the mapping.

    2. (Optional) Apply a default if value is null. Learn more about how to Apply a default value to a mapping.

  5. Click Save.

    If the mapping source is an identity profile, click the Preview button to view an example of how the mapping displays between the source and target. Learn more in Preview a mapping.

Understanding correlation

Correlate source objects and target objects in a mapping to ensure the attributes match between target and source. The goal of a correlation query is to find like objects, which could be users, groups, titles—​whatever the mapping is reconciling, and link them together. This correlation helps with future synchronization updates because the link is saved.

Typically, you choose several source and target objects to match. For example, if you have an account/user mapping, you could correlate the email address. Perhaps, the email field in the target is called Email and in the source, it’s called mail. In the correlation query, you’re directing Advanced Identity Cloud to look at the Email field it receives from the target and attempt to find a match for the mail field in the source. If the match is successful, Advanced Identity Cloud links those two accounts together.

Learn more in Correlate source objects with existing target objects.

Configure a correlation

To configure the correlation query in advanced sync:

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

  2. View or edit the default correlation query.

  3. Click Save.

Once you’ve saved a correlation, click Edit adjacent to Custom to open the modal and edit the query, if needed.

Reconciliation

In advanced sync, reconciliation uses the details you define on the Mapping tab to determine how to map and update properties between two systems.

Running reconciliation syncs any object type and identity profile changes between these systems. Learn more about Source reconciliation and Target reconciliation.

Run a manual reconciliation

When you perform a reconciliation, information is reconciled between the source object and the target object. This reconciliation creates an association between the two objects, which can be recorded in Advanced Identity Cloud by setting Persist Associations in the Advanced tab to true. Learn more in Reconciliation association details.

To avoid performance issues for large reconciliation jobs, set Persist Associations to false.

Run a manual reconciliation for an advanced sync mapping using these steps:

  1. In the Advanced Identity Cloud admin UI, go to Applications > Provisioning > Advanced Sync.

  2. On the Advanced Sync tab, click the ellipsis icon ( ) adjacent to the mapping to edit.

  3. Click Edit or click the row of the mapping to open the Mapping page, which opens additional advanced sync options.

  4. Select the Reconcile tab and click Reconcile Now to Reconcile your data between source-name and target-name.

Understanding reconciliation results

Advanced Identity Cloud uses the first three mapping rules that have a source and target object defined to display reconciliation results, for example:

  • source.userPrincipalName

  • source.mail

  • source.surname

The target object will always exist in the mapping rule, however, target data might not show in the reconciliation results table.
If there is no data in the first three rows of mapping rules, no data or Not found displays for the reconciliation results. Learn more in View a report about the last reconciliation.
If a mapping contains a transformation script and a target, but no source, the mapping rule will not be used to display reconciliation results for the source column.

Manage advanced sync schedules

On the Advanced Sync > Schedules tab, create a schedule to Periodically perform a full reconciliation by completing the following steps:

  1. Click the Full Reconciliation row to open the Schedule Full Reconciliation Job modal. Alternatively, click Set Up adjacent to the Inactive Status column to open the modal.

    The initial schedule state is inactive.

  2. In the Schedule Full Reconciliation Job modal, manually configure the Frequency and interval or Use cron.

    • To manually schedule a full reconciliation (default), complete the following steps:

      1. In the Frequency section:

        1. Enter a value for Run every X day(s). Alternatively, from the day(s) drop-down list, select:

          • hour(s)

          • days(s) (default)

          • week(s)

          • month(s)

        2. (Optional) Select the Set a Start Time checkbox and enter values for:

          • mm/dd/yyyy

          • --:-- -- (time in hours:minutes seconds)

          • Timezone (GMT + 0:00). Learn more in the Time zones chart.

        3. For Repeat, choose one of the following intervals:

          • X times

          • Until specific date

          • Indefinitely

      2. Click Save.

        If you specify a start date and an end date, the time zones must match to create a valid schedule.

    • To schedule a full reconciliation using cron:

      1. Enable the Use cron toggle.

      2. In the Frequency field, Enter a valid cron string.

        An Invalid Cron error displays if the cron string isn’t valid.

      3. Click Save.

Define advanced sync situation rules

Each advanced sync situation rule has an action. Advanced Identity Cloud performs the action when a rule triggers an action to be performed on a record. Advanced Identity Cloud evaluates each record. When an event meets a rule condition, Advanced Identity Cloud performs the action you’ve defined for that rule.

On the Advanced Sync > Situation Rules tab, a table displays the Situation and Action that Define rules for various sync situations.

Advanced sync situation rules

Situation Description

Ambiguous

Source object correlates to multiple target objects, without a link.

Source Missing

Valid target found, link found.

Missing

The source links to a missing target object.

Found Already Linked

Correlation from source points to a target object already linked to a different source.

Unqualified

Source object not qualified, but target objects found.

Unassigned

Valid target found, no link.

Link Only

Link found, target object not found.

Target Ignored

Does not pass validTarget script.

Source Ignored

Does not pass validSource script.

All Gone

Source object removed, link not found, correlation not possible.

Confirmed

Valid source and target objects linked.

Found

Correlation query from source points points to one target object.

Absent

Source object has no matching target.

Advanced sync rule action types

When a reconciliation determines the situation of a record, you must specify the action to be taken.

Async is the default action state.
Action Description

Async (default)

An asynchronous process has been started, so do not perform any action or generate any report

Create

Create and link a target object

Delete

Delete and unlink the target object

Unlink

Unlink the linked target object

Exception

Flag the link situation as an exception

Update

Link and update a target object

Ignore

Do not change the link or target object state

Report

Do not perform any action but report what would happen if the default action were performed

No Report

Do not perform any action or generate any report

Edit advanced sync situation rules

To edit the situation rules you’ve defined for advanced sync situations, complete the following steps:

  1. On the Situation Rules tab, click the Situation rule to edit. Alternatively, click the ellipsis icon ( ) adjacent to the Situation and Action, then click Edit.

  2. In the Situation Rule modal, in the When situation occurs drop-down list, select Perform Action (default) or Execute Script:

    • For Execute Script:

      • Enter your script in the commented code block:

        // Script has access to the following variables:
// source, target, sourceAction, linkQualifier, context, recon
// the recon.actionParam object contains information about the current recon operation.

  3. In the second drop-down list for When situation occurs, select an action as described in Advanced sync rule action types.

  4. For advanced settings, click Show advanced settings to display the following options:

    • Restrict situation lets you Specify query filters or add a script to restrict policy actions to a subset of records where situation is applicable.

    • Execute script on action complete lets you Set up a script to execute after your action is complete.

  5. Click Save.

Trigger advanced sync event hooks

Event hooks allow you to Trigger a script or a workflow when specified reconciliation events occur.

On the Event Hooks tab, you can view and define event hooks for reconciliation events.

Add an event hook

  1. On the Event Hooks tab, you can view a table of available event hooks by Name and Script.

    In the Script column, the default state is Not Configured.

    • The following event hook workflows include:

      • Create

      • Update

      • Delete

      • Link

      • Unlink

  2. To the right of an event hook, click + Add. Alternatively, click the row of an event hook to open the Add Event Hook modal.

  3. Edit the script for the event hook.

  4. Click Save or Save and Close.

Configure advanced reconciliation settings

In advanced sync, the Advanced tab includes settings to Filter and tune reconciliation to improve performance.

Name Definition

Filter Source

Restrict reconciliation to specific records by defining an explicit source query.

Filter Target

Restrict reconciliation to specific records by defining an explicit target query.

Valid Source Script

Filter the records that are included in reconciliation using a script.

Persist Associations

Record associations between source or target objects to allow UI to show results of last recon.

Valid Target Script

Filter the records that are included in reconciliation using a script.

Correlate empty target objects

Allow correlation of source objects to empty target objects.

Prefetch Links

Prefetch each link in the database before processing each source or target object.

Allow reconciliations from an Empty Source

Allow reconciliations from an empty source to delete all data in a target resource.

Threads Per Reconciliation

Tune performance by adjusting the number of concurrent threads dedicated to reconciliation.

To configure advanced reconciliation settings, use these steps:

  1. On the Advanced Sync > Advanced tab, configure the following optional settings:

    • (Optional) To restrict reconciliation to specific records in a source by defining an explicit source query:

      1. Enable Filter Source.

      2. Choose to filter the source if Any or All conditions are met.

      3. Use the remaining fields to define the explicit source query using all properties available in the source system.

    • (Optional) To restrict reconciliation to specific records in the target by defining an explicit target query:

      1. Enable Filter Target.

      2. Choose to filter the target if Any or All conditions are met.

      3. Use the remaining fields to define the explicit target query using all the properties available in the target.

    • (Optional) To filter the records that are included in reconciliation using a script:

      1. Enable Valid Source Script.

      2. Edit the script.

    • (Optional) To record associations between source or target objects to allow the UI to show results of the last reconciliation, set Persist Associations to true. Learn more in View a report about the last reconciliation.

      To avoid performance issues for large reconciliation jobs, set Persist Associations to false. Learn more in Reconciliation association details.

    • (Optional) To filter the target records that are included in reconciliation using a script:

      1. Enable Valid Target Script.

      2. Edit the script.

    • (Optional) To allow correlation of source objects to empty target objects, enable Correlate empty target objects.

    • (Optional) To prefetch each link in the database before processing each source or target object, enable Prefetch Links.

    • (Optional) To allow reconciliations from an empty source to delete all data in a target resource, enable Allow reconciliations from an Empty Source.

    • (Optional) To tune performance by adjusting the number of concurrent threads dedicated to reconciliation, in the Threads Per Reconciliation field, enter the number of concurrent threads.

      The default number of Threads Per Reconciliation is 10.

  2. Click Save.