.. _list-number-inventory-overview: Number inventory --------------------- .. _20.1.1|VOSS-651: .. _21.4-PB1|EKB-15472: .. _21.4-PB1|EKB-15473: .. _21.4-PB4|VOSS-1295|EKB-17672: .. _24.1|EKB-18466: .. _24.2|VOSS-1382: .. _25.2|EKB-23112: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ........ The VOSS number inventory allow you to view and manage the numbers used by users, devices, and services for the given hierarchy level. The number inventory includes a combination of data that is automatically managed by the system (such as usage), and other fields that are configurable and available to store any additional useful information you choose about the numbers (such as ranges, billing IDs, and circuit IDs), to complete your inventory view. .. important:: The number format in the VOSS Internal Number Inventory (INI) is with prefix ``\+``, including a leading slash ``\`` when the INI is in E164 format. Verify that entries in the **Internal Number** column of the Number Inventory - also Webex Calling numbers - follow this format. .. image:: /src/images/number-inventory.png The VOSS number inventory functionality supports a range of capabilities outside of the basic loading and tracking of inventory status. The table describes the additional number inventory capabilities: .. tabularcolumns:: |p{5cm}|p{10cm}| +----------------------------+------------------------------------------------------------------------+ | Functionality | Description | +============================+========================================================================+ | Number Reservation | Numbers can be reserved and made unavailable until you change their | | | *reserved* status (unreserve). Reserved numbers can't be assigned to | | | any user, device, or service. When reserving a number you can add a | | | note about why its reserved. | +----------------------------+------------------------------------------------------------------------+ | Reserved For | Allows the admin to flag numbers (INI) as reserved for a specific | | | user. When used with the *next available number* option for onboarding | | | and provisioning, the system first looks for a number reserved for the | | | user you're working with. If there's a match, this number is assigned | | | to the user at the site. If no match is found, the next available | | | number is | | | assigned to this user. A number that is reserved for a specific user | | | cannot be assigned to a different user unless the **Reserved For** | | | flag is removed. | +----------------------------+------------------------------------------------------------------------+ | Number Cooling | Numbers can be placed into a cooling period, either manually or | | | automatically. Placing a number into *cooling* quarantines the number | | | for a specified number of days so that is can't be re-used for that | | | period. When VOSS number cooling is enabled, numbers are placed | | | into cooling for a predefined period when the subscriber or phone | | | associated with the number is deleted. | | | | | | VOSS number cooling is enabled and disabled in the Global | | | Settings. The default is disabled. | | | | | | A number that is in *cooling* is unavailable and can't be allocated to | | | a subscriber, phone, or device. | | | | | | A number is released from cooling and is available for use when: | | | | | | * The cooling period reaches its end date | | | * The number is manually released from the cooling period | +----------------------------+------------------------------------------------------------------------+ | Number Audit | Checks the inventory against the currently configured devices and | | | updates the inventory where needed to keep the inventory in sync for | | | changes made outside the system. | +----------------------------+------------------------------------------------------------------------+ | Number Inventory Alerting | Configure alerts to be sent if a threshold is met (e.g less than 10% | | | of numbers are available) to allow for proactive management of the | | | inventory. | +----------------------------+------------------------------------------------------------------------+ .. note:: Typically, numbers are pushed to the UC applications when they're assigned to users, devices, or services. While some available numbers may be in the UC apps for various reasons, the platform is not trying to maintain the available numbers in the underlying UC applications as it is only important when assigning the numbers to be used. .. rubric:: Related Topics * :ref:`number-inventory-alerting` * :ref:`number-management-cooling` * :ref:`global-settings` * .. raw:: latex Reserve a number for a user in the Core Feature Guide .. raw:: html Reserve a number for a user Number inventory and hierarchy in VOSS ............................................. To ensure proper visibility and allocation, numbers should be added to the inventory at the correct hierarchy level in VOSS, based on where and how they will be used. Proper planning of hierarchy and inventory allocation is essential for a scalable and efficient setup when building out the number inventory. .. rubric:: Hierarchy relationship * Inventory numbers can be placed at the same level or higher than the users, services, or devices they're assigned to. * The hierarchy level of a number determines its visibility for MACD (Move, Add, Change, Delete) operations like user onboarding. .. rubric:: Choosing the right hierarchy level Consider the following scenarios when deciding where to load inventory numbers: * **Site-level numbers** Use the site level if numbers are tied to a specific site due to: * Local trunks * Area codes * Emergency routing Assign these numbers directly to the site in VOSS so they're only available for that site's users and services. * **Intermediate nodes** If a number range is shared across multiple sites within a region, city, or country: * Group the sites under an intermediate node. * Assign the inventory to that node to allow shared access across all included sites. * **Global use** If numbers aren't tied to specific sites: * Assign these numbers to a common hierarchy node, such as customer level. * This is ideal for centralized environments or enterprises operating within a single region. .. rubric:: Dial plan considerations If using dial plan schemas, the schema rules may dictate where numbers must reside. For example, site-based dial plans with site codes require numbers to be loaded at the site level. .. rubric:: System behavior VOSS does not automatically move inventory numbers to match the hierarchy of the assigned service. * Example: A number at the customer level assigned to a site user will remain at the customer level unless manually moved. * Admins can relocate numbers if needed, but this is not required (the admin may simply prefer the number to be at the same hierarchy). .. rubric:: Typical usage Users, devices, and services that will consume numbers usually exist at the site level. Therefore, inventory numbers should be placed at the same site, or above (intermediate or customer level). You can also combine strategies: * Site-specific numbers at the site level. * Shared pools at intermediate or customer levels. Number inventory and end-user provisioning ............................................. The number inventory is integrated into various features in the system to: * Display options of numbers for selecting/assignment across the system. Numbers presented for selection follow rules specific to the feature in many cases, for instance, whether lines can be shared or not. * Manage the state of the numbers in the inventory via the workflows - marking the number used, available, and updating other managed fields depending on the MACD being performed. This includes any specific logic setup for the un-managed fields. See the section on flexibility for options to control the update that occurs. .. rubric:: Related Topics * :ref:`concepts-number-status-usage` * :ref:`number-management-cooling` * :ref:`number-reservation` * :ref:`number-inventory-alerting` * .. raw:: latex AudioCodes Device Number Integration in the Core Feature Guide .. raw:: html AudioCodes Device Number Integration .. _number-inventory-vendor-specific-guidance: UC vendor guidelines for numbers .................................... This section provides UC vendor-specific guidance and behaviors related to how their numbers are handled in VOSS. Cisco UCM/dedicated instance '''''''''''''''''''''''''''''' When the VOSS number inventory is used in a Cisco UCM/Webex Dedicated instance environment: * The value for the **Vendor** field is either *Cisco* or blank, depending on how numbers are loaded * The **Internal Number Type** field is not relevant in UCM or Dedicated Instance deployments Partition and cluster ''''''''''''''''''''''' The VOSS number inventory is not partition or cluster aware: * If the same numbers are used multiple times but in different *partitions*, these all map to the same number. This should be considered for the hierarchy level at which the number inventory exists. * If the same number exists on different *clusters*, this will map back to the same inventory value unless numbers are assigned to the site level. .. _cisco-ms-hybrid-number-inventory: Cisco-Microsoft hybrid number inventory ''''''''''''''''''''''''''''''''''''''''''' This section applies if you're using VOSS's Cisco-Microsoft hybrid feature for integrated services. A Cisco-Microsoft hybrid setup is an integration of Cisco and Microsoft capability, where Microsoft calls are routed via Cisco UCM. In a hybrid setup, the internal number inventory (INI) can be set up in two ways: .. note: The Microsoft service *always* needs an E164 number to be configured. * E164 number based, for example: * an INI entry 3334567 is mapped to an external number of +15553334567. * The number 3334567 is set up in Cisco (along with routing for the mapped external number). * The number +15553334567 is set up in Microsoft as the line. * The numbers 3334567 and \+15553334567 should be seen as the *same* number from an INI tracking perspective. * Internal number based (site code+extension or just extension) * an E164 number is generated by adding a prefix (\+88800) to the internal number for setup in Microsoft. .. note:: A name macro, ``MultiVendorLine-InternalExt-E164Prefix``, is used to store the prefix - currently set to `\+88800`. * For example, 3334567 is set up as an internal number for the user and no external number is mapped. The line is selected in the Hybrid setup. Then the prefix is added, so the number \+1888003334567 is the number in MS Teams for that user. .. important:: The numbers 3334567 and \+888003334567 should be seen as the *same* number from an INI tracking perspective. The mapping is also reflected in the :ref:`run-dni-audit-tool`. In this case, an update of the inventory takes place so that these are not counted as two separate numbers. The table summarizes the number inventory data for these cases: .. note:: **Extra2** and **Extra4** hold the service type and E164 number (includes generated) respectively. ==================== ======= ================ ================ =============== =================== ============= Scenario Status Vendor E164 Number [7]_ Usage Extra2 Extra4 ==================== ======= ================ ================ =============== =================== ============= Cisco-MS-Hybrid Used Cisco, Microsoft Exists Device, User Cisco-MS-Hybrid Cisco-MS-Hybrid [8]_ Used Cisco, Microsoft Device, User Cisco-MS-Hybrid \+88800 Cisco-No-Services Avail Cisco-Only Used Exists Device MS-Only-Entvoice Used Microsoft Exists User MS-Only-Entvoice MS-Only-Entvoice Used Microsoft User MS-Only-Entvoice \+88800 MS-Only-Hybrid Used Microsoft Exists User MS-Only-Hybrid MS-Only-Hybrid Used Microsoft User MS-Only-Hybrid \+88800 MS-Only-No-Entvoice Avail No-Hybrid-Service Avail ==================== ======= ================ ================ =============== =================== ============= .. raw:: latex For details on the service type scenarios, see Multi Vendor Service Definitions in the Core Feature Guide. .. raw:: html For details on the service type scenarios, see: Multi Vendor Service Definitions. .. rubric:: Footnote .. [7] If assigned (and associated with Extra4 - prefix e.g. \+88800) .. [8] Generated TelURI will start with prefix e.g. \+88800 .. _number-audit-process-ms: Microsoft Teams deployments ''''''''''''''''''''''''''''''''''' The use of the inventory and how it is maintained or managed can differ depending on the types of numbers in your environment. The following is some guidance and best practices to consider for the different number types. If you have a mix of number types, then consider the notes for different number types. In the number inventory: * The **Vendor** field value is typically ``Microsoft``. If numbers aren't loaded with this value initially, the system updates the numbers as they are allocated to vendor ``Microsoft``. * The **Internal Number Type** field is used to reflect the type of number in a Microsoft environment, either of the following: * Direct Routing * Operator Connect * Calling Plan The internal number type can be selected when loading the numbers. It is recommended that the relevant values are chosen. Typically, the system also updates the value for this field as required during audit or allocation of numbers, if they're incorrect or left blank. .. rubric:: General Notes The hierarchy consideration is a key section in this chapter to read in planning for numbers in the inventory. Often the numbers are meant to be used in specific sites or regions only due to agreements or emergency services requirements. This is the business context which the VOSS number inventory can provide when the numbers are loaded into the inventory at the appropriate hierarchy level. It is often found, after adding VOSS to an existing environment, that we identify various numbers that have been incorrectly assigned previously and allow them to be corrected. Any numbers that were added to the VOSS inventory through the sync/audit process will likely require moving to the correct hierarchy level. You can find more information related to the specific numbers types below. This section covers specific logic related to creating and managing the inventory in relation to specific number types in the Microsoft environment. In VOSS you can mix and match the types for different needs, so one or more of the sections may apply. .. rubric:: Direct Routing In this type of setup, you are getting ranges of numbers outside the Microsoft framework from one or more providers. For these number types, the Microsoft tenant only knows about the numbers that you have assigned to users/services. The tenant has no knowledge of the ranges or available/unused numbers. So the VOSS number inventory capability can only auto-populate the inventory from a sync/audit with those used numbers discovered from the tenant. In this scenario, you will need to load the available numbers into the VOSS number inventory to be managed and available for administrators to assign going forward. Guidelines for this setup: * You can preload the ranges of numbers you own ahead of any overbuild process that will sync/audit the inventory. In this case, the system will update the inventory as part of the sync/audit process to mark assigned numbers used. It will still add any used numbers it discovered form the tenant if there were any missed in the preload process. * You can load the full ranges after the overbuild process - this will fill in the inventory around the used numbers that were discovered and auto created in the inventory from the tenant. You may need to move the created numbers to a different hierarchy level depending on your needs (intermediate node, moving to site/customer). When you load the ranges after the sync/overbuild, the system will fill in the gaps by adding numbers as available that are missing in the inventory while leaving the ones added via the sync/audit process alone. * Any future ranges you add to the system beyond the initial overbuild will need to be added to VOSS to be available for administrators to use. .. rubric:: Operator Connect and Calling Plan numbers In this type of setup, you are getting ranges facilitated by the Microsoft Teams framework. For these types of numbers, the Microsoft tenant is fully aware of the ranges of numbers available as they are populated into the system by Microsoft (Calling Plans) or the selected Provider (Operator Connect). So it is important to note the numbers can only actually be used (e.g assigned to a user) when the numbers are available in the Microsoft Tenant post ordering – from Microsoft (Calling Plan) or the selected Provider (Operator Connect). If you add them to the VOSS inventory and try to allocate them before they are present in the tenant, you will get an error message about the numbers not existing in the tenant. Currently, the data we receive from the Microsoft tenant about the numbers does not provide any information regarding how the numbers are to be used - e.g site specific, etc. The hierarchy recommendations earlier in this chapter should be referenced and numbers should be loaded according to how the numbers are ordered and registered with Microsoft or the Provider (e.g site specific, global, etc). The best practice recommendation to streamline the inventory management of these number types is: * Number ranges are loaded into the VOSS number inventory at the appropriate hierarchy *before* they're synced in from the Microsoft tenant * This ensures that the numbers are at the correct hierarchy level and context in the system for use in the system - that users and services can only be assigned appropriate numbers. .. important:: New Calling Plan numbers cannot be assigned to users unless an emergency location is set. To set the emergency location for new Calling Plan numbers: 1. Select the relevant customer or site hierarchy, then go to **Emergency Location Ops Tool**. 2. On the Ops Tool form, verify that **Number Type** is set to ``CallingPlan``. 3. Select an **Emergency Location** from the drop-down. Also ensure a temporary user is created at the location and has the Calling Plan assigned. 4. Click **Save** to update the emergency location of the numbers at this hierarchy where this has not been set. * When the sync/audit process completes, the system updates those inventory entries with status, usage, type, etc., and won't move them. VOSS can generate inventory entries for numbers of these types. However, there are some considerations and for this reason it is recommended to preload the numbers for improved accuracy and ease of use. The following are considerations of the generated inventory and potential actions if the sync/audit was run before you loaded your inventory: * It will generate inventory entries for numbers assigned to users/services in the tenant only. We do this for assigned numbers to ensure they are at least captured and since they are assigned there is not a risk of being assigned incorrectly. * Numbers that are not assigned will not be generated in the inventory. This is to avoid available numbers being created at the wrong place in the hierarchy and inadvertently being assigned to users in the wrong sites, etc. * It will create the generated inventory entries at the same hierarchy level as the tenant details (typically customer). Typically, they are required at a different level in the hierarchy and they will need to be moved after this creation. * The ranges will need to be loaded to create the available numbers in the range within the inventory so they are available to be assigned to users/services. You can just load the whole range and the system will fill in the blanks, creating inventory entries for missing numbers while leaving existing numbers (created by the sync) alone. You can look at the number data provided by Microsoft for these number types by reviewing the ``device/msteamsonline/Number`` device model. Note - these model instances will always be at the same level as the tenant - they do not get moved around and are completely independent of the inventory entries for the numbers. Number inventory for Webex Calling ..................................... This section describes number inventory handling in a Webex Calling environment. Key considerations in a Webex Calling environment: * In a Webex Calling environment, resources all reside in locations including numbers regardless of the source (for example, CCP, non-integrated CCP, or Cisco). * PSTN numbers must be loaded into Webex as available numbers before they can be used/assigned to users. This process can vary depending on how you're sourcing the numbers - for example, CCP, or Cisco Cloud. For this reason, the numbers are typically already in Webex - to pull into the VOSS system and inventory. From the **Number Range Management** page at a site: * For numbers and ranges of numbers, **Starting Extension** and **Ending Extension** number values must be prefixed with ``+`` and are then created and maintained in VOSS with the prefix format ``\+``. When adding numbers, this can also be seen in the **Transaction** detail. * **Vendor** – this field will typically be ``Webex Calling``. If they are not loaded with this value initially, the system will update the numbers as they are allocated to vendor ``Webex Calling``. .. note:: Numbers can be pushed to the Webex Control Hub when adding number ranges at site level with the Vendor set as ``Webex Calling``. .. image:: /src/images/number-range-vendor-webex.png * If the **Operation** is *Add*: When *adding* numbers and selecting the **Vendor** as ``Webex Calling``, a **Webex Control Hub** panel displays the options if: 1. The Webex App is configured at the customer hierarchy. .. raw:: latex See the Webex App chapter in the Core Feature Guide. .. raw:: html See Webex App. 2. The available macro ``WebexCallingNumberMgmtEnabledSite`` has not been cloned to the site and set to value False. (If required, this task can be carried out if Webex Calling number management should be disabled for a site.) The options are: * **Push Numbers to Webex**: this allows for numbers to be added to the site in VOSS and to the Webex Control Hub. (Refer to the ``Create Spark Number`` action in the **Transaction** list.) * **Push as Active**: dependent on the option **Push Numbers to Webex** set to enabled. If enabled and **Push Numbers to Webex** is enabled, numbers are added in VOSS INI added as **Status** of **Available**, and on Webex Control Hub created as **Active**. If disabled and **Push Numbers to Webex** is enabled, numbers are added in both VOSS INI and the Webex Control Hub as **Inactive**. Number extensions are added to the INI when a user is assigned a number and an extension is then added. * If the **Operation** is Modify: This operation can be used on selected numbers that are in **Status** of **Inactive** - to set them as: * **Active** in the Webex Control Hub. Refer to the ``Activate Spark Number`` action in the **Transaction** list. * Status is **Available** in the VOSS INI. * If the **Operation** is Delete: Selected numbers are deleted from VOSS INI and the Webex Control Hub. Refer to the ``Delete Spark Number`` action in the **Transaction** list. * **Internal Number Type** – this field is used to reflect the type of number in the Webex environment. If you are adding or activating numbers via Number Range Management then the type is ``Phone Number``. Any numbers marked as ``Extension`` have been synced in from the Webex Control Hub. Since the numbers are known in the Webex environment, as well as the Locations for use, the VOSS system will generate the inventory based on the data from Webex. This includes: * The sync process handles the creation of inventory entries in the VOSS platform as numbers are pulled in. You should ensure the sync process handles Locations in Webex prior handling numbers (out of the box syncs ensure this). * During a site handling Webex Locations, if a corresponding VOSS site does not exist, VOSS will create a site. .. raw:: latex See the Webex Location Node Mapping topic in the Core Feature Guide for more details on Site to Location mapping for Webex for more details on how they are aligned. .. raw:: html Webex Location Node Mapping for more details on Site to Location mapping for Webex for more details on how they are aligned. * When Webex numbers are synced into VOSS, the prefix format ``\+`` is used. Any inventory entries that don't exist are created in the VOSS site corresponding to the Webex Location. This includes PSTN numbers and also internal-only extensions. * The internal number in the VOSS number inventory uses the PSTN number (if it has one); or it uses the extension number, if that is the only data available. * For PSTN numbers, the extension (if there is one) is also captured in the number inventory record via the **Extension** field. * Removal of numbers * Typically, inventory audit functionality won't be required if good sync practices are followed, as the inventory changes are handled through the sync process. Webex number owner types and inventory behavior ................................................. When Webex Calling numbers are synchronized into VOSS, each number is evaluated based on its Webex **Owner Type**. The Owner Type determines how the number is classified in the Internal Number Inventory (INI), specifically the values for **Status** and **Usage**. This classification applies to: * Newly discovered numbers * Existing numbers when their owner or service assignment changes * Inventory audit reconciliation Owner Type to Status and Usage mapping '''''''''''''''''''''''''''''''''''''''' This section describes how Webex Calling owner types are mapped in VOSS: * PEOPLE * Status: ``Used`` * Usage: ``User`` * PLACE * Status: ``Used`` * Usage: ``Device`` * VIRTUAL_LINE * Status: ``Used`` * Usage: ``User`` * HUNT_GROUP * Status: ``Used-Utility`` * Usage: ``Hunt_Group`` * AUTO_ATTENDANT * Status: ``Used-Utility`` * Usage: ``Auto_Attendant`` * CALL_QUEUE * Status: ``Used-Utility`` * Usage: ``Call_Queue`` * PAGING_GROUP * Status: ``Used-Utility`` * Usage: ``Paging_Group`` * OFFICE_ANYWHERE * Status: ``Used-Utility`` * Usage: ``Office_Anywhere`` * VOICE_MESSAGING * Status: ``Used-Utility`` * Usage: ``Voice_Messaging`` * VOICEMAIL_GROUP * Status: ``Used-Utility`` * Usage: ``Voicemail_Group`` These mappings ensure that **service and pilot numbers** are distinguished from user or device numbers and are consistently treated as utility resources across reporting, audit, and provisioning workflows. Update behavior '''''''''''''''''' If the Webex owner type of a number changes (for example, a number is reassigned from a user to a Hunt Group), VOSS automatically recalculates and updates the **Status** and **Usage** fields in the number inventory during the synchronization process. This ensures that the inventory always reflects the current functional role of the number in Webex.