☰
Navigation :

Script Types

Introduction

The OCS supports several types of scripts that can be run within the OCS. The most frequently used are lifecycle actions, and hooks.

Lifecycle Actions

A lifecycle action is defined as an action on a lifecycle state. In API terms, this is done by creating a lifecycle state with the embedded lua code in the action:

POST {{ocs_host}}/resource/lifecycle/my-lifecycle/state/CREATED

Where {{ocs_host}} is the OCS API hostname/port, and my-lifecycle is the lifecycle being enhanced, and CREATED is the state being updated. For more information on the OCS lifecycle creation API, see the OpenAPI docs.

The POST should include the Lua action content:

{
    "action" : "local ocs = require \"n2.n2ocs\"\nlocal f = function()\nocs.succeeded('next')\nend\nreturn ocs.create_lifecycle_action_handler (f)",
    "action_language": "lua",
    "description" : "Example Lua action. Will automatically move to the next state via the next transition.",
    "name" : "Created",
    "id" : "CREATED",
    "transitions" : [ {
        "event" : "next",
        "to_state" : "PREUSE"
    } ]
}

Note the use of action_language set to lua. The default scripting language is javascript (which has been deprecated) and for lua scripts lua must be explictly specified.

The action is the Lua code to run to create the lua action to run, and has the following basic format:

local ocs = require "n2.n2ocs"
local f = function(context, tracekey)
  ocs.succeeded('next')
end
return ocs.create_lifecycle_action_handler (f)

This Lua script:

  1. Loads the OCS API.
  2. Defines a function that will be the handler called when the associated lifecycle action is triggered.
  3. The handler uses the ocs.succeeded() method. This is analogous to the JSLEE.succeeded() method, returning a successful result from the handler - in this case the name of the transition to take.
  4. The last line then uses the ocs.create_lifecycle_action_handler() method to create the handler for the OCS, and returns it.

More detail is provided in the create_lifecycle_action_handler() documentation.

Hooks

A hook is defined as a script as part of the hook API call. In API terms, this is done by creating a hook with the embedded lua code in the hook creation:

POST {{ocs_host}}/resource/hook

Where {{ocs_host}} is the OCS API hostname/port, For more information on the hook API, see the OpenAPI docs.

The POST must include the action content:

{
  "id": "set_lifecycle_expiry_on_access",
  "name" : "Set Lifecycle Expiry on Access",
  "hookclass" : "lua",
  "type" : "engine",
  "event" : "pre_return_response",
  "priority" : 500,
  "actions" : [ "debit", "credit" ],
  "script": "# the Lua script"
}

Note the use of hookclass set to lua. Other hook classes (such as jslee-notification and javascript) support different hook formats and features.

The script is the Lua code to run when the hook is loaded. This code must create the callback that should be executed when the hook executes (based on the actions and event defined), and has the following basic format:

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

This Lua script:

  1. Loads the OCS API.
  2. Defines a function that will be the handler called when the associated hook is triggered.
  3. The hook handler function will execute with the given context each time it is triggered.
  4. The last line then uses the ocs.create_hook_handler() method to create the handler for the OCS, and returns it.

More detail is provided in the create_hook_handler() documentation.

File-Based Scripts

A hook or lifecycle script is expected to be a syntactically correct Lua script which executes the appropriate actions for the context in which it is run. However script logic can become quite involved and to manage script content it might be preferable to store scripts on disk rather than in the database.

To execute a script from disk, simply require the script:

return require "myscript"

The Lua library path will be used to load the script and execute it.