OCS API

Introduction

The OCS API provides key functions of the OCS API to Lua scripts. Most importantly it provides methods to create lifecycle and hook handlers. To access the API, require the N2OCS API lua file:

    local ocs = require "n2.n2ocs"

API Methods

.create_lifecycle_action_handler

Creates a handler for a lifecycle action. The handler created is expected to be returned as the result of the script defined by the lifecycle action field in the lifecycle JSON API.

To create the lifecycle action handler, use this method similarly to this:

local ocs = require "n2.n2ocs"
local handler = function(context, tracekey)
  ...
end
return ocs.create_lifecycle_action_handler (handler)

The create_lifecycle_action_handler() method returns a coroutine suitable for use by the OCS during lifecycle action processing.

Note that the lifecycle action script itself runs during initial startup of the OCS (or on load by the OCS if it is created dynamically via the OCS lifecycle API). That is to say, the script prepares itself for use during action processing.

Each instance of the OCS (specifically every verticle) will execute this script independently. Therefore it is possible to perform startup actions relevant to the execution of the handler, but any variables are only global to this instance of the script (and hence the OCS verticle), and are not global to all executions of the handler.

The following parameters are required for the create_lifecycle_action_handler() method call:

The handler itself is a function, and has the following structure:

local handler = function(context)
  ...
  -- either:
  -- ocs.succeeded('next')
  -- or
  -- ocs.failed (410, 'error - failure to complete processing')
  ...
end

The handler function provided to create_lifecycle_action_handler() will have the context passed to it as the first argument of the method.

The second argument to the handler function is the tracekey, a string that can be used in debugging and logging to trace the action processing unique to this instance of the call processing in the OCS.

Instead of returning from the handler using a return statement, the handler is expected to use either ocs.succeeded() or ocs.failed() to complete the method call.

.create_hook_handler

Creates a handler for a hook. The handler created is expected to be returned as the result of the script defined by the script field in the OCS Hook API.

To create the hook script, use this method similarly to this:

local ocs = require "n2.n2ocs"
local handler = function(context, tracekey)
  ...
end
return ocs.create_hook_handler (handler)

The create_hook_handler() method returns a coroutine suitable for use by the OCS during hook processing.

Note that the hook script itself runs during initial startup of the OCS (or on load by the OCS if it is created dynamically via the OCS hook API). That is to say, the script prepares itself for use during hook processing.

Each instance of the OCS (specifically every verticle) will execute this script independently. Therefore it is possible to perform startup actions relevant to the execution of the handler, but any variables are only global to this instance of the script (and hence the OCS verticle), and are not global to all executions of the handler.

The following parameters are required for the create_hook_handler() method call:

The handler itself is a function, and has the following structure:

local handler = function(context)
  ...
end

The handler function provided to create_hook_handler() will have the context passed to it as the first argument of the method.

.request_source

All OCS events are triggered by a source, aka the channel. This information is presented in a (read only) table of data to Lua scripts using this method.

This method accepts no parameters.

    ...
    local channel = ocs.request_source()
    ...

This method returns a request_source object: The request_source object represents auditing information about the source of the request the Lua script is processing:

.now

All engine requests are considered as at a certain time, which might not be the true now - but is instead the “now” the client wants us to think.

This method accepts no parameters.

    local now = ocs.now()

The seconds since epoch, but as a floating point number. The milliseconds component of the instant is the value after the decimal point.

Note that this time does not change during processing of the script. A 2s HTTP requests during processing for example will not alter the time returned by this method call.

To retrieve the wall clock time, use the ocs.time() Lua method call.

Note that if a script is run in a situation which does not strictly allow for a client-provided “now” time, this method will return the wall clock time. nil is never returned.

.time

Instead of using os.time(), use this to get a floating point value representing the same thing, but also with millisecond granularity.

This method accepts no parameters.

    local start_time = ocs.time()

The seconds since epoch, but as a floating point number. The milliseconds component of the instant is the value after the decimal point.

.notify

Attempts to send a notification to the interaction manager on the JSLEE This reuses the OCS notification subsystem to send this request. What occurs with the notification will depend on OCS configuration as notifications can be suppressed by OCS configuration.

This method requires several parameters:

For example, a lifecycle action my trigger the predormant notification 3 days prior to the state change on an wallet’s lifecycle with the lua:

    local ocs = require "n2.n2ocs"
    ocs.notify ("OCS_PREDORMANT", "3D", { wallet_id = ocs.context().active_wallet().id() })

The ocs.notify() method does not return any response. If the notification submission fails then the OCS will generate a system log message.

.succeeded

The succeeded() method is used to return a successful response from a Lua handler (e.g. a lifecycle action handler). It may be done anywhere in the Lua handler code and may be followed by additional logic. This allows a handler to trigger the early return to normal call processing, but perform follow-on actions such as send and manage the results of web services requests or file operations.

This method accepts one parameter. When used in the context of a lifecycle action, the parameter is interpreted in the following way:

Note that succeeded() and failed() can only be called once per event handler, i.e. a script cannot succeed or fail more than once for the same event.

local ocs = require "n2.n2ocs"
local handler = function (context)
    ...
    ocs.succeeded ('next')
end
return ocs.lifecycle_action_handler(handler)

The OCS succeeded() method doesn’t return any result.

.failed

This method returns a failure response back to the OCS engine at the point where the handler was triggered. It may be done anywhere in the Lua code and may be followed by additional logic (including as many events as required to send).

The response should be an error code, along with a string describing what the error is.

This method accepts two parameters.

Note that succeeded() and failed() can only be called once per event handler, i.e. a script cannot succeed or fail more than once for the same event.

local ocs = require "n2.n2ocs"
local handler = function (context)
    ...
    ocs.failed (600, "barred - international barring in effect")
end
return ocs.lifecycle_action_handler(handler)

The OCS failed() method doesn’t return any result.