TCAP Lua Agent

Introduction

The TcapLuaAgent is a helper agent for Lua scripts running within the LogicApp.

• The TCAP Agent may be used by any Lua script, regardless of which Service initiated that script.

The TcapLuaAgent communicates with one or more instances of the SigtranApp which can be used to communicate via one or more external M3UA or SUA connections.

The TcapLuaAgent communicates with the SigtranApp using the TCAP-… messages.

TCAP Agent methods are accessed via the “n2.n2svcd.tcap_agent” module:

    local tcap_api = require "n2.n2svcd.tcap_agent"

Configuring TcapLuaAgent

The TcapLuaAgent is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <parameters>
            ...
            <parameter name="default_tcap_app_name" value="SIGTRAN-C"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="SigtranApp::TcapLuaAgent" libs="../apps/sigtran/lib">
                <config tcap_timeout_secs="20" ignore_reset_timer="1"/>
              </agent>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

In addition, the TcapLuaAgent must be configured with the name of the SigtranApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

The TcapLuaAgent API

All methods may raise a Lua Error in the case of exception, including:

• Invalid input parameters supplied by Lua script.
• Unexpected results structure returned from SigtranApp.
• Processing error occurred at SigtranApp.
• Timeout occurred at SigtranApp.

.ignore_reset_timer [Synchronous]

The ignore_reset_timer method overrides the default behavior for handling of ResetTimer INAP operations.

This method accepts the following parameters:

The ignore_reset_timer method returns nil.

[Fragment] Example (Enable ignore of ResetTimer):

    tcap_api.ignore_reset_timer (true)

.auto_activity_result [Synchronous]

The auto_activity_result method overrides the default behavior for handling of ActivityTest INAP operations.

This method accepts the following parameters:

The auto_activity_result method returns nil.

[Fragment] Example (Enable automatic handling of ActivityTest):

    tcap_api.auto_activity_result (true)

.initialise [Synchronous]

The initialise method creates and prepares a new outbound TCAP transaction for the subsequent sending of a TCAP BEGIN message.

This method accepts the following parameters:

The initialise method returns nil.

[Fragment] Example (Initialise CAMEL2 Transaction):

    local scp_dra = {
      dgt_digits = "049991000"
    }
    tcap_api.initialise (nil, 'ssp.scp.1', scp_dra, tcap_api.APPLICATION_CONTEXT_ALIASES['camel2'])

.map_register_ati3_msisdn [Synchronous]

There are three mechanisms by which Lua scripts running in the LogicApp can becomes associated with a new TCAP transaction. Those mechanisms are as follows:

1. An incoming TCAP BEGIN can start a new script by invoking a Lua Service.
2. An already-running Lua script can create a new outbound TCAP transaction using the initialise method.
3. An already-running Lua script can register to accept a new unbound TCAP transaction using one of the register methods.

The most common use of these “register” methods is a test script which is testing another application and which expects that “application under test” to generate a TCAP transaction. e.g. we are writing a test script to send InitialDP and simulate a call for a mobile subscriber. We expect the application to send out a MAP AnyTimeInterrogation message to determine the current subscriber state.

The map_register_ati3_msisdn method informs the LogicApp that this currently running script instance expects to receive a new inbound TCAP BEGIN in the near future. The LogicApp will register that expectation, and if/when the matching AnyTimeInterrogation arrives, it will be delivered to the script instance.

Naturally, only one script instance may be registered for the exact ATI MSISDN digits at any one time.

The full set of matching conditions for the inbound TCAP BEGIN is:

• The Dialogue part must have the TCAP Application Context = 4.0.0.1.0.51.3.
• There must be exactly one component.
• The component must be Invoke.
• The Invoke must have operation ID = 71 (ATI).
• The AnyTimeInterrogation must be decodable.
• The AnyTimeInterrogation must contain the subscriberIdentity.
• The subscriberIdentity MSISDN digits must exactly match the specified digits.

This is a synchronous method. It sets the registration information in preparation for a message and then returns immediately. The expect_invoke method must then be used to retrieve the actual ATI operation if/when it arrives.

The registration method accepts the following parameters:

The map_register_ati3_msisdn method returns nil.

[Fragment] Example (Register for ATI Transaction):

    -- Register to expect an inbound AnyTimeInterrogationRequest for our MSISDN.
    tcap.map_register_ati3_msisdn ('hlr.scp.1', '414511860')

    -- EXPECT AnyTimeInterrogationRequest
    local result = tcap.expect_invoke ('hlr.scp.1')

    tcap.check_opcode ('hlr.scp.1', result, map_api.OPCODE_AnyTimeInterrogationRequest, 'map AnyTimeInterrogationRequest')
    local arg_AnyTimeInterrogationRequest = map_api.decode_op (result.opcode, result.parameter)

.map_deregister [Synchronous]

This method will cancel any existing prior registration for all/any inbound MAP operation.

If no MAP registration is present, this method will silently suceed.

The map_deregister method taks no parameters.

At most one MAP registration may be activated at any time, and so it is not necessary to resupply the registration parameters here, since there is no ambiguity.

[Fragment] Example (De-Register any current MAP registration):

    tcap.map_deregister ()

.send_components [Synchronous]

The send_components method sends one or more TCAP Components on a previously initialised outbound TCAP transction. The components are sent in a single TCAP message. The first message sent on an initialised TCAP transction must be TCAP BEGIN. Subsequent messages may be TCAP CONTINUE or TCAP END.

The transaction becomes closed automatically if a TCAP END is sent.

This method accepts the following parameters:

The send_components method returns nil.

[Fragment] Example (Encode/Send RRBCSM):

    -- SEND EventReportBCSM
    arg_EventReportBCSM = {
      eventSpecificInformationBCSM = {
        oDisconnectSpecificInfo = { releaseCause_cause = 12 }
      },
      eventTypeBCSM = 9,
      legID = { sendingSideID_hex = '01' }
    }
    param_EventReportBCSM = inap_api.encode_op (inap_api.OPCODE_EventReportBCSM, arg_EventReportBCSM, nil, nil)

    tcap_api.send_components ('ssp.scp.1', { { type = tcap_api.CT_INVOKE, opcode = inap_api.OPCODE_EventReportBCSM, parameter = param_EventReportBCSM } }, tcap_api.TYPE_CONTINUE)

[Fragment] Example (Encode/Send ProcessUSSD Request):

    local scp_dra = { dpc = 2068, dssn = 120 }
    tcap_agent.initialise (nil, 'hlr.scp.1', scp_dra, tcap_agent.APPLICATION_CONTEXT_ALIASES['ussd2'])

    -- Start USSD session.
    local param_ProcessUnstructuredSSRequest = map_agent.encode_op (map_agent.OPCODE_ProcessUnstructuredSSRequest, { msisdn_digits = '9607499901', ussdString_text = '*123#' }, nil, nil)

    -- MAP-OPEN is required (empty in this case).
    tcap_agent.send_components ('hlr.scp.1', { { type = tcap_agent.CT_INVOKE, opcode = map_agent.OPCODE_ProcessUnstructuredSSRequest, parameter = param_ProcessUnstructuredSSRequest } }, tcap_agent.TYPE_BEGIN, {})

.send_empty_end [Synchronous]

The send_empty_end method sends one an empty TCAP END previously initialised outbound TCAP transction.

The transaction becomes closed automatically.

This method accepts the following parameters:

The send_empty_end method returns nil.

[Fragment] Example (Send Empty END):

    -- SEND EventReportBCSM
    tcap_api.send_empty_end ('ssp.scp.1')

.send_abort [Synchronous]

The send_abort method sends a TCAP ABORT message on a previously initialised outbound TCAP transction.

The transaction is subsequently closed.

This method accepts the following parameters:

The send_abort method returns nil.

[Fragment] Example (Send User Abort):

    tcap_api.send_abort ('ssp.scp.1', nil, 1, { "Processing Error 3007-A" })

.expect_invoke [Asynchronous]

The expect_invoke method waits until a TCAP Invoke component is received on the specified TCAP transaction.

• If the transaction is not registered for this instance, an error is raised.
• If an Invoke component has previously been received but not handled, it will be returned immediately.
• If the received component is/was a ReturnResult/ReturnError, an error is raised.
• If the received message is/was a TCAP ABORT, an error is raised.
• If the transaction is closed with no unhandled components, an error is raised.
• If the timeout expires with no message received, an error is raised.

This method accepts the following parameters:

The expect_invoke method returns the following result structure.

[Fragment] Example (Expect ApplyCharging Invoke):

    result = tcap_api.expect_invoke ('ssp.scp.1')

    tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_ApplyCharging, 'INAP ApplyCharging')

.expect_result [Asynchronous]

The expect_result method waits until a TCAP ReturnResult component is received on the specified TCAP transaction.

• If the transaction is not registered for this instance, an error is raised.
• If an ReturnResult component has previously been received but not handled, it will be returned immediately.
• If the received component is/was a Invoke/ReturnError, an error is raised.
• If the received message is/was a TCAP ABORT, an error is raised.
• If the transaction is closed with no unhandled components, an error is raised.
• If the timeout expires with no message received, an error is raised.

This method accepts the following parameters:

The expect_result method returns the following result structure.

[Fragment] Example (Expect ProcessUnstructuredSSRequest ReturnResult):

    result = tcap_api.expect_result ('hlr.scp.1')
    tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequest / ReturnResult')
    tcap_api.match_received_last_component ('hlr.scp.1', result, true)

    local arg_ProcessUnstructuredSSRequestResult = map_api.decode_result (result.opcode, result.parameter, nil, nil)

    local exp_ProcessUnstructuredSSRequestResult = { ussdString_text = 'Early Response Message' }
    map_api.match_result (result.opcode, arg_ProcessUnstructuredSSRequestResult, exp_ProcessUnstructuredSSRequestResult, nil)

.expect_error [Asynchronous]

The expect_error method waits until a TCAP ReturnError component is received on the specified TCAP transaction.

• If the transaction is not registered for this instance, an error is raised.
• If an ReturnError component has previously been received but not handled, it will be returned immediately.
• If the received component is/was a Invoke/ReturnResult, an error is raised.
• If the received message is/was a TCAP ABORT, an error is raised.
• If the transaction is closed with no unhandled components, an error is raised.
• If the timeout expires with no message received, an error is raised.

This method accepts the following parameters:

The expect_error method returns the following result structure.

[Fragment] Example (Expect ProcessUnstructuredSSRequest ReturnError):

    local result = tcap_api.expect_error ('hlr.scp.1')
    tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequest / ReturnError')
    tcap_api.match_received_last_component ('hlr.scp.1', result, true)
    match.integer ('ProcessUnstructuredSSRequest error_code', result.error_code, 27)

.expect_empty_end [Asynchronous]

The expect_empty_end method waits until a TCAP END is received on the specified TCAP transaction, with no contained Components.

• If the transaction is not registered for this instance, an error is raised.
• If any component has previously been received but not handled, an error is raised.
• If the received message is/was a TCAP ABORT, an error is raised.
• If the timeout expires with no message received, an error is raised.

This method accepts the following parameters:

The expect_empty_end method returns the following result structure.

[Fragment] Example (Expect Empty End):

    -- Expect Empty TCAP End within 2.5 seconds
    result = tcap_api.expect_empty_end ('ssp.scp.1', 2.5)

.expect_abort [Asynchronous]

The expect_abort method waits until a TCAP ABORT is received on the specified TCAP transaction, with no contained Components.

• If the transaction is not registered for this instance, an error is raised.
• If any component has previously been received but not handled, an error is raised.
• If the transaction is closed with no unhandled ABORT, an error is raised.
• If the timeout expires with no message received, an error is raised.

This method accepts the following parameters:

The expect_abort method returns the following result structure.

[Fragment] Example (Expect Abort):

    -- EXPECT TCAP Abort
    result = tcap_api.expect_abort ('ssp.scp.1')

    tester.match_pass ('Expect to receive an empty TCAP_END.', 'Received empty TCAP END on transaction ssp.scp.1, as expected.')
    exp_Abort = {
      p_cause =     UNDEF,
      u_info_0_octets = 'Plain ASCII',
      u_source = 1
    }
    arg_Abort = tcap_api.match_abort (result.abort, exp_Abort)

.check_opcode [Pure Lua]

The check_opcode method compares the opcode attribute of the result table returned by the expect_invoke operation, and raises a Lua error if it does not match the expected value.

No action is performed if the opcode does match.

This method accepts the following parameters:

[Fragment] Example (Check Opcode):

    -- Abort script if the received opcode is not correct.
    tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_ApplyCharging, 'INAP ApplyCharging')

.match_received_ac_bin [Synchronous]

The match_received_ac_bin method performs a pass/fail match test of the TCAP Application Context value received back from the first call to expect_invoke or expect_empty_end for a transaction.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_received_ac_bin method returns nil.

[Fragment] Example (Match Received TCAP AC):

    result = tcap_api.expect_invoke ('ssp.scp.1')
    tcap_api.match_received_ac_bin ('ssp.scp.1', result, tcap_api.APPLICATION_CONTEXT_ALIASES['camel3'])

.match_received_aare_result [Synchronous]

The match_received_aare_result method performs a pass/fail match test of the result attribute of the TCAP AARE-apdu value received back from the first call to expect_invoke or expect_empty_end for a transaction.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_received_aare_result method returns nil.

[Fragment] Example (Match Received Result Parameter):

    result = tcap_api.expect_invoke ('ssp.scp.1')
    tcap_api.match_received_aare_result ('ssp.scp.1', result, 0)

.match_received_aare_result_diagnostic_user [Synchronous]

The match_received_aare_result_diagnostic_user method performs a pass/fail match test of the dialogue-service-user attribute of the TCAP AARE-apdu value received back from the first call to expect_invoke or expect_empty_end for a transaction.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_received_aare_result_diagnostic_user method returns nil.

[Fragment] Example (Match Received User Diagnostic):

    result = tcap_api.expect_invoke ('ssp.scp.1')
    tcap_api.match_received_aare_result_diagnostic_user ('ssp.scp.1', result, 1)

.match_received_aare_result_diagnostic_provider [Synchronous]

The match_received_aare_result_diagnostic_provider method performs a pass/fail match test of the dialogue-service-provider attribute of the TCAP AARE-apdu value received back from the first call to expect_invoke or expect_empty_end for a transaction.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_received_aare_result_diagnostic_provider method returns nil.

[Fragment] Example (Match Received Provider Diagnostic):

    result = tcap_api.expect_invoke ('ssp.scp.1')
    tcap_api.match_received_aare_result_diagnostic_provider ('ssp.scp.1', result, 3)

.match_received_last_component [Synchronous]

The match_received_last_component method performs a pass/fail match test of the last_component flag received back from a method call to expect_invoke or expect_empty_end for a transaction.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_received_last_component method returns nil.

[Fragment] Example (Match Last Component):

    -- EXPECT Connect
    result = tcap_api.expect_invoke ('ssp.scp.1')

    tcap_api.check_opcode ('ssp.scp.1', result, inap_api.OPCODE_Connect, 'INAP Connect')
    exp_Connect = { destinationRoutingAddress_digits = v_msisdn, destinationRoutingAddress_noa = '3' }
    arg_Connect = inap_api.decode_op (result.opcode, result.parameter, nil, nil, exp_Connect)

    -- Must be last component.
    tcap_api.match_received_last_component ('ssp.scp.1', result, true)

.match_abort [Synchronous]

The match_abort method compares the actual argument structure decoded from a TCAP Abort message against an expected argument structure.

The match pass/fail results will be recorded against the Lua instance’s trace log. In general, you will typically only wish to use this method within Lua scripts which are run by a service which is part of the IN Tester framework, such as the REST Test Lua Service.

This method accepts the following parameters.

If the global TRACE_LEVEL == 0, then this method will not create any match records, will not perform any match checks, and will return nil.

The match_abort method returns nil.

[Fragment] Example (Match TCAP Abort):

    -- EXPECT TCAP Abort
    result = tcap_api.expect_abort ('ssp.scp.1')

    tester.match_pass ('Expect to receive an empty TCAP_ABORT.', 'Received TCAP ABORT on transaction ssp.scp.1, as expected.')
    exp_Abort = {
      p_cause = UNDEF,
      u_info_0_octets = 'Plain ASCII',
      u_source = 1
    }
    arg_Abort = tcap_api.match_abort (result.abort, exp_Abort)

.sccp_address_merge [Pure Lua]

The sccp_address_merge method is a utility method that constructs an SCCP destination routing address for use in the call to the initialise method for a new outbound TCAP transaction.

It merges parameters from a local Table structure and from any supplied REST query args.

The locally-defined (inline) values take priority.

This method accepts the following parameters.

The following parameters are processed separately.

• dri
• dpc
• dssn
• dgt_digits
• dgt_noa
• dgt_np
• dgt_tt

For each parameter, the following logic is applied:

1. If the inbound dra contains a value for this parameter, that value is used.
2. Otherwise, use the query arg value prefixed by the node name and a period ..

For example, the query args value for scp.dpc is used as the default destination point code for sending a new TCAP BEGIN to the SCP node.

The sccp_address_merge method returns a Table containing all of the indicated attributes for which an explicit dra or default extra_args value was found.

[Fragment] Example (Match TCAP Abort):

local handler = function (args)
    local scp_dra_prefs = { dgt_digits = '640003', dri = 0 }
    
    local scp_dra = tcap_api.sccp_address_merge (args.content_json.test_details.content, 'scp', scp_dra_prefs)
    tcap_api.initialise ('ssp.scp.1', tcap_api.APPLICATION_CONTEXT_ALIASES['camel3'], scp_dra)

Constants

The following TCAP constants are defined on the returned tcap_api object.

TCAP Component and Message Types

The following component and message types are used for the sending and receiving of TCAP. Refer to the method-specific documentation. They are defined here for reference:

-- TCAP Component Type Constants.
tcap_api.CT_INVOKE = 'Invoke'
tcap_api.CT_RETURN_RESULT = 'ReturnResult'
tcap_api.CT_RETURN_ERROR = 'ReturnError'

-- TCAP Message Type Constants.
tcap_api.TYPE_BEGIN = 'BEGIN'
tcap_api.TYPE_CONTINUE = 'CONTINUE'
tcap_api.TYPE_END = 'END'

TCAP AC Aliases

The tcap_api.APPLICATION_CONTEXT_ALIASES is a Lua table constant which provides convenient access to some standard TCAP Application Context, for the purpose of setting outbound TCAP Application Context via the .initialise method, or for validating received TCAP Application Context received in .tcap_ac_bin from a successful return of .expect_invoke.

The values in this table are binary strings.

[Fragment] Example (Initialise Transaction with camel2 AC):

    local scp_dra = {
      dgt_digits = "049991000"
    }
    tcap_api.initialise (nil, 'ssp.scp.1', scp_dra, tcap_api.APPLICATION_CONTEXT_ALIASES['camel2'])

The current definition is:

-- These are the strict alias names which should be used in preference.
tcap.APPLICATION_CONTEXT_ALIASES = {
    -- ETSI CS-1 SSP to SCP
    cs1_ssp = "\004\000\001\001\001\000\000",

    -- ETSI CS-1 IP to SCP
    cs1_ip  = "\004\000\001\001\001\002\000",

    -- ETSI CS-2, ssf/scf AC, id-ac-cs2-ssf-scfGenericAC
    cs2_ssf = "\004\000\001\001\020\003\004",

    -- Application Context for camel v1.
    camel1_ssf = "\004\000\000\001\000\050\000",

    -- Application Context for CAMEL v2 (SSF to SCF).
    camel2_ssf = "\004\000\000\001\000\050\001",

    -- (SRF to SCF)
    camel2_srf = "\004\000\000\001\000\052\001",

    -- Application Context for CAMEL v3 (SSF to SCF).
    camel3_ssf = "\004\000\000\001\021\003\004",

    -- (SRF to SCF)
    camel3_srf = "\004\000\000\001\020\003\00e",

    -- Application Context for CAMEL v4 (SSF to SCF).
    camel4_ssf = "\004\000\000\001\023\003\004",

    -- (SRF to SCF)
    camel4_srf = "\004\000\000\001\022\003\00e",

    -- Application Context for Network Unstructured SS v2.
    ussd2 = "\004\000\000\001\000\019\002",

    -- Application Context for Network Unstructured MAP ATI v3.
    ati3 = "\004\000\000\001\000\029\003"
}

-- And some less-strict aliases:
tcap.APPLICATION_CONTEXT_ALIASES['cs1']    = tcap.APPLICATION_CONTEXT_ALIASES['cs1_ssp']
tcap.APPLICATION_CONTEXT_ALIASES['etsi']   = tcap.APPLICATION_CONTEXT_ALIASES['cs1_ssp']
tcap.APPLICATION_CONTEXT_ALIASES['cs2']    = tcap.APPLICATION_CONTEXT_ALIASES['cs2_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel1'] = tcap.APPLICATION_CONTEXT_ALIASES['camel1_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel2'] = tcap.APPLICATION_CONTEXT_ALIASES['camel2_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel3'] = tcap.APPLICATION_CONTEXT_ALIASES['camel3_ssf']
tcap.APPLICATION_CONTEXT_ALIASES['camel4'] = tcap.APPLICATION_CONTEXT_ALIASES['camel4_ssf']