[ADMIN] Prozessverwaltung Hooks

Inhalt

Hooks sind automatische Nachverarbeitungsschritte in MOXIS. In diesem Tab der Prozessverwaltung können Sie ihre Konfiguration ausführen. 

1. Begriffsklärung

Hook: ist ein automatischer Nachverarbeitungsschritt in MOXIS, der zeitlich abgestimmt in regelmäßigen Abständen ausgelöst werden kann (zB die automatische Ablage von Files am Filesystem oder die Anlage eines Auftragsprotokolls). 

Sambashare: Ein Samba-Dateiserver ermöglicht die gemeinsame Nutzung von Dateien zwischen verschiedenen Betriebssystemen über ein Netzwerk.

Cron Job: Das Programm cron wird verwendet, um Skripte und Befehle in regelmäßigen Abständen sowie zu bestimmten Zeiten und Daten auszuführen. Es ist in die meisten Linux-Anwendungen integriert und bietet die Möglichkeit, Aufgaben auf Ihrem Server zu planen.

1.1. Der Hook-Tab in der Prozessverwaltung 

Um den Hook-Tab in der Prozessverwaltung zu öffnen, steigen Sie in den Administrationsbereich ein und öffnen Sie die Prozessverwaltung. Klicken Sie sodann auf den Basisprozess, den Sie bearbeiten möchten oder legen Sie einen neuen an. Unter dem Reiter Hook (siehe Abbildung 1 [1]) können Sie die Einstellungen für Hooks konfigurieren. 

XiTipp
Bitte beachten Sie: Die in diesem Reiter dargestellten Optionen hängen von der Basiskonfiguration von MOXIS ab, die in Zusammenarbeit mit XiTrust erstellt wurde. Daher kann es sein, dass Sie in Ihrer Übersicht weniger Optionen angezeigt bekommen. Sollte eine der Optionen eine sinnvolle Ergänzung für Ihre aktuelle MOXIS Instanz sein, so wenden Sie sich bitte an Ihre:n XiTrust Ansprechpartner:in.

1.1.1. Grundlegendes zu Hooks 

Folgende Hooks stehen optional zur Verfügung und können entsprechend der gewünschten Konfiguration eingesetzt werden: 

• CSRD Datenerfassung (Standard)

• Nach MOXIS Guest publizieren (Standard)

• Jobstatus übermitteln (Standard)

• Datei lokal ablegen (nur für On-Prem Anwendungen)

• Datei am Sambashare ablegen (nur für On-Prem Anwendungen)

• Datei an Output Service senden 

• Protokoll aktualisieren (auslaufend - bei Fragen kontaktieren Sie bitte den XiTrust Support)

Hooks ermöglichen das Hinzufügen benutzerdefinierter Aktionen bei bestimmten finalen und nicht finalen Events im MOXIS Default-Workflow. Sobald eines der ausgewählten Events ausgelöst wird, wird die entsprechende Hook-Verarbeitung gestartet. Die Konfiguration erfolgt über den Hook Event Block (siehe Abbildung 1 [2]). 

Einem Prozess können beliebig viele Hooks hinzugefügt werden. Dazu klicken Sie bitte einfach auf den [Neuen Block hinzufügen]-Button (siehe Abbildung 1 [3]) und wählen die gewünschten Hooks aus. Mit einem Klick auf den [Speicher]-Button (siehe Abbildung 1 [4]) speichern Sie Ihre Änderungen, während Sie sie mit einem Klick auf den [Verwerfen]- oder [Löschen]-Button (siehe Abbildung 1 [4]) verwerfen oder löschen können.  

Der Mechanismus übernimmt die Vorbereitung von Daten und – falls erforderlich – die asynchrone Ausführung von Aktionen mit Retry-Handling, während der korrekte ProcessState gesetzt wird. Sie können Aufgaben nach Erreichen des Retry-Limits manuell über die Admin-UI auslösen.

Jeder Hook reagiert auf bestimmte, definierte Events bei der Verarbeitung eines Auftrags. Es können entweder alle für den jeweiligen Hook verfügbaren Events ausgewählt werden oder Sie können eine bestimmte Auswahl treffen. Welche Events von einem Hook unterstützt werden, können Sie sehen, wenn Sie mit der Maus über das Rufzeichen-Icon fahren (siehe Abbildung 2 [1]).

Sofern Hooks durch das gleiche Ereignis ausgelöst werden, können sie in einem Block zusammengefasst werden. In unserem Beispiel ist das Datei lokal ablegen und Datei am Sambashare ablegen (siehe Abbildung 3 [1]). Hooks, die zu einem Block hinzugefügt werden, arbeitet MOXIS in der Reihenfolge ab, in der sie konfiguriert wurden. Dabei werden alle konfigurierten Hooks durchlaufen. Zudem wird überprüft, ob das entsprechende Event ausgelöst werden muss oder nicht. 

In den folgenden Kapiteln stellen wir Ihnen die einzelnen Hooks und ihre Konfigurationsmöglichkeiten näher vor. 

1.1.2. CSRD Datenerfassung Hook 

Dieser Hook dient der Datensammlung für den CSRD-Report in MOXIS. Er stellt die Ausnahme unter den Hooks dar, denn er kann nicht konfiguriert werden (siehe Abbildung 4). Ist er in einem Prozess aktiviert, stellt er sicher, dass MOXIS im Hintergrund alle Daten sammelt, die für den Report benötigt werden.  

1.1.3. Nach MOXIS Guest publizieren Hook

Verwenden Sie diesen Hook (siehe Abbildung 5), um Dokumente mit dem Status erfolgreich beendet externen Personen (nach Signatur) zum Herunterladen zur Verfügung zu stellen. Diese bekommen dann eine E-Mail mit einem entsprechenden Link zugeschickt.

Sie haben zwei Möglichkeiten, den Hook via Bearbeiten-Icon zu editieren (siehe Abbildung 6)

1. Für externe Unterschreiber publizieren

2. Für zusätzliche Empfänger:innen publizieren

   1. Wenn diese Option aktiviert ist, können beim Anlegen von Aufträgen zusätzliche Empfänger:innen angegeben werden. 

1.1.4. Jobstatus übermitteln Hook

Nutzen Sie diesen Hook, um den Job-Status per HTTP POST Webservice Call an ein anderes System zu übermitteln (siehe Abbildung 7). Bitte beachten Sie: Dieser Hook ist der einzige, der durch alle Events ausgelöst werden kann. Jedoch kann hier ebenso eine optionale Auswahl getroffen werden. 

Um den Hook zu editieren, klicken Sie bitte auf das Bearbeiten-Icon. Um ihn zu löschen, auf das rote x-Icon. 

Bitte beachten Sie: Solange bei der Konfiguration ein rotes Rufzeichen angezeigt wird, ist der Hook ungültig konfiguriert. 

Die Konfiguration des Jobstatus übermitteln Hooks erfolgt in fünf Schritten (siehe Abbildung 8, welche mit Beispieldaten konfiguriert ist): 

1.  Definieren Sie einen Zugriffspunkt (siehe Abbildung 8 [1]). Bitte beachten Sie: Vergessen Sie bei der Eingabe keinesfalls das https:// vor der URL.

2.  Testen Sie die Verbindung mit einem Klick auf den [Verbindung testen]-Button (siehe Abbildung 8 [2]) und bestätigen Sie Ihr Vertrauen in das Serverzertifikat.

3.  Wiederholen Sie Schritt 2, bis Verbindung als erfolgreich angezeigt wird.

4.  Konfigurieren Sie die Benutzer Klassifizierung (siehe Abbildung 8 [3]), die Header Parameter (siehe Abbildung 8 [4]) und die Wiederholungsintervalle (siehe Abbildung 8 [5]). 

5.  Legen Sie den Authentifizierungsmodus fest (rechte Seite). Sollten Sie Fragen zum Authentifizierungsmodus haben, wenden Sie sich bitte an den XiTrust Support. 

1.1.4.1. Optional: Zertifikatsprüfung überspringen

Seit MOXIS 4.52 gibt es die Möglichkeit, den Schritt des Testen der Verbindung zu überspringen. Dazu wurde die Checkbox Zertifikatsprüfung überspringen eingeführt. Ist das Häkchen hier gesetzt (siehe Abbildung 9 [1]), testet der Klick auf den [Verbindung testen]-Button lediglich nur mehr die Verbindung. Dabei ist es egal, ob die URL SSL aufweist oder nicht. Das bedeutet, dass sowohl bei https, als auch bei http die Meldung Verbindung erfolgreich erfolgt. Die Sicherheit des Links wird jedoch nicht mehr hinterfragt. 

XiTipp 
Ist die Checkbox nicht aktiviert, behält die Verbindung nur solange Gültigkeit, wie das Zertifikat gültig ist. Die Funktion wie sie bis zur Version 4.52 von MOXIS bekannt war, bleibt also weiterhin bestehen. 

1.1.4.2. Konfiguration der Benutzer Klassifizierung 

Die Benutzer Klassifizierung dient der Ausgabe des Benutzers oder der Benutzerin in einem bestimmten Format (siehe Abbildung 10). Sie haben die Wahl zwischen: 

• UPN:  User Principle Name zur Übergabe an Active Directory; z.B.: Andreas Mustermann > amustermann

• Email: E-Mail wird mit übergeben, z.B.: andreas.mustermann@xitrust.com

• ID: Übergabe der ID 

1.1.4.3. Konfiguration der Header Parameter 

Die Header-Parameter werden mit dem Auftrag verschickt. Es handelt sich dabei um Parameter, die das Fremdsystem, an die sie geschickt werden, auslesen kann. So können weitere Parameter festgelegt werden, um z.B. der Firewall eines anderen Systems zu signalisieren, dass die Übertragung sicher ist. 

Wenn Sie zusätzliche Header Parameter konfigurieren, verwenden Sie "=" als Trennzeichen zwischen <Schlüssel>=<Wert>, um sie in separaten Zeilen im Texteingabefeld zu konfigurieren. 

Ein "=" wird automatisch hinzugefügt, wenn es vorher nicht eingegeben wurde.

Ein Anwendungsfall ist die Einstellung eines speziellen Headers "X-API-KEY" für einen Kunden, der diesen Header verwendet, um die Anfrage an die richtige Anwendung auf seiner Seite weiterzuleiten → z.B.: X-API-KEY = MOXIS_SIG (siehe Abbildung 8 [4])

XiTipp 

Bei Fragen zur Konfiguration der Header Parameter wenden Sie sich bitte an den XiTrust Support. 

1.1.4.4. Konfiguration der Wiederholungsintervalle 

Setzen Sie hier das Intervall, in dem Sie eine Wiederholung einleiten wollen, falls der Hook fehlgeschlagen sein sollte (siehe Abbildung 8 [5]). Dabei geben Sie bitte die Anzahl an Tagen/Stunden etc. ein, die verstreichen darf, bis der Job erneut gestartet wird. Die Syntax ist dabei folgende (erklärt an einem Beispiel): Für einen Tag, 10 Stunden und 30 Minuten geben Sie bitte 1d10h30m ein.    

1.1.5 Datei lokal ablegen 

Mit diesem Hook legen Sie Dateien direkt auf dem Server ab, auf dem MOXIS installiert ist (siehe Abbildung 11). 

XiTipp 
Bitte beachten Sie: Der Dateien lokal ablegen Hook kann nur auf On-Prem Instanzen von MOXIS eingesetzt werden.

Dabei können Sie folgende Konfigurationen vornehmen (siehe Abbildung 12):

• Dokumente: Legen Sie den Folder- und den Dateinamen hier fest, unter welchem die unterschriebenen Dokumente abgelegt werden sollen.

• Dokumenten-Regex: Durch eine Regex lässt sich der Hook auf Dokumente einschränken, welche dem angegebenen Namensmuster folgen.

• Anlagen: Legen Sie den Folder- und den Dateinamen hier fest, unter welchem die Anlagen/Beilagen abgelegt werden sollen.

• Anlagen-Regex: Durch eine Regex lässt sich der Hook auf Anlagen/Beilagen einschränken, welche dem angegebenen Namensmuster folgen.

• Protokoll-Pfad: Legen Sie den Pfad hier fest, unter welchem das erstellte Auftragsprotokoll abgelegt werden soll. Definieren Sie zudem die Sprache, in welcher es erstellt und abgelegt werden soll.

• Job Status-Pfad: Geben Sie hier den Pfad an, unter welchem eine JSON-Datei mit dem Auftragsstatus abgelegt werden soll.

• Job Status: Die Nutzer-Identifikationsart gibt an, wie die Benutzerdaten im generierten JSON gespeichert werden sollen: 

• UPN = Login Name oder User Principal Name bei Anbindung an AD 

• ID= fortlaufende eindeutige Identifikationsnummer oder 

• Mailadresse in MOXIS.

• Bitte beachten Sie: Das JSON File entspricht der Spezifikation des Layer 2 Get job state Aufruf.

• Intervall für erneuten Versuch (s,m,h,d):Hier kann definiert werden, nach welchen jeweiligen Zeitabständen ein erneuter Versuch für die Ablage gestartet werden soll. Z. B. würde 1m, 1h, 1d bedeuten, dass MOXIS die Ablage zuerst nach einer Minute, dann nach einer Stunde und dann nach einem Tag nochmals probiert, bevor der Auftrag unter Nachverarbeitung wiederholen erscheint. Dort kann die Nachverarbeitung manuell gestartet werden. 

1.1.6. Ersetzungen für Dateinamensvorlagen 

Die folgenden Ersetzungen können unter anderem mit Dateinamensvorlagen für den Datei lokal ablegen-Hook und den Protokoll aktualisieren-Hook verwendet werden. 

XiTipp 
Bitte beachten Sie: Die unten aufgelisteten, sogenannten "Freemarker" gelten nben dem Dateil lokal ablegen-Hook auch für Sambashare und je nach Camel auch für das Outputservice. 

...${processInstanceId} # Replaced with processInstanceID

  ...${refNo} # Replaced with job reference number

  ...${fileName} # Filename of document WITHOUT extension eg "test"

  ...${fileNameWithExtension} # Filename of document WITH extension eg "test.pdf"

  ...${fileExtension} # Extension of document eg "pdf"

  ...${processParameterId} # Process entry ID/Process parameter ID

  ...${processLaunchParameterId} # Process launch ID

  ...${creationDateTime} # creation Date as Java Date (to be used when providing custom dateformat in template eg: ${creationDateTime?datetime?string("dd-MM-yyyy")})

  ...${creationDate} # creation Date as String (format according to: moxis.commons.fileName.fileNameDateFormat | default format "yyyy-MM-dd")

  ...${exportDateTime} # date of export as Java Date (see creationDateTime)

  ...${exportDate} # date of export as String (see creationDate)

  ...${jobOwner} # Full name of job owner

  ...${currentIteration} # current iteration

  ...${category} # job Category

  ...${duplication} # Placeholder for file duplication marker: If filename does not yet exist in destination it will be empty, otherwise it will be a counter to prevent duplicate files (e.g.: "myfile${duplication}.out" might result in the files "myfile.out" "myfile1.out" "myfile2.out" ...)

  ...${getProcessNameForParameterId(<id>,<locale>)} # get the process name in given locale and for the given process parameter id 

     # - i.e.: <#assign id = processParameterId>${getProcessNameForParameterId(id,'de')}

  ...${getProcessNameForLaunchParameterId(<id>,<locale>)} # get the process name in given locale and for the given process launch parameter id 

     # - i.e.: <#assign id = processLaunchParameterId>${getProcessNameForLaunchParameterId(id,'en')}

Datums- und Zeitwerte sind nur zu verwenden, wenn ein benutzerdefiniertes DateTime-Format erforderlich ist (siehe Abbildung 13).

XiTipp 
Bitte beachten Sie: Das Escaping-Verhalten für " hat sich mit der Konfiguration über die MOXIS Admin UI geändert. Das Escapen mit \ " ist nicht mehr notwendig. Letzteres ist nur relevant, wenn ein benutzerdefiniertes *DateTime-Format angegeben wird. 

1.1.6.1. Weiterführende Erläuterungen und Begriffsklärungen zu den Template-Variablen in Dateinamensvorlagen

Die einzelnen Variablen sprechen jeweils ein anderes Feld an. In diesem Kapitel finden Sie weitere Erläuterungen zu den Gängigsten. 

$ {processInstanceId} = Auftragsnummer 

$ {processLaunchParameterId] = Prozess-ID

$ {processParameterId} = für Enduser:innen "unsichtbare", lediglich für interne Prozesse relevante ID 

$ {jobOwner} = Vollständiger Name der Auftraggeber:innen 

$ {fileNameWithExtension} = Dokumentenname mit der Dateiendung (z.B. .pdf)

$ {fileName} = Dokumentenname alleine (z. B. "testdatei")

$ {category} = Kategorie 

1.1.7. Datei am Sambashare ablegen Hook

Der Export Hook für einen Fileshare (SAMBA) hat im Wesentlichen dieselben Funktionen wie bei der lokalen Ablage, nur dass zusätzlich noch der Server konfiguriert werden kann, auf dem abgelegt werden soll (siehe Abbildung 14).

XiTipp 
Bitte beachten Sie: Sambashare kann nur bei On Premises Instanzen von MOXIS installiert werden. 

Ein Klick auf den [Edit]-Button öffnet ein Pop-up, in dem weitere Konfigurationen vorgenommen werden können (siehe Abbildung 15).

• Dokumente: Legen Sie den Folder- und den Dateinamen hier fest, unter welchem die unterschriebenen Dokumente abgelegt werden sollen.

• Dokumenten-Regex: Durch eine Regex lässt sich der Hook auf Dokumente einschränken, welche dem angegebenen Namensmuster folgen.

• Anlagen: Legen Sie den Folder- und den Dateinamen hier fest, unter welchem die Anlagen/Beilagen abgelegt werden sollen.

• Anlagen-Regex: Durch eine Regex lässt sich der Hook auf Anlagen/Beilagen einschränken, welche dem angegebenen Namensmuster folgen.

• Protokoll-Pfad: Legen Sie den Pfad hier fest, unter welchem das erstellte Auftragsprotokoll abgelegt werden soll. Definieren Sie zudem die Sprache, in welcher es erstellt und abgelegt werden soll.

• Job Status-Pfad: Geben Sie hier den Pfad an, unter welchem eine JSON-Datei mit dem Auftragsstatus abgelegt werden soll.

• Job Status: Die Nutzer-Identifikationsart gibt an, wie die Benutzerdaten im generierten JSON gespeichert werden sollen: 

• UPN = Login Name oder User Principal Name bei Anbindung an AD, 

• ID= fortlaufende eindeutige Identifikationsnummer oder 

• Mailadresse in MOXIS.

• Bitte beachten Sie: Das JSON File entspricht der Spezifikation des Layer 2 Get job state Aufruf.

• Intervall für erneuten Versuch (s,m,h,d): Hier kann definiert werden, nach welchen jeweiligen Zeitabständen ein erneuter Versuch für die Ablage gestartet werden soll. Z. B. würde 1m, 1h, 1d bedeuten, dass MOXIS die Ablage zuerst nach einer Minute, dann nach einer Stunde und dann nach einem Tag nochmals probiert, bevor der Auftrag unter Nachverarbeitung wiederholen erscheint. Dort kann die Nachverarbeitung manuell gestartet werden. 

1.1.8. Datei an Output Service senden Hook 

Dieser Hook basiert auf dem File Storage Hook. Dokumente, Anhänge und Protokolle können an den OutputService gesendet werden. Der OutputService sendet Dateien an die vorkonfigurierbare Routen (z. B. SFTP-Server). Diese Routen werden in einem eigenen Service konfiguriert und in der Administrationsoberfläche können diese vom Benutzer ausgewählt werden. 

Das Output Service basiert auf Apache Camel. Dies ist ein Open Source Projekt, das unter anderem den Dateiaustausch unterstützt. Es wird individuell von Kunde zu Kunde konfiguriert und bietet so die Möglichkeit, kundenspezifische Systeme anzubinden, für die es in Camel eine Unterstützung gibt. 

1.8.1. Protokoll aktualisieren Hook

Nutzen Sie den Hook um beim Abschluss eines Auftrags einen PDF Report zu generieren, der alle Informationen zum Auftrag enthält (siehe Abbildung 16). Der Report umfasst Daten wie Auftraggeber:in, Dokumentennamen, Zeitpunkt des Setzens der Unterschrift, etc. 

Bitte beachten Sie: Das Service ist mittlerweile ein Auslaufmodell, da die Funktion in MOXIS integriert wurde. Sollte bei Ihrer Instanz eine Sonderkonfiguration dieses Services installiert sein, wenden Sie sich bitte an das XiTrust Support Team.