Configure Phone Services#

Overview#

This procedure sets up and enables phone services feature.

Pre-requisites

Phone services setup workflow

This procedure involves the following steps:

  1. Step 1: Configure a local admin for use by phone services

  2. Step 2: Enable the PBR instance for CUCM clusters

  3. Step 3: Create CUCM IP phone service for phones to access phones services

  4. Step 4: Verify connectivity between VOSS Automate and phones

Related Topics

Step 1: Configure a local admin for use by phone services#

Configure a local admin user in the system, at the Provider level, to be used by the phone services feature to initiate transactions in VOSS Automate.

It is recommended that this user is used only for phone services, and is not used to log in to the system or for other admin purposes.

The permissions required for this user are included in the access profile RS_PBR_RestrictedAPIAccess, which is on the system by default.

You may need to create a role with the relevant settings to assign to the user being created. This user and password is used in the next step.

Note

Consider a credential policy for this user that does not expire the password to avoid needing to change the password and update the various configurations setup in Step 2 for the new password.

Step 2: Enable the PBR instance for CUCM clusters#

Note

If you’ve already configured phone-based registration, some of these steps may already be complete. To access configuration parameters, go to (default menus) Services > Phone Based Registration > PBR Config.

  • Set up the required PBR configuration instances in VOSS Automate.

    You may be required to add the correct model (data/RS_PBR_Config) to the access profile and menu layouts for the roles that require access to enable/configure phone services.

  • An instance of the model at the Provider level is required (with the CUCM IP value blank if you don’t have a CUCM at the Provider level).

    This instance enables the basic phone services capability on the system.

  • An instance of the model at the hierarchy level of the CUCM cluster that requires the feature to be supported.

    Important

    In the case of a multi-cluster setup, multiple instances may be required at the same hierarchy (one instance per CUCM).

The table lists mandatory fields for phone services:

Note

Where an image showing values is included in the documentation for this step, values are examples only. Besides these required values, all other fields are optional for phone services.

Setting

Description

Name

Unique name for this instance.

Phone Registration Portal Address

The IP address of the VOSS Automate Proxy that the phones will communicate with. This needs to be the address visible to the phones (could be across a NAT boundary).

Phone Registration Portal Port

This must be port 8412.

Phone Registration Portal API User

This user ID is hardcoded for phone services:

pbr-api-access@[providername].com

Phone Registration Portal API Password

The password for the local admin user you set up.

Phone Registration Service Hierarchy

This field is populated based on the hierarchy breadcrumb when you click the Add button. If it is incorrect, return to the list view and change the breadcrumb to the correct hierarchy:

  • If the config record is defined at Provider level, then this must be the Provider hierarchy, for example sys.hcs.CS-P.

  • If the config record is defined at the Customer level, then this must be the Customer hierarchy, for example sys.hcs.CS-P.CS-NB.AAAGlobal.

CUCM IP

This should be the IP address of the Unified CM Publisher that is accessible to VOSS Automate using HTTP SOAP requests. Optional if this is the initial Provider level record and there is not a Unified CM at that level.
../../../_images/edited-manage-phone-services.png

To simplify the setup of multiple instances of this record in a system with two or more clusters, include a configuration template in your menu layout with values for the shared settings (for example, portal address, portal port, API user, and API password). This will pre-populate the form with these values.

Note

Depending on your network setup, in the event of a proxy failure (for example, a data center disaster recovery failover scenario), the phone services hostname/IP address may need to be changed to the proxy in the disaster recovery data center.

Important

  • You must restart the services once you’ve saved the above configuration in VOSS Automate. To restart services, run the following CLI command on the primary node (if not already done):

    cluster run application app start phone-based-registration

    If you’re on-boarding and configuring several customers at the same time, the command needs to be run only once, after all configuration is complete.

    Subsequent single customer onboarding will however require that the command is re-run.

  • Ensure you set the Services Provisioning value (under Enterprise Parameters Configuration - Parameter Name on the associated Unified CM) to Both.

Step 3: Create CUCM IP phone service for phones to access phones services#

The table describes two methods for setting up the service that controls which devices the service appears on:

Method

Description

Regular service

The service must be subscribed individually to specific phones on which the service must appear:

Enable checkbox = Selected

Enterprise-wide subscription

The service will appear on all phones in the system:

Enterprise Subscription checkbox = Selected

Typically, an enterprise-wide subscription is simpler as it means not managing the service subscriptions by device.

For more granular control, manage it as a regular service, and subscribe as needed.

The IP Phone Service provides the details of the VOSS Automate service, which is how the IP Phones access the feature. The service needs to be set up into the Unified CM for the phones to use it.

Go to (default menus) Device > Device Settings > Phone Services.

The table describes settings for the service:

Note

The service can be configured via VOSS Automate if the IP Phone Services device model is included in your menus (or via bulk loader). Otherwise it can be configured directly in the CUCM.

Setting

Description

Service Name

VOSS Automate Phone Services (or preferred name that will appear in the Phone’s services menu)

Service Description

VOSS Automate Phone Services

Service Category

XML Service

Service Type

Standard IP Phone Service

Service Vendor

VOSS

ServiceURL

Set the URL as described in ServiceURL Format, below.

ServiceURL Format

This section describes the format to be used for the ServiceURL.

This is an example ServiceURL only, showing the corporate directory format set to “UN-LN-FN” and the corporate directory scope set to “Customer”. See parameters below, and replace the value following the equals sign (=) with the values you require.

http://<VOSS Automate-Address>:8412/phoneservices/<UnifiedCMAddress>/menu
  ?name=#DEVICENAME#
  &corp_dir=true
  &corp_dir_format=UN-LN-FN
  &corp_dir_scope=Customer
  &refresh=true

The table describes the parameters in the ServiceURL:

Parameter

Description

<VOSS Automate-Address>

The address the phones will use to reach VOSS Automate (typically the primary proxy server - consider any NAT setup in your network). You may consider using/validating a DNS SRV address here for redundancy in the event of a proxy failure.

<UnifiedCMAddress>

The address of Unified CM as known to VOSS Automate - consider any NAT setup in your network.

corp_dir

Corporate directory. Enabled (true) by default.

To disable it, set “corp_dir=false” in the URL.

When enabled, the “Corp Dir” menu item is added to the list of services.

Corporate directory shows the user with the number of the associated device at the selected hierarchy or lower (see corp_dir_scope), and displays a maximum of 50 numbers only. Users are filtered and formatted according to the corp_dir_format parameter.

Note that the corporate directory excludes “end user” type users who have been marked “Exclude from Directory”, as well as “admin” type users.

corp_dir_format

Determines the format of the corporate directory. Options are:

  • “UN-LN-FN” = Username, Lastname, Firstname

  • “LN-FN-UN” = Lastname, Firstname, Username

  • “LN-FN” = Lastname, Firstname

  • “FN-LN” = Firstname, Lastname

  • “UN” = Username

The default is “UN-LN-FN”, i.e. Username, Lastname, Firstname

corp_dir_scope

Defines which users and numbers display in the corporate directory.

Options are Provider, Reseller, Customer, IntermediateNode, Site, LinkedSite. (Default is “Customer”)

The phone or device profile directory is used as a starting point, and then the search looks up the hierarchy for the corp_dir_scope value. For example, if set to “Customer”, the corporate directory displays users and numbers at the Customer hierarchy or lower.

If the phone or device profile number making the call is located at a higher hierarchy than the corp_dir_scope value, then VOSS Automate ignores the corp_dir_scope value and includes all users and numbers at the hierarchy of the phone or device profile number.

refresh

Default is refresh=false

Defines whether the service retrieves the latest settings from the underlying Unified CM when the service is used. For example, when opening the call forward option, refresh=true allows the service to retrieve the latest “call forward all setting” from the Unified CM. This is useful if the CFWD ALL softkey is also used on the phone. If the softkey is not being used and changes are only in VOSS Automate, then refresh=false (default) can be used to speed up the service.

Note

For more details around user types and corporate directory (corp_dir), see also Add Admin Users

Important

When making any change to a value on the IP Phone Services URL, click Update Subscriptions on the IP Phone Services Configuration page on the Unified CM for the update to take effect.

Step 4: Verify connectivity between VOSS Automate and phones#

To enable the phone services feature, the network must support connectivity between the phones and the VOSS Automate Proxy server. This may be across a NAT boundary, or configuring a firewall to allow HTTP traffic on port 8412.

For redundancy, consider the user/validating of a DNS SRV entry for the VOSS Automate proxy address. Otherwise, if IP address or static hostname is used, the service and rules may need updating in the event of a disaster recovery (DR) scenario or proxy failure.