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.

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.5) 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.
  • Configuring a filter on an AD Identity attribute:
    • The filter is applied to users of the AD User SmartObject. For example when used in custom setups, such as using the AD User SmartObject as the data source for a Picker control, or when the AD User SmartObject is used as the default data source, such as the people picker in K2 for SharePoint.
    • If you enabled the filter and want to disable it at a later stage, change the IdentityAttributeFilterEnabled variable to false. Restart the K2 server to refresh the changes you made in the K2 database.
    • If you want your K2 Service Accounts to always be included in the filtered values, add them to the allowlist.
    • When enabling and configuring the filter and then running a full sync, existing users are not removed. The filter only applies to user records containing the attribute you used to configure the filter.