Navigation :

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_src` and `imsi_src` 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_src` and `imsi_src` must be provided.
`src_noa`	Integer	The Nature of Address to set for the source MSISDN or IMSI when sending requests to the HLR. Possible values are: `0` - Unknown `1` - International `2` - National Significant `3` - Network Specific `4` - Subscriber `5` - Reserved `6` - Abbreviated (Default = `1`, International).
`src_npi`	Integer	The Number Plan Indicator to set for the source MSISDN or IMSI when sending requests to the HLR. Possible values are: `0` - Unknown `1` - ISDN/telephony (E.163, E.164) `2` - Generic `3` - Data (X.121) `4` - Telex (F.69) `5` - Maritime (E.210, E.211) `6` - Land mobile (E.212) `7` - ISDN/mobile (E.214) `14` - Private or network-specific (Default = `1`, ISDN/telephony).

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"` to write the output of `match_found` to the tag `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.
`srf_name`	String	[Required with `action` = `announcement_release` or `announcement_connect`] The SRF name (as configured in the `ScpApp`) to use to play an announcement to the caller, if appropriate to the `action`.
`srf_source`	String	The tag to use as the SRF 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, `srf_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

CUG rules, in addition to the parameters for rule selection, require 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` `srf_name`	`announcement_source` `srf_source`	Yes	Play announcement ID `announcement_id` on the resource `srf_name` (as configured under SRF Endpoints) and then apply handling as for `continue`.
`announcement_release`	`announcement_id` `srf_name`	`announcement_source` `srf_source` `cause`	No	Play announcement ID `announcement_id` on the resource `srf_name` (as configured under SRF Endpoints) and then apply handling as for `release`.
`announcement_connect`	`announcement_id` `srf_name` `divert_to`	`announcement_source` `srf_source`	Yes	Play announcement ID `announcement_id` on the resource `srf_name` (as configured under SRF 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:

allow_sc_user
allow_match_sc
show_sc
user_number
match_number

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

match_found
no_match_found
no_user_found
not_allowed_list
not_allowed_user

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.