Generische Jobparameter

Neben den Eingabeparametern, die jeder Job selbst definiert, wertet der Server-Kernel eine Reihe von Parametern aus, die bei beliebigen Jobaufrufen mitgegeben werden können — unabhängig von der ausführenden Engine. Diese Seite dokumentiert diese Parameter zentral; die Prozedurseiten der einzelnen Jobs führen sie nicht auf, sondern verweisen hierher.

Kenntlich sind diese Parameter an der Schreibweise mit dreifachem Dollarzeichen ($$$Name$$$).

1. Wechsel des Benutzerkontextes bei Jobaufrufen

Ein Serverjob kann in einem anderen Benutzerkontext ausgeführt werden. Dazu wird dem Jobaufruf einer der folgenden Parameter hinzugefügt:

Name Beschreibung

$$$SwitchContextUserGUID$$$

GUID des Benutzers, in dessen Namen der Job ausgeführt werden soll.

$$$SwitchContextUserID$$$

ID des Benutzers, in dessen Namen der Job ausgeführt werden soll. In enaio® 12.0 ohne Wirkung — siehe Wirksamkeit der drei Varianten.

$$$SwitchContextUserName$$$

Name des Benutzers, in dessen Namen der Job ausgeführt werden soll.

Die drei Parameter sind Alternativen — der Benutzer wird entweder über GUID, ID oder Name adressiert. Tatsächlich wirksam sind in enaio® 12.0 allerdings nur die GUID- und die Namensvariante (siehe Wirksamkeit der drei Varianten).

Bei Jobs, die das Rechtesystem auswerten, wird die Rechteprüfung für den angegebenen Benutzer ausgeführt. Auch weitere Jobs, die serverseitig als Folge des Aufrufs ausgeführt werden — etwa ein interner Aufruf von std.IndexDataChanged zum Erstellen eines Historieneintrages auf DMS-Objekte — laufen dann im Namen des angegebenen Benutzers.

Der ausführende (angemeldete) Benutzer benötigt die Systemrolle 72 (Server: Jobkontext wechseln, intern R_SRV_SWITCH_CONTEXT). Fehlt sie, wird der Aufruf mit dem Fehlercode -1042218022 („The system role R_SRV_SWITCH_CONTEXT is not present.") abgewiesen.

Die dem aufrufenden Benutzer zugewiesenen Systemrollen lassen sich mit mng.GetUserRoles ermitteln; eine Übersicht aller Rollen findet sich unter Systemrollen.

Kann der adressierte Benutzer nicht übernommen werden, wird der Aufruf mit dem Fehlercode -1043332467 abgewiesen — unabhängig vom aufgerufenen Job und unabhängig von der Ursache (siehe Fehler beim Kontextwechsel).

Dieselbe Rolle setzt auch krn.CheckUserAccount voraus — dort ohne Kontextwechsel, allein für den Aufruf des Jobs.

Typischer Anwendungsfall ist eine Integration, die unter einem technischen Service-Benutzer angemeldet ist, Operationen aber im Namen des fachlich handelnden Benutzers ausführen soll — damit greifen dessen Berechtigungen und der Historieneintrag nennt ihn als Verursacher.

Für die XML-Jobs der DMS-Engine existiert daneben der jobspezifische Eingabeparameter JobUserGUID (siehe Der Parameter JobUserGUID), der nur bei serverseitigen Aufrufen aus anderen Jobs zulässig ist.

1.1. Wirksamkeit der drei Varianten

In enaio® 12.0 wechseln nur $$$SwitchContextUserName$$$ und $$$SwitchContextUserGUID$$$ den Benutzerkontext.

$$$SwitchContextUserID$$$ bleibt wirkungslos: Der Job läuft unverändert im Kontext des angemeldeten Benutzers weiter — ohne Fehlercode und ohne Warnung. Geprüft wurde dies als INT- und als STRING-Parameter, mit gültiger wie mit erfundener Benutzer-ID und in mehreren Schreibweisen (verifiziert).

Eine Integration, die über die numerische Benutzer-ID impersoniert, läuft damit still mit den Rechten des technischen Benutzers weiter. Für den Kontextwechsel ist stattdessen $$$SwitchContextUserGUID$$$ oder $$$SwitchContextUserName$$$ zu verwenden.

1.2. Fehler beim Kontextwechsel

Scheitert der Kontextwechsel, wird der Jobaufruf mit dem Fehlercode -1043332467 (0xC1D0028D) abgewiesen. Dieser Code ist ein reiner Sammelcode: Er ist für alle Ursachen identisch und benennt lediglich, dass der Kontextwechsel nicht möglich war.

Die Ursache trägt erst der Fehlerstack der Antwort. Er unterscheidet fünf Zustände des Zielbenutzers — unbekannt bzw. gelöscht, manuell gesperrt, durch Fehlanmeldungen gesperrt, abgelaufen und noch nicht gültig; die zugehörigen Codes sind unter Ursachencodes im Fehlerstack aufgeführt.

Wer nur den Rückgabewert auswertet, kann einen gesperrten nicht von einem gelöschten Zielbenutzer unterscheiden. Der Fehlerstack enthält zusätzlich Einträge ohne Diagnosewert, die zu überspringen sind — siehe Einträge ohne Diagnosewert.

Die genannten Benutzerattribute lassen sich vorab mit mng.GetUserAttributes bzw. mng.GetUserList prüfen.

never_expire hebt validto nicht auf. Ein Konto mit abgelaufenem validto und gesetztem never_expire scheitert weiterhin mit -1042218315 — das Flag wirkt nur auf das Passwort, nicht auf die Kontogültigkeit (verifiziert).

Der Fehler ist nicht jobspezifisch: Derselbe Kontextwechsel scheitert identisch bei mng.GetUserRoles, mng.GetUserList und krn.GetServerInfo (verifiziert). Der Kontextwechsel wird vor dem eigentlichen Job ausgeführt; der Job, an dem der Fehler auffällt, ist damit lediglich der erste Aufruf nach dem Wechsel.

1.3. Zustände, die den Kontextwechsel nicht verhindern

Folgende Zustände des Zielbenutzers wechseln den Kontext regulär (verifiziert):

  • Der Zielbenutzer hat keine einzige Systemrolle. Ein anschließendes mng.GetUserRoles liefert dann ein leeres Result.

  • Für den Zielbenutzer ist ein erzwungener Passwortwechsel gesetzt (changepwd).

  • Der Zielbenutzer hat ein Gültigkeitsfenster, das den aktuellen Zeitpunkt einschließt.

  • Der Zielbenutzer war noch nie angemeldet.