Service Desk Web API Technical Guide Introduction The Service Desk Web API is the Java programming interface to the Service Desk application. It allows you to write custom Java code to use Service Desk functionality. The primary reason for developing the Web API is to allow you to build your own Web applications around the Service Desk core. The Service Desk Server Pages subsystem is a Java Service Pages application that uses Java servlets that are built with the Service Desk Web API. In addition to building Web applications, the Web API can also be used for integrating Service Desk with local applications, and to add new unique functionality to their Service Desk implementation. The Web API not only allows you to develop Intranet applications around Service Desk, it also opens up the Service Desk application, its object model and its data, to your specific needs. You use the Web API to integrate any Java application with Service Desk. Using the Web API in commands that can be called from a Service Desk smart action, or from a database rule action, gives you many opportunities to customize how processes are implemented using Service Desk. You can define alternative assignment algorithms, automatically close items if related items have been closed, and much more. This guide assumes that you have a sufficient knowledge of Service Desk and Java to understand its contents. Only superficial knowledge is needed to understand the introductory material at the beginning of this guide. The goal of this guide is to transfer knowledge of the Web API, not to teach you Java or Service Desk. If you can write and run simple Java programs and you know what Service Desk is about, this guide will help you. If you want to learn Java programming, refer to a Java book. If you want to know more about Service Desk and its concepts, refer to the Service Desk Users Guide and the Service Desk Administrator s Guide. To understand the details of Web API programming, you will need to have administrator-level knowledge of Service Desk. However, in many cases the structure of the Service Desk client application can help you in understanding the Service Desk object model. This guide s intention is to transfer technical information about the Web API and its use. The first few sections (up to installation) deal with technical concepts. They are aimed at anyone who wants to gain a technical understanding of the Web API. The rest of this guide is intended as technical guidance for programmers. To compile and run the examples that come with the Web API, and that are discussed in this guide, you need a Java development environment and a working Service Desk installation. Refer to the Service Desk Installation Guide for more information. Contents of the Web API package The Web API is delivered as a single Java.jar file, with some accompanying documentation. Apart from base java functionality included in the Java Runtime Environment (JRE) and extra functionality that you might need for your specific application, the only prerequisite for building your own extensions to Service Desk Copyright 2002 Hewlett-Packard Company.
using the Web API is the Web API.jar file. To test and run the software that you develop with the Web API, you also require a working installation of Service Desk. To compile and run the Service Page example, you need the Java2 Development Environment and a working Service Pages installation. Although you need a Service Desk somewhere on the network to use the Web API, a Service Desk installation is not required on computers that only run Web API applications. In a standard Sun JDK environment, you can add the full name of the.jar file to the CLASSPATH environment variable, or you can explicitly add it to the class path in the invocations of the compiler and of the applications. Refer to your Java Development Environment documentation for information on how to add the Web API.jar file to its class path. To use the Web API.jar file with the Sun JDK, you can use commands similar to the ones shown below: set CP=":C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\web-api\lib\webapi.jar" javac -classpath %CP% com\hp\itsm\api\examples\example1.java java -cp %CP% com.hp.itsm.api.examples.example1 localhost jeffp servicedesk With a functional Java Development Environment and a Service Desk installation, the Web API.jar file by itself should be sufficient to build and run Web API applications. For convenience, the distribution contains JavaDoc documentation of the API and a set of simple examples that clarify some of the concepts of the Service Desk Web API. You can use them as the starting point for your first Web API application. Refer to the installation instructions below for more details. The installation of a Java runtime environment, or a Java development environment (such as the Sun JDK), or Service Desk is beyond the scope of this guide. Please refer to the Service Desk Installation Guide. Architecture This section presents a short overview of the Service Desk architecture and the role of the Web API in that architecture. Although not everything presented here is directly relevant for understanding the Web API itself, it might be helpful in obtaining a better understanding of the mechanism under the hood of the Web API, and the design of applications that optimally fit in the architecture. As an interactive application, Service Desk uses a three-tier architecture: Interactive client: communicates with the application using the ITP protocol. Application server: communicates with the database server via the JDBC API. ITP is a communication protocol that is specific to Service Desk. Its details are not relevant to this discussion. The database server is a third-party off-the-shelf product and, as such, the database system itself and the interface of the Application Server to the database system are not relevant to this discussion. So, physically, Service Desk uses the usual three-tier architecture. Logically the functionality of Service Desk is divided over a number of layers. Below is a schema of the logical layers and the communication between them: Copyright 2002 Hewlett-Packard Company 2
Figure 1: Service Desk Logical Layers and Their Communication Presentation Workflow Business Repository Data Access Data Storage The presentation layer displays information on the computer screen. It also allows the user to enter information. From an application point of view, the presentation layer embodies very little logic. All Service Desk-specific concepts are implemented in the workflow layer. The workflow layer is the implementation of the Service Desk object model and of application logic that is expressed in terms of the object model. The base classes of the workflow model implement the more frequent patterns in the relationship between sets of objects. Some of these patterns are those that can be found in almost any business application (such as one-to-many or one-to-one relationships). Others are more specific to Service Desk and workflow applications (such as History lines). The workflow layer keeps the state of the Service Desk application for a particular user that logs into Service Desk. All information that passes from the user to the database passes through the workflow layer. This allows the workflow layer to enforce the logic of the object model. The workflow layer also retrieves data for the user. When doing so, it does things such as retrieving objects that are referenced by the object that the presentation layer retrieves for the user. The business and data access layers implement the interaction of the workflow layer with external resources, such as the database and mail delivery agents. The workflow layer never accesses external resources directly. The business layer in the application server, as defined in Service Desk, accesses the resources from the workflow layer. It also executes database rules. In the Service Desk application, the presentation and workflow layers are physically situated in the interactive client application process. Because both the presentation and the workflow layer use the repository, the interactive client consults the repository over the network the first time it needs some piece of repository information. In this setup, sessions are long and repository information is cached, so the overhead of retrieving repository information over a network connection is Copyright 2002 Hewlett-Packard Company 3
relatively low. The business and data access layers are executed in the Application server. That is, most of the state of a user login session is kept in the GUI client process. The little state information that is used in the application server process is used for keeping track of the login session and authorization. Note: some exceptions, that are beyond the scope of this introductory discussion, do exist. From the Service Desk point of view, a Web API application is a client of the Service Desk application server, even when it serves a different client. However, the distribution of the logical layers over the physical processes is different; the workflow layer is executed in the application server. This means that most of the state of the client session is kept in the Service Desk application server, and that the client application does not need to query the repository to implement the Service Desk object model. The Web API offers a set of Java classes and methods that implement the concepts of the Service Desk object model by remotely invoking the workflow layer in the application server. Therefore, although many of the functions in the Web API look like database functionality, the logic of the workflow layer is still activated when you submit a whole object to be saved via the Web API. It is treated as if the values came from a form in the Service Desk client GUI application. The business layer executes database rules in the same way as with the GUI client. The User interface rules are not relevant when you use the Web API. This means that interactive per field data validation is not implemented by the Web API itself. If you want to validate individual field values in a Web API application, you will have to validate them with handcrafted custom code in your application. You might wonder about the role of the Service Desk agent. It gets its commands from the Application Server, and even when the programs that it executes are interactive, it is not relevant in a discussion of the architecture of the Web API. In other words, a program started by the agent that uses the Web API has the same features and restrictions that apply for any other program. Important: note the remarks about logging below. Programming Considerations The Web API is designed for transaction-based applications. The typical example is the intranet application: a user fills out forms and browses data, and all the application logic is implemented inside transactions that receive the user input and return some data. The data is intended for the user s immediate consumption. Additionally, in a low to medium volume situation, the Web API can be used to implement database rule actions. The purpose of this section is to point out some limitations of the Web API when it is used in a non-typical scenario. Not made for field-by-field validation Although it requires some effort, it is possible to build applications that do not fit in the scenario described above. However, the performance of non-typical applications might very well be sub-optimal. If you want to use the Web API for a different purpose than it was designed for, you should be aware of some of the disadvantages before you design and build your application. Copyright 2002 Hewlett-Packard Company 4
The Service Desk Web API is designed for transaction-based applications. As most of the information that the Service Desk GUI client uses for field-by-field validation is available through the Web API, you could write your own field validation code and incorporate it in your application. However, GUI rules are not available. You should realize that all Web API calls are made over the network and that, for performance reasons, you will have to limit the number of mini-transactions you make to perform field-by-field validation. Realize also that the need for catching exceptions and their proper handling remains, even if you check user input extensively. You can never rely on the database content when you make a transaction, and an exception is waiting around the corner all the time. Anyway, you should be ready to handle it properly and, beyond a certain point, trying to prevent it is just a waste of effort. Not appropriate for Service Desk GUI client rule implementation Trying to use the Web API to program GUI rules for input validation in the Service Desk GUI client application is not only very difficult, it also has several severe disadvantages. Some of these disadvantages come from the fact that you start a Java Virtual Machine for very small checks, and that the application has to log into the application server every time for something small task. As a result, performance will suffer. Some of the disadvantages come from the fact that you access the same database as the GUI client, but via a different access path. Therefore, it will be very difficult to avoid database concurrency issues (such as locking conflicts) between the two programs, as well as failed transactions because the one program changes a database record that the other thinks it owns. Not optimal for bulk exchange Applications that use the Web API to update or consult the database on a much larger scale than on-line transaction processing, may suffer from performance problems. The Web API only allows you to add entity instances to the database one-by-one via the IEntityHome.openNewEntity().. IEntity.save() path. When you feed a large number of entities to Service Desk with the Web API, this causes Service Desk to validate every entity instance individually, and to perform the insertion of the individual entities as separate database transactions. For medium-volume data feed applications, this might not be a problem. However, when you use the Web API to feed a lot of data to Service Desk at once, performance will suffer. In the other direction, a similar restriction applies. The Web API returns sets of entity instances in arrays. For a high volume-at-once application, the size of the arrays would become prohibitive. Either many attribute values are returned with the arrays and the arrays will consume a lot of memory, or the attributes are fetched over the network one by one. Both situations are unsuitable for large-scale data extraction. From the point of view of performance, Service Desk data exchange is superior to the Web API for bulk data exchange. Authentication Web API applications need to log in to an application server with an account and a password. You can use any account that is authorized to use the Web API. For an efficient use of licenses and conservative security, it may be wise to create a special user for the Web API as a whole, or for the separate applications that use it. Copyright 2002 Hewlett-Packard Company 5
A Web API application receives the permissions of the user that is logged in with the current session. When using the Web API as an extension mechanism to Service Desk this may sound too restrictive; you are inside application code, so why not trust the application itself to check permissions? After all, you as a programmer know what you do. On the other hand, any user could invoke a Web API application, or worse, write a malicious application and then invoke it. Web API sessions are not thread safe Neither the ITP communication protocol that is communicating with the workflow layer on the other side, nor the state information are thread safe. Do not share sessions between threads. When you consider this from a design point of view, you realize that this is almost unavoidable. When a session is used to communicate with the workflow layer in the application server, it builds up a context with a state. Another thread that uses the same session will change and probably destroy the state. Therefore, do not share sessions between threads. To avoid concurrency issues, do not use more than one session for a transaction. Allow for concurrency issues Service desk uses optimistic concurrency control. This means that your application can read data that has been read by other users. The advantage is that all data is accessible at every moment. The disadvantage is that Service Desk and the database system have to make decisions about the validity of the database updates at the moment that they are submitted. An object stored in the database that has been changed by another user before you have the possibility to save it is a possible cause for transactions to fail. Your application design must retry important transactions that fail. Initialisation is expensive A Java program that opens a Web API session, does a few simple things and then exits, has the advantage that it is easy to understand and easy to debug. However, if your application invokes this kind of program with varying frequency, there may be a performance problem. Loading and starting a Java virtual machine is probably more work than executing your small program. In addition, once your small program is started, logging into the Service Desk application server is probably more expensive than the actual application actions of your small program. An application that frequently uses the Web API for relatively small transactions must not use separate Java programs that open and close sessions to the application server. You should try to build programs that live longer and that use just one session during their whole lifetime. Be careful with logging Some of the examples use System.out.println() to inform you of the execution progress. For simple command line applications, such as most of the examples, this is the simplest and, therefore, the appropriate way to produce output. However, if you use the Web API to implement database rule actions or to write servlets, severe disadvantages exist. In the best case, your output can be lost. In the worst case, uncontrolled output will hang your serve (e.g. when the Program pops up a dialog and only continues after the 'OK' button is pushed). Rule actions, programs that are started by the Service Desk agent, do not have their standard output connected to a suitable medium. Therefore, they should not use standard output. Copyright 2002 Hewlett-Packard Company 6
If your application produces informative output of the System.out.println() type, ensure that it is redirected to a log file every time it is used as a rule action. Be aware that there are concurrency issues with the log file. When two rule actions execute simultaneously, their output is mixed. To avoid this, use a unique file name. For example, one based on the functional ID of one of the entity instances involved. Remember that it is your responsibility to clean up the log files at some point. In a servlet, use one of the GenericServlet.log() methods to produce log application progress information, or to signal error situations. This is a way to produce logging information in a Servlet Container. Run simple tests Be aware that running Service Desk rule actions and Java Http servlets is a complex subject. While it is not difficult from a technical point of view, every time that you install software in the context of an environment, your unfamiliarity with the environment greatly complicates your work. Therefore, before you build a rule action or a servlet, test your code in a simple stand-alone command line program. If you encounter any difficulties, go back to your simple command line program. A frequent cause of problems with rule actions is that the Service Desk agent is not running, or that it was never even installed. Installation The Web API installation location is C:\Program Files\Hewlett- Packard\OpenView\service desk 4.5\web-api. On Unix, this is /opt/ov/sd/web-api. Installation on Microsoft Windows: 1. Locate the sdwebapi-4.5.exe installer executable in your distribution. 2. Run it. 3. The following files (among others) are extracted from the zip file: C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\web-api\lib\web-api.jar, C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\webapi\javadoc\index.html, and C:\Program Files\Hewlett- Packard\OpenView\service desk 4.5\webapi\examples\web-api-examples.zip. Installation on Solaris: 1. Locate the file sdwebapi-4.5.pkg in your distribution. 2. Run the following command as root: pkgadd d /where/you/found/it/sdwebapi-4.5.pkg. 3. The following files (among others) are extracted from the pkg file: /opt/ov/sd/web-api/lib/web-api.jar, /opt/ov/sd/webapi/javadoc/index.html, and /opt/ov/sd/webapi/examples/web-api-examples.tar. Installation on HP-UX: 1. Locate the file sdwebapi-4.5.depot in your distribution. Copyright 2002 Hewlett-Packard Company 7
2. Run the following command as root: /usr/sbin/swinstall s /where/you/found/it/sdwebapi-4.5.depot 3. The following files (among other) are extracted from the depot file: /opt/ov/sd/web-api/lib/web-api.jar, /opt/ov/sd/webapi/javadoc/index.html, and /opt/ov/sd/webapi/examples/web-api-examples.tar. Installation on Linux (Using rpm): 1. Locate the file sdwebapi-4.5.rpm in your distribution. 2. Run the following command as root: rpm i /where/you/found/it/sdwebapi-4.5.rpm 3. The following files (among others) are extracted from the rpm file: /opt/ov/sd/web-api/lib/web-api.jar, /opt/ov/sd/webapi/javadoc/index.html, and /opt/ov/sd/webapi/examples/web-api-examples.tar. The file C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\web-api\javadoc\index.html is the root of a JavaDoc documentation system. Open it and review the amount of technical reference information. You now know where to look for documentation when you work on your Service Desk Web API projects! Select a folder location for the Web API development examples. In the examples, the locations c:\web-api folder (Windows) and $HOME/web-api (UNIX) are assumed. Most of the text below refers to the c:\web-api folder. Substitute your chosen folder name in the discussed examples. Some of the scripts that come with the examples explicitly refer to the default installation location for the web-api.jar file. We assume that you installed it in the default location, so you do not have to change the scripts. If the folder where you want to install the examples does not already exist, create it. Then extract the archive file C:\Program Files\Hewlett- Packard\OpenView\service desk 4.5\web-api\examples\webapi-examples.zip. The discussion below assumes that you are working with the examples in the folder c:\web-api. On Windows: Double click the C:\Program Files\Hewlett- Packard\OpenView\service desk 4.5\webapi\examples\web-api-examples.zip file to extract its contents to the c:\web-api folder with Winzip or a similar program. Alternatively, use the following command in the c:\web-api folder to extract the examples from the command line: jar xvf C:\Program Files\Hewlett- Packard\OpenView\service desk 4.5\webapi\examples\web-api-examples.zip Copyright 2002 Hewlett-Packard Company 8
On UNIX (sh): cd && mkdir p web-api && cd web-api && tar xvf /opt/ov/sd/web-api/examples/web-api-examples.tar Your directory now is a directory tree with examples. You will find a few scripts and a tree with example sources rooted in the com domain. Open the compilex.bat (UNIX: compilex.sh) script with Notepad or a better editor. Check that the class path in the commands points to the jar file in the Service Desk web-api\lib folder. Then invoke the compile script to compile the programming examples. This is to check that the installation was successful. All programming examples should compile without any problem. If you have any problems: 1. Check that the Java Development Kit (JDK) and the Java Runtime Environment (JRE) are installed. 2. Check that the programs in the bin directory of the JDK can be found via the PATH environment variable. 3. Check the value of the JAVA_HOME environment variable. It should point to the JRE. 4. Check that the versions of the JDK and the JRE match. The script simply compiles the example programs. For serious development work, you will probably need to build files that can be used with make or ant. You might also want to add a g switch to the compiler command to include information in the class files for a Java debugger, such as jdb. Open the runex1.bat (UNIX: runex1.sh) script and check the class path in the java command. Make sure that it points to the jar file in the Service Desk webapi\lib folder. Invoke the script and check that when you receive any errors, these concern the working of the application, and NOT the Java runtime system. For Java or connection related error messages: 1. Check the issues relating to the compiler again. 2. Check the class path in the script again. 3. Check the server name in the script. If it is not localhost check it twice. 4. Check that the Service Desk application server is actually running on the server machine. For applications or permission related error messages: 1. Check that the Service Desk application server is actually running on the server machine. 2. Check that the demo data was installed in the Application Server database. Finally, to run and test your applications, you need a valid Service Desk account for the application server. The account does not need to be a UI account. It is recommended that you do not use the system account for development purposes. This forces you to consider entitlement from the beginning. The scripts that invoke the example programs use accounts and data from the Service Desk demo database. Copyright 2002 Hewlett-Packard Company 9
Now you have installed a simple Web API development environment. In the rest of this guide, we will use this environment to compile and run the examples. Although you will probably copy its contents to your favorite Java development environment, we will assume that you are using the Sun JDK when providing instructions. Your first Web API application In this section, we will write a very simple Web API application. It is a simplification of example 2. The application logs into the Service Desk Application Server, retrieves a service call by number, and displays some of the properties of the service call. The source for this example is not part of the distribution. Refer to Example 2 for a similar application. The first step is to log into Service Desk. We will have to provide a network location where Service Desk can be reached, a user name and the password. On success, the Web API returns an ApiSDSession instance that implements a connection to the workflow layer in the application server. // 1 package com.hp.itsm.api.examples; // 2 import com.hp.itsm.api.*; import com.hp.itsm.api.interfaces.*; public class Example2 { public static void main(string args[]) { ApiSDSession session = null; try { // 3 session= ApiSDSession.openSession( localhost, olsek, servicedesk ); } catch (RuntimeException e) { // 4 System.out.println(e.getMessage()); return; } 1 By convention the Web API examples belong to the com.hp.itsm.api.examples package. 2 To use the Web API, you need to import the classes with the basic types and interfaces of the Web API. 3 Open a session to the application server on the current machine. User olsek with password servicedesk is provided in the Service Desk demo database. 4 If logging in fails, the Web API or the application server throws an exception. It never returns null. The Web API throws only one type of exception: the RuntimeException. The message in the exception should be good enough to present to the user. In all cases, the level of severity is high enough to simply try to exit elegantly from the application. Trying to recover does not make much sense. Copyright 2002 Hewlett-Packard Company 10
Now that we have a session, we can use it to ask the session for the service call home object. Home objects are discussed in some detail in the programming concepts section. For this introductory example, we treat the entity home as an interface to the database that allows you to store and retrieve objects from the database. // 5 IServicecallHome schome = session.getservicecallhome(); // 6 try { IServicecall servicecall = schome.openservicecall( 1234567 ); } catch (RuntimeException e) { System.out.println(e.getMessage()); return; } // 7 String labeldescription=schome.getlabeldescription(); // 8 System.out.println( labeldescription+ ": "+ servicecall.getdescription(); 5) Obtain the home for service calls from the session. 6) Retrieve a particular service call. The number that identifies the service call is known from some external source. Because this call retrieves an object from the database, it can fail. Indeed, it will almost certainly fail with the silly number 1234567. Therefore, catch the possible runtime exception. In this example, it suffices to print a message and exit. 7) Ask the Service call home for a label to identify the description field of the service call. 8) Print the description field of the service call. Examples As mentioned in the installation section, the Service Desk Web API comes with a number of example programs that illustrate some of the concepts of the Web API. The details of the examples are explained in Java comments in the source files. The examples are made up of three packages: The programming examples are in the com.hp.itsm.api.examples package. We just installed the example development tree in c:\web-api, so the programming example source files and class files can be found in the folder c:\web-api\ com\hp\itsm\api\examples. Some more application-oriented examples are contained in the com.hp.itsm.api.cases package. Java servlet examples are provided in com.hp.itsm.api.servlets. Example1.java Use the compilex.bat script to compile the programming examples. Use runex1.bat to run example 1 with the Service Desk demo database. Copyright 2002 Hewlett-Packard Company 11
The example shows how to open a session to the Service Desk application server. It retrieves the account information object from the session object for the user that owns it. This illustrates how to retrieve a related object with the Web API. It then extracts and prints various properties of the account. This illustrates how to retrieve properties of an object. The example obtains all persons that use this account. This illustrates how to obtain a set of related objects via a one-to-many relationship. Example2.java Use the compilex.bat script to compile the programming examples. Use runex2.bat to run example 2 with the Service Desk demo database. This example shows how to open an existing service call when you know its functional ID. It illustrates the concept of entity home objects and how to use an entity home object to retrieve a particular entity object. In this example, a service call. The example retrieves the history lines belonging to the service call. One of the properties of a history line is the date of its creation. Service Desk stores dates in doubles. The Web API offers methods to convert doubles to Java dates and to represent them as strings. The example illustrates some of these methods. Example3.java Use the compilex.bat script to compile the programming examples. Use runex3.bat to run example 3 with the Service Desk demo database. Create a new problem, set some properties of the problem, and save it. Optionally, you can provide the name of a template. If there is a template with that name and the template actually is a template for problems, the template is used to initialize the fresh problem. Finally, add a history line to the problem. The retrieval of the template shows how to use an entity home object to retrieve all entity objects belonging to that home object with a particular value for one of the properties. The creation of the problem object is an example of the use of entity home objects and templates to create fresh objects. The invocation of the save() method of the fresh problem is an example of storing fresh objects in the database. Adding a history line to the problems illustrates the way to add an object to a one-to-many relationship. Additionally, this example shows how to load all objects belonging to a certain home into an array. The example verifies the applicability of the template to problems. This is a rather advanced example of runtime type checking in Service Desk Web API applications. Example 9 illustrates another way of obtaining the templates for certain kinds of entities. Example4.java Use the compilex.bat script to compile the programming examples. Use runex4.bat to run example 4 with the Service Desk demo database. Open an incident. Change the information field of the incident, and assign the incident to a person. The example illustrates application-defined queries that are built with a Copyright 2002 Hewlett-Packard Company 12
where clause object and search criterion objects. It also shows how to access the aggregated assignment object in the incident and how to update the assignment. Aggregated objects are stored in the same record in the database as the object that they belong to. Finally, the incident is saved to the database to show how modified objects, including the aggregated sub objects, are saved to the database. Example5.java Use the compilex.bat script to compile the programming examples. Use runex5.bat to run example 5 with the Service Desk demo database. This is another example of handcrafted selections with where clauses and criteria. Because the selection is on a date field, it also illustrates some of the date manipulation methods. Example6.java Use the compilex.bat script to compile the programming examples. Use runex6.bat to run example 6 with the Service Desk demo database. The example briefly illustrates the concept of a view. Views are a means to reduce the amount of information in a home object that is visible to the application. Unlike selections that are made with where objects and search criteria, views are not built dynamically. The description of a view is stored in the repository, and the application refers to a view in the repository to retrieve the information that belongs to the view. In the Service Desk application, views can limit the number of available fields. In this example, only the selection of the set of objects that is retrieved through the view is relevant. Using a view has the benefit that you can define very complex filters using the service desk GUI, while the programming for selecting the data using the API remains very simple. Example7.java Use the compilex.bat script to compile the programming examples. Use runex7.bat to run example 7 with the Service Desk demo database. This example shows how to use Web application profiles to control the set of attributes that is returned by the methods that return an array of entity instances. It illustrates the concept of the IwebApiApplication and demonstrates its importance for performance. Example8.java Use the compilex.bat script to compile the programming examples. Use runex8.bat to run example 8 with the Service Desk demo database. Illustrates the use of relationships in the Service Desk Web API. It scans the membership relationship between persons and workgroups. Is then makes a new workgroup and relates some persons to it. Finally, it deletes the new workgroup. The purpose is to show you how to use many-to-many relationships. Example9.java Use the compilex.bat script to compile the programming examples. Use runex9.bat to run example 9 with the Service Desk demo database. Copyright 2002 Hewlett-Packard Company 13
This example shows how to use reflection via the IEntityInfo interface to get a display name for a kind of entity and to get a list of applicable templates. Some more application-specific examples can be found in the com.hp.itsm.api.cases package. Having installed the example development tree in c:\web-api, the application case source files and class files can be found in the folder c:\web-api\dev\examples\com\hp\itsm\api\cases. RelateSCtoChange.java Use the compilec.bat script to compile the application cases. Use runcase1.bat to run this application case with the Service Desk demo database. The example relates an existing service call in the database with an existing change. RelateSCtoProblem.java Use the compilec.bat script to compile the application cases. Use runcase2.bat to run this application case with the Service Desk demo database. The example relates an existing service call in the database with an existing problem. SetFolderToCaller.java Use the compilec.bat script to compile the application cases. Use runcase3.bat to run this application case with the Service Desk demo database. The example tries to find the caller of an existing service call. It then sets the folder of the service call to that of the caller or that of their organization. SetSLA.java Use the compilec.bat script to compile the application cases. Use runcase4.bat to run this application case with the Service Desk demo database. The example tries to find the caller of an existing service call. It then sets the service level agreement of the service call to that of the caller or that of their organization. Finally, the com.hp.itsm.api.servlets package is a Java servlet that implements an over-simplified service call management application. Having installed the example development tree in c:\web-api, the servlet source files and class files can be found in the folder c:\web-api\dev\examples\com\hp\itsm\ api\servlets. Use the compiles.bat script to compile the servlet. The use of Java servlets with the Web API is discussed in a separate section. The deployment and invocation of the servlet examples is explained in a section with detailed instructions at the end of this guide. Programming Concepts This section explains the structure of the Service Desk Web API. It does not describe the Service desk Object model. Probably the best way to get an understanding of the Service Desk object model is to browse through the Service Desk client tool. The links from one piece of information in the application to another correspond to the relationships in the object model. A detailed and navigable description of the Service Desk object model can be found on the Service Desk distribution CD-ROM. The file doc\data Dictionary\Data_Dictionary_Items.htm contains more information than you will normally need. The completeness of the information largely compensates for the complex layout. Because it is generated from the same material Copyright 2002 Hewlett-Packard Company 14
as the Web API, it is bound to match the Web API. To locate specific information about the data dictionary, it is often easier to use the JavaDoc documentation for the Web API. The classes of the Service Desk object model appear as interfaces in the Web API. There is no fundamental reason for this. With a few exceptions, you can use the instances of the interfaces as if they were instances of the corresponding class. The Web API is implemented with interfaces instead of classes to force you to use the homes as an instance factory. The programming concepts of Service Desk are based on the concept of an entity. For all practical purposes, Entity is the base class of the Service Desk object model. All objects that are saved to the database are instances of the Entity class. Depending on the context, we will refer to instances of subclasses of Entity as entities or Entity instances. The Entity class (IApiEntity in the Web API), together with the corresponding EntityHome class, takes care of saving instances in the database and retrieving them. Another fundamental concept is that of the entity home. The instances of the instantiable classes in the Service Desk object model are saved in database tables. The classes of objects that are responsible for saving entities to the database are called entity homes. Additional tasks of entity homes include the retrieval of entity instances from the database, and the creation of fresh entity instances that still have to be saved to the database. Therefore, the entity home is at once a factory of entity instances and an interface to the database to store and retrieve the instances. Except for log in and log out, the Web API software is generated from the object model, and follows a rigid naming convention. With the naming convention it is relatively easy to infer the name of a method or a class from the data dictionary. In the overview documentation below, we describe the most important families of classes and methods. The intention is not to document every class and every method. The JavaDoc of the Web API is an exhaustive source of information. The structure of the Web API follows certain paradigms. The existence, name and functionality of a method are applications of the paradigms. The descriptions below deal with the families of classes and methods that come from a certain paradigm. We discuss some properties of the Service Desk classes in general, and the functionality of the methods. We try to add some programming considerations. Most names of classes, attributes and methods in the text below are not actual names of classes. They refer to the patterns that the paradigms follow. In particular, in the discussion below, the words Entity, Attribute, SimpleType, RelatedEntity, ReferredEntity, ContainedEntity, StringAttribute (And some grammatical inflections) do not refer to actual concepts. Mentally replace them with the name of actual entities, attributes and types. For example, for every entity Entity, the name of the interface that the class implements is IEntity, and the name of the interface to the entity home is IEntityHome. We will use names that refer to this convention for naming rules throughout the rest of this section. Usually, we use this notation as if the names refer to actual interfaces or methods without mentioning that the name actually refers to a naming convention rule. Copyright 2002 Hewlett-Packard Company 15
The Entity interface As explained above, entities are the equivalent to the interface to the classes in the Service Desk object model. The JavaDoc documentation that comes with this guide describes a large number entity interfaces. In this section, we give an overview of the methods defined for the entities, because not all methods exist for all kind of entities. Let us first mention the most important families of entity classes: IWorkflow Note that all objects, not just Workflow instances, are managed by the workflow layer. They have a functional record ID (for example, Service Call 1024). They contain aggregate entities for assignment and history. No system constraints on deletion exist. It is transient data (user access and status restrictions can be implemented). Non-workflow Mostly identified by a search code rather than a functional ID (CIs, have both). System constraints on deletion, static data defining the base data in the Service Desk implementation at the customer s site. For example, managed CIs, services, P&O, and so on. Codes For example, status and category texts. A list of codes can be searched from the home class you get from the entity home. For example, you can get a list of statuses from IStatusProblemHome that you can use for an IProblem instance. Aggregated entities Can only be accessed via another entity and many kinds of aggregated entities can be found inside different kinds of containing entities. For example, IAssignment instances are aggregated inside IProblem instances and inside IServicecall instances. Entity instances have attributes. Each attribute has its own getattribute() and setattribute() method. The getattribute() method returns the value of the attribute, and the setattribute() method allows you to give the attribute a value. The Java type of the attribute values can be derived from the method definitions. Attributes can be classified in five groups: Attributes that have a basic Java type. For example, String, Long, Boolean, and so on. The entity classes have getattribute() and setattribute() methods for these attributes. Attributes that are references to other entities. These attributes are called entity reference attributes. The entity classes have getreferredentify() and setreferredentity() methods for these attributes. Aggregated entities that show up as an attribute. A reference to the aggregated entity can be obtained with the getcontainedentity() methods below. Changes to the contained entity can be transferred back to the parent instance with the transfer() method of the aggregated entity instance. Attributes that reference a set of entities. For example, history lines. These attributes are called entity set reference attributes. To retrieve an array with Copyright 2002 Hewlett-Packard Company 16
references, use the getrelatedentity() methods below. To relate one object to another, use the addrelatedentity() methods below. To severe a relationship, use the unrelaterelatedentity() methods. The related entity instances have a getparententity() method to follow the reference in the opposite direction. The final category is actually a special kind of entity set references: n-m relation attributes. To retrieve an array with references, use the getrelatedentity() methods below. To relate one object to another, use the addrelatedentity() methods below. To severe a relationship, use the unrelaterelatedentity() methods. To navigate the relationship in the opposite direction, the related entities offer the same kind of methods. Table 1: The IEntity Interface Methods void addrelatedentity(irelatedentity object) [Where Entity has a one-to-many relationship to RelatedEntity] Add RelatedEntity object to the set of RelatedEntities that belong to this Entity instance. The Entity instance must exist in the database. The RelatedEntity object is saved to the database by this method. Methods of this kind exist for all one-to-many relationships. Because this is a database action, it can fail. Catch RuntimeExceptions when you invoke this method. Note that apart from physical database I/O failure, many other reasons exist for a database modification to fail. Consider validation of the attribute values, entitlement and specific checks in the business logic. Note the fact that the related entity is immediately added to the database. In the case of history lines that describe changes to the entity itself, this means that the update of the entity itself and the insertion of the history line are not executed as a single database transaction. Service Desk considers the hypothetic possibility of database inconsistency in this particular case to be less conclusive than the locking and transaction overhead resulting from embedding the modifications in a database transaction. void addrelatedentity(irelatedentity object) [Where Entity has a many-to-many relationship to RelatedEntity] Add RelatedEntity object to the set of RelatedEntities that are related to this Entity instance. Methods of this kind exist for all many-to-many relationships without any attributes. Relationships with attributes are implemented as an entity kind. The relationship is immediately saved to the database. Both the current entity instance and the related entity instance should have been saved to the database before they are related. This is a database action, so catch exceptions. Copyright 2002 Hewlett-Packard Company 17
void unrelaterelatedentity(irelatedentity object) Remove RelatedEntity object to the set of RelatedEntities that are related to this Entity instance. Methods of this kind exist for all many-to-many relationships without any attributes. Relationships with attributes are implemented as an entity kind. The relationship is immediately removed from the database. The current entity instance and the related entity instance should be related to allow you to unrelated them. This is a database action, so catch exceptions. SimpleType getattribute() Get the value of Attribute. getattribute() methods exist for all attributes that have a simple type. For example, the type of the attribute is not an entity type from the Service Desk object model. If the attribute is not set, getattribute() returns null. (No exceptions thrown) IRelatedEntity[] getrelatedentity() Load all RelatedEntities that belong to the Entity instance from the database into an array. Methods of this kind exist for all one-to-many relationships. Because this is a database action, it can fail. Catch RuntimeExceptions when you invoke this method. IRelatedEntity[] getrelatedentity() Load all RelatedEntities that are related to the Entity instance from the database into an array. Methods of this kind exist for all many-to-many relationships. Because this is a database action, it can fail. Catch RuntimeExceptions when you invoke this method. IReferredEntity getreferredentity() Get the entity instance that this attribute refers to. This follows the link in the database to a different entity instance. These methods exist for all something-to-one relationships in the object model. getreferredentity() returns null if no referred entity exists. Because following the link (if it exists) involves database I/O, catch exceptions when you invoke methods from this family. IContainedEntity getcontainedentity() Get the aggregated entity instance that is part of the current entity instance. The contained entity instance is stored in the same database record as the containing entity instance. If you make changes to the return value that you want to change, use its transfer() method to transfer them back before you save() this instance. void setattribute(simpletype value) Set the value of an attribute. setattribute() methods exist for all attributes that have a simple type. The type of the attribute is not an entity type from the Service Desk object model. Copyright 2002 Hewlett-Packard Company 18