Modify phone data - line recording details 
-----------------------------------------------------

Overview 
..........

This API PATCH call updates the following phone information: 

* Phone description 
* Line label
* Line display name
* Line ASCII display name 
* Line call recording settings


``PATCH https://<hostname>/api/api/device/cucm/Phone/{Phone PKID}``

Where ``{Phone PKID}`` is the ID of the phone to update. 


.. rubric:: References:

* `OpenAPI example for device/cucm/Phone/{Phone PKID} <ServiceNow-integration.html#/paths/~1api~1device~1cucm~1Phone~1%7BPhone%20PKID%7D/patch>`__
* `Model: device/cucm/Phone <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/device_cucm_Phone-Model.html>`__
* `API Reference for device/cucm/Phone <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/device_cucm_Phone-API.html>`__



Using device/cucm/Phone/{Phone PKID}
......................................

Using this API call involves the following tasks: 

1. Identify the customer and the customer's hierarchy, and the site and the site hierarchy.
2. Resolve the phone that needs to be modified, and modify phone details, as required.


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 relevant site.

   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: Resolve the phone that needs to be modified, and modify phone details  
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch the following phone details from Automate, and present this data in separate fields: 

   * Phone PKID
   * Phone MAC Address
   * Phone Description
   * Phone Line Label
   * Phone Display Name 
   * Phone ASCII Display Name

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

   .. note:: 

      You can ignore other values, such as Call Recording fields.

2. User selects a phone, and for the selected phone, resolve the value to ``<Phone PKID>``. 

3. For the selected phone, the user can modify the following details to update the phone:

   .. note:: 

      Depending on the number of lines that the phone returns, the form needs to dynamically 
      populate fields relevant to lines. 

   * ``<Phone Description>``

   * ``<Line (n) Label>``
   * ``<Line (n) Display>``
   * ``<Line (n) DisplayAscii>``

   For example: 

   * ``<Phone Description>``
   
   * ``<Line 1 Label>``
   * ``<Line 1 Display>``
   * ``<Line 1 DisplayAscii>``

   * ``<Line 2 Label>``
   * ``<Line 2 Display>``
   * ``<Line 2 DisplayAscii>``



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: 


::

   [
   {
      "op": "add",
      "path": "/request_meta",
      "value": [
         {
               "external_id": "<id>",
               "external_reference": "<Reference>",
               "callback_url": "<url_string>",
               "callback_username": "<callback_username>",
               "callback_password": "<callback_password>"
         }
   ]
   },
   {"op": "replace","path": "/description","value": "<Phone Description>" },

   {"op": "replace","path": "/lines/line/0/label","value": "<Line 1 Label>" },
   {"op": "replace","path": "/lines/line/0/display","value": "<Line 1 Display>" },
   {"op": "replace","path": "/lines/line/0/displayAscii","value": "<Line 1 DisplayAscii>" },

   {"op": "replace","path": "/lines/line/1/label","value": "<Line 2 Label>" },
   {"op": "replace","path": "/lines/line/1/display","value": "<Line 2 Display>" },
   {"op": "replace","path": "/lines/line/1/displayAscii","value": "<Line 2 DisplayAscii>" }
   ]


The table describes the parameters in the request: 

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

+-------------------------+-------------------+--------------+-----------------------------------------------+
| Parameter               | Description       | Type         | Notes                                         |
+=========================+===================+==============+===============================================+
| ``op``                  |                   | string       |                                               |
+-------------------------+-------------------+--------------+-----------------------------------------------+
| ``path``                |                   | string       |                                               |
+-------------------------+-------------------+--------------+-----------------------------------------------+
| ``value``               |                   | array of     |                                               |
|                         |                   | objects      |                                               |
+-------------------------+-------------------+--------------+-----------------------------------------------+
| ``request_meta``        | Callback details. | object       | These details enable VOSS Automate to update  |
|                         |                   |              | the status when the initiated transaction is  |
|                         |                   |              | complete.                                     |
+-------------------------+-------------------+--------------+-----------------------------------------------+