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

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.

• The FoxLuaAgent is tied to the fox action key.
• The FOX-C-SENT message is written to the debug trace log, but not available to the Lua script.

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:

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.

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:

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

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.

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

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