You are on page 1of 98

Using Collaboration API's to

solve Real-World Challenges

Paul Giralt, Distinguished Engineer


pgiralt@cisco.com - @PaulGiralt

BRKCOL-2256
Cisco Webex Teams

Questions?
Use Cisco Webex Teams to chat
with the speaker after the session

How
1 Find this session in the Cisco Events Mobile App
2 Click “Join the Discussion”
3 Install Webex Teams or go directly to the team space
4 Enter messages/questions in the team space

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 3
Agenda

• Why API’s?
• Collaboration API’s Overview
• Case Studies
• Self-Help Portal / Automated Provisioning System
• Load Balancer for Cisco Meeting Server
• Device Busy Lamp Feature

• Getting Help

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 4
Why API’s?
Why API’s? Sound familiar?
• “Product does not have feature ”
• “Product does not talk to Product ”
• “Provisioning is tedious and error-prone”
• “Managing is a nightmare”
• “I want to customize ”
• “You must automate everything!”

Credit: http://hyperboleandahalf.blogspot.com/
BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 6
Cisco
Collaboration API’s
Cisco DevNet

• http://developer.cisco.com

• One-stop shop for all


Cisco public API’s
• Sorted by Technology
Area
• Documentation, Examples,
and API References
• 43 API’s for Collaboration
Products alone

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 8
Unified CM API’s
• Configuration / Provisioning Interfaces
• Administrative XML (AXL)
• User Data Service (UDS)
• Platform Administrative Web Services (PAWS)
• Extension Mobility API (EMAPI)

• Device Monitoring and Call Control Interfaces


• Cisco Routing Rules (External Call Control) – CURRI or ECC
• Cisco TAPI
• Cisco JTAPI
• Cisco UC Manager SIP
• WebDialer

• Serviceability Interfaces
• Serviceability XML (SXML)

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 9
Collaboration Product API’s

• Webex Teams / Webex Meetings


• Cisco Meeting Server (CMS) REST API
• Cisco Unity Connection API’s
• UC Manager IM & Presence API’s
• IP Phone Services
• Jabber Guest / Jabber Web
• Contact Center API’s

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 10
Case Study 1:
User Self-Care
Portal /
Automated
Provisioning
Case Study 1: Provisioning

Password Resets are


DRIVING ME CRAZY!!!

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 12
Solution: User Self-Care Portal

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 13
Solution: User Self-Care Portal

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 14
Self-Care Portal
Demo
Self-Care Portal Architecture
Self-Care Portal Server

CUPI

DB AD
Replication

Unified CM IM&P Unity Active


Cluster Connection Directory

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 16
AXL API Introduction

• The Administrative XML Web Service (AXL) is an XML/SOAP based


interface that provides a mechanism for inserting, retrieving, updating and
removing data from the Unified Communication configuration database.
• https://developer.cisco.com/site/axl/
• Thick AXL – API defines specific objects that can be created, removed,
queried, or updated
• Thin AXL – Provides a mechanism to perform direct SQL queries / updates

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 17
Administrative XML Configuration API
• Read/Modify UCM Configuration Database
• Methods for All Database Objects
• list*
Read
• get*
• add*
• update* Write
• remove*
• Thin AXL methods:
• ExecuteSQLquery - Read
• ExecuteSQLupdate - Write

• Service port: https://<server>:8443/axl/


• Authentication:
• Member of group with AXL API Access role or Standard CCM Super Users group for Read/Write
permissions
• Member of group with Standard AXL Read Only API Access Role for Read-only permissions

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 18
XML

• eXtensible Markup Language


• Opening / Closing tag for elements
• Not validated against schema
• Example:

<person>
<lastname>Robbins</lastname>
<firstname>Chuck</firstname>
</person>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 19
XML – Schema Definition

• Names, hierarchy, meaning of elements and attributes defined by schema


• XML schema defined by W3C - http://www.w3.org/TR/xmlschema-0/
• Example:
<xsd:element name="person" type="PersonType"/>
<xsd:complexType name="PersonType">
<xsd:sequence>
<xsd:element name="lastname" type="xsd:string"/>
<xsd:element name=”firstname" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 20
SOAP

• The specification formerly known as Simple Object Access Protocol


• W3C specification: http://www.w3.org/TR/soap/
• Exchange of structured and typed information based on XML
• SOAP specification defines
• SOAP message format
• How to send and receive messages
• Data encoding

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 21
SOAP Message Structure
SOAP Message
Envelope (SOAP-ENV:Envelope)
Header (SOAP-ENV:Header) (optional)

Body (SOAP-ENV:Body) (required)

Fault (SOAP-ENV:Fault) (optional)

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 22
Web Services Definition Language (WSDL)

• W3C: http://www.w3.org/TR/wsdl20/
• XML-based format (grammar) to describe web services
• Defines four pieces of data:
• Publicly available methods; interface description, formats
• Data type information for requests and responses
• Binding; which transport protocol
• Address information – where to find the service

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 23
AXL Request Schema - addPhone
AXLAPI.wsdl

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 24
AXL Request Schema - addPhone
AXLAPI.wsdl

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 25
AXL Request Schema - addPhone
AXLSoap.xsd

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 26
AXL Request Schema - addPhone
AXLSoap.xsd

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 27
AXL Versioning
• Abstracts developer from DB schema changes
• Thick AXL methods only, Thin AXL (direct SQL) does not offer backward compatibility
• Maintains Release minus 2 backward compatibility
• Developers writing to Unified CM 12.5(1) will not have to make changes until 16.0(1)
(because there will be no version 13 – so compatible with 14.0 and 15.0
• Oldest supported schema is always the default
• Developer specifies desired schema version via the SOAPAction header
• E.g., SOAPAction: CUCM:DB ver=12.5

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 28
Performance

• Dynamic throttling
• Single request limited to <8MB data
• Concurrent request limited to <16MB

• Up to 1500 writes per minute


• Intelligently accepts or rejects requests
• Row fetch returned when data limits are exceeded

• Always enabled

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 29
Cisco AXL Toolkit
• Download from Unified CM Administration > Application > Plugins

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 30
Cisco AXL Toolkit
• Schema folder contains AXL API schema
for supported AXL versions
• AXLAPI.wsdl – WSDL file
• AXLEnums.xsd – Enum type definitions
• AXLSoap.xsd – Type definitions

• Sample Java classes and .NET code

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 31
Documentation
• AXL Schema Reference
• https://developer.cisco.com/docs/axl-schema-reference/

• AXL Developer Guide


• https://developer.cisco.com/docs/axl/#!axl-developer-guide

• UCM Data Dictionary


• https://developer.cisco.com/docs/axl/#!12-5-cucm-data-dictionary

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 32
Unified CM Serviceability APIs
https://developer.cisco.com/site/sxml/

• Real-Time Information (RisPort) – Provides the current connection status of phones, devices, and
applications connected to Cisco Unified Communications Manager (Unified CM).
https://<server>:8443/realtimeservice2/services/RISService70?wsdl

• Performance Monitoring (PerfMon) – Provides real-time event feeds to monitor the status and
health of Cisco Unified CM.
https://<server>:8443/perfmonservice2/services/PerfmonService?wsdl

• CDRonDemand – SOAP/HTTPS interface to query the Unified CM Call Detail Records (CDR)
Repository.
https://<server>:8443/realtimeservice2/services/CDRonDemandService?wsdl

• Log Collection – Retrieval of trace files and logs


https://<server>:8443/logcollectionservice2/services/LogCollectionPortTypeService?wsdl

• Service Control – Activate / Deactivate / Start / Stop Services


https://<server>:8443/controlcenterservice2/services/ControlCenterServices?wsdl

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 33
Cisco Unity Connection API’s
http://docwiki.cisco.com/wiki/Cisco_Unity_Connection_APIs

• Cisco Unity Connection Provisioning Interface (CUPI) – REST API for


Administrative Provisioning Cisco Unity Connection
• CUPI for End Users – Building Custom end-user applications
• Cisco Unity Connection Messaging Interface (CUMI) – Access to user messages
• Cisco Unity Connection Telephony Interface (CUTI) – Play and record audio
content over the phone
• Cisco Unity Connection Imaging Interface (CUII) – View message state and
mailbox information visually using graphics icons
• Cisco Unity Connection Notification Interface (CUNI) – Notification for one or more
users

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 34
Portal Server

• Ubuntu Linux Server


• Apache2 Web Server
• PHP7
• MySQL Database

Includes

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 35
Programming Languages & SOAP Toolkits
• PHP
• SoapClient - http://php.net/manual/en/book.soap.php

• Python
• zeep – http://docs.python-zeep.org/
• suds – poorly maintained

• Java
• .NET
} – Various options to generate wrapper classes

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 36
Python AxlToolkit

https://github.com/pgiralt/axltoolkit
BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 37
Python AxlToolkit – Adding a Partition

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 38
Using SoapUI - https://www.soapui.org/

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 39
Python AxlToolkit – Adding a Partition

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 40
Python AxlToolkit– Adding a Partition – Request
POST /axl/ HTTP/1.1
Host: vnt-cm1a.cisco.com:8443
Connection: Keep-Alive
Content-Type: text/xml; charset=utf-8
SOAPAction: "CUCM:DB ver=12.5 addRoutePartition"
Content-Length: 399
Authorization: Basic VGhhbmtZb3VGb3JBdHRlbmRpbmdMVFJDT0wtMjI1Ng==

<?xml version="1.0" encoding="UTF-8"?>


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://www.cisco.com/AXL/API/12.5">
<SOAP-ENV:Body>
<ns1:addRoutePartition>
<routePartition>
<name>Test_Partition</name>
<description>This is a Test Partition</description>
</routePartition>
</ns1:addRoutePartition>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 41
Python AxlToolkit – Adding a Partition –
Response
https://developer.cisco.com/docs/axl/#!authentication/authentication-best-practices
HTTP/1.1 200 OK
Set-Cookie: JSESSIONIDSSO=45A62CFBBC948096000A7A0529126596; Path=/; Secure; HttpOnly
Set-Cookie: JSESSIONID=A505B19C384273952BCEA6DA1AC21CC6; Path=/axl; Secure; HttpOnly
X-Frame-Options: SAMEORIGIN
Strict-Transport-Security: max-age=31536000; includeSubdomains
Content-Type: text/xml;charset=UTF-8
Content-Length: 323
Date: Sat, 24 Jun 2019 01:00:01 GMT
Server:

<?xml version='1.0' encoding='utf-8'?>


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:addRoutePartitionResponse xmlns:ns="http://www.cisco.com/AXL/API/11.5">
<return>{7BE42697-9301-FDF5-89ED-7A3C3AE34FFF}</return>
</ns:addRoutePartitionResponse>
</soapenv:Body>
</soapenv:Envelope>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 42
Python AxlToolkit – Using Thin AXL

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 43
AXL & SXML API Demo
Case Study 2:
Cisco Meeting
Server Load
Balancer
Case Study 2: Problem Statement Distribution Calls
Participant Calls

11 6 3 4 13 8 9 7 15 16 14 12

1 2 5 10

Participant 1 Participant 2 Participant 3 Participant 4


4 Participants = 16 HD Conference Ports!!!
BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 46
Case Study 2: Problem Statement
Cluster Server Load during Peak Load on one server

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 47
CMS Load Balancer Architecture

Syslog

LB CMS
REST
CURRI /
ECC
CMS
Unified CM REST
Cluster LB
Syslog
CMS LB Servers CMS Cluster (16 Nodes)

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 48
CMS Load Balancer Message Flow

Translation Pattern 8 Route Pattern Route Pattern


Pattern: 8002XXXX Pattern: *01.8002XXXX Pattern: *0X.8002XXXX
IP Partition: CMS
External Call Control Profile: CMS-LB
Partition: CMSRouting
Digit Strip: PreDot
Partition: CMSRouting
Digit Strip: PreDot
Calling Search Space: CMSRouting
Route List Route List
1 Dial 80021000 Name: cms-server1-rl Name: cms-serverX-rl
2 7
Route Group: cms-server1-rg Route Group: cms-serverX-rg
…. (contains all other CMS servers) …. (contains all other CMS servers)
External Call Control Profile: CMS-LB
Primary Server: cms-lb-server1 Route Group Route Group
Secondary Server: cms-lb-server2 Name: cms-server1-rl Name: cms-serverX-rl
Calling Search Space: CMSRouting Route Group: cms-server1-trunk Route Group: cms-serverX-trunk

SIP Trunk SIP Trunk


Name: cms-server1-trunk Name: cms-serverX-trunk
3 6 Destination: cms-server1 IP address Destination: cms-serverX IP address

4 9

CMS Server 1
CMS LB Server 5
CMS Server(s) X

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 49
Load Balancer UI

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 50
CMS Load Balancer Application

• Ubuntu Linux Server


• Python Flask Application
• Jinja templates for ECC Responses
• Requests library for REST calls
• Redis for in-memory cache / Key-Value Pair storage

• Customized Python Syslog Receiver


• Calculates Server Load from Syslog message and saves in Redis cache

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 51
CURRI

• The Cisco Unified Routing Rules Interface (CURRI) is an XML/HTTP based


interface that enables applications to instruct Unified CM how calls should
be routed based on business rules, compliance policies, and User
preferences.
• https://developer.cisco.com/site/curri/

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 52
Routing Rules Use Cases
• Allow/Block Call Lists – permit or deny calls based on Time-of-Day, Day-
of-Week, User preferences, Do-Not-Call lists, and company policies
• Presence-based routing - combine User availability, location, and
preferences to render a uniquely tailored UC experience
• Single Number Reach
• Find me / Follow me / Hide me

• Ethical Wall – Allow, Deny, or Redirect calls based on Calling/Called Party.


Play custom announcements

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 53
Call Route Request

• XACML request sent over HTTP or HTTPS using POST method


• Contains the following information about the call:
• Calling number
• Transformed calling number
• Called number or dialed digits
• Transformed called number
• Type of the triggering point, i.e., translation pattern

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 54
Example Call Route Request
<?xml version="1.0" encoding="UTF-8"?>
<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<Subject SubjectCategory="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject">
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:role-id” DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="requestor">
<AttributeValue>CISCO:UC:UCMRoute</AttributeValue>
</Attribute>
<Attribute AttributeId="urn:Cisco:uc:1.0:callingnumber” DataType=http://www.w3.org/2001/XMLSchema#string>
<AttributeValue>+19725550101</AttributeValue>
</Attribute>
<Attribute AttributeId="urn:Cisco:uc:1.0:callednumber” DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>50102</AttributeValue>
</Attribute>
<Attribute AttributeId="urn:Cisco:uc:1.0:transformedcgpn” DataType=http://www.w3.org/2001/XMLSchema#string>
<AttributeValue>+19725550101</AttributeValue>
</Attribute>
<Attribute AttributeId="urn:Cisco:uc:1.0:transformedcdpn” DataType=http://www.w3.org/2001/XMLSchema#string>
<AttributeValue>+19725550102</AttributeValue>
</Attribute>
</Subject>
continued on next slide…

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 55
Example Call Route Request - continued
…continued from previous slide
<Resource>
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id” DataType="http://www.w3.org/2001/XMLSchema#anyURI">
<AttributeValue>CISCO:UC:VoiceOrVideoCall</AttributeValue>
</Attribute>
</Resource>
<Action>
<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id” DataType=http://www.w3.org/2001/XMLSchema#anyURI>
<AttributeValue>any</AttributeValue>
</Attribute>
</Action>
<Environment>
<Attribute AttributeId="urn:Cisco:uc:1.0:triggerpointtype DataType=http://www.w3.org/2001/XMLSchema#string>
<AttributeValue>translationpattern</AttributeValue>
</Attribute>
</Environment>
</Request>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 56
Call Route Response
XACML Route Decision and Obligation Details
Route decision values:
• Permit: Call is allowed
• Deny: Call is denied
• Indeterminate: No call routing route is determined. Follows failure route.
• Not Applicable: No route matches the request. Follows failure route.

Obligation overview:
• CIXML block contains specific instructions on how the call will be routed and treatment
should be applied
• CIXML’s obligation must be consistent with route decision. If it is not, Unified CM obeys the
route decision, not the obligation
• Options are Continue, Divert, or Reject

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 57
CIXML Obligation Details
• Continue – Routes normally to current destination
• greeting identification=[id]: An announcement specified by [id] will be played to the caller
before being connected to the called party
• modify callingnumber=[number] callednumber=[number] callingname=[name] calledname =
[name]: Calling and/or called names and numbers will be substituted with the parameters
provided

• Divert – Route to diverted destination specified


• destination: [dest]: The [dest] is a routable number or “voicemail”
• reason: [reason]: the only reason supported in is “chaperone”
• modify callingnumber=[number] callednumber=[number] callingname=[name] calledname =
[name]: Calling and/or called names and numbers will be substituted with the parameters
provided
• resetCallHistory: The last call hop or all previous call hops will be removed from the call
history. Useful when sending call to voicemail.

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 58
CIXML Obligation Details
Reject – Call Rejected
Caller hears (optional announcement followed by fast busy.
• announce announce=[id]: An announcement specified by [id] will be played to the caller when
call is rejected

• reason: [reason]: The reason for the call rejection. The reason is logged to the alarm
CallAttemptBlockedByRoute

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 59
Example Call Route Response

<?xml encoding="UTF-8" version="1.0"?>


<Response>
<Result ResourceId="CISCO:UC:VoiceOrVideoCall">
<Decision>Permit</Decision>
<Obligations>
<Obligation FulfillOn="Permit" ObligationId="urn:cisco:xacml:policy-attribute">
<AttributeAssignment AttributeId="Policy:divert”
<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string”
&lt;cixml version="1.0"&gt;
&lt;divert&gt;
&lt;destination&gt;
+19725550100 <cixml version="1.0>
&lt;/destination&gt;
&lt;/divert&gt;
<divert>
&lt;/cixml&gt; <destination>
</AttributeValue>
</AttributeAssignment> +19725550100
</Obligation>
</Obligations> </destination>
</Result> <divert>
</Response>
<cixml>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 60
Custom Announcements
• Cisco provides the following set of pre-recorded announcements for all the locales
supported by Unified CM:
• Your call has been disallowed by corporate route
• You are not authorized to make 900 phone calls
• You are not authorized to make international calls
• You are not authorized to make toll calls
• Calls to directory assistance are not allowed
• This call may be monitored or recorded
• Your call will be completed momentarily

• Customized announcements with specific locale can be uploaded to replace the


default announcements provided by Cisco

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 61
Basic Requirements for Web Application
• HTTP 1.1 for persistent connection
• Support thread pool for multiple persistent connections
• Support for HTTP connection reuse
• Support HTTPS connection with mutual authentication using certificates
• Support HTTP HEAD method for keepalive from Cisco Unified CM

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 62
External Call Control Parameters

• HTTP Connection Pool Size can affect performance

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 63
REST API Basics

• Leverages HTTP verbs to indicate operation

HTTP Verb DB Equivalent Description


GET SELECT Retrieve one or more objects
POST INSERT Add an object
PUT UPDATE Update attributes on an existing object
DELETE DELETE Delete an object

https://host/api/v1/calls
Base URI Resource

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 64
Cisco Meeting Server REST API

• https://ciscocms.docs.apiary.io/ /callBridges
/callBridges/<call bridge id>
• Object Hierarchy
• Uses Basic Authentication over /callBridgeGroups
HTTPS /callBridgeGroups/<call bridge group id>

/calls
/calls/<call id>
/calls/<call id>/callLegs
/calls/<call id>/diagnostics
/calls/<call id>/participants
/calls/<call id>/participants/*

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 65
CMS REST API
• Many GET requests can have filter parameters

https://cms_host:8443/api/v1/calls?coSpaceFilter=12345&limit=5

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 66
Sending a REST Request in Python

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 67
CMS REST API
• Consult the API Reference Guide /callBridges
/callBridges/<call bridge id>
• Object Hierarchy
• Each object can support up to /callBridgeGroups
4 methods: /callBridgeGroups/<call bridge group id>
• GET
• POST /calls
• PUT /calls/<call id>
• DELETE /calls/<call id>/callLegs
/calls/<call id>/diagnostics
/calls/<call id>/participants
/calls/<call id>/participants/*

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 68
CMS REST API
• Many GET requests can have filter parameters

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 69
CMS REST API Demo
Case Study 3:
Device Busy Lamp
Case Study 3: Device Busy Lamp

Why Can’t THIS

Do what THIS does?!?

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 72
Customer Requirement

• Customer would like a Busy Lamp indicator to show when a


Device is in use or not.
• Cisco UCM Busy Lamp feature allows a user to monitor a Line,
not a Device.

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 73
Device BLF Application Server Architecture

AXL
JTAPI SIP Phones
SIP
Unified CM
Device BLF Cluster
Server

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 74
Device BLF Application Initialization JTAPI
AXL (SOAP over HTTPS)
SIP

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 75
Device BLF Application Operation JTAPI
AXL (SOAP over HTTPS)
SIP

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 76
config.properties file

axl_server = 172.18.106.58
axl_username = axl_user
axl_password = axl_password
axl_version = 12.5
jtapi_server1 = 172.18.106.59
jtapi_server2 = 172.18.106.60
jatpi_username = jtapi_user
jtapi_password = jtapi_password
sip_trunk_name = DeviceBlfTrunk
monitor_phone_list = SEP1C17D34191C5,SEP885A92D9AC88

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 77
phonemap.properties file
# pgiralt-7945
SEP001F6C7FEFE7=80018980
# pgiralt-7841
SEP885A92D9BBEE=80018982
# pgiralt-7861
SEP885A92D9AC88=80018983
# pgiralt-8841
SEP00082FB73569=80018984
# pgiralt-8851
SEPB000B4BA2FE0=80018985
# pgiralt-8861
SEPB000B4BA4482=80018986
# pgiralt-9971
SEP1C17D34191C5=80018987

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 78
Cisco JTAPI Overview
What Is Cisco JTAPI?

• JTAPI is a programming interface standard developed by Sun


Microsystems for use with Java-based computer-telephony applications
• Cisco JTAPI implements Sun’s JTAPI 1.2 specification, with
additional Cisco-specific extensions
• Used to develop applications capable of controlling and observing Cisco
Unified CM phones or applications capable of call routing with CTI ports
and route points (virtual devices)
• https://developer.cisco.com/site/jtapi/

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 79
JTAPI
• Java library provided in a JAR file (jtapi.jar)
• Install from Unified CM Plugins Page

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 80
JTAPI Plugin Installation

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 81
Cisco JTAPI Overview
Call Model
Provider

Call

Connection Connection

Address Address
1002 1000
Terminal Terminal Terminal
Connection Connection Connection

Terminal Terminal Terminal


SEPGHI SEPABC SEPDEF

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 82
Cisco JTAPI Overview
JTAPI Application Flow

• Obtain JTAPIPeer object instance from JTAPIPeerFactory


• Obtain a provider, using the getProvider() API on JTAPIPeer
• Obtain from the provider, the terminal(s) and address(es) for use in
your application
• Determine capabilities of relevant objects
• Add observers for the objects, application wishes to
monitor/control
• Begin application flow

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 83
JTAPI – Login & Get Provider

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 84
JTAPI – Get List of Terminals

Wait for Provider to be IN_SERVICE

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 85
JTAPI – Add Observers to Terminals

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 86
Basic Telephony APIs Supported
• connect() - API on CiscoCall to place a call from originating endpoint to a destination
address string
• answer() - API on TerminalConnection to answer the incoming call on this
TerminalConnection
• redirect() - API on CiscoConnection to redirect an incoming telephone call at an
Address to another telephone address
• transfer(call otherCall) - API on CiscoCall which takes otherCall, which could be
either consult call or just another call on same device, as input to complete transfer
• transfer(string destination) - API on CiscoCall to complete
a blind transfer to destination

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 87
Basic Telephony APIs Supported

• Conference (Call otherCall) - API on CiscoCall which takes otherCall, which could be
either consult call or just another call on same device, as input to join together in
single conference
• Conference(Call otherCalls) - API on CiscoCall which takes list of otherCalls and join
them together in single conference call
• Hold() - API on TerminalConnection which allows application to put the call on hold

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 88
Device BLF Server
• CentOS Linux Server
• Build Application in NetBeans IDE 8.0
• Leverage Oracle JAIN SIP API
• http://www.oracle.com/technetwork/java/introduction-jain-sip-090386.html
• 5 Main Modules:
• DeviceBlfApp
• AxlToolkit
• JTAPICore
• SVSTerminalObserver
• SubscriptionManager

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 89
Device BLF Server – “Demo”

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 90
Device BLF Server – Operation
2017-06-21 10:36:28,071 DEBUG [com.cisco.svs.SVSTerminalObserver] - SEP00082FB73569:
Received Event: (P1-dev_blf-test) [SEP00082FB73569] CiscoTermDeviceStateActiveEv [#44]
Cause:100 CallCtlCause:0 CiscoCause:0 FeatReason:12

2017-06-21 10:36:28,071 DEBUG [com.cisco.svs.SVSTerminalObserver] - SEP00082FB73569:


Found Mapped DN: 80018984

2017-06-21 10:36:28,071 DEBUG [com.cisco.svs.SVSTerminalObserver] - SEP00082FB73569:


Send NOTIFY ON for DN 80018984

2017-06-21 10:36:28,071 DEBUG [com.cisco.svs.DeviceBlfApp] - Searching for DN 80018984 in


subscription table.

2017-06-21 10:36:28,071 DEBUG [com.cisco.svs.DeviceBlfApp] - Have 2 Dialog(s) for DN


80018984 - sending NOTIFY

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 91
Device BLF Server – Operation
2017-06-21 10:36:28,073 DEBUG [com.cisco.svs.DeviceBlfApp] - Sending Request:
NOTIFY sip:dbe40e44-0dfe-45f1-bd7f-e652098ca344@172.18.106.59:6060 SIP/2.0
Via: SIP/2.0/UDP 10.81.98.95:6060;branch=z9hG4bK-363132-
e2440db092c5368279758f8043513079
CSeq: 5 NOTIFY
From: <sip:80018984@10.81.98.95>;tag=888
To: <sip:dbe40e44-0dfe-45f1-bd7f-e652098ca344@172.18.106.59>;tag=986586890
Call-ID: 2f74d300-94a18667-43af9f2-3b6a12ac@172.18.106.59
Max-Forwards: 70
Contact: <sip:10.81.98.95:6060;transport=udp>
Event: presence
Subscription-State: active
Content-Type: application/pidf+xml
Content-Length: 769

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 92
Device BLF Server – Operation
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<presence xmlns="urn:ietf:params:xml:ns:pidf" entity="sip:80018984@10.81.98.95"
xmlns:e="urn:ietf:params:xml:ns:pidf:status:rpid" xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
xmlns:ce="urn:cisco:params:xml:ns:pidf:rpid" xmlns:sc="urn:ietf:params:xml:ns:pidf:servcaps">
<dm:person>
<status>
<basic>open</basic>
</status>
<e:activities>
<e:on-the-phone/>
</e:activities>
</dm:person>
<tuple id="cmp-1-12057152">
<status>
<basic>open</basic>
</status>
<sc:servcaps>
<sc:audio>true</sc:audio>
</sc:servcaps>

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 93
Getting Help
https://developer.cisco.com/site/devnet/support/

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 94
Complete your
online session
survey • Please complete your session survey
after each session. Your feedback
is very important.
• Complete a minimum of 4 session
surveys and the Overall Conference
survey (starting on Thursday) to
receive your Cisco Live t-shirt.
• All surveys can be taken in the Cisco Events
Mobile App or by logging in to the Content
Catalog on ciscolive.com/emea.

Cisco Live sessions will be available for viewing on


demand after the event at ciscolive.com.

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 95
Continue your education

Demos in the
Walk-in labs
Cisco campus

Meet the engineer


Related sessions
1:1 meetings

BRKCOL-2256 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 96
Thank you

You might also like