.. _internal-number-inventory-functions: Number Management Functions ----------------------------------- .. _19.2.1|VOSS-542|EKB-2929: .. _19.3.4-PB4|EKB-9330: .. _20.1.1|VOSS-651: CUSTOMER_INI_ENABLED .................... .. index:: Macro function;fn.get_lines The ``fn.get_lines`` macro function uses the value of a CUSTOMER_INI_ENABLED macro at the relevant hierarchy: * If ``((True))``, then apply the function to the Internal Number Inventory (INI) at the hierarchy: ``data.InternalNumberInventory.internal_number``. * If ``((False))``, then apply the function to ``device.cucm.Line.pattern``. The macro function will check the CUSTOMER_INI_ENABLED macro first. This macro should exist at the required hierarchy level and have a value of ``((True))`` or ``((False))``. Function '''''''''''''''''''''''' Function name: ``fn.get_lines``. Example where ``CUSTOMER_INI_ENABLED`` macro is ``((True))``: .. tabularcolumns:: |p{7cm}|p{8cm}| +--------------------+----------------------------------------------------------------------------------+ | Example | Output | +====================+==================================================================================+ | :: | :: | | | | | {{fn.get_lines}} | | | | | | | [{"value": "1000", | | | "title": "1000 (Used) \\+27826543001", | | | {"value": "2000", | | | "title": "2000"}, | | | {"value": "3000", | | | "title": "3000 (Used-Utility)"}, | | | {"value": "4000", | | | "title": "4000 (Cooling) \\+27826543004 ...(release date: 2021-09-25)..."}, | | | {"value": "5000", | | | "title": "5000 (Reserved)"}] | +--------------------+----------------------------------------------------------------------------------+ Parameters '''''''''''''''''''''''' The parameter names and values are listed below. .. note:: More than one parameter can be used. These should then be comma-separated, for example: ``{{ fn.get_lines status:Used,direction:parent}}``. * ``status``: the status of the line. Parameter values: * ``All`` * ``Available`` * ``Used`` * ``Available_or_Used`` * ``Used-Utility`` * ``Used_or_Used-Utility`` * ``Reserved`` * ``Cooling`` .. raw:: latex For details, refer to the Number Status and Usage topic in the Core Feature Guide. .. raw:: html

For details, refer to Number Status and Usage.

Usage example: ``{{fn.get_lines status:Available}}`` .. tabularcolumns:: |p{7cm}|p{8cm}| +-------------------------------------+-----------------------+ | Example | Output | +=====================================+=======================+ | :: | :: | | | | | {{fn.get_lines status:Available}} | | | | [ | | | {"value": "2000", | | | "title": "2000"} | | | ] | | | | +-------------------------------------+-----------------------+ * ``direction``: the line search direction in the hierarchy. .. note:: The default search direction is up, i.e. without the parameter is equal to ``direction:up``. Parameter values: * ``up`` - Upwards. Include current hierarchy. This is the default if the parameter is not used. * ``down`` - Downwards. Include current hierarchy. * ``local``: - On this level only. Include current hierarchy. * ``parent`` - Parent only. Exclude current hierarchy, in other words, search the parent as ``local``. * ``below`` - Downwards. Exclude current hierarchy. * ``above`` - Upwards. Exclude current hierarchy. Usage example: ``{{fn.get_lines direction:parent}}`` .. tabularcolumns:: |p{7cm}|p{8cm}| +-------------------------------------+-----------------------------------------------+ | Example | Output | +=====================================+===============================================+ | :: | :: | | | | | {{fn.get_lines direction:parent}} | | | | | | | [{"value": "1000", | | | "title": "1000 (Used) \\+27826543001"}, | | | {"value": "3000", | | | "title": "3000 (Used-Utility)"} | | | ] | +-------------------------------------+-----------------------------------------------+ * ``partition``: the line search is for ``device.cucm.Line.pattern`` in the specified partition only, i.e. the specified ``routePartitionName``. Parameter value: a partition name, for example `Site-REL103-Customer`. .. tabularcolumns:: |p{7cm}|p{8cm}| +----------------------------------------------------+-----------------------+ | Example | Output | +====================================================+=======================+ | :: | :: | | | | | {{fn.get_lines partition:Site-REL103-Customer}} | [{"value": "2000", | | | "title": "2000"} | | | ] | +----------------------------------------------------+-----------------------+ * ``e164``: the line search is for the E164 number. Parameter value: an E164 number, for example ``\+27826543001``. .. tabularcolumns:: |p{7cm}|p{8cm}| +-----------------------------------------+----------------------------------------------+ | Example | Output | +=========================================+==============================================+ | :: | :: | | | | | {{fn.get_lines e164:"\+27826543001"}} | | | | | | | [{"value": "1000", | | | "title": "1000 (Used) \\+27826543001"} | | | ] | +-----------------------------------------+----------------------------------------------+ * ``scalar_list_only:true``: only display the ``value`` in the ``title, value`` pair of the result list. Parameter value: only one value: ``true``. Without the parameter, the default display is the ``title, value`` pair. .. tabularcolumns:: |p{7cm}|p{8cm}| +------------------------------------------+-------------+ | Example | Output | +==========================================+=============+ | :: | :: | | | | | {{fn.get_lines scalar_list_only:true}} | | | | | | | [ | | | "1000", | | | "2000", | | | "3000", | | | "4000", | | | "5000" | | | ] | | | | +------------------------------------------+-------------+ Parameter Types and Permutations ''''''''''''''''''''''''''''''''''' Parameters are of the following types: * Applies to INI: ``status``, ``e164`` * Applies to cucm/Line: ``partition`` * Other: ``scalar_list``, ``direction`` The types of parameters will determine the types of lines returned: * Internal Number Inventory or * ``device.cucm.Line.pattern`` in accordance with whether ``CUSTOMER_INI_ENABLED`` is ``((True))`` or ``((False))``. The table below shows the result of parameters and combinations used in these cases. .. note:: The default (if not specified) ``direction`` is up. .. tabularcolumns:: |p{8cm}|p{1.5cm}|p{7cm}| ============================================== =========== ===================================== Parameter Combination INI enabled Result ============================================== =========== ===================================== ``partition`` [``scalar_list``, ``direction``] Y Return ``cucm.Line`` in ``partition`` ``partition`` [``scalar_list``, ``direction``] N Return ``cucm.Line`` in ``partition`` ``status``, ``partition`` Y Return INI by ``status`` upwards ``status``, ``partition`` N Return ``cucm.Line`` in ``partition`` ``status`` Y Return INI by ``status`` upwards ``status`` N Return ``cucm.Line`` upwards ``partition`` Y Return ``cucm.Line`` in ``partition`` ``partition`` N Return ``cucm.Line`` in ``partition`` ============================================== =========== ===================================== Get DN Number from E164 Range ............................... .. index:: Macro Function;fn.get_dn_number *fn.get_dn_number*: Return the matching Directory Number (DN) in a range given a E164 number as input. The E164 ranges are of 1, 10, 100 and 1000. Two models are queried. If no results are found in ``data/HcsDpDNE164AssociateDAT`` then the ranges in ``data/HcsDpDNMultiE164AssociateDAT`` are queried. Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +--------------------------+-------------+ | Example | Output | +==========================+=============+ | hierarchy: | | | | | | sys.hcs.CS.Global.LOC002 | | | | | | | | | :: | :: | | | | | {{ fn.get_dn_number | 82041000 | | \+121000 }} | | | | | +--------------------------+-------------+ Get a list of site associated E164 PKIDs ........................................... .. index:: Macro Function;fn.associated_e164_dn_pkids *fn.associated_e164_dn_pkids*: Given a site hierarchy PKID as input, return the list of E164 PKIDs associated with the site. Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +-----------------------------------+---------------------------------+ | Example | Output | +===================================+=================================+ | Site hierarchy PKID: | | | | | | ``61a67eb627e8f5534d6366a1`` | | | | | | :: | :: | | | | | {{ fn.associated_e164_dn_pkids | ['61a6c5df008014baaa296762', | | 61a67eb627e8f5534d6366a }} | '61a6c5e0008014baaa296777', | | | '61a6c5e0008014baaa29678c'] | | | | +-----------------------------------+---------------------------------+