.. _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'] | | | | +-----------------------------------+---------------------------------+ Get a list of associated DNs ........................................... .. index:: Macro Function;fn.associated_dn_list *fn.associated_dn_list*: Given an optional hierarchy as input, return the list of DNs associated with an E164 number at the hierarchy. Without the hierarchy PKID, all DNs associated with an E164 number are listed. Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +-----------------------------------+-----------------+ | Example | Output | +===================================+=================+ | Hierarchy PKID: | | | | | | ``61edc1c122a4e9dde5664cee`` | | | | | | :: | :: | | | | | {# fn.associated_dn_list | ["85011008", | | 61edc1c122a4e9dde5664cee #} | '85011009", | | | '85022008"] | | | | +-----------------------------------+-----------------+