Web Services Business Methods

This article contains the following topics:
casm173
This article contains the following topics:
This section describes the Web Services Business methods.
createIssue
The following parameters apply to the createIssue method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creatorHandle
String
Identifies the handle of the contact responsible for the creation of the issue (the log agent). Pass an empty string to specify the default CA SDM user.
attrVals
String[]
Identifies the array of name-value pairs that is used to set the initial attribute values for the new issue.
Note:
Dotted names are not permitted.
propertyValues
String[]
(Optional) Identifies the array of values for any properties that are attached to the new issue.
template
String
(Optional) Identifies the handle of an issue template (iss_tpl object) from which to create the issue.
attributes
String[]
Identifies the 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.
newIssueHandle
String Holder
Identifies the String Holder object for capturing returned data. See the XML Element Return list below for details.
newIssueNumber
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 Issue (iss) object. For more information about creating an Issue object with properties, see createRequest().
You
must
use this function to create a Issue; do not use createObject().
Returns
Returns the new object handle, along with
all
of its attribute values. List and LREL types are also returned, but as empty elements.
XML Element
Type
Description
<UDSObject>
N/A
Identifies the standard UDSObject element containing the handle and requested attribute values.
<newIssueHandle>
String
Identifies the new issue’s handle.
<newIssueNumber>
String
Identifies the new issue’s number (its “ref_num” attribute).
createRequest
The following parameters apply to the createRequest method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creatorHandle
String
Identifies the handle of the contact responsible for the creation of the request (the log agent). Pass an empty string to specify the default CA SDM user.
attrVals
String[]
Identifies an array of name-value pairs that is used to set the initial attribute values for the new request.
Note:
Dotted names are not permitted.
propertyValues
String[]
Identifies the array of values for any properties that are attached to the new request.
template
String
(Optional) Identifies the handle of the request template (cr_tpl) from which to create the request.
attributes
String[]
Specifies the sequence of attribute names from the new object for which to return values.
Dot-notation is permitted. If this field is empty, all value-based attribute values are returned.
newRequestHandle
String Holder
Specifies the String Holder object for capturing returned data. See the XML Element Return list below for details.
newRequestNumber
String Holder
Specifies the String Holder object for capturing returned data. See the XML Element Return list below for details.
Description
Creates a CA SDM Request (cr) object. You
must
use this function to create a Request; do not use createObject().
propertyValues
is a list of values for each Property object that will be attached to the new Request. The Properties that are attached are determined by the new Request’s ‘category’ attribute value. All properties created from the CA SDM Web Services interface will have a default value (for more information, see Categories and Properties), which is important because a Request will not save until all of its Properties marked “required” have a value.
You may override the default by supplying values for any properties that will be attached when the Request is created. You must supply this information before the Request is created, since createRequest() attempts to back-store the object you most recently create. Use getPropertyInfoForCategory() to get a list of properties for a specific Category. This function returns the properties in order of their ‘sequence’ attribute, which is the expected order of the
propertyValues
array. For example, if the sequences and symbols of the properties are as follows:
100 - Hard Drive Size 200 - CPU 300 - Memory
The
propertyValues
array, depending on the programming language, may appear as follows:
["40 GB", "Pentium 4 1.7 Ghz", "256"]
getPropertyInfoForCategory() indicates which Properties are marked
required
.
If you do not set the Request category or do not want to set any Property values, pass an empty string for
propertyValues.
If you do not want to rely on the default property values, the following is the suggested order for creating a new Request (or Issue or Change Order):
  1. Retrieve a list of Categories/Areas. The object name for Request Area is ‘pcat’.
  2. Call getPropertyInfoForCategory() and examine the list of properties for the category of the new Request/Issue/Change.
  3. Create a value array for each of the properties returned. This is identified by the
    propertyValues
    parameter for the create operation.
  4. Assemble the
    attrVals
    array and call the create method.
As an alternative to the previous procedure, you can retrieve the list of properties using getRelatedListValues() after createRequest() returns. Properties are stored in the ‘properties’ list for a Request.
Depending upon the application, it may be faster to at least cache the list of Categories, since this data does not change often at many client sites.
By default, this method creates a Request. If you are using the ITIL methodology, you need to set the ‘type’ attribute in the attrVals array to define whether you are creating an Incident or a Problem ticket. For more information about ITIL procedures, see ITIL Methodology.
Returns
Returns the new objects handle with
all
of its attribute values. List and LREL types are also returned, but as empty elements.
XML Element
Type
Description
N/A
Identifies the standard UDSObject element containing the handle and requested attribute values.
<newRequestHandle>
String
Identifies the new request handle.
<newRequestNumber>
String
Identifies the new request’s number (its “ref_num” attribute).
createChangeOrder
The following parameters apply to the createChangeOrder method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creatorHandle
String
Identifies the handle of the contact responsible for the creation of the change order (the log agent). Pass an empty string to specify the default CA SDM user.
attrVals
String[]
Identifies an array of name-value pairs that is used to set the initial attribute values for the change order.
Note:
Dotted names are not permitted.
propertyValues
String[]
(Optional) Identifies the array of values for any properties that are attached to the new change order.
template
String
(Optional) Identifies the handle of the change template (chg_tpl object) from which to create the change order.
attributes
String[]
Specifies the sequence of attribute names from the new object for which to return values.
Dot-notation is permitted. If this field is empty, all value-based attribute values are returned.
newChangeHandle
String Holder
Specifies the String Holder object for capturing returned data.
newChangeNumber
String Holder
Specifies the String Holder object for capturing returned data.
Description
Creates a CA SDM Change Order (chg) object. You
must
use this function to create a change order; do not use createObject().
Returns
The new object handle with
all
of its attribute values. List and LREL types are also returned, but as empty elements.
XML Element
Type
Description
<UDSObject>
N/A
Identifies the standard UDSObject element containing the handle and request attribute values.
<newChangeHandle>
String
Identifies the new change order handle.
<newChangeNumber>
String
Identifies the new change order number (its ‘chg_ref_num’ attribute).
createActivityLog
The following parameters apply to the createActivityLog method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creator
String
Identifies the handle of the contact responsible for the activity.
objectHandle
String
Identifies the handle for a request, issue, or change order. Any other object type is rejected.
description
String
Identifies the description for the activity, which will appear in the activity log.
LogType
String
Identifies the type of log to create -- see the following Description.
TimeSpent
Integer
Sets the Time Spent field for the activity log, which is the duration of the activity. Pass zero for the default.
Internal
Boolean
Identifies the values that apply:
True = Internal-only activity
False = Non-internal activity that can be viewed by everyone.
Description
Creates an activity log for a specified request, issue or change order. This method corresponds to, “Activities - Log Comment/Research/Callback” on a Change/Request/Issue detail in the CA SDM interface.
LogType
is the code attribute for the activity type of the new log. The most common codes are as follows:
  • “CB” (Callback)
  • “RS” (Research)
  • “LOG” (Log Comment)
The CA SDM Administrative Client also shows the code values. To access the code values, select from the Main Menu Administration, then select Notification, Activity Notifications.
Returns
The handle to the activity log object created.
XML Element
Type
Description
<LogHandle>
String
Identifies the handle for the new activity log.
transfer
The following parameters apply to the transfer method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creator
String
Identifies the handle of the contact responsible for the activity.
objectHandle
String
Identifies the handle for a request, issue, or change order. Any other object type is rejected.
description
String
Identifies the description for the activity, which will appear in the activity log.
setAssignee
Boolean
Used to update the assignee field with the value in newAssignee, if the value is true.
newAssigneeHandle
String
Identifies the new assignee for the object.
setGroup
Boolean
Updates the group field, if true.
newGroupHandle
String
Identifies the new group for the object.
setOrganization
Boolean
Update the organization, if the value is true.
newOrgnizationHandle
String
(Issues and Change Orders only) Identifies the new organization for the object.
Description
Performs a transfer activity on an Issue, Request or Change Order. This method corresponds to the “Activities -- Transfer” command in the CA SDM interface. This method generates an activity log and optionally sets a new assignee, group, or organization.
The assignee, group or organization is not updated unless one or more of the corresponding
setAssignee/setGroup/setOrganization
parameters is set to true.
If the companion parameter is false, then transfer will not attempt to update the field, even if a value is passed for that field. For example, if
setAssignee
is passed as false, transfer will not update the assignee even if
newAssignee
specifies a value. If the
setXXXX
parameter is true, then the field is updated. Pass the empty string to set a field to empty/null.
Returns
One or more handles to the activity log objects created. The returns are under a parent element named <Logs>.
XML Element
Type
Description
<LogHandle>
String
Identifies the handle for the new activity log (zero or more of these can be returned).
escalate
The following parameters apply to the escalate method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creator
String
Identifies the handle of the contact responsible for the activity.
objectHandle
String
Identifies the handle for a request, issue, or change order. Any other object type is rejected.
description
String
Identifies the description for the activity, which will appear in the activity log.
setAssignee
Boolean
Updates the assignee field, if true.
newAssigneeHandle
String
Identifies the handle of the new assignee for the object
.
setGroup
Boolean
Updates the group field with the value in newGroupHandle, if true.
newGroupHandle
String
Identifies the handle of the new group for the object
.
setOrganization
Boolean
Sets the organization field with the value specified in the newOrganizationHandle, if true.
newOrgnizationHandle
String
(Issues and Change Orders only) Identifies the handle of the new organization for the object
.
setPriorityHandle
Boolean
Updates the priority field with the value specified in newPriority, if true.
newPriority
String
Identifies the handle of the new priority for the object.
Description
Performs an escalate activity on an Issue, Request or Change Order. This method generates an activity log and optionally sets a new assignee, group, priority and/or organization.
It corresponds to the “Activities -- Escalate” command in the CA SDM interface.
The assignee, group, or organization is not updated unless one or more of the corresponding
setAssignee/setGroup/setOrganization
parameters is set to true. If the companion parameter is false, then escalate will not attempt to update the field, even if a value is passed for that field. For example, if
setAssignee
is passed as false, escalate will not update the assignee even if
newAssignee
specifies a value. If the
setXXXX
parameter is true, then the field is updated. Pass the empty string to set a field to empty/null.
Organization is not used for Requests.
Returns
One or more handles to the activity log objects created.
XML Element
Type
Description
<LogHandle>
String
Identifies the handle for the new activity log (zero or more of these can be returned).
changeStatus
The following parameters apply to the changeStatus method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
creator
String
Identifies the handle of the contact responsible for the activity.
objectHandle
String
Identifies the handle for a request, issue, or change order. Any other object type is rejected.
description
String
Identifies the description for the activity, which will appear in the activity log.
newStatusHandle
String
Identifies the handle of the status for the object.
Description
Performs a status change activity on an issue, request, or change order. This method generates an activity log and optionally sets the status value. It corresponds to the “Activites -- Update Status” command in the CA SDM interface.
Returns
The handle to the activity log object created.
XML Element
Type
Description
<LogHandle>
String
Identifies the handle for the new activity log (zero or more of these can be returned).
getPropertyInfoForCategory
The following parameters apply to the getPropertyInfoForCategory method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
categoryHandle
String
Identifies a category handle.
attributes
String[]
Identifies the names of one or more attributes from the property template object for which to fetch values. If this is empty, all value-based attributes are fetched.
Description
Information about Properties for the specified category. This method is used to help pre-populate Request/Issue/Change Order properties on insert operations with user-defined data.
Depending on the category, this method queries either the ‘prptpl’ or the ‘cr_prptpl’ object types. Both types are nearly identical. The suggested attributes to fetch are ‘sequence’, ‘label’, ‘description’ and ‘required’.
Returns
A <UDSObject> element containing a sequence of <UDSObject> elements, in the order of the ‘sequence’ attribute.
logComment
The following parameters apply to the logComment method:
Parameter
Type
Description
SID
Integer
Identifies the session retrieved from logging in.
ticketHandle
String
Identifies the handle of the ticket where the activity log should be added.
Comment
String
Identifies the comment text.
internal_flag
String
Identifies the internal flag. Set to True if the new activity log should be marked as internal.
Description
Attaches a ‘Log Comment’ activity log to a ticket. It is a simplified version of createActivityLog().
Returns
Nothing.