Incremental synchronization

When you're configuring synchronization, you can see that there are two types of synchronization available in OpenIAM. These are 'complete' and 'incremental' synchronization. Complete synchronization means that when synchronizing all the data under the query will be returned from the source to OpenIAM.

Incremental synchronization is used when there is a need to return data, changed from the time of the last synchronization run. Generally, it would find and return only recently changed entries.

Configuring incremental synchronization

The configuration happens in the same window as regular synchronization configuration. Hence, to start configuring

  1. Go to webconsole > Provisioning > Synchronization.
  2. Fill in the fields as for the complete synchronization, as noted in this document, except in Synchronization type field choose Incremental.
  3. Upon selecting Incremental synchronization type, you will see that a field has emerged, as shown below.

Last updated field

To run incremental synchronization successfully, you need to make sure that the object to synchronize (user, group, role, etc,) in the target system has the field indicating the date and time this object was last updated. In Active Directory, for instance, this field is the 'WhenChanged' field. This is required for OpenIAM to be able to find recently changed objects.

Hence, when configuring incremental synchronization, you need to specify this field in Last Updated field as shown below for AD target system.

Last updated field filled

  1. Specify the query for objects to be returned to OpenIAM. Mark that query should also contain a 'WhenChanged' field followed by 'ge' (greater) and a question mark (see example below). A question mark is used to return a date from Last Record Processed field. The date format shown below is for PowerShell. This can be any applicable format from the Java SimpleDateFormat library.


Last record processed is the date and time of the newest processed object for the previous synchronization run, it is a point of reference for the new incremental synchronization. Hence, in the query this date means that the synchronization will return the object with modified value greater than that of the newest object in the previous run.

Note that Last Execution time is a time of last synchronization run and doesn't necessarily correlate with the _Last Record Processed'.

Incremental synchronization can be configured not only with the AD PowerShell connector, as other connectors also support such type of synchronization. Moreover, this can also be done via CSV file. The only thing to make sure is that your CSV file has the columns with the date the object was last modified.

In the rest of the characteristics, incremental synchronization is not different from the complete one. It can also be run using a cron expression, or manually. Cron expression is recommended here to create a particular schedule for OpenIAM to get changed objects regularly.

The synchronization scripts are also the same as for the complete synchronization.

It is also worth noting that initially it is required to perform the complete synchronization to get the point of reference and have a value in Last Record Precessed field. Hence, if you're planning on running incremental synchronization on a regular basis after running the complete one, make sure to include WhenChanged field (or equivalent for your target system) into the list of returned attributes by OpenIAM. Note also, that Last Record Precessed value is saved in OpenIAM's time zone. Hence, it may not coincide with the target system time zone.

In case the complete synchronization was performed a while ago and you don't need all the changes for this period, there is an option of running incremental synchronization for one user that was recently changed. In this case the Last Record Processed value will the value of this recent user changed and OpenIAM gets the reference point for ruther synchronizations not as distant as it was before. Otherwise, if the Last Record Processed is null, you will get the complete synchronization

Again, as for complete synchronization, the results for incremental one can be viewed in Log Viewer. Go to webconsole > Administration > Log Viewer. Search for SYCNCHRONIZATION event. Opening the log you can see what values are returned and all the info about synchronization.