Extending Cisco Unified Communications Manager Using The .
Extending Cisco UnifiedCommunicationsManager usingthe AdministrativeXML/SOAP (AXL) APISpecial thanks to authorJohannes Krohn 2008 Cisco Systems, Inc. All rights reserved.Cisco Public1
AbstractThe SOAP based Administrative XML (AXL) interface of the CiscoUnified Communications Manager provides a unique and flexiblebasis to create customer specific tools to allow for more efficientdeployment, management and operation of UnifiedCommunications deployments. This session will give a quickoverview of the fundamentals of the AXL interface, including verybasic example scripts that use the AXL interface to carry outmanagement tasks. The ultimate goal of this session is to drivethe adoption of the AXL interface and create the confidence thatgiven a set of examples and a basic framework everyone cancreate useful scripts to solve some of the challenges faced in day2-day operations. 2008 Cisco Systems, Inc. All rights reserved.Cisco Public2
Pre-requisitesReaders should have a solid understanding ofCisco Unified Communications Managerconfiguration and operations. 2008 Cisco Systems, Inc. All rights reserved.Cisco Public3
AgendaConceptsAXL APIsDocumentationHow to enable AXLTroubleshootingAXL MessagesAXL VersioningDatabase AccessScripting / AutomationSummary 2008 Cisco Systems, Inc. All rights reserved.Cisco Public4
ConceptsXML, WSDL, SOAP etc. 2008 Cisco Systems, Inc. All rights reserved.Cisco Public5
XMLeXtensible Markup LanguageW3C recommendationrestricted form of SGML (Standard Generalized MarkupLanguage, ISO 8879)general purpose markup languageextensible; individual tags can be definedW3C specifies grammar and parsing requirementsencode documents and serialize dataXML 1.0 (4th edition), 16 August 2006http://www.w3.org/TR/2006/REC-xml-20060816/ 2008 Cisco Systems, Inc. All rights reserved.Cisco Public6
XML, well-formed documentdocument conforms to all syntax rulese.g. opening/closing tag for elementsnot validated against schemaexample: person lastname Krohn /lastname givenname Johannes /givenname /person 2008 Cisco Systems, Inc. All rights reserved.Cisco Public7
XML, special characterssome characters can t be used in XMLsolution: escape or numerical representationescape:&& ampersand< less than> greater than' apostrophe"“ quotation markexample: company AT&T company numerical representation of Unicode codepointexample: ™ 2008 Cisco Systems, Inc. All rights reserved.Cisco Public8
XML, semanticsnames, hierarchy, meaning of elements and attributesdefined by schemaXML Schema defined by W3CPrimer: 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 "givenname" type "xsd:string"/ /xsd:sequence /xsd:complexType 2008 Cisco Systems, Inc. All rights reserved.Cisco Public9
SOAPformerly known as “Simple Object Access Protocol”W3C specification: http://www.w3.org/TR/soap/exchange of structured and typed information based onXML; XML infosetSOAP spec. definesSOAP message formatHow to send and receive messagesData encodingcan be used for remote procedure calls (RPC) 2008 Cisco Systems, Inc. All rights reserved.Cisco Public10
SOAP MessageSOAP MessageEnvelopeHeader (optional)Body (required)Fault (optional) 2008 Cisco Systems, Inc. All rights reserved.Cisco Public11
RPC requirementsRPC requires:address of SOAP nodeprocedure/method nameidentities/values of argumentsoutput parameters, return valuesinterface/service definition not part of SOAP 2008 Cisco Systems, Inc. All rights reserved.Cisco Public12
WSDLWeb Services Definition LanguageW3C: http://www.w3.org/TR/wsdl20/XML based format (grammar) to describe WebServicesdefines four pieces of data:publicly available methods; interface description, formatsdata type information for requests and responsesbinding; which transport protocoladdress information; where to find the service 2008 Cisco Systems, Inc. All rights reserved.Cisco Public13
WSDL service description elementsdefinitions: root elementtypes: which datatypes are exchanged?message: which messages are exchanged?portType: what operations/functions exist?binding: message exchange; soap specificsservice: location of the service 2008 Cisco Systems, Inc. All rights reserved.Cisco Public14
WSDL operation patternsone-wayClient input Service output Service output input Service input output uest/responseClient 2008 Cisco Systems, Inc. All rights reserved.Cisco Public15
AXL APIs 2008 Cisco Systems, Inc. All rights reserved.Cisco Public16
AXLAXL AVVID XML LayerRPCs to the Unified Communications ManagerInterface defined using WSDLSOAP message exchange via HTTP(s) 2008 Cisco Systems, Inc. All rights reserved.Cisco Public17
AXL configuration APIread/modify configuration databasemethodslist*add*update*get*remove*includes methods for direct database accessService port: https:// server :8443/axl/ 2008 Cisco Systems, Inc. All rights reserved.Cisco Public18
Other AXL interfacesPerfmon service WSDL:https:// server -time information service WSDL:https:// server :8443/realtimeservice/services/RisPort?wsdlLog collection service WSDL:https:// server ort?wsdlDIME get file service WSDL:https:// server vice?wsdlControl Center services ce/services/ControlCenterServicesPort?wsdlSOAP Monitor rvices/SOAPMonitorService?wsdlCDR on demand /services/CDRonDemand?wsdl 2008 Cisco Systems, Inc. All rights reserved.Cisco Public19
Documentation 2008 Cisco Systems, Inc. All rights reserved.Cisco Public20
Developer ocuments”you will getData DictionaryXML Developers GuideAXL Interface Specification (HTML) 2008 Cisco Systems, Inc. All rights reserved.Cisco Public21
Documentation on icesw/ps556/products programming reference guides list.htmlProducts, Communications Manager, Configure,Programming Guidesyou will getXML Developer GuideJTAPI Developer GuideTAPI Developer GuideData Dictionary. 2008 Cisco Systems, Inc. All rights reserved.Cisco Public22
AXL documentation on the serverCisco Unified CM AXL SQL Toolkit is available in thePlugin listcontains complete schema definition:AXLAPI.wsdl, AXLEnums.xsd, axlmessage.xsd, axlsoap.xsd,axl.xsd 2008 Cisco Systems, Inc. All rights reserved.Cisco Public23
How to enable AXL 2008 Cisco Systems, Inc. All rights reserved.Cisco Public24
Service ActivationIn Communications Manager ServiceabilityIf you want to use CDR on Demand: 2008 Cisco Systems, Inc. All rights reserved.Cisco Public25
AXL AuthorizationAll AXL requests have to be authorizedAXL requests are authorized using HTTPS basic authorizationAuthorization header with user : password in BASE64 codingAuthorization: Basic YXhsVXNlcjpjaXNjbw BASE64 coding can EASILY be decodedAuthorization secure only because HTTPS is usedDon t use “CCMAdministrator”!Dedicated application user should be used insteadAXL API access is a dedicated role in Communications ManagerUser for AXL API access can/should be limited to AXL APIaccess only 2008 Cisco Systems, Inc. All rights reserved.Cisco Public26
Dedicated user for AXL accessCreate special application user for AXL accessCreate User Group for AXL accessPut AXL user in this user groupUser Group needs Role „Standard AXL API Access“ 2008 Cisco Systems, Inc. All rights reserved.Cisco Public27
Rate ControlAll the performance and Real-time monitoring queries should be polledat the rate that should not affect the Call processing performanceAdmin can configure the system level rate that is acceptable in CallManager environmentIf incoming request rate are exceeded then request will be dropped andslow down responses are sent to appropriate clients making the request 2008 Cisco Systems, Inc. All rights reserved.Cisco Public28
Rate Controlif configured rate is exceeded the server will send aHTTPS 503 Service unavailable responseThese requests are not throttled:executeSQLQuerydoDeviceResetall „get“ requestsall „list“ requestsexecuteSQLUpdate is throttledBeware: Excessive use of the API might have negativeimpact on the call control performance 2008 Cisco Systems, Inc. All rights reserved.Cisco Public29
Troubleshooting 2008 Cisco Systems, Inc. All rights reserved.Cisco Public30
Quick Functionality CheckGo to the AXL API URL via a web browserFor instance, enter https://cm1:8443/axl/ in the addresstext boxWhen prompted for user name and password, use thestandard administrator login, or use the configured AXL userLook for a plain page that states the AXL listener is workingand accepting requests, but only communicates via POSTThis verifies functionality and user access 2008 Cisco Systems, Inc. All rights reserved.Cisco Public31
Enable SOAP Tracesdetailed SOAP traces can be enabled in Cisco UnifiedServiceability settings 2008 Cisco Systems, Inc. All rights reserved.Cisco Public32
Analyze SOAP logsUse Real-Time Monitoring Tool to access SOAP loglog contains incoming SOAP requests and outgoingresponsesINFO [http-8443-Processor24] axl.AxlListener - Received request 1195307341505 fromadmin at IP 192.168.121.1INFO [http-8443-Processor24] axl.AxlListener - SOAP-ENV:Envelope xmlns:SOAPENV "http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:Body axl:getCCMVersionxmlns:axl "http://www.cisco.com/AXL/1.0" /axl:getCCMVersion /SOAP-ENV:Body /SOAPENV:Envelope INFO [http-8443-Processor24] axl.Handler - Handler initializingINFO [http-8443-Processor24] axl.AxlListener - ?xml version "1.0"encoding "UTF-8"? SOAP-ENV:Envelopexmlns:SOAP-ENV V:encodingStyle "http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:Header/ SOAP-ENV:Body axl:getCCMVersionResponsexmlns:axl "http://www.cisco.com/AXL/API/1.0"xmlns:xsi "http://www.cisco.com/AXL/API/1.0" return componentVersion version 6.0.1.2107(1) /version /componentVersion /return /axl:getCCMVersionResponse /SOAP-ENV:Body /SOAP-ENV:Envelope INFO [http-8443-Processor24] axl.AxlListener - Request 1195307341505 was process in791ms 2008 Cisco Systems, Inc. All rights reserved.Cisco Public33
AXL messages 2008 Cisco Systems, Inc. All rights reserved.Cisco Public34
AXL messagesAXL message is a SOAP messagecontains:header (HTTPS)SOAP envelope(SOAP header)SOAP body(SOAP fault) 2008 Cisco Systems, Inc. All rights reserved.Cisco Public35
AXL message formatHeaderPOST: 8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ Content-type: text/xmlSOAPAction: "CUCM:DB ver 6.1"Content-length: 613Basic AuthorizationContent TypeVersioningEnvelope SOAP-ENV:Envelope xmlns:SOAP-ENV si sd "http://www.w3.org/2001/XMLSchema" Body SOAP-ENV:Body axl:getPhone xmlns:axl "http://www.cisco.com/AXL/1.0"xsi:schemaLocation ma/axlsoap.xsd"sequence "1234" phoneName SEP222222222245 /phoneName /axl:getPhone /SOAP-ENV:Body /SOAP-ENV:Envelope 2008 Cisco Systems, Inc. All rights reserved.Cisco Public36
SOAP MessagesGraphical representation of schema available as part ofDeveloper DocumentationContains all elements, complex and simple typesFor every request there are two elements: the actualrequest and a response; example addAARGroup andaddAARGroupResponse 2008 Cisco Systems, Inc. All rights reserved.Cisco Public37
LegendElement NameDescriptionComplex Element Can have childs and attributes.Solid border mandatorySimple ElementNo childs, only attributes. Solidborder mandatoryOptionalOptional. Any type of element canbe optionalSequenceAll children must appear in orderChoiceOnly one of the children canappear 2008 Cisco Systems, Inc. All rights reserved.Cisco Public38
Example: addCSSReq axl:addCSS /axl:addCSS 2008 Cisco Systems, Inc. All rights reserved.Cisco Public39
Example: addCSSReq axl:addCSS name test /name members /members /axl:addCSS 2008 Cisco Systems, Inc. All rights reserved.Cisco Public40
Example: addCSSReq axl:addCSS name test /name members member /member member /member /members /axl:addCSS 2008 Cisco Systems, Inc. All rights reserved.Cisco Public41
Example: addCSSReq axl:addCSS name test /name members member index 1 /index routePartitionName Partition1 /routePartitionName /member member index 2 /index routePartitionName Partition2 /routePartitionName /member /members /axl:addCSS 2008 Cisco Systems, Inc. All rights reserved.Cisco Public42
Example: addCSSReq SOAP-ENV:Envelope xmlns:SOAP-ENV si sd "http://www.w3.org/2001/XMLSchema" SOAP-ENV:Body axl:addCSS xmlns:axl "http://www.cisco.com/AXL/1.0" xsi:schemaLocation "http://www.cisco.com/AXL/1.0 http://ccmserver/schema/axlsoap.xsd" sequence "1234" name test /name members member index 1 /index routePartitionName Partition1 /routePartitionName /member member index 2 /index routePartitionName Partition2 /routePartitionName /member /members /axl:addCSS /SOAP-ENV:Body /SOAP-ENV:Envelope 2008 Cisco Systems, Inc. All rights reserved.Cisco Public43
AXL versioning 2008 Cisco Systems, Inc. All rights reserved.Cisco Public44
AXL versioningchanges in Communications Manager functionality drive AXLschema changesschema change might require changes in components using the APISolution: starting with release 6.1 every communications managerwill support several versions of the APIevery release will still support the releases of the previous majorreleaserequestor defines version to use via the “SOAPAction” header; e.g.:SOAPAction: "CUCM:DB ver 6.0"SOAPAction header currently is optional; if missing request will betreated as a 6.0 requestSOAPAction header will be mandatory in future releasesAccess to not supported version will lead to:599, „The version you specified is not available.Available versions are 6.0, 6.1 and 1.0” 2008 Cisco Systems, Inc. All rights reserved.Cisco Public45
Database Access 2008 Cisco Systems, Inc. All rights reserved.Cisco Public46
Database Dictionaryconfiguration in Communications Manager is stored inrelational databasedictionary documents all existing tables inCommunications Manager Databasefield typesdatabase constraintsrelationsCommon Table RelationshipsSchema changes in recent releases 2008 Cisco Systems, Inc. All rights reserved.Cisco Public47
Table relations (1)pkid is the primary key ID. It is always of type GUID.Fields that begin with the letters "fk" represent foreignkeys into another table. The name of the field followingthe "fk" prefix up to but not including an underscorecharacter is the name of the related table. The field inrelated table is always pkid. and is a GUID.Examples in table r lingsearchspace.pkiddevice.fkcallingsearchspace aar 2008 Cisco Systems, Inc. All rights reserved.Cisco Publiccallingsearchspace.pkid48
Table relations (2)Fields that begin with the letters "ik" represent internalkeys into the same table.Example in table device:device.ikdevice primaryphone 2008 Cisco Systems, Inc. All rights reserved.Cisco Publicdevice.pkid49
Table relations (3)Fields that begin with a "tk" represent an enumeratedtype. This field is related to a table whose name beginswith "Type" and ends with the name of the fieldfollowing the prefix up to but not including anunderscore character. The field in the related table isalways "enum" and is an integer.Examples in table el.enumtypeproduct.enum 2008 Cisco Systems, Inc. All rights reserved.Cisco Public50
SQLlanguage for retrieval and management of data storedin relational database management systemsoriginally called SEQUEL (structured english querylanguage)standardized by ISO/IEC 2008 Cisco Systems, Inc. All rights reserved.Cisco Public51
SQL Statements on the CLISQL statements can be executed on the CLI using „run sql““&” can t be used on the CLICan be used to test SQL statements to be used in scriptsExample:admin:run sql select enum,name from typemodel wheretksubclass 1enum name 20SCCP Phone134Remote Destination Profile30027 Analog Phone30028 ISDN BRI Phone2Cisco 12 SP 3Cisco 12 SP. 2008 Cisco Systems, Inc. All rights reserved.Cisco Public52
Example: dialplanAll DNs and patterns are stored in table numplanadmin:run sql select dnorpattern, fkroutepartition, tkpatternusagefrom numplandnorpattern XX006196773.XXXX006196773.XXXX9765fkroutepartition 2dtkpatternusage 5555552Which partition? What type of pattern?Let's look in tables routepartition and typepatternusage 2008 Cisco Systems, Inc. All rights reserved.Cisco Public53
Example: dialplanadmin:run sql select dnorpattern, routepartition.name,typepatternusage.name from numplan,routepartition,typepatternusagewhere fkroutepartition routepartition.pkid andtkpatternusage typepatternusage.enumdnorpattern 496196773.XXXX006196773.XXXXname sNOv100sitesNOvname teAssignment of DNs to devices is in table devicenumplanmap 2008 Cisco Systems, Inc. All rights reserved.Cisco Public54
Database access via AXLAXL provides methods to execute SQL queries andupdates:executeSQLQuery (SELECT)executeSQLUpdate (INSERT, UPDATE, DELETE)both methods take a SQL command as argument 2008 Cisco Systems, Inc. All rights reserved.Cisco Public55
executeSQLQueryResult is a sequence of rowseach row has a number of sub-elements, one per column of theresulting table SOAP-ENV:Envelope . SOAP-ENV:Header/ SOAP-ENV:Body axl:executeSQLQueryResponse . return row pkid 8555d448-5818-8494-e16a-de099e9a403c /pkid realm jkrohn /realm userid jkrohn /userid passwordreverse . /passwordreverse /row /return /axl:executeSQLQueryResponse /SOAP-ENV:Body /SOAP-ENV:Envelope sequence can be empty! SOAP-ENV:Body axl:executeSQLQueryResponse . return/ !!! /axl:executeSQLQueryResponse /SOAP-ENV:Body 2008 Cisco Systems, Inc. All rights reserved.Cisco Public56
executeSQLUpdateWriting to the database can destroy database integrity and thuscompromise core functionality!Very limited to no integrity checks!delete means deleted result is an element indicating the number of rows updated SOAP-ENV:Envelope . SOAP-ENV:Header/ SOAP-ENV:Body axl:executeSQLUpdateResponse . return rowsUpdated 1 /rowsUpdated /return /axl:executeSQLUpdateResponse /SOAP-ENV:Body /SOAP-ENV:Envelope 2008 Cisco Systems, Inc. All rights reserved.Cisco Public57
2008 Cisco Systems, Inc. All rights reserved. Cisco Public 1 Extending Cisco Unified Communications Manager using the Administrative XML/SOAP (AXL) API
Cisco Unified Workspace Licensing (CUWL) Cisco Unity FAX Server : Cisco IP Communicator . Cisco Unified Application Server : Cisco Unified Media Engine . Cisco Unified Communications Manager Attendant Console : Cisco Unified Presence . Cisco Emergency Responder : Cisco Unified Personal Communicator . Cisco Unified IP Interactive Voice Response
Cisco Unified MeetingPlace Express VT: cotang@cisco.com Cisco Unified Personal Communicator: jchase@cisco.com Cisco IP Communicator: cs-communicator@cisco.com Cisco Unified Video Advantage: cotang@cisco.com Cisco Unfied Presence: stlevy@cisco.com Cisco Unified Mobility Advantage: unified_mobility_og@cisco.com
For Cisco Unified Communications Manager Release 5.0 or earlier, see Bulk Administration Tool User Guide for Cisco Unified Communications Manager for detailed instructions about BAT and TAPS. For Cisco Unified Communications Manager Release 6.0 or later, see Cisco Unified Communications Manager Bulk Administration Guide. Related Topics
The Cisco Unified Communications Manager Adapter pr ovides connectivity between the IBM Security Identity server and the Cisco Unified Communications Manager server . The adapter r uns as a service, independent of whether you ar e logged on to IBM Security Identity Manager . The Cisco Unified Communications Manager Adapter automates the following
Cisco Unified IP Phone 6921, 6941, 6945, and 6961 Administration Guide for Cisco Unified Communications Manager 8.6 (SCCP and SIP) OL-24567-01 Understanding How the Cisco Unified IP Phone Interacts with Cisco Unified Communications Manager Express 2-3 Providing Power to the Cisco Unified IP Phone 2-4 Power Guidelines 2-4 Power Outage 2-5
4 Release Notes for Cisco Unified Communications Manager Release 8.5(1) OL-23282-01 System Requirements Note Make sure that the matrix shows that your server model supports Cisco Unified CM Release 8.5(1). Note Be aware that some servers that are listed in the Cisco Unified Communications Manager Software Compatibility Matrix may require additional hardware support for Cisco Unified CM Release .
Cisco Unified IP Phone 6901/6911/6921/6941/ 6961 Cisco Unified Personal Communicator Cisco IP Communicator Cisco Unified Wireless IP Phone 7921G/ 7925G/7925G-EX Cisco Unified Personal Communicator Cisco Unified CME 8.5 - IP Phone Portfolio Accessories Mobility Conference Video Business Manager
Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unified Computing System (Cisco UCS), Cisco UCS B-Series Blade Servers, Cisco UCS C-Series Rack Servers, Cisco UCS S-Series Storage Servers, Cisco UCS Manager, Cisco UCS
