FOX Lua Agent

Introduction

The FoxLuaAgent is an asynchronous helper for Lua scripts running within the LogicApp. It is used for sending out FOX client requests.

The FoxLuaAgent communicates with one or more instances of the FoxApp which can be used to communicate with one or more external FOX servers.

The FoxLuaAgent communicates with the FoxApp using the FOX-C-… messages.

Configuring FoxLuaAgent

The FoxLuaAgent 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_fox_app_name" value="FOX-CLIENT"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="FoxApp::FoxLuaAgent" libs="../apps/fox/lib"/>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

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

In addition, the FoxLuaAgent must be configured with the name of the FoxApp 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_fox_app_name String Attribute Default name for the FoxApp with which FoxLuaAgent will communicate.
.fox_app_name_ String Attribute Use this format when FoxLuaAgent will communicate with more than one FoxApp.
(Default = FoxLuaAgent uses only the default route/FOX endpoint).

Invoking FoxLuaAgent

A Lua Script can access the FoxLuaAgent fox action with code such as the following:

    local n2svcd = require "n2.n2svcd"
    local fox_api = require "n2.n2svcd.fox"

    local handler = function (soap_args)

        local be_id = 1
        local request = {
            TYPE = 'WI',
            BODY = {
                AREF = aref,
                WALT = walt,
                WTYP = wtyp
            }
        }

        local response = fox_api.request (be_id, request)
        if (response.ACTN ~= 'ACK') then
            error ("VWS Wallet Info Failed: [" .. (response.BODY.CODE or "?")
                .. "-" .. (response.BODY.WHAT or "Unknown Error") .. "]")
        end

        for bals_k, bals_v in pairs (response.BODY.BALS) do
            ...
        end

        return
    end

    return n2svcd.handler (handler)

This is standard Lua-style library usage. The n2/n2svcd/fox.lua library is loaded with require "n2.n2svcd.fox". Then methods are invoked on the returned library object.

The FoxLuaAgent API

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

Note that if you are creating a new service, you may not necessarily need to code directly against this API. Instead, you may want to consider using the ccs.lua helper library. This is a high-level service-implementation API for manipulating common NCC CCS subscriber details.

.request

The request method accepts an request object parameter with the following attributes.

Field Type Description
be_id String The billing engine ID for the subscriber configured in CCS_DOMAIN.DOMAIN_ID.
You will normally read this from the CCS_ACCT.BE_ACCT_ENGINE_ID database table.
If only one VWS pair is present, this may be hard-coded.
request Object Description of the FOX request structure.
You must specify TYPE. You may specify BODY. The HEAD will have defaults set.
You must specify HEAD.CMID if you wish to make a follow-up request within a session.
This structure is specified by Oracle.

The request method returns a FOX response object with the following attributes.

Parameter Type Description
TYPE ACK/NACK/EXCP The response type.
These values are specified by Oracle.
HEAD Object Container for header fields returned in the response.
This structure is specified by Oracle.
BODY Object Container for body fields returned in the response.
This structure is specified by Oracle.

[Fragment] Example Wallet Delete FOX request:

    local be_id = 1
    local request = {
        TYPE = 'WD',
        BODY = {
            ACTY = acty,
            CLI = cli,
            WALT = walt,
            WTYP = wtyp
        }
    }

    local response = fox_api.request (be_id, request)
    if (response.ACTN ~= 'ACK') then
        error ("VWS Wallet Delete Failed: [" .. (response.BODY.CODE or "?")
            .. "-" .. (response.BODY.WHAT or "Unknown Error") .. "]")
    end

Supported NCC::FOX Codec Fields

The Oracle FOX protocol design does not support dynamically or user-defined field types. All field names must be pre-defined. This means that the FOX codec used by the LUA agent has a static pre-defined list of field names and associated types.

The BODY fields currently coded into the FOX codec are:

Field Structure FOX Type
.BODYMAP
.BODY.ABALARRAY
.BODY.ABAL.*MAP
.BODY.ABAL.*.BKTSARRAY
.BODY.ABAL.*.BKTS.*MAP
.BODY.ABAL.*.BKTS.*.AASSSTRING
.BODY.ABAL.*.BKTS.*.EXPRDATE
.BODY.ABAL.*.BKTS.*.IDINTEGER
.BODY.ABAL.*.BKTS.*.LUSEDATE
.BODY.ABAL.*.BKTS.*.STDTDATE
.BODY.ABAL.*.BKTS.*.SUBNSTRING
.BODY.ABAL.*.BKTS.*.UVALINTEGER
.BODY.ABAL.*.BKTS.*.VALINTEGER
.BODY.ABAL.*.BTYPINTEGER
.BODY.ABAL.*.BUNTINTEGER
.BODY.ABAL.*.LIMTSYMBOL
.BODY.ABAL.*.STOTINTEGER
.BODY.ABAL.*.UTOTINTEGER
.BODY.ACTVDATE
.BODY.ACTYINTEGER
.BODY.APOLSYMBOL
.BODY.AREFINTEGER
.BODY.BALSARRAY
.BODY.BALS.*MAP
.BODY.BALS.*.BKTSARRAY
.BODY.BALS.*.BKTS.*MAP
.BODY.BALS.*.BKTS.*.EXPRDATE
.BODY.BALS.*.BKTS.*.IDINTEGER
.BODY.BALS.*.BKTS.*.LUSEDATE
.BODY.BALS.*.BKTS.*.STDTDATE
.BODY.BALS.*.BKTS.*.SUBNSTRING
.BODY.BALS.*.BKTS.*.UVALINTEGER
.BODY.BALS.*.BKTS.*.VALINTEGER
.BODY.BALS.*.BTYPINTEGER
.BODY.BALS.*.BUNTINTEGER
.BODY.BALS.*.LIMTSYMBOL
.BODY.BALS.*.STOTINTEGER
.BODY.BALS.*.UTOTINTEGER
.BODY.BPOLSYMBOL
.BODY.CDATDATE
.BODY.CDRARRAY
.BODY.CDR.*MAP
.BODY.CDR.*.TAGSTRING
.BODY.CDR.*.VALSTRING
.BODY.CLISTRING
.BODY.CODESTRING
.BODY.DNSTRING
.BODY.EXPRDATE
.BODY.LUSEDATE
.BODY.MAXCINTEGER
.BODY.NAMESTRING
.BODY.NUMINTEGER
.BODY.RBAAARRAY
.BODY.RBAA.*MAP
.BODY.RBAA.*.BTYPINTEGER
.BODY.RBAA.*.RBIAARRAY
.BODY.RBAA.*.RBIA.*MAP
.BODY.RBAA.*.RBIA.*.BKIDINTEGER
.BODY.RBAA.*.RBIA.*.BPOLSYMBOL
.BODY.RBAA.*.RBIA.*.VALINTEGER
.BODY.RESNSTRING
.BODY.RWINULL
.BODY.SATIINTEGER
.BODY.SCIDSTRING
.BODY.SCLISTRING
.BODY.SCURINTEGER
.BODY.SDIDINTEGER
.BODY.SDNFNULL
.BODY.SPIDINTEGER
.BODY.SSUBINTEGER
.BODY.STATSYMBOL
.BODY.STRVSTRING
.BODY.SWIDINTEGER
.BODY.SWTIINTEGER
.BODY.TATIINTEGER
.BODY.TDIDINTEGER
.BODY.TSUBINTEGER
.BODY.TWIDINTEGER
.BODY.TZSTRING
.BODY.UCURINTEGER
.BODY.WALTINTEGER
.BODY.WHATSTRING
.BODY.WTYPINTEGER