Wie erstelle ich ein Template für einen Datenextrakt?

Geändert am Di, 21 Mai, 2024 um 4:32 NACHMITTAGS

INHALTSVERZEICHNIS

Was sind Templates?
Wer darf Templates anlegen und ändern?
Wie erstelle ich ein Template?
Woher weiß ich, welche Felder ich im Template verwenden kann?
Wie kann ich ein Template testen?
Gibt es ein kommentiertes Beispiel?

Was sind Templates?

Templates sind Beschreibungen für die Ausgabe von Daten.

Wer darf Templates anlegen und ändern?

Um ein Template anzulegen oder anzupassen, müssen Sie Administratorrechte haben.

Dann sehen Sie im Navigationsmenü den Punkt "Templates".

Wie erstelle ich ein Template?

Klicken Sie auf:

Beim Erstellen sind folgende Informationen nötig:

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.
Organisation: ist automatisch mit der eigenen Organisation vorbelegt.
Code: Der eigentliche Template-Code im Format "Apache FreeMarker". Siehe https://freemarker.apache.org/

Hinweis: Für den Code können Sie eine Vorlage verwenden - entweder eine Systemvorlage, oder ein existierendes Template.

Woher weiß ich, welche Felder ich im Template verwenden kann?

In der Seitenleiste ist eine Liste der möglichen Felder enthalten:

Hier können Sie sowohl die verfügbaren Felder, als auch einige eingebaute Funktionen (Helper) finden:

Die Liste enthält die entsprechenden Felder bereits in der FreeMarker Schreibweise. Hinweise für die Verarbeitung der Felder (z.B. Zeichenverarbeitung, Berechnungen...) entnehmen Sie bitte der FreeMarker Dokumentation. Den Link finden Sie auch in der Fußzeile.

Wie kann ich ein Template testen?

Es gibt in der Liste der Templates eine Funktion zum Ausführen eines Tests.

Das Ergebnis wird immer als Datei heruntergeladen.

Hinweis: Sollte das Template Syntaxfehler enthalten, dann werden diese als Ergebnis dort ausgegeben.

Man kann aber jedes Template auch über das Gateway des Clearing Plattform testen. Hier muss man sich mit dem Administrator-Benutzer einloggen.

Den folgenden Link aufrufen und dort die Funktion "Reporting" suchen und testen:

https://api.clearing-service-test

Alternativ kann die Ausführung auch direkt gestartet werden durch:

https://api.clearing-service-dev.de/api/report?template=<Name des templates>

Hinweis: Ohne Angabe eines Templates wird das Ergebnis als Liste von JSON-Objekten ausgegeben.

Gibt es ein kommentiertes Beispiel?

Am Beispiel der Vorlage template_reporting_csv hier eine Erklärung der Arbeitsweise:

`<#include "system_reporting">` XML	Lädt Systemmakros, macht Helper adressierbar
`<#macro formatDate d> ${d?date?string("dd.MM.yyyy")} </#macro>` XML	Makro formatDate: Der Parameter d (Datum) wird aufbereitet als Datum in der Form xx.xx.xxxx, z.B. 07.02.2023
`<#macro formatDateTime d> ${d?datetime?string("dd.MM.yyyy HH:mm")} </#macro>` XML	Makro formatDateTime: Der Parameter d (Zeitstempel) wird ufbereitet als Zeitstempel in der Form xx.xx.xxxx xx:xx, z.B. 07.02.2023 11:23
`<#macro formatDateTimeAsDate d> ${d?datetime?string("dd.MM.yyyy")} </#macro>` XML	Makro formatDate TimeAsDate: Der Parameter d (Zeitstempel) wird aufbereitet als Datum in der Form xx.xx.xxxx, z.B. 07.02.2023
`<#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>` XML	Makro lastStateChange: Die Parameter status, statusChange und requestedStatus werden genutzt, um aus status und statusChange den jeweils letzten Wechsel in den Status requestedStatus zu ermitteln. Ausgegeben wird der Zeitstempel.
<@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> ; XML	Die Kopfzeile (Zeile 1) wird aufgebaut aus den jeweiligen Spaltenüberschriften - durch “;” separiert. <@compress single_line=true> sorgt dafür, dass aus den diversen Zeilen des Templates nur eine einzige Zeile erzeugt wird.
`<#list tickets as ticket>` XML	Die Anweisung <#list tickets as ticket> stellt nacheinander jedes einzelne Ticket der Ergebnismenge tickets als Variable ticket zur Verfügung.
`<@compress single_line=true>` XML	<@compress single_line=true> sorgt dafür, dass aus den diversen Zeilen des Templates nur eine einzige Zeile je Ticket erzeugt wird.
`<#-- 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/>"` XML	Jeder Abschnitt des “list-Blocks” füllt eine Spalte dieser Zeile. Um später beim Einlesen in Excel unnötige automatische Formatierungen zu vermeiden, wird der Trick verwendet, jeden Wert einer Spalte, eingeleitet durch das Semikolon (;) mit einem Gleichheitszeichen (=) und double-quotes (“) zu kapseln: also ;=”wert”.
`<#-- Hauptclearingszenario ID --> ;="${Helper.mainScenarioId(ticket.ticketType)}" <#-- Unterclearingszenario ID --> ;="${ticket.ticketType}" <#-- Hauptclearingszenario --> ;="${Helper.mainScenario(ticket.ticketType)}" <#-- Unterclearingszenario --> ;="${Helper.scenario(ticket.ticketType)}"` XML	Die in dieser Anweisung enthaltenen Aufrufe des “Helper” sind nicht Freemarker-Standard. Vielmehr werden hier spezielle Methoden in der Clearing Plattform aufgerufen – mit Übergabe von Parametern. Die Beschreibung der verfügbaren Helper Methoden ist im GUI im Template-Editor integriert.
<#-- 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>" XML	Diese komplexe Anweisung ermittelt die letzte erfolgte “Reklamation” - also die Zurückweisung eines als erledigt gekennzeichneten Tickets. Das Ergebnis der Analyse wird in der Variable reklamiert abgelegt. Diese dient anschließend auch dazu, das “Reklamiert Flag” zu ermitteln.
<#-- 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 --> ; XML