CA Nimsoft Service Desk

Transcription

1 CA Nimsoft Service Desk Web Services Guide 7.0.6

2 Legal Notices Copyright 2013, CA. All rights reserved. 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 (June 1995), or as a "commercial item" as defined in FAR 2.101(a) or as "Restricted computer software" as defined in FAR (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 (c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR (June 1987) or DFAR (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 document at:

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 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 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 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 Factors that Affect Data Access Web Service Output Data Format Types Security Error Handling Supported Entities Supported Operations General Form of the Nimsoft Service Desk Web Service API SOAP Implementation Chapter 3: Web Service API Calls 15 Requirements for All Calls The Get Call The List Call The insert Call The update Call The delete Call The relate Call The unrelate Call Field-level Security Numeric Fields Chapter 4: Determining the Type of Standard Fields 23 Enumerated Fields Date/Time Fields Custom Fields Contents 5

6 The ID Fields The Cross-Reference ID Fields Long Text Fields System ModTimeStamp Fields Chapter 5: Entity Specific Issues 27 Attachment Categorization Change Request Communication Configuration Item Contact Defined Search Incident Knowledge Article Organization Problem Service Request Support Group Task Ticket Ticket Value List Worklog Chapter 6: Appendix A: Status Codes 39 Chapter 7: Appendix B: Web Services Client Examples 41 Setting up the environment Generating the Axis2 Client code using "wsdl2java" tool Typical API Call Sequence get Call Client Example list Call Client Example insert Call Client Example update Call Client Example delete Call Client Example Web Services Guide

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 recommend using the SOAP UI client to interface with CA Nimsoft Service Desk Web-Services. Please refer to for more information about using SAOP UI client. Standards Compliance The WS API is implemented to comply with the following standard specifications Standard Name Simple Object Access Protocol (SOAP) 1.1 Website Chapter 1: Introduction 7

8 Development Platforms Web Service Description Language (WSDL) 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 Axis and JDK 1.6. For more information about Apache Axis2 1.5 refer to 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 URLhttp://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. 8 Web Services Guide

9 Chapter 2: Service Desk Web Service API Basics This section contains the following topics: 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. Add, update, and delete data. Chapter 2: Service Desk Web Service API Basics 9

10 Characteristics of API Calls 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. 10 Web Services Guide

11 Web Service Output Data Format Types Web Service Output Data Format Types The following standard data format types are supported by CA Nimsoft Service Desk via the HTTP protocol: JSON - XML - JAVA BEAN - 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. Chapter 2: Service Desk Web Service API Basics 11

12 Supported Entities 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 Get List Insert Update Description Retrieve specified fields for a record based on the record identifier Retrieves records based on the specified search criteria Create a new record with the specified information Modify an existing record with the specified information 12 Web Services Guide

13 General Form of the Nimsoft Service Desk Web Service API Delete Relate Unrelate Delete an existing record based on the record identifier Relates a entity record identified by record identifier to the another entity identified by record identifier 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 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 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 targetnamespace xmlns Value Chapter 2: Service Desk Web Service API Basics 13

14 SOAP Implementation xmlns:soap xmlns:xsd xmlns:wsdl Web Services Guide

15 Chapter 3: Web Service API Calls This section contains the following topics: 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 authorizationto ken slicetoken username userpassword responseforma t Response to All Calls: Description Credentials Web Service Client s Authorization Token Web Service Client s Slice Token Web Service Client User Name Extended Settings Web Service Client User Password Web Service Output Data Format (JSON, XML, JavaBean) Members responsestatus 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 Description Default Service Response The outgoing message status for a web service invocation Chapter 3: Web Service API Calls 15

16 The Get Call statuscode statusmessage responseformat responsetext responsebean errors warnings notes Status code for the web service response Status message for the web service response The outgoing message format for a web service invocation The formatted outgoing message text (applicable for format types XML, JSON) The outgoing service-specific bean class (applicable when response format is BEAN) The list of error messages that occurred during the web service invocation The list of warning messages informing the client of non-fatal problems or condition that may cause problem 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: Members Record Identifier Description 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 Members Search Text Description Search Text Value to look up against the identified set of fields for an entity 16 Web Services Guide

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: Members Bean Class Description 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. Chapter 3: Web Service API Calls 17

18 The update Call 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. 18 Web Services Guide

19 The delete Call 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 Members Record Identifier Description 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: Members Record Identifier Related Record Identifier Description Record Identifier (Row ID) of an entity to which another entity must be related 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. Chapter 3: Web Service API Calls 19

20 The unrelate Call 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: Members Record Identifier Related Record Identifier Description Record Identifier (Row ID) of an entity from which another entity must be unrelated 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. 20 Web Services Guide

21 Numeric Fields 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. Members Digits Scale Precision Description Specifies the maximum number of digits that an integer can have For double fields, specifies the maximum number of digits to the right of the decimal place 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. Chapter 3: Web Service API Calls 21

22

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. This section contains the following topics: 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. Chapter 4: Determining the Type of Standard Fields 23

24 Date/Time Fields 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. 24 Web Services Guide

25 Custom Fields 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. Chapter 4: Determining the Type of Standard Fields 25

26 The Cross-Reference ID Fields 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. 26 Web Services Guide

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. This section contains the following topics: 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) Worklog (see page 38) Chapter 5: Entity Specific Issues 27

28 Attachment 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 28 Web Services Guide

29 Change Request 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 Worklog Communication Attachment Configuration Item Related Tickets Activity SLA Compliance Description The worklog is used to track the actual work and progress made against a particular change request. All the incoming and outgoing communications related to the change request. Attachments are files that users have uploaded and attached to a parent entity. The configuration item associated with the change request. 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. 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. Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the change request. Chapter 5: Entity Specific Issues 29

30 Communication Communication Nimsoft Service Desk enables you and your team to communicate with internal and external customers via web submittals, 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. 30 Web Services Guide

31 Defined Search 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: Member Worklog Description 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 Related Tickets The configuration item associated with the incident ticket. 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. Chapter 5: Entity Specific Issues 31

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. The organization entity can be queried via the Service Desk WS API. 32 Web Services Guide

33 Problem 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: Member Worklog Description 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. Attachment Attachments are files that users have uploaded and attached to a parent entity. Configuration Item The configuration item associated with the problem ticket. 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 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. Chapter 5: Entity Specific Issues 33

34 Service Request 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: Member Worklog Communication Description The worklog is used to track the actual work and progress made against a particular service request. All the incoming and outgoing communications related to the service request. Attachment Attachments are files that users have uploaded and attached to a parent entity. Configuration Item The configuration item associated with the service request. Related Tickets Activity SLA Compliance 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. 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. Provides real-time SLA compliance data to determine the status regarding achievement of SLA Targets applicable to the service request. 34 Web Services Guide

35 Support Group 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: Member Worklog Description 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. Attachment Attachments are files that users have uploaded and attached to a parent entity. Configuration Item The configuration item associated with the task ticket. Chapter 5: Entity Specific Issues 35