Script Executor

The Script Executor runs small scripts that automate call handling - interactive voice menus, call routing, call forwarding - so behaviour can be tailored without changing the software.

Overview

SBN Media can run scripts, written in a simple scripting language (Lua), to control how calls are handled. Each script is a *scenario*: it is started by an event in the system and runs its steps in response. Scenarios are kept as files and loaded when the service starts.

• Runs: When configured. One per host.
• Required: Only if you use scripted call handling. With no scripts, nothing runs and nothing breaks.
• Depends on: NATS. The scripts themselves are plain files on the host.

Configuration

The Script Executor is configured under the scriptexecutor namespace. The scripts live in a folder on the host.

Each scenario names the event that starts it and the steps it runs; scenarios are maintained as files in the scripts folder. After changing settings in sbn-media.local.yaml, apply them with ./sbn-media config reload.

The standard library

Scripts come with a built-in standard library - ready-made building blocks for the common things a script needs to do, such as injecting a signal, sending an SMS, text-to-speech, working with the alarm queue, SIP, and devices. A script uses one by requiring it:

local signal = require("signal")
local api3 = require("api3")

There are three ways to get at the library and its documentation:

• Browse the reference. The full library is documented and published by the API Proxy as a browsable reference at /script-stdlib/ - for example https://<your-api-proxy-host>/script-stdlib/. It lists every built-in library and the functions it provides. (This needs the API Proxy's static content to be enabled, which it is by default.)
• Read it on the host. The library's source, with its documentation comments, is written to the folder set by scriptexecutor.stdlib (by default ./scripts/stdlib/lua) when the service starts, so you can read the modules directly.
• Start from an example. Run ./sbn-media script eject to write out sample scripts you can copy and adapt.

FAQ

What can a script do?

Automate call handling - voice menus (IVR), routing, and forwarding - by reacting to events in the system.

Where do the scripts live?

In the folder set by scriptexecutor.location (./scripts by default).

Where do I find the built-in functions I can call?

In the standard library reference served by the API Proxy at /script-stdlib/, or by reading the library source written to scriptexecutor.stdlib (./scripts/stdlib/lua). See "The standard library" above.

Do I need it?

Only if you use scripted call handling. It does nothing until scenarios are added.

Related pages

• SBN Media Overview (SBN-Media/overview)
• Installing and Configuring SBN Media (SBN-Media/installation)
• SBN IVR (SBN-Media/Automation/sbn-ivr)
• Watchdog (SBN-Media/Platform/watchdog)