.. _number-range-management:

Number Range Management
-----------------------

.. index:: Quick Add Subscriber (Feature);Feature Number Management


.. _20.1.1|VOSS-651:
.. _21.3-PB1|VOSS-1072|EKB-12742:
.. _21.3-PB3|EKB-12768:
.. _21.4-PB1|EKB-15472:
.. _24.2|VOSS-1382:



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



Automate's number range management feature allows you to add and manage a range of internal numbers, 
at a customer, at a site, or at an intermediate node. 

.. note:: 
   
   An internal number range created at an intermediate node is also available at the sites below this 
   intermediate node. 

You can add an internal number range that includes existing numbers, but in this case, it is not possible to 
modify the existing numbers. New, unused numbers are added only to complete the range. This means that the 
number range will display as complete, with unused numbers displaying along with numbers imported from 
CUCM. 


.. image:: /src/images/number-range-management.png 

.. note::

   Using a bulk loader sheet or the API, you can create the number inventory at the customer hierarchy only. 
   The **Details** column of sub-transactions shows whether the number already exists or if it is 
   creating a new number. If any numbers exist in the range, the sub-transaction fails and the 
   parent transaction shows the status *Success with Async Failures*.

While you can delete a number range, only numbers in this range with a status of *Available* can be deleted. 
Numbers in the range with the following statuses are ignored and can't be deleted unless their 
status changes to *Available*: 

* Used 
* Used-Utility
* Reserved
* Cooling

Numbers with status *Available* and *Reserved* can be modified manually once they're added.  

Numbers can be added, edited, or deleted. When modifying a number, you can only edit the free text fields. 
The usage and availability property for each number is associated with a line or taken into use by a service.

The number inventory isn't partition-aware so if the same directory number is used on a 
cluster but in different partitions, Automate updates the inventory when 
any of these instances are changed. For example, if there's a number, *1111*, in the *Cluster X* partition, 
and a number, *1111*, in the *Cluster Y* partition, this number is marked as *Used*. If 
either of these instances are deleted, Automate checks whether other instances of this line 
exists (based on the number only, not partition) before it clears the *Used* flag. If other instances 
exist, the number status remains as *Used*.  



.. rubric:: Related Topics 

* For details around managing number ranges specific to the UC vendors you're using, see :ref:`number-inventory-vendor-specific-guidance`
* 
  .. raw:: latex

     Reserve a Number for a User in the Core Feature Guide

  .. raw:: html

     <a href="ini-reserve-for.html">Reserve a Number for a User</a>


.. _add_delete_and_modify_internal_number_inventory_range:

Manage Numbers and Number Ranges
.........................................

This procedure adds, updates, and deletes numbers and number ranges.


1. In the Admin Portal, use the **Action Search** to go to **Manage Internal Number Inventory**. 
2. Select the relevant hierarchy, customer or site.
#. Optionally, choose a target site. 

   .. note:: 
      
      Target site may be auto-populated as a read-only field if you've chosen to open this page from the 
      site hierarchy. If you've opened this page from the customer hierarchy, you may need to select a 
      target site (mandatory in some dial plans, such as site code based dial plan). 

#. At **Operation**, choose an option:  

   * **Add or Modify**?  

     * By default, **Status** is set to *Available*. 
     * When changing status to *Reserved*, optionally, fill out a value for **Reservation duration (days)**, 
       for example, *30*. At the end of this period, status returns to *Available*. If no value is 
       specified the numbers are reserved indefinitely. 
     
   * **Delete**?  

     * Only the following fields are now available: Target Site, Starting Extension, Ending Extension 
     * When deleting a number range, you won't be able to mark lines as either **Available** or **Reserved** 
       (these options won't display on the form).  
     * If a number in a deleted number range was set at *Used*, it won't be deleted. 
     
#. Fill out a starting and ending extension. 

   .. note:: 

      The maximum allowed range is 1000 for a single action. The starting extension should always be smaller 
      than the ending extension. 

      If you're adding or deleting a single number, the starting and ending extension number will be the same. If 
      numbers in the range already exist, they won't be affected - only non-existing numbers will be added.

#. If required, at **Reserved For**, you can reserve a number for a specific user. Choose an existing 
   username, or fill out a custom value. Here you can also 
   remove the *Reserved For* flag (clear the field) to allow the number to be assigned to other users. 

#. At **Vendor**, select the relevant vendor for the number range (Cisco, Microsoft, Cisco/Microsoft, or Webex 
   Calling). 
#. Based on the vendor you chose, select an appropriate option at **Internal Number Type** (direct routing, calling plan, or 
   operator connect). 
   
   .. note:: 
      
      For more information for your use case, see :ref:`number-inventory-vendor-specific-guidance`

#. Optionally, fill out values for the additional free text fields, for example **Tag**, **Description**, 
   **Reservation notes**, **E164Number** (if applicable), and **Extra1** to **Extra9**.

#. Save your changes. 

   .. note:: 
      
      Numbers at a specific hierarchy can be viewed on the **Number Inventory** list view. See :ref:`number-inventory-list-view`.

      When a line is added and selected from the drop-down list of available numbers, 
      it has a status of **Used**. If the line is used by a device or service that does not 
      allow a shared line (for example, a Hunt Pilot), it has a status of **Used-Utility**. 
      See :ref:`concepts-number-status-usage`.

      Internal numbers are available when adding subscribers.



.. rubric:: Related Topics 

* :ref:`number-inventory-vendor-specific-guidance`
* :ref:`concepts-number-status-usage`
* :ref:`number-inventory-list-view`
* 
  .. raw:: latex

     Reserve a Number for a User in the Core Feature Guide

  .. raw:: html

     <a href="ini-reserve-for.html">Reserve a Number for a User</a>

* 
  .. raw:: html

     <a href="concepts-number-reservation.html">Number Reservation</a>.
        
  .. raw:: latex

     Number Reservation 





Modify a Number in the Number Inventory 
.................................................

This procedure modifies an individual number via the Number Inventory list view. 

1. In the Admin Portal, use the **Action Search** to go to **Number Inventory**.
#. Click on the relevant number in the list to view its detailed management page. 
#. Choose an available edit option: 

   * To reserve the number, click the vertical ellipsis toolbar button to display the overflow menu, 
     then select **Reserve Number**. Transaction is scheduled for processing. When done, the status of the number 
     changes to *Reserved*. 

   * To select the internal number type, select an option at **Internal Number Type**, either Direct Routing, 
     Calling Plan, or Operator Connect.
     
   * Edit free text fields, such as Tag, Description, Reservation notes, E164Number (if applicable), and 
     Extra1 to Extra9.
   * To reserve a number for a specified user, at **Reserved For**, choose an existing username or fill out a 
     username for a new user. This number won't be available for allocation to any other user until you remove this 
     *reserved for* flag.

#. Save your changes. 


.. rubric:: Related Topics 

* :ref:`number-inventory-list-view`
* 
  .. raw:: latex

     Reserve a Number for a User in the Core Feature Guide

  .. raw:: html

     <a href="ini-reserve-for.html">Reserve a Number for a User</a>


.. _extra-fields-persist:

Number Range Management Extra1 to Extra9 Fields 
..................................................

When editing numbers in the Number Inventory or when adding or updating number ranges, you can modify values in additional fields called **Extra1** to **Extra9**. 


* When the status of a number changes, for example, from *Used* to *Available* - this may 
  occur when an associated device is unassociated with the line - then any values originally in any of the 
  **Extra1** to **Extra9** fields, remain unchanged by default.
* A default custom Configuration Template (CFT), ``IniUpdateCustomCFT``, which applies to 
  ``data/InternalNumberInventory``, can be cloned to the user hierarchy and then to 
  modify the custom persistence of extra field values. 
  
  For more information around CFT cloning and custom configuration, see the Advanced Configuration Guide. 
  

  .. important::

     Any changes to this custom CFT *only* apply to updates in workflows resulting in number
     status changes - manual updates are *not* affected.
  
  The following default values in this CFT can be modified according to your needs:

  ::

     "description": "{{ pwf.ini_dat_before.description }}",

     "extra1": "{{ pwf.ini_dat_before.extra1 }}",
     "extra2": "{{ pwf.ini_dat_before.extra2 }}",
     "extra3": "{{ pwf.ini_dat_before.extra3 }}",
     "extra4": "{{ pwf.ini_dat_before.extra4 }}",
     "extra5": "{{ pwf.ini_dat_before.extra5 }}",
     "extra6": "{{ pwf.ini_dat_before.extra6 }}",
     "extra7": "{{ pwf.ini_dat_before.extra7 }}",
     "extra8": "{{ pwf.ini_dat_before.extra8 }}",
     "extra9": "{{ pwf.ini_dat_before.extra9 }}",
     "tag": "{{ pwf.ini_dat_before.tag }}"

  The default macros for each extra field can thus be replaced inside the cloned CFT
  with custom text and macros as needed. Use the macro ``{{ macro.CLEAR }}`` if
  it is necessary to clear a field.

* The **Description** field is *always* cleared when the status of the number
  changes to **Available**, regardless of CFT value. For other number status changes,
  the CFT value will apply.

  There is full customization functionality of the **Description** field available
  to allow values in accordance with VOSS Automate feature usage.

  .. raw:: html

     For details, see <a href="number-inventory-flexibility.html">Number Inventory Flexibility and Description Customization</a>

  .. raw:: latex

     For details, see the *Number Inventory Flexibility and Description Customization* topic in the Advanced Configuration Guide.
     

* This CFT can't be used to modify any other VOSS managed fields in ``data/InternalNumberInventory``.