For cisco unified communications manager 9.0 (50 pages)
Summary of Contents for Cisco OL-18696-01
Page 1
Cisco Unified IP Phone Services Application Development Notes Supporting XML Applications Release 7.1(2) Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA 95134-1706 http://www.cisco.com Tel: 408 526-4000 800 553-NETS (6387) Fax: 408 527-0883 Text Part Number: OL-18696-01...
Page 5
C H A P T E R Accessing Phone Service Administration Adding a Phone Service Defining IP Phone Service Parameters User Service Subscription DeviceListX Report C H A P T E R Benefits Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 6
A P P E N D I X Cisco Unified IP Phone Services A P P E N D I X XML Schema File Updated XML Parser and Schema Enforcement CiscoIPPhone.xsd N D E X Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Use this document with Cisco Unified Communications Manager, Release 7.1(2) to develop and deploy customized client services for the Cisco Unified IP Phones that support Cisco Unified Phone services. Because of the complexity of a Unified Communications network, this guide does not provide complete and detailed information for procedures that you need to perform in Cisco Unified Communications Manager or other network devices.
Preface The Cisco TAC does NOT provide support for this API/interface under standard hardware or software Note support agreements. All technical support for this API/interface, from initial development assistance through API troubleshooting/bugs in final production apps, is provided by Cisco Developer Support and requires a separate Developer Support contract.
Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html...
Means the described action saves time. You can save time by performing the action described in Timesaver the paragraph. Means reader be warned. In this situation, you might perform an action that could result in Warning bodily injury. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
C H A P T E R Overview You can use Cisco Unified IP Phones 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.
Page 12
DTMF keypad. When a menu selection is made, the Cisco Unified 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 CiscoIPPhone XML objects.
Page 13
HTML. Although content is delivered to the phone through HTTP messages by 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 Unified IP Phone Services Application Development Notes OL-18696-01...
Page 14
Chapter 1 Overview Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Regarding services, the phone does not have any concept of a state when it loads an XML page. Cisco Unified 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 after it loads a page.
Page 16
CiscoIPPhoneError 1. The Cisco Unified IP Phone 7920G has only a 128-by-59 display with 2 grayscale images clipping the graphic equally on both sides and providing vertical scrolling. When an image with 4 grayscale settings occurs (<Depth>2</Depth>), the phone equally splits them into 2 grayscale settings (0-1 get treated as 0 and 2-3 get treated as 1).
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 objects. Cisco Unified IP Phones allow a maximum of 100 . Each MenuItem...
Note Keypad navigation: Cisco Unified IP Phones allow navigation to a specific line in a menu by pressing numeric DTMF keys. When a menu is on the display, the number for selecting the menu is on the left. When normal text displays, the numbers do not display on the left side of the screen, but the navigation capability still exists.
Page 19
Telephone number—enter only DTMF digits for this field. The acceptable input includes numbers, #, and *. Numeric—enter numbers as the only acceptable input. Equation—enter numbers and special math symbols. Uppercase—enter uppercase letters as the only acceptable input. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
(*). During text entry, Cisco Unified IP Phones display softkeys to assist users with text entry. Users can navigate between fields with the vertical scroll button that is used to navigate menus, and so on.
Each pixel includes four grayscale settings. A value of three (3) displays as black, and a value of zero (0) displays as white. The phone uses an LCD display, which inverts the palette. Note XML type lets you use the Cisco Unified IP Phone display to present graphics CiscoIPPhoneImage to the user. Definition <CiscoIPPhoneImage>...
Page 22
Height field, results will be unpredictable incorrect. Data specifies the number of bits per pixel. Cisco Unified IP Phones support a maximum value of 2. A Depth bit depth of 1 is black and white. tag delimits a string of hexadecimal digits that contain the packed value of the pixels in the Data display.
Page 23
1. Represents the size of the display that is accessible by Services—not the full resolution of the physical display. 2. The Cisco Unified IP Phones 7905 and 7912 have pixel-based displays, but they do not support XML images. If the number of colors in the image is not reduced to match the phone capabilities, the image will be dithered by the phone and yield less than desirable results in most cases.
Page 24
For example, using the value of 16 (4-bits per channel = 16 tones per channel) will correctly dither the color palette of the image for the best display results on the Cisco Unified IP Phone 7970G. Figure 2-4 shows a CiscoIPPhoneImageFile object on a Cisco Unified IP Phone 7970G display.
CiscoIPPhoneGraphicFileMenu Some of the Cisco Unified IP Phone models, such as the Cisco Unified IP Phone 7970G and Cisco IP Communicator, have pointer devices. The Cisco Unified IP Phone 7970G uses a touchscreen overlay on the display, and the PC-based Cisco IP Communicator uses the standard Windows mouse pointer.
Page 26
CiscoIPPhoneMenu pixels. Figure 2-6 shows an IconMenu on a Cisco Unified IP Phone. Figure 2-6 IconMenu on a Cisco Unified IP Phone Sample The system presents the information as a bitmap graphic to the left of the menu item text. The user selects menu items in the same way as a object.
<Name>The name of each menu item</Name> <URL>The URL associated with the menu item</URL> </MenuItem> <IconItem> <Index>A unique index from 0 to 9</Index> <URL>location of the PNG icon image</URL> </IconItem> </CiscoIPPhoneIconFileMenu> Cisco Unified IP Phone Services Application Development Notes 2-13 OL-18696-01...
Overview content. For example, using a smaller window for an application allows more content from the Overview to be displayed. Sizing the window occurs upon the reception of a CiscoIPPhoneStatus or CiscoIPPhoneStatusFile object with its associated PNG file. Cisco Unified IP Phone Services Application Development Notes 2-14 OL-18696-01...
Page 29
An exception is allowed for the Cisco Unified IP Phones 7940G/7960G due to resource constraints. For these phones, you should implement both the maximum size and minimum size windows ignoring all of the intermediate sizes.
CiscoIPPhoneStatus image instead of a grayscale CIP image for the graphics area. The maximum image size is 262 x 50 pixels for the Cisco Unified IP Phone 7970G, but differs for other phone models. See “Dynamic Sizing of the Application Status Window” section on page 2-14 for details.
The Idle Timer (along with an optional Idle URL) is defined globally in the Cisco Unified Communications Manager Administration Enterprise Parameters and can be overridden on a per phone basis in the Cisco Unified Communications Manager Device configuration.
CiscoIPPhoneError describe the nature of the error condition. Custom Softkeys Cisco Unified IP Phones can use custom softkeys with any of the displayable CiscoIPPhone XML objects, excluding the object which cannot control softkeys and the CiscoIPPhoneStatus object which is not displayable.
</SoftKeyItem> XML Considerations The XML parser in Cisco Unified IP Phones does not function as a fully capable XML parser. Do not include any tags other than those defined in your XML display definitions. All CiscoIPPhone element names and attribute names are case sensitive.
The following examples illustrate UTF-8 and ISO-8859-1 encoding, respectively: <?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="iso-8859-1" ?> For details on setting HTTP header encoding settings, see the “HTTP Encoding Header Setting” section on page 5-5. Cisco Unified IP Phone Services Application Development Notes 2-20 OL-18696-01...
The Application Event Handlers can be attached to a supported object by specifying the attributes: An Application URI with Priority=0 is not allowed in the Application Event Handlers (see “Application” Note section on page 4-17). Cisco Unified IP Phone Services Application Development Notes 2-21 OL-18696-01...
Page 36
This event handler cannot contain HTTP or Note HTTPS URLs. Note If a Notify URI is used as the event handler, a notification is sent with this default data: <notifyApplicationEvent appId="appId" type="closed"/> Cisco Unified IP Phone Services Application Development Notes 2-22 OL-18696-01...
The event handlers typically use the standard Notification framework (see “Notify” section on page 4-15), but they can also invoke most other URIs, with the exception of HTTP URLs. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
The port parameter, if startMediaResponse specified, must be an even number in the range of 20480-32768. <?xml version="1.0" encoding="UTF-8"?> <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Cisco Systems, Inc. (Cisco Systems, Inc.) --> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">...
DATA=<notifyMediaEvent type=”stopped” origin=”user”> <mediaStream id=”abc123”/> </notifyMediaEvent> Errors and Responses Error conditions and responses for the RTP Streaming API include: Applicable Condition Methods HTTP Result Code Type Data Authorization failed 401 (Authorization Failed) N/A Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 44
Resource DSP resources is Available available to handle the media Media cannot be stopMedia 400 (BadRequest) InvalidResourceID Unknown Media stopped because the Stream ID: specified stream ID <streamID> does not exist Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
These sections provide details about the available internal URIs: Supported URIs by Phone Model • Device Control URIs • • XML Displayable Object URIs Multimedia URIs • • Telephony URIs Application Management URIs • Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
1. Only supports one incoming and one outgoing unicast stream and does not support the Volume parameter for RTP Receive streams. 2. Requires Cisco Unified IP Phone firmware version 8.3(2) or later, which contains an updated XML parser. See the “Updated XML Parser and...
• Display The Display URI is available only on those Cisco Unified IP Phones that have a color backlight on the phone display, including the Cisco Unified IP Phone 7970G and 7971G-GE. Using the Display URI, you can control how long the backlight remains on or off.
Page 49
When the user performs an action with a softkey, you can either append a query string parameter to the URL of the highlighted MenuItem or append the query string parameter from the MenuItem to the URL of the softkey. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
• RTPMRx • RTPMTx • For some Cisco Unified IP Phone models, the RTP Streaming URIs have been deprecated by the RTP Note Streaming API. See the “RTP Streaming API” section on page 3-1. The supported format of the RTP stream is as follows: The codec is G.711 mu-Law.
The RTPRx URI instructs the phone to receive a Unicast RTP stream or to stop receiving Unicast or Multicast RTP streams. URI Formats RTPRx:i:p:v RTPRx:Stop Where i = the IP Address from which the stream is coming. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
If the optional volume parameter does not get included, the current volume setting on the phone gets used as the default. RTPMTx The RTPMTx URI instructs the phone to transmit a Multicast RTP stream. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Where f = the filename of a raw audio file in the TFTP path (such as Play:Classic2.raw). The audio files for the rings must meet the following requirements for proper playback on Cisco Unified IP Phones: Raw PCM (no header) •...
Telephony URIs Vibrate The Vibrate URI is available on the Cisco Unified IP Phones 7920G and 7921G wireless phone models, and it enables third-party applications to invoke the phone’s vibration capabilities for silent alerts, similar to the way in which the Play URI plays audible alerts. If the Vibrate parameters are not specified or if the device is unable to support custom Vibrate sequences, the device will execute its default vibrate sequence.
Page 56
Speaker button • Headset button • Handset hook switch • Normal menu item • Softkey item selection • URI Format EditDial:n Where n = the number dialed (such as EditDial:1000). Cisco Unified IP Phone Services Application Development Notes 4-12 OL-18696-01...
Page 57
Invalid URI URI is not supported 6 (Internal error) URI not found Unable to execute URI because there currently is no 6 (Internal error) No Active Call active (streaming) call Cisco Unified IP Phone Services Application Development Notes 4-13 OL-18696-01...
XSI objects that support action handlers (such as displayable XSI objects and RTP streams). For example, use the Notify URI to deliver notifications to back-end applications when an XSI application is closed or when an RTP stream is terminated. Cisco Unified IP Phone Services Application Development Notes 4-14 OL-18696-01...
Page 59
Host: myserver:8080 Content-Length: 23 DATA=myStreamStoppedData Called from RTP onStreamStopped Event Handler, no credentials, no data: • Notify:http:server:8080:path/streamhandler?event=stopped HTTP POST /path/streamhandler?event=stopped HTTP/1.1 Accept: */* Content-Type: application/x-www-form-urlencoded; charset=”UTF-8” Host: myserver:8080 Content-Length: 40 Cisco Unified IP Phone Services Application Development Notes 4-15 OL-18696-01...
The Application URI allows applications to request changes to their application or window state. Applications can request to change focus, to be minimized, or to be closed. Cisco Unified IP Phone Services Application Development Notes 4-16 OL-18696-01...
Page 61
If the requested application is open, but not currently active, this request will not succeed (error – response). This request will result in the application context (and all applications within that context) being closed. Cisco Unified IP Phone Services Application Development Notes 4-17 OL-18696-01...
Page 62
Invalid URI Unknown application ID 6 (Internal error) Unknown Application ID Request made to change state of an application that is 6 (Internal error) Application is not Active not current active Cisco Unified IP Phone Services Application Development Notes 4-18 OL-18696-01...
HTTP Client Requests (HTTP GET) The following description designates how HTTP client requests are handled: The Cisco Unified IP Phone HTTP client performs an HTTP GET for a specified URL. The HTTP server processes request and returns an XML object or plain text.
512 bytes. See the Cisco Unified Communications Manager JTAPI Developer Guide for more information. HTTP Header Settings The following list provides definitions for HTTP header elements for Cisco Unified IP Phone Services: “Refresh”—sets the refresh time (in seconds) and URL •...
URL points. The Cisco Unified 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.
When this MIME type is used, the body of the response should contain raw audio data in the same format that is used for custom Cisco Unified IP Phone rings. Refer to the chapter on “Custom Phone Rings” in the Cisco Unified Communications Manager System Guide (also available in the online help).
Set-Cookie: ASPSESSIONIDGQGQGRLS=OCPNMLFDBJIPNIOOKFNFMOAL; path=/ The Cisco Unified IP Phone can receive and use a total of four cookies per host per session and can store information for up to eight sessions at once. Each cookie can be up to 255 bytes in size. These cookies are available until the server terminates the session or the client session has been idle for more than 30 minutes.
HTTP Requests and Header Settings HTTP Header Settings Accept-Language Cisco Unified IP Phones populate the Accept-Language HTTP request header in compliance with the HTTP specification. For example, the Accept-Language value advertised by a phone configured for the English_United_States user locale would look like:...
IP phone to optimize the content returned to the phone. For example, if the requesting phone is a Cisco Unified IP Phone 7960, which cannot support color PNG images, the application server must be able to identify this and return a gray scale CIP image instead.
Cisco Unified IP Phones include proprietary content-types to indicate which XML objects are supported. These proprietary content-types all begin with x-CiscoIPPhone, to indicate Cisco Unified IP Phone XML objects, followed by a slash “/”, followed by either a specific XML object or a “*” to indicate all objects.
Page 71
The target URL of a phone push (HTTP POST) request. /CGI/Screenshot Returns an exact snapshot of the current phone display. The size and format of the image returned is model-specific. 1. Password-protected CGI script Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 72
Chapter 5 HTTP Requests and Header Settings Accessing IP Phone Information Cisco Unified IP Phone Services Application Development Notes 5-10 OL-18696-01...
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 Unified IP Phone services applications: •...
SoftKeyItem—The Position field is mandatory. If the Position field is not present, the updated XML parser will report an error. Error Messages The following error messages may appear on the prompt line of the Cisco Unified IP Phone display: • XML Error[4] = XML Parser error (Invalid Object) •...
Cisco IP Phone Services Software Development Kit (SDK) The Cisco IP Phone Services Software Development Kit (SDK) contains everything that you require to create XML applications, including necessary documentation and sample applications. Contact Cisco Developer Services to obtain the SDK at: http://developer.cisco.com/web/ipps...
MultiDirectory (ASP) – – Phone Push Step and Subsystem (Cisco Unified Contact Center Express / CRS) Sample Services Requirements The following list contains the items that are required for the sample services to work properly: Microsoft IIS 4.0 or later (for ASP sample services) •...
Page 78
Chapter 7 Cisco IP Phone Services Software Development Kit (SDK) Sample Services Requirements Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
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 Unified Communications Manager cluster must have network connectivity to the server.
Service Information Service Name Enter the name of the service as it will display on the menu of available services in Cisco Unified CM User Options. Enter up to 32 characters for the service name. ASCII Service Name Enter the name of the service to display if the phone cannot display Unicode.
IDs. The service provider defines the semantics of a parameter. The Cisco Unified IP Phone Service Parameter Configuration page in Cisco Unified Communications Manager Administration contains the fields as described in Table 8-2.
IP Phone Service Administration and Subscription User Service Subscription If you change the service URL, remove a Cisco Unified 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.
Troubleshooting DeviceListX Reports • Note DeviceListX does not support all devices. If you have a device that you need to support, contact Cisco Developer Support to verify whether it is supported: http://developer.cisco.com/web/ipps When a third-party developer initiates an HTTP GET request for the DeviceListX.asp report page, the...
XML version 1.0. Performance and Scalability You can run this report on the largest supported Cisco Unified Communications Manager cluster size for the targeted release without impacting core features, such as delaying dial tone. On multiserver Cisco Unified Communications Manager clusters, the report can access only from the publisher server.
Use the following URL to access the report via HTTP: http://x.x.x.x/CCMAdmin/reports/devicelistx.asp where x.x.x.x can either be the IP address or hostname of the Cisco Unified CallManager system that contains the report. Beginning with Cisco Unified CallManager 4.1 release, the DeviceListX report can only be accessed via Note secure HTTP (HTTPS), so the URL must begin with “https:”...
These sections can assist you in troubleshooting DeviceListX Reports: Error Codes • Determining Problems With the Interface • Error Codes The error codes that are specific to this report interface follow. Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Request information only as often as necessary. Recommended Action Cisco recommends that you wait longer than 60 seconds between requests. Note Error Message 1002 Too many consecutive requests for Device List. Please wait at least 60 seconds and try again.
Page 88
Chapter 9 DeviceListX Report Troubleshooting DeviceListX Reports Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
<InputFlags>The flag specifying the type of allowable input</InputFlags> </InputItem> </CiscoIPPhoneInput> CiscoIPPhoneDirectory <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> </CiscoIPPhoneDirectory> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 90
<LocationX>Horizontal position of graphic</LocationX> <LocationY>Vertical position of graphic</LocationY> <URL>Points to the PNG background image</URL> <MenuItem> <Name>Same as CiscoIPPhoneGraphicMenu</Name> <URL>Invoked when the TouchArea is touched</URL> <TouchArea X1="left edge" Y1="top edge" X2="right edge"Y2="bottom edge"/> </MenuItem> </CiscoIPPhoneGraphicFileMenu> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 91
<ExecuteItem URL=”The URL or URI to be executed”/> </CiscoIPPhoneExecute> CiscoIPPhoneError <CiscoIPPhoneError Number=”x”/> CiscoIPPhoneResponse <CiscoIPPhoneResponse> <ResponseItem Status”the success or failure of the action”Data=”the information associated with the request” URL=”the URL or URI specified in the Execute object”/> </CiscoIPPhoneResponse> Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Page 92
Appendix A CiscoIPPhone XML Object Quick Reference Cisco Unified IP Phone Services Application Development Notes OL-18696-01...
Cisco released an updated XML parser beginning with firmware release 8.3(2). As a result, many Cisco Unified IP Phones now contain this updated XML parser which provides a more rigid enforcement of the XML schema. This updated parser provides more error logging information when it encounters XML schema violations, and it enables developers to debug their applications more efficiently.
CGI script supported URIs Execute supported XML objects 2-2, 2-15, 2-16 Screenshot client requests, using HTTP Cisco IP Phone Services Software Development Kit (SDK) content expiration, header setting components cookie behavior development tools sample services description requirements...
Page 108
2-13 header settings, for HTTP icon, grayscale 2-12 HTML URL text DeviceInformation MIME type, for HTTP DeviceLog?n EthernetInformation EthernetInformation?n NetworkConfiguration StreamingStatistics?n NetworkConfiguration HTTP Next softkey client requests header settings Cisco Unified IP Phone Services Application Development Notes IN-2 OL-18696-01...
Page 109
RTPMTx, used as URI 4-10 troubleshooting error messages tips XML parsing errors Screenshot, CGI script SDK. See Cisco IP Services Software Development Kit (SDK) Search softkey uniform resource identifiers (URI) Select softkey description server requests, using HTTP miscellaneous...
Page 110
Index DeviceInformationX DeviceLogX?n EthernetInformationX NetworkConfigurationX PortInformationX?nX StreamingStatisticsX?n Cisco Unified IP Phone Services Application Development Notes IN-4 OL-18696-01...