create_os_event()

Creates a new server-side scripting event (OsEvent) via dms.CreateOsEvent and returns its id.

1. Signature

  • Sync

  • Async

ecm.system.create_os_event(
    event_code: int | ECMOsEventCode,
    script: str,
    *,
    is_js: bool = False,
    os_class_name: str | None = None,
    os_event_params: str | None = None,
    app_class: int | ECMOsAppClass | None = None,
) -> int
await ecm.system.create_os_event(
    event_code: int | ECMOsEventCode,
    script: str,
    *,
    is_js: bool = False,
    os_class_name: str | None = None,
    os_event_params: str | None = None,
    app_class: int | ECMOsAppClass | None = None,
) -> int

2. Parameters

Parameter Type Default Description

event_code

int | ECMOsEventCode

—

Event trigger. ECMOsEventCode lists well-known codes (e.g. KERNEL_BEFORE_JOB=5000); a plain int is also accepted.

script

str

—

Executable script code (JavaScript or VBScript, depending on the event type). Sent to the server as UTF-8 with a leading byte-order mark (BOM); the server detects the BOM and stores the full Unicode range. Any character valid in the script is preserved.

is_js

bool

False

Scripting language of the event: True = JavaScript, False = VBScript. The server stores the flag as passed — it neither derives it from the event code nor validates it.

os_class_name

str

None

Target object type: "Application" for application/server-wide events, otherwise the type_id as string. Defaults to application scope when omitted.

os_event_params

str

None

Context parameter whose meaning depends on event_code (field GUID, job name, or library name).

app_class

int | ECMOsAppClass

None

Target platform: CLIENT=1, SERVER=2, WEBCLIENT=3. Inferred from event_code when omitted.

3. Return value

The int id of the newly created event (the id field of an ECMOsEvent). Use it as the handle for update_os_event() and delete_os_event().

4. Examples

4.1. Create a server event

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMOsEventCode

event_id = ecm.system.create_os_event(
    ECMOsEventCode.KERNEL_BEFORE_JOB,
    "'my server script",
    os_class_name="Application",
)
from ecmind_blue_client.ecm import ECMOsEventCode

event_id = await ecm.system.create_os_event(
    ECMOsEventCode.KERNEL_BEFORE_JOB,
    "'my server script",
    os_class_name="Application",
)

4.2. Create a web client event (JavaScript)

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMOsAppClass

event_id = ecm.system.create_os_event(
    11017,  # AfterWebClientLogin
    "// my web client script",
    is_js=True,
    app_class=ECMOsAppClass.WEBCLIENT,
)
from ecmind_blue_client.ecm import ECMOsAppClass

event_id = await ecm.system.create_os_event(
    11017,  # AfterWebClientLogin
    "// my web client script",
    is_js=True,
    app_class=ECMOsAppClass.WEBCLIENT,
)

5. Important note

These operations access the enaio scripting infrastructure directly. Misconfigured events can disrupt the client or server.

Scripting language. is_js defaults to False (VBScript) and is stored exactly as passed; the server derives nothing from the event code. Web client events and the JavaScript libraries (event codes 10005 and 10006) are always JavaScript and must be created with is_js=True. Created with the default, such an event is stored as VBScript: it appears in the administration tool, is returned by get_os_events() — and never fires. Verified against enaio 12.0.

Script-code encoding. The VBCode parameter (BYTE[]) is transmitted as UTF-8 with a byte-order mark (BOM, EF BB BF). The server recognises UTF-8 only by the BOM: without it, the bytes are interpreted as the legacy code page (Windows-1252), so plain UTF-8 comes back with mangled non-ASCII characters. With the BOM the full Unicode range is preserved (umlauts, CJK, emoji …​). Verified empirically against enaio 12.0. The JSON payload returned by get_os_events(), by contrast, is always plain UTF-8 without a BOM.

6. See also