CA Nimsoft Service Desk

(1)

Web Services Guide

7.0.6

(2)

Legal Notices

Warranty

The material contained in this document is provided "as is," and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Nimsoft LLC disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Nimsoft LLC shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Nimsoft LLC and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control.

Technology Licenses

The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license.

No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Nimsoft LLC as governed by United States and international copyright laws.

Restricted Rights Legend

If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as "Commercial computer software" as defined in DFAR 252.227-7014 (June 1995), or as a "commercial item" as defined in FAR 2.101(a) or as "Restricted computer software" as defined in FAR 52.227-19 (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Nimsoft LLC’s standard commercial license terms, and non-DOD Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR 52.227-19(c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR 52.227-14 (June 1987) or DFAR 252.227-7015 (b)(2) (November 1995), as applicable in any technical data.

Trademarks

Nimsoft is a trademark of CA.

Adobe®, Acrobat®, Acrobat Reader®, and Acrobat Exchange® are registered trademarks of Adobe Systems Incorporated. Intel® and Pentium® are U.S. registered trademarks of Intel Corporation.

Java(TM) is a U.S. trademark of Sun Microsystems, Inc.

Microsoft® and Windows® are U.S. registered trademarks of Microsoft Corporation. Netscape(TM) is a U.S. trademark of Netscape Communications Corporation.

Oracle® is a U.S. registered trademark of Oracle Corporation, Redwood City, California. UNIX® is a registered trademark of the Open Group.

ITIL® is a Registered Trade Mark of the Office of Government Commerce in the United Kingdom and other countries. All other trademarks, trade names, service marks and logos referenced herein belong to their respective companies. For information on licensed and public domain software, see the Nimsoft Monitor Third-Party Licenses and Terms of Use

(3)

Contact CA Nimsoft

Contact CA Support

For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources:

■ _{Online and telephone contact information for technical assistance and customer}

services

■ Information about user communities and forums

■ Product and documentation downloads

■ _{CA Support policies and guidelines}

■ Other helpful resources appropriate for your product

Providing Feedback About Product Documentation

Send comments or questions about CA Technologies Nimsoft product documentation to

[email protected].

To provide feedback about general CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at

(4)

(5)

Contents 5

Chapter 1: Introduction

7

Overview ... 7 Standards Compliance ... 7 Development Platforms ... 8

API Support Policy ... 8

Backward Compatibility ... 8

Chapter 2: Service Desk Web Service API Basics

9

API Call Basics ... 9

Characteristics of API Calls ... 10

Factors that Affect Data Access ... 10

Web Service Output Data Format Types ... 11

Security ... 11

Error Handling ... 11

Supported Entities ... 12

Supported Operations ... 12

General Form of the Nimsoft Service Desk Web Service API ... 13

SOAP Implementation ... 13

Chapter 3: Web Service API Calls

15

Requirements for All Calls ... 15

The Get Call ... 16

The List Call ... 16

The insert Call ... 17

The update Call ... 18

The delete Call ... 19

The relate Call ... 19

The unrelate Call ... 20

Field-level Security ... 20

Numeric Fields ... 21

Chapter 4: Determining the Type of Standard Fields

23

Enumerated Fields ... 23

Date/Time Fields ... 24

(6)

6 Web Services Guide

The ID Fields ... 25

The Cross-Reference ID Fields ... 26

Long Text Fields ... 26

System ModTimeStamp Fields ... 26

Chapter 5: Entity Specific Issues

27

Attachment ... 28 Categorization ... 28 Change Request ... 29 Communication ... 30 Configuration Item ... 30 Contact ... 30 Defined Search ... 31 Incident ... 31 Knowledge Article ... 32 Organization ... 32 Problem ... 33 Service Request ... 34 Support Group ... 35 Task Ticket ... 35 Ticket ... 36 Value List ... 37 Worklog ... 38

Chapter 6: Appendix A: Status Codes

39 Chapter 7: Appendix B: Web Services Client Examples

41

Setting up the environment ... 41

Generating the Axis2 Client code using "wsdl2java" tool ... 42

Typical API Call Sequence ... 42

get Call Client Example ... 43

list Call Client Example ... 46

insert Call Client Example ... 49

update Call Client Example ... 53

delete Call Client Example ... 57

(7)

Chapter 1: Introduction 7

Chapter 1: Introduction

This section contains the following topics:

Overview (see page 7)

Standards Compliance (see page 7)

Development Platforms (see page 8)

API Support Policy (see page 8)

Backward Compatibility (see page 8)

Overview

The CA Nimsoft Service Desk Web Services API documentation provides the information necessary to access and use the Web Services API. The Web Services API currently supports SOAP protocol.

The WS API provides a programmatic way of interacting with the Service Desk platform to access and change data for the main entities such as Tickets, Configuration Items, Knowledge Articles, etc. that are managed within the Service Desk application. To use this document, you should have a basic familiarity with software development, Web services, and the Service Desk user interface. Any functionality described in this guide is available only if your organization has been granted a Web Services access license.

If you cannot access the features you see in this guide please contact Service Desk Support.

Note: We recommendusing the SOAP UI client to interface with CA Nimsoft Service

Desk Web-Services. Please refer to http://www.soapui.org for more information about using SAOP UI client.

Standards Compliance

The WS API is implemented to comply with the following standard specifications

Standard Name Website

Simple Object Access Protocol (SOAP) 1.1

(8)

Development Platforms

Web Service Description Language (WSDL) 1.1

http://www.w3.org/TR/2001/NOTE-wsdl-20010315

Development Platforms

The API has been validated to work with J2EE 1.6 and Apache Axis2 development environments. In this document we provide examples in Java. The Java examples are based on Apache Axis2 1.5.1 and JDK 1.6. For more information about Apache Axis2 1.5 refer to http://axis.apache.org/axis2/java/core/

API Support Policy

We recommend that your new client applications use the most recent version of the Service Desk WSDL file to fully exploit the benefits of richer features and greater efficiency. You can fetch the most recent WSDL by accessing the Service Desk Web Services URL.

For example, you may obtain the Service Request WSDL by going to this URL- http://{servicedeskcontexturl}/webservices/ServiceRequest?wsdl.

Note: The exact URL depends on the instance that you are accessing. Please contact the support team for the exact URL.

Each time a newer version of Web Services is released, use the following steps to quickly regenerate the client code from an existing WSDL document:

■ Regenerate the client stubs using WSDL2JAVA utility

■ Update Client Class from existing/latest version of WSDL document

■ Compile & Run the Client Class

Backward Compatibility

Nimsoft does not guarantee that an application written against one WS API version will work with future API versions. Changes in method signatures and data representations are often required as we continue to enhance the API.

However, we strive to keep the API consistent from version to version with minimal changes (if any) required to port applications to newer API versions.

(9)

Chapter 2: Service Desk Web Service API Basics 9

Chapter 2: Service Desk Web Service API

Basics

API Call Basics (see page 9)

Characteristics of API Calls (see page 10)

Factors that Affect Data Access (see page 10)

Web Service Output Data Format Types (see page 11)

Security (see page 11)

Error Handling (see page 11)

Supported Entities (see page 12)

Supported Operations (see page 12)

General Form of the Nimsoft Service Desk Web Service API (see page 13)

SOAP Implementation (see page 13)

API Call Basics

API calls represent specific operations that your client applications can invoke at runtime to perform tasks, for example:

■ Query data in your organization.

(10)

Characteristics of API Calls

All API calls are:

Requests and Responses: Your client application prepares and submits a request to the Service Desk Web Service via the API, the Service Desk Web Service processes the request and returns a response, and the client application handles the response. Synchronous: Once the API call is invoked, your client application waits until it receives a response from the service. Asynchronous calls are not supported.

Committed Automatically Versus Rollback on Error: By default, every operation that writes to a Service Desk object, is committed automatically. This is analogous to the AUTOCOMMIT setting in SQL.

For create(), update(), and delete() calls that attempt to write to multiple records for an object, the write operation for each record is treated as a separate transaction. For example, if a client application attempts to create two new accounts, they’re created using mutually exclusive insert operations that succeed or fail individually, not as a group.

Factors that Affect Data Access

When using the API, the following factors affect access to your organization’s data:

■ Your organization must be enabled for WS API access, and the user attempting to access the WS API must have the "Web Service" license type.

■ Whether your configured permissions allow access to the data. Your client application logs in as a user to the Service Desk Web Service. The profile associated with the logged-in user grants or denies access to specific objects and fields in your organization.

■ When an application logs into the API, all transactions are run as the user who logs in. Therefore, to protect the security of your data, give that user (the logged-in user) only the permissions needed to successfully execute all the calls made by the application.

■ Whether a particular change would compromise the referential integrity of your organization’s Service Desk data.

■ Whether a given field in an object can be updated or not. For example, read-only fields cannot be changed in create() or update() calls.

■ Rules for custom objects-such as fields that are configured in the Service Desk user interface to be unique or required are automatically enforced via the API.

(11)

Web Service Output Data Format Types

The following standard data format types are supported by CA Nimsoft Service Desk via the HTTP protocol:

■ JSON - http://json.org/

■ XML - http://en.wikipedia.org/wiki/XML

■ JAVA BEAN - http://en.wikipedia.org/wiki/JavaBean

Security

Client applications that access your organization’s Service Desk data are subject to the same security protections that are used in the Service Desk user interface. Client applications must log in using valid credentials for an organization. The server authenticates these credentials and, if valid, permits access to the web service operation.

An organization’s Service Desk administrator controls the availability of various features and views by configuring profiles and assigning users to them. To access the API (to issue calls and receive the call results), a user must be granted the "Web Services" license. Client applications can query or update only those objects and fields to which their customer-slice have access via the profile of the logged-in user.

For access via the API or a client, the user must either use their security token or provide their login id and password in order to log in. A security token is an

automatically-generated key from Service Desk.

Error Handling

The API calls return error data that your client application can use to identify and resolve runtime errors. If an error occurs during the invocation of most API calls, then the API provides the following types of error handling:

■ For errors resulting from badly formed messages, failed authentication, or similar problems, the API returns a default service response with the appropriate status code and a descriptive status message.

■ For most calls, if the error occurs because of a problem specific to the query, the API returns an Error. For example, if a create() request contains values to be updated for read-only fields.

(12)

Supported Entities

You can use the CA Nimsoft Service Desk Web Service API to access and change the following entity types:

■ Attachment ■ _{Change Request} ■ Configuration Item ■ Communication ■ _Contact ■ _{Defined Search} ■ Incident ■ Knowledge Article ■ _Organization ■ Problem ■ Service Request ■ _{Support Group} ■ _{Task Ticket} ■ Ticket ■ Value List ■ _Worklog

The list of supported entities may change in the future. Some of the entities may not be accessible to a particular user, depending on the organization’s and user’s permissions.

Supported Operations

API calls represent specific operations that your client applications can invoke at runtime to perform tasks. The Nimsoft Service Desk Web Services supports the following types of operations

Operation Description

Get Retrieve specified fields for a record based on the record identifier List Retrieves records based on the specified search criteria

Insert Create a new record with the specified information Update Modify an existing record with the specified information

(13)

General Form of the Nimsoft Service Desk Web Service API

Delete Delete an existing record based on the record identifier

Relate Relates a entity record identified by record identifier to the another entity identified by record identifier

Unrelate Unrelates an entity record from another entity identified by their respective record identifiers

General Form of the Nimsoft Service Desk Web Service API

Each API call is initiated by a request from a client and has a response from the server. API calls are never initiated from the server to the client. Each API call has a method name, which is one of the operations described in Supported Operations section. The Nimsoft Service Desk Web Services API allows you to encode calls using either SOAP (Simple Object Access Protocol) or XML-RPC, a simple RPC mechanism encoded in XML.

SOAP Implementation

The Nimsoft Service Desk Web Service API allows you to encode your calls using SOAP. SOAP (Simple Object Access Protocol) is an XML-based protocol for exchanging information. See http://www.w3.org/TR/SOAP/ for a detailed description of SOAP. All of the supported operations are available in the SOAP implementation. See Supported Operations section.

Each SOAP call must be made to a Service Desk application server hostname with a servlet name of webservices/xxxx. This section outlines the high-level SOAP specification for the Service Desk API.

See the Service Desk WSDL at http://www.w3.org/TR/SOAP/ for a more technical specification.

SOAP Namespaces

SOAP uses different namespaces for different elements and attributes depending on the role that the data plays in the message formatting, handling, or encoding. The

namespaces reflect how all data type definitions in SOAP are delegated to XML schema. The Nimsoft Service Desk Web Service API uses the following namespaces

Namespace Value

targetNameSpace http://www.inteqnet.com

(14)

SOAP Implementation

xmlns:soap http://schemas.xmlsoap.org/wsdl/soap/ xmlns:xsd http://www.w3.org/2001/XMLSchema xmlns:wsdl http://schemas.xmlsoap.org/wsdl/

(15)

Chapter 3: Web Service API Calls 15

Chapter 3: Web Service API Calls

Requirements for All Calls (see page 15)

The Get Call (see page 16)

The List Call (see page 16)

The insert Call (see page 17)

The update Call (see page 18)

The delete Call (see page 19)

The relate Call (see page 19)

The unrelate Call (see page 20)

Field-level Security (see page 20)

Numeric Fields (see page 21)

Requirements for All Calls

All WS API calls must be contained in an HTTP request with appropriate HTTP headers. All Service Desk WS API calls require the following standard arguments:

Argument Description

Credentials

authorizationTo ken

Web Service Client’s Authorization Token

sliceToken Web Service Client’s Slice Token username Web Service Client User Name userPassword

Web Service Client User Password

Extended Settings

responseForma t

Web Service Output Data Format (JSON, XML, JavaBean)

Response to All Calls:

The response to all Service Desk WS API calls comprises of a default service response bean class regardless of whether the request succeeded or failed. The get response bean class may contain the following members

Members Description

Default Service Response

(16)

The Get Call

statusCode Status code for the web service response statusMessage Status message for the web service response

responseFormat The outgoing message format for a web service invocation

responseText The formatted outgoing message text (applicable for format types XML, JSON) responseBean The outgoing service-specific bean class (applicable when response format is BEAN) errors The list of error messages that occurred during the web service invocation

warnings The list of warning messages informing the client of non-fatal problems or condition that may cause problem

notes The list of informational messages to convey information or improve diagnostics

The Get Call

The get call is used to retrieve a pre-defined set of field values for an entity based on the record identifier.

The get Request

Beyond the normal login id and password arguments, the get call also requires the following:

Record Identifier Record Identifier (Row ID) of the entity

The get Response

The default service response for all the API calls will contain the record in the requested output format for a get call.

The List Call

The list call is used to retrieve records (entities) based on the specified search criteria.

The list Request: Beyond the normal login id and password arguments, the list call also

requires the following

(17)

The insert Call

The list Response

The default service response for all the API calls will contain the set of records matching the search criteria in the requested output format for a list call.

The insert Call

The insert call is used to create a new record (entity) of a particular type with the specified values.

The insert Request- Beyond the normal login id and password arguments, the insert call

also requires the following:

Bean Class Entity specific java bean class (complex data type) containing values for the fields which must be set, while creating the new entity

During an insert, you do not need to specify all fields for that entity type. Most fields are optional, except for those marked as required in the describe response, indicated by the attribute ‘nullable’ with the Boolean value ‘0’. Fields that are not specified are set to blank or to default values. Fields that are too long are truncated.

If you send unrecognized field values in the insert request, the Service Desk WS API rejects the call and sends status code 300 ‘Rejecting the value supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.’

The API applies a strict definition of unrecognized field values such that all fields in the call must be valid for the user for that operation.

For example:

■ The API rejects calls that specify a value for a custom field that has been deleted or removed from a user’s access.

■ The API rejects calls that specify read-only fields.

For some types of entities, if you try to insert a new record that already exists, the API does not insert a new record.

The insert Response

The default service response for all the API calls will contain the Record Identifier (Row ID) of a record being inserted in the requested output format for an insert call.

(18)

The update Call

The update call is used to modify an existing record (entity) identified by the record identifier with specified values.

The update Request

Beyond the normal login id and password arguments, the update call also requires the following:

Member: Bean Class

Description: Entity specific java bean class (complex data type) containing values for the fields which must be updated, while updating an existing entity identified by the record identifier.

During an update, you do not need to specify all fields for that entity type. You must pass the values for those fields which you would like to update during this call.

Fields that are not specified will be kept intact. Fields that are too long are truncated. If you send unrecognized field values in the update request, the Service Desk WS API rejects the call and sends status code 300 with an associated status message that reads ‘Rejecting the value supplied for input data element "{ 0} "; due to a correlation failure because the data transformation process could not resolve the supplied input data element into native format.’

■ The API applies a strict definition of unrecognized field values such that all fields in the call must be valid for the user for that operation. For example: The API rejects calls that specify a value for a custom field that has been deleted or removed from a user’s access.

■ The API rejects calls that specify read-only fields.

The update Response: The default service response for all the API calls will contain the

Record Identifier (Row ID) of a record being updated in the requested output format for an update call.

Note: You can clear text fields that are not mandatory by entering ##NULL##. However,

if you enter ##NULL## in a mandatory field, you will get the standard message stating the field is a mandatory one.

When a user tries to update the ticket he get an error message for the fields Requester Organization, Requester Location, Requester Site, Requested for Organization,

Requested for Location, Requested for Site, and Parent Case stating that they are read only fields.

(19)

The delete Call

The delete call is used to delete an existing record (entity) identified by the record identifier.

The delete Request- Beyond the normal login id and password arguments, the delete

call also requires the following

Record Identifier Record Identifier (Row ID) of a record

The delete Response

The default service response for all the API calls will contain the Record Identifier (Row ID) of a record being deleted in the requested output format for a delete call.

The relate Call

The relate call is used to relate a entity (record) to another entity identified by their respective record identifiers.

The relate Request- Beyond the normal login id and password arguments, the relate call

also requires the following:

Record Identifier Record Identifier (Row ID) of an entity to which another entity must be related Related Record Identifier Record Identifier (Row ID) of an entity which must be related to another entity

The relate Response

The default service response for all the API calls may contain the Record Identifier (Row ID) of a record being inserted into the relationship table in the requested output format for a relate call.

(20)

The unrelate Call

The unrelate call is used to unrelate a entity record from another entity identified by their respective record identifiers.

The unrelate Request- Beyond the normal login id and password arguments, the

unrelate call also requires the following:

Record Identifier Record Identifier (Row ID) of an entity from which another entity must be unrelated

Related Record Identifier Record Identifier (Row ID) of an entity which must be unrelated from another entity

The unrelate Response: The default service response for all the API calls may contain

the Record Identifier (Row ID) of a record being inserted into the relationship table in the requested output format for a relate call.

Field-level Security

The Service Desk WS API enforces the field-level security model that is set up in the Service Desk user interface. In the user interface, certain fields could be marked as read-only or hidden in the page layouts.

For a particular user, the API can access only those fields that are accessible to that user in their assigned page layout. The following restrictions apply:

■ The API can query read-only fields, but cannot insert or update them for that user.

■ The API cannot query, insert, or update fields that are marked as hidden for that user.

With the Service Desk WS API, hidden fields are not visible to any users, even users with full privileges. This behavior is consistent with how the application functions.

(21)

Numeric Fields

Numeric fields include fields of type integer and double. The standard, predefined fields are of type integer or double, according to criteria explained in Determining the Type of Standard Fields. All numeric custom fields are handled as type double.

Numeric fields must be transferred as i4 or double types, as appropriate, with the exception that you can set a numeric field to null by setting it to a blank string value. The type is indicated in the describe response for an entity.

The type must be respected in all future calls that refer to that field, including the insert and update calls. The type for the field is also returned from the query call.

Numeric field bounds are enforced when inserting or updating records. The bounds are indicated in the describe response by the ‘digits’ attribute to an integer field, or by the ‘scale’ and ‘precision’ attributes to a double field.

Digits Specifies the maximum number of digits that an integer can have

Scale For double fields, specifies the maximum number of digits to the right of the decimal place Precision For double fields, specifies the total number of digits, including those to the left and the right

of the decimal place

The maximum number of digits to the left of the decimal place is equal to ‘precision’ minus ‘scale’. In the Service Desk user interface, precision is defined differently; it is the maximum number of digits allowed to the left of the decimal place.

The limits for numeric fields are enforced when inserting or updating data. However, the Service Desk WS API may return data that does not meet these restrictions.

(22)

(23)

Chapter 4: Determining the Type of Standard Fields 23

Chapter 4: Determining the Type of

Standard Fields

The server determines whether a standard, predefined numeric field should be handled as a double XML-RPC type or as an i4 XML-RPC type. Normally, the server chooses to use type i4 when the scale is zero and type double when the scale is greater than zero. The i4 type in XMLRPC is limited to a four-byte integer, so it cannot handle the full range of integer values that are supported by Service Desk integer fields. Because of this, the server indicates a type of double for numeric fields with a scale greater than zero, or with a precision greater than nine.

However, there will not be any loss of precision for very large integer values (greater than 15 or 16 digits) that are transferred via the Service Desk WS API. Clients should not encode this logic themselves, but should use the type specified in the describe response. The decision of when to use double or i4 type may change in the future, but any change will be reflected in the describe response.

Enumerated Fields (see page 23)

Date/Time Fields (see page 24)

Custom Fields (see page 25)

The ID Fields (see page 25)

The Cross-Reference ID Fields (see page 26)

Long Text Fields (see page 26)

System ModTimeStamp Fields (see page 26)

Enumerated Fields

In the Service Desk WS API, enumerated fields are fields that are restricted to a defined list of values. They are indicated in the describe response with a Boolean value of ‘1’ for the ‘restricted’ member of the ‘fields’ substructure. The allowed values for an

enumerated field are specified in the ‘values’ array of the ‘display’ substructure of the describe response.

Note that the ‘values’ member is present for any field of type picklist, and picklist fields that do not have the ‘restricted’ member are advisory. The Service Desk WS API enforces the list of values for picklist fields on insert or update.

The query call always returns the value, not the label. The corresponding label for a value in the describe response should be used when displaying the value to the user in any user interface.

(24)

Date/Time Fields

All Date/Time fields are transferred via the Service Desk WS API using the XML-RPC type dateTime.iso8601 or the SOAP type dateTime. However, Service Desk has two different ways of handling dates and times internally.

In some cases you can handle these identically, but in other cases you may need to treat them differently.

Regular Date/Time Fields:

Regular Date/Time fields are stored as number of seconds after midnight January 1, 1970 GMT. They are automatically converted in the GMT/UTC time zone. You do not need to translate your local timestamp into GMT/UTC time zone value.

Examples of regular Date/Time fields include all Create Date fields and the Start and End DateTime fields.

Date-Only Fields:

Some fields in Service Desk are Date-Only fields. The time portion of a

Date-Only field is not relevant and is always set to midnight in the GMT/UTC time zone. Date-Only fields are transferred in the API as dateTime types for SOAP and as

dateTime.iso8601 types for XML-RPC calls, since XMLRPC does not have a Date-Only type.

■ You should handle Date-Only field values differently than regular Date/Time values:

■ You should ignore any time portion.

■ You should always send a time portion of all zeroes.

The Service Desk accepts Date-Only values that have a non-zero time portion, but the time portion is always truncated to zero. You should not alter any Date-Only values to account for time zone changes, since the time portion is not relevant.

(25)

Custom Fields

Chapter 4: Determining the Type of Standard Fields 25

Custom Fields

In the Service Desk user interface, organizations can define a set number of custom fields for different entities. For the most part, clients of the Service Desk WS API do not need to know whether a field is a standard field or a custom field for the organization. Custom fields have a unique field ID, rather than an English-readable ID name. This unique field ID is always prefixed with ‘cf_’ in all calls. When making requests, you must also prefix any custom field IDs with the string ‘cf_’. This restriction does not apply to the XML-RPC implementation of the Service Desk WS API.

Note that all numeric custom fields are handled as type integer.

The ID Fields

The id field is created automatically upon insert, and it cannot change over the lifetime of that record, even if the record is deleted and then undeleted. Each id value is guaranteed to be globally unique. The id of a record is the best way to uniquely identify that record. When inserting or updating records, the API accepts an integer ID.

(26)

The Cross-Reference ID Fields

Many entities have cross-reference ID fields, which are similar to foreign key fields in a database table. In some cases, an entity can refer to another entity of its same type. For example, tickets have a parent link that can point to another ticket.

You can also query each cross-referenced entity. When you query a cross-reference ID field, it returns an entity ID of the appropriate type. You can then query that ID to get additional information about the entity, using the ID in the id field for that query. The cross reference ID field value is either a valid record in your organization, or an empty value, which indicates an empty reference.

The cross-reference ID field value, if non-empty, is guaranteed to be an entity in your organization. However, it is not guaranteed that you can query that entity.

Users of an organization who are granted the necessary privileges (permissions) to access query operation on that entity can always query that entity. Other users who belong to the same organization may be restricted from viewing or editing the referenced entity.

Specifying a value for a cross-reference ID field when inserting or updating a record has specific limitations also. The value must be a valid entity of the appropriate type, and the user must have appropriate access to that entity.

Long Text Fields

Several entities have long text fields (256 bytes, 4000 bytes etc.) which can contain data that spans multiple lines.

You can clear text fields that are not mandatory by entering ##NULL##. However, if you enter ##NULL## in a mandatory field, you will get the standard message stating the field is a mandatory one.

System ModTimeStamp Fields

Most entities have a standard systemModstamp field that contains a timestamp of when the record was last changed. This field is automatically maintained; you cannot insert, update or delete it.

(27)

Chapter 5: Entity Specific Issues 27

Chapter 5: Entity Specific Issues

Most entities are fully explained by their metadata, but some entity-specific

characteristics warrant further explanation. Refer the Web Services client API to obtain a list of all the entity-specific fields available in the Service Desk WS API.

Attachment (see page 28)

Categorization (see page 28)

Change Request (see page 29)

Communication (see page 30)

Configuration Item (see page 30)

Contact (see page 30)

Defined Search (see page 31)

Incident (see page 31)

Knowledge Article (see page 32)

Organization (see page 32)

Problem (see page 33)

Service Request (see page 34)

Support Group (see page 35)

Task Ticket (see page 35)

Ticket (see page 36)

Value List (see page 37)

(28)

Attachment

Attachments are files that users have uploaded and attached to a parent entity. The insert, get, and delete calls support attachments. The Service Desk WS API sends and receives the binary file attachment data encoded as a base64 data type.

Prior to insert, clients must encode the binary attachment data as base64. Upon receiving an API response, clients must decode the base64 data to binary. The insert call restricts attachments to a maximum size of 3 MB by default. The maximum size restrictions for an attachment can be configured by modifying the slice-level configuration parameter MAX_ATTACHMENT_SIZE.

Attachments can queried, downloaded, uploaded, related to a parent entity and deleted via the Service Desk WS API.

The following entity types are supported as parents of attachments:

■ Service Request ■ Incident ■ Problem ■ Change Request ■ Task Ticket ■ Configuration Item ■ Knowledge Article

Categorization

Nimsoft Service Desk offers categorization levels for enhanced classification and provides up to 4 levels of classification for tickets, configuration items, knowledge articles, etc. using a Class, Category, Type and Item taxonomy.

The following entity types can be classified using the CCTI taxonomy:

■ Service Request ■ Incident ■ Problem ■ Change Request ■ Task Ticket ■ Configuration Item ■ Knowledge Article

(29)

Change Request

Nimsoft Service Desk includes an ITIL-based Change Module that allows your Help Desk to evaluate, prioritize, plan, test, document, and implement change requests

throughout the organization.

The change requests entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields associated with a change request are treated as part of the base entity.

When you execute a get request against the change request base entity, only the base details for that entity are returned however the details pertaining to the associated sub entities such as attachments, configuration item, SLA compliances etc. will not be returned.

The sub entities associated with the change request should be separately queried, updated, or deleted.

The following sub entity types are supported as part of Change Request:

Member Description

Worklog The worklog is used to track the actual work and progress made against a particular change request.

Communication All the incoming and outgoing communications related to the change request. Attachment Attachments are files that users have uploaded and attached to a parent entity. Configuration Item The configuration item associated with the change request.

Related Tickets Related Tickets describe the relationships established between multiple tickets dependencies between multiple tickets when working through your support requests. "Master" and "Sub" tickets have a hierarchical relationship where "Related" tickets are viewed as on the same level.

Activity The activity entity contains historical information about changes that have been made to a change request. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the change request.

(30)

Communication

Nimsoft Service Desk enables you and your team to communicate with internal and external customers via web submittals, email and phone. Communications Management in Nimsoft Service Desk provides a very consistent and professional mode of messaging from your Service Desk to your end users and customers.

Communications can be queried, related to a parent entity via the Service Desk WS API. The following entity types are supported as parents of communications:

■ Service Request ■ Incident ■ Problem ■ Change Request ■ Task Ticket ■ Service Feedback ■ Schedule Tasks

Configuration Item

The Configuration Management Database (CMDB) within Nimsoft Service Desk is considered the cornerstone of IT Service Support, providing a centralized view of IT data that is essential to delivering consistent, reliable, effective, and efficient service to your business customers.

The configuration item entity can be queried, inserted, and updated via the Service Desk WS API.

The operations for the associated child/sub entities are currently not implemented and may be provided in a future release. The operations to query or update custom fields associated with a configuration item are also not supported.

Contact

Nimsoft Service Desk manages and tracks your contacts - end users who will be submitting tickets requesting technical support or employees/agents making decisions and solving end-user problems.

The detailed information for one or more contact entities can be queried via the Service Desk WS API.

(31)

Defined Search

Repeatedly required predictable information needs can be met with Defined Searches. The Nimsoft Service Desk Administrator can predefine search criteria so that the Service Desk Agents can get the most useful search results. Access rights for the Predefined search can be set for multiple groups / roles / Individuals.

The defined search entity can be queried, and executed via the Service Desk WS API, provided that the user has access privileges on a particular pre-defined search.

Incident

Nimsoft Service Desk includes an ITIL-based Incident Management module, with pre-packaged workflows, which will allow you to identify, register, prioritize, categorize and track Incidents reported to your Help Desk.

The incident ticket entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields associated with a incident ticket are treated as part of the base entity.

When you execute a get request against the incident ticket base entity, only the base details for that entity are returned however the details pertaining to the associated sub-entities such as attachments, configuration item, SLA compliance etc. will not be returned.

The sub entities associated with the incident ticket should be separately queried, updated, or deleted. The following sub entity types are supported as part of Incident Ticket:

Worklog The worklog is used to track the actual work and progress made against a particular incident ticket.

Communication All the incoming and outgoing communications related to the incident ticket.

Attachment Attachments are files that users have uploaded and attached to a parent entity.

Configuration Item The configuration item associated with the incident ticket.

(32)

Knowledge Article

Activity The activity entity contains historical information about changes that have been made to a incident ticket. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the incident ticket.

Knowledge Article

Nimsoft Service Desk’s Knowledge Management module improves the quality of decision making made by staff, and management, by ensuring that reliable and safe information is available to resolve service issues.

It provides a means for end-users to search out and solve problems on their own before requesting for support from the support team. The knowledge article entity can be queried, inserted, and updated via the Service Desk WS API.

The operations for accessing or updating the associated child/sub entities are currently not implemented and may be provided in a future release.

Organization

Organization entities are used to capture company information for itself and its Customers, Service Providers, Vendors, Manufacturers etc. in a hierarchical three-tier structure (Organization/Site/Location). Each organization can have sub units at lower levels such as Sites, and Locations under a Site.

(33)

Problem

Nimsoft Service Desk includes an ITIL-based Problem Management module to help you identify the underlying cause of service issues and effectively implement corrective action to prevent recurrences and eliminate the impact of these issues on the business. The problem ticket entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields associated with a problem ticket are treated as part of the base entity.

When you execute a get request against the problem ticket base entity, only the base details for that entity are returned however the details pertaining to the associated sub-entities such as attachments, configuration item, SLA compliance etc. will not be returned.

The sub entities associated with the problem ticket should be separately queried, updated, or deleted. The following sub entity types are supported as part of Problem Ticket:

Worklog The worklog is used to track the actual work and progress made against a particular problem ticket.

Communication All the incoming and outgoing communications related to the problem ticket.

Configuration Item The configuration item associated with the problem ticket.

Activity The activity entity contains historical information about changes that have been made to a problem ticket. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the problem ticket.

(34)

Service Request

Nimsoft Service Desk provides the ability to publish a catalog of common requests for IT and non-IT services. Service Catalogs leverage the routing capabilities, approvals, service-level management and other features within the application necessary to fulfill a request.

The service request entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields associated with a service request are treated as part of the base entity.

When you execute a get request against the service request base entity, only the base details for that entity are returned however the details pertaining to the associated sub-entities such as attachments, configuration item, SLA compliance etc. will not be returned.

The sub entities associated with the service request should be separately queried, updated, or deleted. The following sub entity types are supported as part of Service Request:

Worklog The worklog is used to track the actual work and progress made against a particular service request.

Communication All the incoming and outgoing communications related to the service request.

Configuration Item The configuration item associated with the service request.

Activity The activity entity contains historical information about changes that have been made to a service request. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the service request.

(35)

Support Group

The concept of a Support Group is to have Service Desk Agents who handle the same type of assignments grouped together, organized as more skilled work groups, or support group providing a higher level of technical support.

Contacts within Service Desk are grouped together and assigned or made members of different support groups for various purposes such as Permission, Assignment, Notification, Approval, etc.

The detailed information for one or more support group entities can be queried via the Service Desk WS API.

Task Ticket

Service Desk provides the ability to divide work related to Service Request/ Incident/ Problem/ Change resolution into individual components which can be assigned to a number of different groups or individuals, while allowing the original ticket to remain owned by the person solving it.

The task ticket entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields associated with a task ticket are treated as part of the base entity.

When you execute a get request against the task ticket base entity, only the base details for that entity are returned however the details pertaining to the associated sub-entities such as attachments, configuration item, SLA compliance etc. will not be returned. The sub entities associated with the task ticket should be separately queried, updated, or deleted. The following sub entity types are supported as part of Task Ticket:

Worklog The worklog is used to track the actual work and progress made against a particular task ticket.

Communication All the incoming and outgoing communications related to the task ticket.

(36)

Ticket

Activity The activity entity contains historical information about changes that have been made to a task ticket. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the task ticket.

Ticket

This entity allows access to the Service Desk functionality for all Types of Tickets as a generic ticket entity. The ticket entity including the associated child/sub entities can be queried, inserted, and updated via the Service Desk WS API. The custom fields

associated with a ticket are treated as part of the base entity.

When you execute a get request against the ticket base entity, only the base details for that entity are returned however the details pertaining to the associated sub entities such as attachments, configuration item, SLA compliance etc. will not be returned. The sub entities associated with the ticket should be separately queried, updated, or deleted. The following sub entity types are supported as part of Ticket:

Worklog The worklog is used to track the actual work and progress made against a particular ticket.

Communication All the incoming and outgoing communications related to the ticket.

(37)

Value List

Related Tickets Related Tickets describe the relationships established between multiple tickets dependencies between multiple tickets when working through your support

requests. "Master" and "Sub" tickets have a hierarchical relationship where "Related" tickets are viewed as on the same level.

Activity The activity entity contains historical information about changes that have been made to a ticket. The activity entity is read-only via the API. The list call supports activity.

SLA Compliance Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the ticket.

Value List

NImsoft Service Desk provides ability for having enumerated dynamic lists for different types of field elements in different functional domains.

The value list entity can be queried via the Service Desk WS API. The following entity types are currently using the value list.

■ Service Request

■ Incident

■ Problem

■ Change Request

(38)

Worklog

Worklogs are manual entries in the ticket made to record information that is relevant or significant to the ticket and which is not automatically captured by Nimsoft Service Desk.

The worklog entity can be queried, inserted, and updated via the Service Desk WS API. The following entity types are supported as parents of worklogs:

■ Service Request

■ Incident

■ Problem

■ Change Request

(39)

Chapter 6: Appendix A: Status Codes 39

Chapter 6: Appendix A: Status Codes

Service Desk WS API requests always returns a default response. A response status should be used to determine whether the request has succeeded or failed. The default response comprises of a status code and an associated status text message.

The status message is a short description in English that can be displayed to the user as a minimally descriptive status message. If you display the status message, you should also display the status code.

Clients should always recognize the status codes, not the status messages. When a request cannot be completed successfully, the actual fault or an error messages will be returned which may vary slightly from the messages listed in this appendix.

Some faults are particular to certain calls, while others are more general faults that may occur on any call, such as status code 100 for a Access is denied due to invalid

credentials.

0xx : Success Status Code Message

000 Success: The request was successfully fulfilled by the server; the service returned results of the operation.

001 Success: The request was successfully fulfilled by the server; no results were returned by the service.

1xx : Authorization Error Status Code

Message

100 Unauthorized: Access is denied due to invalid credentials.

101 License Error: You do not have an appropriate license to use any service.

2xx : Operation Access Error Status Code

Message

200 Invocation Error: The operation definition for the requested service was not found.

201 Invocation Error: The requested service operation has been disabled.

3xx : Operation Pre-processing Error Status Code

Message

300 Execution Error: An unexpected error occurred during data-transformation of the request parameters passed during invocation of the web service: { 0} .{ 1} .

301 Execution Error: An unexpected error occurred during data-validation of the request parameters passed during invocation of the web service: { 0} .{ 1} .

(40)

Worklog

4xx : End-point Execution Error Status Code

Message

400 Execution Error: An un-handled exception occurred within the service endpoint (provider) during execution of the requested service. 401 Execution Error: Some errors were captured by the service endpoint

(provider) during execution of the requested service.

402 Execution Error: An unexpected error occurred when rendering the service response in the requested format.

403 Execution Error: An unexpected error occurred while processing the requested service.

(41)

Chapter 7: Appendix B: Web Services Client Examples 41

Chapter 7: Appendix B: Web Services Client

Examples

Service Desk Web Services API is based on The Apache Axis2 project which is a Java-based implementation of both the client and server sides of the Web services equation. Axis is essentially a SOAP engine -- a framework for constructing SOAP processors such as clients, servers, gateways, etc.

The following samples demonstrate the structure for developing client code to consume Service Desk Web Services.

Following steps are required for consuming all the types of Service Desk Web Services. This section contains the following topics:

Setting up the environment (see page 41)

Generating the Axis2 Client code using "wsdl2java" tool (see page 42)

Typical API Call Sequence (see page 42)

get Call Client Example (see page 43)

list Call Client Example (see page 46)

insert Call Client Example (see page 49)

update Call Client Example (see page 53)

delete Call Client Example (see page 57)

Setting up the environment

Download the binary version of Apache Axis2 and extract the binary

version(axis2-1.5.1-bin.zip). After extracting the file into E:Axis2Client (assuming your client directory), you will get a directory "E:Axis2Clientaxis2-1.5.1-binaxis2-1.5.1" which contains the binary version of the Apache Axis2 engine. Now, set the environment variables by invoking following code from a command line:

(42)

Generating the Axis2 Client code using "wsdl2java" tool

A Web Services Description Language (WSDL) file describes a Web service. The Java API for XML-based Remote Procedure Call (JAX-RPC) 1.1 specification defines a Java API mapping that interacts with the Web service.

The Web Services for Java 2 Platform, Enterprise Edition (J2EE) 1.1 specification defines deployment descriptors that deploy a Web service in a J2EE environment. The

WSDL2Java command is run against the WSDL file to create Java APIs and deployment descriptor templates according to these specifications.

The command-line syntax is:

WSDL2Java [arguments] WSDL-URI

From a command line generate the client code for ServiceRequest web service by issuing the following command:

%AXIS2_HOME%\ bin\ WSDL2Java –url

http://nsd-preview.nimsoftondemand.com/webservices/ServiceRequest?wsdl -o com/infradeskonline/genclient

Where,

■ The "-url" is either the path where you have saved a copy of the wsdl to either ".wsdl" or ".xml", or the URL the WSDL resides at.

■ The "-o" is the path where you want the files to be written out to. If not specified, the files will be written out to the current bin location.

■ The above command will generate "ServiceRequestStub.java" and

"ServiceRequestCallbackHandler.java" into "com/infradeskonline/genclient" directory.

Typical API Call Sequence

For each call, your client application typically:

Prepares the request by defining request parameters, if applicable.

Invokes the call, which passes the request with its parameters to the Service Desk Web Service for processing.

Receives the response from the API.

Handles the response, either by processing the returned data (for a successful invocation) or by handling the error (for a failed invocation).

(43)

get Call Client Example

Developing the code to call the service

The following is an example of a Axis Client program that calls the getServiceRequest operation to query an excerpt of the primary details (general information) pertaining to the service request identified by the specified ticket identifier, in XML output format.

(44)

public class ServiceRequestClient {

public void main ( String [] args) {

try {

// Create the request

ServiceRequestStub srqStub = new ServiceRequestStub(); ServiceRequestStub.Credentials credentials = new ServiceRequestStub.Credentials(); ServiceRequestStub.ExtendedSettings extParams = new ServiceRequestStub.ExtendedSettings();

// Initialize Credentials (User Name & User Password / Authorization Token & Slice Token)

credentials.setUserName ( "wsuser");

credentials.setUserPassword ( "wsuser");

// Initialize Extended Settings such as Response Format (XML, JSON) extParams.setResponseFormat (

"XML");

// Invoke the GET service

ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.getServiceRequest (credentials, extParams, ticketIdentifier);

// Inspect successful execution of service and retrieve the response text

if (serviceResponse.getResponseStatus ().equals ( "OK"))

(45)

System.out.println(

"XML Response : " + serviceResponse.getResponseText ()); }

// Retrieve the status code, status message and error messages, in case of failures else { System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());

System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());

System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ()); } } catch (Exception e) { System.out.println ( "Exception: " + e.getMessage()); } } }

(46)

list Call Client Example

The following is an example of a Axis Client program that calls the listServiceRequest operation to query return the list of all open service requests for the logged in user and his groups matching the specified search criteria, in JSON output format.

(47)

Chapter 7: Appendix B: Web Services Client Examples 47 public class ServiceRequestClient

{

try {

ServiceRequestStub srqStub = new ServiceRequestStub(); ServiceRequestStub.Credentials credentials = new ServiceRequestStub.Credentials(); ServiceRequestStub.ExtendedSettings extParams = new ServiceRequestStub.ExtendedSettings();

"JSON");

// Invoke the LIST service

ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.listServiceRequest (credentials, extParams, ticketIdentifier);

// Inspect successful execution of service and retrieve the response text

if (serviceResponse.getResponseStatus ().equals ( "OK"))

{

(48)

System.out.println(

"JSON Response : " + serviceResponse.getResponseText ()); }

// Retrieve the status code, status message and error messages, in case of failures else { System.out.println(

"Status Code : " + serviceResponse.getStatusCode ());

System.out.println(

"Status Message : " + serviceResponse.getStatusMessage ());

System.out.println(

"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ()); } } catch (Exception e) { System.out.println ( "Exception: " + e.getMessage()); } } }

(49)

insert Call Client Example

The following is an example of a Axis Client program that calls the listServiceRequest operation to create/log a new service request ticket with the provided details.

(50)

insert Call Client Example

public class ServiceRequestClient {

try {

ServiceRequestStub srqStub = new ServiceRequestStub(); ServiceRequestStub.Credentials credentials = new ServiceRequestStub.Credentials(); ServiceRequestStub.ExtendedSettings extParams = new ServiceRequestStub.ExtendedSettings(); ServiceRequestStub.ServiceRequest srqBean = new ServiceRequestStub.ServiceRequest();

"JSON");

// Initialize Service Request Bean with neccessary details srqBean.setRequester_name (

"Admin, InteQ");

srqBean.setTicket_description ( "Ticket creation via webservice# " +