Table Of Contents
Cisco IP Phone Services Application Development Notes
Use this document with Cisco CallManager 3.1 to develop and deploy customized client services for the Cisco IP Phone 7960 and 7940 models, which support Cisco IP phone services.
Note Developers and Cisco CallManager administrators who want to create applications for Cisco IP phone services have the eXtensible Markup Language (XML) Application Programming Interface (API) described in this document available. Developers using this guide should join the Cisco Developer Support Program because standard Cisco TAC support is limited to the Cisco AVVID installation/configuration and Cisco-developed applications. This program will provide you with a consistent level of support that you can depend on while leveraging Cisco interfaces in your development projects. For more information about the program and how to join, contact us at email@example.com.
This document covers the following topics:
You can use Cisco IP phones, such as the Cisco IP Phone 7960 and 7940, to deploy customized client services with which users can interact via the keypad and display. Services deploy using the HTTP protocol from standard web servers, such as Microsoft IIS. This document provides the information needed for XML programmers and system administrators to develop and deploy new services.
Note Currently, only Cisco IP Phone 7960 and 7940 models support Cisco IP phone services. Throughout this document, the term "Cisco IP phone" applies only to the Cisco IP Phone 7960 and 7940.
Cisco IP phones have buttons labeled services and directories. When a user presses the services button, a menu of services that are configured for the phone displays. The user then chooses a service from the listing, and the phone display updates.
The following list gives typical services that might be supplied to a phone:
Figure 1 shows a sample text menu created during development.
Figure 1 Cisco IP Phone Text Menu Sample
Cisco IP phones can also display graphic menus, as shown in Figure 2.
Figure 2 Graphic Menu on a Cisco IP Phone Sample
The way that a service is configured determines whether a graphic or text menu displays.
A phone user can navigate a text menu using the up/down rocker switch followed by the Select soft key, or by using the DTMF keypad to enter a selection directly. Graphic menus do not currently support any type of cursor-based navigation; users simply enter a numeric item selection using the DTMF keypad.
When a menu selection is made, the Cisco IP phone acts on it by using its HTTP client to load a specific URL. The return type from this URL can be plain text or one of the
CiscoIPPhoneXML objects. The object loads and then interacts with the user in an appropriate manner for the object.
Figure 3 Plan Text Display Example
Figure 4 displays a graphic image.
Figure 4 Graphic Image Display Example
Cisco CallManager limits Cisco IP phone service activity to a specific Services pane in the Cisco IP phone display. A service cannot modify the top line of the phone display, which contains the time, date, and primary extension. A service cannot overwrite the bottom line of the display, which contains soft key definitions. The pane that displays the service sits flush with the left side of the display, and enough of the right side of the display remains intact to ensure that users can see the status of phone lines.
Note HTML Disclaimer: Phone service developers must take into consideration that the phone is not a web browser and cannot parse HTML. Although content is delivered to the phone through HTTP messages using a web server, keep in mind that the content is not HTML. All content comes either as plain text or packaged in proprietary XML wrappers.
Cisco IP Phone XML Object Definitions
Creating interactive service applications proves relatively easy once you understand the XML objects that are defined for Cisco IP phones and the behavior that each object generates.
Regarding services, understand that the phone does not have any concept of a state when it loads an XML page. Cisco IP phones can use HTTP to load a page of content in many different places, starting when the services button is pressed. Regardless of what causes the phone to load a page, the phone always behaves appropriately once it loads a page.
Appropriate behavior depends solely on the type of data that has been delivered in the page. This section of the document discusses the supported XML display types and how they work with Cisco IP phones.
Refer to the "MIME Type and Other HTTP Headers" section for more information.
The following sections provide definitions and descriptions of each Cisco IP phone XML object:
CiscoIPPhoneGraphicMenu, CiscoIPPhoneIconMenu, CiscoIPPhoneExecute, CiscoIPPhoneErrorand
A menu on the phone comprises a list of text items, one per line. Users choose individual menu items using the exact same mechanisms that is used for built-in menus in the phone, such as those seen in the Cisco IP phone settings pages.
Definition<CiscoIPPhoneMenu><Title>Title text goes here</Title><Prompt>Prompt text goes here</Prompt><MenuItem><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position></SoftKeyItem></CiscoIPPhoneMenu>
Note The Name field under the <MenuItem> now supports 64 characters. This field can also accept two carriage returns to allow the MenuItem name to span three lines on the display.
The XML format allows you to specify a title and prompt that are used for the entire menu, followed by a sequence of
MenuItemobjects. Cisco IP phones allow a maximum of 100
Nameand an associated
When a menu is loaded, the phone behaves exactly the same as for built-in phone menus. The user navigates through the list of menu items and eventually chooses one using either the Select soft key or the DTMF keys.
After the user chooses a menu option, the phone generates an HTTP request for the page with the URL or executes the uniform resource identifiers (URIs) associated with the menu item.
CiscoIPPhoneTextXML object displays ordinary 8-bit ASCII text on the phone display. The <Text> message must not contain any control characters, except for carriage returns, line feeds, and tabs. The Cisco IP phone firmware controls all other pagination and wordwrap issues.
Note The Cisco IP phone now supports the full ISO 8859-1 (Latin 1) character set.
Definition<CiscoIPPhoneText><Title>Title text goes here</Title><Prompt>The prompt text goes here</Prompt><Text>The text to be displayed as the message body goes here</Text><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneText>
Two optional fields can appear in the XML message:
•The first optional field,
Title, defines text that displays at the top of the display page. If a
Titleis not specified, the
Namefield of the last chosen
MenuItemdisplays in the
•The second optional field,
Prompt, defines text that displays at the bottom of the display page. If a
Promptis not specified, Cisco CallManager clears the prompt area of the display pane.
Many XML objects that are described in this document also have
Promptfields. These fields normally behave identically to behavior described in this section.
The display shown in Figure 3 provides an example of a text display. The title appears at the top above the text.
Note Non-XML Text: This document only describes the supported Cisco IP XML objects. You can also deliver plain text via HTTP. Pages delivered as MIME type text/html behave exactly the same as XML pages of type
CiscoIPPhoneText. The only important difference is that you cannot include a title or prompt.
Note Keypad navigation: Cisco IP phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. When a menu is on the display, the actual number to be pressed displays on the left side of the screen.
When normal text displays, the numbers do not display on the left side of the screen, but the navigation capability still exists. So, a carefully written text service display can take advantage of this capability.
When a Cisco IP phone receives an XML object of type
CiscoIPPhoneInput, it constructs an input form and displays it. The user then enters data into each input item and sends the parameters to the target URL. Figure 5 shows a sample display that is receiving input from a user.
Figure 5 Sample User Input Display
Definition<CiscoIPPhoneInput><Title>Directory title goes here</Title><Prompt>Prompt text goes here</Prompt><URL>The target URL for the completed input goes here</URL><InputItem><DisplayName>Name of the input field to display</DisplayName><QueryStringParam>The parameter to be added to the target URL</QueryStringParam><DefaultValue>The default display name</DefaultValue><InputFlags>The flag specifying the type of allowable input</InputFlags></InputItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneInput>
Prompttags in the object delimit text that is used in the same way as the identical fields in the other Cisco IP phone XML objects.
URLtag delimits the URL to which the input results are sent. The actual HTTP request sent to this server specifies the URL with a list of parameters appended to it as a query string. The parameters include Name/Value pairs, one for each input item.
Note Cisco IP phones do not use the HTTP POST method.
InputItemtag delimits each item in the list. The number of
InputItemsmust not exceed five. Each input item has a
DisplayName, which is the prompt written to the display for that particular item. Each item also has a
QueryStringParam, which is the name of the parameter appended to the URL when it is sent out after input is complete. Each input item can also use the
DefaultValuetag to set the default value to be displayed.
The final item for each input item comprises a set of
InputFlags. The following table describes the input types that are currently defined.
During text entry, Cisco IP phones display soft keys to assist users with text entry. At this time, the following soft keys operate:
Indicates that the form is complete and that the resulting URL should be requested via HTTP.
Backspaces within a field.
Cancels the current input.
Users can navigate between fields with the vertical scroll button that is used to navigate menus, and so on.
The phone actually incorporated the
CiscoIPPhoneDirectoryXML object to support the Directory operation of Cisco IP phones. Because the functionality already exists in the phone, phone service application developers have it available as well. Figure 6 shows how an XML
CiscoIPPhoneDirectoryobject displays on the phone.
Figure 6 CiscoIPPhoneDirectory Object Display Sample
Definition<CiscoIPPhoneDirectory><Title>Directory title goes here</Title><Prompt>Prompt text goes here</Prompt><DirectoryEntry><Name>The name of the directory entry</Name><Telephone>The telephone number for the entry</Telephone></DirectoryEntry><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position><SoftKeyItem></CiscoIPPhoneDirectory>
Note For the directory listing, the Cisco IP phone displays the appropriate soft keys that are needed to dial the numbers listed on the display. The soft keys include the Edit Dial soft key, which allows users to insert access codes or other necessary items before dialing.
Prompttags in the XML object have the usual semantics. A single
CiscoIPPhoneDirectoryobject can contain a maximum of 32
DirectoryEntryobjects. If more than 32 entries must be returned, use multiple
CiscoIPPhoneDirectoryobjects in subsequent HTTP requests.
You can use the "URL Directories" enterprise parameter and Cisco IP phone XML objects to display custom directories.
The Cisco CallManager enterprise parameter "URL Directories" points to a URL that returns a
CiscoIPPhoneMenuobject that extends the directories menu. The request for "URL Directories" must return a valid
CiscoIPPhoneMenuobject, even if has no
You must use the following optional objects, if used, in the order in which they are listed:
CiscoIPPhoneInputXML object to collect search criteria.
CiscoIPPhoneTextXML object to display status messages or errors.
CiscoIPPhoneDirectoryXML object to return a list of directory entries that can be dialed.
You can omit the
CiscoIPPhoneTextobjects. You can display multiple
CiscoIPPhoneDirectoryobjects by specifying an HTTP refresh header that points to the URL of the next individual directory object, which the user accesses by pressing the Next soft key on the phone.
Cisco IP phones include a bitmap display with a 133 x 65 pixel pane that is available to access services. Each pixel includes four greyscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white.
Note The phone uses an LCD display, which explains why the palette is inverted.
CiscoIPPhoneImageXML type lets you use the Cisco IP phone display to present graphics to the user. Figure 4 shows an example of how this looks on the current release of the Cisco IP phone.
Definition<CiscoIPPhoneImage><Title>Image title goes here</Title><Prompt>Prompt text goes here</Prompt><LocationX>Position information of graphic</LocationX><LocationY>Position information of graphic</LocationY><Width>Size information for the graphic</Width><Height>Size information for the graphic</Height><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data><SoftKeyItem><Name>Name of the soft key</Name><URL>URL of soft key</Name><Position>Numerical position of the soft key</Position><SoftKeyItem></CiscoIPPhoneImage>
CiscoIPPhoneImageobject definition includes two familiar elements:
Prompt. These elements serve the same purpose as they do in the other Cisco IP phone XML objects. The
Titledisplays at the top of the page, and the
Promptdisplays at the bottom.
LocationYto position the graphic on the phone display. Position the upper, left corner of the graphic at the pixel defined by these two parameters. Setting the X and Y location values to (0, 0) positions the graphic at the upper, left corner of the display. Setting the X and Y location values to (-1, -1) centers the graphic in the services pane of the phone display.
Self-explanatory values include
Height. If the values specified do not match up properly with the pixel stream specified in the
Datafield, unpredictable and generally incorrect results occur.
Depthspecifies the number of bits per pixel. Cisco IP phones only support a value of 2.
Datatag delimits a string of hexadecimal digits that contain the packed value of the pixels in the display. In the Cisco IP phone, each pixel comprises only four possible values, which means that you can pack four pixels into a single byte. A pair of hexadecimal digits represents each byte.
Figure 7 provides an example of the mechanics of pixel packing. Scanning from left to right in the display, the illustration shows the process for packing consecutive pixel values of 1, 3, 2, and 0. First, the pixels get converted to 2-bit binary numbers. Then, the binary pairs get re-ordered in sets of four to create a single re-ordered byte, which two hexadecimal digits represent.
Figure 7 Packed Pixel Translation Example
The following XML code defines a
CiscoIPPhoneImageobject that displays the sequence of pixels shown in Figure 7 as a graphic positioned at the center of the phone display:<CiscoIPPhoneImage><Title/><LocationX>-1</LocationX><LocationY>-1</LocationY><Width>4</Width><Height>1</Height><Depth>2</Depth><Data>2D</Data><Prompt/></CiscoIPPhoneImage>
The graphic display comprises a contiguous stream of hexadecimal digits, with no spaces or other separators. If the number of pixels to be displayed does not represent an even multiple of four, pad the end of the pixel data with blank (zero value) pixels, so the data is packed correctly. The phone ignores the padded data.
Tip When graphics display on a Cisco IP phone, the software clears the pane dedicated to services before a graphic image displays. If a service has text or other information that must be preserved, the information must get redrawn as part of the graphic.
This includes the title area. If the title is to be hidden, the graphic must be large enough to cover it.
Graphic menus serve the same purpose as text menus: they allow a user to select a URL from a list. Use graphic menus in situations when the items may not be easy to display in a text list. For example, users might prefer to have their choices presented in a non-ASCII character set such as Kanji or Arabic. Figure 2 shows a graphic menu on a Cisco IP phone.
In these cases, the system presents the information as a bitmap graphic. The user then enters a menu selection by using the DTMF keypad to enter a number.
Definition<CiscoIPPhoneGraphicMenu><Title>Menu title goes here</Title><Prompt>Prompt text goes here</Prompt><LocationX>Position information of graphic</LocationX><LocationY>Position information of graphic</LocationY><Width>Size information for the graphic</Width><Height>Size information for the graphic</Height><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data><MenuItem><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL of soft key</URL><Position>Numerical position of the soft key</Position><SoftKeyItem></CiscoIPPhoneGraphicMenu>
Menu items in the graphic menu have a name, just like the text menu counterparts. Although the name does not display to the user, it still performs a function. The name of the menu item provides the default title used when the URL for the chosen item is loaded. If the loaded page has a title of its own, the phone uses that title instead.
The XML tags in GraphicMenu use the tag definitions for
CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can have only 12
MenuItemobjects in a
CiscoIPPhoneGraphicMenuobject. Refer to the "CiscoIPPhoneMenu" section and "CiscoIPPhoneImage" section for detailed descriptions.
Icon menus serve the same purpose as text menus: they allow a user to select a URL from a list. Use icon menus in situations when you want to provide additional visual information to the user to show the state or category of an item. Having a read and unread icon in a mail viewer serves as an example. The icons can convey the message state with the icon.
Figure 8 shows an IconMenu on a Cisco IP phone.
Figure 8 IconMenu on a Cisco IP Phone Sample
In these cases, the system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items that are the same as a CiscoIPPhoneMenu object.
Definition<CiscoIPPhoneIconMenu><Title>Title text goes here</Title><Prompt>Prompt text goes here</Prompt><MenuItem><IconIndex>Indicates what IconItem to display</IconIndex><Name>The name of each menu item</Name><URL>The URL associated with the menu item</URL></MenuItem><SoftKeyItem><Name>Name of soft key</Name><URL>URL or URI of soft key</URL><Position>Position information of the soft key</Position></SoftKeyItem><IconItem><Index>A unique index from 0 to 9</Index><Height>Size information for the icon</Height><Width>Size information for the icon</Width><Depth>Number of bits per pixel</Depth><Data>Packed Pixel Data</Data></IconItem></CiscoIPPhoneIconMenu>
The XML tags in IconMenu use the tag definitions for CiscoIPPhoneImage and CiscoIPPhoneMenu. Although the semantics of the tags are identical, you can only have 32 MenuItem objects in a CiscoIPPhoneIconMenu object. Refer to the "CiscoIPPhoneMenu" section and "CiscoIPPhoneImage" section for detailed descriptions.
The CiscoIPPhoneExecute object differs from the other CiscoIPPhone objects. You use this object to push a request to the phone via its web server. You must use the HTTP POST method to submit the object to the phone.
You post the CiscoIPPhoneExecute object to a case-sensitive URL. The URL http://x.x.x.x/CGI/Execute, replaces the x.x.x.x with the IP address of the destination Cisco IP phone. The form that you post should have a form field called "XML" that contains the XML object that you are posting. You can post multiple requests in a single object and receive a ResponseItem for each ExecuteItem.
When posting a CiscoIPPhoneExecute object to a phone you must provide basic HTTP authentication information with the POST. The credentials that you provide must be that of a user in the global directory with a device association with the target phone. If the credentials are invalid, or the Authentication URL is not set properly in the Cisco CallManager administration, the phone will return a CiscoIPPhoneError with a value of 4 (Authentication Error).
Note Limit the requests to three ExecuteItems: one URL and two URIs per CiscoIPPhoneExecute object.
Definition<CiscoIPPhoneExecute><ExecuteItem URL="the URL or URI to be executed"/><CiscoIPPhoneExecute>
ResponseItems exist for all ExecuteItems that you send. The order differs according to completion time. The URL specifies the URL or URI that was sent with the request. The Data field contains any special data for the item. Status specifies a status code. A "0" indicates that no error occurred during processing of the ExecuteItem. If an error occurred, the phone returns a CiscoIPPhoneError object.
Definition<CiscoIPPhoneResponse><ResponseItem Status="the success or failure of the action" Data="the information returned with the response" URL="the URL or URI specified in the Execute object"/><CiscoIPPhoneResponse>
The following list gives possible CiscoIPPhoneError codes:
•Error 1 = Error parsing CiscoIPPhoneExecute object
•Error 2 = Error framing CiscoIPPhoneResponse object
•Error 3 = Internal file error
•Error 4 = Authentication error
Cisco IP Phone XML Object Quick Reference
Table 1 provides a quick reference of the Cisco IP phone XML objects and the definitions associated with each.
Custom Soft Keys
Cisco IP phones now have the ability to receive custom soft keys with the CiscoIPPhone objects. Soft keys can have URLs or URIs associated with them. Newly created URIs allow you to call the native softkey event with a custom soft key.
This section describes objects that you use in what context with nonstreaming URIs and what, if any, comprise the object order requirements.
The following list contains the XML objects that can be used:
The default softkey name as it appears on the object type in question provides basis for SoftKey URIs. Valid SoftKey URIs for each object type follow:
Generic URIs that can be used in place of URLs follow:
•Dial:2000 (where 2000 represents the number to be dialed)
•EditDial:2000 (where 2000 represents the number to load into the edit dial context)
It is possible to invoke RTP streaming via URIs in services. You can instruct the phone to transmit or receive an RTP stream with the following specifications.
The RTP information for the stream types follow:
•The codec specifies G.711 mu-Law.
•The packet size specifies 20 ms.
Transmit RTP (RTPTx)
Transmit RTP Stream (RTPTx://x.x.x.x:xxxx) indicates the IP address to which the phone streams, followed by the destination port. Transmit requires the port.
Note If you specify a port, you must make it between 5000 and 8000 hexadecimal.
You can stop transmitting RTP with the following URI:RTPTx:Stop
Receive RTP (RTPRx)
Receive RTP Stream (RTPRx://x.x.x.x:xxxx) indicates the IP address from which the stream is coming and on what port the phone should listen. If the port is not specified (the recommended method), the phone chooses a port and returns it in the data section of the Response Object. You need the ability to specify a port for streaming URIs that are inside of service objects that are not pushed to the phone.
You can stop receiving RTP with the following URI:RTPRx:Stop
Cisco IP Services Software Development Kit (SDK)
The Cisco IP Services Software Development Kit (SDK) contains everything that is needed to create XML applications, including necessary documentation and sample applications.
The following list contains the components included in the SDK:
–Cisco IP phone Services Application Development Notes (this document) in Adobe .pdf format
–Cisco URL Proxy Guide in rich text format
–Cisco LDAP Programming Guide in Microsoft Word format
–Cisco CIP Image Release Notes in Microsoft Word format
–Cip.8bi—Photoshop plug-in that allows .cip extensions to be viewed and saved.
–Cip2Gif.exe—DOS-based program that converts .cip files to .gif.
–Gif2Cip.exe—DOS-based program that converts .gif files to .cip.
–ImageViewer.exe—Windows application that displays .cip graphic files.
–Cisco URL Proxy—Proxy server that is needed to use the sample services (automatically installed).
–Cisco LDAP Search—Service that is installed to do LDAP searches (automatically installed).
•Calendar—A graphical calendar
•LDAP—www interface for Cisco LDAP Search
•Real-time Stock Ticker—Stock quote
•Stock Chart—Stock graphic that charts a stock symbol
•Airline flight information
•Foreign currency exchange
–Windows Scripting (WSH)
•Cip—A command line windows scripting graphic conversion example using ActiveX.
Sample Services Requirements
The following list contains the items that are required for the sample services to work properly:
•Cisco IP 7940/7960 IP Phone
•Microsoft IIS 4.0 or higher (for sample services)
•Windows Scripting (for WSH example code)
The setup program installs a CiscoServices web project to c:\CiscoIpServices directory. The sample services get copied to the c:\CiscoIpServices\Services subdirectory, and IIS and WSH example codes are provided. The web server already senses these services; you need no further administration. You can view or edit all the source code with any text editor. The c:\CiscoIpServices\Documentation directory provides further documentation. Find tools to help develop services in c:\CiscoIpServices\Tools.
The XML parser in Cisco IP phones does not function as a fully capable XML parser. Do not include any tags other than those defined here in your XML display definitions.
Mandatory Escape Sequences
By XML convention, the XML parser also requires that you escape a few special characters. Table 2 lists characters and their escaped values.
Table 2 Escape Sequences for Special Characters
Character Name Escape Sequence
Left angle bracket
Right angle bracket
Escaping text can be tedious, but some authoring tools or scripting languages can automate this task.
HTTP Client Requests
The following procedure designates how HTTP client requests are handled:
•The Cisco IP phone HTTP client performs an HTTP GET for a specified URL.
•The HTPP server processes request and returns an XML object or plain text.
•The phone processes the supported HTTP headers.
•The phone parses the XML object if ContentType is
•The phone presents data and options to the user per the server response.
HTTP Header Settings
The following list provides definitions for HTTP header elements for Cisco IP phone services:
•"Refresh" (Time in Seconds, URL)
–If no time is set or it is zero, the refresh gets set to manual.
–If no URL is set, the current URL gets used.
Refer to the "HTTP Refresh Setting" section for details.
•"ContentType" — The ContentType notifies the phone of the MIME type that was sent. Refer to the "MIME Type and Other HTTP Headers" section.
•"Expires" — Expires sets the Date/Time in GMT when the page is to expire.
Pages that have expired before being loaded do not get added to the URL stack in the phone. The phone does not cache content. Refer to the "Content Expiration Header Setting" section for more information.
HTTP Refresh Setting
The HTTP headers that are sent with any page from an HTTP server can include a Refresh setting. This setting comprises two parameters: a time in seconds and a URL. These two parameters direct the recipient to wait the time given in the seconds parameter and then get the data to which the URL points.
The Cisco IP phone HTTP client properly supports this setting, which gives a great deal of power to service developers. It means that a new page can replace any XML object that displays after a fixed time.
Figure 9 shows a good example of how to use the refresh setting. This sample page shows the current value of Cisco stock to the user. It first brings up a splash screen that displays the Yahoo logo. After a very short time, it displays the numeric Cisco stock parameters. Finally, it shows a graph of Cisco intraday stock performance. The display then repeatedly cycles between the final two views.
Figure 9 Refresh Display Sample
Refreshing the display can occur without user intervention, as the display automatically cycles if a timer parameter is specified. However, on any given screen, the user can force an immediate reload by pressing the Update soft key. Also, if a timer parameter of 0 was sent in the header, the page never automatically reloads. In this case, the display will move to the next page only when the Update soft key is pressed. If no refresh URL is specified, the current page gets reloaded.
MIME Type and Other HTTP Headers
Usually, you can set the MIME type for pages in any web server by simply performing an association to the .xml file extension. Your web server documentation should explain how to accomplish this. This action allows you to serve static pages without the need for writing script.
If you want to deliver dynamic content using the other supported HTTP headers, you will need to understand how to generate the HTTP headers using the desired programming language and have common gateway interface (CGI) or script access on the target web server.
Content Expiration Header Setting
The expiration header can control what URLs are added to the phone URL history. This behavior differs slightly from traditional web browsers but is implemented to perform the same function. Disable the back button functionality to avoid calling a URL twice.
This functionality allows you to make the content of any page that is sent to the phone expire. When a user presses the Exit soft key, the user goes back to the last URL that did not expire when it was loaded. This differs from traditional browsers by not considering the current freshness of the data but the freshness of the data when the URL was requested. This requires you to have a page expire when it is first loaded and to not set a time and date in the future.
The "Expires" property specifies the number of minutes to wait for the content to expire. Setting this value to -1 subtracts 1 minute from the request time and returns a date and time that have already passed.
IP Phone Service Administration and Subscription
Cisco CallManager administrators maintain the list of services to which users can subscribe. Add and administer Cisco IP phone services through Cisco CallManager Administration:
•To access phone service administration, open Cisco CallManager Administration and choose Feature > Cisco IP Phone Services.
•Phone services can have any number of parameters associated with them.
•You can specify phone service parameters as optional or required, depending on how the phone service application defines them.
•Users can subscribe to any service configured in their cluster.
•Service subscriptions currently occur on a device basis.
A URL constitutes the core of each service. When a service is chosen from the menu, the URL is requested via HTTP, and a server somewhere provides the content. The Service URL field shows this URL entry. For the services to be available, the phones in the Cisco CallManager cluster must have network connectivity to the server.
Where <servername> designates a fully qualified domain name or an IP address.
Adding a Phone Service
Figure 10 shows the pane that the administrator uses to add new services to the system:
•To access this pane in Cisco CallManager Administration, choose Feature > Cisco IP Phone Services.
•You can insert, update, or delete a service definition.
•After a service is inserted, you can insert, update, or delete service parameter definitions.
•When you delete a Cisco IP phone subscription, Cisco CallManager removes all service information, user subscriptions, and user subscription data from the database.
•The Update Subscriptions button rebuilds all user subscriptions if the service has been modified after subscriptions exist.
Caution Do not put Cisco IP phone services on any Cisco CallManager server at your site or any server associated with Cisco CallManager, such as the TFTP server or directory database publisher server. This precaution eliminates the possibility of errors in a Cisco IP Phone Service application having an impact on Cisco CallManager performance or interrupting call-processing services.
Figure 10 Adding a New Service in Cisco CallManager Administration
Defining IP Phone Service Parameters in Cisco CallManager Administration
Each service can have a list of parameters. You can use these parameters, which are appended to the URL when they are sent to the server, to personalize a service for an individual user. Examples of parameters include stock ticker symbols, city names, or user IDs. The service provider defines the semantics of a parameter. The Cisco IP Phone Service Parameter Configuration pane in Cisco CallManager Administration contains the following fields:
Tip If you change the service URL, remove a Cisco IP phone service parameter, or change the Parameter Name of a phone service parameter for a phone service to which users are already subscribed, be sure to click Update Subscriptions to update all currently subscribed users with the changes. If you do not do so, users must resubscribe to the service to rebuild the URL correctly.
Figure 11 displays an example Cisco IP phone Service Parameter Configuration pane in Cisco CallManager Administration.
Figure 11 Defining Service Parameters in Cisco CallManager Administration
User Service Subscription
User service subscriptions get configured with the CCMUser web site after the user has logged in and chosen a device.
The end user has a single list of services that are attached to an individual phone. The user configures this list of services via the user pages, which are also used to set speed-dial numbers and call-forwarding options. These password-protected pages get authenticated via the LDAP directory.
Users use these user configuration panes to assign values to the service parameters, allowing for personalization:
•The user can customize the name of the service when it displays on the services list.
•The user can enter any service parameters that are available for the chosen service.
•The user can review the description of each parameter.
•After all the required fields are set, the user can click Subscribe.
•A custom URL gets built and stored in the database for this subscription.
•The service then appears on the device services list.
Figure 12 Cisco CallManager User Subscription Screen
Figure 13 Personalizing a User Subscription
Figure 14 Personalizing a User Subscription Completed
The following tips apply to troubleshooting Cisco IP phone service applications:
•Microsoft Internet Explorer 5 or higher can display the XML source with its default style sheet.
•Understand that standard IP troubleshooting techniques are important for HTTP errors.
•Externally verify name resolution (Phone has DNS set).
•If DNS is suspected, use IP addresses in URLs.
•Browse the URL in question with IE5 or download and verify with Netscape.
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).
XML Parsing Errors
The following tips apply to troubleshooting XML parsing errors in Cisco IP phone services applications:
•Verify the object tags (the object tags are case-sensitive).
•Verify that "&" and the other four special characters are used per the restrictions while inside the XML objects. Refer to "Mandatory Escape Sequences" section.
Error messages appear on the prompt line of the Cisco IP phone display. Only two messages should appear:
XML Error = XML Parser error (Invalid Object)
•HTTP Error = Unknown HTTP Error
HTTP Error = HTTP Connection Failed
The following documents provide further information:
•Cisco CallManager Administration Guide (also available in the online help). Refer to the chapter on configuring Cisco IP phone services.
•Cisco CallManager System Guide
•Cisco IP Phone 7960/7940 Quick Start Guide
Provides instructions for users on subscribing to phone services.
•CiscoURLProxy ActiveX Component
Provided with the Cisco IP Services SDK.
•LDAP Search COM Server Programming Guide
Provided with the Cisco IP Services SDK.
•CipImage Release Notes
Provided with the Cisco IP Services SDK.
The following sections explain how to obtain documentation from Cisco Systems.
World Wide Web
You can access the most current Cisco documentation on the World Wide Web at the following URL:
Translated documentation is available at the following URL:
Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which is shipped with your product. The Documentation CD-ROM is updated monthly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual subscription.
Cisco documentation is available in the following ways:
•Registered Cisco.com users (Cisco direct customers) can order Cisco product documentation from the Networking Products MarketPlace:
•Registered Cisco.com users can order the Documentation CD-ROM through the online Subscription Store:
•Nonregistered Cisco.com users can order documentation through a local account representative by calling Cisco corporate headquarters (California, USA) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).
If you are reading Cisco product documentation on Cisco.com, you can submit technical comments electronically. Click the Fax or Email option under the "Leave Feedback" at the bottom of the Cisco Documentation home page.
You can e-mail your comments to firstname.lastname@example.org.
To submit your comments by mail, use the response card behind the front cover of your document, or write to the following address:
Attn: Document Resource Connection
170 West Tasman Drive
San Jose, CA 95134-9883
We appreciate your comments.
Obtaining Technical Assistance
Cisco provides Cisco.com as a starting point for all technical assistance. Customers and partners can obtain documentation, troubleshooting tips, and sample configurations from online tools by using the Cisco Technical Assistance Center (TAC) Web Site. Cisco.com registered users have complete access to the technical support resources on the Cisco TAC Web Site.
Cisco.com is the foundation of a suite of interactive, networked services that provides immediate, open access to Cisco information, networking solutions, services, programs, and resources at any time, from anywhere in the world.
Cisco.com is a highly integrated Internet application and a powerful, easy-to-use tool that provides a broad range of features and services to help you to
•Streamline business processes and improve productivity
•Resolve technical issues with online support
•Download and test software packages
•Order Cisco learning materials and merchandise
•Register for online skill assessment, training, and certification programs
You can self-register on Cisco.com to obtain customized information and service. To access Cisco.com, go to the following URL:
Technical Assistance Center
The Cisco TAC is available to all customers who need technical assistance with a Cisco product, technology, or solution. Two types of support are available through the Cisco TAC: the Cisco TAC Web Site and the Cisco TAC Escalation Center.
Inquiries to Cisco TAC are categorized according to the urgency of the issue:
•Priority level 4 (P4)—You need information or assistance concerning Cisco product capabilities, product installation, or basic product configuration.
•Priority level 3 (P3)—Your network performance is degraded. Network functionality is noticeably impaired, but most business operations continue.
•Priority level 2 (P2)—Your production network is severely degraded, affecting significant aspects of business operations. No workaround is available.
•Priority level 1 (P1)—Your production network is down, and a critical impact to business operations will occur if service is not restored quickly. No workaround is available.
Which Cisco TAC resource you choose is based on the priority of the problem and the conditions of service contracts, when applicable.
Cisco TAC Web Site
The Cisco TAC Web Site allows you to resolve P3 and P4 issues yourself, saving both cost and time. The site provides around-the-clock access to online tools, knowledge bases, and software. To access the Cisco TAC Web Site, go to the following URL:
All customers, partners, and resellers who have a valid Cisco services contract have complete access to the technical support resources on the Cisco TAC Web Site. The Cisco TAC Web Site requires a Cisco.com login ID and password. If you have a valid service contract but do not have a login ID or password, go to the following URL to register:
If you cannot resolve your technical issues by using the Cisco TAC Web Site, and you are a Cisco.com registered, you can open a case online by using the TAC Case Open tool at the following URL:
If you have Internet access, it is recommended that you open P3 and P4 cases through the Cisco TAC Web Site.
Cisco TAC Escalation Center
The Cisco TAC Escalation Center addresses issues that are classified as priority level 1 or priority level 2; these classifications are assigned when severe network degradation significantly impacts business operations. When you contact the TAC Escalation Center with a P1 or P2 problem, a Cisco TAC engineer will automatically open a case.
To obtain a directory of toll-free Cisco TAC telephone numbers for your country, go to the following URL:
Before calling, please check with your network operations center to determine the level of Cisco support services to which your company is entitled; for example, SMARTnet, SMARTnet Onsite, or Network Supported Accounts (NSA). In addition, please have available your service agreement number and your product serial number.
This document is to be used in conjunction with the documents listed in the "Related Documentation" section.
CCIP, the Cisco Powered Network mark, the Cisco Systems Verified logo, Cisco Unity, Follow Me Browsing, FormShare, Internet Quotient, iQ Breakthrough, iQ Expertise, iQ FastTrack, the iQ Logo, iQ Net Readiness Scorecard, Networking Academy, ScriptShare, SMARTnet, TransPath, and Voice LAN are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, Discover All That's Possible, The Fastest Way to Increase Your Internet Quotient, and iQuick Study are service marks of Cisco Systems, Inc.; and Aironet, ASIST, BPX, Catalyst, CCDA, CCDP, CCIE, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, the Cisco IOS logo, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Empowering the Internet Generation, Enterprise/Solver, EtherChannel, EtherSwitch, Fast Step, GigaStack, IOS, IP/TV, LightStream, MGX, MICA, the Networkers logo, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, RateMUX, Registrar, SlideCast, StrataView Plus, Stratm, SwitchProbe, TeleRouter, and VCO are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries.
All other trademarks mentioned in this document or Web site are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0203R)
Copyright © 2002, Cisco Systems, Inc.
All rights reserved.