Document Metadata
Format: PDF
Title: Cisco Unity Connection Imaging Interface (CUII) API
Author: Unknown
Creator: DITA Open Toolkit
Page 1
Cisco Unity Connection Imaging Interface (CUII) API
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
Page 2
© 2019 Cisco Systems, Inc. All rights reserved.
Page 3
C O N T E N T S
Cisco Unity Connection Imaging Interface (CUII) API
1
C H A P T E R 1
Cisco Unity Connection Imaging Interface (CUII) API
1
Benefits
1
Technical Details
2
Getting Started
2
Other CUII Resources
2
Troubleshooting
2
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting the Message Status
3
C H A P T E R 2
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting the Message Status
4
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting Message Specific
Information
5
C H A P T E R 3
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting Message Specific
Information
5
Using CUII for Getting Message Specific Information
5
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII to View the Current MWI Status
7
C H A P T E R 4
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII to View the Current MWI Status
7
Cisco Unity Connection Provisioning Interface (CUPI) API -- Using CUII to Get the Current Status of
a Message
9
C H A P T E R 5
Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling
11
C H A P T E R 6
Cisco Unity Connection Imaging Interface (CUII) API
iii
Page 4
Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling
11
Possible Errors
11
Cisco Unity Connection Imaging Interface (CUII) API
iv
Contents
Page 5
C H A P T E R 1
Cisco Unity Connection Imaging Interface (CUII)
API
Links to Other API pages: Cisco Unity Connection APIs
• Cisco Unity Connection Imaging Interface (CUII) API, on page 1
Cisco Unity Connection Imaging Interface (CUII) API
Links to Other API pages: Cisco Unity Connection APIs
Benefits
The Cisco Unity Connection Imaging Interface (CUII) API provides the ability to view message state and
mailbox information visually using graphics icons. The CUII API allows users to view voice messages
information visually, which can be leveraged in a cross-functional environment and can be integrated with
other applications.
By using CUII, you can get the icon based representation for the following information:
• Unread messages count
• Urgent unread messages count
• Read messages count
• Urgent read messages count
• MWI status and the corresponding image
Note: All the above functions associated with CUII API support both the IPv4 and IPv6 addresses. However,
the IPv6 address works only when Connection platform is configured in Dual (IPv4/IPv6) mode.
For more information see the chapter "Adding or Changing the IPv6 Addresses of Cisco Unity Connection
Servers" at the following link
http://www.cisco.com/en/US/docs/voice_ip_comm/connection/9x/upgrade/guide/9xcucrug051.html.
Note: With Cisco Unity Connection 9.1(1), the single sign-on feature is enabled for all the Connection Rest
APIs. For more information, see the "Single Sign-On in Cisco Unity Connection" chapter in Security Guide
for Cisco Unity Connection 9.x
http://www.cisco.com/en/US/docs/voice_ip_comm/connection/9x/security/guide/9xcucsec061.html.
Cisco Unity Connection Imaging Interface (CUII) API
1
Page 6
Technical Details
CUII allows notification templates to dynamically display the information like MWI state, message count,
current state of a specific message (like read, unread, deleted) about a specific user's inbox and/or specific
message.
CUII is a REST-based interface that provides standard CRUD operations. The XML and JSON interfaces are
annotated with information about what is in them.
As a web-based interface, CUII 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 CUII API, the following hardware and software
requirement must be met:
Hardware
• For detailed hardware requirements, see the Cisco Unity Connection 9.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 CUII Resources
Additional information about CUII is also available on the Cisco Developer Network (link to CDN). Note,
however, that the documentation here on the DocWiki is the most up-to-date documentation available for
CUII.
To participate in the CUII forum, see the CUPI forum on CDN.
On the CUII page on CDN, you will also find links to the CUII WADL and CUII XML schema.
Troubleshooting
See the following for information on troubleshooting all Connection APIs:
Troubleshooting (applies to all Connection APIs)
The error handling for CUII APIs is same as it is done for CUPI API. For more information on how error
handling done in CUPI API, refer to Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling
Cisco Unity Connection Imaging Interface (CUII) API
2
Cisco Unity Connection Imaging Interface (CUII) API
Technical Details
Page 7
C H A P T E R 2
Cisco Unity Connection Imaging Interface (CUII)
API -- Using CUII for Getting the Message Status
Links to Other API pages: Cisco_Unity_Connection_APIs
GET https://<connection-server>/vmrest/mailbox/folders/inbox/<user-alias>/notification
The above request returns unread message count, unread urgent count, MWI status, and MWI image URL
for the INBOX folder. The following are the sample GET requests and responses. The values can differ
depending on the state of the mailbox. Note that for displaying correct behavior of MWI status and its
corresponding image, MWI must be configured properly in the system. If not configured properly, the default
value 'OFF' is returned, even if the unread messages are present in the mailbox.
Get Request
GET https://<connection-server>/vmrest/mailbox/folders/inbox/jsmith/notification
Response
<NotificationInformation>
<UnreadMsgCount>2</UnreadMsgCount>
<UnreadUrgentMsgCount>0</UnreadUrgentMsgCount>
<Mwi>ON</Mwi>
<MwiImageUrl>
/vmrest/mailbox/folders/inbox/jsmith/mwistatusimage
</MwiImageUrl>
<MsgState> </MsgState>
<MsgStateImageUrl> </MsgStateImageUrl>
</NotificationInformation>
Get Request
GET https://<connection-server>/vmrest/mailbox/folders/inbox/gjoseph/notification
Response
<NotificationInformation>
<UnreadMsgCount>4</UnreadMsgCount>
<UnreadUrgentMsgCount>2</UnreadUrgentMsgCount>
<Mwi>ON</Mwi>
<MwiImageUrl>
/vmrest/mailbox/folders/inbox/gjoseph/mwistatusimage
</MwiImageUrl>
<MsgState> </MsgState>
<MsgStateImageUrl> </MsgStateImageUrl>
</NotificationInformation>
Cisco Unity Connection Imaging Interface (CUII) API
3
Page 8
• Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting the Message Status,
on page 4
Cisco Unity Connection Imaging Interface (CUII) API -- Using
CUII for Getting the Message Status
Links to Other API pages: Cisco_Unity_Connection_APIs
GET https://<connection-server>/vmrest/mailbox/folders/inbox/<user-alias>/notification
The above request returns unread message count, unread urgent count, MWI status, and MWI image URL
for the INBOX folder. The following are the sample GET requests and responses. The values can differ
depending on the state of the mailbox. Note that for displaying correct behavior of MWI status and its
corresponding image, MWI must be configured properly in the system. If not configured properly, the default
value 'OFF' is returned, even if the unread messages are present in the mailbox.
Get Request
GET https://<connection-server>/vmrest/mailbox/folders/inbox/jsmith/notification
Response
<NotificationInformation>
<UnreadMsgCount>2</UnreadMsgCount>
<UnreadUrgentMsgCount>0</UnreadUrgentMsgCount>
<Mwi>ON</Mwi>
<MwiImageUrl>
/vmrest/mailbox/folders/inbox/jsmith/mwistatusimage
</MwiImageUrl>
<MsgState> </MsgState>
<MsgStateImageUrl> </MsgStateImageUrl>
</NotificationInformation>
Get Request
GET https://<connection-server>/vmrest/mailbox/folders/inbox/gjoseph/notification
Response
<NotificationInformation>
<UnreadMsgCount>4</UnreadMsgCount>
<UnreadUrgentMsgCount>2</UnreadUrgentMsgCount>
<Mwi>ON</Mwi>
<MwiImageUrl>
/vmrest/mailbox/folders/inbox/gjoseph/mwistatusimage
</MwiImageUrl>
<MsgState> </MsgState>
<MsgStateImageUrl> </MsgStateImageUrl>
</NotificationInformation>
Cisco Unity Connection Imaging Interface (CUII) API
4
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting the Message Status
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting the Message Status
Page 9
C H A P T E R 3
Cisco Unity Connection Imaging Interface (CUII)
API -- Using CUII for Getting Message Specific
Information
Links to Other API pages: Cisco_Unity_Connection_APIs
• Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting Message Specific
Information, on page 5
Cisco Unity Connection Imaging Interface (CUII) API -- Using
CUII for Getting Message Specific Information
Links to Other API pages: Cisco_Unity_Connection_APIs
Using CUII for Getting Message Specific Information
GET
https://<connection-server>/vmrest/mailbox/folders/inbox/<user-alias>/notification?messageid=<messageid
The above request returns the message specific information, that is message state and message state image
URL along with the unread count, unread urgent count, MWI status, MWI image URL for the INBOX folder.
The following is the sample response from the above GET request. The values can differ depending on the
state of the mailbox and the message. Note that for deleted, invalid, or non existing message IDs, the message
state is DELETED.
<NotificationInformation>
<UnreadMsgCount>2</UnreadMsgCount>
<UnreadUrgentMsgCount>0</UnreadUrgentMsgCount>
<Mwi>ON</Mwi>
<MwiImageUrl>
/vmrest/mailbox/folders/inbox/<user_alias>/mwistatusimage
</MwiImageUrl>
<MsgState>Unread</MsgState>
<MsgStateImageUrl>
/vmrest/mailbox/folders/inbox/<user_alias>/msgstateimage?messageid=<msgid>
</MsgStateImageUrl>
</NotificationInformation>
Cisco Unity Connection Imaging Interface (CUII) API
5
Page 10
Cisco Unity Connection Imaging Interface (CUII) API
6
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII for Getting Message Specific Information
Using CUII for Getting Message Specific Information
Page 11
C H A P T E R 4
Cisco Unity Connection Imaging Interface (CUII)
API -- Using CUII to View the Current MWI Status
Links to Other API pages: Cisco Unity Connection APIs
GET https://<connection-server>/vmrest/mailbox/folders/inbox/<user_alias>/mwistatusimage
The above request returns the image with respect to current MWI status of the mailbox. The MWI status can
be ON or OFF.
• Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII to View the Current MWI Status
, on page 7
Cisco Unity Connection Imaging Interface (CUII) API -- Using
CUII to View the Current MWI Status
Links to Other API pages: Cisco Unity Connection APIs
GET https://<connection-server>/vmrest/mailbox/folders/inbox/<user_alias>/mwistatusimage
The above request returns the image with respect to current MWI status of the mailbox. The MWI status can
be ON or OFF.
Cisco Unity Connection Imaging Interface (CUII) API
7
Page 12
Cisco Unity Connection Imaging Interface (CUII) API
8
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII to View the Current MWI Status
Cisco Unity Connection Imaging Interface (CUII) API -- Using CUII to View the Current MWI Status
Page 13
C H A P T E R 5
Cisco Unity Connection Provisioning Interface
(CUPI) API -- Using CUII to Get the Current Status
of a Message
GET
https://<connection-server>/vmrest/mailbox/folders/inbox/<user_alias>/msgstateimage?messageid=<msgid>
The above request returns the image with respect to current status of the message. The message state can be
read, unread, deleted, read urgent, or unread urgent.
Cisco Unity Connection Imaging Interface (CUII) API
9
Page 14
Cisco Unity Connection Imaging Interface (CUII) API
10
Cisco Unity Connection Provisioning Interface (CUPI) API -- Using CUII to Get the Current Status of a Message
Page 15
C H A P T E R 6
Cisco Unity Connection Imaging Interface (CUII)
API -- Error Handling
Links to Other API pages: Cisco_Unity_Connection_APIs
• Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling , on page 11
Cisco Unity Connection Imaging Interface (CUII) API -- Error
Handling
Links to Other API pages: Cisco_Unity_Connection_APIs
Possible Errors
The HTTP status codes themselves provide information about many typical errors. See the following list for
some of the status codes returned by CUII:
Troubleshooting
Cause
Description
Possible
Errors
As the error clearly specifies the
user does not have necessary
permissions to access the
information, so either provide
admin credentials or admin should
assign the user the necessary role.
The cause of this error can be that
the user credentials provided in the
request are not authorized to view
the information requested in the
API.
This means there has been
an error in authentication
and the response text will
have a "Not Authorized"
message.
401
This is actually not a problem.
The throttling is implemented to
save connection's tomcat server
from taking up multiple requests
which can cause issues in
memory, DB etc.
The cause of this error can be that
the connection server is processing
multiple simultaneous API requests
so it is not able to take up that
request at that particular time.
This means "Server Busy".
It signifies that the
connection server is busy
and cannot handle this
request at that time.
503
Cisco Unity Connection Imaging Interface (CUII) API
11
Page 16
Troubleshooting
Cause
Description
Possible
Errors
This error would contain the
details of the missing or incorrect
or error data in the response itself
as described above but for further
debugging the traces can be
analyzed.
The causes of this error can be that
the input data which is required for
processing the API request is either
incomplete or incorrect.
This means "Bad request".
The error signifies that the
data provided in the
request is not valid.
400
To troubleshoot this type of error,
one has to look into the stack trace
returned in the response, which
will clearly specify the exception.
For further debugging, one must
look into the traces for errors as
the errors are quite prominently
logged with a lot of details.
The causes of this error can be
multiple. Generally those are the
scenarios which should have been
handled in the application but not
done.
This means "Internal
Server Error". The error
signifies that there has
been an error while
processing the request and
this error is not handled by
the application.
500
Cisco Unity Connection Imaging Interface (CUII) API
12
Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling
Possible Errors