Join to explore concrete use cases implemented with the Administrative & Serviceability capabilities of Webex Teams (formally Cisco Spark) APIs. We'll cover how to manage Webex Teams Users but also track Spaces activity through the recently added /events API resource. Moreover, we will dig into the possibilities offered by the xAPI for Webex Teams-registered devices: discover Company Branding, People counting, and how to initiate Video Calls to Webex Teams & SIP addresses. This session is aimed at Webex Teams Administrators, Compliance Officers, and Cisco Collaboration Endpoints owners. DEVNET-3610 https://www.ciscolive.com/us/learn/sessions/session-catalog/?search=DEVNET-3610

1. #CLUS
Stève Sfartz, API Evangelist
DEVNET-3610
WebexTeams APIs
for Admin
and Serviceability

2. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
/Cisco/DevNet/SteveSfartz
• API Evangelist @CiscoDevNet
• API Design,Architecture and Operations
• WebexTeams & Devices/xAPI developer
• hosted @CiscoROI: Paris Innovation Center
• Node.js mainly, a bit of #golang
• Europe and all over the world
• github://ObjectIsAdvantag
DEVNET-3610
“vision without
execution is
hallucination”
-- Thomas Edison
mailto: stsfartz@cisco.com
twitter: @SteveSfartz
2

3. Agenda
© 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
• REST API forWebex Administrators
• Managing Users, Roles & Licenses from
Code
• ComplianceOfficer and /events API
• CE xAPI for Cloud-registered Devices
• PersonalizingWebex Devices
• Fetching Room Analytics from Code
DEVNET-3610 3

4. WebexTeams
Admin APIs
Overview

5. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
https://admin.webex.com

6. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Administrator Role
• A user can be assigned various roles
• Full administrator
• Read-only administrator
• Support administrator
• Compliance officer
6DEVNET-3610

7. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Admin Sandbox
IF you are NOT an administrator of a WebexTeams organization
• Send an email to devsupport@ciscospark.com
• from aWebexTrial account: this email address should not have been previously
used forWebex.Your home email address or a web email service is recommended.
• dev support will add this account to the Admin Sandbox organization
• As your new admin account is created, you will receive an email inviting you to
administer the Sandbox organization. Follow the instructions to complete the
activation.
• You are now an admin of theWebexTeams sandbox organization, along
with others developers who’ve been granted access.
7DEVNET-3610

8. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
WebexTeams API v1 (for admins)
/People
/Organizations
/Roles /Licenses /Policies /Events /Metrics
List People List Organizations List Roles List Licenses List Policies List Events
Get Metrics Report
Create a Person Create a Policy
Get details Get details Get details Get details Get Details Get Details
Update a Person Update a Policy
Delete a Person Delete a Policy
GET GET GET GET
GET GET GETGET
POST
DELETE
PUT
GET
GET
POST
DELETE
PUT
GET
GET
GET
DEVNET-3610
90 or unlimited days
depending on
Pro Pack subscription
8

9. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS DEVNET-3610
fromAdministrator Roles …. to OAuth Scopes
9

10. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
‘scoped’ Adminstrator access tokens
DEVNET-3610 10

11. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS DEVNET-3610
https://www.cisco.com/go/pro-pack
11

12. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS 12DEVNET-3610
https://collaborationhelp.cisco.com/article/en-us/np3c1rm

13. Use case:
Checking User Details

14. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
What is so great about REST?
same concept, many Cisco APIs
Easy to Build
Web apps
Mobile apps
M2M, Bots…
REST API
DEVNET-3610 14

15. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
‘Your App’
now with
Cisco Collab!
WebexTeams REST API
extend Cisco Collaboration Cloud
GET
POST
DELETE
PUT /Rooms
/Memberships
/Messages
/Teams
/People
/Webhooks
DEVNET-3610 15

16. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Terminology of a REST API query
DEVNET-3610
GET /../repos?page=1 HTTP/1.1 accept: application/json
HTTP 200 OK
browser api.github.com:443
method path protocol
status code
https://api.github.com/users/CiscoDevNet/repos?page=1&per_page=2
headers
URL:
response body
HTTP
request
HTTP
response
api endpoint
JSON payload
parameters
16

17. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
HTTP Request : Methods
• GET – retrieve contents from the server
• HEAD – only get the HTTP headers & status code (don't GET the body)
• PUT – update content
• PATCH – partial update
• POST – create content
• DELETE – delete content
• OPTIONS – retrieve contextual information before issuing a request
• checkW3C RFC 7230-7 to get an exhaustive list of HTTP/1.1 methods
DEVNET-3610 17

18. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
HTTP Response : Status Codes
 1xx - Information
 100 Continue
 2xx - Success
 200 OK, 201 Created, 204 No Content
 3xx - Redirection
 301 Moved permanently, 304 Not modified
 4xx - Client error
 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
 5xx - Server error
 500 Internal Error, 501 Not Implemented, 503 Service Unavailable
 interactive map at www.restapitutorial.com/httpstatuscodes.html
DEVNET-3610 18

19. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
JSON syntax
• square brackets for lists
• curly braces for objects
• name/value pairs for properties,
separated by commas
• pick an online editor
• http://codebeautify.org/jsonviewer
http://www.jsoneditoronline.org
DEVNET-3610 19

20. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Get Person Details
 As aWebexTeams User
 Presence attributes for people in your organization
 lastActivity: “YYYY-MM-DDTHH:MM:SS.SSSZ” ISO8601 format
 status: “active”, “inactive”, “OutOfOffice”, “DoNotDisturb”
 As aWebex Administrator
 Check an invited user’s provisioning status: “invitePending”, “loginEnabled”
DEVNET-3610 20

21. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS DEVNET-3610
Creating of a WebexTeams User
ResponseRequest
21

22. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
After user’s first sign in
DEVNET-3610
Response
22

23. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
After user’s activity
DEVNET-3610
Response
23

24. Use case:
Update Licenses
for aWebex User

25. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Updating Licenses
• Pick a Person id and extra Licenses, update the Person with a PUT
/people/<id>
DEVNET-3610 25

26. Compliance
and /eventsAPI

27. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Webex Compliance
Enforce company policies
DEVNET-3610
eDiscovery Search
and Extraction
Flexible Retention
Policy Administration
Enforce
company
retention
policies
Comply
with legal
requests
Integrate with
Existing DLP,
Archival and
eDiscovery
Events
API
27

28. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Compliance Officer
• Ensures that a company is conducting its business in full compliance with all
laws and regulations
• searchWebex for space IDs, keywords, shared files, and any email address used in
your organization. Generate reports and download data in JSON format.
• TheWebexTeams RESTAPI has compliance authorization scopes that
support the compliance officer’s role.
• access and manage all data created by their organization including messages,
content attachments, etc. in order to monitor data and to mitigate compliance
issues
DEVNET-3610 28

29. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Compliance Officer
• Note that
• [TBC] Full administrators can't assign the compliance officer role to
themselves. Another full administrator must assign the role to them.
• Administrators can limit the amount of messages and files that are kept by
configuring a data retention policy.When that threshold is met, aging
content gets purged.
DEVNET-3610 29

30. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Extension of
Cisco Spark
Control Hub
Search on email ID,
space ID, keywords
Designed for
Compliance
Officer
90-day in Webex base offer, any time period with Webex Pro Pack
Search Compliance Data
30DEVNET-3610

31. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS DEVNET-3610
JSON data reports
https://collaborationhelp.cisco.com/article/en-us/nr70c1m
Actor An actor represents the person or entity that initiated the event or action.
Object An object is the person or conversation or entity that is being operated on. For example,
someone sends a message, the object will be of type comment. If someone adds Bob to a
to a space, the object will of type person. If someone shares a file, the object will be of
type file.
Target A target is the place or destination the action is directed towards.Target is
always conversation (for example, a conversation in a space).
Verb A verb is the type of action being performed. For messages, the action is usually post but could
31

32. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
jq example to parse JSON data
DEVNET-3610 32

33. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS DEVNET-3610
https://collaborationhelp.cisco.com/article/en-us/np3c1rm
33

34. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Events API
https://developer.webex.com/resource-events.html
DEVNET-3610
Enables polling for events and
content that enables
organizations to monitor and
correct behavior, preventing the
loss of sensitive data
Cisco Cloudlock will be the first
integration to provide DLP
management via the Events API
Third party
DLP or CASBCisco Spark Events API
Governance code
Corrective actions
- delete content
- remove member
- alert admin/user
34

35. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Compliance ‘scopes’
DEVNET-3610 35

36. Hands-on with Postman

37. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
http://getpostman.com
• Want to code along? Install POSTMAN now
• Free tool to forge API requests, examine responses
DEVNET-3610 37

38. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
method
url
request
headers
status code
response headers
content-type
response
body
query parameters
DEVNET-3610 38

39. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Tip: import theWebex Admin API colllection
https://github.com/CiscoDevNet/postman-ciscospark#admin-api
https://raw.github..../admin-scripted.json
DEVNET-3610 39

40. Demo: AutomateWebex from Code

41. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Generate code with Postman
1. Start from a REST call
2. Select your favorite language
3. Run your code
DEVNET-3610 41

42. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
… or leverage aWebexTeams SDK
for javascript, python, ruby, php…
• Official SDKs
• Community SDKs
• node-sparky, node-spark-client
• python ciscosparkapi
• …
DEVNET-3610
https://github.com/nmarus/sparky
https://github.com/CiscoDevNet/ciscosparkapi
42

43. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Security Best Practices
• Forge custom access tokens
• Restrict to the scopes required by your code
• Using anWebex OAuth integration
• « Running an OAuth Integration Locally »
• https://learninglabs.cisco.com/tracks
/collab-cloud/creating-spark-integrations-sd
/collab-spark-intl/step/1
DEVNET-3610 43

44. Agenda
© 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
• REST API forWebex Administrators
• Managing Users, Roles & Licenses from
Code
• ComplianceOfficer and /events API
• CE xAPI for Cloud-registered Devices
• PersonalizingWebex Devices
• Fetching Room Analytics from Code
DEVNET-3610 44

45. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Admin UI for cloud-registered Webex Devices
https://admin.webex.com/devices
DEVNET-3610
http://192.168.1.34/cloud-login
45

46. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Adding user credentials to access your device
http://192.168.1.34/web/localusers
• Create a local ‘integrator’ user
• Connect via SSH with the Integrator user credentials
• REQUIREMENT: local network connectivity to the device
DEVNET-3610 46

47. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
https://developer.cisco.com/site/sandbox/

48. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Prototype with the RoomKit Sandboxes
DEVNET-3610 48

49. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Waking up your system (viaWebUI andTSH)
*s Standby State: Off
xcommand Standby Deactivate
http://<ip-address>/web/personalization
Other Standby commands
- xcommand Standby Activate
- xcommand Standby Halfwake
DEVNET-3610 49

50. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Personalization via Web UI & ssh
xConfiguration UserInterface CustomMessage: “Welcome to the DevNet Zone"
http://<ip-address>/web/personalization
DEVNET-3610 50

51. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Personalization via Postman
DEVNET-3610 51

52. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Personalization: Brand logo (awake) via WebUI
*e UserInterface Branding Updated
Type: "Branding"
DEVNET-3610 52

53. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Personalization: Brand logo (awake) viaTSH
Your logo
272x272
Example:
https://www.base64-image.de/
 Turn your image (PNG, 272px272p) to base64 bytes
 Remove heading string (such as ‘data:image/png;base64’)
 Paste to the command line and hit Enter
 Add ‘.’ and hit Enter again
544523454353
BVHhe7d2/WuJ
MH8b…x4T0W
sNjLI4hCYII=
xcommand UserInterface Branding Upload Type: Branding
iVBORw0KGgoAAAANSUhEUgAAARAAAAEQCAYAAAB4CisVAAAAAXNSR0IArs4c6Q
AAAppLdq81bWeZNTvqk+uW5x7p/On5ZEcWb/pjN/uRDxGPoVINtH4xv+OG3wqZPVtK5J
b/tiTa7Ln0j37vMp7zhCQgtx9StANi/2be0yMY2dCLq9NTf1p4fdzK8apvV/sZpGD483tCyQ8
zym42zfbx3hl++=.
OK
*r BrandingUploadResult (status=OK):
** end
*e UserInterface Branding Updated Type: "Branding"
** end
DEVNET-3610 53

54. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Personalization: Brand logo (awake) via Postman
Your logo
272x272
Example:
https://www.base64-image.de/
 Turn your image (PNG, 272px272p) to base64 bytes
 Remove heading string (such as ‘data:image/png;base64’)
 Forge XML PUT request in Postman
544523454353
BVHhe7d2/WuJ
MH8b…x4T0W
sNjLI4hCYII=
DEVNET-3610 54

55. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
To go further: import an xAPI colllection
https://github.com/CiscoDevNet/postman-xapi#integrator
DEVNET-3610
https://raw.github..../xapi-integrator.json
55

56. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Resources
cs.co/roomdevices
• Telepresence Deploy XML APP
• https://github.com/voipnorm/CiscoTPCustomXML
• Advanced Settings for Room and Desk Devices
• https://collaborationhelp.cisco.com/article/en-us/n5pqqcm
• Postman collections
• https://github.com/CiscoDevNet/postman-xapi
• xAPI samples
• https://github.com/ObjectIsAdvantag/xapi-samples
• Awesome-xapi
• https://github.com/CiscoDevNet/awesome-xapi
DEVNET-3610 56

57. Webex Devices
Programmability

58. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS 58DEVNET-3610
https://github.com/ObjectIsAdvantag/roomkit-react-map

59. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Cisco Collaboration Devices Programmability
59DEVNET-3610
Pull
data
Listen to
events
Embed
code

60. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
xAPI
60DEVNET-3610
Pull
data
xstatus, xconfig,xcommand
local network connectivity*
(coming viaWebex Cloud)

61. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
xAPI
61DEVNET-3610
Pull
data
Listen to
events
xstatus, xconfig,xcommand
xfeedback
Invoke remote APIs
Interact with control systemslocal network connectivity*
(coming viaWebex Cloud)

62. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
xAPI
62DEVNET-3610
Pull
data
Listen to
events
Embed
code
Javascript
Macros
All CE devices but SX10
No remote API calls*
Admin role only* (coming support for cloud-
registered, HttpFeedback)
xstatus, xconfig,xcommand
xfeedback
Invoke remote APIs
Interact with control systemslocal network connectivity*
(coming viaWebex Cloud)

63. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Ultrasound
https://github.com/ObjectIsAdvantag/xapi-samples/tree/master/controls/ultrasound
63DEVNET-3610
Give users control to your
devices’ Ultrasound
MaxVolume
• In-Room Control
• Macro-compatible
custom message pushed to your
devices’Touch10/DX interface as
pairing is enabled / disabled.

64. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Notifier
https://github.com/ObjectIsAdvantag/xapi-samples/tree/master/controls/notifier
64DEVNET-3610
Captures an email address
• In-RoomControl
• state management
• macro-compatible
• Node.js jsxapi
• WebexTeams Bot
account

65. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Agenda with notifications
https://github.com/ObjectIsAdvantag/xapi-samples/tree/master/controls/agenda_notif
65DEVNET-3610
Pushes session details to a
WebexTeams space
• In-RoomControl
• Node.js jsxapi
• Incoming webhook

66. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Maze Game
https://github.com/ObjectIsAdvantag/xapi-samples/tree/master/controls/maze-scores
66DEVNET-3610
End-to-end enrichedUser
Experience for Meeting
Rooms
• In-RoomControl
• macro

67. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
In-Room Simulator
https://controls-editor.herokuapp.com/playground.html?virtualroom
67DEVNET-3610
End-to-end enrichedUser
Experience for Meeting
Rooms
• In-RoomControl
• Node.js jsxapi

68. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Interactive Live Map
https://github.com/ObjectIsAdvantag/roomkit-react-map
68DEVNET-3610
Interactive map showing
PeopleCount analytics from a
set of Room Kits
• React
• Node.js
• ‘jsxapi’

69. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Collect data from devices
https://github.com/ObjectIsAdvantag/roomkit-collector
GET / healthcheck
GET /devices
GET /devices/Workbench1
GET /devices/Workbench1/average?period=60
GET /devices/Workbench1/last
GET /devices/Workbench1/max
69DEVNET-3610
Node.js local service collecting PeopleCount events
from a RoomKit deployment,
to compute weighted averages

70. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Resources
• In-RoomControls Learning Lab
• https://learninglabs.cisco.com/lab/collab-xapi-controls/step/1
• xAPI samples
• https://github.com/ObjectIsAdvantag/xapi-samples
• ‘xAPI devs’ community space
• https://eurl.io/#rkp76XDrG
• awesome-xapi catalog
• https://github.com/CiscoDevNet/awesome-xapi
70DEVNET-3610

71. © 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
xAPI module at DevNet
https://learninglabs.cisco.com/modules/xapi-intro
71DEVNET-3610

72. Complete your online session evaluation
© 2018 Cisco and/or its affiliates. All rights reserved. Cisco Public#CLUS
Give us your feedback to be entered into a
Daily Survey Drawing.
Complete your session surveys through the
Cisco Live mobile app or on
www.CiscoLive.com/us.
Don’t forget: Cisco Live sessions will be available for viewing on
demand after the event at www.CiscoLive.com/Online.
DEVNET-3610 72

73. Q&A

74. Thank you
#CLUS

75. #CLUS