.. _phone-services-feature-setup: Configure phone services ---------------------------- .. _20.1.1|EKB-4777: .. _20.1.1|EKB-5747: .. _19.2.1|VOSS-538: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ........... This procedure sets up and enables phone services feature. .. rubric:: Pre-requisites * The phone-based registration web service must be installed before you can set up phone services. Refer to :ref:`install-web-service-PBR`. .. rubric:: Phone services setup workflow This procedure involves the following steps: 1. :ref:`configure-local-admin-for-feature` 2. :ref:`enable-pbr-instance-for-ucm-clusters` 3. :ref:`create-ucm-ip-phone-service-for-phones-to-access-feature` 4. :ref:`connectivity-between-phones-and-voss-4-uc` .. rubric:: Related Topics * :ref:`intro-phone-services` * :ref:`manage-phone-services` * :ref:`install-web-service-PBR` .. _configure-local-admin-for-feature: 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. .. _enable-pbr-instance-for-ucm-clusters: 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 the **PBR Config** page. * Set up the required PBR configuration instances in 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. .. tabularcolumns:: |p{4cm}|p{11cm}| +-----------------------------------------+-------------------------------------------------------------------+ | 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. | +-----------------------------------------+-------------------------------------------------------------------+ .. image:: /src/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 CUCM) to **Both**. .. _create-ucm-ip-phone-service-for-phones-to-access-feature: 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: .. tabularcolumns:: |p{4cm}|p{11cm}| +--------------------------------+-----------------------------------------------------------------------------+ | 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 the **Phone Services** page. The table describes settings for the service: .. note:: The service can be configured via 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. .. tabularcolumns:: |p{4cm}|p{11cm}| +---------------------+-----------------------------------------------------------------------------+ | 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. | +---------------------+-----------------------------------------------------------------------------+ .. rubric:: 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://:8412/phoneservices//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: .. tabularcolumns:: |p{4cm}|p{11cm}| +------------------------------+-----------------------------------------------------------------------------+ | Parameter | Description | +==============================+=============================================================================+ | ```` | 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. | +------------------------------+-----------------------------------------------------------------------------+ | ```` | 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``), refer to :ref:`user-settings` .. 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 CUCM for the update to take effect. .. _connectivity-between-phones-and-voss-4-uc: 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 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 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.