☰
Navigation :

Library Usage

Overview

The CUG core library may be used by any N2SVCD LogicApp script as required. It depends on having a CUG database available via an N2SVCD DB agent. The global DB_APP_ROUTE may be used to specify the correct application to use.

To use the library, simply require it within your script and then call its functions as necessary, e.g.:

local cug = require "n2.cug"

local cug_details
...
ok, cug_details = pcall ( function ()
    return cug.cug_lookup (user_number, match_number)
end)

if not ok then
    ...

CUG Outcomes

The CUG core library has several outcomes that it determines when it makes a CUG lookup. These are accessed via the outcomes member of the library and consist of the following key:value pairs in a table:

CUG Output Fields

When a CUG lookup is made, a CUG_LOOKUP EDR is written with the results of that lookup.

Field Name Type Description
user_found Boolean Whether a CUG user was found.
user_id Integer The database ID of the CUG user.
user_number String The user number found in the CUG lookup. Note that this may be different to the match number initially provided for the CUG query.
user_short_code String The short code of the CUG user.
user_long_number String The long number of the CUG user.
user_is_prefix Boolean Whether the CUG user was matched by prefix.
user_range_size Integer The range size of the CUG user.
user_orig_on_net_allowed Boolean Whether the CUG user is allowed to make calls within the CUG group.
user_orig_off_net_allowed Boolean Whether the CUG user is allowed to make calls outside the CUG group.
user_term_on_net_allowed Boolean Whether the CUG user is allowed to receive calls from within the CUG group.
user_term_off_net_allowed Boolean Whether the CUG user is allowed to receive calls from outside the CUG group.
group_id Integer The database ID of the CUG group for the CUG user.
group_name String The name of the CUG user’s CUG group
match_found Boolean Whether a CUG match was found.
match_number String The match number found in the CUG lookup. Note that this may be different to the match number initially provided for the CUG query.
match_id Integer The database ID of the CUG match user.
match_short_code String The short code of the CUG match user.
match_long_number String The long number of the CUG match user.
match_is_ln Boolean Whether the match was made against the long number of the CUG match user.
match_is_prefix Boolean Whether the match was made by prefix.
match_range_size Integer The range size of the CUG match user.
match_virtual Boolean Whether the CUG match user is virtual.
match_display_caller_sc Boolean Whether caller shortcodes will be shown on terminating calls.
list_found Boolean Whether a match was made to a blacklist or a whitelist.
list_disallowed Boolean Whether the applicable list disallowed the call.
list_entry_id Integer The database ID of the applicable list.
list_whitelist_match Boolean Whether the applicable list is a whitelist.
list_is_prefix Boolean Whether the applicable list match was made by prefix.

Note that these fields are only populated after a CUG lookup has occurred with a given configuration, so cannot be used within CUG configuration selector rules.

CUG Lookup

CUG users are searched for in the following order, stopping if a user is found:

  1. Non-virtual by single long number
  2. Non-virtual by range long number
  3. Non-virtual by prefix long number
  4. Non-virtual by single short code (if allowed by configuration)
  5. Non-virtual by range short code (if allowed by configuration)
  6. Non-virtual by prefix short code (if allowed by configuration)

CUG matches are searched for in the following order, stopping if a match is found:

  1. Non-virtual by single short code (if allowed by configuration)
  2. Non-virtual by range short code (if allowed by configuration)
  3. Non-virtual by prefix short code (if allowed by configuration)
  4. Virtual by single long number
  5. Virtual by range long number
  6. Virtual by prefix long number

All range lookups are performed in ascending range size order, and prefix lookups from longest match to shortest.

CUG Library Functions

When the CUG library is included within a script, the following functions are available.

cug_lookup

This function performs a CUG lookup with the supplied parameters, using the global DB_APP_ROUTE if defined to select the applicable database application. This function may write an EDR of type CUG_LOOKUP.

It expects the following parameters, in order:

  1. user_number: (Required) the normalised number to use as the user number.
  2. match_number: (Required) the normalised number to use as the match number.
  3. allow_match_sc: whether to allow short codes to be used for match lookup. Default: true.
  4. allow_sc_user: whether to allow short codes to be used for user lookup. Default: false.
  5. terminating: whether the call is a terminating leg or not. Default: false. Note that this is used solely for statistics purposes and does not affect the lookup.
  6. suppress_edr: whether to suppress EDR generation during lookup. Default: false.

This function will return a table with some or all of the following elements:

A Lua error will be thrown if a problem is encountered.

determine_outcome

This function determines the CUG outcome based on the service context, CUG configuration, and CUG lookup details.

It expects the following parameters, in order:

  1. service_context: (Required) the service context. This must contain: the results of the CUG lookup in the cug key and whether the call is originating in the originating key.

This will return the appropriate CUG outcome.

A Lua error will be thrown if a problem is encountered.