Ereignissteuerung
Um kundenindividuelle Abläufe optimal unterstützen zu können, kann diaLIMS auf das Ändern jedes Feldes eines Datensatzes reagieren, indem bestimmte Aktionen ausgelöst werden. Dieser Zusammenhang kann kundenindividuell konfiguriert werden. Ein häufiger Anwendungsfall, der so abgedeckt werden kann, ist, dass durch das Eintragen/Ändern eines Datensatzes eine E-Mail-Benachrichtigung an einen bestimmten Mitarbeiter verschickt wird.
Typische Anwendungsfälle wären:
-
Ereignis:
Eine Probe wird fertiggestellt
-
Aktion:
Der Auftraggeber der zu untersuchenden Probe wird per E-Mail darüber benachrichtigt
-
Ereignis:
Bei einer Probe wird ein Ergebniswert eingetragen, der zu einer Grenzwertverletzung führt
-
Aktion:
diaLIMS fügt automatisch 2 weitere Analysen hinzu, die deswegen durchgeführt werden sollen
Ereignissteuerung mit externen (Groovy)-Script-Dateien
Die einfachste Weise, eine Ereignissteuerung zu implementieren ist, im Skript-Verzeichnis bsh/scripts des Programm-Servers eine Datei zu erzeugen, die dem Namen des Controllers entsprechen muss, der auf dieses Ereignis reagieren soll. Der Inhalt der Datei muss die Groovy-Definition der Methode fieldModified sein. Durch die bloße Anwesenheit dieser Datei wird sie zur Laufzeit interpretiert. Der Rumpf der Datei sieht so aus:
fieldModified = (field, object, oldValue, newValue) -> {
if (field.equals("<attributname>")) {
// tu irgendwas
}
}
Konventionen für die Skriptdatei
-
Dateiname:
- <vollständiger Name des business controllers>.groovy
- Beispiel: com.dialog.dialims.business.AngebotController.groovy
-
Ordner:
/bsh/scripts
-
Inhalt:
Methodendefinition für Methode
fieldModified
Durch die Ableitungshierarchie im Klassenmodell kann die Methode auch 'ganz oben' in der Oberklassecom.dialog.dialims.business.BusinessController implementiert werden und gilt so für alle Ableitungen. Es wird die komplette Ableitungshierarchie von unten (also dem aktuellen Objekt) nach oben durchgegangen und versucht ein entsprechendes Script zu finden.
Tip:
Für Entwickler ist es praktisch, statt eines Skriptes den entsprechenden Controller um die Methode fieldModified zu erweitern. So hat er die volle Unterstützung der Entwicklungsumgebung (Debug, Code Completion).
Der häufigste Fall für den Einsatz der Ereignissteuerung ist die E-Mail-Benachrichtigung. Überträgt ein Mitarbeiter einem anderen die Verantwortung für einen Datensatz, wird von diaLIMS eine automatisch generierte E-Mail erzeugt und versendet.
Tip:
Beispielscript: Benachrichtigung des Laborleiters bei Auftreten einer Grenzwertverletzung
Name der Skript-Datei: com.dialog.dialims.business.ErgebnisWertController.groovy
/*
* Beispielskript für E-Mail-Benachrichtigung für den Fall, dass
* eine Grenzwertverletzung aufgetreten ist.
*
* 29.12.2006 db: Erstellung
*/
fieldModified = (field, object, oldValue, newValue) -> {
if (field.equals("grenzwert")) {
// dann wurde der Grenzwert geändert
if ("GRENZ".equals(newValue)) {
// dann ist eine Grenzwertverletzung aufgetreten
dm = DialogMailer();
ew = (ErgebnisWert) object;
zpae = ew.getZuordnungProbeAnalyseErgebnis();
msg = "Grenzwertverletzung aufgetreten!<br>" +
"<br><b>Probe:</b> " + HTMLUtil.createDialimsLink(zpae.getProbe(), true) +
"<br><b>Analyse:</b> " + zpae.getAnalyse() +
"<br><b>Ergebnis:</b> " + zpae.getErgebnis() +
"<br><b>Ergebniswert:</b> " + ew +
"<br><b>Grenzwerte:</b> " +
com.dialog.dialims.printing.BerichtsController.getInstance().getGrenzwerteToString(zpae);
dm.sendMessage(msg, "Grenzwertverletzung Probe " + zpae.getProbe(), "system@dialims.de", "laborleiter@firma.com");
}
}
}
Die E-Mail sieht dann etwa so aus:
Tip:
Grenzwertverletzung aufgetreten!
Probe: P2025000002
Analyse: Test-Methode
Ergebnis: Test-Ergebnis
Ergebniswert: 1,0
Grenzwerte: 5,0000~25,2360
Sobald sich der Verantwortliche für einen Datensatz ändert, kann diaLIMS eine automatisch erzeugte E-Mail versenden. Das geschieht beim Speichern des Datensatzes. Es kann dann ein Dialog erscheinen, in dem ein kurzer Text für die E-Mail mitgegeben werden kann. Damit diese Nachricht aus Gründen der Nachvollziehbarkeit in dem persönlichen E-Mail-Programm des Absenders vorhanden ist, wird der Versender selbst als BCC in der E-Mail genannt. Der Empfänger erhält eine E-Mail mit einem diaLIMS-Link auf den Datensatz.
Aktivierung
Die Aktivierung der E-Mail-Benachrichtigung erfolgt über das Einstellen eines Skriptes im Ordner <diaLIMS-Programmverzeichnis>/bsh/scripts und muss den voll qualifizierten Namen eines BusinessControllers haben. Dabei wird die Ableitungshierarchie rückwärts durchlaufen. So kann die allgemeine Benachrichtigung in der Klasse BusinessController und eine spezielle vielleicht für den AngebotController implementiert werden.
Tip:
Beispielskript für E-Mail-Benachrichtigung für den Fall, dass das Feld "Betreuer" geändert wurde
Name der Skript-Datei: com.dialog.dialims.business.BusinessController.groovy
/*
* Beispielskript für E-Mail-Benachrichtigung für den Fall, dass
* das Feld "Betreuer" geändert wurde.
*
* 25.08.2006 db: Erstellung
*/
fieldModified = (field, object, oldValue, newValue) -> {
if (field.equals("betreuer")) {
// herausfinden, ob der Datensatz eine Methode "getBetreuer" hat
c = object.getClass();
m = ReflectionUtil.getGetter(c, "betreuer", false);
betreuer = m.invoke(object);
prVon = BenutzerController.getInstance().getProjektRessource(null);
prAn = ProjektResourceController.getInstance().findByKurzbezeichnung(betreuer);
// nur senden, wenn man es nicht selber ist
if (prVon != null && prAn != null && !prVon.equals(prAn)) {
msg = "Bitte zusätzlichen Benachrichtigungstext für " + prAn +
" eingeben\n ('Abbrechen' sendet die Benachrichtigung ohne Zusatztext)";
s = ObserverInputOutputController.get()
.getInput(BusinessController.class, "fieldModified", msg, "");
dm = new DialogMailer();
dm.sendAssigneeChangeNotificationEmail(prVon, prAn, object, s);
}
}
}
Funktionsweise
Für die E-Mail-Benachrichtigung wird eine vom diaLIMS erstellte E-Mail vom diaLIMS-Client aus gesendet. Dafür werden benutzerabhängig SMTP-Zugangsdaten benötigt.
Anwendungsbeispiel
Der Anwender Otto Müller, dem die Ressource OM zugeordnet ist, erstellt eine Aktivität für Heiner Schmidt, dem die Ressource HS zugeordnet ist. Er trägt in das Feld Betreuer "HS" ein. Beim Speichern sendet diaLIMS eine E-Mail an die E-Mail-Adresse, die beim Heiner Schmidt zugeordeten Ansprechpartner hinterlegt ist.
Für die Benachrichtigung steht die Klasse DialogMailer zur Verfügung. Durch Aufruf der Methode sendAssigneeChangeNotificationEmail wird die E-Mail erstellt und versendet. Die Aufbereitung des Textes wird über die dialims.properties-Datei gesteuert. Die beiden Schlüssel dafür lauten:
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationAssigneeSubject
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationAssigneeBody
Für den Text werden 5 Variablen von diaLIMS ausgefüllt:
-
0
= Neuer Betreuer (Empfänger - Kurzbezeichnung der Ressource)
-
1
= Alter Betreuer (Absender - Kurzbezeichnung der Ressource)
-
2
= Art des Datensatzes (z.B. "Aktivität")
-
3
= diaLIMS-Link zu dem Datensatz. Durch Klick auf diesen Link wird der Datensatz im diaLIMS direkt aufgerufen.
-
4
= Zusatztext (ggf. über Eingabe des Alten Betreuers)
Es kann dabei eine kundenindividuelle Properties-Datei über die Locale-Variante angesteuert werden. Dafür wird diaLIMS mit den Übergabeparametern <Sprache> <Land> <Variante> gestartet. Beispiel "de DE XX". Die zugehörige kundenindividuelle Properties-Datei lautet dann dialims_de_DE_XX.properties.
Tip:
Beispiel für Properties-Datei zum Betreuerwechsel
cBusinessController.EmailNotificationAssigneeSubject
= diaLIMS-Systemnachricht: Betreuerwechsel {2} {4}
BusinessController.EmailNotificationAssigneeBody
= <FONT FACE="Tahoma, sans-serif" SIZE=2>Die Zuständigkeit für {2} {3} wurde von {1} auf {0} geändert.<br>{4}</FONT>
Eine so erzeugte E-Mail sieht dann in etwa so aus:
Tip:
diaLIMS-Systemnachricht: Zuständigkeitswechsel Aktivität Zusatztext
Die Zuständigkeit für Aktivität 2025000009 wurde von OM auf HS geändert. Zusatztext
E-Mail-Benachrichtigung mittels Windows-Taskplaner
Aufgabe
Einmal täglich sollen Proben, die ausserhalb eines vorgegebenen Registrierungsdatums liegen, auf fehlende Einträge bei den Analysen überprüft werden. Der Registrierer der Proben erhält dann eine Liste mit den fehlenden Ergebniswerten.
Modul Abfragen
Es wird eine Abfrage angelegt, die die folgenden 4 Spalten enthalten muss:
- LIMS-Klasse (Kurzname)
- OID des Objektes
- Datum
- Beschreibung
Im Programmordner Abfragen/_System gibt es eine Beispielabfrage Erinnerung. Diese ist ins diaLIMS zu importieren.
-
diaLIMS-Klasse:
Probe
-
OID des Objekts:
OID der Probe
-
Datum:
Registrierdatum
-
Beschreibung:
(RTRIM(PROBE)||': fehlende Ergebniswerte von Labor '||coalesce(RTRIM(PRUEFMITTEL), 'n.n.')||' für Analyseergebnis '||RTRIM(ANALYSE)||'/'||RTRIM(ERGEBNIS))
Nach der Abfrage könnte der Text in der Beschreibung z.B. so aussehen:
-
P2008001289:
fehlende Ergebniswerte von Labor n.n. für Analyseergebnis ABDRS/ABDRS
Alle diese Angaben werden in ein HTML-Dokument mit einer Tabelle geschrieben, die als E-Mail verschickt wird. Die im SQL-Statement enthaltene Variable <benutzer> wird durch den Benutzer ersetzt, der in der Batch-Datei, die vom Taskplaner ausgeführt wird, gesetzt ist.
Einstellungen in der dialims.properties
Für die Erzeugung des HTML-Codes der Email sind folgende Keys in der dialims.properties wichtig:
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationAssigneeSubject
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationAssigneeBody
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationTasksSubject
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationTasksBodyHeader
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationTasksBodyTableRow
- com.dialog.dialims.business.controller.BusinessController.EmailNotificationTasksBodyFooter
Der HMTL-Code der den Keys zugewiesen wird, kann verändert werden. Die Variablen dürfen nicht an anderer Stelle gesetzt werden.
Inhalt der Variablen
-
0
= E-Mail-Adresse des Benutzers bzw. des Ansprechpartners des Benutzers (Benutzer hat Vorrang)
-
1
-
2
= Art des Objektes (z.B. "Probe")
-
3
= .
-
4
= Name des Objektes (z.B. Probe "P2008001289")
-
5
= Beschreibung
Modul Benutzer
Auf der ersten Seite muss eine E-Mail Adresse eingetragen werden, entweder beim Benutzer selbst oder beim zugeordneten Ansprechpartner. Sind bei beiden Einträge gesetzt, hat die E-Mail des Benutzers Vorrang.
Einstellungen in der mail.properties
Die benutzerabhängigen SMTP-Zugangsdaten werden vor dem ersten Versand interaktiv abgefragt und in einer Datei <diaLIMS-Programmverzeichnis>/Einstellungen/<Benutzername>/mail.properties mit dem verschlüsselten Kennwort abgelegt. Nach Eingabe der Zugangsdaten muss diaLIMS beendet und neu gestartet werden.
Tip:
Mail.properties
- #This is a diaLIMS-Properties file.
- #Thu Dec 28 13:24:44 CET 2006
- mail.smtp.host=smtp.firma.com
- mail.smtp.user=user.name
- mail.smtp.encryptedPassword=57F3AA3530355273494D3D
- From=user.name@firma.com
Batch-Script
Batch-Skript erstellen und mit dem Programm "geplante Tasks" ausführen lassen.
Ereignissteuerung über Optioneneinträge
Eine weitere Möglichkeit für das Auslösen von ereignisgesteuerten Aktionen besteht im Zuweisen von Skripten zu bestimmten Feldern. Dafür muss der Wert System\ooEventProcessing im Optionen-Modul auf 0 gesetzt werden.
Das Zuweisen von Skripten zu den Feldern erfolgt im Optionen-Modul, unter dem Punkt Allgemein\Datenbank\Protokollierung (Audit Trail). Dort können alle in den Eingabemasken des diaLIMS verwendeten Felder in einer Tabelle dargestellt werden.
Nach Einblenden der Spalte Skript können Sie direkt in den gewünschten Feldern oder über den erweiterten Text-Editor die auszuführenden Skripte eintragen.
CAUTION:
Skripte an einem Knotenpunkt gelten auch für Änderungen an den diesem Knoten untergeordneten Feldern, jedoch nicht für untergeordnete Knoten und deren Felder. Gibt es Einträge für Knoten und untergeordnete Felder, werden beide ausgeführt.
Audit-Trail muss für das Feld nicht aktiviert sein, damit die Skripte wirken.
Die Skripte müssen in diaLIMS.script-gültiger Syntax angelegt sein, das Übernehmen aus Beanshell-Skripten ist ebenfalls möglich.
Beim Eintreten der im Skript hinterlegten Bedingung wird dann die gewünschte Aktion ausgeführt.