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.n2iwf_hook_before_setup (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_before_pre_rating (input_context, service_context, ...)
    local msisdn = service_context:subscriber_msisdn ()
    if msisdn == '6421009201' then
        -- Jump over pre-rating.
        return core.iwf_state_names.RATING_SESSION
    end
end

return hooks

Hook Functions

Hooks are divided into several categories:

• N2IWF state model hooks, called at the beginning or end of N2IWF states.
• Action rule retrieval hooks, called as required to retrieve an action rule.
• Rating request hooks, called to populate rating information.
• Rating response hooks, called with the response from the OCS.
• Data hooks, called as required to provide miscellaneous data.

In addition, both SCP- and SIP-specific hooks are available.

State Model Hooks

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

The available state model hook function names are:

• n2iwf_hook_before_setup - called before N2IWF setup.
• n2iwf_hook_after_setup - called after N2IWF setup.
• n2iwf_hook_before_pre_rating - called before N2IWF pre-rating.
• n2iwf_hook_after_pre_rating - called after N2IWF pre-rating.
• n2iwf_hook_before_rating_session - called before N2IWF rating.
• n2iwf_hook_after_rating_session - called after N2IWF rating.
• n2iwf_hook_before_post_rating - called before N2IWF post-rating.
• n2iwf_hook_after_post_rating - called after N2IWF post-rating.

Note that all “before” hooks take place after external action processing has been executed.

All N2IWF state model hooks take the same positional arguments:

State model hooks may indicate in their return value that the IWF should jump to the beginning of another state in the N2IWF state model.

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

• iwf_core.iwf_state_names.SETUP - before setup.
• iwf_core.iwf_state_names.PRE_RATING - before pre-rating.
• iwf_core.iwf_state_names.RATING_SESSION - before rating.
• iwf_core.iwf_state_names.POST_RATING - before post-rating.

Jumps in processing will update the internal N2IWF state automatically. If a processing jump is indicated from a “before” state hook, the “after” state hook will not be executed for the current state.

Note that jumping is not considered looping and infinite loops are not checked for - they are the hook author’s responsibility to avoid.

Sub-State Hooks

These hooks are called for certain sub-state events in the N2IWF state model.

• n2iwf_hook_after_vars - called after variable population has completed.
• n2iwf_hook_external_action_complete called every time an external action is completed. Note that mandatory external actions that fail do not trigger this hook.

These hooks take the same initial positional arguments:

The external action complete hook takes two additional positional arguments:

No return value is expected from these hooks.

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:

• n2iwf_hook_pre_rating_rule - called when a pre-rating action rule is required.
• n2iwf_hook_result_code_rule - called when a Result-Code action rule is required.
• n2iwf_hook_post_rating_rule - called when a post-rating action rule is required.
• n2iwf_hook_error_handling_rule - called when an error handling action rule is required.

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:

• Pre-rating rule: no action.
• Result-Code rule: the default Result-Code action rules will apply. Note that protocol-specific fallback rules are not used.
• Post-rating rule: no action.
• Error handling rule: the default error handling action rule will apply.

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:

• n2iwf_hook_mscc_additional_avps - used to populate additional AVPs within the Multiple-Services-Credit-Control AVP in rating requests.
• n2iwf_hook_root_additional_avps - used to populate additional AVPs at the root level in rating requests.
• n2iwf_hook_request_service_context_id - used to populate the Service-Context-Id AVP in rating requests or grace handling. If not defined, the default value will apply.
• n2iwf_hook_request_service_identifier - used to populate the Service-Identifier AVP in rating requests or grace handling. If not defined, no Service-Identifier will be sent.
• n2iwf_hook_request_rating_group - used to populate the Rating-Group AVP in rating requests or grace handling. If not defined, no Rating-Group will be sent.
• n2iwf_hook_request_requested_units - used to populate the Requested-Service-Units -> CC-Service-Specific-Units in rating requests. If nil or an empty string, will cause the Requested-Service-Units body to be empty.
• n2iwf_hook_request_requested_times - used to populate the Requested-Service-Units -> CC-Time in rating requests. If nil or an empty string, will cause the Requested-Service-Units body to be empty.

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 functions are:

• n2iwf_hook_read_avps - called prior to response parsing if no Result-Code rules are configured.
• n2iwf_hook_after_cca - called after each Diameter response is parsed.

All hooks take the positional arguments:

No return value is expected from these hooks. The service context or AVPs may be updated as required, but note that AVP modification in the n2iwf_hook_after_cca will be ignored.

Data Hooks

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

The available data hook function names are:

• n2iwf_hook_notification_details - called when notification definitions are required to send a notification.
• n2iwf_hook_variable_population - called when N2SVCD rule engine variables are populated.
• n2iwf_hook_translation_details - called to perform destination translation.
• n2iwf_hook_external_action_rules - called when external action rules are required for external action processing.
• n2iwf_hook_external_action_type - called when an external action type rules is needed for external action processing.

All N2IWF data hooks take the same initial positional arguments:

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 parameters of a single notification to send, as per the notification definition.

The notification details hook takes a third positional argument:

Note that:

• name is ignored.
• Default values, if configured, will be used as normal.
• Returned parameters must be scalar.

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 external action type hook takes a third positional argument:

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 messages.

Note that for MAP messages, the optional field (if included) must be a table of keys to a true value, e.g.:

{
    action1 = {
        ...
        optional = {
            sgsn = true
        }
    }
}

SCP Hooks

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

The available SCP hook functions are:

• n2iwf_hook_scp_tone_rule - called when a tone may be played.
• n2iwf_hook_scp_termination - called prior to terminating a call.

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:

• n2iwf_hook_sip_call_direction - called when selecting the subscriber based on call direction.
• n2iwf_hook_sip_termination - called prior to terminating a call.

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:

• core.directions.ORIGINATING for the originating leg of a call (A calls B, paid for by A)
• core.directions.FORWARDING for a forwarded leg of a call (A calls B who redirects to C, paid for by B)
• core.directions.TERMINATING for a terminating leg of a call (A calls B, paid for by B)

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 be ignored.