run_script()

Executes a script on the server via krn.RunScript. Supports both VBScript and JavaScript.

The script text is resolved in the following order: script parameter, script_file, file list. If the script is empty and only parameters are passed, only server-side Before/After events are triggered.

1. Signature

  • Sync

  • Async

ecm.system.run_script(
    script: str = "",
    *,
    script_file: str | None = None,
    javascript: bool = False,
    evaluate: bool = False,
    context_name: str = "",
    main_function: str | None = None,
    inspector_enabled: int | None = None,
    script_name: str | None = None,
    files: list[JobRequestFile] | None = None,
    **params: JobValueTypes,
) -> JobResult
await ecm.system.run_script(
    script: str = "",
    *,
    script_file: str | None = None,
    javascript: bool = False,
    evaluate: bool = False,
    context_name: str = "",
    main_function: str | None = None,
    inspector_enabled: int | None = None,
    script_name: str | None = None,
    files: list[JobRequestFile] | None = None,
    **params: JobValueTypes,
) -> JobResult

2. Parameters

Parameter Type Default Description

script

str

""

The script text to execute. In evaluate mode this can be a simple expression (e.g. "40 + 2"). In exec mode it should contain a Main function (or the function named by main_function). Can be empty when using script_file.

script_file

str | None

None

Name of a script file in the server’s scripts configuration subdirectory. Used when script is empty.

javascript

bool

False

If True, the script is executed as JavaScript instead of VBScript.

evaluate

bool

False

If True, the script is evaluated as an expression and its value is returned. If False, the script is executed and the return value of the main function is returned.

context_name

str

""

Name of the script context. An empty string uses the server’s default context.

main_function

str | None

None

Name of the entry-point function. Defaults to "Main" on the server when not provided.

inspector_enabled

int | None

None

V8 inspector control for JavaScript debugging. 0 = disabled, 1 = enabled, -1 = determined by oxv8.metadata.cfg.

script_name

str | None

None

Name of the script for debugging purposes.

files

list[JobRequestFile] | None

None

Optional list of input files to send to the script.

**params

JobValueTypes

 — 

Additional keyword arguments are sent as input parameters to the job and are accessible from within the script.

3. Return value

A JobResult object. The script return value is accessible via result.get("$ScriptResult$", …​). Additional output parameters via result.get(name, …​) and returned files via result.files.

4. Examples

4.1. Evaluate an expression (eval mode)

  • Sync

  • Async

result = ecm.system.run_script("40 + 2", evaluate=True)
print(result.get("$ScriptResult$", str))  # "42"
result = await ecm.system.run_script("40 + 2", evaluate=True)
print(result.get("$ScriptResult$", str))  # "42"

4.2. Execute JavaScript (exec mode)

  • Sync

  • Async

script = """
function Main() {
    return "Hello from JavaScript";
}
"""
result = ecm.system.run_script(script, javascript=True)
print(result.get("$ScriptResult$", str))  # "Hello from JavaScript"
script = """
function Main() {
    return "Hello from JavaScript";
}
"""
result = await ecm.system.run_script(script, javascript=True)
print(result.get("$ScriptResult$", str))  # "Hello from JavaScript"

4.3. Pass parameters to the script

  • Sync

  • Async

script = """
function Main() {
    return "Hello " + GetEntry("UserName");
}
"""
result = ecm.system.run_script(script, javascript=True, UserName="Max")
print(result.get("$ScriptResult$", str))  # "Hello Max"
script = """
function Main() {
    return "Hello " + GetEntry("UserName");
}
"""
result = await ecm.system.run_script(script, javascript=True, UserName="Max")
print(result.get("$ScriptResult$", str))  # "Hello Max"

5. See also

  • empty_job() — Generic no-op job for server-side events