Associate an existing Cisco device or device profile to subscriber
------------------------------------------------------------------------


Overview 
..........

This API POST call associates a standalone phone (Cisco device) or standalone Cisco Unified Device Profile (UDP) to a subscriber. 


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


.. rubric:: References:

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



Using POST GS_AddDeviceToUser_VIEW
.....................................

Associating an existing device or UDP to an existing subscriber involves the following tasks: 

1. Identify the customer and customer hierarchy, and the site and site hierarchy. 
2. Populate a list of users to which the Cisco device or UDP can be associated.  
3. Assign the unassociated Cisco device or UDP. 


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: Retrieve users and choose a user 
''''''''''''''''''''''''''''''''''''''''''''

1. Populate the list of existing users at the site, displaying ``username``, ``firstname``, and ``lastname``.  

   Refer to :ref:`tool-macro-subscriber-pkid-and-name-id`, passing the site hierarchy (``<Site Hierarchy>``).

2. User selects one user from the list, and resolve the choice to ``<username>``. 


Step 3: Assign unassociated Cisco device or UDP
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''


1. The form provides two radio buttons. The user selects one option, either Device or Device Profile: 

   * If user selects "Device": 
   
     a. For ``newDeviceType``, assign the value ``phone`` for ``<device_or_udp>``
     b. Use :ref:`tool-macro-all-phones-without-associated-user-id` to fetch all 
        unassociated devices at the site.  
     c. User selects one device (phone) at ``newDeviceName``, and the selected value is resolved to 
        ``<device_or_udp_name>``.

   * If user selects "Device Profile":

     a. For ``newDeviceType``, assign the value ``deviceProfile`` to ``<device_or_udp>``
     b. Use :ref:`tool-macro-all-deviceprofiles-without-associated-user-id` to fetch 
        all unassociated device profiles at the site. 
     c. Users selects a device profile at ``newDeviceName``, and the selected value is resolved to 
        ``<device_or_udp_name>``.



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: 

::

   {
      "username": "<username>",
      "newDeviceType": "<device_or_udp>",
      "newDeviceName": "<device_or_udp_name>",
      "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       |                                               |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``newDeviceType``           | The device type.            | string       | Device type, either Cisco device (phone), or  |
|                             |                             |              | Cisco UDP (device profile).                   |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``newDeviceName``           | The device name.            | string       | The name of an unassociated device or         |
|                             |                             |              | unassociated device profile name              |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``request_meta``            | Callback details.           | object       | These details enable VOSS Automate to update  |
|                             |                             |              | the status when the initiated transaction is  |
|                             |                             |              | complete.                                     |
+-----------------------------+-----------------------------+--------------+-----------------------------------------------+