Web Services Miscellaneous Methods

This article contains the following topics:
casm172
This article contains the following topics:
This section describes the Web Services Miscellaneous methods.
callServerMethod
The following parameters apply to the callServerMethod method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
methodName
String
Identifies the name of the method to call.
factoryName
String
Identifies the factory name of the object type containing the method.
formatList
String
Identifies the format list, a series of characters describing the intended data types for the incoming parameters. It is related to the Parameter() description in this table).
parameters
String[]
Indicates zero or more parameter values for the method.
Description
Use this method to invoke an arbitrary server-side method. These are methods defined in the proprietary “spel” scripting language.
Only factory methods can be called and the caller must be logged in with full administrative rights.
The format list is a series of zero or more characters that indicate (in order) the data types of the parameters to follow. The character codes are as follows:
  • 0 S -- string
  • 0 I -- integer (covers dates and duration)
  • 0 N -- null
For example, suppose a spell method is defined as follows:
cr::DoStuff(int in_one, string in_two, string in_three);
Invoke it with the following:
callServerMethod("DoStuff", "cr", "ISS", [3, "a string", "another one"]);
This method is intended for CA Development and services for customizations only; it is not recommended for most sites.
Returns
Each return message component in its own XML element. The elements are all string representations of the value. The elements are ordered in the return order from the server using the following format:
<ServerReturn> <Paramx>
This call does not support object reference returns. If an object reference is returned by the spell method, the return data is the string, “OBJECT”. This is not an error and any other parameters are also returned.
XML Element
Type
Description
<ServerReturn>
N/A
Indicates the outer element, which contains zero or more <ParamX> elements for return values.
<Paramx>
String
Indicates zero or more for the return values, where
x
is an integer starting at zero and increments for each return element.
You can validate BOPSIDs using check_bopsid. This is invoked with callServerMethod as follows:
String bopsid; // somehow gets populated with the BOPSID value String [] stuff = new String [] { bopsid }; String ret = usd.callServerMethod (sid, "check_bopsid", "api", "I", stuff);
If the BOPSID validation fails, a SOAP Fault is returned. If validation succeeds, the return value is a small XML structure of the following form:
<ServerReturn> <Param0>CONTACT_PERSID</Param0> <Param1>SESSION_TYPE</Param1> <Param2>SESSION_ID</Param2> </ServerReturn>
  • CONTACT_PERSID
    Defines the unique persistent id of the validated/trusted contact. It is of the form, "cnt:<uuid>".
  • SESSION_TYPE
    Defines a small integer id indicating the type of session that generated the BOPSID. This is typically not used by integrators
  • SESSION_ID
    Defines an optional session id. This is the id of the session that generated the BOPSID. It may or may not be set. This is useful to maintain a user's logical session within CA SDM, especially if the user is "passed" back to CA SDM by another BOPSID.
If the BOPSID validation returns a success, log into CA Support Automation bypassing the login screen, else the CA Support Automation Login screen will be displayed.
createObject
The following parameters apply to the createObject method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
ObjectType
String
Identifies the type of object to create (the majic factory name).
attrVals
String[]
Identifies a sequence of name-value pairs used to set the initial attribute values for the new issue.
Note:
Dotted names are not permitted.
attributes
String[]
Identifies a sequence of attribute names from the new object for which to return values. Dot-notation is permitted. If this field is empty, all attribute values are returned.
createObjectResult
String Holder
Identifies the String Holder object for capturing returned data. See the XML Element Return list below for details.
newHandle
String Holder
Identifies the String Holder object for capturing returned data. See the XML Element Return list below for details.
Description
Creates a CA SDM object. The caller is responsible for setting any required fields in the
attrVals
parameter. Dotted-names are not permitted.
  • ObjectType
    Identifies the name for an object type (factory).
  • attrVals
    Describes the array of name-value pairs used to initialize the new object. For example, the following pseudo-code shows how to create a contact and return a <UDSObject> element with values for all its attributes:
    String [4] attrVals; attrVals[0] = "first_name"; // attribute name attrVals[1] = "Edgar"; attrVals[2] = "last_name"; attrVals[3] = "Martin"; string [0] emptyArray; CreateObject(sid, "cnt", attrVals, emptyArray, createObjectReturn, newHandle);
    Do not use this method for new assets, issues, requests, or change orders. Use the specialized createXXX() methods for those object types. This comment also applies if you are using the ITIL methodology -- use the appropriate methods to create Configuration Items, Incidents, and Problems.
Returns
A <UDSObject> element containing the new objects handle, along with attribute values specified in the
attributes
parameter. If the
attributes
parameter is empty,
all
attribute values are returned. List and LREL types are also returned, but as empty elements.
XML Element
Type
Description
<createObjectResult>
N/A
Identifies the standard UDSObject element containing the handle and requested attribute values.
<newHandle>
String
Identifies the new objects handle.
serverStatus
The following parameter applies to the serverStatus method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
Description
Returns the status of the CA SDM server, that is, whether it is up and ready or shut down.
This method executes rapidly on the server. Calling this method periodically is a good way to keep a SID active.
Returns
The following values apply:
  • 1
    -- Indicates the Service Desk server is not available
    Note:
    Any non-zero return code indicates that the server is unavailable, such as 1010.
  • 0
    -- Indicates the Service Desk server it is running
XML Element
Type
Description
<ServerStatus>
Integer
Identifies the value associated with the server status, zero or 1.
updateObject
The following parameters apply to the updateObject method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
objectHandle
String
Identifies the handle of a CA SDM object to update.
attrVals
String[]
Identifies the name-value pairs for the update.
attributes
String[]
Identifies the sequence of attribute names from the object for which to return values. Dot-notation is permitted. If this field is empty, all attribute values are returned.
Description
Updates one or more attributes for the specified object.
To set values for the object, the caller passes a single-dimensional array of attribute name-value pairs. The first half of the pair is an attribute name; the second is the actual value. Dotted-names are not permitted.
To update an attribute that is a Pointer type (for example, the customer field on a request) a handle must be used for the value. For Integer, Date, and Duration types, pass the string representation of an integer.
For example, to update a request with a new assignee, description and priority, the array would appear as follows:
[0] - "assignee" [1] - "cnt:555A043EDDB36D4F97524F2496B35E75" (a contact Handle) [2] - "description" [3] - "My new description" [4] - "priority" [5] - "pri:38903" (a priority Handle)
If the update fails for any reason, the entire operation aborts and no changes occur.
When updating a task, set the status value last in the attribute array.
Returns
A <UDSObject> element containing the updated object’s handle, along with attribute values specified in the
attributes
parameter. If the
attributes
parameter is empty,
all
of the attribute values are returned. List and LREL types are also returned, but as empty elements.