Cisco Video Codecs and XAPI
Its been a while i have blogged on here and i think its time i highlighted a lot of the work that i have done with Cisco Codecs and In-room control in the last few months. Cisco video codecs have come a long way since TC 7.x days and the amount of power the XAPIs provide is going to revolutionize the way we will be able to control meetings and analyze meeting statistics. It is the way of the future.
What is XAPI ? Sounds like TAPI (if you remember what that is). XAPI is a command set available to Cisco Video Codecs including all of the DX70/80, SX, MX, Room Kit, +, Spark Room 70s yada yada. A comprehensive set of these commands work consistently on all these units with some special commands that may work only on certain advanced endpoints. Simple things such as camera pan, tilt zoom can be done from a Touch 10 panel or you could execute the same from command line. You can reduce the volume , mute/unmute volume and microphones from the command line. Or even better you can dial a SIP URI from command line. Think of all the possibilities if you were able to remotely execute these commands via API. Thats what XAPI has enabled and here through this post i am going to demonstrate some of those capabilities.
First of lets be clear the following post will be specific to CUCM registered endpoints as you need full admin rights to execute most of the commands. Spark Registered endpoints will work too as long you assign "Intergrator / Room Control' Rights to the user so that that user can login to the console and execute these commands. With that said there may be many XAPI commands that will not work on a Spark registered endpoints today.
To keep things simple we will only be exploring Xcommand set in this blog post and assuming CUCM registration only. Xcommand is a CLI command to execute a step such as dial a number, hang up a call, place call on hold, mute microphone, increase volume etc. So if you SSH into a Cisco Video codec (hopefully at least running version 8.x or higher) and at the command prompt you simply type 'help' and you can see the various commands supported.
So to dial a video call to john.doe@abc.com you can simply type the command xcommand dial: john.doe@abc.com and the codec will place the video call. Now SSH isnt the most obvious and easiest way to run these commands. Cisco has been kind enough to allow for these commands to work via HTTP calls using XML format. To show the power of this API,i will use Postman as a tool to place these calls.
Postman can be used to send HTML GET or POST requests to a web server and see the results for testing / dev purposes. Great tool to have for troubleshooting. Google Postman and download it today. Once you have that installed and ready to go, you need three things. The IP address of the Codec you are trying to control, the admin user ID and password. With Spark registered endpoints if you attempt to do this , you have to first log into Spark Control Hub and go to Advanced Settings of the codec and it will cross launch a new window to administer the local endpoint. You will have to create a new user who has In-Room Control / Integrator rights in order to execute the same command.
Once you have the IP address and user ID handy, you can use the following Query settings and it will be a HTTP POST for almost all Xcommand set that you want to execute via HTTP. There are three settings that you will need to touch. The Authorization tab which takes the admin username and password.
The Headers tab is generally optional but i would recommend putting the COntent type as application/xml or text/xml.
and last but least the most important tab is the Body tab which takes most of the XML content. So lets go back to the command to dial a number : It said 'xcommand dial: <john.doe@abc.com>' We need to convert this to XML format. If you are familiar with XML you should know that XML has opening and closing tags. An Xcommand is equivalent to <Command> </Command>. The Dial option is equivalent to <Dial> </Dial> and finally the Number option is equivalent to <Number> </Number. So to dial my webex bridge in this case below, the following screenshot shows how i can send a HTTP POST to my codec to dial my webex address sankar@cdw.webex.com
When a call is placed by the codec creates a reference ID for that call which is usually referred to as Call ID. To find the call ID you can either do a XStatus command or you can observe the response you get when you place a call from a codec, the response usually has the Call ID returned back to you. So for the above call when you hit Send, it will produce the following output. Once you know the Call ID you can now place the call on hold, resume the call, hang up the call etc.
To disconnect this call i can now execute a 'Xcommand call disconnect callid:<callid>' where CallID = 2 in this particular example above. How does this translate to XML ?
In a similar fashion Hold/Resume are very similar commands, just replace the Disconnect Tag with Hold or Resume.
both requires the CallId so its important to capture the CallId programmatically.
Keep in mind that the XAPI command set available to admin user is very rich and powerful while the Spark registered endpoints only have a Integrator / Room Control user privilege so a lot of these commands may or may not work. I have found them only by trial and error (no real documentation stating what works and what doesnt). So go out there and play with the XAPIs and build some cool toys to control your video Codec. Hopefully this was useful read and in my next blog post i will talk about Alexa integration with your Cisco video codec. It is pretty cool what you can do with voice activated commands instead of merely using XAPI commands via web.
Here is a good guide you can follow for all the XAPI commands supported by a CUCM registered codec (SX80 in this case)
Also here are good collection of APIs posted by Cisco
Please leave any comments or questions you have below.
