Sync Service

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.

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

   1
   2
   3
   4
   5
   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

   1
   2
   3
   4
   5
   6
   7
   8
   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.

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 Management.
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.

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

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

To remove the domain from the Sync Service:

1. Browse to 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.

You can use an identity attribute to filter users in the product. The filter acts as middleware to filter identities in the product for a specific attribute set for that user in AD. For example if you have an organization with lots of users and you want to filter those users according to their divisions, you can use the Division attribute in AD to do this. By specifying a value for the attribute per user, you can filter users that belong to a specific division such as Operations. Note when doing this users belonging to other divisions or where the division is not set will not have access to product components. You can add admin users to an allowlist to ensure they are not restricted from accessing product components, regardless of which filters are set. The filter is applied to users of the AD User SmartObject. It does not apply to the AD Group or AD Organizational Unit SmartObjects.

Configure the filter

Follow the steps below to configure a filter on an Active Directory Identity Attribute:

1. Open the Properties of a user in Active Directory Users and Computers and go to the Attribute Editor tab. Set the value of the attribute you want to use in your filter. The example below uses the Operations value for the Division attribute.
   
2. Run the following script against the K2 database to insert the filter attribute into the [SyncEngine].[ProviderObjectPropertry] table:
   Copy

   Insert filter attribute

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   DECLARE @ProviderFilteProp NVARCHAR(200);
   
                                               SET @ProviderFilteProp = 'Filter Value';
   
                                               IF NOT EXISTS (SELECT * FROM [SyncEngine].[ProviderObjectProperty] WHERE [Name] = @ProviderFilteProp)
                                               BEGIN
                                               INSERT INTO [SyncEngine].[ProviderObjectProperty]
                                               ([ProviderObjectID], [Name], [IsCore], [ComputedProperty], [ProviderObjectPropertyTypeID])
                                               VALUES
                                               (4, @ProviderFilteProp, 0, 0, 17),
                                               (5, @ProviderFilteProp, 0, 0, 17)
                                               END
                                               ELSE
                                               BEGIN
                                               PRINT 'Records already Exists'
                                               END;
   
                                               SELECT *
                                   FROM [SyncEngine].[ProviderObjectProperty]

   Replace [Filter Value] with the name of the attribute you want to use for the filter such as Division.
3. Restart the server to refresh the changes you made in the K2 database.
4. Run a sync for the provider to perform a full sync. This is required to update the data in the [Identity].[CacheConfiguration] table in the K2 database.
5. Run the following script against the K2 database to set up the AD Sync filter to be used in the product:
   Copy

   Set up AD sync filter

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   /*Set IdentityAttributeFilterType for which attribute to filter on*/
                                               /*Set IdentityAttributeFilterValue for the value that needs to be used in the filter*/
                                               DECLARE @IdentityAttributeFilterEnabled AS NVARCHAR(100);
                                               DECLARE @IdentityAttributeFilterOperator AS NVARCHAR(150);
                                               DECLARE @IdentityAttributeFilterIncludeNonSet AS NVARCHAR(100);
                                               DECLARE @IdentityAttributeFilterType AS NVARCHAR(250);
                                               DECLARE @IdentityAttributeFilterValue AS NVARCHAR(250);
   
                                               SET @IdentityAttributeFilterEnabled = 'false'
                                               SET @IdentityAttributeFilterOperator = 'Equals'
                                               SET @IdentityAttributeFilterIncludeNonSet = 'false'
                                               SET @IdentityAttributeFilterType = 'Filter Type';
                                               SET @IdentityAttributeFilterValue = 'Filter Value';
   
                                               DECLARE @IdentityAttributeFilter TABLE
                                               (
                                               [Name] nvarchar(128) NULL,
                                               [Value] nvarchar(max) NULL
                                               );
   
                                               INSERT INTO @IdentityAttributeFilter
                                               VALUES
                                               ('IdentityAttributeFilterEnabled', @IdentityAttributeFilterEnabled),
                                               ('resultFilter','SourceCode.Hosting.Runtime.IdentityService.Filters.IdentityAttributeFilter'),
                                               ('IdentityAttributeFilterOperator', @IdentityAttributeFilterOperator),
                                               ('IdentityAttributeFilterIncludeNonSet', @IdentityAttributeFilterIncludeNonSet),
                                               ('IdentityAttributeFilterType', @IdentityAttributeFilterType),
                                               ('IdentityAttributeFilterValue', @IdentityAttributeFilterValue)
   
                                               MERGE [Identity].[CacheConfiguration] AS TARGET
                                               USING @IdentityAttributeFilter AS SOURCE
                                               ON (TARGET.[Name] = SOURCE.[Name])
                                               WHEN MATCHED AND TARGET.[Value] <> SOURCE.[Value] THEN
                                               UPDATE SET TARGET.[Value] = SOURCE.[Value]
                                               WHEN NOT MATCHED THEN
                                               INSERT ([Name], [Value])
                                               VALUES (SOURCE.[Name], SOURCE.[Value]);
   
                                               SELECT *
                                       FROM [Identity].[CacheConfiguration]

   Update the following variables:
   • @IdentityAttributeFilterEnabled = 'false'
     Replace [false] with true to enable the filter.
   • @IdentityAttributeFilterType = 'Filter Type'
     Replace [Filter Type] with the attribute name you want to use for the filter. This must match the attribute name you used in step 2, for example Division.
   • @IdentityAttributeFilterValue = 'Filter Value'
     Replace [Filter Value] with the value you want to use for the specific attribute, for example Operations where Division = ‘Operations’. The value must match the value you used in step 1.
   • @IdentityAttributeFilterOperator = 'Filter Operator'
     Replace [Filter Operator] with the operator you want to use for the filter. The only operators available are Equals or NotEquals, where Equals: Determines if two values are equal, and NotEquals: Determines if two values are not equal.
   • @IdentityAttributeFilterIncludeNonSet = 'false'
     Includes or excludes empty values in the filter, where True=Enabled and False=Disabled
   
   The [Identity].[CacheConfiguration] table in the K2 database is updated as follows. Your environment may be different.
   
6. Restart the K2 server to refresh the changes you made in the K2 database.

Configure allowlist entries

Add admin users to the allowlist in the K2HostServer.exe.config file to ensure they always have access to Nintex K2 components, regardless of which filters are set. Add multiple users using a semicolon-separated list.

You can find the config file in the following location: "%ProgramFiles%\K2\Host Server\K2HostServer.exe.config"
Add the following entry to the "appSettings" section of the file for each admin user:

Copy

Add user to allowlist

1
2
3
4
<appSettings>
                                    <add key="AdminIdentities" value="User FQNs” />
                                    </appSettings>
                            

For example:

Copy

Add user to allowlist

1
2
3
4
<appSettings>
                                    <add key="AdminIdentities" value="K2:NintexTEST\TestUser” />
                                    </appSettings>
                        

You can add these entries according to your business requirements. Restart the K2 server to apply the changes.