Integrate contacts from Active Directory or an Address Book

You can integrate your organization's Active Directory/ADFS/LDAP data into Diligent One so users can find people who do not use Diligent One and assign things to them.

How it works

Bringing Active Directory contacts into Diligent One is an automated process, but setting it up requires collaboration between a Results Admin and an IT person or data administrator who manages Active Directory in your company. This can be the same person, but typically, it is different people.

By default, Results includes a reference collection. This collection contains an analysis called Contacts and a table called Contact book. You set up a robot to pull data from Active Directory into this table using a script we provide. Once it is set up, this robot will sync data from Active Directory to Diligent One on a regular schedule. Users in Diligent One can then find contacts that are stored in your contact book and assign things to them.

ACL Robotics subscription requirements

  • To use the Active Directory script we provide, you need ACL Robotics Enterprise Edition and a on-premise Robots Agent.
  • To use a script you create yourself, you can use any edition of ACL Robotics. If you are using a cloud-based Robots Agent, the data source must be in the cloud.

What data you can access

Our Active Directory script pulls in ObjectSid, name, email address, and an optional field. This optional field can provide context like department or title to help Diligent One users identify someone.

Filter which records are imported

By default, our Active Directory script filters out inactive Active Directory users. You can further filter which records you import using the Object Category parameter while setting up the robot. Custom filters using ACLScript or SQL are not supported.

Contact book and Diligent One user accounts are not related

People in your contact book cannot access Diligent One. The primary purpose of the contact book is to allow Diligent One users to find contacts from Active Directory.

If a Diligent One user is also in the contact book, Diligent One displays the Diligent One user when assigning things, not their contact book equivalent. This is based on email address.

Getting contacts from systems other than Active Directory

Currently, Diligent only offers a complete Active Directory solution. However, you can modify our Active Directory script, or write your own, and use the same basic process to pull contacts from other systems, your CRM, or another address book you use. For help writing scripts, see Scripting in Analytics.

Permissions

  • Only Results Admins can view and manage the reference collection containing the contact book.
  • Your system admin, IT professional, or data administrator who manages Active Directory in your company needs a Diligent One account that can use Analytics, create and manage robots, and verify that data is flowing into Results.
    • Option 1 (simpler) Diligent One System Admin with a Professional subscription and access to Analytics.
    • Option 2 (more segregation of duties) Diligent One User with a Professional subscription and a Results Admin and a Robots User or Robots Admin and access to Analytics.

Limitations

Your contact book is subject to the table size limitations in Results.

Each table contains a maximum of:

  • 100,000 records
  • 500 columns

    Note

    You can import up to 100 columns at a time. More columns can then be added using linked questionnaires or exports from Analytics that use a primary key. The combined number of data columns and questionnaire columns cannot exceed 500. Metadata columns are excluded from this limit.

  • 256 characters per field name, including blank characters (does not apply to individual data fields)

If the number of active users exceeds the Results limit of 100,000 records per table, use the ObjectCategory parameter to filter on a subset of the data while setting up the robot.

Set up integration for the first time

Setting up this process requires two people with different responsibilities to work together.

1. Results Admin steps

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. Look for the table ID in the Contact book table. Make note of this ID. You will need to give it to the next person.

    Note

    If you have more than one contact book table, just choose the one you want to be your contact book.

  5. Ensure there is a HighBond API token for the syncing script to use.

    If a HighBond API token does not exist, generate one. Because tokens are tied to user accounts, not to your company, we recommend using a token from a generic account rather than your own. This ensures the syncing process will not be interrupted in the future if you leave or change roles. If you don't have access to a generic account, contact the person who administers Diligent One in your organization and ask for their help.

  6. Contact the person responsible for managing Active Directory in your company. This might be a system administrator or data administrator. Give them the following information:
    1. These instructions: 2. Data administrator/system administrator steps.
    2. The table ID
    3. Which optional field you want (title or department, for example)
    4. The HighBond API token you want the syncing script to use.
  7. Ensure that the system administrator helping you has a Diligent One account, has been added to the instance(s) of Diligent One you need contacts in, and has the permissions they need to complete their tasks.

2. Data administrator/system administrator steps

Your colleague has asked you to bring Active Directory contacts into Diligent One. If you are not familiar with Diligent One, it is an enterprise governance software platform that creates stronger security, risk management, compliance, and assurance. By allowing Active Directory contacts into Diligent One, users in your company can more easily locate stakeholders and assign tasks and responsibilities to them. In turn, these people will help your organization manage its risks and comply with laws and regulations.

To complete these steps, you will install the Active Directory Contacts Robot toolkit and create a task to pull in Active Directory data at regular intervals. Then, you will verify if the robot works correctly.

Note

The contact data in Diligent One is a copy. It will never alter the source data.

  1. If you do not already know it, get the following from the person who asked you to complete this task:
    1. A table ID
    2. Which optional field they want to bring in (title or department, for example)
    3. Diligent One access with the permissions you need to complete your tasks
    4. A HighBond API token
  2. Perform the following steps to install the Active Directory Contacts Robot toolkit.
    1. Open the Marketplace app.
    2. From the toolkit catalog, choose the toolkit and select Install.

      A panel appears with a preview of the toolkit.

      Important

      Choose the edition of the toolkit – Non-Unicode or Unicode – that matches the edition of the Robots Agent used by your organization. To verify, see Verifying your Robots Agent edition.

      The installation process works only if the editions match.

    3. Click Install.

      Installation may take a few moments.

      Result When installation is complete, a success message appears.

      Note

      If an error message appears during installation, try installing again. If the installation fails again, contact Support.

  3. Switch to the Robots app and activate the robot scripts.

    1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

      If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

    2. Find and open the Active Directory Contacts Integration robot.

      Tip

      If the robot is not present, try refreshing the page. If the robot still does not appear, the toolkit installation was not successful. Delete the toolkit that you tried to install and try installing again. If still unsuccessful, contact Diligent Support.

    3. Click Activate version.

      Robots switches from production to development mode.

    4. In the Script versions tab, select v1.
    5. In the right-hand-side Version details panel, select Activate.
    6. Optional. In the Add comment field, enter any information that you want to accompany the script activation.
    7. Click Activate v1.

      Result The script version is activated and becomes available for use in production mode.

  4. Create a robot task.
    1. In the upper-right corner of the robot, click Production to switch back to production mode.
    2. In the Tasks tab, click Create task.
    3. Give the task a descriptive name like "Sync Active Directory contacts" and click Save.
    4. Click Activate All to turn on the script.
    5. Click the down arrow to access the script parameters.
    6. Enter the required parameters.

      If necessary, enter the optional parameters, or leave them blank to use the defaults. This step is when you need the table ID, HighBond API token, and optional field your colleague provided.

      ParameterDefinitionExample
      Enter the Active Directory user name in the format domain\user_name.The distinguished name of a user. Together with Password, this field is used to authenticate against the Active Directory server.example/john_smith
      Enter the password to access Active Directory.

      The password for the distinguished name of the specified user. Together with User, this field is used to authenticate against the Active Directory server.

      Note

      You may connect without providing a password if your Active Directory server permits anonymous connections. Based on your server's security configuration, anonymous connections may be able to list available tables. However, such connections may not be able to select data from some or all of the tables listed. For more information about your Active Directory security configuration, contact your company's administrator.

      		aStrongPassword
      Enter the domain name or IP of the Active Directory server.The domain name or IP of the Active Directory server. This does not need to include the LDAP:\\ portion, only the server domain name or IP.192.0.2.255
      Enter the port the Active Directory server is running on.The port the Active Directory server is running on. Together with Server, this property is used to specify the Active Directory server.389
      Enter the base portion of the Distinguished name.

      The base portion of the distinguished name, used for limiting results to specific subtrees.

      Specifying a base DN may greatly improve performance when returning entries for large servers by limiting the number of entries that need to be examined.

      		DC=myConnection,DC=com
      Select the LDAP version to connect to and communicate with the server.The LDAP version used to connect to and communicate with the server. Valid options are 2 and 3 for LDAP versions 2 and 3.2
      Select the authentication mechanism to use.

      The authentication mechanism to be used when connecting to the Active Directory server:

      • SIMPLE default plaintext authentication is used to log in to the server
      • DIGESTMD5 the more secure DIGEST-MD5 authentication is used
      • NEGOTIATE NTLM/Negotiate authentication will be used
      		SIMPLE
      Select the scope.

      Whether to limit the scope of the search to:

      • WholeSubtree the whole subtree (BaseDN and all of its descendants)
      • SingleLevel a single level (BaseDN and its direct descendants)
      • BaseObject the base object (BaseDN only)

      Tip

      Limiting scope can greatly improve the search performance.

      		BaseObject
      Enter the Object Category to exclude.

      Use this value to import records with a particular ObjectCategory. For example, "Computer" will only imports contacts with an ObjectCategory of "Computer". You can use a pipe-separated list to match on multiple values.

      Tip

      If the number of active users exceeds the Results limit of 100,000 records per table, you can use the ObjectCategory parameter to filter on a subset of the data.

      		Computer|Person
      Select the Optional Configuration Field. The optional field to help identify people. This value should have been provided for you by the Results Admin who requested your help. By default, our Active Directory script limits this choice to title, department, or manager. However, you can modify this script, or create your own, if you need more options.Title
      Enter the control test ID and data center code of the Contacts Reference Table in Results. The table ID and region for your Diligent One instance. This value should have been provided for you by the Results Admin who requested your help.12345@eu
      Enter the HighBond Access Token. The HighBond access token so the script can authenticate with Diligent One. This value should have been provided for you by the Results Admin who requested your help. 
    7. Click Continue.
    8. Click Put your task on a schedule and enter a frequency. Generally, nightly is sufficient.
    9. Click Continue.
    10. If you want someone to be notified if the task does not run for any reason, click Send notifications on failure and choose the person who should get these emails. This might be you, or it might be the Results Admin who asked for your assistance with this task.
    11. Click Continue.
    12. Review the settings. If you need to make any changes, click one of the Edit buttons. If everything looks good, click Confirm and create task.

Test the data import

Now that the robot is ready, test it to ensure it works properly.

  1. Still on the Tasks tab, click on the new task you created.
  2. From the Task details panel, click Run Now.

    The task runs in the background. You can monitor its status under Latest results, on the left. It should only take a minute or two.

  3. When the task indicates Success, it has run successfully.
    • Error and warnings are written to Export_Summary.log, which you can view in the Task run details panel. The log will also provide advice for fixing the source data.
    • Even if the task is successful, we still recommend viewing the log. There may be warnings about malformed and missing data in your database.
  4. Open the Results app.
  5. Open the Special collections panel if it is closed.
  6. Click Reference Collection.

    If you do not see the Reference Collection, you do not have Results Admin privileges. You must be a Results Admin before you can continue. A Diligent One System Admin can assign you these privileges.

  7. Verify that the number of records in the reference collection is the same as the number of records you expected to import from Active Directory. Optionally, click your contact book to inspect the records.
  8. If everything looks good, let the Results Admin know. They will perform some steps and ask you for assistance one final time.

3. Results Admin steps

At this point, your system administrator/data administrator should have created and tested the robot that will automate Active Directory integration. Now you should activate your contact book so people can use it.

Activate the contact book

Before Diligent One users can take advantage of Active Directory contacts, you need to set this table as the contact book.

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. Click Manage contacts for the table you want to use as your contact book.

    The Manage contact book side-panel opens. If this table has any interpretations, there is an Interpretation dropdown in the Manage contact book panel.

    • Choosing the table sets up the contact book to use all records in that table.

    • Choosing an interpretation sets up the contact book to use only the records that match the filters set on that interpretation. If there are no interpretations, continue to step 5.

  5. Choose the name and email columns.
  6. If you are using an optional field, choose it here, too, and enter a descriptive name for what it represents (for example, "Title" or "Department"). Diligent One users will see this label and value when they look for contacts in the system.
  7. Click Activate or Save.

Set a primary key on the table

In order to update the records in this table in the future, you must set a primary key.

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. For the table that is your contact book, click and click Settings.
  5. Click the Primary key field dropdown and choose a primary key. We recommend that you set this table's primary key to a unique user ID column now. If you are using our default active directory syncing script, the field you should use is ObjectSID.
  6. Click Save.

You are done

You may want to make yourself a reminder to return and check that the robot is running its task on schedule. If the log indicated warnings for the Active Directory data, this is a good opportunity to cleanse that data and ensure users won't experience any confusion. See Fix errors and warnings for help.

If your organization has a limited number of licenses, once you are sure you no longer need yours, you can contact the person who administers these licenses to inform them that your account can be deactivated.

Fix errors and warnings

When the robot runs the task to populate the contact book, it may report errors and warnings based on the Active Directory data.

  • Errors may cause the task to fail. If not, they may leave it in an incomplete state.
  • Warnings will not cause the task to fail, but they reflect data problems that could leave users confused.

In either case, it is best to try to resolve the issues in the source data quickly. Error and warnings are written to Export_Summary.log, which you can view in the Task run details panel after the task runs. The log also provides advice for fixing the source data.

Keep contacts up-to-date

If you set the robot to do so, it will update the contact book table in Diligent One with any changes to Active Directory on the schedule you choose. You can run the robot manually, but you do not need to.

View all contacts

Once you have a contact book setup, you can view everyone in it.

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. Click the contact book's title.

Change which table is used for the contact book

It is possible to have multiple tables with contacts, but only one can be the active contact book at any time. Typically, you might use a separate table for testing changes before making a new list of contacts available to Diligent One users. To do this, you need to deactivate the current Contact book table, then activate the new one.

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. Find the current contact book table and click Manage Contacts. The Manage contact book side panel opens.
  5. Click Deactivate. The Manage contact book side panel closes.
  6. Find the table you want to use as the contact book and click Manage Contacts.

    The Manage contact book side panel opens. If this table has any interpretations, there is an Interpretation dropdown in the Manage contact book panel. An interpretation is a bundled collection of filters, visualizations, and statistics based on a table in a collection.

    • Choosing the table sets up the contact book to use all records in that table.

    • Choosing an interpretation sets up the contact book to use only the records that match the filters set on that interpretation. If there are no interpretations, continue to step 7.

  7. Choose the name and email columns.
  8. If you are using an optional field, enter a descriptive name for what it represents (for example, "Title" or "Department". Diligent One users will see this label and value when they look for contacts in the system.
  9. Click Activate or Save.

Update contact book configurations

You can adjust how fields from your contact book are mapped and change the optional field's label for the existing contact book.

  1. Open the Results app.
  2. Open the Special collections panel if it is closed.
  3. Click Reference Collection.
  4. Find the table you are using as the contact book and click Manage Contacts. The Manage contact book side-panel opens.
  5. If this table has any interpretations, choose the one you want to use. If not, continue to step 6.
  6. Choose the name and email columns. If you want to use an optional field, choose it here, too, and enter a descriptive name for what it represents (for example, "Title" or "Department").
  7. Click Save.

What happens when you delete or update contacts

Any time you delete a contact book, or edit or delete a row from that contact book, items assigned to that contact will still be assigned to that contact, but the contact becomes static and will no longer update.

For example, an action in Projects is assigned to john.smith@example.com. Then, John is removed from the contact book. The action is still assigned to john.smith@example.com, and will remain so until someone reassigns the action.