Sync Service

The sync service synchronizes identities from your Identity Provider (IdP), such as Active Directory and Azure Active Directory, to K2. Use the service's SmartObjects as shown in this article to perform your initial sync, to schedule ongoing syncs, and to see sync history.

Do not edit or create a new sync service instance. The sync service is a K2 system service and editing the instance or creating a new instance may cause errors on your K2 server.

Prerequisites

You need to install the sync service to enable this service type. For more information on installing and configuring the service, please see KB002707: Identity Synchronization and Caching.

Using the SmartObjects to perform the initial and ongoing syncs

You must perform the following steps to run the initial full identity sync after you enable the sync service and to schedule ongoing syncs:

  1. Get a list of providers in your environment.
  2. Run the initial sync for all providers in your environment. Confirm the status of the initial sync.
  3. Configure scheduled syncs for each provider.
  4. Confirm the status of scheduled syncs regularly .

Use K2 Management to find the Sync Service SmartObjects in the System category.

See the Sync Service SmartObject reference topic for detailed information about the properties and methods of these SmartObjects.

To start a full sync and configure scheduled syncs, you need the following details:

  • Provider Name: this matches the security label configured in your K2 environment. The K2 Five installation creates identity sync providers for each K2 security label in your environment. Common ones include K2, AAD, K2SQL, and SP. For more information about the values to configure sync providers for different types of IdPs, see KB002707: Identity Synchronization and Caching
  • Provider Instance Name: this is the name of the provider instance and is the domain section of a fully qualified domain name. Use your domain name if you have Active Directory. The AAD provider does not have a Provider Instance Name so leave it blank. SharePoint requires a Provider Instance Name which you can find by executing the List Provider Instances method of the Provider Instance SmartObject.

For example, if a sync provider instance is created for an Active Directory sync on a standalone Denallix server, the Provider Name is K2 and the Provider Instance Name is Denallix (the domain name).

  • To get a list of Provider Names, execute the List Providers method of the Provider SmartObject.
  • To get a list of Provider Instance Names, execute the List Provider Instances method of the Provider Instances SmartObject.

Use the methods of the Provider SmartObject to list existing providers and to see associated information.

Execute the List Providers method to see provider names, types, and if they are enabled.

An example results page.

You use the Provider Name to start a sync and schedule ongoing syncs. Note that the Provider ID in the results for the List Providers method is also shown in the results of the List Provider Instances method shown below.

Use the methods of the Provider Instance SmartObject to list existing provider instances and see associated information about them.

Execute the List Provider Instances method to see provider instance names and additional information. Use the provider instance name to start a full sync and to scheduled ongoing sync, which you do in the next section.

Use the methods of the Operation SmartObject to start a full sync, configure a sync schedule, and get information about existing schedules.

To manually start a full sync:

  • Execute the Start Sync method.
  • Enter the Provider Name (required) as text, for example, K2 for AD.
  • Enter the Provider Instance Name as text. For example, your AD domain name Denallix. The AAD provider does not have a Provider Instance Name and remains blank. SharePoint requires a Provider Instance Name which you can find by executing the SmartObject methods as shown above.
  • Enter a value of Yes or No in the Skip Deleted box to include or exclude identities marked as deleted. The value defaults to No if you leave it blank. K2 recommends setting this to Yes for new installations, and No to upgraded environments.
  • Click Execute to start the sync, and Done on the Results screen.

To set an ongoing sync schedule:

  • Execute the Set Provider Schedule method
  • Enter the Provider Name (required) as text, for example, K2 for AD.
  • Enter the Provider Instance Name as text, for example, your AD domain name Denallix.
  • Enter the Schedule time in the format DD:HH:MM:SS, for example, 00:07:00:00 (sync occurs every seven hours after the previous sync ended)
  • Click Execute to set the sync schedule, and Done on the results screen.

To get a list of existing schedules:

  • Execute the Get Provider Schedule method.
  • Enter the Provider Name (required) as text, for example, K2 for AD.
  • Enter the Provider Instance Name as text, for example, your AD domain name Denallix.
  • Click Execute. The Results screen shows you the sync schedule for the provider you chose.

Use the methods of the Run History SmartObject to see run histories by either date range or status.

To get a run history by date range:

  • Execute the Get Run History Entries By Date Range method.
  • Enter the Provider Name (required) as text, for example, K2 for AD.
  • Enter the Provider Instance Name as text, for example, your AD domain name Denallix.
  • Enter the Sync Start date/time in the format MM/DD/YYYY HH:MM, for example, 09/13/2018 10:00AM
  • Enter the Sync End date/time in the format MM/DD/YYYY HH:MM, for example, 09/14/2018 09:59AM

Executing the SmartObject gives you a list of previous sync runs in the date range along with some counts as shown in this image:

The first row shows the full sync of 168 identities in the IdP, while subsequent syncs only sync changes, two of which occurred on the tenth run.

To get a run history by status:

  • Execute the Get Run History Entries By Status method.
  • Enter the Provider Name (required) as text, for example, K2 for AD.
  • Enter the Provider Instance Name (optional) in text, for example your AD domain name.
  • Enter a Run Status which can be Synchronizing, Completed, or Failed.

Once you are using the Sync Service, you can add an Active Directory (AD) domain, if needed, as documented in the topic Domains.

The steps are summarized here:

  1. Browse to the K2 Management site.
  2. Expand Users > K2 > Domains.
  3. Click Add and fill in the required information.

Adding the domain like this automatically also adds the domain in the relevant tables for the Sync Service.

There are additional steps needed to remove a domain from the Sync Service than just removing a domain from K2 Management.

To remove a domain from the Sync Service follow these steps:

  1. Browse to the K2 Management site.
  2. Expand Users > K2 > Domains.
  3. Click Remove for the selected domain. This will remove the domain from the K2 Management.

To remove the domain from the Sync Service:

  1. Browse to K2 Management > Categories > System > Sync Service.
  2. Open the Provider Instance SmartObject and run the Delete Provider Instance method.
  3. Enter the Provider Name (required) as text, for example, K2 for AD.
  4. For the Provider Instance Name enter the domain name that was deleted earlier.
  5. Execute the SmartObject method and it will remove the values for the deleted domain in the Sync Service.

Considerations

  • Hybrid SharePoint environments cannot use the sync service. If you use SharePoint in a hybrid environment, in other words using both SharePoint online and on-premises, the sync service only syncs the most recently registered SharePoint. So, if you first registered SharePoint on-premises and then later registered SharePoint Online, only SharePoint Online will be synced.
  • When you enable the sync service, automatic syncing is enabled for SharePoint groups, but you must still configure a sync schedule for the SP provider. Note that if you try to sync groups in SharePoint by clicking the Sync Groups link on the K2 for SharePoint app settings page, you see the following message "Automatic Synchronization is turned on in this environment":
  • When syncing with AD FS, only the first 1000 records (identities or groups) are returned by default. To sync all AD FS identities, change your configuration as described in KB002721 - How To Configure ADFS To Return More Than The Default 1000 Records.
  • Groups in AAD with the same name are cached as a combined single group in K2. See the KB003504 article for more information.
  • If you upgrade to K2 Five (5.4) and are using the Identity Sync Service, you may notice error messages logged to the Host Server log file relating to SharePoint. This is especially true if you sync an ADFS provider. For more information see the KB article KB003569 Code Fix: After upgrading to K2 Five (5.4), errors are logged in the Host Server log file related to SharePoint.

To re-execute a full sync

If you want to run a full sync instead of a differential sync at some point after the initial sync, you first need to clear the SyncState and LastSyncDateOffset column values stored in the Provider Instance table in the K2 database. Follow these steps:

  1. Find the instance ID by running this query:
    Copy

    Find instance ID

    SELECT 
      * 
    FROM 
      [SyncEngine].[ProviderInstance]

    This image is an example of what is returned. Your environment might be different.
  2. Use this query to clear the values for the SyncState and LastSyncDateOffset columns for the Provider Instance ID you need:
    Copy

    Clear the values

    UPDATE 
      [SyncEngine].[ProviderInstance] 
    SET 
      [SyncState] = NULL, 
      [LastSyncDateOffset] = NULL 
    WHERE 
      ID = [Provider Instance]
    Replace [Provider Instance] with the ID for the Provider Instance on which you want to run the full sync. For example, ID 2 from the example image above. Remember that the ProviderID value corresponds to the ID value in the [SyncEngine].[Provider] table.
  3. Run a sync for the provider to perform a full sync. The full sync generates new values for the SyncState and LastSyncDateOffset columns. From this point forward differential syncs are run if the IdP supports it as in the case of AD, AAD, and SharePoint.