Scripting engine types
Type 1 — Singleton
The engine starts on first use and is available for the entire application lifetime. Each call runs asynchronously relative to the main app, is thread-safe, but runs synchronously within the engine — so it has an impact on overall performance. Overridden functions are checked and the result is cached for better performance. If you don't want to use an event, it's better not to override the function at all (rather than leaving an empty one), due to marshalling overhead. Mainly used for storing general app data and shared resources between different scripting engines.
Entry point: Path.Combine(ExtraConfig:ScriptsRoot, "main.lua")
Type 2 — Transient
Each request runs on its own independent Lua engine, on a separate thread. Data can be passed between Lua instances. Lifetime equals the underlying request (web or DICOM).
Entry point: Path.Combine(ExtraConfig:ScriptsRoot, "main-transient.lua")
Type 3 — Background task
Each request runs on its own independent Lua engine, in a queued background task. Data can be passed between Lua instances.
Entry point: Path.Combine(ExtraConfig:ScriptsRoot, "main-task.lua")
Special types
Email — validated string, described in RFC 5322 (sections 3.2.3 and 3.4.1).
UID — Unique Identifiers, validated string, as per the DICOM specification.
System exports (app → script)
-- Access main app configuration (mainly from appsettings.json, but also other internal settings)
-- e.g.:
-- tusPath = Config["ExtraConfig:TusUploadFolder"]
-- configFolder = Config["ConfigRoot"]
object Config
-- Load native modules available in the Lua search path
function requireNative("socket.core")
-- Execute an OS command (escapes the escape hell)
function OsExecute(string command, string arguments)
-- Logging
function LogDebug(string message, params object[] args)
function LogInfo(string message, params object[] args)
function LogError(string message, params object[] args)
-- Start a Type 3 scripting engine
function LuaBackgroundWorker(string luaScriptPath, string entryFunc, string args)
-- Run an internal command
-- e.g.: InternalCmdRun("send", "[folder] [CallingAE:AE@remotehost:port]")
function InternalCmdRun(string command, string args)
Callbacks to app events
function onSendMail(mailObject)
-- Example:
mail = {}
mail["From"] = "test@dicom.link" -- typeof Email
mail["To"] = "test@dicom.link" -- typeof Email
mail["Subject"] = "subject"
mail["TextBody"] = "some text"
mail["HtmlBody"] = "some html text"
onSendMail(mail)
Notifications
function onNotificationShow(notificationObject)
-- notificationObject = { Title, Body, Link }
HTTP middleware
-- ILuaHttpRequest interface
-- request (read)
-- string Scheme
-- string Method
-- string Path
-- IHeaderDictionary Headers
-- AddHeader(string key, string value)
-- RemoveHeader(string key)
-- response (write)
-- AddResponseHeader(string key, string value)
-- RemoveResponseHeader(string key)
-- ResponseWrite(string data)
-- Called as the first middleware in the pipeline.
-- Return true to override/intercept the request.
function onHttpRequest(ILuaHttpRequest)
-- ILuaHttpResponse interface
-- request data (readonly):
-- string Scheme, Method, Path
-- response (modify if no body sent yet):
-- IHeaderDictionary Headers
-- AddHeader / RemoveHeader
-- ResponseWrite(string data)
function onHttpResponse(ILuaHttpResponse)
TUS protocol
-- Called when a file is successfully uploaded via TUS.
-- tus file id = metadata["fileId"]
-- file path = ExtraConfig.TusUploadFolder
-- Return true to override default handling.
function onTusFileComplete(Dictionary<string, string> metadata)
DICOM events
(Additional DICOM event callbacks are available in the full reference — contact support for details.)