.. _phone-services-feature-setup:

.. rst-class:: chapter-with-expand

Phone Services Feature Setup
----------------------------

:ref:`intro-phone-services`

.. _19.2.1|VOSS-538:

To enable and setup Phone Services, the following steps are required:

1. Pre-requisites
.................

Prior to setting up the Phone Services Feature, make sure that the phone based
registration web service has already been installed, see :ref:`install-web-service-PBR`.

.. _configure-local-admin-for-feature:

2. Configure a Local Admin for use by the Feature
.................................................

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-4-UC. VOSS suggests
this user is used just for phone services and not used to login 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 will be 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 3 for the new password.

.. _enable-pbr-instance-for-ucm-clusters:

3. Enable the PBR instance for UCM Clusters
...........................................

If you have already configured Phone-based Registration then some of these steps
might already be complete. Configuration parameters are accessed from the
**Services > Phone Based Registration > PBR Config** menu item.

* Setup the required PBR Configuration instances in VOSS-4-UC. This may require
you 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 Unified CM
IP value blank if you don't have a Unified CM at the Provider level). This instance
will enable the basic Phone Services capability on the system.
* An instance of the model at the hierarchy level of the Unified CM Cluster that
requires the feature to be supported. **In the case of a multi-cluster setup,
multiple instances may be required at the same hierarchy (one instance per Unified CM)**.

The following fields and settings are required for Phone Services (see also illustration
below - values are examples only). The other settings on the form are not required
for Phone Services.

* **Name** - Unique name for this instance.
* **Phone Registration Portal Address** - this is the IP address of the VOSS-4-UC
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 hard coded for Phone
Services: ``pbr-api-access@[providername].com``.
* **Phone Registration Portal API Password** - The password for the user setup
in Step 2.
* **Phone Registration Service Hierarchy** - This field is populated based on
the hierarchy breadcrumb when you click the add button. If it is wrong, navigate
back 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-4-UC using HTTP SOAP requests. Optional if this is the initial
provider level record and there is not a Unified CM at that level.

.. image:: /src/images/edited-manage-phone-services.png

To make the setup of multiple instances of this record easier in a system with more
than one cluster, you can include a configuration template in your menu layout
populated with the values for the shared settings then the form will pre-populate
with them, e.g. Portal address, Portal port, API User, and API Password.

.. note::

Depending on your network setup, in the event of a proxy failure, e.g. a data
center DR Failover scenario, the Phone Services hostname/IP address may need
to be changed to the proxy in the DR data center.

.. Important::

After saving the above configuration in VOSS-4-UC, you must restart the services
by running the following CLI command on the primary node (if not already done):

**cluster run app start phone-based-registration**

.. _create-ucm-ip-phone-service-for-phones-to-access-feature:

4. Create Unified CM IP Phone Service for Phones to Access the Feature
......................................................................

There are two ways of setting up the service that controls which devices the
service appears on:

* Regular service - the service must be subscribed individually to specific phones
on which the service must appear:

**Enable** check box = Selected
* Enterprise-wide subscription - the service will appear on all phones in the system:

**Enterprise Subscription** check box = Selected.

Typically an enterprise-wide subscription would be the easiest as it means not
managing the service subscriptions by device. However, if more granular control is
required then managing it as a normal service and subscribing as needed is possible.

The IP Phone Service provides the details of the VOSS-4-UC Service which is how
the IP Phones access the feature. The service needs to be setup into the Unified
CM for the phones to use it.

Choose **Device > Device Settings > Phone Services**.

The following are the settings for the service. The service can be configured via
VOSS-4-UC if the IP Phone Services device model is included in your menus (or via
bulk loader). Otherwise it can be configured directly in the Cisco Unified CM:

* **Service Name**: VOSS-4-UC Phone Services (or preferred name that will appear in the
Phone's services menu)
* **Service Description**: VOSS-4-UC Phone Services
* **Service Category**: XML Service
* **Service Type**: Standard IP Phone Service
* **Service Vendor**: VOSS
* **ServiceURL**: ``http://<VOSS-4-UC-Address>:8412/phoneservices/<UnifiedCMAddress>/menu?name=#DEVICENAME#&corp_dir=false&refresh=true``

* ``corp_dir`` - this parameter is enabled (true) by default. It can be disabled
if necessary by adding it to the URL (as shown in the example above - corp_dir=false).
When enabled, the Corp Dir menu item is added to the list of services.
The corporate directory consists of all directory numbers located at the customer
hierarchy or lower, and displays a maximum of 50 numbers only. The numbers can
be filtered by adding first name and last name.
* ``refresh`` - this parameter is used to control whether the service will
retrieve the latest setting from the underlying Unified CM when the service is used.

For example, when opening the call forward option, it would retrieve the latest
call forward all setting from the Unified CM. This can be 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-4-UC then ``refresh=false`` (which is the default if
excluded) can be used to make the service quicker.

Where ``<VOSS-4-UC-Address>`` - is the address that the phones will use to reach
VOSS-4-UC (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>`` - is the address of Unified
CM as known to VOSS-4-UC - consider any NAT setup in your network.

.. image:: /src/images/cucm-ip-phone-services-config.png

.. _connectivity-between-phones-and-voss-4-uc:

5. Connectivity between Phones and VOSS-4-UC
.............................................

For the Phone Services feature to work, the network needs to support connectivity
between the Phones and the VOSS-4-UC Proxy server. This could be across a NAT
boundary or a firewall that requires the appropriate configuration to allow the
traffic. From a firewall perspective, the connectivity is via HTTP and the port
is ``8412``. As noted above, consider the user/validating of a DNS SRV entry for the
VOSS-4-UC proxy address for redundancy, otherwise if IP address or static hostname
is used the service and rules may need updating in the event of a DR scenario or
proxy failure.