Move a Cisco subscriber between sites
----------------------------------------------

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

This API POST call moves a Cisco subscriber (and their services and devices) between sites, creates one 
or more new lines during the move, and assigns the new lines to the devices/services. 

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


.. rubric:: References:

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



Using POST UserPhoneMoveUsers_VIEW
.........................................

Moving a subscriber and their services/devices involves the following tasks: 

1. Identify the customer and customer hierarchy. 
2. Identify the subscriber to be moved, as well as their devices and/or services. 
3. Choose the target site. 
4. Define whether new lines will be assigned in the target site, or whether to move existing lines. 
5. Define whether new phones will be assigned in the target site (with the profile moved from the existing phone), 
   and/or whether to move existing phones belonging to the subscriber. 
6. Allocate the default CUC template defined in the site defaults. 
7. Hardcode values in the payload. 


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

1. Fetch the list of customers to populate a drop-down, 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>``).

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

3. Resolve ``<Customer 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``.


Step 2: Identify the subscriber to be moved
''''''''''''''''''''''''''''''''''''''''''''''

In this step, identify the subscriber to be moved, as well as their associated devices and/or services. 

1. Populate a list of usernames, and allow the user to select one user (``<username>``).  

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

   .. note:: 

      Hide the PKID. Display only the username, firstname, and lastname in the form. 

2. Use :ref:`tool-macro-subscriber-phones-and-services-id` to fetch the details of all the 
   selected subscriber's phones, lines, and services. 

3. Segregate and collate the data into the following read-only GUI fields: 

   * "Existing Phones"
   * "Existing DeviceProfiles"
   * "Existing Voicemail"
   * "Existing SNR"

4. Populate the read-only field, "Current Site", with value collected from step 3, and 
   assign the value to ``<move_from_hn>``.



Step 3: Choose the target site
'''''''''''''''''''''''''''''''

1. Fetch the customer's sites and populate the values in ``move_to_hn`` ("Move to Site"). 

   Refer to :ref:`tool-macro-available-hierarchies-of-a-customer-id`

2. User selects a target site, and the value is assigned to ``<move_to_hn>``, 
   for example, ``sys.hcs.CS-P.CS-NB.Innovia.INV-Reading``.



Step 4: Add new lines or move existing lines
''''''''''''''''''''''''''''''''''''''''''''''

In this step, decide whether to assign new lines in the target site, or whether to move the 
subscriber's existing lines.

1. Define whether to move lines to the target site, via the form checkbox titled "Move Line" (``<move_line_trueFalse>``).
2. Define whether to allocate new lines in the target site when the subscriber is moved, via the checkbox titled 
   "Allocate New Line(s)" ``<new_line_truefalse>``.

   If "Move Line" and "Allocate New Line(s)" are selected (value: true), the 
   system attempts to move existing lines to the target site and also creates new lines 
   (one or more) in the target site, and adds it to the device and/or Extension Mobility.

   When ``<new_line_truefalse> = true``: 
   
   * Fetch all directory numbers currently available at this site. The user can select one value 
     ``<dn>``. See ``tool-macro-directory-numbers-id``.
   * Form text field titled "Line Label" ``<line_label>``. 
   * Form text field titled "Display" ``<line_display>``.


Step 5: Add new phones or move existing phones
'''''''''''''''''''''''''''''''''''''''''''''''''

In this step, define whether to assign new phones in the target site 
(with the profile moved from the existing phone), or whether to move existing phones belonging 
to the subscriber.

1. To move desk phones, select the "Move Deskphone(s)" checkbox, setting the value for ``<move_deskphone_truefalse>`` 
   to ``True``. The default is False. 

2. To create new desk phones, select the "Create new Deskphone" checkbox, setting the value for 
   ``<add_new_phone_at_target_truefalse>`` to ``True``. The default is False.

3. If ``<add_new_phone_at_target_truefalse>`` = ``True``, choose an option, and follow the relevant steps:

   * Option 1: Use existing phone's config: 

     a. Select the "Use Existing Phone config" checkbox, setting the value for 
        ``<copy_deskphoneprofile_to_target_truefalse>`` to ``True``. The default is False.
     b. Populate the "Configuration of existing Phone to be used" drop-down with all phones 
        currently belonging to the subscriber. See :ref:`tool-macro-subscriber-phones-and-services-id`
     c. User selects one phone (``<phone_mac_address_at_source>``).
     d. Process the payload returned by the GET call.
     e. Resolve the value at for field "existingPhones", and display it in the drop-down. 
     f. Depending on operation selection, assign the following:
     
        * ``<phone_mac_address_at_source>``
        * ``<phone_type_at_source>``
        
   * Option 2: Don't use existing phone's config: 
   
     a. Leave the "Use Existing Phone config" checkbox clear, setting the value for 
        ``<copy_deskphoneprofile_to_target_truefalse>`` to ``False``. The default is False.
     b. Set ``<phone_mac_address_at_source>`` to null.
     c. Assign phone model in target site by fetching available phone models in the platform.
     d. Populate the drop-down titled "Phone Model in target site" (``<phone_type_at_target>``).

        .. note:: 
         
           The GET call you use depends on how Automate is set up, either all phone models available 
           to the customer, or all phone models the provider makes available to the customer. 
           
           Refer to :ref:`tool-macro-phone-models-id`

4. Fill out the MAC Address of the phone in the target site in a text field (``name``), and 
   resolve the value to ``<new_phone_MAC_Address>``. 

   .. note:: 

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




Step 6: Allocate the default CUC template defined in the site defaults
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. Execute the following GET request to allocate the default CUC template from the Site Defaults: 

   ::

      GET https://servername/api/tool/Macro/?hierarchy=<move_to_hn>&method=evaluate&format=json&input={%23 data.SiteDefaultsDoc.defaultcucsubscribertemplate || direction:local %23}

   Example:

   ::

      GET https://servername/api/tool/Macro/?hierarchy=sys.hcs.CS-P.CS-NB.Innovia.INV-Reading&method=evaluate&format=json&input={%23 data.SiteDefaultsDoc.defaultcucsubscribertemplate || direction:local %23}


2. Assign the value returned from the GET call, to ``<default_vm_template>``.

   .. note:: 

      You will only need to include ``<default_vm_template>`` in the payload if the user 
      being moved to the other site has voicemail.



Step 7: Hardcode values in the payload
''''''''''''''''''''''''''''''''''''''''

1. Hardcode the following values in the payload: 

   * Set ``AllowLineMove`` to ``true`` (``<move_line_truefalse>``)
   * Set ``default_css`` to ``true`` 
   * Set ``default_dp`` to ``true``



Query parameters
......................


.. tabularcolumns:: |p{4cm}|p{11cm}|

+--------------------+----------------+
| Parameter          | Value          |
+====================+================+
| ``hierarchy``      | Customer       |
+--------------------+----------------+



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>",
      "move_from_hn": "<move_from_hn>",
      "move_to_hn": "<move_to_hn>",
      "move_line": <move_line_truefalse>,
      "AllowLineMove": <move_line_truefalse>,
      "new_line": <new_line_truefalse>,
      "lines": [
            {
               "directory_number": "<line_1>",
               "label": "<line_label1>",
               "display": "<line_display1>"
            },
            {
               "directory_number": "<line_2>",
               "label": "<line_label2>",
               "display": "<line_display2>"
            }
      ],

         "move_phone": <move_deskphone_truefalse>,
         "new_phone": <add_new_phone_at_target_truefalse>,
         "new_phone_from_source": <copy_deskphoneprofile_to_target_truefalse>,
         "new_phone_config_source_product": <phone_type_at_source>,
         "new_phone_config_source": "<phone_mac_address_at_source>",
         "phone_type": <phone_type_at_target>,
         "name": <new_phone_mac_address>,
         "AllowLineMove": <include_lines_from_source_truefalse>,
         "newCucUserTemplate": "<default_vm_template>",
         "default_dp": true,
         "default_css": true

         "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       |                                               |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``move_from_hn``                    | Source site.                | string       | The name of the site where you're moving the  |
|                                     |                             |              | subscriber from.                              |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``move_to_hn``                      | Target site.                | string       | The name of the site where you're moving the  |
|                                     |                             |              | subscriber to.                                |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``move_line``                       | Whether line move is        | boolean      | Defines whether existing lines need to be     |
|                                     | allowed.                    |              | moved to the new site. True or False. Default |
|                                     |                             |              | is False.                                     |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``AllowLineMove``                   | Whether to move lines.      | boolean      | True or False. Default is False.              |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``new_line``                        | Whether to allocate new     | boolean      | Defines whether to allocate new lines in the  |
|                                     | lines.                      |              | target site when moving the subscriber.       |
|                                     |                             |              | Default is True.                              |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``lines``                           | Line details.               | array        | For each line you add, the directory number,  |
|                                     |                             |              | the line label, and the line display name.    |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``move_phone``                      | Whether to move the phone.  | boolean      | True or False.                                |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``new_phone``                       | Whether to add a new phone. | boolean      | True or False.                                |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``new_phone_from_source``           | Whether to create a new     | boolean      | True or False.                                |
|                                     | phone from existing phone.  |              |                                               |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``new_phone_config_source_product`` | Type of phone.              | string       | The source phone type.                        |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``new_phone_config_source``         | Configuration source.       | string       | New phone's configuration source.             |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``phone_type``                      | The phone type.             | string       | Phone type at target site.                    |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``name``                            | The phone name              | string       | The MAC address of the phone.                 |
|                                     |                             |              |                                               |
|                                     |                             |              | * 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.                     |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``AllowLineMove``                   | Whether to include lines in | string       | True or False.                                |
|                                     | the move.                   |              |                                               |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``newCucUserTemplate``              | Default CUC template.       | string       | This value is defined in the Site Defaults.   |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``default_dp``                      |                             | boolean      | Hardcode this value to True.                  |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``default_css``                     | The CSS                     | boolean      | Hardcode this value to True.                  |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+
| ``request_meta``                    | Callback details.           | string       | These details enable VOSS Automate to update  |
|                                     |                             |              | the status when the initiated transaction is  |
|                                     |                             |              | complete.                                     |
+-------------------------------------+-----------------------------+--------------+-----------------------------------------------+