Category: IP Phones

Building Cisco IP Phone Services (Part 2) : The XML Payload

Simranjit SinghLeave a comment

In Part 1 of this series, we went over basic introduction of Cisco IP Phone services and what kind of XML Objects are available to us within the phone’s firmware vis-à-vis different phone models.

Cisco 8800 Series
Fig 1 : Cisco 8800 Series

In this part 2 of the series, we will look at the payload that we need to send as a part of the request to execute an HTTP POST action on the phone. We are focusing only on one of the XML objects called Cisco IP Phone Execute because that gives you the most bang for your buck. This is the object that can we can leverage to handle the use cases we had highlighted in the previous post. The table of contents is listed below. You may click directly on the links to jump to relevant sections

  1. Introduction
  2. Common URIs
  3. Use Case
  4. Payload

Introduction

The purpose of the Cisco IP Phone Execute object is to deliver single or multiple execution requests to the phone. As these are XML objects, it is no surprise that the payload also has to adhere to XML standards. Each <CiscoIPPhoneExecute> tag has a sub tag called <ExecuteItem>. As the name suggests, whatever you put under this sub tag will be what gets executed on the phone. It can be a URI of an internal phone resource or an explicit URL of an external entity. The basic syntax is given below.

<CiscoIPPhoneExecute>
	<ExecuteItem URL="the URL or URI to be executed"/>
</CiscoIPPhoneExecute>

The <ExecuteItem> tag of the CiscoIPPhoneExecute object also includes an optional attribute called Priority. The Priority attribute is used to inform the phone of the urgency of the execute request and to indicate whether the phone should be interrupted to perform the request. The point to note is that the Priority attribute is only used for URLs. Internal URIs always execute immediately irrespective of the priority attribute.

PriorityDescription
0 = Execute ImmediatelyThe URL executes regardless of the state of the phone. This is the default priority.
1 = Execute When IdleThe URL gets delayed until the phone goes idle, then it executes. Best Option to avoid any interruption.
2 = Execute If IdleThe URL executes only on an idle phone. This doesn’t wait for the phone to become idle.
Table 1 : Priority Attribute Values

Common URIs

Some of the common URIs available on the 78XX series and 88XX series phones are listed below. If you want to know more on what URIs are available on other phone models then you can refer to the official Cisco documentation.

URI78XX Series88XX Series
KeySupportedSupported
SoftkeySupportedSupported
InitSupportedSupported
Dial, EditDialSupportedSupported
PlaySupportedSupported
Unicast RTPSupportedSupported
Multicast RTPSupportedSupported
DisplayNot supportedSupported
VibrateNot supportedSupported
SendDigitsNot supportedSupported
Table 2 : Common URIs

The functionality of the URIs is pretty self explanatory from the names. For example,

  • The “Key” URI sends an event indicating that a physical key has been pressed. It is akin to someone physically pressing the button on the phone.
  • The “Softkey” URI sends an event indicating that a softkey on the phone menu has been pressed. It is akin to someone pressing the softkey on the phone display.
  • The “Display” URI controls the on/off settings of the phone display.
  • The “Play” URI downloads an audio file from the TFTP server and plays through the phone speaker or play files that are in the Ringlist.xml. We can program it whichever way we want.
  • The “Dial” URI initiates a new call to a specified number
  • The “SendDigits” URI instructs the phone to send a specified sequence of DTMF digits during an active call.

Use Case

Objective : Delete ITL Security settings on a Cisco 7841 IP phone

The process of deleting security settings on the phone goes something like this for, let’s say, a 7841 model phone

  1. Press the “gear” button on the phone. This is known as the “Applications” button in the realm of 7841 model phones.
  2. Select Admin Settings. This is option 5 in the list.
  3. Select Reset Settings. This is option 4 in the list
  4. Select the Security Softkey. This is option 4 in the list.
  5. Confirm the action by selecting the Reset Softkey. This is option 2 in the list.

Now, this 5 step process needs to be performed remotely which means that we will have to send following commands to the phone’s HTTP server.

  1. Three “Key” URIs to mimic step 1 to 3 listed above.
  2. Two “Softkey” URIs to mimic step 4 and 5 listed above.

Payload

Since we now know what sort of payload needs to be sent as a part of the request, it should be easy to frame it in an XML format. The following is how the above mentioned 5 step process will be translated in the form of an XML Payload.

  • Press the “Settings/Applications” button
<CiscoIPPhoneExecute>
	<ExecuteItem URL="Key:Applications"/>
</CiscoIPPhoneExecute>
  • Select Admin Settings which is option 5 in the list.
<CiscoIPPhoneExecute>
	<ExecuteItem URL="Key:KeyPad5"/>
</CiscoIPPhoneExecute>
  • Select Reset Settings which is option 4 in the list.
<CiscoIPPhoneExecute>
	<ExecuteItem URL="Key:KeyPad4"/>
</CiscoIPPhoneExecute>
  • Select Security Softkey which is option 4 in the list.
<CiscoIPPhoneExecute>
	<ExecuteItem URL="Key:Soft4"/>
</CiscoIPPhoneExecute>
  • Confirm the action by pressing “Reset Security” softkey which is option 2 in the list.
<CiscoIPPhoneExecute>
	<ExecuteItem URL="Key:Soft2"/>
</CiscoIPPhoneExecute>

I hope that this article was successful in explaining the structure that needs to be adhered to while sending payload as a part of the request. In the next part, we will write some code in Python to complete this loop. The code will be based on part 1 and 2 of this series. So, make sure that you’ve gone through & understood the basics and payload details.

So, Stay tuned for Part 3 !!

Please feel free to drop your feedback/suggestions, if any. Happy Learnings!!

Let’s connect on LinkedIn