The ISC

by Helen Heyns

Overview

The Integrated Services Component is also known as the ISC.

Before you start using ISC there are some things to consider:

Terminology

Terminology can vary, for example, Customers are also known as Clients, and Callers also known as Contacts.

Vivantio Support Team

Contact the Vivantio Support Team or your Vivantio Consultant to discuss any concerns.

Permissions

To perform a Contact Synchronization with the Active Directory (AD) you will require the necessary permissions. You will also need to know where the ISC is going to be installed - will it be on the same server on the AD, or somewhere else, depending on your internal policies.

Migrating Customers

For Migrating Customers with the AD already installed on the Service Desk you will need to create a new link with the ISC.

It is important to note to give the same instance name as the previous AD connector link, if these differ, you will have duplicate contacts.

When some customers migrated from Vivantio Service Desk to Vivatio PRO / ITSM they retained the old legacy Custom Fields from Vivantio Service Desk for a variety of reasons.

There are limitations to these old legacy custom fields, such as:

They can't be used in Business Rules
They can't be used in Roles and Permissions
They can't be exposed to the Self Service Portal
They are not supported in the new FLEX UI in any capacity

Vivantio will run a script to migrate the data from these legacy custom fields to the current supported custom fields built into Vivantio PRO / ITSM.

The process will be:

For Tickets, Clients, Callers and Locations a new Custom Form called 'Additional Info' will be copied across, including all historic data
The old legacy custom fields will be disabled and no longer used or accessible within the application

Limitations:

Any reports that use the old legacy custom fields will need changing as those legacy fields will still appear in the reports but would not reflect the data held in Vivantio PRO / ITSM
Any email templates that use the old legacy custom fields will need changing as those legacy fields could still appear in the emails but would not reflect the data held in Vivantio PRO / ITSM
Anyone who uses the Vivantio ISC to download data will need to be careful as those legacy custom fields will still appear in the extracts but would not reflect the data held in Vivantio PRO / ITSM

SQL Experience

For Asset import you will need to create the SQL script to select and the Assets and Fields you wish to import. You will need to access the SQL Database and Tables and also need to know the credentials for this process. For the export of data, you will need to know the SQL connection string for your own Database with the required tables and fields to map the data too.

If you have any difficulties configuring this, please contact the Vivantio Support Team or your Vivantio Consultant who can guide you through the process and answer any questions.

Introduction to the ISC

The ISC is an application you install on your own servers to connect your local systems to the Vivantio SaaS Platform. It allows you to schedule tasks to pull data from or push data too your Vivantio SaaS Instance.

The ISC can be installed via the Setup Wizard using the Download Integration Services Component button.

Navigate to the Admin Area > Integration & API > Downloads

To download, follow the instructions in the Setup Wizard, clicking the Next button to progress through the 5 screens, this only takes a minute or so to reach the Finish button in the Wizard.

Once installed the ISC has a range of different options for integrating with external systems.

You can install it on your Active Directory Server and Synchronize directory information with Vivantio with the Caller Synchronization.
You can export data via SQL code on a scheduled basis.
You can import Assets via SQL code into the Vivantio Asset system area on a scheduled basis - this includes connecting to a SCCM.
You can Sync your locations.
You can Sync your Clients.

Do you have a Proxy Server?

If your organisation uses a proxy server to access the internet, then it may be necessary to configure the ISC to use the proxy when sending data to Vivantio through the integration tool.

If this is the situation, please raise with your Vivantio Implementation Consultant or the Vivantio Support Team so that we can work with you to configure the ISC appropriately.

Credential Manager

The first time you launch the configuration utility you will be asked to provide Web Service Credentials; these settings control the behaviour of the directory connector and must be provided before you can continue.

The Credential Manager can be viewed and modified at any time by selecting Manage Credentials from the Vivantio Task Scheduler.

To prevent malicious and unauthorised access to the Web Service, it is secured with a Username and Password.

If you are using the Vivantio SaaS Platform, please contact a member of your internal Vivantio Support Team to obtain the login credentials.

If you have an onsite installation, then the login credentials can be configured locally in the helpdesk.config file.

This file can be found in the following location:

[Your Installation Directory / Config / Helpdesk.config]

Caller Synchronization

Introduction to Caller Synchronization

Vivantio AD Connector is a software component that can read any LDAP based directory. such as Microsoft Active Directory and then add, update or remove Contact records in Vivantio.

Once configured the utility can read the AD on a periodic basis, automatically maintaining the Contacts within Vivantio. The directory connector service allows the directory connector to run automatically in the background and carry out automatic synchronization on a scheduled basis.

By default, this service is stopped after installation.

Warning: 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.

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 populated when the sync runs and saved in Vivantio. These fields are especially useful for line managers approvals in workflows.

For example <manager.email> for the manager's email address or <manager.givenName> <manager.sn> for the Managers firstname and surname respectively.

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.

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.

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.

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 is needing to be synchronized you'll need to provide a LDAP attribute that it maps too. LDAP attributes must be enclosed in angular brackets.

This MSDN Article provides a list of all attributes available in AD.

To help with the mapping process there is a Preview and 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.

You do not need to click Save until the final tab is configured. 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 and 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.

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.

Occasionally, you may need to transform the data in someway before inserting it into Vivantio. An expample of this is the ClienID 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 LDA attribute.

Below are the director fields:

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 values that you would like to be inserted into Vivantio Service Desk
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, where the Edit Task button can be selected to return back to the Sync tab to click the Sync button which will now be available to you.

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.

Data Exports

The Integrated Services Component (ISC) contains a task entitled Scheduled Export, which provides you with the capability of exporting data in SQL format. The data is exported by table and your SQL database details are required to enable access to the fields and tables.

Configuring a Scheduled Export

From the Task Scheduler, Select the button to Add Task

Select the Scheduled Export option from the drop-down list and click OK

Add the credentials in to the Export Scheduler Configuration screen

Enter the name of the Export and tick the box to enable the Export
Choose the Data Source Credential from the drop-down box
Choose a table to export from the drop down, each table is contained as a separate export
Select SQL from the Destination Type drop down, SQL is the only option available to you for exporting
Enter your connection string (which accesses your local database), the subject headers exist in t

Example of a Windows Authentication connection string:
Data Source=(local)\SQL_NEW_2012;Integrated Security=SSPI;Initial Catalog=Demo_Import;
Select ‘Test Connection’ to confirm the configuration entered so far is correct
Create a new Destination Table, e.g. if you are creating a Ticket Export then enter the name ‘Ticket’
In the Field Mappings, select Auto Map in the bottom left hand corner of the screen, which will populate the box above the button
Click Save

Schedule the Export from the main Task screen, on a daily, weekly or monthly basis. The best practice when you are first creating a scheduled export is to set it up to run weekly to make sure all data is exported in the first scheduled run and this doesn’t overlap with the second scheduled run. This scheduled can be changed later to run daily if required.

Client and Locations

The importing of your clients are managed in the ISC for update on a scheduled basis using SQL code. The Clients and Locations will link to the Callers record using the Contact Email address and the Location name.

Select Client Synchronization from the Task Type and click OK.