Overview

Velocity integrates with Cisco Unified Call Manager (CUCM) to provide a reliable, secure, and manageable HTTPS service request for successful handshake and communication. The service request must be registered and subscribed with all HTTP/HTTPS supported VoIP Phones connected to CUCM.

It is recommended to use HTTPS since HTTPS uses TLS to encrypt HTTP requests and responses.

Velocity and CUCM System Requirements

The following table lists the required configuration.

Installing Velocity CUCM Integration Plugin on Velocity

1. After downloading the Velocity CUCM Integration plugin, right-click to Run as administrator.

   

2. Enter the Velocity Service Account and its password and click Next.

3. The Velocity Update wizard for Velocity CUCM Integration starts updating.

4. After completion, a successful Velocity Update dialog box displays. Click Ok.

5. Launch Velocity and select Help->About Velocity from the menu.

   

   The Velocity CUCM Integration plugin installed is displayed as shown below.

Creating a Service URL

1. Go to Call Manager web admin and login to the Cisco Unified CM Administration page.

   

2. Navigate from Device ->Device Settings -> Phone Services.

   

3. Click “Add New” for new Phone service creation.

4. The IP Phone Services Configuration page displays as shown below.

   

5. Enter a new Service Name and enter the description of the content that the service provides in the Service Description field.
   The user can either configure HTTP(S) or HTTP Service URL:

6. To configure HTTPS service request, enter the Service URL address.
   The URL syntax is,

   1. <<https://<velocity_IP_Address>/velcucm/api/cucm/?Action=<User_Action>&Username=<velocity_username>&password=<velocity_password>&Address=<door_address>>

   2. For example, <<https://10.151.30.81/velcucm/api/cucm/?Action=MomentaryUnlockDoor&UserName=Administrator&Password=password@1&Address=XNET.001.0001.001.01.DR06>>

7. Click Save.

   

8. To configure the HTTP service request, enter the Service URL address.
   The URL syntax is,
   <<http://<velocity_IP_Address>/velcucm/api/cucm/?Action=<User_Action>&Username=<velocity_username>&password=<velocity_password>&Address=<door_address>>
   For example,
   <<http://10.151.30.81/velcucm/api/cucm/?Action=MomentaryUnlockDoor&UserName=Administrator&Password=password@1&Address=XNET.001.0001.001.01.DR06>>

9. Click Save after you are done.

   

The newly added Service URL is displayed after saving the changes.

Subscribing Service URL to VoIP Phone

Login into Cisco Unified CM Administration page and navigate to Device and Phone.

1. Click any one of the HTTPS supported VoIP phones in the Device Name (Line) list.

   

2. Select Subscribe/Unsubscribe Service link from the Related Links drop-down list and click Go

3. In the new service subscription, select the newly created phone service URL and click Next.

   

4. Click the Subscribe button to confirm subscription.

   

5. The subscribed services display as shown below.

   

Supported Commands through VoIP Phone

The table lists the functions and commands supported in VoIP Phone.

Assigning Phone Service URL to a VoIP Phone button

After subscribing to the phone service, the phone service must be assigned to a phone button until then the service does not get displayed in the VoIP phone. Perform the following steps to assign the service to a phone button.

1. Click the “Add a new SURL” link on the Unassigned Associated Items in Modify Button Items as shown below.

   

2. Select the Button Service from the drop-down and then select the subscribed phone service.

   

3. Click Save and Close.

4. Click Modify Button Items to associate the Service URL to a button in the Phone Configuration screen.
   The Reorder Phone Button Configuration screen displays.

   

5. Associate the phone buttons that need to be managed as shown in the figure above.

6. After finishing, click Save and Close.

7. After associating the phone service to a phone button, the VoIP Phone restarts automatically and reconnects with CUCM. The Service URL /Secure Service URL name is listed on the VoIP Phone after the VoIP Phone is restarted.

8. Press the Phone button to confirm the device command execution that takes place in Velocity.

Exporting/Importing Velocity Self-Signed Certificates

The steps below explain how to Export the Self-Signed Certificate from Velocity and Import it into the Cisco Unified Call Manager (CUCM) for HTTPS service requests to work.

Exporting Self Signed Certificate from Velocity

1. From within the Command prompt type MMC and hit the Enter key.
   The following window will appear.
   

   

2. If prompted select Yes in the User Account Control window

3. Go to File > Add/Remove Snap-in… as shown below

4. Select Certificates and click the Add button.

   

5. Select the Computer account radio button and click Next.

6. Select Local computer: (the computer this console is running on) radio button and click Finish.

7. The certificate shows up as shown below, Click Ok.

   

8. Click Certificates (Local Computer).

9. Expand Personal -> Certificates and select Velocity TLS as shown below.

   

10. Right-click VelocityTLS and select All Tasks->Export…

11. The Certificate Export Wizard window opens, click Next.

    

12. Select DER encoded binary X.509(.CER) format radio button and click Next. This exports a certificate to the file system as a DER-encoded .cer file without its private key.

    

13. Enter the file name (VelocityTLS_Key) and click Next.

14. Select File Name from the path and click Finish.

    

15. The Certificate Export wizard will display a message indicating the export was successful, click OK.

    

16. Go to File -> exit to come out of the Console.

Importing Self Signed Certificate

1. Login into Cisco Unified OS Administration.

2. Navigate to Security and Certificate Management.

   

3. Click the “Upload Certificate/Certificate Chain” link.

   

4. Select Certificate Purpose as Phone-trust.

   

5. Enter the Description (friendly name). Click Browse to upload the downloaded Certificate from your system and click Upload.

   

6. Once the Certificate is uploaded into CUCM, the Certificate is displayed as shown below.

   

The uploaded certificate gets listed and is displayed when it is selected as shown below.

Limitations

• No success or failure message on the VoIP phone for the device command execution is displayed

• There are no events for IP Phone request from Velocity side to track which VoIP phone has requested for the device command execution

• The device command execution delay is from 5 seconds to 8 seconds after pressing the phone button the first time

• To display the modified service name that should be associated to a VoIP phone button, the user must unsubscribe and then subscribe to the service URL again. This is a known limitation in CUCM.

Common Troubleshooting

• Confirm with your CUCM Administrator, if the VoIP phone is registered with CUCM in case if there is no display in the VoIP phone

• In the case of HTTPS/HTTP service request failure in Velocity, troubleshoot the following:

  • Check if there is network reachability between VoIP Phone, CUCM, Velocity and Mx-Controller

  • Check if the Mx-Controller is enabled and online

  • Check if the service URL contains the correct velocity IP address and device command

  • Check if the service URL is configured with the correct username and password

  • Check if the service URL is configured with the correct door or expansion input/output

  • Check if the subscribed URL is mapped to the correct phone

  • Check the service URL on the web-browser before configuring it on CUCM

  • Check if the Secure service URL is subscribed to HTTPS supported VoIP phone

  • Check if the VoIP phone firmware is upgraded to the latest version to support HTTPS service URL request

• To check if the service URL is working, the user can hit the service URL (HTTPS or HTTP) in the system web browser as shown below.