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:
Watch a video tutorial
The AdaptiveWork Active Directory User Sync Agent application is comprised of 2 functional elements:
- AdaptiveWork Active Directory User Sync Agent - the configuration screens
AdaptiveWork Active Directory User Sync - the sync engine that can be scheduled
Downloading and Installing the Sync Agent:
Before configuring the integration, make sure that you have:
- Ability to install Programs on your Windows PC
- Administrative privileges for your AdaptiveWork environment
- Privileges for your company’s Active Directory Federation Services.
- .Net 4.6.2 or above
- Network access to AdaptiveWork API (port:443)
- Network access to you company's Active Directory
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.
- 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:
- AdaptiveWorkADSyncSettings - Run this first to set up connections to Active Directory and AdaptiveWork for Groups and field mappings
ActiveDirectorySyncEngine- This is the engine that runs the sync and can be scheduled to run on an ongoing basis using Windows Task Scheduler
- 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.
Previously the Active Directory sync relied on custom fields to work:
SSOKey, SSONotes, SSOUpdated.
v2 uses standard fields so no additional installations are required.
Old Custom Field
New Standard Field
User, User Group
User Sync ID
User, User Group
User Sync Updated
User, User Group
User Sync Notes
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,
- 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
"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.
Choose the Sandbox option in Account Credentials > AdaptiveWork connection. Add your username and password, and check the connection.
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.
- 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.
- 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.
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 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)
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 email@example.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.
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.
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:
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 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
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
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.