collab-xapi-macros

- Fix missing image on 4.md
- Fix some typos
- Add code exegesis for 5.md

Author: dstaudt

labs/collab-xapi-macros/3.md

@@ -92,7 +92,7 @@ The use-case might be environments where multiple collaboration devices are clos
 
 While restoring a 'template' backup file to multiple devices is much easier than manually creating macros and in-room controls sets step-by-step on each one individually, it still requires a significant effort and is susceptible to user error.  Luckily collaboration devices running CE 9.3+ registered to CUCM or TMS can be configured to automatically retrieve, verify, and install template backup files from a web server (or CUCM TFTP) on startup.
 
-Complete details on how this mechanism works, its capabilities and needed configurations are available in the Administration uide for your device (see the **Maintenance** > **Backup and restore configurations and custom elements** section.)
+Complete details on how this mechanism works, its capabilities and needed configurations are available in the Administration Guide for your device (see the **Maintenance** > **Backup and restore configurations and custom elements** section.)
 
 ## Programmatic provisioning of macros / controls
 

labs/collab-xapi-macros/4.md

@@ -110,6 +110,6 @@ To test your device's HttpClient functionality, we will make an HTTP request via
 
     If everything worked, you should see `HTTP Request successful...` in the console log:
 
-    ![Success](assets/images/step4-httpclient-success.png)
+    ![Success](assets/images/step4-success.png)
 
 **This example was pretty abstract, let's try something a little more tangible...**

labs/collab-xapi-macros/5.md

@@ -18,17 +18,17 @@ Frequently, enterprises have requirements like:
 
 * Meetings frequently 'run over' and it's difficult for users to extend both the room reservation and any associated Webex session - again, laptops, logins, lookup and reservation steps are a pain.  Users should be able to request a room / meeting reservation easily from the Touch10 interface.
 
-Solutions to these use-cases exist, but typically involve cobbling together various hardware and software components into a clunky (and expensive) 'Rube Goldberg machine' scenario - e.g. a Cisco room device withTouch10, _plus_ a Crestron/AMX codec _plus_ tablet interface, _plus_ 3rd party occupancy sensors, _plus_ an external app-server...
+Solutions to these use-cases exist, but typically involve cobbling together various hardware and software components into a clunky (and expensive) 'Rube Goldberg machine' scenario - e.g. a Cisco room device with a Touch10, _plus_ a Crestron/AMX codec _plus_ tablet interface, _plus_ 3rd party occupancy sensors, _plus_ an external app-server...
 
 ![Compelex](assets/images/step5-rube-goldberg.png)
 
-The good news is that with Cisco collaboration device automation, xAPI and macros, all of the above scenarios can potentially be accomplished by creating applications that run on-board the device itself and present customized Touch10 control interfaces for user interaction!
+The good news is that with Cisco collaboration device automation, xAPI, and macros, all of the above scenarios can potentially be accomplished by creating applications that run on-board the device itself and present customized Touch10 control interfaces for user interaction!
 
 ## The solution - a 'Book Meeting Room' panel + macro
 
 The sample macro + in-room-control set we will test next provides a Touch10 panel UI allowing walk-in users to reserve the room for 15/30/45 or 60 minutes, using a simple UI on the Touch10.  
 
-The macro will handle this UI interaction, then make an HttpClient request to a remote app server to 'book' the room, providing feedback on the success/failure of the request via an on-screen alert pop-up.
+The macro will handle this UI interaction, then make an HttpClient request to a remote app server to 'book' the room, and finally provide feedback on the success/failure of the request via an on-screen alert pop-up.
 
 ![Book](assets/images/step5-book-panel.png)
 
@@ -43,8 +43,8 @@ Note, this sample solution will use the 'fake' cloud REST API we used previously
 The sample would operates like this:
 
 * It is deployed by an admin as a template backup file to the room system
-* The user clicks **Book** to open the booking panel, selects a duration, and click **Submit**
-* The macro handles the submit button click, and reads the selected duration value, creating a payload object encapsulating details of the booking request (start time, end time, device name, etc.)
+* The user clicks **Book** to open the booking panel, selects a duration, and clicks **Submit**
+* The macro handles the submit button click, and reads the selected duration value creating a payload object encapsulating details of the booking request (start time, end time, device name, etc.)
 * An HttpClient request is made to the JSONPlaceholder cloud REST API service containing the payload data (as this is a mock service, the request will always succeed)
 * The HttpClient response return code is checked for success/failure and an appropriate on-screen alert message is displayed
 
@@ -66,6 +66,50 @@ The sample would operates like this:
 
 **Congrats!  You've completed the lab with flying colors...**
 
+## Code review
+
+Let's look at some of the interesting things going on in this macro (feel free to view the macro's JavaScript code in the **Macro Editor**:)
+
+* Everything happens within a big function called when an event is received from `xapi.event.on('UserInterface Extensions Widget Action', ... )`
+
+* Here we examine the incoming event, and proceed only on the one we need (clicking the Book/submit button:)
+
+    ```javascript
+    if ((event.WidgetId == 'button_submit') && (event.Type == 'clicked'))
+    ```
+
+* The next section is interesting:
+
+    ```javascript
+    Promise.all([ 
+        xapi.status.get('UserInterface Extensions Widget 1 Value'),
+        xapi.config.get('SystemUnit Name')
+        ]).then( ... )
+    ```
+
+    'Promises' are a language feature of modern JavaScript which handles asynchronous methods - commands that are called and immediately allow the app to continue, but that sometime later return with their actual results.  `Promise.all()` allows you to bundle and execute multiple promise executions in parallel, to be handled all at once when all complete - here `xapi` requests to read the meeting duration group widget's value and retrieve the system's unit name
+
+* An object is created collecting together the various pieces of the booking request: the start/end times (calculated from the duration value and the current time via `Date.()`), and the system name: `let payload = {...}`
+
+* As in the previous step, the HTTP request is made using the `xapi.command('HttpClient Post',...)`.  Note that we are using the `AllowInsecureHTTPS: 'True'` parameter previously mentioned
+
+* 'Promise chaining' (using `.then()` ) is used throughout the code to link the successful completion of one command with the execution of the next one.  See if you can spot the general structure of the promise chain in this sample:
+
+    ```javascript
+    Promise.all(...)
+        .then(
+            xapi.command('HttpClient Post', ... )
+            .then(
+                xapi.command('UserInterface Message Alert Display', ... )
+            )
+            .catch( ... )
+        )
+    ```
+
+    What do you think the `.catch( err ... )` block does..?
+
+* The final outcome of the function depends on whether the `xapi.command('HttpClient Post')` promise succeeds of fails.  If success, the `.then( ... )` block executes, and an xAPI command is performed to display a popup alert interface (with a 5 second timer); if fail, the `.catch( ... )` block runs, and the `err` object containing failure details is dumped to the console log
+
 ## Going further
 
 We've just scratched the surface of the possiblities with macros, and would certainly encourage you to learn and experiment further...