> For the complete documentation index, see [llms.txt](https://docs.pascom.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pascom.net/en/integrations/connector/contacts-active-directory.md).

# Contacts from Microsoft Active Directory

Snychronise your telephone book entries from Microsoft Active Directory

## Microsoft Active Directory

In order to be able to read data from Active Directory, you require a user with the appropriate permissions. You could use the Active Directory Administrator for this purpose. However, as the PASCOM cloud phone system needs to save the access credentials for the automated future imports and the the administrator as significantly more than the required permissions, it is advisable to create a user account for the PASCOM PBX:

If you use *mobydick* as the username, this will be automatically detected by the LDAP filter during the import process and will not be automatically added as a PASCOM cloud phone system user.

Assign a password for the PASCOM user and select *password never expires*. The PASCOM PBX can then authenticate itself by the Active Directory with every execution of the connector sync. If you wish to change this password, you must change the password in both Active Directory and within the PASCOM connector profile:

## "Telephone Book from AD" Connector Profile

Create a new connector profile by logging into the PASCOM Web UI and navigating to **Settings** > **Connector** > **Add**.

Select the option *Telephone book from AD* and enter the following information:

| Field                         | Description                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Name**                      | Connector Name                                                                                       |
| **AD Domain**                 | Active Directory Domain Name                                                                         |
| **AD Server**                 | Host server IP or DNS name                                                                           |
| **Enable SSL**                | **YES**: Secure SSL connection to Active Directory. **NO**: Connect to Active Directory without SSL. |
| **Username** and **Password** | The PASCOM user previously added to AD for authentication purposes                                   |

After saving, the template can be modified according to requirements under the tab **Basic Data**.

### Basic Data

Under the basic data tab, you can configure your LDAP connection more precisely or update the previously configured settings.

| Field                         | Description                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Title**                     | Connector profile name (*automatically filled*)                                                                                                                                                                                                                                                                                                                          |
| **Mode**                      | <p><strong>Create and update records. Remove missing records from previous imports.</strong>: (<em>default setting</em>) Imports only new phone book entries and compares updated entries, old entries will be removed.<br><strong>Create and update records</strong>: Imports only new phone book entries and compares updated entries. No entries will be removed.</p> |
| **URI**                       | URI to Active Directory (*automatically filled*)                                                                                                                                                                                                                                                                                                                         |
| **Base DN**                   | Base DN to AD entries (*automatically filled*)                                                                                                                                                                                                                                                                                                                           |
| **Username** and **Password** | AD authentication credentials for the added PASCOM user (*automatically filled*)                                                                                                                                                                                                                                                                                         |
| **Search Filter**             | AD search filter for filtering the destination telephone book read folders (*automatically filled*)                                                                                                                                                                                                                                                                      |
| **Comments**                  | Serves as a documentation / description for the connector                                                                                                                                                                                                                                                                                                                |

### Pre Filter

Per default, the template will import all users from the Active Directory. Using the **Pre Filter** tab you can restrict the import according to certain factors e.g. *company-phonebook* is populated. Simply replace "*return array\_key\_exists('displayName', $row);*" with the following code:

```
# only import contacts with membership
if (!array_key_exists("memberOf", $row)) return false;

$groups = $row["memberOf"];
# turn a single group membership (string) into a list of memberships (array)
if (!is_array($groups)){
  $groups = array($row["memberOf"]);
}

# always search in a list of memberships
return preg_grep('/company-phonebook/i', $groups);
```

### Telephone Book Fields in AD

| Active Directory       | PASCOM       | Description                                                                                  |
| ---------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| General > Display Name | Display Name | Display names appear on phone screens and within the PASCOM App call logs. Compulsory field. |
| Phone number > Private | Telephone    | The contact phone number.                                                                    |
| General > First name   | First name   | Contact's forename.                                                                          |
| General > Last name    | Last name    | Contact's surname.                                                                           |
| Organisation > Company | Organisation | Contact's company.                                                                           |
| Phone number > Fax     | Fax          | Conctact's fax number.                                                                       |
| General > E-mail       | Email        | Contact's E-mail address.                                                                    |
| Phone number > Mobile  | Mobile       | Contact mobile phone number.                                                                 |

These fields are only suggestions for the template. You can add and remove fields as required or if necessary completely modify the structure to match your needs.

### Test and Activate the Import Process

After you have finalised your configuration, you can test the connector profile to determine which datasets will be imported using the **Save and Simulate** button. Once you are satisfied with the results, it is possible to either perform a one off import using the **Action** > **Import Now** option or automate the import to be performed at regular intervals by clicking the **Automate** button.

#### Individualised Display Names

The PASCOM telephone book display name is displayed for in- and outbound calls, desktop VoIP phone displays as well as in your PASCOM App. Should you wish to customised / change display names because the stored display name in Active Directory does not match your needs or requirements of your PASCOM cloud phone system, it is possible to individually populate this field.

Where the information originates from in Active Directory can be found under the tab **Variables**. Per default, the display name (*displayName*) is taken directly from Active Directory.

| Variable    | Source                        |
| ----------- | ----------------------------- |
| displayname | `return $row['displayName'];` |

However, as the display name within your PASCOM cloud phone system may not exceed 80 characters, it may be necessary to shorted the display name from Active Directory or, if desired, be read from different fields.

In the following example, the display name from Active Directory will be:

* Checked for length
* Automatically populated using the users' Surname and Forename (Givenname) should the AD display name not have been set
* Shortenedd to the maximum allowed 80 characters.

To do this, under the **Variables** tab, the *displayname* **Source** will be replaced with the following content:

```
# check if displayname is empty
if (!empty($row['displayName'])) {

  # check if displayname has more than 80 chars and cut it if necessary
  if (strlen($row['displayName']) <= 80) {
    return $row['displayName'];
  }
  # displayname will be cut from 0 to 80 chars
  return substr($row['displayName'],0,80);
}

# if displayname is empty use a combination of "Surname" and "Givenname" 
# and also cut it if it's longer than 80 chars
return substr($row['Surname'] . ', ' . $row['GivenName'],0,80);
```

Instead of forename and surname, it is of course also possible to read any other Active Directory field and use this as the display name source.

#### Optional Modifications

Do you want to make changes to source variables or the Connector structure? Then follow the links below to the appropriate instructions:

[Variable Assignment](/en/integrations/connector/variables-assignment.md)

[Variables structure](/en/integrations/connector/variables-structure.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pascom.net/en/integrations/connector/contacts-active-directory.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.