Serverweite Aktivierung / Konfiguration per oxv8.cfg

Die Konfigurationsdatei oxv8.cfg im Installationsverzeichnis in eniao® server enthält die Sektion [inspector], in der die Konfigurationsparameter des Debuggers eingetragen sind. Die oxv8.cfg liegt immer direkt im Serververzeichnis, da sie nach dem Löschen erneut in einer Default-Variante vom Server erzeugt wird. In dieser Datei kann das Debugging für enaio® server grundlegend im System aktiviert werden. Per Default ist das Debugging in einer Installation deaktiviert. Eine Änderung an dieser Datei bedingt einen Neustart des Servers. Die Feinregulierung auf die zum Debuggen vorgesehenen Events wird nachfolgend und ohne Neustart über die oxv8.metadata.cfg gesteuert.

Auszug aus [Server-Install]\oxv8.cfg:

Mit Enabled = 0/1 (Default: 0) kann man regeln, ob Inspector verwendet wird oder nicht. Diesen Schalter liest der Server beim Start und verwendet ihn dann bei jeder Ausführung von Eventskripten. Eine Änderung dieses Schalters erfordert einen Neustart des enaio® servers.

Kommunikation  mit den Chrome DevTools als GUI für das Debuggen erfolgt per Netzwerk (HTTP + Websockets). Chromium ist dabei ein Http-Client, der AppServer ist dabei der Http- bzw. Websocket-Server. Beim Start erstellt der Server einen TCP-Listener mit Host und Port (falls Enabled = 1). Die Portnummer 9191 ist hier nur ein Beispiel. Die Portnummer kann frei vergeben werden.

Trace = 0/1/2 regelt, ob ausführliche Websocket-Protokollierung notwendig ist (das Tracing sollte nur aktiviert werden, wenn Probleme mit dem Inspector auftreten und die Verbindung zu den Chrome DevTools (CDT) nicht hergestellt werden kann).

0 - keine Protokollierung

1 - Protokollierung ohne Http-Pings

2 - Protokollierung mit Http-Pings

LogDir besagt, in welchem Verzeichnis die Protokolldateien erstellt werden. Aktuelle Datei heißt immer oxv8.inspector.log. Die Datei liegt per Default im Installationsverzeichnis des Servers unter Install-Dir\log, sofern kein anderes Verzeichnis konfiguriert wurde. Die Datei wird tageweise geschrieben. Am neuen Tag wird sie nach oxv8.inspector.YYYY-MM-DD.log umbenannt. 

StartTimeout gibt die Zeit an, die im ausführenden Skript gewartet wird, ob ein Debugger den Prozess steuern möchte. Die Eingabe erfolgt in Millisekunden. Nach Verstreichen dieser Frist, wird das Skript ohne Debugger weiter auf dem Server ausgeführt. 

Inspector ein- / ausschalten

Die Einstellung inspector\Enabled regelt, ob das Debugging prinzipiell möglich ist (technisch bedeutet dies vor allem, ob der TCP-Listener für den CDT gestartet wird), oder nicht. Für den produktiven Betrieb empfehlen wir, im Normalfall diesen Wert auf 0 zu setzen. Wenn der Inspector prinzipiell aktiviert ist, werden trotzdem noch keine Skripte in den Debugging Prozess einbezogen. Um zielgerichtet konkrete Server-Skript zu debuggen müssen diese zuerst für den Inspector freigeschaltet werden. Das wird in der Datei oxv8.metadata.cfg geregelt und im Folgenden beschrieben. 

Aktivieren von Events zum Debugging per osv8_meta.cfg

Nachdem das Debugging in der oxv8.cfg aktiviert wurde, ist ein weiterer Schritt nötig. Das Debugging muss nun für einzelne oder mehrere Events jeweils aktiviert und freigeschaltet werden. Diese Einstellungen können ohne einen Serverneustart durch Editieren der Datei oxv8.metadata.cfg vorgenommen werden. Pro Event wird in dieser Datei eine Sektion eingerichtet. Die Namen von Sektionen entsprechen den Skriptnamen. Diese Sektionsnamen sind case-sensitiv. Das Namensschema der Skriptnamen ist unten im Detail beschrieben. Jeder Sektion kann den Eintrag Name=script-name beinhalten. In diesem Fall wird Sektionsname ignoriert und ist frei wählbar und dieser Eintrag regelt, welcher Event durch diese Sektion gesteuert wird.

Die Datei enthält für jedes Skript eine eigene Sektion zu Steuerung des Inspectors und damit der Debug-Möglichkeiten. Diese Sektionen haben folgenden Aufbau:

InspectorEnabled besagt, ob bei diesem Skript der Inspector verwendet werden darf oder nicht.
Mögliche Werte sind:

0 – "false": Den Inspector nicht verwenden, das Skript kann aktuell nicht debugged werden.

1 –  "true": Den Inspector verwenden, das Skript kann prinzipiell debugged werden.

-1 –  "unknown": Ob der Inspector verwendet wird oder nicht, wird für dieses Skript zentral in der oxv8.cfg geregelt. unknown ist auch der Defaultwert, falls die Sektion in oxv8.metadata.cfg fehlt.

Der Wert unknown ist nur für krn.RunScript relevant (s. u.). Für andere Server-Events wird dieser Wert wie false ausgewertet.

InspectorConnectOnStart besagt, dass die Verbindung des Inspectors zur Scriptausführung hergestellt wird. Das Skript wird aber nicht automatisch am Anfang der Ausführung in der Scriptengine angehalten. Das Anhalten des Skripts im Debugger ist möglich mit rc.inspector.breakPointHere(true).
Mögliche Werte sind:

0 –  "false": Der Inspector wird mit dem Script verbunden und kann einem beliebigen Breakpoint angehalten werden.

1 –  "true": Der Inspector wird mit dem Script verbunden und kann einem beliebigen Breakpoint angehalten werden.

-1 –  "unknown": Ob die Verbindung des Inspectors hergestellt wird oder nicht, wird für dieses Skript zentral in der oxv8.cfg geregelt. unknown ist auch der Defaultwert, falls dieser Wert in der entsprechenden Sektion zum Event in oxv8.metadata.cfg fehlt.

InspectorBreakOnStart besagt, dass die Programmausführung automatisch beim Start des Skripts angehalten wird.
Mögliche Werte sind:

0 –  "false": Der Inspector wird die Scriptausführung nicht automatisch in der ersten Scriptcode Zeile anhalten, sondern an einer späteren Stelle, an der das Skript dies explizit wünscht (siehe rc.inspector.breakPointHere(false)).

1 –  "true": Der Inspector wird die Ausführung des Skripts in der ersten Codezeile anhalten und im verbundenen Debugger anzeigen.

-1 –  "unknown": Ob das Skript automatisch beim Start der Skriptausführung angehalten wird oder nicht, wird für dieses Skript zentral in der oxv8.cfg geregelt. unknown ist auch der Defaultwert, falls dieser Wert in der entsprechenden Sektion zum Event in oxv8.metadata.cfg fehlt.

Falls die Konfigurationsdatei oxv8.metadata.cfg im Installationsverzeichnis des Servers nicht existiert, wird sie beim Starten des Servers erneut mit sinnvollen Default-Einträgen erzeugt. Liegt beim Starten des enaio® servers dort bereits ein solche Datei, wird diese verwendet.

Exemplarischer Auszug aus [Server-Install]\oxv8.metadata.cfg:

Die Bezeichnung der entsprechenden Sektionen in der Konfigurationsdatei ist durch die im folgenden aufgeführte Namensgebung beschrieben.

Naming der allgemeinen Serverskripte

Im Server gibt es folgende Skripte (die Namen entsprechen den Namen im Client-Skripteditor):

• KDE Skripte (Before- und After-Events zu jedem Job). Der jeweilige Sektionsname ist dabei wie folgt aufgebaut: KernelBeforeJob#dms.XMLUpdate und KernelAfterJob#dms.XMLUpdate.

• JDE-Skripte die pro Objekttyp konfiguriert werden (momentan nur std.DoArchive): JobBeforeObject#std.DoArchive und JobAfterObject#std.DoArchive

• Spezielle JDE Skripte:

  • JDE#OnObjectHistoryEntry

  • JDE#OnInitializeMedium

  • JDE#BeforeStartArchiveBatch

  • JDE#BeforeOpenMedia

  • JDE#OnCloseMedia

  • JDE#OnFinishMedia

  • JDE#OnFinishArchiveBatch

  • JDE#OnArchiveError

  • JDE#OnSessionLogin

• Skripte, die per krn.RunScript Job ausgeführt werden: RunScript#skript-name. Nach dem # kommt der Name des Skripts (s. entsprechenden krn.RunScript Job Parameter)

Naming der WF seitigen Serverskripte

Die Namen der WF seitigen Serverskripte entsprechen den im WF-Editor sichtbaren Daten aus dem Skriptbaum eines Modells. Das Naming folgt allgemein dem Schema WFM#{ Modellname }@{ Aktivittätsname }@{ Eventbezeichner }. Modell- und Aktivitätsname sind im jeweiligen Modell durch den Bearbeiter festgelegt.
Als Eventbezeichner stehen folgende Werte zur Verfügung:

• StartActivity

• EndActivity

• PersonalizeWorkItem

• GetWorkItemParams

• CancelWorkItem

• TimerFired

• StartInstance

• EndInstance

• TerminateActivity

Als Beispiel ergibt sich dann für eine solche Sektion des "EndActivity (JS)"-Events der Initialisierungs-Aktivität aus dem Beispiel Taskflow Modell von enaio® ein Sektionsname wie folgt: [WFM#Taskflow 1.8.1 german@Initialisierung@EndActivity].

Für das Debugging von Schleifenbedingungen gilt das Namensschema WFM#{ Modellname }@{ Aktivititätsname }.

Für das Debugging von Transitionsbedingungen gilt das Namensschema WFM#{ Modellname }@{ Start-Aktivititätsname }@{ Ziel-Aktivititätsname }.

krn.RunScript

Der Serverjob krn.RunScript ist an dieser Stelle etwas Besonderes. Das Debugging dieses speziellen Jobs muss explizit in der serverseitigen Registry freigeschaltet werden. Dafür existiert der Registry-Schalter: .\ScriptEngine\V8RunScriptInspector.
Folgende Werte sind dabei möglich:

0 – Der Inspector ist bei krn.RunScript grundsätzlich ausgeschaltet

1 – Der Inspector ist bei krn.RunScript prinzipiell möglich. Ob der Inspector bei konkretem krn.RunScript verwendet wird oder nicht, wird pro Job geregelt.

Der Serverjob krn.RunScript hat folgende optionale Parameter

IsJS (boolean) : true besagt. dass es ein JS Skript ist. Andernfalls handelt es sich um ein VBS Skript. Die folgenden Parameter haben nur eine Auswirkung, wenn es um die Ausführung eines JS Skripts geht.

ScriptName (string) : Name des Skripts (Name kann auch leer sein)

InspectorEnabled (integer) :

0 – false : Inspector nicht verwenden

1 (genau gesagt >0) – true : Inspector verwenden

-1 (genau gesagt <0) – unknown : durch oxv8.metadata.cfg regeln. Das ist auch der Defaultwert (falls der Parameter fehlt).

Zusammenfassung

• Bei Serverevents wird Inspector nur dann verwendet, wenn die entsprechende Sektion in oxv8.metadata.cfg existiert, und InspectorEnabled=1. Mit den Werten InspectorConnectOnStart und InspectorBreakOnStart wird das Anhalten eines Skripte im Debugger gesteuert.

• Bei krn.RunScript wird Inspector nicht verwendet, falls ScriptEngine\V8RunScriptInspector=0.

• sonst: falls Eintrag in oxv8.metadata.cfg nicht vorhanden oder ausgeschaltet ist oder der Job-Parameter InspectoreEnabled=0, wird der Inspector nicht verwendet.

• sonst: falls Eintrag in oxv8.metadata.cfg vorhanden und Job-Parameter=true wird Inspector verwendet

• sonst: wird Inspector nicht verwendet

Speziell bei der Steuerung des Serverjobs krn.RunScript hat also immer ein Verbot Priorität.