Configure Outbound Web Services

This article contains the following topics:

Outbound web services enables Serviceaide Intelligent Service Management to interact with external systems using SOAP or RESTful web service calls. The outbound web service operation is linked to a workflow action. When an analyst executes the workflow action on a ticket, the outbound web service operation is initiated. If the external application returns a response to the web service call, the product accepts the response and updates the ticket accordingly.

As an administrator, you can configure web service adapters and can define the field mapping to enable exchange of data with external applications.

When you configure outbound web services, external applications can exchange data with the product without building a polling mechanism. You can set up the data exchange to update fields on the external application and on the application. The exchange of data happens in response to a call initiated by the product.

Complete the following tasks to configure your outbound web services.

Gather Prerequisite Information

To configure outbound web services for an external application, acquire basic understanding about the web services that it supports. Also identify the fields in the external application and the corresponding fields in the product.

Gather the credentials that are required to configure the outbound web service calls. The credentials vary depending on whether the external application uses SOAP or RESTful web services.

SOAP-based Web Service Calls

Intelligent Service Management uses Web Service Description Language (WSDL) to communicate with SOAP-based applications. The WSDL file of the external application contains the information that is required for configuring web service operations. The WSDL document contains information such as methods, field mapping, and more.

To access a web service, find its WSDL entry. The WSDL entry is generally a URL on the Web. Companies control the access to their WSDL files to different degrees. Contact the administrator of the external application for access.

RESTful Web Service Calls

The RESTful web service calls are not defined in a formal document. However, some external applications define the supported web services. You can find the supported operations in the Web Application Description Language (WADL) file of the application.

Usually, RESTful web service calls do not require any authentication. Contact the administrator of the external application, if the application requires authentication.

Gather the following prerequisite information to plan the outbound web services:

1. Validate that the external application offers web services. You cannot proceed if the external application does not offer web services.
2. Validate that the external application supports SOAP based or RESTful web service calls.
   • For an application that supports SOAP-based calls, 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 supporting the RESTful web service calls, determine whether the supported web services are defined. When the web services are defined, gather information about the path to the WADL entry. You can proceed without specifying the WADL path for undefined web services.
3. Validate that you are able to connect the product with the external application. Ping the external application server from the Intelligent Service Management web server. Check the result for any errors. You cannot proceed if the Intelligent Service Management web server is not able to connect to the external application.
4. Identify the URL that is invoked to access the WSDL/WADL entry for the external application. When you identify the URL, confirm the following requirements:
   • The access and authentication that is required to invoke the web service.
   • Confirm whether the external application requires basic authentication. Get the external application user name and password.
   • 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 the product. 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.

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 and the existing custom fields do not suffice, you can configure custom attributes. You can then relate the attributes to custom field templates. 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.

Note: Custom field mapping for Date field is not supported.

For more information about creating attributes, see Create and Manage Attributes.

For more information about creating custom field templates, see Create and Manage Custom Field Templates.

Enable Web Service Invocation

Follow these steps:

1. Navigate to WORKSPACES, ADMINISTRATION, Tools, Configuration Parameters.
2. In the Search field, search for the ENABLE_EXTERNAL_WEB_SERVICES_INVOCATION parameter.
3. Click the parameter name in the list, to view the details of the parameter.
4. Set the parameter value to Yes.

The product now supports exchange of data using outbound web service calls.

Configure Web Service Credentials

Intelligent Service Management uses web services credentials to connect to the external application for data exchange. You can create and manage credentials that are required to invoke the external web services for the data exchange. The same external web service credentials can be used for all authentication methods that the external application supports.

Follow these steps:

1. Navigate to WORKSPACES> ADMINISTRATION> Tools> Web Services Credentials.
   The Web Service Credentials tab displays. You can filter the list to see active or inactive credentials. You can modify an existing credential or can create credentials from here. You can provide the web service credentials for the external application here.
2. Provide the required information and click Save.

When you click Save, the Summary and Related Operations sections display.

Configure Web Service Operations for SOAP-based Calls

The web service operations enable the exchange of data between the product and the external application. After you configure the web service credentials, you can configure multiple operations using the methods that the external application supports.

Follow these steps:

1. Navigate to WORKSPACES, ADMINISTRATION, Tools, and select Web Services Operations.
2. Provide the name, description, and credentials for the external application.
3. Enter the field mapping details for the web service operation. Specify information such as:
   • The type of web service binding that is used for the operation.
   • The method that is used for the operation.
   • Operation timeout duration.
   • The ticket type for which this operation is available.

4. (Optional) Specify the Outbound Mapping. The value from the ticket field that you specify here populates the corresponding field in the external application.
   You can map the fields either through the XML file or through the drop-down fields.

   1. To use the XML file, select the Advanced Configuration check box. 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 use the same in the SOAP call request. Advanced Configuration includes 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, tokens can be inserted by placing a cursor or by selecting the text that needs to be 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.

   2. To specify the field mapping using the drop-down 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 Intelligent Service Management ticket field tokens to map the ticket field that gets updated when the web service operation executes on the ticket. You can use standard ticket fields, custom fields, or user tokens that you configure.
      Example: Standard ticket field ${description_long}
      Note: The fields that are displayed as required fields in the WSDL document, display in the External Field list by default.

5. (Optional) Specify the Inbound Mapping. The value from the external application is updated in the corresponding ticket field in the application. Mention the ticket field and the xpath to the field in the external application. You can also map up to ten display Entity Fields. The display entity fields provide extra information for reference purpose, but are not saved on the ticket. You can view the display entity fields on the ticket details page, in the Web Service Lookup attribute type.
   
6. Click Save.

The web service operation is configured.

You can now relate the web service operation to a workflow action.

Configure Web Service Operations for RESTful Calls

The web service operations enable the exchange of data between the product and the external application. After you configure the web service credentials, you can configure multiple operations using the methods that the external application supports.

Follow these steps:

1. Navigate to WORKSPACES, ADMINISTRATION, Tools, and select Web Service Operations.
2. Provide the name, description, and web service credentials for the external application.
3. Specify the field mapping details for the web service operation. Specify information such as:
   • Entity type of the operation or the applicable ticket type.
   • Endpoint address of the web service.
   • Method that is used for the operation.
   • Operation timeout duration.
4. (Optional) Specify the Outbound Mapping. The value from the ticket field that you specify here populates the corresponding field in the external application. When a WADL is configured for the web service, the external application values are rendered in a drop-down. The values that are rendered depend on the method that you select in the Select Method field. You can select a value from the drop-down to configure the outbound mapping. When a WADL is not configured, the fields display as text areas. You can enter the valid values manually. The fields that are displayed as required fields in the WADL document display in the external fields by default.
5. (Optional) To use the XML or JSON file, select the Advanced Configuration check box. You can provide the outbound field mapping by specifying the values at the relevant nodes. When you use Advanced Configurations, a text box displays to enter the XML or JSON content. 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 REST request XML or JSON, tokens are inserted by placing a cursor or by selecting the text that needs to be 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.
6. (Optional) Specify the Inbound Mapping. The value from the external application is updated in the corresponding ticket field in the product. Mention the ticket field and the path to the field in the external application.
   Note:
   • Do not use wildcard or operators characters in the XML search path for Inbound Mappings.

   • Verify that you have mapped only the required node of the response file to configure the Inbound Mapping value. For example, in the following code snippet, if you want to populate the attribute id, enter the node as employees.employee.id. Specifying the node as employees.employee will not populate any attribute.

     Code Block

     {
         "employees": {
             "employee": [
                 {
                     "id": "1",
                     "firstName": "Tom",
                     "lastName": "Cruise",
                     "photo": "http://cdn2.gossipcenter.com/sites/default/files/imagecache/story_header/photos/tom-cruise-020514sp.jpg"
                 }
              ]
         }
     }

7. Click Save.

The web service operation is configured.

You can now relate the web service operation to a workflow action.

Pass Custom Attributes in an Outbound Web Services Call

To pass all the custom attributes in a name-value pair, there is a specific token available in the Outbound web service operation.

As an example of what the outbound mapping must look like in the Web Sevice Operation:

{"summary":"${ticket_description}",
"description":"${description_long}",
"category":{"$(@COMMON_NAME" : "Facilities.Conference Room.Reservation"},
"properties":"${cf_all_custom_fields_in_a_ticket}"}

If the ticket has custom fields, while executing the web service operation the tokens will get replaced as below:

{"summary":"Summary for ticket",
"description":"Details of ticket",
"category":{"@COMMON_NAME":"Facilities.Conference Room.Reservation"},
"properties":{"collection":[
{"@COMMON_NAME":"Conference_Room_Name","value":"East"},
{"@COMMON_NAME":"Host_Employee_ID","value":"123"}
{"@COMMON_NAME":"Number_of_Attendees","value":"23"},
{"@COMMON_NAME":"Meeting_Start_Time","value":"12:00"},
{"@COMMON_NAME":"Meeting_End_Time","value":"12:30"}]}}

Relate Web Service Configurations to Workflow Actions

After you configure the web service operation, you can relate the operation to a workflow action. The application invokes the web service operation when the analyst executes the corresponding workflow action on a ticket.

You can relate a web service operation to a workflow action from WORKSPACES, ADMINISTRATION, Tools,  Workflow Actions page. Use the Web Service Operations field of a workflow action to relate the action to a web service configuration.

You can configure workflow actions using both SOAP and RESTful Web service calls.

For information about workflow actions, see Create and Manage Workflow Actions.

Verify the Configurations

To verify the configuration, you need access to both the product and the external application.

Consider the following example. You configure outbound web service to communicate with Service Desk Manager. You want the creation of a service request in Intelligent Service Management to result in the creation of an Incident in Service Desk Manager. To enable the communication, you configure the web service credentials for Service Desk Manager. Then you configure the web service operation to create an incident in Service Desk Manager. You configure the outbound mapping to make the ticket details field to update the corresponding ticket details field in Service Desk Manager.

Configure the field mapping to update the custom fields in the product with the details of the ticket in 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 verify 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, 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 about the cause of failure.

Follow these steps:

1. Log in to the application as an analyst.
2. Click WORKSPACES, SERVICE DESK,  Ticket Center.
3. Click Actions, Create Request.
4. Provide basic information such as details and description in the About section of the ticket.
5. Click Actions, CASD_Create Ticket (this action is the workflow action that you created).
6. Log in to Service Desk Manager using appropriate credentials.
7. Navigate to the ticket list and search for newly created tickets.

If the ticket list displays the corresponding incident ticket, the outbound web services call succeeded. You can navigate back to the ticket in the product to verify the ticket board for more details.