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 ITRP to avoid having to maintain this information manually in two systems.
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 ITRP.
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 ITRP. 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 ITRP, 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 email@example.com Active Directory Frank Williams Widget USA Sales Executive Chicago Sales Office Room 202 en-US Central Time (US & Canada) 0 firstname.lastname@example.org 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
ITRP 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 email@example.com telephone mobile +1 (713) 441 8299 1 firstname.lastname@example.org telephone work +33 (1) 4703 5144 1 email@example.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
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
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
ITRP ID column to update existing contact details.