CA Service Management - 14.1

17.3 17.2 17.1 14.1
English

Web Services Methods

This article contains the following topics:
casm1401
This article contains the following topics:
This section provides the details for using the Web Services methods. Each method explains the parameters, description, and returns.
Web Services Method Summary
The following table provides a summary of web services methods in the product:
Method Name (Input Parameters)
Return Type [XML Root Element]
Output Parameters (Type: StringHolder) [XML Root Element]
Description
addAssetLog
(int sid, String assetHandle, String contactHandle, String logText)
void
 
Adds a new log entry to an asset.
addBookmark
(int sid, String contactId, int docId)
String
[UDSObject]
 
Adds a bookmark to a knowledge document.
addComment
(int sid, String comment, int docId, String email, String username, String contactId)
String
[UDSObject]
 
Adds a comment to a knowledge document.
addMemberToGroup
(int sid, String contactHandle, String groupHandle)
void
 
Adds a contact to a group.
attachChangeToRequest
(int sid, String creator, String requestHandle, String changeHandle, ArrayOfString changeAttrVals, String description)
String
 
Attaches a new or existing change order to a request.
attachURLLink
(int sid, int docId, String url, String attmntName, String description)
int
 
Attaches a URL link to a knowledge document.
attmntFolderLinkCount
(int sid, int folderId)
int
 
Returns the number of attachment links for a folder.
callServerMethod
(int sid, String methodName, String factoryName, String formatList, ArrayOfString parameters)
String
[ServerReturn]
 
Invokes any arbitrary server-side method.
changeStatus
(int sid, String creator, String objectHandle, String description, String newStatusHandle)
String
[UDSObject
(Handle only)]
 
Performs an update status activity on a ticket.
clearNotification
(int sid, String lrObject, String clearBy)
int
 
Clears a notification message.
closeTicket
(int sid, String description, String ticketHandle)
String
[UDSObject
(Handle only)]
 
Sets the status of the ticket to Closed.
createActivityLog
(int sid, String creator, String objectHandle, String description, String logType, int timeSpent, boolean internal)
String
[UDSObject
(Handle only)]
 
Creates an activity log entry for a ticket.
createAsset
(int sid, ArrayOfString attrVals, ArrayOfString attributes, StringHolder createAssetResult, StringHolder newAssetHandle, StringHolder newExtensionHandle, StringHolder newExtensionName)
void
createAssetResult
[UDSObject]
newAssetHandle
newExtensionHandle
newExtensionName
Creates a configuration item (asset).
createAssetParentChildRelationship
(int sid, String parentHandle, String childHandle)
String
 
Creates an asset parent-child relationship.
createAttachment
(int sid, String repositoryHandle, String objectHandle, String description, String fileName)
String
 
Uploads a file to the back-end server and attaches it to a ticket.
createAttmnt
(int sid, String repositoryHandle, int folderId, int objectHandle, String description, String fileName)
String
 
Uploads a file to the back-end server and attaches it to a knowledge document.
createChangeOrder
(int sid, String creatorHandle, ArrayOfString attrVals, ArrayOfString propertyValues, String template, ArrayOfString attributes, StringHolder newChangeHandle, StringHolder newChangeNumber)
String
[UDSObject]
newChangeHandle
newChangeNumber
Creates a Change Order ticket.
createDocument
(int sid, ArrayOfString kdAttributes)
String
[UDSObjectList]
 
Creates a knowledge document.
createFolder
(int sid, int parentFolderId, int repId, int folderType, String description, String folderName)
String
[UDSObject]
 
Creates a folder in an attachment repository.
createIssue
(int sid, String creatorHandle, ArrayOfString attrVals, ArrayOfString propertyValues, String template, ArrayOfString attributes, StringHolder newIssueHandle, StringHolder newIssueNumber)
String
[UDSObject]
newIssueHandle
newIssueNumber
Creates an Issue ticket.
createLrelRelationships
(int sid, String contextObject, String lrelName, ArrayOfString addObjectHandles)
void
 
Adds one or more many-to-many relationships.
createObject
(int sid, String objectType, ArrayOfString attrVals, ArrayOfString attributes, StringHolder createObjectResult, StringHolder newHandle)
void
createObjectResult
[UDSObject]
newHandle
Creates any CA SDM object.
createQuickTicket
(int sid, String customerHandle, String description, StringHolder newTicketHandle, StringHolder newTicketNumber)
String
[UDSObject]
newTicketHandle
newTicketNumber
Creates a ticket based on the preferred document type of the given end user.
createRequest
(int sid, String creatorHandle, ArrayOfString attrVals, ArrayOfString propertyValues, String template, ArrayOfString attributes, StringHolder newRequestHandle, StringHolder newRequestNumber)
String
[UDSObject]
newRequestHandle
newRequestNumber
Creates a Request ticket.
createTicket
(int sid, String description, String problem_type, String userid, String asset, String duplication_id, StringHolder newTicketHandle, StringHolder newTicketNumber, StringHolder returnUserData, StringHolder returnApplicationData)
String
[UDSObject (empty)]
newTicketHandle
newTicketNumber
returnUserData
returnApplicationData
Creates a ticket based on the rules defined in the Service Aware Policy and the given Problem Type.
createWorkFlowTask
(int sid, ArrayOfString attrVals, String objectHandle, String creatorHandle, String selectedWorkFlow, String taskType, ArrayOfString attributes, StringHolder createWorkFlowTaskResult, StringHolder newHandle)
void
createWorkFlowTaskResult
[UDSObject]
newHandle
Creates Workflow Task.
deleteBookmark
(int sid, String contactId, int docId)
int
 
Deletes a bookmark from a knowledge document.
deleteComment
(int sid, int commentId)
int
 
Deletes a comment for a knowledge document.
deleteDocument
(int sid, int docId)
int
 
Flags a knowledge document for deletion.
deleteWorkFlowTask
(int sid, String workFlowHandle, String objectHandle)
void
 
Removes a workflow task from its associated ticket.
detachChangeFromRequest
(int sid, String creator, String requestHandle, String description)
String
 
Detaches a change order from a request.
doQuery
(int sid, String objectType, String whereClause)
ListResult
[listHandle, listLength]
 
Performs a SQL-like select on the specified object type.
doSelect
(int sid, String objectType, String whereClause, int maxRows, ArrayOfString attributes)
String
[UDSObjectList]
 
Performs a SQL-like select on the specified object type.
doSelectKD
(int sid, String whereClause, String sortBy, boolean desc, int maxRows, ArrayOfString attributes, int skip)
String
[UDSObjectList]
 
Performs a SQL-like select on the knowledge document object.
escalate
(int sid, String creator, String objectHandle, String description, boolean setAssignee, String newAssigneeHandle, boolean setGroup, String newGroupHandle, boolean setOrganization, String newOrganizationHandle, boolean setPriority, String newPriorityHandle)
String
[UDSObject
(Handle only)]
 
Performs an escalate activity on a ticket.
faq
(int sid, String categoryIds, int resultSize, String propertyList, String sortBy, boolean descending, String whereClause, int maxDocIDs)
String
[UDSObjectList]
 
Performs a faq search on knowledge documents.
findContacts
(int sid, String userName, String lastName, String firstName, String email, String accessType, int inactiveFlag)
String
[UDSObjectList]
 
Retrieves a list of contacts.
freeListHandles
(int sid, ArrayOfInt handles)
void
 
Frees the server-side resources for lists and invalidates the list handles.
getAccessTypeForContact
(int sid, String contactHandle)
String
 
Returns a handle for the Access Type of a contact.
getArtifact
(int sid, String contact, String password)
String
 
Returns an artifact for appending to URLs.
getAssetExtensionInformation
(int sid, String assetHandle, ArrayOfString attributes, StringHolder getAssetExtInfoResult, StringHolder extensionHandle, StringHolder extensionName)
void
getAssetExtInfoResult
[UDSObject]
extensionHandle
extensionName
Returns extension information for an asset.
getAttmntInfo
(int sid, int attmntId)
String
[UDSObjectList]
 
Returns the attributes for an attachment.
getAttmntList
(int sid, int folderId, int repId)
String
[UDSObjectList]
 
Returns a list of attachments under a given attachment folder.
getAttmntListPerKD
(int sid, int docId)
String
[UDSObjectList]
 
Returns a list of attachments for a given knowledge document.
getBookmarks
(int sid, String contactId)
String
[UDSObjectList]
 
Retrieves bookmarks for a given contact.
getBopsid
(int sid, String contact)
String
 
Returns a token for appending to URLs.
getCategory
(int sid, int catId, boolean getCategoryPaths)
String
[UDSObjectList]
 
Retrieves information for a knowledge category.
getComments
(int sid, String docIds)
String
[UDSObjectList]
 
Retrieves all comments from the list of knowledge documents.
getConfigurationMode
(int sid)
String
 
Returns confirmation if CA SDM is running in ITIL mode.
getContact
(int sid, String contactId)
String
[UDSObject]
 
Retrieves information for a given contact.
getDecisionTrees
(int sid, String propertyList, String sortBy, boolean descending)
String
[UDSObjectList]
 
Retrieves all Decision Tree knowledge documents.
getDependentAttrControls
(int sid, String handle, ArrayOfString attrVals)
String
[UDSObjectList]
 
Returns a list of locked and required attributes for the Status object.
getDocument
(int sid, int docId, String propertyList, boolean relatedDoc, boolean getAttmnt, boolean getHistory, boolean getComment, boolean getNotiList)
String
[UDSObject]
 
Retrieves information for a knowledge document.
getDocumentsByIDs
(int sid, String docIds, String propertyList, String sortBy, boolean descending)
String
[UDSObjectList]
 
Retrieves information for one or more knowledge documents.
getDocumentTypes
(int sid)
String
[UDSObjectList]
 
Returns a list of all knowledge document types.
getFolderInfo
(int sid, int folderId)
String
[UDSObject]
 
Retrieves information for a given attachment folder.
getFolderList
(int sid, int parentFolderId, int repId)
String
[UDSObjectList]
 
Returns a list of folders under a given parent folder.
getGroupMemberListValues
(int sid, String whereClause, int numToFetch, ArrayOfString attributes)
String
[UDSObjectList]
 
Queries the group of the system and member relationship.
getHandleForUserid
(int sid, String userID)
String
 
Returns the persistent handle for a contact.
getKDListPerAttmnt
(int sid, int attmntId)
String
[UDSObjectList]
 
Returns a list of knowledge documents with reference to a given attachment.
getListValues
(int sid, int listHandle, int startIndex, int endIndex, ArrayOfString attributeNames)
String
[UDSObjectList]
 
Returns attribute values for a range of objects in a list.
getLrelLength
(int sid, String contextObject, String lrelName)
int
 
Returns the number of objects on one side of a many-to-many relationship.
getLrelValues
(int sid, String contextObject, String lrelName, int startIndex, int endIndex, ArrayOfString attributes)
String
[UDSObjectList]
 
Returns attribute values for a range of objects in a many-to-many relationship.
getNotificationsForContact
(int sid, String contactHandle, int queryStatus)
ListResult
[listHandle, listLength]
 
Returns a list handle of notifications (lr objects) for a given contact.
getObjectTypeInformation
(int sid, String factory)
String
[UDSObject (special)]
 
Returns a list of all attribute names for a given object.
getObjectValues
(int sid, String objectHandle, ArrayOfString attributes)
String
[UDSObject]
 
Returns the attribute values for a given object handle.
getPendingChangeTaskListForContact
(int sid, String contactHandle)
ListResult
[listHandle, listLength]
 
Returns all the pending change order workflow tasks assigned to a given contact.
getPendingIssueTaskListForContact
(int sid, String contactHandle)
ListResult
[listHandle, listLength]
 
Returns all the pending issue workflow tasks assigned to a contact.
getPermissionGroups
(int sid, int groupId)
String
[UDSObjectList]
 
Retrieves info for a permission group.
getPolicyInfo
(int sid)
String
[SAPolicy]
 
Returns information about the access policy for the current session.
getPriorities
(int sid)
String
[UDSObjectList]
 
Retrieves all the knowledge priorities.
getPropertyInfoForCategory
(int sid, String categoryHandle, ArrayOfString attributes)
String
[UDSObjectList]
 
Retrieves property information for a given category.
getQuestionsAsked
(int sid, int resultSize, boolean descending)
String
[UDSObjectList]
 
Retrieves historical knowledge document search text.
getRelatedList
(int sid, String objectHandle, String listName)
ListResult
[listHandle, listLength]
 
Returns a list handle for a list (QREL or BREL) of an object.
getRelatedListValues
(int sid, String objectHandle, String listName, int numToFetch, ArrayOfString attributes, StringHolder getRelatedListValuesResult, IntHolder numRowsFound)
void
getRelatedListValuesResult
[UDSObjectList]
numRowsFound
(IntHolder)
Returns values for lists of an object.
getRepositoryInfo
(int sid, int repositoryId)
String
[UDSObject]
 
Returns information of a repository.
getStatuses
(int sid)
String
[UDSObjectList]
 
Retrieves all the knowledge statuses.
getTaskListValues
(int sid, String objectHandle, ArrayOfString attributes)
String
[UDSObjectList]
 
Returns values for tasks associated with a given issue or change order.
getTemplateList
(int sid)
String
[UDSObjectList]
 
Retrieves all the document templates.
getValidTaskTransitions
(int sid, String taskHandle, ArrayOfString attributes)
String
[UDSObjectList]
 
Returns all possible status transitions for a particular task.
Returns all possible status transitions for a particular task.
String
[UDSObjectList]
 
Returns all possible status transitions for a particular ticket.
getWorkflowTemplateList
(int sid)
String
[UDSObjectList]
 
Retrieves all the knowledge workflow templates.
getWorkFlowTemplates
(int sid, String objectHandle, ArrayOfString attributes)
String
[UDSObjectList]
 
Returns all the workflow templates associated with the category of a change order or issue.
impersonate
(int sid, String userid)
int
 
Invalidates the old session and returns a new session ID for the new user.
isAttmntLinkedKD
(int sid, int attmntId)
int
 
Returns the number of attachment links to all knowledge documents.
logComment
(int sid, String ticketHandle, String comment, int internalFlag)
void
 
Performs a log comment activity on a ticket.
login
(String username, String password)
int
 
Authenticates a user and returns a unique session ID.
loginService
(String username, String password, String policy)
int
 
Authenticates a user and returns a unique session ID.
loginServiceManaged
(String policy, String encrypted_policy)
String
 
Performs user authentication for PKI configurations and returns a session ID.
loginWithArtifact
(String userid, String artifact)
int
 
Authenticates a user with artifact and returns a unique session ID.
logout
(int sid)
void
 
Invalidates and frees a session ID.
modifyDocument
(int sid, int docId, ArrayOfString kdAttributes)
String
[UDSObject]
 
Updates a knowledge document.
notifyContacts
(int sid, String creator, String contextObject, String messageTitle, String messageBody, int notifyLevel, ArrayOfString notifyees, boolean internal)
String
[UDSObject (Handle only)]
 
Sends a notification to one or more contacts.
rateDocument
(int sid, int docId, int rating, int multiplier, String ticketPerId, boolean onTicketAccept, boolean solveUserProblem, boolean isDefault)
String
[UDSObjectList]
 
Rates a particular knowledge document.
removeAttachment
(int sid, String attHandle)
int
 
Removes an attachment from a ticket.
removeLrelRelationships
(int sid, String contextObject, String lrelName, ArrayOfString removeObjectHandles)
void
 
Removes one or more many-to-many relationships.
removeMemberFromGroup
(int sid, String contactHandle, String groupHandle)
void
 
Removes a contact from a group.
search
(int sid, String problem, int resultSize, String properties, String sortBy, boolean descending, boolean relatedCategories, int searchType, int matchType, int searchField, String categoryPath, String whereClause, int maxDocIDs)
String
[UDSObjectList (nested)]
 
Searches for knowledge document solutions.
serverStatus
(int sid)
int
 
Returns the status (up or down) of the CA SDM server.
transfer
(int sid, String creator, String objectHandle, String description, boolean setAssignee, String newAssigneeHandle, boolean setGroup, String newGroupHandle, boolean setOrganization, String newOrganizationHandle)
String
[UDSObject
(Handle only)]
 
Performs a transfer activity on a ticket.
updateObject
(int sid, String objectHandle, ArrayOfString attrVals, ArrayOfString attributes)
String
[UDSObject]
 
Updates one or more attributes for a given object.
updateRating
(int sid, int buId, int rate)
String
[UDSObject]
 
Updates an existing rating of a knowledge document.
loginWithArtifact
(String userid, String artifact)
int
 
Authenticates a user with artifact and returns a unique session ID.
getArtifact
(int sid, String contact, String password)
String
 
Returns an artifact for appending to URLs.
 
XML Object Returns
Many of the Web Services methods return an XML representation of CA SDM objects. The Web Services uses a standard XML structure beginning with the following root element:
<UDSObject>
The format of the XML representation is described in the following table:
XML Element
Type
Description
<UDSObject>
N/A
Identifies the root node.
<Handle>
String
Identifies the object’s handle.
<Attributes>
Sequence
Identifies the attribute values. This holds zero or more elements for the object’s attribute values.
<
attrName0
DataType =
“typeEnum">
String
Identifies the
AttrName0,
 which is an object attribute name as defined in the CA SDM majic (.maj) or mod (.mod) file.
This name may use dot-notation depending on the web method used.
The element’s value is the attribute’s value. An empty element indicates a null/empty value for this object’s attribute.
The DataType attribute is an integer indicating the attribute’s data type in the CA SDM environment.
For example, a call to getObjectValues() can return information illustrated by the following:
<UDSObject>
	<Handle>cnt:555A043EDDB36D4F97524F2496B35E75</Handle>
	<Attributes>
		<Attribute DataType="2003">
			<AttrName>first_name</AttrName>
			<AttrValue>first name</AttrValue>
			<DisplayValue>Yaakov</DisplayValue>
		</Attribute>
		<Attribute DataType="2005">
			<AttrName>organization</AttrName>
				<AttrValue>342</AttrValue>
		<DisplayValue>Accounting Crew</DisplayValue>
	</Attribute>
</Attributes>
	<Lists>		<List name="mylist1">
			<UDSObject>...</UDSObject>
			<UDSObject>...</UDSObject>
		</List>
	</Lists>
</UDSObject>
Some methods, such as doSelect(), return a sequence of <UDSObject> elements contained inside a <UDSObjectList> element.
The <Lists> section holds zero or more <List> nodes. A <List> node holds zero or more <UDSObject> nodes. <List> elements are generally returned only when a specific request for list values is made.
When you want to return a list of values related to a specific object, you should use the
getRelatedListValues
 method.
If a request is made just for a list with no attribute name, such as actlog, then the entire <UDSObject> is returned in the <List> section.
Specialized methods, like getDocument(), can of course be different. When a request is made for an attribute, the database value is returned. For SREL attributes, this may not be so useful. Requesting the assignee attribute of a Request returns an integer because the Contact REL_ATTR (foreign key) is its ID. For CA Service Desk Manager r11.0, the return data for attributes includes elements for the DBMS and common name value of SREL references.