Modify line data
--------------------------

Overview 
..........

This API PATCH call updates the following device line information: 

* Line description 
* Line alerting name
* Line alerting name ASCII


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

Where ``{Line PKID}`` is the ID of the line to update. 


.. rubric:: References:

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



Using device/cucm/Line/{Line 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 line that needs to be modified, and modify line 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 line that needs to be modified, and modify line details  
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

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

   * Line record PKID
   * Line Pattern
   * Line Description
   * Line AlertingName
   * Line ASCIIAlerting Name

   Refer to :ref:`tool-macro-all-line-details-id`

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

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

   * A line description, at ``description``, resolved to ``<Line Description Text>``.
   * A line alerting name, at ``alertingName``, resolved to ``<Line Alerting Text>``
   * A line ASCII alerting name, at ``asciiAlertingName``, resolved to ``<Line Alerting ASCII Text>``

   .. note:: 

      Note the input conditions for these fields, at `OpenAPI Example <ServiceNow-integration.html#/paths/~1api~1device~1cucm~1Line~1%7BLine%20PKID%7D/patch>`__



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: 

::

   {
      "description": "<Line Description Text>",
      "alertingName": "<Line Alerting Text>",
      "asciiAlertingName": "<Line Alerting ASCII Text",
      "request_meta": {
            "external_id": "<id>",
            "external_reference": "<Reference>",
            "callback_url": "<url_string>",
            "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                                         |
+========================+========================+==============+===============================================+
| ``description``        | Line description.      | string       | Max 30 characters.                            |
+------------------------+------------------------+--------------+-----------------------------------------------+
| ``alertingName``       | Line alerting name.    | string       | Max 30 characters.                            |
+------------------------+------------------------+--------------+-----------------------------------------------+
| ``asciiAlertingName``  | Line alerting ASCII    |              | Max 30 characters.                            |
|                        | name.                  |              |                                               |
+------------------------+------------------------+--------------+-----------------------------------------------+
| ``request_meta``       | Callback details.      | string       | These details enable VOSS Automate to update  |
|                        |                        |              | the status when the initiated transaction is  |
|                        |                        |              | complete.                                     |
+------------------------+------------------------+--------------+-----------------------------------------------+