BRKCDN-1106

Cisco in the real world:

Making use of Cisco Unity
Connection APIs
Heath Ward
Technical Marketing Engineer
July 2011
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 2
By the end of the session you should be able to:
Demonstrate basic REST API knowledge (product independent)
Describe different API services available to you on Unity Connection 8.x+
Demonstrate a basic application using CUPI, CUMI, CUTI
Understand how to download the WADL and XML schemas for use in applications
Explain the importance of and use of the Cisco Developer Network


Objectives
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 3
Representational State Transfer
REST
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 4
HTTP Basically text communication over an IP port
HTTP headers are a big part of a RESTful web service by identifying the resource and
the method (GET, PUT, POST, DELETE)
The first line is the request line that identifies the HTTP method, the resource and the
protocol
HTTP method comes first, one of: GET, PUT, POST, DELETE
Example: GET /vmrest/users HTTP/1.1
Content-Type defines the content of the HTTP payload (what comes after the headers)
Example: Content-Type: application/json
Commonly used content types in our API: application/xml, application/json or audio/wav
Accept tells the server what kind of output the client wants as output
Authorization gives the server the users credentials
Example: Authorization: BASIC Y2NtYWRtaW5pc3RyYXRvcjplY3NidWxhYg==
The last part of the authorization string is a base64 encoded username and password
Lots of other headers, but these are the big ones used in handling an API request

Basic REST
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 5
Authentication and Authorization
API uses the same authentication and authorization scheme that the administration
console uses: what objects a user has access to once authenticated are determined
by the roles assigned to the user.
API authenticates using standard HTTPS and Basic authentication, so the credentials
can be passed using the mechanisms typically used to send username/password via
HTTP headers.

Basic REST cont.
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 6
Demo Authorization
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 7
Connection API Services
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 8
Full support for users, distribution lists, and contacts
Batch support for adding, deleting, and modifying users
Read-only access to system configuration information
CUPI Provisioning Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 9
Basic User Information
A view of a subset of the User fields that an administrator can access
GET /vmrest/user
Voice Name
Allows end users to get the audio that is their recorded voice name and to change the
audio
GET /vmrest/user/voicename
PUT /vmrest/user/voicename
PUT takes audio/wav data as the HTTP content
CUPI Provisioning Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 10
To Read a users info:
GET http://<connection-server>/vmrest/users/{objectid}
To Create a user:
POST http://<connection-server>/vmrest/users?templateAlias=voicemailusertemplate <?xml
version="1.0" encoding="UTF-8" standalone="yes"?> <User> <Alias>jdoe</Alias>
<DtmfAccessId>7890</DtmfAccessId> </User> 201 Created (URL to created object will be
returned as body and in "Location:" header)
To Modify a user:
PUT http://<connection-server>/vmrest/users/{objectid} <?xml version="1.0" encoding="UTF-8"
standalone="yes"?> <User> <DisplayName>johnd</DisplayName> </User> 204 Accepted
To Delete a user:
DELETE http://<connection-server>/vmrest/users/{objectid} 200 OK
To Search for a user:
GET http://<connection-server>/vmrest/users?query=(alias%20startswith%20ab)
CUPI Provisioning Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 11
Demo CUPI
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 12
Interface for accessing voicemail on Unity Connection systems.
Based on standard HTTPS and XML to be consistent with other VTG
APIs currently under development.
CUMI provides full access to a users messages, including broadcast
messages.
CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 13
The root of the messaging API is the "Mailbox" resource that is
associated with each user. This contains some general information
about the Users's mailbox, and also contains a "Folders" resource
that has a list of the folders for the mailbox. This list is currently fixed,
although it's possible folders may be added in the future.

CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 14
Doing a GET on the mailbox will return properties of the mailbox itself (quotas, etc) as well a link to
the Folders element for the mailbox.
The folder list is fixed, but to get a list of them a GET on folders will return the list:
GET /vmrest/mailbox/folders
A Folder consists of a small set of properties (name, message count) and a collection of Messages.
So doing a GET on a folder returns a small folder resource object and a reference to it's list of
Messages:
<Folder>
<DisplayName></DisplayName>
<MessageCount></MessageCount>
</Folder>
Doing a GET on <folder>/messages returns a message list:
<Messages>
<Message>
...
</Message>
<Message>
...
</Message>
...
</Messages>


CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 15
HTTP requests for Messages differ by folder, so they are listed here
separately for each folder:
inbox/messages
GET Returns read and unread messages that are not drafts or deleted messages.
PUT Can be used to update the message subject only.
DELETE Depending on system settings either removes message or moves to folder "deleted".
POST?method=accept - Causes a dispatch message to be accepted (see below).
POST?method=reject - Causes a dispatch message to be rejected (see below).
deleted/messages
GET - Returns list of deleted messages (if system is set to "soft" delete - otherwise will always be empty).
DELETE - Removes message from deleted folder (i.e. does a "hard" delete).
POST?method=empty - Empties the deleted folder (removes permanently all messages within).
POST?method=undelete - Undeletes the specified message.
sent/messages
GET - Returns a list of recently sent messages.
DELETE - Deletes a message from the sent list. If the message has not yet been opened by the recipient, this
will effectively "cancel" the message (recipient will never get it).
CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 16
Offset and Limit
Each of the folders will accept the parameters "pagenumber" and "rowsperpage" to
specify which messages to retrieve:
/vmrest/mailbox/folders/inbox/messages?pagenumber=1&rowsperpage=10
Sorting
Initially server side sorting will be limited to what can be done efficiently by the
database, and will default to sorting by placing new messages first followed by read
messages, and sorted within each by ArrivalTime.
Sorting is controlled via "sortkey" and "sortorder" parameters, although initially only
the following sort orders will be supported by the server:
Newest first - no parameters (default) or sortkey=arrivaltime&sortorder=descending
Oldest first - sortkey=arrivaltime&sortorder=ascending
Urgent first - sortkey=priority&sortorder=descending
CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 17
Filtering
Filtering can be done on the folders by read, priority, voice, fax and dispatch.
read={true|false}
priority={urgent|normal|low}
dispatch={true|false}
type={voice|fax|email|receipt}
To get a list of unheard voice messages: GET
/vmrest/mailbox/folders/inbox/messages?read=false&type=voice
To get a list of unheard urgent messages: GET
/vmrest/mailbox/folders/inbox/messages?read=false&priority=urgent
To get a list of saved (deleted) messages: GET
/vmrest/mailbox/folders/deleted/messages
CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 18
The Message resource is what you might think of as a message
"header" or "envelope". It's a small description of the message (from,
to, time, etc.) so that loading a list of them is efficient, and the actual
message content is provide in the form of links to one or more
attachments.
The recipient list is also provide by a link since there is no fixed limit
on the number of recipients a message can have. Because of that,
loading recipients into the Message resource itself could then have a
big impact on performance.
Non-delivery receipts (NDRs) will have one additional child resource:
FailedRecipients that will include a Recipient URI and a failure status
code.

CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 19
Sending Messages - A message can be sent by a POST request to
the root URI for messages. The content of the request is be
"multipart/form-data". There must be two pieces of data in the request
in the following order:
A message in either "application/xml" or "application/json" format
A list of recipients
Audio data as "audio/wav
When sending a message, the following fields can be set:
Dispatch, secure, priority, sensitivity, read receipt requested, delivery receipt
requested. Only a few fields on a received message can be modified: Priority,
Subject, Read.
Although a Message may appear in a folder it will always be available
via a unique id:
/vmrest/mailbox/messageid

CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 20
Addressing in CUMI consists of a lookup method that will return a list
of addresses matching a specified name or beginning of name:
URI: GET /mailbox/addresses?name=<full or partial name>
GET Returns an Addresses resource that lists all of the matched names (up to a
maximum of 100).
The name can be a whole or beginning of the first name, last name, display name, or
alias. It will match distribution lists, personal distribution lists, contacts, and users.
As a quick example, to search for the user "Alexander Bell" the name
could be any of the following:
name=abell
name=alexander
name=alex
name=bell
name=bel
name=alexander be
name=alex be
CUMI Messaging Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 21
Demo CUMI
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 22
Telephony interface that allows a client to manage calls using a
Connection server.
A second part of the CUTI interface allows an established call to play
and record audio content over the phone.
CUTI Telephony Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 23
Make a call, check call connected status and hang up. The
Call object is used to convey information about a call (see API
XSD's).
When making a call, the fields used are:
Number - the only field that does not have a default value. User's with the
system administrator role can call any number, but end users can only call
numbers that don't violate their associated call restriction table based on
their class of service
maximumRings - defaults to 4.
mediaSwitchObjectId - for end users defaults to the phone system
associated with the user. For users that do not have an associated phone
system (e.g. administrators), the phone system marked as the default TRAP
phone system is used.
Once a call has been placed, a client can get server
information about the call, most importantly the connected
status.
CUTI Telephony Interface
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 24
Demo CUTI
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 25
Q&A
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 26
Cisco Developers Network
http://developer.cisco.com/web/cupi
http://developer.cisco.com/web/cumi
http://developer.cisco.com/web/cuti
Unity Connection Reference Material
http://www.cisco.com/en/US/products/ps6509/tsd_products_support_series_home.ht
ml
Unity Connection Mailer
cs-unity@cisco.com
Cisco Unity Tools
http://www.ciscounitytools.com/
References
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 27
Visit the Cisco Store for
Related Titles
http://theciscostores.com

2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 28
Receive 25 Cisco Preferred Access points for each session evaluation
you complete.
Give us your feedback and you could win fabulous prizes. Points are
calculated on a daily basis. Winners will be notified by email after
July 22nd.
Complete your session evaluation online now (open a browser
through our wireless network to access our portal) or visit one of the
Internet stations throughout the Convention Center.

Dont forget to activate your Cisco Live and Networkers Virtual
account for access to all session materials, communities, and on-
demand and live activities throughout the year. Activate your account
at any internet station or visit www.ciscolivevirtual.com.


Complete Your Online
Session Evaluation
Thank you.
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 31
Segue Slide
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 32
Bullet place holder
Bullet place holder

Bullet Slide Option 1
Comparison Column Chart
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 33
0
1
2
3
4
5
6
Category 1 Category 2 Category 3 Category 4
Series 1 Series 2 Series 3
Heavy Column Chart
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 34
0
1
2
3
4
5
Category 1 Category 2 Category 3 Category 4
Series 1
Series 2
Series 3
Series 4
Series 5
Series 6
Line Chart
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 35
0
1
2
3
4
5
6
Category 1 Category 2 Category 3 Category 4
Series 1
Series 2
Series 3
Series 4
Series 5
Series 6
Series 7
Pie
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 36
Category 1
Category 2
Category 3
Category 4
Category 1
Category 2
Category 3
Category 4
Table
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 37
Header Header Header Header Header
Data 500 400 300 200
Data 100 200 300 400
Data 500 400 300 200
Data 100 200 300 400
Data 500 400 300 200
Data 100 200 300 400
Pantone1665
R 243
G 112
B 33
Pantone3005
R 22
G 138
B 203
Pantone382
R 190
G 214
B 0
Pantone137
R 255
G 161
B 0
Pantone306
R 0
G 185
B 228
Pantone247
R 177
G 5
B 157
Pantone
Cool Gray 7
R 154
G 155
B 156
Primary Color Palette
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 38
Pantone164
R 248
G 156
B 92
Pantone2935
R 22
G 91
B 187
Pantone373
R 208
G 235
B 138
Pantone7509
R 217
G 172
B 109
Pantone325
R 99
G 206
B 202
Pantone2592
R 143
G 35
B 179
Pantone
Cool Gray 4
R 188
G 189
B 188
Pantone
Cool Gray 2
R 213
G 214
B 210
Secondary Color Palette
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 39
Editable Graphic Elements
25% Scale
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 40
2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 42
Visit the Cisco Store for
Related Titles
http://theciscostores.com

2011 Cisco and/or its affiliates. All rights reserved. Cisco Confidential 43
Receive 25 Cisco Preferred Access points for each session evaluation
you complete.
Give us your feedback and you could win fabulous prizes. Points are
calculated on a daily basis. Winners will be notified by email after
July 22nd.
Complete your session evaluation online now (open a browser
through our wireless network to access our portal) or visit one of the
Internet stations throughout the Convention Center.

Dont forget to activate your Cisco Live and Networkers Virtual
account for access to all session materials, communities, and on-
demand and live activities throughout the year. Activate your account
at any internet station or visit www.ciscolivevirtual.com.


Complete Your Online
Session Evaluation
Thank you.