Getting started with Cloud xAPI Soon Christmas again.. :). At the time of writing this article, the feature is not available for on-premises deployments, but as soon as Webex Edge for devices is ready and released with CE9.10.0 its good to go (~Jan 2020). Cloud users can also use this as guidance since the feature is already there, but it meant as a tease for onpremise deployments.   So what is Cloud xAPI? If you have devices registered in the Webex Cloud (Control Hub) this has been available for a while now, but with CE9.10.0 it is now possible to link a device to the cloud providing a small set of cloud features to an on-premises device (se the admin guide for how to link a device to the Webex Cloud). This is kind of cool since it is opening up for using the Cloud xAPI on-premises(!), which basically means you get access to xStatus and xCommand using a user / admin or bot accesstoken depending on the accesslevel granted by a Control Hub admin (What about xConfiguration you say? - sorry not yet available.. but there are some cool things you can do with just xCommand as well and local macros). I decided to experiment a little with this feature to give you a place to start.   Read more on how to link a device to the cloud when the documentation is released in January. It is not available at the time of writing this anyway. But for existing cloud devices:   It all starts by an admin granting access to a user or a bot in Control Hub. Useful guide: https://developer.webex.com/docs/api/guides/xapi   Once that is done you can go to https://developer.webex.com and read more about the device API's there but I will just jump straight into this with a couple of example requests. I use python 3.7 in my examples, I also have written an app to make device management easier via a bot (Webex Bot Manager) but first lets look at the basics. Python class for testing the Device APIs When you have granted access to a user or a bot you can use the access token to list the devices that the bot or user have access to. Note the below class is just an example on how you can get started, feel free to use the examples to get started with your own solutions. import requests import urllib3 import json urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning) # Device API class class DeviceAPI: def __init__ ( self , auth): self ._authHeader = self .genHeader(auth) self ._apiUrls = { 'status' : 'https://api.ciscospark.com/v1/device/xapi/status' , 'command' : 'https://api.ciscospark.com/v1/device/xapi/command' , 'devices' : 'https://api.ciscospark.com/v1/devices' } # Create authorization header def genHeader( self , auth): return { 'Authorization' : 'Bearer ' + auth, 'Content-type' : 'application/json' } # Create device list def getDevicesList( self ): url = self ._apiUrls[ 'devices' ] return self .get(url) def showDevices( self ): devices = self .getDevicesList() for i in devices[ 'items' ]: print ( "{}:{}" .format(i[ 'id' ], i[ 'displayName' ])) # Returns the xStatus of a specific device def getStatus( self , deviceId, keyPath): url = self ._apiUrls[ 'status' ] return self .get( "{}?name={}&deviceId={}" .format(url, keyPath, deviceId)) def sendCommand( self , keyPath, payload): url = self ._apiUrls[ 'command' ] print ( "{}/{}" .format(url, keyPath)) return self .post( "{}/{}" .format(url, keyPath), payload) def get( self , url): return requests.get(url, headers = self ._authHeader, verify = False ).json() def post( self , url, payload): return requests.post(url, headers = self ._authHeader, data =payload, verify = False ).json() #users = {'edge-test': '<access token>'} devices = DeviceAPI(users[ 'edge-test' ] Ok, so the above class will just simplify the requests a little bit so its easier to use. Referring to the above class I can add the following to the script to list my devices (using json.dumps to pretty print it):  devicelist = devices.getDevicesList() print (json.dumps(devicelist, indent = 4 , sort_keys = True )) { "items": [ { "activeInterface": "LAN", "capabilities": [], "connectionStatus": "connected_with_issues", "displayName": "My System", "errorCodes": [ "audiopairingnoise", "ntpstatus" ], "id": "Y2lzY29zcGFyazovL3VzL0rFVklDRS9lZDc3YTFmZC03NzkyLTQ4YTktODc2MS04OGUzYmMyZjRjNDg", "ip": "10.10.10.1", "mac": "2C:31:24:61:5C:4C", "orgId": "Y2lzY29zcGFyazovL3VzL09SRfFOSVyBVElPTi80NTdhZDZiMS01OWNjLTQyOGQtYTRkNy03MmU4ZDdjZDY5ODk", "permissions": [ "xapi" ], "placeId": "Y2lzY29zcGFyazovL3VzL1BMQUNFuzQ1N2FkNmIxLTU5Y2MtNDI4ZC1hNGQ3LTcyZThkN2NkNjk4OTpmMjM2Y2MwZi0wNjIyLTQ1NTgtYThkYi1jY2RhNTBhNWE3ZjI", "primarySipUrl": "", "product": "Cisco Webex Room 55", "serial": "FTT2130035A", "sipUrls": [ "" ], "software": "ce 9.10.0 0a25d810acf 2019-12-09", "tags": [] } ] } Ok, I only have one device, but its quite a bit of information following in the device list. This info can be used for whatever purpose but the part I am looking for in this request is the "id" field which is the deviceId. Implementing this into the bot app where I have filtered out the fields that I need I could be getting something like this by just using a bot (this is just to give you an idea of what you can do): Once you get the device id you can start requesting statuses and commands. Since I only have one device I will just pick the first device entry in the array. payload = json.dumps({ "deviceId" :devicelist[ 'items' ][ 0 ][ 'id' ], "arguments" : { "Number" : "mohm@cisco.com" } }) result = devices.sendCommand( 'dial' , payload) print (json.dumps(result, indent = 4 , sort_keys = True ))   https://api.ciscospark.com/v1/xapi/command/dial { "arguments": { "Number": "mohm@cisco.com" }, "deviceId": "Y2lzY29zcGFyazovL3VzL0rFVklDRS9lZDc3YTFmZC03NzkyLTQ4YTktODc2MS04OGUzYmMyZjRjNDg", "result": { "CallId": 7, "ConferenceId": 6 } } The device will dial the specified number. If the command has arguments, they must be included else you will get a malformed payload error. For commands without arguments, you can either send arguments:{} or only the deviceId. The payload must contain the deviceId to execute the command on the correct device.    payload = json.dumps({ "deviceId" :devicelist[ 'items' ][ 0 ][ 'id' ]}) result = devices.sendCommand( 'audio.microphones.mute' , payload) print (json.dumps(result, indent = 4 , sort_keys = True ))   https://api.ciscospark.com/v1/xapi/command/audio.microphones.mute { "deviceId": "Y2lzY29zcGFyazovL3VzL0rFVklDRS9lZDc3YTFmZC03NzkyLTQ4YTktODc2MS04OGUzYmMyZjRjNDg", "result": {} } A blank result indicates that the request was successful.   Implemented in the bot app you could control the commands sending the different variables that is needed. Getting the status of a device is even easier, it´s just a GET request towards the keypath. With status you can also use wildcards that allow you to get all statuses under a certain key.part. Commands have to be exact in order to work, the commands will not return any schema data so you need to know the exact key path unless you build it in some other way, it is certainly possible. Continuing on the script using the same class as above: deviceid = devicelist[ 'items' ][ 0 ][ 'id' ] result = devices.getStatus(deviceid, 'systemunit.uptime' ) print (json.dumps(result, indent = 4 , sort_keys = True ))   { "deviceId": "Y2lzY29zcGFyazovL3VzL0rFVklDRS9lZDc3YTFmZC03NzkyLTQ4YTktODc2MS04OGUzYmMyZjRjNDg", "result": { "SystemUnit": { "Uptime": 437881 } } } You can use the * as a wildcard and get all the items you want under a specific key or just grab the full status: result = devices.getStatus(deviceid, 'systemunit.*' ) { "deviceId": "Y2lzY29zcGFyazovL3VzL0rFVklDRS9lZDc3YTFmZC03NzkyLTQ4YTktODc2MS04OGUzYmMyZjRjNDg", "result": { "SystemUnit": { "Hardware": { "Module": { "CompatibilityLevel": "0", "SerialNumber": "<snip>" }, "Monitoring": { "Temperature": { "Status": "Normal" } } }, "Notifications": { "Notification": [ { "Text": "OK", "Type": "SoftwareUpgradeOK", "id": 1 } ] }, "ProductId": "Cisco Webex Room 55", "ProductPlatform": "Room 55", "ProductType": "Cisco Codec", "Software": { "DisplayName": "<snip>", "Name": "s53200", "OptionKeys": { "Encryption": "True", "MultiSite": "False", "RemoteMonitoring": "True" }, "ReleaseDate": "", "Version": "" }, "State": { "NumberOfActiveCalls": 0, "NumberOfInProgressCalls": 0, "NumberOfSuspendedCalls": 0 }, "Uptime": 438170 } } } result = devices.getStatus(deviceid, '*' )  The above will return the full xStatus from the device. And this is how it can be done via bot communication: So what are the use-cases for this? It can be quit useful to automate certain things, like for example branding. Note that the Cloud xAPI currently has no support for Multiline commands (like the "body" attribute - but hopefully this will be implemented soon), this means that you cannot currently add macros or custom GUI using multiline commands. But you can use the new "UserInterface Branding Fetch" command to change the branding images using the Cloud xAPI.   Configuration is not supported in the Cloud xAPI. Only status and commands are currently supported at the time of writing this.   But I wanted to show you how you can use the Cloud xAPI together with local macros by triggering custom events. So lets just create our own way of configuring the device then. I add the following macro to my device:   const xapi = require('xapi'); function parse(event) { return JSON.parse(event); } xapi.event.on('Message Send Text', event => { event = event.replace(/'/g,'"'); try { var config = parse(event); for (var key in config) { xapi.config.set(key, config[key]); } } catch(e) { console.log(e); } }); Ok, this may seem a little weird.. but it is a way to make the macro do something based on an incoming event. With the command path message.send (that will generate a custom event). So my custom event is in the form of a JSON blob, which is parsed by the macro and inserted into xapi.config.set(). This will allow me to send configurations as a custom event through the Cloud xAPI. So lets assume the above macro is running on my device, which it is.. haha (I am just trying to keep it very simple for example purposes so the macro needs a bit more work if its supposed to work properly).   From my script I am sending the follwing to the Cloud xAPI: payload = json.dumps({ "deviceId" :devicelist[ 'items' ][ 0 ][ 'id' ], "arguments" : { "Text" : "{ \" SystemUnit Name \" : \" New Device Name \" }" }}) result = devices.sendCommand( 'message.send' , payload) print (json.dumps(result, indent = 4 , sort_keys = True )) Ok, so you see the key is message.send and the text value is the command path: SystemUnit Name, and the value of that key is the actual configuration value "New Device Name". I want to change the device name to New Device Name but it is a configuration and therefore not normally available via the Cloud xAPI so the macro takes care of business.    This macro will allow any configuration but you can also restrict it to certain configuration actions. For example, the macro can listen for a keyword (not the actual command) and run a set of configurations based on the event:   const xapi = require('xapi'); xapi.event.on('Message Send Text', event => { if (event === "signage") { xapi.config.set("Standby Signage Mode", "On"); xapi.config.set("Standby Signage Audio", "On"); xapi.config.set("Standby Signage URL", "http://mysignageurl"); xapi.command("Standby Halfwake"); } }); So now the macro becomes much less complicated and can trigger a series of actions based on the keyword that comes from the Cloud xAPI.   So from the above python script example:  payload = json.dumps({ "deviceId" :devicelist[ 'items' ][ 0 ][ 'id' ], "arguments" : { "Text" : "signage" }}) result = devices.sendCommand( 'message.send' , payload) print (json.dumps(result, indent = 4 , sort_keys = True )) Sending this will trigger the macro to do the config / command sequence. Imagine what you can do with this when you can trigger many actions in a macro from a single Cloud xAPI request. That sure can automate a lot of zZZ things :) I will let you think about this over Christmas so the creative ideas can be born. My examples only touches the surface, but the use-cases are endless - depending on your creativity.     Merry Christmas!   ... View more

Hi, it´s me again and I have been playing around with the new Web Engine feature that came with CE9.9.0 a few days ago. This is just a wonderful feature with so many different use-cases that I don´t really know where to start. But the most obvious use-case is to re-purpose the device while it is not in use with Digital Signage, and at the same time have the option to create on-demand web views or web apps when needed.  First of all, what is the difference between a web app and a web view? Well, nothing really but there is a difference on what the devices support. The Webex Board has a big touch screen and also have a mode called; Interactive Mode, which basically means you can interact with the web page you have opened, perfect for "Web Apps". The other devices you may view a web site but you cannot interact with it. So for now, Webex Board is the only device that support interactive "Web Apps", you can even create native shortcut icons to open different apps on-demand without creating complex macros, which is great for those who likes it simple. I like to make it a little bit more complicated for the benefit of flexibility, but we will take a look at both aspects as we go. Please enjoy, and I hope this will inspire you to create something amazing! Summary  Supported hardware Cisco Webex Board (all models), Room Kit, Room Kit Plus, Room55, Room 55 Dual, Room 70 (Dual), Room 70 G2 (Dual), Room Kit Mini,  Room Kit Pro The Web Engine is the core feature used for Digital Signage and Web Apps. So, the first thing you must do is to enable this from the web interface or which ever method you prefer. xConfiguration WebEngine Mode: On We will be talking about Digital Signage and then about the UI Extensions while moving towards Web Apps. Digital Signage Digital Signage is a feature designed for re-purposing devices for displaying content of a web page when not in use. When the device enters half-wake the device will temporary display the content of the URL provided for the signage configuration until the device goes into standby. For Webex Boards there is also an interactive mode, which allows a user passing by the device, to interact with the web page displayed on the board. This could be a map of the building, todays lunch menu or whatever you want!  Typical use cases Digital signage Dashboards Digital collaboration tools such as Trello / Realtime Board Facility services as building maps or room bookings Help, instructions Games, ice breakers Display emergency information   Feature description, functional overview, compatibility  When the device enters standby it will no longer display the web page on screen to save power (for example outside office hours). Today we do not have a native way of defining office hours on the devices, although you can do, with a macro. This means that it is possible to make the device display content, only during office hours and never go into standby during this time. Extending the standby timer will increase the duration of the web view, but it is limited to 120 minutes (2 hours) for now. xConfiguration Standby Delay: 120 Lets look at some examples on how to configure and set up Digital Signage. Configurations First of all, and I cannot stress this enough, you need to make sure the Web Engine is turned on for Digital Signage to work. xConfiguration WebEngine Mode: On Then you can enable the standby signage mode. Set the Standby Signage Mode to On and how often you want the page to refresh in seconds. Then finally, type in the URL to the page you want to load. xConfiguration Standby Signage Audio: Off xConfiguration Standby Signage InteractionMode: NonInteractive xConfiguration Standby Signage Mode: On xConfiguration Standby Signage RefreshInterval: 1 xConfiguration Standby Signage Url: "http://<url to something awesome>" Important note: Self-signed or other custom CA certificates on any HTTPS sites you are trying to open will not work in CE9.9.0 :( as it only validates toward a pre-installed list of Certificate Authorities. This will most likely improve in later versions of CE. Interaction mode is for Webex Boards only and allow you to navigate the displayed web page, clicking links and filling in forms and so on using the pop-up on-screen keyboard. For example, if you have a website monitoring statistics of some kind, this can be displayed on the system screen while in "Halfwake". When the device enters Standby mode the screen will go black as usual to save power. Here is a simple example on how to setup standby control during office hours, I have just tested this quickly so you probably want to expand on this and fix the bugs you may encounter :D. const xapi = require('xapi'); //Define office hours and days 1 = Monday etc const dayFrom = 1; const dayTo = 5; const hourFrom = 8; const hourTo = 16; /* * Timer interval, checking the time of day. If the time is in office hours it will check the current state. * If the device is in standby (which it will usually be in the mornings, it will automatically set the device in halfwake. * After checking the standby state it will reset the standby timer, not the halfwake timer which means that the device will go into halfwake but never in standby during the office hours. */ function signageControl() { setInterval(function() { if (checkOfficeHours()) { xapi.status.get('Standby State').then(standbyState => { if (standbyState === "Standby") { xapi.command('Standby Halfwake'); } else if (standbyState === "Halfwake") { resetStandbyTimer(); } }); } }, 50 * 1000); } function checkOfficeHours() { var d = new Date(); var hour = d.getHours(); var day = d.getDay(); if (day >= dayFrom && day <= dayTo) { return (hour >= hourFrom && hour < hourTo); } return false; } function resetStandbyTimer(){ xapi.command('Standby ResetTimer', { Delay: 5 }); } signageControl(); You can expand on the above as well to display different content at different time of the day. I could expand on this forever, but we have to move on :). Feel free to copy any of these examples and make them your own and better. Remember that whatever web site you choose to display on the screen and what functionality is provided is up to the content creator (maybe that is you?) either if it is a static web page with information or a dynamic web app with animations or interaction capabilities. Examples (Interactive mode) Lets create a simple interactive signage example, I mean -really- simple and I am not focusing on creating something slick here, it´s just to plant a seed in your brain.  Use your favorite web server accessible by the Webex Board (IIS, apache, nginx or whatever). I am going to use a simple background using CSS and a couple of links that the user can click to interact with the Board. index.php (could also be .html) which is located in the <web-root>/signage web-root/signage <!DOCTYPE html> <html> <style> body{ background-image: url('cisco.png'); background-size: cover; height: 100vh; padding:0; margin:0; } a { font-size: 3em; text-decoration: none; } </style> <center><h1>WELCOME TO CISCO</h1></center> <a href='map.php'>Click here to see a map</a> <br> <a href='lunch.php'>Click here to see todays lunch menu</a> </html> I then set the correct configurations: xConfiguration WebEngine Mode: On xConfiguration Standby Signage Audio: Off xConfiguration Standby Signage InteractionMode: Interactive xConfiguration Standby Signage Mode: On xConfiguration Standby Signage RefreshInterval: 0 xConfiguration Standby Signage Url: "http://10.10.10.1/signage" I set the refresh interval to 0 so that the page never refreshes automatically, you should consider this as it can be disturbing for users navigating the page. As the final step the end I set the URL to my web server. Note: The refresh interval is in seconds and is useful if the page displaying content has dynamic values that needs to be refreshed or if the server logic is to show random content on each request (depending on the use-case etc..). If the content is heavy to load, you should use a longer refresh timer so that the page gets time to load and display the content for a while.  If the device is currently NOT in halfwake, nothing will happen after setting the configurations. If you see the black screen and the device is in standby it is normal since the web page will only show as long as the device is in halfwake mode. You can trigger halfwake from the web interface or xAPI:  xCommand Standby Halfwake The beautiful result! Note the black line at the bottom saying "Tap here to start". This is visible when a web page is being displayed in signage mode (not using web app), as tapping the screen anywhere else will try to interact with the web view. Pressing the "home" button on the webex board will also wake the system up from halfwake. The screen now renders my web page, which is quite simple. The links on the screen are just normal <a href> links but I have not created them yet, so when I click the links it will display: not found If you use broken links, like I have in this case, you will see "File not found". A floating "back" button will appear when you start navigating so you can move back in case you get lost on the web page. There is no forward button. The Room Devices render the web pages but you have no standard browser functionality (like typing in a URL, bookmark etc, but you do have a back button, which helps a lot).  floating back button So lets take a look at the "map.php". map.php <!DOCTYPE html> <html> <style> body{ background-image: url('cisco.png'); background-size: cover; height: 100vh; padding:0; margin:0; } a { font-size: 3em; text-decoration: none; } </style> <a href='index.php'><<-Go back</a> <center> <h1>&nbsp;&nbsp; Here is a map of the building</h1> </center> <iframe src='http://internal.domain.com/map' height='100%' width='100%'> </iframe> </html> The markup above will render a link to navigate back to the "index.php" and will also render an external page using an iframe.  Map As you now see how this works in a simple form, you can start create your own signage flow or help customers understanding how they should get started. The burden is on the user that is creating this to get the flow properly in place like with any web site you are creating for whatever purpose. Note that you don´t have to create this from scratch if you already have a working site, just type in the URL to the site you want to open. The device needs to be able to access the page over the network. Example of rolling signage in NonInteractive mode using a macro Other Room Devices do not support Interactive mode, which means that the user cannot click links or interact with the web page. So this mode is for displaying either static content or over-time dynamic content, for example, information about on-going activities in the workplace or other useful information / statistics / recognitions etc.. NonInteractive mode works exactly the same way as the examples above but without the navigation options, if you touch the screen anywhere, it will wake up the system. You can customize the server side to show a slideshow / gif or video content. Macros can also customize the behavior to an extent where you can randomize the content on intervals the way you want. There are apps or other ways of creating automated slideshows without updating the link every time, but here is a macro example (see description after the code example): signageCarousel.js const xapi = require('xapi'); //1 const baseUrl = 'http://10.10.10.1/noninteractive/'; const links = [ 'image1.jpg', 'image2.jpg', 'image3.jpg' ]; var slideshowInterval; var standbyInterval; let index = -1; //2 function resetStandbyTimer() { xapi.command('Standby ResetTimer', { Delay: 100 }); } //3 function show() { ++index; if (index >= links.length) { index = 0; } xapi.config.set('Standby Signage Url', baseUrl + links[index]); } //4 function init(state) { if (state == "Halfwake") { slideshowInterval = setInterval(show, 15000); standbyInterval = setInterval(resetStandbyTimer, 90000); } else { clearInterval(slideshowInterval); clearInterval(standbyInterval); } } //5 xapi.status.get('Standby State').then(init); xapi.status.on('Standby State', init); Description: 1: Define the base url and an array of "links", I have used images to create an image carousel (without any server side coding), the images are just stored on the web server.  2: resetStandbyTimer() will reset the standby timer to prevent the device from entering standby until someone puts it in standby or wakes it up from halfwake. This is not recommended as the device will constantly loop through the images forever and during weekends. But I use it in my example to show that it is possible. It is also possible to tweak the example to extend the standbytimer to only reset during office hours. 3: show() is the URL changer. It will loop through one of the links index each time it is called by the interval and set a new URL in the config which will take effect instantly (as the device is already in halfwake mode). 4: init() is the function that starts and stops the intervals depending on the standby state. If the standby state is halfwake, we will start two intervals, one to control the standbytimer and one to change the signage URLs on a given interval (15 seconds). 5: It will get the current status of the standby state and test the value through the init function. If the state is Off or the device is in Standby, nothing happens. If the state is in halfwake it will start the carousel right away. xapi.status.on will start a listener for change in the standby state and test the value through init every time. So if someone wakes up the system by tapping the touch panel the carousel will stop and start again when entering halfwake.  Again, this may not work perfectly so feel free to change the behavior as you please. UI Extensions editor Just to make it clear, In-Room Control is now re-named to "UI Extensions", it still has the same basic functionality as before but with a few updates to the editor it-self. You can now select what kind of buttons you want to create and on a Webex Board there is a brand new button you can add, called "Web Apps". These are simply buttons for opening Web Apps from a connected Touch 10 or on-screen from a Webex Board. Note that the web app button is only supported on Webex Board for the time being because it has interactive mode. You can of course emulate the same thing using a macro and an action button on the other devices. Let´t take a quick look at creating a webapp button. Button type selection Having a button that natively opens a web app without the need for creating a supplementing macro is great for many use-cases where you only need to open a web app on demand. You can create many web app buttons to get a selection up there so, knock your self out! New webapp So what is special about this button is that you configure the URL it is supposed to open, directly in the UI Extensions button properties. Easy, right? :) This is all I need to do before pushing the button to the codec using the now highlighted blue button on the top menu. What about the icon you may wonder.. yes, and this is pretty cool. The device will look for a favicon on the web site its trying to open and set this as the button icon, and yes, you may choose your own icon by setting a specific URL to an image that will become the icon image. News webapp button That's it, now you press the button and it opens the bbc.com web site. Using this feature will enable the user to annotate on the web page as well (different from signage)! You can move this button around on the screen as well.   Annotation / back button   Creating your own buttons for web views on devices that do not have the web app option Access the web interface of the device. Now go into the UI Extensions editor (former In-Room Control editor) on the web interface. Integration > UI Extensions Editor UI Extensions Editor As you see in the screenshot above I have create one panel that should open the BBC News page. The button is configured to show "Out of Call" only. This is because Web Views only works out of call, so it does not make any sense to have the button display while in a call. Type in the name of the button and select an suitable icon and color. Tip: Select the globe icon if nothing else matches. The panel ID is set to "bbc" and is the event we will be listening for in our macro example. Once done, upload the button to the codec by pressing the highlighted "Up arrow" in the top bar. Creating the macro Please see below for a simple example to get make the buttons bring up the web view. Note that the xAPI command for Web View is the feature we use here.  const xapi = require('xapi'); function open(url) { xapi.command('UserInterface WebView Display', { Url: url }) .catch(e => console.log('Not able to open url', e.toString())); } function guiEvent(event) { console.log('Pressed button', event.PanelId); // First button on your home page. change the panel id and url below to what you want // The panel id must match the id you typed in the inroom editor if (event.PanelId === 'bbc') { open('https://bbc.com'); } // Second button on your home page else if (event.PanelId === 'office') { open('https://www.office.com'); } } xapi.event.on('UserInterface Extensions Panel Clicked', guiEvent); The "open" function will open the URL that is passed to it from the guiEvent function depending on which button is pressed. At the very bottom an event listener has started to pick up the "Clicked" events from the panel that will contain our panel Id's that we setup earlier in the UI part. If the panelId is "bbc" we will open "https://bbc.com" using the xapi.command('UserInterface WebView Display', {Url: url}) as you see above.  Remember to activate the macro before you press the action button, and you are good to go! :) Note that it makes more sense displaying web pages that shows all the information needed in one page because on these systems you cannot navigate the web page. If you want to display a QR code or something similar this would work perfectly with this example. A button to clear the web view / or a timeout on the webview it self can also be useful to improve user experience. Known Issues, Limitations & Advisories Currently the Signage Mode is limited to showing content when Halfwake triggers until the device enters standby. You can increase the standby timer to extend the time the content will display on screen or create a macro like the example above. Touch 10 do not support rendering of web pages with this feature in any scenario. Compatibility Since the browser is based on a standard Chromium browser, most of the features you expect from a modern desktop browser is available. Features such as HTML5, EcmaScript 6, CSS3, web fonts, multi-touch, SVG, canvas, iframes, web sockets, web assembly, web workers and more are available. Note that the following features are currently NOT supported: PDF WebGL Password manager Plugins (Flash etc..) Downloading and uploading files Notifications   Some of the above may be added later, but no guarantees can be provided now. How many windows / tabs are supported? Only one web tab / window is supported. If a web page tries to open a page in a new window or tab, it will replace the existing page. Multimedia Standard video codecs are supported, such as WebM and Mpeg4. Decoding is done through software. It is not recommended to go beyond 720p resolution as this will lead to choppy performance! Multimedia is supported What about audio / volume? The volume follows the volume setting of the video system. For digital signage, the audio is "Off" by default to avoid unwanted noise by accident, but it can be controlled with the following configuration. xConfiguration Standby Signage Audio: <on/off> You can of course enforce volume and mute control on top of this by using JavaScript audio frameworks. Browser info: The web engine is based on Chromium / Qt WebEngine with V8 JavaScript. The Chromium version is upgraded every time Cisco updates the Qt version in RoomOS/CE, meaning it will not be as up-to-date as your Chrome laptop version, but will be updated periodically. You can inspect the version at any time by looking at the user agent, i.e. by visiting http://whatsmyuseragent.org/ on your device. User-agent Is user data persisted? For digital signage, web engine is running in persistent ("desktop browser") mode, meaning that cookies, local storage etc. are saved to disk and persisted across reboots and even upgrades. This means its possible to have persisted logins for team dashboards etc. Are touch events supported (developer related)? Yes, the Webex Board supports up to 10 simultaneous touch events, using ontouchstart, ontouchmove and ontouchend. The traditional onclick event is also supported but not recommended since it incurs a slight delay to detect gestures. Note that the ordering of touch events is not stable so use the touch event "identifier" to keep track of simultaneous touches. How to prevent the standard zoom gestures in the rendered web views? Two finger zoom is default of accessibility and convenience, but not always wanted, for example in immersive apps, such as Google Maps, whiteboards and games where you need more control. You can overwrite this with preventDefault: document.querySelector('.myCanvas').ontouchstart = (e) => { e.preventDefault(); // .. my action } // similar for ontouchmove and ontouchend What is the viewport / screen size? The logical viewport is 1920 pixels wide, and 1080 pixels high minus whatever is used for the toolbar (typically less than 200 pixels). The actual rendering is done on a 4k canvas (3840 x 1260, similar to Apple´s Retina mechanism, so text and images will be crisp. Be sure to provide high resolution images and assets for the optimal user experience. Developers can also modify the viewport meta tag, i.e.: <meta name="viewport" content="width=960, initial-scale=1"> Are JavaScript dialogs available? Yes, most of the JavaScript dialogs such as alerts, prompt and confirm works like on a desktop and is implemented using the native dialogs of the video system. Uploading and downloading dialogs are not supported! What fonts are available? Currently only the system font of RoomOS / CE (sans serif). Web fonts are supported though so third party app developers can add their own fonts as needed with CSS, i.e.: @font-face { font-family: handwriting; src: url(handwriting.woff); } div { font-family: handwriting; } Login and authorization One of the most challenging aspects for a web app on a shared video device is the user login. We cannot just store the users credentials like on a personal device, since it can be used by anyone, and entering the username and password on a large-screen, soft keyboard device is both annoying and unsafe.We will strive towards a solution that makes this easy and safe in the future. In the meantime, the model solution is to use a second, personal device for authentication and authorization. User flow: The user launches the web app on the video device The user is prompted and enters their email The web app sends a notification to the user's phone The user accepts the login on the phone The web app is automatically logged in on the video device The Microsoft Authenticator for Office 365 an example of how this can be implemented in a way that is convenient, fast and safe for the user. What animations are supported? Both CSS transitions and web animations are supported and hardware accelerated whenever possible. This typically means the transform and opacity CSS property. Try to avoid doing animations that requires DOM or layout operations. How to improve performance? The web engine has the difficult task of running modern, full scale web content on a 4K screen while having lower priority than the main video features. This means it can sometimes struggle with heavy web sites such as Google Maps 3D and similar. But there are many things a developer can do to improve performance. This is worthy of its own guide, but here are a few things you can try: Start testing on the device early in development, if possible, or use a mobile device Avoid using images that are larger than needed, resize them on the server Reduce the number of layers with opacity Avoid drop shadows Avoid huge canvases, load content dynamically as needed instead Use only hardware accelerated CSS / web animations Skip certain features, eg animations, based on user agent Avoid doing much work in event handlers, delegate to async tasks Use requestAnimationFrame instead of setInterval if you are doing low level animations/simulations Move heavy calculations / algorithms to WebAssembly Best but also most challenging: Learn the performance monitor of Chromium and use it actively. Can I create offline applications? Yes. Web workers are supported, and can be used to speed up initial loading of heavy web apps. Note that currently the web views are not available if the device does not have network, so real offline apps are not possible. Keyboard input The RoomOS / CE soft keyboard behaves similarly to the touch keyboards on Android and iOs, and pops up any time an input field gets focus. The content also scrolls up if needed so both the input field and keyboard are visible. It does not support specialized formats such as numeric, calendar and color picker at the moment. A vertical soft keyboard does not encourage a lot of text input and provides little privacy, so keep that in mind. Localization The web engine sends the language header of the current language in each HTTP requests, i.e. Accept-Language: fr for French. A web app can then translate the content to the current language, either server side by looking at the header, or in JavaScript by querying useragent.language in the browser. Non-fullscreen windows? Currently only fullscreen web views are supported. In the future we may support different types such as web dialogs and side-bars. Multiple screens? For digital signage, content is cloned to the extra screens. A web view cannot be logically stretched across multiple screens. In other cases than signage, only the primary monitor will display the web view. Best practices Writing web apps for a shared device with a huge touch screen comes with its own set of challenges. A dedicated best practice manual may be offered later, but here are a couple of pointers: The screens are large and the user can be very close to it - choose your content based on wether you prefer interactive use (smaller font and content) or passive audience (larger font and content). Provide high resolution assets for crisp graphics Only use hardware accelerated CSS animations (transform and opacity) If possible, provide a second, personal device for log in such as Microsoft Authenticator Use local storage to store temporary user data, to prevent data loss if the web view is closed by accident Don't rely on multiple tabs Style guide As a third party developer you do of course have the tools and freedom to design the web content exactly as you like or to match your company's visual profile. If you prefer something that feels native and in line with the Cisco design language, you can find everything you need at https://momentum.design/. As well as styles and guide lines, this web site contains CSS, assets, fonts and icons and component support for popular web frameworks. Can the content access the xAPI? At the moment, not directly. The Cisco video systems provide rich and powerful API integrations through the xAPI, such as making calls, starting presentations, counting the number of people in the room etc. Currently a web view does not have direct access to the xAPI, but it can access it the same way as other integrations, provided that credentials to the video systems are available. Alternatives include local REST APIs (on premise deployments), HTTP feedback (web hooks), cloud APIs or direct web socket communication. For more info about these, see separate RoomOS / CE developer documentation. Be careful about exposing credentials in your client side code, though, and consider going through your web app's server. What about non-touch / non-interactive devices? At the moment, the only supported device that has touch screen capability is the Webex Board, but all the new Cisco video devices such as Room Kit, Room Kit Mini, Room 55 etc also support web view. Troubleshooting, diagnostics Page lifecycle: As soon as the user hits the home button, the state of the web page is lost. When the user starts the web activity again, the same url is reloaded. You can save the current state of the page and and re-apply it by always saving to local storage (or session storage), then fetching those state values whenever the page loads. Remote developer console xConfiguration WebEngine RemoteDebugging: On The remote developer console is by far the most important and powerful tool available to third-party developers. This is a standard Chrome dev console, that you can run remotely on your own laptop to inspect what is happening in the web engine. See the log console and manipulate the content live just like with local web development. When this is enabled all the web views will display a prominent warning that they may be monitored as a privacy warning. Accessing the remote debugger via a browser is done like this when remote debugger is enabled (the URL is also listed on the device screen together with the warning): http://<codecip>:9222 Remote debugger is only supported with Google Chrome browser and Chromium Browser. Using this tool I can troubleshoot failing functions or check elements that are not displayed correctly in the web view. In the above screenshot I can view the page that is rendered on the device from my laptop. This tool should be used for debugging and development only. Remember to turn it off when done. System Resources The web engine has a lower priority than the main video features and is restricted. Currently it is limited to 1 CPU core and 650 MB of memory (excluding GPU usage). If the web page requires more memory than allowed, Chromium will try to optimize usage with the memory pressure handler. Failing this the web view will eventually be terminated and show an error page. The web view may also be terminated if the video system is running on low memory in general. For Room Kit Pro there are 6 cores and 8 GB of memory but the restriction is currently the same as the other devices. Resources & References Special thanks to Tore Bjolseth for all the details.           ... View more

It´s time for a new software release CE9.7.1 has just arrived, introducing an interesting feature called XoWS (pronounced cows) This feature basically allows you to setup a persistent bi-directional connection to the xAPI. WebSocket is just an alternative way of communicating with the xAPI like SSH, Serial or XMLAPI, but using JSON RPC 2.0 as data transport, you send and receive all the data in JSON format which is easier to work with than parsing XML or scraping plain text. Most of the popular programming languages have a WebSocket module you can use to integrate your app/script with XoWS. The difference between a HTTP request and a WebSocket is that a HTTP request is client initiated and a response is received for the request before the connection is closed. To send and receive more data you have to generate new client requests. With a WebSocket the communication channel is open both ways and the server can send data to the client when new data is available. More information can be found here: https://en.wikipedia.org/wiki/WebSocket In order to get started and open the device for connections you need to enable the WebSocket service on the device. xConfiguration NetworkServices Websocket: FollowHTTPService We set the Websocket config to FollowHTTPService. The connection is setup via HTTP so if you disable the HTTP service on the device, Websocket will not work. The WebSocket entrypoints is: ws(s)://<codecip>/ws ws(s)://<codecip>/ws?legacy These are the URLs you use when setting up the connection /ws and /ws?legacy is essentially the same but /ws is integer aware which means switching your jsxapi app from SSH directly to using WebSocket will most likely break something in your existing code. Legacy is setup to avoid that and returns all values as strings. This is the difference between the two.  Feature summary Benefits Simple mapping between request and response, no difference between "sync" and "async" responses. Each message contains a complete JSON document and nothing else, no need to parse text or a mix of text and XML. Can be accessed directly from a browser using javascript (using auth protocol header)(Currently not supported) Benefits with respect to HTTP API (I.E XMLAPI) Much faster. No need to re-authenticate for every request. Clients can get events from the codec. No need to run your own web server and register for HttpFeedback or listen for HTTP POSTS and PUT from the codec. Benefits with respect to XAPI over SSH/telnet/RS-232 The SSH/telnet/RS-232 services can be turned off if not used for anything else. Feature description, functional overview, compatibility Purpose Provide a modern an powerful way of interacting with the xAPI using WebSocket. Keep in mind that this is an integration feature which allows flexibility on how you choose to use the API. You can write an application that uses WebSocket to monitor devices or whatever other use-case you can think of. XoWS - Guide Connecting Basic Authentication: HTTP request header HTTP request header “Authorization: Basic <encoded user:pw>” before upgrading the HTTP connection to a WebSocket. User needs to provide a valid user:password combination using basic auth. Auth protocol header (Disabled in CE9.7.1, planned for a future release) Because browser based clients have no direct control over headers, you can also authenticate using an auth protocol header. The authentication is sent similarly to basic authentication, i.e. as a base64 encoded string of username:password. The complete header looks like this: Sec-WebSocket-Protocol: auth-dXNlcjpwYXNz. Example usage from javascript (the replace train is for making sure the base64 is "url-safe" else it will not always work): var ws = new WebSocket("wss://codec.example.com/ws", "auth-" + btoa("user:password").replace(/[\/+=]/g, function(c){return {'+':'-','/':'_','=':''}[c]})); Possible error codes Currently, these are the possible error codes: (from the JSON RPC spec):         Invalid Request, -32600         Method Not Found, -32601         Invalid Params, -32602         Internal Error, -32603         Parse Error, -32700 (implementation-defined server errors):         Unexpected response, -32099 (application-defined server errors):         CommandError, 1         Permission Denied, -31999         Subscriber Count Exceeded, -31998         Not Ready, -31997  Let´s take a look at the JSON documents that we can send and receive to the codec. In the JSON document we have some required fields, jsonrpc, id, method and params. jsonrpc needs to be set to 2.0 since that is the version we are using. id can be set to anything you like in order to map the request with the response, the response will contain the same id as the request. method is basically the "xcommand/xconfig" but its a little bit different, since with WebSocket we use xGet, xSet, xQuery, xCommand/path/to/basic etc.. but we will get back to that as we move on. params is all the parameters to the method, it could be parameters or a path To get started you need to choose your cup of language that you wish to use and find out if it has a websocket library. I will be using mostly Python3.7 in my examples and at the end I will show you how to start using WebSocket with jsxapi and NodeJS. I also assume you have some experience of python and how to setup your environment.  Before you read further: Note that the following examples are not using the newly released XoWS library (pyxows for Python 3.7). If you scroll further down you will find examples that uses the pyxows library. I strongly recommend you to use the pyxows library but I will keep the below examples in this article for learning purposes. For Python3.7 you can use a WebSocket library (I am using the websockets module) which can be acquired by issuing   pip install websockets     Below is a basic script I will use to show you how it works, as a start. xows-entry.py import websockets import ssl import asyncio import base64 async def connect(): return await websockets.connect( 'wss://{}/ws/' .format( '10.10.10.1' ), ssl =ssl._create_unverified_context(), extra_headers ={ 'Authorization' : 'Basic {}' .format(base64.b64encode( '{}:{}' .format( 'admin' , '' ).encode()).decode( 'utf-8' ))}) async def send(ws, message): await ws.send(message) print ( 'Sending:' , message) async def receive(ws): result = await ws.recv() print ( 'Receive:' , result) async def task(): ws = await connect() try : await send(ws, '{"jsonrpc": "2.0","id": "0","method": "xGet","params": {"Path": ["Status", "SystemUnit", "State"]}}' ) await receive(ws) finally : ws.close() asyncio.run(task()) This simple example connects to the XoWS, send a payload through the socket and receive data back before the script ends. See below for the output. Sending: {"jsonrpc": "2.0","id":"0","method": "xGet","params": {"Path": ["Status", "SystemUnit", "State"]}} Receiving: {"jsonrpc":"2.0","id":"0","result":{"NumberOfActiveCalls":0,"NumberOfInProgressCalls":0,"NumberOfSuspendedCalls":0}} So the connection works, we can send data and receive data. In a WebSocket connection we dont deal with posts / puts / gets we send data and receive data back or we just receive data (feedback events, for example).   Here is a modified version of the above to make sending data a little bit easier, as the functions create the json documents automatically and I can interact with the xAPI by writing much simpler commands if you look in the "task" function now I use the get function to generate the JSON document while keeping the syntax almost the same as I would type it in the xAPI CLI. import websockets import ssl import asyncio import base64 import json count = 0 async def connect(): return await websockets.connect( 'wss://{}/ws/' .format( '10.10.10.1' ), ssl =ssl._create_unverified_context(), extra_headers ={ 'Authorization' : 'Basic {}' .format(base64.b64encode( '{}:{}' .format( 'admin' , '' ).encode()).decode( 'utf-8' ))}) def construct(method): global count count += 1 return { 'jsonrpc' : '2.0' , 'id' : str (count), 'method' : method} def query(params): payload = construct( 'xQuery' ) payload[ 'params' ] = { 'Query' : params.split()} return payload def get(params): payload = construct( 'xGet' ) params = [i if not i.isnumeric() else int (i) for i in params.split()] payload[ 'params' ] = { 'Path' : params} return payload def command(path, params= None ): payload = construct( '{}{}' .format( 'xCommand/' , '/' .join(path.split( ' ' )))) # Params are for multiline commands and other command parameters {'ConfigId':'example', 'body':'<Extensions><Version>1.0</Version>...</Extensions>'} if params != None : payload[ 'params' ] = params return payload def config(path, value): payload = construct( 'xSet' ) payload[ 'params' ] = { "Path" : [ 'Configuration' ] + path.split( ' ' ), "Value" : value } return payload def feedbackSubscribe(path= None , notify= False ): payload = construct( 'xFeedback/Subscribe' ) payload[ 'params' ] = { "Query" : path.split( ' ' ), "NotifyCurrentValue" : notify } return payload async def send(ws, message): await ws.send(json.dumps(message)) print ( 'Sending:' , message) async def receive(ws): result = await ws.recv() print ( 'Receive:' , result) async def task(): ws = await connect() try : await send(ws, get( 'Status SystemUnit Uptime' )) await receive(ws) finally : ws.close() asyncio.run(task()) Here is the result of the run Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xGet', 'params': {'Path': ['Status', 'SystemUnit', 'State']}} Receive: {"jsonrpc":"2.0","id":"1","result":{"NumberOfActiveCalls":0,"NumberOfInProgressCalls":0,"NumberOfSuspendedCalls":0}} So pretty much the same output. Let´s go through the guide and put it to the test. Status and configuration Get a single leaf node. Send: { "jsonrpc": "2.0", "id": "a1336", "method": "xGet", "params": { "Path": ["Status", "SystemUnit", "Uptime"] } } Receive: { "jsonrpc": "2.0", "id": "a1336", "result": 62974 } Lets see how this works with the script: -snip- await send(ws, get( 'Status SystemUnit Uptime' )) -snip- Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xGet', 'params': {'Path': ['Status', 'SystemUnit', 'Uptime']}} Receive: {"jsonrpc":"2.0","id":"1","result":64882} Moving on.. Get a single subtree. Send: { "jsonrpc": "2.0", "id": "3" "method": "xGet", "params": { "Path": ["Status", "SystemUnit", "State"] } } Receive: { "jsonrpc": "2.0", "id": "3", "result": { "NumberOfActiveCalls": 0, "NumberOfInProgressCalls": 0, "NumberOfSuspendedCalls": 0 } } We already tested this above, so skipping this one. Single leaf nodes from inside arrays can be retrieved by specifying the one-based index with a Number in the path. Send: { "jsonrpc": "2.0", "id": "a1338", "method": "xGet", "params": { "Path": ["Status", "SystemUnit", "Hardware", "Monitoring", "Fan", 2, "Status"] } } Receive: { "jsonrpc": "2.0", "id": "a1338", "result": "2372 rpm" } If you notice in the get function there is a check for numeric values: params = [i if not i.isnumeric() else int (i) for i in params.split()] and this will make sure that my path is built with an in when I send the string below. await send(ws, get( 'Status SystemUnit Hardware Monitoring Fan 2 Status' )) Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xGet', 'params': {'Path': ['Status', 'SystemUnit', 'Hardware', 'Monitoring', 'Fan', 2, 'Status']}} Receive: {"jsonrpc":"2.0","id":"1","result":"2820 rpm"} Query with wildcard in path Works on both Status and Configuration. "**" matches zero or more levels in the path. Send: { "jsonrpc": "2.0", "id": "a1350", "method": "xQuery", "params": { "Query": ["Status", "**", "DisplayName"] } } Receive: { "jsonrpc": "2.0", "id": "a1350", "result": { "Status": { "SIP": { "CallForward": { "DisplayName": "" } }, "SystemUnit": { "Software": { "DisplayName": "ce 9.7.1 xxx" } } } } } Ok, then we switch to the query function of the script: await send(ws, query( 'Status ** DisplayName' )) Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xQuery', 'params': {'Query': ['Status', '**', 'DisplayName']}} Receive: {"jsonrpc":"2.0","id":"1","result":{"Status":{"SIP":{"CallForward":{"DisplayName":""}},"SystemUnit":{"Software":{"DisplayName":"ce 9.7.1 30bff6140aa 2019-04-02"}}}}} Set configuration Send: { "jsonrpc": "2.0", "id": "a1360", "method": "xSet", "params": { "Path": ["Configuration", "SystemUnit", "Name"], "Value": "my-codec" } } Receive: { "jsonrpc": "2.0", "id": "a1360", "result": true } Ok, I will run this through the config function of the script: await send(ws, config( 'SystemUnit Name' , 'my-codec' )) await send(ws, get( 'Configuration SystemUnit Name' )) Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xSet', 'params': {'Path': ['Configuration', 'SystemUnit', 'Name'], 'Value': 'my-codec'}} Receive: {"jsonrpc":"2.0","id":"1","result":true} Sending: {'jsonrpc': '2.0', 'id': '2', 'method': 'xGet', 'params': {'Path': ['Configuration', 'SystemUnit', 'Name']}} Receive: {"jsonrpc":"2.0","id":"2","result":"my-codec"} Commands Send: { "jsonrpc": "2.0", "id": "a1370", "method": "xCommand/Dial", "params": { "Number": "alice@example.com", "Protocol": "Spark" } } Receive: { "jsonrpc": "2.0", "id": "a1370", "result": { "CallId": 2, "ConferenceId": 1 } } Receive error: { "jsonrpc": "2.0", "id": "a1370", "error": { "code": -32601, "message": "Method not found." } } Sending commands is a little different since the command path is in the method field, but the command function in the script will take care of building the JSON blob, all I need to type in is something that reminds me a lot of the macro command syntax: await send(ws, command( 'CallHistory Get' , { 'Limit' : '1' })) Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xCommand/CallHistory/Get', 'params': {'Limit': '1'}} Receive: {"jsonrpc":"2.0","id":"1","result":{"status":"OK","Entry":[{"id":0,"CallHistoryId":2,"CallbackNumber":"sip:user@cisco.com","DisplayName":"user@cisco.com","StartTime":"2018-11-13T14:44:44","DaysAgo":141,"OccurrenceType":"NoAnswer","IsAcknowledged":"Acknowledged","RoomAnalytics":{}}],"ResultInfo":{"Offset":0,"Limit":1}}} If the command does not add up you will get "Method not found". Multi-line commands. Multi-line commands are identical to regular commands, but they provide the command body in the "body" parameter. A Multi-line command is a command that takes text as input. For example if you want to upload In-Room Control design as pure XML via WebSocket instead of uploading as a file through the web interface. Please see the API Reference guides for more information about Multi-line commands. Send: { "jsonrpc": "2.0", "id": "a1370", "method": "xCommand/UserInterface/Extensions/Set", "params": { "ConfigId": "example", "body": "<Extensions><Version>1.0</Version>...</Extensions>", } } Ok, in my example I am just going to send a HTTP POST to a server since this is a multiline command. payload = json.dumps({ "field1" : "value1" }) <- body payload await send(ws, command( 'HttpClient Post' , { 'Url' : 'http://10.10.10.1:5000/api' , 'Header' : 'Content-Type: application/json' , 'body' : payload})) <- multiline content here Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xCommand/HttpClient/Post', 'params': {'Url': 'http://10.10.10.1:5000/api', 'Header': 'Content-Type: application/json', 'body': '{"field1": "value1"}'}} Receive: {"jsonrpc":"2.0","id":"1","result":{"status":"OK","StatusCode":200}} Server receives (simple Flask driven API in python): * Running on http://10.10.10.1:5000/ (Press CTRL+C to quit) {'field1': 'value1'} 10.10.10.2 - - [09/Apr/2019 23:21:17] "POST /api HTTP/1.1" 200 Status feedback and events Register feedback. "NotifyCurrentValue": When set to "true" there should be feedback notification triggered with the current value of the config/status nodes matching the expression. "Query": Subscribing to all feedback can be done by subscribing to "Query": ["**"]. Send: { "jsonrpc": "2.0", "id": "a1400", "method": "xFeedback/Subscribe", "params": { "Query": ["Status", "Audio", "Volume"], "NotifyCurrentValue": false, } } Receive: { "jsonrpc": "2.0", "id": "a1400", "result": { "Id": 3 } } Feedback events is one of the more powerful things you can do with websockets without the need for a web server to receive the feedback events. The feedback events will be sent through the open connection from the codec when new feedback is available. Lets do it! await send(ws, feedbackSubscribe( 'Status Audio Volume' , True )) while True : await receive(ws) I added a listener on this so the script does not complete. This is bad programming, I know but just to show you an example of how you can listen for feedback. Sending: {'jsonrpc': '2.0', 'id': '1', 'method': 'xFeedback/Subscribe', 'params': {'Query': ['Status', 'Audio', 'Volume'], 'NotifyCurrentValue': True}} Receive: {"jsonrpc":"2.0","id":"1","result":{"Id":0}} Receive: {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Volume":70}},"Id":0}} There, we have registered a feedback listener on the Status value for Audio Volume. So whenever the Volume on the device changes we should receive the new value through our WebSocket channel. Deregister feedback Send: { "jsonrpc": "2.0", "id": "a1401", "method": "xFeedback/Unsubscribe", "params": { "Id": 3 } } Receive: { "jsonrpc": "2.0", "id": "a1401", "result": true } Receive error: { "jsonrpc": "2.0", "id": "a1401", "error": { "code": -32602, "message"; "Invalid params", "data": "Unknown feedback ID." } } This is just deregistering the feedback based on the feedback ID you registered with. Receiving feedback Feedback is received as JSON-RPC notifications. The feedback message will include the feedback id. By changing the audio level we receive the following feedback message (after we registered the above feedback subscription): Receive: { "jsonrpc": "2.0", "method": "xFeedback/Event", "params": { "Status": { "Audio": { "Volume":60 } }, "Id":3 } } I log into the device on SSH and execute: xcommand Audio Volume Set Level: 80 OK *r VolumeSetResult (status=OK): ** end And a couple of other values, produces this as an output in my script: Receive: {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Volume":80}},"Id":0}} Receive: {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Volume":50}},"Id":0}} Receive: {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Volume":40}},"Id":0}} Pretty cool! Get complete documents Both xGet and xQuery can get an entire tree / subtree. These need to be fetched separately, i.e. by passing ["Configuration"] or ["Status"]. ["**"] is not valid. Lets just do an example in NodeJS: In NodeJS it can look like this (requires NodeJS environment and WebSocket module) websocket.js - Working example to get you started on NodeJS: const WebSocket = require('ws'); const url = 'wss://10.10.10.1/ws/' const websoc = new WebSocket(url, {   perMessageDeflate: false,   headers: {     Authorization: `Basic YWRtaW4xOg==`,   },   rejectUnauthorized: false, }); websoc.onopen = function (event) {   websoc.send('{"jsonrpc": "2.0","id": "a1336","method": "xGet","params": {"Path": ["Status", "SystemUnit", "Uptime"]}}');   websoc.send('{"jsonrpc": "2.0","method": "xGet","params": {"Path": ["Status", "SystemUnit", "State"]}}');   websoc.send('{"jsonrpc": "2.0","id": "a1400","method": "xFeedback/Subscribe","params": {"Query": ["Status", "Audio", "Microphones", "Mute"],"NotifyCurrentValue": true,}}'); } websoc.onmessage = function (event) {   console.log(event.data); } websoc.on('error', function(event) {   console.log(event); }); Output: NodeJS mohm$ node websockets.js {"jsonrpc":"2.0","id":"a1336","result":510806} {"jsonrpc":"2.0","id":null,"result":{"NumberOfActiveCalls":0,"NumberOfInProgressCalls":0,"NumberOfSuspendedCalls":0}} {"jsonrpc":"2.0","id":"a1400","result":{"Id":0}} {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Microphones":{"Mute":"Off"}}},"Id":0}} {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Microphones":{"Mute":"On"}}},"Id":0}} {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Microphones":{"Mute":"Off"}}},"Id":0}} {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Microphones":{"Mute":"On"}}},"Id":0}} {"jsonrpc":"2.0","method":"xFeedback/Event","params":{"Status":{"Audio":{"Microphones":{"Mute":"Off"}}},"Id":0}} If you are using jsxapi which is the NodeJS module for writing "external macros" you can switch from SSH to using WebSocket. See the following example (I know it seems cumbersome but this will improve going forward, finding easier ways of utlizing the WebSocket as a backend): ws-jsaxpi.js const WebSocket = require('ws'); const XAPI = require('jsxapi/lib/xapi').default; const WSBackend = require('jsxapi/lib/backend/ws').default; const url = 'ws://codecip/ws'; const username = 'admin'; const password = ''; const auth = Buffer.from(`${username}:${password}`).toString('base64'); const options = { headers: { 'Authorization': `Basic ${auth}`, } }; const websocket = new WebSocket(url, options); websocket.on('error', console.error); const xapi = new XAPI(new WSBackend(websocket)); xapi.status.get('Audio Volume') .then(console.log) .catch(console.error); xapi.status.on('Audio Volume', console.log); Output (first prints out the current volume, then prints out the updated status from the codec when the volume changes). MOHM-M-D2KG:NodeJS mohm$ node ws-jsxapi.js 60 70 { Status: { Audio: { Volume: 70 } }, Id: 0 } 60 { Status: { Audio: { Volume: 60 } }, Id: 0 } 70 { Status: { Audio: { Volume: 70 } }, Id: 0 } 80 { Status: { Audio: { Volume: 80 } }, Id: 0 } 90 { Status: { Audio: { Volume: 90 } }, Id: 0 }   NEW: PYXOWS - XoWS Python Library for Python 3.7 =< Download/Clone here: https://github.com/cisco-ce/pyxows pyxows is a Python library or XoWS written by the super hero Morten Minde Neergaard and wraps around the XoWS feature to make it easier for you to get started! This library requires Python3.7 and above. mohm$ git clone https://github.com/cisco-ce/pyxows Cloning into 'pyxows'... remote: Enumerating objects: 15, done. remote: Counting objects: 100% (15/15), done. remote: Compressing objects: 100% (11/11), done. remote: Total 15 (delta 2), reused 15 (delta 2), pack-reused 0 Unpacking objects: 100% (15/15), done. pyxows mohm$ python3.7 setup.py install Done! Now I can use the pyxows library for interacting with codec(s) over XoWS. Let´s get started! One of the features with pyxows is that it comes with a CLI tool "clixows". mohm$ clixows Usage: clixows [OPTIONS] HOST_OR_URL COMMAND [ARGS]... First argument is hostname, or url (e.g. ws://example.host/ws) Usage examples: clixows ws://example.codec/ws get Status SystemUnit Uptime clixows example.codec set Configuration Audio Ultrasound MaxVolume 70 clixows example.codec command Phonebook Search Limit=1 Offset=0 clixows example.codec feedback -c '**' Options: --version Show the version and exit. -u, --username TEXT [default: admin] -p, --password TEXT [default: ] --help Show this message and exit. Commands: command Run a command. demo Runs a quick demo, read source to see... feedback Listen for feedback on a particular query. get Get data from a config/status path. query Query config/status docs. set Set a single configuration. mohm$ clixows -u admin1 10.10.10.1 feedback -c Status Audio Volume Subscription Id: 0 {'Status': {'Audio': {'Volume': 40}}} With clixows you can instantly start a feedback subscription in the terminal or run configurations and commands. mohm$ clixows -u admin1 10.10.10.1 command Audio Volume Set Level=50 {'status': 'OK'} mohm$ clixows -u admin1 10.10.10.1 set Configuration Audio DefaultVolume 60 True mohm$ clixows -u admin1 1010.10.1 query Status '**' DisplayName {'Status': {'SystemUnit': {'Software': {'DisplayName': 'RoomOS 2019-04-26 ' '363d7728a2a'}}}} mohm$ clixows -u admin1 10.10.10.1 query Status '**' Volume {'Status': {'Audio': {'Output': {'LocalOutput': [{'VolumeControlled': 'On', 'id': 2}, {'VolumeControlled': 'Off', 'id': 8}, {'VolumeControlled': 'Off', 'id': 9}]}, 'Volume': 50, 'VolumeMute': 'Off'}}} To authenticate with a password you add an additional flag -p <password>. This was just a short demo of the CLI function (that uses WebSocket for the connection). But now over to the python examples to create some practical scenarios, and listen to multiple systems at once: pyxows-demo.py import xows import asyncio async def start(): async with xows.XoWSClient( '10.10.10.1' , username = 'admin1' , password = '' ) as client: def callback(data, id_): print ( f'Feedback (Id {id_}): {data}' ) print ( 'Status Query:' , await client.xQuery([ 'Status' , '**' , 'DisplayName' ])) print ( 'Get:' , await client.xGet([ 'Status' , 'Audio' , 'Volume' ])) print ( 'Command:' , await client.xCommand([ 'Audio' , 'Volume' , 'Set' ], Level = 60 )) print ( 'Configuration:' , await client.xSet([ 'Configuration' , 'Audio' , 'DefaultVolume' ], 50 )) print ( 'Subscription 0:' , await client.subscribe([ 'Status' , 'Audio' , 'Volume' ], callback, True )) await client.wait_until_closed() asyncio.run(start()) Callback is the function that is ran every time we receive feedback from the subscription. You can create several subscriptions on one device by adding more susbcriptions. I set True to report the current value of the feedback setting I am listening for. print ( 'Subscription 1:' , await client.subscribe([ 'Status' , 'Audio' , 'Microphones' , 'Mute' ], callback, True )) When something happens on the feedback we can parse it in the callback function. I have modified the function a bit here, I am checking the first feedback id (id 0) if the audio volume goes above 60, set it back. async def callback(data, id_): print ( f'Feedback (Id {id_}): {data}' ) if id_ == 0 : if data[ 'Status' ][ 'Audio' ][ 'Volume' ] > 60 : await client.xCommand([ 'Audio' , 'Volume' , 'Set' ], Level = 60 ) Output currently looks like this when I increase the volume to 65: Status Query: {'Status': {'SystemUnit': {'Software': {'DisplayName': 'RoomOS 2019-04-26 363d7728a2a'}}}} Get: 65 Command: {'status': 'OK'} Configuration: True Subscription 0: 0 Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} Subscription 1: 1 Feedback (Id 1): {'Status': {'Audio': {'Microphones': {'Mute': 'Off'}}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 65}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 65}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 65}}} Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} The request/response is close to realtime and very cool to work with, and with the async aspect of this you can create several instances with multiple devices at the same time. Lets do some more modifications to the script so it looks like this: import xows import asyncio async def start(ip, usr, pw, name): async with xows.XoWSClient(ip, username =usr, password =pw) as client: async def callback(data, id_): print (name + f' Feedback (Id {id_}): {data}' ) if id_ == 0 : if data[ 'Status' ][ 'Audio' ][ 'Volume' ] > 60 : await client.xCommand([ 'Audio' , 'Volume' , 'Set' ], Level = 60 ) print (name + ' Status Query:' , await client.xQuery([ 'Status' , '**' , 'DisplayName' ])) print (name + ' Get:' , await client.xGet([ 'Status' , 'Audio' , 'Volume' ])) print (name + ' Command:' , await client.xCommand([ 'Audio' , 'Volume' , 'Set' ], Level = 60 )) print (name + ' Configuration:' , await client.xSet([ 'Configuration' , 'Audio' , 'DefaultVolume' ], 50 )) print (name + ' Subscription 0:' , await client.subscribe([ 'Status' , 'Audio' , 'Volume' ], callback, True )) print (name + ' Subscription 1:' , await client.subscribe([ 'Status' , 'Audio' , 'Microphones' , 'Mute' ], callback, True )) await client.wait_until_closed() async def task(): codecs = [( '10.10.10.1' , 'admin1' , '' , 'KitPro' ), ( '10.10.10.2' , 'admin' , '' , 'MX300 G2' )] connections = [start(*codec) for codec in codecs] await asyncio.wait(connections) asyncio.run(task()) Now we setup a connection running the same task on both devices, all I need to do is to add mode devices to the "codecs" object. See below for the output (nice and async :) ): MX300 G2 Status Query: {'Status': {'Call': [{'id': 7, 'DisplayName': ''}], 'SIP': {'CallForward': {'DisplayName': ''}}, 'SystemUnit': {'Software': {'DisplayName': 'ce 9.8.0 ece17b2774f 2019-04-02'}}}} KitPro Status Query: {'Status': {'SystemUnit': {'Software': {'DisplayName': 'RoomOS 2019-04-26 363d7728a2a'}}}} MX300 G2 Get: 60 KitPro Get: 60 MX300 G2 Command: {'status': 'OK'} KitPro Command: {'status': 'OK'} MX300 G2 Configuration: True KitPro Configuration: True MX300 G2 Subscription 0: 0 MX300 G2 Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} MX300 G2 Subscription 1: 1 MX300 G2 Feedback (Id 1): {'Status': {'Audio': {'Microphones': {'Mute': 'Off'}}}} KitPro Subscription 0: 0 KitPro Feedback (Id 0): {'Status': {'Audio': {'Volume': 60}}} KitPro Subscription 1: 1 KitPro Feedback (Id 1): {'Status': {'Audio': {'Microphones': {'Mute': 'Off'}}}} With these examples in place I hope you are able to take advantage of the pyxows library and create something awesome. The above works like a charm for test sequences, provisioning of multiple commands / configs and status checks etc. Use with Macros and In-Room Control? Go ahead! Have fun, and please ask if you have questions. Implementation This is an integration feature like the XMLAPI its a different way of communicating with the xAPI but with the speedy benefits of WebSockets and pure JSON communication. Feel free to build on the examples in this blog post and create something awesome! Known Issues & Limitations Degraded error handling for WebSocket - improvment request for this is filed. Application errors will also be better documented in the future for those that wants to build their own WebSocket implementations. Troubleshooting, diagnostics, limitations and advisories When a new configuration or command is issues via WebSocket you will see this in the endpoint logs with the user that issued the command. 2019-02-01T14:52:10.073+01:00 appl[2177]: CuilApp[1]: User remotesupport/websocket about to execute command '/UserInterface/OSD/Key/Click Key: Left' from 10.10.10.5. 2019-02-01T14:52:12.078+01:00 appl[2177]: CuilApp[1]: User remotesupport/websocket about to execute command '/UserInterface/OSD/Key/Click Key: Right' from 10.10.10.5. 2019-02-01T14:52:14.082+01:00 appl[2177]: CuilApp[1]: User remotesupport/websocket about to execute command '/UserInterface/OSD/Key/Click Key: Up' from 10.10.10.5. 2019-02-01T14:52:16.087+01:00 appl[2177]: CuilApp[1]: User remotesupport/websocket about to execute command '/UserInterface/OSD/Key/Click Key: Down' from 10.10.10.5.     ... View more

Hi everyone! Its soon Christmas and I have been reviewing the features of the upcoming CE9.6.1 release (currently targeted for early January) and I can tell you that there is a few interesting features that comes with this release! In particular I am talking about custom HTTP POST and PUT requests that will open the door to countless new scenarios that has not been possible before. In combination with USB input devices and hiding of the default UI buttons this release is soaked in integration awesomeness. HttpClient POST in xAPI and Macros Feature summary Allow utilization of the codec HttpClient to do custom HTTP(S) POST and PUT requests on demand via the xAPI or using Macros. The requests can be sent to a third party server for triggering new actions or for data collection. Feature description and functional overview Purpose The purpose of this feature is to allow on-demand data collection or distribution and not rely on webhooks. A webhook (synonymous with the all familiar HttpFeedback in this context) is just the same thing, a HTTP(S) POST coming from the Room Device to some server (for example TMS relies on these webhooks to collect data from the Room Devices). The problem is that a HttpFeedback Webhook is quite specific to what it will send (including structure of the payload) and it also needs to be triggered by an event on the endpoint to fire the request.   The difference that comes with HttpClient POST / PUT is that you can send the data whenever you want, you choose what data to send and how to structure it. With that you can adapt the request to an already established service running on your network and not vice versa.   Note: For this feature to be useful you should have a service that can take the requests coming from the Room Device, parse, store, process or whatever suits a given use-case. This is what the feature is for: data collection from the Room Device or use as a webhook to trigger other actions or tasks in third-party services... with me so far?    Functional overview   Lets take a look at a very high-level diagram, the XMLAPI and the Macros are both channels to utilize the xAPI. Using the added xAPI command HttpClient Post or Put you can send customized data to third-party servers. If you wonder if POST is supported back to the endpoint the answer is partly "yes" and partly "no". "Yes" because it is and has been supported for a long time but currently only via the XMLAPI (/putxml) so this is not new. "No" because the new HttpClient only supports outgoing data and will not have access to incoming response payloads or headers, only the status code and a brief error description, but for now this should not be a big issue. Getting started! Now this is currently not yet available so, I am sorry for being a tease, but its something to look forward to and I could not wait to write about this!   To get started you must first enable the HttpClient using a xConfiguration (or via the web interface):   xConfiguration HttpClient Mode: On This is required to send request, which means you also can disallow outgoing data for integration users for example.   The actual request is performed using a xCommand, lets look at our arsenal:   xcommand //httpclient ? xCommand HttpClient Allow Hostname Add Expression(r): <S: 2, 200> xCommand HttpClient Allow Hostname Clear xCommand HttpClient Allow Hostname List xCommand HttpClient Allow Hostname Remove Id(r): <0..9> xCommand HttpClient Post AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> Url(r): <S: 8, 2048> xCommand HttpClient Put AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> Url(r): <S: 8, 2048>   There is a few commands here, but lets not rush it to avoid confusion and jump right to the good stuff!   Lets try out the HttpClient Post from one endpoint (EP1) to another (EP2) imagining that the XMLAPI on EP2 device is the "Third-party remote HTTP Server" in the diagram above.   mohm$ echo admin:1234 | base64 YWRtaW46MTIzNAo= In order to authenticate to a different endpoint I need to base64 encode the credentials for this example, see above. This is needed for the HttpClient Post "Authorization" Header.   The HttpClient Post and Put commands supports up to 10 headers and are issued as follows directly into the xAPI (this is via SSH):   xCommand HttpClient Post Header: "Authorization: Basic YWRtaW46MTIzNAo=" Header: "Content-Type: text/xml" Url: http://codec-ip/putxml The above example should give you an idea of how you issue multiple headers in the xAPI. For each header you need a new "Header: "Header1" Header: "Header2" etc.. ". Usually it is enough with a Content-Type and an Authorization header but that depends on the server.   So the next part is the data, the actual payload that we will send to the remote server. You need to send some data that will be posted to the third party server (and constructed in a way so that the server can parse it). When you hit enter on the above command, nothing seems to happen - well duh, its a multi line command. Now that we have the authorization and data type in the headers the command expects that you insert whatever data you are going to send. Below is how it looks like after I have issued the command:   xCommand HttpClient Post Header: "Authorization: Basic YWRtaW46MTIzNAo=" Header: "Content-Type: text/xml" Url: http://codec-ip/putxml <Configuration><SystemUnit><Name>Hello World!</Name></SystemUnit></Configuration> . OK *r HttpClientPostResult (status=OK): *r HttpClientPostResult StatusCode: 200 ** end See description of the above below:   Command xCommand HttpClient Post Header: "Authorization: Basic YWRtaW46MTIzNAo=" Header: "Content-Type: text/xml" Url: http://10.47.97.195/putxml <enter> Data (Payload) - The data you type in here should really match the Content-Type Header, which in this case is text/xml <Configuration><SystemUnit><Name>Hello World!</Name></SystemUnit></Configuration> <enter> End input . <enter> OK *r HttpClientPostResult (status=OK): *r HttpClientPostResult StatusCode: 200 ** end The xAPI will output the StatusCode only. If the server returns data with the request it will not be displayed, which is  the biggest limitation of this feature.   Now that we know that the HttpClient Post works as expected (yes, I checked that EP2 changed the displayname to "Hello World!") we can go ahead and create a simple REST API just for the fun of it and try it with a Macro!   I will not go through what a REST API is or go through how its done, I will just show you the code of an "embarrassingly" simple REST API in Python 3.7 using Flask so think of this as a very simplified simulation of the real thing. This is just for learning the nature of the HttpClient Post and Put.   api.py from flask import Flask from flask import abort from flask import jsonify from flask import request app = Flask(__name__) database = [ { 'call' : 1 , 'destination' : u'jaeger@pacific.rim' }, { 'call' : 2 , 'destination' : u'king@kong.com' } ] @app.route ( '/api' , methods =[ 'POST' ]) def create_call(): if not request.json or 'destination' not in request.json: abort( 400 ) else : new_call = { 'call' : database[- 1 ][ 'call' ] + 1 , 'destination' : request.json[ 'destination' ]} database.append(new_call) return jsonify({ 'response' :database}), 200 if __name__ == '__main__' : app.run( debug = True , host = 'serverIP' ) #Change server IP to the host where you run this script   mohm$ python3.7 api.py * Running on http://serverIP:5000/   Ok, the whole point of the above is to collect call destinations from an incoming POST to the http://serverIP/api I will return the full database upon a successful add of a new call. I expect the server to return a call: 3 with the destination I manually assign, since this is a custom request I don´t have to actually wait for the endpoint to make a call before its sent. Lets try it.   I have enabled "log ctx httpclient debug 9" on the codec so we can see the request in and out (you can also use wireshark):   log ctx httpclient debug 9 log output on xcommand HttpClient Post Header: "Content-Type: application/json" Url: http://serverIP:5000/api {"destination":"new@destination.com"} . OK CuilApp[1]: User admin1/shell about to execute command '/HttpClient/Post Header: Content-Type: application/json Url: http://serverIP:5000/api' from serverIP. HttpClient[8]: Engine::addNewRequest CuilApp[1]: HTTP(77) => POST http://serverIP:5000/api HttpClient[1]: HTTP: Outgoing => POST http://serverIP:5000/api HttpClient[3]: [curl] Connected to serverIP (serverIP) port 5000 (#2099) HttpClient[3]: [header OUT] POST /api HTTP/1.1 HttpClient[3]: [header OUT] Host: serverIP:5000 HttpClient[3]: [header OUT] Accept: */* HttpClient[3]: [header OUT] Content-Type: application/json HttpClient[3]: [header OUT] User-Agent: Cisco/CE HttpClient[3]: [header OUT] Accept-Charset: ISO-8859-1,utf-8 HttpClient[3]: [header OUT] Content-Length: 37 HttpClient[3]: [header OUT] ---- HttpClient[9]: [data OUT] {"destination":"new@destination.com"} HttpClient[3]: [header IN] HTTP/1.0 200 OK HttpClient[3]: [header IN] Content-Type: application/json HttpClient[3]: [header IN] Content-Length: 240 HttpClient[3]: [header IN] Server: Werkzeug/0.14.1 Python/3.7.0 HttpClient[3]: [header IN] Date: Thu, 18 Oct 2018 19:33:18 GMT HttpClient[9]: [data IN] { HttpClient[9]: [data IN] "response": [ HttpClient[9]: [data IN] { HttpClient[9]: [data IN] "call": 1, HttpClient[9]: [data IN] "destination": "jaeger@pacific.rim" HttpClient[9]: [data IN] }, HttpClient[9]: [data IN] { HttpClient[9]: [data IN] "call": 2, HttpClient[9]: [data IN] "destination": "king@kong.com" HttpClient[9]: [data IN] }, HttpClient[9]: [data IN] { HttpClient[9]: [data IN] "call": 3, HttpClient[9]: [data IN] "destination": "new@destination.com" HttpClient[9]: [data IN] } HttpClient[9]: [data IN] ] HttpClient[9]: [data IN] } HttpClient[9]: [data IN] ---- CuilApp[1]: HTTP(77) <= 200 By doing this we can confirm functionality before we put it into a Macro like this: const xapi = require('xapi'); var payload; var data = {'destination': ''}; function sendPOSTtoAPI(data){ payload = JSON.stringify(data); xapi.command('HttpClient Post', { Header: "Content-Type: application/json", Url: 'http://serverIP:5000/api' }, payload) .then((result) => {     console.log("success:" + result.StatusCode)   })   .catch((err) => {       console.log("failed: " + err.message)   }); } xapi.event.on('OutgoingCallIndication', (status) => { xapi.status.get('Call', {'CallId': status.CallId}).then((call) => { data.destination = call[0].RemoteNumber; sendPOSTtoAPI(data); } ); }); The above Macro basically looks for a OutgoingCallIndication event. You may be thinking "isnt this just another webhook?". YES it is but I get to choose what data I´ll be sending which is only the remote number that the device is trying to call). Once it has the OutgoingCallIndication (the ID of the call) it looks up the call details and finds the remote number which is then forwarded to my super advanced Python REST API.   So, lets see..   Making a few calls and this is displayed in the macro console if you print the payload and the event using console.log (not included in the macro): 22:21:56 callMonitor'[{"id":"21","AnswerState":"Unanswered","CallType":"Video","CallbackNumber":"spark:test@test1.com","DeviceType":"Endpoint","Direction":"Outgoing","DisplayName":"","Duration":"0","Encryption":{"Type":"Unknown"},"FacilityServiceId":"0","HoldReason":"None","PlacedOnHold":"False","Protocol":"Spark","ReceiveCallRate":"6000","RemoteNumber":"test@test1.com","Status":"Dialling","TransmitCallRate":"6000"}]' 22:21:56 callMonitor'{"destination":"test@test1.com"}' 22:22:05 callMonitor'[{"id":"22","AnswerState":"Unanswered","CallType":"Video","CallbackNumber":"spark:test@test2.com","DeviceType":"Endpoint","Direction":"Outgoing","DisplayName":"","Duration":"0","Encryption":{"Type":"Unknown"},"FacilityServiceId":"0","HoldReason":"None","PlacedOnHold":"False","Protocol":"Spark","ReceiveCallRate":"6000","RemoteNumber":"test@test2.com","Status":"Dialling","TransmitCallRate":"6000"}]' 22:22:05 callMonitor'{"destination":"test@test2.com"}' Looking at the logs, as from above I see that the entries are added successfully. This was just one use case but you can re-use what you have learned to send whatever data you want to collect. Knock yourself out!   PUT REQEUSTS PUT requests and allow lists for hosts   A PUT request is essentially the same as a POST, but within a REST API the different method have different meaning. When you design a REST API you may want to filter the operations based on the methods where POST = Create new and PUT = Modify existing. The PUT request is handled the same was as the POST demonstrated above, but how the server side handles the request methods may be different. This is anyway up to the developer / integrator to decide and handle as such.   xCommand HttpClient Put AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> Url(r): <S: 8, 2048>   Allow lists Lets move over to the prevention stuff. You may setup host allow lists, which means that you can list up the hosts that the HttpClient can talk to. If the allow list has been populated with one or more host filter it will check if the host exists in this list before sending the request. If not the request will be denied. This is useful when you have multiple users for example a user with integrator rights but not admin access. The admin decides which service the codec is allowed to send data to.    xCommand HttpClient Allow Hostname Add Expression(r): <S: 2, 200> xCommand HttpClient Allow Hostname Clear xCommand HttpClient Allow Hostname List xCommand HttpClient Allow Hostname Remove Id(r): <0..9> To whitelist a host use the following command type in the hostname or IP as the expresstion (whatever is used to connect to the server):   xCommand HttpClient Allow Hostname Add Expression: 10.10.10.10 xCommand HttpClient Allow Hostname Add Expression: server.domain.com   Don´t include http:// or custom port numbers only the host name or IP. If a POST request is sent to a server that is not in the allow list:   xCommand HttpClient Post Header: "Content-Type: application/json" Url: http://10.10.10.20:5000/api . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult Message: "URL not allowed by rule" ** end If the host is not reachable:   xcommand HttpClient Post Header: "Content-Type: application/json" Url: http://10.10.10.25:5000/api . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult Message: "Timeout was reached" ** end   This concludes the functional section as an example on how to utilize this feature for custom data collection, feel free to use code found in this article to learn and experiment.    Other use-cases (Webex Teams and BOTS) Integrate with Webex Teams to post messages or create a space in webex teams when something happens on the device (requires a bot / user API access token).   Ok, even though we went through the functional overview and you should now have an idea of how it works, lets do an example of sending a message to a user in Webex Teams whenever a user makes a call, we will use and build on the same Macro we have used so far, we will also learn how to authenticate the certificate. Lets start:   xCommand HttpClient Post Url: https://api.ciscospark.com/v1/messages . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult Message: "Peer certificate cannot be authenticated with given CA certificates" ** end Ok, so what I did above is just to test the connection the the Webex Teams API, and it won´t let me since the Certificate cannot be verified by any of my custom Root CA´s, well actually I don´t believe there are any custom Root CA´s available for the HttpClient, this will hopefully improve in the future. If you really want to verify the certificate let´s work around it using a few simple steps:   In Firefox:       Hover the mouse pointer over the green padlock. Verified by: GoDaddy.com, Inc. OK so lets find that Root CA, go to the Preferences -> Privacy & Security -> View Certificates (at the bottom) and locate the GoDaddy Root CA.     Now export this CA as x509 (PEM) and save it wherever.   Go to the codec web interface and add the exported certificate to the list of Certificate Authorities (not Service Certificate):       Once done, check it:   xcommand HttpClient Post Url: https://api.ciscospark.com/v1/messages . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult StatusCode: 401 ** end 401 Unauthorized as expected. Good, lets proceed to the Macro since the status code confirms that I can now send data to Webex Teams (we need the Authorization header).   const xapi = require('xapi'); var data = {'destination': ''}; var accesstoken = 'BOT-ACCESSTOKEN'; function sendPOSTtoWebexTeams(data){ var payload = JSON.stringify({'toPersonEmail':'YOUR@EMAIL.ADDRESS', 'markdown': "<blockquote class=success>Hey! LAB-101-RoomKit just made a call to: " + data.destination + "</blockquote>"}); console.log(payload); xapi.command('HttpClient Post', { Header: ["Content-Type: application/json", "Authorization: Bearer " + accesstoken], Url: "https://api.ciscospark.com/v1/messages" }, payload) .then((result) => {     console.log("success:" + result.StatusCode)   })   .catch((err) => {       console.log("failed: " + err.message)   }); } xapi.event.on('OutgoingCallIndication', (status) => { xapi.status.get('Call', {'CallId': status.CallId}).then((call) => { data.destination = call[0].RemoteNumber; console.log(JSON.stringify(call)); sendPOSTtoWebexTeams(data); } ); }); So I have just made a small modification to the previous Macro (mainly adding a bot access token and changing the URL and payload). More info on the Webex Teams API´s can be found on https://developer.webex.com   Note that the accesstoken is removed from the above example and you must add your own for this to work, change the "BOT-ACCESSTOKEN" with your bots accesstoken (acquired from the website link above) and the "YOUR@EMAIL.ADDRESS" with your email address (must be tied to a Webex Teams account). ALSO note that, in order to send multiple headers using a Macro you have to issue the headers in an Array.   *snip* Header: ["Content-Type: application/json", "Authorization: Bearer " + accesstoken] *snip* If I now make a call to someone I should get a ping from my bot with the number the device is trying to call. You can modify the script to fetch the device name or to however you want the text to look like. I successfully received a message:     Need to send data to other public API´s or your own service? Just follow the same process as above to enable certificate verification or if you trust the service you can bypass the ceritifcate verification, see below for instructions.    RoomOS May 2019 / CE9.8.0 June 2019 - Changes Author: Magnus Ohm Here comes an update for the HttpClient feature! We have now added some more long awaited candy! For you who are registered on Webex Teams, this feature is available NOW! For CE9.8.0, you have to wait until early summer :( - Added new HTTP request methods such as, GET / PATCH / DELETE - You can now see the returning response headers and body, not only the status code but all of the actual data returned from the server. This feature extension adds a lot of missing flexibility! You can now read and use values from external web servers by polling them. Let´s give some examples. I assume you have already read my article to get an understanding of the feature before looking at the changes. xcommand //httpclient xCommand HttpClient Allow Hostname Add - Adds an HTTP(S) server to the list of allowed servers (hosts). The HttpClient Allow Hostname commands let you set up and maintain a list of up to ten allowed hosts. As long as the list is not empty, you can send HTTP(S) requests only to the servers in the list. The check against the list is performed both when using insecure (HTTP) and secure (HTTPS) transfer of data. Expression(r): <S: 2, 200> xCommand HttpClient Allow Hostname Clear - Removes all HTTP(S) servers from the list of allowed servers (hosts), leaving you with an empty list. xCommand HttpClient Allow Hostname List - Returns the list of allowed HTTP(S) servers (hosts). The HttpClient Allow Hostname commands let you set up and maintain a list of up to ten allowed hosts. As long as the list is not empty, you can send HTTP(S) requests only to the servers in the list. The check against the list is performed both when using insecure (HTTP) and secure (HTTPS) transfer of data. xCommand HttpClient Allow Hostname Remove - Removes an HTTP(S) server from the list of allowed servers (hosts). Use the HttpClient Allow Hostname List command to find the indentifier of each entry in the list. Id(r): <0..9> xCommand HttpClient Delete - Sends an HTTP(S) Delete request to the server that is specified in the Url parameter. AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> ResponseSizeLimit: <0..100000> (default 100000) ResultBody: <None, PlainText, Base64> (default None) Timeout: <1..30> (default 30) Url(r): <S: 8, 2048> xCommand HttpClient Get - Sends an HTTP(S) Get request to the server that is specified in the Url parameter. AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> ResponseSizeLimit: <0..100000> (default 100000) ResultBody: <None, PlainText, Base64> (default PlainText) Timeout: <1..30> (default 30) Url(r): <S: 8, 2048> xCommand HttpClient Patch - Sends an HTTP(S) Patch request to the server that is specified in the Url parameter. AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> ResponseSizeLimit: <0..100000> (default 100000) ResultBody: <None, PlainText, Base64> (default None) Timeout: <1..30> (default 30) Url(r): <S: 8, 2048> xCommand HttpClient Post - Sends an HTTP(S) Post request to the server that is specified in the Url parameter. You can use the AllowInsecureHTTPS parameter to specify whether or not to validate the server’s certificate before sending data over HTTPS. This parameter has no effect unless the xConfiguration HttpClient AllowInsecureHTTPS is set to On. This is a multiline command, so the payload (data) follows after the parameters. AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> ResponseSizeLimit: <0..100000> (default 100000) ResultBody: <None, PlainText, Base64> (default None) Timeout: <1..30> (default 30) Url(r): <S: 8, 2048> xCommand HttpClient Put - Sends an HTTP(S) Put request to the server that is specified in the Url parameter. You can use the AllowInsecureHTTPS parameter to specify whether or not to validate the server’s certificate before sending data over HTTPS. This parameter has no effect unless the xConfiguration HttpClient AllowInsecureHTTPS is set to On. This is a multiline command, so the payload (data) follows after the parameters. AllowInsecureHTTPS: <False, True> (default False) Header[N]: <S: 0, 1024> ResponseSizeLimit: <0..100000> (default 100000) ResultBody: <None, PlainText, Base64> (default None) Timeout: <1..30> (default 30) Url(r): <S: 8, 2048> OK As you see above there are a few changes to the HttpClient xCommand and its parameters. The most obvious I have highligted  but we can now also receive the response headers and body (optional). A timeout setting where we can define when the request should timeout within a range of 1-30 seconds is also conveniently added.  I am just going to continue on our BOT / Macro example above since the Webex Teams API supports most of the new request headers, and also allows us to take advantage of the GET APIs. I have created a couple of more functions to enable the new functionality. const xapi = require('xapi'); const wxAPIs = { 'people':'https://api.ciscospark.com/v1/people', 'message': 'https://api.ciscospark.com/v1/messages', 'space':'https://api.ciscospark.com/v1/rooms' }; var payload; var accesstoken = 'ACCESSTOKEN'; function spaceCreate(title) { payload = JSON.stringify({'title': title}); sendWebexTeams(wxAPIs.space, 'Post', payload); } function sendWebexTeams(url, method, data=NULL) { xapi.command('HttpClient ' + method, { Header: ["Content-Type: application/json", "Authorization: Bearer " + accesstoken], Url: url, AllowInsecureHTTPS: 'True', ResultBody: 'plaintext' }, data) .then((result) => { console.log("success:" + JSON.stringify(result)); }) .catch((err) => { console.log("failed: " + JSON.stringify(err)); }); } spaceCreate("Test space"); The above request will basically create a new space with only the BOT inside it. It is not new that you can do this, but in order to re-use the space you have just created you need the space ID. There was no way the macro could retrieve the space ID when doing the same action before CE9.8.0 / RoomOS May. See below for the full response for and note that I have enabled the result body in the xCommand so that I receive the response from the server that includes the space ID I need to proceed with my experiment. {"status":"OK", "Body":"{"id":"Y2lzY29zcGFyazovL3VzL1JPT00vZDlhOWEzZTtNmZlOC0xMWU5LThlNWMtZGI2ZGMwZWMyYmUw", "title": "Test space", "type": "group", "isLocked": false, "lastActivity": "2019-05-06T10:22:28.638Z", "creatorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8ZjM4NjIzMi1kNjgyLTRkM2EtOWU4My1lZjAxZWQ0MTNjYjY", "created": "2019-05-06T10:22:28.638Z"}", "Headers":[ {"id":"1", "Key":"Strict-Transport-Security", "Value":"max-age=63072000; includeSubDomains; preload"}, {"id":"2", "Key":"Vary", "Value":"Accept-Encoding"}, {"id":"3", "Key":"Content-Type", "Value":"application/json;charset=UTF-8"}, {"id":"4", "Key":"Transfer-Encoding", "Value":"chunked"}, {"id":"5", "Key":"Via", "Value":"1.1 linkerd"}, {"id":"6", "Key":"l5d-success-class", "Value":"1.0"}, {"id":"7", "Key":"Date", "Value":"Mon, 06 May 2019 10:22:29 GMT"}, {"id":"8", "Key":"TrackingID", "Value":"ROUTER_5CD00AE4-D004-01BB-0054-AD26DC2A0054"}, {"id":"9", "Key":"Server", "Value":"Redacted"}], "StatusCode":"200"} "id":"Y2lzY29zcGFyazovL3VzL1JPT00vZDlhOWEzZTAtNmZlC0xMWU5LThlNWMtZGI2ZGMwZWMyYmUw" Now with the space id I can view the members add more users to the space using the membership API. Adding the following to the macro above produces this output: function spaceGetMembers(roomId) { sendWebexTeams(wxAPIs.members + "?roomId="+roomId, 'Get'); } spaceGetMembers("Y2lzY29zGFyazovL3VzL1JPT00vZDlhOWEzZTAtNmZlC0xMWU5LThlNWMtZGI2ZGMwZWMyYmUw"); Now I am using the GET method, which is just a read verb and the Macro gets access to the response body. From the below I could generate some UI elements that displays the members for example. The opportunities for integration and creativity here is endless. {"status":"OK", "Body":"{"items": [{"id":"Y2lzY29zcGFyazovL3VzL0FTUJFUlNISVAvNWYODYyMzItZDY4Mi00ZDNhLTllODMtZWYwMWVkNDEzY2I2OmQ5YTlhM2UwLTZmZTgtMTFlOS04ZTVjLWRiNmRjMGVjMmJlMA", "roomId":"Y2lzY29zcGFyazovL3VzL1JPT00vZDlhOWEzZTAtNmZlOC0xMWU5LThlNWMtZGI2ZGMwZWMyYmUw", "personId":"Y2lzY29zcGFyazovL3VzL1BFT1BMRS81ZjM4NjIzMi1kNjgyLTRkM2EtOWU4My1lZjAxZWQ0MTNjYjY", "personEmail":"release@webex.bot", "personDisplayName":"Releasebot", "personOrgId":"Y2lzY29zcGFyazovL3VzL09SR0FOSVBVElPTi8xZWI2NWZkZi05NjQzLTQxN2YtOTk3NC1hZDcyY2FlMGUxMGY", "isModerator":false, "isMonitor":false, "created":"2019-05-06T10:22:29.397Z\\"}]}", "Headers":[{"id":"1","Key":"Strict-Transport-Security","Value":"max-age=63072000; includeSubDomains; preload"},{"id":"2","Key":"Vary","Value":"Accept-Encoding"},{"id":"3","Key":"Content-Type","Value":"application/json;charset=UTF-8"},{"id":"4","Key":"Via","Value":"1.1 linkerd"},{"id":"5","Key":"Server","Value":"Redacted"},{"id":"6","Key":"Cache-Control","Value":"no-cache"},{"id":"7","Key":"TrackingID","Value":"ROUTER_5CD01277-AE40-01BB-0053-AD26DC2A0053"},{"id":"8","Key":"Transfer-Encoding","Value":"chunked"},{"id":"9","Key":"l5d-success-class","Value":"1.0"},{"id":"10","Key":"Date","Value":"Mon, 06 May 2019 10:54:47 GMT"}], "StatusCode":"200"} For now only the bot is in the space, so I will add my self to the space using the macro. The Webex Teams API uses POST to add new members. function spaceAddMembers(roomId, email) { payload = JSON.stringify({ 'roomId': roomId, 'personEmail': email }); sendWebexTeams(wxAPIs.members, 'Post', payload); } spaceAddMembers("Y2lzY29zcGFyazovL3VzL1JPT00vZDlOWEzZTAtNmZlOC0xMWU5LThlNWMtZGI2ZGMwZWMyYmUw", "mohm@cisco.com"); With the above the server will return to me the membership ID (also returned on list members) which I can use to modify moderator priveleges with. So I want to make myself moderator of the space, the bot aill automatically get moderator as well since the mod flag was set through the API.For this operation the Webex Teams API expects "PUT". function memberSetModerator(membershipid) { payload = JSON.stringify({ 'isModerator': true, }); sendWebexTeams(wxAPIs.members + '/' + membershipid, 'Put', payload); } memberSetModerator('Y2lzY29zcGFyazovL3VzL01FTUJFUlNISVAvNzkyMDY0ZmYtMmMxOS00MmY4LWI2NTEtNmQ4NGZlMmNhMWM2OmQ5YTlhM2UwLTZmZTgtMTFlOS04ZTVjLWRiNmRjMGVjMmJlMA'); The bot changed our status to moderators! Finally I can use the DELETE method to remove members: function memberDelete(membershipid) { sendWebexTeams(wxAPIs.members + '/' + membershipid, 'Delete'); } memberDelete('Y2lzY29zcGFyazovL3VzL01FTUJFUlNISVAvNzkyMDY0ZmYtMmMxOS00MmY4LWI2NTEtNmQ4NGZlMmNhMWM2OmQ5YTlhM2UwLTZmZTgtMTFlOS04ZTVjLWRiNmRjMGVjMmJlMA'); Other notes You can decide the max size on the incoming payload up to 100 000 bytes, this size is restricted to avoid tons of incoming data overloading the system. If the response payload is larger than the set size the request will fail! 'failed: {"code":0,"message":"HttpClientGetResult","data":{"status":"Error","Message":"Maximum file size exceeded/Failed to write data to disk"}}' So the codec HTTP Client is not designed to scrape large web sites with tons of information and designed mainly for API communication. But this all depends on what the remote server returns. Set the timeout by using the Timeout flag to kill the connections on a shorter timeout if aspplicable. The PATCH method is examplified here because I did not have an API that uses this method properly, but its essentially requested the same way as the POST and PUT with a JSON or XML payload (depending on the server) and is normally used for partial updates. This is API dependant but we support the request if applicable. Read the external API guide provided by the third party for more requirements. So the full Macro after the above demos looks like this: const xapi = require('xapi'); const wxAPIs = { 'people':'https://api.ciscospark.com/v1/people', 'message': 'https://api.ciscospark.com/v1/messages', 'space':'https://api.ciscospark.com/v1/rooms', 'members':'https://api.ciscospark.com/v1/memberships' }; var payload; var accesstoken = 'ACCESSTOKEN-BOT'; function sendWebexTeams(url, method, data=null) { xapi.command('HttpClient ' + method, { Header: ["Content-Type: application/json", "Authorization: Bearer " + accesstoken], Url: url, AllowInsecureHTTPS: 'True', ResultBody: 'none' }, data) .then((result) => { console.log("success:" + JSON.stringify(result)); }) .catch((err) => { console.log("failed: " + JSON.stringify(err)); }); } function spaceCreate(title) { payload = JSON.stringify({'title': title}); sendWebexTeams(wxAPIs.apace, 'Post', payload); } //spaceCreate('<space title>'); function spaceGetMembers(roomId) { sendWebexTeams(wxAPIs.members + "?roomId="+roomId, 'Get'); } //spaceGetMembers('<spaceid>'); function spaceAddMembers(roomId, email) { payload = JSON.stringify({ 'roomId': roomId, 'personEmail': email }); sendWebexTeams(wxAPIs.members, 'Post', payload); } //spaceAddMembers('<spaceid>', '<user you want to add email>'); function memberSetModerator(membershipid) { payload = JSON.stringify({ 'isModerator': true, }); sendWebexTeams(wxAPIs.members + '/' + membershipid, 'Put', payload); } //memberSetModerator('<membershipid>'); function memberDelete(membershipid) { sendWebexTeams(wxAPIs.members + '/' + membershipid, 'Delete'); } //memberDelete('<membershipid>'); With a hint of creativity you can use the above to create something cool between your Room Device and Webex Teams (Or other third party stuff). More Webex Teams API documentation can be found on https://developer.webex.com   Have fun!   Known Issues & Limitations HTTPS Requires (by default) a signed CA certificate to authenticate the remote server certificate.   If you are attempting to connect to a host over HTTPS the HttpClient will try to authenticate the installed certificate with the server certificate. Self-signed certificates will therefore not work by default. In order to use secure HTTPS without bypass you must install a signed CA certificate.   xcommand HttpClient Post Url: https://api.ciscospark.com/v1/messages . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult Message: "Peer certificate cannot be authenticated with given CA certificates" ** end To workaround the issue you can bypass the certificate verification (although not recommended) to get the request through. This is a flag that has to be set per request. Firstly you have to enable the codec to send insecure HTTPS requests, if this is set to False you will get an error (Insecure HTTPS not allowed). Once set to "True" you can send insecure HTTPS requests. This is not recommended, but we implemented a way for customers to do this against self-signed certificatge servers they may be testing against. See below for an example. Here I do not need a signed CA to go forward with the request.   xcommand HttpClient Post Url: https://api.ciscospark.com/v1/messages Header: "Content-Type: application/json" AllowInsecureHTTPS: True . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult Message: "Insecure HTTPS not allowed" ** end xConfiguration HttpClient AllowInsecureHTTPS: True ** end OK xcommand HttpClient Post Url: https://api.ciscospark.com/v1/messages Header: "Content-Type: application/json" AllowInsecureHTTPS: True . OK *r HttpClientPostResult (status=Error): *r HttpClientPostResult StatusCode: 401 ** end   Payload IN and headers IN is not currently supported.  We do not currently support fetching feedback from the server when doing a HTTP POST or PUT via Macro or xAPI, but it can be seen in the logs if a high debug level is enabled. The only feedback we get is the request status code and a description.   Support for 3rd party USB input devices (keyboards for use with In-Room Control) Now, after looking at the HTTP POST / PUT feature I want to talk about adding support for USB keyboards and just to make it clear, this is not a "replace the Touch 10 keyboard input" feature,  as in, we do not offer it as a supplement for typing in long and complicated URI´s quicker ;), no, no, this is a In-Room Control feature where every key-click on the keyboard generates an event, and events can be used for doing cool stuff! I hope you are as excited as me for this one. Summary We continue to take In-Room Controls to new levels, now supporting 3rd party USB input devices (as in input devices that are seen by the codec as generic "keyboards")! With this simple feature you can do awesome stuff for example, control your device behavior using a generic Bluetooth remote (with USB dongle) or USB keyboard, imagine starting the meeting and composing input sources into the main video while walking around in the room with a wireless USB clicker from Logitech?! Play with that idea for a moment before we explore the world of opportunities with this feature.  Feature summary We will take a look at how to utilize third-party input devices to provide an overview of how this feature works and how it can benefit certain scenarios. This feature opens up a whole lot of new integration angles for customization of device behavior. In other words, pure awesomeness! See below for a couple of generic devices we will be utilizing for this walk through:     Regular (found in trash) USB keyboard USB media remote, bought of the shelf at a general electric shop Feature description, functional overview, compatibility  Purpose The purpose of this feature is to extend In-Room Control with more options for third party integration on our newest portfolio (yea unfortunately this is only supported on the Cisco Webex Room Series, and the DX70 and DX80 which is kind of a comfort and actually have a few use-cases). A wireless remote control like the one in the image above can for example, replace some functionality of a Touch 10 with the benefit of being able to carry it around and for example unmute the device from a distance (just saying, I actually use this remote in all my meetings now, its really handy ;)).   Functional overview The generic USB input device will when a button is pressed, generate an event in the xAPI allowing macros or third-party control devices react upon the event in the same manner as the Touch 10 In-Room Control widgets generate events upon state changes.    So lets get started by hooking up our wireless remote control to a Cisco Webex Codec Plus. We will use the available USB-A input on the device.   Cisco Webex Codec Plus <3 Now SSH into the Codec Plus (xAPI) and let the magic happen...   xConfig //inputdevice *c xConfiguration Peripherals InputDevice Mode: Off ** end OK xConfiguration Peripherals InputDevice Mode: On ** end OK xFeedback Register /event/userinterface/inputdevice ** end OK xFeedback list /event/userinterface/inputdevice ** end OK   What is happening above is that I first of all, enable the feature which is required for the device to even see my connected keyboard. Then I register a session feedback, this is basically the same as the macro xapi.event.on() method and it can be used to trigger actual events but I mostly use it to test events to see what they produce. Now, press a few buttons on the third-party USB input device to make sure it works! I call them USB input devices since these generic keyboard imitators come in many shapes (USB Super Nintendo controllers? you bet!).   *e UserInterface InputDevice Key Action Key: KEY_ENTER *e UserInterface InputDevice Key Action Code: 28 *e UserInterface InputDevice Key Action Type: Pressed ** end *e UserInterface InputDevice Key Action Key: KEY_ENTER *e UserInterface InputDevice Key Action Code: 28 *e UserInterface InputDevice Key Action Type: Released ** end *e UserInterface InputDevice Key Action Key: KEY_SLEEP *e UserInterface InputDevice Key Action Code: 142 *e UserInterface InputDevice Key Action Type: Pressed ** end *e UserInterface InputDevice Key Action Key: KEY_SLEEP *e UserInterface InputDevice Key Action Code: 142 *e UserInterface InputDevice Key Action Type: Released ** end *e UserInterface InputDevice Key Action Key: KEY_VOLUMEUP *e UserInterface InputDevice Key Action Code: 115 *e UserInterface InputDevice Key Action Type: Pressed ** end *e UserInterface InputDevice Key Action Key: KEY_VOLUMEUP *e UserInterface InputDevice Key Action Code: 115 *e UserInterface InputDevice Key Action Type: Released ** end *e UserInterface InputDevice Key Action Key: KEY_VOLUMEDOWN *e UserInterface InputDevice Key Action Code: 114 *e UserInterface InputDevice Key Action Type: Pressed ** end *e UserInterface InputDevice Key Action Key: KEY_VOLUMEDOWN *e UserInterface InputDevice Key Action Code: 114 *e UserInterface InputDevice Key Action Type: Released ** end   It works! So, now that we can generate events based on button presses on the USB device we can implement reactions to the events. As you see above the button presses generates two different events, one for "Pressed" and one for "Released". So if you press and hold one button you only see one event "Pressed" until you release the button which will generate the second event "Released" which may be handy if you want to implement camera control from the USB device for example.   We can create a remote controller that monitors the events via webhooks, directly in a SSH session or just create a macro (depending on what functionality we want to implement). For this walk through I will use macros for the examples.   Let´s first make something simple, like bringing the standby, volume up and volume down buttons to life. Below is an example macro, yes they also come in different shapes and forms and below is just an example on how it can be done, feel free to use anything in this blog post and improve it!    const xapi = require('xapi'); function com(command) {   xapi.command(command);   log(command); } function log(event) {   console.log(event); } function notify(message) {   xapi.command('UserInterface Message TextLine Display', {     Text: message,     duration: 3   }); } function init() {   let standbyState;   xapi.status.get('Standby').then((state) => {standbyState = state.State === 'Off' ? false : true; })   xapi.status.on('Standby', state => {       standbyState = state.State === 'Off' ? false : true;   });     xapi.event.on('UserInterface InputDevice Key Action', press => {     if (press.Type == "Pressed") {       switch (press.Key) {             default:             break;         }     } else if (press.Type == "Released") {         switch (press.Key) {           case 'KEY_VOLUMEUP':             com('Audio Volume Increase');             break;           case 'KEY_VOLUMEDOWN':             com('Audio Volume Decrease');             break;           case 'KEY_SLEEP':             com(standbyState ? 'Standby Deactivate' : 'Standby Activate');             break;           default:             notify(press.Key + ' is not bound!');             break;           }       }   }); } init(); This macro simply listens for the InputDevice and if it sees an event containing "KEY_VOLUMEUP", "KEY_VOLUMEDOWN" or "KEY_SLEEP" it will execute the related commands:   KEY_VOLUMEUP: Audio Volume Increase KEY_VOLUMEDOWN: Audio Volume Decrease KEY_SLEEP: If in standby or halfwake send Deactivate, If not in standby send Activate If the key that is pressed is not found in the key map dict it will display a notification on the screen that the key is not usable (see below). This is useful when you start adding new event triggers, just press a button and see what it is called and type it into the switch case structure, quick and easy!     Now, lets do one cool thing. Creating a camera control function for the arrow keys, utilizing the "pressed" event.   const xapi = require('xapi'); function com(command, args='') { xapi.command(command, args); log(command + ' ' + JSON.stringify(args)); } function log(event) { console.log(event); } function notify(message) { xapi.command('UserInterface Message TextLine Display', { Text: message, duration: 3 }); } function cameraControl(motor, direction, cameraId='1') { com('Camera Ramp', { 'CameraId': cameraId, [motor]: direction }); } function init() { let standbyState; xapi.status.get('Standby').then((state) => {standbyState = state.State === 'Off' ? false : true; }); xapi.status.on('Standby', state => { standbyState = state.State === 'Off' ? false : true; }); xapi.event.on('UserInterface InputDevice Key Action', press => { if (press.Type == "Pressed") { switch (press.Key) { case "KEY_LEFT": cameraControl('Pan', 'Left'); break; case "KEY_RIGHT": cameraControl('Pan', 'Right'); break; case "KEY_UP": cameraControl('Tilt', 'Up'); break; case "KEY_DOWN": cameraControl('Tilt', 'Down'); break; default: break; } } else if (press.Type == "Released") { switch (press.Key) { case "KEY_LEFT": cameraControl('Pan', 'Stop'); break; case "KEY_RIGHT": cameraControl('Pan', 'Stop'); break; case "KEY_UP": cameraControl('Tilt', 'Stop'); break; case "KEY_DOWN": cameraControl('Tilt', 'Stop'); break; case 'KEY_VOLUMEUP': com('Audio Volume Increase'); break; case 'KEY_VOLUMEDOWN': com('Audio Volume Decrease'); break; case 'KEY_SLEEP': com(standbyState ? 'Standby Deactivate' : 'Standby Activate'); break; default: notify(press.Key + ' is not bound!'); break; } } }); } init();   The above code that was added will move the camera as long as the event type shows "Pressed". When the button is released a new event is generated hitting the same key binding only to "Stop" the camera movement.   We could bind a lot more keys and do other stuff as well, but the concept is the same, I would just need to create more key-bindings. The sky is the limit to what you can do with this feature.       Configuration xConfiguration Peripherals InputDevice Mode: On Troubleshooting When you connect a keyboard, make first make sure that the events are generated by accessing the codec API and issue:   xFeedback Register /event/userinterface/inputdevice Use a few buttons to see that the events are displayed. If they are showing the feature is working as it should. The rest is up to the integrator.   The keyboard can be seen in the Peripherals menu from the web interface or via the xAPI (xStatus):     xStatus //Peripherals *s Peripherals ConnectedDevice 1017 HardwareInfo: "1997:2433" *s Peripherals ConnectedDevice 1017 ID: "1997:2433:/dev/input/event3" *s Peripherals ConnectedDevice 1017 Name: " :Mini Keyboard" *s Peripherals ConnectedDevice 1017 SoftwareInfo: "" *s Peripherals ConnectedDevice 1017 Status: Connected *s Peripherals ConnectedDevice 1017 Type: InputDevice *s Peripherals ConnectedDevice 1017 UpgradeStatus: None *s Peripherals ConnectedDevice 1018 HardwareInfo: "1997:2433" *s Peripherals ConnectedDevice 1018 ID: "1997:2433:/dev/input/event4" *s Peripherals ConnectedDevice 1018 Name: " :Mini Keyboard" *s Peripherals ConnectedDevice 1018 SoftwareInfo: "" *s Peripherals ConnectedDevice 1018 Status: Connected *s Peripherals ConnectedDevice 1018 Type: InputDevice *s Peripherals ConnectedDevice 1018 UpgradeStatus: None *s Peripherals ConnectedDevice 1019 HardwareInfo: "1997:2433" *s Peripherals ConnectedDevice 1019 ID: "1997:2433:/dev/input/mouse0" *s Peripherals ConnectedDevice 1019 Name: " :Mini Keyboard" *s Peripherals ConnectedDevice 1019 SoftwareInfo: "" *s Peripherals ConnectedDevice 1019 Status: Connected *s Peripherals ConnectedDevice 1019 Type: InputDevice *s Peripherals ConnectedDevice 1019 UpgradeStatus: None ** end   The above shows that my remote is seen as two different keyboards and a mouse which is correct. The mouse device can be ignored as we do not support it and it wont generate events. But as long as the keyboard works as it should then all should be well.   Here is a CEC macro I created to control my AppleTV, same basic macro, different functionality based on key click: const xapi = require('xapi'); function com(command, args='') { xapi.command(command, args).catch(e => { com('UserInterface Message TextLine Display', { Text: e.message, duration: 3 }); }); log(command + ' ' + JSON.stringify(args)); } function log(event) { console.log(event); } function notify(message) { com('UserInterface Message TextLine Display', { Text: message, duration: 3 }); } function init() { xapi.event.on('UserInterface InputDevice Key Action', press => { if (press.Type == "Pressed") { switch (press.Key) { case "KEY_PLAYPAUSE": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Play'}); break; case "KEY_UP": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Up'}); break; case "KEY_DOWN": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Down'}); break; case "KEY_LEFT": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Left'}); break; case "KEY_RIGHT": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Right'}); break; case "KEY_ENTER": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Ok'}); break; case "CODE_273": com('Video CEC Input KeyClick', {ConnectorId: 5, NamedKey: 'Back'}); break; default: notify(press.Key + ' is not bound!'); break; } } else if (press.Type == "Released") { switch (press.Key) { default: break; } } }); } init(); For this use case you might notice that I have chosen to use the "Pressed event", this is because I expect the cursor to move the second I press the right up left or down button, not when I release it.. it just does not feel natural. But there you see, the options are many and.. we might see HDCP coming for more devices in CE9.6.1 where this sweet thing can come handy ;)!   const xapi = require('xapi'); function com(command, args='') { xapi.command(command, args).catch(e => { com('UserInterface Message TextLine Display', { Text: e.message, duration: 3 }); }); log(command + ' ' + JSON.stringify(args)); } function log(event) { console.log(event); } function notify(message) { com('UserInterface Message TextLine Display', { Text: message, duration: 3 }); } function composer(sources) { var layout = 'equal'; com('Video Input SetMainVideoSource', { ConnectorId: sources, Layout: layout }); } function cameraControl(motor, direction, cameraId='1') { log(motor); com('Camera Ramp', { 'CameraId': cameraId, [motor]: direction }); } function presentation(share) { com('Presentation ' + share); return (share === "Stop") ? "Start":"Stop"; } function init() { let standbyState; let presentationState = 'Start'; let compose = 1; let sources; let muteState; var selfviewTimer; xapi.status.get('Standby').then((state) => {standbyState = state.State === 'Off' ? false : true; }); xapi.status.get('Audio Microphones Mute').then((state) => { muteState = state === 'Off' ? false : true; }); xapi.status.on('Standby', state => { standbyState = state.State === 'Off' ? false : true; }); xapi.status.on('Audio Microphones Mute', state => { muteState = state === 'Off' ? false : true; }); xapi.event.on('UserInterface InputDevice Key Action', press => { if (press.Type == "Pressed") { switch (press.Key) { case "KEY_LEFT": cameraControl('Pan', 'Left'); break; case "KEY_RIGHT": cameraControl('Pan', 'Right'); break; case "KEY_UP": cameraControl('Tilt', 'Up'); break; case "KEY_DOWN": cameraControl('Tilt', 'Down'); break; case "CODE_272": cameraControl('Zoom', 'In'); break; case "CODE_273": cameraControl('Zoom', 'Out'); break; case "KEY_PAGEUP": selfviewTimer = setTimeout(function() { com('Video Selfview Set', { Mode: 'On', FullscreenMode: 'On' })}, 2 * 1000); break; default: break; } } else if (press.Type == "Released") { switch (press.Key) { case "KEY_LEFT": cameraControl('Pan', 'Stop'); break; case "KEY_RIGHT": cameraControl('Pan', 'Stop'); break; case "KEY_UP": cameraControl('Tilt', 'Stop'); break; case "KEY_DOWN": cameraControl('Tilt', 'Stop'); break; case "CODE_272": cameraControl('Zoom', 'Stop'); break; case "CODE_273": cameraControl('Zoom', 'Stop'); break; case "KEY_ENTER": presentationState = presentation(presentationState); break; case 'KEY_VOLUMEUP': com('Audio Volume Increase'); break; case 'KEY_VOLUMEDOWN': com('Audio Volume Decrease'); break; case 'KEY_SLEEP': com(standbyState ? 'Standby Deactivate' : 'Standby Activate'); break; case 'KEY_PLAYPAUSE': com(muteState ? 'Audio Microphones Unmute' : 'Audio Microphones Mute'); break; case "KEY_PAGEDOWN": com('Video Selfview Set', { Mode: 'Off', FullscreenMode: 'Off' }); break; case "KEY_PAGEUP": clearTimeout(selfviewTimer); com('Video Selfview Set', { Mode: 'On' }); break; case "KEY_COMPOSE": compose = compose + 1; if (compose > 3) { compose = 1; } sources = Array.from({length: compose}, (v, k) => k+1); composer(sources); break; default: notify(press.Key + ' is not bound!'); break; } } }); } init(); In the above macro I have added a bit more functionality to mute and unmute, turn on/off self view - even if you hold down the "enable selfview" button for 2 seconds it will enable self view in full screen. Hey, just use the imagination, combine it with the HTTP POST / PUT feature, like make your bot send a message to your secretary that you need a coffee in the {meetingRoom} and that without ANY external control devices!!!   Is there any limitations? No USB hubs are supported, the amount of USB-A ports is your limit to the connected USB devices. We might not support all the dongles out there (too many to test), but feel free to let us know if you find any issues.   Hide default feature buttons in UI (Call, Share, Meetings) One of the most asked features has finally arrived. Being able to customize the UI as you please, well we are not quite there yet but at least this is one step towards the goal, you asked for it and you got it, congratulations!   With this feature you get the ability to hide the big green call button, the blue share button, and all the other buttons as well if you like, conveniently the In-Room Control buttons are not affected by it, so you now control which buttons should be visible.   This also means exceptional control over the user experience with our devices, which means that this feature should be used with some level of caution as hiding the buttons without creating some kind of custom user flow can be confusing and leave the users with nothing on the Touch 10 panel or on the screen. Yes, literally no buttons in the UI. But let´s move on, and I promise this will not be a long one. Summary This feature adds the ability to hide the default feature buttons in UI while still exposing custom In-Room Control panels. This allows for a even more customizable UI but still not fully qualified as "Kiosk mode" just yet. This feature simply adds a series of configurations that allow you to hide / display certain feature buttons in the UI that has previously not been possible to hide. Feature description, functional overview Purpose Customers that wanted to create a custom UI for their users has been unable to do so as the Call button and Share button is visible together with the Custom buttons. This may confuse the users in scenarios where they should not use the Call or Share buttons, but rather use the Custom setup that defines the use-cases that the customer wants their users to utilize.   This feature is not for everyone, but for those that requires special use-cases that involves removing some of the default buttons in the UI.   Functional overview   xconfig //userinterface/features ? *? xConfiguration UserInterface Features Call End: <Auto, Hidden> *? xConfiguration UserInterface Features Call MidCallControls: <Auto, Hidden> *? xConfiguration UserInterface Features Call Start: <Auto, Hidden> *? xConfiguration UserInterface Features HideAll: <False, True> *? xConfiguration UserInterface Features Share Start: <Auto, Hidden> OK The above configurations will also be available to configure via the web interface of the Room Device. The default configurations are in bold. You can hide the call button, which hides the default UI feature for making a call or do directory look-ups / favorites / recent calls etc, and will also hide the Add button for adding participants while in a call. Hide the share button, which in turn hides the default UI for sharing and previewing sources in and out of call.   You cannot hide other single buttons that are displayed based upon provisioning. For example; Meetings, Extension Mobility, Voicemail etc. If those buttons must be hidden, you have to use the following:   xConfiguration UserInterface Features HideAll: <False, True> This will hide all the default feature buttons except custom In-Room Control buttons. An alternative is to not provision these settings from the backend.   You can also hide buttons that are default for In-Call scenarios, for example "End call" can be hidden by itself or you can hide all the default In-Call buttons except In-Room Controls. Let's take a look at some examples.   I want to create a custom UI for my employees where they can dial into specific meeting room that is used regularly. We don´t make external calls anyway and it's only between the meeting rooms that calls take place.       My UI looks like the above on the Touch 10.   xConfiguration UserInterface Features HideAll: True   After issuing the command above the UI will look like this:       Not very user-friendly, but here is where the In-Room Control magic comes into play. We want to have user friendly, self-explaining buttons that simply defines the use-case.   Open the In-Room Control editor found on the web interface (Integration -> In-Room Control)       The above is the design that I want, perfectly adapted to my company's use-case for this Room Device, nice and clean. I push the design to the codec and now it looks like this:           There is little the user can do wrong here, but this is exactly how I want it to be. I don´t want them to make random calls or do mistakes. I need to keep it simple for my users. The three entries I have here are the meeting rooms that we have and the user only have to click "Dial" and they will dial the correct number, they don´t have to remember any URI details or know how to navigate the phonebook.   In order to make use of this In-Room Control panel I need to have a control device or create a Macro. I will not do that in this feature walk-through since the ability to do that has been there for a while. Please refer to the tutorial on how to give In-Room Control buttons life (its basically the same concept as the "third-party USB input devices" above). Just imagine that when you press one of these buttons it just works! :)   This feature is about designing a UI tailored for the customers' use-cases ("Kiosk Mode" like setups - not even sure if I am allowed to use that term for this feature ;) ). I can create a lot of In-Room Control panels like this on the UI and add almost any functionality only limited to imagination. OK, this was the general "Out of call" UI. We have another UI which is "In-Call".   I make a call by pressing one of the meeting room buttons only to discover the below:       It should not come as a surprise since I have executed the Hide All features command and the In-Room Control UI element that I pushed was only visible "Out of call". I need at least some functionality for In-Call. Back to the drawing board:       I mark this button to be displayed in calls only and push it to the Room Device. Now I have UI for the In-Call scenario limiting my users to use the functionality I have implemented. Some of you might think, what the... is he doing (I am creating a fake UI that does not work after all), but I am just trying to give you ideas on how you can set things up, I am sure you can do this way better than me.    Voila! The only thing missing now is a survey asking my users how the experience was, of which I am using the new cool HttpClient feature to send to my server.. maybe another time, there are lots of examples on the developer community! :)   Make sure you visit: https://developer.cisco.com/site/roomdevices/ Known Issues & Limitations You cannot hide buttons that has fluctuating appearance (depends on scenario / configuration / setup) for example, Meetings, Extension Mobility or Voicemail by them self. To hide these buttons you must hide all the feature buttons or make the back end service not provision them to the devices.   Maybe we will see more of this UI customization features going forward.. at least I am both optimistic and excited! CE9.6 is going to be a FRESH start of 2019! I hope you enjoyed my humble post.   Merry Christmas and a Happy New Year! :)   /Magnus           ... View more