Konfiguration von Druckvorlagen

Mit Klick auf die Schaltfläche Drucken können Agenten ein PDF mit den jeweiligen Objektinformationen generieren und dieses anschließend zur Weiterverwendung herunterladen. Dem Layout dieser PDFs liegt eine objektspezifische Druckvorlage zugrunde.

Eine Druckvorlage ist die Blaupause eines PDFs im JSON-Format. Sie dient dazu, die PDFs zu generieren. In der Druckvorlage ist definiert, welche Daten in welcher Form und an welcher Stelle im PDF enthalten sind.

Aktuell stellt KIX für die Kontexte Ticket, Artikel und Asset je eine Druckvorlage als Standard bereit. Sie können zusätzliche Druckvorlagen im System bereitstellen oder im Bedarfsfall die Standard-Druckvorlagen modifizieren.

Warnung

Änderungen an den Standard-Druckvorlagen haben globale Auswirkung! Alle Funktionen, die eine Standard-Druckvorlage nutzen, verwenden dann auch die geänderte Standard-Vorlage.

Voraussetzungen

Für das Erstellen einer Druckvorlage bis zur Bereitstellung des PDF benötigen Sie grundlegendes Wissen über die jeweiligen Objekte (z.B. Ticket, Asset, Artikel, Kontakt usw.) sowie ausreichend Kenntnisse in JSON, SQL und HTML/CSS.

Zum Erstellen (oder Modifizieren) einer Druckvorlage müssen Sie ein valides JSON bereitstellen, welches mit spezifischen Inhaltsbausteinen (Bausteine) befüllt ist. KIX wandelt dieses JSON in mehrere HTML-Dateien um (Header, Content, Footer) und konvertiert diese anschließend in ein PDF. Sie müssen daher genau wissen, WAS, WIE und WO im PDF angezeigt werden soll.

Zum Bereitstellen von Druckvorlagen in KIX On-Premises-Umgebungen benötigen Sie administrative Rechte auf den Server und Zugriff auf die KIX Datenbank. Für KIX.Cloud-Umgebungen übernimmt das unser Support, wenn Sie uns eine entsprechende Druckvorlage bereitstellen (Support-Vertrag vorausgesetzt).

Verwendung

Die im System bereitgestellten Druckvorlagen können in verschiedenen Bereichen von KIX ausgewählt und angewendet werden:

beim Druck von Assets
Sie können klassenspezifische Druckvorlagen bereitstellen.
für den Standard Ticketdruck
Für Agenten besteht keine Möglichkeit, die zu verwendende Druckvorlage auszuwählen. Sie können jedoch die Standard-Vorlage mit geändertem Inhalt über die KIX-Datenbank bereitstellen.
Achtung
Änderungen an der Standard-Druckvorlage beeinflussen auch den Sammeldruck von Tickets.
bei Verwendung des Konsolenbefehls Console::Command::Admin::HTMLToPDF::Convert

Der Aufbau einer Druckvorlage

Eine Druckvorlage besteht aus mehreren Abschnitten, die zusammen den Aufbau des PDF bilden. Der Aufbau wird im JSON-Format abgebildet, um eine klare Struktur zu erhalten, welche gut vom System interpretiert werden kann.

Die einzelnen Abschnitte bestehen aus einer Liste von Eigenschaften und/oder Objektinformationen:

Beispiel:

Aufbau einer Druckvorlage

{
  "Expand": [
    "DynamicField",
  ],
  "Page": {
    "Top": "10",
    "Left": "15",
    "Right": "10",
    "Bottom": "10",
    "SpacingHeader": "1",
    "SpacingFooter": "1",
    "Format": "A5",
    "Orientation": "Landscape"
  },
  "Header": [ ... ],
  "Content": [ ... ],
  "Footer": [ ... ]
}

Expands Ist eine Liste von Erweiterungen, die das Hauptobjekt bereitstellen soll (z. B. Dynamische Felder)
Page Definiert die Seiteneinstellung des PDF (Randabstände, Format usw.)
Header Definiert den Seitenkopf, in dem beispielsweise ein Logo enthalten ist.
Ist der Header gesetzt, wird er auf jeder Seite wiederholt angewendet.
Content Definiert den Inhalt der PDF-Datei über alle Seiten.
Hier ist festgelegt, WAS für Informationen WIE und WO im PDF dargestellt werden sollen.
Hinweis: Positionierungen auf einer bestimmten Seite ist nicht direkt möglich.
Footer Definiert eine Fußzeile, die beispielsweise Seitenzahl, Kontaktdaten usw. anzeigt.
Ist der Footer gesetzt, wird er auf jeder Seite wiederholt angewendet.

Tipp

Informationen zum Aufbau einer Druckvorlage erhalten Sie im Menü System → Konsole durch Ausführung des Konsolenbefehls Console::Command::Admin::HTMLtoPDF::Inspect (s. auch: Verwendung der Konsole‌ und Console::Command::Admin::HTMLToPDF::Inspect)

Seitenaufbau

Der Aufbau der Seite kann in 4 Kombinationsvarianten erfolgen. Die gewählte Variante gilt für das gesamte PDF. Folgende Kombinationen sind möglich:

Header + Content + Footer
Seitenkopf + Seiteninhalt + Seitenfuß
Content + Footer
Seiteninhalt + Seitenfuß
Header + Content
Seitenkopf + Seiteninhalt
nur Content
nur Seiteninhalt

Header + Footer + Content	Content + Footer	Header + Content	nur Content

Header und Footer (blau) sind Abschnitte, die optional gesetzt werden können. Sind sie nicht gesetzt, nimmt der Content diesen Platz ein.

Der Content (grün) ist ein Pflicht-Abschnitt, der gesetzt werden muss. Er liefert den grundlegenden Inhalt des PDF. Im Content ist definiert, welche Objektinformationen an welcher Position auf der Seite angezeigt werden.

Für die Anzeige der Objektinformationen stehen verschiedene Bausteine zur Verfügung. Sie ermöglichen die Darstellung der Inhalte in einer bestimmten Form (Tabellen, Listen, Bilder, Text etc.). Zudem können CSS-Stylings angegeben werden, um die Anzeige ansprechend zu gestalten.

Seiteneinstellung

Damit der Inhalt korrekt auf der Seite platziert wird, müssen Seiteneinstellungen wie Format und Randabstände angegeben werden. Die Einstellungen werden jeweiligen Template im Abschnitt Page hinterlegt.

Beispiel für die Seiteneinstellung

{
  "Expand": [ ... ],
  "Page": {
    "Top": "10",
    "Left": "15",
    "Right": "10",
    "Bottom": "10",
    "SpacingHeader": "1",
    "SpacingFooter": "1",
    "Format": "A5",
    "Orientation": "Landscape"
  },
  "Header": [ ... ],
  "Content": [ ... ],
  "Footer": [ ... ]
}

Parameter für die Seitenkonfiguration

Wichtig

Bitte geben Sie die Maßeinheit ausschließlich in Millimeter an!

Parameter	Beschreibung
Format	Legt das Seitenverhältnis fest, z. B. A4 Wird nichts angegeben, dann wird automatisch A4 als Standard verwendet. Hinweis: Nicht alle existierenden DIN-Formate werden unterstützt. Wird ein DIN-Format nicht akzeptiert, sollte Height/Width angegeben werden.
Orientation	Definiert die Ausrichtung der Seite. `Landscape`: Seitenausrichtung im Querformat `Portraite`: Seitenausrichtung im Hochformat (Standard)
Height	Konfigurierbare Seitenhöhe. Wenn definiert, muss `Width` mit angegeben werden. Wenn unter `Format` ein Seitenverhältnis definiert ist, wird diese Einstellung ignoriert.
Width	Konfigurierbare Seitenbreite Wenn definiert, muss `Height` mit angegeben werden. Wenn unter `Format` ein Seitenverhältnis definiert ist, wird diese Einstellung ignoriert.
Top	Definiert den oberen Seitenrand (Abstand zum Seitenrand in Millimeter)
Bottom	Definiert den unteren Seitenrand (Abstand zum Seitenrand in Millimeter)
Left	Definiert den linken Seitenrand (Abstand zum Seitenrand in Millimeter)
Right	Definiert den rechten Seitenrand (Abstand zum Seitenrand in Millimeter)
SpacingHeader	Abstand der Kopfzeile in Millimeter Je kleiner der Wert, desto weiter ragt die Kopfzeile ins PDF.
SpacingFooter	Abstand der Fußzeile in Millimeter Je kleiner der Wert, desto weiter ragt die Fußzeile ins PDF.

Bausteine

Bausteine ermöglichen die Darstellung der Inhalte in einer bestimmten Form (Tabellen, Listen, Bilder, Text etc.). Sie können in den Abschnitten Header, Content und Footer angewendet werden.

Abb.: Baustein unterhalb eines Containers

Blocks‌

Blocks ist ein Baustein, der andere Bausteine unter sich kombinieren kann und speziellere Daten vererbt. Hierbei sind folgende Varianten möglich:

wiederholende Kombination: Kombination von Bausteinen, die wiederholt nacheinander dargestellt werden sollen. Dabei werden den Bausteinen mit jeder Wiederholung andere Daten bereitgestellt.
einfache Kombination: Kombination aus zwei oder mehreren Bausteinen, die einmalig abgebildet werden, aber spezielle Daten erhalten.

Wiederholende Kombinationen

Zum Abbilden wiederholender Kombinationen ist zu beachten:

Blocks muss vom Typ Listsein.
Damit wird gewährleistet, dass sich die darunter liegenden Bausteine wiederholen.
Angegeben werden müssen:
- Ein Objekt, welches die neuen Daten aufbereitet
- das Data, welches die notwendige ID, Name und Nummer liefert
Filter oder Expands (Datenerweiterung) sind optional.
Filter prüft, ob die geholten Daten zulässig sind.
Soll mit weiteren Daten des Objekts innerhalb des Blocks gearbeitet werden, muss dies angegeben werden.

pdf-druck_wiederholende-doppelstrukturen

Abb.: Baustein für ein Objekt

Parameter	Pflichtfeld	Hinweise
Object	ja	Objekt, welches in den darunter liegenden Bausteinen genutzt werden soll.
Expands	nein	Erweiterung der Datenmenge um zusätzliche Angaben des gewählten Objekts.
Filters	nein	Einschränkung der Datenliste von Data.
Data	ja	Daten aus der Datenerweiterung des darüber liegenden Objekts (Elternobjekt), welche im Baustein angewendet werden sollen. Achtung: Hier sollten nur Array Daten Anwendung finden.
Type	ja	Angabe des Type `List`
ID	nein	Kenner des gesamten Blocks (Default: `Blocks`)

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Struktur für Blocks (wiederholende Kombination)

{
   "Type": "List",
   "Object": "Article",
   "Expand": "DynamicField",
   "Data": "Article",
   "Blocks": [
      {
         "ID": "ArticleHeader",
         "Type": "Text",
         "Value": [
            "<Font_Bold>Article",
            "#<Count>"
         ],
         "Join": " ",
         "Break": true,
         "Translate": true,
         "Style": {
            "Size": "1.1em",
            "Color": "gray"
         }
      },
      ….
   ]
}

Einfache Kombination

Diese Bausteinvariante kann Bausteine kombiniert darstellen, die gemeinsame Daten beziehen oder beispielsweise nebeneinander dargestellt werden sollen.

Sollen Bausteine nebeneinander dargestellt werden, dann muss ein Style-Width mit 48 bis 50%, sowie ein Style-Float gesetzt sein.

Abb.: Bausteinvariante für eine einfache Kombination

Parameter	Hinweise
Data	Daten aus der Datenerweiterung, welche in Blocks angewendet werden sollen. Ist kein Data gegeben, werden nur die Hauptdaten des Objekts genutzt Achtung: In diesem Fall sollten die Daten aus einem `Expands` kommen, welches kein Array ist.
ID	Kenner des gesamten Blocks (Default: `Blocks`)

Parameter

Hinweise

Data

Daten aus der Datenerweiterung, welche in Blocks angewendet werden sollen.

Ist kein Data gegeben, werden nur die Hauptdaten des Objekts genutzt

Achtung: In diesem Fall sollten die Daten aus einem Expands kommen, welches kein Array ist.

Kenner des gesamten Blocks (Default: Blocks)

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel:

Nebeneinander dargestellte Bausteine

{
   "Data": "LinkObject",
   "Blocks":
   [
      {
         "ID": "LinkedHeader",
         "Type": "Text",
         "Value": "<Font_Bold>Linked Objects",
         "Translate": true,
         "Break": true,
         "Style":
         {
            "Size": "1.1em",
            "Color": "gray"
         }
      },
      {
         "ID": "LinkedTable",
         "Type": "Table",
         "Columns":
         [
            "<Font_Bold>Key",
            "Value"
         ],
         "Translate": true,
         "Join": "<br>"
      }
   ]
},

Text

Der Baustein Text wird für die Darstellung einzeiliger Texte oder Überschriften verwendet. Der Text kann als Hyperlink hinterlegt werden. Die URL dazu muss im Value angegeben sein.

Parameter	Pflichtfeld	Hinweise
Type	ja	Muss `Text` sein
ID	ja	Kenner
AsLink	nein	Bestimmt, ob der Text als Link dargestellt werden soll.
Value	ja	Array oder String; Kann Platzhalter auflösen
Translate	nein	Aktiviert die Übersetzung
Style	nein	Benötigt eine ID Zulässige Styles: `Color` Height Width Float BGColor Size Class
Break	nein	Aktiviert die Trennlinie unterhalb des Strukturtyps
Join	nein	Wird benötigt, wenn Value als Array genutzt wird.
ReplaceAs		Definiert einen Wert, der gesetzt werden soll, wenn der Platzhalter nach dem Ersetzen keinen Wert beinhaltet. Es ist möglich, ein Leerwert zu setzen. Standard: `-`

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Struktur-Code für den Baustein Text

{
   "ID": "ArticleHeader",
   "Type": "Text",
   "Value":
   [
      "<Font_Bold>Article",
      "#<Count>"
   ],
   "Join": " ",
   "Break": true,
   "Translate": true,
   "Style":
   {
      "Size": "1.1em",
      "Color": "gray"
  }
},

Richtext‌

Der Baustein Richtext ist die HTML-Variante zu Text. Hiermit können mehrzeilige Texte, aber auch Bilder, Tabellen oder HTML-Code eingefügt und dargestellt werden.

Parameter	Pflichtfeld	Hinweise
Type	ja	Muss `Richtext` sein
ID	ja	Kenner
Value	ja	Array oder String Kann Platzhalter auflösen
Translate	nein	Aktiviert die Übersetzung
Style	nein	Benötigt eine ID Zulässige Styles: Height Width Float BGColor Class
Join	nein	Wird benötigt, wenn `Value` als Array genutzt wird.

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Struktur-Code für den Baustein Richtext

{
   "ID": "ArticleBody",
   "Type": "Richtext",
   "Value": "<KIX_ARTICLE_BodyRichtext>"
}

Page

Mit dem Baustein Page können Sie die Seitenzahl angegeben. Die Seitenzahl kann als "Seite x" oder als "Seite x von y" dargestellt werden. Verwenden Sie Page vorzugsweise nur im Header oder Footer.

Parameter	Pflichtfeld	Hinweise
Type	ja	Muss `Page` sein
ID	ja	Kenner
PageOf	ja	Legt die Darstellungsart fest. 0 - Seite x 1 - Seite x von y
Translate	nein	Aktiviert die Übersetzung
Style	nein	Benötigt eine ID Zulässige Styles: Height Width Float Size Class

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Struktur-Code für den Baustein Page

{
   "ID": "Paging",
   "Type": "Page",
   "PageOf": 0,
   "Translate": true,
   "Style":
   {
      "Float": "right"
   }
}

Hinweis

Der Baustein Page und der Abschnitt Page haben nichts gemeinsam.

Der Baustein Page liefert eine Seitennummer, die man auf der Seite beliebig setzen kann.

Der Abschnitt Page ist die Einstellung aller Seiten des PDFs hinsichtlich Randabstand, Format, Ausrichtung usw. (s. Seiteneinstellung).

Image‌

Der Baustein vom Typ Image ermöglicht das Einfügen einzelner Bilder, die unabhängig von einem Richtext entstammen, wie z. B. ein Header-Logo. Es gibt folgende Möglichkeiten, wie das Bild ins Dokument gelangen kann:

Aus der KIX Datenbanktabelle (ObjectIcon)
Als Dateipfad vom Server (wo das KIX-Backend liegt)
Als übergebener Base64-Content.

Hinweis

Der ContentType muss immer image/[Dateityp] sein (z. B. image/png).

Parameter

Pflichtfeld

Hinweise

Type

Muss Image sein

Kenner

Value

Abhängig von Typen:

DB: ObjectID des Objects von ObjectIcon
Path: Sytempfad zum Bild (Platzhalter möglich)
Base64: Direkter Base64-Code im HTML-Image-Src-Style
Beispiel: 'data:image/png;base64,<Base64-Content>;'

TypeOf

Zulässige Typen:

DB
Path
Base64

Style

nein

Benötigt eine ID

Zulässige Styles:

Height
Width
Float
Class

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Baustein vom Typ Image

{
   "ID": "PageLogo",
   "Type": "Image",
   "Value": "agent-portal-logo",
   "TypeOf": "DB",
   "Style":
   {
      "Width": "2.5rem",
      "Height": "2.5rem",
      "Float": "left"
   }
},

Table‌

Mit dem Baustein Table können Informationen in Form von Tabellen dargestellt werden.

Als Beispiel dienen die Standard-Druckvorlagen für Ticket oder Artikel. Sie enthalten im Seitenkopf die Metadaten des jeweiligen Objekts (Bearbeiter, Ticketstatus usw.). Zur strukturierten Darstellung dieser Informationen wird der Baustein Table verwendet.

Abb.: Mit dem Baustein Table können Informationen in Tabellenform dargestellt werden

Beispiel:

Code-Struktur für die Tabellendarstellung

{
  "Columns": [
     "Key",
     "Value"
  ],
  "Type": "Table",
  "SubType": "KeyValue | DataSet | Custom | XMLStructure",
  ...
},

Hinweis

Da der Platz auf einem Blatt je nach Format und Ausrichtung begrenzt ist, sollten in den Tabellen nur notwendige Attribute angezeigt werden.

Bausteinvarianten (SubTypes)

Tabellen können große Datenmengen abbilden und das in unterschiedlicher Form. Um diese Daten abzubilden, gibt es folgende Bausteinvarianten, die unter SubType definiert werden:

KeyValue

Dieser Tabellentyp ist der Standard. Er wird eingesetzt, um die Attribute eines Objekts anzuzeigen. Ist in der Konfiguration kein SubType angegeben, dann wird KeyValue automatisch gesetzt.

Grundsätzlich ist KeyValue eine zweispaltige Tabelle, die die Daten des Objekts als Attributname (Key) und Attributwert (Value) gegenübersetzt. Dazu werden im Parameter Columns die Werte Key und Value hinterlegt. Durch Weglassen eines dieser Werte können Sie eine einspaltige Tabelle erzeugen, in der nur die Attributnamen oder nur die Attributwerte dargestellt werden.

Durch Angabe der Parameter allow und ignore können Sie den in der Tabelle anzuzeigenden Inhalt einschränken.

Durch zusätzliche Angabe von Count, können Sie der Tabelle eine Nummerierungs-Spalte hinzuzufügen.

Beispiel: Standard-Darstellung einer Tabelle (KeyValue ohne Count)

Key	Value
Attributname	Attributwert

{
  "Columns": [
     "Key",
     "Value"
  ],
  "Type": "Table",
  "SubType": "KeyValue",
  ...
},

Beispiel 2. Beispiel: Standard-Darstellung einer Tabelle mit Nummerierungsspalte (KeyValue mit Count)

Beispiel: Standard-Darstellung einer Tabelle mit Nummerierungsspalte (KeyValue mit Count)

Count	Key	Value
1	Attributname	Attributwert

{
  "Columns": [
     "Count",
     "Key",
     "Value"
  ],
  "Type": "Table",
  "SubType": "KeyValue",
  ...
},

Die Parameter Allow und Ignore

Die Parameter Allow (Erlaubt) und Ignore (Ignorieren) dienen dazu, Attribute einzuschränken. Sie beeinflussen somit den Informationsgehalt von Tabellen, die im PDF ausgegeben werden.

Beispiel: Allow bei Tabellentyp KeyValue

{
  "ID": "InfoTableLeft",
  "Type": "Table",
  "Include": "DynamicField",
  "SubType": "KeyValue",
  "Columns":
  [
    "<Font_Bold>Key",
    "Value"
  ],
  "Allow":
  {
    "State": "KEY",
    "Queue": "KEY",
    "Lock": "KEY",
    "CustomerID": "KEY",
    "Owner": "KEY",
    "Responsoble": "KEY",
    "Type": "KEY",
    "Priority": "KEY"
  },
},

Allow lässt Attribute zu und definiert somit eine Whitelist.
Es werden nur die benannten Attribute anzeigt.
Alle Attribute, die nicht im Allow angegeben sind, werden nicht in der Tabelle angezeigt.
Beispiel: Allow - Lässt folgende Attribute zu (Objekt ist Ticket)
```
[...],
"Allow": {
   "State": "KEY",      // lässt Attribut zu - egal was drin steht, da "KEY" gesetzt
   "Type": "^Prob.*"    // lässt Attribut nur zu, wenn der Ausdruck im Attributwert enthalten ist.
}
```
Ignore verweigert Attribute und definiert somit eine Blacklist.
Es werden die Attribute entfernt, welche es durch die Whitelist geschafft haben.
Ist kein Ignore gesetzt, entspricht das Endergebnis dem Ergebnis der Allow-Anwendung.
Ignore kann zusätzlich zu Allow eingesetzt werden. Der Aufbau entspricht dem von Allow, mit dem Unterschied, dass die angegebenen Attribute aus der Tabelle entfernt werden.
Zu beachten ist:
- Ist ein Allow für die Tabelle gesetzt, so wird das Ignore auf die Attibute angewendet, die durch Allow gefiltert wurden.
- Ist kein Allow gesetzt, so geht Ignore über alle Attribute und schränkt diese ein.
Beispiel: Ignore - verwirft die folgenden Attribute (Objekt ist Ticket)
```
[...],
"Ignore": {
   "State": "KEY",      // verwirft das Attribut - egal was drin steht, da "KEY" gesetzt
   "Type": "^Prob.*"    // verwirft das Attribut nur, wenn der Ausdruck im Attributwert enthalten ist.
}
```
Sind weder Allow noch Ignore definiert, werden alle Angaben aus den Objekten angezeigt.
Die Angabe eines leeren Hashes leert das vom Template vorgegebene Allow bzw. Ignore:
```
{
  "ArticleMeta": {}
}
```

DataSet

Mit der Bausteinvariante DataSet können die Datensätze zeilenweise in einer Tabelle angezeigt werden. Im Gegensatz zu KeyValue muss jedoch unter Columns festlegt werden, welche Attribute aus den Datensätzen dargestellt werden sollen.

Die angegebenen Attributnamen bilden die Tabellenspalten. Der jeweilige Datensatz befüllt anhand der gesetzte Spalte die Zellen mit den entsprechenden Werten.

Durch Angabe der Parameter allow und ignore können Sie den in der Tabelle anzuzeigenden Inhalt einschränken. Dabei werden aber nicht die einzelnen Attribute beeinflusst, sondern der gesamte Datensatz.

Beispiel:

Standard-Darstellung einer Tabelle

Attributname	[Attributname...]
Attributwert	[Attributwert...]

{  
  "Columns": [
    "AttributeX",
    "AttributeY",
    ...
  ],
  "Type": "Table",
  "SubType": "DataSet",
  ...
},

Die Parameter Allow und Ignore

Bei DataSet wirkt die Einschränkung auf den gesamten Datensatz und nicht auf einzelne Spalten. Das heißt:

Allow: Der Datensatz wird nur zugelassen, wenn alle zu prüfenden Werte der Attribute übereinstimmen.
Ignore: Der Datensatz wird nur ignoriert, wenn eines der zu prüfenden Werte der Attribute übereinstimmt.

Wichtig

Vermeiden Sie bei DataSet die Verwendung von Key bei Allow / Ignore. Prüfen Sie ausschließlich mit regulären Ausdrücken.

Allow - Lässt den folgenden Datensatz zu (Objekt ist Ticket)

[...],
"Allow": {
   "Type": "^Prob.*" 	// lässt den Datensatz nur zu, wenn der Ausdruck für das Attribut im Attributwert enthalten ist.
}

Ignore - verwirft den folgenden Datensatz (Objekt ist Ticket)

[...],
"Ignore": {
    "Type": "^Prob.*" 	// verwirft den Datensatz, wenn der Ausdruck für das Attribut im Attributwert enthalten ist.
},

Beispiel: Struktur-Code Tabletyp DataSet

{ 
  "ID": "Example",
  "Type": "Table",
  "Include": "DynamicField",
  "SubType": "DataSet",
  "Columns":
  [
    "AttributeX",
    "AttributeY"
    "AttributeZ"
  ],
  "Ignore":
  {
    "AttributeX": "Prob.*",
  }, 
},

Custom

Die Bausteinvariante Custom ist die flexibelste Variante hinsichtlich der Darstellung von Tabelleninhalten. Es können

mehrere Objektattribute in eine Zelle eingetragen werden
eine beliebige Anzahl an Spalten und Zeilen definiert werden
Hinweis
Zu viele Spalten werden beim Druck abgeschnitten, da diese über den Rand hinaus ragen.
objektbezogene KIX-Platzhalter verwendet werden
Beispiel für Object.Attribute.Value: Ticket.Status.Value oder Ticket.DynamicField_xyz.Value

Eine Einschränkung mit Allow bzw. Ignore ist nicht möglich, da dieser Tabellentyp frei wählbaren Inhalt besitzt. Somit kann nicht bestimmt werden, was zulässig ist oder ignoriert werden soll.

Tipp

In der von KIX ausgelieferten Druckvorlage wird dieser Bausteinvariante für die Anzeige der Daten im Block Customer Information verwendet.

Sie können den Aufbau der Tabelle frei gestalten, indem Sie die Tabelle ähnlich einer verschachtelten Liste im HTML bilden.

Der Parameter Columns definiert die Spalten der Tabelle. Die Angabe der Spaltenüberschrift ist optional. Ist kein Spaltenname angegeben, muss ein Leerstring für die jeweilige Spalte definiert sein. Mit den Platzhaltern <Class_...> kann eine CSS Klasse an einer Spalte/Zelle hinterlegt werden, welche im Style unter Angabe der Klasse konfiguriert wird. Sie können auch vordefinierte Platzhalter <Font_...> anwenden, z. B. <Class_Col1><Font_Bold> (s. auch: Zusätzliche Hinweise).

Der Parameter Rows definiert die einzelnen Zeilen in den jeweiligen Spalten und deren Inhalte. Der Parameter Rows ist eine verschachtelte Liste, wobei der erste Index die Zeile und der zweite Index die jeweilige Spalte ist. Rows beinhaltet nicht die Spaltenüberschriften, sondern nur den Tabelleninhalt.

Beispiel: Nur Angabe von Rows

[...],
"Rows": [
    [
      "Zeile1Spalte1"
      "Zeile1Spalte2"
    ],
    [
      "Zeile2Spalte1"
      "Zeile2Spalte2"
    ]  
]

Beispiel: Gemeinsame Angabe von Columns und Rows

[...],
"Columns": [
    "Spalte1",
    "Spalte2"
],
"Rows": [
    [
      "Zeile1Spalte1"
      "Zeile1Spalte2"
    ],
    [
      "Zeile2Spalte1"
      "Zeile2Spalte2"
    ] 	
]

Beispiel: Tabellentyp Custom (komplett)

{
  "Type": "List",
  "Object": "Contact",
  "Data": "Contact",
  "Expand": "DynamicField",
  "Blocks":
  [
    {
      "ID": "Contact",
      "Type": "Table",
      "SubType": "Custom",
      "Include": "DynamicField",
      "Columns":
      [
        "<Class_Col1><Font_Bold>",  //Spalte 1 in Fettschrift
        ""                            //Spalte 2
      ],
      "Rows":
      [
        [
          "Contact",
          "Contact.Fullname.Value"
        ],
        [
          "Phone",
          "Contact.Phone.Value"
        ],
        [ 
          "Mobile",
          "Contact.Mobile.Value"
        ]
      ],
      "Translate": true,
      "Style":
      {
        "Class":
        [
          {
            "Selector": ".Col1", //Formatierung für Spalte 1 (s. "Columns")
            "CSS": "width: 20%;"
          }
        ]
      }
    }
  ]

}

Der Code in diesem Beispiel erzeugt folgende Tabelle. Die Breite der 1. Spalte beträgt 20%. Die Werte werden beim Druck durch die reellen Werte ersetzt.

`Contact`	`Contact.Fullname.Value`
`Phone`	`Contact.Phone.Value`
`Mobile`	`Contact.Mobile.Value`

XMLStructure

Die Bausteinvariante XMLStructure ist nur in Kombination mit dem Objekt Asset nutzbar. Sie erzeugt eine Tabelle, die ähnlich der Asset Detailansicht ist.

Zu beachten ist:

Einstellungen mit Columns und Rows sind nicht möglich.
Im Konfigurationsblock muss als Data immer XMLStructure gesetzt sein.
Einschränkungen mittels allow oder i gnore sind nicht möglich.
Attribute ohne Werte werden nicht angezeigt.
Einrückungen und Formatierung können anhand von CSS-Klassen beeinflusst werden.
- Nur die erste Spalte wird beeinflusst
- Die jeweilige Ebene (Nummer) bestimmt die Endung der CSS-Klasse
- Attribute mit dem Inputtyp Dummy haben als Klassenprefix DL
- Alle anderen Attribute haben den Klassenprefix PL
- Wenn kein CSS hinterlegt ist, greift das CSS der Standard-Tabelleneinstellung.

Beispiel: Struktur des Tabellentyps XMLStructure

{
   "ID": "AssetVersionMeta",
   "Type": "Table",
   "SubType": "XMLStructure",
   "Data": "XMLStructure",
   "Translate": true,
   "Style": {
      "Class": [
         {
            "Selector": " .DL0",
            "CSS": "padding: 0.625rem 0; font-weight: bold;"
         },
         {
            "Selector": " .DL1",
            "CSS": "font-weight: bold; padding: 0.625rem 0 0.625rem 0.313rem; color: gray;"
         },
         {
            "Selector": " .DL2",
            "CSS": "font-weight: bold; padding-left: 0.625rem 0 0.625rem 0.625rem; color: gray;"
         },
         {
            "Selector": " .DL3",
            "CSS": "font-weight: bold; padding-left: 0.625rem 0 0.625rem 0.938rem; color: gray;"
         },
         {
            "Selector": " .DL4",
            "CSS": "font-weight: bold; padding-left: 0.625rem 0 0.625rem 1.25rem; color: gray;"
         },
         {
            "Selector": " .DL5",
            "CSS": "font-weight: bold; padding-left: 0.625rem 0 0.625rem 1.563rem; color: gray;"
         },
         {
            "Selector": " .PL1",
            "CSS": "padding-left: 0.313rem;"
         },
         {
            "Selector": " .PL2",
            "CSS": "padding-left: 0.625rem;"
         },
         {
            "Selector": " .PL3",
            "CSS": "padding-left: 0.938rem;"
         },
         {
            "Selector": " .PL4",
            "CSS": "padding-left: 1.25rem;"
         },
         {
            "Selector": " .PL5",
            "CSS": "padding-left: 1.563rem;"
         }
      ]
   }
}

Parameter des Strukturtyps "Table"

Parameter	Pflichtfeld	Hinweise
ID	ja	Kenner der Tabelle
Type	ja	Angabe des Blocktyps. Muss `Table` sein
SubType	ja	Definiert den konkreten Tabellen-Typ Mögliche Tabellen-Typen: `KeyValue`: Schlüssel-Wert-Paar (Standard) `DataSet`: Angabe eines Datensatzes z. B. Name und Daten eines Dynamischen Feldes `Custom`: Flexible Darstellung z. B. Freitext oder mehrere Attribute in einer Zeile `XMLStructure`: Fixierte Darstellung von Asset-Attributen Nur in Kombination mit Objekt-Typ Asset möglich. Je nach gewähltem SubType stehen unterschiedliche Parameter zur Verfügung (s. auch: Verfügbarkeit der Parameter je SubType
Allow	nein	Liefert ein Hash mit Attributen die je Variante das Attribute oder den Datensatz in der Tabelle darstellt. (Whitelist)
Ignore	nein	Liefert ein Hash mit Attributen die je Variante das Attribute oder den Datensatz nicht in der Tabelle darstellt. (Blacklist)
Columns	ja (vom SubType abhängig)	Angaben der Spalten je Variante
Rows	ja (vom SubType abhängig)	Nur für Tabellentyp `Custom` Definiert den Tabelleninhalt zeilen- und spaltenweise
Include	nein	Fügt ein `Expand` in die Hauptdaten nur für diese Tabelle hinzu. Achtung: Der `Expand` sollte vorher vom Objekt geholt worden sein.
Translate	nein	Wenn aktiviert: Übersetzt den Spalteninhalt und den Spaltenkopf
Style	nein	Benötigt eine ID Zulässige Styles: Height Width Float Class
Headline	nein	Aktiviert den Spaltenkopf `false`: inaktiv `true`: aktiv
ReplaceAs	nein	Definiert einen Wert, der gesetzt werden soll, wenn die Platzhalter nach dem Ersetzen keinen Wert beinhaltet. Standard: `-` Es ist auch möglich, ein Leerwert zu setzen.
ReplaceKey	nein	Ändert die internen Schlüsselbezeichnung mit übersetzbaren Anzeigenamen. Nur möglich mit dem Tabellentyp `KeyValue`. Die ersetzbaren Schlüsselbezeichnungen sind aktuell fest im System hinterlegt.

Siehe auch:

Die Parameter und ihre Bedeutung

Verfügbarkeit der Parameter je SubType

Parameter	KeyValue	DataSet	Custom	XMLStructure
ID	✓	✓	✓	✓
Type	✓	✓	✓	✓
SubType	✓	✓	✓	✓
Allow	✓	✓
Ignore	✓	✓
Columns	✓	✓	✓
Rows			✓
Include	✓	✓	✓	✓
Translate	✓	✓	✓	✓
Style	✓	✓	✓	✓
Headline	✓	✓	✓	✓
ReplaceAs			✓
ReplaceKey		✓	✓	✓

List

Mit dem Baustein List können Aufzählungen mit oder ohne vorangestellte Aufzählungspunkte abgebildet werden. Die Anzahl der aufzulistenden Daten kann unabhängig der gelieferten Daten eingeschränkt werden.

Abhängig von den anzuzeigenden Daten ist es möglich, dass nicht alle Datensätze belegt sind. Dann wird der Eintrag nicht angezeigt, was in bestimmten Fällen die Darstellung beeinflusst. Daher können Einträge, die keinen Wert haben, auch als Leerzeile angezeigt werden.

Parameter	Pflichtfeld	Hinweise
Type	ja	Muss `List` sein
ID	ja	Kenner
Data	ja	Beinhaltet die Daten aus einer Datenerweiterung. So werden bspw. genutzt: für Assets: XMLContent (Hash) für Tickets: Contact (Array)
Object	(ja)	Objekt, welches in den darunter liegenden Strukturen genutzt werden soll.
ListObject	(ja)	Objekt welches in den darunter liegenden Strukturen genutzt werden soll. Nur möglich, wenn `ListData` gesetzt ist und die Daten darin einem anderem Objekt unterliegen als das angegebene `Object`.
ListData	(ja)	Beinhaltet den Parameternamen, der in `Data` die Daten für die Auflistung enthält. Wenn unter `Data` ein Hash angegeben ist, muss in `ListData` ebenfalls ein Hash angegeben sein Wenn unter `Data` ein Array angegeben ist, dann ist die Angabe von `ListData` nicht erforderlich `Data` muss ein Hash sein, wenn Array, dann ist ListData nicht notwendig
ListCount	nein	Definiert eine maximale Anzahl von Listeneinträgen die angezeigt werden sollen. Ist die Anzahl der Datensätze kleiner als die maximale Anzahl, werden diese aufgefüllt, sofern `ShowEmpty` aktiv ist.
ListStyle	nein	Definiert den Stil der Liste Folgende Typen sind möglich: `ul`: nicht geordnete Liste (symbolisch) `ol`: geordnete Liste (numerisch) `none`: keine führenden Listenpunkte
ShowEmpty	nein	Zeigt Leerzeilen an, wenn beim Datensatz kein Wert vorhanden ist. Kann kombiniert werden mit `ListCount`.
Value	ja	Beinhaltet den Wert der pro Datensatz angezeigt werden soll. Erwartet Array oder String Wird dies als Array aufgebaut, werden alle Einträge kombiniert und in einer Zeile dargestellt. Kombinierbar mit `Join` Kann Platzhalter auflösen
Join	nein	Definiert, wie die Werte aus `Value` zusammengesetzt werden sollen.
ReplaceAs	nein	Definiert einen Wert, der gesetzt werden soll, wenn Platzhalter nach dem Ersetzen keinen Wert beinhalten. Standard: `-` Sie können auch einen Leerwert setzen.
Translate	nein	Aktiviert die Übersetzung
Style	nein	Benötigt eine ID Zulässige Styles: Height Width Float Size Class

Siehe auch:

Die Parameter und ihre Bedeutung

Beispiel: Struktur-Code für den Baustein List

{
   "ID": "Contact",
   "Type": "List",
   "Data": "XMLContents",
   "ListData": "SectionContacts::1::OwnerContact",
   "ListObject": "Contact",
   "ListCount": 4,
   "ShowEmpty": 1,
   "ListType": "none",
   "Translate": true,
   "Value": [
      "Contact.Title.Value",
      "Contact.Fullname.Value"
   ],
   "ReplaceAs": "",
   "Join": "&nbsp;",
   "Style": {
      "Width": "100%",
      "Float": "left",
      "Class": [
         {
            "Selector": " ",
            "CSS": "margin-bottom: 0.5rem;"
         },
         {
            "Selector": " > li",
            "CSS": "font-family:arial; font-size:28pt; "
         }
      ]
   }
}

Die Parameter und ihre Bedeutung

Parameter

erwarteter Datentyp

Bedeutung

Object

String

Ist das Objekt, welches die Daten aufbereitet und bereitstellt.

Für die Aufbereitung wird - abhängig vom Objekt - eine ID, Name oder Nummer benötigt.

Expands

Array | String

Mit diesem Parameter kann die Datenmenge des Objekts um weitere Daten erweitert werden.

Je Objekt sind unterschiedliche Expands möglich.

Abhängig des Expands wird entweder eine Datenerweiterungen oder eine ID-Liste bereitgestellt.

Data

String

Wird nur von den Bausteinen Blocks und List unterstützt.

Hiermit können explizit nur die Daten genutzt werden, die per Expands angefordert wurden.

Es ist zu beachten, dass das die Daten des übergeordnetem Objekt-Expands sind und nicht des Objekts, welches aufgebaut wird.

Allow

Hash

Whitelist für den Baustein Table vom Typ KeyValue und DataSet.

Je nach Tabellentyp werden auch die darin genutzten Daten entsprechend gefiltert.

Wird beispielsweise nur ein KeyValue-Typ genutzt, können damit nur bestimmte Attribute zugelassen werden.

Wird stattdessen nur der Attribut-Typ genutzt, können nur bestimmte Datensätze zugelassen werden - sofern die Werte der zu prüfenden Attribute stimmen.

Es gibt zwei Wertprüfungen die angewendet werden können:

KEY Zulassen des Eintrags ohne direkte Prüfung des Attributes
Prüfwert Ein Wert, der mit dem Wert des Parameters gegengeprüft werden soll (RegEx möglich)

Ignore

Hash

Blacklist für den Baustein Table vom Typ KeyValue und DataSet.

Abhängig von der vorliegenden Tabellenstruktur werden auch die darin genutzten Daten entsprechend gefiltert.

Wird beispielsweise nur ein KeyValue-Typ genutzt, können damit bestimmte Attribute ignoriert werden.

Wird stattdessen der Attribut-Typ genutzt, können bestimmte Datensätze weggelassen werden - sofern die Werte der zu prüfenden Attribute übereinstimmen.

Es gibt zwei Wertprüfungen, die angewendet werden können:

KEY Auslassen des Eintrags ohne direkte Prüfung des Attributes
Prüfwert Ein Wert, der mit dem Wert des Parameters gegengeprüft werden soll (RegEx möglich)

Columns

Array

Ein Parameter für den Baustein "Table".

Mit diesem Parameter kann festgelegt werden, wie die Tabelle aufgebaut werden soll. Dabei wird unterschieden zwischen den Typen:

KeyValue Angabe des Parameters als Schlüssel-Wert-Paar.
Das heißt: In der Tabelle wird pro Spalte der Schlüsselname als Key und der Wert als Value angegeben.
```
'Columns' => [
   '<Class_Key><Font_Bold>Key',
   'Value'
 ],
```
Attribute Definiert, welches Attribut in welcher Spalte angezeigt werden soll

Info: KeyValue und Attribute sind hier nur indirekte Bezeichnungen zum Verdeutlichen.

Rows

ArrayOfArrays

Ein Parameter für den Baustein Table und dem Tabellentyp Custom.

Mit diesem Parameter kann der Inhalt der Tabelle festgelegt werden. Dieser Parameter steht in Kombination mit Columns.

'Rows' => [
   [
     'Title',
     'Contact.Title.Value',
     'Phone',
     'Contact.Phone.Value'
  ],

Headline

Boolean

Aktiviert die Kopfzeile der Tabelle und zeigt die unter Columns hinterlegten Einträge an.

String

Ist der Kenner des jeweiligen Bausteins.

Sichert ab, dass das gesetzte Style nur den betreffenden Baustein beeinflusst.

In Tabellen mit der angegebenen ID kann die Verwendung von Allow oder Ignore das in der jeweiligen Tabelle inital definierte Allow oder Ignore überschreiben.

Translate

Boolean

String

Aktiviert die Übersetzung.

Style

Hash

Definiert die Darstellung des jeweiligen Bausteins. Nicht jeder Style-Typ findet in jedem Baustein Anwendung.

Achtung: Für eine gute Darstellung, sollten im Style möglichst nur die Maßangaben %, em oder rem angegeben werden.

Width (%, rem, em): Beeinflusst die Breite des Strukturtyps. Geben Sie möglichst nur Prozentwerte an (z. B.: 50%)
Height (rem, em): Höhe eines Strukturtyps
Size (rem, em): Schriftgröße
Float (right, left): Ausrichtung des Strukturtyps
Color (Hex, Farbname): Schriftfarbe
BGColor (Hex, Farbname): Hintergrundfarbe
Class (ArrayOf Hash): Klassenspezifisches CSS

Join

String

Mit Join können Textpassagen kombiniert werden, wenn beim Baustein Text als Value ein Array genutzt wird.

Break

Boolean

Setzt eine Trennlinie unterhalb des Bausteins Text.

Value

Array | String

Werte, die im jeweiligen Baustein angezeigt werden sollen (Platzhalter-Ersetzung möglich).

Nicht für Strukturtyp Table geeignet.

'Value' => 'Ticket.Title.Value'

'Value' => [
   '<Font_Bold>Customer Information'
]

Dieser Parameter kann sowohl als Array oder String genutzt werden.

Hintergrund für das Array ist, dass nicht immer vollständige Texte übersetzt sind oder in Kombination mit Inhalten aus Platzhaltern diese Inhalte nicht existieren. Dadurch können die einzelnen Passagen mit Join kombiniert und vorher einzeln übersetzt (Translate) werden.

Type

String

Ist der Baustein (wie Table, Text, Richtext usw.)

SubType

String

Ist der Tabellentyp (wie Custom, KeyValue, DataSet usw.)

PageOf

Boolean

Ist Teil des Bausteins Page. Legt fest, ob "Seite X von Y" oder nur die Seitennummer angezeigt werden soll.

TypeOf

String

Ist Teil des Bausteins Image. Legt fest, was mit dem Wert aus dem Parameter Value geschehen soll.

DB Sucht anhand der "ObjektID" in der Datenbank-Tabelle "ObjectIcon" nach einem Bild.
Path Sucht lokal auf dem Server nach einem Bild. Fügt dieses anschließend als Base64 der Struktur hinzu.
Base64 Übergibt dem Strukturtyp einen Base64-String (z. B. ein Bild).

Hinweis: Es sollte die HTML-Schreibweise genutzt werden (data:<ContentType>; base64,<base64Content>)

AsLink

Boolean

Definiert, dass der Baustein als Hyperlink dargestellt wird.

Nur für Baustein Text anwendbar.

Achtung: Wenn angegeben, dann sollte auch eine URL als Value hinterlegt werden.

ReplaceKey

Boolean

Ändert die internen Schlüsselbezeichnung mit übersetzbaren Anzeigenamen.

Nur möglich mit dem Tabellentyp KeyValue.

Die ersetzbaren Schlüsselbezeichnungen sind aktuell fest im System hinterlegt.

ReplaceAs

String

Definiert einen Wert, der gesetzt werden soll, wenn ein Platzhalter nach dem Ersetzen keinen Wert beinhaltet.

Standard: -

Es ist möglich, einen Leerwert zu setzen. Dies gilt für alle Platzhalter, die im Valueangewendet wurden.

ListObject

String

Definiert das Objekt, welches die Daten aufbereitet und bereitstellt.