Wie erstelle ich eine Berichtsdefinition?

Bevor ein Bericht erstellt werden kann, muss zu diesem eine Berichtsdefinition angelegt sein. Diese ist die Grundlage und Datenbasis für den Bericht.

Berichtsdefinitionen können nur von Nutzern mit Berechtigungsrolle Report Manager erstellt werden.

Die Berichtsdefinition enthält die konkrete Konfiguration des zu erstellenden Berichts. In ihr sind die Datenquelle, Auswertungskriterien, möglichen Ausgabeformate sowie die Eingabeparameter definiert. Die möglichen Parameter sind von der Datenquelle abhängig.

Berichtsdefinitionen basieren auf SQL Select Abfragen und können daher völlig frei und nach Bedarf konfiguriert werden. Unabhängig von der späteren Anwendung der Berichtsdefinition können Sie bspw.:

ganz konkret festlegen, wie der künftige Bericht aufgebaut ist und welche Informationen im Bericht angezeigt werden sollen
den Ersteller des Berichts führen, indem Sie festlegen, welche Angaben benötigt werden, welche Angaben Pflicht sind und welche Daten im Hintergrund gesetzt werden
beliebige Bezeichnungen und von der Datenquelle unabhängige Parameter verwenden
u.v.a.m.

Für jede Berichtsdefinition können Sie separat festlegen, welcher Personenkreis Berichte erstellen kann und in welchen Ausgabeformaten die Berichte erzeugt werden können.

So legen Sie eine Berichtsdefinition an

Öffnen Sie das Modul Berichte
Klicken Sie im Kopf der Tabelle Übersicht Berichtsdefinitionen auf Neue Definition.
Es wird ein Assistent geöffnet, in dem Sie schrittweise die Berichtsdefinition konfigurieren können.
Konfigurieren Sie die Berichtsdefinition entsprechend Ihrer Anforderungen.
Konfiguration und Parameter siehe: Konfigurationsbeispiel einer Berichtsdefinition
Klicken Sie abschließend auf Speichern, um die Berichtsdefinition zu sichern.

Die Berichtsdefinition wird nun in der Übersicht Berichtsdefinitionen aufgeführt. Damit ist die Grundlage geschaffen, um anhand dieser Berichtsdefinition einen Bericht zu erstellen.

Konfigurationsbeispiel einer Berichtsdefinition

Im folgenden Beispiel wird eine Berichtsdefinition erstellt, deren Berichte die Anzahl der Tickets des ausgewählten Typs und der ausgewählten Organisation(en) ausgeben.

Das Beispiel enthält die in der Berichtsdefinition anzugebenden Konfigurationsparameter nebst deren Erläuterung.

Die Konfiguration erfolgt in 3 Schritten:

Berichtsinformationen
Datenquelle
Ausgabeformat

Um zum jeweils nächsten Schritt zu gelangen oder um zwischen den einzelnen Schritten zu wechseln, klicken Sie bitte auf die kleinen blauen Pfeilschaltflächen oder auf die dazwischen befindlichen blauen Punkte.

Schritt 1 - Berichtsinformationen

In diesem Schritt hinterlegen Sie allgemeine Informationen zur Berichtsdefinition und legen fest, welche Berechtigungsrollen um die Berechtigung zum Erstellen von Berichten erweitert werden.

Abb.: Berichtsinformationen hinterlegen

Parameter	Beschreibung
Titel	Name/Bezeichnung der Berichtsdefinition. Tragen Sie eine aussagekräftige Bezeichnung ein, damit Agenten den gewünschten Bericht gezielt finden.
Periodische Erstellung	Sie können angeben, ob ein Bericht periodisch erzeugt werden soll. Ja: Der Bericht wird periodisch erzeugt. KIX wird mit dem Job Periodic Reports ausgeliefert, der initial alle 15 Minuten die periodisch zu erstellenden Berichte ermittelt und im Ausgabeformat CSV erzeugt. Sie können die Ausführungszeiten im Job ändern. In KIX Pro können Sie zudem die Ausgabeformate ändern. Nein: Der Bericht wird nicht periodisch erzeugt. Er kann entweder manuell oder über einen von Ihnen konfigurierten Job automatisiert erstellt werden.
Max Reports	Anzahl der maximal vorzuhaltenden Berichte. Überzählige, zuvor erstellte Berichte werden automatisch entfernt. Beispiel: "2" → die letzten beiden Berichte bleiben erhalten. Wird ein dritter Bericht erzeugt, wird der erste und damit älteste Bericht gelöscht.
Kommentar	Optionaler Kommentar zum Bericht. Sie können hier bspw. detaillierte Informationen zum Bericht hinterlegen.
Rollen	Zuweisen von Berechtigungsrollen. Das Zuweisen von Berechtigungsrollen erfordert administrative Berechtigungen. Hierzu ist die Rolle "System Admin" erforderlich. Die Nutzer der hier ausgewählten Berechtigungsrollen können die Berichtsdefinition nutzen, um auf deren Basis Berichte zu erstellen. Die Berechtigungen der gewählten Rollen werden damit um das Erstellen und Lesen des Berichts erweitert. Initial vorbelegt ist die Rolle "Report User". Warnung KIX erzeugt die Berichte ohne gesonderte Prüfung der Berechtigungen. Es werden alle Objekte ausgewertet. Beachten Sie deshalb die Berechtigungen innerhalb der Rollen! "Report Manager" tragen daher die Verantwortung, dass Berichtsdaten nur durch berechtigte Personen eingesehen werden können! Wichtig Wählen Sie die Rollen ausschließlich, um deren Berechtigungen für das Erstellen von Berichten zu erweitern. Vergeben Sie die Berechtigung niemals auf Rollen, die mehr als Leserechte auf Berichte haben (z. B. Rollen "Super User" und "System Admin")! Anderenfalls kann die Berichtsdefinition nicht mehr bearbeitet werden.
Gültigkeit	gültig: Berichte können auf Basis dieser Berichtsdefinition erstellt werden (temporär) ungültig: Es können keine Berichte auf Basis dieser Berichtsdefinition erstellt werden.

Schritt 2 - Datenquelle

In diesem Schritt legen Sie die Datenquelle fest und definieren die SQL-Abfrage zur Ermittlung der Berichtsdaten einschließlich eventueller Parameter.

Abschnitt "Datenquelle"

Erstellen Sie hier die SQL-Abfrage, um festzulegen, welche Daten Sie aus welcher Datenquelle beziehen möchten und welche Parameter vom Ersteller des Berichts eingegeben werden sollen. Möglich sind nur SQL Select Abfragen. Individuelle Parameter können Sie frei definieren.

Abb.: Beispiel einer SQL-Abfrage

Parameter	Beschreibung
Datenquelle	Auswahl der Datenquelle Aktuell nur "GenericSQL" möglich.
DBMS	Angabe des Datenbankmanagementsystems Diese Information wird für die ausgelieferten Standardberichte genutzt. Für neue, über die GUI angelegte Berichte ist nur "Any" möglich.
SQL	Datenbankabfrage/SQL-Statement Setzen Sie sich im Bedarfsfall mit Ihrem System-Administrator oder mit unserem Support in Verbindung. Tragen Sie hier die SQL-Abfrage ein. Es werden nur `select`-Statements ausgeführt. Der Code wird vor dem Speichern geprüft; alle an die API gesendeten Attribute werden validiert. Sie können SQL-Aliase als temporäre Spaltenbezeichner in der Ergebnistabelle verwenden. Auf diese Aliase können Sie im Schritt 3 (Ausgabeformat > Spalten) Bezug nehmen, um die anzuzeigenden Tabellenspalten festzulegen. Sie können mehrere Arrays erstellen (z. B. Array von Tickettypen, Array von Organisationen usw.). Sie können beliebig viele, frei definierbare Parameter im SQL-Statement angeben: Parameter werden durch das Schlüsselwort `Parameters` definiert. Verwenden Sie folgende Syntax: `${Parameters.<Parameterbezeichner>}`. Die Parameterbezeichnung ist frei wählbar. Parameter bilden die Eingabefelder im Report. Die im SQL-Statement deklarierten Parameter müssen im Abschnitt Parameter konfiguriert werden. Fügen Sie pro verwendeten Parameter einen Konfigurationsblock ein. Die verwendeten Parameter werden im GenericSQL Datasource Backend gequotet, sodass ein SQL-Injection nicht möglich ist. Sie können einem Parameter einen Default-Wert als Fallback mitgeben. Dieser Wert wird anstelle der Variable verwendet, wenn kein Wert vorhanden ist. Ergänzen Sie dazu am Parameter die Angabe: `?<DefaultValue>`. Beispiel: `${Parameters.StartDate?2020-01-01 00:00:00}`. Als Default-Wert wird betrachtet, was zwischen dem Fragezeichen und der schließenden geschweiften Klammer steht. Beispiel eines SQL Statements select o.name as organisation, tt.name as type_name, count() as total from organisation o, ticket_type tt, ticket t where t.type_id = tt.id and t.organisation_id = o.id and tt.id in (${Parameters.TypeIDList}) and o.id in (${Parameters.OrganisationIDList}) group by o.name, tt.name order by o.name, tt.name Das Beispiel verwendet folgende Aliase (Schlüsselwort: `as`): organisation type_name total Das Beispiel verwendet folgende Parameter (Schlüsselwort: `in`): Parameter "TypeIDList": `${Parameters.TypeIDList}` Parameter "OrganisationIDList": `${Parameters.OrganisationIDList}` Beide Parameter müssen im Abschnitt Parameter konfiguriert werden. Im SQL-Statement erfolgt lediglich deren Deklaration. Tipp:* Das Schlüsselwort `in` ermöglicht die Angabe mehrerer Werte.

Parameter

Beschreibung

Datenquelle

Auswahl der Datenquelle

Aktuell nur "GenericSQL" möglich.

DBMS

Angabe des Datenbankmanagementsystems

Diese Information wird für die ausgelieferten Standardberichte genutzt.

Für neue, über die GUI angelegte Berichte ist nur "Any" möglich.

SQL

Datenbankabfrage/SQL-Statement

Setzen Sie sich im Bedarfsfall mit Ihrem System-Administrator oder mit unserem Support in Verbindung.

Tragen Sie hier die SQL-Abfrage ein. Es werden nur select-Statements ausgeführt. Der Code wird vor dem Speichern geprüft; alle an die API gesendeten Attribute werden validiert.

Sie können SQL-Aliase als temporäre Spaltenbezeichner in der Ergebnistabelle verwenden. Auf diese Aliase können Sie im Schritt 3 (Ausgabeformat > Spalten) Bezug nehmen, um die anzuzeigenden Tabellenspalten festzulegen.

Sie können mehrere Arrays erstellen (z. B. Array von Tickettypen, Array von Organisationen usw.).

Sie können beliebig viele, frei definierbare Parameter im SQL-Statement angeben:

Parameter werden durch das Schlüsselwort Parameters definiert.
Verwenden Sie folgende Syntax: ${Parameters.<Parameterbezeichner>}.
Die Parameterbezeichnung ist frei wählbar.
Parameter bilden die Eingabefelder im Report.
Die im SQL-Statement deklarierten Parameter müssen im Abschnitt Parameter konfiguriert werden. Fügen Sie pro verwendeten Parameter einen Konfigurationsblock ein.
Die verwendeten Parameter werden im GenericSQL Datasource Backend gequotet, sodass ein SQL-Injection nicht möglich ist.
Sie können einem Parameter einen Default-Wert als Fallback mitgeben.
Dieser Wert wird anstelle der Variable verwendet, wenn kein Wert vorhanden ist.
Ergänzen Sie dazu am Parameter die Angabe: ?<DefaultValue>.
Beispiel: ${Parameters.StartDate?2020-01-01 00:00:00}.
Als Default-Wert wird betrachtet, was zwischen dem Fragezeichen und der schließenden geschweiften Klammer steht.

Beispiel eines SQL Statements

select o.name as organisation, tt.name as type_name, count(*) as total
  from organisation o, ticket_type tt, ticket t 
  where t.type_id = tt.id
      and t.organisation_id = o.id
      and tt.id in (${Parameters.TypeIDList})
      and o.id in (${Parameters.OrganisationIDList})
  group by o.name, tt.name
  order by o.name, tt.name

Das Beispiel verwendet folgende Aliase (Schlüsselwort: as):

organisation
type_name
total

Das Beispiel verwendet folgende Parameter (Schlüsselwort: in):

Parameter "TypeIDList": ${Parameters.TypeIDList}
Parameter "OrganisationIDList": ${Parameters.OrganisationIDList}

Beide Parameter müssen im Abschnitt Parameter konfiguriert werden. Im SQL-Statement erfolgt lediglich deren Deklaration.

Tipp: Das Schlüsselwort in ermöglicht die Angabe mehrerer Werte.

Weiterführende Hinweise:

Informationen zum Erstellen einer SQL-Abfrage finden Sie in einschlägiger Literatur und im Internet (z. B.: https://www.w3schools.com/sql/default.asp).
Informationen zum Aufbau der KIX-Datenbank finden Sie in der SVG-Grafik im GitHub: https://github.com/kix-service-software/kix-backend/blob/master/ doc/database/KIX.svg (Option "an Seite anpassen" wählen)
Nutzer von On-Premises-Installationen können das SQL-Datenbankschema auch über diverse Tools erzeugen wie bspw.
- DBSchema: https://dbschema.com/?AFFILIATE=144826&__c=1
- SchemaSpy: https://dev.to/mostalive/how-to-visualize-a-postgresql-schema-as-svgwith- schemaspy-516g
  (Infos dazu: https://dev.to/mostalive/how-to-visualize-apostgresql- schema-as-svg-with-schemaspy-516g)

Abschnitt "Output Handler"

In diesem Abschnitt können spezifische Anweisungen angegeben werden, um die Ausgabe der Berichte zu transformieren (z. B. Ausgabe als Pivot Chart)

Aktuell können Output-Handler nicht konfiguriert werden. Die Output-Handler werden für die Ausführung der von KIX Pro mitgelieferten Standardberichte benötigt.

Die Parameter der Output-Handler sind direkt von den Spaltenbezeichnungen des SQL-Statements abhängig. Das heißt: Änderungen am SQL-Statement der Standardberichte führen zum Fehlverhalten der Output-Handler.

Abschnitt "Parameter"

In diesem Abschnitt werden die Parameter konfiguriert, die Sie im SQL-Statement deklariert haben. Sie spezifizieren damit die Eingabe- und Auswahlfelder, welche dem Berichtersteller im Dialog zur Verfügung stehen.

Für jeden im SQL-Statement definierten Parameter muss ein separater Konfigurationsblock angelegt werden. Klicken Sie dazu ggf. mehrfach auf die Plus-Schaltfläche am rechten Rand.

Nachfolgend werden für das Beispiel die im SQL-Statement definierten Parameter TypeIDList und OrganisationIDList konfiguriert.

Abb.: Konfiguration der im SQL-Statement verwendeten Parameter

Parameter	Beschreibung
Name	Interner Bezeichner des Parameters (Referenz des Parameters aus dem SQL-Statement) Im Beispiel: `TpyeIDList` bzw. `OrganisationIDList`
Label	Beschriftung vor dem Eingabe- bzw. Auswahlfeld Kennzeichnet den erwarteten Feldinhalt Im Beispiel: Ticket Typ bzw. Organisation
Beschreibung	Kurze Beschreibung des Parameters. Die Beschreibung wird als Hinweistext angezeigt, wenn der Berichtersteller auf klickt.
Datentyp	Auswahl des Datentyps Der gewählte Datentyp bestimmt, welche Art von Daten das Feld aufnehmen wird. Im Beispiel: jeweils "numeric" Mögliche Datentypen: String: Zeichen und Zeichenketten Numeric: Ganzzahlen (z. B. für IDs) Date: Datum Date Time: Datum und Zeit Zeit: Zeitangabe
Pflichtfeld	Pflichtfeldkonfiguration Wenn aktiviert: Das Feld ist ein Pflichtfeld und erwartet zwingend eine Eingabe vom Berichtersteller. Wenn nicht aktiviert: Das Feld kann vom Berichtersteller optional mit Werten gefüllt werden.
Mehrfach	Mehrfachauswahl in Auswahlfeldern möglich? Wenn aktiviert: Der Berichtersteller kann mehrere Werte eingeben. Wenn nicht aktiviert: Der Berichtersteller kann nur einen Wert eingeben.
Nur Lesen	Das Feld kann vom Berichtersteller nicht bearbeitet werden und wird im Dialog nur zur Information angezeigt.
Verweise	Objektreferenz des Parameters Syntax: <Objekt>.<Attribut> Beispielsweise für: Referenz auf Teams: `Queue.QueueID` Beachten Sie die Abweichung der Syntax: Das Attribut lautet `.QueueID` und nicht `.ID` Referenz auf Nutzer: `User.UserID` Beachten Sie die Abweichung der Syntax: Das Attribut lautet `.UserID` und nicht `.ID` Referenz auf Tickettyp: `TicketType.ID` Referenz auf Organisationen: `Organisation.ID` Referenz auf Dynamisches Feld: `DynamicField.DFName` usw. Abb: Datenquelle Organisation.ID
Mögliche Werte	Definiert die im Bericht auswählbaren Werte. Die möglichen Werte basieren auf der unter Verweise gewählten Datenquelle. Verweisen Sie bspw. auf die Tickettypen (TicketType.ID), können Sie hier konkretisieren, welche der Tickettypen dem Berichtersteller zur Auswahl stehen. Gleiches für die Organisationen (Organisation.ID). Wird hier nichts angegeben, dann sind im Bericht alle Objekte auswählbar. Hinweis zu Datentyp `string`: Wurde unter Verweise keine Datenquelle angegeben, können hier mögliche Auswahlwerte frei definiert werden, aus denen der Berichtersteller auswählen kann. Die Auswahlwerte müssen nicht Bestandteil der Datenbank sein. Abb: Datenquelle TicketType.ID und Werte für die Ticket ID
Standard	Legen Sie optional fest, mit welchem der unter Mögliche Werte angegebenen Wert das Feld vorbelegt sein soll. Im Beispiel: "Störung"

Schritt 3 - Ausgabeformat

In diesem Schritt legen Sie fest, welche Tabellenspalten im Bericht angezeigt werden, in welchen Ausgabeformaten der Bericht erstellt werden kann und definieren für jedes Ausgabeformat die dazugehörigen Parameter.

Der Ersteller eines Berichts kann im Feld Ausgabeformat eins oder mehrere dieser Ausgabeformate auswählen und damit festlegen, in welchen Dateiformaten der Bericht erzeugt wird.

Werden hier keine Ausgabeformate definiert, kann der Bericht in allen verfügbaren Ausgabeformaten mit den jeweiligen Default-Werten erstellt werden. Möglich sind folgende Ausgabeformate: CSV, Atom Feed, Excel, HTML, JSON, PDF, XML

Abb.: Konfiguration des Ausgabeformats

Parameter	Beschreibung
Titel	Tragen Sie einen allgemeingültigen Titel ein, der im erzeugten Bericht als Überschrift gesetzt wird. Der Titel wird in der HTML-Ausgabe auch als `<title>`-Tag gesetzt. Der Titel kann durch den im jeweiligen Ausgabeformat angegebenen Titel überschrieben werden (s. unten) Im Titel können die gleichen Parameter wie im SQL Statement verwendet werden. Sie fungieren damit als Platzhaltervariable. Beispiel: Titel: "Report from `${Parameters.startDateTime}` to `${Parameters.stopDateTime}"`
Ausgabeformat	Wählen Sie aus, in welchen Ausgabeformaten der Bericht erzeugt werden kann. Sie können immer nur 1 Ausgabeformat auswählen und dieses gezielt konfigurieren. Weitere Ausgabeformate fügen Sie mit einem Klick auf hinzu. Abhängig vom gewählten Ausgabeformat werden weitere Eingabefelder angezeigt, sodass Sie für jedes Ausgabeformat formatspezifische Parameter angegeben können: für nicht-technische Formate (CSV, Excel, HTML, PDF) Angabe formatspezifischer Parameter möglich Einschränkung der anzuzeigenden Tabellenspalten möglich Änderung des Titels möglich für technische Formate (JSON, XML) Keine Einschränkung der anzuzeigenden Tabellenspalten möglich; es werden alle Daten ausgegeben, welche das SQLStatement liefert. Änderung des Titels möglich. Hinweis: Die Statistiken im Home Dashboard werten nur die Ausgabeformate CSV und JSON aus.
Spalten	Optionale Angabe der im Bericht anzuzeigenden Spalten. Sie können damit die im Bericht anzuzeigenden Spalten einschränken. Beispielsweise, wenn das SQL-Statement mehr Ergebnisspalten liefert, als im Bericht benötigt werden. Tragen Sie dazu hier die entsprechenden Aliase aus dem SQL-Statement ein, sofern Sie Aliase verwenden (im Beispiel: `organisation`, `ticket_type`, `total` ). Trennen Sie mehrere Werte durch Kommas. Diese Angaben bilden die Spaltenüberschriften. Die Reihenfolge der Spalten im Bericht entspricht der hier angegebenen Reihenfolge. Wird hier nichts eingetragen, werden alle Ergebnisse aus dem SQL-Statement gezogen und deren Ergebniswerte in der Reihenfolge ausgegeben, wie sie aus dem SQL kommen.
Spalten-Header beachten	Wenn ausgewählt, werden die Spaltentitel im Bericht mit ausgegeben, sofern dies das Ausgabeformat unterstützt. Ist unter Spalten nichts angegeben, werden keine Spaltentitel angezeigt - auch wenn diese Option aktiviert ist.
Quote	Zeichen, in welches die einzelnen Werte eingefasst werden (für CSV) Standard: doppelte Hochkommas (") Andere Zeichen sind möglich, z. B.: einfache Hochkommas (') Zum Beispiel: "Mustermann GmbH" , "Incident" , "27" 'Mustermann GmbH' , 'Incident' , '27'
Trenner	Trennzeichen zwischen den einzelnen Werten (für CSV) Standard: Komma (,) Andere Zeichen sind möglich, z. B.: Semikolon (;) oder Strich (\|) Zum Beispiel: "Mustermann GmbH" , "Incident" , "27" "Mustermann GmbH" ; "Incident" ; "27" "Mustermann GmbH" \| "Incident" \| "27
Titel	Sie können für jedes Ausgabeformat einen anderen Titel angeben. Der hier hinterlegte Titel überschreibt den Titel der Standardkonfiguration (1. Eingabefeld dieser Dialogseite)
Spaltentitel übersetzen	Für nicht-technische Ausgabeformate (CSV, Excel, HTML, PDF) können Sie festlegen, in welcher Sprache die Spaltentitel ausgegeben werden. KIX ersetzt beim Erstellen des Berichts die entsprechenden Patterns. Voraussetzung: Die Sprache muss im SysConfig-Schlüssel DefaultUsedLanguages implementiert sein und die Patterns müssen im Menü Internationalisierung > Übersetzungen hinterlegt sein. Mögliche Werte: 1: Der Spaltentitel wird in die Standardsprache des Systems übersetzt (Default). Hinweis: Die Standardsprache ist im SysConfig-Schlüssel DefaultLanguage festgelegt. 0: Keine Übersetzung des Spaltentitels. Es wird die im SysConfig-Schlüssel DefaultLanguage hinterlegte Standardsprache verwendet. Sprachkürzel der im System hinterlegten Sprachen: Der Spaltentitel wird in die gewählte Sprache übersetzt (z. B. de, en)