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.