Cisco Unity Connection has a set of feature-rich APIs to accomplish various tasks:

• Cisco Unity Connection Provisioning Interface (CUPI) API for administrative provisioning functions, such as adding/removing users and system-wide settings.
• CUPI API (for End Users) for provisioning end-user accessible features, such as their greetings or transfer settings.
• Cisco Unity Connection Messaging Interface (CUMI) API handles all send/receive/reply and other message functionality.
• Cisco Unity Connection Telephony Interface (CUTI) API is a web service for Telephony Record and Playback (TRaP) functions. Using this, you can place a call from Unity Connection and then record the audio to a greeting or a recorded name.
• Cisco Unity Connection Imaging Interface (CUII) API allows access to message state, but responses will be in the form of graphical icons, indicating the state.
• Cisco Unity Connection Notification Interface (CUNI) API is used for managing subscriptions to events, such as notifications when voice mail messages are received or deleted.

Most of these APIs function very similarly. They are all REST-based and can typically respond with either JSON or XML in the response body. As mentioned above, the API for managing and provisioning a Unity Connection system is the CUPI API. Most of the other APIs simply add more functionality for specific use cases and types of server or client data.

NOTE: this lab will focus entirely on features exposed by the supported APIs, which means it is not a direct database query/request. Unity Connection does have some ability to do this using tools such as the Cisco Utilities Data Link for Informix (CUDLI) and/or the Python Scripting Host, however these tools are generally meant to handle specific one-off scenarios and are not part of this lab and should not be used for regular, ongoing automation tasks.

In this section, you will perform the following tasks:

1. Get a list of all LDAP users available for import into Unity Connection
2. Search for a specific user to import
3. Import a user into Unity Connection
4. Modify a user's settings
5. Modify a Voicemail PIN and unlock a mailbox
6. Retrieve the user to verify settings changes
7. Delete the voicemail user account

Step 1 - List Unity Connection LDAP Users

In Unity Connection, users can either be created manually or imported either via LDAP or via a CUCM server using AXL. For this lab, you will use LDAP. For this, the LDAP synchronization between Unity and the LDAP server is already set up. When synchronization occurs, Unity simply learns about those users that exist in LDAP and are available for import, which is to say, have actual accounts with or without a voicemail box created in Unity Connection.

First, generate a query to get the users that can be imported as show in the following steps.

1. In Postman, make sure the side-bar at the left is visible.
2. In the HOLCOL-2574 collection, navigate to Direct to Server > CUC and click on Get LDAP Users to import
3. Examine the query that opened in a new tab:
   • Notice it is a GET request to: https://cuc1a.pod6.col.lab/vmrest/import/users/ldap
   • In the Headers you have Accept set to application/json. With this header, you are telling the server that you would prefer the response data to be in JSON format. Unity Connection supports XML, by default, or JSON. Note that this will only be honored for GET requests. Things like POST, where you will sending information to the server, will usually generate a simple string reply containing the object ID created. A POST and DELETE will not return any data at all; and the successful response code is 204 No Content.
4. Click Send to execute the query.
   When sending the first REST request to CUPI via Postman, you may get a response type of 401 Unauthorized and a payload that indicates "<!--custom Cisco error page-->". Try re-submitting your request. This is simply due to Postman presenting an expired session cookie (saved in the Collection) with the request. The second attempt will have an updated session cookie and will therefore work. If that still fails, then it is likely an actual authentication error.
5. Note the result status is 200 OK and the body looks like this:
    

   
   {
       "@total": "5",
       "ImportUser": [
           {
               "alias": "Token_User_501dfdf6-2861-4072-a4f8-8abaa0f5b7aa",
               "firstName": "",
               "lastName": "Token",
               "pkid": "8993458a-4a99-47c4-92ec-3f01bfa06942"
           },
           {
               "alias": "pod6user1",
               "firstName": "Pod6",
               "lastName": "User1",
               "pkid": "6ad0a9c9-260a-5663-668f-275a290c8be2"
           },
           ...
       

6. The result consists of a dictionary with one key being @total (indicating that there are 5 ImportUser entries) and the other being ImportUser consisting of a list of users available for import, where each user consists of their alias, firstName, lastName, and pkid. This pkid is especially useful, since it uniquely identifies this object in the same way that the uuid field identified objects in CUCM.
   Note: The fact that the data under ImportUser is a JSON list (as denoted by the square brackets, [ and ] ) is significant: if @total, that is to say, the number of items under ImportUser, were exactly 1, then the user data under ImportUser would be a JSON dictionary with that user's settings (alias, firstName, lastName, and pkid) and not in a list of dictionaries. When working with these results programmatically as you will do later in the lab, you need to account for both scenarios.

Step 2 - Search for a specific user to import

Searching in CUPI for users of any type is done via parameters in the URI. The following steps will show you how to add a query for the alias that matches pod6user1 exactly. The part that would need to be added to the URL is ?query=(alias%20is%20pod6user1). If you consider that %20 is the hexadecimal representation of the space character, this is very readable (e.g. ?query=(alias is pod1user1) ). Aside from the is keyword, CUPI also supports startswith in order to perform a wildcard search.

1. In Postman, in the HOLCOL-2574 collection under Direct to Server > CUC, click on the Get LDAP User query.
2. Notice nothing is different except for the ?query=(alias%20is%20pod6user1) portion appended to the URL. Click Send
3. There should be exactly one result user:
    

   
   {
       "@total": "1",
       "ImportUser": {
           "alias": "pod6user1",
           "firstName": "Pod6",
           "lastName": "User1",
           "pkid": "6ad0a9c9-260a-5663-668f-275a290c8be2"
       }
   }
           

4. Copy the pkid value for your LDAP user, since you will need to use it in the next step.
   Notice that you still have the @total dictionary item, as well as the ImportUser key, however, instead of having ImportUser with a list containing just the one user, you simply have the dictionary of that user's settings. Later on when you work on developing the portal, you will force that single-object scenario to be a list, with the user information contained in it, regardless of how many objects are present.

Step 3 - Import a User into Unity Connection

Importing a user, just as creating a user in Unity Connection, consists of a POST request and specifying not only what user should be imported, but also a template to use when creating this user. This is exactly the same in the Unity Connection GUI, since there are so many settings, the system only allows you to add a user using a template that has most settings filled in for you. In the actual Postman request, we need to not only specify parameters, as we did earlier, but also add a body to the request.

1. In the Postman HOLCOL-2574 collection under Direct to Server > CUC, click on Import LDAP User with new VM.
2. Notice that the URL is now a POST method, and the URL is the same as previous queries, but then has a parameter added at the end: ?templateAlias=voicemailusertemplate. This specifies the default, system-generated "voicemailusertemplate".
3. Underneath the URL, the Body has some required content. The pkid of the user to be imported must be specified. In this case, use the pkid retrieved from the previous query. You will also fill in a DTMF Access ID, which is basically the phone number associated with this mailbox.
   You need to replace the value of the PKID with the pkid of your user from the earlier step. The full Body will be in JSON format such as:
    

   
   {
       "dtmfAccessId": "12345",
       "pkid": "dbc37047-7565-6b29-3327-18850f64d406"
   }
           

4. Click Send to submit this query.
5. The result should be a string, indicating the URL to this new user. The pkid-like portion at the end is different than the original PKID specified in the request:
    

   
       /vmrest/users/3967c91f-30ee-4656-83ac-3bc4600ee0dd
           

   This occurs despite that your request still has an Accept header with "application/json". However, since this is the reply to a POST instead of a GET, the response is different and you need to be able to handle this kind of response, as well.
   If you received a NOT_FOUND error message, this is because the pkid in the Body of the request was not correct. Look at the previous step, specifically the output from the "Get LDAP User" query. Make sure the PKID value for the user returned is copied into the Body of this "Import LDAP User with new VM" query.

Step 4 - Retrieve the User's Settings

1. In the Postman HOLCOL-2574 collection, under Direct to Server > CUC, click on Get user.
2. The URL is now: /vmrest/users with paramenter ?query=(alias%20is%20pod6user1) Without this parameter, you would get a list of all current Unity Connection accounts (with and without mailboxes). Click Send,
3. The reply contains a single user (the @total key is 1) and a User key that has all settings associated with that user in dictionary format:
    

   
   {
       "@total": "1",
       "User": {
           "URI": "/vmrest/users/3967c91f-30ee-4656-83ac-3bc4600ee0dd",
           "ObjectId": "3967c91f-30ee-4656-83ac-3bc4600ee0dd",
           "FirstName": "Pod6",
           "LastName": "User1",
           "Alias": "pod6user1",
           "City": "",
           "Department": "31",
           "DisplayName": "Pod6 User1",
           ...
           "ListInDirectory": "true",
           ...
           "DtmfAccessId": "12345",
           ...
           "UserVoicePinURI": "/vmrest/users/3967c91f-30ee-4656-83ac-3bc4600ee0dd/credential/pin",
           ...
           

   You have also see the ListInDirectory and DisplayName settings, which you will modify next. The PKID for this user account is in the ObjectId field. It is the same ID that was returned when importing/creating the account using the LDAP user. Copy this user PKID (ObjectID) value from your response for the next step

Step 5 - Modify User's Settings

Modifying most user settings is not difficult. It requires the PUT request and information in the Body indicating what settings to change. Not all settings can be modified. Some things, such as the alias, first name / last name, and password are controlled in LDAP because you chose to import that user instead of creating the user from scratch, where everything can be specified and modified.

1. In the Postman HOLCOL-2574 collection, under Direct to Server > CUC, click on Modify CUC user.
2. Make sure the URL is similar to: /vmrest/users/32139706-1743-4729-a4e7-7684a5345fe5, where the ID after /vmrest/users/ is the pkid of the mailbox to be modified, i.e. the URI from the previous query or the result of the POST to create the user account.
3. In the Body, specify the new settings. For CUPI, the boolean values must be their string equivalents, i.e. you have to put true/false in quotes.
    

   
   {
       "DisplayName": "Updated User",
       "ListInDirectory": "false"
   }        
           

4. Click Send.
5. Upon successful execution, the response should be a 204 No Content.
   If you receive a 500 Internal Server Error response, you have likely specified an incorrect PKID. Be sure you are using the object ID of the user, which is the ObjectId value from the previous Retrieve the User's Settings step.
6. To convince yourself that the change was made successfully, re-execute the Get user query. Either switch back to the previous tab in Postman or in the collection under Direct to Server > CUC, click on Get user.
7. Everything is already filled out, so just click Send and validate the update:
    

   
   {
       "@total": "1",
       "User": {
           "URI": "/vmrest/users/3967c91f-30ee-4656-83ac-3bc4600ee0dd",
           ...
           "DisplayName": "Updated User",
           ...
           "ListInDirectory": "false",
           ...
           

Step 6 - Modify A Voicemail PIN and Unlock a Mailbox

Updating a voicemail user's PIN and unlocking the mailbox is one of the most common administrator tasks. PINs can be forgotten, and after repeated failed attempts, a mailbox is locked for some time. Luckily, unlocking the mailbox and changing the PIN is no more difficult than other user setting updates. Note that existing passwords and PINs can never be retrieved, however they can be changed, if they were forgotten. Also be aware that in this lab scenario, the user voicemail accounts are imported from our LDAP directory. User passwords, not the PIN, are utilizing LDAP authentication, so they cannot be changed in Unity Connection (either via the GUI or API). If these were stand-alone users not tied to LDAP, then that would, of course, be possible.

1. In the Postman HOLCOL-2574 collection, under Direct to Server > CUC, click on Modify CUC user credentials.
2. Make sure the URL is similar to: /vmrest/users/32139706-1743-4729-a4e7-7684a5345fe5/credential/pin, where the ID following /vmrest/users/ is the pkid of the user to be modified.
3. The Body is set to:
    

   
   {
       "Credentials": "14235834",
       "HackCount": 0,
       "TimeHacked": []
   }
           

   This sets the PIN credential and unlocks the account by resetting the HackCount and TimeHacked settings (the latter being set to a blank value).
4. Click Send.
5. Upon successful execution, the response should again be a 204 No Content.
6. In understanding an API, it is important to understand the error conditions that can occur. For example, in situations where some kind of illegal input was supplied, then CUPI will responsd with an XML error message. You can see this by re-issuing the above query, but this time change the "Credentials" value in the Body to just "1" and click Send.
7. The response will be a 400 Bad Request response code, with a body of:
    

   
   {
       "errors": {
           "code": "DATA_EXCEPTION",
           "message": "Password does not have enough characters",
           "DetailCode": "19"
       }
   }
           

Step 7 - Delete the Voicemail User Account

Deleting a user is simple, as expected. It requires a DELETE operation sent to the /vmrest/users/ URL followed by the pkid of the user account to be deleted. Note that this simply deletes the account in Unity Connection. In this case, this same user would then be available to be re-imported via LDAP.

1. In the Postman HOLCOL-2574 collection, under Direct to Server > CUC, click on Delete CUC user.
2. Make sure the URL is similar to: /vmrest/users/32139706-1743-4729-a4e7-7684a5345fe5, where the ID following /vmrest/users/ is the pkid of the user to be deleted.
3. Click Send.
4. A 204 No Content message is returned to indicate successful deletion.

Feel free to close some or all of the requests in Postman at this time (no need to save anything), as you will be adding more in the next section.

Now that you are familiar with Unity Connection's CUPI API, you can dive into the Cisco Meeting Server (CMS) API, another REST-based API.