Directory Services

The Import API is commonly used to establish an integration with Microsoft Active Directory or another LDAP directory service. Most organizations already maintain their employee information in a directory service. It therefore makes sense for an organization to integrate its directory service with R-Service to avoid having to maintain this information manually in two systems.

Important Some directory services also support SCIM Provisioning , which makes it possible to send user data to R-Service without the need to roll your own integration.

Integrating With Directory Services

Most organizations only have one directory service from which data need to be extracted for the maintenance of the Person records in R-Service.

Even though information about organizations can be obtained from a directory service, it is normally easier to maintain the Organization records, and the hierarchical relations between them, manually in R-Service. That is because the structure of an organization does not change very often. When organizations have tried to automate the maintenance of their organization structure using the data from a directory service, the result is often that too many organization records get generated because of inconsistencies in the way that organization names have been written in the directory service.

When a People import file is prepared, however, it is still important to detect and address such inconsistencies in the naming of organization in the directory service. If the Organization that is specified in the People import file does not exist in R-Service, then the generation or update of this Person record will fail.

To import a Person record, only a few field values are required in the import file (see People API - Fields . The example below shows how the columns could be populated using data from a directory service.

Primary Email      Source      Name    Organization  Job Title    Site      Location  Locale  Time Zone      Time Format 24h
frank.williams@widget.com  Active Directory  Frank Williams  Widget USA  Sales Executive    Chicago Sales Office  Room 202  en-US  Central Time (US & Canada)  0
pierre.lefevre@widget.com  Active Directory  Pierre Lefèvre  Widget France  Account Manager    Paris Sales Office  Room 312  fr  Paris        1

Note that in the example above the Primary Email is used as the unique identifier for the people in the import file. This makes it possible for the directory service to update a Person record without knowing its ID ( see Create or update ).

After the People have been imported, the CSV or TSV file with the contact details of these people can be imported. Before starting the People Contact Details import, however, use the polling feature to make sure that the People import has completed and that it was successful.

The example below demonstrates how the Primary Email is used in the Person column of a People Contact Details import file to ensure that People can be identified uniquely using data only from the directory service.

Person        Contact Protocol  Contact Label  Contact URI    Address Label  Address Address    Address City  Address State  Address Zip  Address Country    Integration
frank.williams@widget.com  telephone    mobile    +1 (713) 441 8299                              1
pierre.lefevre@widget.com  telephone    work    +33 (1) 4703 5144                              1
pierre.lefevre@widget.com                  home    14 Rue de Seine    Paris        75006    FR      1

If one or more rows of contact details are defined for a Person in the import file and the Integration value is set to true (or 1 ), then all existing contact details of that Person, which Integration value is also true , will be removed during the import. Any contact details that were manually added for this Person (i.e. contact details which Integration value is false ) will not be removed during imports.

Note that contact details which Integration value is true cannot be modified manually. It is possible, however, to use the Import API to change the Integration value of contact details from true to false or vice versa.

Important : Make sure all contact details for a Person are grouped together in the import file. Otherwise the last row of contact details in the import file will cause the previous contact details, which were added during the import for that same Person, to be removed.

If needed, it is also possible to specify the ID column to update existing contact details.