.. _add-standalone-phone-example:

Add a standalone Cisco phone
--------------------------------------


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


This API POST call adds a standalone Cisco phone.

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


.. rubric:: References:

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


Using POST AddPhone
........................

The API call involves the following tasks: 

1. Identify the customer and customer hierarchy, and the site and site hierarchy. 
2. Provide phone details: 

   * Phone MAC address
   * Phone model 
   * Phone description 

3. Provide line details: 

   * Directory numbers 
   * Line labels
   * Display names 


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

1. Fetch the list of customers and populate a drop-down list. Allow the operator 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>``). Allow 
   the operator to select the site where the phone will be added.

   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``, ``sys.hcs.CS-P.CS-NB.Innovia.INV-New York``


Step 2: Provide phone details 
'''''''''''''''''''''''''''''''''

1. Fill out a phone description ``<PhoneDescription>`` for the ``description`` field.
2. Select a phone model: 

   * Populate ``device_type`` with phone models currently available to the customer. 

     Refer to :ref:`tool-macro-phone-models-id` by passing ``<Customer Hierarchy>``.

   * User chooses a phone model, and the choice is resolved into ``<PhoneModel>``.

3. Fill out the MAC address of the new phone in the ``name`` field. 

   .. note:: 

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


Step 2: Provide line details 
'''''''''''''''''''''''''''''''''

1. List all available directory numbers (DN) to populate ``lines``. 

   Refer to :ref:`tool-macro-directory-numbers-id`.

2. User chooses a directory number (``directory_number``). 

   .. note:: 

      Multiple lines can be added to one phone. Two or more lines can be ordered 1,2,... (``<line_(n)>``). 

3. For each directory number selected, user fills out: 

   * A line label (``label: <Label (n)>``)
   * A display name (``display: <Display Name (n)>``)
   
   .. note:: 

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


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: 

::

   {
      "standalone": true,
      "name": "<MACAddress>",
      "device_type": "<PhoneModel>",
      "description": "<PhoneDescription>",
      "lines": [
         {
            "directory_number": "<line_1>",
            "label": "<Label 1>",
            "display": "<Display Name 1>"
         }
      ],
      "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{2.5cm}|p{4.5cm}|p{1cm}|p{7cm}|

+------------------+----------------------------+--------+----------------------------------------------+
| Parameter        | Description                | Type   | Notes                                        |
+==================+============================+========+==============================================+
| ``name``         | The MAC address or phone   | string | The form field should check the following    |
|                  | name of the new phone.     |        | inputs:                                      |
|                  |                            |        |                                              |
|                  |                            |        | * Max value: 15 characters                   |
|                  |                            |        | * The first 3 characters must be ``SEP``     |
|                  |                            |        | * Following the first 3 characters, the      |
|                  |                            |        |   next 12 characters must consist of         |
|                  |                            |        |   hexadecimal characters.                    |
+------------------+----------------------------+--------+----------------------------------------------+
| ``device_type``  | The phone model.           | string | A drop-down with available phone types. The  |
|                  |                            |        | operator selects a phone model.              |
|                  |                            |        |                                              |
+------------------+----------------------------+--------+----------------------------------------------+
| ``description``  | The phone description.     | string | Max value: 30 characters                     |
+------------------+----------------------------+--------+----------------------------------------------+
| ``lines``        | Line details for each line | array  | Line is populated by listing all directory   |
|                  | added.                     |        | numbers (DNs) available, and then allowing   |
|                  |                            |        | the user to select a DN. Multiple lines can  |
|                  |                            |        | be added to a phone. Two or more lines can   |
|                  |                            |        | be ordered 1,2,...                           |
|                  |                            |        | ``(<line (n)>)``                             |
|                  |                            |        |                                              |
|                  |                            |        |                                              |
|                  |                            |        | * ``<directory_number>`` (Line number)       |
|                  |                            |        |                                              |
|                  |                            |        | * ``<label>`` (Line Label)                   |
|                  |                            |        |                                              |
|                  |                            |        |   * User input text field                    |
|                  |                            |        |   * Value ``<Label (n)>``                    |
|                  |                            |        |   * Max characters (for each line added): 30 |
|                  |                            |        |                                              |
|                  |                            |        | * ``<display>`` (Display Name)               |
|                  |                            |        |                                              |
|                  |                            |        |   * User input text field                    |
|                  |                            |        |   * Value: ``<Display Name (n)>``            |
|                  |                            |        |   * Max characters (for each line added): 30 |
+------------------+----------------------------+--------+----------------------------------------------+
| ``request_meta`` | Contains callback details. | object | These details enable VOSS Automate to update |
|                  |                            |        | the status when the initiated transaction is |
|                  |                            |        | complete.                                    |
+------------------+----------------------------+--------+----------------------------------------------+