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} .
Worklog
40 Web Services Guide
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.
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:
Generating the Axis2 Client code using "wsdl2java" tool
42 Web Services Guide
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).
get Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 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.
get Call Client Example
44 Web Services Guide
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"))
get Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 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()); } } }
list Call Client Example
46 Web Services Guide
list Call Client Example
Developing the code to call the service
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.
list Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 47 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 (
"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"))
{
list Call Client Example
48 Web Services Guide
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()); } } }
insert Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 49
insert Call Client Example
Developing the code to call the service
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.
insert Call Client Example
50 Web Services Guide
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(); ServiceRequestStub.ServiceRequest srqBean = new ServiceRequestStub.ServiceRequest();
// 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 (
"JSON");
// Initialize Service Request Bean with neccessary details srqBean.setRequester_name (
"Admin, InteQ");
srqBean.setTicket_description ( "Ticket creation via webservice# " +
insert Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 51 new Date());
// Invoke the INSERT service
ServiceRequestStub.DefaultServiceResponse serviceResponse = srqStub.logServiceRequest (credentials, extParams, srqBean);
// Inspect successful execution of service and retrieve the response text if (serviceResponse.getResponseStatus ().equals ( "OK")) { 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) {
insert Call Client Example
52 Web Services Guide
System.out.println (
"Exception: " + e.getMessage()); }
} }
update Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 53
update Call Client Example
Developing the code to call the service
The following is an example of a Axis Client program that calls the listServiceRequest operation to update an existing service request ticket identified by row_id "123" with the provided details.
update Call Client Example
54 Web Services Guide
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(); ServiceRequestStub.ServiceRequest srqBean = new ServiceRequestStub.ServiceRequest();
// 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 (
"JSON");
// Initialize Service Request Bean with neccessary details srqBean.setRow_id (123);
srqBean.setTicket_description ( "Updated - Ticket creation via webservice# " + new Date());
update Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 55 ServiceRequestStub.DefaultServiceResponse serviceResponse =
srqStub.logServiceRequest (credentials, extParams, srqBean);
// Inspect successful execution of service and retrieve the response text if (serviceResponse.getResponseStatus ().equals ( "OK")) { 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());
update Call Client Example
56 Web Services Guide
} } }
delete Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 57
delete Call Client Example
Developing the code to call the service
The following is an example of a Axis Client program that calls the deleteAttachment operation to deletes the attachment document entry from the database identified by the Row Id# 12.
delete Call Client Example
58 Web Services Guide
public class AttachmentClient {
public void main ( String [] args) {
try {
// Create the request
AttachmentStub attachmentStub = new AttachmentStub(); AttachmentStub.Credentials credentials = new AttachmentStub.Credentials(); AttachmentStub.ExtendedSettings extParams = new AttachmentStub.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 (
"JSON");
// Invoke the DELETE service
AttachmentStub.DefaultServiceResponse serviceResponse = attachmentStub.deleteAttachment (credentials, extParams, "12");
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals ( "OK"))
delete Call Client Example
Chapter 7: Appendix B: Web Services Client Examples 59 {
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()); } } }