Cisco Unity Connection Provisioning Interface (CUPI) API-- Routing Rules
About Routing Rules and Routing Rule Conditions
This page contains information on how to use the API to create, list, update, and delete Routing Rules and their support objects, Routing Rule Conditions. Please note that the syntax for Routing Rules and Routing Rule Conditions is relatively complicated. Retrieving existing rules and conditions is not too difficult, but creating and modifying them via CUPI should only be done with great care. If the Routing Rules or Routing Rule Conditions are misconfigured, they might not display correctly in Cisco Unity Connection Administration (CUCA), and calls into Cisco Unity Connection might not get answered or might route to the wrong Conversation. Routing Rules and Routing Rule Conditions both include some fields that are enumeration types (meaning numeric constants), which makes understanding these fields more complicated. Some examples can be found near the end of this document.
Each Routing Rule has a Type (Direct, Forwarded, or Both) and a RuleIndex (starting at index 0 and increasing by 1 for each additional rule). When Cisco Unity Connection answers a call of the specified type, it attempts to match the Routing Rules in order starting at RuleIndex 0 and continuing with each successive index until a rule matches. The factory default rules (which are built in and cannot be deleted) should match any call that doesn't match a custom rule. An individual Routing Rule also specifies the destination for the call in the event the rule matches, such as a user, call handler, interview handler, directory handler, or conversation.
In addition, each Routing Rule can have 0 or more Routing Rule Conditions, and a call must match all of these conditions before it is considered a match. If a Routing Rule does not have any Routing Rule Conditions, then all calls match it. The default Routing Rule, which transfers to the Opening Greeting, does not have any Routing Rule Conditions and is usually at the highest RuleIndex, so if a call does not match any other Routing Rules it ends up at the Opening Greeting. An individual Routing Rule Condition can specify any of the following conditions: call information such as Calling Number, Called Number, or Redirecting Number (Forwarded Routing Rules only); port or phone system; or schedule.
Routing Rules
Listing and Viewing
The following is an example of a GET that lists all Routing Rules:
|
The following is the response from the above GET request:
|
To retrieve a sorted list of all Routing Rules, add the following query parameter to the GET: sort=(column[asc | desc])
For example, to retrieve a list of all Routing Rules sorted by RuleIndex in ascending order:
|
To retrieve a specific Routing Rule by its ObjectId:
|
JSON Example
To list all the routing rules, use the following command:
Request URI:
|
The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
|
Response Code: 200 |
Searching
To retrieve a list of Routing Rules that meet a specified search criteria, add the following query parameter to a GET: query=(column [is | startswith] value)
For example, to find the Routing Rule at RuleIndex 1:
|
Creating
The only required field for creating a Routing Rule is DisplayName. All other Routing Rule fields are optional. A Routing Rule that is created with default fields has Type=1 (Direct) and routes to the System Directory Handler. Some examples of other types of Routing Rules can be found at the end of this document.
Note that RuleIndex cannot be specified when creating a new Routing Rule; all new Routing Rules are created at RuleIndex 0, and the RuleIndex of all other Routing Rules is incremented by 1 when the new Routing Rule is created.
The following is an example of a POST that creates a Routing Rule with the name "My Routing Rule" of Type 1 (Direct):
|
|
The following is the response from the above POST request:
|
JSON Example
To create new routing rule, do the following:
Request URI:
|
Request Body:
|
The following is the response from the above *POST* request and the actual response will depend upon the information given by you:
Response Code: 201 |
Updating
The following is an example of a PUT request that modifies the DisplayName of an existing Routing Rule:
|
|
The following is the response from the above PUT request:
|
Note that the RuleIndex of a Routing Rule cannot be modified with this method. Rather, the ordering of the entire Routing Rules collection can be modified, as described later in this document.
JSON Example
To update display name of routing rule, do the following:
|
Request Body
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
|
Deleting
The following is an example of a DELETE request that deletes a Routing Rule:
|
The following is the response from the above DELETE request:
|
JSON Example
|
|
Changing Routing Rule Indices
As noted in previous sections, a Routing Rule's RuleIndex field cannot be modified when creating or updating a Routing Rule. Instead, you can change a Routing Rule's RuleIndex only in the context of ordering all of the Routing Rules in a collection.
The following is an example of a PUT request that modifies the RuleIndices of a collection of Routing Rules:
|
|
The following is a response from the above PUT request:
|
After this PUT request is processed, the Routing Rule with ObjectId aabbccdd-1111-2222-3333-1234567890ab would have RuleIndex 0, the Routing Rule with ObjectId 12345678-abcd-abcd-abcd-123412341234 would have RuleIndex 1, and the Routing Rule with ObjectId 99990000-1234-1234-1234-abcdef012345 would have RuleIndex 2.
JSON Example
To update the order of routing rule, do the following:
Request URI:
|
Request Body:
|
The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:
Response Code: 204 |
Routing Rule Conditions
Each Routing Rule can have a collection of Routing Rule Conditions. The Routing Rule Conditions that belong to a specified Routing Rule can be accessed at /vmrest/routingrules/<routingruleobjectid>/routingruleconditions. When first created, a Routing Rule does not have any Routing Rule Conditions, which means that every call matches it and is routed to its destination.
Listing and Viewing
The following is an example of a GET that lists all Routing Rule Conditions that belong to a specified Routing Rule:
|
The following is the response from the above GET request:
|
To retrieve a specific Routing Rule Condition by its ObjectId:
|
Creating
The required fields for creating a Routing Rule Condition are Parameter, Operator, and OperandValue. All other Routing Rule Condition fields are optional.
The following is an example of a POST that creates a Routing Rule Condition with Parameter=2 (Dialed Number), Operator=2 (Equals), and OperandValue=8675309:
|
The following is the response from the above POST request:
|
Updating
The following is an example of a PUT request that modifies the OperandValue of an existing Routing Rule Condition to 5551212:
|
|
The following is the response from the above PUT request:
|
Deleting
The following is an example of a DELETE request that deletes a Routing Rule Condition:
DELETE https://<connection-server>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/
The following is the response from the above DELETE request:
204
No Content
Routing Rule Examples
It can be relatively complicated to specify the destination for a Routing Rule. The fields RouteAction, RouteTargetConversation, and RouteTargetHandlerObjectId are used together to specify the destination. The fields RouteTargetHandler, DisplayName and RouteTargetHandlerObjectType should not be specified when creating or updating a Routing Rule; rather they are set automatically based on the other specified values.
The following sections give some examples of how to specify different types of route destinations by using these fields. Note that all other fields in the Routing Rule objects have been omitted for brevity.
This list of examples covers all of the Routing Rules that can be configured by using Cisco Unity Connection Administration (CUCA). Creating a different type of Routing Rule by using CUPI is likely to yield a Routing Rule that will not display properly in CUCA, and it also may not operate as expected when Connection tries to route a call.
Transfer to a User or a Call Handler
To transfer a caller to a user or a call handler, do the following PUT request:
|
The Action field of 2 denotes that this key should transfer the caller to another conversation. This is used to transfer callers to other objects, or to send callers to other conversations such as the system transfer conversation.
The TargetConversation should be set to PHTransfer if you want to transfer to the call handler in question. If you want to have the call go directly the call handler greeting, set it to PHGreeting instead.
The TargetHandlerObjectId is the object ID of the call handler that you want the key to transfer the caller to.
Go to a User or Call Handler's Greeting
The following Routing Rule will go to (Action=2) the call handler aab5eab2-38f7-4231-a3be-bf2a8fde820c (which happens to be a user's primary call handler) by using the PHGreeting Conversation (meaning it will go directly to the call handler's greeting, bypassing transfer). If you want to go to a different call handler's greeting, set RouteTargetCallHandlerObjectId to it.
|
Go to an Interview Handler
|
The TargetConversation should be set to PHInterview and the TargetHandlerObjectId is the object ID of the interview handler that you want to the caller input key to go to.
Go to a Directory Handler
|
The TargetConversation should be set to AD and the TargetHandlerObjectId is the object ID of the directory handler you want to the caller input key to go to.
Go to a Specific Conversation
The following Routing Rule will go to (Action=2) the BroadcastMessageAdministrator Conversation. Note that RouteTargetHandlerObjectId is ignored if the RouteTargetConversation is anything other than PHTransfer, PHGreeting, PHInterview, or AD.
|
Routing Rule Condition Examples
Routing Rule Conditions are not as complicated as Routing Rules, but care should still be taken when creating or modifying them. The fields Parameter, Operator, and OperandValue are used to specify the conditions.
This list of examples covers all of the Routing Rule Conditions that can be configured by using Cisco Unity Connection Administration (CUCA). Creating a different type of Routing Rule Condition by using CUPI is likely to yield a Routing Rule Condition that will not display properly in CUCA, and it also may not operate as expected when Connection tries to match a call.
Condition Based on a Phone Number
The following Routing Rule Condition specifies a match of Calling Number (Parameter=1) Equals (Operator=2) 1234 (OperandValue). A Routing Rule Condition to match on Called Number would use Parameter=2, and a Routing Rule Condition to match on Forwarded Number (valid only on Forwarded Routing Rules) would use Parameter=3. Other Operators are allowed when matching Phone Numbers, such as In and Less Than. With the Equals Operator, the OperandValue can include the wildcards * and ?, and with the In Operator, the OperandValue can include comma-separated ranges of numbers like 2000-2199,3001-3199, 4001.
|
Condition Based on a Port
The following Routing Rule Condition specifies a match of a Port (Parameter=5) Equals (Operator=2) ObjectId b79765f1-e14f-47b6-b8e1-00479909f710 (OperandValue). Creating a Routing Rule Condition to match based on a Port has the side effect of setting MediaPortObjectId to the same value as OperandValue. When matching Ports, only the Equals Operator is allowed, and the OperandValue must be a single ObjectId.
|
Condition Based on a Phone System
The following Routing Rule Condition specifies a match of a Phone System (Parameter=9) Equals (Operator=2) ObjectId 2eb79e66-1e53-415c-9222-36665e0e76ae (OperandValue). Creating a Routing Rule Condition to match based on a Port has the side effect of setting MediaSwitchObjectId to the same value as OperandValue. When matching Phone Systems, only the Equals Operator is allowed, and the OperandValue must be a single ObjectId.
|
Condition Based on a Schedule Set
The following Routing Rule Condition specifies a match of a Schedule Set (Parameter=7) Equals (Operator=2) ObjectId 4cc6c1be-e1ba-4fcf-be81-95bce20acbec (OperandValue). Note that you must specify the ObjectId of a Schedule Set, not a Schedule. When matching Schedule Sets, only the Equals Operator is allowed, and the OperandValue must be a single ObjectId.
|
Enumeration Type
Routing Rule RouteAction
The RouteAction field in a Routing Rule is read/write, and can take the following values. It defaults to 2, and should be set to that value in most cases (it is set to 2 in all of the examples above).
Value |
Description |
---|---|
0 |
Ignore (take no action) |
1 |
Hang up call |
2 |
Go to specified object |
3 |
Error (play error message) |
4 |
Take a message |
5 |
Skip greeting |
6 |
Restart greeting |
7 |
Transfer to Alternate Contact Number |
8 |
Route from Next Call Routing Rule |
Routing Rule RouteTargetHandlerObjectType
The RouteTargetHandlerObjectType field in a Routing Rule is read-only and can take various values. The relevant values are listed here. As noted previously, it will automatically be set to the type of object specified by the RouteTargetHandlerObjectId field.
Value |
Description |
---|---|
3 |
Call Handler |
5 |
Interview Handler |
6 |
Directory Handler |
Routing Rule State
The State field in a Routing Rule is read/write, and can take the following values. It defaults to 0.
Value |
Description |
---|---|
0 |
Active |
1 |
Inactive |
2 |
Invalid |
Routing Rule Type
The Type field in a Routing Rule is read/write, and can take the following values. It defaults to 1.
Value |
Description |
---|---|
1 |
Direct |
2 |
Forwarded |
3 |
Both (normally only used by Opening Greeting) |
Routing Rule Condition Operator
The Operator field in a Routing Rule Condition is read/write, and can take the following values. It does not have a default value.
Value |
Description |
---|---|
1 |
In |
2 |
Equals |
3 |
Greater than |
4 |
Less than |
5 |
Less than or equal to |
6 |
Greater than or equal to |
7 |
Schedule Set |
9 |
Phone System |
Routing Rule Condition Parameter
The Parameter field in a Routing Rule Condition is read/write, and can take the following values. It does not have a default value. Several values are legacy and should not be used.
Value |
Description |
---|---|
1 |
Calling Number |
2 |
Dialed Number |
3 |
Forwarding Number |
5 |
PortID |
Routing Rule RouteTargetConversation
The RouteTargetConversation field in a Routing Rule is read/write, and can take the following values. It defaults to AD. Although it is not an enumeration type, only certain string values are valid Conversation names. For some Conversations, it is required to specify a Route_TargetHandlerObjectId as well. Examples of how to use several of these Conversations can be found earlier in this document.
Value |
Description |
TargetHandler |
---|---|---|
AD |
Directory Conversation |
Directory Handler |
PHTransfer |
Transfer to User or Call Handler |
User or Call Handler |
PHGreeting |
Play Greeting of User or Call Handler |
User or Call Handler |
PHInterview |
Interview Conversation |
Interview Handler |
AttemptForward |
Forwards the call to the User's Greeting if the Forwarding Number matches a User |
n/a |
AttemptSignIn |
Sends the call to a User's Sign-in if the Calling Number matches a User |
n/a |
BroadcastMessageAdministrator |
Sends the call to a Conversation for Sending Broadcast Messages |
n/a |
SystemTransfer |
Sends the call to a Conversation allowing the caller to transfer to a number they specify (assuming the restriction table allows it) |
n/a |
CheckedOutGuest |
Sends the call to a Conversation for checked-out hotel guests |
n/a |
GreetingsAdministrator |
Sends the call to a Conversation allowing changing greetings by phone |
n/a |
ReverseTrapConv |
Connects to Visual Voicemail |
n/a |
SubSignIn |
Sends the call to the Sign-In Conversation, which prompts the user to enter their ID |
n/a |
ConvUtilsLiveRecord |
Sends the call to the Live-Record pilot number configured on CUCM |
n/a |
SubSysTransfer |
Similar to SystemTransfer, but requires users sign-in first (so unknown callers cannot use it) |
n/a |