Modulautomation

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Die Automation ist ein wichtiger Bestandteil des eStudy-Frameworks. Sie kann bestimmte Aufgaben täglich oder wöchentlich ausführen, übernimmt Initialisierungen beim Neuerstellen eines Kurses oder Benutzer-Accounts und hält die Datenbank sauber, indem sie beim Löschen eines Kurses oder Benutzers die Modul-Tabellen bereinigt.

Verwendung der Automation für eigene Modulgruppen

Als erstes benötigen Sie eine Klasse, die Sie von der Klasse common/classes/class.modulautomation.inc.php ableiten. In dieser Klasse werden alle benötigten Methoden (siehe unten) überschrieben. Allgemein sollte diese Klasse etwa folgendermaßen aussehen:

require_once(PATH_TO_ROOT."common/classes/class.modulautomation.inc.php");

class MyModulAutomation extends ModulAutomation {

    function MyModulAutomation(){
        parent::ModulAutomation();
        $this->info = "<Modulgruppenname>";
        $this->necessaryDatabaseTable = "<Tabellenname>";
    }

    // Funktionen, die von der Automation aufgerufen werden (siehe unten)

}

Ersetzen Sie <Modulgruppenname> durch den Namen Ihrer Modulgruppe, dieser wird später in den Log-Dateien der Automation so ausgegeben. Statt <Tabellenname> können Sie den Namen einer Ihrer Datenbanktabellen angeben, die vorhanden sein muss, damit die Automation ausgeführt wird.

Weiterhin benötigen Sie eine Datei namens auto.inc.php in Ihrem Modulgruppenverzeichnis. Ein Template für diese Datei finden Sie im Ordner Vorlagen im CVS. In dieser Datei wird eine Instanz Ihrer Automationsklasse einem Container übergeben:

require_once(PATH_TO_ROOT."<Modulgruppen-Verzeichnis>/classes/class.mymodulautomation.inc.php");
$container->add(new MyModulAutomation());

Methoden der Automation

Folgende Methoden können in Ihrer Automationsklasse überschrieben werden. Die Funktionen müssen jeweils einen boolschen Wert zurückliefern.

  • dailyWork(): Diese Funktion wird täglich per Cronjob-Script aufgerufen (admin/daily.php).
  • weeklyWork(): Diese Funktion ist für wöchentliche Arbeiten vorgesehen, wird aber derzeit nicht verwendet.
  • newUser($userID): Wenn sich ein neuer Benutzer am Portal registriert hat.
  • changeUserGroup($userID, $oldGroup): Wenn ein Benutzer die Benutzergruppe wechselt.
  • updateUser($userID): Wenn Benutzerinformationen aktualisiert werden.
  • deleteUser($userID): Wenn ein Benutzer das Portal verlässt, sollten hier alle Datenbankeinträge gelöscht oder anonymisiert werden, die seine User-ID betreffen. Gelöscht werden sollten z.B. benutzerspezifische Einstellungen. Sollen die Beiträge (z.B. Foreneinträge) des Benutzers erhalten bleiben, sollten sie anonymisiert werden, indem die Benutzer-ID durch die ID 3 (Abgemeldeter Benutzer) ersetzt wird.
  • addUserToCourse($userID, $courseID): Wenn ein Benutzer zu einem Kurs hinzugefügt wird.
  • deleteUserFromCourse($userID, $courseID): Wenn ein Benutzer einen Kurs wieder verlässt.
  • newCourse($courseID): Wenn ein neuer Kurs angelegt wird.
  • updateCourse($courseID): Wenn Kurs-Informationen aktualisiert werden.
  • deleteCourse($courseID): Wenn ein Kurs gelöscht wird.
  • addAssistentToCourse($userID, $courseID): Wenn einem Kurs ein Tutor hinzugefügt wird.
  • deleteAssistentFromCourse($userID, $courseID): Wenn einem Tutor seine Tutorenrechte wieder entzogen werden.

Fehlermeldungen und Ausgaben in Logfiles

Ihre Automation sollte keine Ausgaben an den Browser senden. Stattdessen werden für jeden Aufruf der Automation Log-Dateien angelegt (eine Datei pro Tag). Sie sollten in Ihren Automationsmethoden ebenfalls hilfreiche Informationen in der Log-Datei speichern.

Dazu stehen folgende Methoden zur Verfügung:

  • error($string): Fügt eine Fehlermeldung einem Array hinzu, das in die Log-Datei ausgegeben wird, wenn die Automations-Methode false zurückgeliefert hat.
  • writeToLogFile($message, $indent = " "): Gibt eine Erfolgsmeldung direkt in die Log-Datei aus. Optional kann eine Einrückung angegeben werden.

Als Beispiel von sinnvollen Ausgaben in Log-Dateien sei hier eine Methode aus der Automation des News-Moduls aufgeführt:

function deleteUserFromCourse($userID, $courseID) {
    global $db, $EZSQL_ERROR;
    $errorCount = count($EZSQL_ERROR);
    $db->query("DELETE FROM news_preferences WHERE courseID='$courseID' AND userID='$userID'");
    if (count($EZSQL_ERROR) > $errorCount) {
        $this->error("Fehler beim Löschen der News-Einstellungen:\n".print_r($EZSQL_ERROR[$errorCount], true));
    } else {
        $this->writeToLogfile($db->rows_affected." News-Einstellung(en) gelöscht.");
    }
    if (!empty($this->errorString)) return false;
    return true;
}

Die Automation selber aufrufen

In einigen Fällen kann es sinnvoll sein, selber die Automation aufzurufen. Hier gelten zwei Regeln:

  1. Wenn Sie Daten ändern oder neu erzeugen, tun Sie das, bevor Sie die Automation aufrufen. Also: Erst ändern/erzeugen, dann aufrufen.
  2. Wenn Sie Daten löschen, tun Sie dass, nachdem Sie die Automation aufgerufen haben. Also: Erst aufrufen, dann löschen.

Beispiel: Neuer Benutzer registriert sich am Portal

/**zum Ausführen automatischer Funktionen*/
require_once(PATH_TO_ROOT."common/classes/class.automation.inc.php");

//neues Objekt erstellen und Standard-Logfile benutzen
$auto = new Automation("");
$auto->newUser($id);