SOAP Lua Service

Introduction

The SoapLuaService is a service for initiating Lua scripts running within the LogicApp.

The SoapLuaService receives messages from one or more instances of the SoapServerApp which is configured to receive SOAP/HTTP(S) Requests from an external client.

The SoapLuaService communicates with the SoapServerApp using the SOAP-S-… messages.

Configuring SoapLuaService

The SoapLuaService 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>
              <service module="SoapServerApp::SoapLuaService" libs="../apps/soap_s/lib" script_dir="/var/lib/n2svcd/logic/soap"/>
            </services>
            <agents>
              ...
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

In addition to the Common LogicApp Service Configuration, note the following specific attribute notes, and service-specific attributes.

Under normal installation, the following service attributes apply:

Script Selection (SOAP Request)

Script selection is not configured. The script name is simply the SOAP message name received in the request.

e.g. an inbound request with message name OfferList will map to a script name of OfferList, which will be satisfied by a file named OfferList.lua in any of the directories configured as lua_script_dir in the LogicApp.

Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.

Script Global Variables

Scripts run with this service have access to the Common LUA Service Global Variables.

There are no service-specific global variables.

Script Entry Parameters (SOAP Request)

The Lua script must be a Lua chunk which returns an n2svcd.handler, such as the following:

    local n2svcd = require "n2.n2svcd"

    local handler = function (soap)
        n2svcd.notice ("Echo Supplied SOAP Inputs:")
        n2svcd.notice_var (soap)

        return soap.args
    end

    return n2svcd.handler (handler)

The handler will be executed with a single soap entry parameter which is an object with the following attributes:

Each object in the .http_headers Array for the soap entry parameter has the following structure.

Script Return Parameters (SOAP Response)

The Lua script is responsible for determing the SOAP Response which will be sent back in reply to the original SOAP Request.

The simplest way to do this is by the return value given back to the service at the end of script execution.

The script return value is simply an args Table which will be encoded as the SOAP Body.

This simple method does not allow control over the response message name, and does not allow setting of custom HTTP header fields. You must use the .response SOAP API method for controlling those values.

Example (returning SOAP Response arguments):

    local n2svcd = require "n2.n2svcd"

    local handler = function (soap)
        return ({ ARG1 = "VALUE ONE", ARG2ARRAY = [ 'First Value', 'Second Value' ]})
    end

    return n2svcd.handler (handler)

The encoding of array elements will vary according to the quirks_mode configured for the SoapServerApp. For example, when SoapServerApp is configured to run in generic quirks mode, an array is encoded as:

    <ARG2ARRAY soapenc:arrayType="xsd:string[2]" xsi:type="soapenc:Array">
      <item xsi:type="xsd:string">First Value</item>
      <item xsi:type="xsd:string">Second Value</item>
    </ARG2ARRAY>

By comparison, in ncc_pi quirks mode, an array is simply a repeated element, e.g.:

    <ARG2ARRAY>First Value</pi:ARG2ARRAY>
    <ARG2ARRAY>Second Value</pi:ARG2ARRAY>

Alternatively, a script may return nil to return an empty SOAP response.

Example (returning a SOAP Response with no arguments):

    local n2svcd = require "n2.n2svcd"

    local handler = function (soap)
        return nil
    end

    return n2svcd.handler (handler)

The SoapLuaService API

The SOAP Server API can be loaded as follows.

    local soap_server_api = require "n2.n2svcd.soap_server"

It is not necessary to load the SOAP Server API if you are only using the simple response mechanism described above. It is only required if you wish to use any of the extended features described below.

.response

When a Lua Script needs to perform extended processing, it may wish to send an early SOAP response before the script completes. This can be done with the response method on the SOAP Server API. This method also allows the script to use a non-default response message name.

The response method takes the following parameters.

The response method returns true.

[Fragment] Example (Early Response with overridden name and extra headers):

    ...
    soap_server_api.response (
        { num_updated = 3, new_ids = [ "1003", "3344"] }, 
        "OfferSaveACK", 
        { { name = 'Set-Cookie', value = 'FOO=BAR' }, 
          { name = 'Custom-HDR', value = 'success; Expiry=7' }
        }
    )
    ...
    [post-processing after SOAP transaction is concluded]
    ...