|
|
Table Of Contents
Architecture for Troubleshooting XML Services
Parsing Issues and Syntax Errors
XML Services Troubleshooting
This chapter contains the following topics:
•
Overview
Overview
Extensible Markup Language (XML) services are applications for IP phones in Cisco CallManager environments. For example, an XML service can be used to display directory listings or to submit billing account numbers to be associated with calls. XML is a text-based markup language that is used to create documents that convey object information and the hierarchical structure of that information. XML services for IP phones can include the display of text or graphic information.
When an IP phone in a Cisco CallManager system uses a web-based XML service, it communicates with a web server using HTTP, the same protocol that PC web browsers use. Note that the applications themselves are written in XML and that Cisco IP phones do not understand HTML. For normal phone transactions, IP phones use other protocols to communicate. Messages between Cisco CallManager and an IP phone are sent using Skinny Client Control Protocol (SCCP). Voice packets are sent between phones connected in a call using Real-Time Transport Protocol (RTP), a UDP-based protocol especially designed for sending voice, video, and other time-sensitive data across packet networks.
An IP phone begins to invoke a service when the phone user presses the Services button. By default the Services button is assigned a URL that points to a web page called GetServicesMenu.asp on the Cisco CallManager server, although this default can be changed by using one of the Cisco CallManager administration screens.
The GetServicesMenu.asp web page displays a menu of phone services that have been specified for this phone. Each item on the service menu points to another URL on the web server where the XML application files for that service are stored. Figure 17 illustrates the life cycle of an XML phone service application.
For more information, refer to the " Cisco IP Phone Services" chapter of the Cisco CallManager System Guide and the " Cisco IP Phone Services Configuration" chapter of the Cisco CallManager Administration Guide.
Figure 17 XML Services Life Cycle
Architecture
This section describes the following XML services concepts:
•
XML Services Call Flow
HTTP call flows for XML services are shown in Figure 18. Services can be initiated by the user, by the phone, or by another service that the phone is already using.
Figure 18 HTTP Web Services Request Call Flow
User-Triggered Service
When a user initiates a phone service, the following call flow is observed:
1.
2.
3.
4.
5.
6.
Event-Triggered Service
When an event initiates a phone service, the following call flow is observed:
1.
2.
3.
4.
Architecture for Troubleshooting XML Services
Figure 19 shows the suggested architecture for troubleshooting XML services on Cisco CallManager networks, in which a packet sniffer is located at the switch. Typically, you collect sniffer traces by connecting a laptop or other sniffer-equipped device to a Catalyst port that is configured to span the VLAN or specific port(s), directly connected at the router, that contain the trouble information. If no free port is available, connect the sniffer-equipped device to a hub that is inserted between the switch and the device.
Figure 19 Architecture for Troubleshooting XML Services
Troubleshooting Tools
The following tools will help you troubleshoot problems with XML services.
•
Verifies authentication or connection issues to and from the XML services URL and the phone.
•
Allows you to analyze the syntax of the XML code and make changes where necessary.
•
Verifies exactly what data is being sent among the Cisco CallManager, the application server, and the phones.
•
Parses the XML content of a file or web page and authenticates it against a schema for Cisco IP phone XML objects. The XML Validator is a command-line tool that is available on a CD-ROM in the Cisco Press book called Developing Cisco IP Phone Services. Instructions for XML Validator can be found in Chapter 11 of that book. The following is an example of a validated file from Validator:
<?xml version="1.0"?><CiscoIPPhoneMenu><Title>Cisco Phones Are Great, Right?</Title><Prompt>What do you want to do today?</Prompt><MenuItem><Name>Yahoo</Name><URL>http://www.yahoo.com/index.html</URL></MenuItem></CiscoIPPhoneMenu>The following is an example of a validation error reported by Validator:
MS Parser reported this error:Code = 0xc00ce014Source = Line : b Char : 11Error Description = Element content is invalid according to the DTD/Schema.Expecting: Input Flags.Source text where the error occurred:<DefaultValue></DefaultValue>--------------^Troubleshooting Checklist
The following tips apply to troubleshooting Cisco IP phone service applications:
•
•
•
Use the following checklist for initial troubleshooting of common problems.
____ Ensure that the user is associated with the device. The username and password that are passed to Cisco CallManager for authentication must have a corresponding user who is associated with the device that will receive the PUSH. See "PUSH-Related Issues" .____ Check for parsing issues. See "Parsing Issues and Syntax Errors" .____ If the AXL client application is unable to connect to the AXL service, check the following:____ Ensure that the web service is reachable from the Cisco CallManager and the IP phone. From your web browser, type the URL of the web service page that has been configured in Cisco CallManager to confirm that the service is reachable. You can perform a quick check at the phone by pressing the Services button and selecting the service that has been configured.____ Externally verify the name resolution for URLs and whether the phone has DNS set. If DNS is suspected as a source of trouble, use IP addresses in URLs.____ Troubleshoot the PUSH-related issue. See "PUSH-Related Issues" .If you still cannot locate the root cause for your problem, examine some packets using the Packet Sniffer. Typically, you collect sniffer traces by connecting a laptop or other sniffer-equipped device to a Catalyst port that is configured to span the VLAN or specific port(s), directly connected at the router, that contains the trouble information. If no free port is available, connect the sniffer-equipped device to a hub that is inserted between the switch and the device.
To use the Packet Sniffer, perform the following steps:
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
When reporting a problem, be sure to have available the IP and MAC addresses of all equipment that is involved, such as IP phones, gateways, and Cisco CallManager servers.
Service Connection
Copy the service URL of your service as configured in Cisco CallManager and paste it into the web browser on your PC. Then analyze the response to determine whether the service can be reached.
Use a logged Telnet session to verify that the desired HTTP headers are returned. Telnet to the server on port 80; then, enter get /path/page.
PUSH-Related Issues
A PULL results from a request made at the phone, whereas a PUSH results from the web service initiating content to be sent to the phone. When troubleshooting PUSH problems, use the following simple HTML page to verify that the username and password are correct:
<HTML><HEAD></HEAD><BODY><FORM action="http://10.0.0.1/CGI/Execute" Method="POST"><TEXTAREA NAME="XML" Rows="20" Cols="80"><CiscoIPPhoneExecute><ExecuteItem Priority="0" URL="Play:chime.raw"/></CiscoIPPhoneExecute></TEXTAREA><BR><input type=submit value=POST></FORM></BODY></HTML>This HTML page provides a text area for entering the XML object to be PUSHed to the phone. You need to replace 10.0.0.1 in the example above with the IP address of your phone. When the POST button is clicked, the object will be PUSHed to the phone. The phone will then force the browser to authenticate, and a username and password window will open. After authenticating, the phone will return the <CiscoIPPhoneResponse> object, which will be viewable in the web browser if you are using an XML-capable browser, such as Internet Explorer 5 or a later version. Using this simple HTML page allows you to quickly rule out any authentication or XML parsing and validation issues with your application.
Parsing Issues and Syntax Errors
The XML Validator can be used to validate the syntax of the XML code as a first step.
When troubleshooting XML parsing errors, do not exceed the maximum field lengths allowed by the XML schema. For example, the <Title> and <Prompt> fields are each limited to 32 characters (31 characters in some older firmware loads). A good reference for XML syntax and restrictions can be found in the Cisco Press book Developing Cisco IP Phone Services. For more detailed information, refer to the Cisco IP Phone XML Schema file (xsd) that is included in SDK version 3.3(4) or later. This XML-standard schema file defines all of the details of the allowed XML objects and can be used with XML editing software packages to greatly simplify the process of creating and validating Cisco IP phone XML objects.
The following tips apply to troubleshooting XML parsing errors in Cisco IP phone services applications:
•
•
Table 2 Escape Sequences for Special Characters
Ampersand
&
&
Apostrophe
'
'
Left angle bracket
<
<
Right angle bracket
>
>
Quote
"
"
Error Reporting
When reporting problems with IP phone services (IPPS), be prepared to provide the following information:
•
•
•
•
•
Error and Status Codes
An error or status code is received by the XML application as an XML response from the web browser that is resident in the phone.
An XML error tag appears in the following format:
<CiscoIPPhoneError Number="x"/>The following error codes can result from a PUSH.
•
•
•
•
The following error messages may appear on the prompt line of the Cisco IP phone display.
•
•
•
Posted: Fri Sep 10 09:50:58 PDT 2004
All contents are Copyright © 1992--2004 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.
