McDewey

Cisco Unity Connection Imaging Interface (CUII) API -- Error Handling 11 Possible Errors 11 Cisco Unity Connection Imaging Interface (CUII) API iv Contents

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

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

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

• 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

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

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

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

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

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

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

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

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