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,
    *,
    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,
    *,
    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.

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",
)

5. Important note

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

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