TCAP Lua Agent

Introduction

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

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:

Parameter Name Type XML Type Description
module SigtranApp:: TcapLuaAgent Attribute [Required] The module name containing the Lua Agent code.
libs ../apps/sigtran/lib Element Location of the module for TcapLuaAgent.
config Object Element Container for extended configuration for this Application instance.
.tcap_timeout_secs Integer Attribute How long to wait for an expected TCAP message to arrive.
(Default = 10 seconds)
.ignore_reset_timer 0 / 1 Attribute Should received ResetTimer operations be ignored when received?
The service logic may override this for individual tests.
(Default = 0, do not ignore, pass to user layer)
.auto_activity_result 0 / 1 Attribute Should we automatically send ActivityTestResult for ActivityTest.
The service logic may override this for individual tests.
(Default = 0, do not automatically respond)

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.

Parameter Name Type XML Type Description
parameters Array Element Array of name = value Parameters for this Application instance.
.default_tcap_app_name String Attribute Default name for the SigtranApp with which TcapLuaAgent will communicate.
.tcap_app_name_<route> String Attribute Use this format when TcapLuaAgent will communicate with more than one SigtranApp.
(Default = TcapLuaAgent uses only the default route/SIGTRAN connectivity application).

The TcapLuaAgent API

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

.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:

Field Type Description
value Boolean / UNDEF Should the TcapLuaAgent ignore received ResetTimer operations?
true = yes, ignore. These operations are silently discarded.
false = no, do not ignore. The script must explicitly expect these operations.
nil = revert to the default behavior configured for the agent.

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:

Field Type Description
value Boolean / UNDEF Should the TcapLuaAgent automatically respond to ActivityTest operations?
true = yes, send automatic response then silently discard the operation.
false = no, do not automatically respond. The script must explicitly expect these operations and generate responses.
nil = revert to the default behavior configured for the agent.

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:

Field Type Description
route String The identifier of the SIGTRAN application to use, or nil for the default.
transaction String [Required] A key for the new TCAP transaction. This must be unique within this Lua instance (script). Closing a TCAP transaction via TCAP END or TCAP ABORT or TCAP Pre-Arranged END does not free up the transaction name for re-use.
The standard naming convention for these transactions has the form "ssp.scp.1", where "ssp" is the role of the local end of the transaction, "scp" is the role for the far and of the transaction, and "1", "2", etc. is the incrementing "subcall" number within this instance.
sccp_dest_address Table The SCCP address to which the TCAP BEGIN should be sent.
Subsequent messages will be sent to the SCCP address which responds back to us for that transaction.
.dri 0 / 1 SCCP Destination Routing Indicator
(Default = Automatically Determined).
.dpc Integer SCCP Destination Point Code
(Default = Does not route on PC/SSN).
.dssn Integer SCCP Destination Subsystem Number
(Default = Does not route on PC/SSN).
.dgt_digits String SCCP Destination Global Title Digits
(Default = Does not route on GT).
.dgt_noa Integer SCCP Destination Global Title Nature of Address
(Default = Varies).
.dgt_np Integer SCCP Destination Global Title Numbering Plan
(Default = Varies).
.dgt_tt Integer SCCP Destination Global Title Translation Type
(Default = Automatically Determined).
tcap_ac_bin String [Required] A binary TCAP Application Context string.
This is typically one of the entries in the tcap_api.APPLICATION_CONTEXT_ALIASES table.

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:

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:

Field Type Description
transaction String [Required] A key for the new TCAP transaction which will be created when the TCAP BEGIN arrives. This must be unique within this Lua instance (script). Closing a TCAP transaction via TCAP END or TCAP ABORT or TCAP Pre-Arranged END does not free up the transaction name for re-use.
The standard naming convention for these transactions has the form "ssp.scp.1", where "ssp" is the role of the local end of the transaction, "scp" is the role for the far and of the transaction, and "1", "2", etc. is the incrementing "subcall" number within this instance.
msisdn_digits String The subscriberIdentity.MSISDN digits which must exactly match, in order for the new AnyTimeInterrogation transaction to be associated with the current-running Lua script.

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.

Component InvokeID is assigned automatically. For an Invoke a new InvokeID is assigned consecutively for the transaction. For ReturnResult or ReturnError the most recently received Invoke ID for that operation code copied across. Attempting to send ReturnResult or ReturnError for an operation code not yet recieved on that transaction will fail.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
components List [Required] Array of components to send. May contain zero components.
Each has the following structure.
.type String [Required] Type of component, being one of:
tcap_api.CT_INVOKE - TCAP Invoke
tcap_api.CT_RETURN_RESULT - TCAP Return Result
tcap_api.CT_RETURN_ERROR - TCAP Return Error
.opcode Integer The INAP Operation Code. This is required for Invoke.
Optional for Return Result without parameter, and for Return Error.
.parameter Integer The ASN.1 encoded binary parameter, if required for this type/opcode.
msg_type String [Required] One of tcap_api.TYPE_BEGIN, tcap_api.TYPE_CONTINUE, tcap_api.TYPE_END.
map_open String Defines a MAP-OPEN to be sent in the AARQ dialogue element.
This field should only be present when using TYPE_BEGIN, and should always be present when performing a TCAP BEGIN for the MAP protocol.
To create a minimum empty MAP-OPEN address, specify {} for this parameter.
(Default = MAP-OPEN is not present).
.destination_reference_digits Hex String The digits for the Destination Reference address in the MAP-OPEN.
(Default = destination reference is not present).
.destination_reference_noa Integer The Nature of Address for the Destination Reference address in the MAP-OPEN.
(Default = 0).
.destination_reference_npi Integer The Numbering Plan Indicator for the Destination Reference address in the MAP-OPEN.
(Default = 1).
.origination_reference_digits Hex String The digits for the Origination Reference address in the MAP-OPEN.
(Default = orgination reference is not present).
.origination_reference_noa Integer The Nature of Address for the Origination Reference address in the MAP-OPEN.
(Default = 0).
.origination_reference_npi Integer The Numbering Plan Indicator for the Origination Reference address in the MAP-OPEN.
(Default = 1).

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:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.

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:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
p_cause Integer Specify the Protocol Cause.
(Default = attribute is not present).
u_source Integer Specify the User Source.
(Default = attribute is not present).
u_source List of String Array of User Information strings.
(Default = attribute is not present).

The send_abort method returns nil.

[Fragment] Example (Send User Abort):

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

.get_pending [Synchronous]

The get_pending method returns any currently pending (previously received but not yet provided) TCAP Components or TCAP Abort for the indicated transaction. If this is the first time that any get_* or expect_* method has returned information, then the TCAP Application Context and result information is also provided.

The transaction pending buffers are then cleared, subsequent calls to get_pending will not include these returned components.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.

The get_pending method returns nil if the transaction is not known.

If the transaction is known, then the get_pending method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.state OPEN / HALF / CLOSED The state of the transaction.
OPEN - Sent/Received TCAP CONTINUE but not END/ABORT.
HALF - Send/Received TCAP BEGIN only.
CLOSED - Send/Received TCAP END/ABORT.
.tcap_ac_bin String Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result Integer Integer result from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user Integer Integer result-source-diagnostic.dialogue-service-user from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider Integer Integer result-source-diagnostic.dialogue-service-provider from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.components Array of Table Array of all pending received components, or nil if no pending components.
.type Invoke / ReturnResult / ReturnError The type of this received component.
.opcode Integer The received Invoke Operation Code for this component.
.invoke_id Integer The received Invoke ID for this component.
.parameter String The binary-encoded ASN.1 operation parameter for this component, if present.
.error_code Integer The error code, if this is a ReturnError component.
.last_component Integer Returned as 1 if and only if this Invoke was the last TCAP component within a TCAP END message.
.abort Object An object representing the decoded Abort information, if Abort was received and is pending processing.
.p_cause Integer The Protocol Cause, if present.
.u_source Integer The User Source, if present.
.u_info_0_octets String The content of the user-information[0].encoding.octet-aligned information element, if present.

[Fragment] Example (Send User Abort):

    local result = tcap_api.get_pending ('ssp.scp.1')
    if (result.abort) then 
        error ("Unexpected Abort")
    end
    local components = result.components
    if (not components or (#components ~= 1)) then
        error ("Expected exactly one component.")
    end

.expect_invoke [Asynchronous]

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

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
seconds Number Override the default TCAP timer.
(Default = configured timer for TCAP Agent).

The expect_invoke method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.tcap_ac_bin String Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result Integer Integer result from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user Integer Integer result-source-diagnostic.dialogue-service-user from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider Integer Integer result-source-diagnostic.dialogue-service-provider from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.opcode Integer The received Invoke Operation Code.
.invoke_id Integer The received Invoke ID.
.parameter String The binary-encoded ASN.1 operation parameter.
.last_component Integer Returned as 1 if and only if this Invoke was the last TCAP component within a TCAP END message.

[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.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
seconds Number Override the default TCAP timer.
(Default = configured timer for TCAP Agent).

The expect_result method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.tcap_ac_bin String Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result Integer Integer result from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user Integer Integer result-source-diagnostic.dialogue-service-user from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider Integer Integer result-source-diagnostic.dialogue-service-provider from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.opcode Integer The sent Invoke Operation Code for which this is a ReturnResult.
.invoke_id Integer The sent Invoke ID for which this is a ReturnResult.
.parameter String The binary-encoded ASN.1 operation parameter (if present).
.last_component Integer Returned as 1 if and only if this ReturnResult was the last TCAP component within a TCAP END message.

[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.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
seconds Number Override the default TCAP timer.
(Default = configured timer for TCAP Agent).

The expect_error method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.tcap_ac_bin String Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result Integer Integer result from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_user Integer Integer result-source-diagnostic.dialogue-service-user from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.tcap_aare_result_diagnostic_provider Integer Integer result-source-diagnostic.dialogue-service-provider from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
.opcode Integer The sent Invoke Operation Code for which this is a ReturnError.
.invoke_id Integer The sent Invoke ID for which this is a ReturnError.
.error_code Integer The error code for this error.
.parameter String The binary-encoded ASN.1 operation parameter (if present).
.last_component Integer Returned as 1 if and only if this ReturnError was the last TCAP component within a TCAP END message.

[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.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
seconds Number Override the default TCAP timer.
(Default = configured timer for TCAP Agent).

The expect_empty_end method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.tcap_ac_bin String Binary string containing the received TCAP Application Context.
This value is only returned for the first received TCAP component.
.tcap_aare_result Integer Integer result from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
tcap_aare_result_diagnostic_user Integer Integer result-source-diagnostic.dialogue-service-user from the AARE-apdu if present.
This value is only returned for the first received TCAP component.
tcap_aare_result_diagnostic_provider Integer Integer result-source-diagnostic.dialogue-service-provider from the AARE-apdu if present.
This value is only returned for the first received TCAP component.

[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.

This method accepts the following parameters:

Field Type Description
transaction String [Required] The key for the already initialised TCAP transaction.
seconds Integer Override the default TCAP timer.
(Default = configured timer for TCAP Agent).

The expect_abort method returns the following result structure.

Field Type Description
result Table Container for returned attributes.
.p_cause Integer The Protocol Cause, if present.
.u_source Integer The User Source, if present.
.u_info_0_octets String The content of the user-information[0].encoding.octet-aligned information element, if present.

[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:

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
opcode Integer The required opcode. This will typically be a constant from the INAP Lua Agent API, or the MAP equivalent.
label String A brief string fragment to include in the error message.

[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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
tcap_ac_bin String [Required] The expected binary TCAP Application Context string.
This is typically one of the entries in the tcap_api.APPLICATION_CONTEXT_ALIASES table.

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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
tcap_aare_result Integer [Required] The expected integer value for result.

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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
tcap_aare_result_diagnostic_user Integer [Required] The expected integer value for result-source-diagnostic.dialogue-service-user.

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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
tcap_aare_result_diagnostic_provider Integer [Required] The expected integer value for result-source-diagnostic.dialogue-service-provider.

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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
result Table [Required] The returned result from the expect_invoke method.
last_component Boolean [Required] Do we expect this to be (or not to be) the last component on this transaction.

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.

Field Type Description
transaction String [Required] The key for the TCAP transaction, for the match pass/fail message.
abort Table [Required] The abort attribute of the result from the expect_abort method.
expected Table [Required] The expected structure of the received TCAP Abort.
For the structure of this parameter, see Tester Internals (TCAP Abort Operation).

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.

Field Type Description
extra_args Table Map of REST-supplied query args extracted from the `?` part of the REST URI.
node String [Required] The destination node name `scp` or `srp`.
dra Table [Required] Inbound destination routing map.

The following parameters are processed separately.

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 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:

-- Agent Key (for n2svcd.progress)
tcap.AGENT_KEY = 'tcap'

-- Transaction state Constants
tcap.STATE_OPEN = 'OPEN'
tcap.STATE_HALF_OPEN = 'HALF'
tcap.STATE_CLOSED = 'CLOSED'

-- 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']