DocWiki - User contributions [en]

Cisco Unity Connection APIs

2010-12-15T17:10:16Z

Juliew:

Cisco Unity Connection is a feature-rich voice messaging platform based on the same Linux operating system as Cisco Unified Communications Manager. Connection users can access voice messages by using email, web clients, mobile devices, instant messaging, and desktop clients such as Cisco Unified Personal Communicator; and can view, search, sort, and play messages on a Cisco Unified IP Phone display. Connection also provides comprehensive automated-attendant functions, including intelligent call routing and easily customizable call screen and message notification options. For more information see [http://www.cisco.com/en/US/products/ps6509/tsd_products_support_series_home.html Cisco Unity Connection documentation on Cisco.com].

Cisco Unity Connection includes several Representational State Transfer (REST) application programming interfaces (APIs) that provide provisioning, messaging, and telephony access to Connection. These APIs provide the ability to integrate Connection features into existing enterprise-wide provisioning management systems and messaging clients.
The APIs are REST interfaces that standardize operations such as add, delete, view, and modify.

== Available Connection APIs ==

'''CUPI''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API]]

The Cisco Unity Connection Provisioning Interface (CUPI) API provides access to the most commonly provisioned data on Cisco Unity Connection systems—users, contacts, distribution lists, and call handlers.

'''CUPI for End Users''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API_--_For_End_Users]]

The Cisco Unity Connection Provisioning Interface (CUPI) API includes access for individual users when authenticating against user credentials. This allows for custom end-user applications.

'''CUMI''': [[Cisco_Unity_Connection_Messaging_Interface_(CUMI)_API]]

The Cisco Unity Connection Messaging Interface (CUMI) API provides access to user messages.

'''CUTI''': [[Cisco_Unity_Connection_Telephony_Interface_(CUTI)_API]]

The Cisco Unity Connection Telephony Interface (CUTI) API provides the ability to play and record audio content over the phone.

'''CUNI''': [[Cisco_Unity_Connection_Notification_Interface_(CUNI)_API]]

The Cisco Unity Connection Notification Interface (CUNI) API provides notification for one or more users. CUNI is designed for use in server-to-server applications where receiving notifications for many users over a single connection is required.

[[Category: Unity Connection APIs]]

Cisco Unity Connection APIs

2010-12-15T02:07:12Z

Juliew:

Cisco Unity Connection is a feature-rich voice messaging platform based on the same Linux operating system as Cisco Unified Communications Manager. Connection users can access voice messages by using email, web clients, mobile devices, instant messaging, and desktop clients such as Cisco Unified Personal Communicator; and can view, search, sort, and play messages on a Cisco Unified IP Phone display. Connection also provides comprehensive automated-attendant functions, including intelligent call routing and easily customizable call screen and message notification options. For more information see [http://www.cisco.com/en/US/products/ps6509/tsd_products_support_series_home.html Cisco Unity Connection documentation on Cisco.com].

Cisco Unity Connection includes several Representational State Transfer (REST) application programming interfaces (APIs) that provide provisioning, messaging, and telephony access to Connection. These APIs provide the ability to integrate Connection features into existing enterprise-wide provisioning management systems and messaging clients.
The APIs are REST interfaces that standardize operations such as add, delete, view, and modify.

== Available Connection APIs ==

'''CUPI''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API]]

The Cisco Unity Connection Provisioning Interface (CUPI) API provides access to the most commonly provisioned data on Cisco Unity Connection systems—users, contacts, distribution lists, and call handlers.

'''CUPI for End Users''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API_--_For_End_Users]]

The Cisco Unity Connection Provisioning Interface (CUPI) API includes access for individual users when authenticating against user credentials. This allows for custom end-user applications.

'''CUMI''': [[Cisco_Unity_Connection_Messaging_Interface_(CUMI)_API]]

Cisco Unity Connection Messaging Interface (CUMI) API provides access to user messages.

'''CUTI''': [[Cisco_Unity_Connection_Telephony_Interface_(CUTI)_API]]

Cisco Unity Connection Telephony Interface (CUTI) API provides the ability to play and record audio content over the phone.

'''CUNI''': [[Cisco_Unity_Connection_Notification_Interface_(CUNI)_API]]

Cisco Unity Connection Notification Interface (CUNI) API provides notification for one or more users. CUNI is designed for use in server-to-server applications where receiving notifications for many users over a single connection is required.

[[Category: Unity Connection APIs]]

Cisco Unity Connection Notification Interface (CUNI) API -- CUNI FAQs

2010-12-14T19:28:20Z

Juliew:

Cisco Unity Connection Notification Interface (CUNI) API -- CUNI FAQs

2010-12-14T19:27:43Z

Juliew:

Cisco Unity Connection Notification Interface (CUNI) API -- CUNI FAQs

2010-12-14T19:27:05Z

Juliew:

Cisco Unity Connection Notification Interface (CUNI) API -- CUNI FAQs

2010-12-14T19:23:35Z

Juliew: New page: * Where can I get the WSDL http://<connection-server>/messageeventservice/services/MessageEventService?wsdl Note: the WSDL is the same across versions *except* that for 8.0 there wa...

* Where can I get the WSDL

http://<connection-server>/messageeventservice/services/MessageEventService?wsdl

Note: the WSDL is the same across versions *except* that for 8.0 there was a "keepAlive" parameter added to the "subscribe" method.

* What happens to subscriptions if the Unity Connection server is restarted?

Subscriptions are stored in the database. When Unity Connection is restarted, the Notifier reads the existing subscriptions and begins sending out notifications.

* Are there any unsupported methods?

Yes - subscribeForAllResources currently not supported, so users must be listed explicitly. Also there's not currently support for SSL connections for callbacks.

* Can multiple subscriptions use the same callback URL?

Not exactly - if Unity Connection sees a repeat subscription for a callback URL it will delete the previous subscription as a safeguard against ending up with unintentional subscriptions.

Cisco Unity Connection Notification Interface (CUNI) API

2010-12-14T19:23:21Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUNI Guide Contents'''
|-
|[[Cisco Unity Connection Notification Interface (CUNI) API|API Overview ]] [[Cisco Unity Connection Notification Interface (CUNI) API -- CUNI Event Schema|CUNI Event Schema]] [[Cisco Unity Connection Notification Interface (CUNI) API -- Subscribing to and Processing Notification Events|Subscribing to and Processing Notification Events]] [[Cisco Unity Connection Notification Interface (CUNI) API -- CUNI FAQs|CUNI FAQs]]
|}

__TOC__

== Introduction ==

The Cisco Unity Connection Notification Interface (CUNI) API is a web service interface for managing subscriptions to events from Cisco Unity Connection systems. It provides a way to get asynchronous notifications when voice mail messages are received, deleted, or changed. CUNI can be used to integrate Connection into an existing enterprise-wide portal.

CUNI is designed to provide a simple, stable method of accessing the notification functionality on Connection systems through a standards based interface using XML and HTTPS.

Through CUNI, you can do the following:

* Subscribe for message events
* Subscribe for one or many users on a single channel

Note that CUNI is intended for use in server-to-server applications where receiving notifications for many users over a single connection is required. As such, it is designed to handle a small number of clients that are each subscribing for notifications on a large set of subscribers. It also requires Administrative credentials, making it inappropriate for browser applications to use directly.

CUNI is composed of two parts: a SOAP interface for subscribing, and an asynchronous piece (the Notifier) that delivers events as XML over HTTP.

== Technical Details ==

* CUNI is standards-based: it implements a standard SOAP-based interface for managing subscriptions. Message events are sent as standard XML over HTTP.
* CUNI is easy to use: as a web-based interface, CUNI is independent of operating systems and programming languages, and does not require any client libraries to use.

== Getting Started with CUNI ==

In order to begin developing with CUNI, you need to obtain the following:

=== Hardware ===

* Cisco Media Convergence Server (MCS) for Cisco Unity Connection version 8.0 or later
* For detailed hardware-specification information, see the [http://www.cisco.com/en/US/docs/voice_ip_comm/connection/8x/supported_platforms/8xcucspl.html Cisco Unity Connection 8.x Supported Platforms List]

=== Software ===

* Cisco Unity Connection Software Ordering
* Not for Resale Kits (Must for eligible to purchase)
* Select Unified Communications System Release Kit

Discounts for some of the above hardware and software may be available for participants in the Cisco Technology Developer Program.

We recommend that all developers have an up-to-date Cisco Developer Services support agreement. This provides the developer with access to professional support and assistance for application development.

== Other CUNI Resources ==

Additional information about CUNI is also available on the Cisco Developer Network ([http://developer.cisco.com/web/cuni/home link to CDN]). Note, however, that the documentation here on the DocWiki is the most up-to-date documentation available for CUNI.

To participate in the CUNI forum, see the [http://developer.cisco.com/web/cuni/forums CUNI forum on CDN].

== Troubleshooting ==

See the following for information on troubleshooting all Connection APIs:

[[Cisco Unity Connection APIs -- Troubleshooting |Troubleshooting (applies to all Connection APIs)]]

[[Category:Cisco Unity Connection Notification Interface (CUNI) API]]

Cisco Unity Connection Provisioning Interface (CUPI) API -- Schedules

2010-12-14T17:47:36Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUPI Guide Contents'''
|-
|[[Cisco Unity Connection Provisioning Interface (CUPI) API|API Overview ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- Index of All CUPI Documentation|Index of All CUPI Documentation ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- Schedule Example|Schedule Example ]]
|}

__TOC__

== Overview of Cisco Unity Connection Schedule Objects ==

Schedules in Cisco Unity Connection are somewhat complicated, since they are composed of several different types of objects. Before presenting the API for accessing schedules, it may be useful to review what these objects are and how they are used.

=== ScheduleSet Objects ===

ScheduleSet objects are the top-level objects. They are comprised of one or more Schedules, each of which is marked as included or excluded in the ScheduleSet.

=== Schedule Objects ===

Schedule objects are composed of one or more ScheduleDetail objects.

=== ScheduleDetail Objects ===

ScheduleDetail objects are the atomic schedule building blocks which comprise Schedule objects. They can be specified with Start and End Dates, Start and End Times of the day, and active Days of the Week. ScheduleDetails have a link to the Schedule objects that they are part of, and said Schedule object in a sense owns the ScheduleDetail object.

=== ScheduleSetMemberMap Objects ===

ScheduleSetMemberMap objects provide the linkage between a ScheduleSet and a Schedule that is included or excluded from it (via a boolean called Exclude). There will be one ScheduleSetMemberMap object for each Schedule that is included in or excluded from a ScheduleSet.

A ScheduleSetMemberMap abstracts the linkage between a ScheduleSet and a Schedule since neither object has an explicit linkage or ownership relationship of the other. One reason for this is that several ScheduleSets might reference the same Schedule (a Holiday Schedule for example). This differs from the relationship between a Schedule and a ScheduleDetail, since a ScheduleDetail has an explicit link to a Schedule, the Schedule essentially owns the ScheduleDetail, and no other Schedule may use another Schedule's ScheduleDetail object.

=== Schedule Example ===

For example, let's model a weekday schedule with the lunch hour blocked out as unavailable every work day, and with various holidays blocked out as well. Using the objects discussed previously, this schedule might be composed like so:

* First, we create a top-level ScheduleSet called WeekdaySet. WeekdaySet includes the WeekdaySchedule and excludes the HolidaySchedule (2 Schedule objects).
* After we create these 2 Schedule objects, we create 2 ScheduleSetMemberMap objects for WeekdaySet - one to include WeekdaySchedule and one to exclude HolidaySchedule.
* Then, we create 2 ScheduleDetail objects for WeekdaySchedule - one active from 8AM to 12PM Mon-Fri, and the other active from 1PM to 5PM Mon-Fri.
* Finally, we create various ScheduleDetails objects for HolidaySchedule, one per holiday. For example, we might create a July4ScheduleDetail with start and end dates both set to July 4 2010, and a WinterBreakScheduleDetail with a start date of Dec 23 2010 and an end date of Jan 3 2011.

To see how to create this schedule via CUPI, see the [[Cisco_Unity_Connection_Provisioning_Interface_%28CUPI%29_API_--_Schedule_Example|Schedule Example page]].

== CUPI for Schedules ==

The previously described database objects are accessible to the administrator via CUPI. The following sections list the URIs to access these resources along with the data contained within them.

=== ScheduleSets in CUPI ===

ScheduleSets are top-level resources in CUPI, with a base URI of +/vmrest/schedulesets+.

A ScheduleSet object has the following fields:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Field Name
! Field Type
! Default
! Notes
|-
| ObjectId
| GUID
| none
|
|-
| DisplayName
| String(64)
| none
|
|-
| OwnerLocattonObjectId
| GUID
| NULL
| One of the Owners must be non-NULL
|-
| OwnerPersonalRuleSetObjectId
| GUID
| NULL
|
|-
| OwnerSubscriberObjectId
| GUID
| NULL
|
|-
| Undeletable
| Boolean
| False
| Is only True for factory default objects
|}

==== Retrieving the list of ScheduleSets ====

To retrieve the list of ScheduleSets, an administrator makes a GET to the schedulesets resource:

<pre>
GET /vmrest/schedulesets
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleSets total="3">
<ScheduleSet>
<URI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da</URI>
<ObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ObjectId>
<DisplayName>Weekdays</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<ScheduleSetMemberURI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers</ScheduleSetMemberURI>
</ScheduleSet>
<ScheduleSet>
<URI>/vmrest/schedulesets/75af01af-d290-4e0e-9862-5adf8293536c</URI>
<ObjectId>75af01af-d290-4e0e-9862-5adf8293536c</ObjectId>
<DisplayName>All Hours</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<ScheduleSetMemberURI>/vmrest/schedulesets/75af01af-d290-4e0e-9862-5adf8293536c/schedulesetmembers</ScheduleSetMemberURI>
</ScheduleSet>
<ScheduleSet>
<URI>/vmrest/schedulesets/e2e381e4-6096-4643-b0bb-b17a65b101bc</URI>
<ObjectId>e2e381e4-6096-4643-b0bb-b17a65b101bc</ObjectId>
<DisplayName>Voice Recognition Update Schedule</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>false</Undeletable>
<ScheduleSetMemberURI>/vmrest/schedulesets/e2e381e4-6096-4643-b0bb-b17a65b101bc/schedulesetmembers</ScheduleSetMemberURI>
</ScheduleSet>
</ScheduleSets>
</pre>

==== Retrieving a ScheduleSet ====

To retrieve a single ScheduleSet, an administrator makes a GET to the schedulesets resource, specifying the ObjectId of the requested ScheduleSet in the URI:

<pre>
GET /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleSet>
<URI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da</URI>
<ObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ObjectId>
<DisplayName>Weekdays</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<ScheduleSetMemberURI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers</ScheduleSetMemberURI>
</ScheduleSet>
</pre>

This would return the following if the specified ScheduleSet does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>scheduleset - ObjectId=30d9c0df-534b-437a-a6b7-439adfd850da</message>
</errors>
</ErrorDetails>
</pre>

==== Adding a ScheduleSet ====

To add a new ScheduleSet, an administrator makes a POST to the schedulesets resource, specifying the new ScheduleSet via XML:

<pre>
POST /vmrest/schedulesets

<ScheduleSet>
<DisplayName>Night Shift</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
</ScheduleSet>
</pre>

This will return the URI to the newly created ScheduleSet (which includes its ObjectId):

<pre>
201
Created
/vmrest/user/schedulesets/0e58ec49-5064-4c9a-b1dc-dd47fe189419
</pre>

==== Changing a ScheduleSet ====

To change an existing ScheduleSet, an administrator makes a PUT to the schedulesets resource, specifying the ObjectId of the ScheduleSet they wish to change in the URI and any data changes via XML:

<pre>
PUT /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da

<ScheduleSet>
<DisplayName>Graveyard Shift</DisplayName>
</ScheduleSet>
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified scheduleset does not exist:

<pre>
400
Bad Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>DATA_EXCEPTION</code>
<message>ScheduleSet not found </message>
</errors>
</ErrorDetails>
</pre>

==== Deleting a ScheduleSet ====

To delete an existing ScheduleSet, an administrator makes a DELETE to the schedulesets resource, specifying the ObjectId of the ScheduleSet they wish to delete in the URI:

<pre>
DELETE /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified scheduleset does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>scheduleset - ObjectId=30d9c0df-534b-437a-a6b7-439adfd850da</message>
</errors>
</ErrorDetails>
</pre>

Note that if an administrator deletes a ScheduleSet object, then all of the supporting ScheduleSetMembers for that ScheduleSet will also be deleted.

=== Schedules in CUPI ===

Schedules are top-level resources in CUPI, with a base URI of +/vmrest/schedules+.

A Schedule object has the following fields:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Field Name
! Field Type
! Default
! Notes
|-
| ObjectId
| GUID
| none
|
|-
| DisplayName
| String(64)
| none
|
|-
| OwnerLocattonObjectId
| GUID
| NULL
| One of the Owner's must be non-NULL
|-
| OwnerPersonalRuleSetObjectId
| GUID
| NULL
|
|-
| OwnerSubscriberObjectId
| GUID
| NULL
|
|-
| Undeletable
| Boolean
| False
| Is only True for factory default objects
|-
| StartDate
| DateTime
| NULL
| NULL means effective immediately
|-
| EndDate
| DateTime
| NULL
| NULL means effective indefinitely
|-
| IsHoliday
| Boolean
| False
| Holiday Greetings are used during this period if True
|}

==== Retrieving the list of Schedules ====

To retrieve the list of Schedules, an administrator makes a GET to the schedules resource:

<pre>
GET /vmrest/schedules
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<Schedules total="3">
<Schedule>
<URI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76</URI>
<ObjectId>387f051e-3367-4cc8-abed-810293d39f76</ObjectId>
<DisplayName>Weekdays</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<IsHoliday>false</IsHoliday>
<ScheduleDetailsURI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails</ScheduleDetailsURI>
</Schedule>
<Schedule>
<URI>/vmrest/schedules/75af01af-d290-4e0e-9862-5adf8293536c</URI>
<ObjectId>75af01af-d290-4e0e-9862-5adf8293536c</ObjectId>
<DisplayName>All Hours</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<IsHoliday>false</IsHoliday>
<ScheduleDetailsURI>/vmrest/schedules/75af01af-d290-4e0e-9862-5adf8293536c/scheduledetails</ScheduleDetailsURI>
</Schedule>
<Schedule>
<URI>/vmrest/schedules/e2e381e4-6096-4643-b0bb-b17a65b101bc</URI>
<ObjectId>e2e381e4-6096-4643-b0bb-b17a65b101bc</ObjectId>
<DisplayName>Holidays</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>false</Undeletable>
<IsHoliday>true</IsHoliday>
<ScheduleDetailsURI>/vmrest/schedules/e2e381e4-6096-4643-b0bb-b17a65b101bc/scheduledetails</ScheduleDetailsURI>
</Schedule>
</Schedules>
</pre>

==== Retrieving a Schedule ====

To retrieve a single Schedule, an administrator makes a GET to the schedules resource, specifying the Objectid of the requested Schedule in the URI:

<pre>
GET /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<Schedule>
<URI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76</URI>
<ObjectId>387f051e-3367-4cc8-abed-810293d39f76</ObjectId>
<DisplayName>Weekdays</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<OwnerLocationURI>/vmrest/locations/connectionlocations/6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationURI>
<Undeletable>true</Undeletable>
<IsHoliday>false</IsHoliday>
<ScheduleDetailsURI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails</ScheduleDetailsURI>
</Schedule>
</pre>

This would return the following if the specified Schedule does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>schedule - ObjectId=387f051e-3367-4cc8-abed-810293d39f76</message>
</errors>
</ErrorDetails>
</pre>

==== Adding a Schedule ====

To add a new Schedule, an administrator makes a POST to the schedules resource, specifying the new Schedule via XML:

<pre>
POST /vmrest/schedules

<Schedule>
<DisplayName>EveningShift</DisplayName>
<OwnerLocationObjectId>6a56503e-c1c8-406c-85fd-76be40994d39</OwnerLocationObjectId>
<IsHoliday>false</IsHoliday>
</Schedule>
</pre>

This will return the URI to the newly created Schedule (which includes its ObjectId):

<pre>
201
Created
/vmrest/user/schedules/df7faf3b-3278-4852-b488-7e3134dc3336
</pre>

==== Changing a Schedule ====

To change an existing Schedule, an administrator makes a PUT to the schedules resource, specifying the ObjectId of the Schedule they wish to change in the URI and any data changes via XML:

<pre>
PUT /vmrest/schedules/df7faf3b-3278-4852-b488-7e3134dc3336

<Schedule>
<DisplayName>No Daylight Shift</DisplayName>
</Schedule>
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified schedule does not exist:

<pre>
400
Bad Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>DATA_EXCEPTION</code>
<message>Schedule not found </message>
</errors>
</ErrorDetails>
</pre>

==== Deleting a Schedule ====

To delete an existing Schedule, an administrator makes a DELETE to the schedules resource, specifying the ObjectId of the Schedule they wish to delete in the URI:

<pre>
DELETE /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified schedule does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>schedule - ObjectId=387f051e-3367-4cc8-abed-810293d39f76</message>
</errors>
</ErrorDetails>
</pre>

Note that if an administrator deletes a Schedule object, then all of the supporting ScheduleDetail objects for that Schedule will also be deleted.

=== ScheduleSetMembers in CUPI ===

ScheduleSetMembers are the resources representing ScheduleSetMemberMaps objects. They are sub-resources of ScheduleSets in CUPI, and thus are at a sub-URI of the schedulesets resource: +/vmrest/scheduleset/+{_}+<ScheduleSetObjectId>+{_}+/schedulesetmembers+.

A ScheduleSetMember object has the following fields:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Field Name
! Field Type
! Default
! Notes
|-
| ScheduleSetObjectId
| GUID
| none
| Owning ScheduleSet
|-
| ScheduleObjectId
| GUID
| none
| Schedule to include/exclude from ScheduleSet
|-
| Exclude
| Boolean
| False
| False means Include, True means Exclude
|}

====Retrieving the list of ScheduleSetMembers ====

To retrieve the list of ScheduleSetMembers for a particular ScheduleSet, an administrator makes a GET to the schedulesetmembers resource, specifying the ObjectId of the ScheduleSet in the URI:

<pre>
GET /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleSetMembers total="2">
<ScheduleSetMember>
<URI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</URI>
<ScheduleSetObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetObjectId>
<ScheduleSetURI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetURI>
<ScheduleObjectId>a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</ScheduleURI>
<Exclude>false</Exclude>
</ScheduleSetMember>
<ScheduleSetMember>
<URI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/279fd73f-36a9-469a-9ad5-a0f80f09b2d</URI>
<ScheduleSetObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetObjectId>
<ScheduleSetURI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetURI>
<ScheduleObjectId>279fd73f-36a9-469a-9ad5-a0f80f09b2d</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/279fd73f-36a9-469a-9ad5-a0f80f09b2d</ScheduleURI>
<Exclude>true</Exclude>
</ScheduleSetMember>
</ScheduleSetMembers>
</pre>

==== Retrieving a ScheduleSetMember ====

To retrieve a single ScheduleSetMember for a particular ScheduleSet, an administrator makes a GET to the schedulesetmembers resource, specifying the ObjectIds of the ScheduleSet and the requested ScheduleSetMember in the URI:

<pre>
GET /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleSetMember>
<URI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</URI>
<ScheduleSetObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetObjectId>
<ScheduleSetURI>/vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetURI>
<ScheduleObjectId>a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</ScheduleURI>
<Exclude>false</Exclude>
</ScheduleSetMember>
</pre>

This would return the following if the specified ScheduleSetMember does not exist (meaning the Schedule is not listed as either included or excluded from the ScheduleSet):

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>schedulesetmember - ObjectId=a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</message>
</errors>
</ErrorDetails>
</pre>

==== Adding a ScheduleSetMember ====

To add a new ScheduleSetMember to a particular ScheduleSet, an administrator makes a POST to the schedulessetmembers resource, specifying the ObjectId of the ScheduleSet in the URI and the new ScheduleSetMember via XML:

<pre>
POST /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers

<ScheduleSetMember>
<ScheduleSetObjectId>30d9c0df-534b-437a-a6b7-439adfd850da</ScheduleSetObjectId>
<ScheduleObjectId>db46f878-bc72-4870-9482-9f1c336641ed</ScheduleObjectId>
<Exclude>false</Exclude>
</ScheduleSetMember>
</pre>

This will return the URI to the newly created ScheduleSetMember (which includes its ObjectId):

<pre>
201
Created
/vmrest/user/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/68c53107-5d28-4f40-ae43-f83d35eee8d6
</pre>

NOTE: A ScheduleSet can have at most 1 Schedule marked as Included, and that Schedule must not be a Holiday Schedule. A ScheduleSet can also have at most 1 Schedule marked as Excluded, and that Schedule must be a Holiday Schedule. If an administrator makes a POST to the schedulesetmembers resource in an attempt to Include or Exclude more than 1 Schedule of a given type to a ScheduleSet, then CUPI will return an HTTP 400 error with a descriptive error message. Similarly, if an administrator makes a POST to the schedulesetmembers resource in an attempt to Include a Holiday Schedule or Exclude a non-Holiday Schedule, then CUPI will return an HTTP 400 error with a descriptive error message.

==== Changing a ScheduleSetMember ====

The schedulesetmembers resource does not support the PUT method. In order to change a ScheduleSetMember, an administrator must delete the existing one and then add it back with the requested change.

==== Deleting a ScheduleSetMember ====

To delete an existing ScheduleSetMember for a particular ScheduleSet, an administrator makes a DELETE to the schedulesetmembers resource, specifying the ObjectIds of the ScheduleSet and the ScheduleSetMember they wish to delete in the URI:

<pre>
DELETE /vmrest/schedulesets/30d9c0df-534b-437a-a6b7-439adfd850da/schedulesetmembers/a1f34a57-b642-4d8b-9634-b4c2e37bfd2b
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified schedulesetmember does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>schedulesetmember - ObjectId=a1f34a57-b642-4d8b-9634-b4c2e37bfd2b</message>
</errors>
</ErrorDetails>
</pre>

=== ScheduleDetails in CUPI ===

ScheduleDetails are sub-resources of Schedules in CUPI, and thus are at a sub-URI of the schedules resources: +/vmrest/schedules/+{_}+<ScheduleObjectId>+{_}+/scheduledetails+.

A ScheduleDetail object has the following fields:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Field Name
! Field Type
! Default
! Notes
|-
| ObjectId
| GUID
| none
|
|-
| Subject
| String(2048)
| none
|
|-
| ScheduleObjectId
| GUID
| none
| Owning Schedule
|-
| StartDate
| DateTime
| NULL
| NULL means effective immediately, also Time portion of DateTime is ignored
|-
| StartTime
| Int
| NULL
| NULL means 12:00AM, otherwise minutes past 12:00AM so 480 means 8:00AM
|-
| EndDate
| DateTime
| NULL
| NULL means effective indefinitely, also Time portion of DateTime is ignored
|-
| EndTime
| Int
| NULL
| NULL means End-of-Day (11:59:59PM), otherwise minutes past 12:00AM so 1020 means 5:00PM
|-
| IsActiveMonday
| Boolean
| False
|
|-
| IsActiveTuesday
| Boolean
| False
|
|-
| IsActiveWednesday
| Boolean
| False
|
|-
| IsActiveThursday
| Boolean
| False
|
|-
| IsActiveFriday
| Boolean
| False
|
|-
| IsActiveSaturday
| Boolean
| False
|
|-
| IsActiveSunday
| Boolean
| False
|
|}

==== Retrieving the list of ScheduleDetails ====

To retrieve the list of ScheduleDetails for a particular Schedule, an administrator makes a GET to the scheduledetails resource, specifying the ObjectId of the Schedule in the URI:

<pre>
GET /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleDetails total="2">
<ScheduleDetail>
<URI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e</URI>
<ObjectId>fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e</ObjectId>
<ScheduleObjectId>387f051e-3367-4cc8-abed-810293d39f76</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76</ScheduleURI>
<Subject>Weekday Mornings</Subject>
<StartTime>480</StartTime>
<EndTime>720</EndTime>
<IsActiveMonday>true</IsActiveMonday>
<IsActiveTuesday>true</IsActiveTuesday>
<IsActiveWednesday>true</IsActiveWednesday>
<IsActiveThursday>true</IsActiveThursday>
<IsActiveFriday>true</IsActiveFriday>
<IsActiveSaturday>false</IsActiveSaturday>
<IsActiveSunday>false</IsActiveSunday>
</ScheduleDetail>
<ScheduleDetail>
<URI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/e049dc1e-7447-4e2a-907e-03d67e2d40a1</URI>
<ObjectId>e049dc1e-7447-4e2a-907e-03d67e2d40a1</ObjectId>
<ScheduleObjectId>387f051e-3367-4cc8-abed-810293d39f76</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76</ScheduleURI>
<Subject>Weekday Afternoons</Subject>
<StartTime>780</StartTime>
<EndTime>1020</EndTime>
<IsActiveMonday>true</IsActiveMonday>
<IsActiveTuesday>true</IsActiveTuesday>
<IsActiveWednesday>true</IsActiveWednesday>
<IsActiveThursday>true</IsActiveThursday>
<IsActiveFriday>true</IsActiveFriday>
<IsActiveSaturday>false</IsActiveSaturday>
<IsActiveSunday>false</IsActiveSunday>
</ScheduleDetail>
</ScheduleDetails>
</pre>

==== Retrieving a ScheduleDetail ====

To retrieve a single ScheduleDetail for a particular Schedule, an administrator makes a GET to the scheduledetails resource, specifying the ObjectIds of the Schedule and the requested ScheduleDetail in the URI:

<pre>
GET /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e
</pre>

This would return the following on success:

<pre>
200
OK
<?xml version="1.0" encoding="UTF-8"?>
<ScheduleDetail>
<URI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e</URI>
<ObjectId>fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e</ObjectId>
<ScheduleObjectId>387f051e-3367-4cc8-abed-810293d39f76</ScheduleObjectId>
<ScheduleURI>/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76</ScheduleURI>
<Subject>Weekday Mornings</Subject>
<StartTime>480</StartTime>
<EndTime>720</EndTime>
<IsActiveMonday>true</IsActiveMonday>
<IsActiveTuesday>true</IsActiveTuesday>
<IsActiveWednesday>true</IsActiveWednesday>
<IsActiveThursday>true</IsActiveThursday>
<IsActiveFriday>true</IsActiveFriday>
<IsActiveSaturday>false</IsActiveSaturday>
<IsActiveSunday>false</IsActiveSunday>
</ScheduleDetail>
</pre>

This would return the following if the specified ScheduleDetail does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>scheduledetail - ObjectId=fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e</message>
</errors>
</ErrorDetails>
</pre>

==== Adding a ScheduleDetail ====

To add a new ScheduleDetail to a particular Schedule, an administrator makes a POST to the scheduledetails resource, specifying the ObjectId of the Schedule in the URI and the new ScheduleDetail via XML:

<pre>
POST /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails

<ScheduleDetail>
<Subject>Saturday (Half-day)</Subject>
<StartTime>540</StartTime>
<EndTime>780</EndTime>
<IsActiveSaturday>true</IsActiveSaturday>
</ScheduleDetail>
</pre>

This will return the URI to the newly created ScheduleDetail (which includes its ObjectId):

<pre>
201
Created
/vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/9d8afb61-bd4b-4e65-b274-e870a2b51865
</pre>

==== Changing a ScheduleDetail ====

To change an existing ScheduleDetail for a particular Schedule, an administrator makes a PUT to the scheduledetails resource, specifying the ObjectId of the Schedule and the ScheduleDetail they wish to change in the URI and the data changes via XML:

<pre>
PUT /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/fb6cb280-ea91-4ee5-9225-6ca9c5e3b77e

<ScheduleDetail>
<StartTime>450</StartTime>
</ScheduleDetail>
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified scheduledetail does not exist:

<pre>
400
Bad Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>DATA_EXCEPTION</code>
<message>ScheduleDetail not found </message>
</errors>
</ErrorDetails>
</pre>

==== Deleting a ScheduleDetail ====

To delete an existing ScheduleDetail from a particular Schedule, an administrator makes a DELETE to the scheduledetails resource, specifying the ObjectId of the Schedule and the ScheduleDetail they wish to delete in the URI:

<pre>
DELETE /vmrest/schedules/387f051e-3367-4cc8-abed-810293d39f76/scheduledetails/9d8afb61-bd4b-4e65-b274-e870a2b51865
</pre>

This would return the following on success:

<pre>
204
No Content
</pre>

This would return the following if the specified scheduledetail does not exist:

<pre>
404
Not Found
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorDetails>
<errors>
<code>NOT_FOUND</code>
<message>scheduledetail - ObjectId=9d8afb61-bd4b-4e65-b274-e870a2b51865</message>
</errors>
</ErrorDetails>
</pre>

[[Category:Cisco Unity Connection Provisioning Interface (CUPI) API]]

Cisco Unity Connection Provisioning Interface (CUPI) API

2010-12-14T14:29:29Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users

2010-12-14T14:29:03Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUPI for End Users Guide Contents'''
|-
|[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users|API Overview ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Basics, Voice Name, Greetings |Basics, Voice Name, Greetings ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Unified Messaging Accounts |Unified Messaging Accounts ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Alternate Devices |Alternate Devices ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Directory |Directory ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Enabling and Disabling Greetings |Enabling and Disabling Greetings ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Location |Location ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Private Lists |Private Lists ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- SMTP Proxy Addresses |SMTP Proxy Addresses ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- System Configuration |System Configuration ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Transfer Options |Transfer Options ]]
|}

__TOC__

== Introduction ==

Cisco Unity Connection Provisioning Interface (CUPI) for End Users is a provisioning API for Cisco Unity Connection that has been designed to be stable and simple to use. It is based on leading industry standards for web-based API development, and provides access to many of the end user's account settings.

== Benefits ==

By using CUPI, end users can do the following:

* Update transfer options (basic transfer rules), unified messaging account passwords (Connection 8.5 and later), external services account passwords (Connection 8.0), and user passwords and PINs

* Record greetings and voice names

* Create, read, update, and delete private lists and private list members, alternate names, and user-defined alternate extensions

* Read SMTP proxy addresses. basic user information (for example, alias, display name, and DTMF access ID), class of service information, and administrator-defined alternate extensions

== Technical Details ==

Previous provisioning APIs required knowledge of the underlying database, and were vulnerable to changes in the database schema. CUPI provides a layer over the database to make the interface more stable.

CUPI is standards based. CUPI was developed by using the latest advances in web-based interfaces. It is a REST interface that standardizes operations such as add, delete, and modify. The XML comes with standard XML schema definitions that are annotated with information about what is in them.

Other product groups in VTG are developing REST-based interfaces, and as the interfaces converge this positions CUPI well to fit in with them. REST interfaces also work well with Web 2.0 applications.

As a web-based interface, CUPI is independent of operating system and programming language and does not require any client libraries to use.

== Getting Started ==

In order to begin developing with the Cisco Unity Connection CUPI API, you need to obtain the following:

=== Hardware ===

* Cisco Media Convergence Server (MCS) for Cisco Unity Connection version 8.0 and later
* For detailed hardware requirements, see the [http://www.cisco.com/en/US/docs/voice_ip_comm/connection/8x/supported_platforms/8xcucspl.html Cisco Unity Connection 8.x Supported Platforms List]

=== Software ===

* Cisco Unity Connection Software Ordering
* Not for Resale Kits (Must be eligible to purchase)
* Communications System Release Kit

Discounts for some of the required hardware and software may be available for participants in the Cisco Technology Developer Program.

We recommend that all developers have an up-to-date Cisco Developer Services support agreement. This provides the developer with access to professional support and assistance for application development.

== Other CUPI Resources ==

Additional information about CUPI is also available on the Cisco Developer Network ([http://developer.cisco.com/web/cupi/home link to CDN]). Note, however, that the documentation here on the DocWiki is the most up-to-date documentation available for CUPI.

To participate in the CUPI forum, see the [http://developer.cisco.com/web/cupi/forums CUPI forum on CDN].

On the CUPI page on CDN, you will also find links to the CUPI WADL and CUPI XML schema.

== Troubleshooting ==

See the following for information on troubleshooting all Connection APIs:

[[Cisco Unity Connection APIs -- Troubleshooting |Troubleshooting (applies to all Connection APIs)]]

[[Category:Cisco Unity Connection Provisioning Interface (CUPI) API For End Users]]

Cisco Unity Connection Notification Interface (CUNI) API

2010-12-14T14:27:48Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUNI Guide Contents'''
|-
|[[Cisco Unity Connection Notification Interface (CUNI) API|API Overview ]] [[Cisco Unity Connection Notification Interface (CUNI) API -- CUNI Event Schema|CUNI Event Schema]] [[Cisco Unity Connection Notification Interface (CUNI) API -- Subscribing to and Processing Notification Events|Subscribing to and Processing Notification Events]]
|}

__TOC__

== Introduction ==

The Cisco Unity Connection Notification Interface (CUNI) API is a web service interface for managing subscriptions to events from Cisco Unity Connection systems. It provides a way to get asynchronous notifications when voice mail messages are received, deleted, or changed. CUNI can be used to integrate Connection into an existing enterprise-wide portal.

CUNI is designed to provide a simple, stable method of accessing the notification functionality on Connection systems through a standards based interface using XML and HTTPS.

Through CUNI, you can do the following:

* Subscribe for message events
* Subscribe for one or many users on a single channel

Note that CUNI is intended for use in server-to-server applications where receiving notifications for many users over a single connection is required. As such, it is designed to handle a small number of clients that are each subscribing for notifications on a large set of subscribers. It also requires Administrative credentials, making it inappropriate for browser applications to use directly.

CUNI is composed of two parts: a SOAP interface for subscribing, and an asynchronous piece (the Notifier) that delivers events as XML over HTTP.

== Technical Details ==

* CUNI is standards-based: it implements a standard SOAP-based interface for managing subscriptions. Message events are sent as standard XML over HTTP.
* CUNI is easy to use: as a web-based interface, CUNI is independent of operating systems and programming languages, and does not require any client libraries to use.

== Getting Started with CUNI ==

In order to begin developing with CUNI, you need to obtain the following:

=== Hardware ===

* Cisco Media Convergence Server (MCS) for Cisco Unity Connection version 8.0 or later
* For detailed hardware-specification information, see the [http://www.cisco.com/en/US/docs/voice_ip_comm/connection/8x/supported_platforms/8xcucspl.html Cisco Unity Connection 8.x Supported Platforms List]

=== Software ===

* Cisco Unity Connection Software Ordering
* Not for Resale Kits (Must for eligible to purchase)
* Select Unified Communications System Release Kit

Discounts for some of the above hardware and software may be available for participants in the Cisco Technology Developer Program.

We recommend that all developers have an up-to-date Cisco Developer Services support agreement. This provides the developer with access to professional support and assistance for application development.

== Other CUNI Resources ==

Additional information about CUNI is also available on the Cisco Developer Network ([http://developer.cisco.com/web/cuni/home link to CDN]). Note, however, that the documentation here on the DocWiki is the most up-to-date documentation available for CUNI.

To participate in the CUNI forum, see the [http://developer.cisco.com/web/cuni/forums CUNI forum on CDN].

== Troubleshooting ==

See the following for information on troubleshooting all Connection APIs:

[[Cisco Unity Connection APIs -- Troubleshooting |Troubleshooting (applies to all Connection APIs)]]

[[Category:Cisco Unity Connection Notification Interface (CUNI) API]]

Cisco Unity Connection Notification Interface (CUNI) API -- CUNI Event Schema

2010-12-14T14:26:54Z

Juliew:

'''Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUNI Guide Contents'''
|-
|[[Cisco Unity Connection Notification Interface (CUNI) API|API Overview ]] [[Cisco Unity Connection Notification Interface (CUNI) API -- CUNI Event Schema|CUNI Event Schema ]] [[Cisco Unity Connection Notification Interface (CUNI) API -- Subscribing to and Processing Notification Events|Subscribing to and Processing Notification Events]]
|}

__TOC__

== Schema Example ==

<pre>
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns="\[http://www.cisco.com"\] elementFormDefault="qualified" targetNamespace="\[http://www.cisco.com"\] xmlns:xs="\[http://www.w3.org/2001/XMLSchema">\]
<xs:simpleType name="priorityType">
<xs:restriction base="xs:string">
<xs:enumeration value="Low-Priority" />
<xs:enumeration value="Normal-Priority" />
<xs:enumeration value="Urgent" />
<xs:enumeration value="Unknown-Priority" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="eventType">
<xs:restriction base="xs:string">
<xs:enumeration value="MESSAGE_INFO" />
<xs:enumeration value="NEW_MESSAGE" />
<xs:enumeration value="SAVED_MESSAGE" />
<xs:enumeration value="UNREAD_MESSAGE" />
<xs:enumeration value="DELETED_MESSAGE" />
<xs:enumeration value="FAILOVER" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="messageType">
<xs:restriction base="xs:string">
<xs:enumeration value="Voice" />
<xs:enumeration value="NDR" />
<xs:enumeration value="DR" />
<xs:enumeration value="RR" />
<xs:enumeration value="Fax" />
<xs:enumeration value="Text" />
<xs:enumeration value="UnknownType" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="messageInfoType">
<xs:attribute name="messageId" type="xs:string" />
<xs:attribute name="receiveTime" type="xs:string" />
<xs:attribute name="msgType" type="messageType" />
<xs:attribute name="uid" type="xs:integer" />
<xs:attribute name="priority" type="priorityType" />
<xs:attribute name="sender" type="xs:string" />
<xs:attribute name="callerAni" type="xs:string" />
</xs:complexType>
<xs:element name="messageEvent">
<xs:complexType>
<xs:sequence minOccurs="1" maxOccurs="unbounded">
<xs:element name="messageInfo" type="messageInfoType" />
</xs:sequence>
<xs:attribute name="subscriptionId" type="xs:string" />
<xs:attribute name="eventType" type="eventType" />
<xs:attribute name="eventTime" type="xs:string" />
<xs:attribute name="mailboxId" type="xs:string" />
<xs:attribute name="displayName" type="xs:string" />
<xs:attribute name="USN" type="xs:integer" />
</xs:complexType>
</xs:element>
</xs:schema>
</pre>

[[Category:Cisco Unity Connection Notification Interface (CUNI) API]]

Cisco Unity Connection APIs

2010-12-14T01:09:27Z

Juliew:

Cisco Unity Connection is a feature-rich voice messaging platform based on the same Linux operating system as Cisco Unified Communications Manager. Connection users can access voice messages by using email, web clients, mobile devices, instant messaging, and desktop clients such as Cisco Unified Personal Communicator, and can view, search, sort, and play messages on a Cisco Unified IP Phone display. Connection also provides comprehensive automated-attendant functions, including intelligent call routing and easily customizable call screen and message notification options. For more information see [http://www.cisco.com/en/US/products/ps6509/tsd_products_support_series_home.html Cisco Unity Connection documentation on Cisco.com].

Cisco Unity Connection includes several Representational State Transfer (REST) application programming interfaces (APIs) that provide provisioning, messaging, and telephony access to Connection. These APIs provide the ability to integrate Connection features into existing enterprise-wide provisioning management systems and messaging clients.
The APIs are REST interfaces that standardize operations such as add, delete, view, and modify.

== Available Connection APIs ==

'''CUPI''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API]]

The Cisco Unity Connection Provisioning Interface (CUPI) API provides access to the most commonly provisioned data on Cisco Unity Connection systems—users, contacts, distribution lists, and call handlers.

'''CUPI for End Users''': [[Cisco_Unity_Connection_Provisioning_Interface_(CUPI)_API_--_For_End_Users]]

The Cisco Unity Connection Provisioning Interface (CUPI) API includes access for individual users when authenticating against user credentials. This allows for custom end-user applications.

'''CUMI''': [[Cisco_Unity_Connection_Messaging_Interface_(CUMI)_API]]

Cisco Unity Connection Messaging Interface (CUMI) API provides access to user messages.

'''CUTI''': [[Cisco_Unity_Connection_Telephony_Interface_(CUTI)_API]]

Cisco Unity Connection Telephony Interface (CUTI) API provides the ability to play and record audio content over the phone.

'''CUNI''': [[Cisco_Unity_Connection_Notification_Interface_(CUNI)_API]]

Cisco Unity Connection Notification Interface (CUNI) API provides notification for one or more users. CUNI is designed for use in server-to-server applications where receiving notifications for many users over a single connection is required.

[[Category: Unity Connection APIs]]

Cisco Unity Connection Provisioning Interface (CUPI) API -- About Versioning

2010-12-14T00:59:54Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Wave Formats

2010-12-13T22:58:03Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- System Default Language and TTS Language

2010-12-13T22:57:35Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Schedule Example

2010-12-13T22:57:12Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Schedules

2010-12-13T22:56:41Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Routing Rules

2010-12-13T22:55:54Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUPI Guide Contents'''
|-
|[[Cisco Unity Connection Provisioning Interface (CUPI) API|API Overview ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- Index of All CUPI Documentation|Index of All CUPI Documentation]]
|}

__TOC__

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

<pre>
GET https://<connection-server>/vmrest/routingrules
</pre>

The following is the response from the above GET request:

<pre>
200
OK

<?xml version="1.0" encoding="UTF-8"?>
<RoutingRules total="3">
<RoutingRule>
<URI>/vmrest/routingrules/a2f64719-c82f-491c-996f-ee543e6d7e38</URI>
<ObjectId>a2f64719-c82f-491c-996f-ee543e6d7e38</ObjectId>
<DisplayName>Opening Greeting</DisplayName>
<State>0</State>
<RuleIndex>2</RuleIndex>
<Type>3</Type>
<Flags>3</Flags>
<RouteTargetConversation>PHTransfer</RouteTargetConversation>
<RouteTargetHandlerObjectId>198ff222-1129-486c-9bef-c05057dae950</RouteTargetHandlerObjectId>
<RouteTargetHandlerDisplayName>Opening Greeting</RouteTargetHandlerDisplayName>
<RouteTargetHandlerObjectType>3</RouteTargetHandlerObjectType>
<RouteAction>2</RouteAction>
<LanguageCode>0</LanguageCode>
<UseDefaultLanguage>true</UseDefaultLanguage>
<UseCallLanguage>true</UseCallLanguage>
<CallType>2</CallType>
<SearchSpaceObjectId>02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceObjectId>
<SearchSpaceURI>/vmrest/searchspaces/02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceURI>
<Undeletable>true</Undeletable>
<RoutingRuleConditionsURI>/vmrest/routingrules/a2f64719-c82f-491c-996f-ee543e6d7e38/routingruleconditions</RoutingRuleConditionsURI>
</RoutingRule>
<RoutingRule>
<URI>/vmrest/routingrules/857c5cd6-0153-4673-a917-27c59bf5ce37</URI>
<ObjectId>857c5cd6-0153-4673-a917-27c59bf5ce37</ObjectId>
<DisplayName>Attempt Sign In</DisplayName>
<State>0</State>
<RuleIndex>1</RuleIndex>
<Type>1</Type>
<Flags>3</Flags>
<RouteTargetConversation>AttemptSignIn</RouteTargetConversation>
<RouteTargetHandlerObjectType>0</RouteTargetHandlerObjectType>
<RouteAction>2</RouteAction>
<LanguageCode>0</LanguageCode>
<UseDefaultLanguage>true</UseDefaultLanguage>
<UseCallLanguage>true</UseCallLanguage>
<CallType>2</CallType>
<SearchSpaceObjectId>02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceObjectId>
<SearchSpaceURI>/vmrest/searchspaces/02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceURI>
<Undeletable>true</Undeletable>
<RoutingRuleConditionsURI>/vmrest/routingrules/857c5cd6-0153-4673-a917-27c59bf5ce37/routingruleconditions</RoutingRuleConditionsURI>
</RoutingRule>
<RoutingRule>
<URI>/vmrest/routingrules/8b7ea5be-48c5-4e7b-bc9d-c06f052074a4</URI>
<ObjectId>8b7ea5be-48c5-4e7b-bc9d-c06f052074a4</ObjectId>
<DisplayName>Attempt Forward</DisplayName>
<State>0</State>
<RuleIndex>0</RuleIndex>
<Type>2</Type>
<Flags>3</Flags>
<RouteTargetConversation>AttemptForward</RouteTargetConversation>
<RouteTargetHandlerObjectType>0</RouteTargetHandlerObjectType>
<RouteAction>2</RouteAction>
<LanguageCode>0</LanguageCode>
<UseDefaultLanguage>true</UseDefaultLanguage>
<UseCallLanguage>true</UseCallLanguage>
<CallType>2</CallType>
<SearchSpaceObjectId>02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceObjectId>
<SearchSpaceURI>/vmrest/searchspaces/02cb3fba-1525-4768-89f6-64f4712ea177</SearchSpaceURI>
<Undeletable>true</Undeletable>
<RoutingRuleConditionsURI>/vmrest/routingrules/8b7ea5be-48c5-4e7b-bc9d-c06f052074a4/routingruleconditions</RoutingRuleConditionsURI>
</RoutingRule>
</RoutingRules>
</pre>

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:

<pre>
GET https://<connection-server>/vmrest/routingrules?sort=(RuleIndex%20asc)
</pre>

To retrieve a specific Routing Rule by its ObjectId:

<pre>
GET https://<connection-server>/vmrest/routingrules/<objectid>
</pre>

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

<pre>
GET https://<connection-server>/vmrest/routingules?query=(RuleIndex%20is%201)
</pre>

=== 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):

<pre>
POST https://<connection-server>/vmrest/routingrules

<RoutingRule>
<DisplayName>My Routing Rule</DisplayName>
<Type>1</Type>
</RoutingRule>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/routingrules/bd73528d-e810-4533-8aab-89de32013885
</pre>

=== Updating ===

The following is an example of a PUT request that modifies the DisplayName of an existing Routing Rule:

<pre>
PUT https://<connection-server>/vmrest/routingrules/<objectid>

<RoutingRule>
<DisplayName>Changed Display Name</DisplayName>
</RoutingRule>
</pre>

The following is the response from the above PUT request:

<pre>
204
No Content
</pre>

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.

=== Deleting ===

The following is an example of a DELETE request that deletes a Routing Rule:

<pre>
DELETE https://<connection-server>/vmrest/routingrules/<objectid>
</pre>

The following is the response from the above DELETE request:

<pre>
204
No Content
</pre>

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

<pre>
PUT https://<connection-server>/vmrest/routingrules

<RoutingRules>
<RoutingRule>
<ObjectId>aabbccdd-1111-2222-3333-1234567890ab</ObjectId>
</RoutingRule>
<RoutingRule>
<ObjectId>12345678-abcd-abcd-abcd-123412341234</ObjectId>
</RoutingRule>
<RoutingRule>
<ObjectId>99990000-1234-1234-1234-abcdef012345</ObjectId>
</RoutingRule>
</RoutingRules>
</pre>

The following is a response from the above PUT request:

<pre>
204
No Content
</pre>

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.

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

<pre>
GET https://<connection-server>/vmrest/routingrules/<routingruleobjectid>/routingruleconditions
</pre>

The following is the response from the above GET request:

<pre>
200
OK

<?xml version="1.0" encoding="UTF-8"?>
<RoutingRuleConditions total="2">
<RoutingRuleCondition>
<URI>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/2a5263b7-c896-47ff-ad8c-749e0459a28c</URI>
<ObjectId>2a5263b7-c896-47ff-ad8c-749e0459a28c</ObjectId>
<RoutingRuleObjectId>d2f86bc0-4cab-4c29-9321-d756fe3add6a</RoutingRuleObjectId>
<RoutingRuleURI>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a</RoutingRuleURI>
<Parameter>1</Parameter>
<Operator>2</Operator>
<OperandValue>12345</OperandValue>
</RoutingRuleCondition>
<RoutingRuleCondition>
<URI>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/d9635722-f1ee-4459-a2d4-533f85cd2c24</URI>
<ObjectId>d9635722-f1ee-4459-a2d4-533f85cd2c24</ObjectId>
<RoutingRuleObjectId>d2f86bc0-4cab-4c29-9321-d756fe3add6a</RoutingRuleObjectId>
<RoutingRuleURI>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a</RoutingRuleURI>
<Parameter>7</Parameter>
<Operator>2</Operator>
<OperandValue>4cc6c1be-e1ba-4fcf-be81-95bce20acbec</OperandValue>
</RoutingRuleCondition>
</RoutingRuleConditions>
</pre>

To retrieve a specific Routing Rule Condition by its ObjectId:

<pre>
GET https://<connection-server>/vmrest/routingrules/<routingruleobjectid>/routingruleconditions/<objectid>
</pre>

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

<pre>
POST https://<connection-server>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions

<RoutingRuleCondition>
<Parameter>2</Parameter>
<Operator>2</Operator>
<OperandValue>8675309</OperandValue>
</RoutingRuleCondition>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/74b50eeb-8c06-4e86-b981-e4be62586feb
</pre>

=== Updating ===

The following is an example of a PUT request that modifies the OperandValue of an existing Routing Rule Condition to 5551212:

<pre>
PUT https://<connection-server>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/74b50eeb-8c06-4e86-b981-e4be62586feb

<RoutingRuleCondition>
<OperandValue>5551212</OperandValue>
</RoutingRuleCondition>
</pre>

The following is the response from the above PUT request:

<pre>
204
No Content
</pre>

=== Deleting ===

The following is an example of a DELETE request that deletes a Routing Rule Condition:

<pre>
DELETE https://<connection-server>/vmrest/routingrules/d2f86bc0-4cab-4c29-9321-d756fe3add6a/routingruleconditions/74b50eeb-8c06-4e86-b981-e4be62586feb
</pre>

The following is the response from the above DELETE request:

<pre>
204
No Content
</pre>

== 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 RouteTargetHandlerDisplayName 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 Call Handler ===

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 PHTransfer Conversation (meaning it will attempt to transfer to the call handler). If you want to transfer to a different call handler, set RouteTargetCallHandlerObjectId to it.

<pre>
<RoutingRule>
<RouteAction>2</RouteAction>
<RouteTargetConversation>PHTransfer</RouteTargetConversation>
<RouteTargetHandlerObjectId>aab5eab2-38f7-4231-a3be-bf2a8fde820c</RouteTargetHandlerObjectId>
</RoutingRule>
</pre>

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

<pre>
<RoutingRule>
<RouteAction>2</RouteAction>
<RouteTargetConversation>PHGreeting</RouteTargetConversation>
<RouteTargetHandlerObjectId>aab5eab2-38f7-4231-a3be-bf2a8fde820c</RouteTargetHandlerObjectId>
</RoutingRule>
</pre>

=== Go to an Interview Handler ===

The following Routing Rule will go to (Action=2) the interview handler (60367a3d-213e-4696-bd2a-f8d46091f2bf by using the PHInterview Conversation.

<pre>
<RoutingRule>
<RouteAction>2</RouteAction>
<RouteTargetConversation>PHInterview</RouteTargetConversation>
<RouteTargetHandlerObjectId>60367a3d-213e-4696-bd2a-f8d46091f2bf</RouteTargetHandlerObjectId>
</RoutingRule>
</pre>

=== Go to a Directory Handler ===

The following Routing Rule will go to (Action=2) the directory handler e6304212-d846-4957-b364-ebe323251007 by using the AD Conversation.

<pre>
<RoutingRule>
<RouteAction>2</RouteAction>
<RouteTargetConversation>AD</RouteTargetConversation>
<RouteTargetHandlerObjectId>e6304212-d846-4957-b364-ebe323251007</RouteTargetHandlerObjectId>
</RoutingRule>
</pre>

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

<pre>
<RoutingRule>
<RouteAction>2</RouteAction>
<RouteTargetConversation>BroadcastMessageAdministrator</RouteTargetConversation>
</RoutingRule>
</pre>

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

<pre>
<RoutingRuleCondition>
<Parameter>1</Parameter>
<Operator>2</Operator>
<OperandValue>1234</OperandValue>
</RoutingRuleCondition>
</pre>

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

<pre>
<RoutingRuleCondition>
<Parameter>5</Parameter>
<Operator>2</Operator>
<OperandValue>b79765f1-e14f-47b6-b8e1-00479909f710</OperandValue>
</RoutingRuleCondition>
</pre>

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

<pre>
<RoutingRuleCondition>
<Parameter>9</Parameter>
<Operator>2</Operator>
<OperandValue>2eb79e66-1e53-415c-9222-36665e0e76ae</OperandValue>
</RoutingRuleCondition>
</pre>

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

<pre>
<RoutingRuleCondition>
<Parameter>7</Parameter>
<Operator>2</Operator>
<OperandValue>4cc6c1be-e1ba-4fcf-be81-95bce20acbec</OperandValue>
</RoutingRuleCondition>
</pre>

== Enumeration Types ==

Routing Rules and Routing Rule Conditions have several fields that are enumeration types, meaning the fields are numeric constants whose meaning is not immediately obvious. The following tables list these constants and their meanings.

=== 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).

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Value
! Description
|-
| 1
| In
|-
| 2
| Equals
|-
| 3
| Greater than
|-
| 4
| Less than
|-
| 5
| Less than or equal to
|-
| 6
| Greater than or equal to
|}

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

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Value
! Description
|-
| 1
| Calling Number
|-
| 2
| Dialed Number
|-
| 3
| Forwarding Number
|-
| 5
| PortID
|-
| 7
| Schedule Set
|-
| 9
| Phone System
|}

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

{| border="1" cellspacing="0" cellpadding="5" align="center"
! 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
|}

[[Category:Cisco Unity Connection Provisioning Interface (CUPI) API]]

Cisco Unity Connection Provisioning Interface (CUPI) API -- Port Groups and Ports

2010-12-13T22:54:26Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- LDAP Phone Number Transform

2010-12-13T22:51:58Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Language Map

2010-12-13T22:45:16Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Cluster

2010-12-13T22:43:34Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Updating Caller Input Keys

2010-12-13T22:42:51Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Greetings

2010-12-13T22:41:56Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Caller Input Keys

2010-12-13T22:41:11Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Assigning a Schedule to a Call Handler

2010-12-13T22:39:32Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- User Import

2010-12-13T22:38:49Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- SMTP Proxy Addresses

2010-12-13T22:37:59Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Private Lists

2010-12-13T22:37:04Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Private List Members

2010-12-13T22:36:23Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Notification Devices

2010-12-13T22:34:37Z

Juliew:

'''Links to Other API pages:''' [[Cisco_Unity_Connection_APIs]]
{| align="right" border="1"
|align="center"|'''CUPI Guide Contents'''
|-
|[[Cisco Unity Connection Provisioning Interface (CUPI) API|API Overview ]] [[Cisco Unity Connection Provisioning Interface (CUPI) API -- Index of All CUPI Documentation|Index of All CUPI Documentation]]
|}

__TOC__

== About Notification Devices ==

This page contains information on how to use the API to create, list, update, and delete Notification Devices.

Cisco Unity Connection supports four different types of Notification Devices:

* Phone Devices
* Pager Devices
* SMS Devices
* SMTP Devices

The generic Notification Device resource contains the data fields that are common to most or all of the specialized Device resources, which in turn may contain additional data fields that are specific to certain Device resources. A listing of all data fields, including a description of what they mean and which specialized Device types support them, can be found later in this document.

An API user can retrieve a complete list of all Notification Devices or a specific Notification Device, but this is a read-only resource. In order to create, update, or delete a Notification Device, an API user must use the appropriate specialized Device resource. In other words, an API user can retrieve all of a user's Notification Devices, but if they then want to update a particular Phone Device, they must do the update operation on the Phone Device resource, not the Notification Device resource. This will be explained in more detail below.

The Notification Device resource and the four specialized Device resources contain data fields from the Device objects in the database, plus some data fields from the Notification Rule object. From an API user's perspective, this detail may not usually be important, but it is worth mentioning that the Device resources collapse two database objects into a single resource. This can be safely done because there is always a one-to-one mapping in the database of Notification Devices and Notification Rules.

The factory default User Template for Voicemail Users contains five Notification Devices: three Phone Devices (Home, Work, and Mobile), one Pager Device, and one SMTP Device. Any of these default Notification Devices can be modified, and new Devices of any of four specialized types can be created or deleted. Note that Notification Devices for User Templates are not currently exposed via the API, only Notification Devices for Users are exposed.

== Listing and Viewing ==

An API user can list all generic Notification Device resources or all Device resources of a specified type (Phone, Pager, SMS, or SMTP).

=== Listing and Viewing Notification Devices ===

The following is an example of a GET that lists all Notification Devices of all types for the specified User:

<pre>
GET https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices
{noformat}
The following is the response from the above *GET* request. Notice that this list contains a mix of different types of specialized Devices, since the request was for a list of all Notification Devices. The Type field indicates the specialized Device type for each Notification Device (1 = Phone, 2 = Pager, 4 = SMTP, 5 = SMS).
{noformat}
200
OK

<?xml version="1.0" encoding="UTF-8"?>
<NotificationDevices total="5">
<NotificationDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/2b13dda8-6249-45b2-9a87-aba1b27a1f95</URI>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<ObjectId>2b13dda8-6249-45b2-9a87-aba1b27a1f95</ObjectId>
<DisplayName>Pager</DisplayName>
<Active>false</Active>
<BusyRetryInterval>5</BusyRetryInterval>
<Type>2</Type>
<DialDelay>1</DialDelay>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<SendCount>true</SendCount>
<WaitConnect>true</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<DeviceName>Pager</DeviceName>
<PromptForId>false</PromptForId>
<SendCallerId>true</SendCallerId>
<SendPcaLink>false</SendPcaLink>
<Undeletable>true</Undeletable>
<MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
<DetectTransferLoop>false</DetectTransferLoop>
<SuccessRetryInterval>1</SuccessRetryInterval>
<RetriesOnSuccess>0</RetriesOnSuccess>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</NotificationDevice>
<NotificationDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/0f4ce029-1939-4ae0-9dee-9d84c77fadae</URI>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<ObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</ObjectId>
<DisplayName>Home Phone</DisplayName>
<Active>false</Active>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<Type>1</Type>
<DialDelay>1</DialDelay>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<SendCount>false</SendCount>
<WaitConnect>true</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<DeviceName>Home Phone</DeviceName>
<PromptForId>false</PromptForId>
<SendCallerId>false</SendCallerId>
<SendPcaLink>false</SendPcaLink>
<Undeletable>true</Undeletable>
<MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
<DetectTransferLoop>false</DetectTransferLoop>
<SuccessRetryInterval>0</SuccessRetryInterval>
<RetriesOnSuccess>0</RetriesOnSuccess>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</NotificationDevice>
<NotificationDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/878de0bf-9169-4ef7-afe4-ec82998c2322</URI>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<ObjectId>878de0bf-9169-4ef7-afe4-ec82998c2322</ObjectId>
<DisplayName>Mobile Phone</DisplayName>
<Active>false</Active>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<Type>1</Type>
<DialDelay>1</DialDelay>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<SendCount>false</SendCount>
<WaitConnect>true</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<DeviceName>Mobile Phone</DeviceName>
<PromptForId>false</PromptForId>
<SendCallerId>false</SendCallerId>
<SendPcaLink>false</SendPcaLink>
<Undeletable>true</Undeletable>
<MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
<DetectTransferLoop>false</DetectTransferLoop>
<SuccessRetryInterval>0</SuccessRetryInterval>
<RetriesOnSuccess>0</RetriesOnSuccess>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</NotificationDevice>
<NotificationDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/3a314c33-a69f-4179-a260-0c84a4520b3b</URI>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<ObjectId>3a314c33-a69f-4179-a260-0c84a4520b3b</ObjectId>
<DisplayName>Work Phone</DisplayName>
<Active>true</Active>
<AfterDialDigits>1701</AfterDialDigits>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<Type>1</Type>
<DialDelay>1</DialDelay>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<PhoneNumber>3475</PhoneNumber>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<SendCount>false</SendCount>
<WaitConnect>false</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<DeviceName>Work Phone</DeviceName>
<PromptForId>true</PromptForId>
<SendCallerId>false</SendCallerId>
<SendPcaLink>false</SendPcaLink>
<Undeletable>true</Undeletable>
<MediaSwitchDisplayName>PhoneSystem</MediaSwitchDisplayName>
<DetectTransferLoop>false</DetectTransferLoop>
<SuccessRetryInterval>0</SuccessRetryInterval>
<RetriesOnSuccess>0</RetriesOnSuccess>
<EventList>AllMessage</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>5</InitialDelay>
<RepeatInterval>15</RepeatInterval>
<RepeatNotify>true</RepeatNotify>
<FailDeviceObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</FailDeviceObjectId>
</NotificationDevice>
<NotificationDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/3e7f802b-d707-489f-b241-399ab67a0dc3</URI>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<ObjectId>3e7f802b-d707-489f-b241-399ab67a0dc3</ObjectId>
<DisplayName>SMTP</DisplayName>
<Active>false</Active>
<BusyRetryInterval>0</BusyRetryInterval>
<Type>4</Type>
<DialDelay>0</DialDelay>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<RetriesOnBusy>0</RetriesOnBusy>
<RetriesOnRna>0</RetriesOnRna>
<RingsToWait>0</RingsToWait>
<RnaRetryInterval>0</RnaRetryInterval>
<SendCount>true</SendCount>
<WaitConnect>false</WaitConnect>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<DeviceName>SMTP</DeviceName>
<PromptForId>false</PromptForId>
<SendCallerId>true</SendCallerId>
<SendPcaLink>false</SendPcaLink>
<Undeletable>true</Undeletable>
<DetectTransferLoop>false</DetectTransferLoop>
<SuccessRetryInterval>0</SuccessRetryInterval>
<RetriesOnSuccess>0</RetriesOnSuccess>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</NotificationDevice>
</NotificationDevices>
</pre>

=== Listing and Viewing Specialized Devices ===

The following is an example of a GET that lists all Phone Devices for the specified User. Listing all specialized devices of other types is very similar; simply do a GET to the pagerdevices, smsdevices, or smtpdevices resource, rather than to the phonedevices resource.

<pre>
GET https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices
</pre>

The following is the response from the above GET request. Note that each returned resource is a Phone Device rather than a Notification Device since the request was for Phone Devices only.

<pre>
200
OK

<?xml version="1.0" encoding="UTF-8"?>
<PhoneDevices total="3">
<PhoneDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/3a314c33-a69f-4179-a260-0c84a4520b3b</URI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<AfterDialDigits>1701</AfterDialDigits>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<DialDelay>1</DialDelay>
<PhoneNumber>3475</PhoneNumber>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<WaitConnect>false</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<ObjectId>3a314c33-a69f-4179-a260-0c84a4520b3b</ObjectId>
<Active>true</Active>
<DeviceName>Work Phone</DeviceName>
<DisplayName>Work Phone</DisplayName>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<PromptForId>true</PromptForId>
<Undeletable>true</Undeletable>
<DetectTransferLoop>false</DetectTransferLoop>
<EventList>AllMessage</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>5</InitialDelay>
<RepeatInterval>15</RepeatInterval>
<RepeatNotify>true</RepeatNotify>
<FailDeviceObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</FailDeviceObjectId>
</PhoneDevice>
<PhoneDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/0f4ce029-1939-4ae0-9dee-9d84c77fadae</URI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<DialDelay>1</DialDelay>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<WaitConnect>true</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<ObjectId>0f4ce029-1939-4ae0-9dee-9d84c77fadae</ObjectId>
<Active>false</Active>
<DeviceName>Home Phone</DeviceName>
<DisplayName>Home Phone</DisplayName>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<PromptForId>false</PromptForId>
<Undeletable>true</Undeletable>
<DetectTransferLoop>false</DetectTransferLoop>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</PhoneDevice>
<PhoneDevice>
<URI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/878de0bf-9169-4ef7-afe4-ec82998c2322</URI>
<TransmitForcedAuthorizationCode>false</TransmitForcedAuthorizationCode>
<BusyRetryInterval>5</BusyRetryInterval>
<Conversation>SubNotify</Conversation>
<DialDelay>1</DialDelay>
<RetriesOnBusy>4</RetriesOnBusy>
<RetriesOnRna>4</RetriesOnRna>
<RingsToWait>4</RingsToWait>
<RnaRetryInterval>15</RnaRetryInterval>
<WaitConnect>true</WaitConnect>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneSystemURI>/vmrest/phonesystems/6ecaa89b-2d29-4a21-8013-75c154ee58f5</PhoneSystemURI>
<ObjectId>878de0bf-9169-4ef7-afe4-ec82998c2322</ObjectId>
<Active>false</Active>
<DeviceName>Mobile Phone</DeviceName>
<DisplayName>Mobile Phone</DisplayName>
<MaxBody>512</MaxBody>
<MaxSubject>64</MaxSubject>
<SubscriberObjectId>70c5d764-b2f3-498a-b16e-1a4d2a369dfa</SubscriberObjectId>
<UserURI>/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa</UserURI>
<PromptForId>false</PromptForId>
<Undeletable>true</Undeletable>
<DetectTransferLoop>false</DetectTransferLoop>
<EventList>NewVoiceMail</EventList>
<ScheduleSetObjectId>d7ea64ca-e3fc-4d0a-8bd5-ef2337a31b97</ScheduleSetObjectId>
<InitialDelay>0</InitialDelay>
<RepeatInterval>0</RepeatInterval>
<RepeatNotify>false</RepeatNotify>
</PhoneDevice>
/PhoneDevices>
</pre>

== Searching ==

To retrieve a list of Notification Devices that meet a specified search criteria, add the following query parameter to a GET: query=(column [is | startswith] value)

For example, to find all Notification Devices with a DisplayName that starts with "Phone":

<pre>
GET https://<connection-server>/vmrest/users/<UserObjectId/notificationdevices?query=(DisplayName%20startswith%20Home)
</pre>

Search criteria can also be used when doing a GET to the specialized Device resources.

== Creating ==

A generic Notification Device resource is read-only, so new ones cannot be created. However, the four specialized Device resources are not read-only, so new ones can be created. Each of the four specialized Device resources has different required parameters during creation.

=== Creating Phone Devices ===

The required fields for creating a Phone Device are DisplayName, MediaSwitchObjectId, and PhoneNumber. All other Phone Device fields are optional.

The following is an example of a POST that creates a Phone Device with a DisplayName="My New Phone", MediaSwitchObjectId="6ecaa89b-2d29-4a21-8013-75c154ee58f5", PhoneNumber="5551212", and optional parameter InitialDelay=10:

<pre>
POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices

<PhoneDevice>
<DisplayName>My New Phone</DisplayName>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneNumber>5551212</PhoneNumber>
<InitialDelay>10</InitialDelay>
</PhoneDevice>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3
</pre>

=== Creating Pager Devices ===

The required fields for creating a Pager Device are DisplayName, MediaSwitchObjectId, and PhoneNumber. All other Pager Device fields are optional.

The following is an example of a POST that creates a Pager Device with DisplayName="My New Pager", MediaSwitchObjectId="6ecaa89b-2d29-4a21-8013-75c154ee58f5", PhoneNumber="8675309", and optional parameter Active=false.

<pre>
POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/pagerdevices

<PagerDevice>
<DisplayName>My New Pager</DisplayName>
<MediaSwitchObjectId>6ecaa89b-2d29-4a21-8013-75c154ee58f5</MediaSwitchObjectId>
<PhoneNumber>8675309</PhoneNumber>
<Active>false</Active>
</PagerDevice>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/pagerdevices/13cbf32e-dc58-4695-aaf0-9f3a027cdab7
</pre>

=== Creating SMS Devices ===

The required fields for creating an SMS Device are DisplayName, SmppProviderObjectId, and RecipientAddress. All other SMS Device fields are optional. Note that there must be an SMPP Provider configured on the system before you can create an SMS Device for Notification. If the SmppProviderObjectId field is not supplied or does not correspond to an SMPP Provider configured on the system, then an HTTP 400 error will be returned, with text explaining that the parameter is missing or cannot be found in the SmppProvider table.

The following is an example of a POST that creates an SMS Device with DisplayName="My New SMS Device", SmppProviderObjectId="60cd37e8-499c-43a3-b733-30f2640e5003", RecipientAdress="bob@xyz.com", and optional parameter SenderAddress="voicemail@xyz.com".

<pre>
POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/smsdevices

<SmsDevice>
<DisplayName>My New SMS Device</DisplayName>
<SmppProviderObjectId>60cd37e8-499c-43a3-b733-30f2640e5003</SmppProviderObjectId>
<RecipientAddress>bob@xyz.com</RecipientAddress>
<SenderAddress>voicemail@xyz.com</SenderAddress>
</SmsDevice>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/smsdevices/ac200457-284c-4951-b04a-4d76bd03235e
</pre>

=== Creating SMTP Devices ===

The required fields for creating an SMTP Device are DisplayName and SmtpAddress. All other SMTP Device fields are optional.

The following is an example of a POST that creates an SMTP Device with DisplayName="My New SMTP Device", SmtpAddress="sylvia@email.com", and optional parameter EventList="AllMessages".

<pre>
POST https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/smtpdevices

<SmtpDevice>
<DisplayName>My New SMTP Device</DisplayName>
<SmtpAddress>sylvia@email.com</SmtpAddress>
<EventList>AllMessage</EventList>
</SmtpDevice>
</pre>

The following is the response from the above POST request:

<pre>
201
Created
/vmrest/users/70c5d764-b2f3-498a-b16e-1a4d2a369dfa/notificationdevices/smtpdevices/233e4e41-4743-41e2-a2c1-4f6691a21599
</pre>

== Updating ==

A generic Notification Device resource is read-only, so Notification Devices cannot be updated. However, the four specialized Device resources are not read-only, so an API user can update the appropriate specialized Device resource.

The following is an example of a PUT request that modifies the FailDeviceObjectId of an existing Phone Device. The FailDeviceObjectId indicates which Notification Device to try if notification fails to the current device, which allows you to setup a chain of Notification Devices.

<pre>
PUT https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3

<PhoneDevice>
<FailDeviceObjectId>ac200457-284c-4951-b04a-4d76bd03235e</FailDeviceObjectId>
</PhoneDevice>
</pre>

The following is the response from the above PUT request:

<pre>
204
No Content
</pre>

Updating other types of specialized Device resources is very similar; simply do a PUT to the appropriate pagerdevice, smsdevice, or smtpdevice resource instead of a phonedevice resource.

== Deleting ==

A generic Notification Device resource is read-only, so Notification Devices cannot be deleted. However, the four specialized Device resources are not read-only, so an API user can delete the appropriate specialized Device resource, assuming its not one of the factory default Device resources (which are flagged as Undeletable).

The following is an example of a DELETE request that deletes an existing Phone Device:

<pre>
DELETE https://<connection-server>/vmrest/users/<UserObjectId>/notificationdevices/phonedevices/2e377eba-a924-434b-b967-bac3815551d3
</pre>

The following is the response from the above DELETE request:

<pre>
204
No Content
</pre>

== Explanation of Data Fields ==

The following chart lists all of the data fields available on Notification Devices, Phone Devices, Pager Devices, SMS Devices, and SMTP Devices. In the Device Types column, "Base" means the generic Notification Device resource. Note that on a GET to the generic Notification Device resource, you may receive data fields that are meaningless for a particular type of device, so these fields can be safely ignored.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Field Name
! Device Type
! Writable?
! Explanation / Comments
|-
| ObjectId
| All
| Read-only
| ObjectId of the Device
|-
| Type
| Base
| Read-only
| Auto-set during Create. 1=Phone, 2=Pager, 4=SMTP, 5=SMS
|-
| Active
| All
| Read/Write
| Factory default=false. For newly-created, default=true
|-
| AfterDialDigits
| Base, Phone, Pager
| Read/Write
| Extra-digits to dial after the Phone Number. Default=null
|-
| BusyRetryInterval
| Base, Phone, Pager
| Read/Write
| Time in minutes to wait between retries if Busy. Default=5
|-
| Conversation
| Base, Phone
| Read-only
| Auto-set during Create.
|-
| DetectTransferLoop
| Base, Phone
| Read/Write
| Flags if Transfer Loop Detection is Enabled. Default=false
|-
| DeviceName
| All
| Read/Write
| Friendly name for the Device type (not shown in CUCA or CPCA). Default="Other"
|-
| DialDelay
| Base, Phone, Pager
| Read/Write
| Time in seconds to wait after Connect before dialing AfterDialDigits (ignored if no AfterDialDigits). Default=1
|-
| DisplayName
| All
| Read/Write
| Friendly name for the Device like "Mobile Phone"
|-
| EventList
| All
| Read/Write
| Comma-delimited list of Events that trigger Notification (see below). Default=NewVoiceMail
|-
| FailDeviceObjectid
| All
| Read/Write
| ObjectId of next Notification Device to use if this one fails (to chain Notifications). Default=null
|-
| InitialDelay
| All
| Read/Write
| Time in minutes to wait after a Message is received before Notification is triggered. Default=0
|-
| MaxBody
| All
| Read/Write
| Maximum number of characters in the Body of a Notification message. Default=512
|-
| MaxSubject
| All
| Read/Write
| Maximum number of characters in the Subject of a Notification message. Default=64
|-
| MediaSwitchObjectId
| Base, Phone, Pager
| Read/Write
| ObjectId of the Phone System to use for the Dial-out.
|-
| PhoneNumber
| Base, Phone, Pager
| Read/Write
| Phone Number to dial to reach the Device.
|-
| PromptForId
| Base, Phone
| Read/Write
| Flags if the User must enter their ID to get the Notification message. Default=false
|-
| RecipientAddress
| SMS
| Read/Write
| Address of Message recipient
|-
| RepeatInterval
| All
| Read/Write
| Time in minutes to wait before re-notifying of messages. Default=0
|-
| RepeatNotify
| All
| Read/Write
| Flags if Notification process should begin for each newly arrived message. Default=false
|-
| RetriesOnBusy
| Base, Phone, Pager
| Read/Write
| Number of retry attempts if Busy. Default=4
|-
| RetriesOnRna
| Base, Phone, Pager
| Read/Write
| Number of retry attempts if RNA. Default=4
|-
| RetriesOnSuccess
| Base, Pager
| Read/Write
| Number of retry attempts if successful. Default=0
|-
| RingsToWait
| Base, Phone, Pager
| Read/Write
| Number of rings to wait for Connect before RNA. Default=4
|-
| RnaRetryInterval
| Base, Phone, Pager
| Read/Write
| Time in minutes to wait between retries if RNA. Default=5
|-
| ScheduleSetObjectId
| All
| Read/Write
| ObjectId of the ScheduleSet during which Notification may trigger. Default=AllHours
|-
| SendCallerId
| Base, Pager, SMS, SMTP
| Read/Write
| Flag to include CallerId in the Notification message. Default=true
|-
| SendCount
| Base, Pager, SMS, SMTP
| Read/Write
| Flag to include the message counts in the Notification message. Default=true
|-
| SenderAddress
| SMS
| Read/Write
| Address of Message sender. Default=null
|-
| SendPcaLink
| Base, SMTP
| Read/Write
| Flag to include a link to CPCA in the Notification message. Default=false
|-
| SmppProviderObjectId
| Base, SMS
| Read/Write
| ObjectId of the SMPP Provider
|-
| SmtpAddress
| Base, SMTP
| Read/Write
| SMTP address to send the Notification message to
|-
| StaticText
| Base, SMS, SMTP
| Read/Write
| Static text to include in the Notification Message. Default=null
|-
| SubscriberObjectId
| All
| Read-only
| ObjectId of the User
|-
| SuccessRetryInterval
| Base, Pager
| Read/Write
| Time in minutes to wait between retries if successful. Default=0
|-
| TransmitForcedAuthorizationCode
| Base, Phone, Pager
| Read/Write
| Flags if an authorization code should be sent to CUCM after the PhoneNumber is dialed. Default=false
|-
| Undeletable
| All
| Read-only
| Factory default=true. For newly-created, default=false
|-
| WaitConnect
| Base, Phone, Pager
| Read/Write
| Flags if need to wait for Connect before dialing AfterDialDigits. Default=true
|}

The EventList field is a comma-delimited list of Message types which could trigger Notification. It can contain any of the following values. Note that Calendar Appointments and Meetings are not included in the AllMessage or AllUrgentMessage categories, which just include voicemail, fax, and dispatch messages.

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Event Name
! Description
|-
| None
| No messages of any type or urgency
|-
| AllMessage
| All messages of all types and urgencies
|-
| AllUrgentMessage
| All urgent messages of all types
|-
| CalendarAppointment
| Calender appointments
|-
| CalendarMeeting
| Calendar meetings
|-
| DispatchMessage
| All dispatch messages
|-
| UrgentDispatchMessage
| All urgent dispatch messages
|-
| NewFax
| All fax messages
|-
| NewUrgentFax
| All urgent fax messages
|-
| NewVoiceMail
| All voicemail messages
|-
| NewUrgentVoiceMail
| All urgent voicemail messages
|}

[[Category:Cisco Unity Connection Provisioning Interface (CUPI) API]]

Cisco Unity Connection Provisioning Interface (CUPI) API -- Enabling Single Inbox Example

2010-12-13T22:34:03Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Class of Service (COS)

2010-12-13T22:32:39Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Changing Primary and Alternate Extensions

2010-12-13T22:31:26Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Changing Passwords and Password Settings

2010-12-13T22:30:54Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Alternate Names

2010-12-13T22:29:42Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Voice Names

2010-12-13T22:28:54Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Searching and Sorting

2010-12-13T22:27:42Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Getting the Object Count Without Getting the Objects

2010-12-13T22:26:48Z

Juliew:

Cisco Unity Connection REST API FAQ

2010-12-13T22:25:46Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Examples of Basic Operations

2010-12-13T22:25:06Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Error Handling

2010-12-13T22:24:02Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Authentication and Authorization

2010-12-13T22:23:29Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- About Versioning

2010-12-13T22:13:52Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API -- Index of All CUPI Documentation

2010-12-13T22:13:12Z

Juliew:

Cisco Unity Connection Provisioning Interface (CUPI) API

2010-12-13T22:12:44Z

Juliew: