CA Nimsoft Service Desk Configure Outbound Web Services 7.13.7
Legal Notices Copyright 2013, CA. All rights reserved. Warranty The material contained in this document is provided "as is," and is subject to being changed, without notice, in future editions. Further, to the maximum extent permitted by applicable law, Nimsoft LLC disclaims all warranties, either express or implied, with regard to this manual and any information contained herein, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Nimsoft LLC shall not be liable for errors or for incidental or consequential damages in connection with the furnishing, use, or performance of this document or of any information contained herein. Should Nimsoft LLC and the user have a separate written agreement with warranty terms covering the material in this document that conflict with these terms, the warranty terms in the separate agreement shall control. Technology Licenses The hardware and/or software described in this document are furnished under a license and may be used or copied only in accordance with the terms of such license. No part of this manual may be reproduced in any form or by any means (including electronic storage and retrieval or translation into a foreign language) without prior agreement and written consent from Nimsoft LLC as governed by United States and international copyright laws. Restricted Rights Legend If software is for use in the performance of a U.S. Government prime contract or subcontract, Software is delivered and licensed as "Commercial computer software" as defined in DFAR 252.227-7014 (June 1995), or as a "commercial item" as defined in FAR 2.101(a) or as "Restricted computer software" as defined in FAR 52.227-19 (June 1987) or any equivalent agency regulation or contract clause. Use, duplication or disclosure of Software is subject to Nimsoft LLC s standard commercial license terms, and non-dod Departments and Agencies of the U.S. Government will receive no greater than Restricted Rights as defined in FAR 52.227-19(c)(1-2) (June 1987). U.S. Government users will receive no greater than Limited Rights as defined in FAR 52.227-14 (June 1987) or DFAR 252.227-7015 (b)(2) (November 1995), as applicable in any technical data. Trademarks Nimsoft is a trademark of CA. Adobe, Acrobat, Acrobat Reader, and Acrobat Exchange are registered trademarks of Adobe Systems Incorporated. Intel and Pentium are U.S. registered trademarks of Intel Corporation. Java(TM) is a U.S. trademark of Sun Microsystems, Inc. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. Netscape(TM) is a U.S. trademark of Netscape Communications Corporation. Oracle is a U.S. registered trademark of Oracle Corporation, Redwood City, California. UNIX is a registered trademark of the Open Group. ITIL is a Registered Trade Mark of the Office of Government Commerce in the United Kingdom and other countries. All other trademarks, trade names, service marks and logos referenced herein belong to their respective companies. For information on licensed and public domain software, see the Nimsoft Monitor Third-Party Licenses and Terms of Use document at: http://docs.nimsoft.com/prodhelp/en_us/library/index.htm?toc.htm?1981724.html.
Contact CA Nimsoft Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation Send comments or questions about CA Technologies Nimsoft product documentation to nimsoft.techpubs@ca.com. To provide feedback about general CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs.
Contents Chapter 1: Introduction 7 Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 9 Gather Prerequisite Information... 12 Configure Attributes and Custom Field Templates for Field Mapping... 14 Enable Web Service Invocation... 16 Configure Web Service Credentials... 17 Configure Web Service Operations for SOAP based calls... 19 Configure Web Service Operations for RESTful calls... 23 Relate Web Service Configurations to Workflow Actions... 27 Verify the Configurations... 29 Contents 5
Chapter 1: Introduction This document provides service desk administrators instructions on how to configure outbound web services to communicate with other applications. When you configure outbound web services, CA Nimsoft Service Desk can interact with third-party systems using outbound SOAP-based or RESTful web service calls. The outbound web service operation is linked to a workflow action. When the analyst executes the workflow action on the ticket, the outbound web service operation is invoked. If the external application returns a response to the web service call, CA Nimsoft Service Desk accepts the response and updates the ticket accordingly. Chapter 1: Introduction 7
Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications As the service desk administrator, you can configure web service adapters, and can define the field mapping to enable exchange of data with third-party applications. When you configure outbound web services, external applications can exchange data with CA Nimsoft Service Desk without building a polling mechanism. You can setup the data exchange to update fields on the external application and on CA Nimsoft Service Desk. The exchange of data happens in response to a call initiated by CA Nimsoft Service Desk. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 9
Gather Prerequisite Information 10 Configure Outbound Web Services
Gather Prerequisite Information Perform the following steps to configure outbound web services to communicate with an external application. 1. Gather Prerequisite Information. 2. (Optional) Configure Attributes and Custom Field Templates. 3. Enable Outbound Web Services. 4. Configure Web Service Credentials. 5. Configure Web Service Operations. 6. Configure Workflow Actions and Relate Web Service Operations. 7. Verify Configurations. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 11
Gather Prerequisite Information Gather Prerequisite Information To configure outbound web services, you need to gather basic understanding about the web services supported by the third-party application. You also need an understanding of the fields in the third-party application and the corresponding fields on CA Nimsoft Service Desk. When you configure field mappings, if the corresponding fields do not exist in CA Nimsoft Service Desk you can configure attributes and relate them to custom field templates. CA Nimsoft Service Desk supports SOAP based and RESTful web service calls. Depending on whether the third-party application uses SOAP or RESTful web services, you can gather the credentials that you need to configure the outbound web service calls. For SOAP based Web Service Calls: SOAP is an XML based message protocol and uses Web Service Description Language (WSDL) to communicate between the consumer and the provider. The WSDL XML file describes the web services for third-party applications that use SOAP based calls. The WSDL document normally describes the service, including the structure of the input and output. The WSDL document provides information that you use to configure the web service operations including the Methods, field mapping, and so on. The WSDL document has a standard and CA Nimsoft Service Desk can interpret the document. To access a web service, you need to find its WSDL entry. The WSDL entry is generally a URL on the web. Different companies control the access to the WSDL to different degrees. Some examples of the degree of control include: Free access approach: The WSDL document is available as a public URL or as an XML file and anyone can download the document. Basic authentication approach: The user name and password are required fields. The credentials that you provide here are used by the Web Service Operations to perform the data exchange. The administrator of the third-party application can provide you with the user name and password. In some cases, the administrator of the third-party application can create a new user name and password for CA Nimsoft Service Desk web service calls. Some third-party applications require you to make a web request for the user name and password as part of the credentials. Session based control in addition to authentication: A log in method is used to obtain a token that is used during the session. After the log out, the token expires. At every login a new token is generated. When the third-party application follows this approach, you need to configure login and logout operations after you configure the credentials. For RESTful Web Service Calls: 12 Configure Outbound Web Services
Gather Prerequisite Information RESTful web services enables simple point-to-point communication over HTTP using XML or JSON to send and receive data. Usually, RESTful web service calls are not defined in a formal document. However, some third-party applications define the supported web services. You can find the supported operations in the Web Application Description Language (WADL) XML.. Usually, applications that support RESTful web service calls, do not need authentication information. However, some applications may required basic authentication. Gather the following prerequisite information to plan the Outbound Web Services. 1. Validate that the third-party application offer web services. You cannot proceed if the third party application does not offer web services. 2. Validate that the third-party application supports SOAP based or RESTful web service calls. For an application that supports SOAP based calls, determine whether the WSDL is accessible as a URL or as an XML file that you can download. Determine the path to the WSDL entry and the level of authentication. Gather information that you can use to configure the credentials. For an application that supports RESTful web service calls, determine whether the web services that are supported are defined. When the web services are defined, determine whether the WADL is accessible as a URL or as an XML file that you can download. Gather information on the path to the WADL entry. When the web services are not defined, you can proceed without specifying the WADL path. 3. Validate that you are able to connect with the third-party application. Ping the third-party application server from the CA Nimsoft Service Desk web server. Check the result for any errors. You cannot proceed if the CA Nimsoft Service Desk web server is not able to connect to the third-party application server. 4. Identify the URL that is invoked to access the WSDL/WADL URL for the third-party application. When you identify the URL, confirm the following: The access and authentication that is required to invoke the web service. Confirm whether the third-party application requires basic authentication. If the application needs basic authentication, gather the user name and password that is used for basic authentication. Confirm whether the application uses session based control. You can get this information from the WSDL. 5. Identify the field mapping that you want to configure. Confirm whether the fields that you want to map are available on CA Nimsoft Service Desk. Identify any additional fields that you need for the configuration that you plan. 6. Identify the type of operations you want to configure. You can configure the web service operations and the related workflow actions according to this plan. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 13
Configure Attributes and Custom Field Templates for Field Mapping Configure Attributes and Custom Field Templates for Field Mapping During the planning process, you can identify the field mapping requirements. When the standard ticket fields in CA Nimsoft Service Desk and the existing custom fields do not suffice, you can configure custom attributes. You can then relate the attributes to custom field templates for tickets. You can identify the attribute name and the data type and then you can configure the attributes. When you relate the custom fields to the custom field templates, the attributes become available for field mapping. If the existing fields meet your requirements, you can ignore this procedure. Follow these steps: 1. Log in to CA Nimsoft Service Desk as the service desk administrator. 2. Click Manage, then click Application Setup and then click Manage Attributes. The Manage Attributes window appears. You can create custom attributes here. 3. Provide the following information: Attribute Name Unit Specify a name for the attribute. (Optional) Specify the unit type. Example: Miles. Sort Order (Optional) Select a Sort Order. The sort order determines the position of the attribute in the form where you add the attribute. Attribute Type Select an Attribute Type from the drop-down. You can choose from Text, Number, Datetime, List, Multi-line Text, Radio Button, and Checkboxes. Default: Text Note: The drop-down list the attribute type Section Header. The Section Header option is used to group attributes on the ticket field. Do not select the Section Header option. Possible Values The possible values field applies only when you select List, Radio Button, or Checkboxes as Attribute Type. Specify the possible values using the format that displays in the field. Use double tildes (~~) to separate display value and stored value and double pipes ( ) to separate different values. 4. Click Apply Changes. 14 Configure Outbound Web Services
Configure Attributes and Custom Field Templates for Field Mapping You can now use the attribute on a custom field template that is related to any ticket type. 5. Click Application Setup and then click Manage Custom Fields. The Manage Custom Fields window appears. You can relate the attribute that you created to the system defined custom field template for any ticket type. You can filter the Custom Field Template list to search and locate the system defined templates. System Defined templates have negative IDs (-1, -2, -3, and so on). 6. (Optional) Click Filter, and filter by type 'System Defined' and then click the refresh icon. The Custom Field attributes list is filtered and displays the system defined templates. A system defined template is present for each ticket type. 7. Click a Custom Field Template to view details. The Custom Field Template that selected is displayed in the form. The Related to Form, Template Name, and Description display as Read Only. Any attribute that is already related to the template displays in the Attributes section. 8. Click Create New and click the lookup icon in the Attribute Name field. The Attribute Name lookup displays a list of attributes that can be added to the template. 9. Enter the custom attribute name that you created in the search field and click Search. The list is filtered and the attribute matching the name is displayed in the list. 10. Select the Attribute from the list. The lookup closes and the attribute that is selected is displayed in the Attribute Name field. The Attribute Type and Possible Values get updated accordingly. 11. Click Save Attributes. The attribute name is generated in the Attribute Name list. You can first create all the attributes from Manage Attributes and then relate the attributes to the desired custom field template. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 15
Enable Web Service Invocation Enable Web Service Invocation To allow the exchange of data between CA Nimsoft Service Desk and a third-party application, enable to configuration parameter that controls the exchange of data. When the parameter is enable, web service calls get executed as part of the workflow action. You can enable the parameter from the Manage Config Parameter option in the Application Setup navigation menu. Follow these steps: 1. Log into CA Nimsoft Service Desk as the service desk administrator and navigate to Application Setup, Manage Config Parameters. The Config Parameters list displays in a new tab. You can search for the parameter and enable the parameter here. 2. In the Search field, enter ENABLE_EXTERNAL_WEB_SERVICES_INVOCATION and hit the return key. The parameter displays in the list. 3. Click the parameter name in the list to view the details of the parameter. The default value for the parameter is NO. You can set the parameter value to Yes to enable exchange of data using outbound web service calls. 4. In the Parameter Value field, click the radio button option Yes and then click Apply Changes. The parameter value modifications apply. CA Nimsoft Service Desk now supports exchange of data using outbound web service calls. 16 Configure Outbound Web Services
Configure Web Service Credentials Configure Web Service Credentials The web services credentials are the credentials that CA Nimsoft Service Desk uses to connect to the external application for data exchange. You can create and manage credentials that can be used to invoke the external web services for carrying out the data exchange. The external web service credentials that you configure here can be used for multiple methods that the external application supports. You can create and manage web service credentials from the Web Service Credentials option in the Workflow Tools navigation menu. Follow these steps: 1. Click Manage << Workflow Tools in the navigation menu and click Web Service Credentials in the list.. The Web Service Credentials list displays in a new tab. You can filter the list to see active or inactive credentials. The list displays the credential name and the status. You can view or modify an existing credential or add a new credential. 2. Click Add Credentials to create a new credential. A new tab displays the form to create the new credentials. 3. Provide the following information: Image Name (Optional) Click Browse to locate and upload an image. You can upload the logo or other relevant image to identify the external application. Specify a name by which to identify the external application. Description (Optional) Specify a description to describe the external application. Web Service Type Select either SOAP or REST by clicking the relevant radio-button. a. When you select the Web Service Type as SOAP, provide the following information: WSDL Type Select either URL or File. The selection depends on the whether the third-party application provides the credential information at a designated URL, or provides the credentials as an XML file. The next field displayed depends on the WSDL Type that you select. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 17
Configure Web Service Credentials WSDL File When you select the WSDL Type as File, the option to Browse to the file location displays. Click Browse to locate the file on your local system and upload the file. WSDL URL When you select the WSDL Type as URL, specify the URL name in the WSDL URL field. b. When you select the Web Service Type as REST, provide the following information: WADL Type When the third-party application supports a defined set of operations, the operations are defined in the WADL XML. Select either URL or File. The selection depends on the whether the third-party application provides the credential information at a designated URL, or provides the credentials as an XML file. The next field displayed depends on the WSDL Type that you select. WADL File (Optional) When you select the WADL Type as File, the option to Browse to the file location displays. Click Browse to locate the file on your local system and upload the file. WADL URL (Optional) When you select the WADL Type as URL, specify the location of the WADL here. Use Basic Authentication? Check this checkbox when you want to connect to the external application using basic authentication. Username Specify the username that is used to access the external application. When the Use Basic Authentication? checkbox is checked, Username is a required field. Password Specify the password for the user name that is used to access the external application. When the Use Basic Authentication? checkbox is checked, Password is a required field. 18 Configure Outbound Web Services
Configure Web Service Operations for SOAP based calls 4. Click Save. The web service credentials are saved. When you click Save, the Summary and Related Operations portlets display. The Summary portlet displays information on the Status of the Web Service Credential. You can see the Created By user name with the date and time stamp, and Modified By user name with the date and time stamp. The Related Operations portlet displays three most recently modified Web Service Operations that are related to that Web Service Credential. After you create the credentials, you can modify the credentials or can set the status as Inactive. You can use the Web Service Credentials that you created to configure the Web Service Operations that get used to carry out the data exchange. Note: Some applications require the external application to log in and log out for completing transactions. When the application that you are configuring requires login and logout operations, you can configure the login and logout operations from Web Service Operations. You can then update the Web Service Credentials for that application with the login and logout operations details. Configure Web Service Operations for SOAP based calls The web service operations that you configure enables exchange of data between CA Nimsoft Service Desk and the external application. After you configure the web service credentials, you can configure multiple operations using the methods that the external application supports. You configure the web service operations from the Web Service Operations option in the Workflow Tools navigation menu. Note: The information that you need to provide for the field mapping depends on the web service type. The procedure in this topic provides instructions for a web service credentials using SOAP based calls. Follow these steps: 1. Click Manage << Workflow Tools in the navigation menu and click Web Service Operations in the list.. The Web Service Operations list displays in a new tab. You can filter the list to see active or inactive credentials. The list displays the operation name and the status. You can view or modify an existing operation or add a new operation. 2. Click New Operation to create a new operation. A new tab displays the form to create the new operation. Note: You can also open an existing operation and use the Copy to New action to create a new operation from an existing operation. When you copy the existing operation, the details from all fields except Image, Name and Description are copied over. You can retain the details as is or modify the fields to create a new web service operation. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 19
Configure Web Service Operations for SOAP based calls 3. Provide the following information: Image Name (Optional) Click Browse to locate and upload an image. You can upload the logo or other relevant image to identify the external application. Specify a name to identify the external application. Description (Optional) Specify a description to describe the external application. Web Service Credentials Specify the name that you configured for the web service credentials that is used to connect to the external application. As you type in the name, the look-ahead search displays a list of web service credentials that you have configured. 4. Specify the Field Mapping. Provide the following information: Select Binding Select a binding from the dropdown. The options in the dropdown depend on the type of binding supported by the third-party application. Select Method Select a method that the external application supports. The drop-down list displays a list of methods that the external application supports. The list renders dynamically based on the Web Service Credentials that you select. Timeout Select the timeout for when the operation times out. When the external application fails to respond within the timeout that you specify, the operation fails. Unit: Milliseconds Entity Type Select the type of entity the web service operation relates to. You can choose from blank, Service Request, Incident, Problem, Change Request, and Task. Note: Select the entity type as blank when you configure login or logout operations. 20 Configure Outbound Web Services
Configure Web Service Operations for SOAP based calls 5. (Optional) Specify the Outbound Mapping. The value from the ticket field that you provide here populates the corresponding field in the external application. You can either specify the outbound field mapping in the XML file or you can select fields using the dropdown fields. To use the XML file, check the Advanced Configuration checkbox. The XML contents display. You can provide the outbound field mapping by specifying the values at the relevant nodes. When you use Advanced Configurations, you can see the entire SOAP request XML and you can provide it in the SOAP call. The Advanced Configuration is an auto-grow text area. You can use the lookup icon to open the entity lookup and to select entity tokens. The entity tokens that you select get replaced as external field values. In the SOAP request XML, insert tokens by placing a cursor, or select the text that is replaced by the token. The entity tokens that you select get replaced as external field values when the request is sent to the external application. Note: When you modify the configurations in an existing operation, click XML Diff to view the changes. The XML Diff button is enabled only when you modify the configuration, before you save the configuration. The lookup displays the previous configuration and the current configuration and highlights all the modification that you make. Click Restore to Default to reset the configuration to the last saved state. To specify the field mapping using the dropdown options, provide the following information and click the + icon to add the mapping: External Field Select an external field from the drop-down. The drop-down renders dynamically based on the method that you choose in the Select Method field. Ticket Field Specify the CA Nimsoft Service Desk ticket field tokens to map the ticket field that gets updated when the web service operation executes on the ticket. You can specify either standard ticket fields or custom fields that you configure. Example: ${description_long} Note: The fields that are displayed as required fields in the WSDL document display in the External fields by default. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 21
Configure Web Service Operations for SOAP based calls 6. (Optional) Specify the Inbound Mapping. The value from the field that you have identified on the external application updates the corresponding ticket field in CA Nimsoft Service Desk. To add the mapping, provide the following information and click the + icon. Ticket Field Select a ticket field for the CA Nimsoft Service Desk ticket. The drop-down displays the ticket standard fields and custom fields that you configure. XPath/Regular Expression Specify the path to the field in the external application. Example: /Envelope/Body/mc_issue_addResponse 7. (Optional) Click Actions and click Validate Operations to validate that configuration. The ticket selection lookup displays. Enter a ticket number to select a ticket and click Validate. The application executes the operation and displays the logs. You can review the logs to validate that the operation is configured correctly. Important! When you click Validate Operation, the Operation is saved, and the operation gets executed on the selected ticket. However, the operation does not display on the ticket board. It is recommended that you use a sample ticket to validate the operation. Do not use a ticket that is being worked on since the operation could change the field values on the ticket. The Validate Operation action displays only after you select an Entity Type. This action is not available on Login or Logout operations, where the entity type is blank. 8. Click Save. The Web Service Operation is configured. When you save the Web Service Operation, the Summary portlet displays. The Summary portlet displays information on the Status of the Web Service Operation. You can see the Created By user name with the date and time stamp, and Modified By user name with the date and time stamp. You can now relate the web service operation to a workflow action. 22 Configure Outbound Web Services
Configure Web Service Operations for RESTful calls Configure Web Service Operations for RESTful calls The web service operations that you configure enables exchange of data between CA Nimsoft Service Desk and the external application. After you configure the web service credentials, you can configure multiple operations using the methods that the external application supports. You configure the web service operations from the Web Service Operations option in the Workflow Tools navigation menu. Note: The information that you need to provide for the field mapping depends on the web service type. The procedure in this topic provides instructions for a web service credentials RESTful calls. Follow these steps: 1. Click Manage << Workflow Tools in the navigation menu and click Web Service Operations in the list.. The Web Service Operations list displays in a new tab. You can filter the list to see active or inactive credentials. The list displays the operation name and the status. You can view or modify an existing operation or add a new operation. 2. Click New Operation to create a new operation. A new tab displays the form to create the new operation. Note: You can also open an existing operation and use the Copy to New action to create a new operation from an existing operation. When you copy the existing operation, the details from all fields except Image, Name and Description are copied over. You can retain the details as is or modify the fields to create a new web service operation. 3. Provide the following information: Image Name (Optional) Click Browse to locate and upload an image. You can upload the logo or other relevant image to identify the external application. Specify a name to identify the external application. Description (Optional) Specify a description to describe the external application. Web Service Credentials Specify the name that you configured for the web service credentials that is used to connect to the external application. As you type in the name, the look-ahead search displays a list of web service credentials that you have configured. Select a credential from the list. The information that you need to specify for the field mapping depends on whether a WADL is configured for the Web Service Credential that you select. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 23
Configure Web Service Operations for RESTful calls 4. Specify the details for the Field Mapping. a. When a WADL is configured for the Web Service Credential that you select, provide the following information. Select Endpoint URI/Path Select an Endpoint URI from the dropdown. The options in the dropdown depend on the Resource Endpoint URI the third-party application supports. Select Method Select a method that the external application supports. The drop-down list displays a list of methods that the external application supports. The list renders dynamically based on the Endpoint URI/Path that you select. Based on the Method, the HTTP Method value updates. The HTTP Method field is read only. Timeout Select the timeout for when the operation times out. When the external application fails to respond within the timeout that you specify, the operation fails. Unit: Milliseconds Entity Type Select the type of entity that the web service operation relates to. You can choose from Service Request, Incident, Problem, Change Request, and Task. b. When WADL URL NOT is configured for the Web Service Credential that you select, provide the following information. Endpoint URI/Path Provide an Endpoint /Path to make a RESTful call to the third-party application. HTTP Method Select a HTTP Method that is to be used when making a RESTful call to the third-party application. Timeout Select the timeout for when the operation times out. When the external application fails to respond within the timeout that you specify, the operation fails. Unit: Milliseconds 24 Configure Outbound Web Services
Configure Web Service Operations for RESTful calls Entity Type Select the type of entity the web service operation relates to. You can choose from Service Request, Incident, Problem, Change Request, and Task. 5. (Optional) Specify the Outbound Mapping. The value from the ticket field that you provide here populates the corresponding field in the external application. The value from the Ticket Field in CA Nimsoft Service Desk that you select updates corresponding External Field in the third-party application. Important! When a WADL is configured for the corresponding Web Service Credential, the values for fields for specifying the third-party application information are rendered in a dropdpwn. The values that are rendered depend on the method that you select in the Select Method field. You can select a value from the dropdown to configure the Outbound Mapping. When a WADL is not configured, the fields display as Text areas. You can enter the valid values manually. You can specify Headers and the URL parameters in the appropriate section provided within Outbound Mapping section. Provide the following information: Content-Type Accept Specify the Media Type in which the Outbound Mappings are passed to the third-part application using RESTful web service calls. Specify the Media Type in which Inbound Mappings parse the response that is received from the RESTful call that is made to the third-party application. External Field Specify the field name from the third-party application to set the mapping. Ticket Field Specify the CA Nimsoft Service Desk ticket field token. You can specify either standard ticket fields or custom fields that you configure. Note: Click the lookup icon to see a list of CA Nimsoft Service Desk field tokens. You can select the field token from the lookup. Click the + icon to add the field mapping. Example: ${description_long} Note: The fields that are displayed as required fields in the WADL document display in the External fields by default. 6. (Optional) Specify the Inbound Mapping. The value from the field that you have identified on the external application updates the corresponding ticket field in CA Nimsoft Service Desk. To add the mapping, provide the following information and click the + icon. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 25
Configure Web Service Operations for RESTful calls Ticket Field Select a ticket field for the CA Nimsoft Service Desk ticket. The drop-down displays the ticket standard fields and custom fields that you configure. XPath/JSONPath/Regular Expression Specify the XPath to the field in the external application, if Accept value is specified as application/xml Example: /Envelope/Body/mc_issue_addResponse Specify the JSONPath to the field in the external application, if Accept value is specified as application/json Example: $.store.book[0].title 7. (Optional) Click Actions and click Validate Operations to validate that configuration. The ticket selection lookup displays. Enter a ticket number to select a ticket and click Validate. The application executes the operation and displays the logs. You can review the logs to validate that the operation is configured correctly. Important! When you click Validate Operation, the Operation is saved, and the operation gets executed on the selected ticket. However, the operation does not display on the ticket board. It is recommended that you use a sample ticket to validate the operation. Do not use a ticket that is being worked on since the operation could change the field values on the ticket. The Validate Operation action displays only after you select an Entity Type. This action is not available on Login or Logout operations, where the entity type is blank. 8. Click Save. The Web Service Operation is configured. When you save the Web Service Operation, the Summary portlet displays. The Summary portlet displays information on the Status of the Web Service Operation. You can see the Created By user name with the date and time stamp, and Modified By user name with the date and time stamp. You can now relate the web service operation to a workflow action. 26 Configure Outbound Web Services
Relate Web Service Configurations to Workflow Actions Relate Web Service Configurations to Workflow Actions The application invokes the web service operation when the analyst executes a workflow action on the ticket. By relating a web service operation to a workflow action you can manage which web service operation is called when a workflow action applies. After you configure the web service operations, you can relate the operation to a workflow action. You can relate a web service operation to a workflow action from the Workflow Actions option in the Workflow Tools navigation menu. Follow these steps: 1. Click Manage and then click Workflow Tools in the navigation menu. The options for Workflow Tools displays. 2. Click the Manage Workflow Actions option. The Manage Workflow Actions options displays in a new tab. You can filter the list to see active or inactive workflow actions. You can modify an existing workflow action or can create workflow actions from here. 3. Provide the following information: Ticket Type Select the ticket type for the drop-down. You can choose from Service Request, Incident, Problem, Incident, Change, or Task. Special Function Name (Optional) Select an option from the drop-down. The special function is a back-end action that is executed on the ticket when the workflow action applies. Specify a name for the workflow action. The name that you specify here displays in the Actions dropdown on the ticket. Sort Order Select a sort order to control the order in which the workflow action appears on the ticket. Description (Optional) Specify a brief description for the workflow action. Web Service Operations Click the lookup icon to view a list of web service operations that you can relate to the workflow action. The lookup displays that web service operations that you have configured for the selected ticket type. 4. Click Apply Changes. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 27
Relate Web Service Configurations to Workflow Actions The workflow action is created and the web service operation is related to the workflow action. You can now configure matching conditions to define when the workflow action becomes available on the selected ticket. You can also configure the field values that get set when the workflow action is taken on the ticket. You can also define required fields and associate a communication template to the ticket. 5. (Optional) Define the Matching Conditions. You can set the Match Type as Include or Exclude and select the fields and the field values that apply. 6. (Optional) Define the Set Fields. You can select the field names and can define the field values that get set when the workflow action applies to the ticket. 7. (Optional) Define the Required Fields. You can select the fields where a value is required before the analyst takes the workflow action on the ticket. 8. (Optional) Associate a communication template. You can relate a communication template that is used to send notifications when the analyst takes the workflow action on the ticket. 9. Click Permissions, and then click Manage Permissions to view the permissions editor. You can assign access to the workflow action to different support groups and roles. The analysts from the support groups or roles with the permission to the workflow action can now see the workflow action on the ticket. When you configure matching conditions, the workflow action displays on tickets that meet the matching conditions. When you do not configure any matching conditions, the workflow action displays on all tickets of the selected ticket type. 28 Configure Outbound Web Services
Verify the Configurations Verify the Configurations You can verify the configurations to confirm that the configurations work as desired. To verify the configuration, you need access to both CA Nimsoft Service Desk and the third-party application that you have configured the outbound web services for. Consider the following example. You configure outbound web service to communicate with CA Service Desk Manager. You want the creation of a new Service Request in CA Nimsoft Service Desk to result in the creation of an Incident in CA Service Desk Manager. To enable the communication, you configure the web service credentials for CA Service Desk Manager. Then you configure the web service operation to create an incident in CA Service Desk Manager. You configure the Outbound Mapping to take the ticket details field to update the corresponding ticket details field in CA Service Desk Manager. Configure the field mapping to update custom fields in CA Nimsoft Service Desk with the ticket number for the ticket that gets created in CA Service Desk Manager. Next configure a workflow action CASD_Create Ticket and relate it to the Web Service Operation. Assign the L1 support group permission to the workflow action. To check the configurations, submit a ticket and use the work action to move the ticket through the workflow. All web service operations are recorded on the ticket board. You can see the web service operation that was executed, the start time and the end time, and the status of the operation. When the web service operation fails, the trace log message provides more information on the cause of failure. Follow these steps: 1. Log in to CA Nimsoft Service Desk as an analyst. 2. Click Workspaces and click My Tickets. You can log a new service request and can confirm that an incident gets created in CA Service Desk Manager. 3. Click Actions and click Create Request. A blank Service Request displays in a new tab. The Requester information displays the name of the logged-in user. 4. Provide basic information such as Details and Description in the About section of the ticket. 5. Click Actions and click CASD_Create Ticket. Note: If the CASD_Create Ticket action does not display, check that the logged-in analyst has permission to the action. Click Manage Workflow Action in the Workflow Tools navigation menu option and locate the workflow action to check the permissions. The page refreshes and the ticket number displays. The summary section, ticket board, and other sections display. You can check the board to see that the web service operation was executed. Chapter 2: How to Configure Outbound Web Services to Communicate with External Applications 29
Verify the Configurations 6. Log in to CA Service Desk Manager using appropriate credentials. 7. Navigate to the ticket list and search for newly created tickets. If the ticket list displays a ticket with the same details as the CA Nimsoft Service Desk ticket, you have successfully configured the outbound web service call. You can navigate back to the ticket in CA Nimsoft Service Desk and can check the ticket board for more details. 30 Configure Outbound Web Services