Templates

Einführung in Templates in ConSol CM

Templates sind aus Text und Code bestehende Vorlagen. Sie werden an verschiedenen Stellen von ConSol CM verwendet, insbesondere zur Definition von Anzeigenamen und als Entwürfe für E-Mails.

Konzepte, Begriffe und Definitionen

Konzept

Andere Begriffe

Definition

Template

 

Übergeordnetes Konzept, das Anzeige-Templates, Textvorlagen und Dokumentvorlagen einschließt.

Anzeige-Template

Template für die Datendarstellung

Technisches Template, mit dem der Anzeigename von Kontakten, Ressourcen und Benutzern festgelegt wird.

E-Mail-Template

E-Mail-Vorlage

Template für E-Mails. Dies kann ein technisches Template sein, wenn es nur in automatischen E-Mails verwendet werden soll. Andernfalls muss es eine Textvorlage sein.

System-Template

Text-Template

Technisches Template, das automatisch bei der Installation oder dem Update des Systems erstellt wird

Freemarker

 

Template-Engine zum Erstellen von Templates in ConSol CM

Zweck und Verwendung

Templates haben in ConSol CM mehrere Zwecke. Sie werden zum Definieren der Anzeigenamen von Kontakten, Ressourcen und Benutzern verwendet und dienen als Vorlagen für automatische E-Mails, die vom System verschickt werden.

Eine ConSol CM-Standardinstallation enthält bereits System-Templates und einige Beispiel-Templates, die Ihnen die Definition neuer Templates für Ihre besonderen Anwendungsfälle erleichtern.

Templates werden in Freemarker geschrieben (siehe https://freemarker.apache.org/). Einige Arten von Templates können HTML-Tags enthalten.

In diesem Abschnitt sind die technischen Templates, die in der Web Admin Suite verwaltet werden, beschrieben. Informationen zu den im Web Client verwalteten Templates finden Sie in Textvorlagen. In der folgenden Tabelle sind die verfügbaren Template-Typen aufgeführt:

Typ

Beschreibung

E-Mail

Verwendung für E-Mails, sowohl für manuelle, im Web Client geschriebene E-Mails als auch für automatisch durch den Workflow versendete E-Mails. Siehe Textvorlagen für manuelle E-Mails. Templates für automatische E-Mails sind in Bearbeiten von E-Mail-Templates beschrieben.

Kontakt

Legt den Anzeigenamen von Kontakten fest, siehe Hinzufügen von Kontakt- und Ressourcen-Templates.

Ressource

Legt den Anzeigenamen von Ressourcen fest, siehe Hinzufügen von Kontakt- und Ressourcen-Templates.

Benutzer

Legt den Anzeigenamen der Benutzer fest, siehe Bearbeiten von System-Templates.

Passwort zurücksetzen

Für die E-Mail verwendet, die gesendet wird, wenn ein Benutzer sein Passwort für den Web Client oder CM/Track zurücksetzt, siehe Zurücksetzen des Passworts.

Vertretung

Für die E-Mails verwendet, die an die betroffenen Benutzer gesendet werden, wenn es Änderungen an Vertretungen gibt, siehe Bearbeiten von System-Templates.

Zuweisung

Für die E-Mails verwendet, die an die Benutzer gesendet werden, wenn ihnen Vorgänge zugewiesen werden, siehe Zuweisen von Vorgängen.

Verfügbare Einstellungen für Templates

Ein Template hat drei Einstellungen:

Grundlegende Aufgaben

Suchen nach Templates

Die Liste der Templates wird direkt nach dem Öffnen der Seite Templates der Web Admin Suite angezeigt. Sie können die Liste filtern, um ein Template leichter zu finden:

Arbeiten mit Templates

Sie können für Templates folgende Aktionen ausführen:

Hinzufügen von Kontakt- und Ressourcen-Templates

Die Anzeigenamen von Kontakten und Ressourcen im Web Client müssen mittels Templates definiert werden. In den Templates wird festgelegt, welche Datenfelder für den Anzeigenamen verwendet werden.

Datenfelder werden über den Namen ihrer Feldgruppe und den Feldnamen referenziert:

Sie können den Code mit dem Template-Generator erzeugen, indem Sie in der Kopfzeile des Editors auf das Icon Template-Generator klicken und die gewünschten Felder auswählen.

Verwenden Sie in den Ausdrücken, die den Anzeigenamen definieren, keine Zeilenumbrüche.

Die Templates werden in den entsprechenden Datenmodellen den Kontaktobjekten bzw. Ressourcentypen zugewiesen.

Erweiterte Aufgaben

Verwenden der Funktionen des Template-Editors

Der Template-Editor hat folgende Funktionen:

Sie können auf den Button Verwendung klicken, um zu sehen, wo ein Template verwendet wird. Im Popup-Fenster sind die Stellen aufgeführt, an denen das Template referenziert wird, und Sie können über die Links zu den referenzierenden Objekten springen.

Verwenden von Templates in Skripten

Mit den folgenden Methoden können Sie Templates in Skripten referenzieren, zum Beispiel, um in einer Workflow-Aktivität eine automatische E-Mail zu senden.

Bearbeiten von System-Templates

In einer Standardinstallation von ConSol CM gibt es mehrere vordefinierte System-Templates:

Die folgenden Variablen sind in der Benachrichtigung bei der Erstellung oder Löschung einer Vertretung verfügbar. „representing“ steht für den Benutzer, der einen anderen Benutzer vertritt, und „represented“ steht für den Benutzer, der von einem anderen Benutzer vertreten wird.

Bearbeiten von E-Mail-Templates

Es gibt eine Reihe von Ereignissen, bei denen ConSol CM automatisch E-Mails versendet. Der Inhalt dieser E-Mails wird in E-Mail-Templates definiert. In den folgenden Abschnitten sind die E-Mail-Templates beschrieben, die in der Web Admin Suite definiert werden müssen. Sie können in der Web Admin Suite oder im Web Client weitere E-Mail-Templates für Ihre speziellen Anwendungsfälle definieren.

E-Mail-Templates, die für manuell gesendete E-Mails zur Verfügung stehen sollen, müssen im Web Client definiert werden.

Zuweisen von Vorgängen

Benutzer werden in automatischen E-Mails benachrichtigt, wenn ihnen ein Vorgang zugewiesen oder entzogen wird. Für jeden Fall (Zuweisen oder Entziehen) gibt es ein Template, das in der entsprechenden Queue referenziert wird (siehe Queues).

Standardmäßig wird die E-Mail-Adresse des CM-Administrators (siehe System-Property cmas-core-security, admin.email) als From-Adresse verwendet. Sie können die From-Adresse auch explizit im Template setzen (siehe folgendes Beispiel).

Das folgende Beispiel zeigt ein Template für die Vorgangszuweisung:

Subject: Ticket #${ticket.name} assigned to you

From: cm@example.com

 

<#setting number_format="0.######"/>

The ticket #${ticket.name}

 

"${ticket.subject}"

 

has been assigned to you by <#if engineer_exec??>${engineer_exec.name}<#else>the workflow</#if> <#if engineer_old??>(former engineer: ${engineer_old.name})<#else>(no former engineer)</#if>

 

Please take care.

 

URL: ${urlWebclient}/ticket/name/${ticket.name}

Code-Beispiel 18: Inhalt eines Zuweisungs-Templates

Zurücksetzen des Passworts

Wenn Datenbankauthentifizierung verwendet wird (siehe Authentifizierung), können die Benutzer ihre Passwörter sowohl im Web Client als auch in CM/Track zurücksetzen. Für jeden Client muss ein E-Mail-Template mit einem Link zur Seite für die Passwort-Zurücksetzung definiert werden.

Web Client

Wenn ein Benutzer sein Web-Client-Passwort vergessen hat, kann er über den Link Passwort vergessen? auf der Anmeldeseite ein neues Passwort anfordern. Es wird eine E-Mail mit einem Link zu einer URL, über die der Benutzer ein neues Passwort festlegen kann, an den Benutzer gesendet.

Auf der Seite Benutzer muss eine gültige E-Mail-Adresse für den Benutzer angegeben sein.

Das Template mit dem E-Mail-Inhalt muss password-reset-template heißen. Das folgende Beispiel zeigt ein einfaches Template, mit dem das Web-Client-Passwort zurückgesetzt werden kann.

Subject: Password reset procedure

From: no-reply@consol.de

 

Dear ${engineer.firstname} ${engineer.lastname},

Please click the following link to reset your password:

 

${urlWebclient}/passwordChange?resetCode=${resetCode}

 

This link expires at ${expirationDate?string("yyyy.MM.dd HH:mm:ss")}.

Code-Beispiel 19: Template zum Zurücksetzen des Passworts für den Web Client

Die folgende Variable wird in den System-Properties konfiguriert:

Die From-Adresse der E-Mail wird in der System-Property cmas-core-security, password.reset.mail.from definiert.

CM/Track

Wenn ein Kontakt sein CM/Track-Passwort vergessen hat, kann er über den Link Passwort vergessen? auf der Anmeldeseite ein neues Passwort anfordern. Es wird eine E-Mail mit einem Link zu einer URL, über die der Kontakt ein neues Passwort festlegen kann, an den Kontakt gesendet.

Im entsprechenden Datenfeld im Web Client muss eine gültige E-Mail-Adresse für den Kontakt angegeben sein.

Das Template mit dem E-Mail-Inhalt muss track-password-reset-template heißen und manuell erstellt werden. Das folgende Beispiel zeigt ein einfaches Template zum Zurücksetzen des CM/Track-Passworts.

Subject: Your Password Reset Link

From: no-reply@consol.de

 

Dear ${unit.firstname} ${unit.lastname},

Please click the following link to reset your password:

 

${urlTrack}/#/password-reset/resetCode-${resetCode}

 

This link expires at ${expirationDate?string("yyyy.MM.dd HH:mm:ss")}.

Abbildung 10: Template zum Zurücksetzen des Passworts in CM/Track

Die folgenden Variablen werden über System-Properties konfiguriert:

Syntaxbeispiele

Lokalisieren von Listenwerten

Lokalisierte Werte von Sortierten Listen können mit der Methode localize() in Templates angezeigt werden. Diese Methode ruft den lokalisierten Listenwert ab, wie er in der Web Admin Suite definiert ist, um ihn im Web Client anzuzeigen. Ansonsten würde der interne Listenwert angezeigt.

Das folgende Beispiel zeigt ein Template für eine Ressource. Das Ressourcenfeld SLA_country ist eine Sortierte Liste, die eine Länderliste enthält. Die Methode localize() wird verwendet, um den Ländernamen in der im Browser eingestellten Sprache anzuzeigen.

${localize(resource.getFieldValue("SLA_Fields_basic","SLA_country"))!}

Abkürzen von Werten

Werte, die von einem Template abgerufen werden, können mit der Methode abbreviate() abgekürzt werden. Dadurch werden lange Werte gekürzt, sodass alle Felder angezeigt werden, auch wenn das erste Feld einen langen Wert enthält.

Die Methode abbreviate() benötigt zwei Parameter:

Das folgende Beispiel zeigt das Template für eine Firma und wie der abgekürzte Firmenname in der Vorgangsliste angezeigt wird.

${abbreviate(ResellerCompany.getFieldValue("ResellerCompanyData","company_name"),8)!} - ${ResellerCompany.getFieldValue("ResellerCompanyData","company_number")!}

Verwenden von Links

Mit den Methoden linkInWebClientTo() und linkInTrackTo() können Sie Links zu Vorgängen, Kontakten und Ressourcen in ein Template einfügen. Es sind folgende Methoden verfügbar:

Das folgende Beispiel zeigt die Verwendung dieser Methoden::

[#assign ticketUrl = "${linkInWebClientTo(ticket)}"]

<p>This is a link to ticket: <a href="${ticketUrl?no_esc}">ticket</a></p>

Umgang mit fehlenden Werten

Sie können if-Anweisungen in Kombination mit dem Operator ?? oder dem Operator ?has_content verwenden, um zu prüfen, ob ein Objekt existiert oder ein Feld einen Wert enthält.

<#if ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")?has_content &&
ResellerCustomer.getFieldValue("ResellerCustomerData","firstname")?has_content>
${ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")!},
${ResellerCustomer.getFieldValue("ResellerCustomerData","firstname")!}
<#else> ${ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")!}</#if>

Code-Beispiel 20: Beispiel für ein Kontakt-Template mit if-Anweisung (muss in eine Zeile geschrieben werden!)

Alternativ können Sie einen Standardwert mit dem Operator ! definieren, um Exceptions wegen fehlender Werte zu vermeiden. Der Standardwert kann leer sein.

${ResellerCompany.getFieldValue("ResellerCompanyData","company_name")!} - ${ResellerCompany.getFieldValue("ResellerCompanyData","company_number")!}

Code-Beispiel 21: Beispiel für ein Kontakt-Template mit leerem Standardwert (muss in eine Zeile geschrieben werden!)

Definieren eines Musters für Zahlenformate

Mit Freemarker können Sie ein Muster für das Zahlenformat definieren. Das folgende Beispiel zeigt ein Muster, das Zahlen mit zwei Nachkommastellen anzeigt.

<#setting number_format="0.##"/>${customerModelCompany.getFieldValue("groupName", "numberValueField")!}

Code-Beispiel 22: Zahlenformat so definieren, dass nur zwei Nachkommastellen angezeigt werden