Disassociate a Cisco phone from a subscriber
-----------------------------------------------

Overview 
..........

This API POST call removes a subscriber-phone association to make it an unassigned (standalone) Cisco phone (device). 


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


.. rubric:: References:

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



Using POST GS_removeDeviceFromUser_VIEW
.........................................

Replacing a Cisco phone involves the following tasks:

1. Identify the customer and customer hierarchy, and the site and site hierarchy. 
2. Identify the user and device to disassociate.   



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: Identify the user and device to disassociate 
''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch users to populate the list of users for ``username``. 

   Refer to :ref:`tool-macro-subscriber-pkid-and-name-id`

   .. note:: 

      Hide the PKID. Display only the following, for ``username``: username, first name, last name

2. User selects a username. Resolve the value to ``<username>``. 

3. Fetch all phones associated to the selected user to populate ``oldDeviceName``. 

   Refer to :ref:`tool-macro-all-phones-belonging-to-a-user-id`

4. Users selects the phone to be unassigned. Resolve the chosen value to ``<MAC_Address>``.




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: 

::

   {
      "username": "<username>",
      "oldDeviceName": "<MAC_Address>",
      "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                                         |
+=============================+=============================+==============+===============================================+
| ``username``                | The username.               | string       |                                               |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``oldDeviceName``           | Associated device name.     | string       | The name of the device you're removing.       |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``request_meta``            | Callback details.           | object       | These details enable VOSS Automate to update  |
|                             |                             |              | the status when the initiated transaction is  |
|                             |                             |              | complete.                                     |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+