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

References:

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 (GET) Customers (for deployments with or without HCM-F).

  2. Fetch available site hierarchies for the selected customer (<Customer Name>).

    Refer to (GET) All Sites Belonging to the Customer

  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 (GET) Subscriber PKID and Name

    Note

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

  2. Use (GET) Subscriber’s Phones and Services 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 (GET) Available Hierarchies of a Customer

  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:

      1. Select the “Use Existing Phone config” checkbox, setting the value for <copy_deskphoneprofile_to_target_truefalse> to True. The default is False.

      2. Populate the “Configuration of existing Phone to be used” drop-down with all phones currently belonging to the subscriber. See (GET) Subscriber’s Phones and Services

      3. User selects one phone (<phone_mac_address_at_source>).

      4. Process the payload returned by the GET call.

      5. Resolve the value at for field “existingPhones”, and display it in the drop-down.

      6. 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:

      1. Leave the “Use Existing Phone config” checkbox clear, setting the value for <copy_deskphoneprofile_to_target_truefalse> to False. The default is False.

      2. Set <phone_mac_address_at_source> to null.

      3. Assign phone model in target site by fetching available phone models in the platform.

      4. 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 (GET) Phone Models

  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

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#

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:

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 allowed.

boolean

Defines whether existing lines need to be 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 lines.

boolean

Defines whether to allocate new lines in the 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 phone from existing phone.

boolean

True or False.

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 the move.

string

True or False.

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.