Skip to content

18.2 ScriptHelper Funktionen

Nachfolgend finden Sie eine Beschreibung aller verfügbaren ScriptHelper-Funktionen.

18.2.1 E-Mail-Adressänderung durch Empfänger

Initial ausgelöst werden E-Mail-Adressänderungen durch den Aufruf der folgenden Funktion:

$ScriptHelper.updateRecipientWithEmailChangeConfirmation(recipient, mailingID, profileFieldForConfirmationCode)

Es muss dann eine aktionsbasierte E-Mail an die neue Empfängeradresse gesendet werden, die den Bestätigungscode aus dem angegebenen Profilfeld in einem Link als Parameter verwendet.

In der Datenbanktabelle „pending_email_change_tbl“ werden E-Mail-Adressänderungen der Empfänger zwischengespeichert, solange diese noch nicht bestätigt sind (entspricht Double Opt-in, um Missbrauch der Änderungsfunktion zu vermeiden).

Durch folgende Funktion wird dann die Bestätigung gespeichert:

$ScriptHelper.confirmEmailAddressChange(uidString, confirmationCode)

18.2.2 Empfängerdaten verändern

Wenn die Daten des Empfängers (anhand der enthaltenen CustomerID) noch nicht in der Datenbank vorliegen, wird ein neuer Empfänger angelegt, ansonsten der bestehende Empfänger (anhand der CustomerID) aktualisiert.

#set($recipient = new RecipientImpl())
$recipient.setCustParameters("email", "neue.email@example.com")
$ScriptHelper.storeRecipient($recipient)

18.2.3 Erzeugen einer AgnUID für einen bestehenden Empfänger

Diese Methode dient der Erzeugung eines agnUID String, welcher dann in Formular-Links verwendet werden kann, um die Empfängerdaten (CustomerID) durch Verschlüsselung zu sichern.

#set($agnUID=$ScriptHelper.createUidForCustomer($companyId, $customerKeyColumnNameString, $customerKeyColumnValueString)

Beispiel:

#set($agnUID=$ScriptHelper.createUidForCustomer(123, "email", "tester@agnitas.de")

18.2.4 decodeUID (String)

Diese Funktionen decodieren die verschlüsselten Inhalte einer agnUID.

Folgende Werte (Namen sind case-sensitive) sind in der zurückgegebenen Map enthalten:

  • companyID: CompanyID des Mandanten

  • mailingID: MailingID des Mailings in welcher der Link enthalten war

  • urlID: LinkID des Links die geklickt wurde

  • customerID: CustomerID des Empfängers

  • prefix: Prefix

#set($mapVariable=$ScriptHelper.decodeUID("<agnUID>"))

18.2.5 URL-Encodieren von SessionIDs und anderen Werten

Um ein URL Encoding eines String Wertes zu erhalten (z.B. „abc&def“ → „abc%26def“):

#set($encoded=$ScriptHelper.encodeSessionID($zuEncodierenderWert))

18.2.6 Ermitteln des letzten versendeten Newsletters

Anhand der CustomerID, der CompanyID und der MailinglistID kann einem Empfänger nach der Anmeldung der letzte Newsletter zugeschickt werden.

Dabei werden die verwendeten Zielgruppen der Mailings mit dem Empfängerprofil abgeglichen.

#set($mail=$MailingDao.getMailing($ScriptHelper.findLastNewsletter($customerID, $companyID, $mailinglistID), $companyID))
#if($mail)
$ScriptHelper.sendEventMailing($mail, $customerID.intValue(), 
0, "1", null)
#end

18.2.7 Abfrage des Namens eines Mailings

Dieser Aufruf liefert einen String oder NULL zurück. Es können nur Mailings des aktuellen Mandanten abgefragt werden.

#set($mailingName=$ScriptHelper.getMailingName(mailingID))

18.2.8 Abfrage des Betreffs eines Mailings

Dieser Aufruf liefert einen String oder NULL zurück. Es können nur Mailings des aktuellen Mandanten abgefragt werden.

#set($mailingSubject=$ScriptHelper.getMailingSubject(mailingID))

18.2.9 Abfrage des Versanddatums eines Mailings

Dieser Aufruf liefert ein Date-Objekt oder NULL zurück. Dieses kann dann für weitere Zwecke verwendet werden, z.B. um das Versanddatum zu formatieren und anzuzeigen.

#set($sendDate=$ScriptHelper.getMailingSendDate(companyID, mailingID))

18.2.10 Datum formatieren

Die Formatzeichen sind jene aus JAVA:

  • yyyy: Jahr 4-stellig

  • MM: Monat 2-stellig

  • dd: Tag 2-stellig

  • hh: 24-Stunden, 2-stellig

  • mm: Minuten 2-stellig

  • ss: Sekunden 2-stellig

Achtung: DD = Tag des Jahres

#set ($nowDate1 = $ScriptHelper.newDate())
#set ($nowFormatted1 = $ScriptHelper.formatDate($nowDate1, "yyyy-MM-dd", "de", "de")) ## Datum imFormat "YYYY-MM-DD"

#set ($nowDate2 = $ScriptHelper.newCalendar().getTime())
#set ($nowFormatted2 = $ScriptHelper.formatDate($nowDate2, "yyyy-MM-dd", "de", "de")) ## Datum imFormat "YYYY-MM-DD"

18.2.11 Aktuelles Datum nutzen

Folgender Ausdruck erzeugt das aktuelle Datum:

#set ($now = $ScriptHelper.newCalendar())

##1 = Year, 2 = Month, starting with 0, 5 = Day of Month
#set ($year4 = $now.get(1).toString())
#set ($month = $now.get(2) + 1)
#set ($month = $month.toString())
#set ($dayOfMonth = $now.get(5).toString())

## keep leading zeros
#if ($month.length() < 2)
   #set ($month = "0$month")
#end

## keep leading zeros
#if ($dayOfMonth.length() < 2)
   #set ($dayOfMonth = "0$dayOfMonth")
#end

#set ($nowFormatted = "$year4$month$dayOfMonth") ## Datum im Format "YYYYMMDD"

18.2.12 Zahlen formatieren

Um Zahlen aus unerwünschten Formaten (z.B. „4.5“) in gefällige, lesbare Formate (z.B. „4,50“) zu wandeln:

#set($format='###,##0.00')
#set($productPrice = $ScriptHelper.formatNumber("8.00", $format,"de")) ## Standard Dezimaltrenner ist "."
##oder:
#set($productPrice = $ScriptHelper.formatNumber('8.00', '.', '###,##0.00', 'de'))
##oder:
#set($productPrice = $ScriptHelper.formatNumber('8,00', ',', '###,##0.00', 'de'))## Dezimaltrenner Komma verwenden

18.2.13 Zahlen in String umwandeln

(Long-)Zahlenwerte werden manchmal im String Format benötigt:

#set($zahlAlsString = $ScriptHelper.toString($zahl)

18.2.14 String in Zahl umwandeln

String Zahlenwerte werden manchmal wieder als echte Zahl benötigt

#set($zahl = $ScriptHelper.parseInt($zahlAlsString)

18.2.15 int-Zahl in Integer-Zahl umwandeln

Sehr selten werden simple Zahlenwerte (int) als Integer Zahl (JavaKlasse Integer) benötigt

#set($zahlAlsInteger = $ScriptHelper.newInteger($zahlAlsInt)

18.2.16 Abfrage des letzten Mailings, das einem Empfänger zugesendet wurde

Dieser Aufruf liefert eine MailingID zurück. Diese kann dann für weitere Zwecke verwendet werden, z.B. um das Mailing nochmals zu senden oder die ID irgendwo zu loggen.

#set($lastSentMailingID=$ScriptHelper.getLastSentMailingID(companyID, customerID))

18.2.17 Erzeugen eines "doppelten Anführungsstrichs"

Da es schwierig ist, in Velocity Skripten das Zeichen „doppelter Anführungsstrich“ zu erzeugen, gibt es hierfür die Hilfsmethode getDoubleQuote().

#set($doubleQuote=$ScriptHelper.getDoubleQuote()
#set($textWithDoubleQuotes="${doubleQuote}Mein Text mit doppelten Anführungsstrichen$doubleQuote")

18.2.18 Liste der Zahlen von 1 bis x

Erstellen einer Liste Zahlen von 1 bis x als Stringwerte. Diese können dann als in einer foreach-Schleife durchlaufen werden.

#set($listeVon1Bis20 = $ScriptHelper.getForLoop(20))

18.2.19 Abfrage des letzten Mailings, das ein Mandant versendet hat

Dieser Aufruf liefert eine MailingID zurück.

Diese kann dann für weitere Zwecke verwendet werden, z.B. um das Mailing nochmals zu senden oder die ID irgendwo zu loggen.

#set($lastSentMailingID=$ScriptHelper.getLastSentWorldMailingIDByCompanyAndMailinglist(companyID, mailingListID))

18.2.20 Erzeugen eines Zeilenumbruchs

Da es schwierig ist in Velocity Skripten einen Zeilenumbruch zu erzeugen, gibt es hierfür die Hilfsmethode getNewline().

#set($linebreak=$ScriptHelper.getNewline()
#set($textWithLinebreak="Mein Text${linebreak}mit Zeilenumbruch")

18.2.21 Logausgabe in das Fehlerlog File auf dem Rdir Server

Zum Anzeigen des Fehlertextes wird folgender Ausdruck verwendet:

$ScriptHelper.println($fehlerText)

18.2.22 Restwert einer Division berechnen

Folgende Funktion liefert den Rest einer Division (Teilen). Also das Ergebnis von „a mod b“ oder „a % b“.

Beispiele:

„16 mod 5 = 1“

„10 mod 4 = 2“

#set($rest=$ScriptHelper.mod($a, $b))

18.2.23 (Veraltete) Map Funktionen

Die Funktionen newHashMap und newHashtable werden in Kürze entfernt und sollen nicht mehr verwendet werden.

Stattdessen ist zu verwenden:

#set($mapVariable={})

18.2.24 Auffüllen oder Begrenzen eines Textes

Mit folgenden Funktionen kann ein Text auf eine bestimmte Länge begrenzt werden oder im Fall, dass der Text zu kurz ist, dieser mit Leerzeichen auf die gewünschte Länge gebracht werden.

Beispiel:

#set($kurzerText="aBc")
#set($langerText="abcdefghi")

#set($linksGefuellterText=$ScriptHelper.padLOrTrim($kurzerText, 5))
#set($rechtsGefuellterText=$ScriptHelper.padROrTrim($langerText, 5))
#set($gekuerzterText=$ScriptHelper.padLOrTrim($langerText, 5))

$linksGefuellterText: "  aBc"
$rechtsGefuellterText: "aBc  "
$gekuerzterText: "abcde"

18.2.25 Verarbeiten eines Textes als Datum

Mit folgender Funktion kann ein Text als GregorianCalendar verwendet werden.

Als Zeichen im DatePattern sind alle Java-Datumsformat-Zeichen (dMyHms, siehe auch https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html) erlaubt.

#set($date=$ScriptHelper.parseDate($dateString, "dd.MM.yyyy"))
#set($dateTime=$ScriptHelper.parseDate($dateTimeString, "dd.MM.yyyy HH:mm:ss"))

18.2.26 Validieren eines Google reCaptcha Tokens

Mit folgender Funktion kann das Token Ergebnis eines reCaptcha Aufrufs validiert werden, bevor dann weitere Maßnahmen folgen (siehe auch https://developers.google.com/recaptcha/docs/verify)

ACHTUNG: Jedes reCaptcha Token kann nur ein einziges Mal geprüft werden.

Jede Folge-Prüfung (Browser Reload, doppelter Aufruf im Velocity-Skript etc.) führt zu einem Fehler.

Doku und Beispiel separat erhältlich bei Support.

#set($isValid=$ScriptHelper.validateReCaptcha($apiKey, $captchaResponseToken))
#if($isValid)
    ...
#end

18.2.27 XML Daten parsen und eventbasiertes Mailing versenden

Bei dieser Skriptaktion wird ein XML-Konstrukt geparsed und danach ein eventbasiertes Mailing an eine Mailingliste versendet.

Beispiel Code dazu:

##hier die mailinglist-id einsetzen
  #set($ml=6995)
  #set($messageList=$ScriptHelper.parseTransactionMailXml($requestParameters.xml))
  #if($messageList)
    $Customer.loadCustDBStructure()
    #foreach( $message in $messageList )
      #set($recipient=$message.recipient)
      $Customer.resetCustParameters()
      $Customer.setCustomerID(0)
      #set($customerID=$Customer.findByKeyColumn("KDNR", $recipient.get("KDNR").toLowerCase()))
      #if($customerID!=0)
        #set($bind=$Customer.loadAllListBindings())
        #if($bind)
          #set($mt=$bind.get($ml))
          #if($mt)
            #if($mt.get(0).getUserStatus()==1)
              #set($params=$ScriptHelper.newHashtable())
              $params.put("UMSATZ", $recipient.get("REVENUE"))
              #set($text="")
              #set($link="")
              #set($link1="")
              #set($content="")
              #set($loop=$ScriptHelper.getForLoop(99))
              #foreach($index in $loop)
                #set($line="")
                #set($link_part="")
                #set($link_part2="")
                #set($link_part3="")
                #if($recipient.get("BEZEICHNUNG$index"))
                  #set($art=$ScriptHelper.padROrTrim($recipient.get("BEZEICHNUNG$index"),50))
                  #set($line = "$art <br>$ScriptHelper.getNewline()")
                  #set($text="$line")
                  #set($art_no="")
                  #set($art_ma="")
                  #set($art_no=$recipient.get("ARTIKEL$index"))
                  #set($art_ma=$recipient.get("GROESSE$index"))
                  #set($link_part2="&size=$art_ma")
                  #set($link_part3="&format=baur_formatQ")
                  #set($link="$link_part$link_part2")
                  #set($link1="$link_part$link_part3")
                  #set($content="$content<table width='610' border='0' align='center' cellpadding='2' cellspacing='0' style='border: 1px solid;'><tr><td width='130' class='smalltext'>$art_no</td><td width='*' style='font-family:Arial,sans-serif; font-size:10.0pt; color:black;'>&nbsp;$text</td><td width='133'><a href='http://www.bewerten.de'>Bewerten</a></td></tr></table>")
                #end
              #end
              $params.put("UMFRAGE", $content)
              $Mailing.setMailingID(106715)
              #set($mail=$MailingDao.getMailing(106715, 468))
              #if($mail)
                 $ScriptHelper.sendEventMailing($mail, $customerID, 0, "1", $params)
              #end
            #end
          #end
        #end
      #end
    #end
    #set($scriptResult="1")
  #end

18.2.28 E-Mail-Versand (ohne existierendem EMM Mailing) innerhalb eines Skripts

Um eine einzelne E-Mail zu versenden, muss hierfür nicht zuvor ein Mailing angelegt werden. Allerdings wird dadurch auch keine Statistik erstellt.

Diese kann innerhalb einer Skriptaktion versendet werden an einen bestimmten Empfänger, der nicht als EMM-Empfänger angelegt werden muss und somit KEINE CustomerID und auch keine Statistik erhält.

Die Variable $mailtypeIntLegacy dient nur der Abwärtskompatibilität und hat keinerlei Auswirkungen, muss aber trotzdem noch angegeben werden.

Historisch verfügbare Methoden:

## Mit CC-Adresse
$ScriptHelper.sendEmail($from_address, $to_address, $cc_address, $subject, $body_text, $body_html, $mailtypeIntLegacy, $charset)
## oder ohne CC-Adresse
$ScriptHelper.sendEmail($from_address, $to_address, $subject, $body_text, $body_html, $mailtypeIntLegacy, $charset)

Zukünftig sollte nur noch folgende Methode verwendet werden:

$ScriptHelper.sendEmail($from_address, $to_address, $cc_address, $subject, $body_text, $body_html, $charset)

18.2.29 Aktionsbasierter (eventbased) Mailing-Versand innerhalb eines Skripts

Um ein einzelnes Event-basiertes Mailing zu versenden, muss dieses zuvor angelegt werden. MailingID (und CompanyID) muss bekannt sein.

Dann kann dieses innerhalb einer Skriptaktion an einen bestimmten Empfänger (CustomerID) versendet werden.

Die Variable „overwrite“ kann dabei eine Map von Werten enthalten, die die aktuellen Profilfelder des Empfängers nur für den Versand des E-Mails überschreibt.

Diese Werte werden aber nicht dauerhaft im Empfängerprofil gespeichert.

#set($mailing=$MailingDao.getMailing($mailingID, $companyID))
#if($mailing)
    #set($overwriteParams={})
    $overwriteParams.put("firstname", $recipient.get("firstname")) 
     ## Als Default den Vornamen des Empfängers nutzen
    $overwriteParams.put("firstname", $!requestParameters.firstname)
     ## Nur wenn ein anderer Vorname als Requestparameter
     übergeben wird, diesen benutzen


    ## Mit UserStatus als Liste von Integer Werten (ohne BCC)
    $ScriptHelper.sendEventMailing($mailing, $customerID, $delayMinutes, $userStatusList, $overwriteParams)
    ## oder mit UserStatus als einzelner Wert in einem String (ohne BCC)
    $ScriptHelper.sendEventMailing($mailing, $customerID, $delayMinutes, $userStatus, $overwriteParams)
    ## oder mit UserStatus als Liste von Integer Werten und mit BCC Adresse
    $ScriptHelper.sendEventMailing($mailing, $customerID, $delayMinutes, $bccEmails, $userStatusList, $overwriteParams)
    ## oder mit UserStatus als einzelner Wert in einem String und mit BCC Adresse
    $ScriptHelper.sendEventMailing($mailing, $customerID, $delayMinutes, $bccEmails, $userStatus, $overwriteParams)
#end

Folgende Empfängerstatus-Werte sind möglich:

  • 1 = Active

  • 2 = Bounce

  • 3 = AdminOut

  • 4 = UserOut

  • 5 = WaitForConfirm

  • 6 = Blocklisted

  • 7 = Suspend / Pending

18.2.30 SHA-512 Hash zu einem Text erzeugen

Manchmal benötigt man einen SHA-512 Hash für Texte, dieser kann wie folgt erzeugt werden:

Mit Default Encoding UTF-8:
#set($hashWert=$ScriptHelper.sha512($text))

Mit speziellem Encoding z.B. ISO-8859-1:
#set($hashWert=$ScriptHelper.sha512WithEncoding($text, "ISO-8859-1"))

18.2.31 Zeitmessung innerhalb einer Velocity Skriptaktion (Debugging)

Es können bis zu 10 Stoppuhrzeiten gestartet werden ($eindeutigeId von 0 bis 9)

Zum Starten einer Stoppuhr:

$ScriptHelper.startTimer($eindeutigeId)

Zum Auslesen der vergangenen Zeit in Millisekunden auf dieser Stoppuhr:

#set($vergangeneMillisekunden=$ScriptHelper.stopTimer($eindeutigeId))

18.2.32 Setzen einer neuen DatasourceID am Empfänger

Dies kann zweckmäßig sein, um einen Empfänger für Zielgruppen zu markieren oder eine Bearbeitung der Empfängerdaten durch ein Skript zu dokumentieren.

$ScriptHelper.updateDatasourceID($recipient)

Liegt dabei bereits eine bestehende DatasourceID größer als 0 vor, so wird die neue DatasourceID in das Profilfeld „latest_datasource_id“ geschrieben.

Achtung: Das Schreiben in das Profilfeld „latest_datasource_id“ kann durch den EMM-Konfigurationswert „DontWriteLatestDatasourceId“ (technisch: „system.DontWriteLatestDatasourceId“) verhindert werden.

In Parameterwerten für Links dürfen einige Zeichen nicht enthalten sein, z.B “=“.Diese können durch die Methode urlEncode ersetzt werden.

Beispiel:

#set($klartext = "Mein§=Text")
#set($encodiertertext = urlEncode($klartext))

Ergebnis: encodiertertext = "Mein%C2%A7%3DText"

18.2.34 E-Mail-Adresse prüfen / validieren

Prüfung auf korrekte E-Mail-Adressen-Syntax; KEINE Prüfung, ob die Adresse auch wirklich existiert.

#if($ScriptHelper.validateEmail($!requestParameters.EMAIL))
    ##Email-Adresse ist gültig
#else
    ##Email-Adresse ist ungültig
#end

18.2.35 Zufälligen Wert erstellen

Mit ScriptHelper.random(int startvalueInclusive, int startvalueExclusive) können Sie einen Zufallswert ausgeben. Die Werte in Klammer geben den Werteraum an, in dem sich der Zufallswert bewegen muss. Der Startwert ist im Werteraum enthalten, der Endwert befindet sich außerhalb.

Beispiel: Erstellen eines 4-stelligen Codes von „1000“ bis „9999“

#set($zufallscode = $ScriptHelper.random(1000, 10000))

18.2.36 Abgleich der Anmelde-Domain mit Domain-Negativliste oder -Positivliste

Mit folgender Funktion kann eine Emailadresse gegen eine Liste von erlaubten Domains oder eine Liste von nicht erlaubten Domains oder eine Blocklist geprüft werden.

Die Patterns dürfen Wildcards wie „*“ (= beliebige viele beliebige Zeichen) oder „?“ (= einzelnes beliebiges Zeichen) enthalten.

#set($emailAddress="tester@agnitas.de")
#set($includePatterns = ["*@must.be.used.domain"])
#set($excludePatterns = ["evil@agnitas.de", "*@not.allowed.domain"])

Email-Adresse muß in den includePatterns enthalten sein:
#set($emailIsGood_1=$ScriptHelper.checkEmailIncludes($emailAddress, includePatterns))

Email-Adresse darf nicht in den excludePatterns enthalten sein:
#set($emailIsGood_2=$ScriptHelper.checkEmailExcludes($emailAddress, excludePatterns))

Email-Adresse muss in den includePatterns enthalten und darf nicht in den excludePatterns enthalten sein:
#set($emailIsGood_3=$ScriptHelper.checkEmailIncludesExcludes($emailAddress, includePatterns, excludePatterns))