Navigation :

External Action Handler

The external action handler is a Lua object that is used to handle all external action processing via pluggable modules.

As the network session progresses through the N2IWF states, a rating session may be opened in order to use real-time rating of that session.

Attributes

The external action handler should only be accessed using its methods. Direct access to its attributes is not recommended.

Methods

The external action handler is a globally-cached object that does not have instances, so its methods should be accessed using the period operator, e.g.:

external_action_handler.maybe_do_actions ()

maybe_do_actions

This function performs the applicable external actions for the current N2IWF state based on either configuration or hook functions.

This function takes five positional parameters:

Parameter	Type	Description
`state`	String	The name of the current N2IWF state, as returned by the service context state functions.
`input_context`	Object	The input context in use for the network session.
`service_context`	Object	The service context in use for the network session.
`hook_manager`	Object	The hook manager in use for the network session.
`edr_manager`	Object	The EDR manager in use for the network session.

This function returns two dynamic positional results:

false if one or more mandatory external actions failed or if any error was encountered with external action hook or configuration processing, otherwise true.
If the first return parameter is true, the number of external actions successfully processed. Otherwise, a table containing a freeform message and a class from iwf_core.error_classes.

Custom External Actions

Custom external actions may be created and will be automatically made available as per the N2SVCD Lua service caching configuration.

Custom External Action Configuration

Custom external actions must be defined in a file called external_action.lua that is placed in a directory that matches the external action type name used in configuration and/or hooks. For example, the XML configuration for a custom action called custom1 might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
  <external name="custom_action_1" action="custom1">
    <!-- custom action configuration here -->
  </external>
</global>

<global name="EXTERNAL_ACTIONS" type="array">
  <rule var="something" value="else" external="custom_action_1"/>
</global>

This could then exist in the filesystem as:

/path/to/custom1/external_action.lua

This would then be looked up by the external action handler as (in order):

n2.external.custom1.external_action
custom1.external_action

The custom external action location must be accessible to the Lua service via the configured library path - for example, the Lua SCP service configuration for this case could include /path/to/?.lua in its lua_lib_path.

Custom External Action Specification

All custom external actions must support two methods.

parse

This method is only called for external action types defined in the external action configuration. Each such external action type is submitted in turn for validation of its configuration.

This method takes two positional parameters:

Parameter	Type	Description
`name`	String	The configured name of the external action type.
`configuration`	Object	The configuration details of the external action type.

Any return value is ignored. An error should be thrown for any issue found that prevents usage of the custom external action according to the supplied configuration.

do_action

This method is called to perform a synchronous execution of the specific external action.

This function takes seven positional parameters:

Parameter	Type	Description
`configuration`	Object	The configuration table for this instance of the external action. If the action details are from configuration (rather than a hook), configuration items may be N2IWF selector ruleset.
`name`	String	The name of this external action invocation (not the external action type name).
`input_context`	Object	The input context in use for the network session.
`service_context`	Object	The service context in use for the network session.
`edr_manager`	Object	The EDR manager in use for the network session.
`mandatory`	Boolean	Whether the external action instance is mandatory or not.
`from_hook`	Boolean	Whether the external action definition was sourced from a hook or not.

This method should return two positional results:

The status of the external action execution, either true or false.
if execution failed, either a freeform error message string or a table containing a freeform message and a class from iwf_core.error_classes.

Note that:

Not returning true for the status of a mandatory external action will immediately cause the network session to undergo error handling.
The external action handler does not record any statistics nor raise any alarms for external actions. These are expected to occur within the specific external action library as required.

Example

An example of a custom external action might be:

local external_action = {}

external_action.parse = function (name, action_type)
    -- Check that configuration is passed appropriately.
    local p1 = tostring (action_type.parameter1)
    if p1 ~= "123" then error ("Unexpected custom external action parameter value '" .. p1 .. "'.") end
end

external_action.do_action = function (action_type_details, external_type_name, input_context, service_context, edr_manager, mandatory, type_from_hook)
    -- Perform custom action here.
end

return external_action