Cisco Unity Connection Provisioning Interface (CUPI) API -- External Services

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


About External Services

This page contains information on how to use the API to create, list, modify, and delete Unified Messaging Services (also known as external services). When you create Unified Messaging Service Accounts, you base each account on a Unified Messaging Service. Creating a new Unified Messaging service is based on any one of the following:

  • Exchange/BPOS-D
  • MeetingPlace
  • Office 365


Listing External Services

Example 1

The following is an example of the GET request that lists the Unified Messaging Services:

 https://<connection_server>/vmrest/externalservices 

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

<ExternalServices total="3"><ExternalService>
 <URI>/vmrest/externalservices/6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78</URI>
 <ObjectId>6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78</ObjectId>
 <AuthenticationMode>1</AuthenticationMode>
 <DisplayName>UMS_API</DisplayName>
 <IsEnabled>true</IsEnabled>
 <SecurityTransportType>1</SecurityTransportType>
 <Server>10.65.156.190</Server>
 <ServiceAlias>clientteam\administrator</ServiceAlias>
 <ServicePassword/>
 <ServerType>4</ServerType>
 <SupportsCalendarCapability>true</SupportsCalendarCapability>
 <SupportsTtsOfEmailCapability>true</SupportsTtsOfEmailCapability>
 <ValidateServerCertificate>false</ValidateServerCertificate>
 <UseServiceCredentials>true</UseServiceCredentials>
 <SupportsMailboxSynchCapability>true</SupportsMailboxSynchCapability>
 <ExchDoAutodiscover>false</ExchDoAutodiscover>
 <ExchServerType>1</ExchServerType>
 <MailboxSynchFaxAction>1</MailboxSynchFaxAction>
 <MailboxSynchEmailAction>2</MailboxSynchEmailAction></ExternalService>
 <ExternalService><URI>/vmrest/externalservices/4ce278eb-033e-460e-a4f7 5a0cf57b3b2d</URI>
 <ObjectId>4ce278eb-033e-460e-a4f7-5a0cf57b3b2d</ObjectId>
 <DisplayName>Office_365</DisplayName>
 <IsEnabled>true</IsEnabled>
 <Server>10.65.156.190</Server>
 <ServiceAlias>clientteam\administrator</ServiceAlias>
 <ServicePassword/>
 <ServerType>5</ServerType>
 <SupportsCalendarCapability>true</SupportsCalendarCapability>
 <SupportsTtsOfEmailCapability>true</SupportsTtsOfEmailCapability>
 <ValidateServerCertificate>false</ValidateServerCertificate>
 <UseServiceCredentials>true</UseServiceCredentials>
 <SupportsMailboxSynchCapability>true</SupportsMailboxSynchCapability>
 <ExchDoAutodiscover>false</ExchDoAutodiscover>
 <MailboxSynchFaxAction>1</MailboxSynchFaxAction>
 <MailboxSynchEmailAction>2</MailboxSynchEmailAction>
 <ProxyServer/></ExternalService>
 <ExternalService><URI>/vmrest/externalservices/33dd7a5e-8c5e-479a-b6e3-7342c0470072</URI>
 <ObjectId>33dd7a5e-8c5e-479a-b6e3 7342c0470072</ObjectId>
 <DisplayName>Meeting_CUCA</DisplayName>
 <IsEnabled>true</IsEnabled>
 <Server>10.65.156.190</Server>
 <ServiceAlias>clientteam\administrator</ServiceAlias>
 <ServicePassword/>
 <ServerType>1</ServerType>
 <SupportsCalendarCapability>true</SupportsCalendarCapability>
 <SupportsMeetingCapability>true</SupportsMeetingCapability>
 <TransferExtensionDialString>111</TransferExtensionDialString>
</ExternalService>
</ExternalServices>

Response Code: 200 

JSON Example

The following is a JSON example of the GET request that lists the Unified Messaging Services:

 
GET https://<connection_server>/vmrest/externalservices
Accept : application /json
Connection : keep-alive

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

{   
  "@total": "3",   
  "ExternalService": [      
    {         
      "URI": "/vmrest/externalservices/6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78",         
      "ObjectId": "6f4f7023-e9e5-4cd0-bf55 e20a0be6fd78",         
      "AuthenticationMode": "1",
      "DisplayName": "UMS_API",         
      "IsEnabled": "true",         
      "SecurityTransportType": "1",         
      "Server": "10.65.156.190",         
      "ServiceAlias": "clientteam\\administrator",   
      "ServicePassword":[],         
      "ServerType": "4",         
      "SupportsCalendarCapability": "true",  
      "SupportsTtsOfEmailCapability": "true",   
      "ValidateServerCertificate": "false",
      "UseServiceCredentials": "true",  
      "SupportsMailboxSynchCapability": "true", 
      "ExchDoAutodiscover": "false",  
      "ExchServerType": "1",  
      "MailboxSynchFaxAction": "1", 
      "MailboxSynchEmailAction": "2", 
      "ExternalServiceResetURI": "/vmrest/externalservices/1cfe4c57-23f1-4807-8784-474760a0ee6e/reset"      
    },      
    {         
      "URI": "/vmrest/externalservices/4ce278eb-033e-460e-a4f7 5a0cf57b3b2d",         
      "ObjectId": "4ce278eb-033e-460e-a4f7-5a0cf57b3b2d",         
      "DisplayName": "Office_365",   
      "IsEnabled": "true", 
      "Server": "10.65.156.190",   
      "ServiceAlias": "clientteam\\administrator",  
      "ServicePassword":[],         
      "ServerType": "5",   
      "SupportsCalendarCapability": "true",   
      "SupportsTtsOfEmailCapability": "true",    
      "ValidateServerCertificate": "false",  
      "UseServiceCredentials": "true",    
      "SupportsMailboxSynchCapability": "true",      
      "ExchDoAutodiscover": "false",      
      "MailboxSynchFaxAction": "1",  
      "MailboxSynchEmailAction": "2",     
      "ProxyServer": []      
    },      
    {         
      "URI": "/vmrest/externalservices/33dd7a5e-8c5e-479a-b6e3-7342c0470072",         
      "ObjectId": "33dd7a5e-8c5e-479a-b6e3 7342c0470072",   
      "DisplayName": "Meeting_CUCA",     
      "IsEnabled": "true",      
      "Server": "10.65.156.190", 
      "ServiceAlias": "clientteam\\administrator",   
      "ServicePassword": [],
      "ServerType": "1",      
      "SupportsCalendarCapability": "true",  
      "SupportsMeetingCapability": "true",    
      "TransferExtensionDialString": "111",    
      "ExternalServiceResetURI": "/vmrest/externalservices/1cfe4c57-23f1-4807-8784-474760a0ee6e/reset"      
    }   
  ]
}

Response Code: 200

Example 2

The following is an example of another GET request that lists the Unified Messaging Service based on <externalservice-id>:

 https://<connection_server>/vmrest/externalservices/<objectId> 

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

<ExternalService>
 <URI>/vmrest/externalservices/6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78</URI>
 <ObjectId>6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78</ObjectId>
 <AuthenticationMode>1</AuthenticationMode>
 <DisplayName>UMS_API</DisplayName>
 <IsEnabled>true</IsEnabled>
 <SecurityTransportType>1</SecurityTransportType>
 <Server>10.65.156.190</Server>
 <ServiceAlias>clientteam\administrator</ServiceAlias>
 <ServicePassword/>
 <ServerType>4</ServerType>
 <SupportsCalendarCapability>true</SupportsCalendarCapability>
 <SupportsTtsOfEmailCapability>true</SupportsTtsOfEmailCapability>
 <ValidateServerCertificate>false</ValidateServerCertificate>
 <UseServiceCredentials>true</UseServiceCredentials>
 <SupportsMailboxSynchCapability>true</SupportsMailboxSynchCapability>
 <ExchDoAutodiscover>false</ExchDoAutodiscover>
 <ExchServerType>1</ExchServerType>
 <MailboxSynchFaxAction>1</MailboxSynchFaxAction>
 <MailboxSynchEmailAction>2</MailboxSynchEmailAction>
</ExternalService>
 Response Code: 200 

JSON Example

The following is a JSON example of the GET request that lists the particular Unified Messaging Service:

 
GET https://<connection_server>/vmrest/externalservices/<objectId>
Accept : application /json
Connection : keep-alive

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

{   
    "URI": "/vmrest/externalservices/6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78", 
    "ObjectId": "6f4f7023-e9e5-4cd0-bf55-e20a0be6fd78",   
    "AuthenticationMode": "1",  
    "DisplayName": "UMS_API", 
    "IsEnabled": "true",
    "SecurityTransportType": "1",  
    "Server": "10.65.156.190", 
    "ServiceAlias": "clientteam\\administrator", 
    "ServicePassword": [],  
    "ServerType": "4", 
    "SupportsCalendarCapability": "true",   
    "SupportsTtsOfEmailCapability": "true", 
    "ValidateServerCertificate": "false",   
    "UseServiceCredentials": "true",   
    "SupportsMailboxSynchCapability": "true",   
    "ExchDoAutodiscover": "false",   
    "ExchServerType": "1",   
    "MailboxSynchFaxAction": "1",   
    "MailboxSynchEmailAction": "2",   
    "ExternalServiceResetURI": "/vmrest/externalservices/1cfe4c57-23f1-4807-8784-474760a0ee6e/reset"
}
Response Code: 200

Adding Unified Messaging Service

This section contains information on how to create External Services:

  • Adding Exchange/BPOS-D External Service
  • Adding Meeting Place External Service
  • Adding Office 365 External Service

Adding Exchange/BPOS-D External Service

The following is an example of the POST request that adds the Exchange/BPOS-D Unified Messaging Service:

 https://<connection_server>/vmrest/externalservices 

The request parameters will depend upon the information given by you.

<ExternalService>
 <DisplayName>UMS_API</DisplayName>
 <ServiceAlias> client-team\administrator</ServiceAlias>
 <ServicePassword>Ecsbulab12</ServicePassword>
 <ServerType>4</ServerType> 
 <Server>10.65.156.190</Server>
 <AuthenticationMode>1</AuthenticationMode>
 <ExchServerType>1</ExchServerType>  
 <SecurityTransportType>1</SecurityTransportType>
</ExternalService>
 Response Code: 201 

JSON Example

The following is a JSON example of the POST request that adds the Exchange/BPOS-D Unified Messaging Service:

 
POST https://<connection_server>/vmrest/externalservices
Accept : application /json
Connection : keep-alive

The request parameters will depend upon the information given by you.

{   
   "DisplayName": "UMS_API",   
   "ServiceAlias": "client-team\\administrator",   "ServicePassword": "Ecsbulab12",   
   "ServerType": "4",   "Server": "10.65.156.190",   
   "AuthenticationMode": "1",   
   "ExchServerType": "1",   
   "SecurityTransportType": "1"
}
Response Code: 201

The following are the list of mandatory parameters required to create a Unified Messaging Service:

  • Display Name: The display name of the unified messaging service
  • Service Alias: The alias of the unified messaging service
  • Service Password: The password of the unified messaging service
  • Server Type: The type of unified messaging service account (Exchange/BPOS-D: 4)
  • Server: The IP address of the Exchange server
  • Authentication Mode: The web-based Authentication Mode of the Unified Messaging Service: Basic (1), Digest (2), and NTLM (3)
  • Exchange Server Type: The Exchange Server Type of the Unified Messaging Account: Exchange 2003 (0) and Exchange 2007/2010 (1)
  • Security Transport Type: The web-based protocol of the Unified Messaging Account: HTTP (0) and HTTPS (1)

Adding Meeting Place External Service

The following is an example of the POST request that adds the Meeting Place Unified Messaging Service:

 https://<connection_server>/vmrest/externalservices 

The request parameters will depend upon the information given by you.

<ExternalService>
 <DisplayName>MeetingPlace</DisplayName>
 <ServiceAlias> admin</ServiceAlias>
 <ServicePassword>ecsbulab</ServicePassword>
 <ServerType>1</ServerType>
 <Server>10.76.175.167</Server>
 <TransferExtensionDialString>111111</TransferExtensionDialString>
</ExternalService>
 Response Code: 201 

JSON Example

The following is a JSON example of the POST request that adds the Meeting Place Unified Messaging Service:

 
POST https://<connection_server>/vmrest/externalservices
Accept : application /json
Connection : keep-alive

</pre>

The request parameters will depend upon the information given by you.

{   
   "DisplayName": "MeetingPlace",   
   "ServiceAlias": "admin",   
   "ServicePassword": "ecsbulab",   
   "ServerType": "1",   
   "Server": "10.76.175.167",   
   "TransferExtensionDialString": "111111"
}
 Response Code: 201 


The following are the list of mandatory parameters required to create a Unified Messaging Service:

  • Display Name: The display name of the unified messaging service
  • Service Alias: The alias of the unified messaging service
  • Service Password: The password of the unified messaging service
  • Server Type: The type of unified messaging service account (Meeting Place: 1)
  • Server: The IP address of the Exchange server
  • TransferExtensionDialString: The digits that Cisco Unity Connection must dial to transfer users on the phone to the opening of the Cisco Unified Meeting Place Server.

Adding Office 365 External Service

The following is an example of the POST request that adds the Meeting Place Unified Messaging Service:

 https://<connection_server>/vmrest/externalservices 

The request parameters will depend upon the information given by you.

<ExternalService>
 <DisplayName>Office365</DisplayName>
 <ServiceAlias>admin</ServiceAlias>
 <ServicePassword>password</ServicePassword>
 <ServerType>5</ServerType>
 <Server>10.76.175.167</Server>
</ExternalService>
 Response Code: 201 

JSON Example

The following is a JSON example of the POST request that adds the Meeting Place Unified Messaging Service:

POST https://<connection_server>/vmrest/externalservices
Accept : application /json
Connection : keep-aliveSample 

The request parameters will depend upon the information given by you.

{   
   "DisplayName": "Office365",   
   "ServiceAlias": "admin",   
   "ServicePassword": "password",   
   "ServerType": "5",   
   "Server": "10.76.175.167"
}
 Response Code: 201 

The following are the list of mandatory parameters required to create a Unified Messaging Service:

  • Display Name: The display name of the unified messaging service
  • Service Alias: The alias of the unified messaging service
  • Service Password: The password of the unified messaging service
  • Server Type: The type of unified messaging service account (Office 365: 5)
  • Server: The IP address of the Exchange server

Modifying Unified Messaging Service

The following is an example of the PUT request that modifies the Unified Messaging Service represented by <externalserviceObject-id>:

 https://<connection_server>/vmrest/externalservices/<objectId> 

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

<ExternalService>
 <ServiceAlias> client-team\administrator</ServiceAlias>
 <ServicePassword>Ecsbulab13</ServicePassword>
 <ServerType>5</ServerType> 
 <Server>10.65.156.190</Server>
 <AuthenticationMode>1</AuthenticationMode>
 <ExchServerType>1</ExchServerType>  
 <SecurityTransportType>1</SecurityTransportType>
</ExternalService>
 Successful Response Code: 204 

JSON Example

The following is a JSON example of the PUT request that modifies the Unified Messaging Service represented by <externalserviceObject-id>:

 
PUT https://<connection_server>/vmrest/externalservices 
Accept : application /json 
Connection : keep-alive 

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

{   
    "ServiceAlias": "client-team\\administrator",   
    "ServicePassword": "Ecsbulab13",   
    "ServerType": "5",   "Server": "10.65.156.190",   
    "AuthenticationMode": "1",   
    "ExchServerType": "1",   
    "SecurityTransportType": "1"
}
 Response Code: 204 

Deleting Unified Messaging Service

The following is an example of the DELETE request that deletes a Unified Messaging Service as represented by < externalserviceobject-id >:

 https://<connection_server>/vmrest/usertemplates/externalservices/<objectId > 


The output for this request returns the successful response code.

 Response Code: 204 

Explanation of Data Fields

Parameter Operations Data Type Comments
ObjectId Read Only String(36) A globally unique, system-generated identifier for an external service object.
AuthenticationMode Read/Write The method of authentication used when authenticating via HTTP with the server hosting the service. Default value:0

Note: This field will be visible when server type is: Exchange()

DisplayName Read/Write string(64) A descriptive name for the external service.
ExchDoAutodiscover Read/Write Boolean Flag indicating whether Connection is permitted to search the network for the URL to log in each Exchange. 2007 or 2010 mailbox. Connection may use the Exchange Autodiscovery feature (which was first available in Exchange 2007) in combination with LDAP and DNS calls to identify the URL.

Possible values:

  • false: Do not use autodiscovery.
  • true: Use autodiscovery when needed.
  • Default value: false
ExchDoAutodiscover2003 Read/Write Boolean Select the versions of Exchange in which you have mailboxes that you want Cisco Unity Connection to be able to access..

Possible values:

  • false: . Exchange 2007 and/or 2010
  • true: Exchange 2003 2007 and/or 2010
  • Default value: false
ExchOrgDomain Read/Write String(255) Root of the domain to search for autodiscovery
ExchServerType Read/Write Integer Categorization of Microsoft Exchange server type.

Possible values:

  • 0: Exchange 2003
  • 1: Exchange 2007/2010Exchange2007
  • Default value: 0
ExchSite Read/Write String Name of the Exchange site to which to confine searches for domain controllers and Autodiscover servers.
IsEnabled Read/Write Boolean A flag indicating whether the external service is enabled.

Possible values:

  • false: The external service is disabled.
  • true: The external service is enabled.
  • Default value: false
LdapSecurityTransportType Read/Write Integer The method of encryption used for LDAP.

Possible values:

  • 0: No encryption
  • 1: SSL encryption
  • Default value: 0
LdapValidateServerCertificate Read/Write Boolean A flag indicating whether server certificates should be validated against a trust-certificate when establishing an LDAPS connection.

Possible values:

  • false or false: for LDAP connection
  • Default value: false
MailboxSynchEmailAction Read/Write Integer Action to take for incoming emails. Default value:2

Note: Applies only if mailbox synchronization is enabled.

MailboxSynchFaxAction Read/Write Integer Action to take for incoming FAX messages. Default value:1

Note: Applies only if mailbox synchronization is enabled.

ProxyServer Read/Write String(512) IP address or Hostname for Proxy Server
SecurityTransportType Read/Write Integer The method of encryption used for HTTP sessions to or from the external service.

Possible values:

  • 0: No encryption
  • 1: SSL encryption
  • Default value: 0
Server Read/Write String(255) The name of the server which hosts the external service.
ServerType Read Only Integer The type of external service. Examples are MeetingPlace 7.0, Exchange 2003, and Exchange 2007.
ServiceAlias Read/Write String(320) The unique text name (i.e., logon name) to use to logon to the external service.
ServicePassword Read/Write String(256) The password for logon to the external service.
SupportsCalendarCapability Read/Write Boolean A flag indicating whether the external service supports the capabilities to access calendar information such as appointments, information for free/busy based PCTR rules, and for Exchange servers only, the capability to import a user's contacts from Exchange

Possible values:

  • false: External service does not support calendar capability
  • true: External service supports calendaring capability
  • Default value: true
SupportsMailboxSynchCapability Read/Write Boolean A flag indicating whether the external service supports synchronizing mailbox contents between a Connection mailbox and an external, third-party mailbox.

Possible values:

  • false: External service does not support mailbox synchronization
  • true: External service supports mailbox synchronization
  • Default value: true
SupportsMeetingCapability Read/Write Boolean A flag indicating whether the external service supports the capability to access meeting information from a server. For example, allowing a user to receive notification of a meeting about ready to start, providing join meeting and cancel meeting capabilities on the server, and allowing a user to schedule a meeting on the server.

Possible values:

  • false: External service does not support meeting capability
  • true: External service supports meeting capability
  • Default value: true
SupportsTtsOfEmailCapability Read/Write Boolean A flag indicating whether the external service supports the capability to access an email store for the purpose of playing the email via TTS.

Possible values:

  • false: External service does not support TTS of email capability
  • true: External service supports TTS of email capability
  • Default value: true
TransferExtensionDialString Read/Write String(40) The number dialed by Unity Connection to access (join) the Cisco Unified MeetingPlacemeeting.
UseServiceCredentials Read/Write Boolean A flag indicating whether to use service credentials rather than user credentials to logon to the external service.

Possible values:

  • false: Use user credentials to logon to this external service
  • true: Use service credentials to logon to this external service
  • Default value: false
ValidateServerCertificate Read/Write Boolean A flag indicating whether server certificates should be validated against a trust-certificate when establishing an HTTPS connection.

Possible values:

  • false: No certificate validation
  • true: Validate certificate
  • Default value: false

Rating: 0.0/5 (0 votes cast)

Personal tools