Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Content Zone
Table of Contents

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

3.

xxxx

3284 or higher

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 before installing the plugin.

...

The table shows the Windows versions supported for the different computer roles.

System Role

Versions of Windows supported

Velocity Server

  • Windows Server 2022

  • Windows Server 2019

  • Windows Server 2016

Velocity Workstation or Client

  • Windows Server 2022

  • Windows Server 2019

  • Windows Server 2016

  • Windows 11 Pro

  • Windows 10 Pro

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

...

  1. Image Added
  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.

...

  1. Image Added

    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.

...

  1. Image Added
  2. Navigate from Device ->Device Settings -> Phone Services.

...

  1. Image Added
  2. Click “Add New” for new Phone service creation.

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

...

  1. Image Added
  2. Enter a new Service Name and enter the description of the service’s content

...

  1. in the Service Description field.
    The user can either configure HTTP(S) or HTTP Service URL:

  2. To configure the 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>>

  3. Click Save.

...

  1. Image Added
  2. 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>>

  3. Click Save after you are done.

...

  1. Image Added

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 the 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.

...

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

...

  1. Select the newly created phone service URL in the new service subscription and click Next.

...

  1. Image Added
  2. Click the Subscribe button to confirm your subscription.

...

  1. Image Added
  2. The subscribed services display as shown below.

...

  1. Image Added

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 by VoIP PhonePhones.

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 is 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.

...

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

...

  1. Image Added
  2. Click Save and Close.

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

...

  1. Image Added
  2. Associate the phone buttons that need to be managed as shown in the figure above.

  3. After finishing, click Save and Close.

  4. 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.

  5. 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.

...

  1. Image Added

  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.

...

  1. Image Added
  2. Select the Computer account radio button and click Next.

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

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

...

  1. Image Added
  2. Click Certificates (Local Computer).

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

...

  1. Image Added

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

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

...

  1. Image Added
  2. 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.

...

  1. Image Added
  2. Enter the file name (VelocityTLS_Key) and click Next.

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

...

  1. Image Added
  2. The Certificate Export wizard will display a message indicating the export was successful, click OK.

...

  1. Image Added
  2. 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.

...

  1. Image Added
  2. Click the “Upload Certificate/Certificate Chain” link.

...

  1. Image Added
  2. Select Certificate Purpose as Phone-trust.

...

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

...

  1. Image Added
  2. Once the Certificate is uploaded into CUCM, the Certificate is displayed as shown below.

...

  1. Image Added

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.

...