Home

Unicenter Service Desk Web Services User Guide

1. 91 createRequest i reis ets tesa ier IR ERRRE EFIE URIKRRY nes cies EXER EREREEKN KEY RIA KU UR en ERROR I ERE wks 92 createChangeOFder s rne rh Ea TOE AX MUR D FUE KMERE NEG ieee RR MEAE 95 getPropertylnfoForCategory 0 essen esee es enie sess e ine ese eene ene nnn 97 uai 98 SCA ALS e Pe T LU EM 100 chiangeStatus 5c oce pt b IR dM ER RP MP NIME RIEN RPM TION A nda Rd 102 agris audire 103 attachGhangelORequest nece ere Pee baee ex e es Rd x Ma ee ER iEn nS RR EAR REA 105 detachChangeFromhRequUest 1 err re e heit teca eux tee e deg e DER RE EL e C Ra od 108 lO JCO ENE ERES EE ETE OLD LEES 108 notify Contacts eniin Ue beet enki paddy ne e ba Preterea Pelle Leva dus pe ee ewan Re ERA a aes 109 CleArNOUiMlCatlON poe TUUS 111 e uiuejlterdbrjieee e A A A A A N 112 e Suidas ETE 113 getValidTaskTransitiors ierit tior Pra reote EEA E NEEE E EEEE vica ea alegres 114 Asset Management Methods 5 cose ease iiie E CEE Pra su e tela lores Vete ed Eee deer Ear encin 116 ClGateASSQL rcc ier etes indes T 117 getAssetExtensionl nformation essssssessssessssssssssssssne sehe mese senes eee een 119 Cepit a EAT A AEE A ETET A EA E R A AEEA 120 createAssetParentChildRelationship s ssssssrssssrrsrrrstrinnrttntrn nents 121 List Query uiuere DELL 122 COS CISC E Sem ECT 122 JOQ UEY EE 125 duin INC EE E a E S E EEE EO EA E E EE E 126 freekistElandles cc
2. The string representation of a uuid is surrounded by single quotes and prefixed with a capital U character The string representation of a UUID value is the id part of an object handle Using the previous example if you know that the handle for a particular contact is cnt 9313B485771E1B347968E530276916387 you can form the query as shown by the following example assignee id U 913B485771E18347968E530276916387 Do not form where clauses querying the persistent id attribute as in the following example rootcause persistent id rc 1234 For more information about handles see Out of the Box Handles Common Elements 63 Where Clauses IN Clause The IN clause requires some special explanation The two syntactic forms are SREL attr name subq WHERE attr attr IN valuel value2 SREL attr name subq SELECT attr LIST name subq WHERE attr IN valuel value2 41 The left side of the clause must begin with an SREL type attribute of the table being queried which is represented by SREL attr name subq WHERE attr is an attribute of the foreign object which itself may be another SREL pointer For example a query against the request cr object may be coded as follows category sym IN Soft Email This translates to the following pseudo SQL SELECT FROM cr WHERE cr category IN SELECT persistent id FROM pcat WHERE sym LIKE Soft OR sym Email In the previous sub query
3. A D aType 2005 gt ame gt organization lt AttrName gt AttrVal ue 342 AttrVal ue Di spl ayVal ue Accounti ng Crew Displ ayVal ue Attribute Attributes Li sts List namez mylistl UDSObj ect UDSObj ect gt UDSObj ect gt UDSObj ect gt List Lists lt UDSObj ect gt Some methods such as doSelect return a sequence of lt UDSObject gt elements contained inside a lt UDSObjectList gt element The lt Lists gt section holds zero or more lt List gt nodes A lt List gt node holds zero or more lt UDSObject gt nodes lt List gt elements are generally returned only when a specific request for list values is made For the generic data retrieval methods such as getObject a list is requested by naming it in the return value array The list requested must be a BREL QREL LREL defined for the object The list is requested in the parameter array of the form listname attribute where listname is the name of a QREL BREL LREL for example for the Request object actlog description actlog time_spent and so on Requests for multiple values from the same list source are consolidated into a single lt List gt return such as the previous example should only return one lt List gt element for the actlog list The contents are lt UDSObjects gt with two attributes time_spent and description If a request is made just for a list with n
4. Handl e Attributes Attri buteName0 Attri buteNamel Web ServicesMethods 127 List Query Methods Returns The following XML Element Type lt UDSObjectList gt Sequence lt UDSObject gt N A free ListHa ndles Description Identifies the outer Element which contains a sequence of lt UDSObject gt elements Contains a lt Handle gt element and lt Attributes gt sequence For information about the contents of each lt UDSObject gt element see XML Object Returns The following parameters apply to the freeListHandles method Parameter Type SID Integer Handles Integer Description Description Identifies the session retrieved from logging in Identifies an array of list handles to free Frees the server side resources for a list and invalidates the list handles This method should be called whenever a list reference is no longer needed Returns Nothing 128 Web Services User Guide Lis Query Methods getRelatedList The following parameters apply to the getRelatedList method Parameter Type SID Integer Description Description Identifies the session retrieved from logging in ObjectHandle String Identifies the object handle ListName String Identifies a list type attribute name of the object Returns a list handle for list QREL or BREL attribute of an object For example the request object has a related list named children which is
5. Identifies the contact handle Returns a list handle representing all the pending change order workflow tasks assigned to a contact A pending task is an active workflow task with a status that permits task updates Returns The following XML Element Type lt listHandle gt Integer lt listLength gt Integer getPendinglssueTaskListForC ontact Description Identifies the list handle Identifies the length of the list generated The following parameters apply to the getPendingl ssueTaskListForContact method Parameter Type SID Integer contactHandle String 132 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the contact handle Description Lis Query Methods Returns a list handle representing all the pending Issue tasks assigned to a contact A pending task is an active task with a status that permits task updates Returns The following XML Element Type lt listHandle gt Integer lt listLength gt Integer getNotific ationsForC ontact Description Identifies the list handle Identifies the length of list generated The following parameters apply to the getNotificationsForContact method Parameter Type SID Integer contactHandle String queryStatus Integer Description Identifies the session retrieved from logging in Identifies the contact handle Optional Identifies the target of the notifications Web
6. findContacts Contact Management Methods XML Element Type Description ReturnAppCode String Identifies the user specified data for the problem type intended for use within the application code especially for actions You can set this value in the Application Data Return field on the Returned Data tab of the Problem Type Detail window ReturnUserCode String Identifies the user specified data for the problem type intended for display to the end user or for log entries You can set this value in the User Data Return field on the Returned Data tab of the Problem Type Detail window The following parameters apply to the findContacts method Parameter Type Description SID Integer Identifies the session retrieved from logging in userName String Returns only the contacts with this user name You can do wildcard searches by using the percent 96 sign For example to search for all contacts where the User Name begins with Smi specify Smi lastName String Returns only the contacts with this last name You can do wildcard searches by using the percent 96 sign Web Services Methods 79 Contact Management Methods Parameter Type Description firstName String Returns only the contacts with this first name You can do wildcard searches by using the percent 96 sign email String Returns only the contacts with this email address You can do wildcard searches by using the percent 96 sign accessTyp
7. 1005 1006 1007 Use the Web Services Description 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 An error occurred updating an object Make sure all required attributes were set and check the system log An error occurred creating a new object Make sure all required attributes were set and check the system logs 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 The current method timed out the Service Desk server may be heavily loaded or the method itself was bad The Service Desk server connection is lost UDS methods will no longer function and all list references are lost Unicenter Service Desk Web Services 53 Use the Web Services Error Name UDS FETCH ERR UDS BAD SESSION UDS CNTXT TIMEOUT UDS SECURE CHANNEL REQUIRED UDS SECURITY VIOLATION UDS OVER POLICY LIMIT 54 Web ServicesUser Guide Value 1008 1010 1011 1012 1013 3002 Description An error occurred while retrieving list data An invalid SID was used The SID timed out The Web Services or a web service method requires a secure channel for example SSL for access but an unsecured channel is being used See the Security section The attempted
8. Business Methods Parameter Type Description propertyValues String Optional Identifies the array of values for any properties that are attached to the new 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 Description Creates a Service Desk Change Order chg object You must use this function to create a new change order do not use createObject For more information about creating a Change Order object with properties see createRequest Returns The new object s handle along with all of its attribute values List and LREL types are also returned but as empty elements For more information about the return format see XML Object Returns XML Element Type Description lt UDSObject gt N A Identifies the standard UDSObject element containing the handle and request attribute values lt NewChangeHandle gt String Identifies the new change order s handle lt NewChangeNumber gt String Identifies the new change order s number its chg_ref_num attribute 96 Web Services User Guide Business Methods getPropertyInfoFoiC ategory The following parameters apply to the getPropertyl nfoForCategory method Parameter Type Description SID Integer Identifies the session retrieved from logging in categoryHandle String I
9. pcat is the object name pointed to by cr category The second form of the IN clause can search through QREL or BREL lists For example to find all requests assigned to an analyst in a specific group the clause is as follows assignee member group list group IN U 913B485771E1B347968E530276916387 The first part of the clause assignee is an SREL foreign key of the cr object pointing to the cnt object Next group_list which is an attribute of the cnt object is a list of cnt objects that represent groups to which a contact belongs The last part group forms the first part of the where clause for the IN sub query U 913B485771E1B347968E530276916387is the foreign key value to match on group The sub query return is specified by member This translates to the following pseudo SQL statement SELECT FROM cr WHERE cr assignee IN SELECT member from grpmem WHERE group U 9138485771E1B347968E530276916387 You can specify multiple foreign keys for matching multiple objects by providing a comma separated list assignee member group list group IN U 913B485771E1B347968E530276916387 U 9138485771E1B347968E530276916300 You cannot extend the dot notation for this use of the IN clause for example the following is not valid assignee member group list group last name IN Account Center 64 Web Services User Guide Where Clauses One use of IN is to avoid Cartesian products For example the following query r
10. 36 Web Services User Guide Simplified Web Services Access Simplified Web Services Access Unicenter Service Desk Web Services provides an abbreviated set of high level web services methods that are simplified versions of existing web services methods The majority of users applications do not have to completely rely on a large set of web services methods before requesting service desk services through Unicenter Service Desk Web Services Working closely with user defined access policies and using default parameters defined in the policies this set of high level web services methods can function with little knowledge of the Service Desk object schema Also the high level methods cover a common set of Service Desk functionalities that most ServiceAware applications need The following describes the use of these high level web services methods createTicket SI D Description Problem Type Userid Asset Duplicationl D You must specify a problem type for the reported problem if you use this method The problem type should contain the ticket template appropriate for the ticket you want to create It should define the action to take in the case of a duplicate ticket specify the data outputs and finally it must be associated to the access policy that is defined for the user application When this method is invoked Unicenter Service Desk Web Services locates the current access policy and the problem type required for the ticket creatio
11. Description Represents the binary combination of fields in which to search Title 2 1 Summary 2 Problem 4 Resolution 8 For example to search all fields specify 15 1 2 4 8 To search in Summary and Problem only specify 6 2 4 Note The default is to search Problem If you set the searchType parameter to NLS the searchFields parameter is ignored because NLS searches can only search the Problem field Limits the results of the search to a specific category or categories You need to specify the full ID path to the category and separate multiple categories with commas For example 1 3 5 1 4 8 to limit the search to categories 5 and 8 and their sub categories Use this to add your own SQL where clause for filtering the results of the search Represents the maximum amount of document IDs allowed to be returned For example if you specify a resultSize of 10 and a maxDoclds of 50 if there are 100 matching documents in the database then 10 have their detailed information retrieved and 40 have just their IDs returned The remaining 50 are not returned at all The default is 100 doSelectKD Knowledge Tools Description Searches for solutions to a problem Documents are retrieved based on the problem that is passed Any documents matching the description of the problem or a similar description are returned To improve performance these methods only retrieve detailed information on
12. Description Returns all of the possible values for the status attribute of a particular task The Status codes to which a task may be set depend upon several factors such as the current status of the task and restrictions set by the administrator Note taskHandle can be a task owned by either a change order or an issue The objects returned are Task Status tskstat objects used for both types of tasks Returns zero or more Status objects to which a task can be set Returns The following XML Element Type Description lt UDSObjectList gt N A Identifies the outer element which contains zero or more lt UDSObject gt elements with the requested attribute values For information about the contents of each lt UDSObject gt element see XML Object Returns Web Services Methods 115 Asset Management Methods Asset Management Methods It is possible for a client site to enhance the asset object using extensions Asset extensions are separate tables that hold extra attribute information for an asset The extension table is linked to a particular asset by using the asset ID as a foreign key Unicenter Service Desk Web Services ships two predefined extensions Computer and Software For more information read the text executed by the following command bopcfg majic assetx maj The asset s family attribute determines if the asset has an extension Setting the Class attribute generally sets the family at ass
13. String String Boolean Boolean Integer Integer Knowledge Tools Description Identifies the number of documents for which you want to retrieve detailed information The remaining documents have their IDs returned only Detailed information for these documents can be accessed later using the getDocumentsByl Ds method The default is 10 Identifies the comma separated list of database fields from which you want to retrieve information The following fields are always returned regardless of the propertyList parameter id DOC TYPE ID Identifies the database field that you want to use for sorting the results Multiple sort fields are not supported The default is RELEVANCE When id is a secondary sort it always sorts the results For a valid sort property see the faq method Identifies an indicator you can use for sorting the results in descending order Returns a list of all related categories for the documents found Type of search to perform a 1 Natural Language Search NLS a 2 Keyword search Represents the type of match 0 OR type match a 1 AND type match m 2 Exact match Note If NLS is selected for the searchType parameter then only the OR and AND matchTypes are valid Web ServicesMethods 145 Knowledge Tools Parameter searchFields categoryPaths whereClause maxDoclds 146 Web Services User Guide Type Integer String String Integer
14. Therefore it is important to free lists Unlike object handles list handles are not persistent across sessions I nteger I ndex Several methods require an integer index into a list Lists are zero based so the first element is at index 0 As previously mentioned using list handles is most useful for larger sets of data that may be queried multiple times For some operations however lists are excessive Several methods are provided but the most notable is doSelect as it returns requested information about a set of data without the overhead of list handles Common Elements 59 Lists The decision to use list handles versus methods such as doSelect is one of performance and convenience For example suppose your application does processing on all 15 000 Contacts in your system The doSelect method can retrieve all the contact data in one call but the reply will be delayed and will negatively impact overall system performance while it assembles and returns a very large data set The doQuery method in this case will return a list reference very quickly Ranges of data can be queried from the list to improve response times from the server A good practice to follow is to use list references if the data set exceeds 250 items Sometimes it does not make sense to use list handles For example an issue has a list of Activity Logs Depending on the installation the number of logs can range from a few to several dozen It is pr
15. createFolder Description A list of attachments with reference to a given Knowledge document Returns A lt UDSObject gt node with zero or more lt UDSObject gt nodes describing the attachment with the following Attributes child nodes XML Element Value Type Description id Integer Identifies the unique ID of the attachment The following parameters apply to the AttmntLinkedKD method Parameter Type Description SID Integer Identifies the session retrieved from logging in attmntl d Integer Identifies the unique ID of the attachment Description Checks if an attachment is linked to any Knowledge document and returns the number of links found Returns Any number of links found The following parameters apply to createFolder method Parameter Type Description SID Integer Identifies the session retrieved from logging in parentFolderl d String Identifies the unique ID of the parent folder zero if no parent 178 Web Services User Guide Knowledge Tools getFolderList Parameter Type repl d Integer folderType Integer description String folderName String Description Creates a folder Returns Description Identifies the unique ID of the repository Identifies the type of folder to be created Identifies the description of the folder Identifies the name of the folder A lt UDSObject gt describing the folder created with some of the following child lt Attributes gt nodes X
16. 20 Q QREL keyword 57 querying for change orders assigned to a contact 51 for incidents 47 for issues assigned to a contact 51 for problems 47 for requests assigned to a contact 51 R rateDocument method 165 removeAttachment method 200 removeLrelRelationships method 140 removeMemberFromGroup method 83 Index 205 requests querying for those assigned to a contact 51 require secure connection security feature 14 require secure logon security feature 14 resolving a duplicate ticket 36 retrieving related list lengths 52 S search method 144 security features require secure connection 14 require secure logon 14 serverStatus method 193 Service Desk access using the Web Services 41 categories and properties 43 Design time feature 43 error codes 52 handling queries 51 locking errors 41 logs 17 objects 39 system updates and caching 42 timeouts 41 understanding objects 39 XML object returns 44 severity handles 49 SID 25 simplified web services access 37 SKELETON table 141 SOAP Fault 17 SREL 57 system updates caching 42 T table O INDEXES 141 SKELETON 141 types for Knowledge Tools 141 timeouts 41 tips for web service clients 12 transfer method 98 U UDS BAD PARAM 52 UDS BAD SESSION 52 UDS CNTXT TIMEOUT 52 UDS CREATION ER 52 206 Web Services User Guide UDS FAILURE 52 UDS FECTH ERR 52 UD
17. E Hide uice e etes re dau RdEs 57 Him M S 57 UNKNOWN EMITTE 58 OUI pre 58 LISS crnan AT A N a A T AaS 59 Where Glaluses 1 2 dite MM HU HER MINIMA A E A eeiiaaeecead 62 IN CRUSE Mm 64 Chapter 5 Web Servic es Methods 67 Contact Management Methods ear rtr x a a EA A E ETAETA 67 mL 67 IOQINS T Ie e EE 68 loginiserviceMariaged cd experte EE repete qr pex igne ru E Eae upra e cede rai 69 impersonate 2 5 ieee edente mes tree ti lee tere rele dis Rove ka ind sk exta re iaa eite Dd 70 VOC ON rae 71 getHarncdleForU serid 3 eri RUE EH Exp er ERR EI Clarice UE ME UE 72 getAccessTypeForCoritact isse oriri rr HR r n RERERRe EFE ORARE cs HRENSRRRRKNET REKERRERTKRCRPEE RERO EFRAE A 72 QUOC A E nM 73 e ug M mUUE 75 NMA CONCACCS e E E A E A 79 getPermissiorGFolps aips a a E A a aa 81 vi Web Services User Guide Group Management Methods I nsn nnne enn nnne nnn 82 addMemberTOoGroUp eoe heh tret punk pi Ed yee bik ees eis RENI ie erie UA QU 82 removeMember From Grou Dis cseceu et expen E ERR REX RERERNKRRRFENEIRRRRNRC GRU RxRERGCRG XY E rion RXRRERY peer RET 83 getGroupMemberListValues ssssssssssssesssssee ses eese eae 84 B siness Method UE 87 CREATE SSUC c ne n AAR D ETEN EOE AA OE EENE A AE E 87 createOuIclcnick BE a E A AO E ARRO 89 ClOSCTICK CE sma
18. Identifies the handle of the contact to remove GroupHandle String Identifies the group from which you will remove the contact Description Removes a contact from a group Nothing happens if the contact is not a member Returns Nothing Web Services Methods 83 Group Management Methods getGroupMembernlistValues The following parameters apply to the getGroupMemberListValues method Parameter SID whereClause numToFetch attributes 84 Web Services User Guide Type Integer String Integer String Description Identifies the session retrieved from logging in Identifies the SQL where clause Determines the maximum number of records to return This cannot be zero 0 Use 1 to return all Identifies the array of attribute names for which to retrieve values see the following description Group Management Methods Description Functions similarly to getListValues except that it queries the system s group and member relationships The system uses a special Group Member grpmem object for each group member relationship The Unicenter Service Desk system administers grpmem objects behind the scenes you do not manipulate them directly and they are essential for certain queries The grpmem object simply contains two pointers one to a Contact and the other to a Group which in itself is a Contact object The attribute names are member and group respectively Because t
19. Identifies the session retrieved from logging in Identifies the unique ID of the attachment folder A lt UDSObject gt describing the attachment folder with some of the following child lt Attributes gt nodes XML Element Value Type repository String parent id String 180 Web Services User Guide Description Identifies the repository name Identifies the unique ID of the parent attachment folder getAtimntiist XML Element Value folder_type folder_name description Type Integer String String Knowledge Tools Description Identifies the type of attachment folder Identifies the name of the attachment folder Identifies the description of the attachment folder The following parameters apply to the getAttmntList method Parameter SID folderl d repl d Description Type Integer String Integer Description Identifies the session retrieved from logging in Identifies the unique ID of the attachment folder Identifies the unique ID of the repository This parameter is required only when the folder ID is zero which indicates the root folder Returns a list of attachments under a given attachment folder Returns A lt UDSObjectList gt with zero or more lt UDSObject gt describing the attachment with some of the following child Attributes nodes XML Element Value repository parent id folder type Type String String Integer Descript
20. Services Methods 133 List Query Methods Description Returns a list of notifications Ir objects for a contact You can query on a specific status for the notifications with the queryStatus field which is useful for returning for example only non cleared messages The possible queryStatus values are as follows m 1 Fetch all notifications m O Fetch non cleared notifications those with a status value of less than 7 m 1 Fetch cleared notifications those with a status value of 7 8 or 9 Returns The following XML Element Type Description lt listHandle gt Integer Identifies the list handle lt listLength gt Integer Identifies the length of the list generated 134 Web Services User Guide LREL Methods LREL Methods LREL relationships are defined in majic maj and mod mod files on the server and are declared with the LREL keyword LRELs define many to many relationships The most commonly used LRELs are for example relationships between the following m Issues and Assets m Contacts and Assets m Task Types and Status codes Attachments also use LRELs although the Web Services does not define any Attachment related methods Group relationships do not use LRELs special methods are provided to group management Remember an LREL has two names one for each side of the many to many relationship For example the following is declared in Irels maj LREL Irell iss asset lt gt nr PDM is
21. The rest of the documents return their IDs only For example you can set up a paging mechanism where the user can click on Top Previous Next and Bottom links When you need to retrieve the next set of information you can use the getDocumentsBylDs method Returns A lt UDSObjectList gt node with the following section UDSObject nodes with requested Attributes nodes describing Knowledge Document You should pass the IDs into the getDocumentsBylDs doclds parameter in this same format The following parameters apply to the getDocument method Parameter Type Description SID Integer Identifies the session retrieved from logging in docld Integer Identifies the document ID to retrieve propertyList String Identifies the comma separated list of database fields from which you want to retrieve information Leave blank to retrieve all fields getRelatedDocuments Boolean Indicates whether to retrieve a list of documents that are related to this document getAttachments Boolean Indicates whether to retrieve the list of attachments and URL links for the document getHistory Boolean Indicates whether you want to retrieve the complete history for the document 152 Web Services User Guide createDocument Knowledge Tools Parameter Type Description getComments Boolean Indicates whether you want to retrieve all comments for the document getNotificationList Boolean Indicates whether you want to retrieve th
22. UUIDs are used mostly with primary keys 58 Web Services User Guide Lists Some Web Services methods return lists represented by a unique integer handle A list is simply a collection of same type objects Lists are especially useful when dealing with a large collection of objects for example all the contacts in the system because you can retrieve information about items in a range of the list The disadvantage is that you must make more method calls to obtain a list handle retrieve information and finally free the list handle If the expected number of list rows is small use methods that do not involve list handles such as doSelect The following describes more details about lists Lists are homogenous List may only contain objects of a single type for example lists of contacts list of organizations and so on Lists are Static For example if a list object is obtained for all contacts and another contact is added to the system the update is not reflected in the list Another list handle must be obtained to get the most current data List Handles A request for a list returns an integer handle representing the list of same type objects No other information is sent to the client The client may query the list for specific information about its rows When a client is finished with a list the handle must be released with freeListHandles The Unicenter Service Desk server maintains the list consuming system resources
23. a Knowledge Document table Supply one or more attributes you want fetched from the objects that match the supplied where clause Returns A sequence of lt UDSObject gt elements The following format applies lt UDSObj ectList gt lt UDSObj ect gt Handl e Attributes Attri buteName0 Attri buteNamel XML Element Type lt UDSObject gt Sequence lt UDSObjectList gt Description Contains a lt Handle gt element and an lt Attributes gt sequence For information about the contents of each lt UDSObject gt element see XML Object Returns Signifies the outer element which contains a sequence of lt UDSObject gt elements Web Services Methods 149 Knowledge Tools getDec isionTrees The following parameters apply to the getDecisionTrees method Parameter SID propertyList sortBy descending Description Retrieves all Decision Trees Returns Description Identifies the session retrieved from logging in Identifies the comma separated list of database fields for which you want to retrieve information The following fields are always returned regardless of the propertyList parameter id DOC TYPE ID m BU RESULT Identifies the database field that you want to use for sorting the results The default is id Multiple sort fields are not supported If you specify another field id as a secondary sort always sorts the results Identifies an indicator availab
24. a tool to generate proxy classes from a WSDL service description A method may take a long time to process if the Unicenter Service Desk server is heavily loaded 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 Unicenter Service Desk server time out not a Web server time out network time out and so on If a method times out it returns the following error code UDS TI MEOUT ERR The operation is not aborted The server may have received the request and will process it successfully although slowly Note The Web Services will delay a few seconds the first time it is accessed after the J 2EE 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 Unicenter Service Desk Web Services 41 System Updates and Caching System Updates and Caching The Unicenter Service Desk Web Services caches information for object types Type information is not cached until the type is referenced for the first time and will cause a small delay To avoid any server or caching delays you may want to run a primer client to activate the Web Services and cache the most popular object type informatio
25. analyst a calling application must first construct a Web interface URL which includes a bopsid token a web interface security token Failure to provide a bopsid token may result in an interactive login challenge when attempting to launch the web interface in the chosen context such as a detail view of a given ticket The getBopsid method allows the bopsid to be generated in the context of the user provided by the Name parameter If Name is not provided it uses the user associated with the current web interface SID Note To prevent unauthorized elevation of privileges the SID of the current login must have equal or greater access rights than the name of the user entered Returns A bopsid based on the name of the user entered The returned bopsid expires based on web interface configuration settings and should not be held by the caller indefinitely but used in a launch of the web interface in a timely manner Note The SID of the current login must have equal or greater access rights than the name of the user entered If no user name is entered then the bopsid created is based only on the SID 188 Web Services User Guide Miscellaneous Methods getC onfiguratonMode getObjectValues The following parameters apply to the getConfigurationMode method Parameter Type Description SID Identifies the SID of the current login session Integer Description This method returns a string indicating if the Service Desk insta
26. 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 getPropertyl nfoForCategory 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 getPropertyl nfoForCategory 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 Web Services Methods 93 Business Methods 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 Note By default this method creates a Request If you are using the ITIL methodology you need to set
27. detail later in this chapter are summarized as follows Option Name Description design mode stubs Sets the Web Service to design mode Service Desk only require secure logon Requires the login and loginService web methods to be called with a secure protocol such as https 12 Web Services User Guide Configuration Option Name Description 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 Note The configuration settings can be set in the deploy wsdd file For r11 this file is located in this subdirectory lt NX_ROOT gt sdk websvc R11 For post GA 6 0 it is located in this subdirectory lt NX_ROOT gt sdk websvc 60 We recommend that you create a back up copy of either file before making any changes to it New configuration settings take effect when Unicenter Service Desk Web Services is redeployed The following steps taken directly from the Apache Axis documentation redeploys the Unicenter Service Desk 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 use the following set AXI SHOMEZ NX ROOT j ava lib set classpath AX SHOME axi s j ar AXI SHOME j axrpc jar AXI SHOME saaj j ar A
28. doSelectKD method Parameter Type Description SID Integer Identifies the session retrieved from logging in whereClause String Optional Identifies the where clause for the query Web Services Methods 147 Knowledge Tools Parameter Type sortBy String descending Boolean maxRows Integer attributes String skip Integer 148 Web Services User Guide Description Identifies the database field that you want to use for sorting the results Multiple sort fields are not supported The default is BU RESULT meaning that the faq rating sorts it When id is used as the secondary sort it always sorts the results Identifies the indicator available for sorting the results in descending order Use True for descending and False for ascending the document order Indicates the maximum number of rows to return Specify 1 to return all rows Note Regardless of the integer specified Unicenter Service Desk will return a maximum of 250 rows per call Identifies the attribute list from which to fetch values Dotted attributes are permitted If this field is blank all value based attributes are returned These attributes cannot be defined as LOCAL in the majic definition file LOCAL attributes are temporal they have no database storage Identifies the number of knowledge documents to skip from the beginning Enter zero 0 to return all documents Description Knowledge Tools Performs an SQL like select on
29. existing ticket is within a specified threshold for example it was opened less than 2 days ago Note The create date field is configured using the Maximum time interval for searching duplicates The duplicate ID matches the one provided by users when invoking the createTicket method Users can also assist in preventing duplicates by classifying tickets as being unique or different based on criteria known to the user To do this add an optional string parameter to the createTicket Web Services call If duplicate handling is on the string parameter is inspected after other duplicate handling criteria match to determine whether this is a unique or duplicate call to this method Extemal Specifications 35 Access Control and Management Resolve a Duplicate Tic ket If the create ticket action results in a duplicate the existing Problem Type may be configured to do one of the following Reconfigured Problem Type Results Create the New Ticket and Ignore A new ticket handle and number will Duplicates be returned default Do Not Create a New Ticket Add an The ticket handle and number of the Activity Log to the Existing Duplicate existing ticket will be returned Instead Do Not Create a New ticket Add an A ticket handle and number of the Entry to the Service Desk Standard Log existing ticket will be returned Instead Create a New Ticket and Attach it asa A new ticket handle and number will Child to the Duplicate be returned
30. has a related list named children that is a list of its child requests This method is a list handle free alternative to getRelatedList The return format is similar to getListValues as indicated by the following numRowsFound lt UDSObj ectList gt lt UDSObj ect gt Handl e lt Attri but eName0 gt lt Attri but eNamel gt To retrieve information for an object s list attributes object schema majic see Understanding Service Desk Objects and the appendix Data Element Dictionary in the Unicenter Service Desk Modification Guide An alternative method is to use getObjectTypel nformation Returns The following XML Element Type Description lt numRowsFound gt Integer Indicates the total number of rows in the queried list Note This is not necessarily how many rows were returned lt UDSObjectList gt N A Identifies the outer element which contains a sequence of lt UDSObject gt elements lt UDSObject gt N a Contains a lt Handle gt element and zero or more lt AttributeNameX gt elements For more information about the contents of each lt UDSObject gt element see XML Object Returns Web Services Methods 131 List Query Methods getPendingC hangeTaskListForC ontact The following parameters apply to the getPendingChangeTaskListForContact method Parameter Type SID Integer contactHandle String Description Description Identifies the session retrieved from logging in
31. is a regular document HITS Integer Indicates the number of times that the document has been viewed DOC TEMPLATE ID Integer Identifies the ID for the template you want to assign to this document WF TEMPLATE Integer Identifies the ID for the workflow template you want to assign to this document CUSTOM1 String Indicates a custom field CUSTOM2 String Indicates a custom field CUSTOM3 String Indicates a custom field CUSTOM4 String Indicates a custom field CUSTOM5 String Indicates a custom field CUSTOMNUM1 Double Indicates a numeric custom field CUSTOMNUM2 Double Indicates a numeric custom field 160 Web Services User Guide deleteDoc ument getCategory Knowledge Tools Description Modifies a document Returns A lt UDSObject gt node describing the Knowledge Document modified The following parameters apply to the deleteDocument method Parameter Type Description SID Integer Identifies the session retrieved from logging in docl d Integer Identifies the unique ID of the document you want to delete Description Flags a document for deletion The Knowledge Tools Windows Service permanently deletes the document Returns Returns error codes only when there are individual errors For additional information see Error Codes The following parameters apply to the getCategory method Parameter Type Description SID Integer Identifies the session retrieved from logging in categoryld Integer Identif
32. lt AttributeNameX gt elements Note For information about the contents of each lt UDSObject gt element see XML Object Returns The following parameters apply to the createLrelRelationships method Parameter Type SID Integer contextObject String 138 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the object on one side of the LREL LREL Methods Parameter Type Description LrelName String Identifies the Lrel Name as seen by contextObject addObectHandles String Identifies the handles of objects for the other side of the LREL relationships Description Adds one or more many to many relationships contextObject is one side of the LREL relation The caller passes one or more object handles for the other side If a relationship already exists between the two objects no change is made and the system continues to process the addObjectHandles array If an invalid object handle is passed the entire operation is canceled The following example shows how to add several assets to a contact s environment createlrel Relationships sid ContactHandle cenv nr 655A043EDDB36D4F97524F2496B35E75 nr 755A043EDDB36D4F97524F2496B35E75 ContactHandle is a string handle to a contact and nr 655A043EDDB36D4F97524F2496B35E75 and nr 755A043EDDB36D4F97524F2496B35E75 are Asset handles Returns Nothing Web ServicesMethods 139 Knowledge Tools rem
33. methods are used only with Unicenter Service Desk s built in workflow engine These methods are not applicable when a ticket is using the integrated CA Workflow product CA Workflow does have a separate web service interface For details see the product documentation getWorkflowlemplates The following parameters apply to the getWorkflowTemplates method Parameter Type Description SID Integer Identifies the SID of the current login session objectHandle String Identifies the object handle persistent id of a change order or issue Web ServicesMethods 195 WorkFlow Methods Description Takes a parameter of the handle of a change order or issue and returns a list of workflow templates that are associated with the category of the change order or issue It first verifies that the change order or issue has a category Then it retrieves a list of associated workflow templates of the category If the change order or issue does not have a category the following error appears Error UDS BAD PARAM Empty null list is returned if there are no associated workflow templates found for the category Returns The following XML Element Type lt listHandle gt String Description Identifies the list handle listLength Integer Identifies the length of the list generated 196 Web Services User Guide WorkFlow Methods createWorkHowTask The following parameters apply to the createWorkFlowTask method Parameter Ty
34. operation violates Service Desk security and was aborted The attempted request is refused because it exceeds the limit defined in the policy Chapter 4 Common Elements This chapter describes Unicenter Service Desk Web Services elements that are shared by Service Desk and Knowledge Tools Attribute Data Types Integer Each attribute of an object is of a specific type that has meaning to the Unicenter Service Desk application such as string date or integer Knowing the attribute type is essential to correctly retrieving and updating attribute values The Service Desk uses an enumeration to identify each data type These enumeration values are returned in various web methods as illustrated by the following table Data Type Value Integer 2001 String 2002 Duration 2003 Date 2004 SREL 2005 UNKNOWN 2006 List QREL BREL 2007 Lrel many to many 2008 UUID 2009 The Integer data type represents a 32 bit signed integer Null an integer attribute by passing the empty string Common Elements 55 Attribute Data Types String The String data type represents a character string where the the maximum length is defined by the database storage allocated for a particular string attribute For more information about character strings see Parsing Tools in the Unicenter Service Desk Modification Guide If you attempt to set a string attribute to a value that exceeds its length the value is truncated and an error message
35. or in a Where clause You cannot use dot notation to set values To set an SREL attribute such as with updateObject always pass the handle of the object to which you want to point To set an SREL attribute to null pass the empty string An object can have a list attribute that represents a one to many relationship These are defined in majic files with the QREL or BREL keywords A list exists at the object level it does not take any additional storage in the DBMS The Service Desk system handles list collections as abstract data types The Web Services provides several methods to interact with lists for references and queries to lists defined in an object use getRelatedList and getRelatedListValues For more information about lists see Service Desk Lists in this chapter The LREL data type represents a many to many relationship between two object types An LREL has two names one for each side of the relationship The Unicenter Service Desk Web Services provides special functions for interacting with LRELs For more information about LRELs see LREL Methods Common Elements 57 Attribute Data Types UNKNOWN The Unknown data type represents an unknown data type UUID A UUID is a 128 bit integer 16 bytes or a 32 byte character that can be used across all computers and networks wherever a unique identifier is required Such an identifier has a very low probability of being duplicated for example a contact ID
36. policy code defined in a policy How a login is validated depends on the contact s assigned Access Type The Access Type object is hosted by Unicenter Service Desk and sets the validation type To view the Access Type record in the Unicenter Service Desk Web Interface access the Web Authentication tab You can also use the getAccessTypeForContact web method to retrieve any Access Type object information For more information about Access Types see the Unicenter Administrator Guide Public Key Infrastructure PKI Authentic ation If you plan to use the PKI authentication realize that the content of the login request is encrypted with a private key that can only be decrypted by its matching public key The response of the login request is returned as plain text Generally each application accessing Unicenter Service Desk Web Services is assigned with a policy Unicenter Service Desk Web Services stores detailed information about a policy along with the public key of a digital certificate An application as the policy holder uses the private key of the digital certificate and the policy code as policy identifier to assemble a login request 20 Web Services User Guide Public Key Infra structure PKI Authentication loginServic eManaged Policy Encrypted Policy Unicenter Service Desk Web Services performs the user authentication by locating the policy through the plain text policy code retrieving the policy holder s public key
37. submitted the comment Identifies the user name of the person who submitted the comment Identifies the email address of the person who submitted the comment Identifies the text for the comment recently added Identifies the date and time the comment was added The following parameters apply to the addComment method Parameter SID comment Type Integer String Description Identifies the session retrieved from logging in Identifies the comment to add Web ServicesMethods 163 Knowledge Tools Parameter Type docld Integer email String username String contact d String Description Adds a comment to a particular docu Returns Description Identifies the document ID for the comment you want to add Indicates the email address of the person who submitted the comment Leave blank if you want the email address retrieved from the database based on the user ID parameter Indicates the user name of the person who submitted the comment Leave blank if you want the user name retrieved from the database based on the user id parameter Indicates the ID of the person submitting the comment If this contact ID exists in the database the associated email and user name are retrieved and placed in the email and user name fields If this ID does not exist the email and user name parameters are used instead if supplied Use zero 0 if you are not using this parameter Contact ID is UUID in
38. 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 a True Internal only activity a False Non internal activity that can be viewed by everyone 104 Web Services User Guide Business Methods 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 Service Desk interface LogType is the code attribute for the activity type of the new log The most common codes are as follows m CB Callback m RS Research m LOG Log Comment For more information about all possible values see the Act Type aty table in the appendix Data Element Dictionary of the Unicenter Service Desk Modification Guide The Service Desk 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 lt LogHandle gt String Identifies the handle for the new activity log attachChangeToRequest The following parameters apply to the attachChangeToRequest method Parameter Type Description SID Integer Id
39. to the modifyDocument method Parameter SID docld attributeValues Type Integer Integer String Description Identifies the session retrieved from logging in Identifies the unique ID of the document you want to modify Specifies the name value pairs for the update for example SUMMARY Summary text TITLE and Title text Web ServicesMethods 157 Knowledge Tools As part of the modifyDocument method the following table reflects examples of valid commonly used attribute values for a document Data in the Type column reflect the actual type which must be parsed to the method in string format in the attrVals string array Parameter MODIFY DATE USER DEF ID TITLE SUMMARY PROBLEM RESOLUTION STATUS ID PRIORTY ID START DATE EXPIRATION DATE 158 Web Services User Guide Type String String String String String String Integer Integer Date String Date String Description Indicates a special field used for record locking purposes to make sure someone else is not updating the document at the same time that you are You must pass in the existing MODIFY DATE of the document If you leave this blank you receive an error that another user has updated the document Specifies any ID that you want to use to represent the document Indicates the title of the document Indicates the summary of the document Indicates the problem of the do
40. uses a standard XML structure beginning with the following root element lt UDSObj ect gt The format of the XML representation is described in the following table XML Element Type Description lt UDSObject gt N A Identifies the root node lt Handle gt String Identifies the object s handle lt Attributes gt Sequence Identifies the attribute values This holds zero or more elements for the object s attribute values lt attrNameO DataType String Identifies the AttrNameO typeEnum which is an object attribute name as defined in the Service Desk 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 Service Desk environment The value is one of the data type enumerations described in the Data Types section in this document 44 Web Services User Guide XML Object Retums For example a call to getObjectValues can return information illustrated by the following lt UDSObj ect gt Handl e gt cnt 555A043EDDB36D4F97524F2496B35E75 lt Handl e Attri butes Attribute DataType 2003 gt AttrName first name Attr Name AttrVal ue first name AttrVal ue Di spl ayVal ue gt Yaakov lt Di spl ayVal ue Attribute Attribute D
41. values Dotted attributes are permitted If this field is blank all value based attributes are returned These attributes cannot be defined as LOCAL in the majic definition file LOCAL attributes are temporal they have no database storage Web ServicesMethods 123 List Query Methods Description Performs an SQL like select on a specified object table Supply one or more attributes you want fetched from the objects that match the supplied where clause Returns A sequence of lt UDSObject gt elements The following format applies UDSObj lt U lt A A A A A XML Element UDS UDS 124 Web Services User Guide ectlist DSObj ect Handle Attributes tri buteNameA tri buteVal ueA0 tri buteVal ueAl gt tri buteNameB tri buteVal ueB0 Type Object N A ObjectList gt Sequence Description Specifies the standard UDSObject element containing the handle and requested attribute values Contains a lt Handle gt element and an lt Attributes gt sequence For information about the contents of each lt UDSObject gt element see XML Object Returns doQuery Lis Query Methods For example if the method used is the following String myArray last name first name doSelect mySID cnt last name LIKE JV 2 myArray The return could be the following lt UDSObj ectList gt lt UDSObj ect gt Handl e cnt 555A043EDDB36D4F97524F2
42. with some of the following child getRepositoryInfo Parameter Type SID Integer repositoryl d Integer Description Returns the attributes of a repository Returns lt Attributes gt nodes XML Element Value Type repository String parent id String folder type Integer folder name String description String Miscellaneous Methods Description Identifies the repository name Identifies the unique ID of the parent attachment folder Identifies the type of attachment folder Identifies the name of the attachment folder Identifies the description of the attachment folder This section describes the Web Services Miscellaneous methods Web ServicesMethods 183 Miscellaneous Methods callServerMethod The following parameters apply to the callServerMethod method Parameter SID methodName factoryName formatList ParameterO parameterX 184 Web Services User Guide Type Integer String String String String Description Identifies the session retrieved from logging in Identifies the name of the method to call Identifies the factory name of the object type containing the method 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 Indicates zero or more parameter values for the method Miscellaneous Methods Description Use this method to invo
43. 496B35E75 Handl e Attri butes AttributeName last name Attri but eName gt Attri buteVal ue J ohnson AttributeVal ue lt AttributeName gt first_name lt Attri buteName r t Attri buteVal ue Carol Attri buteVal ue Attributes UDSObj ect gt UDSObj ect Handl e gt cnt 555A043EDDB36D4F97524F 2496B35E76 lt Handl e Attributes Attri buteName last name AttributeName Attri buteVal ue J ones Attri buteVal ue Attri buteName first name Attri buteName Attri buteVal ue Ron Attri buteVal ue Attributes lt UDSObj ect gt lt UDSObj ect Li st gt The following parameters apply to the doQuery method Parameter Type Description SID Integer Identifies the session retrieved from logging in ObjectType String Identifies the object type factory to query WhereClause String Optional Identifies the where clause for the query Web Services Methods 125 List Query Methods getlistValues Description Performs an SQL like select for the specified object type It also returns a list handle that points to a list of the rows returned from the query where each row represents a Unicenter Service Desk object that matched the supplied where clause The caller can fetch values for the list rows using getListValues Note For more information about where clauses see Where Clauses The object list is stored on the
44. D Integer Identifies the session retrieved from logging in Description Returns information about the access policy that is controlling and managing the current Service Desk Web Services session Returns The following XML string XML Element Type Description lt SAPolicy gt N A Identifies the detailed information of this access policy and its related problem types The content of lt SAPolicy gt is shown as follows lt SAPolicy gt lt Name gt name of policy lt Name gt lt Code gt policy code lt Code gt lt ContactName gt policy proxy contact s combo name lt Contact Name lt ContactHandle gt handle of policy s contact lt ContactHandl e gt lt Access gt lt TicketCreation gt limitation lt TicketCreation gt lt Obj ectCreation gt limitation ObjectCreation lt Obj ectUpdate gt limitation lt Obj ect Update gt lt Attachments gt limitation lt Attachments gt Queries limitation lt Queries gt Knowledge limitation Knowl edge Access ProblemTypes zero or more ProblemType elements Probl emType Code code of a problem type Code lt Status gt active or inactive lt Status gt Probl emType Probl emlypes gt lt SAPolicy gt 112 Web Services User Guide Business Methods getTaskListValues The following parameters apply to the getTaskListValues method Parameter Type Description SID Integer Identifies the session retrieved from loggi
45. D may expire if it is not used before a timeout elapses User authentication is performed on the username and password while access control is applied based on the policy specified The authentication is performed as described in login Empty policy will allow default policy to be applied automatically The login user not the proxy contact specified in the policy is responsible for subsequent web service activities All function group security and data partitions are enforced for the login user Returns The following is returned Parameter Type Description SID Integer Specifies the unique SID to use for all other Web Services calls loginServic eManaged The following parameters apply to the loginServiceManaged method Parameter Type Description policy String Required Identifies the policy which must be must be in plain text encrypted policy String Required Identifies the digital signature of the policy code encrypted with the policyholder s private key It is in BASE64 text format Web Services Methods 69 Contact Management Methods impersonate Description Performs the user authentication by locating the policy through the plain text policy code finding the policyholder s public key associated with the policy decrypting the encrypted policy code matching decrypted content with the policy code and finally opening a session with a back end server The returned session ID SID can be used for subse
46. Internal Identifies the field as read only which indicates whether this problem type is an internal out of the box default problem type Symbol Indicates the symbolic name of the problem type Code Identifies the unique text identifier of the problem type Description Describes the detailed description of the problem type 34 Web ServicesUser Guide Access Control and Management Problem Type Description Duplicate Handling Defines the action to take when the system detects that an identical ticket already exists For more information about Handling duplicate tickets see Handling Duplicate Tickets Return Data Identifies the user defined return Duplicate Tic ket Handling message you can specify for the web method createTicket to return to client applications Return data might be used for indicating an action the application should take Application Data Return or a message User Data Return to display to the end user The Web Service Access Policy can detect and handle duplicate tickets which is helpful for preventing ticket flooding A ticket created with the potential of being a duplicate applies if all of the following conditions are true At least one ticket of the same type cr iss or chg already exists and is ACTIVE The existing ticket was created by the web service The existing ticket was created with the same Policy and Problem Type as the ticket being created The create date of the
47. ML Element Value Type repository String parent id String folder type Integer folder name String description String Description Identifies the repository name Identifies the unique ID of the parent folder Identifies the type of folder created Identifies the name of the folder Identifies the description of the folder The following parameters apply to getFolderList method Parameter Type SID Integer parentFolderl d String repl d Integer Description Identifies the session retrieved from logging in Identifies the unique ID of the parent folder 0 if no parent Identifies the unique ID of the repository Web ServicesMethods 179 Knowledge Tools Description Returns a list of folders under a given parent folder Returns A lt UDSObjectList gt with zero or more lt UDSObject gt describing the attachment folder with some of the following child Attributes nodes XML Element Value Type repository String parent id String folder type Integer folder name String description String getFolderinfo Description Identifies the repository name Identifies the unique ID of the parent folder Identifies the type of folder created Identifies the name of the folder Identifies the description of the folder The following parameters apply to the getFolderl nfo method Parameter Type SID Integer folderl d Integer Description Returns the attributes of a folder Returns Description
48. P ER PP Leg tatiana e a Eee ra ds 43 Contents v Desigi time FeaLtute z e ii pertum ue trina tiui md eitubupde tbe da dur aded t Exda Netus i eRE 43 XMIObj6cE Ret tris oi ruo mx et acide e eer e erar exRE E ur ness ute int as Mania URRA M ERQUM 44 Note on Using the ITIL Methodology Installation sssssesseeem Hmm 46 Create an Inciderit or Problem RC RRERRRRRR ERR IDEM RIPDERNR d IR SAP aaa 46 Query for Incidents or PrODIEMS ccc cece EE EEE cit EN EE EEE EEE E EEE SEES nen nnn 47 Attach an Incident to a Problem ccccceee cere eee ne ee esee esee esee essen nennen 47 Attach a Problem to a Change Order sssssrsssersssrrsrrtrsrrtntrrtrtrntt trst nena eee messen nennen 47 Configuration tems cte erint ento xi beret MEA x MDXWAF NUR X eP MNULIMPEU TER A A CENE pM REPRE UNE 48 Use the Web Services rtm HR OR E RR LER E UAI DERE IRR agence FL A 48 LOGINS NEED LLL 48 Perform Common Tasks csse cure gin nrbe RR RRERRAFEA dade REFER REEF RRa ur E ahia Sie casas 49 igo 52 Chapter 4 Common Elements 55 Attribute Data Types i iio er eret ee ec on Ra bcr eb Fea Sans Ve e ea eile T Qu esa ee doe degree 55 Ini EDU 55 cu p E 56 Bn H H P T 56 Date he x Rn IRAK EE SANI OUTRE Denne Kee med Pade REGS Sanaa KE RU RERENUU UCERERE REL E TA RR ERU RE XR ak 56 clim LLM 57 List QREL BRE izninin a tas aden casein Matera etre pnt
49. R E RAE E RR RE REP ER RP DIAS AA A RR RR R dA 189 a suslerlecr D EET 189 getobjectTypelinformatiorn 5 tert Ree e A euet er rebua Far d EAR RR 190 SerVerStatul eerdiaswer cien Pre iu ee Ca e eene Eua RE e bu Ra RUD PE Cx PERO ERI na code RI one a 193 MPC ALCOD GCE E n 193 WorkFlow Methods doce te Leia eed dite We la a dead bere Demy rell re Lec bed DERE edite EA Aa ae 195 getWorkflowTermplates ccrr n rete ERR RE ER RERRYRNRRR AREE YUR RR EX RI RRAV REI RDVEFRIR XR RIA irR E Ra ARE ERR 195 createWorkFloWTask RR ERU E lindadd caved nidadsdigaaiedek EAA 197 deleteWorkEloWTasKk rre vetus EEN UR ra eric ERI enviaerisietpe PRG NM ME EE IUE 199 Attachment Methods eren epe rene tux iiie AAE ieee datas PEE E AAEN eet cd ats et 199 createAttachiment scie esse eee m Avete PUER ER Aa aeu Lek Due tr pa Cr Vi rb na DR red pdt 199 removeAttachmentb edebant pedir E n EN E E EFI RRbR E MAiadaaasieandGe ENRE E 200 Index 203 viii Web Services User Guide Chapter 1 Web Services Basics This document describes the web services interface for the Unicenter Service Desk and Knowledge Tools products The Unicenter Service Desk Web Services are built upon the standards set by the World Wide Web Consortium you can find this product on their web site including SOAP and WSDL These XML based standards combined with the well known HTTP protocol make Unicenter Service Desk functionality accessible to remote
50. REL 57 Knowledge Tools database structure 140 general methods 142 system logs 17 table types 141 using the web services 174 L list QREL BREL 57 list query methods 122 lists 59 locking errors 41 logComment method 108 Login Username Password 20 login method 67 loginService Username Password Policy 20 loginService method 68 loginServiceManaged policy encrypted policy 21 loginServiceManaged method 69 logout method 71 logs Application Event 17 Service Desk 17 LREL 57 definition of 57 keyword 135 methods 135 M majic files 39 135 methods asset management 116 attachement related 135 attachment 199 business 87 by category for web services 29 contact management 67 68 69 70 71 general for Knowledge Tools 142 group management 82 list query 122 LREL 135 miscellaneous 183 workFlow methods 195 mod files 39 135 modifyDocument method 157 N notifyContacts method 109 O O INDEXES table 141 object attributes 39 factories about information caching 42 handles 39 objects 39 obtaining the WSDL document 11 out of the box handles 46 P priority handles 49 problem type defining 32 problem types for Web Services 33 problems how to attach to a change order 47 how to create 46 querying for 47 property objects 43 protocols 9 public key infrastructure PKI authentication e
51. S INTERNAL ERR 52 UDS LOCK ERR 52 UDS LOCK ERR code 41 UDS NOT FOUND 52 UDS OK 52 UDS OVER POLICY LIMIT 52 UDS SECURE CHANNEL REQUIRED 52 UDS SECURITY VIOLATION 52 UDS SERVER GONE 52 UDS SESSION TIMEOUT 52 UDS TIMEOUT ERR code 41 UDS UPDATE ERR 52 UNKNOWN 58 updateObject method 193 updateRating method 167 user access authentication 19 user name password authentication 19 using the Knowledge Tools Web Services 174 the Web Services 48 UUID 58 V Visual Studio NET tip 12 WwW Web Services access 10 12 advantages with Unicenter Service Desk 9 configuration 12 definition of 9 implementations offered 10 installation 18 methods by categories 29 performing common tasks in Unicenter Service Desk 49 problem types 33 simplified access 37 tips for clients 12 workFlow methods 195 WSDL document obtaining 11 X XML object returns 44
52. SD_ WebServiceSoap WSDL Note Any client code written to the r6 0 Web Services will continue to function as long as it references the post GA r6 0 WSDL The r11 interface is not compatible with the GA r6 0 interface Many servlet containers use a port other than 80 For example Tomcat defaults to port 8080 which is established during installation Web Services Basics 11 Configuration Tips for Web Services Clients To assist developers in getting started with web services client application development there is a sample Java client application for the Web Services included in the samples directory of the Unicenter Service Desk installation Many of the Web Services methods require arrays as input parameters for example the method createlssue permits an empty array for the propertyValues Sometimes these arrays are optional but the service requires an empty array to be passed As a tip for using 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 Similarly for Java String emptyArray new String 0 Note emptyArray can then be passed to array parameters that accept empty arrays Configuration The Unicenter Service Desk Web Services may be configured with entries in special web configuration files The names and descriptions of the configuration options described in
53. ToRequest SI D creatorHandle cr 12347 new String 0 activity description Unicenter Service Desk Web Services 47 Use the Web Services Configuration Items The ITIL methodology uses the term Configuration Item to refer to software hardware and other IT resources The out of the box Unicenter Service Desk Web Services uses the term Asset These terms both refer to the nr object stored in the ca owned resource database table All methods described in this guide that use asset objects specifically those described in the Web Services Asset Management Methods and Web Services Business Methods sections work in the same manner for Configuration Items It is merely a difference in terminology Use the Web Services The information in this section provides you with the fundamentals for using the Unicenter Service Desk Web Services Example code using the Web Services exists in the following Service Desk installation directory NX ROOT sampl es sdk websvc j ava The sample code is written in Java using Apache Axis for SOAP messaging Logins Before any Web Services method can be used a SID session ID must be obtained from one of these methods login loginService and loginServiceManaged The first two methods require a username and password that are validated exactly the same as the Unicenter Service Desk Web client the contact s Access Type specifies the validation method The third method requires a pub
54. Top Previous Next and Bottom links When you need to retrieve the next set of information you can use the getDocumentsBylDs method The maximum number of 100 IDs is returned Returns A lt UDSObjectList gt node with the following sections lt UDSObject gt node from the lt UDSObject gt Node Description section of this chapter There is a lt UDSObject gt node with all the given properties for the first n documents that the method finds where n equals the resultSize parameter For example if the resultSize parameter is 10 the maxDoclDs parameter is 50 and the method finds 100 documents then there are 10 lt UDSObject gt with lt Attributes gt nodes in the first lt UDSObject gt section with detail attribute information from propertyList parameter and 40 lt UDSObject gt nodes with only ID Attributes in the following section If you want to retrieve detailed ID lt AttrName gt information for documents numbering 11 20 you have to make a call to the getDocumentsByl Ds method and pass it those IDs from lt AttrValue gt The following parameters apply to the search method Parameter Type Description SID Integer Identifies the session retrieved from logging in problem String Identifies the problem description to which you want to find solutions 144 Web Services User Guide Parameter resultSize propertyList sortBy descending getRelatedCategories searchType matchType Type Integer
55. Unicenter Service Desk Web Services User Guide r112 This documentation the Documentation and related computer software program the Software hereinafter collectively referred to as the Product is for the end user s informational purposes only and is subject to change or withdrawal by CA at any time This Product may not be copied transferred reproduced disclosed modified or duplicated in whole or in part without the prior written consent of CA This Product is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties Notwithstanding the foregoing licensed users may print a reasonable number of copies of the Documentation for their own internal use and may make one copy of the Software as reasonably required for back up and disaster recovery purposes provided that all CA copyright notices and legends are affixed to each reproduced copy Only authorized employees consultants or agents of the user who are bound by the provisions of the license for the Software are permitted to have access to such copies The right to print copies of the Documentation and to make a copy of the Software is limited to the period during which the license for the Product remains in full force and effect Should the license terminate for any reason it shall be the user s responsibility to certify in writing to CA that all copies and partial copies of the Product have been returne
56. Unicenter Service Desk server and consumes system resources The caller is responsible for freeing the list with freeListHandles Lists created with this function are homogenous meaning the objects are all the same type and they are static meaning the list never changes even if a data change to an object excludes it from the initial where clause Returns A list handle that must be freed with freeListHandle XML Element Type Description lt listHandle gt Integer Identifies the list handle lt listLength gt Integer Identifies the length of the list generated The following parameters apply to the getListValues method Parameter Type Description SID Integer Identifies the session retrieved from logging in ListHandle Integer Identifies the list handle obtained with a previous call Startl ndex Integer Identifies the position in the list from which to begin fetching 126 Web Services User Guide Parameter Type Endl ndex Integer AttributeNames String Description List Query Methods Description Identifies the last list position from which to fetch Specify 1 to fetch all rows from Startl ndex Note Regardless of the integer specified Web Services will return a maximum of 250 rows per call Identifies an array of one or more attribute names for which you want to fetch values Returns attribute values for a range of objects in a list For example lt UDSObjectList gt lt UDSObj ect gt
57. XCEPTION FATAL EXP FT fatal exception is encountered No EXCEPTION RUNTIME EXP RT runtime exception is encountered Yes LOGIN ERROR LOGIN ER Failed to login No The following describes each of the internal problem types ACCESS ERROR Indicates that the system failed to connect to or find a resource such as a file website and so on EXCEPTI ON FATAL Indicates that the application is shutting down unexpectedly EXCEPTI ON RUNTI ME Indicates that the application code encountered an exception LOGIN ERROR Indicates that the operator failed to gain access to the application Extemal Specifications 33 Access Control and Management Additional Problem Types The administrator to an access policy can add additional problem types that are described in the following table Problem Type Description Ticket Template Identifies a template of a request Incident or Problem for ITIL issue or change order that you use to create a ticket when this problem type is reported Note The owning policy s contact is used as the end user The Ticket Type and Ticket Template Name define the ticket template Default Indicates if this problem type is the default for the policy Only one default is allowed per policy Note that a new default problem type overwrites the existing default problem type associated with the policy Active Represents an active problem type Note An inactive type does not create tickets
58. XI SHOME comm ons loggi ng j ar WAXI SHOME9 commons discovery j ar AXI SHOME wsdl 4j j ar AXI SHOME 10g4j 1 2 8 j ar amp cl asspat h 96 2 Change the directory to NX ROOT 2 sdk websvc R11 or NX ROOT 2 sdk websvc 60 for GA r6 0 Web Services and run 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 Service Desk service You may avoid shutting down the entire Service Desk system by recycling Tomcat by simply using the following commands pdm tomcat nxd c stop pdm tomcat nxd c start The Unicenter Service Desk Web Service is now redeployed You can verify that the service actually deployed by viewing the Axis services listing page at the following default URL http servername lt port gt axis services Note The exact URL depends upon your installation settings Web Services Basics 13 Security Security There are important security considerations in deploying web services The default configuration when using HTTP is insecure as it is for all information in web service calls sent between the client and the server in plain text over the network using the HTTP protocol This includes not only application data such as ticket descriptions and contact names but also web service session identifiers SID and depending upon the web service application login methods used it may include pass
59. a list of its child requests The Request s Activity Log act_log or act_log_all is another example To retrieve information about an object s list attributes refer to the object schema majic documentation or use getObjectTypel nformation Returns The following XML Element Type lt listHandle gt Integer Description Identifies the list handle lt listLength gt Integer Identifies the length of the list generated Web Services Methods 129 List Query Methods getRelatedListValues The following parameters apply to the getRelatedListValues method Parameter SID objectHandle listName numToFetch attributes 130 Web Services User Guide Type Integer String String Integer String Description Identifies the session retrieved from logging in Identifies the object handle Identifies a list type attribute name for the object Signifies the maximum number of rows to return a Cannot be zero Specify 1 to return all rows Note Regardless of the integer specified Web Services will return a maximum of 250 rows per call Identifies an array of one or more attribute names for which to fetch values Dotted names are permitted Lis Query Methods Description Returns values for lists related to a specific object The lists must be defined as a QREL or BREL Use the LREL methods to query LREL types For example the request object
60. a user defined set of documents which is controlled through the resultSize parameter The rest of the documents return their ids only Using this method you can for example set up a paging mechanism where the user can click on Top Previous Next and Bottom links When you need to retrieve the next set of information you can use the getDocumentsBylDs method Returns A lt UDSObjectList gt node with the following sections lt UDSObject gt node from the lt UDSObject gt Node Description section of this chapter There will be a lt UDSObject gt node with all the given properties for the first n documents that the method finds where n equals the resultSize parameter For example if the resultSize parameter is 10 the maxDocl ds parameter is 50 and the method finds 100 documents then there are 10 lt UDSObject gt nodes with all the properties requested in the Attributes section and 40 lt UDSObject gt with only the ID property in the Attributes section If you want to retrieve detailed lt UDSObject gt information for documents 11 20 you need to make a call to the getDocumentsBylDs method and pass it those IDs If the getRelatedCategories parameter is set to True the lt UDSObjectList gt node is included in the Attributes section for related categories Each INDEX DOC LINKS node contains the relational ID of the category as shown by the following example 1 70 The following parameters apply to the
61. ad of applications for accessing web services Whether it is a C application a Microsoft Office Add In a Java Server Page or a script there is a tool available to add web services capabilities Some examples of environments and toolkits available include Microsoft s Visual Studio NET Microsoft s SOAP Toolkit Java 2 Enterprise Edition technology Sun s Java Web Services Development Pack IBM Websphere and Apache Axis Many others are also available We recommend that you browse the various options and select one that matches your requirements Most toolkits provide documentation and samples for creating web service clients Implementations Offered Two implementations of the Unicenter Service Desk Web Services were included in the prior release one used Microsoft NET and the other used Java 2 Enterprise Edition J 2EE technology However only the J2EE implementation is offered in this release in order to provide consistent behaviors across platforms For backward compatibility the post GA r6 0 J2EE Web Services is still offered in this release Users of GA r6 0 NET Web Services need to switch to J2EE Web Services The WSDL of the post GA r6 0 Web Services is exactly the same as the original NET implementation meaning that code targeted for 6 0 should continue to function the same but you will need to specify a different SOAP end point Important After migrating from r6 0 Unicenter Web Services running on Unicenter Service Des
62. all contacts Returns A lt UDSObject gt node with a lt UDSObject gt node describing a contact with some of the following child Attributes nodes XML Element Value Type Description contactid String Specifies a unique ID of the contact contactld is UUID in string format userid String Indicates the user name of the contact last name String Indicates the last name of the contact first name String Specifies the first name of the contact middle name String Specifies the middle name of the contact location String Indicates the location of the contact dept String Identifies the department of the contact organization String Identifies the organization of the contact email address String Identifies the email address of the contact pemail address String Signifies the alternate email address of the contact phone number String Indicates the phone number of the contact 74 Web ServicesUser Guide createTic ket XML Element Value alt phone address1 address2 city state zip country delete flag Contact Management Methods Type Description String Indicates the alternate phone number of the contact String Specifies the address of the contact String Specifies the alternate address of the contact String Identifies the city of the contact String Identifies the state of the contact String Indicates the zip code of the contact String Indicates the coun
63. an example of efficient querying of groups and members see Where Clauses Web Services Methods 85 Group Management Methods Returns Automatically returns no handles The Handle element in the return is always empty To request the member or group handle for each row use one of the following in the attributes parameter described in the table member persistent id group persistent id XML Element Type Description lt UDSObjectList gt N A Identifies the outer element which contains an array of lt UDSObject gt elements Each object is really a grpmem object For information about the contents of each lt UDSObject gt element see XML Object Returns 86 Web Services User Guide Business Methods Business Methods This section describes the Web Services Business methods createlssue The following parameters apply to the createl ssue 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 Service Desk user attrVals String Identifies the array of name value pairs that is used to set the initial attribute values for the new issue propertyValues String Optional Identifies the array of values for any properties that are attached to the new issue template String Optional I
64. an existing change order specify a handle in the changeHandle parameter In this case changeAttrVals is ignored If a new change order is created description is used on the new change order s activity log If an existing change is attached description is used on the request s activity log If the request already has an attached change order the following error is returned UDS CREATI ON ERROR Note This method works exactly the same for the ITIL methodology simply verify that you are passing the appropriate handle of an ITIL Incident or Problem to the method Returns The following is returned XML Element Type Description lt changeHandle gt String Identifies the handle for the change order created or attached Web Services Methods 107 Business Methods detachChangeFromRequest The following parameters apply to the detachChangeFromRequest method Parameter Type SID Integer creator String requestHandle String Description String Description Description Identifies the session retrieved from logging in Identifies the handle of the contact responsible for the activity Identifies the handle of a request Optional Identifies the description of the activity Detaches a change order from a request This method corresponds with Activities Detach Change Order on the Service Desk client The change order is not deleted from the system There is no effect if the request did not have an atta
65. applications regardless of platform Web Services and Unicenter Service Desk Advantages Web Services is a set of data exchange standards that enable communication between applications even if they are on completely different platforms This is analogous to browsing the Web on a personal computer all remote websites are accessible regardless of whether they are hosted on Solaris AI X Windows and so on In the same manner Web Services allow applications to communicate over HTTP to various servers regardless of platform For example a Microsoft Office application can communicate with a program on a UNIX server and a Java Server Page can access a server hosted on a Windows server This platform neutral communication allows for powerful integrations The Web Services takes advantage of this technology allowing most any application access to Unicenter Service Desk and Knowledge Tools Web Services clients can create tickets update assets search the knowledge base and much more Web Services Basics 9 Access Web Services Access Web Services To access the Unicenter Service Desk Web Services as with any web services your application must be capable of handling standard web services technologies including XML SOAP WSDL and HTTP The easiest method for implementing any web services is to use an environment or toolkit that supports these technologies Many vendors and open source initiatives offer SDKs and tools that enable a myri
66. associated with the policy decrypting the encrypted policy code matching the decrypted content with the policy code and finally opening a session with a back end server The plain text session ID SID is returned and can be used for subsequent method invocations Only the policyholder holds the private key that matches the policy s associated public key stored in Unicenter Service Desk All subsequent web services calls must include the returned session ID SID The Proxy contact specified in the policy is responsible for all web services activities initiated in this session All function group security and data partition is enforced for the proxy contact Important The Encrypted Policy parameter should be in the BASE64 text format The user application must perform proper conversion from the binary format Policy is a required field When you define it use plain text policy code as defined in a policy Encrypted Policy the digital signature of the policy code encrypted with the policy holder s private key is required When you define Encrypted Policy use the algorithm SHA1 with RSA to obtain the digital signature Extemal Specifications 21 Public Key Infrastructure PKI Authentication Configuration for the PKI Authentication Type To configure for PKI authentication you must first create an access policy The process flow is as follows Create an Access Policy The administrator performs this task by using the GUI web int
67. ations using the entire table of 10 000 Contacts Downloading values for all 10 000 at once could result in an unacceptable performance lag this condition is actually prevented by the system see Where Clauses With a list handle however you can select a range of rows upon which to query The primary drawback to using a list handle is the extra method calls it requires At least two or three calls are necessary as indicated by the following m One to get the handle Ww A second or third to retrieve values A final call to free the list You need to balance the amount of remote method calls versus the expected amount of data returned Note Unicenter Service Desk restricts the amount of data that can be returned from any one list For more information see Where Clauses The following parameters apply to the doSelect method Parameter Type Description SID Integer Identifies the session retrieved from logging in objectType String Identifies the object type factory to query whereClause String Optional Identifies the where clause for the query 122 Web Services User Guide Parameter maxRows attributes Type Integer String Lis Query Methods Description Indicates the maximum number of rows to return Specify 1 to return all rows Note Regardless of the integer specified Unicenter Service Desk will return a maximum of 250 rows per call Identifies the attribute list for which to fetch
68. center Asset Portfolio Management APM Unicenter Management Portal Unicenter Network and Systems Management NSM Unicenter Remote Control Unicenter Service Desk Unicenter Knowledge Tools KT Unicenter Software Delivery Unicenter TNG for Windows Contact Technical Support For online technical assistance and a complete list of locations primary service hours and telephone numbers contact Technical Support at http ca com support Contents Chapter 1 Web Services Basics 9 Web Services and Unicenter Service Desk Advantages sssssssssssse memes 9 Access WED SERVICES ceste endet tone orar detti dasuetedkuni eaututuM LL cer A DL P ex EEEE 10 Implementations Offered eret oe teni or ge Pe dee ed in vhs ses kinder ens Erg iae bre ubere PENERE RAE 10 Web Services Components idrici narria eni a annen aE REA AT EA es e esie esie ese san nnn 10 Unicenter Service Desk COMPONENTS meme mmn eem he essen nennen nnns 11 Obtain the Web Services WSDL Document sssssssssssssssssee se meses ese eene nns 11 Tips for Web Services Clients sessssssssssse Im mme memes esse ene esee 12 e neun 12 SECUN RR EE 14 Error Handling ete 17 Web Services linstallatiOni xenon ettet thee ER RRREEREE RNKRFRSERVR ERR X e ER RLMEREXRDAR ET QUE EE 18 Chapter 2 Extemal Specifications 19 User Access Authentication scrisse ki Renee PR RR RR KERERE LENKER AE EEEE EEEE ERR du
69. cess policy contains no access restrictions and is only applied to sessions authenticated through username and password Define an Access Policy To create any web services access policy an administrator has to define an access policy Perform the following steps to define the access policy 1 Launch Unicenter Service Desk and select the Administration tab to view the Administration menu 2 Select Web Services Policy and then Policies to access the Create New Web Services Acess Policy window 3 Each access policy contains a unique symbol and code Enter field information based on the following table descriptions Field Description Symbol Required Identifies a symbolic name of the access policy Code Required Indicates the unique text that identifies this access policy Status Identifies the status of an access policy An inactive policy is not used Proxy Contact Identifies the contact to use for all web services operations and Service Desk security 26 Web ServicesUser Guide Field Default Has Key Allow Impersonate Description Ticket Creation Object Creation Object Updates Attachments AccessControl and Management Description Identifies the default policy Set this policy as the default policy Only one active default policy is allowed to exist Creating a new default policy automatically sets the current default policy to a non default status Read Only indicates whether a public k
70. cess to Unicenter Service Desk Web Services Note The login user that you specify in the username parameter not the proxy contact specified in the policy is responsible for activities initiated in a session All function group security and data partition is enforced for this login user Extemal Specifications 19 Public Key Infrastructure PKI Authentication login Usemame Password This method is provided for backward compatibility where access authentication is performed on the username and password supplied A SID session ID is returned only if the access is authenticated All subsequent web services calls need to include this SID Default access policy is then applied to all subsequent web services accesses labeled with the SID Username and password are required fields that require plain text when you define them loginServic e Usemame Password Polic y This method is similar to the previous login function in that access authentication is performed on the username and password supplied A SID is returned only if the access is authenticated However a specific access policy as identified in the third parameter is applied to control and manage all subsequent Web Services accesses Empty content in the policy parameter automatically applies the default policy Username and password are required fields that require plain text when you define them Policy is required but can be empty and you must use plain text Use the
71. ched change Returns The handle of the request s activity log marking the event logComment The following parameters apply to the logComment method Parameter Type SID Integer ticketHandle String 108 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the handle of the ticket where the activity log should be added notifyContacts Parameter Type Comment String internal flag String Description Business Methods Description Identifies the comment text Identifies the internal flag Set to True if the new activity log should be marked as internal Attaches a Log Comment activity log to a ticket It is a simplified version of createActivityLog Returns Nothing The following parameters apply to the notifyContacts method Parameter Type SID Integer creator String Description Identifies the session retrieved from logging in Identifies the handle of the contact responsible for the activity Web Services Methods 109 Business Methods Parameter contextObject messageTitle messageBody notifyLevel notifyees Internal 110 Web Services User Guide Type String String String Integer String Boolean Description Identifies the handle for a request issue or change order The following applies a It is the context for the notification Any other object type is rejected An activity
72. child nodes XML Element Values Data Type Description id Integer Identifies the unique ID of the document type DOC TYPE TXT String Identifies the name for the document type The following parameter applies to the getTemplateList method Parameter Type Description SID String Identifies the session retrieved from logging in 172 Web Services User Guide Knowledge Tools Description Retrieves the list of document templates Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing CI DOC TEMPLATES with the following Attributes child nodes XML Element Value Type Description id Integer Identifies the unique ID of the document type TEMPLATE NAME String Identifies the name for the document template IS PREDEFINED Integer Indicates whether the template is predefined by the Knowledge Tools system and cannot be deleted IS DEFAULT Integer Indicates whether the template is the default that will be assigned to new documents getWorkflowTemplateList The following parameter applies to the getWorkflowTemplateList method Parameter Type Description SID String Identifies the session retrieved from logging in Description Retrieves the list of workflow templates Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing WF TEMPLATE with the following lt Atttributes gt child nodes XML Element Value Type Description id Integer Identifies t
73. code a failed Web Services method call raises a SOAPException exception All errors cancel the operation invoked Web Services Basics 17 Web Services Installation Web Services In some cases errors may be written by the servlet container and therefore display in the servlet container logs In other cases error information may be written to Unicenter Service Desk logs These logs are located in the following subdirectories m n the bopcfg www CATALINA_BASE logs subdirectory of Unicenter Service Desk installation n the log subdirectory of the Unicenter Service Desk installation and to all that have the prefix stdlog see the following note concerning activating this logging Note We recommend that you constantly monitor these logs as the server may log its own errors without reporting them to the Unicenter Service Desk Web Services Installation The Web Services is installed during Unicenter Service Desk installation for both the primary and secondary servers For the primary server installation the Web Services is automatically deployed during Unicenter Service Desk configuration For the secondary server this is an option you select during Service Desk configuration All appropriate files are included with the primary server installation If you want to install the Web Services on a machine other than the primary install the primary package along with the web engine package but configure it as a secondary Y
74. ct the otherwise plain text transmission of the application level authentication exchange s and subsequent session identification and data Important SSL or https is recommended when deploying Web Services to protect the application level authentication exchange s and subsequent transmissions of session identification and data Web Services Basics 15 Security Web Service Configuration 16 Web Services User Guide To allow administrators to enforce communications protocol level security at the level of the Web Services application the following two security configuration commands are supported require secure logon This security feature requires you to use SSL or https for calling the Login and LoginService methods This feature also provides a handy method for protecting the username and password while avoiding the overhead of SSL for the rest of the web services Important If you use the require secure logon command the Web Services application will not confirm that communications protocol level security is enforced for methods other than Login and LoginService Unless other precautions are taken the other Web Services methods may be invoked insecurely causing greater vulnerability to security threats require secure connection This security feature requires you to use SSL to access any part of the web service If https is required but not used then a SOAP Fault with code UDS SECURE CHANNEL REQUIRED is ret
75. cument Indicates the resolution of the document This can contain html Indicates the status ID for the document The default is 70 Published Indicates the priority ID for the document The default is 20 Normal Indicates the date that the document becomes active which is also used in conjunction with ExpirationDate Leave blank to specify no start date and the document becomes active as long as the expiration date is not exceeded Indicates the date that the document expires which is used in conjunction with StartDate Leave blank to specify no expiration date Parameter SD PRODUCT ID ASSIGNEE ID SD ASSET ID SD ROOTCAUSE ID SD PRIORITY ID SD SEVERITY ID SD IMPACT ID SD URGENCY ID AUTHOR ID OWNER ID SUBJECT EXPERT ID NOTES Type Integer UUID UUID Integer Integer Integer Integer Integer UUID UUID UUID String Knowledge Tools Description Indicates the product ID from Unicenter Service Desk with which to associate this document Indicates the unique ID from Unicenter Service Desk to which this document is assigned Indicates the asset ID from Unicenter Service Desk with which to associate this document Indicates the root cause ID from Unicenter Service Desk with which to associate this document Indicates the priority ID from Unicenter Service Desk with which to associate this document Indicates the severity ID from Unicenter Serv
76. d If this field is empty all attribute values are returned Web ServicesMethods 117 Asset Management Methods Description Describes the recommend method for creating a new asset If you intend to create an asset with an extension be sure to set the Asset Class attribute in the attrVals section Note If you are using the I TIL methodology use this method to create a Configuration Item See the Note on Using the I TIL Methodology Installation Returns A lt UDSObject gt element containing the new object s 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 For more information about the return format see XML Object Returns XML Element Type Description UDSObject N A Identifies the standard lt UDSObject gt element containing the handle and requested attribute values lt NewAssetHandle gt String Identifies the new request s handle lt ExtensionHandle gt String Identifies the handle for the new Asset s extension If no extension was created this field is empty lt ExtensionName gt String Identifies the name for the new asset s extension If no extension was created this field is empty 118 Web Services User Guide getAssetExtensioninformation Asset Management Methods The following parameters apply to the getAssetExtensionl nformation
77. d by the OBJECT declaration in a majic file All objects shipped with Unicenter Service Desk are enumerated in the Unicenter Service Desk Modification Guide Unicenter Service Desk Web Services 39 Objects SSS An object has attributes which are essentially columns in a database table do not confuse these with XML attributes Web Services offers many methods to retrieve values for attributes Many methods require you to name attributes for setting or retrieving values You must use the attribute name assigned in the majic or mod file that defines the object which can be different than the actual database name For a list of all the attributes for each object see the Unicenter Service Desk Modification Guide It is possible for client sites to add additional attributes as a customization Web Services uniquely identifies an object by its handle which is a string value of the form objectType ID where objectType is the object s type factory name and ID is a unique value The ID value matches that of the id attribute found in every Unicenter Service Desk object Because the id attribute is almost always indexed in the DBMS using the ID portion of the object handle is especially valuable for forming efficient queries Each object regardless of its type stores this value in an object attribute named persistent id Note n prior releases the ID portion of the handle was always a string of integers In r11 the ID portio
78. d Integer Description Description Identifies the session retrieved from logging in Identifies the unique ID of the contact for which you want to retrieve bookmarks Contact ID is UUID in string format Identifies the document ID you want to bookmark Adds a bookmark for a particular contact Returns A lt UDSObject gt node describing the newly created bookmark Web ServicesMethods 169 Knowledge Tools deleteBookmark getStatuses The following parameters apply to the deleteBookmark method Parameter Type Description SID Integer Identifies the session retrieved from logging in contactl d String Identifies the unique ID of the contact for which you want to delete a bookmark Contact ID is UUID in string format docld Integer Identifies the document ID of the bookmark you want to remove Description Deletes a bookmark for a particular contact Returns Returns error codes only for individual errors For additional information see Error Codes The following parameter applies to the getStatuses method Parameter Type Description SID String Identifies the session retrieved from logging in Description Retrieves the list of statuses 170 Web Services User Guide getPriorities Knowledge Tools Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing CI STATUSES with the following Attributes child nodes XML Element Values Data Type Description id I
79. d in secure storage on the user side where it can be retrieved and used for logging in to Unicenter Web Services Example of secure storages include the following Windows Certificate Store a java Certificate Store managed by java keytool utility a Certificate store created by other security products such as one of the eTrust products A user application should be able to load the digital certificate and extract the private key using appropriate APIs depending on user environments Once the private key is extracted from the digital certificate it can be used to generate a digital signature of policy code Creating a digital signature encrypts a digest of a text with a private key The digest algorithm must be standard SHA1 and the encryption algorithm should be RSA Also the binary digital signature should be converted to BASE64 text format before it can be used for logging in to Unicenter Web Services Depending on user environments appropriate API calls should be used to archive this information Extemal Specifications 23 Public Key Infrastructure PKI Authentication Process Description Invoke the Web Service Call A user application should invoke the Web Services method loginServiceManaged along with the plain text policy code and the BASE64 text formatted digital signature of the policy code Obtain the Returned SID If the access request is authenticated a plain text SID is automatically re
80. d to CA or destroyed EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LI CENSE AGREEMENT TO THE EXTENT PERMITTED BY APPLI CABLE LAW CA PROVI DES THIS PRODUCT AS IS WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NONI NFRINGEMENT IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE DIRECT OR INDIRECT FROM THE USE OF THIS PRODUCT INCLUDING WITHOUT LIMITATION LOST PROFITS BUSINESS INTERRUPTI ON GOODWILL OR LOST DATA EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE The use of this Product and any product referenced in the Documentation is governed by the end user s applicable license agreement The manufacturer of this Product is CA This Product is provided with Restricted Rights Use duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12 212 52 227 14 and 52 227 19 c 1 2 and DFARS Section 252 227 7013 c 1 ii as applicable or their successors All trademarks trade names service marks and logos referenced herein belong to their respective companies Copyright 2006 CA All rights reserved CA Product References This document references the following CA products Advantage Allfusion BrightStor CleverPath Portal eTrust Embedded Identity and Access Management eTrust el AM Unicenter Asset Management Uni
81. dListValues getGroupMemberListValues QgetPendingChangeTasksForContact a QetPendinglssueTasksForContact a getWorkFlowTemplates a getWorkflowTemplateList getTasksListValues a getNotificationsForContact a getPolicyl nfo a QetAssetExtensionl nformation a getLrelValues 30 Web Services User Guide getObjectValues doSelect doQuery getPropertyl nfoForCategory getValidTaskTransitions getListValues getListl nfo findContact getAttmntl nfo getAttmntList getBookmarks getCategory getComments getContact getDecisionTrees getDocument getDocumentTypes getFolderl nfo getFolderList getLrelLength getPriorities getRepositoryl nfo getStatuses getTemplateList Knowledge createDocument deleteDocument doSelectKD faq attmntFolderLinkCount getAttmntListPerKD isAttmntLinkedKD getDocumentByl Ds Access Controland Management Extemal Specifications 31 Access Control and Management a getKDListPerAttmnt getQuestionsAsked modifyDocument a rateDocument a Search When an access policy is updated by Unicenter Service Desk Web Services dynamically updates the corresponding policy information Active Web Services sessions controlled under this policy remain controlled with configurations in the policy New Web Services sessions for this policy to manage and control take the latest configurations in effect Not
82. dentifies the handle of an issue template iss tpl object from which to create the new issue Web Services Methods 87 Business Methods Parameter Type Description 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 Description Creates a Service Desk Issue iss object For more information about creating an Issue object with properties see createRequest Note You must use this function to create a new Issue do not use createObject Returns Returns the new object s handle along with all of its attribute values List and LREL types are also returned but as empty elements For more information about the return format see the XML Object Returns XML Element Type Description UDSObject N A Identifies the standard UDSObject element containing the handle and requested attribute values NewlssueHandle String Identifies the new issue s handle NewlssueNumber String Identifies the new issue s number its ref num attribute 88 Web ServicesUser Guide createQuic kTic ket Business Methods The following parameters apply to the createQuickTicket method Parameter SID customerHandle description Type Integer String String Description Identifies the session retrieved from logging in Identifies the customer handle used
83. dentifies 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 lt UDSObject gt element containing a sequence of lt UDSObject gt elements in the order of the sequence attribute Web Services Methods 97 Business Methods 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 Iden
84. dle Required Identifies the handle of the contact used for the log s author Identifies the text for the new asset log Asset Management Methods Description Adds a new log entry for an asset The log s author is the user associated with the SID Returns Nothing createAssetParentC hildRelationship The following parameters apply to the createAssetParentChildRelationship method Parameter Type Description SID Integer Identifies the session retrieved from logging in parentHandle String Identifies the asset handle for the parent childHandle String Identifies the asset handle for the child Description Makes assetParent a parent of assetHandle Web Services creates a separate object the hier object which is the Assignment table for parent child relationships between assets These are stored in related lists child_hier and parent_hier in the Asset nr object Returns Handle of the new hier Assignment object Web Services Methods 121 List Query Methods Lisy Query Methods doSelect Two paradigms are available for working with lists One paradigm uses a list handle for referring to and making queries on a server side list and the other simply performs a SQL like select If you need to maintain reference to a static list use the methods that return list handles These methods are especially useful when working with very large lists For example your application may need to perform oper
85. ds 19 User Name Password Authentication sess meses eee 19 login Username Password cic nemen mener nennen nnne nnn enn 20 loginService Username Password Policy cssssssssssssssee mene 20 Public Key Infrastructure PKI Authentication sssssssssssssssee nnm emm nn 20 loginServiceManaged Policy Encrypted Policy sssssssss Hm 21 Configuration for the PKI Authentication Type sssssssssssse memes nnns 22 Login to Web Service Seicise EUER 23 Session and Authorization e trt ee e E RR RE TY E ERN E E DX E YR ET 25 Access Control and Management noc eterne Rr eA ERRNRER UR REY EE RNTEEIEREERYA TR RRFR RIS AIR EX xU R EE P YRGUR 26 Define an Access Polly ecran etes end dt E ex un ra ERREUR Ra rn b Rea pun Ka ed nbn daas 26 Web Services Methods by CateQoriesS ccc cee emen semen hen nenne 29 Define a Problem Types nrs t eto ree RR epee ciet candace saute FEN easier Mene tdv uER E 32 Simplified Web Services Access ssssssrssserrrrtrstttrstrun ee me en memen e emeehemesis esie esee esse ess nnns 37 Chapter 3 Unicenter Service Desk Web Services 39 ell HEEL 39 LOCKER OFS tt UELLE 41 Access the Unicenter Service Desk Web Services sssssssssssesss mmm 41 TIME QUES cette Em 41 System Updates and Caching ccccece cece nee ee eee eee eee ems esse enn enn nnns 42 Categories and Properties ipi sie na ienris enn ona ea dete Eae Se ed
86. e For more information about each method see the chapter Web Services Methods Define a Problem Type Problem Types are assigned when creating tickets and an access policy defines one set of these problem types A Unicenter Service Desk Web Services user application may use low level web methods to create a ticket request change order or issue specifying one of these types to categorize the problem addressed in the ticket Problem Types can be used only with the high level createTicket method For more information about high level web methods see Simplified Web Services Access Note Low level methods such as createRequest do not use problem types 32 Web Services User Guide Access Control and Management Web Services Problem Types Unicenter Service Desk Web Services also provides a defined set of out of the box problem types which are created for every policy These default types designated as internal problem types can be deactivated but never deleted The following Web Services Access Policy Detail window shows the default problem types provided when a new policy has been created Logged in as Log Out Window Help Web Services Access Policy Detail Symbol Gode status DEFAULT DEFAULT Yes No No Default web service access policy 1 Access Control 2 Problem Types Problem Type List Summary Name Code Description Default R ACC ER Failed to access resource No E
87. e RS E aa E E E EI DEI E EE was A 128 getRelatedliStsmpgirrrisn cnn A E EETA RE 129 getRelatedListValues iirinn aA A A A A A 130 getPendingChangeTaskListForContact 0 cc iene 132 getPendingl ssueTaskLiStForContact 0 ete 132 getNotificatlonsFOrCohtact eere das lene er ER pere cab ened ag Der Fears Gusts ane T Rn dawns 133 Contents vii LRELIMECROQ S ERR ETE UUUTEUEK 135 o sg R Ierepi merce 136 getire altes cisrasasn s cteasvesnxedes covert eituianear via dereerntadveaemlacgeervs staevee A yaaa 137 createLrelRelationships eer E ERRARE ERU ERR ERR RIFRERERIR EASRPPTERUEDR RR I BIRRR R XR RM RA Rada 138 removeLrelRelationships iori cere dne ert rede ede a e rid Ee ir tede beri eren E d pe Yet E 140 Knowledge TEO0l5 ote exiens xg ex ertt tue att edet be tds cubes th gucmensp eure teer 140 Table TYP S ee erni aE aon EESE ARRESE E EES ET EEOAE E OE PEE EEAS ER EAEN EENE E ED 141 Knowledge Tools General Methods ssssssssssssssrserrtssrrtntrntrnrntrerstrenstranstransrnannnnurnnnernnnene 142 Attachment Methods ve tet c ERE RE VER ARA RARE Od ERR DM PLN dea IRE UR E NY RIA 174 Miscellaneous Methods rre es ER ERREREYRERERRER r XAR PU E IR V RXMRR CRF eas VENCER RERESET 183 callServerMetli d iere depen a teen thee Ru ERE EAE Nt Uebt Rud td nde ERa 184 ael E 186 CCB OPS Micah se etre PCENA 188 getConfigurationMode cii te ERR RR R
88. e String Returns only the contacts with this access type You can specify multiple roles by separating them with commas Specify the following a 2402 for Administrators 2403 for Analysts m 2404 for External Customers a 2405 for Internal Customers 2406 for Knowledge Engineers 2407 for Knowledge Managers inactiveFla Integer Returns only the contacts that g are inactive or active Specify the following O for active a 1 for inactive a 999 for all 80 Web Services User Guide Description Retrieves the list of contacts Returns Contact Management Methods A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing contacts with the following lt Attributes gt child nodes XML Element Value id userid last name first name access type delete flag getPermissionG roups Type UUID String String String Integer Integer Description Specifies the unique ID of the contact Specifies the user name of the contact Identifies the last name of the contact Identifies the first name of the contact Specifies the Role ID of the contact Indicates whether the contact is active or inactive m O for active 1 for inactive a 999 for all The following parameters apply to the getPermissionGroups method Parameter SID groupl d Type Integer nteger Description Identifies the session retrieved from logging in Returns o
89. e dash separated list of group IDs that have read permission for this document for example 1 3 4 Use A to assign permission to everyone Identifies the dash separated list of group IDs that have write permission for this document for example 1 3 4 Use A to assign permission to everyone Indicates the status of the flag to inherit permissions from the category in which the document is being created Set to True if you want to inherit permissions and then ReadPermissions and the WritePermissions parameters will be ignored Identifies the ID for the type of document that this document will be a regular document or a tree document The default is a regular document Identifies the number of times that the document has been viewed Identifies the ID for the template you want to assign to this document Identifies the ID for the workflow template you want to assign to this document Specifies a custom field Knowledge Tools modifyDoc ument Attribute Value CUSTOM2 CUSTOM3 CUSTOMA CUSTOM5 CUSTOM_NUM1 CUSTOM_NUM2 Description Creates a new document Returns Type String String String String Double Double Description Specifies a custom field Specifies a custom field Specifies a custom field Specifies a custom field Specifies a numeric custom field Specifies a numeric custom field A lt UDSObject gt node describing the Knowledge Document created The following parameters apply
90. e email notification list for the document Description Retrieves information for a document Returns A lt UDSObject gt node as described in the lt UDSObject gt Node Description with requested lt Attributes gt provided by the propertList parameter The following parameters apply to the createDocument method Parameter Type Description SID String Identifies the session retrieved from logging in attributeValues String Identifies an array of name value pairs used to set the initial attribute values for the new Knowledge document as illustrated by the following SUMMARY Summary text TI TLE Title text Web ServicesMethods 153 Knowledge Tools As part of the createDocument method the following table reflects examples of valid commonly used attribute values for a document Data in the Type column reflect the actual type which must be parsed to the method in string format in the attrVals string array Attribute Value Type Description PRIMARY INDEX Integer Identifies the category ID in which to create the document Use 1 for the Root category USER DEF ID String Identifies any ID that you would like to use to represent the document TITLE String Identifies the title of the document SUMMARY String Identifies the summary of the document PROBLEM String Identifies the problem of the document RESOLUTION String Identifies the resolution of the document This can contain html STATUS ID Integer Id
91. e of these can be returned Web Services Methods 99 Business Methods escalate The following parameters apply to the escalate method Parameter SID creator objectHandle description setAssignee newAssigneeHandle setGroup newGroupHandle setOrganization newOrgnizationHandle 100 Web Services User Guide Type Integer String String String Boolean String Boolean String Boolean String Description Identifies the session retrieved from logging in Identifies the handle of the contact responsible for the activity Identifies the handle for a request issue or change order Any other object type is rejected Identifies the description for the activity which will appear in the activity log Updates the assignee field if true Identifies the handle of the new assignee for the object Updates the group field with the value in newGroupHandle if true Identifies the handle of the new group for the object Sets the organization field with the value specified in the newOrganizationHandle if true Issues and Change Orders only Identifies the handle of the new organization for the object Business Methods Parameter Type Description 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 Perform
92. ecently added Use this with the updateRating method if you want to modify the rating at a later time DOC ID Integer Identifies the document ID INDEX ID Integer Identifies the category ID 166 Web Services User Guide Knowledge Tools updateRating getQuestionsAsked XML Element Value Data Type Description BU RATING String Identifies the rating given to the document HIT NO VOTE Integer Identifies the rating set because a user viewed the document and not actually rated it or vice versa The following parameters apply to the updateRating method Parameter Type Description SID Integer Identifies the session retrieved from logging in ratingl D Integer Identifies the unique ID of the rating you want to modify This ID is returned by the rateDocument method rating Integer Identifies the new rating to apply to the document a scale of 0 4 where 0 is the worst and 4 is the best Description Updates one of the ratings of a particular document Returns A lt UDSObject gt node describing BU TRANS with the updated rating attribute The following parameters apply to the getQuestionsAsked method Parameter Type Description SID String Identifies the session retrieved from logging in resultSize Integer Identifies the number of searched text for which you want to retrieve detailed information Web ServicesMethods 167 Knowledge Tools getBookmarks Parameter Type Descending Boolean Descripti
93. ement Type Description lt UDSObject gt N A Identifies the standard UDSObject element containing the handle and requested attribute values lt NewWorkflowHandle gt String Identifies the new workflow task s handle 198 Web Services User Guide Attachment Methods deleteWorkHowTask The following parameters apply to the deleteWorkFlowTask method Parameter Data Type Description SID Integer Identifies the SID of the current login session workflowHandle String Identifies the object handle of a workflow task objectHandle String Identifies the object handle of a change order or issue from which the workflow task is deleted Description Removes a workflow from its associated change order or issue Returns Nothing Attachment Methods This section describes the Web Services attachment related methods Only file attachments are handled by these methods link type attachments are handled by generic methods such as CreateObject In addition file uploads through Web Services employ the Direct Internet Message Encapsulation DI ME protocol Your SOAP implementation must support DIME in order to use these methods createAttac hment The following parameters apply to the createAttachment method Parameter Data Type Description SID Integer Identifies the session retrieved from logging in repositoryHandle String Identifies the object handle of a document repository Web ServicesMethods 199 Attachment Met
94. entifies the session retrieved from logging in creator String Identifies the handle of the contact responsible for the activity requestHandle String Identifies the request to which you attach the change Web ServicesMethods 105 Business Methods Parameter changeHandle changeAttrVals description 106 Web Services User Guide Type String String String Description Identifies the handle of the change to add If this is blank a new change order is created For additional information see the following Description Identifies the attribute value pairs used to initialize a new change order if the changeHandle is blank For more information see the following Description Optional Identifies the description of the activity Business Methods Description Attaches a new or existing change order to a request It corresponds with Activities New Change Request or Activities Attach to Existing Request on a Request detail in the Service Desk interface To create a new change order pass the empty string in changeHandle The system will create a new change order with values initialized from the request including the change s Requestor Affected End User Description and Priority you can see this effect in the Service Desk interface You can override these or set additional values with changeAttrVals which is a name value array similar to what is passed for createObject To attach
95. entifies the status ID for the document The default is 70 Published PRIORITY ID Integer Identifies the priority ID for the document The default is 20 Normal CREATION DATE Date String Identifies the date and time the document was created Leave blank to assign current date MODIFY DATE Date String Identifies the date and time the document was last modified Leave blank to assign the current date START DATE Date String Identifies the date the document becomes active and is used in conjunction with Expiration Date Leave blank to specify no start date and the document will be active as long as the expiration date has not been reached 154 Web Services User Guide Attribute Value EXPIRATION DATE PUBLISHED DATE SD PRODUCT ID ASSIGNEE ID SD ASSET ID SD ROOTCAUSE ID SD PRIORITY ID SD SEVERITY ID SD IMPACT ID SD URGENCY ID AUTHOR ID Type Date String Date String Integer UUID UUID Integer Integer Integer Integer Integer UUID Knowledge Tools Description Identifies the date the document expires and it is used in conjunction with Start Date Leave blank to specify no expiration date Identifies the date and time the document was published Leave blank to assign current date if the status is Published If the status is not Published this parameter is ignored Identifies the product ID from Unicenter Service Desk with which to associate this documen
96. eous Methods Description A list of all attribute names for a given object type along with type information for each attribute Information returned for the attribute s type includes the Integer String Date Pointer List and so on if the attribute is required for back storing its storage space requirements if appropriate Callers should cache the type information requested per object type to avoid multiple redundant and expensive calls The attribute information can change only after modifications are performed on the Service Desk server and the service is recycled Web ServicesMethods 191 Miscellaneous Methods Returns The following XML Element Type Description lt UDSObject gt N A Indicates the root node lt Attributes gt Sequence Indicates zero or more elements for each attribute lt attrName DataType dataType Empty Indicates an element with a Size storageSize Element name matching an object Required Boolean attribute name The element Factory factoryName gt has several attributes DataType Signifies the integer representation of the data type For more information about data types see the table in Attribute Data Types Size Represents the maximum size needed to store this attribute in a string Required Represents the flag status of True if this attribute must be set for the object to back store Factory Represents the Type name of the object if the attribute is a List Lre
97. er Identifies the folder handle ID objectHandle String Identifies the object handle of a Knowledge document to which this attachment is attached 174 Web Services User Guide Knowledge Tools Parameter Data Type Description description String Identifies the description for the attachment object fileName String Identifies the name of the full path of the file to be uploaded Description Uploads a file to the back end server An uploaded file is stored in a document repository specified by the repositoryHandle An attachment object is then created and attached to a document object specified by the objectHandle The attachment object has all the information for accessing the newly uploaded file in the repository Returns The following Parameter Type Description Handle String Identifies the object handle of the newly created attachment object Web ServicesMethods 175 Knowledge Tools attmntFolderLinkC ount attac hURLLink The following parameters apply to the attmntFolderLinkCount method Parameter Type SID Integer folderl d Integer Description Description Identifies the session retrieved from logging in Identifies the unique ID of the folder Describes the number of attachment links under a specific folder to be attached Returns Returns the number of attachments found under the specific folder The following parameters apply to the attachURLLink method Parameter Type SID Intege
98. erface only provided by Unicenter Service Desk and as part of the process needs to assign a unique text code to each access policy For additional information see Defining an Access Policy Obtain a Digital Certificate with a Public Private Key Pair and Associate it with the Access Policy 22 Web Services User Guide For PKI access authentication a user application needs to obtain a digital certificate that contains both a public key and private key pair An administrator can obtain the digital certificate through third party Certificate Authority CA or security products that support digital certificates Unicenter Service Desk also provides a server side utility that can generate a digital certificate It is located in NX ROOT bin directory as follows pdm pki p policy code certificate file f If you obtain a digital certificate through a third party CA or security products import it to where the Unicenter Service Desk server is located and then associate it to an access policy The administrator of the user application should obtain a digital certificate file that includes the content of an X509 V3 certificate in DER ASN 1 format In addition the certificate should contain only the public key of the public private key pair Using the I option the administrator should invoke the pdm pki utility to load the certificate The utility then loads the certificate extracts the public key converts the public key to BASE64
99. erty values at creation time there are three ticket creation methods createChangeOrder createlssue and createRequest Each has a parameter with which you can pass in values for any properties To discover which properties will be attached you must find out the properties associated with the category you intend to assign to the ticket The easiest method to use is getPropertyl nfoForCategory For more information about the getPropertyl nfoForCategory see createRequest To set property values after an update operation with updateObject you must query the property list after the update getRelatedList can help with this task Design time Feature The Unicenter Service Desk Web Services includes a method stub configuration feature for developers When activated the Web Services ignores the Unicenter Service Desk server and returns simulated data for method calls so Web Services calls can be made without running a Unicenter Service Desk server To activate this feature in the Java version edit deploy wsdd to uncomment the sections for design mode stubs You must reverse the deployment and redeploy the server and recycle the application server Note The Design time feature applies to Unicenter Service Desk Web Services methods only Unicenter Service Desk Web Services 43 XML Object Retums XML Object Retums Many of the Web Services methods return an XML representation of Unicenter Service Desk objects The Web Services
100. es 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 Tir ss 194 Web Services User Guide assignee cnt 555A043EDDB36D4F97524F2496B35E75 a contact Handle description My new description priority pri 38903 a priority Handle WorkFlow Methods If the update fails for any reason the entire operation aborts and no changes occur Note When updating a task set the status value last in the attribute array Returns A lt UDSObject gt 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 For more information about the return format see XML Object Returns WorkHow Methods This section describes the Web Services workflow related methods These
101. esults in a Cartesian product and is very inefficient assignee last name LIKE MIS OR group last name LIKE MI S Using IN the query can be coded as follows assignee last name IN MIS OR group last name IN MI S This query does not create a Cartesian product in fact it creates no joins at all Note The parentheses that normally enclose the list of values on the right side of IN can be omitted if there is only one value in the list Similarly you should avoid joins by converting queries as shown by the following example assignee last name LIKE Smith to assignee U 913B485771E1B347968E530276916387 This avoids the join with some loss in clarity Using IN the same partition can be written as follows with the clarity of the first version and almost the same efficiency as the second version assignee last name IN Smith The NOT keyword cannot be in conjunction with IN for example NOT IN Common Elements 65 Chapter 5 Web Services Methods This section provides the details for using the Web Services methods Each method explains the parameters description and returns Contact Management Methods This section explains the Web Services Contact Management methods login The following parameters apply to the login method Parameter Type Description username String Identifies the user ID password String Identifies the password Web Services Methods 67 Contact Management Me
102. et Handling see Duplicate Ticket Handling Web Services Methods 77 Contact Management Methods Description Creates a ticket based on the rules defined in both the Service Aware Policy and the specified Problem Type The Problem Type specifies the type of ticket created by a Request Change Issue template The supplied description is copied in and the user is set from the access policy s proxy contact If input problem type does not exist the policy s default problem type is used The problem type also defines how to handle duplicate ticket creation and additional returned data For detailed information about configuring access policy and problem types see the chapter External Specifications Returns Returns the new ticket s handle ticket number and the user specified return data defined in the problem type that is used to create the ticket XML Element Type Description UDSObject N A Returns a partial set of attributes because it is a high level method designed to simplify the process Their values come from the following methods and the XML element is returned so it is consistent with the returns of these methods createRequest createChange createlssue The body of this tag is empty NewTicketHandle String Identifies the new ticket s handle NewTicketNumber String Identifies the new ticket s number its ref_num or chg_ref_num attribute 78 Web Services User Guide
103. et creation time To determine if an asset has an extension query the extension_name attribute of the asset s family for example family extension name To retrieve values from an extension object query it like any other object by using the following method get Obj ect Val ues To get the handle for a particular extension object use the following method get Asset Extensi onl nf or mati on Update an extension object like you would any other object by using the following method updateObj ect We do not recommend that you create your own extension objects One is created for you if needed when createAsset is called Because of this automatic creation we recommend that you only use createAsset to create asset objects Note If you are using the I TIL methodology remember that Asset and Configuration Item are interchangeable in this context For more information see Note on Using the ITIL Methodology Installation 116 Web Services User Guide createAsset Asset Management Methods The following parameters apply to the createAsset method Parameter Type Description SID Integer Identifies the session retrieved from logging in attrVals String Identifies the array of name value pairs used to set the initial attribute values for the new asset attributes String Identifies the sequence of attribute names from the new object for which to return values Dot notation is permitte
104. ey has been associated with this policy This field is updated when a public key is associated with a policy through the pdm pki utility Identifies the allow impersonate privilege if this field is set the policyholder can invoke the impersonate web services method and create a new web services session in the name of the user to be impersonated Additional access authentication is not performed when creating the new session However only when the access level of the new user s access type is less than or equal to the grant level of the proxy user s access type can this method be successfully called Indicates the detailed description of this access policy Indicates the number of ticket call request change order and issue insertion operations allowed per hour Indicates the number of Service Desk object other than ticket object insertion operations allowed per hour Indicate the number of Service Desk object update operations allowed per hour Indicates the number of attachment related operations allowed per hour Extemal Specifications 27 Access Control and Management Field Description Data Queries Indicates the number of data query operations allowed per hour Knowledge Indicates the number of knowledge related operations allowed per hour Note The default value of 1 in any operation counter indicates that no restrictions apply to the corresponding operation A value of 0 zero indicates tha
105. g tables Note While the handles do not change the legible symbols may be edited Contact Type Object name ctp Handle Note ctp 2307 The Analyst type ctp 2310 The Customer type ctp 2305 The Employee type ctp 2308 The Group type I mpact Object name imp Handle Note imp 1605 Impact None imp 1600 Low impact 5 imp 1601 Medium low impact 4 imp 1602 Medium impact 3 Unicenter Service Desk Web Services 49 Use the Web Services Handle imp 1603 imp 1604 Priority object name pri Handle pri 505 pri 500 pri 501 pri 502 pri 503 pri 504 Severity object name sev Handle sev 800 sev 801 sev 802 sev 803 sev 804 Call Request Type object name crt Handle crt 180 crt 181 crt 182 50 Web ServicesUser Guide Note Medium high impact 2 High impact 1 Note Unassigned priority None Low priority 5 Medium low priority 4 Medium priority 3 Medium high priority 2 High priority 1 Note Low severity 1 Medium low severity 2 Medium severity 3 Medium high severity 4 High severity 5 Note Request Problem available only with the ITIL installation Incident available only with the ITIL installation Use the Web Services Query for Requests or Issues or Change Orders Assigned to a Contact The Active Hag One of the most common operations is retrieving the active requests assigned to an a
106. h you want to retrieve information The following fields are always returned regardless of the propertyList parameter id DOC TYPE ID m BU RESULT Identifies the database field that you want to use for sorting the results Multiple sort fields are not supported The default is BU RESULT meaning that the fag rating sorts it When id is used as a secondary sort it always sorts the results Identifies an indicator available for sorting the results in descending order Use this to add your own SQL where clause for filtering the results of the search Identifies the maximum amount of document IDs to be returned the default is 100 For example if you specify a resultSize of 10 and a maxDoclds of 50 if there are 100 matching documents in the database then 10 have their detailed information retrieved and 40 have just their IDs returned The remaining 50 are not returned at all Web ServicesMethods 143 Knowledge Tools search Description Use to perform a faq search Documents are retrieved based on the category ID that is passed Any documents residing in that category or in any sub category are returned To improve performance these methods only retrieve detailed information on a user defined set of documents which is controlled through the resultSize parameter The rest of the documents return their IDs only Using this method you can for example set up a paging mechanism where the user can click on
107. he unique ID of the workflow template Web ServicesMethods 173 Knowledge Tools XML Element Value Type Description WF NAME String Identifies the name for the workflow template WF DESCRIPTION String Identifies the description for the workflow template IS DEFAULT Integer Indicates that the default template is to be assigned to new documents Use the Knowledge Tools Web Services The login process and any error codes that may display for the Knowledge Tools Web Services are the same as those found for the Service Desk Web Services For additional information see Login and Error Codes Access the Knowledge Tools Web Services The Knowledge Tools Web Services uses Apache Axis implementation of standards set forth by the W3C Ideally a client on any type of platform should be able to access the services but vendor implementations vary For example Java and NET both provide tools for generating proxy classes from a WSDL service description If you experience any issues using the Web Services with a different technology consult your platform vendor or Microsoft s knowledge base Attachment Methods This section describes the Web Services Knowledge attachment methods createAtimnt The following parameters apply to the createAttmnt method Parameter Data Type Description SID Integer Identifies the session retrieved from logging in repositoryHandle String Identifies the object handle of a document repository folderld Integ
108. hese are pointers you must use dot notation to form a query as normal For example to find all Contacts with a last name beginning with B and in a group with the name Seattle you would use the following member last name LIKE B AND group last name Seattle You may also use handles as normal illustrated by the following member last name LIKE A AND group id U 555A043EDDB36D4F97524F2496B35E75 It is important to note that this method can retrieve values from all members and groups not just a single group To simply get information about all the members of a specific group or member just specify a handle in the where clause For example the following would retrieve values from a specific group group id U 555A043EDDB36D4F97524F2496B35ET75 The important concepts to remember are grpmem object contains two pointer attributes one is to member and the other is to group m grpmem object exists for each group member relationship The grpmem method actually queries the grpmem object table thereby returning an object representing a relationship between two contacts Therefore the attribute values you want to fetch in attributes must use dot notation from the grpmem object To fetch values from the member all your attribute names should be of the form member ATTRNAME as illustrated by the following example member last name To fetch values from the group use group ATTRNAME Note For
109. hods Parameter Data Type Description objectHandle String Identifies the object handle of a call request change order or issue to which this attachment is attached description String Identifies the description for the attachment object fileName String Identifies the full path of the file to be uploaded Description Uploads a file to the back end server An uploaded file is stored in a document repository specified by the repositoryHandle An attachment object is then created and attached to a ticket object specified by the objectHandle The attachment object has all the information for accessing the newly uploaded file in the repository Returns The following Parameter Type Description Handle String Identifies the object handle of the newly created attachment object removeAttac hment The following parameters apply to the removeAttachment method Parameter Type Description SID Integer Identifies the SID of the current login session attachmentHandle String Identifies the object handle of an attachment to be removed 200 Web ServicesUser Guide Attachment Methods Description Removes an attachment from a ticket object The attached file is then removed from the repository Returns Nothing Web ServicesMethods 201 Index A access for Web Services 10 policy 22 type for a contact 72 Access Control and Management 26 active flag 51 addAssetLog method 120 addBook
110. ice Desk with which to associate this document Indicates the impact ID from Unicenter Service Desk with which to associate this document Specifies the urgency ID from Unicenter Service Desk with which to associate this document Identifies the unique ID of the contact who authored this document If the author is not an internal contact you can set this filed to zero 0 and use the Author parameter instead Identifies the unique ID of the contact who owns this document Indicates the unique ID of the contact who is the subject expert for this document Indicates notes for the document Web ServicesMethods 159 Knowledge Tools Parameter Type Description READ GROUP LIST String Indicates the dash separated list of group ids that have read permission for this document for example 1 3 4 Use A to assign permission to everyone WRITE GROUP LIST String Indicates the dash separated list of group IDs that have write permission for this document for example 1 3 4 Use A to assign permission to everyone INHERIT PERMISSION Boolean Indicates the status of the inherit permissions flag Set to True if you want to inherit permissions from the category in which the document is being created If set to True the ReadPermissions and WritePermissions parameters are ignored DOC TYPE ID Integer Identifies the ID for the type of document that this document is to become a regular document or a tree document The default
111. ies the category ID in which to create the document getCategoryPaths Boolean Indicates the path for which to get category information It returns category information and the full text category path for each category Web Services Methods 161 Knowledge Tools Description Retrieves information for a category including a listing of all of its child categories Returns A lt UDSObjectList gt node with an lt UDSObject gt node describing the category requested getComments The following parameters apply to the getComments method Parameter Type SID Integer docl ds String Description Gets all the comments from documents 162 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the document IDs for all the comments you want to retrieve Note Use commas to separate for example 400001 400002 addComment Returns Knowledge Tools A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing O COMMENTS with the following Attributes child nodes XML Element Value id DOC ID USER ID USER NAME EMAIL ADDRESS COMMENT TEXT Data Type Integer Integer Integer String String String COMMENT TIMESTAMP Date Description Identifies the unique identifier for the comment most recently added Identifies the document IDs for the comment recently added Identifies the ID of the person who
112. ign key types For example the following query against the Request cr object returns all Requests assigned to contacts with a specific last name as illustrated by the following example assignee last name like Martin 62 Web ServicesUser Guide Where Clauses Dot notation is a great convenience to forming where clauses but you must be careful to ensure the query is an efficient one The query in the example could prove inefficient if the contact s last name attribute was not indexed in the DBMS however for this example it is To ensure indexes are used to their best advantage when searching through SRELs make use of the id attributes of the Unicenter Service Desk objects All tables in Unicenter Service Desk have an index on the id attribute The id attribute of an object is easily obtained from the object s handle As previously outlined an object s handle is a string of the form lt objectName gt lt id gt where id is the value of the id attribute found in every Service Desk object Simply extract the id portion and use lt attributeName gt id in the where clause An object s id is either of type integer or a UUID If it is an integer simply use it as such For example to search for Requests with the rootcause pointing to a Root Cause object with handle rc 1234 the where clause is rootcause id 1234 If the id of an object is a UUID type you must format it as follows U uui d gt
113. ion Identifies the repository name Identifies the unique ID of the parent folder Identifies the type of folder created Web ServicesMethods 181 Knowledge Tools getAumntinfo XML Element Value Type folder name String description String Description Identifies the name of the folder Identifies the description of the folder The following parameters apply to the getAttmntl nfo method Parameter Type SID Integer attmntl d Integer Description Returns the attributes of an attachment Returns Description Identifies the session retrieved from logging in Identifies the unique ID of the attachment folder A lt UDSObject gt describing the attachment with some of the following child lt Attributes gt nodes XML Element Value Type id Integer description String attmnt name String file name String folder id Integer repository Integer Description Identifies the unique ID of the attachment Identifies the description of the attachment Identifies the name of the attachment Identifies the name of the file Identifies the unique ID of the attachment folder Identifies the unique ID of the repository 182 Web Services User Guide Miscellaneous Methods The following parameters apply to the getRepositoryl nfo method Description Identifies the session retrieved from logging in Identifies the unique ID of the repository A lt UDSObject gt describing the repository
114. is written to the Service Desk log The Duration data type is an integer representing time duration in seconds For example 90 represents one minute and 30 seconds To set a duration type use an integer representing the number of seconds for the duration Negative values are not permitted To make a duration attribute null pass the empty string The Date data type represents a date value This is stored as a UNIX like UTC value in the database the number of seconds since 1 1 1970 When retrieving date values the integer UTC is returned Similarly use a UTC value to set a date Negative values are not permitted Null a date attribute by passing the empty string 56 Web Services User Guide List QREL BREL Attribute Data Types The SREL data type represents an SREL Single RELation which is a pointer to another object In database terms it is a foreign key to another table For example an Issue object has a pointer attribute to a Contact representing the Assignee Most Service Desk Web Services methods permit dot notation to retrieve information about objects to which an SREL points For example to specify the name of a Contact s organization from the context of the Contact use the following organization name You may expand to an arbitrary number of levels as shown in the following example organization contact first name Dot notation can only be used to retrieve attribute values such as using getObjectValues
115. k r6 0 to a r6 0 level Web Service on version r11 any object handles that you may have persisted should be considered invalid after migration Web Services Components Web Services components for this release of Unicenter Service Desk vary from those required for previous releases of the product The following topics summarize the components currently required 10 Web Services User Guide Web Services Components Unicenter Service Desk Components The installation files for this version of J 2EE Web Service are initially installed by the Service Desk and Knowledge Tools installation and can be located in the following directory NX ROOT sdk websvc R11 The installation files for the backward compatible J 2EE Web Services are located in the following directory NX ROOT sdk websvc 60 where lt NX_ROOT gt is the root installation path for Unicenter Service Desk Obtain the Web Services WSDL Document The location you need to access to obtain the WSDL Web Services Description Language document depends on the release of Unicenter Service Desk you intend to use The following outlines the two locations available r11 By default the WSDL for the r11 Web Services resides at the following URL http lt servername gt lt port gt axis services USD_R11_WebServi ce WSDL Post GA 6 0 The WSDL for the post GA 6 0 Web Services resides at the following URL http lt servername gt lt port gt axis services U
116. ke an arbitrary server side method These are methods defined in the proprietary spell 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 OSc string Ol 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 LSS 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 lt ServerReturn gt lt Paramx gt Web Services Methods 185 Miscellaneous Methods 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 lt ServerReturn gt N A lt Paramx gt String createObject Description Indicates the outer element which contains zero
117. keyword in an SQL statement For example a where clause to find contacts the cnt object by last name could be the following last name Jones or last name LIKE J one The second example finds all contacts with names beginning with Jone while the first just finds the J ones Unicenter Service Desk supports only a subset of the standard SQL parameters for where clauses and are listed as follows Logical operators AND OR and NOT LIKE andIS m NULL IN see notes following m Wildcard characters and _ for string matches All comparison operators lt gt lt gt lt gt Parentheses are allowed for grouping Explicit joins EXISTS and GROUP BY elements are not supported The column names are simply the object s attribute names You must use the names defined for the attributes at the object level do not use the actual DBMS column names for more information about mapping of object level names to DBMS column names see the appendixes Data Element Dictionary Objects and Attributes and Table and Object Cross References in the Unicenter Service Desk Modification Guide String values must be quoted as in the previous example Unicenter Service Desk data types such as date and duration are treated as integers as shown in the following example creation_date gt 38473489389 Dot notation is allowed in the where clause to search through SREL fore
118. l nfo SI D Lets users obtain the policy information that controls the current web services session You can use this information as an indicator of server capacity for this user application Users may want to adjust their web services calls to fit into the capacity By having this set of simplified Web Services APIs a majority of users are spared the tremendous effort of understanding the complete set of web services API and Service Desk schema Using them simplifies and accelerates the process of creating ServiceAware enabled applications for these users 38 Web ServicesUser Guide Chapter 3 Unicenter Service Desk Web Services Objects This section explains additional Unicenter Service Desk Web Services behaviors The Unicenter Service Desk system treats each entity such as a contact or an issue as an object These high level objects are defined in majic maj and mod mod files on the Service Desk server in the following directory bopcfg majic Customized objects are defined in the following directory site mods majic Objects are essentially high level wrappers around a database table Important The Unicenter Service Desk Modification Guide is essential to working with Web Services especially the sections describing the objects and database schema An object s type sometimes referred to as factory defines the object For example request objects belong to the cr type Each object s type is define
119. l or Pointer type It is not written unless it is a Llist Lrel or Pointer type data type 192 Web Services User Guide serverStatus updateObject Miscellaneous Methods 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 Service Desk server that is whether it is up and ready or shut down Note This method executes rapidly on the server machine Calling this periodically is a good way to keep a SID active Returns The following values apply m 1 Indicates the Service Desk server is not available m O Indicates the Service Desk server it is running XML Element Type Description lt ServerStatus gt Integer Identifies the value associated with the server status zero orl 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 Service Desk object to update Web Services Methods 193 Miscellaneous Methods Parameter Type Description attributeValues 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 Updat
120. le for sorting the results in descending order A lt UDSObjectList gt node with the following sections UDSObject nodes with requested Attributes nodes 150 Web Services User Guide getDocumentsByIDs Knowledge Tools The following parameters apply to the getDocumentsBylDs method Parameter SID docl ds propertyList sort By descending Type Integer String String String Boolean Description Identifies the session retrieved from logging in Identifies the comma separated list of document IDs to retrieve Identifies the comma separated list of database fields for which you want to retrieve information The following fields are always returned regardless of the propertyList parameter id DOC TYPE ID a BU RESULT Identifies the database field that you want to use for sorting the results The default is id but multiple sort fields are not supported If you specify another field id as a secondary sort always sorts the results Identifies an indicator available for sorting the results in descending order Web ServicesMethods 151 Knowledge Tools getDocument Description Retrieves information on one or more documents by passing the document IDs for which you want to retrieve information This is usually used after calling the faq or search methods In order to improve performance these methods only retrieve detailed information on a user defined set of documents
121. lic private key pair where login request encrypted with the private key can only be decrypted through the public key and vice versa For more information about access authentication see External Specifications 48 Web Services User Guide Use the Web Services Perform Common Tasks The Web Services is a flexible and powerful API into the Unicenter Service Desk but it requires some knowledge of the system s object structure The first step is to familiarize yourself with the appendix Objects and Attributes in the Unicenter Service Desk Modification Guide It lists the attributes of each object in the system which is essential because many of the Web Services methods require attribute names The next step is to review the Web Services methods especially generic ones For example if your application needs to display all the activity logs for a request first identify how the activity logs relate to the request The Unicenter Service Desk Modification Guide shows that the request object has two lists of Activity Logs The act log which shows only non internal logs and act log all which lists all activity logs Finally identify which Web Services methods are needed To get lists attached to an object use getRelatedList or getRelatedListValues Out of the Box Handles Some data shipped out of the box is used frequently Instead of looking up handles for these objects some of the commonly used ones are listed in the followin
122. llation is in the ITIL mode Returns A string itil if the installation is in ITIL mode Otherwise an empty string is returned The following parameters apply to the getObjectValues method Parameter Type Description SID Integer Identifies the session retrieved from logging in objectHandle String Identifies the handle of a Service Desk object to query attributes String Identifies the names of attributes to fetch Dotted names are permitted If this field is empty all the object s attributes are returned Web Services Methods 189 Miscellaneous Methods Description This method returns the attribute values of an object The caller passes one or more attribute names to fetch the object and dotted names are permitted All values are returned as a string Empty null attributes are returned as empty strings Returns A lt UDSObject gt element For more information see XML Object Returns XML Element Type Description lt UDSObject gt N A Contains a lt Handle gt element and zero or more lt AttributeNamex gt elements getObjectlypelnformation The following parameters apply to the getObjectTypel nformation method Parameter Type Description SID Integer Identifies the session retrieved from logging in factory String Identifies the object type known as factory to query This is the majic name of the object for example cr Request 190 Web Services User Guide Miscellan
123. log is added to the object to record the notification Identifies the title of the notification message Identifies the body of the notification message Indicates the notification level Specify an integer from 1 Low to 4 Emergency Identifies the array of contact handles to notify Indicates internal only notification Set to True to flag for an internal only notification which guarantees that the message is sent only to those who can view internal logs and the resulting activity log is flagged as internal clearNotification Business Methods Description Sends a notification to one or more contacts This is equivalent to the Manual Notify activity on requests issues and change orders Returns The following is returned XML Element Type Description lt LogHandle gt String Identifies the handle for new activity log The following parameters apply to the clearNotification method Parameter Type Description SID Integer Identifies the session retrieved from logging in IrObject String Identifies the handle to a Notify Log Header Ir object clearBy String Identifies the name of the contact responsible for the clear operation Description Clears a notification message Returns The new status of the notification message Web ServicesMethods 111 Business Methods getPolic yInfo The following parameters apply to the getPolicyl nfo method Parameter Type Description SI
124. logging in Identifies the document ID to rate Identifies the rating to give the document a scale of 0 4 where 0 is the worst and 4 is the best Identifies the persistent ID of a ticket related to this Knowledge document Web ServicesMethods 165 Knowledge Tools Parameter Type Description multiplier Integer Identifies the multiplier parameter This parameter can be used to simulate many ratings at once Use the default of 1 for a single rating and any other number for multiples For example if you submit 3 it acts as if you called the method 3 times Three ratings with the value you supplied in the rating parameter is added to the database onTicketAccept Boolean Identifies whether the document was accepted as a solution for the ticket solveUserProblem Boolean Identifies whether this document solved the user s problem It signifies how the user responded to the question Did this document solve your problem on the Solution Survey isDefault Boolean Indicates a default rating status If you are setting the rating just because the user viewed the document and not because he actually rated it set this to True This is used for reporting reasons Description Rates a particular document Returns A lt UDSObject gt node with the following Attributes children nodes describing the rating BU TRANS XML Element Value Data Type Description id Integer Identifies the unique identifier for the rating most r
125. mark method 169 addComment method 163 adding additional problem types 34 addMemberToGroup method 82 advantages of Web Services and Service Desk 9 Application Event log 17 Asset Management methods 116 attachChangeToRequest method 105 attaching a problem to a change order 47 48 an incident to a problem 47 attachment methods 174 199 attachURLLink method 176 attmntFolderLinkCount method 176 attribute data types 55 attributes for objects 39 LREL 57 SREL 57 authentication public key infrastructure PKI 20 user access 19 user name password 19 authorization and SID 25 BREL keyword 57 Business methods 87 C caching 42 callServerMethod method 184 category field 43 change orders querying for those assigned to a contact 51 changeStatus method 102 clearNotification method 111 closeTicket method 91 common elements 55 common tasks 49 components for Service Desk 11 configuration items 48 configuring for public key infrastructure PKI 22 Web Services 12 contact management methods 67 68 69 70 contact type handles 49 createActivityLog method 103 createAsset method 117 createAssetParentChildRelationship method e 121 createAttachment method 199 createAttmnt method 175 createChangeOrder method 95 createDocument method 153 createFolder method 178 createLrelRelationships method 138 createObject method 186 createQuickTicket
126. method Parameter Type SID Integer assetHandle String attributes String Description Description Identifies the session retrieved from logging in Identifies the asset to query Identifies the standard array of attributes from the asset extension object from which to request values If this value is empty all attributes are returned Returns extension information for an asset If the asset does not have an extension nothing is returned An asset has an extension if a value exists for its family extension name property This property is empty if the asset does not have an extension Web ServicesMethods 119 Asset Management Methods Returns The following elements with empty values if the asset does not have an extension XML Element lt UDSObject gt lt ExtensionHandle gt lt ExtensionName gt addAssetLog Type String String String Description Identifies all the attribute values for the extension For information about the contents of each lt UDSObject gt element see XML Object Returns Identifies the extension s handle Identifies the name for the asset s extension The following parameters apply to the addAssetLog method Parameter SID assetHandle contactHandle logText 120 Web Services User Guide Type Integer String String String Description Identifies the session retrieved from logging in Identifies the asset han
127. method 89 createRequest method 92 createTicket method 75 createWorkFlowTask method 197 creating incidents 46 problems 46 customized objects 39 D database structure for Knowledge Tools 140 defining a problem type 32 an access policy 26 definition of Web Services 9 deleteBookmark method 170 deleteComment method 165 deleteDocument method 161 deleteWorkFlowTask method 199 design time feature 43 Index 203 detachChangeFromRequest method 108 digital certificate about 22 doQuery method 125 doSelect method 122 doSelectKD method 59 147 dot notation 57 duplicate ticket handling 36 resolving 36 enumeration values 55 error codes for Unicenter Service Desk 52 UDS LOCK ERR 41 UDS TIMEOUT ERR 41 errors locking 41 escalate method 100 exceptions SOAPException 17 F factory 39 faq method 142 fault message 17 fields category 43 files majic 39 135 mod 39 135 findContacts method 79 freeListHandles method 128 G general methods 142 getAccessTypeForContact method 72 getAssetExtensionl nformation method 119 getAttmntl nfo method 182 getAttmntList method 181 getAttmntListPerKD method 177 getBookmarks method 168 getBopsid method 188 getCategory method 161 getConfigurationMode method 189 getContact method 73 getDecisionTrees method 150 getDocument method 152 getDocumentsBylI Ds method 151 getDocumentT
128. n The easiest way to cache the object type information is to perform repeated calls to GetObjectTypel nformation The object types to consider for this technique could be one of the following Object Type cr chg iss cnt nr wf iss wf prp prptpl cr prp cr prptpl Definition Request Change Order Issue Contact Asset Workflow Change Orders Workflow Issues Property for Change and Issue Property Template for Change and Issue Request Property Request Property Template Add any additional object types your client code references 42 Web Services User Guide Categories and Properties Categories and Properties The request change order and issue objects all have a category field which is used to classify the nature of the ticket A category may have zero or more property objects which are instantiated and attached to the ticket when the category is assigned Zero or more of these may be marked required which means a value must be supplied before the ticket can be saved and applies to both insert and update operations This enforcement works fine in a GUI environment but is more difficult to deal with programmatically To make things easier the Unicenter Service Desk Web Services automatically supplies default values for any ticket created with the Web Services The default value currently is obtained from Unicenter Service Desk s localized message catalog If you need to set prop
129. n The following shows the sequence that Unicenter Service Desk Web Services uses for locating the proper problem type Ifa specific problem type code is provided as input and it matches a problem type that is associated to the policy this problem type is used regardless of whether it is internal a f a problem type is not specified or the previous step fails to locate a problem type the default problem type is used if there is one defined for the policy fa default problem type is not defined for the policy or the previous step fails the default problem type defined for internal problem types is used Once a problem type is defined Unicenter Service Desk Web Services uses it to create a ticket The proxy user defined in the access policy is used for the ticket creation if the userid is empty and asset information is added to the ticket if the input is not empty Once the ticket is created successfully Unicenter Service Desk Web Services returns both user data and application data as specified by the problem type closeTicket SI D Description TicketHandle Users can call this function to close an open ticket It simply sets the status of an open ticket to close and adds the input description to the activity log Extemal Specifications 37 Simplified Web Services Access logComment SI D TicketHandle Comment Internal Flag Adds an entry with the input comment to the activity log for the open ticket getPolicy
130. n may also be the string representation of a UUID typically 32 characters The following table lists the object and factory names of the entities that use UUIDs Object Name Factory Name Contact cnt Asset nr Organization org Location loc Company Vendor ca cmpny Model mfrmod Handles are persistent a handle representing a particular object is always unique for its lifetime even across database migrations Clients may want to take advantage of this persistence when working with fairly static objects for example Status or Contact Types Object handles are the key to successfully using Service Desk Web Services Many methods especially those that update data require handles Most methods that return object data also include the object s handle 40 Web Services User Guide Lock Enors Lock Errors Unicenter Service Desk 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 Access the Unicenter Service Desk Web Services Time Outs The Unicenter Service Desk Web Services uses the Apache implementation of standards set forth by the W3C Ideally a client on any type of platform should be able to access the services but vendor implementations vary Many programming environments provide
131. nalyst assignee You can use one of several methods such as doQuery to get a list reference or doSelect to get the values immediately Assuming the assignee s handle is already known the where clause to use is as follows assignee id U assigneel D AND active 1 where assigneel D is the id portion of a contact handle value such as 555A043EDDB36D4F97524F2496B35E75 This where clause works for requests change orders and issues because they all have the assignee and active attributes and they mean the same thing for all three object types The active 1 portion of the where clause restricts the search to active requests For more information on the active flags see the next section Most Unicenter Service Desk objects have a field called active or delete flag This is actually an SREL pointer to the Active Boolean Table object or Boolean Table object Consider adding these fields to your queries to filter objects marked as Inactive by the system administrator For querying purposes search for delete flag 0 to find active records and delete flag 1 for inactive records For example the following pseudo code demonstrates using doSelect to retrieve values for all active Request Status objects doSelect SID crs delete flag 0 1 new String 0 To set an object to active or inactive you need to pass the handle of the Boolean object representing either true or false These handle
132. ncident or problem To create a request incident or problem call createRequest and specify the appropriate value for the type attribute The type attribute is a pointer SREL to the crt Call Req Type object so you must pass a handle as the value For more information about possible crt handle values see Out of the Box Handles For example the following pseudo code illustrates how to create a new incident by passing the correct crt object handle to the createRequest method In the following example setting the type attribute in the name value pair that is passed as a parameter to createRequest creates the new incident attrVals summary A new incident description new incident type crt 182 USPSD createRequest SI D creatorHandle attrVals template new String 0 new String 0 Note The type attribute is only used when Unicenter Service Desk is configured for ITIL so it can be ignored if ITIL is not being used 46 Web Services User Guide Note on Using the ITIL Methodology Installation Query for Incidents or Problems To retrieve incidents or problems include the type attribute of the cr object in the where clause The following example illustrates a where clause for retrieving all active Incidents This where clause could be used with methods that perform queries for cr objects such as doSelect and doQuery type id 182 AND active 1 The 182 is the ID portion of the handle representing Inciden
133. ng in objectHandle String Identifies the object handle for an issue or change order attributes String Identifies the sequence of attribute names for which to fetch values Dotted attributes are permitted If this is blank all attributes are fetched Web ServicesMethods 113 Business Methods Description Returns values for all the tasks associated with the specified issue or change order Note This is a convenience method The same list could be obtained using doSelect Returns The following XML Element lt UDSObjectList gt getValidTaskTransitions Type N A Description Outer element contains zero or more lt UDSObject gt elements as described in XML Object Returns Each lt UDSObject gt node represents a Task The nodes are ordered by the Task s sequence attribute For information about the contents of each lt UDSObject gt element see XML Object Returns The following parameters apply to the getValidTaskTransitions method Parameter SID taskHandle 114 Web Services User Guide Type Integer String Description Identifies the session retrieved from logging in Identifies the handle to a Workflow task for an issue or change order Business Methods Parameter Type Description attributes String Identifies the names of attributes to fetch from the tskstat object If this field is empty all value based attributes are returned
134. nly the group with this ID Pass zero 0 when you do not want to use this parameter Web Services Methods 81 Group Management Methods Description Retrieves the list of Permission Groups Returns A lt UDSObject gt node with zero or more lt UDSObject gt nodes describing Permission Group with the following Attributes child nodes XML Element Value id GRP LIST KEY GRP LIST Group Management Methods Type Integer String String Description Identifies the unique ID of the group Shows a list of the IDs of Service Desk groups separated by commas Displays a field containing the entire group list This section explains the Web Services Group Management Methods addMemberToGroup The following parameters apply to the addMemberToGroup method Parameter SID ContactHandle GroupHandle 82 Web ServicesUser Guide Type Integer String String Description Identifies the session retrieved from logging in Identifies the handle of the contact to add as a member Identifies the group to which you will add the contact Group Management Methods Description Adds a contact to a group Nothing happens if the contact is already a member Returns Nothing removeMemberfromGroup The following parameters apply to the remove MemberFromGroup method Parameter Type Description SID Integer Identifies the session retrieved from logging in ContactHandle String
135. nt see the chapter External Specifications Authentication with username password methods may be disabled using the following security configuration command disable user logon Before enabling this option the administrator needs to determine if each web service client for which an enterprise is requesting Web Services access can actually provide support for the alternative authentication method which is the PKI based login method The key advantage to the PKI technology is that Web Services client applications do not require maintained system user accounts that is the maintenance storage and transmission of their passwords Networking Level Security Configuration In both authentication schemes username password and Public Key Infrastructure PKI notice that the session identifier returned from the specific login method as well as all subsequent information are transmitted in plain text when using HTTP Furthermore if the username password authentication scheme is used the password is sent unprotected in plain text from the web service client application to the Web Services During product development the W3C did not have recommended standards for web services security Subsequently WS Security is not used by these Web Services implementations to provide a security context Instead point to point transport layer security SSL TLS and other network level security mechanisms for example IPSec are recommended to prote
136. nteger Identifies the unique ID of the status STATUS String Identifies the name for the status STATUS DESCRIPTION String Identifies the description for the status PREDEFINED Integer Indicates whether the status is predefined by the Knowledge Tools system meaning that it cannot be deleted STATUS ORDER Integer Describes the order by which the status should appear in the Workflow task list Workflows can only be created when they follow this order The following parameter applies to the getPriorities method Parameter Type Description SID String Identifies the session retrieved from logging in Description Retrieves the list of priorities Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing Cl_ PRIORITIES with the following lt Attributes gt child nodes XML Element Values Data Type Description id Integer Identifies the unique ID of the priority Web Services Methods 171 Knowledge Tools getDocumentlypes getlemplateList XML Element Values Data Type Description PRIORITY String Identifies the name for the priority The following parameter applies to the getDocumentTypes method Parameter Type Description SID String Identifies the session retrieved from logging in Description Retrieves the list of document types Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing CI DOC TYPES with the following lt Attributes gt
137. o attribute name such as actlog then the entire lt UDSObject gt is returned in the List section Unicenter Service Desk Web Services 45 Note on Using the ITIL Methodology Installation 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 since the Contact REL ATTR foreign key is its ID For Unicenter Service Desk r11 the return data for attributes includes elements for the DBMS and common name value of SREL references Note on Using the ITIL Methodology Installation The Web Services fully supports the ITIL methodology if the Unicenter Service Desk installation is configured to support the ITIL The Web Services API uses terminology inherent to the out of the box product but you only need to follow the simple guidelines in the following sections to take advantage of Unicenter Service Desk s ITIL features For more information about ITIL methodology see the Unicenter Service Desk ITIL User Guide Create an Incident or Problem When Unicenter Service Desk is configured to use the ITIL methodology Incidents and Problems can easily be created using the Unicenter Service Desk Web Services Both Incidents and Problems are held in the cr Call Req object One of these attributes named type distinguishes the record as a request i
138. obably faster to request the data all at once instead of requesting a list reference querying it for data and then releasing the list Examples of methods that return data sets instead of list references include the following m doSelect m getRelatedListValues getlrelValues m getTaskListValues m getValidTaskTransitions As previously stated queries that return a large number of rows can severely impact the performance of the server To protect against this Unicenter Service Desk limits the number of rows returned to 250 This affects all Unicenter Service Desk Web Services methods that return lists of objects including the following doSelect doSelectKD getGroupMemberListValues m getListValues wm getPropertyl nfoForCategory m getRelatedListValues m getTaskListValues getValidTaskTransitions This limit applies even if you request one of these methods to retrieve more than 250 rows 60 Web Services User Guide Lists To retrieve large numbers of rows you should obtain a handle to the list of results and use getListValues to retrieve chunks of 250 or fewer rows each This strategy helps keep the server from becoming slow while serving huge amounts of data Common Elements 61 Where Clauses Where Clauses Several Web Services methods such as doSelect and doQuery require where clauses for searching A where clause is the string appearing after the WHERE
139. on Description Indicates an option available for sorting the results in descending order Retrieves historical Knowledge document search text Returns A lt UDSObjectList gt node with zero or more UDSObject nodes describing EBR LOG with the following Attributes child nodes XML Element Value Data Type id Integer SEARCH TEXT Integer Description Indicates the unique identifier of the question asked Indicates the search text of the question asked The following parameters apply to the getBookmarks method Parameter Type SID String contactl d String 168 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the unique ID of the contact for which you want to retrieve bookmarks Contact ID is UUID in string format addBookmark Description Knowledge Tools Retrieves bookmarks for a particular contact Returns A lt UDSObjectList gt node with zero or more lt UDSObject gt nodes describing CI BOOKMARKS with the following Attributes child nodes XML Element Name Type DOCUMENT ID Integer id Integer USER ID String BOOKMARK TITLE String Description Identifies the unique ID of the document Identifies the bookmark ID Identifies the user ID for the owner of this bookmark Identifies the bookmark title from the document The following parameters apply to the addBookmark method Parameter Type SID Integer contactld String docl
140. or more lt ParamxX gt elements for return values Indicates zero or more for the return values where x is an integer starting at zero and increments for each return element The following parameters apply to the createObject method Parameter Type SID Integer ObjectType String attrVals String attributes String 186 Web Services User Guide Description Identifies the session retrieved from logging in Identifies the type of object to create the majic factory name Identifies a sequence of name value pairs used to set the initial attribute values for the new issue Dotted names are not permitted 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 Miscellaneous Methods Description Creates a Service Desk 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 new contact and return a lt UDSObject gt 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 emptyA
141. ou do not need to activate the secondary object server or web engine For detailed information see the online help for Service Desk configuration 18 Web Services User Guide Chapter 2 Extemal Specific ations This chapter describes what you need to know for specifying user access authentication and the features available by access control and management User Access Authentication Unicenter Service Desk Web Services provides two access authentication schemes They are associated with the new access control and management feature which uses an access policy For more information about creating and defining an access policy see Defining an Access Policy User Name Password Verifies the User Name Password as described in previous releases of the product Public Key I nfrastructure PKI Technology Verifies that the person requesting the access has ownership of a certain private key Important f you plan to use an application that accesses this version of Unicenter Web Services for Service Desk we strongly recommend that you first define a Web Service Access Policy complete with its code value in Service Desk A default access policy with a policy code of DEFAULT is available when Service Desk is installed and configured User Name Password Authentic ation If you plan to use the User Name Password type of access authentication the user application needs to invoke one of following two web services methods to gain ac
142. oveLrelRelationships The following parameters apply to the removeLrelRelationships method Parameter Type Description SID Integer Identifies the session retrieved from logging in contextObject String Identifies the object on one side of the LREL LrelName String Identifies the Lrel Name as seen by contextObject removeObjectHandles String Identifies the handles of objects to remove from the other side of the LREL relationships Description Removes one or more many to many relationships contextObject is one side of the LREL relationship The caller passes one or more object handles for the other side It is not an error if no relationship existed between the two objects If an invalid object handle is passed the entire operation is canceled For a usage example see createLrelRelationships in this chapter Returns Nothing Knowledge Tools To use the Web Services Knowledge Tools it is helpful if you are familiar with the database structure 140 Web Services User Guide Table Types Knowledge Tools Some of the more important tables are described as follows Table Type skeleton o indexes Description Stores all information pertaining to documents with each row representing one document Field names from this table can be used when passing the PropertyList and SortBy parameters to methods such as FAQ and Search The field names are case sensitive so make sure you pass them just as they a
143. pe Description SID Integer Identifies the SID of the current login session attrVals String Identifies an array of name value pairs that are used to set the initial attribute values for this workflow task These optional attributes include Asset a Assignee a Estimated duration m Estimated cost m Estimated completion date objectHandle String Identifies the object handle of a change order or issue for which this workflow task is created or attached creatorHandle String Identifies the object handle of the contact that created this workflow task Web ServicesMethods 197 WorkFlow Methods Parameter Type Description selectedWorkFlow String Identifies the object handle of an existing workflow task after which the new workflow task is to be inserted taskType String Identifies the object handle of a workflow task template or the code of a task type Description Verifies the input value of selectedWorkFlow If it is empty the new workflow task is inserted at the bottom Otherwise the new workflow task is created after the selectedWorkFlow The input value of taskType is also verified to determine whether to create a workflow based on a workflow template or on a task type code Returns The new workflow task s handle along with all of its attribute values List and LREL types are also returned but as empty elements For more information about the return format see XML Object Returns XML El
144. peForC ontact The following parameters apply to the getAccessTypeForContact method Parameter Type Description SID Integer Identifies the session retrieved from logging in ContactHandle String Identifies the contact handle upon which to query 72 Web ServicesUser Guide getContact Contact Management Methods Description Returns a handle for the Access Type for a Contact Every Contact is assigned an Access Type object which defines a Contact s permissions and security Note the access type field on a Contact is not required To accommodate this a single Access Type is marked as the default for Contacts who do not have an object specifically assigned This method returns the Access Type directly assigned to a Contact that is the information to which the access type field points in the Contact record or it returns the default Typical value methods such as getObjectValues or getListValues may not return the correct Access type therefore these are not the accurate methods for retrieving the Contact s Access Returns A string handle for an Access Type object The following parameter applies to the getContact method Parameter Type Description SID String Identifies the session retrieved from logging in contactld String Identifies the unique ID of the contact to retrieve contactld is UUID in string format Web Services Methods 73 Contact Management Methods Description Retrieves information on
145. ply to the closeTicket method Parameter Type SID Integer description String ticketHandle String Description Description Identifies the session retrieved from logging in Optional Identifies the description of the ticket which can be used in the Close activity log Identifies the ticket to close Sets the status of the ticket to Closed and adds an activity log with the input description Returns The handle to the activity log object created It provides the same return as the changeStatus method XML Element Type lt LogHandle gt String Description Specifies the handle for new activity log 0 or more of these can be returned Web Services Methods 91 Business Methods createRequest The following parameters apply to the createRequest method Parameter SID Type Integer Description Identifies the session retrieved from logging in creatorHandle attrVals template propertyValues attributes 92 Web Services User Guide String String String String 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 Service Desk user Identifies an array of name value pairs that is used to set the initial attribute values for the new request Optional Identifies the handle of the request template cr_tpl from which to create the new reques
146. proxy user of the policy used in the current web services session If the access level of the new user s access type is less than or equal to the grant level of the proxy user s access type this method will replace the current user with the new user A new web services session starts while the old session ends A new SID is then returned In addition the new user is given the responsibility for all subsequent activities initiated in this new session The function group security and data partition are enforced for the new user Returns The following is returned Parameter Type Description SID Integer Identifies the unique SID to use for all other Web Services calls The following parameter applies to the logout method Parameter Type Description SID Integer Identifies the session retrieved from logging in Description Invalidates a SID obtained from login loginService and loginServiceManaged Returns Nothing Web Services Methods 71 Contact Management Methods getHandleForUserid The following parameters apply to the getHandleForUserid method Parameter Type Description SID Integer Identifies the session retrieved from logging in userl D String Identifies the user ID upon which to query Description Returns the persistent handle for a Contact represented by userlD Returns The following is returned Parameter Type Description Handle String Identifies the contact s handle getAccessly
147. ptions Manager and is specified by the following Service Desk Option webservice session ti meout If this value is set to zero 0 a SID never times out If this option is missing or not set the default is one hour If a Web Service method is called with an expired SID a Fault is returned with an error code of UDS SESSION TIMEOUT the first time it is referenced and UDS BAD SESSION each time thereafter To keep a SID active call any web service method before the time out is reached To keep the SID active without working the server call serverStatus Extemal Specifications 25 Access Control and Management Access Control and Management To minimize the potential problem of web services ticket flooding and to maintain the stability of the Service Desk server this version of Unicenter Service Desk Web Services uses an Access Control and Management system It works primarily to handle the excessive service activities initiated by trusted user applications that can result from programming errors or exceptions It also works as a barrier for controlling access to Unicenter Service Desk Web Services from malicious attackers An administrator of a web service application is able to create and define an access policy in Unicenter Service Desk that controls access to Unicenter Service Desk Web Services from a web service application Note A default access policy is provided out of the box and has a code of DEFAULT The default ac
148. quent web services method invocations Proxy contact specified in the policy is responsible for all subsequent web service activities initiated All function group security and data partition are enforced for the proxy contact defined in the policy It is also important to note that the encrypted policy parameter is in the BASE64 text format and it is necessary to perform proper conversion from the binary format The SID should be freed with logout A SID may expire if it is not used before a timeout elapses Returns The following is returned Parameter Type Description SID String Identifies the unique session ID SID to use for all other Web Services calls It is in plain text format The following parameters apply to the impersonate method Parameter Type Description SID Integer Identifies the session retrieved from logging in username String Required Identifies the user name of the user being impersonated 70 Web Services User Guide logout Contact Management Methods Description Lets an administrator switch the user responsible for all web services activities in a current web services session without additional user authentication Invoking this method is allowed only if the current web services session is started by using the PKI access authentication scheme and the access policy is defined to allow impersonation The Access Type of the user to be impersonated is checked against the Access Type of the
149. r docld Integer URL String attmntName String Description String Description Description Identifies the session retrieved from logging in Identifies the unique ID of the Knowledge document Indicates the URL to attach to the Knowledge document Identifies the name of the attachment Indicates the description of the attachment Attaches a URL link to a Knowledge document Returns Returns error codes only for individual errors For additional information see Error Codes 176 Web Services User Guide getKDListPerAttmnt getAtimntlistPerKD Knowledge Tools The following parameters apply to the getKDListPerAttmnt method Parameter Type Description SID Integer Identifies the session retrieved from logging in attmntl d Integer Identifies the unique ID of the attachment Description Returns a list of Knowledge documents with reference to a given attachment Returns A lt UDSObject gt node with zero or more lt UDSObject gt nodes describing the Knowledge document with the following Attributes child nodes XML Element Value Type Description id Integer Identifies the unique ID of the Knowledge document The following parameters apply to the getAttmntListPerKD method Parameter Type Description SID Integer Identifies the session retrieved from logging in docl d Integer Identifies the unique ID of the Knowledge document Web ServicesMethods 177 Knowledge Tools isAttmntLinkedKD
150. re in the database Stores all information pertaining to categories with each row representing one category Web ServicesMethods 141 Knowledge Tools Knowledge Tools General Methods This section describes Knowledge Tools general methods Valid Knowledge document sorting properties when available are as follows m RELEVANCE AUTHOR ID BU RESULT CREATION DATE m DOC TYPE ID EXPIRATION DATE m HITS m id MODIFY DATE OWNER ID PRIORITY ID m ACCEPTED HITS ASSET ID m SD ASSET ID ASSIGNEE ID PRODUCT ID START DATE STATUS ID SUBJECT EXPERT ID faq The following parameters apply to the faq method Parameter Type Description SID Integer Identifies the session retrieved from logging in categorylID String Identifies the category ID used to perform the faq Use 1 for the Root category Note Multiple ids are supported for example 1 2 3 142 Web Services User Guide Parameter resultSize propertyList sortBy descending whereClause maxDoclds Type Integer String String Boolean String Integer Knowledge Tools Description Identifies the number of documents for which you want to retrieve detailed information For the rest of the documents only their IDs return Detailed information for these documents can be accessed later using the getDocumentsByIDs method The default is 10 Identifies the comma separated list of database fields from whic
151. responsible for the activity Identifies the handle for a request issue or change order Any other object type is rejected Identifies the description for the activity which will appear in the activity log Optional Identifies the handle of the new status for the object Identifies the handle of the status for the object createActivityLog Description Business Methods 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 Service Desk interface Returns The handle to the activity log object created XML Element lt LogHandle gt Type String Description Identifies the handle for the new activity log zero or more of these can be returned The following parameters apply to the createActivityLog method Parameter SID creator objectHandle description Type Integer String String String Description Identifies the session retrieved from logging in Identifies the handle of the contact responsible for the activity Identifies the handle for a request issue or change order Any other object type is rejected Identifies the description for the activity which will appear in the activity log Web Services Methods 103 Business Methods Parameter Type Description LogType String Identifies
152. rray int err CreateObject sid cnt attrVals emptyArray Note Do not use this method for new assets issues requests or change orders Use the specialized createXXX methods for those object types This also applies if you are using the ITIL methodology use the appropriate methods to create Configuration Items Incidents and Problems Returns A lt UDSObject gt element containing the new object s 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 lt UDSObject gt N A Identifies the standard UDSObject element containing the handle and requested attribute values lt newHandle gt String Identifies the new object s handle Web Services Methods 187 Miscellaneous Methods getBopsid The following parameters apply to the getBopsid method Parameter Type Description SID Integer Identifies the SID of the current login session Name String Identifies the name of the user associated with the returned bopsid Note This is the system login name not the Service Desk contact name Description Facilitate the building of Web interface URLs which may be used to launch the web interface in the context of a given user without a login challenge To launch the web interface in the context of a given user for example an
153. s LREL Methods The following parameters apply to the getLrelValues method Parameter SID contextObj ect LrelName startl ndex endindex attributes Type Integer String String Integer Integer String Description Identifies the session retrieved from logging in Identifies the object on one side of the LREL Identifies the Lrel Name Use the name Identifies the position in the list from which to begin fetching Identifies the Last list position from which to fetch Specify 1 to fetch all rows from startl ndex Identifies an array of one or more attribute names for which to fetch values Web Services Methods 137 LREL Methods Description Returns attribute values for a range of objects in an LREL relationship Remember that items involved in an LREL relationship have no specific ordering In fact it is not really a list as defined in this document The start and end index parameters are there to help throttle a large number of items The format is as follows lt UDSObj ectList gt lt UDSObj ect gt Handl e lt Attri but eName0 gt lt Attri but eNamel gt Returns The following XML Element Type lt UDSObjectList gt Array lt UDSObject gt Sequence createLrelRelationships Description Specifies the outer element which contains a sequence of lt UDSObject gt elements Contains a lt Handle gt element and zero or more
154. s 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 Service Desk 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 Note Organization is not used for Requests Returns One or more handles to the activity log objects created XML Element Type Description lt LogHandle gt String Identifies the handle for the new activity log zero or more of these can be returned Web Services Methods 101 Business Methods changeStatus The following parameters apply to the changeStatus method Parameter SID creator objectHandle description setStatus newStatusHandle 102 Web Services User Guide Type Integer String String String String String Description Identifies the session retrieved from logging in Identifies the handle of the contact
155. s do not change So you can safely hard code them These are listed as follows Active Boolean Table Boolean Table actbool 4551 Active bool 200 False actbool 4552 Inactive bool 201 True Unicenter Service Desk Web Services 51 Use the Web Services Retrieve Related List Length When requesting attribute values from an object such as with getObjectValues you can get the length of a related list by requesting the following attribute lt listName gt length For example to get the number of Activity Logs for a certain request pass the following to getObjectValues act log all length Note This is the only way you can use list names in these types of methods Eror Codes The following table lists the possible values for the lt ErrorCode gt 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 52 Web ServicesUser Guide Error Name UDS LOCK ERR UDS UPDATE ERR UDS CREATION ERR UDS NOT FOUND UDS SESSION TIMEOUT UDS SERVER GONE Value 1002 1003 1004
156. snr This declares a many to many relationship between the Issue iss and Asset nr tables An issue sees the collection of related assets as a pseudo list called asset while an asset is related to issues as issnr To discover how many assets are related to a particular issue call getLrelLength with the following parameters getLrelLength sid ssueHandle asset where sid is a SID obtained with login and IssueHandle is the string handle to a particular issue object Similarly the following pseudo code describes how to get the names of all the assets related to an issue String attrs name getLrelValues sid lssueHandle asset 0 1 attrs Web Services Methods 135 LREL Methods getlrelLength The following parameters apply to the getLrelLength method Parameter Type Description SID Integer Identifies the session retrieved from logging in contextObj ect String Identifies the object on one side of the LREL LrelName String Identifies the LrelName Use the name Description Returns the number of objects on one side of a many to many relationship contextObject Specifies it as a handle to an object on one side of the LREL relationship LrelName Specifies it as the name of the side of the relationship identified by ObjHandle Returns The following XML Element Type Description Length Integer Specifies the number of objects 136 Web Services User Guide getirelValue
157. string format ment A lt UDSObject gt node with the following lt Attributes gt child nodes describing the comment most recently added XML Element Value Data Description Type id Integer Identifies the unique identifier for the comment most recently added DOC ID Integer Identifies the document ID for the comment most recently added USER ID Integer Identifies the ID of the person who submitted the comment USER NAME String Identifies the user name of the 164 Web Services User Guide person who submitted the comment Knowledge Tools deleteC omment rateDoc ument XML Element Value Data Type EMAIL ADDRESS String COMMENT TEXT String COMMENT TIMESTAMP Date Description Identifies the email address of the person who submitted the comment Identifies the text for the comment recently added Identifies the date and time the comment was added The following parameters apply to the deleteComment method Parameter Type SID Integer commenti d Integer Description Deletes a comment Returns Description Identifies the session retrieved from logging in Identifies the unique ID for the comment you want to delete Returns error codes only for individual errors For additional information see Error Codes The following parameters apply to the rateDocument method Parameter Type SID Integer docld Integer rating Integer ticketPersld String Description Identifies the session retrieved from
158. t Optional Identifies the array of values for any properties that are attached to the new request 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 Business Methods Description Creates a Service Desk Request cr object You must use this function to create a new 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 Service Desk 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 getPropertyl nfoForCategory 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
159. t Identifies the unique assignee ID from Unicenter Service Desk to which this document is assigned Identifies the asset ID from Unicenter Service Desk with which to associate this document Identifies the root cause ID from Unicenter Service Desk with which to associate this document Identifies the priority ID from Unicenter Service Desk with which to associate this document Identifies the severity ID from Unicenter Service Desk with which to associate this document Identifies the impact ID from Unicenter Service Desk with which to associate this document Identifies the urgency ID from Unicenter Service Desk with which to associate this document Identifies the unique ID of the contact who authored this document If the author is not an internal contact you can set this field to zero and use the Author parameter instead Web ServicesMethods 155 Attribute Value OWNER ID SUBJECT EXPERT ID NOTES READ GROUP LIST WRITE GROUP LIST INHERITPERMISSI ONS DOC TYPE ID HITS DOC TEMPLATE ID WF TEMPLATE CUSTOM1 156 Web Services User Guide Type UUID UUID String String String Boolean Integer Integer Integer Integer String Knowledge Tools Description Identifies the unique ID of the contact who owns this document Identifies the unique ID of the contact who is the subject expert for this document Identifies the notes for the document Identifies th
160. t the corresponding operation is not allowed 4 Click Save to save the access policy 28 Web ServicesUser Guide AccessControl and Management Web Services Methods by Categories Each Unicenter Service Desk Web Services method belongs to a specific category The following lists each category and their corresponding methods Ticket Creation createTicket createQuickTicket createRequest createChangeOrder createl ssue Object Creation logComment createAsset addAssetLog createAssetParentChildRelationship createObject createWorkFlowTask createActivityLog notifyContacts addBookmark addComment createFolder Object Updates addMemberToGroup removeMemberFromGroup closeTicket createLrelRelationships remove LrelRelationships deleteWorkFlowTask updateObject transfer escalate attachChangeToRequest detachChangeFromRequest Extemal Specifications 29 Access Control and Management changeStatus a ClearNotification updateLrel a deleteBookmark updateRating Attachments createAttmnt a createAttachment a attachURLLink a deleteAttmnt deleteComment removeAttachment Data Queries impersonate ServerStatus getBopsid getConfigurationMode a getHandleForUserid a QetAccessTypeForContact m getPermissionsGroup getObjectTypel nformation QetRelatedList getRelate
161. t types for more information see the crt Call Req Type objects table illustrated in Out of the Box Handles For more information about forming proper queries see Where Clauses Attach an Incidentto a Problem The Web Services can create associations between ITIL tickets such as associating one or more Incidents to a Problem The parent attribute on a ticket is used to create parent child relationships between the cr objects which are used for request incident and problem objects Setting the parent attribute of a ticket to point to another ticket creates the relationship For example a newly created incident relates to an existing problem To associate the incident to the problem use UpdateObject to set the incident s parent attribute to point to the problem The following pseudo code example illustrates this by setting the parent attribute to the handle of an existing problem ticket attributeValues parent cr 12346 USPSD UpdateObj ect SID incidentHandle attributeValues new String 0 Attach a Problem to a Change Order Incidents and problems can be linked to change orders with the attachChangeToRequest method The following pseudo code example uses this method to simultaneously create a new change order and attach it to a problem In the example cr 12347 is the object handle of the problem it passes a blank handle for the fourth parameter which causes the method to create a new change UPSPSD attachChange
162. text format and saves it with the access policy specified by the policy code When a digital certificate is generated by the pdm pki utility the administrator invokes the command in Service Desk without the 1 option The utility then generates a public and private key pair keys are RSA1024 bit keys The public key is converted to BASE64 text format where it is stored along with the access policy specified by the policy code An X509 V3 certificate is also created to hold the public key along with other information the default pass phase is set as the policy code Finally the X509 V3 certificate is packaged with the private key to a standard portable certificate format of PKCS12 It is then saved in a file with a file name of policy code p12 depending on the policy code supplied This file can then be exported to clients Note If an access policy has already been associated with a public key of a certificate users need to specify the f option when calling the pdm pki command in order to overwrite the existing public key with a new public key Public Key Infra structure PKI Authentication Login to Web Services The following describes the process flow for logging in to Unicenter Web Services configured with PKI authentication Process Load the Digital Certificate and Extract the Private Key Create a Digital Signature of the Plain Text Policy Code with the Private Key Description The digital certificate must be store
163. 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 Note on Using the ITIL Methodology Installation Returns Returns the new object s handle with all of its attribute values List and LREL types are also returned but as empty elements For more information about the return format see XML Object Returns XML Element Type Description lt UDSObject gt N A Identifies the standard UDSObject element containing the handle and requested attribute values lt NewRequestHandle gt String Identifies the new request s handle lt NewRequestNumber gt String Identifies the new request s number its ref num attribute 94 Web Services User Guide createChangeOrder Business Methods The following parameters apply to the createChangeOrder method Parameter Type SID Integer CreatorHandle String attrVals String template String Description Identifies the session retrieved from logging in 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 Service Desk user Identifies an array of name value pairs that is used to set the initial attribute values for the change order Optional Identifies the handle of the change template chg tpl object from which to create the new issue Web Services Methods 95
164. thods loginService Description Login validates a user with Service Desk login validation and returns a unique session ID that is required for most other web method calls This key should be freed with logout A SID may expire if it is not used before a time out elapses The username password is validated exactly the same as the Service Desk Web client the contact s Access Type specifies the validation method The default access policy will be applied to control and manage all subsequent accesses after a successful call of this function The login user not proxy contact specified in the default policy is then responsible for subsequent web service activities All function group security and data partition are enforced for the login user Returns The following is returned Parameter Type Description SID Integer Identifies the unique SID to use for all other Web Services calls The following parameters apply to the loginService method Parameter Type Description username String Identifies the user ID password String Identifies the password policy String Required Identifies the policy code which must be in plain text Although it is required it may be empty 68 Web Services User Guide Contact Management Methods Description Lets users log in with a conventional username password authentication scheme where if valid the system returns a unique session ID This key should be freed with logout A SI
165. tifies the new assignee for the object setGroup Boolean Updates the group field if true newGroupHandle String Identifies the new group for the object 98 Web Services User Guide Business Methods Parameter Type Description 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 Service Desk 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 lt LogHandle gt String Identifies the handle for the new activity log zero or mor
166. to create the ticket Optional Identifies the description of the ticket Web Services Methods 89 Business Methods Description Creates a ticket based on the preferred document type of the user represented by customerHandle Every contact s access rights are determined by an Access Type record which also sets the contact s preferred document type Request Incident Problem Issue or Change Order If a contact s document type is Issue this method will create an Issue if the document type is Request a Request is created and so on The contact represented by customerHandle is used to set the end user customer field of the new ticket The ticket s description is set to the input description value Returns Returns the new ticket s handle ticket number and a brief representation of the new ticket in lt UDSObject gt format XML Element Type Description UDSObject N A Returns a partial set of attributes because it is a high level method designed to simplify the process Their values come from the following methods and the XML element is returned so it is consistent with the returns of these methods a createRequest createChange a createlssue NewTicketHandle String Identifies the new ticket s handle NewTicketNumber String Identifies the new ticket s number its ref num or chg ref num attribute 90 Web Services User Guide closeTic ket Business Methods The following parameters ap
167. try of the contact Integer Indicates whether the contact is active O Active 1 I nactive The following parameters apply to the createTicket method Parameter SID Description Type Description Integer Identifies the session retrieved from logging in String Optional Identifies the description of the ticket Web Services Methods 75 Contact Management Methods Parameter Type Description problem type String Specifies the code not the persistent ID for an existing problem type for the policy under which a Web Services application is running If this is blank or contains a bad value the default problem type is used Userid String Optional Specifies the user ID of the end user for the new ticket If this is blank or the supplied user ID is not found the proxy contact defined in the access policy is used and the ticket is still created Asset String Optional Identifies the handle of an asset to be attached to the ticket 76 Web Services User Guide Parameter Duplicationl D Type String Contact Management Methods Description Optional Allows callers to assist the duplication handling routines used for classifying tickets as being unique or different If duplicate handling is on this string is inspected after other duplicate handling criteria match to determine whether this is a unique or duplicate call to this method For more information about Duplicate Tick
168. turned Once a SID is generated it establishes a successful binding between a Web Service session and an access policy The user application can invoke other web services methods with this SID and all of its access to Unicenter Web Services becomes controlled and managed by this access policy 24 Web Services User Guide Session and Authorization Session and Authorization A successful validation returns a SID that is associated with the validated username whether it is the user name supplied for login or the proxy contact specified in a policy Because of this process each Service Desk user is assigned security rights that you may want enforced in your web service application For example a specific user may have a Data Partition restricting which Requests the user can view When using a SID for the user to get Request information the Service Desk system ensures the data partition is enforced Function Group security is also applied For example a user may not have access to the Call Manager function group Invoking any web services methods such as viewing or creating Requests is denied because access is denied to the Call Manager function group When your application is finished doing work for a user call the Logout method to invalidate the SID Each SID expires after a period of inactivity That is a SID expires if the interval between method calls is greater than a certain timeout value The timeout interval is set in O
169. urned For more information about how to configure SSL see the J 2EE Servlet Container documentation Emor Handling Enor 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 lt Detail gt element The Detail element contains lt ErrorCode gt and lt ErrorMessage gt elements The lt ErrorCode gt element returns an enumerated error code specific to either the Unicenter Service Desk or Unicenter Knowledge Tools product The lt ErrorMessage gt contains an English string describing the errors The lt ErrorMessage gt 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 Unicenter Service Desk s getObjectValues method soap Fault gt lt faultcode gt soap Client lt faultcode gt lt faultstring gt Error on fetch with attribute list persistent id first name last nameParamErrorHere faultstri ng detail Error Code 1001 ErrorCode ErrorMessage Error on fetch with attribute list persistent id first name last nameParamErrorHere lt ErrorMessage gt detail soap Fault If you are using a client built with Microsoft NET managed
170. words Administrators deploying web services are highly encouraged to review this section carefully and to take additional configuration steps at the application and network levels in order to secure their web service environment Important The default web service configuration used with HTTP is insecure and vulnerable to security threats which can include password discovery session fixation and data spying among others There are three interrelated key security considerations in deploying Web Services What application level access authentication schemes should this deployment support What additional networking level security features does this deployment require How will these requirements be enforced through web service configuration options 14 Web Services User Guide Security The following describes each security feature Web Service Application Level Authentication Schemes To access Web Services a web service client application must be authenticated with the web service application Web Services provides two schemes of access authentication The first is by username password and the other is by Public Key Infrastructure PKI technology Both work closely with the Access Control and Management component in Web Services using access policy Access authentication and access management are the most important security features of Web Services For more information about access authentication and access manageme
171. ypes method 172 getFolderl nfo method 180 getFolderList method 179 204 Web ServicesUser Guide getGroupMemberListValues method 84 getHandleForUserid method 72 getKDListPerAttmnt method 177 getListValues method 126 getLrelLength method 136 getLrelValues method 137 getNotificationsForContact method 133 getObjectTypel nformation method 190 getObjectValues method 189 getPendingChangeTaskListForContact method e 132 getPendinglssueTaskListForContact method 132 getPermissionGroups method 81 getPolicyl nfo method 112 getPriorities method 171 getPropertyl nfoForCategory method 97 getQuestionsAsked method 167 getRelatedList method 129 getRelatedListValues method 130 getRepositoryl nfo method 183 getStatuses method 170 getTaskListValues method 113 getTemplateList method 173 getValidTaskTransitions method 114 getWorkflowTemplateList method 173 getWorkflowTemplates method 195 group management methods 82 group relationships 135 H handles for objects 39 out of the box 49 HTTP protocol 14 impersonate method 70 IN clause 64 incidents how to attach to a problem 47 how to create 46 querying for 47 information caching for object factories 42 installing ITIL Methodology 46 Web Services 18 isAttmntLinkedKD method 178 issues querying for those assigned to a contact 51 ITIL Methodology installation 46 K keywords BREL 57 LREL methods 135 Q

Unicenter Service Desk Web Services User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents