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

From DocWiki

Jump to: navigation, search

Links to Other API pages: Cisco_Unity_Connection_APIs

CUPI Guide Contents
API Overview
Index of All CUPI Documentation

Contents


Unified Messaging Account API

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, Exchange 2007, Exchange 2010. 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 account

Listing all the Unified Messaging Accounts In the following example, the user has two unified messaging service accounts, Exchange2K3 and Exchange2K7.

GET https://<connection-server>/vmrest/user/externalserviceaccounts 

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

<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> 
Response Code: 200

JSON Example

GET https://<connection-server>/vmrest/user/externalserviceaccounts
Accept: application/json
Content-type: application/json
Connection: keep-alive 

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

{
  "URI": "/vmrest/user/externalserviceaccounts/510eeaa6-6e85-40f3-88b3-863c2a4eec84",
  "IsEnabled": "true",
  "UseServiceCredentials": "true",
  "LoginType": "0",
  "ObjectId": "510eeaa6-6e85-40f3-88b3-863c2a4eec84",
  "DisplayName": "Exchange2K3"
} 
Response Code: 200

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

Listing Details of Particular Unified Messaging Service Account To retrieve a specific unified messaging service account, use the GET method with the URI field from above as follows:

GET http://<connection-server>/vmrest/user/externalserviceaccounts/<unified-messaging-account-objectid> 
The following is the response from the above *GET* request and the actual response will depend upon the information given by you:
<UserExternalServiceAccount>
  <IsEnabled>true</IsEnabled>
  <UseServiceCredentials>false</UseServiceCredentials>
  <LoginType>2</LoginType>
  <UserId>fung</UserId>
  <ObjectId>75436abf-8784-450f-ac61-23a08be2c364</ObjectId>
  <DisplayName>Exchange2K7</DisplayName>
</UserExternalServiceAccount>
Response Code: 200

Updating the Unified Messaging Account

Some unified messaging service accounts use service credentials to sign in and 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 using a PUT method by using the unified messaging service account URI and a query parameter, _password_, as follows.

PUT https://<connection-server>/vmrest/user/externalserviceaccounts/<unified-messaging-account-objectid?password=<password> 

The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204 

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.

JSON Example

PUT https://<connection-server>/vmrest/user/externalserviceaccounts/<unified-messaging-account-objectid?password=<password>
Accept: application/json
Content-type: application/json
Connection: keep-alive 

The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204


Explanation of Data Fields:

Parameter Operations Data Type Comments
URI Read Only String URI of the Unified Messaging Account.
ObjectId Read Only String(36) Unique Identifier of the Unified Messaging Account.
IsEnabled Read Only Boolean A flag indicating whether the external service is enabled.

• false: The external service is disabled. • true: The external service is enabled. Default value: false.

UseServiceCredentials Read Only Boolean A flag indicating whether to use service credentials rather than user credentials to logon to the external service.

• true: Use service credentials • false: Use user credentials

LoginType Read Only Integer 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 .
DisplayName Read/Write String(64) The display name of the unified messaging service account.
UserId Read Only String The user ID to sign in to the unified messaging service account, if one is used

Rating: 0.0/5 (0 votes cast)

Personal tools