Download Altiris eXpress Helpdesk API Overview

Altiris eXpress Helpdesk
5.1 API Overview
Technical White Paper
July 10, 2001
Altiris Product Strategy
Technical White Paper: Altiris eXpress Helpdesk API Overview
1
Copyrights & Trademarks
©2001 Altiris, Inc. All rights reserved. The Altiris logo, logotype, and eXpress are
trademarks of Altiris, Inc. All other trademarks are properties of their respective holders.
TECHNICAL WHITE PAPER .....................................................................1
EXECUTIVE SUMMARY ...........................................................................2
PROJECT OVERVIEW ..............................................................................3
1.0
Introduction ..................................................................................3
2.0
Architecture ..................................................................................3
3.0
Getting Started..............................................................................4
USING THE AEXADOHELPDESK CLASSES ...............................................5
4.0
General Information ........................................................................... 5
MANAGING HELPDESK DATA .................................................................7
USING THE AEXHDVBS WORKITEM CLASS .............................................8
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
2
Executive Summary
Help desk organizations continue to face the need to customize existing applications in
order to better meet business critical needs. However, budgetary concerns generally
limit the amount of customizations organizations are able to perform. Organizations
need solutions that are easy to customize in order to increase the number of
customizations projects that are performed in-house.
This white paper provides the needed documentation to better understand the Helpdesk
API structure that will support automatically raising work items within Helpdesk, as well
as other things. The ability to automatically raise work items will help streamline and
facilitate the awareness and resolution of IT issues, and increase overall effectiveness
and customer satisfaction.
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
3
Project Overview
1.0
Introduction
Altiris eXpress Helpdesk is a multi-tier application that presents information stored in a
SQL Server database through a user interface developed using the Altiris AppWeaver
presentation technology.
This document describes how to use the Application Programming Interfaces (APIs) that
are part of Helpdesk to access the data stored in the SQL database, including how the
SQL database is organized so programmers can access and modify Helpdesk data
directly at the SQL Server level.
Readers and users of this information should have a strong understanding of the
following technologies and capabilities (in no particular order):

COM+/MTS

Visual Basic (VB) and VBScript (all examples use these two languages)

Microsoft SQL Server 7.0 and SQL 2000 Transact-SQL

Relational database theory

Helpdesk functionality as exposed through its UI
Helpdesk supports several powerful modes of customization based on AppWeaver
capabilities to allow customers to modify the functionality and look and feel of a
Helpdesk installation. These capabilities are not discussed here.
Note:This document is based on Helpdesk 5.1.020. Some documentation points may
change with future releases of Helpdesk. Therefore, it is critical to correlate the
documentation with the specific product version.
2.0
Architecture
Helpdesk functions are installed in two DLLs that contain COM objects written in VB plus
numerous Windows Script Components (.wsc files) that are responsible for the
functionality exposed in the user interface. The DLLs are:
 AeXHelpdesk.dll – Altiris eXpress Helpdesk User Services.
The COM classes defined in this DLL use and rely on services provided by AppWeaver.dll
– Altiris AppWeaver Web Application Library. They cannot be used except in the context
of an AppWeaver application, and in particular, Helpdesk. They are of no interest to
developers interested in accessing Helpdesk data using ADO recordsets. They are
designed to be used by Helpdesk commands that want to manipulate Helpdesk
information using AppWeaver data structures and services.
 AeXADOHelpdesk.dll – Altiris eXpress Helpdesk Business Services.
These COM classes provide access to all Helpdesk information stored in the SQL Server
database. These classes permit callers to create, update, retrieve, and in some cases,
delete Helpdesk information. All functionality provided in the Helpdesk UI is provided
using these classes. These classes are invoked by the AeXHelpdesk COM objects to
perform all the operations provided by the Helpdesk UI without exception.
AeXADOHelpdesk classes have methods and properties that are common, such as the
ConnectionString property and the ability to return extended error information from ADO
via the GetLastError method. Most of the methods defined by these objects require
typed arguments and use ByRef output parameters to return information to the caller
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
4
rather than using the return value of the method. ADO Recordset objects are used
extensively as the primary means to pass information in and out of the SQL Server
database. AeXADOHelpdesk objects are not AppWeaver-aware objects – they do not use
AppWeaver services.
The classes generally represent the major functional objects of Helpdesk: work items,
contacts, managed objects, bulletins, email messages, etc. However there are
exceptions that will be explained below in the Using AeXADOHelpdesk Classes section.
One exception we mention here are the classes that perform importing and publishing
data to external sources, such as Microsoft SMS and Altiris eXpress Notification Server.
These classes are invoked and called by other AeXADOHelpdesk objects to import data
or publish work item information. These classes are included in the DLL as a matter of
convenience – they do not fully follow all the conventions defined for the other classes.
There is a third DLL that ships with Helpdesk: AeXHDVBS.dll. This DLL currently provides
a single COM class called Workitem that exposes a few methods and properties using
Variants for input and output parameters instead of the typed parameters used by the
adoHDWorkitemBS class. Its methods simply wrap the same methods in
adoHDWorkitemBS, allowing non-types languages like VBScript to use that object to
create work items. Future versions of the DLL may provide other classes that wrap other
AexADOHelpdesk classes to allow VBScript programmers to manipulate other Helpdesk
data: contacts, managed objects, etc. Currently, programmers must use Visual Basic or
Visual C++ or other languages that support COM early-binding to access any
functionality other than creating a work item.
Finally, Helpdesk functionality exists inside SQL Server databases configured as
Helpdesk databases by the Helpdesk Configuration Wizard. Besides the fully-normalized
set of tables that contain all Helpdesk data, there are views that hide the details of the
relationships among these tables and there are many stored procedures that govern
these relationships and actually perform all inserts, updates, and deletes that can be
performed through the Helpdesk UI. In fact, there is only one hardcoded SELECT
statement in the AeXADOHelpdesk classes (not including the two source classes
mentioned above – each of these has one additional SELECT).
Everything AeXADOHelpdesk classes do to the database is done using stored procedure
calls. However, the AeXADOHelpdesk classes may make several calls to perform a given
operations and certain features such as e-mail notification are controlled by logic in the
classes, not by what the stored procedures do.
3.0
Getting Started
First, decide at what level you need to access and manipulate Helpdesk data. We
assume here that you are not customizing the Helpdesk UI, but instead you need to
access Helpdesk data and perhaps create or modify Helpdesk objects such as work items
or contacts.
You have several options:
1. Use the AeXADOHelpdesk classes.
2. Use Transact-SQL directly to access the Helpdesk database with SELECT
statements and stored procedures calls.
3. Use AeXHDVBS Workitem class to create work items in Helpdesk.
4. Use AeXADOHelpdesk classes to create or update Helpdesk objects, use
Transact-SQL to do SELECT statements to retrieve information.
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
5
Clearly, option 3 is only good if creating work items is all you want to do.
For options 1 and 4 you must be able to use VC++, VB, or other language that supports
early binding. Be sure to reference the AeXADOHelpdesk.dll in your project so you can
see the classes it supports.
We recommend option 1. We do not recommend calling the Helpdesk stored procedures
directly in general, although most are atomic operations. Future versions of the
Helpdesk database may rename stored procedures, or delete them. We reserve the right
to change the database tables, views, and stored procedures at any time. We intend to
preserve and maintain the interfaces for the classes of AeXADOHelpdesk, however, so
you may use those with a greater degree of confidence than simply executing random
SQL statements against the database.
At the current time, the only option for VBScript writers is option 3, which only permits
creation of work items. Future versions of AeXHDVBS may include more wrapper classes
as demand warrants.
Using the AeXADOHelpdesk Classes
4.0
General Information
Here is a table of the classes defined in AEXADOHelpdesk:
Name/ProgId
Description
adoHDBulletinBS
Create, update, delete bulletins
adoHDContactBS
Create, update contacts
adoHDEmailMsgBS
Create, update e-mail messages.
Process work item updated notifications.
adoHDManagedObjBS
Create, update managed objects.
Registration, import, auto-update, and publish to/from sources.
License management.
adoHDNSSource
Notification Server import, source management
adoHDOrganizationBS
Create, update organizations
adoHDQueryBS
Retrieve named query.
Execute SQL queries are return results
Create, update, delete worker queries
adoHDSmsSource
SMS import, publish, source management
adoHDWorkerBS
Create, update workers
adoHDWorkitemBS
Create, update work items.
Add, update, and delete Workitem-WUCIs.
Add attachments.
adoHDWUCIBS
Create, update delete WUCIs (Workitem Update Custom
Instances)
dctHDTagBS
Create, retrieve, update tag collections
These classes can be divided into two groups: the *BS classes and the *Source classes.
The *BS classes have a property and certain methods in common. Similarly, the *Source
classes share some methods. Generally speaking, methods with the same name, such as
Create and Update, operate the same way across all classes.
The *Source classes are not intended to be invoked by external programs with some
exceptions related to how Helpdesk displays source-specific information in the Register
Source command. In the discussion that follows, we are referring to the *BS classes
unless otherwise specified.
Since we are now discussing actual operations, we use the word “object” to refer to an
instance of a class created using a CreateObject or New call.
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
4.1.
6
ConnectionString Property
All *BS classes have the following read/write property:
ConnectionString(sValue As String)
sValue is an ADO connection string that fully identifies the Helpdesk SQL Server and
database. This property must be set before any other method is called for each object.
To repeat, this property is not shared or remembered in any way, you must set it each
time after you create the object. For example:
Dim oBulletin as adoHDBulletinBS
set oBulletin = New adoHDBulletinBS
' set the connection string
oBulletin.ConnectionString = sConnString
You can get the connection string from the Helpdesk registry key or construct it yourself.
Here is a sample:
Provider=SQLOLEDB;SERVER=aztek;DATABASE=HD;Trusted_Connection=yes;Network
=dbmssocn;
The Trusted_Connection=yes parameter means that the identity of the Altiris eXpress
Helpdesk package will be used to access the SQL Server database. This is usually what
you want. If for some reason you want to use a named SQL login and password then
replace TrustedConnection=yes; with USER=user;PWD=password; and make sure that
SQL Login has sufficient authority to perform whatever operations you intend. We do not
recommend this alternative.
4.2.
Return codes
Almost all *BS methods are VB functions that return a 32-bit integer (a VB Long) as a
return value. The COM enum HDConsts contains all possible return codes. The value
adoHDOK is the most common and it means the method/function was successful.
adoHDOK has the value 1000.
4.3.
GetLastError Method
All *BS classes expose this method:
Public Function GetLastErrors(ByRef errLast As ErrObject, ByRef errErrors As
ADODB.Errors) As Long
This function returns an Err object that represents the last error encountered by the
previously executed function and also, if that function executed ADO commands (as
most do), what ADO returned in its Errors Collection. See ADO documentation for more
details about that collection and its members.
4.4.
Recordsets and ADO details
All ADODB.Recordsets returned from method calls are client-side, disconnected, and
updateable recordsets. ADO Connections are made and destroyed tightly around each
ADO Command that is executed and do not persist from one method call to another. Use
GetLastError immediately after a method call returns a failure code, i.e. not adoHDOK,
to retrieve any ADO error information.
4.5.
Retrieving Helpdesk data
The adoHDQueryBS object is used to retrieve data from Helpdesk, including data that
can be manipulated by other objects such as work items, but also data that does not
have any other sort of API, such as the priority lookup list and other lookups.
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
7
Helpdesk maintains a table of named queries that retrieve all Helpdesk data. This table
is not manageable through adoHDQueryBS: Currently, you cannot create, update, or
delete entries in the query table.
Use the Retrieve function to get a Recordset that contains the SQL expression:
Public Function Retrieve(ByVal sQueryName As String, ByRef rsResult As
ADODB.Recordset) As Long
The Recordset will contain one row with three fields, one of which is the SQL
expression<table of field returned>. This expression could be any kind of Transact-SQL
statement, such as a stored procedure call, but is usually a SELECT statement. After
retrieving the query you want, you can modify it before executing it. Helpdesk User
Services provides a robust filtering API that can create useful WHERE clauses and
ORDER BY clauses. In many cases, however, the retrieved query can be used without
any further modification. This is particularly true of the queries that return lookup lists.
Therefore, callers only need be aware of the nature of the SQL query when they want to
modify it.To execute a query use one of these functions:
Public Function ExecuteSQL(ByVal sExpression, ByRef rsResult As ADODB.Recordset) As
Long
Public Function ExecuteLimitedSQL(ByVal sExpression, ByVal sCountExpression, ByVal
nRowsToReturn As Long, ByVal nRowsToSkip As Long, ByRef nTotalResult As Long,
ByRef rsResult As ADODB.Recordset) As Long
ExecuteSQL will simply return the entire Recordset. This is most useful for queries that
return a small amount of data. ExecuteLimitedSQL is useful when you want only a partial
result set, for example, to display in a grid or a table.
Managing Helpdesk data
4.6.
Create/Insert/Update methods
Most *BS objects have Create, Insert, and Update methods. Some have more than one
of each kind, with additional information tacked onto the name, such as
adoHDWorkitemBS.CreateAttachment.
All of these functions work in a similar way. Create returns a Recordset that has one row
in it that contains all the fields that a caller is allowed to populate. Callers populate some
or all of those fields and then call Insert, passing back the populated Recordset. Insert
typically returns in place a Recordset that includes additional fields that are associated
with the item that was just inserted – lookup values, modified date/time fields and such.
This occurs when the item being created participates in views across multiple tables:
work items, managed objects, and contacts. The actual field names are not different.
Updates are performed as follows:
 Retrieve a specific Helpdesk item Recordset using adoHDQueryBS. Modify the fields.
 Get an empty Recordset of the same type using the appropriate Create method.
 Copy all fields from the modified Recordset that exist in the empty Recordset into the
empty Recordset.
 Call the Update method passing the now populated Recordset.
This may seem clumsy compared to a more direct kind of API, but this technique allows
these classes to handle their data with only minimal knowledge of its structure. New
fields can be added or old fields modified in the database without affecting these classes
at all because they don’t really know what is inside the Recordsets they deal with. There
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
8
are some exceptions, such as the fields that serve as primary keys, and special fields
like the workitem_comment field.
Each class has quirks or special semantics that relate to the actual purpose of the data it
is managing. Most of the classes have additional methods to provide secondary features
such as licensing support.
Using the AeXHDVBS Workitem Class
--------------------------------------------------------------------------------------------------------------------Here is a snippet of code that demonstrates using the VBScript support object:
set oADOWorkItem = CreateObject("AeXADOVBS.Workitem")
' set the connection string
' RC3 and later - if you are running on the IIS Server
' then you don't need to do this
oADOWorkItem.ConnectionString = sConnString
' a full connection string with TrustedConnection=yes
' or USER and PWD values
' get an empty recordset with all fields in a workitem
' defaults are already filled in.
set rsWorkitem = CreateObject("ADODB.Recordset")
lRet = oADOWorkItem.Create(rsWorkitem)
' 1000 means OK
if lRet <> 1000 then
' ug - error handling
else
'field names match the fields in workitem_only_view
' note you have to set the *_lookup_id fields, you can't
' use direct names like "ASAP", but must use database ids.
' The lookup ids are defined out the box and so can be trusted
' unless the users change them by hand using Enterprise Manager - not
recommended
rsWorkItem("workitem_start_on") = Date
rsWorkItem("workitem_title") = sTitle
rsWorkItem("workitem_comment") = sComment
' this field is required!
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.
Technical White Paper: Altiris eXpress Helpdesk API Overview
9
' It can be the id of a virtual worker or the guest worker
' but it can't be zero.
' You may need to hardcode a worker id after examining the
' worker table in the database to see what
' the id for a particular one is
rsWorkitem("workitem_created_by_worker_id") = sWorkerId
lRet = oADOWorkItem.Insert(rsWorkItem)
if lRet = 1000 then
' ok, did a good insert,
' the recordset has its id and number field set
else
' error happened.
end if
end if
' be a good citizen
set oADOWorkItem = nothing
Conclusion
We have presented an overview of the Helpdesk API’s to increase the general
understanding of the Helpdesk structure, and more specifically, to enable administrators
to automatically raise work items within Helpdesk from third party products. A more
detailed training can be provided by Altiris Professional Services in order to accomplish
objectives specific to your business environment.
This White Paper has been produced by Altiris, Inc. It is owned and controlled by Altiris, Inc.
and is only to be distributed according to the guidelines of the Altiris Product Resource kit.