.. _phone-services-feature-setup: .. rst-class:: chapter-with-expand Phone Services Feature Setup ---------------------------- :ref:`intro-phone-services` .. _20.1.1|EKB-4777: .. _20.1.1|EKB-5747: .. _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 Automate. 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 Automate. 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 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 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 Automate 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 Automate, 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** * The **Services Provisioning** value under **Enterprise Parameters Configuration - Parameter Name** on the associated Unified CM **must** be set to **Both**. .. _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 Automate 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 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 Cisco Unified CM: * **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 follows (see Note below) .. note:: 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 '=' sign with the value you require. :: http://:8412/phoneservices//menu ?name=#DEVICENAME# &corp_dir=true &corp_dir_format=UN-LN-FN &corp_dir_scope=Customer &refresh=true Where ```` - is the address that 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. ```` - is the address of Unified CM as known to VOSS Automate - consider any NAT setup in your network. * ``corp_dir`` - this parameter is enabled (true) by default. It can be disabled if necessary by adding it to the URL as "corp_dir=false". When enabled, the "Corp Dir" menu item is added to the list of services. The corporate directory shows the user with the number of the associated device at the selected hierarchy or lower (see ``corp_dir_scope`` below), and displays a maximum of 50 numbers only. The users are filtered and formatted according to the ``corp_dir_format`` parameter. .. note:: The corporate directory excludes **End User** type users who have been marked "Exclude from Directory" as well as **Admin** type users (see :ref:`create_a_user`). * ``corp_dir_format`` - this parameter determines the format of the corporate directory, and can have one of the following values: * "UN-LN-FN" = Username, Lastname, Firstname * "LN-FN-UN" = Lastname, Firstname, Username * "LN-FN" = Lastname, Firstname * "FN-LN" = Firstname, Lastname * "UN" = Username If the parameter is omitted from the URL, the default corporate directory format will be "UN-LN-FN", i.e. Username, Lastname, Firstname. * ``corp_dir_scope`` - this parameter (either Provider, Reseller, Customer, IntermediateNode, Site, or LinkedSite) determines which users and numbers are displayed in the corporate directory. Default = Customer if a value is not specified. 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 will display 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`` - 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 Automate then ``refresh=false`` (which is the default if excluded) can be used to make the service quicker. .. note:: To effect a change to any value on the IP Phone Services URL, you must click **Update Subscriptions** on the **IP Phone Services Configuration** page on the Unified CM. .. _connectivity-between-phones-and-voss-4-uc: 5. Connectivity between Phones and VOSS Automate ................................................. For the Phone Services feature to work, the network needs to support connectivity between the Phones and the VOSS Automate 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 Automate 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. See also: * :ref:`manage-phone-services`