Table Of Contents

Cisco Unified Routing Rules Interface

Overview

New and Changed Information

New Information for Cisco Unified Communications Manager 9.0(1)

New and Changed Information in Previous Releases of Unified CM

New Information for Cisco Unified Communications Manager 8.6(1)

New Information for Cisco Unified Communications Manager 8.5(1)

New Information for Cisco Unified Communications Manager 8.0(1)

Call Routing Request

Description

Format

Parameters

Example

XACML Request Schema

Call Routing Response

Description

Format

Parameter

CIXML Format

CIXML Parameter

Example

XACML Response Schema

CIXML Schema

Keep-Alive Message

Message Timer

Connections

Multiple Connections

Redundant Web Services

Persistent Connection and Keep-Alive

Redirection

Error Handling

Web Service Connection Failure

Unified CM Timeout Awaiting Response from Web Service

Error Response from Web Service

Web Service Parse Request Error

Unified CM Parse Response Error

Web Service Evaluation Request Error

Security

Authentication

Certificate and Key

Generation and Exchange

Certificate Format

Transport Layer Security Version

Cipher Specification

Cisco Unified Routing Rules Interface

---

This chapter describes the Cisco Unified Routing Rules Interface.

It contains the following sections:

•Overview

•New and Changed Information

•Call Routing Request

•Call Routing Response

•Keep-Alive Message

•Connections

•Error Handling

•Security

Overview

Cisco Unified Communication Manager (Unified CM) 8.0(1) and later supports the External Call Control (ECC) feature. This feature enables an adjunct route server to make call-routing decisions for Unified CM by using the 8.0(1) and later Cisco Unified Routing Rules interface. On configuring the external call control feature, Unified CM issues a call routing request when the called number matches the external call control enabled pattern. The call routing request contains the calling party and called party information to the adjunct route server. The adjunct route server receives the request, applies appropriate business logic, and returns a call routing response that instructs Unified CM on how the call should be routed, along with any additional call treatment that should be applied.

The adjunct route server can instruct Unified CM to:

•Allow, divert, or deny the call.

•Modify calling and called party information.

•Play announcements to callers.

•Reset call history so that the adjunct voicemail and IVR servers can properly interpret calling or called party information.

•Log reason codes that indicate why calls were diverted or denied.

The following examples show how external call control works:

•Best Quality Voice Routing—The adjunct route server monitors network link availability, bandwidth usage, latency, jitter, MOS scores, and returns routing directives to ensure that calls are routed through voice gateways that deliver the best voice quality to all call participants.

•Least Cost Routing—The adjunct route server is configured with carrier contract information such as Lata and Inter-Lata rate plans, trunking costs, and burst utilization costs to ensure calls are routed over the most cost effective links.

•Ethical Wall—The adjunct route server is configured with corporate policies that determines which users are allowed to communicate with each other and ensures that only permitted communications are allowed.

For information on how to configure External Call Control, refer to the Cisco Unified Communications Manager Features and Services Guide for Release 8.0(1) at http://www.cisco.com/en/US/products/sw/voicesw/ps556/prod_maintenance_guides_list.html.

New and Changed Information

The following sections provide information on the changes in the Routing Rules APIs in Unified CM release 9.0(1) and the previous releases:

•New Information for Cisco Unified Communications Manager 9.0(1)

•New and Changed Information in Previous Releases of Unified CM

New Information for Cisco Unified Communications Manager 9.0(1)

There are no changes in the Routing Rules API in Unified CM release 9.0(1).

New and Changed Information in Previous Releases of Unified CM

This section provides the new and changed information in previous versions of Unified Communications Manager.

•New Information for Cisco Unified Communications Manager 8.6(1)

•New Information for Cisco Unified Communications Manager 8.5(1)

•New Information for Cisco Unified Communications Manager 8.0(1)

New Information for Cisco Unified Communications Manager 8.6(1)

There are no changes in the Routing Rules API in Unified CM release 8.6(1).

New Information for Cisco Unified Communications Manager 8.5(1)

There are no changes in the Routing Rules API in Unified CM release 8.5(1).

New Information for Cisco Unified Communications Manager 8.0(1)

This is the initial release of the routing rules interface.

Call Routing Request

This section provides information on the call routing request message. The following topics are covered:

•Description

•Format

•Parameters

•Example

•XACML Request Schema

Description

Unified CM sends the eXtensible Access Control Markup Language (XACML) based routing request over HTTP or HTTPS using the POST method. The XACML requests comply with XACML v2.0 standard.

---

Note For more information on XACML, refer to XACML 2.0 Core: eXtensible Access Control Markup Language (XACML) Version 2.0 document at http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf

---

The XACML request contains the following information about the call:

•The calling and called numbers

•The transformed calling and called numbers, that is, the results of the calling and called number transformation applied at the translation pattern.

•The type of trigger point. TranslationPattern is the only trigger point type that is supported in Unified CM release 8.0(1).

Format

The following is the call routing request format:

POST <Request-URI> HTTP/1.1

Host: <route server>:<port>

Accept: */*

Content-type: text/xml; charset=ISO-8859-1

methodName: <string>

User-Agent: CiscoUCM-HttpClient/1.0

Connection:Keep-Alive

Content-Length: <length>

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

<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:2.0:subject:role-id" 
DataType="http://www.w3.org/2001/XMLSchema#string" Issuer="requestor" 
<AttributeValue>[string]</AttributeValue> </Attribute>

<Attribute AttributeId="urn:Cisco:uc:1.0:callingnumber" 
DataType="http://www.w3.org/2001/XMLSchema#string"> 
<AttributeValue>[number]</AttributeValue> </Attribute>

<Attribute AttributeId="urn:Cisco:uc:1.0:callednumber" 
DataType="http://www.w3.org/2001/XMLSchema#string"> 
<AttributeValue>[number]</AttributeValue> </Attribute>

<Attribute AttributeId="urn:Cisco:uc:1.0:transformedcgpn" 
DataType="http://www.w3.org/2001/XMLSchema#string"> 
<AttributeValue>[number]</AttributeValue> </Attribute>

<Attribute AttributeId="urn:Cisco:uc:1.0:transformedcdpn" 
DataType="http://www.w3.org/2001/XMLSchema#string"> 
<AttributeValue>[number]</AttributeValue> </Attribute>

</Subject>

<Resource>

<Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" 
DataType="http://www.w3.org/2001/XMLSchema#anyURI"> 
<AttributeValue>[string]</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>[URI]</AttributeValue> </Attribute>

</Action>

<Environment>

<Attribute AttributeId="urn:cisco:1.0:triggerpointtype" 
DataType="http://www.w3.org/2001/XMLSchema#string"> 
<AttributeValue>[string]</AttributeValue></Attribute>

</Environment>

</Request>

Parameters

This section provides the description of various parameters in the request format.

Parameters	Description
HTTP POST Message
Request-URI	You can provision the Request-URI in an external call control profile. The Cisco Unified CM administrator can customize the URI for a particular web service in a deployment. For example, when an XACML 2.0 compliant policy server provides the web service, the Request-URI can be set to /pdp/AuthorizationEndPoint
Host:<route server>:<port>	The host and port of the web service to which the request is sent. For example, Host:cepm1.cisco.com:8080
methodName	The name of the method. For example, isRoleAccessAllowed is used when Cisco Enterprise Policy Manager is the Policy Decision Point (PDP).
User-Agent	The User-Agent field is set to CiscoUCM-HttpClient/1.0
Content-Length	The Content-Length field indicates the size of the entity-body in octets.
XACML Message
role-id	The static role configured in the web service.
callingnumber	The telephone number or the directory number of the calling party. It depends on the dial plan configured on Unified CM and the transformations provisioned on the translation pattern. The number is represented by the regular expression [+]?[0-9A-D*#]{1,48}. It can be in E.164 number format.
callednumber	The telephone number or the directory number of called party. It depends on the dial plan configured on Unified CM and the transformations provisioned on the translation pattern. The number is represented by the regular expression [+]?[0-9A-D*#]{1,48}. It can be in E.164 number format.
transformedcgpn	The transformed calling number. The result of the calling number transformation applied at the translation pattern.
transformedcdpn	The transformed called number. The result of the called number transformation applied at the translation pattern.
resource-id	The name of the resource to which the dynamic roles are mapped and for which the authorization decision is to be made.
action-id	The action a subject is permitted to perform on a resource.
triggerpointtype	Specifies where the external call control is triggered. For Unified CM 8.0(1), only TranslationPattern is supported.

Example

The following is an example call request scenario:

Scenario

User A with directory number 9725550101 calls user B by dialing 50102. Cisco Unified CM is configured to allow five digit dialing for internal calls. The dialed number, 50102, is transformed into +19725550102 on the translation pattern 5XXXX.

Unified CM sends an XACML call routing request to the web service when processing the dialed digits on the translation pattern. The call routing request is as follows:

POST /pdp/AuthorizationEndPoint HTTP/1.1

Host: 10.89.81.55:8080

Accept: */*

Content-type: text/xml; charset=ISO-8859-1

methodName: isRoleAccessAllowed

User-Agent: CiscoUCM-HttpClient/1.0

Connection:Keep-Alive

Content-Length: 1704

<?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:UCMPolicy</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>

<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>

XACML Request Schema

Figure 6-2 displays the schema diagram for the XACML call routing request.

Figure 6-1 XACML Schema

Schema text

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

<xs:schema targetNamespace="http://www.cisco.com/ExternalCallControl" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns="http://www.cisco.com/ExternalCallControl" elementFormDefault="qualified" 
attributeFormDefault="unqualified">

	<xs:element name="Request">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Subject"/>

				<xs:element ref="Resource"/>

				<xs:element ref="Action"/>

				<xs:element ref="Environment"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Action">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Attribute"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Attribute">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="AttributeValue"/>

			</xs:sequence>

			<xs:attribute name="Issuer" type="xs:NMTOKEN" use="optional"/>

			<xs:attribute name="DataType" type="xs:string" use="required"/>

			<xs:attribute name="AttributeId" type="xs:string" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="AttributeValue">

		<xs:complexType mixed="true"/>

	</xs:element>

	<xs:element name="Environment">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Attribute"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Resource">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Attribute"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Subject">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Attribute" maxOccurs="unbounded"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

</xs:schema>

Call Routing Response

This section provides information on the call routing response message. The following topics are covered:

•Description

•Format

•Parameter

•Example

•XACML Response Schema

•XACML Response Schema

•CIXML Schema

Description

On receiving a call routing request, the Policy Decision Point evaluates the request and generates an XACML response. The XACML response is returned to Unified CM as the body of a 200 OK message. The XACML response includes one of the following policy decsions:

•Permit—The call is allowed.

•Deny—The call is denied.

•Indeterminate—Unable to evaluate the policy for the request. Routes the call as specified in the Call Treatment on Failure configuration that is set on the external call control profile.

•Not Applicable—Cannot find policy applicable to the request. Routes the call as specified in the Call Treatment on Failure configuration that is set on the external call control profile.

The XACML may contain a call instruction XML (CIXML) obligation attribute that gives additional instructions for Unified CM to route the call or apply other special treatments. Example for obligations include directives to play a particular greeting before connecting a call and diverting a call to a different extension than the one that was dialed.

The CIXML obligation must be consistent with the policy decision. If it is not, then Unified CM obeys the policy decision and not the obligation. For example, an obligation set to divert the call is ignored if the policy decision is to deny that call.

The CIXML consists of a call routing directive and one or more optional sub-elements, with or without the attributes. The call routing directives are call routing action verbs and are defined in CIXML elements. A call routing directive is a mandatory element in an obligation. An obligation can have only one call routing directive.

Format

The following is the call routing response format:

HTTP/1.1 <Status-Code and Reason Phase>

Server: <product | comment>

Connection:Keep-Alive

Keep-Alive: timeout = <timeou value>  max  = <count>

Location: <new-URI>

Date: <date and time>

Content-Length: <msg body leng>

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

<Response>

<Result ResourceId="CISCO:UC:VoiceOrVideoCall">

<Decision>[decision value]</Decision>

<Status> <StatusCode Value="[status code]"/>

<StatusMessage>[status message]</StatusMessage>

<StatusDetail>[status details]</StatusDetail>

</Status>

<Obligations>

  [other obligations]

<Obligation FulfillOn="[fulfil on value]" 
ObligationId="urn:cisco:cepm:3.3:xacml:policy-attribute">

<AttributeAssignment AttributeId="[name of attribue]">

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

<cixml version="1.0>

[routing directive[sub-element]]

</cixml>

</AttributeValue>

</AttributeAssignment>

</Obligation>

</Obligations>

</Result>

</Response>

For CIXML format, see CIXML Format.

Parameter

This section provides description of various parameters in the request format.

Parameters	Description
HTTP Post Message
<Status-Code and Reason Phase>	One of the following: •200 OK—HTTP response received successfully •302 Found—Unified CM resends the request using the new request URI returned in the location header. •307 Temporary Redirect—Unified CM follows the new location specified in the location header and re-sends the same request. Unified CM does not support cache-control and expire-header in a 307 responses. •4xx or 5xx—Client or server errors encountered. Unified CM follows the Call Treatment on Failure configuration specified in the external call control profile to route call. Note For details on error handling, see Error Handling.
<product | comment>	The software used by the web service to handle the request.
Connection: Keep-Alive	This connection header indicates that the web service supports persistent connection and the same connection can be used by Unified CM to send the next request.
Keep-Alive: timeout = <timeout value> max = <count>	The timeout value indicates the duration the server will keep the connections live. Unified CM sends a Keep-Alive message before the timeout. The max parameter is ignored by Unified CM. If the persistent connection has not been timed-out, the Keep-Alive header may not be included in the response.
Date: <date and time>	The date and time at which the response is sent from the server.
Location: <new-URI>	The location header should be included in a 302, 303 or 307 response. Unified CM resends the request to the new location specified by new-URI.
Content-Type: text/xml; charset=<char coding>	Unified CM only accepts responses with the message body in text/xml format encoded in us-ascii or utf-8. For example: text/xml; charset=utf-8
Content-Length	The Content-Length field indicates the size of the entity-body, in decimal number of octets.
XACML Message
ResourceId	The name of the resource to which the dynamic roles are mapped and for which the authorization decision is to be made.
decision-value	This is the decision of the policy evaluation. It takes one of the following values: •Permit—The requested call is allowed. •Deny—The requested call is denied. •Indeterminate—The web service is unable to evaluate policies for the requested call. Reasons for such inability include missing attributes from request, network errors while retrieving policies, syntax errors in the decision requests or in the policies, and so on. •NotApplicable—The web service cannot find a policy applicable to the request
StatusCode	The status code represents the status of the policy decision result. Unified CM recognize the following status codes: •urn:oasis:names:tc:xacml:1.0:status:missing-attribute—some attributes are missing in the XACML request message. •urn:oasis:names:tc:xacml:1.0:status:ok—the request is successfully processed. •urn:oasis:names:tc:xacml:1.0:status:processing-error—some processing errors are encountered when evaluating policies for the request. •urn:oasis:names:tc:xacml:1.0:status:syntax-error—the request contains elements with syntax errors.
StatusMessage	The status message describing the status code. For example, "Request is successful".
StatusDetail	Additional message description for the status code.
FulfillOn	The fulfillon value is the effect for which this obligation must be fulfilled. It is either Permit or Deny.
other obligations	Unified CM ignores all obligations other than those described in this document.
name of attribute	The name of the obligation as defined in the policy.

For description of CIXML parameters, see CIXML Parameter.

CIXML Format

The following are the formats for the various call routing obligations (directives):

•Continue directives:

–Simple continue—Call routes normally to the current destination:
<cixml version="1.0">
<continue></continue>
</cixml>

–Continue with modified calling and called number:
<cixml version="1.0">
<continue>
<modify callingnumber=[number]callednumber=[number]/>
</continue>
</cixml>

–Continue with greeting:
<cixml version="1.0">
<continue>
<greeting identification=[id]/>
</continue>
</cixml>

•Divert directives:

–Divert to a different number or to voicemail:
<cixml version="1.0">
<divert>
<destination>[number]|voicemail</destination>
</divert>
</cixml>

–Divert to a number with modified calling/called numbers:
<cixml version="1.0">
<divert>
<destination>[number]</destination>
<modify callingnumber=[number] callednumber=[number]/>
</divert>
</cixml>

–Divert with call history reset:
<cixml version="1.0">
<divert>
<destination>[number]</destination>
<resetcallhistory> resetLastHop|resetAllHops </resetcallhistory>
</divert>
</cixml>

–Divert to a chaperone:
<cixml version="1.0">
<divert>
<destination>[number]</destination>
<reason> chaperone </reason>
</divert>
</cixml>

---

Note A chaperone is a special type of end-user who monitor calls between two parties.

---

•Reject directives:

–Simple reject—Unified CM rejects the call, and the caller hears fast busy tone:
<cixml version="1.0">
<reject> </reject>
</cixml>

–Reject with announcement:
<cixml version="1.0">
<reject>
<announce identification=[id] />
</reject>
</cixml>

–Reject with reason string:
<cixml version="1.0">
<reject>
<reason>[string]</reason>
</reject>
</cixml>

The web service can return an XACML call routing response with policy decision of Permit or Deny without including a CIXML as an obligation. In this case, Unified CM assumes a default CIXML element that corresponds to the policy decision. The following are the default CIXML elements:

•If policy decision is permit, then:

<cixml version="1.0"> <continue> </continue> </cixml>

•If policy decision is deny, then:

<cixml version="1.0"> <reject> </reject> </cixml>

CIXML Parameter

This section provides description of various parameters in CIXML.

Parameters	Description
<continue> </continue>	The continue routing directive instructs Unified CM to proceed with the call routing process. On receiving the continue directive, Unified CM proceeds to find the best match with the resulting digits of the translation pattern. The web service can overwrite the result of the translation pattern by including a sub-element called <modify>. The continue directive has the following sub-elements: •<greeting identification=ann-id/>—This sub-element specifies that an announcement will be played to the calling party before routing the call to the called party. The ann-id should match the one provisioned in the Unified CM administration Media Resources-Announcements page. •<modify callingNumber=number calledNumber=number/>—This sub-element specifies that the calling number or called number is modified with the number(s) provided. The web service overwrites the calling and called party transformation that is configured for the translation pattern. Unified CM changes the calling or called number(s) to the numbers that are provided in the directive. If the number is not included in the directive, the configuration for the route pattern or translation pattern applies.
<reject></reject>	The reject routing directive instructs Unified CM to reject the call. This is the only valid call routing directive if the policy decision is "Deny". The reject directive has the following sub-elements: •<announce identification=ann-id/>—this sub-element specifies that an announcement will be played to the calling party before the call is cleared. The ann-id should match the one provisioned in the Unified CM administration Media Resources-Announcements page. •<reason> reason-string </reason>—this sub-element specifies the reason for the call to be rejected. When a reason is included, Unified CM will log warning alarm. An email notification may be sent if it is configured through Unified CM RTMT tool.
<divert></divert>	The divert routing directive instructs Unified CM to redirect the call to another destination. The divert directive has the following sub-elements: •<destination> number | voicemail</destination>—This sub-element is mandatory for the divert directive. This sub-element specifies the destination to which the call is diverted. The destination can be a number routable in Unified CM, such as a directory number, a hunt pilot, or a route pattern. The destination can also be the string voicemail. If voicemail is specified as the destination, Unified CM will redirect the call to the voice mail box of the original called party. The call will be released if the original called party does not have a voicemail box. •<reason>chaperone</reason>—this sub-element specifies the reason for the call diversion. Chaperone indicates the destination is a chaperone line or a hunt list of chaperone lines. When this reason is included, the destination device will be enabled for chaperone features. For more information on chaperone feature, refer the Cisco Unified Communications Manager Features and Services Guide, release 8.0(1). •<modify callingNumber=number calledNumber=number/>—This sub-element specifies that the calling number or called number is modified with the number(s) provided. The web service overwrites the calling and called party transformation that is configured for the translation pattern. Unified CM changes the calling or called number(s) to the numbers that are provided in the directive. If the number is not included in the directive, the configuration for the route pattern or translation pattern applies. •<resetCallHistory> resetLastHop | resetAllHops </resetCallHistory>—this sub-element specifies the method to reset call history. The following options are available: –resetLastHop: erase the last called party number from the call history. –resetAllHops: erase all previous called party numbers from the call history.

Example

The following is an example for a call routing response.

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Connection: Keep-Alive

Keep-Alive: timeout = 1000  max = 100

Transfer-Encoding: chunked

Date: Mon, 08 Jun 2009 16:50:21 GMT

<?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">&lt;cixml 
<http://www.w3.org/2001/XMLSchema#string> 
ver="1.0"&gt;&lt;continue&gt;&lt;/continue&gt;&lt;/cixml&gt;

         </AttributeValue>

      </AttributeAssignment>

       </Obligation>

     </Obligations>

   </Result>

</Response>

XACML Response Schema

Figure 6-2 displays the schema diagram for the XACML call routing response.

Figure 6-2 XACML Response Schema

Schema Text

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

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

	<xs:element name="AttributeAssignment">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="AttributeValue"/>

			</xs:sequence>

			<xs:attribute name="AttributeId" type="xs:NMTOKEN" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="AttributeValue">

		<xs:complexType mixed="true">

			<xs:attribute name="DataType" type="xs:string" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="Decision">

		<xs:complexType mixed="true"/>

	</xs:element>

	<xs:element name="Obligation">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="AttributeAssignment" maxOccurs="unbounded"/>

			</xs:sequence>

			<xs:attribute name="FulfillOn" type="xs:NMTOKEN" use="required"/>

			<xs:attribute name="ObligationId" type="xs:NMTOKEN" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="Obligations">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Obligation" maxOccurs="unbounded"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Response">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Result"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="Result">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="Decision"/>

				<xs:element ref="Status"/>

				<xs:element ref="Obligations"/>

			</xs:sequence>

			<xs:attribute name="ResourceId" type="xs:NMTOKEN" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="Status">

		<xs:complexType>

			<xs:sequence>

				<xs:element ref="StatusCode"/>

				<xs:element ref="StatusMessage"/>

				<xs:element ref="StatusDetail"/>

			</xs:sequence>

		</xs:complexType>

	</xs:element>

	<xs:element name="StatusCode">

		<xs:complexType>

			<xs:attribute name="Value" type="xs:NMTOKEN" use="required"/>

		</xs:complexType>

	</xs:element>

	<xs:element name="StatusDetail">

		<xs:complexType mixed="true"/>

	</xs:element>

	<xs:element name="StatusMessage">

		<xs:complexType mixed="true"/>

	</xs:element>

</xs:schema>

CIXML Schema

Figure 6-3 displays the schema diagram for the CIXML.

Figure 6-3

Call Instruction XML Schema

Schema Text

<xs:schema targetNamespace="http://www.cisco.com/ExternalCallControl" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns="http://www.cisco.com/ExternalCallControl" elementFormDefault="qualified" 
attributeFormDefault="unqualified">

	<xs:element name="cixml">

		<xs:annotation>

			<xs:documentation>cixml</xs:documentation>

		</xs:annotation>

		<xs:complexType>

			<xs:choice>

				<xs:element name="continue">

					<xs:complexType>

						<xs:choice>

							<xs:element name="greeting" minOccurs="0">

								<xs:complexType>

									<xs:attribute name="identification" use="required">

										<xs:simpleType>

											<xs:restriction base="xs:string"/>

										</xs:simpleType>

									</xs:attribute>

								</xs:complexType>

							</xs:element>

							<xs:element name="modify" minOccurs="0">

								<xs:complexType>

									<xs:attribute name="callingNumber" type="phoneNumber" 
use="optional"/>

									<xs:attribute name="calledNumber" type="phoneNumber" 
use="optional"/>

								</xs:complexType>

							</xs:element>

						</xs:choice>

					</xs:complexType>

				</xs:element>

				<xs:element name="divert">

					<xs:complexType>

						<xs:choice>

							<xs:element name="destination" type="destinationNumber"/>

							<xs:element name="reason" type="reasonCode" minOccurs="0"/>

							<xs:element name="modify" minOccurs="0">

								<xs:complexType>

									<xs:attribute name="callingNumber" type="phoneNumber" 
use="optional"/>

									<xs:attribute name="calledNumber" type="phoneNumber" 
use="optional"/>

								</xs:complexType>

							</xs:element>

							<xs:element name="resetCallHistory" type="resetMode" 
minOccurs="0"/>

						</xs:choice>

					</xs:complexType>

				</xs:element>

				<xs:element name="reject">

					<xs:complexType>

						<xs:choice>

							<xs:element name="announce" minOccurs="0">

								<xs:complexType>

									<xs:attribute name="identifiaction" type="xs:string" 
use="optional"/>

								</xs:complexType>

							</xs:element>

							<xs:element name="reason" type="xs:string" minOccurs="0"/>

						</xs:choice>

					</xs:complexType>

				</xs:element>

				<xs:any namespace="##other" processContents="lax" minOccurs="0">

					<xs:annotation>

						<xs:documentation>Other mechanisms for describing routing 
rule</xs:documentation>

					</xs:annotation>

				</xs:any>

			</xs:choice>

			<xs:attribute name="version" type="xs:integer"/>

			<xs:attribute name="id" type="xs:token"/>

		</xs:complexType>

	</xs:element>

	<xs:simpleType name="phoneNumber">

		<xs:annotation>

			<xs:documentation>phone number digits ( +, 0-9A-D,*,#)</xs:documentation>

		</xs:annotation>

		<xs:restriction base="xs:string">

			<xs:pattern value="[+]?[0-9A-D*#]{1,48}"/>

		</xs:restriction>

	</xs:simpleType>

	<xs:simpleType name="reasonCode">

		<xs:annotation>

			<xs:documentation>reasonCode</xs:documentation>

		</xs:annotation>

		<xs:restriction base="xs:string">

			<xs:enumeration value="unknown"/>

			<xs:enumeration value="user-busy"/>

			<xs:enumeration value="no-answer"/>

			<xs:enumeration value="unavailable"/>

			<xs:enumeration value="unconditional"/>

			<xs:enumeration value="time-of-day"/>

			<xs:enumeration value="time-of-day"/>

			<xs:enumeration value="do-not-disturb"/>

			<xs:enumeration value="deflection"/>

			<xs:enumeration value="follow-me"/>

			<xs:enumeration value="out-of-service"/>

			<xs:enumeration value="away"/>

			<xs:enumeration value="blocked"/>

			<xs:enumeration value="chaprone"/>

		</xs:restriction>

	</xs:simpleType>

	<xs:simpleType name="resetMode">

		<xs:annotation>

			<xs:documentation>resetMode</xs:documentation>

		</xs:annotation>

		<xs:restriction base="xs:string">

			<xs:enumeration value="resetLastHop"/>

			<xs:enumeration value="resetAllHops"/>

		</xs:restriction>

	</xs:simpleType>

	<xs:simpleType name="destinationNumber">

		<xs:union>

			<xs:simpleType>

				<xs:restriction base="phoneNumber">

					<xs:minInclusive value="1"/>

					<xs:maxExclusive value="1"/>

				</xs:restriction>

			</xs:simpleType>

			<xs:simpleType>

				<xs:restriction base="xs:string">

					<xs:enumeration value="voiceMail"/>

				</xs:restriction>

			</xs:simpleType>

		</xs:union>

	</xs:simpleType>

</xs:schema>

Keep-Alive Message

Unified CM periodically sends Keep-Alive messages to the web service. This maintains persistent connection with the web service and determines if the PDP engine of the web service is in service.

Request Message

Unified CM sends the following HTTP HEAD request to the web service as the Keep-Alive message:

HEAD [Request-URI]HTTP/1.1

Connection: Keep-Alive

where the Request-URI is the URI provisioned in the external call control profile.

Example request message:

HEAD /pdp/AuthorizationEndPoint HTTP/1.1

Host: cepm1.cisco.com:8080

Accept: */*

Content-type: text/xml; charset=ISO-8859-1

methodName: isRoleAccessAllowed

User-Agent: CiscoUCM-HttpClient/1.0

Connection:Keep-Alive

Response Message

The web service sends the following response to the Keep-Alive message:

HTTP/1.1 200 OK

Connection: Keep-Alive

Keep-Alive: timeout = <TO> max = <count>

When a Keep-Alive header is included in a response message, Unified CM sends a subsequent keep-alive message within the specified timeout range. When a Keep-Alive header is not present in the response, Unified CM assumes there is no connection timeout at the web service. Unified CM ignores the max count value.

Example 200 OK response message:

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Connection: Keep-Alive

Keep-Alive: timeout = 20000  max = 100

Content-Length: 0

Date: Mon, 08 Jun 2009 16:50:12 GMT

Message Timer

The Unified CM administrator can set a call routing request timer. The call routing request timer is the maximum duration that Unified CM waits for a call routing or Keep-Alive response from the web service after sending the call routing or Keep-Alive request.

The call routing request timer is provisioned in the external call control profile. The timer can be set in the range of 1000 to 5000 milliseconds.

If the call routing request timer field in the external call control profile is left blank, Unified CM takes the cluster-wide value specified by the External Call Control Call Routing Request Timer service parameter. The value for the service parameter can be set to a number in the range of 1000 to 5000 milliseconds. The default value is 2000 milliseconds.

Connections

This section provides information on the various connection scenarios between Unified CM and the web service. The following topics are included:

•Multiple Connections

•Redundant Web Services

•Persistent Connection and Keep-Alive

•Redirection

---

Note HTTP Proxy: Cisco Unified CM does not support proxy for web services.

---

Multiple Connections

Unified CM establishes multiple connections to the web service to support multiple parallel requests. The number of connections may be increased at run time to support high call rates. The initial connection count and the maximum connection count to PDP can be configured in Unified CM via the service parameters.

For more information refer to Unified CM administration guides at:

http://www.cisco.com/en/US/products/sw/voicesw/ps556/prod_maintenance_guides_list.html

Redundant Web Services

Unified CM allows two web services to be provisioned in an external call control profile. A primary web service and a secondary web service. The two web services can be provisioned to operate in the following two modes:

•Active-standby mode—This is the default mode. All call routing requests will be sent to the active web service. The primary web service is the active web service when it is in service. The secondary web service becomes active when the primary web service goes out of service.

•Load balance mode—Call routing requests will be sent to primary and secondary web service alternatively with the round-robin algorithm. The load balance mode is enabled on the external call control profile.

Persistent Connection and Keep-Alive

Unified CM maintains persistent connections with the web service by sending Keep-Alive messages to the web service before the connection timeout timer expires. Using the HTTP HEAD method the Keep-Alive messages are sent to the same URI as the call routing request message.

Unified CM sends an initial Keep-Alive message when it establishes a connection to the web service. The subsequent Keep-Alive is sent when the connection timeout timer expires. The Keep-Alive timer is reset each time a response to a Keep-Alive or a call routing request is received.

The minimum connection timeout value is 1000 milliseconds and the maximum is 20000 milliseconds.

The connection timeout value for Unified CM cannot be configured. The web service can include a Keep-Alive header in the response message to change the connection timeout value within the 1000 to 20000 milliseconds range. When a Keep-Alive header is included, Unified CM resets the Keep-Alive timer to 100 milliseconds less than the timeout value returned. If the Keep-Alive header is not present in the response, Unified CM assumes there is no connection timeout at the web server and the Keep-Alive timeout value is then set to 20000 milliseconds.

Redirection

Unified CM supports the following redirections from web services in response to call routing requests:

•302 Found—The requested call routing policy resides temporarily under a different URI. Unified CM resends the request using the new URI returned in the location header.

•307 Temporary Redirect—The requested call routing policy resides temporarily under a different URI. Unified CM resends the request using the new URI returned in the location header. Unified CM does not support expire-header in the 307 response.

A new connection is created if the new location is on a different server and no existing connection can be reused. The maximum number of redirections Unified CM follows for a request is two. Unified CM does not cache redirected locations.

Error Handling

This section provides information on the various error handling scenarios. The following topics are included:

•Web Service Connection Failure

•Unified CM Timeout Awaiting Response from Web Service

•Error Response from Web Service

•Web Service Parse Request Error

•Unified CM Parse Response Error

•Web Service Evaluation Request Error

Web Service Connection Failure

A web service connection error occurs when Unified CM fails to establish a connection with the web service. The following reasons may cause this failure:

•The web service is not in service.

•Unified CM fails to authenticate the web service.

•The web service fails to authenticate Unified CM.

•Slow responses from the web service that cause Unified CM to time out for two consecutive call routing or Keep-Alive requests.

Unified CM handles this failure with the following actions:

•Issues a ConnectionFailureToPDP error alarm.

•Switches to standby web service for call routing requests, if two URIs are provisioned in the external call control profile to operate in active-standby mode.

•Starts sending all call routing requests to the other web service that Unified CM still has good connections with, if two URIs are provisioned in the external call control profile to operate in load balance mode.

•Retries to establish connections to the web service.

•If no web service is available for call routing request, then follows the Call Treatment on Failure configuration as set on the external call control profile to route the call.

Unified CM Timeout Awaiting Response from Web Service

The routing request timer is the maximum time in milliseconds that Unified CM waits for the response from the web service for a call routing request. The routing request timer can be provisioned in an external call control profile in the range of 1000 to 5000 milliseconds. If the timer is not set in the external call control profile, the cluster wide service parameter "External Call Control Routing Request Timer" takes effect. The default value for the timer is 2000 milliseconds.

Unified CM takes the following actions when the routing request timer expires before receiving the call routing response:

•Issues an AwaitingResponseFromPDPTimeout error alarm.

•Routes the call following the Call Treatment on Failure configuration set on the external call control profile.

Error Response from Web Service

The web service can return a 4XX or 5XX error response to Unified CM to indicate invalid call routing requests or internal errors when processing a request from Unified CM.

Unified CM takes the following actions for a 4XX or 5XX error response:

•Issues a FailureResponseFromPDP error alarm.

•Routes the call following the Call Treatment on Failure configuration on the external call control profile.

Web Service Parse Request Error

When there are errors either in the request from the Unified CM or in processing the request, the web service states these errors in the XACML response. The following status codes may be returned:

•Missing-attribute—Some mandatory attributes not found.

•Processing-error—Errors encountered when evaluating policies for the request.

•Syntax-error—The request contains elements with syntax errors.

Unified CM takes the following actions when the response from the web service contains the status indicating request errors:

•Issues an ErrorParsingResponseFromPDP warning alarm.

•Routes the call by following the call routing directive in the response.

Unified CM Parse Response Error

This error occurs when Unified CM fails to parse the response from the web service. The following errors may cause this failure:

•XACML missing mandatory attributes or error in parsing XACML mandatory attributes

•CIXML missing mandatory attributes or error in parsing CIXML mandatory attributes

•Error in parsing the CIXML optional attributes

•XACML syntax error

•CIXML syntax error

Unified CM takes the following actions when it fails parsing the response:

•XACML missing mandatory attributes, or error in parsing XACML mandatory attributes:

–Issues an ErrorParsingDirectiveFromPDP error alarm.

–Routes the call following the "Call Treatment on Failure" configuration on the external call control profile.

•XACML missing mandatory attributes, or error in parsing CIXML mandatory attributes:

–Issues an ErrorParsingDirectiveFromPDP error alarm.

–Routes the call by following the Call Treatment on Failure configuration set on the external call control profile.

•CIXML missing optional attributes, or XACML or CIXML syntax errors

–Issues an ErrorParsingResponseFromPDP warning alarm.

–Routes the call by following the call routing directive in the response.

Web Service Evaluation Request Error

The web service may return the following decision in XACML in the call routing response:

•Indeterminate—The web service is unable to evaluate the policy for the request

•NotApplicable—The web service cannot find a policy applicable to the request.

Unified CM takes the following actions when one of these policy decisions is returned:

•Issues an ErrorParsingDirectiveFromPDP error alarm.

•Routes the call following the Call Treatment on Failure configuration on the external call control profile.

Security

This section provides information on the security and authentication setup between Unified CM and web service. The following topics are included:

•Authentication

•Certificate and Key

•Transport Layer Security Version

•Cipher Specification

Authentication

When a secure connection is desired, a HTTPS URI must be provisioned in the Unified CM. Unified CM does not support upgrade of an HTTP connection to HTTPS.

When HTTPS is provisioned, Unified CM uses mutual authentication with a self-signed certificate or a CA issued certificate to communicate to the web service. Unified CM conducts the following verifications when authenticating the server:

•Verification of host—Checks if the certificate subject name matches the host name of the server.

•Verification of peer—Checks if 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.

Certificate and Key

Generation and Exchange

If mutual authentication using self-signed certificates is required, the Unified CM administrator should generate the required certificate for the web service to import. The administrator of the web service should also generate the certificate for Unified CM to import.

Certificate Format

All certificates must be in Privacy Enhanced Mail (PEM) format or convertible to PEM format.

Transport Layer Security Version

Unified CM supports Transport Layer Security (TLS) version1 for HTTPs connections.

Cipher Specification

In mutual authentication both Unified CM and the web service send the change cipher specification message to notify the receiving party that subsequent records are protected under the just-negotiated CipherSpec and keys.

The following Cipher Spec is supported in Unified CM for external call control:

Cipher Spec: TLS_RSA_WITH_AES_256_CBC_SHA (0x000035)