CSM Web Services & API

Transcription

1 CSM Web Services & API Release: 5.0 Revision October All Rights Reserved. Innovative Technology Built on Timeless Values

2 Copyright Cherwell Service Management and the Cherwell logo are trademarks or registered trademarks of Cherwell Software, LLC, in the U.S. and may be registered or pending registration in other countries. ITIL is a registered trademark of the Office of Government Commerce in the United Kingdom and other countries. All other trademarks, trade names, service marks and logos referenced herein are the property of their respective owners. The information contained in this documentation is proprietary and confidential. Your use of this information and Cherwell Service Management is subject to the terms and conditions of the applicable End-User License Agreement and/or Nondisclosure Agreement and the proprietary and restricted rights notices included therein. All Rights Reserved. Cherwell Software, LLC [email protected] Oracle Blvd., Suite 200 Colorado Springs, CO USA Revision History Revision Date Comments Author October 2014 First draft. Mark Clayton CSM Web Services & API ii

3 Contents Introduction... 1 Cherwell Web Service... 1 Overview... 1 Tutorials... 3 Introduction... 3 Login to Cherwell... 3 Create a Record in Cherwell... 4 Find a Record in Cherwell... 5 Further Information... 5 Methods Explained... 6 Shape of a Business Object HTTP Request & Response Considerations Trebuchet API Overview Using the API Tutorials Introduction Login to Cherwell Create a Record in Cherwell Find a Record in Cherwell Further Information One-Step: Call a Web Service Overview Tutorials Introduction Call a REST Service Call a WSDL Service About Cherwell Software Contact Information CSM Web Services & API iii

4 Introduction Cherwell Service Management (CSM) provides two API integration options used for communicating to CSM from an external source or application. CSM Also provides the ability to call out to an external web service through the One-Step actions functionality. This is for CSM to communicate with a third party, whereas the other two options are for a third party to communicate with CSM: The Cherwell Web Service is essentially an API, but to avoid confusion we will refer to it simply as CWS. CWS is a.net web service used for communicating with CSM using SOAP over HTTP. CWS provides programmatic access to a subset of CSM functionality. The Trebuchet API, which we will refer to simply as API, is a set of.net assemblies that encompass the entire functionality of the CSM platform. The CSM One-Step: Call a Web Service Action allows you to communicate with a third party from within the CSM application. This communication could be to GET information for form population, or to POST data somewhere else. Cherwell Web Service Overview Cherwell Web Service (CWS) provides designated functionality, by utilizing methods from the API suite. CWS was designed to expose particular methods, or combinations of methods to provide a single purposeful action, which can easily be called from a third party application. CWS is installed by the Portal and Browser Apps installation, and is installed in a virtual directory under IIS called CherwellService. Web services are self-documenting, therefore navigating to the URL: will provide a list of all of the available methods and their arguments. This page should look like the screenshot below: CSM Web Services & API 1

5 Clicking any of the available methods will provide the parameters required to perform that operation. Most methods cannot be called directly through this interface. To put CWS into context, we stated earlier that it provides designated functionality, utilizing methods in the API suite. The API suite is a complete collection of classes and methods that make up the entire Cherwell Service Management platform (CSM); therefore everything you see within the UI and functionality of CSM is available within the API. For example, the CreateBusinessObject method in CWS is actually made up of several API methods in a particular sequence. In a pseudo example, this method takes the following steps within the API: 1. On call, it takes the parameters: "busobnameorid" (This could be "Incident" or the RecID of the Incident Business Object), and "creationxml" (The XML of the object to be created). 2. Makes a call to obtain the definition structure of the provided Business Object. This is for it to map the fields provided within the XML to the fields defined within the definition. 3. Makes a call to create a new Business Object Record, but this is an empty record. It captures this new record in the response from this call. 4. From within the captured record class it calls a method to "UpdateFromXml", which updates the blank record with the provided XML data. 5. The RecID of the new record is returned from the CreateBusinessObject method. As you can see, CWS was developed to provide an easy platform to call from a third party, such as a web site or application. CWS exposes one method to create a new Business Object record; such as an Incident, but in the background several processing steps take place within the API. For an example of making this call, follow the guide to Create a Record in Cherwell. CWS provides a limited list of activities, but this list is continuously updated through each version of Cherwell Service Management. CWS must be running for the Mobile Applications to operate, and is also required for a number of other features (RSS feeds, SAML security access, Bomgar Integration, and so on). CSM Web Services & API 2

6 Tutorials Introduction The following tutorials provide a basic example of how to login, and call some of the Cherwell Web Service methods. These tutorials are given in Windows PowerShell and C#, and should only be used by Developers with a good understanding of APIs and.net languages. We have only provided a sample of methods as tutorials, with the rest of the methods explained in the next section. Ideally, these methods should be tested with an application such as Windows PowerShell or Visual Studio. Login to Cherwell Before we begin, a few points to note about this example: Usernames and Passwords provided are for a demo/starter database, you will need to provide credentials for a user within your environment. The web service URL provided is typical for a local install of Cherwell. The result of this method will return True if successful. PowerShell Example # Define URL, and create proxy for web service $URI = " $cherwellservice = New-WebServiceProxy -Uri $URI # Create container for storing session cookie $cherwellservice.cookiecontainer = New-Object system.net.cookiecontainer # Run Login method with provided credentials $cherwellservice.login( CSDAdmin, CSDAdmin ) C# Example Create a Web Reference to CWS, with the URL set to and with a name of Cherwell. public bool Login() { // Instantiate new service proxy called cherwellservice var cherwellservice = new Cherwell.api(); // Create container for storing session cookie cherwellservice.cookiecontainer = new System.Net.CookieContainer(); } // Run Login method with provided credentials return cherwellservice.login( CSDAdmin, CSDAdmin ); CSM Web Services & API 3

7 Create a Record in Cherwell Before we begin, a few points to note about this example: Creating records through the Web Service reads data in the same way as through the Cherwell Client; therefore validation, calculations and required fields should all be considered. The XML provided would create a record within a demo/starter instance. Your environment may have additional required fields, or content that invalidates some of the data. This example follows on from login, meaning you will need to run the login method and store a session cookie in order to run this method. The result of this method will return the RecID of the new record if successful. PowerShell Example $incidentid = $cherwellservice.createbusinessobject("incident","<businessobject Name='Incident'><FieldList><Field Name='Call Source'>Event</Field><Field Name='CustomerDisplayName'>Henri Bryce</Field><Field Name='Service'>Desktop Management</Field><Field Name='Category'>Computer</Field><Field Name='SubCategory'>Request New Computer</Field><Field Name='Priority'>3</Field><Field Name='Description'>From SOAP</Field></FieldList></BusinessObject>") C# Example public string CreateBusinessObject() { var creationxml = new StringBuilder(); creationxml.append("<businessobject Name='Incident'>"); creationxml.append("<fieldlist>"); creationxml.append("<field Name='Call Source'>Event</Field>"); creationxml.append("<field Name='Customer Display Name>Henri Bryce</Field>"); creationxml.append("<field Name='Service'>Desktop Management</Field>"); creationxml.append("<field Name='Category'>Computer</Field>"); creationxml.append("<field Name='SubCategory'>Request New Computer</Field>"); creationxml.append("<field Name='Priority'>3</Field>"); creationxml.append("<field Name='Description'>From SOAP</Field>"); creationxml.append("</fieldlist>"); creationxml.append("</businessobject>"); return cherwellservice.createbusinessobject("incident", creationxml.tostring()); } To find out more about the XML structure used here, read Shape of a Business Object. CSM Web Services & API 4

8 Find a Record in Cherwell Before we begin, a few points to note about this example: We have provided two options below, the first searches Cherwell using a named stored query, the second searches Cherwell using a given field name and value. Both methods return an XML string as a list of records. Should you need to interrogate this list, you will need to map and deserialise the XML into a new class. PowerShell Example Query By Stored Query $queryxml = $cherwellservice.querybystoredquery("incident", "All Incidents") Query By Field Value $queryxml = $cherwellservice.querybyfieldvalue("incident", "Customer Display Name", "Henri Bryce") C# Example Query By Stored Query public string QueryByStoredQuery() { // Return XML string containing list of records. return cherwellservice.querybystoredquery("incident", "All Incidents"); } Query By Field Value public string QueryByFieldValue() { // Return XML string containing list of records. return cherwellservice.querybyfieldvalue("incident", "Customer Display Name", "Henri Bryce"); } The methods explained above return an XML string containing a list of records. You may wish to restrict the list further, or manipulate the records individually. Some example code for this has been provided within the links detailed in the Further Information section below. Look out for the InterrogateListFromQueryString method, which accepts a Business Object and an XML string as parameters this can be used to convert the XML string to a list of objects in code. Further Information A console testing platform had been developed in C# to test some of the Cherwell Web Service methods. You can download this project using the following URL: This should be used for testing purposes, or as a starting block for integration with Cherwell through the Web Service. CSM Web Services & API 5

9 Methods Explained All methods for the current version of the Web Service have been explained in further detail below. Each has a description about what the method does, and each parameter and return value is also explained. Some methods may have some small examples to help with execution. The majority of methods in CWS were added for mobile or portal use. Sometimes they are not very user-friendly and cannot be used in isolation. Quite often, some parameters come from previous calls to other methods. AddAttachmentToRecord Adds an attachment to the specified record. busobnameorid String Name or ID of Business Object (ex: Incident). busobrecid String RecID of record to attach to. attachmentname String Name of attachment to store. attachmentdata String XML String of Base64 encoded attachment data. Return Value Bool True/False return if successful. ClearMruForObject Removes all entries in a user s Most Recently Used list for the specific object type and ID. objecttype String Definition name of object (ex: StoredQueryDef or BusinessObjectDef). objectnameorid String Name or ID of Business Object (ex: Incident). Return Value None No return value. ConfirmLogin Confirm connectivity and login credentials. Used to confirm username and password are correct. userid String Username of Cherwell ID. password String Password of Cherwell ID. Return Value Bool True/False return if successful. CSM Web Services & API 6

10 CreateBusinessObject Create a new Business Object and populate it based on the passed XML. For an example, see Create a Record in Cherwell. busobnameorid String Name or ID of Business Object (ex: Incident). creationxml String XML Structure to create record. For an example, see Shape of a Business Object. Return Value String RecID of newly created record, or error code if unsuccessful. ExecuteAction Call GetItemDisplayHTML with includeactions to return a list of actions that can be called by ExecuteAction. objecttype String ** Not Used ** objectnameorid String Name or ID of Business Object (ex: Incident). recid String RecID of record to effect. actionid String ID of the action to take. actioninputs String XML for inputs for the action. returnnewhtmlonsuccess Bool If true, return HTML for the record in its new state. returnavailableactionsonsuccess Bool If true, and including above, actions included in HTML. actioncargo String Optional additional data added by server. Return Value String Success or HTML depending on bool options above. GetApiVersion Returns official version number for the Web Service installed. Return Value String Version of Cherwell Web Service (ex: 4.60e). CSM Web Services & API 7

11 GetAttachment Retrieves the specified attachment in Base64 encoded string. attachmentid String ID of Attachment (could be found in DB) Return Value String XML String of Base64 encoded attachment data GetAttachmentsForBusinessObject Retrieves a list of attachments associated with a Business Object. busobnameorid String Name or ID of Business Object (ex: Incident). busobrecid String RecID of record to retrieve attachments for. Return Value String XML String List of Base64 encoded attachment data. GetBusinessObject Retrieves a Business Object based on its record ID. busobnameorid String Name or ID of Business Object (ex: Incident). busobrecid String RecID of record to retrieve. Return Value String XML String of Business Object. For an example, see Shape of a Business Object. GetBusinessObjectByPublicId Retrieves a Business Object based on its public ID. For example Incident public ID is Incident ID, which is the 5+ digit reference number. busobnameorid String Name or ID of Business Object (ex: Incident). busobpublicid String Public ID of record. Return Value String XML String of Business Object. For an example, see Shape of a Business Object. CSM Web Services & API 8

12 GetBusinessObjectDefinition Get a Business Object definition. Gets the structure of a Business Object, such as field names and types. nameorid String Name or ID of Business Object (ex: Incident). Return Value String XML String of Business Object definition. GetDashboard This returns the contents of the specified Mobile Dashboard, including images for items. dashboardid String String of Dashboard ID, such as Alert:Default Alert. alertonly Bool If true, only short alert mobile Dashboards. updatemru Bool If true, update User Settings. recordlimit Int Maximum number of records to return. Return Value String XML string of Dashboard definition. GetDashboardWithSizes This returns the contents of the specified Dashboard, including images for items. dashboardid String String of Dashboard ID, such as Alert:Default Alert. alertonly Bool If true, only show alert mobile Dashboards. updatemru Bool If true, update User Settings. widgetwidth Int Number of pixels wide. widgetheight Int Number of pixels high. recordlimit Int Maximum number of records to return. Return Value String XML string of Dashboard definition. CSM Web Services & API 9

13 GetImages This method returns encoded versions of the specified images. imageids String Comma separated list of images which each value in the following format: (ex: [PlugIn]Images;Images.Common.Dashboards.MobileDashboard 32.png ). width Int Number of pixels wide. height Int Number of pixels high. Return Value String XML string with encoded Image Data. GetItemDisplayHtml Retrieves the html to display a Business Object. objecttype String ** Not Used ** objectnameorid String Name or ID of Business Object (ex: Incident). recid String RecID of record to return. includeactions Bool If true, include actions for use in ExecuteAction and other methods. actioncargo String Internal use only, leave empty. Return Value String Returns HTML for record. GetItemList This returns the items that should appear on a list of objects. objecttype String Definition name of object (ex: StoredQueryDef or BusinessObjectDef ). objectnameorid String Name or ID of Business Object (ex: Incident). currentlocation String Optional location of items (ex: Scope#ScopeOwner). forcerefresh Bool If true, the code will refresh the cache before retrieving the data. Return Value String XML string with list of items. CSM Web Services & API 10

14 GetItemListWithParentInfo This returns the items that should appear on a list of objects and includes parent information. objecttype String Definition name of object (ex: StoredQueryDef or BusinessObjectDef ). objectnameorid String Name or ID of Business Object (ex: Incident). currentlocation String Optional location of items (ex: Scope#ScopeOwner). forcerefresh Bool If true, the code will refresh the cache before retrieving the data. Return Value String XML string with list of items including parent info. GetLastError Get the last error that occurred in the session. Return Value String Last error reported from the Cherwell Web Service. GetLastError2 Get the last error, with header and sub-header messages. Return Value String Last error reported from the Cherwell Web Service. GetMruForObject Retrieve a user s Most Recently Used items for the specified object type and ID. objecttype String Definition name of object (ex: StoredQueryDef or BusinessObjectDef ). objectnameorid String Name or ID of object definition (ex: Incident). includesystem Bool If true, if specialized object (ex: MobileDashboardDef) then result includes items such as Home and Alerts. forcerefresh Bool If true, the code will refresh the cache before retrieving the data. Return Value String XML string of MRU data. CSM Web Services & API 11

15 GetParametersForAction Gets the list of parameters needed by the specified action. objectnameorid String Name or ID of Business Object (ex: Incident). recid String RecID of record to retrieve. actionid String Can be found by calling GetItemDisplayHTML. Return Value String XML string list of parameters for given action. GetQueryResults This returns the results of a specified query. queryid String ID of Stored Query to run. updatemru Bool If true, update user s Most Recently Used items. recordlimit Int Maximum number of records to return. allowpromptinfo Bool ** Not Used ** proximitythreshold Double Optional proximity based on user s location (default: 0.0). proximitysortasc Bool If true, sort proximity field in results Ascending. Return Value String XML string list of query results. CSM Web Services & API 12

16 GetQueryResultsUsingPromptInfo This returns the results of a specified query. queryid String ID of Stored Query to run. updatemru Bool If true, update user s Most Recently Used items. recordlimit Int Maximum number of records to return. queryinputs String XML Inputs for Query prompts. proximitythreshold Double Optional proximity based on user s location (default: 0.0). proximitysortasc Bool If true, sort proximity field in results Ascending. Return Value String XML string list of query results. GetServiceInfo Returns CherwellService info such as the required login mode for Cherwell Mobile apps and the current version of Cherwell. Return Value String Returns Cherwell Service info. GetTabBarOptions Gets a list of all of the available items for the tab bar from the Mobile Dashboard, in the default order. iphoneimages Bool If true, images are returned for iphone (Cherwell Mobile for ios ). Return Value String Returns XML string of Tab bar items. GetiCherwellCredentialsMode Returns the required login mode for icherwell - 0 means can store User ID and Password, 1 icherwell can store the User ID, but must prompt for Password, 2 means icherwell must prompt for both the User ID and Password. Return Value Int Returns Cherwell Mobile credentials mode. CSM Web Services & API 13

17 Login Establish a session and log in. For an example, see Login to Cherwell. userid String Cherwell user login name. password String Cherwell user password. Return Value Bool Returns True/False if login successful. LoginWithProductCode Establish a session and log in, with a specified product code. userid String Cherwell user login name. password String Cherwell user password. productcode String Product to login with (ex: CSD). module String Version of product (ex: Mobile, Android ). sessionid String Optional login to existing session. Return Value Bool Returns True/False if login successful. Logout Close down a session and logout. Return Value Bool Returns True/False if logout successful. MobileLogin Establish a session and log in for mobile devices. userid String Cherwell user login name. password String Cherwell user password. version String Version of software (ex: Android or iphone ). sessionid String Optional login to existing session. CSM Web Services & API 14

18 preferences String Optional XML preferences (ex: Timezone offset, language, locale). Return Value String String containing Logged In Info, API Version, etc. MobileLogout Close down a mobile session and logout. Return Value Bool Returns True/False if logout successful. QueryByFieldValue Query for a specific field value. For an example, see Find a Record in Cherwell. busobnameorid String Name or ID of Business Object (ex: Incident). fieldnameorid String Name or ID of Business Object Field (ex: ). value String Search value (ex: [email protected]). Return Value String XML string with list of results. QueryByStoredQuery Query using a specific stored query. For an example, see Find a Record in Cherwell. busobnameorid String Name or ID of Business Object (ex: Incident). querynameorid String Name of Stored Query (ex: All Incidents). Return Value String XML string with list of results. QueryByStoredQueryWithScope Query using a specific stored query with scope. busobnameorid String Name or ID of Business Object (ex: Incident). querynameorid String Name of Stored Query (ex: All Incidents). CSM Web Services & API 15

19 scope String Scope (ex: Global, Team, User, Role). scopeowner String Owner of Scope (if User, then User name). Return Value String XML string with list of results. QueryForWidgetDataAtPos Retrieves widget data for specified x,y position in widget, with default size (175px x 175px). widgetid String ID of Widget. x Int X Position to return data from. y Int Y Position to return data from. recordlimit Int Maximum number of records to return. Return Value String XML string with Widget data. QueryForWidgetDataAtPosWithSizes Retrieves widget data for specified x,y position in widget. widgetid String ID of Widget. x Int X Position to return data from. y Int Y Position to return data from. widgetwidth Int Number of pixels wide. widgetheight Int Number of pixels high. recordlimit Int Maximum number of records to return. Return Value String XML string with Widget data. CSM Web Services & API 16

20 QueryForWidgetImage Retrieves widget image, with default size (175px x 175px). widgetid String ID of Widget. Return Value String XML string with encoded Image Data. QueryForWidgetImageWithSizes Retrieves widget image. widgetid String ID of Widget. widgetwidth Int Number of pixels wide. widgetheight Int Number of pixels high. Return Value String XML string with encoded Image Data. QuickSearch Retrieves results of a quick search for a particular Business Object type. busobnameorid String Name or ID of Business Object (ex: Incident). searchtext String Search string, such as Printer. nonfinalonly Bool If true, returns record if not in final state. finalonly Bool If true, returns record if in final state. timelimitcount Int Limit search timeout, such as 30. timelimitunits String Limit search timeout units, such as seconds. Return Value String XML string query result, showing RecID. UpdateBusinessObject Locates a Business Object by its RecID and updates it based on the passed XML. busobnameorid String Name or ID of Business Object (ex: Incident). CSM Web Services & API 17

21 busobrecid String RecID of existing record to update. updatexml String XML Structure to update record. For an example, see Shape of a Business Object. Return Value Bool Return True/False if update successful. UpdateBusinessObjectByPublicId Locates a Business Object by its RecID and updates it based on the passed XML. busobnameorid String Name or ID of Business Object (ex: Incident). busobpublicid String Public ID of existing record to update. updatexml String XML Structure to create record. For an example, see Shape of a Business Object. Return Value Bool Return True/False if update successful. CSM Web Services & API 18

22 Shape of a Business Object It is important to understand how a Business Object is structured when trying to create, update or retrieve a record in Cherwell. We use XML to shape our requests, and without the correct XML provided, the request will inevitably fail. We have provided a sample Business Object XML below, which is how you will see it returned when calling the GetBusinessObject and GetBusinessObjectByPublicId methods above, and how it should be structured for CreateBusinessObject and UpdateBusinessObject methods. <BusinessObject Name="Incident"> <FieldList> <Field Name="Call Source">Event</Field> <Field Name="Service">Desktop Management</Field> <Field Name="Category">Computer</Field> <Field Name="SubCategory">Request New Computer</Field> <Field Name="Customer ID">9349ef749d8a5426d9db2443b3b207287af8760ff5</Field> <Field Name="Customer Type ID">93405caa107c376a2bd15c4c8885a900be316f3a72</Field> <Field Name="CustomerDisplayName">Mrs. Alberta Albertson</Field> <Field Name="Description">From SOAP</Field> <Field Name="Priority">3</Field> </FieldList> </BusinessObject> The important sections to note are Name, Field, Field Name, and Field Value. A Business Object will have a Name, which refers to the type of record you wish to create. It will contain a Field List, which contains a number of Fields. Each field has a Name, and a Value. You only need to provide fields in the XML that you wish to set, however you will need to be mindful of field validation, such as Required for Save, Auto Populate, and Content Validation. CSM Web Services & API 19

23 HTTP Request & Response We have provided a sample successful HTTP request and response below, taken from running one of the Web Service methods and tracing via a third party utility, such as Fiddler. HTTP Post Request POST HTTP/1.1 User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol ) VsDebuggerCausalityData: uidpoypomixrxuxchwaoanmeuuaaaaaace0ktszeje+u/ikeu9glyfqsovaxr7bogsrz3vjjuz8acqaa Content-Type: text/xml; charset=utf-8 SOAPAction: " Host: cherwell-demo Cookie: ASP.NET_SessionId=brupd1ew3pzyhyygcpifvegy Content-Length: 1097 Expect: 100-continue <?xml version="1.0" encoding="utf-8"?><soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns=" Object Name="Incident"> <FieldList> <Field Name="Call Source">Event</Field> <Field Name="Service">Desktop Management</Field> <Field Name="Category">Computer</Field> <Field Name="SubCategory">Request New Computer</Field> <Field Name="Customer ID">9349ef749d8a5426d9db2443b3b207287af8760ff5</Field> <Field Name="Customer Type ID">93405caa107c376a2bd15c4c8885a900be316f3a72</Field> <Field Name="CustomerDisplayName">Mrs. Alberta Albertson</Field> <Field Name="Description">From SOAP</Field> <Field Name="Priority">3</Field> </FieldList> HTTP Post Response HTTP/ OK Cache-Control: private, max-age=0 Content-Type: text/xml; charset=utf-8 Server: Microsoft-IIS/7.5 X-AspNet-Version: X-Powered-By: ASP.NET Date: Fri, 03 Oct :59:06 GMT Content-Length: 442 <?xml version="1.0" encoding="utf-8"?><soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" y><createbusinessobjectresponse xmlns=" Result>93f586e73d8a1b28e601f247c6bb85641abe0e57e3</ CreateBusinessObjectResult></CreateBusinessObjectRespon se></soap:body></soap:envelope> </BusinessObject></creationXml></CreateBusinessObject></soap:Body></soap:Envelope> Considerations There are factors that will help determine whether the CWS is appropriate for your desired integration. Firstly, the login method creates a session in CSM by providing a Username and Password, which the third party application/site will need to be able to store in a client-side cookie container for you to then be able to use this session to execute subsequent methods. Secondly, if you intend to use methods that create or manipulate Cherwell Business Objects, a defined XML format must be provided; therefore the requesting application will need to be able to provide data in this format. If the third party is unable to conform to the above constraints, then it will not be possible to use the Cherwell Web Service directly. In these circumstances, you may need to develop an intermediary Web Service or connector that references CWS or the Trebuchet API, and that is able to translate the requests of the third party application. CSM Web Services & API 20

24 Trebuchet API Overview The API is a very complete.net API that provides access to virtually every feature and function of CSM. Everything you see within the CSM platform utilizes the methods within the API suite. Therefore with easy access to these assemblies, you can recreate any functionality with Cherwell in a third party, such as through a web service, external web site or application. As the API is written in.net, a developer can interface with these assemblies in any.net based coding language, but this does mean you need to be able to read and write code to develop with this platform. Using the API In order to begin developing with the API, you will need a copy of the required assemblies and their dependencies from the Cherwell Service bin directory, which is usually located C:\Program Files\Cherwell Browser Applications\Cherwell Service\bin. Required are those starting Trebuchet.xx.dll and the following list: FlexCell.dll, GenuineChannels.dll, HtmlAgilityPack.dll, htn.dll, ICSharpCode.SharpZipLib.dll, Interop.ActiveDs.dll, log4net.dll, Newtonsoft.Json.dll, Remotion.Data.Linq.dll, Remotion.dll, Remotion.Interfaces.dll and tern.dll You will need to reference the following assemblies directly: Trebuchet.API.dll, Trebuchet.Core.dll and Trebuchet.Utility.dll. The rest are dependencies and can be placed in the bin directory at runtime. You may find depending on the methods you are accessing directly, that you need additional referenced assemblies. Before making any calls to classes and methods in the API, you must first establish a connection to the database, and login. Samples of these can be found in the below context by following the ConnectAndDisconnect and Login methods. CSM Web Services & API 21

25 Tutorials Introduction The following tutorials provide an example of how to login, Create a Business Object record, and Find a record in Cherwell. These tutorials are given in C# only, and should only be used by Developers with a very good understanding of APIs and.net languages. Before you begin, as stated in the Using the API section above, you will need to reference the required assemblies within your project and class file. Login to Cherwell Before we begin, a few points to note about this example: Usernames and Passwords provided are for a demo/starter database, you will need to provide credentials for a user within your environment. public bool Login() { // If API is not already connected, then connect to provided connection name if (!TrebuchetApi.Api.Connected) { TrebuchetApi.Api.Connect( [Common]Cherwell ); } // Attempt login with CSDAdmin credentials, return true if successful. bool login = TrebuchetApi.Api.Login(ApplicationType.RichClient, CSDAdmin, CSDAdmin, false, LicensedProductCode.CherwellServiceDesk, "SAM", "Sample Application"); // If login failed, disconnect the API connection if (!login) { if (TrebuchetApi.Api.Connected) TrebuchetApi.Api.Disconnect(); } } return login; CSM Web Services & API 22

26 Create a Record in Cherwell Before we begin, a few points to note about this example: Creating records through the API reads data in the same way as through the Cherwell Client; therefore validation, calculations and required fields should all be considered. The XML provided would create a record within a demo/starter instance. Your environment may have additional required fields, or content that invalidates some of the data. This example follows on from login, meaning you will need to run the login method first. The result of this method will return the RecID of the new record if successful. An example of the objectxml parameter can be found by reading the Shape of a Business Object section. public string CreateBusinessObject(string objectname, string objectxml) { BusinessObjectDef busobdef = null; // Get the definition of the object name provided (ex: Get Definition for Incident) if (!string.isnullorempty(objectname)) busobdef = TrebuchetApi.Api.DefinitionRepository.GetDefinition(DefRequest.ByName(BusinessObjectDef.Class, objectname)) as BusinessObjectDef; if (busobdef!= null) { // Create empty Business Object record for given object type. BusinessObject bo = TrebuchetApi.Api.BusObServices.CreateBusinessObject(busObDef); string recid = string.empty; // Update newly created Business Object record with provided XML. OperationResult result = bo.updatefromxml(objectxml); } // If update is successful, then save the record, and return the new RecID. if (result.success) result = bo.save(); if (result.success) { recid = bo.recid; return recid; } else return string.concat("error creating new object: " + result.errortext); } return "Error creating new object: Object Type not found."; CSM Web Services & API 23

27 Find a Record in Cherwell Before we begin, a few points to note about this example: This method returns a Business Object type, steps to return XML are given in the comments. public BusinessObject FindObjectByFields() { // Add as many fields as you wish to the dictionary to narrow the search down. Dictionary<string, string> fields = new Dictionary<string, string>(); dictionary.add(" ", "[email protected]"); // Run method below to get the Top 1 record. Change the second parameter to search a different Business Object BusinessObject bo = this.getbusinessobject(fields, "Incident"); // Uncomment the return below to return XML string (remember to change method return type to String) if (bo!= null) return bo; // return bo.toxml(); return string.empty; } public BusinessObject GetBusinessObject(Dictionary<string, string> fields, string objectname) { // Build query and search criteria. Amend TopCount to retrieve more records. QueryDef query = QueryDef.CreateQuery(); BusinessObjectDef busobdef = TrebuchetApi.Api.DefinitionRepository.GetDefinition(DefRequest.ByName(BusinessObjectDef.Class, objectname)) as BusinessObjectDef; query.busobid = busobdef.id; query.queryresulttype = QueryResultType.BusOb QueryResultType.Top; query.topcount = 1; // For each field provided in dictionary, add a search clause to narrow down results. foreach (var field in fields) { FieldDef fielddef = busobdef.fields.getfieldbyname(field.key); QueryConditionClause clause = query.toplevelgroupingclause.createfieldvalueclause(fielddef.id, Operator.Equal, TypedValue.ForString(field.Value)); query.toplevelgroupingclause.clauses.add(clause); } // Run query and return first record as a Business Object. QueryCacheManager querymanager = new QueryCacheManager(query); querymanager.initialize(true); BusinessObject bo = querymanager.getcurrentrecord(); } return bo; CSM Web Services & API 24

28 Further Information Some API examples can be found here: Within this folder, you will find a CherwellAPI.chm file, which contains a complete list of all available classes, methods and properties of the API. You will also find an APISamples.cs file. This is a C# class file, which could be added to an existing project and expanded on, or simply used as reference. It contains some specific examples of using the API to Login, Create Business Objects and Find Customer By and more. Additional examples and information can be found on the Cherwell Community page: Questions can be asked here, or on the forum page: CSM Web Services & API 25

29 One-Step: Call a Web Service Overview Using the Call a Web Service Action within the One-Step Manager allows you to call a REST or WSDL (SOAP) based Web Service or WCF Service. Utilizing the REST protocol in the latest version of CSM, it is possible to perform a GET, POST, PUT or DELETE method; additionally the methods can be input manually, along with their parameters. By using the WSDL protocol, CSM will read the WSDL and automatically generate the methods and parameters. CSM currently supports basic security (username and password), HTTPS and SSL. Tutorials Introduction The following tutorials give some brief examples of how to call out to the two types of Web Service protocol. The examples may use free to use sample Web Services located on the Internet. These tutorials can be used by anyone who has some experience writing One-Steps within Cherwell Service Management. Call a REST Service The example we will use for our REST service call is actually a free to use Internet hosted web service on the Yahoo Developer network. Before creating your One-Step you will need to configure the Web Service you intend to call. This can be done through the CSM Administrator, in the Web Services Manager of thebrowser and Mobile settings. Full documentation of this example is available here: weather/ CSM Web Services & API 26

30 In here, create a new Web Service, and most importantly, supply the URL. As this is a REST service call, be sure to select REST from the Service Type drop down. This particular example does not require security, so select None from the Security Type drop down. As this is REST, we need to create our methods and parameters manually, you can create a method as shown below. The endpoint field adjusts the structure of the resulting service call URL. Using the above example, this will give us a URL of: The parameters are then added onto the end of the URL in the format: Once you have created your service and methods, you can reuse this stored service at any time. For example, if the service had multiple methods, we can create multiple One-Steps to call each of the methods, using the stored Service and methods that you created. CSM Web Services & API 27

31 To make a call to this service, from the One-Step Manager in either Cherwell Administrator or the Desktop Client, create a new One-Step, and choose the Call a Web Service step. You should then see a window like the image below, where you can select your newly created Service using the ellipses button. Account will be greyed out if you chose a Security Type of None. You can then choose from the methods you created from the Method drop down. Select each parameter, and provide a value from the options on the right hand side. All the usual values can be passed, such as Business Object fields, Stored Values and expressions, by right-clicking the Set Value field. If your method call returns a response that you wish to capture, select Store result as and provide a Variable name. If your method returns a return code (this could be a known code, or an error), select Store return code as and provide a Variable name. These variables can then be used in subsequent steps within your One-Step, such as to populate a form field, updated a stored value or use as part of an Expression. CSM Web Services & API 28

32 Call a WSDL Service Also known as a SOAP service call, the WSDL service is self-documenting, meaning it provides a document that can be translated by the requesting application to automatically create all the methods and parameters from the service. For this example, we use a public SOAP service to the Daily Dilbert Comic. Before creating your One-Step, you will need to configure the Web Service you intend to call. This can be done through the CSM Administrator, in the Web Services Manager of thebrowser and Mobile settings. With a WSDL service, you do not need to populate the WSDL URL field, simply select Parse WSDL, and it will automatically generate the URL and all the methods and parameters from the service. You can now go to the methods tab to see all the methods that have been created. You will need to select a Default Method. CSM Web Services & API 29

33 Once you have created your service, you can call it from a One-Step in the same way as the REST service documented in the previous section. This method example should return a value of This tutorial uses a publiclyhosted SOAP web service. The following site provides some more samples: CSM Web Services & API 30

34 About Cherwell Software Cherwell Software builds Cherwell Service Management (CSM), the award-winning IT Service Management software, as well as extraordinary customer relationships. Recognized by both Gartner and Forrester, CSM is an affordable, easy-to-use, and flexible ITSM platform you will never outgrow. Founded by some of the industry's most notable leaders, Cherwell Software began with simple goals: to make help desk software we would want to use and to do business honestly, putting customers first. Cherwell is one of the fastest growing IT service management software providers with corporate headquarters in Colorado Springs, CO, USA; EMEA headquarters in Swindon, UK; and a global network of expert partners. Please visit for more information about Cherwell Software. Contact Information Support Website: Sales Website: Support Sales [email protected] [email protected] Corporate Headquarters North America Support Phone: Sales Phone: ext.1 Address: Oracle Blvd., Suite 200 Colorado Springs, CO 80921, USA Europe, the Middle East, and Africa Sales Phone: +44 (0) Address: Delta 1200 Delta Office Park Swindon, Wiltshire SN5 7XZ, UK CSM Web Services & API 31