Replace a Cisco phone 
------------------------------

Overview 
...........

This API POST call replaces an existing Cisco phone with a new phone. 

``POST https://<hostname>/api/api/view/ReplacePhone_VIEW``


.. rubric:: References:

* `OpenAPI example for <ServiceNow-integration.html#/paths/~1api~1view~1ReplacePhone_VIEW/post>`__
* `Model: view/ReplacePhone_VIEW <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/view_ReplacePhone_VIEW-Model.html>`__
* `API Reference for view/ReplacePhone_VIEW <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/view_ReplacePhone_VIEW-API.html>`__


Using POST ReplacePhone_VIEW
...................................

Replacing a Cisco phone involves the following tasks: 

1. Identify the customer and customer hierarchy, and the site and site hierarchy. 
2. Populate a list of existing phones in the site, and allow user to choose the phone to be replaced. 
3. User provides details for the replacement phone. 


Step 1: Identify Customer+Customer Hierarchy and Site+Site Hierarchy
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch the list of customers to populate a drop-down list, and allow the user to select a 
   customer from the list. ``<Customer Name>``

   Refer to :ref:`tool-macro-customers-id`. 

2. Fetch available site hierarchies for the selected customer (``<Customer Name>``), and allow the user to 
   select the site where the phone will be replaced.

   Refer to :ref:`tool-macro-sites-belonging-to-the-customer-id`

3. Resolve ``<Customer Hierarchy>`` and ``<Site Hierarchy>``.

   * ``<Customer Hierarchy>`` is the entry in the earlier step that ends with the ``<Customer Name>``. 

     For example, if ``<Customer Name>`` is Innovia, the ``<Customer Hierarchy>`` 
     will be ``sys.hcs.CS-P.CS-NB.Innovia``.
   
   * ``<Site Hierarchy>`` is the entry in the earlier step that the operator selects. 

     For example, ``sys.hcs.CS-P.CS-NB.Innovia.INV-Reading``


Step 2: Populate a list of existing phones at the site 
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch all phones currently available to the customer to populate a list of existing phones (``existing_phone``) 
   at the site. 

   Refer to :ref:`tool-macro-phone-models-id`

2. User select the MAC address of the existing phone that must be replaced (``<old_phone_MAC_Address>``).


Step 3: Provide replacement phone details 
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

In this step the user fills out the details of the replacement phone: 

1. Users fills out the replacement phone MAC address in ``replacement_phone``, and the value is 
   resolved to ``<new_phone_MAC_Address>``.

   .. note:: 

      Note the input conditions for the MAC address in the `OpenAPI example for <ServiceNow-integration.html#/paths/~1api~1view~1ReplacePhone_VIEW/post>`__

2. Fetch the available phone models to populate ``replacement_model``. 

   Refer to :ref:`tool-macro-phone-models-id`.

   .. note:: 

      Depending on how Automate is set, fetch either all phone models currently available 
      to the customer, or fetch all phone models currently offered to customers by the Provider.

3. Fetch the phone protocols that the replacement phone model supports, to populate ``protocol``.

   Pass ``new_phone_model`` in the GET query. 

   Refer to :ref:`tool-macro-protocols-supported-id`.

4. Fetch all available phone button templates for the phone model to populate ``pbt``.

   Refer to :ref:`tool-macro-phone-button-templates-for-phone-model-id`

5. Fetch available security profiles for the replacement phone model to populate ``security_profile``.

   Refer to :ref:`tool-macro-security-profiles-for-phone-model-id`

6. User fills out a phone description for ``replacement_description``.




Query parameters
......................

.. tabularcolumns:: |p{4cm}|p{11cm}|

+--------------------+----------------+
| Parameter          | Value          |
+====================+================+
| ``hierarchy``      | Site           |
+--------------------+----------------+


Request Payload (Body)
...........................

The box lists all parameters that could be included in the call request. These parameters are described 
in the table below the box:

::

   {
      "existing_phone": "<old_phone_MAC_Address>",
      "replacement_phone": "<new_phone_MAC_Address>",
      "replacement_model": "<new_phone_model>",
      "protocol": "<new_phone_protocol>",
      "pbt": "<new_phone_PBT>",
      "security_profile": "<new_phone_SecProfile>",
      "replacement_description": "<new_phone_Description>",
      "request_meta": {
      "external_id": "<external-id>",
      "external_reference": "<external_)reference>",
      "callback_url": "<callback_url_or_ip",
      "callback_username": "callback_username",
      "callback_password": "callback_password"
      }
   }


The table describes the parameters in the request: 

.. tabularcolumns:: |p{3cm}|p{3cm}|p{3cm}|p{6cm}|

+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| Parameter                   | Description                 | Type         | Notes                                         |
+=============================+=============================+==============+===============================================+
| ``existing_phone``          | Existing phone name.        | string       | The MAC address of the existing phone, the    |
|                             |                             |              | phone to be replaced.                         |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``replacement_phone``       | Replacement phone name.     | string       | The MAC address of the replacement phone.     |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``replacement_model``       | Replacement phone model.    | string       | Choose from existing phone models available.  |
|                             |                             |              |                                               |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``protocol``                | The phone protocol.         | string       | The phone protocols that the replacement      |
|                             |                             |              | phone model supports.                         |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``pbt``                     | The phone button template.  | string       | The phone button templates that are available |
|                             |                             |              | in the system for the specified replacement   |
|                             |                             |              | phone model.                                  |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``security_profile``        | The phone security profile. | string       | The phone security profile for the            |
|                             |                             |              | replacement phone model.                      |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``replacement_description`` | New phone description.      | string       | A phone description for the new, replacement  |
|                             |                             |              |                                               |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+ 
| ``request_meta``            | Callback details.           | object       | These details enable VOSS Automate to update  |
|                             |                             |              | the status when the initiated transaction is  |
|                             |                             |              | complete.                                     |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+