☰
Navigation :

Signalling Gateway Hooks

Signalling Gateway Hooks

The N2IWF provides the ability to allow custom Lua code to be executed at various points throughout the N2IWF state model, allowing for arbitrary logic and decision-making.

This ability is provided by calling out to hook functions as each network session progresses. These hook functions may inspect and alter values in the current session context or perform any other required external function.

Hooks that are not defined will be skipped during processing.

Hooks are expected to return rapidly and synchronously, as network elements will always be waiting for the N2IWF’s response.

A sample hooks file might be:

local core = require "n2.iwf_core"

local hooks = {}

function hooks[core.hooks.AFTER_INIT] (input_context, service_context, ...)
    local msisdn = service_context:subscriber_msisdn ()
    if msisdn == '6421009200' then
        -- Insert new variable for MCC/MNC based on VLR. This will NOT set an EDR tag.
        service_context.vars ['mcc_mnc'] = '12345'

        -- Add new EDR fields. Persistent will be in every EDR, temporary only until the next write.
        local edr_manager = service_context:get_edr_manager ()
        edr_manager:update_persistent ('hook1', 1)
        edr_manager:update_temporary ('hook2', 2)
    end
end

function hooks.n2iwf_hook_after_vars (input_context, service_context, ...)
    local msisdn = service_context:subscriber_msisdn ()
    if msisdn == '6421009201' then
        -- Jump over pre-rating.
        return core.hook_destinations.RATING_SESSION
    end
end

return hooks

Hook Functions

Hooks are divided into several categories:

In addition, specific SCP hooks are provided for CAMEL/INAP call handling.

State Model Hooks

N2IWF state model hooks are called when various N2IWF states are entered or exited.

The available state model hook function names are:

All N2IWF state model hooks take the same positional arguments:

The “after external action” type hook takes a third positional argument:

Most state model hooks may indicate in their return value that the IWF should jump to the beginning of a logical block in the N2IWF state model. Jumps may not be made from the “after external action” or “after CCA” hooks.

The available jump destinations are set in the N2IWF Lua library iwf_core:

Jumps in processing will update the internal N2IWF state automatically.

Infinite loops are not checked for, and are the hook author’s responsibility to avoid.

Action Rule Retrieval Hooks

Action rule retrieval hooks are called when an action rule is required for N2IWF processing and no configured global is defined.

The available action rule retrieval hook function names are:

All N2IWF action rule retrieval take the same positional arguments:

Calls to these methods are expected to return either nil or a table consisting of a single action rule. At minimum, this table must contain a key action, giving the action to perform. Some actions may use or require additional parameters, which should be returned using the same parameter names as when used in the N2IWF configuration of such rules.

If no rule is returned, the default fallback action will be taken, depending on the rule type:

Note that N2SVCD rule engine selector rule parameters for rule selection are ignored. The rule returned by an action rule retrieval hook is always used.

Note that action rule retrieval hooks are never called if the applicable global parameter is defined in the N2SVCD configuration.

Rating Request Hooks

Rating request hooks are called when populating requests to be sent to the OCS.

The available rating request hook function names are:

All N2IWF rating request hooks take the same positional arguments:

Calls to the “additional AVPs” methods are expected to return a (possibly empty) array of AVP definitions. Each AVP definition must be a table with the contents as defined for additional AVPs specified through configuration. Note that these AVPs will not be parsed and that N2SVCD rule engine selector rule parameters for rule selection are ignored.

Calls to the other rating request hooks are expected to return the appropriate single scalar value for use in the request. This may be nil if allowed by the hook, as set out above.

Note that rating request hooks are never called if the applicable global parameter is defined in the N2SVCD configuration.

Rating Response Hooks

Rating response hooks are provided to allow analysis of the last OCS response.

The available rating response hook function is:

This hook takes the positional arguments:

No return value is expected from this hook. The service context may be updated as required.

Data Hooks

Data hooks are used to provide miscellaneous information elements to the N2IWF processing.

The available data hook function names are:

All N2IWF data hooks take the same initial positional arguments:

The notification details hook takes a third positional argument:

The external action type hook takes a third positional argument:

Note that data hooks are never called if the applicable global parameter is defined in the N2SVCD configuration.

Notification Details Hook

This hook is expected to return a table containing the details of a single notification to send, as per the notification definition. Note that name is ignored.

Translation Details Hook

This hook is expected to return a table containing the details of a single translation to apply, as per the destination translation. If no translation occurs, nil should be returned.

Variable Population Hook

This hook is expected to populate N2SVCD rule engine variables directly as required directly into the service_context.vars table. No checking is done on updates made to these variables. If EDR values are desired, these must be set directly in the EDR manager.

Note that this hook will be called twice as per the N2IWF state model, both before and after external action processing. The IWF state can be queried directly via the service context API.

Note that if no rules are being used for N2IWF processing, populating variables directly will have no effect.

External Action Rules Hook

This hook is expected to return a (possibly empty) array of rules to apply as external actions. Each rule must follow the specification for configured external action rules.

External Action Types Hook

This hook supplies the external action types that are referenced by external action rules. It is expected to return a table of external action types keyed by name, e.g.:

{
    action1 = {
        ...
    },
    action2 = {
    }
}

Where action and action2 are referenced in external action rules as the external parameter.

The contents of each external action type will depend on the type of action required. They must comply with the same definitions as configured external action types, including any specific fields for N2CUG lookup or MAP ATI.

SCP Hooks

SCP hooks are used to enrich processing of CAMEL/INAP calls.

The available SCP hook functions are:

Tone Rule Hook

This hook takes the positional arguments:

This hook may either return nil or a table containing a single member tone. In the latter case, the value will be read as a truthy value to determine if a tone should be played or not.

Note that this hook is never called if the tone global parameter is defined in the N2SVCD configuration.

Termination Hook

This hook takes the positional arguments:

The return value from this hook is ignored. The termination details object may be updated as required. Note that the elements details.charged and details.monitored should not be altered.

The available content of the details object will differ depending on the call scenario.

For free or diverted calls where looping has not been requested, the details object will be as per the N2SCP SCP-DO-INAP-BLEG-TERMINATION-FINAL message.

In all other call termination cases, the details object will be as per the N2SCP SCP-DO-INAP-BLEG-TERMINATION-ATTEMPT message.

SIP Hooks

SIP hooks are used to enrich processing of SIP calls.

The available SIP hook functions are:

Call Direction Hook

This hook takes the positional arguments:

This hook may either return nil or a table containing the member direction. In the latter case, the value will be compared against the values from the N2IWF Lua library iwf_core to determine the call direction:

For forwarded call legs, the returned table must also contain a forwarder_uri_header member to indicate where to locate the redirecting party’s URI.

If no value is returned from the hook, the call will be considered to be originating. Note that this determination can be overridden using the service context method set_direction.

Note that this hook is never called if the call direction global parameter is defined in the N2SVCD configuration.

Termination Hook

This hook takes the positional arguments:

The return value from this hook is ignored. The termination details object may be updated as required. Note that the elements details.charged and details.monitored should not be altered.

The available content of the details object will be as per the N2SIP SCC-DO-BLEG-TERMINATION-ATTEMPT message.

Hook Inclusion

The IWF service library will attempt to require custom hooks automatically.

A path to the hook file must be included in the Lua Library path.

The hook file itself must be in the included location and be named iwf_hooks.lua (or the appropriate suffix if compiled).

If no hook library exists or any individual hook method is not implemented, message processing will continue normally.

Error Handling

All N2IWF hook invocations are performed using a Lua protected call. If an error is raised within a hook, error handling rules will be used to handle the network session.

All errors raised by hooks will have the error message text appear in both a warning alarm and a PROBLEM EDR.

N2IWF Globals

All N2IWF globals are available under _G, e.g. _G.RESULT_CODES for the Result-Code rules.

It is highly recommended that great care be taken if modifying any N2IWF globals.

In addition to the globals referenced in the configuration documentation, the N2IWF creates several globals after parsing its configuration. These internal globals are prefixed with __ (two underscores) and should not be altered.