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

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

.. note::

   For more details specific to managing number ranges specific to the
   UC vendors you are using, refer to :ref:`number-inventory-vendor-specific-guidance`. 

The Number Range management feature allows you to create a range of internal numbers
at a customer, site or intermediate node in the hierarchy. The latter option allows
for number ranges to be available for all sites below the intermediate nodes.

When adding a range that includes existing numbers, these cannot be modified. 
New unused numbers will be added only to complete the range. In other words, 
the range will show up as complete, with unused numbers in between numbers imported
from Unified CM.

Number ranges can also be deleted. Numbers in the range that have a status of
**Used**, **Used-Utility**, **Reserved** or **Cooling** will be ignored and can
not be deleted. If these numbers are modified to the **Available** status, and not
in use, they can then be deleted. The **Available** and **Reserved** status of
numbers can also be modified manually once they are added.

.. note::

   * Using bulk loader sheet or 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.


.. _add_delete_and_modify_internal_number_inventory_range:

Add, Modify, or Delete a Number or Number Range
.................................................

Numbers can be added 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.

Since the number inventory is not partition aware, if the same directory number
is used on a cluster but in different partitions, then VOSS Automate workflows will
update the inventory when *any* of those instances are changed. For instance, if
there is a number 1111 in the Cluster X partition and a number 1111 in the 
Cluster Y partition, then the number is marked as **Used**.

If one of those instances are deleted, we check to see if there are other instances
of that line based on the number only (not partition), before clearing the **Used**
flag. In this case, the other instance will be found and the inventory will stay
marked as **Used**.

1. Browse to the hierarchy at which you want manage the number range.
#. Open the **Number Range Management** form (default menu 
   **Number Management > Number Range Management**) and if required, you can
   choose the target site from the **Target Site** drop-down. 
   This is required in some dial plans (site code based dial plan) or can
   optionally be used to choose a site if you want to add the numbers
   to a specific site.
#. From the **Operation** drop-down, choose **Add**, **Modify** or **Delete**.
   
   .. note::
   
      * When adding or modifying a number range, the **Status** of the numbers is
        **Available** by default. However you can change this to **Reserved** from
        the **Status** drop-down. If set to **Reserved**, you can also enter the
        **Reservation duration (days)** value, e.g. 30, after which period the
        number/s will return to the **Available** status. If this value is left
        blank, the number/s will be reserved indefinitely. 
        
        .. raw:: html

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

           See also the topic on Number Reservation.

      * When deleting a number range, only the **Operation**, **Target Site**,
        **starting Extension** and **Ending Extension** fields are visible.
        Lines cannot be marked as **Available** or **Reserved**, and the
        check boxes are hidden. 

4. Enter the **Starting Extension** and **Ending Extension**. The maximum allowed
   range is 1000 for a single action. The starting extension should always be
   smaller than the ending extension. 
   
   If you are adding or deleting a single number, the starting and ending extension
   number will be the same. If numbers in the range already exist, they will not
   be affected - only non-existing numbers will be added.
#. Choose the relevant **Vendor** for the number range and based on that, select the
   appropriate internal number type if relevant. See
   :ref:`number-inventory-vendor-specific-guidance` for more details specific
   to your use case.
#. Edit free text fields, for example **Tag**, **Description**, **Reservation notes**
   **E164Number** (if applicable), and **Extra1** to **Extra9**.
#. Click **Save** to save the single or range of numbers that you added, modified
   or deleted. If a number in a deleted range was set as **Used**, it will not be
   deleted.

The numbers at a specific hierarchy can be viewed on the **Number Inventory**
list view (default menu **Number Management > Number Inventory**).
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.


Modify an individual number
............................

You can also modify an individual number from the list view (:ref:`number-inventory-list-view`)
by selecting it.

1. Click **Reserve Number** on the button bar of the number instance form to
   reserve it.
#. Edit free text fields, for example: **Tag**, **Description**, **Reservation notes**, 
   **E164Number** (if applicable), and **Extra1** to **Extra9**.
#. Click **Save**.


.. _extra-fields-persist:

Persisting and Modifying Values in Extra Fields
................................................

Note the following properties of the extra fields **Extra1** to **Extra9**:

* When managing the Number Inventory, users can modify the fields **Extra1** to **Extra9**.
* When the status of a number changes from for example **Used** to **Available**
  (for example, when an associated device is unassociated with the line), then any values originally of
  the fields **Extra1** to **Extra9** remain unchanged by default.
* A default custom Configuration Template (CFT) called **IniUpdateCustomCFT** that applies
  to ``data/InternalNumberInventory`` is available to clone to the user hierarchy and then
  to modify the custom persistence of extra field values. For details on CFT cloning and
  custom configuration, refer to 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 cannot be used to modify any other VOSS managed fields in
  ``data/InternalNumberInventory``.