Overview
Using the Integrated Services Component (ISC) you can integrate Vivantio with any LDAP based directory, such as Microsoft Active Directory to populate Callers/Contacts in Vivantio, in other words your end users. There are lots of advantages to doing this; the caller list is kept up to date by automatically adding, updating or removing records as specified in the task. This means new staff can be automatically set up with access to raise tickets via the portal or email and line managers email details can be brought in to manage approval processes. The synchronization is one way, changes to Vivantio callers will not appear in the Active Directory.
Once configured, the caller synchronization task can be scheduled to run automatically in the background and on a regular basis.
Brief Instructions
Install the Integrated Service Component and register Vivantio credentials
Create Caller Synchronization Task
Add the Active Directory Details
Select the records to import from the Data Source Tab
Map the Active Directory Fields to the Fields in Vivantio
Requirements
- The ISC must have been installed in a location able to access the Active Directory, this will depend on your internal policies. For the download instructions please click this link
- If the ISC is not installed on the local domain controller for the Active Directory you will need to provide the location of Active directory
- A specific account which has permission to read the Active Directory, this can be the active account if the ISC is installed locally.
- Custom forms and fields should be created for any additional data required e.g. managers name and email address.
Warnings
To avoid loss of data in Vivantio, it is recommended that you leave the service stopped while you're becoming familiar with the configuration utility and the settings that are contained within it. Link to AD is read only and only Vivantio data is ever updated. Only once you have found a configuration that you are happy with should the service be started. By default, this service is stopped after installation.
It is also possible to use a special syntax to reference fields from a user's manager within AD. In AD each user can have a single manager configured. Information from the user's manager can be referred and referenced within the AD connector by specifying a prefix of manager. in the field mappings. These will then be evaluated when the sync runs and saved in Vivantio. These fields are especially useful for line managers approvals in workflows.
For example <manager.mail> for the manager's email address or <manager.givenName> <manager.sn> for the Managers firstname and surname respectively.
Create a Caller Synchronization Task
Main Window and Tasks
The main window provides information about the current state of the AD sync tasks. The menu options allow the run, view, add, edit and deletion of tasks.
When adding a task, it is necessary to select the type of task.
It is possible to create and run more than one AD Sync task, however, it is highly recommended that only 1 AD sync be set up to avoid the possibility of creating duplicate contacts.
Editing a Caller Sync task opens the Caller Sync form.
Adding the Active Directory Details - General Tab
Now we can configure the AD integration settings and start with the General Tab.
The General Tab allows you to define the instance name, which Web Service Credentials are to be used, AD location and the domain account details that will be used to read the AD.
Please Note: The domain account must have permission to read the AD.
The directory location section allows you to specify the location of the LDAP directory that you wish to connect too. If your local domain controller hosts the directory you can simply select the local domain controller option; alternatively select the specified location option and enter the location into the text box. This can either be an IP Address or the Host Name of the Server.
The directory authentication section finds how the directory connector should connect to the LDAP directory. If you are using Microsoft AD and are logged into a local domain, you can often select the active account option, this option will take the credentials from your Windows account and use them to access the LDAP directory. Alternatively, you can select the specified account option and provide a Username and Password. The authentication mode drop down allows you to specify an authentication mode for connecting to the LDAP directory. The correct mode varies between different directory vendors and will also depend on your particular configuration, for Microsoft AD the Kerberos Authentication mode is a good starting point.
If you are having trouble connecting to your directory, please contact the Vivantio Support Team or your implementation consultant.
Data Source
The Data Source identifies the directory nodes to include during synchronization. The tree view on the Data Source tab allows you to specify which LDAP nodes you want to include during synchronizations (e.g. which Organizational Units or OUs).
The Filter box at the top of the Data Source tab allows you to provide a filter string that will limit the results returned when querying the LDAP directory. This is useful, for example, if you need to exclude certain users or only include certain types of users.
The following list contains some common examples of LDAP Search Filters:
- Exclude any users with name John Smith
(&(!givenName=john)(!sn=smith)) - Only include users who have an email address property
(mail=*) - Only include users who have a surname property
(sn=*) - Exclude any users with the name administrator
(!cn=administrator) - Exclude any disabled user accounts
(!userAccountControl&2<>2)
The actual field names used in your LDAP directory may vary.
For further information about the LDAP search filter syntax please refer to the MDSN Article
For further information on which specific account control values mean and how to use them please refer to the Microsoft Knowledge Base
Field Mappings
In the Field Mappings tab, it is possible to specify how fields in the LDAP directory are mapped to fields in Vivantio. For each Vivantio field that you would like to synchronize you'll need to provide the LDAP attribute/s that it maps too. LDAP attributes must be enclosed in angular brackets.
You can look up the attribute by using the Active Directory Attribute Editor tab to find the attribute name which corresponds to the value you are trying to map (see below). This MSDN Article provides a list of all attributes available in AD.
To help with the mapping process there is a Preview / Test button that will be displayed, and you can see a subset of the results.
Please Note: that a link to Contacts and their corresponding Customer and / or Locations that the LDAP attribute value must exactly match the Vivantio customer reference or Location name values in Vivantio. These can be populated manually before the sync, via manual entry, an import or an integration.
Clicking Save will take you back to the ISC Task List and you will need to edit the AD Task to re-enter the integration settings, Preview / Test is sufficient here.
Composite Field Mappings
Sometimes it is not possible to get all of the data you need from a single LDAP field, an example of this is where first name and surname are stored in separate fields. In these situations, you can use a Composite Mapping by concatenating 2 or more fields. For example <givenName> <sn> will bring in the given name and surname of your caller to the Caller Name field. Vivantio will suggest some common mappings when you open the Field Mappings tab which you can overwrite.
Another more advanced example of using Composite Mappings is if your LDAP directory doesn't store the email address. You also know that the email addresses within your company follow the format firstname.surname@vivantio.com for example, so you could provide a contact email mapping: <givenName>.<sn>@vivantio.com.
Occasionally, you may need to transform the data in someway before inserting it into Vivantio. An example of this is the ClientID field, it is unlikely that you will have an ID for your LDAP directory that is meaningful to Vivantio, instead you may have some Client Reference or some Client Name. In this situation you need to perform a ClientID Lookup as part of the mapping by opening up the Lookup field mapping window (with the button to the right of the field). Within the Lookup field mapping it is also possible to specify values to appear in Vivantio based on a value of LDAP attribute. The example above shows how you can map Locations AD values to Vivantio location reference numbers.
To set these mappings up
- Enter the LDAP directory field that will be used to provide the data (Do not include angular brackets here)
- When Value = In this column, enter the values that can be found in the LDAP directory
- Set Value To In this column, enter the reference values that you would like to be inserted into the Vivantio field. For example if the Department is Finance and its reference number value is 003, you would record 003.
- Default Value If the value found in the LDAP directory does not match any of the values provided in the When Value = column, the default value will be used instead
Sync
In the Sync Tab the data is greyed out until the screen has been saved. Once Save has been selected you will be taken back to main Task Scheduler screen. Edit Task to return back to the Sync tab and click the active Sync button.
A full Sync will be performed here and once complete a message will appear to confirm the number of successful contacts.
Please Note: If the sync is performed from the main screen, then this will perform a part sync, in which the changes and differences from when the last full sync was performed and now will be made.
In Vivantio you will now be able to see these new Callers in the CRM. Set up lists and tabs to organise the new data.
Scheduling Updates
When you are happy with the sync you can schedule regular updates to you callers by clicking on the Schedule/Notification button and choosing how often you want the sync to happen. You can only add notifications if you have set up an email contact under SMTP settings.
Reviewed: 08 March 2023