BRKCDN-1116 - Creating Applications Using Cisco Unified Routing Rule Interface.pdf

BRKCDN-1116

Creating Applications Using Cisco’s Unified Routing Rule Interface

Follow us on Twitter for real time updates of the event:

@ciscoliveeurope, #CLEUR

© 2012 Cisco and/or its affiliates. All rights reserved. Cisco Public BRKCDN-1116 2

Housekeeping

We value your feedback- don't forget to complete your online session evaluations after each session & the Overall Conference Evaluation which will be available online from Thursday

Visit the World of Solutions and Meet the Engineer

Visit the Cisco Store to purchase your recommended readings

Please switch off your mobile phones

After the event don‘t forget to visit Cisco Live Virtual: www.ciscolivevirtual.com

Follow us on Twitter for real time updates of the event: @ciscoliveeurope, #CLEUR

http://www.ciscolivevirtual.com/

http://www.ciscolivevirtual.com/


Agenda

External Call Control Refresher

Enhancements to the Sample Application

Converting the Sample Application to Run Under Apache

Building Applications with Cisco‘s Unified Routing Rules Interface

Q&A

External Call Control Refresher


External Call Control Overview

An External Call Control Profile (ECCP) is assigned to one or more Unified CM translation patterns

When dialed digits match an ECCP pattern, Unified CM issues a Web 2.0 Route Request over the Cisco Unified Routing Rules XML Interface (CURRI)

The Web application evaluates the information and returns call handling instructions as a Decision with Obligation:

Decision - specifies if the call is Allowed or Denied

Obligation - contains specific call routing instructions and treatment

- Route the call normally and optionally modify calling/called party number(s)

- Divert the call to a different destination or to voice mail and optionally modify calling/called party number(s)

- Reject the call and optionally play an announcement


Cisco UCM

1. Call 5. Setup

Unified CM Administrator assigns external call control profile at trigger points (translation patterns)

A route server hosting call routing policy running web service for Unified CM External Call Control.

Route Server

Unified CM Admin

2. HTTP POST (XACML Request with call info)

3. HTTP 200 OK (XACML Response with policy decisions & obligation)

4. Unified CM routes the call based on the policy decision and obligation

D

External Call Control Architecture


Cisco Unified Routing Rules XML Interface (CURRI)

Uses XACML* over HTTP or HTTPS * eXtensible Access Control Markup Language, an OASIS standard

a standards-based XML-based language

XACML Response consists of a Decision and an Obligation

Obligation encoded in Call Instruction XML (CIXML), routing

instructions customized to Unified CM

Example applications provided for developing web services

for Unified CM ECC


External Call Control Profile (ECCP)

Defines the URI of the web service application queried

Supports HTTP or HTTPS

Mutual authentication using certificates is required for HTTPS

connections

ECCP permits configuration of two URIs for redundancy (active &

standby) or for load balancing

ECCP also specifies

Timeout value for call routing response

Call treatment on failure

Calling search space for call diversion


External Call Control Profile Configuration


The Triggering Point – Translation Pattern

Trigger Point – The point in Unified CM‘s routing logic at which

Unified CM issues a Route Request

Translation Patterns are the trigger points in Unified CM 8.0(1)

Specific Dialed or Received number – 55555 or +14085551212

Wildcard Dialed or Received number – 5XXXX or +1[2-9]XX[2-9]XXXXXX

Calling or Called Party numbers can be masked or changed using

translation patterns as needed

Reduces configuration

Enables large groups of numbers to receive route treatment


Enable External Call Control for a Translation Pattern


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* (see below)

Called number or dialed digits

Transformed called number* (see below)

Type of the triggering point, i.e., translation pattern

* The number that Unified CM‘s translation pattern wants to

convert the calling and called number to. In our reference dial

plans, the transformed value is usually the globalized number of

the caller and called party


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”



</Attribute>

<Attribute AttributeId="urn:Cisco:uc:1.0:transformedcdpn”



</Attribute>

</Subject>

continued on next slide…

For Your Reference

http://www.w3.org/2001/XMLSchema




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


<AttributeValue>translationpattern</AttributeValue>

</Attribute>

</Environment>

</Request>

For Your Reference




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


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]: Calling and/or

called numbers will be substituted with the numbers provided

Divert – Route to diverted destination specified

destination: [dest]: The [dest] is a routable number or ―voicemail‖

reason: [reason]: the only reason supported is ―chaperone‖

modify callingnumber=[number] callednumber=[number]: Calling and/or

called numbers of current hop will be substituted with the numbers

provided

resetCallHistory: The last call hop or all previous call hops will be removed

from the call history. Useful when sending call to voicemail.


Example Call Route Response <?xml encoding="UTF-8" version="1.0"?>

<Response>

<Result>

<Decision>Permit</Decision>

<Obligations>

<Obligation FulfillOn="Permit" ObligationId="continue.simple">

<AttributeAssignment AttributeId="Route:continue.simple”

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string”

<cixml version="1.0>

<divert>

<destination>

+19725550100

</destination>

</divert>

</cixml>

</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

</Response>


Failure Treatment

Unified CM applies failure treatment in the following situations:

Unified CM fails to establish connections to the Route Server

Unified CM cannot parse the response for the route decision or call routing directive

Unified CM receives 4xx or 5xx from Route Server

Unified CM times out waiting for a response

Failure treatment is specified in the External Call Control profile; the treatment

is either ―Allow Calls‖ or ―Block Calls‖

If the failure treatment is ―Allow Calls‖, the call is routed to the current

destination, as if a permit decision with a continue directive is received

If the failure treatment is ―Block Calls‖, the call will be cleared, as if a deny

decision with a reject directive is received

When a failure occurs, an alarm will be logged


Connections to Route Server

Unified CM maintains persistent connections to route servers to

reduce delay in call setup time

All nodes (Publisher and all Subscribers) in a Unified CM cluster will

establish a connection to the route server for parallel/simultaneous

queries at high call rate.

The connection is always enabled on all nodes. The Route server

should be configured to expect Route Requests from all nodes.

URIs in External Call Control determine if HTTP or HTTPS

connections are established


Security

When the URI indicates HTTPS:

- Unified CM establishes TLS connections to route server with mutual authentication

using certificates

To establish HTTPS connections:

- Import certificates from each route server into Unified CM‘s trust store on each

Unified CM node

- Export a self-signed certificate from each Unified CM node and import it to route

server‘s trust store

Unified CM accepts self-signed certificates as well as certificates

signed by trusted CA

Unified CM conducts the following verifications when authenticating

the server:

- Verification of host: Check whether the certificate subject name matches the

server‘s host name

- Verification of peer: Check whether the signature of the certificate is issued by the

trust CA in the trust store or if it matches the imported certificates in the trust store

for a self-signed certificate


Call Detail Records

Three new columns (current, original and last redirecting) for ―external call

control routing reason‖ have been added to Call Detail Record (CDR). The

following values may present in a CDR:

PDPDecision_Allow: Route Server allows the call

PDPDecision_Reject: Route Server denies the call

PDPDecision_Divert: Route Server diverts the call

UCMDecision_Allow: Unified CM applied call allow failure treatment

UCMDecision_Block: Unified CM applied call block failure treatment


Performance Counters: Call-related Call-related performance counters are in the Cisco CallManager object

ExternalCallControlEnabledCallAttempted: Total number of External Call Control-enabled

calls

ExternalCallControlEnabledCallComplete: Total number of External Call Control-enabled

calls that are answered

ExternalCallControlEnabledFailureTreatmentApplied: Total number of External Call

Control-enabled calls that failure treatments were applied


Real-time Monitoring Tool – External Call Control Performance Counters:


Basic Requirements for Web Application

HTTP 1.1 for persistent connection

Support thread pool for multiple persistent connections

Support HTTPS connection with mutual authentication using

certificates

Support HTTP KeepAlive header

- Support HTTP HEAD method for KeepAlive from Cisco Unified CM

Support XACML Call Routing request as specified in Cisco Unified

Route XML API specification

Support HTTP POST method for XACML Call Routing Request

Respond with XACML Call Routing Response as specified in Cisco

Unified Route XML API specification


Getting Unified CM to Perform Route Requests

Make sure you specify the port number of your Route Request server in Unified CM

Configure your Route Request (web) server to hide the complexity of the application‘s URI:

- Don‘t: ―http://server/myapp/routing/curri.asp/request/‖

- Do: ―http://server:80/myapp/routingrequest‖

Make sure your application responds to the Keep-Alive requests from Unified CM (HEAD Requests)

Don‘t forget to turn on the Media Streaming service if you want custom announcements

Enhancements to the Sample Application


My enhancements to the XML Parser

Being a ‗print statement‘ learner, I had a hard time following what was going on in the XML Parser

Added a SetDebug method to allow turning on and off debug print statements in the parser

- Allows disabling the extra messages after learning or debugging is completed

Enhanced the XML Parser to improve the handling of whitespace in the route request

- Ignored data that only contained whitespace

- Remove whitespace from data that could interfere with string matching while processing route requests


Sample Debug Output Prior to Enhancements

1. --- Begin Document ---

2. AttributeId urn:oasis:names:tc:xacml:1.0:subject:role-id

3. AttributeId urn:Cisco:uc:1.0:callingnumber

4. CallingNumber: 2010

5. AttributeId urn:Cisco:uc:1.0:callednumber

6. CalledNumber: 2011

7. AttributeId urn:Cisco:uc:1.0:transformedcgpn

8. TransformedCgpn: +19728132010

9. AttributeId urn:Cisco:uc:1.0:transformedcdpn

10. TransformedCdpn: +19728132011

11. AttributeId urn:oasis:names:tc:xacml:1.0:resource:resource-id

12. AttributeId urn:oasis:names:tc:xacml:1.0:action:action-id

13. AttributeId urn:Cisco:uc:1.0:description

14. endElement Request


Method to Set Debug Status

The Class Constructor‘s default is to turn debugging off

def setDebug(self, debug):

if debug == 1:

self.debug = debug

print 'Debugging is turned on!'

elif debug == 0:

self.debug = debug

else:

print 'Incorrect Debug, defaulting to Debugging turned off!'

In the rest of the parser, you can then check the status of debug before logging any debug output:

- if self.debug: print 'characters are spaces'


Removing Whitespace from Request

def characters(self, ch):

if self.isCallingNumber == 1:

self.CallingNumber = ch

print 'CallingNumber ' + ch

self.isCallingNumber = 0

def characters(self, ch): if ch.isspace(): # Characters are spaces ch = '' else: # Strip any whitespace chStrip = ch.strip() if self.isCallingNumber == 1: self.CallingNumber = chStrip self.isCallingNumber = 0

Sample App‘s Way Enhanced Way


Sample Debug Output after Enhancements

1. --- Begin Document ---

2. characters are spaces


4. AttributeId urn:oasis:names:tc:xacml:1.0:subject:role-id


6. ch len is 25 ch is CISCO:UC:UCMPolicy

7. chStrip len is 18 , value is CISCO:UC:UCMPolicy



10. AttributeId urn:Cisco:uc:1.0:callingnumber


12. ch len is 11 ch is 2010

13. chStrip len is 4 , value is 2010

14. CallingNumber: 2010


Checking out the Sample Policy Application

The sample application illustrates usage of External Routing Rules using Cisco‘s Unified Routing Rules Interface (CURRI)

Hint 1: To run it as a standalone application, you may have to modify the shell‘s path to ―favicon‖

Hint 2: Curl is a very useful application to check the routing application:

- Save the sampleXacmlReq.xml file somewhere handy to the shell and to curl

- curl -k -H "Content-type: text/xml;" -d @sampleXacmlReq.xml http://server:port


Demo 1

Demo of Sample CURRI Application

1. Start the Sample Application as standalone web server:

./samplePolicyApp.py 127.0.0.1 8080 http

2. View the contents of the sample XACML Request:

cat sampleXacmlReq.xml

3. Use curl to POST the XACML Request and see Response:

curl -k -H "Content-type: text/xml;" -d @sampleXacmlReq.xml http:// 127.0.0.1 :8080

Converting the Sample Policy Application to run under Apache


It’s all about the web, right?

Running the Sample Application under the standalone Python web server is great, but what if you want to run multiple applications?

Two key criteria for my CURRI development efforts:

- Wanted to continue using Python

- Wanted something more robust than basic CGI


Running Python under Apache

Leverage the WSGI specification for web applications

mod_wsgi is an Apache module that implements a Python WSGI interface

Very straightforward to install and configure on an Ubuntu-Apache web server


Processing Route Request with WSGI


Sample WSGI Configuration

Some sample configuration snippets from an Apache 2 default site configuration (/etc/apache2/sites-available/default):

1. WSGIDaemonProcess localhost processes=2 threads=15 display-name=%{GROUP} python-path=/var/www/wsgi-scripts

2. WSGIProcessGroup localhost

3. WSGIScriptAlias /apps/ "/var/www/wsgi-scripts/― WSGIScriptAlias /curri1 "/var/www/wsgi-scripts/samplePolicyApp.wsgi"

4. <Directory "/var/www/wsgi-scripts/">

Order allow,deny

Allow from all

- </Directory>

For Your Reference


Get started with the WSGI conversion

No changes needed to the actual XML Parser

Need to convert samplePolicyApp to a WSGI application

Writing to a static-named temporary file in a multi-threaded web application—probably not a good idea!

- Let Python turn the string of POST data into a file-like object that can be passed to the XML Parser

Use Python Templates to make the responses a little more generic (and easier to read)


Overview of the WSGI Conversion


Accepting the web service request – Part 1

def application(environ, start_response):

# Process the Keep Alive (HEAD) Request from CUCM

if (environ.get('REQUEST_METHOD', 'HEAD') == 'HEAD'):

status = '200 OK'

output = ''

response_headers = [('Content-type', 'text/html'),

('Content-Length', '1000')]

start_response(status, response_headers)

return [output]


Accepting the web service request – Part 2

# Get the length of the routing request within the POST data

try:

length = int(environ.get('CONTENT_LENGTH', 0))

except ValueError:

length = 0

# Retrieve the POST data from the routing request

postData = environ['wsgi.input'].read(length)


Building the web service reply

Every reply begins with the same building block:

# Build the actual server response to CUCM

status = '200 OK'

output = response

response_headers = [('Content-type', 'text/xml; charset="utf-8"'), ('Content-Length', str(len(output)))]


After the request processing is complete, the application end by returning the filled in output:

return [output]


Parsing the route request

parser = xml.sax.make_parser()

xacmlParser = XacmlHandler()

xacmlParser.setDebug(parserDebugLevel)

parser.setContentHandler(xacmlParser)

# Treat the POST data (a string object) like a file object

stringXacmlReq = io.StringIO(postData)

# Parse the actual XACML Request

parser.parse(stringXacmlReq)

Note: You may need

cStringIO Method for

your implemenation


Filling in the template ‘blanks’

Python templates allow you to build a ‗string‘ with placeholders that can be filled in later

Divert Template has placeholders for the destination and reason:

- divertResponse =

divertTemplate.substitute({'destination': '1001', 'reason': 'chaperone'})


Using a Template for reply

divertTemplate = string.Template("""\

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

<Response>

<Result>

<Decision>Permit</Decision>

<Obligations>

<Obligation FulfillOn="Permit" ObligationId="continue.simple">

<AttributeAssignment AttributeId="Policy:continue.simple">

<AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">

<cixml ver="1.0">

<divert>

<destination>

$destination

</destination>

</divert>

<reason>$reason</reason>

</cixml>

</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

</Response>

""")


Using a Template for reply - CIXML

<cixml ver="1.0">

<divert>

<destination>

$destination

</destination>

</divert>

<reason>$reason</reason>

</cixml>


Demo 2

Demo of Sample CURRI Application ported to a WSGI-based Web Server:

1. View the contents of the sample XACML Request:

cat sampleXacmlReq.xml

2. Use curl to POST the XACML Request and see Response:

curl -k -H "Content-type: text/xml;" -d @sampleXacmlReq.xml http://172.16.43.121/curri1

Building Applications with CURRI


Using CURRI to solve problems

CURRI can enhance dial plans in ways that can‘t be achieved natively

- Block incoming calls based on calling number

- Route incoming calls based on calling number

CURRI can supplement enterprise dial plans with Session Management

- Use ENUM to resolve next hop call destinations

CURRI can be combined with data from other applications to route calls

- Use called number and presence from CUP to route call to available user without login/logout of hunt groups


Getting started with blocking calls

Need a database of phone numbers that you want Unified CM to block calls from (calling number)

Need a way to maintain the database of numbers

Need an CURRI-based application that:

- Accepts the route request containing the calling number

- Checks the database to see if call should be blocked

- Returns a routing response to Unified CM

CAN leverage the XACML parser that was used for the sample policy application!


Block Calls Application Components


Building a Phone Number database

If your data set is pretty small, you could embed the numbers right in your application

- Obviously, painful to make changes

Use text files to store them; but you have to write a bunch of code to manage adding, deleting, searching

Use a real database to store them; would work, but potentially overkill

- Python extends its dictionary concept to persistent storage with shelves

- Acts like a database for adding, deleting, and searching


Management Web Application

You can use a web application to maintain the data:


Build the CURRI route request processing

Three parts to the application

1. Accept and parse the route request from Unified CM

Reuse keep-alive and POST processing from the samplePolicyApp

Reuse the XACML processor from the samplePolicyApp

2. Check the database to see if it contains the calling number found in this route request

3. Format and return a response to Unified CM

If the number isn‘t in the DB, return a PERMIT decision

If the number is in the DB, return a DENY decision


Search the database – Part 1

def blockedNumber(number):

# Prepare to open the database to process request

shelf = shelvedir + '/' + shelvename

numberDB = shelve.open(shelf)

numEntries = len(numberDB)

if (numEntries < 1):

# Nothing in the database, so nothing to block

return 0

# Use the number as a key to make things easier

key = number


Search the database – Part 2

# Check to see if the number is already in the database

if (key in numberDB):

# Number is already in the database, block it

blockNum = 1

else:

# Number is not in the database, permit call

blockNum = 0

# Close the database shelve

numberDB.close()

return blockNum


Respond to the route request – Part 1

theCallingNum = str(xacmlParser.callingNumber())

# Determine appropriate action and complete the response form

if (blockedNumber(theCallingNum) == 1):

# Number is in the blocked call database, deny it

response = rejectTemplate.substitute({'greetingID': '\"Custom_05001\"',

'reasonValue': 'call blocking'})

else:

# Number should not be blocked, continue the call

response = continueTemplate.substitute()


Respond to the route request – Part 2

# Build the actual server response to CUCM

status = '200 OK'

output = response

response_headers = [('Content-type', 'text/xml; charset="utf-8"'),

('Content-Length', str(len(output)))]


return [output]


SampleBlockApp ToDo List

Add authentication and HTTPS access to the tool

- Straightforward if you are already running Apache

Add some database locking or consistency checking to manage conflicts

Pretty up the web application, format the database display, add searching the database

Add some validation of input phone numbers

Track usage of blocked numbers


Adding ENUM lookups to SME

ENUM uses DNS mechanisms to identify the call processing agent that will route the call to a specified phone number

Provides a scalable means to route calls at the directory number level in complicated environments

Session Management Edition (SME) doesn‘t natively have ENUM lookups

Could use CURRI (along with some SME configuration) to route calls using ENUM lookups


Enum Routing Process


How would ENUM routing work?

1. SME receives a call setup for 4125551212

2. Translation pattern in SME triggers an external call control profile

3. SME sends route request to CURRI application

4. CURRI application makes a DNS request for called number received in the route request

5. DNS server returns a URI that indicates the destination of the call

6. CURRI application extracts the ‗server‘ portion of the URI as the destination or ‗next hop‘ of the call

7. CURRI application converts the ‗server‘ into a routing code that SME can use to select a route (prefixed to the called number)

8. SME strips the routing code and sends the call to the appropriate Route List

For Your Reference


Additional Information

Cisco Developer Web Site:

- http://developer.cisco.com

CURRI Documentation (including sample application):

- http://developer.cisco.com/web/curri/docs

mod_wsgi Documentation:

- http://code.google.com/p/modwsgi/

Python XML Parsing with the SAX2 Parser:

- http://docs.python.org/library/xml.sax.html

For Your Reference

http://code.google.com/p/modwsgi/

Q&A

Recommended Reading

Please visit the Cisco Store for suitable reading.


Please complete your Session Survey

Don't forget to complete your online session evaluations after each session.

Complete 4 session evaluations & the Overall Conference Evaluation

(available from Thursday) to receive your Cisco Live T-shirt

Surveys can be found on the Attendee Website at www.ciscolivelondon.com/onsite

which can also be accessed through the screens at the Communication Stations

Or use the Cisco Live Mobile App to complete the

surveys from your phone, download the app at

www.ciscolivelondon.com/connect/mobile/app.html

We value your feedback

http://m.cisco.com/mat/cleu12/

1. Scan the QR code

(Go to http://tinyurl.com/qrmelist for QR code reader

software, alternatively type in the access URL above)

2. Download the app or access the mobile site

3. Log in to complete and submit the evaluations

http://www.ciscolivelondon.com/onsite

http://www.ciscolivelondon.com/connect/mobile/app.html

http://tinyurl.com/qrmelist



Thank you.

Documents

BRKCDN-1116 - Creating Applications Using Cisco Unified Routing Rule Interface.pdf