MAP Lua Agent

Introduction

The MapLuaAgent is an synchronous helper for Lua scripts running within the LogicApp. It is used for encoding and decoding Mobile Application Part (MAP) operations.

The MapLuaAgent performs the encoding/decoding functions internally and does not rely on any other external applications to perform this task. Hence it does not send or receive any messages.

MAP Agent methods are accessed via the “n2.n2svcd.map_agent” module:

    local map_api = require "n2.n2svcd.map_agent"

Configuring MapLuaAgent

The MapLuaAgent 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>
            ...
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="SigtranApp::MapLuaAgent" libs="../apps/sigtran/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

Parameter Name Type XML Type Description
module SigtranApp:: MapLuaAgent Attribute [Required] The module name containing the Lua Agent code.
libs ../apps/sigtran/lib Element Location of the module for MapLuaAgent.

Note that despite the fact that the Agent module resides within the SigtranApp, invoking the MAP Agent functions to encode/decode an MAP operation does not perform any interaction with the SigtranApp at that time.

The SigtranApp interaction occurs only at the time when the MAP message is actually sent over TCAP, using the TCAP Agent.

The MAP Agent does not reference any entries in the LogicApp’s <parameters> element, nor does it use any expanded <config> block within the <agent> entry.

The MapLuaAgent API

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

.encode_op [Synchronous]

The encode_op method encodes a table structure into a MAP Invoke binary ASN.1 byte sequence.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the MAP operation to encode into ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_UnstructuredSSRequest.
argument Table A (typically nested) table structure defining the attributes of the operation to be encoded.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
variant String An optional identifier for the MAP variant to use when encoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The encode_op method returns the binary ASN.1 “parameter”, which is then passed as the parameter for an Invoke component for the send_components method of the TCAP Agent API.

[Fragment] Example (Encode MAP/USSD ProcessUnstructuredSSRequest):

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

  local arg_ProcessUnstructuredSSRequest = { msisdn_digits = '9607499900', ussdString_text = '*123#' }
  local param_ProcessUnstructuredSSRequest = map_api.encode_op (map_api.OPCODE_ProcessUnstructuredSSRequest, arg_ProcessUnstructuredSSRequest, nil, nil)

  tcap_api.send_components ('hlr.scp.1', { { type = tcap_api.CT_INVOKE, opcode = map_api.OPCODE_ProcessUnstructuredSSRequest, parameter = param_ProcessUnstructuredSSRequest } }, tcap_api.TYPE_BEGIN)

.encode_result [Synchronous]

The encode_result method encodes a table structure into a MAP ReturnResult binary ASN.1 byte sequence.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the MAP operation whose Result we will encode into ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_UnstructuredSSRequest.
argument Table A (typically nested) table structure defining the attributes of the operation Result to be encoded.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
variant String An optional identifier for the MAP variant to use when encoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The encode_result method returns the binary ASN.1 “parameter”, which is then passed as the parameter for a ReturnResult component for the send_components method of the TCAP Agent API.

[Fragment] Example (Encode UnstructuredSSRequestResult):

  -- SEND UnstructuredSSRequestResult
  local arg_UnstructuredSSRequestResult = { ussdString_text = '2' }
  local param_UnstructuredSSRequestResult = map_api.encode_result (map_api.OPCODE_UnstructuredSSRequest, arg_UnstructuredSSRequestResult, nil, nil)

  tcap_api.send_components ('hlr.scp.1', { { type = tcap_api.CT_RETURN_RESULT, opcode = map_api.OPCODE_UnstructuredSSRequest, parameter = param_UnstructuredSSRequestResult } }, tcap_api.TYPE_CONTINUE)

.decode_op [Synchronous]

The decode_op decodes a MAP Invoke binary ASN.1 byte sequence into a table containing individual field values.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the MAP operation to decode from ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_UnstructuredSSRequest.
parameter Table
variant String An optional identifier for the MAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The decode_op method returns a (typically nested) table structure containing the attributes of the Invoke as decoded.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).

[Fragment] Example (Decode/Match MAP UnstructuredSSNotify):

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

  tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_UnstructuredSSNotify, 'map UnstructuredSSNotify')
  local arg_UnstructuredSSNotify = map_api.decode_op (result.opcode, result.parameter, nil, nil)

  local exp_UnstructuredSSNotify = { ussdString_text = 'Here is a Notify' }
  map_api.match_op (result.opcode, arg_UnstructuredSSNotify, exp_UnstructuredSSNotify, nil)

.decode_result [Synchronous]

The decode_result decodes a MAP ReturnResult binary ASN.1 byte sequence into a table containing individual field values.

This method accepts the following parameters.

Field Type Description
opcode Number The numeric operation code identifying the MAP operation whose Result to decode from ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_ProcessUnstructuredSSRequest.
parameter Table
variant String An optional identifier for the MAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).
hints Table Optional table of hints which may include:
.extensions Table of Tables Table of extension types. Key is the extension number (may be Lua string not number).
Value is INTEGER, BOOLEAN, or OCTET STRING.

The decode_result method returns a (typically nested) table structure containing the attributes of the ReturnResult as decoded.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).

[Fragment] Example (Decode/Match USSD ProcessUnstructuredSSRequestResult):

  result = tcap_api.expect_result ('hlr.scp.1')

  tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequestResult')
  local arg_ProcessUnstructuredSSRequestResult = map_api.decode_result (result.opcode, result.parameter, nil, nil)

  local exp_ProcessUnstructuredSSRequestResult = { ussdString_text = 'We\'ll send an SMS with your usage details.' }
  map_api.match_result (result.opcode, arg_ProcessUnstructuredSSRequestResult, exp_ProcessUnstructuredSSRequestResult, nil)

.match_op [Synchronous]

The match_op method compares the actual Invoke argument structure decoded from an MAP operation ASN.1 parameter against an expected argument structure.

The actual fields to be compared are specific to the particular MAP operation code, and will typically also vary according to the specific MAP protocol variant.

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
opcode Number The numeric operation code identifying the MAP operation to decode from ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_UnstructuredSSRequest.
argument Table A (typically nested) table structure defining the actual attributes of the operation to be match.
This is typical the returned result from a call to the decode_op method.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
expected Table A (typically nested) table structure defining the expected attributes of the operation we have just received.
This expected structure is identical to the decoded structure, and identical to the structure passed into encode_op.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
variant String An optional identifier for the MAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).

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_op method returns nil.

[Fragment] Example (Decode/Match MAP UnstructuredSSNotify):

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

  tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_UnstructuredSSNotify, 'map UnstructuredSSNotify')
  local arg_UnstructuredSSNotify = map_api.decode_op (result.opcode, result.parameter, nil, nil)

  local exp_UnstructuredSSNotify = { ussdString_text = 'Here is a Notify' }
  map_api.match_op (result.opcode, arg_UnstructuredSSNotify, exp_UnstructuredSSNotify, nil)

.match_result [Synchronous]

The match_result method compares the actual ReturnResult argument structure decoded from an MAP operation ASN.1 parameter against an expected argument structure.

The actual fields to be compared are specific to the particular MAP operation code, and will typically also vary according to the specific MAP protocol variant.

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
opcode Number The numeric operation code identifying the MAP operation to decode from ASN.1.
Specify one of the provided constants, e.g. map_api.OPCODE_UnstructuredSSRequest.
argument Table A (typically nested) table structure defining the actual attributes of the operation to be match.
This is typical the returned result from a call to the decode_op method.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
expected Table A (typically nested) table structure defining the expected attributes of the operation we have just received.
This expected structure is identical to the decoded structure, and identical to the structure passed into encode_op.
For the structure of this parameter, see Tester Internals (MAP/USSD Operations).
variant String An optional identifier for the MAP variant to use when decoding.
Supported values vary according to the specific operation.
For the interpretation of this parameter, see Tester Internals (MAP/USSD Operations).

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_result method returns nil.

[Fragment] Example (Decode/Match USSD ProcessUnstructuredSSRequestResult):

  result = tcap_api.expect_result ('hlr.scp.1')

  tcap_api.check_opcode ('hlr.scp.1', result, map_api.OPCODE_ProcessUnstructuredSSRequest, 'map ProcessUnstructuredSSRequestResult')
  local arg_ProcessUnstructuredSSRequestResult = map_api.decode_result (result.opcode, result.parameter, nil, nil)

  local exp_ProcessUnstructuredSSRequestResult = { ussdString_text = 'We\'ll send an SMS with your usage details.' }
  map_api.match_result (result.opcode, arg_ProcessUnstructuredSSRequestResult, exp_ProcessUnstructuredSSRequestResult, nil)

Constants

The following MAP constants are defined on the returned map_api object.

-- MAP OPCODE Constants.
map.OPCODE_AnyTimeInterrogationRequest = 71
map.OPCODE_ProcessUnstructuredSSRequest = 59
map.OPCODE_UnstructuredSSRequest = 60
map.OPCODE_UnstructuredSSNotify = 61