Overview

AdaptiveWork Active Directory Sync Agent is a User Provisioning tool that automates the synchronization of your network’s selected Windows Server Active Directory groups and users into your AdaptiveWork organization.

This package is designed for "on premise" Active Directory systems and has not been designed or tested to work with “Azure AD” user provisioning services which uses a SCIM (Simple Cloud Identity Management) standard.

However, once users have been provisioned (added to AdaptiveWork), you can set up to authenticate (SSO) using Azure Active Directory as an Identity Provider.

For more about SSO (Federated Authentication) setup and configuration, use one of the following links:

Note: Whilst you do not need Active Directory Administrator privileges to run the Sync Agent, it is recommended to be accompanied by an Active Directory Administrator as some Active Directory fields have short names, which may not be recognizable to you should you want to add them to your sync mapping.

Installation

Download the .msi file from the AdaptiveWork Apps Marketplace
Run the .msi installer file to install the AdaptiveWork Active Directory Sync Agent, which is comprised of 2 main elements:
1. AdaptiveWorkADSyncSettings - Run this first to set up connections to Active Directory and AdaptiveWork for Groups and field mappings
2. ActiveDirectorySyncEngine- This is the engine that runs the sync and can be scheduled to run on an ongoing basis using Windows Task Scheduler
3. Once you have installed the initial .msi package, navigate to
  Program Files (x86) > AdaptiveWork > ActiveDirectorySync
  and run AdaptiveWorkADSyncSettings to finish the installation process.
You can schedule the Sync using Window Task Manager (detailed later in this article).
If you wish to do so, you should install the .msi package as the same user that you plan to run the scheduled sync with.
For advanced configuration details, please contact your AdaptiveWork Customer Success Manager.

Migrating Users from Active Directory Sync v1

If you have not previously set up AdaptiveWork Active Directory User Sync, you may skip this section.

V2 introduces a number of key improvements including:

Simpler Install
Support for AD Forest (multiple AD domains)
Simpler User Interface
Sync of Direct Manager
Support User Re-Provisioning
Improved Performance & Scalability
Improved Stability
Improved Logging

If you are using v1 and are satisfied, there is no need to migrate immediately or change your processes and it will continue to sync. However, no further updates are planned for the v1 version.

Simpler Install

Previously the Active Directory sync relied on custom fields to work:

SSOKey, SSONotes, SSOUpdated.

v2 uses standard fields so no additional installations are required.

Item Type	^OldCustom Field	^NewStandard Field
User, User Group	SSOKey --------------->	User Sync ID
User, User Group	SSOUpdated --------------->	User Sync Updated
User, User Group	SSONotes --------------->	User Sync Notes
Organization	SSO last update date --------------->	User Sync Updated

You can migrate to the new app by installing a migration utility app that copies over the SSOKey to User Sync ID field if:

You are currently using the v1 AD User Sync app,
and
you are using SID as the primary user key between AD and AdaptiveWork,

This is all that is needed to ensure the new sync does not create duplicate users and groups.

Note: If you have not been using SID as the primary user key, please discuss with your Customer Success Manager to explore your migration options.

Using the Migration App

To migrate SID from SSOKey to User Sync ID fields, install the Migration app and run it before running your sync

Download the Migration App and activate it.
2 new Custom Actions will now be available:

People module: AD Sync v2 Migration Tool - Users
User Groups module: AD Sync v2 Migration Tool - Groups

Select the Users you currently sync by filtering on the SSOKey field.
Use the Custom Action to copy the field values for the users you want to continue to sync. It can be used on up to 50 users / groups at a time. If you have thousands of affected users, consider saving the Custom Action as a Scheduled Workflow Rule and run it before running the AdaptiveWork Active Directory Sync Agent.
Run AdaptiveWork Active Directory Sync Agent on your Windows machine.
Once you have verified results, you can delete the custom (“SSO”) fields from AdaptiveWork.
Remove any scheduled sync tasks of the old app from your Windows machine.

"Marooned" Deprovisioned Users

v2 adds the capability to disable users in AdaptiveWork.

If a user has a User Sync ID in AdaptiveWork and is not found in a sync Group in Active Directory, they will be disabled (State: "Suspended") and their license released.

If you have users that were previously synced by v1 and should now be disabled in AdaptiveWork you can either:

take care to also use the Migration Tool to copy their SSO ID to User Sync ID field.
Once this this is done, the Sync Process will correctly identify them to disable and will release any licenses still assigned to them.
Manually disable/ suspend the users in AdaptiveWork

If you do not take either of these steps, these users will be left untouched by the sync process in AdaptiveWork and will not be deprovisioned.

Setting Up Connections to AdaptiveWork and Active Directory

Connection to AdaptiveWork

User Management in AdaptiveWork is performed by users with Administrator permissions. You will connect to AdaptiveWork using your Administrator username and password.

You can only set 1 AdaptiveWork connection, and it is recommended to first use a Sandbox connection to verify that the sync works as expected with all the relevant groups, users and field values.

Sandbox

Choose the Sandbox option in Account Credentials > AdaptiveWork connection. Add your username and password, and check the connection.

Production

Choose the Production option in Account Credentials > AdaptiveWork connection. Add your username and password, and check the connection.

Selecting Sandbox or Production account to connect

Selecting up all Account Credentials

Connection to Active Directory

AdaptiveWork Active Directory User Sync connects directly to multiple Active Directory domains and does not connect to or use a Global Catalog.

Add one or more Microsoft Active Directory servers (domains).

Click Account.
Enter your AdaptiveWork Username and Password. Click Check to validate the connection.
Enter your Active Directory Domain, Username and Password. Click Check to validate the connection.
If you want to add additional domains, click + Add Domain and enter your Active Directory credentials.
Click Save.

Setting up Field Mappings

Add, remove and update Active Directory-to-AdaptiveWork field mappings.

Click Field Mapping.

The following default field mappings appear in the list.

User
Active Directory	AdaptiveWork
givenName	FirstName
sn	LastName
title	JobTitle
manager	DirectManager
telephoneNumber	OfficePhone
mobile	MobilePhone
displayName	DisplayName
Groups
Active Directory	AdaptiveWork
name	name
displayName	DisplayName

To edit a field, select the Users or Groups tab. Open the relevant drop-down list to select a field value for Active Directory and Clarzen.
To add a new field, click + Add Fields. Open the drop-down lists to select field values.
To remove a field mapping, click the bin icon next to the mapping.

Click Save.

Adding Additional Groups

Select which groups to sync and add groups.

Click + Add Group
Select the domain your groups are in.
Select the groups that you want to sync. Use the search field to find a group(s).
Group Search and Selection
Click UPDATE SYNC LIST and your selected Groups will be added to the sync set.
Click [x] to close the Add Groups window.
Click on a Group to verify its users.
Viewing a Group Users

Verifying Additional Settings

Click Settings to change the default sync settings.

Settings screen

The settings:

New User Invite Policy - Send standard AdaptiveWork invitation to notify new users that they have access, or manually send at a later time
Direct Manager Sync - When a synced user's Direct Manager is not already synced to AdaptiveWork as part of a synced Group
Ungrouped User De-Provisioning - When a synced user is no longer a Member of a sync Group Admins will always be notified
Disable User Policy - When a synced user is Disabled in Active Directory
Deleted User Policy - When a synced user is no longer found in Active Directory

Selecting a Group to Test

Before running a major initial sync, it’s worth creating a small Group to sync to AdaptiveWork with a test user to verify that the fields are mapped correctly.

Organizational Units

Active Directory Groups can be labelled as Organizational Units (OUs) to model organization hierarchy and simplify policy management. Whilst this field value (TRUE/ FALSE) can be synced over from AD Groups to the Organizational Unit field on AdaptiveWork User Groups, it is for informational purposes only in AdaptiveWork. In AdaptiveWork this field has no functional purpose for permission levels or anything else.

License Types

License administration is not handled by the Sync Agent.

AdaptiveWork Licenses are assigned based on the User Type property for Users (Groups do not have this field). New users' user type is based on your AdaptiveWork System setting: New user default license type

New User Invitations

You may want to send invitations later if you have additional setup steps to do in AdaptiveWork or if you want to send them out manually as part of an Onboarding / Training process.

The New User Invite Policy setting allows you to decide whether to send the standard AdaptiveWork invitation email to new Users immediately upon provisioning or not.

New User Added Notifications to Administrators

AdaptiveWork System Settings provides 2 options for notifications for adding new users.

As the Active Directory User Sync Agent can add large quantities of users, it is highly recommended to set these as follows:

Alert Super Users on new user creation - FALSE (OFF)
Suppress new user emails to Administrators - TRUE (ON)

Sync Scenarios

How Active Directory User Sync initially matches Users and Groups

User Sync Agent works by pairing Active Directory groups (as set by you in the Agent itself) with User Groups in AdaptiveWork (initially matching by group name), identifying their users in AdaptiveWork (initially by email address), and then pairing them by storing users’ and groups’ Active Directory SIDs in AdaptiveWork's User Sync ID field.

All mapped data fields are synced one way from Active Directory to AdaptiveWork. No data is synced back to Active Directory.

Users in Active Directory can be members of multiple groups and likewise in AdaptiveWork.

Active Directory User Sync does not create or sync Discussion Groups.

Initial Sync Testing with Sandbox

AdaptiveWork Sandbox Refresh process resets all Sandbox User emails to a common no_reply@clarizen.com email address.

If you already have users in your Sandbox account, the duplicate detection will work inconsistently and you may see duplicate users created.

Sync Now

Click Sync Now to trigger a sync between Active Directory and AdaptiveWork. All changes to Active Directory users and groups since the last sync will be updated. If it is your initial sync, all users in the added Groups will be synced to AdaptiveWork.

Recurring Scheduled Sync

To create a scheduled sync, you can use the Windows Task Scheduler to set a daily sync that runs the ActiveDirectorySyncEngine.exe application.

IMPORTANT

The Task Scheduler job should run as the same user that installed and setup the Active Directory User Sync.

Special Case Handling

Job Title Sync

Users’ Job Titles are only set by the sync if they already exist in AdaptiveWork. This is because Job Titles can have billing rate implications and in AD they are free text fields that can be prone to typos.

If the AD User has a Job Title that does not exist in AdaptiveWork, no matching can be done and Job Title is not added and matched.

Direct Manager Sync Setting

According to this setting, if the Direct Manager is not part of a synced group, the Direct Manager will be created, but without a Group. The Sync Agent does not recursively add their Direct Managers to users added this way.

Deactivating Users in AdaptiveWork

Users in AdaptiveWork can be deactivated if:

Deleted User Policy: They are deleted in Active Directory
Disable User Policy: They are disabled in Active Directory
UnGrouped User Deprovisioning: They are active in Active Directory but no longer a member of any synced Groups (meaning: they are a member of other groups, but those Groups are not synced with AdaptiveWork).

Deactivated users are "Suspended" in AdaptiveWork and not fully deleted.

Viewing Log Files

At the end of a sync run, a daily Sync Report log file is created to help you monitor success and any issues it may encounter. On your Windows machine running the sync, the log files are accessible from:

C:\AdaptiveWorkADSyncLogs

The sync report gives you a summary of how many groups and users were created, disabled and if any errors were encountered. The messages are aimed to be as self-explanatory as possible so that you can resolve issues yourself. Open a support ticket if you need assistance with the logs.

At the end of each sync run, a copy of the daily Sync Report will also be uploaded and attached to the sync user in AdaptiveWork.
Note: The daily Sync Report contains details of all syncs from that day, so on initial syncs while you are getting set up, you can see summaries of multiple syncs.

In AdaptiveWork you can build workflow rules to attach or make additional posts, for example you might want to reply to the post and @mention users who are affected by any issues. You can also automate this by creating a workflow rule on Post to run when $Via = 'Active Directory User Sync'

Sync Report Notification Post in AdaptiveWork.

Sync Report viewed in AdaptiveWork

Workflow Rule for Sync Report Notification Post in AdaptiveWork

Example of an automatic reply to the Log File post with CC to another AdaptiveWork Group

Monitoring

Monitoring Sync Changes

The following AdaptiveWork fields describe sync updates:

User Sync ID - Set as the SID from Active Directory
User Sync Updated - Shows the date on which the record was last updated in Active Directory
User Sync Notes - Shows the date and time (in UTC) when the user/user group was last updated by the AD Sync Agent

Reports

The above fields can be added to AdaptiveWork reports and are also available in the following reports:

Active Directory Sync: Users
Active Directory Sync: User Groups

The reports are available in an App Package.

Monitoring when the Sync Last Ran

At the end of the AD User Sync Agent run, the date field Organization > User Sync Updated is updated and can be seen in Global Settings.

This field is always updated, whether or not the Sync Agent makes any changes to Users and User Groups in AdaptiveWork. You can add the field to the Global Settings layout via Profiles > Organization > Property Card, or find it via the Property Card search.

User Sync Updated viewed via Search

Limitations

1. Supported Groups & Users

Active Directory sync supports Global and Universal groups.

Domain Local groups are currently not supported.

The Active Directory Sync Agent does not sync sub-groups or non-human resources (such as printers, meeting rooms etc…)

2. Duplicate Group Names & Users Emails/SID’s

User Group names in AdaptiveWork are unique. If you have Groups with the same name in different domains, you will not be able to sync them both. You should ensure that Groups have unique names.

Whilst AdaptiveWork User email addresses are not unique, the Sync Agent will only sync users from Active Directory with unique email addresses.

3. Users without an email address

You can only sync users that have a valid email address. Users that do not have a valid email address will not be synced.

4. Number of Groups

There is no limit for the number of Groups you can map and sync into AdaptiveWork, as the Sync Agent syncs each group and then its members (users) separately.

5. Group Size

The User Sync Agent has been tested to work with Groups of up to 5,000 new users.

Above that number, you may encounter timeouts from AdaptiveWork web service APIs.

If you need to create larger numbers of users in a single sync, you can:

Divide the users into separate smaller Groups (e.g. Project Managers, Consultants, Team Members)
Run the sync repeatedly.
Users who were successfully created on previous syncs will then be skipped on subsequent sync runs. Repeat the process until no new users are created by the sync.

6. User Management Settings in AdaptiveWork

Active Directory Users Sync Agent sets some basic user settings specific to the sync process. However, most Advanced user settings managed in AdaptiveWork are also relevant to the users added by the sync process:

New user default license type Learn more

For Users, the User Type setting defines which license the system will assign them on first login. For the initial 14 days, this will be a trial license before they are auto-assigned a license of the relevant type from your organization’s available licenses.

The Default license type system setting sets which type of license new users should get: Full, Team Member, Time & Expense, None

Organization email domain Learn more

This setting lets you define your organization’s email domain.

Mark users from other domains as External Users automatically Learn more

If users have different email domains than the Organization email domain, this setting allows you to control whether they should automatically be flagged as External Users, which limits their access to items they’re specifically assigned to.