| Table of Content Zone | |
|---|---|
|
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.
Description | Release |
|---|---|
Velocity Version | 3.8.4.3284xxxx |
Velocity CUCM Integration Plugin | Build 3.6.11.79 |
Cisco Unified Call Manager (CUCM) | V12.5.1.10000-22 |
HTTPS supported Phone Firmware | V11.7 or later |
Installing Velocity CUCM Integration Plugin on Velocity
It is mandatory to have a valid Velocity “CUCM Integration Plugin” license installed on Velocity prior to installing the plugin.
| Info |
|---|
The steps and screenshots in this guide are based on Windows 2016 Server. |
After downloading the Velocity CUCM Integration plugin, right-click to Run as administrator.
Enter the Velocity Service Account and its password and click Next.
The Velocity Update wizard for Velocity CUCM Integration starts updating.
After completion, a successful Velocity Update dialog box displays. Click Ok.
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
Go to Call Manager web admin and login to the Cisco Unified CM Administration page.
Navigate from Device ->Device Settings -> Phone Services.
Click “Add New” for new Phone service creation.
The IP Phone Services Configuration page displays as shown below.
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:To configure HTTPS service request, enter the Service URL address.
The URL syntax is,<<https://<velocity_IP_Address>/velcucm/api/cucm/?Action=<User_Action>&Username=<velocity_username>&password=<velocity_password>&Address=<door_address>>
For example, <<https://10.151.30.81/velcucm/api/cucm/?Action=MomentaryUnlockDoor&UserName=Administrator&Password=password@1&Address=XNET.001.0001.001.01.DR06>>
Click Save.
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>>Click Save after you are done.
The Service URL field is mandatory and accepts both HTTPS and HTTP URLs. If the Service URL and Secure-Service URL are configured, then the Secure-Service URL takes precedence over the Service URL. For HTTPS service requests to work, the user must download the self-signed certificate from Velocity and import it into CUCM.
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.
Click any one of the HTTPS supported VoIP phones in the Device Name (Line) list.
Select Subscribe/Unsubscribe Service link from the Related Links drop-down list and click Go
In the new service subscription, select the newly created phone service URL and click Next.
Click the Subscribe button to confirm subscription.
The subscribed services display as shown below.
The service is subscribed to the VoIP phone, but the service does not get displayed until this service is assigned to a phone button.
Supported Commands through VoIP Phone
The table lists the functions and commands supported in VoIP Phone.
Function | Command |
|---|---|
Access Functions (Only on Doors) | MomentaryUnlockDoor UnlockDoor RelockDoor |
Relay Control functions (Door base and expansion relays) | TriggerRelay ForceOnRelay ForceOnReleaseRelay ForceOffRelay ForceOffReleaseRelay LockDownRelay LockDownReleaseRelay LockOpenRelay LockOpenReleaseRelay |
InputControl functions (Door base and expansion inputs) | MaskInput UnMaskInput MomentaryMaskInput |
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.
Click the “Add a new SURL” link on the Unassigned Associated Items in Modify Button Items as shown below.
Select the Button Service from the drop-down and then select the subscribed phone service.
Click Save and Close.
Click Modify Button Items to associate the Service URL to a button in the Phone Configuration screen.
The Reorder Phone Button Configuration screen displays.
Associate the phone buttons that need to be managed as shown in the figure above.
After finishing, click Save and Close.
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.
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
From within the Command prompt type MMC and hit the Enter key.
The following window will appear.
If prompted select Yes in the User Account Control window
Go to File > Add/Remove Snap-in… as shown below
Select Certificates and click the Add button.
Select the Computer account radio button and click Next.
Select Local computer: (the computer this console is running on) radio button and click Finish.
The certificate shows up as shown below, Click Ok.
Click Certificates (Local Computer).
Expand Personal -> Certificates and select
...
the appropriate certificate option with Identiv Velocity Web Services as Friendly Name, as shown below..
...
Right-click
...
Desktop and select All Tasks->Export…
The Certificate Export Wizard window opens, click Next.
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.
Enter the file name (VelocityTLS_Key) and click Next.
Select File Name from the path and click Finish.
The Certificate Export wizard will display a message indicating the export was successful, click OK.
Go to File -> exit to come out of the Console.
Importing Self Signed Certificate
Login into Cisco Unified OS Administration.
Navigate to Security and Certificate Management.
Click the “Upload Certificate/Certificate Chain” link.
Select Certificate Purpose as Phone-trust.
Enter the Description (friendly name). Click Browse to upload the downloaded Certificate from your system and click Upload.
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.
...
Before creating the HTTPS service URL request, the user must complete the above steps. If the user uses an HTTP service request, then the user can directly create phone services and start to use it.
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.
...