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

'''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 ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Basics, Voice Name, Greetings |Basics, Voice Name, Greetings ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Unified Messaging Accounts |Unified Messaging Accounts ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Alternate Devices |Alternate Devices ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Directory |Directory ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Enabling and Disabling Greetings |Enabling and Disabling Greetings ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Location |Location ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Private Lists |Private Lists ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- SMTP Proxy Addresses |SMTP Proxy Addresses ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- System Configuration |System Configuration ]]<br>[[Cisco Unity Connection Provisioning Interface (CUPI) API -- For End Users -- Transfer Options |Transfer Options ]]
|}

__TOC__


NOTE: This wiki page was written before we found out that there may not be any external service account that would require a user password. As of today (2010/05/06), this has not been confirmed, so I'm leaving this page as is. When it's time to officially publish this page, make sure to remove the sections on changing password if that information is indeed obsolete.

== About Unified Messaging Service Accounts ==

A user may have zero or more unified messaging service accounts (also known as external service accounts). Examples of these services include Cisco Unified MeetingPlace 8.0, Exchange 2003, and Exchange 2007. Using CUPI for End Users, a user can:

* Retrieve a list of its unified messaging service accounts,
* Retrieve one of its unified messaging service accounts, and
* Change the password for one of its unified messaging service accounts

== Listing and Viewing ==

To retrieve a list of unified messaging service accounts, use the GET method with URI _/vmrest/user/externalserviceaccounts_. In the following example, the user has two unified messaging service accounts, Exchange2K3 and Exchange2K7:

<pre>
GET http://<connection-server>/vmrest/user/externalserviceaccounts

200
OK
<?xml version="1.0" encoding="UTF-8"?>
<UserExternalServiceAccounts>
  <UserExternalServiceAccount>
    <URI>/vmrest/user/externalserviceaccounts/510eeaa6-6e85-40f3-88b3-863c2a4eec84</URI>
    <IsEnabled>true</IsEnabled>
    <UseServiceCredentials>true</UseServiceCredentials>
    <LoginType>0</LoginType>
    <ObjectId>510eeaa6-6e85-40f3-88b3-863c2a4eec84</ObjectId>
    <DisplayName>Exchange2K3</DisplayName>
  </UserExternalServiceAccount>
  <UserExternalServiceAccount>
    <URI>/vmrest/user/externalserviceaccounts/75436abf-8784-450f-ac61-23a08be2c364</URI>
    <IsEnabled>true</IsEnabled>
    <UseServiceCredentials>false</UseServiceCredentials>
    <LoginType>2</LoginType>
    <UserId>fung</UserId>
    <ObjectId>75436abf-8784-450f-ac61-23a08be2c364</ObjectId>
    <DisplayName>Exchange2K7</DisplayName>
  </UserExternalServiceAccount>
</UserExternalServiceAccounts>
</pre>

For each unified messaging service account, CUPI returns the following information:

* '''URI''' - The URI for retrieving the unified messaging service account
* '''IsEnabled''' - A flag to indicate whether the unified messaging service account is enabled
* '''UseServiceCredentials''' - A flag to indicate whether service credentials or user credentials are used to sign in the unified messaging service account
* '''LoginType''' - A flag to indicate whether the user alias (0), a guest account (1), or a specified user ID (2) is used to sign in the account
* '''UserId''' - The user ID to sign in to the unified messaging service account, if one is used
* '''ObjectId''' - The unique ID of the unified messaging service account
* '''Display Name''' - The display name of the unified messaging service account

To retrieve a specific unified messaging service account, use the GET method with the URI field from above as follows:

<pre>
GET http://<connection-server>/vmrest/user/externalserviceaccounts/75436abf-8784-450f-ac61-23a08be2c364

200
OK
<?xml version="1.0" encoding="UTF-8"?>
<UserExternalServiceAccount>
  <IsEnabled>true</IsEnabled>
  <UseServiceCredentials>false</UseServiceCredentials>
  <LoginType>2</LoginType>
  <UserId>fung</UserId>
  <ObjectId>75436abf-8784-450f-ac61-23a08be2c364</ObjectId>
  <DisplayName>Exchange2K7</DisplayName>
</UserExternalServiceAccount>
</pre>

Some unified messaging service accounts use service credentials to sign in; others employ user-supplied credentials. This is indicated by the _UseServiceCredentials_ field. For unified messaging service accounts that require user credentials for signing in (for example, those with _UseServiceCredentials_ set to false), the user may specify the password via a PUT method by using the unified messaging service account URI and a query parameter, _password_, as follows:

<pre>
PUT https://<connection-server>/vmrest/user/externalserviceaccounts/75436abf-8784-450f-ac61-23a08be2c364?password=abc123

204
No Content
null
</pre>

Note that if you attempt to specify the password of a unified messaging service account that does not require a user password (for example, one where _UseServiceCredentials_ is set to true), an error will be returned.


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