External Processing

External Processing

Prior to having their initial Diameter request constructed, calls may require external actions to occur in order to enrich the data available for or otherwise modify the call processing that will occur.

External processing rules can therefore be defined that allow other N2SVCD applications to be called as part of the pre-call handling. Rules are applied in the order listed and any match made is processed accordingly before proceeding with the remainder of the rule checking (if applicable).

If a rule does not specify any matching criteria, it will always match. Depending on the action called, this may impact performance of the system.

External processing takes place after tag assignment and before billing bypass.

An example external processing configuration might be:

...
        <external_processing>
          <rule tag="vlr" value="12345" action="ati" store_in="vlr" msisdn_src="logical"/>
          <rule tag="msc" value="12345" action="ati" store_in="vlr" imsi_src="iMSI_digits"/>
          <rule terminating="0" action="cug" configuration="originating"/>
          <rule terminating="1" action="cug" configuration="terminating" />
        </external_processing>

        <cug>
          <configuration name="common">
            <no_user_found>
              <rule action="continue"/>
            </no_user_found>
            <not_allowed_list>
              <rule action="release"/>
            </not_allowed_list>
            <not_allowed_user>
              <rule action="release"/>
            </not_allowed_user>
            <user_number>
              <rule from_tag="logical"/>
            </user_number>
            <store_tags match_found="cug"
                        group_name="cug_group"
                        list_found="cug_list"/>
          </configuration>
          <configuration name="originating"
                         include="common">
            <match_number>
              <rule idp="normalised_called_party"/>
            </match_number>
            <sci_actual>
              <rule literal="016400"/>
            </sci_actual>
            <sci_virtual>
              <rule literal="016500"/>
            </sci_virtual>
          </configuration>
          <configuration name="terminating"
                         include="common"
                         allow_sc_user="1"
                         allow_match_sc="0"
                         show_sc="1">
            <match_number>
              <rule idp="normalised_calling_party"/>
            </match_number>
          </configuration>
        </cug>
...

Configuration Details

Each rule can support the following attributes:

Attribute Type Description
action String [Required] The External Process Action to invoke when this rule is matched.
tag String [Conditional] The tag name to match the value for If tag is present, value must also be present.
tag_x String [Conditional] As for tag, but with x representing a unique pairing, e.g. tag_1 or tag_a. A matching value_x must also be present.
value (various) [Conditional] The string or integer value to match against during rule selection. Required when tag is present.
value_x (various) [Conditional] As for value, but with x representing a unique pairing, e.g. value_1 or value_a. A matching tag_x must also be present.
originating Boolean Whether this rule applies for originating calls.
(Default: true)
forwarding Boolean Whether this rule applies for forwarding calls.
(Default: true)
terminating Boolean Whether this rule applies for terminating calls.
(Default: true)
mandatory Boolean Whether this external process must complete successfully for the call to continue. If false, the call will be allowed to continue without the external processing completion. If true, Error Handling Rules will be used to end the call.
(Default = false, continue on failure)
(other available fields) (various) Any number of selector rule available fields or additional External Process Action fields.

Note that, unlike other selector rules, the call state selectors at_initial, at_update, and at_terminate are not used, as external processing can only occur at the start of a call.

External Process Actions

Each external processing allows the specification of a single action to take when a rule is matched.

Note that all external processing rules are only applicable prior to initial interrogation, i.e. when the call is first received.

Some rules may require or allow additional parameters than those listed above to be specified.

ATI Action

Specifying the external processing action ati causes a MAP Any Time Interrogation message to be sent to the network. Such a message will return the subscriber’s current location in E.164 format, which is normally the VLR number that the subscriber is served by.

The following parameters are available when sending an ATI.

Parameter Type Description
store_in String [Required] The tag to store the returned subscriber location in.
msisdn_src Hex String [Conditional] The selector field or tag to read the subscriber MSISDN to query from. One and only one of msisdn and imsi must be provided.
imsi_src Hex String [Conditional] The selector field or tag to read the subscriber IMSI to query from. One and only one of msisdn and imsi must be provided.

CUG Action

Specifying the external processing action cug causes a lookup to be done on the local Closed User Group database. This requires that the CUG database application name is configured, along with the appropriate configuration to connect to the database in the N2SVCD DBApp itself.

The following parameters are available when specifying a CUG action.

Parameter Type Description
configuration String The name of the CUG configuration to use when this rule applies. If not specified, this rule will use the default CUG configuration.

For further information on CUG concepts, refer to the CUG functionality overview.

CUG Configurations

Due to their complexity, CUG configurations are specified separately to the external processing rule that triggers them. Within the cug section, each configuration item specifies the values that are used when the rule(s) that trigger them apply.

The CUG configuration section takes the following structure:

...
        <cug>
          <configuration attribute="value">
            <child_node>
              <rule attribute="value"/>
            </child_node>
            <child attribute="value"/>
          </configuration>
          <configuration>
              ...
          </configuration>
        </cug>
...

CUG configurations may inherit values from other CUG configurations by use of the include directive. When this is used, the including configuration will take all values (including default values) from the referenced CUG configuration before applying its own configuration values. Note that referenced CUG configuration nodes may also include other configurations hierarchically.

Each CUG configuration allows the following parameters.

Parameter Location Type Description
name configuration attribute String The name of this CUG configuration, as referenced in cug external processing rules or CUG configuration include directives.
include configuration attribute String The name of another CUG configuration to use as the base for this CUG configuration.
user_number configuration child Array The list of CUG selector rules rule elements to use to populate the CUG user number.
match_number configuration child Array The list of CUG selector rules rule elements to use to populate the CUG match number.
no_user_found configuration child Array The list of CUG rule action rule elements to use to select the action to take when no CUG user_number is found.
not_allowed_list configuration child Array The list of CUG rule action rule elements to use to select the action to take when the CUG user cannot make/receive calls to/from the CUG match due to blacklist or whitelists applying.
not_allowed_user configuration child Array The list of CUG rule action rule elements to use to select the action to take when the CUG user cannot make/receive calls to/from the CUG match (or lack of match) due to user restriction settings applying.
no_match_found configuration child Array The list of CUG rule action rule elements to use to select the action to take when a CUG user_number is found but a CUG match_number is not found (and the call is not disallowed by list or user configuration).
match_found configuration child Array The list of CUG rule action rule elements to use to select the action to take when a CUG user_number is found and a CUG match_number is also found (and the call is not disallowed by list or user configuration).
apply_lists configuration attribute Boolean Whether to apply the restrictions of number lists.
(Default: 1)
allow_sc_user configuration attribute Boolean Whether to allow the user_number to be populated via a short code search.
(Default: 0)
allow_match_sc configuration attribute Boolean Whether to allow the match_number to be matched against short codes.
(Default: 1)
show_sc configuration attribute Boolean Whether to send the match_number for display to the other party as part of the Connect operation.
(Default: 0)
store_tags configuration child Map The attributes of this node specify the CUG output value and an associated tag to store that value in, e.g. match_found="cug". The available CUG output values are as listed in the CUG output fields.

CUG Rule Selection

Each CUG configuration supports selecting the action to take when a CUG user is or isn’t found or when a call is disallowed. Each of these is supported as a list of rules that are applied in the order listed until a match is made.

Each rule can support the following attributes:

Attribute Type Description
action String [Required] The action to take when this rule is matched. Possible values are shown under CUG Rule Actions.
tag String [Conditional] The tag name to match the value for If tag is present, value must also be present.
tag_x String [Conditional] As for tag, but with x representing a unique pairing, e.g. tag_1 or tag_a. A matching value_x must also be present.
value (various) [Conditional] The string or integer value to match against during rule selection. Required when tag is present.
value_x (various) [Conditional] As for value, but with x representing a unique pairing, e.g. value_1 or value_a. A matching tag_x must also be present.
originating Boolean Whether this rule applies for MO calls.
(Default: true)
forwarding Boolean Whether this rule applies for MF calls.
(Default: true)
terminating Boolean Whether this rule applies for MT calls.
(Default: true)
cause Integer The release cause to send to the network if the action releases the call.
(Default: 31)
seconds Integer [Required with action = continue_period] The number of seconds a call to continue for unbilled, if appropriate to the action.
announcement_id Integer [Required with action = announcement_release or announcement_connect] The announcement ID to play to the caller, if appropriate to the action.
announcement_source String The tag to use as the announcement ID to play to the caller, if appropriate to the action. If no value or a non-numeric value is found, announcement_id will be used instead.
srp_name String [Required with action = announcement_release or announcement_connect] The SRP name (as configured in the ScpApp) to use to play an announcement to the caller, if appropriate to the action.
srp_source String The tag to use as the SRP name to use to play an announcement to the caller, if appropriate to the action. If no value or a non-numeric value is found, srp_name will be used instead.
divert_to String [Required with action = connect or announcement_connect] The normalised destination digits to connect the call to, if appropriate to the action.
notification String A notification message name to send when this rule applies.
fci or sci String An FCI or SCI message name to send when this rule applies. Only available for certain actions.
(other available fields) (various) Any number of selector rule available fields.

Note that, unlike other selector rules, the call state selectors at_initial, at_update, and at_terminate are not permitted, as billing bypass can only occur at the start of a call.

CUG Rule Actions

Some CUG rules, in addition to the parameters for rule selection, allow the specification of a single action to take when a rule is matched during processing.

Note that no further processing (including other external actions) will be applied for any action taken other than continue or announcement_continue. In the latter case, the announcement to play will be performed prior to any other actions from other rules.

The following actions are available:

Action Required
Parameters
Optional
Parameters
FCI/SCI? Description
continue - - Yes Continue the call normally with rating interaction where applicable.
continue_free - - Yes Allow the call to continue unmonitored on the network with no rating interaction.
continue_period seconds Yes Allow the call to continue monitored on the network for a limited time with no further interaction.
release - cause No Release the call immediately with the given cause.
connect divert_to - Yes Terminate the call to the provided divert_to with no rating interaction.
announcement_continue announcement_id
srp_name
announcement_source
srp_source
Yes Play announcement ID announcement_id on the resource srp_name (as configured under SRP Endpoints) and then apply handling as for continue.
announcement_release announcement_id
srp_name
announcement_source
srp_source
cause
No Play announcement ID announcement_id on the resource srp_name (as configured under SRP Endpoints) and then apply handling as for release.
announcement_connect announcement_id
srp_name
divert_to
announcement_source
srp_source
Yes Play announcement ID announcement_id on the resource srp_name (as configured under SRP Endpoints) and then apply handling as for connect.
abort - - No Send a TC_ABORT to end the call immediately.

Default CUG Configuration

In cases where no configuration is specified for a CUG external processing action rule, the values used at runtime will be as if the following CUG configuration applies:

          <configuration name="__default" 
                         allow_sc_user="0"
                         allow_match_sc="1"
                         show_sc="0">
            <match_found>
                <rule action="continue" at_update="0" at_terminate="0"/>
            </match_found>
            <no_match_found>
                <rule action="continue" at_update="0" at_terminate="0"/>
            </no_match_found>
            <no_user_found>
                <rule action="continue" at_update="0" at_terminate="0"/>
            </no_user_found>
            <not_allowed_list>
                <rule action="release" cause="31" at_update="0" at_terminate="0"/>
            </not_allowed_list>
            <not_allowed_user>
                <rule action="release" cause="31" at_update="0" at_terminate="0"/>
            </not_allowed_user>
            <user_number>
              <rule idp="normalised_calling_party"/>
            </user_number>
            <match_number>
                <rule idp="normalised_called_party"/>
            </match_number>
          </configuration>

The appropriate default values will also be used in cases where a CUG configuration does not specify any of the following keys:

For the following action rules, the default value will be added as a catch-all after any user-specified rules:

Note that the CUG configuration name __default is reserved and may not be used for user-defined configurations.

CUG Output Fields

When a CUG lookup is made, an EDR is written with the results of that lookup. The fields within that lookup are available to be written to tags so that they can be included in further EDRs written by the DSG-SCP service.

The following CUG output fields are available to be specified as part of a CUG configuration’s store_tags definition. Note that they will only contain values if the appropriate action happened, e.g. there will be no user_number present if no CUG user was found.

Field Name Type Description
user_found 0 or 1 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_prefix_match 0 or 1 Whether the CUG user was matched by prefix.
user_range_size Integer The range size of the CUG user.
user_orig_on_net_allowed 0 or 1 Whether the CUG user is allowed to make calls within the CUG group.
user_orig_off_net_allowed 0 or 1 Whether the CUG user is allowed to make calls outside the CUG group.
user_term_on_net_allowed 0 or 1 Whether the CUG user is allowed to receive calls from within the CUG group.
user_term_off_net_allowed 0 or 1 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 0 or 1 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 0 or 1 Whether the match was made against the long number of the CUG match user.
match_is_prefix 0 or 1 Whether the match was made by prefix.
match_range_size Integer The range size of the CUG match user.
match_virtual 0 or 1 Whether the CUG match user is virtual.
match_display_caller_sc 0 or 1 Whether caller shortcodes will be shown on Connect messages.
list_found 0 or 1 Whether a match was made to a blacklist or a whitelist.
list_disallowed 0 or 1 Whether the applicable list disallowed the call.
list_entry_id Integer The database ID of the applicable list.
list_whitelist_match 0 or 1 Whether the applicable list is a whitelist.
list_is_prefix 0 or 1 Whether the applicable list match was made by prefix.

For further information on CUG concepts, refer to the CUG functionality overview.