Customising the Helpdesk Resource Syncronisation for Contacts

The simplest way for organisations using Notification Server to populate their Altiris Helpdesk with users and computers is to use the built-in syncronisation feature in the Altiris Console. Once enabled, this will keep your Helpdesk user and computer data current with hourly syncs.

There is a problem though which emerges in this synchronisation scenario: any data corrections made by Helpdesk staff to name, email and phone number fields are reset on each synchronization. This is because the Helpdesk staff are not editing the Notification Server data (which assumed to be the authoritative data source), but are instead making their changes to the Helpdesk contact data directly, which is assumed to be non-authoritative.

This article provides a solution to this issue by editing the underlying SQL which governs the syncronisation.

Synchronisation and the Databases

The Altiris helpdesk is at its core an incident management product which was acquired from Tekworks in 2001. Instead of integrating this product directly into the altiris database used by Notification Server, it was decided to keep the Helpdesk separate with its own database, altiris_incidents, so that it could be implemented as a standalone product.

This design choice meant that the Helpdesk should not rely on data being available from NS to function. In the event though that NS was present, Altiris implemented a syncronisation mechanism to allow data gathered by inventories to flow into the Helpdesk as user contacts and assets.

Benefits of enabling syncronisation

By default, the syncronisation mechanism is an ongoing operation. This keeps a regular flow of data from the NS database (altiris) to the Helpdesk database (altiris_incidents) so that your helpdesk data is live. Syncing allows new user and computer data to flow into the Helpdesk as and when they are discovered by Notification Server.

An added advantage in syncing the databases is that the computer-user associations are also passed through to the helpdesk. The dominant user on any computer, the primary user, is marked as having an association with it. When this information syncs to the helpdesk, it simplifies ticket creation -once user is specified within the ticket, the user's asset associations are instantly available in the drop-down list for selection. Very neat.

Enabling Syncronisation

The integration between NS and the Helpdesk is pretty good -enabling syncronisation is as easy as ticking a check-box.

You can enable the syncronisation of assets and users from NS to the Helpdesk, by navigating to the Console page 'Resource and Incident Data Syncronisation'. This can be found under,

Configuration Tab
  -> Server Settings
   -> Notification Server Settings
    -> Incident Settings

Click to view.

Checking the syncronisation checkbox on the above 'Incidents Settings' page will initiate an hourly sync by default. You can view the results of this sync operation by opening the Altiris log view and filtering the entries on AlertManager.AutoUpdate (AlertManager is the program that governs the Helpdesk processes. So, whenever you see AlertManager, think Helpdesk..).

The User and Contacts Tables

To understand why syncing can lead to problems when it comes to maintaining contact information in the helpdesk, lets take a look at the user tables.

When you create a new user in Notification Server from the Resources tab within the Altiris Console, you are presented with a form detailing the fields in the vUser view from the altiris database. You can create a new user by navigating to,

Resources Tab
  -> Resource Management
   -> Resources
    -> Organizational Types
     -> User

In the right-hand pane, you then have the option of clicking the yellow star to create a new user manually.

Click to view.

When you create a new contact in the Helpdesk from the Incidents tab within the Altiris Console, you are presented with a form detailing the fields in the Contact table in the altiris_incidents database. You can create a new contact by navigating to,

Incidents Tab
  -> Contacts
   -> New Contact
In the right-hand pane, you are presented directly with the form to create a contact manually.

Click to view.

Looking at the fields within these tables shows something quite surprising -there is not a full one-to-one correspondance between the contact data in the Helpdesk and the user data in NS.

The graphic below highlights the relevent fields in both tables and the process by which data is transferred from NS to the Helpdesk during a sync.

Graphic showing the process which creates contacts in the helpdesk from users in NS. Notice how some data (like postal address) in the vUser view is not migrated at all to the contact table. Also notice how some fields in the contact table have no equivalent in the vUser view, such as the other_emails field.

Key: The plus flow-diagram symbol shows where one set of data may be chosen over another (OR). The cross flow-diagram symbol shows where data is combined (AND).

Click to view.

The syncronisation algorithm for contacts can be summarised as follows,

1. Any user found in the NS database which does not have a contact counterpart in the Helpdesk is created according to the following criteria,
   • The NT_ID for the contact is built from the users Name and Domain scavenged from NS
   • The contact's name is taken from the users Display Name where this exists, otherwise the contact's name is built from the user's Given Name and Surname.
   • Other fields populate as depicted in the above graphic
2. For pre-existing contacts, if the user data in NS differs from its contact counterpart in the Helpdesk, the contact data will be updated with the authoritative NS data. Contact data without a mapping to user data in NS is not affected.

It is this updating process which presents a problem. A common helpdesk scenario is that perhaps a user's primary email, telephone number, or indeed name is incorrect and requires updating. If the Helpdesk staff were to edit directly throught the helpdesk interface (the most intuitive route) it would appear to be ammended only to be reset within the next hour. This is most frustrating. And it happens even if the data stored in the user information is blank.

So, the most obvious route is to get the Helpdesk staff to update the authoriative source in NS right? Well, as it turns out this doesn't work out to well. If the Helpdesk staff ammended the user data directly (which has its own complications), the change would only be visiable after the next sync. This makes the life of the helpdesk staff somewhat confusing.

One resolution then is to change the algorithm that NS uses to sync this data to the helpdesk.

Customising Contact Synchronisation

The process which manages the importing of assets and contacts from Notification Server across to the Helpdesk is called the Alert manager. How this process makes its decision on how it updates contacts and assets is based on the results of the SQL queries found in the \AexHD\templates\nssource.xml file on the server. The file is split into the following sections,

• Comment
  A full explanation of what I paraphrase in the sections below.
• autoupdate_mergepurge_asset
  Query to find assets which have been imported into the Helpdesk at some point, but no longer exist in Notification Server.
• autoupdate_sql_1
  Query to find Resources in Notification Server which are either not currently stored assets, or are stored as assets but with details which require updating. This query is in fact multiple queries within IF clauses as the actions to perform depend on the solutions installed.
• autoupdate_mergepurge_contact
  Query to find contacts which have been imported into the Helpdesk at some point, but no longer exist in Notification Server.
• autoupdate_contact_sql_1
  Query to find users whom either don't exist as contacts in the Helpdesk, or do exist as contacts but need their contact details updating. Updating means syncing the contact data so that it matches the NS data.
• autoupdate_association_sql
  Query to find any and all NS Resource Associations between an imported contact and an imported asset.

The query then which we seek to change is therefore in the autoupdate_contact_sql_1 section as this deals with the updating of contacts. Lets take a close look at the top of this code which determins what fields are selected,

select 
  i.Guid as resource_guid,
  isnull(i.Email, N'') as contact_email, 
  (case 
      when ivgu.[Domain] is not null then i.[Domain]+'\'+i.[Name]
      else N''
  end) as contact_nt_id,
  (
    case 
      when i.[Display Name] = '' and (i.[Given Name]= N'' and i.[Surname] = N'') and i.[Email] = N'' then isnull(i.[Name],N'')
      when i.[Display Name] = '' and (i.[Given Name]= N'' and i.[Surname] = N'') then i.[Email] 
      when i.[Display Name] = '' then i.[Given Name] + ' ' + i.[Surname]
      else i.[Display Name]
    end
  ) as contact_name, 
  isnull(i.[Company] , N'') as contact_company,
  isnull(i.[Department], N'') as contact_department,
  isnull(i.[Office Location], N'') as contact_location,
  isnull(i.[Office Telephone], N'') as contact_phone, 
  isnull(i.[Mobile], N'') as contact_cell_phone, 
  isnull(i.[Pager], N'') as contact_pager, 
  isnull(i.[Job Title], N'') as contact_title
from .....

Here we see the contact fields being built up from the data in the i tables (an alias for vUser), in accordance to the vUser-Contact table mapping diagram in the User and Contact Tables section of this article.

In this code, we see that the vUser fields are authoritative -that is the contact fields are simply overwritten with the data in VUser. Our task is to ammend this code, so that should the contact data be ammended by the helpdesk staff this data should stick through the next sync.

Making Contact Email Changes Authoritative

The line in autoupdate_contact_sql_1's SQL which governs how contact_email should be set is,

isnull(i.Email, N'') as contact_email,

This code says set contact_email to the contents of vUser's Email field (the isNull command ensures that if Email is Null, then contact_email recieves an empty string instead of a Null).

So, lets put a condition on this. Lets set the contents of contact_email to vUser's Email field only when the contact_email is empty.

In SQL we then replace the original line above with the following,

(case
  when len(isnull(cv.contact_email,N'')) > 0 then cv.contact_email
  else isnull(i.Email,N'')
  end
  ) as contact_email,
  

Making Contact Telephone Changes Authoritative

The line in autoupdate_contact_sql_1's SQL which governs how contact_phone should be set is,

isnull(i.[Office Telephone], N'') as contact_phone,

This code says set contact_phone to the contents of vUser's Office Telephone field (the isNull command ensures that if Office Telehone is Null, then contact_phone recieves an empty string instead of a Null).

In a similar fashion as we just did with email, lets set the contents of contact_phone to vUser's Office Telephone field only when the contact_phone is empty.

In SQL we then replace the original line above with the following,

(case
  when len(isnull(cv.contact_phone,N'')) > 0 then cv.contact_phone
  else isnull(i.[Office Telephone],N'')
  end
  ) as contact_phone,
  

By proceeding through the SQL in this manner, we can make any number of the contact fields authoritative, forcing them to stick through updates.

Good Practice

Here are some extra tips to save you pain,

• Backup your original nssource.xml to nssource.xml.orig so that you always have an clean XML file to return to if things go awry
• nssource.xml will likely be restored to its original form during repairs and upgrades. Once you've made your changes to nssource.xml, keep a copy of this safe as nssource-cust.xml
• In preparation for a system repair/upgrade, turn off syncing. Check after the upgrade that your nssource.xml is intact before reinstating incident syncing.
• Test your revised xml/SQL code on a development system first.. ;-)

If you try this out, I would really appreciate it if you dropped me a line. I can see me sticking with these types of code changes until the holy grail of a fully integrated NS and Helpdesk emerges. So, feedback is most welcome.

Kind Regards,
Ian./