Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- de:create:functions:mailschedule [01.07.2019 23:28] – admin
+++ de:create:functions:mailschedule [05.09.2025 18:09] (aktuell) – admin
@@ Zeile 9: / Zeile 9: @@
   * //PersonID//\\ Die Personenkennung des Adressaten, der die E-Mail erhalten soll. Falls das Interview durch eine Serienmail-Einladung begonnen wurde, können Sie ''false'' eintragen, die passende Kennung wird dann automatisch ermittelt.
   * //Serienmail//\\ (Numerische) Kennung der Serienmail, die an den Teilnehmer verschickt werden soll.
-  * //Zeitpunkt//\\ Die Verzögerung bis zum Versand (in Sekunden, maximal 153900000) __oder__ ein Unix-Zeitstempel, der den Zeitpunkt für den nächsten Versand definiert.
+  * //Zeitpunkt//\\
+    * Die Verzögerung bis zum Versand (in Sekunden, maximal 315576000 enstprechend 10 Jahre).
+    * Ein Unix-Zeitstempel, der den Zeitpunkt für den nächsten Versand definiert.
+    * Eine Zeitangabe als String, wie sie die Funktion ''strototime()'' akzeptiert, vgl. [[https://www.php.net/manual/de/datetime.formats.php|Unterstützte Datums- und Zeitformate (PHP)]].
   * //Einstellungen//\\ Optionale Einstellungen, als assoziatives Array angegeben mit folgenden Schlüsseln:
-    * '''status'''\\ Erinnerungs-/Folgemails nur verschicken, wenn der Link in der usprünglichen Serienmail ...
+    * ''%%'status'%%''\\ Erinnerungs-/Folgemails nur verschicken, wenn der Link in der usprünglichen Serienmail ...
-      * '''finished''' -- ...geöffnet und der Fragebogen bis zum Ende ausgefüllt wurde
+      * ''%%'finished'%%'' -- ...geöffnet und der Fragebogen bis zum Ende ausgefüllt wurde
-      * '''incomplete''' -- ...nicht geöffnet oder nicht bis zum Ende ausgefüllt wurde
+      * ''%%'incomplete'%%'' -- ...nicht geöffnet __oder__ nicht bis zum Ende ausgefüllt wurde
-      * '''no-response''' -- ...nicht geöffnet wurde
+      * ''%%'no-response'%%'' -- ...nicht geöffnet wurde
-    * '''expire'''\\ Gültigkeit des persönlichen Teilnahme-Links beschränken, es gilt dasselbe Format wie für den //Zeitpunkt//
+    * ''%%'expire'%%''\\ Gültigkeit des persönlichen Teilnahme-Links beschränken, es gilt dasselbe Format wie für den //Zeitpunkt//
-    * '''to.email'''\\ E-Mail nicht an die im Adresseintrag hinterlegte E-Mail-Adresse, sondern an die hier angegeben E-Mail-Adresse versenden. Mit dieser Funktion lässt sich ein Hinweis an den Projektleiter realisieren, wenn ein Teilnehmer einen (Folge-)Fragebogen nicht innerhalb einer definierten Zeit bearbeitet.
+    * ''%%'to.email'%%''\\ E-Mail nicht an die im Adresseintrag hinterlegte E-Mail-Adresse, sondern an die hier angegeben E-Mail-Adresse versenden. Mit dieser Funktion lässt sich ein Hinweis an den Projektleiter realisieren, wenn ein Teilnehmer einen (Folge-)Fragebogen nicht innerhalb einer definierten Zeit bearbeitet.
-    * '''to.mobile'''\\ SMS nicht an die (eventuell) im Adresseintrag hinterlegte Rufnummer, sondern an die hier angegeben Rufnummer versenden. Die Rufnummer muss mit Ländervorwahl angegeben werden.
+    * ''%%'to.mobile'%%''\\ SMS nicht an die (eventuell) im Adresseintrag hinterlegte Rufnummer, sondern an die hier angegeben Rufnummer versenden. Die Rufnummer muss mit Ländervorwahl angegeben werden.
+    * ''%%'reply.to'%%''\\ E-Mail-Adresse, die in der E-Mail für Antworten angegeben werden soll. Diese Einstellung ist nur wirksam, wenn das Benutzerkonto die Berechtigung hat, einen individuellen Absender festzulegen, z.B. wenn der [[https://www.soscisurvey.de/help/doku.php/de:survey:mailing-spf#smtp-server_verwenden|E-Mail-Versand via SMTP]] konfiguriert ist.
+    * ''%%'catch.up'%%''\\ Wenn für diesen Schlüssel ein numerischer Wert (Zeit in Sekunden) angegeben wird, erlaubt die Funktion ''mailSchedule()'' auch vergangene Zeitpunkte und holt den Versand in solch einem Fall umgehend nach. Andernfalls wird für den vergangenen Zeitpunkt keine E-Mail verschickt. Beispiel: Die Angabe ''604800'' (7×24×3600) würde eine E-Mail auch dann noch versenden, wenn der Versandzeitpunkt bis zu 7 Tage in der Vergangenheit liegt.
+    * '''%custom1%''' bis '''%custom5%'''\\ Wenn Inhalte für benutzerdefinierte Felder im ''mailSchedule()''-Befehl angegeben werden, dann werden in der Serienmail diese Inhalte anstatt der Angaben im Adresseintrag verwendet.
 **Hinweis:** Eine Serienmail wird (im Gegensatz zu ''mailResume()'') nur einmal pro Empfänger zugestellt, auch wenn die Funktion mit derselben Serienmail mehrfach aufgerufen wird. Der Versand unterschiedlicher Serienmails ist möglich -- z.B. eine Einladung zur zweiten Befragungswelle in 14 Tagen und eine weitere Einladung zur dritten Welle in 1 Monat.
-**Tipp:** Im Internet gibt es zahlreiche Websites, die ein Datum in einen Unix-Zeitstempel umrechnen können, z.B. [[http://www.unixtime.de/|unixtime.de]]. Auch die [[http://www.php.net/manual/de/ref.datetime.php|Datums- und Zeit-Funktionen]] von PHP (insbesondere ''[[http://php.net/manual/de/function.mktime.php|mktime()]]'' und ''[[http://www.php.net/manual/de/function.strtotime.php|strtotime()]]'') sind dafür hervorragend geeignet.
-===== Beispiel =====
+===== Einladung zur Folge-Befragung =====
 Ein Teilnehmer wurde per Serienmail zum Fragebogen eingeladen. 14 Tage, nachdem er auf den Link geklickt und damit den Fragebogen aufgerufen hat, soll er eine Einladung zum zweiten Fragebogen erhalten (Serienmail Nr. 2).
 <code php>
-mailSchedule(false, 2, strtotime('+14 days'));
+mailSchedule(false, 2, '+14 days');
 </code>
-Anstatt die Funktion ''strtotime()'' zu bemühen, kann das Zeitinterval auch in Sekunden spezifiziert werden: 14 Tage = 336 Stunden = 1209600 Sekunden.
+Ein Zeitinterval kann auch in Sekunden spezifiziert werden: 14 Tage = 336 Stunden = 1209600 Sekunden.
 <code php>
@@ Zeile 40: / Zeile 46: @@
 ===== Erinnerungsmails =====
-Der Teilnehmer wird mit Serienmail 1 zum ersten Fragebogen (Welle 1) eingeladen -- die Einladungen erfolgen gestaffelt, sodass a-priori nicht bekannt ist, wann der Teilnehmer den Fragebogen ausfüllt. Einen Monat nach dem Ausfüllen des ersten Fragebogen solle der Teilnehmer eine Einladung zur zweiten Erhebungswelle nach einem Monat bekommen (Serienmail 2). Falls er nicht teilnimmt, soll nach einer Woche noch ein Reminder (Serienmail 3) verschickt werden.
+Der Teilnehmer wird mit Serienmail 1 zum ersten Fragebogen (Welle 1) eingeladen -- die Einladungen erfolgen gestaffelt, sodass a-priori nicht bekannt ist, wann der Teilnehmer den Fragebogen ausfüllt. Einen Monat nach dem Ausfüllen des ersten Fragebogen soll der Teilnehmer eine Einladung zur zweiten Erhebungswelle bekommen (Serienmail 2). Falls er nicht teilnimmt, soll nach einer Woche noch ein Reminder (Serienmail 3) verschickt werden.
 In Serienmail 3 ist eingestellt, dass es sich um eine Erinnerungs-/Folgemail für Serienmail 2 handelt.
@@ Zeile 47: / Zeile 53: @@
 <code php>
-mailSchedule(false, 2, strtotime('+1 month'));
+mailSchedule(false, 2, '+1 month');
-mailSchedule(false, 3, strtotime('+1 month +1 week'), array(
+mailSchedule(false, 3, '+1 month +1 week', [
   'status' => 'no-response'
-));
+]);
 </code>
+===== Benutzerdefinierte Felder =====
+Der folgende Befehl versendet die Serienmail mit der ID 2 am nächsten Montag um 8 Uhr an die Person, die den Fragebogen gerade ausfüllt. Anstelle des Platzhalters ''%custom1%'' wird in der Serienmail das Datum angezeigt, wann ''mailSchedule()'' aufgerufen wurde.
+<code php>
+mailSchedule(false, 2, 'next Monday 08:00:00', [
+  '%custom1%' => date('d.m.Y')
+]);
+</code>