Navigation :

Service Context

The service context is a Lua object that holds all information about the internal state of a network session as it is processed by the N2IWF. It is populated both by its own service logic (including OCS responses) and the protocol handler
library. Data may also be inserted into the service context by the protocol handler as required for call handling.

Attributes

The service context should only be modified using its methods. Direct access to its attributes is not recommended.

Methods

The service context is created as a new instance for each call, so its methods should be accessed using the colon operator, e.g.:

service_context:get_by_dot ("key")

Getter / Setter Functions

Many service context functions operate as both getters and setters for network session information.

When called without parameters, the current value of the appropriate element is returned, if any.

They may be alternatively be provided with a single parameter in order to set the appropriate element. The special N2SVCD global UNDEF may be used to remove the currently stored value.

Function	Parameter and Return Type	Description
`subscriber_msisdn`	String	The subscriber’s MSISDN.
`subscriber_imsi`	String	The subscriber’s IMSI.
`subscriber_uri`	String	The subscriber’s URI.
`service_identifier`	String	The Service-Identifier, if any, for the current session.
`rating_group`	String	The Rating-Group, if any, for the current session.
`service_context_id`	String	The Service-Context-Id for the current session.
`units_total`	Integer	The total units used for the network session.
`units_last`	Integer	The units used for the current reservation.
`loop_counter`	Integer	The current loop number.
`loop_requested`	Boolean	Whether a loop has been requested during this loop.
`network_ongoing`	Boolean	Whether the current action handling for the network session is ongoing.
`rating_ongoing`	Boolean	Whether the rating session is ongoing.
`controlled`	Boolean	Whether the network session is still controllable.
`final`	Boolean	Whether the last grant is the final one for this rating session.
`bypass`	Boolean	Whether the rating session has been bypassed by a pre-rating action.
`balances`	Table	The current internal balance information from the OCS.
`destination_ocs`	String	The current session destination for presentation to the OCS.
`destination_net`	String	The current session destination for the network response.
`hook_manager`	Object	The hook manager in use for the network session.
`edr_manager`	Object	The EDR manager in use for the network session.
`input_context`	Object	The input context in use for the network session.
`notification_handler`	Object	The notification handler in use.
`external_action_handler`	Object	The external action handler in use.

Note that objects for the service context should not be updated without consultation with N-Squared.

Getter Only Functions

Many service context functions act solely as getters for network session information.

These functions are always called without parameters to return the current value of the appropriate element, if any.

Function	Return Type	Description
`subscriber_identifiers`	Table	All subscriber identifiers in a table, keyed as defined in the N2IWF core. Possible keys are: `iwf_core.subscriber_identifiers.MSISDN` - the subscriber MSISDN `iwf_core.subscriber_identifiers.IMSI` - the subscriber IMSI `iwf_core.subscriber_identifiers.URI` - the subscriber URI
`last_gsu`	Integer	The last granted units in the rating session.
`grace_units`	Integer, Integer	The allowed and used units from the last grace handling.
`grace`	Boolean	Whether the network session is currently being handled in grace.
`originating`	Boolean	Whether the direction of the network session is considered to be originating by the network protocol handler.
`forwarding`	Boolean	Whether the direction of the network session is considered to be forwarding by the network protocol handler.
`terminating`	Boolean	Whether the direction of the network session is considered to be terminating by the network protocol handler.
`cug_match_found`	Boolean	Whether the last N2CUG external action found a match.
`cug_match_long`	String	The long number from the last N2CUG external action match, if any.
`cug_match_short`	String	The short code from the last N2CUG external action match, if any.
`cug_match_display_caller_sc`	Boolean	Whether the match from the last N2CUG external action allows caller short code display.
`cug_user_found`	Boolean	Whether the last N2CUG external action found a user.
`cug_user_long`	String	The long number from the last N2CUG external action user, if any.
`cug_user_is_ln`	Boolean	Whether the user from the last N2CUG external action was located by long number.

state_name / last_state_name

These functions return the names of the current or the last N2IWF state respectively, as defined in the N2IWF
core. Possible values are:

iwf_core.iwf_state_names.SETUP - new network session received
iwf_core.iwf_state_names.PRE_RATING - pre-rating
iwf_core.iwf_state_names.RATING_SESSION - OCS rating
iwf_core.iwf_state_names.POST_RATING - post-rating
iwf_core.iwf_state_names.ERROR - error handling

The state_name function may be provided a single parameter in order to set the N2IWF internal state. This should not be done without prior consultation with N-Squared.

looping

This function may be called in order to prepare the service context for a loop. It will clear out any existing rating session information in readiness for another to be potentially created.

This function takes no parameters and returns nothing.

get_by_dot

This function behaves identically to the N2SVCD utility function get_by_dot but:

uses only the context_fields table within the service context.
looks for additional selectors by preference.

This function takes two positional parameters:

Parameter	Type	Description
`k`	String	[Required] The (possibly dot-notated) key to retrieve.
`v`	Scalar	[Required] The comparison value being examined.

open_rating_session / continue_rating_session / finish_rating_session

These functions open, continue, or complete a rating session to the OCS.

Note that a service context can only have one rating session at any time. An open session must be completed before another can be started.

The open_rating_session function takes no parameters.

The continue_rating_session and finish_rating_session functions take an optional integer parameter for the used units from the last reservation, defaulting to 0 if not provided.

These functions return the result of the rating session function last_received.

add_used_amount

This function is used to add used units to the rating session in progress.

It takes a single integer parameter representing the new units used. This is added to the running total for the network session, and replaces the current used units for this reservation. Accordingly, it should only be called once per reservation.

This function returns the new total amount of units used.

clear_units

This function will clear the current rating session total and last-granted units.

This function takes no parameters and returns nothing.

rating_session / rating_session_state_id

These functions return the current rating session or its rating session state ID respectively, if a rating session exists.

These functions take no parameters.

grace_start / grace_end

These functions start or end grace handling on the network.

When starting grace, the units to allow (depending on the input protocol) must be provided as an integer.

When ending grace, the units used (depending on the input protocol) must be provided as an integer.

These functions return nothing.

update_var

This function can be used to update a variable. It will also notify the EDR manager of the change if the variable is configured to be written to an EDR or an EDR key is provided. Note that this function ignores the mutable value of the variable’s configuration.

This function takes three positional parameters:

Parameter	Type	Description
`name`	String	[Required] The name of the variable, as configured in the N2SVCD LogicApp configuration.
`value`	Scalar	The new value of the variable. If `nil`, this will clear the variable.
`edr_key`	String	The EDR key to use to write this variable to an EDR. Overrides any configured EDR key for this variable.

This function returns nothing.

add_balance

This function can be used to add or update balance information from the OCS.

This function takes four positional parameters:

Parameter	Type	Description
`balance_name`	String	[Required] The balance name.
`delta`	Integer	The delta to the balance. If not provided, defaults to `0`.
`exponent`	Integer	The exponent to apply. If not provided, defaults to `0`.
`currency`	String	The OCS value for the currency translation to apply for balance presentation. If not present, currency translation will not apply.

This function returns the new value of the balance.

set_direction

This function is used to set the direction of the network session, overriding the decision made by the
network protocol handler.

It takes a single enumerated parameter from the N2IWF core. Possible values are:

iwf_core.directions.ORIGINATING - an originating network session.
iwf_core.directions.FORWARDING - a forwarding network session.
iwf_core.directions.TERMINATING - a terminating network session.

This function returns nothing.

set_cug_details

This function is used to store the results of a N2CUG external action. of the network session, overwriting the last results, if any.

This function takes a single argument, a table expected to be in the format of a normal N2CUG lookup result.

This function returns nothing.