Einleitung

Hinweis:
Weitere Informationen, beispielsweise zum Anmeldevorgang, entnehmen Sie bitte dem Handbuch für Agenten.

Administrator ist jeder Benutzer mit der Rolle Administrator. 

Ein Administrator darf:

• die eigene Organisation konfigurieren
• Benutzer anlegen
• Templates bearbeiten

Nach dem Anmelden sieht ein Administrator entsprechend das folgende Navigationsmenü.

• Dashboard
• Organisation
• Benutzer
• Template

Standardmäßig wird zunächst das Dashboard angezeigt.

Hinweis
Das Dashboard enthält zurzeit noch keine relevanten Informationen.

Nach Auswahl eines Menüpunktes wird einer der folgenden Bereiche zur Bearbeitung angezeigt.

Organisation

Der Dialog für die Organisation ist aufgeteilt in 3 Bereiche: 

1. Organisation (Grundeinstellungen)
2. Daten für Clearing API
3. Daten für Notification API

Grundeinstellungen

Im ersten Tab mit der Überschrift "Organisation" können Sie folgende Grundeinstellungen für Ihre Organisation vornehmen: 

• die allgemeine Kontaktadresse
• die Sichtbarkeit der Organisation
• den Vorschlagswert für die Benachrichtigung der Agenten per E-Mail
• die Regeln für die Vergabe von Vorgangsnummern

Allgemeine Kontaktadresse

Die Angabe dieser E-Mail Adresse ist verpflichtend. 

Sie wird für wichtige allgemeine Informationen verwendet. Hierüber erhalten Sie Informationen über geplante Wartungen, neue Releases etc.

Gelegentlich werden darüber auch Newsletter verschickt.

Sichtbarkeit der Organisation

Nach der Einrichtung Ihrer Organisation ist sie zunächst für andere Organisationen "unsichtbar".
Hierzu wurde das Datum „Gültig ab“ ca. 1 Monat in die Zukunft gesetzt. 

In der Phase der "Unsichtbarkeit" können Sie das ausgewählte Datum jederzeit anpassen - sowohl weiter, als auch näher in die Zukunft. Sobald das eingestellte Datum erreicht ist oder der Wert gelöscht wird, ist die Sichtbarkeit für andere unmittelbar gegeben.   

Bitte beachten
In diesem geschützten Zeitraum können keine Tickets von anderen Organisationen empfangen werden. 

Wichtig
Nach erstmaliger Sichtbarkeit können keine Änderungen mehr vorgenommen werden. Laut Spezifikation ist diese Funktion lediglich dafür vorgesehen, um einen potenziellen Wechsel zu einem anderen Anbieter geregelt abzuwickeln. Falls dennoch erforderlich, bitte Support-Ticket erstellen. 

E-Mail Benachrichtigung

Sie können für alle Agenten Ihrer Organisation die Art der E-Mail Benachrichtigung einheitlich festlegen:

• eigene: der Agent  soll nur Benachrichtigungen für eigene Tickets erhalten
• alle: der Agent soll Benachrichtigungen für alle Tickets erhalten (also auch für neue und nicht zugeordnete Tickets). Er wird nicht über bereits zugeordnete Tickets benachrichtigt.
• keine: der Agent bekommt keinerlei Benachrichtigungen

Hinweis
Sie setzen nur den Vorschlagswert für den Fall, dass der Agent in seinen persönlichen Einstellungen diesen Wert wünscht (Default). Jeder Agent kann aber unabhängig von dieser allgemeinen Einstellung seine individuelle Wunsch-Einstellung über sein Benutzerprofil vornehmen.

Vorgangsnummer

Vorgangsnummer auf Eindeutigkeit prüfen

Sie haben ebenso die Möglichkeit, die Vorgangsnummer auf Eindeutigkeit prüfen zu lassen. 

Dazu wählen Sie die Option „[x]  auf Eindeutigkeit prüfen“.

Danach ist das Versenden eines Tickets mit einer bereits verwendeten Vorgangsnummer nicht mehr möglich. 

Der Agent erhält eine entsprechende Fehlermeldung.

Hinweis
Bei automatischer Erzeugung der Vorgangsnummer ist diese Option unnötig. 

Vorgangsnummer durch Präfix eindeutig machen

Auch wenn die Vorgangsnummer z.B. durch die Option "auf Eindeutigkeit prüfen" für Ihre Organisation eindeutig ist, heißt das nicht, dass sie auch für den Empfänger des Tickets eindeutig ist, denn dieser erhält ja Tickets von unterschiedlichen Organisationen. Hier empfiehlt es sich, die Vorgangsnummer zusätzlich mit einem Präfix zu versehen. 

Dazu wählen Sie die Option „[x]  durch Präfix für Empfänger eindeutig machen“.

Hinweis
Dieses Präfix ist die eigene ITU-Carrier-Id gefolgt von einem Bindestrich.

Das Präfix wird erst beim Senden erzeugt. Es wirkt auch bei automatischer Erzeugung der Vorgangsnummer. 

Vorgangsnummer automatisch erzeugen 

Die Vorgangsnummer des Tickets ist oft durch andere Systeme vorgegeben und wird in diesem Fall immer manuell erfasst. Falls eine solche externe Nummer aber nicht existiert oder die Verwendung dieser Nummer nicht gewünscht ist, kann eine automatische Generierung dieser Vorgangsnummer durch den Administrator aktiviert werden. 

Dazu wählen Sie die Option „[x] automatisch erzeugen“.

Die Vorgangsnummer ist dann eine automatisch aufsteigende Zahl beginnend mit 1. 

Sie können zusätzlich ein Schema vereinbaren, wie beispielsweise "DEU.DEMO-1". 

Dazu fügen Sie im Feld Schema eine entsprechende Maske ein, siehe folgende Beispiele.

Weitere variable Parameter

• ${date}: Tagesdatum in der Form JJJJMMTT, z.B. 20240823

Hier einige weitere Beispiele für den Fall ${counter} = 123 und ${date} = 20240823

Daten für Clearing API

Die Clearing-Plattform kann ohne Einschränkungen über die Benutzerschnittstelle (GUI) benutzt werden.

Für den Fall, dass beispielsweise eine eigene GUI-Implementierung verwendet werden soll, kann die Plattform ebenso über eine Schnittstelle (API) anstatt über die Benutzerschnittstelle (GUI) benutzt werden. 

Diese Schnittstelle ist vollständig über die aktuelle Spezifikation beschrieben. 

Die API URL ist die URL zum Aufruf der Clearing API.
Sie können Ihre API Aufrufe jederzeit testen. Dazu rufen Sie die Methode ping auf der Clearing API auf. 

GET  <API URL>/ping

Beispiel: 

GET https://clearing-service.de/partner-api/v1/ping

OAuth2-Authentifizierung

Die OAuth2-Authentifizierung ist die derzeit sicherste Authentifizierungs-Methode.

Dadurch, dass die eigentliche Anmeldung nicht mit Benutzernamen und Passwort erfolgt, sondern mit einem generierten sogenannten Token, ist es praktisch unmöglich, diese Information auszuspähen. 

Für die OAuth2 Authentifizierung  benötigen Sie

• Token URI: zur Generierung eines Zugriffs-Tokens
• "Well-Known" Endpunkt: optional - enthält weitere URLs zur OAuth2 Authentifizierung
• Client Id: das ist quasi der Benutzername für die Generierung eines Tokens
• Client-Secret: das ist quasi das Passwort für die Generierung eines Tokens 

Hinweis
Weitere Information zur OAuth2 Authentifizierung finden Sie hier: https://oauth.net/2/.

Basic Authentifizierung

Anders als bei der vorgenannten OAuth2-Authentifizierung wird bei der Basic-Authentifizierung ein Benutzername und ein Passwort verwendet. 

Warnung
Benutzername und ein Passwort  müssen bei jedem Aufruf immer wieder gesendet werden und damit gibt es oft eine Möglichkeit, es abzufangen. Daher empfehlen wir dringend die Verwendung des sicheren OAuth2-Verfahrens. 

Sollten Sie dennoch - eventuell in der Anfangsphase - die Basic Authentifizierung verwenden wollen, so genügt es, einen Benutzer anzulegen mit der Rolle "API". Dieser Benutzer  (Name / Passwort) wird dann für diese Authentifizierung verwendet. Siehe auch: Benutzer anlegen

Daten für Notification API

Sie können sich über jedes Ereignis - also über  jede Aktion bezüglich Ihrer Tickets - automatisch benachrichtigen lassen.

Hierzu müssen Sie selbst die sogenannte Notification API implementieren. Auch diese Schnittstelle ist vollständig über die aktuelle Spezifikation beschrieben.

Hinweis
Nicht verwechseln mit der E-Mail Benachrichtigung für die Benutzer  

Option: "Benutzt API (aktiv)"

Für die Freigabe Ihrer Notification Schnittstelle aktivieren Sie nach Durchführung aller folgenden Schritte die Option „[x] benutzt API (aktiv)“.

Warnung
Sie können selbstverständlich die Option "benutzt API (aktiv)" jederzeit wieder deaktivieren. Allerdings werden danach keine weiteren Benachrichtigungen versendet und noch nicht versendete Benachrichtigungen gelöscht. 

Option: "ECHO aktivieren: Auch über eigene Änderungen / API Aufrufe informieren"

Sie erhalten automatische Benachrichtigungen (Callback) nur für Ereignisse, die nicht von Ihrer Organisation initiiert wurden. Wenn Sie auch über solche Ereignisse benachrichtigt werden wollen, dann wählen Sie diese Option.

Wichtig
Der Standardwert ist ohne Echo - die Option muss also explizit aktiviert werden.

Kontaktadresse für Fehlermeldungen (API)

Diese E-Mail Adresse wird nur für den Fall benötigt, dass eine Notification API eingerichtet ist. 

Danach werden Sie über jeden aufgetretenen Fehler beim Aufruf dieser Notification API benachrichtigt. 

Hinweis:
Als Fehler wird jeder Versuch gewertet, der einen Status-Code ungleich 2xx zurückmeldet. 

Diese Benachrichtigung enthält alle Details zum Fehler, soweit wir ihn eingrenzen können. 

Jeder erfolglose Versuch eine Benachrichtigung zuzustellen löst eine E-Mail-Nachricht an diese Adresse aus.

Hinweis
Beim Scheitern der Zustellung einer Benachrichtigung werden alle folgenden Benachrichtigungen zurückgehalten, bis diese Benachrichtigung erfolgreich zugestellt werden konnte. Nur so kann die korrekte Reihenfolge der Nachrichten gewährleistet werden. Es wird auch nur eine einzige E-Mail für eine gescheiterte Zustellung versendet, obwohl der Zustellversuch regelmäßig wiederholt wird.

Im Falle eines gemeldeten Fehlers sollten Sie möglichst schnell den Grund für den Fehler beseitigen. In der Zwischenzeit werden wir nämlich alle Benachrichtigungen zurückhalten. Erst wenn der Fehler behoben ist, werden diese Benachrichtigungen dann in der korrekten Reihenfolge zugestellt. Dazu wiederholen wir den Zustellversuch kontinuierlich.

Abhängig von der Anzahl der Zustellversuche wächst das zeitliche Intervall bis zur Wiederholung: 

Unbegrenzt lange können wir jedoch die Zustellung nicht unterdrücken. Wir werden Sie ebenfalls über diese E-Mail Adresse darüber informieren, dass wir die Zustellung einstellen und damit alle bisher unzustellbaren Benachrichtigungen löschen.     

Warnung
In keinem Fall sollten Sie aber zwischenzeitlich die Option "benutzt API (aktiv)" deaktivieren. Dies führt unmittelbar zur Löschung aller bisher unzustellbaren Benachrichtigungen!

Daten für Notification API

Zum Aufruf dieser Schnittstelle benötigen wir die Zugangsdaten. 

Die API URL ist die URL zum Aufruf der Clearing API.

Wichtig:
Füllen Sie im Folgenden nur eine der beiden Authentifizierungs-Methoden aus! 
Sobald nämlich ein Benutzername angegeben ist, wird stets die Basic-Authentifizierung verwendet, auch wenn die OAuth2-Authentifizierung ausgefüllt ist.

Verbindungstest

Sie können die eingegebenen Verbindungsdaten jederzeit überprüfen. Dazu klicken Sie auf "Verbindungstest". 

Wir rufen dann auf der angegebenen  API URL die Methode ping auf. 

GET <API URL>/ping

Danach wird geprüft, ob der Aufruf erfolgreich durchgeführt werden konnte.  Als erfolgreich gelten die Status-Codes: 

• 200: OK
• 404: Not found

Alle anderen Status-Codes werden als Fehler interpretiert und entsprechend gemeldet. 

Hinweis
Der Verbindungstest kann auch auf noch nicht gespeicherten Daten ausgeführt werden. Auch die Option benutzt API (aktiv) muss noch nicht aktiviert sein.

Oauth2-Authentifizierung

Die OAuth2-Authentifizierung ist die derzeit sicherste Authentifizierungs-Methode.

Dadurch, dass die eigentliche Anmeldung nicht mit Benutzernamen und Passwort erfolgt, sondern mit einem generierten sogenannten Token, ist es praktisch unmöglich, diese Information auszuspähen. 

Für die OAuth2 Authentifizierung  benötigen wir

• Token URI: zur Generierung eines Zugriffs-Tokens
• "Well-Known" Endpunkt: optional - enthält weitere URLs zur OAuth2 Authentifizierung
• Client Id: das ist quasi der Benutzername für die Generierung eines Tokens
• Client-Secret: das ist quasi das Passwort für die Generierung eines Tokens 

Hinweis
Weitere Information zur OAuth2 Authentifizierung finden sie hier: https://oauth.net/2/.

Basic Authentifizierung

Anders als bei der vorgenannten OAuth2-Authentifizierung wird bei der Basic-Authentifizierung ein 

• Benutzername und ein 
• Passwort 

verwendet. Diese beiden Informationen müssen Sie entsprechend bereitstellen. 

Hinweis
Sobald ein Benutzername angegeben ist, wird stets die Basic-Authentifizierung verwendet, auch wenn die OAuth2-Authentifizierung ausgefüllt ist.

Warnung
Benutzername und ein Passwort  müssen bei jedem Aufruf immer wieder gesendet werden und damit gibt es oft eine Möglichkeit, es abzufangen. Daher empfehlen wir dringend die Verwendung des sicheren OAuth2-Verfahrens. 

Benutzer

Im Bereich Benutzer sehen Sie eine Liste der bereits existierenden Benutzer.

Diese Liste enthält die wesentlichen Attribute des Benutzers.

Hier haben Sie folgende Möglichkeiten:

Benutzer anlegen
Benutzer ändern	Klick auf entsprechenden Eintrag in der Liste.
Benutzer löschen

Benutzer anlegen

Zum Anlegen von neuen Benutzern klicken Sie auf "Neuen Benutzer hinzufügen"

Im folgenden Dialog "Neuen Benutzer hinzufügen" geben Sie ein

• Login-Name: Das ist der Benutzername, der beim Anmelden eingegeben werden muss
  Der Login-Name ist identisch mit der E-Mail-Adresse des Benutzers. Davon sollte nur in Ausnahmefällen abgewichen werden.

Hinweis: Der Benutzername muss in jedem Fall dem Format einer E-Mail-Adresse entsprechen, also [email protected], z.B. [email protected].

Hinweis zum Passwort 
Das Passwort setzt der Benutzer selbst durch die Funktion "Passwort vergessen" auf dem Anmeldedialog.


Dazu muss beim Benutzer zwingend eine gültige E-Mail-Adresse hinterlegt werden.

Nach dem Speichern ist der Benutzer bereits angelegt, allerdings ohne weitere Details und ohne Berechtigungen. 

Im folgenden Dialog ändern Sie nun diesen Benutzer. 

Benutzer ändern

Nach Klick auf einen Eintrag in der Benutzerliste - oder unmittelbar nach dem Anlegen eines neuen Benutzers - können Sie den ausgewählten Benutzer ändern. 

Im ersten Teil ändern Sie die Benutzerdetails:

• Login-Name: der Login-Name kann jederzeit geändert werden
• [ ] Aktiv: Ein Benutzer kann vorübergehend auf inaktiv gesetzt werden. Ein Login ist dann nicht möglich. 
• Vorname und Nachname
• E-Mail: Eine gültige E-Mail-Adresse, die für die Funktion "Passwort vergessen" und die Benachrichtigungen verwendet wird. Typischerweise ist diese identisch mit dem Login-Namen. 

Hier kann unter Umständen auch eine Teamzuordnung getroffen werden. Siehe dazu Kapitel "Teams".

Rollen zuordnen

Jedem Nutzer der Clearing-Plattform können bestimmte Rechte (Rollen) zugewiesen werden. 

Ein Benutzer kann eine oder mehrere Rollen besitzen. Seine sich darauf ergebenden effektiven Rechte entstehen durch die Vereinigung der Rechte aller Rollen:

• Agent: Benutzer darf Tickets als Bearbeiter erzeugen sowie bearbeiten.
• Manager: Benutzer darf Tickets kontrollieren und zuweisen.
• Administrator: Benutzer darf beispielsweise andere Benutzer anlegen und ändern, Templates erstellen und die Organisation konfigurieren. 
• API: Wird nur in Ausnahmefällen benötigt. Benutzer darf die Clearing-Plattform API benutzen. Hierbei wird die schwache "Basic Authentication" verwendet, also Anmeldung mit Benutzernamen und Passwort.
  Wir empfehlen dringend, ausschließlich die starke "OAuth2 Authentication" zu verwenden.
   

Zusätzlich wird durch die Rolle der Inhalt des Dashboards bestimmt. So sieht beispielsweise ein

• Agent eine Übersicht über seine eigenen Tickets ("Meine Tickets") und "Alle Tickets" im Dashboard:
• Manager keine eigenen Tickets, sondern nur Alle Tickets im Dashboard
• Administrator lediglich eine leere Seite im Dashboard. Ein reiner Administrator besitzt keine Berechtigung, Tickets zu sehen oder sie zu bearbeiten.

Benutzer löschen

Bevor Sie einen Benutzer löschen, überlegen Sie, ob es nicht genügt, für diesen Benutzer lediglich die Option 
[ ] Aktiv zu deaktivieren. Danach ist ein Login für diesen Benutzer nicht mehr möglich, aber seine Ticket-Zuordnung kann z.B. für Filter benutzt werden. 

Beim Löschen eines Benutzers wird eine Warnung angezeigt. Diese Warnung enthält die Information, ob dieser Benutzer noch aktive Tickets zugeordnet hat. Nach dem Löschen sind diese Tickets dann alle ohne Bearbeiter - eventuell vorhandene Entwürfe werden gelöscht. 

Benutzerliste verarbeiten

Benutzer können im sogenannten Bulk-Modus hinzugefügt oder verändert oder werden.

Dazu gibt es in der Benutzerpflege die Funktion Benutzerliste verarbeiten.   

Zunächst wird die vollständige (oder gefilterte) Benutzerliste heruntergeladen. 

Danach wird die heruntergeladene Datei entsprechend angepasst:

• die Kopfzeile muss dabei unverändert bleiben
• existierende Benutzer können verändert werden oder, falls sie nicht verändert werden müssen, dann können sie aus der Liste gelöscht werden (die Benutzer werden dabei natürlich NICHT gelöscht).    
• neue Benutzer werden einfach ohne Benutzerkennung als neue Zeilen eingetragen

Danach wird diese veränderte Liste mit der Funktion Benutzerliste verarbeiten  wieder hoch geladen. 

Hinweis zu Rollen:
In der Spalte Rollen dürfen nur folgende Werte als Liste (getrennt durch Leerzeichen oder Komma) eingetragen werden:  writer, manager, admin, api. 
Siehe auch Kapitel Rollen zuordnen.

Als Ergebnis wird ein Protokoll angezeigt, das sowohl die erfolgreiche Verarbeitung, als auch möglicherweise aufgetretene Fehler ausgibt.  Der Vorgang kann beliebig oft wiederholt werden. 

Teams

Hinweis: Das Feature ist im Produktivbetrieb kostenpflichtig. 
Im Testsystem kann das Feature ohne Einschränkung getestet werden. 
Die folgende Beschreibung gilt also nur für den Fall, dass das Feature freigeschaltet ist.

Siehe auch: Feature: Erweiterte Benutzerverwaltung 

Im Bereich Teams sehen Sie eine Liste der bereits existierenden Teams.

Diese Liste enthält die wesentlichen Attribute jedes Teams.

Hier haben Sie folgende Möglichkeiten:

Team anlegen
Team  ändern	Klick auf entsprechenden Eintrag in der Liste.
Team  löschen

Team anlegen

Zum Anlegen eines Teams klicken Sie auf "Neues Team hinzufügen"

Im folgenden Dialog "Neues Team hinzufügen" geben Sie einen Teamnamen ein

• Teamname: Das ist der Name des Teams. Der Name muss eindeutig sein.

Nach dem Speichern ist das Team bereits angelegt, allerdings ohne weitere Details. 

Im folgenden Dialog ändern Sie nun dieses Team.

Team ändern

Der Änderungsdialog ist aufgeteilt in 3 Teile:

1. Team
2. Szenarien: Ticket erstellen
3. Szenarien: Ticket bearbeiten

Tab: Team

In diesem Tab können Sie allgemeine Informationen zum Team festlegen:

• Teamname: der Teamname kann hier wieder geändert werden
• Beschreibung: hier kann optional eine Beschreibung des Teams angegeben werden

Benutzer zum Team hinzufügen

Um einen Benutzer zum Team hinzuzufügen, wählen Sie ihn aus der Liste "Benutzer wählen" aus:

Hinweis: Benutzer, die in einem Team zugeordnet sind, werden entsprechend markiert: Teamsymbol, Teamname.

Die Aktion wird erst nach "Speichern" aktiv.

Benutzer aus dem Team entfernen

Benutzer werden durch Klick auf das Papierkorbsymbol aus dem Team entfernt.

Die Aktion wird erst nach "Speichern" aktiv.

Tab: Ticket erstellen

Die Szenarien, die das Team erstellen bzw. in der Liste der erstellten Tickets sehen darf, werden hier festgelegt.

Interaktionsregeln: Aus der Liste "Zugelassene Szenarien" können Sie Einträge - zunächst ganze Hauptszenarien- in die Liste "nicht zugelassene Szenarien" verschieben durch: 

• Drag&Drop mit der Maus oder Doppelklick
• Selektion und Auswahl der Funktion "Pfeil rechts"

Entsprechendes gilt für den umgekehrten Fall "nicht zugelassene Szenarien" --> "Zugelassene Szenarien" mit der Funktion "Pfeil links".

Die Funktion Doppelpfeil (links oder rechts) verschiebt jeweils alle Einträge in die entsprechende Liste.

Sollte die Selektion auf der Ebene der Hauptszenarien nicht genügen, also wenn feiner selektiert werden soll auf der Ebene der (Unter-)Szenarien, dann muss die Option "nur Hauptszenarien" deaktiviert werden. 

Tab: Ticket bearbeiten

Hier werden folgende Filter für empfangene Tickets festgelegt: 

• Geschäftskunden-Tickets: 
  • Geschäfts- und Privatkunden: das Team kann alle Tickets ohne Einschränkung bearbeiten
  • nur Geschäftskunden: das Team darf nur Tickets von Geschäftskunden bearbeiten
  • nur Privatkunden: das Team darf nur Tickets von Privatkunden  bearbeiten
• Die Szenarien, die das Team bearbeiten darf 

Die Interaktionsregeln sind unter Tab: Ticket erstellen beschrieben.

Hinweis: Die Option "Geschäftskunde" kann an jedem Ticket gesetzt werden. Sie wird durch die folgenden Symbole im Ticket angezeigt: 

Team löschen

Zum Löschen eines Teams klicken Sie in der Liste auf das Papierkorb-Symbol.

Hinweis: Sie können ein Team erst löschen, nachdem alle Benutzer aus dem Team gelöscht wurden.  

Templates

Im Bereich Templates sehen Sie eine Liste der bereits existierenden Templates.

Diese Liste enthält die wesentlichen Attribute des Templates.

Hier haben Sie folgende Möglichkeiten:

Template anlegen
Template ändern	Klick auf entsprechenden Eintrag in der Liste.
Template testen
Template löschen

Was sind Templates?

Templates sind Vorschriften für die Erzeugung von Text-Dateien. 

Diese Templates werden später von der Apache FreeMarker™ Template Engine prozessiert.

Dazu muss diese Vorschrift selbstverständlich der Syntax von Apache FreeMarker™ entsprechen. 

Details zur Syntax finden Sie hier:  https://freemarker.apache.org/ 

Wozu werden Templates benötigt?

Templates werden für 2 Anwendungsfälle benötigt:

1. Individuelle Aufbereitung von Downloads
2. Generierung von Reports über die Clearing API 

Für beide Anwendungsfälle finden Sie später weitere Informationen. 

Template anlegen

Zum Anlegen eines neuen Templates klicken Sie auf "Neues Template"

Im folgenden Dialog "Neues Template" geben Sie ein

• Template-Id: Dies ist die eindeutige Id Templates.

Nach dem Speichern ist das Template bereits angelegt, allerdings ohne weitere Details. 

Im  folgenden Dialog ändern Sie nun dieses Template.

Template ändern

Nach Klick auf einen Eintrag in der Template-Liste - oder unmittelbar nach dem Anlegen eines neuen Templates - können Sie das ausgewählte Template ändern. 

Bei der Neuanlage empfiehlt es sich, zunächst eine Vorlage auszuwählen. Hierzu klicken Sie in der Fußzeile auf "Vorlage verwenden". Dann selektieren Sie aus der Liste "Vorlage auswählen" eine passende Vorlage.

Hinweis
Die Vorlagen unterscheiden die beiden wichtigen Datenquellen: "aktive" Tickets und Reportindex.
Wählen Sie die Vorlage entsprechend aus - hierzu dient die Spalte Datenquelle.  

Mit der Auswahl werden die entsprechenden Eigenschaften übernommen, die Sie anschließend abändern sollten:

• Anzeigename - der Name des Templates, wie er z.B. einem Agenten in einer Auswahlliste angezeigt werden soll
• Beschreibung - falls erforderlich: ausführliche Detailinformation zum Template
• Dateiendung - Auswahl eines Dateityps
• Mime-Type - Auswahl eines Dateiformats für den Browser
• freigegeben  - wenn das Template auch für den GUI-Download von Daten verwendet werden soll, müssen Sie zudem die Sichtbarkeit ändern
• Datenquelle - hier ist festzulegen, ob das Template für "aktive" Tickets oder für den Reportindex eingesetzt werden soll. Der Default ist hier "aktive" Tickets. 

Hinweis
Das Erstellen eines neuen Templates aus einer Vorlage ist nur eine Möglichkeit. Sie können selbstverständlich auch ein Template vollständig ohne Vorlage erstellen.

Liste der Attribute

Mit Hilfe der „Liste der Attribute“ können Sie erfahren, welche Felder und Funktionen (Helper) existieren. 
Per copy und paste können Sie diese in den Code übernehmen.

Hinweis: 
Die entsprechenden Felder sind bereits in der FreeMarker-Schreibweise notiert. 

Testen eines Templates

Zum Testen eines Templates klicken Sie in der Liste der Templates auf die Funktion "Template testen". 

Für diesen Test werden maximal 5 Datensätze verwendet. 

Entscheidend ist hier die Datenquelle:

• Ticket:  das Template wird mit aktiven Tickets prozessiert
• Report: das Template wird aus dem Reportindex prozessiert 

Das Ergebnis wird immer als Datei heruntergeladen.

Hinweis: Sollte das Template Syntaxfehler enthalten, so werden diese auch in dieser Datei ausgegeben.

Löschen von Templates

Über die Funktion „Löschen“ können Sie bereits erstellte Templates löschen:

Individuelle Aufbereitung von GUI-Downloads

Wenn die Option freigegeben bei einem Template gesetzt ist, dann wird dieses Template den Agenten - oder Managern - auch für den GUI-Download angeboten.

Entscheidend ist hier die Datenquelle:

• Ticket:  das Template wird als Option für alle Downloads von Listen aktiver Tickets angeboten
• Report: das Template wird als Option für alle Downloads von Listen im Bereich Auswertungen angeboten

Hinweis
Erst wenn mindestens ein Template für eine Datenquelle "freigegeben" wurde, kann der Benutzer in einem Auswahl-Dialog ein Template wählen. 
Andernfalls wird immer automatisch das Standard-Template verwendet. Dieses Standard-Template ist jedoch in diesem Auswahl-Dialog weiterhin als erstgenannte Option verfügbar.  

Beide Standard-Templates werden übrigens bei der Erstellung eines eigenen Templates auch als Vorlage angeboten und können wunschgemäß abgeändert werden: 

• system_save_list für aktive Tickets 
• system_save_basic_report  für Auswertungen.  

Generierung von Reports über die Clearing API

Templates können auch über auch über eine spezielle API (Schnittstelle) der Clearing Plattform genutzt werden. 

Die Beschreibung dieser Schnittstelle finden Sie in der Datei Reporting.yaml im Anhang.

Hinweis
Diese API ist nicht Teil der offiziellen Spezifikation und ein spezieller Service unserer Plattform.

Template Beispiel mit Erklärung

Nachfolgend finden Sie am Beispiel der Vorlage template_reporting_csv eine Erklärung zum Code:

<#include "system_reporting">

<#macro formatDate d>
  ${d?date?string("dd.MM.yyyy")}
</#macro>

<#macro formatDateTime d>
  ${d?datetime?string("dd.MM.yyyy HH:mm")}
</#macro>

<#macro formatDateTimeAsDate d>
  ${d?datetime?string("dd.MM.yyyy")}
</#macro>

 

<#macro lastStateChangeDate status statusChanges requestedStatus>
  <#assign changeDate = "">
    <#if status.status == requestedStatus>
      <#assign changeDate = status.changeDate>
    <#else>
      <#list statusChanges as statusChange>
        <#if statusChange.status == requestedStatus>
          <#assign changeDate = statusChange.changeDate>
        </#if>
      </#list>
  </#if>
  <#if changeDate?hasContent>
    <@formatDateTime d=changeDate/>
  </#if>    
</#macro>

<@compress single_line=true>
Ticket ID
;EKPauf
;EKPab
;PKIauf
;PKIab
;Ticket erstellt Datum Zeit
;Ticket erstellt Datum
;Hauptclearingszenario ID
;Unterclearingszenario ID
;Hauptclearingszenario
;Unterclearingszenario
;Reklamiert Datum Zeit
;Reklamiert Flag
;Storniert Datum Zeit
;Held Datum Zeit
;Pending Datum Zeit
;In Bearbeitung Datum Zeit
;Abgeschlossen Datum Zeit
;Erledigt Datum Zeit
;Erledigungsstatus
;Statuswechsel Datum erster
;Statuswechsel Datum letzter
;Ticketstatus
;Anzahl Statuswechsel
;Clearing Art
;Partner
;Auftraggeber
;Auftragnehmer
;interne Vorgangsnummer
;BNetzA ID
;PreOrder I
;Externe Auftragsnummer Entstörung
;Externe Auftragsnummer
;Line ID
;VA ID
;Leitungsbezeichnung
;SPRI-Vertragsnummer
;WITA-Vertragsnummer
;Sonstige Vertragsnummern
;Fristueberschreitung
;Zieltermin
;Projektkenner
</@compress>
;

<#list tickets as ticket>

<@compress single_line=true>

<#-- Ticket ID -->
="${ticket.id}"
<#-- EKPauf -->
;="${ticket.clearingData.ekpAuf!""}"
<#-- EKPab -->
;="${ticket.clearingData.ekpAbg!""}"
<#-- PKIauf -->
;="${ticket.clearingData.pkiAuf!""}"
<#-- PKIab -->
;="${ticket.clearingData.pkiAbg!""}"
<#-- Ticket erstellt Datum Zeit -->
;="<@formatDateTime d=ticket.creationDate/>"
<#-- Ticket erstellt Datum -->
;="<@formatDateTimeAsDate d=ticket.creationDate/>"

<#-- Hauptclearingszenario ID -->
;="${Helper.mainScenarioId(ticket.ticketType)}"
<#-- Unterclearingszenario ID -->
;="${ticket.ticketType}"
<#-- Hauptclearingszenario -->
;="${Helper.mainScenario(ticket.ticketType)}"
<#-- Unterclearingszenario -->
;="${Helper.scenario(ticket.ticketType)}"

<#-- Reklamiert Datum Zeit -->
;="<#assign reklamiert = "">
   <#if     ticket.status.status == "inProgress" && ticket.statusChange?last.status == "resolved">
     <#assign reklamiert = ticket.status.changeDate> 
   <#else>
 <#assign resolved = false> 
 <#list ticket.statusChange as statusChange>
  <#if statusChange.status == "resolved">
<#assign resolved = true>
  </#if>
  <#if statusChange.status == "inProgress" && resolved == true>
<#assign reklamiert = statusChange.changeDate> 
<#assign resolved = false>
  </#if>
</#list>
   </#if>
  <#if reklamiert?hasContent>
    <@formatDateTime d=reklamiert/>
  </#if>  
"
<#-- Reklamiert Flag -->
;="<#if reklamiert?hasContent> 1 <#else> 0 </#if>"

<#-- Storniert Datum Zeit -->
;="<@lastStateChangeDate status=ticket.status statusChanges=ticket.statusChange requestedStatus="cancelled"/>" 
<#-- Held Datum Zeit -->
;="<@lastStateChangeDate status=ticket.status statusChanges=ticket.statusChange requestedStatus="held"/>"
<#-- Pending Datum Zeit -->
;="<@lastStateChangeDate status=ticket.status statusChanges=ticket.statusChange requestedStatus="pending"/>"
<#-- In Bearbeitung Datum Zeit -->
;="<@lastStateChangeDate status=ticket.status statusChanges=ticket.statusChange requestedStatus="inProgress"/>"
<#-- Abgeschlossen Datum Zeit -->
;="<@lastStateChangeDate status=ticket.status statusChanges=ticket.statusChange requestedStatus="closed"/>"
<#-- Erledigt Datum Zeit -->
;="<#if ticket.resolutionDate??>
  <@formatDateTime d=ticket.resolutionDate/>
</#if>
"
<#-- Erledigungsstatus -->
;="<#if ticket.resolvedSuccessfully??>
  ${ticket.resolvedSuccessfully?c}
</#if>
"
<#-- Statuswechsel Datum erster -->
;="<#if ticket.statusChange?size != 0> 
<#if ticket.statusChange?size == 1>
<@formatDateTime d=ticket.status.changeDate/> 
<#else>
<@formatDateTime d=ticket.statusChange[1].changeDate/>
   </#if>
</#if>  
"
<#-- Statuswechsel Datum letzter -->
;="<#if ticket.statusChange?size != 0>
  <@formatDateTime d=ticket.status.changeDate/>  
</#if>  
"
<#-- Ticketstatus -->
;="${ticket.status.status}"
<#-- Anzahl Statuswechsel -->
;="${ticket.statusChange?size}"
<#-- Clearing Art -->
;="<#if ticket.originator == owner>
ausgehend
<#else>
eingehend
</#if>
"
<#-- Partner -->
;="<#if ticket.originator == owner>
  ${Helper.carrier(ticket.processor)}
<#else>
  ${Helper.carrier(ticket.originator)}
</#if>
"
<#-- Auftraggeber -->
;="${ticket.originator}"
<#-- Auftragnehmer -->
;="${ticket.processor}"
<#-- interne Vorgangsnummer -->
;="${ticket.externalId}"
<#-- BNetzA ID -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "bnetzaId")}"
<#-- PreOrder ID -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "externalOrderIdServiceApi")}"
<#-- Externe Auftragsnummer Entstörung -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "externalOrderIdTroubleTicketApi")}"
<#-- Externe Auftragsnummer -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "externalOrderId")}"
<#-- Line ID -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "lineId")}"
<#-- VA ID -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "prenegotiationId")}"
<#-- Leitungsbezeichnung -->
;="${Helper.externalIdentifier(ticket.clearingData.externalIdentifier, "technicalLineIdentifier")}"
<#-- SPRI-Vertragsnummer -->
;="${Helper.externalIdentifier(ticket.clearingData.contractNumber, "SPRI")}"
<#-- WITA-Vertragsnummer -->
;="${Helper.externalIdentifier(ticket.clearingData.contractNumber, "WITA")}"
<#-- Sonstige Vertragsnummern -->
;="${Helper.externalIdentifier(ticket.clearingData.contractNumber, "other")}"
<#-- Fristueberschreitung -->
;="${Helper.workingDaysBetween(ticket.requestedResolutionDate, ticket.resultionDate)}"
<#-- Zieltermin -->
;="<@formatDate d=ticket.requestedResolutionDate/>"
<#-- Projektkenner -->
;="${ticket.clearingData.specialAgreements!""}"
</@compress>
<#-- Ende -->
;