Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Microsoft Access wikipedia , lookup
Concurrency control wikipedia , lookup
Entity–attribute–value model wikipedia , lookup
Extensible Storage Engine wikipedia , lookup
Microsoft Jet Database Engine wikipedia , lookup
Relational model wikipedia , lookup
Open Database Connectivity wikipedia , lookup
Clusterpoint wikipedia , lookup
Microsoft SQL Server wikipedia , lookup
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.