Skip to main content

 

Planview Customer Success Center

User Provisioning with On-Premise Active Directory

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:

Watch a video tutorial

Contents

Architecture

Downloading and Installing the Sync Agent

Migrating Users from Active Directory Sync v1

Setting Up Connections to AdaptiveWork and Active Directory

Connection to AdaptiveWork

Connection to Active Directory

Setting up Field Mappings

Adding Additional Groups

Verifying Additional Settings

Selecting a Group to Test

License Types

New User Invitations

New User Added Notifications to Administrators

Sync Scenarios

How Active Directory User Sync initially matches Users & Groups

Sync Now

Recurring Scheduled Sync

Special Case Handling

Job Title Sync

Direct Manager Sync Setting

Deactivating Users in AdaptiveWork

Viewing Log Files

Monitoring

Monitoring Sync Changes

Monitoring when the Sync Last Ran

Limitations

Supported Groups & Users

Duplicate Group Names & Users emails/SID’s

Users without an email address

Number of Groups

Group Size

User Management Settings in AdaptiveWork

Architecture

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

360010286454_mceclip0.png

Downloading and Installing the Sync Agent:

Installation Pre-Requisites

Before configuring the integration, make sure that you have:

  1. Ability to install Programs on your Windows PC
  2. Administrative privileges for your AdaptiveWork environment
  3. Privileges for your company’s Active Directory Federation Services.
  4. .Net 4.6.2 or above
  5. Network access to AdaptiveWork API (port:443)
  6. 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.

Installation

  1. Download the .msi file from the AdaptiveWork Apps Marketplace
  2. 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

      360009311993_mceclip1.png


    3. Once you have installed the initial .msi package, navigate to
      Program Files (x86) > AdaptiveWork > ActiveDirectorySync
      and run AdaptiveWorkADSyncSettings to finish the installation process.

  3. 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.
  4. 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

Old Custom Field

New Standard 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:

  1. You are currently using the v1 AD User Sync app,
    and
  2. 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

  1. Download the Migration App and activate it.
  2. 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.

    360009321173_mceclip0.png
  • "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:

    1. 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.
    2. 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

    360009262914_mceclip3.png

    Selecting up all Account Credentials

    360009312053_mceclip4.png

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

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

    Setting up Field Mappings

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

    1. Click Field Mapping.
    2. 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


      1. 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.
      2. To add a new field, click + Add Fields. Open the drop-down lists to select field values.
      3. To remove a field mapping, click the bin icon next to the mapping.
    3. Click Save.

    360009262954_mceclip0.png

    Adding Additional Groups

    Select which groups to sync and add groups.

    1. Click + Add Group
      360009312133_mceclip1.png
    2. Select the domain your groups are in.
    3. Select the groups that you want to sync. Use the search field to find a group(s).

      Group Search and Selection

      360009312153_mceclip2.png360009262974_mceclip3.png
    4. Click UPDATE SYNC LIST and your selected Groups will be added to the sync set.
    5. Click [x] to close the Add Groups window.
    6. Click on a Group to verify its users.

      Viewing a Group Users

      360009312173_mceclip4.png

    Verifying Additional Settings

    Click Settings to change the default sync settings.

    Settings screen

    360009312193_mceclip5.png

    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.

    360009312233_mceclip6.png

    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.

    360009312253_mceclip7.png

    Sync Report viewed in AdaptiveWork

    360009312273_mceclip8.png

    Workflow Rule for Sync Report Notification Post in AdaptiveWork

    360009312293_mceclip9.png

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

    360009263094_mceclip10.png

    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

    360009271994_mceclip1.png

    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:

    1. Divide the users into separate smaller Groups (e.g. Project Managers, Consultants, Team Members)
    2. 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:

    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

    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.