External Actions

External Actions Configuration

At the beginning of each IWF state, network sessions may require external actions to occur.

External processing rules can therefore be defined that allow other N2SVCD applications and features to be called as part of each pre-state 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). All external action rules will be checked for each session, regardless of any matches made.

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 rules are defined in the EXTERNAL_ACTIONS LogicApp service global variable. Each of these rules must also refer to an external action type, defined in the EXTERNAL_ACTION_TYPES LogicApp service global variable.

External Action Rules

The rules that determine which external action are triggered are defined in the EXTERNAL ACTIONS global variable. An example configuration might be:

<global name="EXTERNAL_ACTIONS" type="array">
    <rule var="vlr" value="" external="ati_msisdn" mandatory="1" service.at_rating="1"/>
    <rule normalised_calling_party_prefix="642" external="cug"/>
</global>

In addition to both the standard rules engine and N2IWF selector rule extensions, each rule in the EXTERNAL ACTIONS global variable supports the following attributes:

Note that if none of the state selector rule extensions service.at_setup, service.at_pre, service.at_rating, or service.at_post are specified, it is assumed that the external action rule applies only at the pre-rating state, i.e. as if service.at_pre were set to a truthy value.

External action rules do not have any default rules. If no rules apply, no external actions will be triggered.

External Action Types

The available external action types that can be applied by external action rules are defined in the EXTERNAL_ACTION_TYPES global variable. An example external rule type configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="cug" action="n2cug_lookup">
        <user_number from_var="logical"/>
        <match_number type="array">
            <rule originating="1" source="normalised_called_party"/>
            <rule source="normalised_calling_party"/>
        </match_number>
        <allow_match_sc type="array">
            <rule originating="1" literal="1"/>
            <rule literal="0"/>
        </allow_match_sc>
        <allow_sc_user type="array">
            <rule originating="1" literal="0"/>
            <rule literal="1"/>
        </allow_sc_user>
        <terminating type="array">
            <rule originating="1" literal="0"/>
            <rule literal="1"/>
        </terminating>
        <suppress_edr literal="0"/>
    </external>
    <external name="ati_msisdn" action="map_ati">
        <gsm_scf_digits literal="6412345"/>
        <hlr_gt_digits literal="642000001"/>
        <hlr_ssn literal="6"/>
        <hlr_timer_secs literal="1"/>
        <msisdn_source from_var="logical"/>
        <store_vlr literal="vlr"/>
    </external>
</global>

Each external action type must specify the following parameters:

MAP Messages

Specifying the external action types map_ati or map_srism causes a MAP Any Time Interrogation or Send Routing Information for Short Message operation, respectively, to be sent to an HLR in the network. Such messages will return information about the subscriber’s mobile details and current location. Both messages use MAP v3.

Using these external action requires N2SVCD MAP integration.

Parameters for MAP messages are listed below, as:

• Common parameters for all MAP message types.
• ATI parameters for MAP ATI messages only.
• SRI-SM parameters for MAP SRI-SM messages only.

Note that each parameter listed (except required) is an N2SVCD rule engine ruleset and that the N2IWF selector rule extensions apply.

If a successful response is received, the subscriber’s applicable details will be populated into the specified variable(s) and/or EXTERNAL EDR tag(s).

Common MAP Parameters

The following additional external action type parameters are available when specifying any MAP external action:

MAP ATI Parameters

MAP ATI messages may be sent as external actions by specifying the external action typ map_ati. An example MAP ATI external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="ati_msisdn" action="map_ati">
        <gsm_scf_digits literal="6412345"/>
        <hlr_gt_digits literal="642000001"/>
        <hlr_ssn literal="6"/>
        <hlr_timer_secs literal="1"/>
        <msisdn_source from_var="logical"/>
        <store_vlr literal="vlr"/>
    </external>
</global>

The following additional external action type parameters are available when sending an ATI:

MAP SRI-SM Parameters

MAP SRI-SM messages may be sent as external actions by specifying the external action typ map_srism. An example MAP SRI-SM external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="sri_sm_imsi" action="map_srism">
        <sca_digits literal="6412345"/>
        <hlr_gt_digits literal="642000001"/>
        <hlr_ssn literal="6"/>
        <hlr_timer_secs literal="1"/>
        <msisdn_source from_var="logical"/>
        <store_imsi literal="sri_sm_imsi"/>
        <edr_imsi literal="sri_sm_imsi"/>
        <store_sgsn literal="sri_sm_sgsn"/>
        <edr_sgsn literal="sri_sm_sgsn"/>
        <optional>sgsn</optional>
    </external>
</global>

The following additional external action type parameters are available when sending an SRI-SM:

N2CUG Lookup

Specifying the external processing action type n2cug_lookup causes a lookup to be done using the N-Squared Closer User Groups library framework.

Using this external action requires N2SVCD N2CUG integration.

An example N2CUG external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="cug" action="n2cug_lookup">
        <user_number from_var="logical"/>
        <match_number type="array">
            <rule originating="1" source="normalised_called_party"/>
            <rule source="normalised_calling_party"/>
        </match_number>
        <allow_match_sc type="array">
            <rule originating="1" literal="1"/>
            <rule literal="0"/>
        </allow_match_sc>
        <allow_sc_user type="array">
            <rule originating="1" literal="0"/>
            <rule literal="1"/>
        </allow_sc_user>
        <terminating type="array">
            <rule originating="1" literal="0"/>
            <rule literal="1"/>
        </terminating>
        <suppress_edr literal="0"/>
    </external>
</global>

The following additional external action type parameters are available when specifying an N2CUG lookup:

Note that each parameter is an N2SVCD rule engine ruleset and that the N2IWF selector rule extensions apply.

If a successful response is received, the lookup details will be populated into the field service.cug as per a normal N2CUG lookup.

Refer to the N2CUG lookup function documentation for further details.

REST Messages

Specifying the external action type rest causes an HTTP(S) REST message to be sent. Responses from the message may be mapped to arbitrary variables.

An example REST external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="rest_xml" action="rest">
        <path>/subscriber/$logical$/check</path>
        <query>location=$vlr$</query>
        <method>GET</method>
        <content_patterns type="array">
            <pattern var="rest_l"              pattern="http_headers[name=Location].value"/>
            <pattern var="rest_t" edr="rest_t" pattern="content.data.thing"/>
            <pattern              edr="rest_h" pattern="http_headers[2].value"/>
        </content_patterns>
        <store_code>rest_code</store_code>
        <edr_code>rest_c</edr_code>
    </external>
</global>

The following additional external action type parameters are available when specifying a REST external action:

The path, query, fragment, username, password, and content parameters may contain dynamic text definitions.

A REST response is considered successful if the HTTP response status code is in the range 200-299.

If a successful response is received, the applicable details will be populated into the specified variable(s) and/or variable EDR tag(s).

An unsuccessful response will populate only the HTTP status code (if configured to do so). The error encountered will be raised as a warning and stored in the ERROR external action EDR field.

SOAP Messages

Specifying the external action type soap causes an HTTP(S) SOAP message to be sent. Responses from the message may be mapped to arbitrary variables.

An example SOAP external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="soap1" action="soap">
        <path>/subscriber/$logical$/check</path>
        <query>location=$vlr$</query>
        <soap_message_name>check</soap_message_name>
        <soap_action>action1</soap_action>
        <args>
            <foo>bar</foo>
        </args>
        <args_patterns type="array">
            <pattern var="soap_l"              pattern="http_headers[name=Location].value"/>
            <pattern var="soap_t" edr="soap_t" pattern="args.thing"/>
            <pattern              edr="soap_h" pattern="http_headers[2].value"/>
        </args_patterns>
        <store_code>soap_code</store_code>
        <edr_code>soap_c</edr_code>
    </external>
</global>

The following additional external action type parameters are available when specifying a SOAP external action:

The path, query, fragment, and args parameters may contain dynamic text definitions.

As noted above, the args parameter (if supplied)) must be native (not CDATA escaped) XML representing the content of the SOAP Body tag.. This will be transcoded to the appropriate SOAP XML internally according to the client configuration.

A SOAP response is considered successful if the HTTP response status code is in the range 200-299 and no SOAP Fault is returned.

If a successful response is received, the applicable details will be populated into the specified variable(s) and/or variable EDR tag(s).

An unsuccessful response will populate only the HTTP status code (if configured to do so). The error encountered will be raised as a warning and stored in the ERROR external action EDR field.

Diameter Messages

Specifying the external action type diameter causes a Diameter event (CC-Request-Type = 4) message to be sent.

An example Diameter external action configuration might be:

<global name="EXTERNAL_ACTION_TYPES" type="array">
    <external name="diam1" action="diameter">
        <edr_dsid>ext_dsid</edr_dsid>
        <edr_rc>ext_rc</edr_rc>
        <send_avps type="array">
            <avp name="Action-Name" literal="diam1" />
            <avp name="Multiple-Services-Credit-Control">
                <value type="array">
                    <avp name="Extension-1" edr="e1" >
                        <value type="array">
                            <rule from_var="logical" />
                        </value>
                    </avp>
                </value>
            </avp>
            <avp name="Extension-3" literal="3" />
        </send_avps>
        <read_avps type="array">
            <avp name="Remaining-Balance">
                <value type="array">
                    <avp name="Unit-Value">
                        <value type="array">
                            <avp name="Value-Digits" to_bal_units="remaining" to_var="bal_value" edr="bal_value" />
                            <avp name="Exponent" to_bal_exponent="remaining" to_var="bal_exp" edr="bal_exp" />
                        </value>
                    </avp>
                    <avp name="Currency-Code" to_bal_currency="remaining" to_var="currency" edr="currency" />
                </value>
            </avp>
            <avp name="Extension-2" to_var="ext2" edr="e2" mandatory="1" />
            <avp name="Extension-3" to_var="ext3" edr="e3" />
        </read_avps>
    </external>
</global>

The following additional external action type parameters are available when specifying a Diameter external action:

The following AVPs (in order) are added to all Diameter external actions automatically:

• Session-Id as per Diameter parameters.
• Auth-Application-Id, always set to 4.
• Service-Context-Id, from scid parameter or as per Diameter requests. Note that, as per the N2IWF state model, the Service-Context-Id is only determined during the setup state. Any Diameter external action that is sent at the start of the setup state will therefore have to have a static scid parameter defined. If no value is available to populate Service-Context-Id, the external action will fail.
• CC-Request-Type, always set to 4 (EVENT_REQUEST).
• CC-Request-Number, always set to 1.
• Event-Timestamp, set to the current time.
• Subscription-Id and/or Subscription-Id-Extension as per Diameter parameters.

By default, no AVP values for either request or response are written to EDR, but this can be achieved as required using the edr_dsid action parameter or the per-AVP edr parameter.

A Diameter external action response is considered successful if the Result-Code AVP has a value in the range 2000-2999 and all read AVPs marked as mandatory have values.

If a data hook is used to provide details for a Diameter external action, the array(s) for send_avps and read_avps are expected to be populated with the value parameter already present. The automatically-added AVPs listed above should not be specified.

Response Path Parsing

Some external actions support specifying individual response fields that should be copied to variables or written to EDRs.

Such configuration is defined within an array consisting of zero or more parsing definitions. The possible values for each definition are:

Patterns

Each pattern consists of a series of strings, separated either by a period (for hash objects) or square brackets (for array objects).

Array object patterns may be specified by:

• positive index (starting from 1) for the nth array member from the array start.
• negative index (starting from -1) for the nth array member from the array end.
• by key/value (e.g. key=value), for the first matching case where an array member has the key set to value.

Note that the name of each of the parsing definitions is freeform and not used.

Example

As a worked example, consider the following configuration for a REST action:

    <content_patterns type="array">
      <pattern var="rest1"          pattern="http_headers[1].value"/>
      <pattern var="rest2" edr="r2" pattern="http_headers[name=Location].value"/>
      <pattern             edr="r3" pattern="content.user.id"/>
    </content_patterns>

If a response was received such as:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/users/123

{
  "message": "New user created",
  "user": {
    "id": 123,
    "firstName": "Example",
    "lastName": "Person",
    "email": "bsmth@example.com"
  }
}

… this would be received for parsing as a REST-C-RESPONSE:

{
    code = 201,
    http_headers = {
        { name = 'Content-Type', value = 'application/json' },
        { name = 'Location', value = 'http://example.com/users/123' }
    },
    content_type = 'application/json',
    content = '{
  "message": "New user created",
  "user": {
    "id": 123,
    "firstName": "Example",
    "lastName": "Person",
    "email": "bsmth@example.com"
  }
}'
}

… and the variables would be populated as:

• rest1 (http_headers[1].value) = application/json
• rest2 (http_headers[name=Location].value) = http://example.com/users/123

… and EDR tags written as:

• R2=http://example.com/users/123
• R3=123