Cisco Unity Connection Provisioning Interface (CUPI) API -- HTTPS(S) APIs

From DocWiki

(Difference between revisions)
Jump to: navigation, search
(Listing of HTTPS Links)
(Viewing of HTTP(S) Links)
Line 220: Line 220:
|}
|}
-
== Viewing of HTTP(S) Links ==
+
== Viewing of HTTPS Links ==
-
Administrator can use this API to fetch the information related to a particular HTTP(S) link in an HTTP(S) network.
+
Administrator can use this API to fetch the information related to a particular HTTPS link in an HTTPS network.
-
The following is an example of the GET request that displays the details of a specific HTTP(S) link associated with the httpsLinkObjectid provided:
+
The following is an example of the GET request that displays the details of a specific HTTPS link associated with the httpsLinkObjectid provided:
<pre>
<pre>
Line 297: Line 297:
</pre>
</pre>
-
Note: LocationBaseURLSub (representing the feed URL of the subscriber) is displayed only if the joined Unity Connection location is a cluster.
+
'''Note:''' LocationBaseURLSub (representing the feed URL of the subscriber) is displayed only if the joined Unity Connection location is a cluster.
'''Explanation of Data Fields'''
'''Explanation of Data Fields'''
Line 390: Line 390:
*0-false
*0-false
*1-true
*1-true
-
Note: This option cannot be disabled once enabled.
+
'''Note:''' This option cannot be disabled once enabled.
|}
|}

Revision as of 04:02, 4 November 2013

Links to Other API pages: Cisco_Unity_Connection_APIs

CUPI Guide Contents
API Overview
Index of All CUPI Documentation

Contents


About HTTPS Networking

In Cisco Unity Connection 10.0(1) and later, the administrator can use the CUPI APIs for listing, viewing, creating, and deleting HTTPS Link. Administrator can use these API for performing operations on Cisco Unity Connection locations joined in the HTTPS network.

Listing of HTTPS Links

Administrator can use this API to fetch the information related to the Cisco Unity Connection locations joined in the HTTPS network. The following is an example of the GET request that fetches the information related to the locations joined in an HTTPS network.

   
GET https://<connection-server>/vmrest/httpslinks/

The following is an example of response from the above *GET* request and the actual result will depend upon the information that has been provided by you:

200
ok
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 <HttpsLinks total="1">
  <HttpsLink>
   <URI>/vmrest/httpslinks/25164390-ec93-4dac-804a-c4567618b008</URI> 
   <AcceptCertificateErrors>false</AcceptCertificateErrors>
   <AcceptSelfSignedCertificates>true</AcceptSelfSignedCertificates>
   <BaseFeedURL>https:// qa-ks-vm-454.cisco.com/feeder</BaseFeedURL> 
   <DisplayName> qa-ks-vm-454</DisplayName> 
   <LastUsn>399</LastUsn> 
   <MaxUsn>399</MaxUsn> 
   <ObjectCount>6</ObjectCount> 
   <ObjectId>25164390-ec93-4dac-804a-c4567618b008</ObjectId> 
   <Status>0</Status> 
   <TimeOfLastFailure>2013-01-31T21:54:21Z</TimeOfLastFailure> 
   <TimeOfLastSync>2013-02-11T16:28:04Z</TimeOfLastSync> 
   <UseSSL>true</UseSSL> 
   <VoiceNameSyncStatus>0</VoiceNameSyncStatus> 
   <SyncDistributionLists>false</SyncDistributionLists>
   <Deleted>false</Deleted> 
   <LocationBaseURLSub>https:// qa-ks-vm-483.cisco.com/feeder</ LocationBaseURLSub>
   <DirectorySynchronizationRole>0</DirectorySynchronizationRole> 
   <WarningMode>false</WarningMode> 
  </HttpsLink>
 </HttpsLinks>

JSON Example

To list the Unity Connection locations joined in an HTTPS network:

GET https://<connection-server >/vmrest/httpslinks/
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:

200
ok
{
 "@total": "1",
 "HttpsLink":    
 {
  "URI": "/vmrest/httpslinks/d06ace70-645d-4763-9a46-6286ac371f1a",
  “AcceptCertificateErrors”:”false”,
  “AcceptSelfSignedCertificates”:”true”,
  "BaseFeedURL": "https:// qa-ks-vm-482.cisco.com/feeder",
  "DisplayName": " qa-ks-vm-482",
  "LastUsn": "114",
  "MaxUsn": "114",
  "ObjectCount": "8",
  "ObjectId": "d06ace70-645d-4763-9a46-6286ac371f1a",
  "Status": "0",
  “TimeOfLastFailure”: “013-01-31T21:54:21Z”,
  "TimeOfLastSync": "2013-03-08T10:21:26Z",
  "UseSSL": "true",
  "VoiceNameSyncStatus": "0",
  “SyncDistributionLists”:”false”,
  "Deleted": "false",
  “LocationBaseURLSub”: “https:// qa-ks-vm-483.cisco.com/feeder”,
  "DirectorySynchronizationRole": "0",
  "WarningMode": "false"
 }
}

Note: LocationBaseURLSub tag (representing the feed url of the subscriber) is displayed only if the joined Unity Connection location is a cluster.

Explanation of Data Fields
The following chart lists the data fields:

Parameter Data Type Operations Description
AcceptCertificateErrors Boolean Read/write If true Cisco Unity Connection ignore any problems with the SSL certificate of the network link
AcceptSelfSignedCertificates Boolean Read/Write If true allow the remote location to use a self-signed certificate to negotiate SSLwith the network link.
URI String Read-Only URI of HTTPS Link
BaseFeedURL varchar Read-Only Specifies the URL used by reader to fetch the information about directory and voice name.
DisplayName nvarchar Read/Write Specifies the display name of the network link.
LastUsn bigint Read-Only Specifies the last USN synched.
MaxUsn bigint Read-Only Specifies the maximum USN received in feed response.
ObjectCount int Read-Only Specifies a count of objects synchronized by the local Unity Connection location from the network link.
ObjectId char Read-Only Acts as a primary key for the API. The ObjectID is a unique system-generated identifier for an HTTPS link object.
Status smallint Read-Only Indicates the status of the directory synchronization with the network link.

Values can be:

  • 0-Idle
  • 1-synching
TimeOfLastFailure datetime Read-Only Reflects the time at which the last error had occurred while synchronizing with the network link.
TimeOfLastSync datetime Read-Only Reflects the time at which the network link was last synchronized.
UseSSL boolean Read/Write Controls whether or not SSL will be used when communicating with the network link.
VoiceNameSyncStatus smallint Read-Only Indicates the status of voice name synchronization with the network link

Values can be:

  • 0- Idle
  • 1- Synching
SyncDistributionLists Boolean Read/write Allow replication of system distribution lists and their memberships.

Values can be:

  • 0- false
  • 1- true

Note: This option cannot be disabled once enabled.

Deleted boolean Read-Only Indicates whether the network link has been marked for deletion.

Values can be:

  • 0- false
  • 1- true
DirectorySynchronizationRole smallint Read-Only Specifies the directory synchronization mode of the network link in the cluster.

Values can be:

  • 0- Standard
  • 1- Alert
LocationBaseURLSub nvarchar Read-Only Specifies the feeder URL for subscriber machine used by reader to fetch the directory information.
WarningMode boolean Read-Only Indicates whether or not the synchronization from the network is in warning mode.

Values can be:

  • 0- false
  • 1- true

Viewing of HTTPS Links

Administrator can use this API to fetch the information related to a particular HTTPS link in an HTTPS network. The following is an example of the GET request that displays the details of a specific HTTPS link associated with the httpsLinkObjectid provided:

GET: https://<connection-server>/vmrest/httpslinks/<httpsLinkObjectid>

The following is an example of the response from the above *GET* request and the actual response will depend upon the information has been provided by you.

200
ok
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <HttpsLink>
  <URI>/vmrest/httpslinks/25164390-ec93-4dac-804a-c4567618b008</URI>
  <AcceptCertificateErrors>false</AcceptCertificateErrors>
  <AcceptSelfSignedCertificates>true</AcceptSelfSignedCertificates>
  <BaseFeedURL>https://qa-ks-vm-454.cisco.com/feeder</BaseFeedURL>
  <DisplayName>qa-ks-vm-454</DisplayName>
  <LastUsn>399</LastUsn>
  <MaxUsn>399</MaxUsn>
  <ObjectCount>6</ObjectCount>
  <ObjectId>25164390-ec93-4dac-804a-c4567618b008</ObjectId>
  <Status>0</Status>
  <TimeOfLastFailure>2013-01-31T21:54:21Z</TimeOfLastFailure>
  <TimeOfLastSync>2013-02-11T16:28:04Z</TimeOfLastSync>
  <UseSSL>true</UseSSL>
  <VoiceNameSyncStatus>0</VoiceNameSyncStatus>
  <SyncDistributionLists>false</SyncDistributionLists>
  <Deleted>false</Deleted>
  <LocationBaseURLSub>https://qa-ks-vm-455.cisco.com/feeder</LocationBaseURLSub>
  <DirectorySynchronizationRole>0</DirectorySynchronizationRole>
  <WarningMode>false</WarningMode>
 </HttpsLink>

JSON Example

To view a particular HTTPS link:

GET https://<connection-server >/vmrest/httpslinks/<httpsLinkObjectId>
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:

200
ok
{
 URI": "/vmrest/httpslinks/d06ace70-645d-4763-9a46-6286ac371f1a",
 “AcceptCertificateErrors”:”false”,
 “AcceptSelfSignedCertificates”:”true”,
 "BaseFeedURL": "https:// qa-ks-vm-482.cisco.com/feeder",
 "DisplayName": " qa-ks-vm-482",
 "LastUsn": "114",
 "MaxUsn": "114",
 "ObjectCount": "8",
 "ObjectId": "d06ace70-645d-4763-9a46-6286ac371f1a",
 "Status": "0",
 “TimeOfLastFailure”: “013-01-31T21:54:21Z”,
 "TimeOfLastSync": "2013-03-08T10:21:26Z",
 "UseSSL": "true",
 "VoiceNameSyncStatus": "0",
 “SyncDistributionLists”:”false”,
 "Deleted": "false",
 “LocationBaseURLSub”: “https:// qa-ks-vm-483.cisco.com/feeder”,
 "DirectorySynchronizationRole": "0",
 "WarningMode": "false"
}

Note: LocationBaseURLSub (representing the feed URL of the subscriber) is displayed only if the joined Unity Connection location is a cluster.

Explanation of Data Fields
The following chart lists the data fields:

Parameter Data Type Operations Description
AcceptCertificateErrors Boolean Read/write If true Cisco Unity Connection ignore any problems with the SSL certificate of the network link.
AcceptSelfSignedCertificates Boolean Read/Write If true allow the remote location to use a self-signed certificate to negotiate SSLwith the network link.
URI String Read-Only URI of HTTPS Link
BaseFeedURL varchar Read-Only Specifies the URL used by reader to fetch the information about directory and voice name.
DisplayName nvarchar Read/Write Specifies the display name of the network link.
LastUsn bigint Read-Only Specifies the last USN synched.
MaxUsn bigint Read-Only Specifies the maximum USN received in feed response.
ObjectCount int Read-Only Specifies a count of objects synchronized by the local Unity Connection location from the network link.
ObjectId char Read-Only Acts as a primary key for the API. The ObjectID is a unique system-generated identifier for an http(s) link object.
Status smallint Read-Only Indicates the status of the directory synchronization with the network link..

Values can be:

  • 0-Idle
  • 1-synching
TimeOfLastFailure datetime Read-Only Reflects the time at which the last error had occurred while synchronizing with the network link..
TimeOfLastSync datetime Read-Only Reflects the time at which the network linkwas last synchronized.
UseSSL boolean Read/Write Controls whether or not SSL will be used when communicating with the network link.
VoiceNameSyncStatus smallint Read-Only Indicates the status of voice name synchronization with the network link

Values can be:

  • 0-Idle
  • 1-Synching
SyncDistributionLists Boolean Read/write Allow replication of system distribution lists and their memberships.

Values can be:

  • 0-false
  • 1-true

Note: This option cannot be disabled once enabled.

Creating the HTTPS Link

Administrator can use this API to add a Unity Connection server to an HTTPS network. The mandatory fields for creating HTTPS link are:

  • RemoteServer
  • RemoteUsername
  • RemotePassword

The following is an example of the POST request that joins the specified Unity Connection location with the network:

POST: https://<connection-server>/vmrest/httpslinks/operation/autojoin
<HttpsLink>
  <RemoteServer> qa-ks-vm-200.cisco.com</RemoteServer>
  <RemoteUsername>admin</RemoteUsername>
  <RemotePassword>ecsbulab</RemotePassword>
  <UseSSL>true</UseSSL>
  <AcceptSelfSignedCertificates>true</AcceptSelfSignedCertificates>
  <AcceptCertificateErrors>false</AcceptCertificateErrors>
  <EnableDirectorySync>true</EnableDirectorySync>
  <EnableVoicenameSync>true</EnableVoicenameSync>
</HttpsLink>

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

201
ResponseBody : /vmrest/httpslinks/< newHttpsLinkObjectId>

JSON example To create an http(s) link:

POST: https://<connection-server>/vmrest/httpslinks/operation/autojoin
Accept: application/json
Content-type: application/json
Connection: keep-alive

{
  "RemoteServer":" qa-ks-vm-200.cisco.com ",
  "RemoteUsername":"admin",
  "RemotePassword":"ecsbulab",
  “UseSSL”: “true”,
  “AcceptSelfSignedCertificates” : “true”,
  “AcceptCertificateErrors” : “false”,
  “EnableDirectorySync” : “true”,
  “EnableVoicenameSync” : “true”
}

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

<pre>
201
ResponseBody : /vmrest/httpslinks/< newHttpsLinkObjectId>

Explanation of Data Fields
The following chart lists the data fields:

Parameter Data Type Operations Description
RemoteServer String Write IP address/Hostname/Fully-Qualified Domain Name (FQDN) of the remote location with which to establish the HTTPS link

Note: In case UseSSL option needs to be enabled, please make sure the remote SSL certificate common name (CN) matches the RemoteServer.

RemoteUsername String Write Username of an administrator on the remote location
RemotePassword String Write Password for the administrator of the remote location
UseSSL Boolean [true only] Read/Write If true Encrypt the data passed between the locations

Note: This option cannot be set to false while joining in Http(s) network.

AcceptSelfSignedCertificates Boolean Read/Write If true Allow the remote location to use a self-signed certificate to negotiate SSL with this site
AcceptCertificateErrors Boolean Read/Write If true Cisco Unity Connection ignore any problems with the SSL certificate of the remote location
EnableDirectorySync Boolean Write If true Enable the task to synchronize all directory information after an HTTPS link is established.
EnableVoicenameSync Boolean Write If true Enable the task to synchronize all recorded names after an HTTPS link is established.

Updating the HTTP(S) Link

Administrator can use this API to modify directly connected location in an HTTPS network.

The following is an example of the PUT request that modifies the HTTP(S) Link as represented by the httpsLinkObjectId:

PUT: https://<connection-server>/vmrest/httpslinks/<httpsLinkObjectid>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <HttpsLink>
   <DisplayName>qa-ks-vm-454_updated</DisplayName>
   <RemoteServer>qa-ks-vm-454.cisco.com</RemoteServer>
   <UseSSL>true</UseSSL>
   <AcceptSelfSignedCertificates>true</AcceptSelfSignedCertificates>
   <AcceptCertificateErrors>true</AcceptCertificateErrors>
   <SyncDistributionLists>true</SyncDistributionLists>
 </HttpsLink>

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
No Content

JSON example

To modify an http(s) link

PUT: https://<connection-server>/vmrest/httpslinks/<httpsLinkObjectid>

Accept: application/json
Content-type: application/json
Connection: keep-alive

{
  "DisplayName":"qa-ks-vm-200_updated",
  "RemoteServer”: “qa-ks-vm-200.cisco.com”,
  “UseSSL”: “true”,
  “AcceptSelfSignedCertificates” : “true”,
  “AcceptCertificateErrors” : “true”,
  “SyncDistributionLists” : “true”,
}

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
No Content

Explanation of Data Fields
The following chart lists the data fields:

Parameter Data Type Operations Description
DisplayName nvarchar Read/Write Specifies the display name of the network link.
RemoteServer String Write IP address/Hostname/Fully-Qualified Domain Name (FQDN) of the remote location with which HTTPS link is established.

Note: In case UseSSL option needs to be enabled, please make sure the remote SSL certificate common name (CN) matches the RemoteServer.

UseSSL Boolean Read/Write If true Encrypt the data passed between the locations

Values can be:

  • 0-false
  • 1-true
AcceptSelfSignedCertificates Boolean Read/Write If true Allow the remote location to use a self-signed certificate to negotiate SSL with this site

Values can be :

  • 0-false
  • 1-true
AcceptCertificateErrors Boolean Read/Write If true Cisco Unity Connection ignore any problems with the SSL certificate of the remote location.

Values can be :

  • 0-false
  • 1-true
SyncDistributionLists Boolean Read/write Allow replication of system distribution lists and their memberships.

Values can be:

  • 0-false
  • 1-true

Note: This option cannot be disabled once enabled.

Removing An HTTPS Location

Administrator can use the following two APIs to unjoin the directly connected Unity Connection location from an HTTPS network.

Deleting an HTTPS Link

Administrator can use this API to unjoin a particular HTTPS Link from the network. This API marks selected HTTPS link as deleted, which is removed from the Unity Connection location after “Remove Objects Associated With Deleted Network Location” task runs.

DELETE: https://<connection-server>/vmrest/httpslinks/operation/unjoin/<httpsLinkObjectid>

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

Response Code :200
Success message

JSON example To delete an http(s) link

DELETE: https://<connection-server>/vmrest/httpslinks/operation/unjoin/<httpsLinkObjectid>
Accept: application/json
Content-type: application/json
Connection: keep-alive

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

Response Code :200
Success message

Deleting self-location from HTTPS network

Administrator can use this API to unjoin self-location from the HTTPS network. This API marks all the HTTPS links as deleted, which are removed from the Unity Connection location after “Remove Objects Associated With Deleted Network Location” task runs.

DELETE: https://<connection-server>/vmrest/httpslinks/operation/unjoinself

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

Response Code : 200
Success message

JSON example To delete self-location from HTTPS network

DELETE: https://<connection-server>/vmrest/httpslinks/operation/unjoinself
Accept: application/json
Content-type: application/json
Connection: keep-alive

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

Response Code :200
Success message

Rating: 0.0/5 (0 votes cast)

Personal tools