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 MAP Agent may be used by any Lua script, regardless of which Service initiated that script.

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:

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:

• Invalid input parameters supplied by Lua script.
• Internal processing error.

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

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.

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.

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 N2::MAP::Codec reference documentation.

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

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 N2::MAP::Codec reference documentation.

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

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.

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_SendRoutingInfoForSM = 45
map.OPCODE_UnstructuredSSRequest = 60
map.OPCODE_UnstructuredSSNotify = 61