Tips for SOAP Web Services Clients

This article contains the following topics:
casm1401
This article contains the following topics:
The samples directory of the CA SDM installation provides a sample Java client application for Web Services. This sample assists developers with web services client application development.
Many of the Web Services methods require arrays as input parameters. For example, the method createIssue() permits an empty array for propertyValues. Sometimes these arrays are optional, but the service requires an empty array for a successful pass. When you use Visual Studio .NET to access Web Services, specify an empty array with one of the following arrays:
  • C# language
    String[] emptyArray = new string[0];
  • Visual Basic .NET
    Dim emptyArray As String() = {}
  • Java
    ArrayOfString attr = new ArrayOfString(); attr.setString(new String[0]); ArrayOfString is a proprietary class.
You can then pass emptyArray to array parameters that accept empty arrays.
The CA SDM Web Services use the Apache implementation of standards established by the World Wide Web Consortium (W3C). Ideally, a client on any type of operating environment can access the services, but vendor implementations vary. Many programming environments provide a tool to generate proxy classes from a Web Services Description Language (WSDL) description.
Java Clients
The TableOfContents.doc in $NX_ROOT/samples/sdk/websvc lists several Java sample programs.
Each sample program contains notes on how it can be compiled and run using the script files run_java_test_bat.txt (Windows) and run_java_test_sh.txt (UNIX). These scripts demonstrate how to use org.apache.axis.wsdl.WSDL2Java to generate the CA SDM web services client-side stub files.
The - w parameter is required to properly generate the stub files when using Axis 1.4. Running WSDL2Java as shown will generate the stub files in subdirectory com/ca/www/UnicenterServicePlus/ServiceDesk. The following files are generated:
  • ArrayOfInt.java
  • ArrayOfString.java
  • ListResult.java
  • USD_WebService.java
  • USD_WebServiceLocator.java
  • USD_WebServiceSoap.java
  • USD_WebServiceSoapSoapBindingStub.java.
Import these classes with the following statement:
import com.ca.www.UnicenterServicePlus.ServiceDesk.*;
Many Web Service methods have parameters of type ArrayOfString, a proprietary class. For example, the createRequest() method’s attrVals, propertyValues and attributes parameters are all ArrayOfString parameters.
To set the values in an ArrayOfString variable, instantiate the variable and then use setString() as follows:
ArrayOfString attrVals = new ArrayOfString(); attrVals.setString(new String[]{"customer", customerHandle, "description", "description text"});
To set it to empty
attrVals.setString(new String[0]);
Use a variable of type ListResult, another proprietary class, as the return value from the List methods: doQuery(), getRelatedList(), getNotificationsForContact(), getPendingChangeTaskListForContact() and getPendingIssueTaskListForContact(). A ListResult contains listHandle and listLength elements, which can be retrieved using getListHandle() and getListLength() as shown in this example:
ListResult doQueryResult = new ListResult(); doQueryResult = USPSD.doQuery(sid, "iss", "active = 1"); int listHandle = doQueryResult.getListHandle(); int listLength = doQueryResult.getListLength();
The getListValues() method uses the listHandle, retrieving the values from a subset of the list.
The Handles parameter of the freeListHandles() method is an ArrayOfInt, another proprietary class. Call freeListHandles() using the listHandle taken from a ListResult:
ArrayOfInt handleList = new ArrayOfInt(); handleList.setInteger(new java.lang.Integer []{ new java.lang.Integer(listHandle) }); USPSD.freeListHandles(sid, handleList);
Some methods have pass by reference parameters of type javax.xml.rpc.holders.StringHolder. For example, createRequest() has two parameters of this type, NewRequestHandle and NewRequestNumber.
StringHolder NewRequestNumber = new StringHolder(); StringHolder NewRequestHandle = new StringHolder(); String result; result = USPSD.createRequest(sid, creatorHandle, attrVals, propertyValues, template, attributes, NewRequestHandle, NewRequestNumber);
The Request’s handle and reference number (ref_num) can then be obtained from NewRequestHandle.value and NewRequestNumber.value respectively.
SOAP Web Services Configuration
You can configure the CA SDM SOAP Web Services with entries in special web configuration files. The following table summarizes the names and descriptions of the configuration options:
Option Name
Description
design_mode_stubs
Sets the Web Servic
e to design mode
(CA SDM only).
require_secure_logon
Requires the login() and loginService() web methods to be called with a secure protocol, such as https.
require_secure_connection
Requires that every web method be called with a secure protocol.
disable_user_logon
Disables both login() and loginService() web methods, so only loginServiceManaged() can be used to log in.
CA SDM adds protection to the integrity of the running Tomcat server by verifying the length of the attribute values that pass to Web Service methods. By default, web service calls return an Axis Fault if the length of an attribute exceeds 900,000 bytes.
You set the following parameters in the deploy.wsdd file:
  • fatal_max_string_length
    Sets the length of the largest attribute value that a web service method accepts.
    Default:
    900,000 bytes
  • validate_parameters
    Sets whether the attribute value length checking is performed. Set the parameter to 0 to turn off the validation.
    Default:
    1 (on)
  • exception_methods
    Displays a comma-delimited list of Web Service methods that are exempt from the attribute value length validation.
Redeploy the Web Services
New configuration settings take effect when you redeploy CA SDM Web Services. Complete the following steps to redeploy the Web Services:
  1. Open a command prompt and set the CLASSPATH environment variable to include the required Axis jar files, which are supplied in <NX_ROOT>/java/lib.
    For example, to set it on Windows, execute the following command:
    set AXISHOME=%NX_ROOT%\java\lib set classpath= %AXISHOME%\axis.jar;%AXISHOME%\jaxrpc.jar;%AXISHOME%\saaj.jar;%AXISHOME%\commons-logging.jar;%AXISHOME%\commons-discovery.jar;%AXISHOME%\wsdl4j.jar;%AXISHOME%\log4j-1.2.8.jar;%classpath%;
  2. Modify the directory to <NX_ROOT>/sdk/websvc/R11 and execute the following commands:
    java org.apache.axis.client.AdminClient undeploy.wsdd java org.apache.axis.client.AdminClient deploy.wsdd
  3. Recycle Tomcat by recycling the CA SDM service. You can avoid shutting down the entire CA SDM system by recycling Tomcat by simply using the following commands:
    pdm_tomcat_nxd - c stop pdm_tomcat_nxd - c start
    The Web Service is redeployed.
  4. Verify that the service deployed by viewing the Axis services listing page at the following default URL:
    http://<servername>:< port>/axis/services
    The exact URL depends upon your installation settings.
SOAP Error Handling
If an error occurs with a Web Services method, a SOAP Fault is returned. The SOAP Fault is the standard means of returning exception information for Web Services.
The Fault message contains standardized <Message> and <Code> elements, but the most informative is the <Detail> element. The <Detail> element contains <ErrorCode> and <ErrorMessage> elements. The <ErrorCode> element returns an enumerated error code specific to either the CA SDM or Knowledge Management product. The <ErrorMessage> element contains an English string describing the errors. The <ErrorMessage> elements are more suitable for aiding the developer and more appropriate messages should display to users.
For example, the following illustrates a SOAP Fault when a bad parameter is supplied to the CA SDM getObjectValues() method:
<soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>Error on fetch with attribute list:persistent_id,first_name,last_nameParamErrorHere<faultstring> <detail> <ErrorCode>1001</ErrorCode> <ErrorMessage>Error on fetch with attribute list: persistent_id,first_name,last_nameParamErrorHere </ErrorMessage> </detail> </soap:Fault>
If you are using a client built with Microsoft .NET managed code, a failed Web Services method call raises a "SOAPException" exception. All errors cancel the operation invoked.
In some cases, the servlet container may write errors and therefore, display in the servlet container logs. In other cases, error information may be written to CA SDM logs. These logs are located in the following subdirectories:
  • In the /bopcfg/www/CATALINA_BASE/logs subdirectory of CA SDM installation
  • In the /log subdirectory of the CA SDM installation and to all logs that have the prefix “stdlog”.
We recommend that you constantly monitor these logs, as the server may log its own errors without reporting them to the CA SDM Web Services.
Lock Errors
CA SDM objects are locked during updates. Methods that update objects (such as, updateObject() or transfer()) may return the following lock error code:
UDS_LOCK_ERR
This code indicates that another user is updating the record. Often the locking user’s handle is returned in the ErrorMessage element.
Time Outs
If the CA SDM server is heavily loaded, a method may take a long time to process. In rare cases, a method may never return because a separate process failed to reply or some other error occurred. To guard against excessive blocking, every Web Services method times out after a number of seconds. Web Services method time-out is a CA SDM server time-out,
not
a Web server time-out, network time-out, and so on.
 The Web Services delay a few seconds the first time accessed after the J2EE application server is recycled. This happens because the application is initializing, loading DLLs, libraries, and so on, and occurs only with the first Web Services method call. All subsequent calls return much faster.
 
If a method times out, it returns the following error code:
UDS_TIMEOUT_ERR
The operation is not aborted! The server may have received the request and processes it successfully, although slowly. This type of problem may occur when using the
doSelect( )
method to retrieve several 1000 records.
For information about the
doSelect
method, see the CA Service Desk Manager Reference Commands section.
Error Codes
The following table lists the possible values for the <ErrorCode> value in a SOAP Fault returned from a Web Services call:
Error Name
Value
Description
UDS_OK
0
Successful.
UDS_FAILURE
1
General failure, check system logs.
UDS_BAD_PARAM
1000
A bad parameter was passed to a method. This error occurs if a required parameter is missing, the wrong type was passed, or an invalid value was used.
UDS_INTERNAL_ERR
1001
Signals that an internal error occurred. A description is found in the return array and the system logs.
UDS_LOCK_ERR
1002
An attempt was made to update an object locked by another user or process. Usually the ID of the contact responsible for locking the object is returned in the return data.
UDS_UPDATE_ERR
1003
An error occurred updating an object. Make sure all required attributes were set and check the system log.
UDS_CREATION_ERR
1004
An error occurred creating an object. Make sure all required attributes were set and check the system logs.
UDS_NOT_FOUND
1005
A search method failed to find any matches or failed to find an object specified. This can happen if a bad or invalid handle is passed to any method.
UDS_SESSION_TIMEOUT
1006
The current method timed out, the CA SDM server may be heavily loaded or the method itself was bad.
UDS_SERVER_GONE
1007
The CA SDM server connection is lost, UDS methods will no longer function and all list references are lost.
UDS_FETCH_ERR
1008
An error occurred while retrieving list data.
UDS_BAD_SESSION
1010
An invalid SID was used.
UDS_CNTXT_TIMEOUT
1011
The SID timed out.
UDS_SECURE_CHANNEL_REQUIRED
1012
The Web Services (or a web service method) requires a secure channel (for example: SSL) for access, but an unsecured channel is being used.
UDS_SECURITY_VIOLATION
1013
The attempted operation violates CA SDM security and was aborted.
UDS_OVER_POLICY_LIMIT
3002
The attempted request is refused because it exceeds the limit defined in the policy.