Administrator Guide: External Contacts Integration

Table of contents

Overview

6 methods are supported to integrate external contacts into your UC solution.

Method Description Contacts stored in Scope
UC Model import Import remote contacts on every SOP (via XML web service or CSV file) Imported contacts table on SOP SOP
UC Model merge Import remote contacts on every SOP (via XML web service or CSV file) and merge them with Internal Directory Internal Directory on SOP SOP
SMP Bulk Import contacts from a CSV file to the SMP, with a unique "short number" per contact Internal Directory on SMP & SOP SMP -> SOP
LDAP Sync Contacts synchronized from external LDAP source into Internal Directory with a unique "short number" per contact Internal Directory on SMP & SOP SyncLDAP on SOP -> SMP -> SOP
Outlook sync Contact synchronized from user's local Outlook directly into end-user UC application UC application user PC
Fusion API integration HTTP request to remote server for each dbGetDirectoryInfo API request Contacts are not imported and remain on remote server SOP

See below in which application the external contacts can be used, depending on the method.

  UC Model import UC Model merge SMP Bulk LDAP Sync Outlook sync Fusion API integration
Connect Me 3.x DONE DONE DONE DONE choice-no DONE
ESCAUX Connect 2.5 choice-no choice-no choice-no choice-no choice-no DONE
net.Desktop As from Fusion API 4.5 As from Fusion API 4.5 DONE DONE DONE DONE
net.Console choice-no DONE DONE DONE choice-no choice-no
Polycom Corporate Directory choice-no DONE DONE DONE choice-no choice-no
Aastra Corporate Directory As from Fusion API 4.5 As from Fusion API 4.5 DONE DONE choice-no DONE
LG Corporate Directory As from Fusion API 4.5 As from Fusion API 4.5 DONE DONE choice-no DONE
dbGetDirectoryInfo API call As from Fusion API 4.5 As from Fusion API 4.5 DONE DONE choice-no DONE
getExtensions & getExtensionInfo callflow actions DONE DONE DONE DONE choice-no choice-no
Short number dialing choice-no DONE DONE DONE choice-no choice-no

UC Model import method

Requirements

UC Model can be configured to fetch contacts from an external XML web service or from a CSV file to be uploaded to the SOP.

XML Web Service

1. An XML web service that exposes the external contacts in the "UC Model" format

You have to create an XML web service on the remote data server. This web service should be accessible by HTTP on port 80.

The web service should return an XML reply in the externalcontacts_v1.xsd format. Character encoding should be UTF-8.

Make sure to have line breaks in the output!

Example:

<?xml version="1.0" encoding="UTF-8"?>
<contacts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="contacts.xsd">
  <contact>
    <owner>Owner</owner>
    <extension>123</extension>
    <department>departement</department>
    <fax_number>0123321</fax_number>
    <home_number>0123456789</home_number>
    <office/>
    <first_name>Daisy</first_name>
    <last_name>Chain</last_name>
    <e_mail>daisy.chain@example.com</e_mail>
    <mobile_number>012345678</mobile_number>
    <source>ldap</source>
    <user_1>t229930</user_1>
    <user_2>03/03/1990</user_2>
    <user_3/>
    <user_4/>
    <user_5/>
    <user_6/>
    <user_7/>
    <user_8/>
    <user_9/>
    <user_10/>
  </contact>
</contacts>

2. Module Unified Communication Model 1.9.4

CSV file

  1. You have to create a CSV file respecting the structure described in contacts.csv. Separator is the comma (,). Character encoding should be UTF-8. Headers must be present in the CSV file and the file cannot contain a BOM. It is good practise to validate the format of the CSV file with a tool such as csvlint prior to uploading it to the SOP.
  2. SOP API Module 4.5.0+
  3. Module Unified Communication Model 1.9.4

Configuration

All the configuration can be done in the Unified Communication Model module.

Contact source

XML Web service

Those parameters need to be configured in the Unified Communication Model module.

  • URL: Specify the URL of your XML web service
  • Cron: Specify the schedule for the external contacts retrieval in the imported contacts table. See "Cron specification" for the format.

CSV file

Upload the CSV on the SOP via the File Manager in "contacts" directory. The file has to be named "contacts.csv".

Those parameters need to be configured in the Unified Communication Model module.

  • URL: http://localhost/xml/dbGetImportedFromCsv
  • Cron: Specify the schedule for the external contacts retrieval in the imported contacts table. See "Cron specification" for the format.

This is to be done on every SOP where the external contacts should be available.

Cron specification

Defines the frequency to fetch the external data source.
Five fields need to be specified separated by spaces:
Minutes Hours Day-of-month Month Day-Of-Week

For more info or a cheatsheet : https://crontab.guru/

Setting an empty value will disable the scheduling.

These fields have the following format:

  • Minutes
    • allowed values: 0-59
    • special characters: * , - /
  • Hours
    • allowed values: 0-23
    • special characters: * , - /
  • Day-of-month
    • allowed values: 1-31
    • special characters: * , - / ?
  • Month
    • allowed values: 1-12
    • special characters: * , - /
  • Day-of-Week
    • allowed values: 1-7
    • special characters: * , - / ?

Day-of-month and Day-of-week are mutually exclusive. They can not be both specified, a '?' must be used for one of them which means it is ignored.

Special characters

"*" is a shorthand used to specify a list with every allowed value for the chosen field.
E.g.:
* * * * ?
an import is occuring every minute.

"," is used to specify a list of allowed values.
Usage: value1,value2,value3
E.g.:
1,30 * * * ?
an import is occuring every 1st and 30th minute of each hour.

'-' is used to specify a range of values.
Usage: value1-value2
E.g.:
* 0-23 ? * *
an import is occuring every hour.

'/' is used to specify increments starting from a certain value.
Usage: value1/value2
E.g.:
0/5 * * * ?
an import is occuring every five minutes starting from the 0th minute (0,5,10,15,...).

Post-install action

After you (re-)installed the module don't forget to do the post-install action. See the UC Model module documentation.

UC Model merge method

Requirements

Same as UC Model import method

Configuration

In order to expose the external contacts to net.Console and the internal LDAP Server (Polycom/Aastra/Gigaset Corporate Directory), the contacts imported in UC Model need to be merged in a new database table. This can be done by configuring those additional parameters in the Unified Communication Module:

  • Merge directory cron: schedule when to merge external contacts and internal contacts in the merged contacts table. See "Cron specification" above for the format. Running it once a day should be more than enough (e.g 0 4 ? * *). Avoid running the import and the merge at the same time, or running it continuously, since it can have an impact on the performance of the SOP.
  • Priority for each field: For each field in the external contacts source file, a priority needs to be specified to tell which source to use, Internal directory or the external source. See below for more details.
  • Matching field: A matching field needs to be selected to specify how entries from the external source can be linked with contacts from the Internal Directory. See below for more details.

Priority

For each field in the external contacts source file, a priority needs to be specified to tell which source to use, Internal directory or the external source.

The priority can have only two values: 0 or 1.

A zero means the SMP data will be used as the authoritive source, a one means the External Source will be used as the authoritive source.

The order in which to specify the priorities of the fields is:

extension first_name last_name mobile_number fax_number home_number e_mail department office owner source user_1 user_2 user_3 user_4 user_5 user_6 user_7 user_8 user_9 user_10

They must be separated by a space.

E.g.:

0 1 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0

How are the external contacts merged?

A matching field needs to be selected to specify how entries from the external source can be linked with contacts from the Internal Directory. Please read the following section carefully to understand how this matching field works.

Abbreviations used: Matching field: MF: What the user has specified in the module configuration.
External datasource: ED.

The following strategy is used to achieve a unified directory when both the SMP and an ED are being used.

The user should be aware that there is an implicit link between entries in the SMP and entries in the ED, the extension field. It is always used! The extension behaves like a primary key but can be omitted (which means that entries without an extension are all considered to be unique). This link is used to group entries that belong to each other. Bear in mind that nothing is merged yet.

The actual merge can be divided in three cases:

  • Case 1: SMP entries for which there are no ED entries with the same extension.
    Since there is only one SMP entry for an extension, the SMP entry is shown as is.

  • Case 2: SMP entries for which there are ED entries with the same extension.
    All ED entries for a certain extension are grouped in MF groups.
    An MF group is a group containing entries that have the same MF value and extension.
    What will be shown:
    • The entries in such an MF group are merged with each other and finally merged with the SMP entry (even it does not have a matching MF value) resulting in one entry to be shown per MF group.
    • If the MF value of the SMP entry matched with an MF group, it will not be shown separately otherwise it will.

  • Case 3: ED entries for which there is no match on extension with the SMP (entries without extension or an unknown extension to the SMP).
    These ED entries are shown as is.

Example

To clarify all this, here is an example with a limited set of fields.

Assume that an SMP or ED entry only consists of the following fields: extension, first_name, last_name, user_1, user_2.
"-" means that is not present in the database.

Example:
  • SMP entry 1: extension: 2000 first_name: Joe last_name: Sixpack user_1: z506010 user_2: -
  • SMP entry 2: extension: 20 first_name: John last_name: Doe user_1: x10203 user_2: -
  • ED entry 1: extension: 201 first_name: Joe last_name: Sixpack user_1: y20201 user_2: 01/01/1970
  • ED entry 2: extension: 20 first_name: John last_name: T. Doe user_1: x10203 user_2: 02/02/1980
  • ED entry 3: extension: 20 first_name: John last_name: Joe user_1: t229930 user_2: 04/04/2000
  • ED entry 4: extension: 50 first_name: Daisy last_name: Chain user_1: z204020 user_2: 03/03/1990

The following priorities are chosen: extension:0 first_name:1 last_name:0 user_1:1 user_2:1

matching field is user_1

which results in:

SMP entry 1 is handled by case 1 and shown as is. ED entry 2 and SMP entry 2 are handled by case 2, merged into a single entry. ED entry 3 and SMP entry 2 are handled by case 2, but have a different matching field, ED entry 4 will be displayed as is. Since SMP entry 2 was involved in a merge with ED entry 2, it is not shown separately. ED entry 1 is handled by case 3 and shown as is. ED entry 4 is handled by case 3 and shown as is.

Contact 1: extension: 2000 first_name: Joe last_name: Sixpack user_1: z506010 user_2: -

Contact 2: extension: 20 first_name: John last_name: Doe user_1: x10203 user_2: 02/02/1980

Contact 3: extension: 20 first_name: John last_name: Joe user_1: t229930 user_2: 04/04/2000

Contact 4: extension: 201 first_name: Joe last_name: Sixpack user_1: y20201 user_2: 01/01/1970

Contact 5: extension: 50 first_name: Daisy last_name: Chain user_1: z204020 user_2: 03/03/1990

Post-install action

After you (re-)installed the module don't forget to do the post-install action. See the module documentation.

SMP Bulk method

Requirements

  1. A contact list in CSV format with at leat first name, last name and phone number with leading 0
  2. A "short number" profile (mandatory)
  3. A "short number" callflow (optional) that will dial the external number associated to the extension.

The "short number" profile & callflow exist in the Fusion Service Template.

Configuration

  1. Use the Bulk administration feature on the SMP for the Internal Directory. See the SMP Admin Guide
  2. Integrate the contact list in the Bulk Administration CSV format
  3. Assign internal extensions to the external contact entries
  4. In case of cluster you can define in field SOP1 (and SOP2 for Active-Active) on which SOP the external contacts should be available. If no SOP1 is defined it will be available on every SOP of the cluster.
  5. Assign the "short number" callflow / profile to the external contact entries
  6. Keep the Source field to "CSV"
  7. Upload the CSV
  8. Make an Apply-Changes

LDAP Sync method

Requirements

  1. LDAP Sync module and LDAP Synchronization task
  2. An external LDAP source containing external contacts: the external LDAP source must be on the same site as the SOP and the external contacts must be in the same format as in the internal LDAP server of the SOP.
  3. A "short number" profile (mandatory)
  4. A "short number" callflow (optional) that will dial the external number associated to the extension.

The "short number" profile & callflow exist in the Fusion Service Template.

Configuration

Assign the "short number" callflow to the external contacts on your LDAP server.

See the LDAP Sync Administrator Guide for details on how to configure the LDAP Synchronisation.

An Apply-changes is needed to push the contact to the SOP database.

Outlook sync

This is to be configured in user's net.Desktop preferences. See the net.Desktop user guides.

Fusion API integration method

Each time the net.Desktop synchronizes the Unified Directory (or the Corporate Directory feature used on Aastra or LG phone), it will issue an HTTP request (API) to the local SOP server. The SOP server undertakes the following actions:

  1. it proxies the HTTP request to all known remote datasources
  2. it consolidates the XML replies from all remote datasources
  3. it returns the consolidated XML reply to the net.Desktop client

The synchronization of the data sources can occur automatically at startup or can be initiated manually on request.

Requirements

1. An XML web service that exposes the external contacts in the "dbGetDirectoryInfo" format

You have to create an XML web service on the remote data server. This web service should listen to port 80 and should be accessible through the following HTTP request:

http://a.b.c.d/xml/dbGetDirectoryInfoBody.php where a.b.c.d is the IP address of the remote data source.

The web service should return an XML reply compliant with the dbGetDirectoryInfo API format. The enclosing <DirectoryInfo> </DirectoryInfo> tags are to be removed from the output.

Character encoding should be UTF-8.

Use "SugarCRM" for the Source field in order to have a different icon in net.Desktop.

Example:
   <DirectoryEntry>
      <login></login>
      <ext>123</ext>
      <fn>Daisy</fn>
      <ln>Chain</ln>
      <site></site>
      <grp></grp>
      <dep>department</dep>
      <profile></profile>
      <status></status>
      <dp></dp>
      <sp></sp>
      <email>daisy.chain@example.com</email>
      <mobile>00474123456</mobile>
      <fax>0026860900</fax>
      <home>0026860900</home>
      <pincode></pincode>
      <company> </company>
      <office> </office>
      <source>SugarCRM</source>
   </DirectoryEntry>

2. SOP API module (XPA001)

Configuration

The remote data source has to be declared. This can be done by adding the IP address of the data source server to the list of SOP IP addresses in the SOP API module.

After adding the IP address of the remote data source, the API module should be reinstalled.

This is to be done on every SOP where the external contacts should be available.

Mentioning SOP A in the SOP API module of SOP B will not in turn proxy the API request to the servers defined on the level of SOP A.

Other resources

Copyright © Escaux SA