Office-Berichte (Word, Excel, PDF)

Vertec stellt einen office-basierten, cloudfähigen Berichtgenerator zur Verfügung.

Die Vertec Office-Berichte bestehen aus der Kombination einer Word- oder Excel-Vorlage für die Layout-Struktur sowie einer Bericht-Definition in Form von Python Code für die Generierung des Inhalts.

Übersicht

• Registrierung der Office-Berichte
• Aufbau der Word-Vorlagen
• Aufbau der Excel-Vorlagen

Um einen Vertec Office-Bericht zu erstellen, muss er registriert werden. Dabei wird die Word- oder Excel-Vorlage hinterlegt und als Bericht-Definition der dazugehörige Python Code eingefügt.

Das Vorgehen ist im Artikel Berichte registrieren detailliert beschrieben.

Der Dateninhalt des Berichts wird berechnet durch Python-Code, welcher als Berichts-Definition hinterlegt ist. Wie dieser Code genau aufgebaut wird, ist im Artikel Python-Code für Office-Berichte detailliert beschrieben.

Soll die Ausgabe in Word bzw. PDF erfolgen, wird dafür ein Word-Dokument (.docx) als Vorlage hinterlegt.

Alles, was gedruckt wird, befindet sich in sogenannten Bands.

Ein Band wird in der Berichtsvorlage durch eine Textmarke dargestellt. Der Name der Textmarke ist der Band-Name. Erstellen Sie dort, wo Sie ein Band erstellen möchten, einen Beispiel-Text im gewünschten Layout (z.B. eine Tabelle, Zeilen mit Tab etc.). Markieren Sie dann diesen Text und klicken Sie auf Einfügen - Textmarke....

Es öffnet sich das Fenster, in dem Sie den Namen der Textmarke angeben können. Es empfiehlt sich, dabei einen Namen zu wählen, bei dem erkennbar ist, worum es sich handelt (also nicht Band1, Band2 etc.). Das erleichtert später das Anpassen der Bänder und der Ausdrücke in den Expressions.

Die Bänder können frei verschachtelt werden. Jede Berichtsvorlage hat mindestens ein Haupt-Band, welches über alles geht. Sie können also, nachdem Sie die Vorlage erstellt haben, alles markieren und mit einer Textmarke umschliessen. Ein Band wird bei der Ausführung eines Berichts ein- oder mehrmals gedruckt, je nachdem, ob es sich um ein einzelnes Objekt oder um eine Liste handelt. In diesem Fall wird das Band so viel mal gedruckt, wie sich Elemente in der Liste befinden.

Die einzelnen Bands werden durch Band-Expressions gesteuert, welche sich in einer durch einen Kommentar markierte Textstelle befinden. Die Syntax ist dabei wie folgt:

• Der markierte Text beginnt mit dem Namen des Bands, auf welches sich die Expression bezieht, gefolgt von Exp, Cond oder Locale, je nachdem, um welche Art von Expression es sich handelt (siehe unten).
• Die Referenz auf den Code wird mit :name angegeben. Dabei handelt es sich um den Feldnamen des entsprechenden TableFields.

Als Band-Expression wird also zum Beispiel bndSpesenExp:spesen geschrieben, dieser Text markiert und mit einem leeren Kommentar versehen:

Im Code enthält das Schlüsselwort spesen dann die gewünschten Objekte, welche im Band dargestellt werden sollen. Es sind folgende Band Expressions möglich (bndXXX bedeutet dabei der Name des Bandes):

1. bndXXXExp: Band Hauptexpression. Falls angegeben, wird der Wert des Bandes aufgrund dieser Expression berechnet. Die Expression bezieht sich auf das Root-Objekt des Berichts oder auf den Wert des nächst äusseren Bandes.Falls das Ergebnis dieser Expression einer Liste entspricht, wird das Band für jeden Eintrag der Liste dupliziert.
2. bndXXXCond: Band Conditional Expression. Falls angegeben, wird diese Expression bei jedem Auftreten des Bandes ausgewertet (d.h. falls das Band innerhalb einer Liste dupliziert wird, für jedes Objekt). Damit das Band gedruckt wird, muss das Ergebnis der Expression True sein:
   • Bei Boolean-Werten (Wahr/Falsch) muss das Ergebnis True sein.
   • Bei Integer-, Currency- und Minutenwerten muss das Ergebnis <> 0 sein.
   • Bei String-Werten muss das Ergebnis <>'' sein, also kein Leerstring.
   • Datums- und Bildwerten muss das Ergebnis <> null sein.
   • Generell gilt: not null = True, null = False.
   • Handelt es sich um Tabellen-Felder (TableFields), kann direkt der Name des Feldes angegeben werden. Ist die Tabelle leer, wird das Band nicht angedruckt, z.B. bndHasSpesenCond:spesen, wobei spesen der Name des TableFields ist.
     Möchte man ein Tabellen-Band andrucken, wenn es keine Einträge hat (z.B. für einen Hinweis, dass keine Einträge gefunden wurden), kann die Expression mit not und dem Feld-Namen umgekehrt werden: bndNoSpesenCond:not spesen.
   • Als Cond-Expression kann auch eine Context-Expression angegeben werden (ab Version 6.2.0.5). Die Syntax ist wie folgt: bndXXXCond:context:variablenname.

     

     Ein Band kann nicht gleichzeitig Exp- und eine Cond-Expression haben. Falls beides gewünscht ist, müssen zwei Bands gemacht werden, wobei das Cond-Band das Exp-Band umschliesst.

3. bndXXXLocale: Zahlenwerte werden nach den lokalen Regionaleinstellungen formatiert. Mit Locale-Expressions können alle Zahlenwerte innerhalb des Bands nach anderen Ländereinstellung formatiert werden. Für die Steuerung gibt es dabei zwei Möglichkeiten:

   Eine Tabelle mit den Ländercodes finden Sie unter: https://msdn.microsoft.com/de-de/library/ee825488(v=cs.20).aspx

   1. Es wird eine Referenz auf den Code angegeben, welcher als Ergebnis einen Ländercode enthält. Im Code wird dafür in der entsprechenden Table ein OclTextField mit dem angegebenen Namen (hier im Beispiel locale) eingefügt:

      

      Resultat der angegebenen OCL-Expression muss ein Ländercode sein. Dieser kann entweder direkt angegeben werden, wie hier oben im Beispiel ("de-DE"), oder z.B. aus einem Feld ausgelesen werden: OclTextField("locale", "projekt.zusatzfeldasstring('locale')").
   2. Der Ländercode wird direkt angegeben, z.B.  bndSpesenLocale:de-DE

Textmarken, die nicht gelöscht werden

Textmarken, deren Name mit trg oder src beginnt, werden vom Vertec Bericht-Mechanismus nicht gelöscht. Wenn Sie also in Ihrem Dokument Textmarken benötigen, die auch nach dem Ausführen bestehen bleiben, nennen sie diese trgXXX oder srcXXX.

Band-Definitionen

Bands über Dokumenthierarchiestufen hinweg

Anfang und Ende eines Bands müssen sich immer auf gleicher (Hierarchie-)Ebene befinden.

Wenn sich z.B. ein Band-Start am Ende eines Absatzes, welcher Text enthält, befindet, aber nur die Absatzmarke umfasst, ist das eigentlich nicht gültig. Damit der Bericht trotzdem funktioniert, wird der Band-Start interpretativ nach vorne an den Beginn des nächsten Elements (Absatz oder Tabelle) geschoben, falls das Band-Ende am Ende einer Tabellenzeile oder eines Absatzes ist:

Diese automatische Anpassung führt dazu, dass ein Absatzwechsel weniger dargestellt wird. Dies ist im Output sichtbar.

Solche Bands sollten nach Möglichkeit nicht definiert werden, sondern möglichst immer ganze Abschnitte oder Start und Ende innerhalb des Textes als Band definiert werden.

Befindet sich der Start des Bands sogar mitten im Absatztext, wie in der folgenden Abbildung dargestellt, dann erscheint eine Fehlermeldung betreffend ungültiger Band-Definition.

Generell:

Beginn und Ende von Textmarken lassen sich ab besten über das Menü Einfügen > Textmarke > bndName -> gehe zu einsehen.

Ununterscheidbare Varianten

Es gibt Fälle von Band-Definitionen, welche vom Code nicht unterschieden werden können, obwohl sie in Word visuell unterscheidbar sind.

Dies ist zum Beispiel dann der Fall, wenn eine Textmarke am Schluss eines leeren Absatzes endet, welcher auf eine Tabelle folgt:

In diesem Fall befindet sich das Band-Ende innerhalb des leeren Absatzes. Endet das Band aber am Ende der Tabelle, enthält den leeren Absatz also nicht, dann befindet sich das Bookmark-Ende ebenfalls im darauffolgenden Abschnitt.

Bookmark-Enden in einem sonst leeren Absatz werden deshalb immer als Ende der vorangehenden Tabelle interpretiert.

Soll ein leerer Absatz nach einer Tabelle explizit zum Band gehören, kann dies erreicht werden, indem im Absatz irgendein Text (z.B. ein Leerzeichen) eingefügt wird. Dann wird der Absatz als zum Band zugehörig interpretiert.

Bands, die in einer leeren Tabellenzeile beginnen

Wenn ein Band am Anfang einer leeren Tabellenzeile beginnt, dann muss in dieser Tabellenzeile mindestens ein Leerzeichen eingefügt werden:

Ansonsten erscheint eine Fehlermeldung der Art: Invalid overlapping bands bndXY and bndYZ.

Ein Feld ist ein durch einen Kommentar markierter Text innerhalb eines Bandes, der beim Ausführen des Berichts durch Daten aus Vertec ersetzt wird. Der markierte Text enthält dabei die Referenz auf die im Python-Code definierten Felder. Der Kommentar selbst ist leer oder enthält das Schlüsselwort translation, um die Übersetzung für dieses Feld zu aktivieren.

Um ein solches Feld zu erstellen, fügen Sie an der Stelle, wo später die Daten aus Vertec eingefügt werden sollen, das Schlüsselwort ein, und klicken Sie auf Überprüfen - Neuer Kommentar.

Es können auch OCL-Members angegeben werden. Dabei muss auf die Gross-/Kleinschreibung geachtet und eine Businessklasse angegeben werden. Diese wird in der Deklaration der Tabelle mittels businessclass= angegeben.

Mit dem Präfix sum: können Feldwerte summiert werden. Im folgenden Beispiel werden die Werte des Feldes wertext der Table leistungen summiert:

sum:leistungen.wertext

Summenfelder können auch Summen über mehrere Table-Hierarchien darstellen:

Als Beispiel gibt es auf einem Spesen-Bericht eine Table, welches eine Gruppierung nach Spesentypen macht (Name der Table: spesentypen) und darauf eine Sub-Table mit der Liste der Spesen für diesen Typ (Name der Sub-Table: spesen).

Möchte man nun ausserhalb des Spesentypen-Bands die Summe aller Spesen ausgeben, geht das mit folgender Expression:

sum:spesentypen.spesen.wertext

Dieses Feld muss sich ausserhalb der ersten durch die Summe referenzierten Table befinden, an einem Ort, wo auch die Table Expression erlaubt wäre und die Table liefern würde.

Mittels sogenannten Context-Expressions können Variablen direkt auf dem Bericht-Context ausgegeben werden, ohne dass dafür extra ein Feld auf einer Table-Definition eingeführt werden muss.

Eine Context-Expression ist durch den Präfix context: gekennzeichnet und referenziert eine Context-Variable des Berichts. Beispiel:

context:stichdatum

Der Datentyp des Feldes richtet sich nach dem Wert der Context-Variable. Falls es sich bei der Context-Variable um eine Objekt-Referenz oder eine Liste handelt, gibt die Context-Expression als Wert einen String (String-Representation) zurück.

Möchte man also beispielsweise im Titel einen Bericht-Parameter angeben, z.B. das Stichdatum einer Auswertung, kann das direkt über die Context-Expression angegeben werden.

Context-Expressions in Kopf- und Fusszeilen

Da in Kopf- und Fusszeilen Kommentare nicht verfügbar sind, werden die Variablen hier in doppelt geschweifte Klammern geschrieben, z.B.:

{{context:stichdatum}}

Um ein Feld zu übersetzen, wird als Kommentar das Schlüsselwort translation eingetragen. Der Übersetzungsmechanismus schaut dann in der Übersetzungsdatei nach dem Begriff und setzt, falls vorhanden, die entsprechende Übersetzung ein.

Das setzt voraus, dass Begriffe, die ausschliesslich im Bericht verwendet werden (zum Beispiel der Bericht-Titel) in die Übersetzungen eingefügt werden.

Übersetzungen in Kopf- und Fusszeilen

In Kopf- und Fusszeilen von Office-Berichten können Translations in doppelten geschweiften Klammern geschrieben werden, z.B.

{{Translation:Page}} X {{Translation:of}} XX

Bilder aus der Datenbank (wie ImageData bei Word-Berichten) werden im Python Code als ImageField bzw. OclImageField deklariert. Im Bericht-Dokument können sie als normale Datenfelder (kommentierter Text) eingefügt werden. Es wird auch die Verwendung von PDF Dokumenten als Bild unterstützt, wobei die Vorschau der ersten Seite angezeigt wird.

Die Angabe eines Bilder-Pfades ist nicht möglich.

Um die dargestellte Grösse der eingefügten Bilder in Word zu steuern, empfiehlt es sich, diese in einer Tabelle anzuzeigen wie in den gezeigten Beispielen. Die Skalierung in der Tabelle verhält sich wie folgt:

Die eingefügten Bilder werden nicht hochskaliert, weder horizontal noch vertikal. Die Bilder werden aber bei Bedarf runterskaliert:

• Ist ein Bild breiter als die Tabellenzelle, wird es runterskaliert, wenn die automatische Grössenanpassung der Tabelle ausgeschaltet ist.
• Wenn ein Bild höher als die Tabellenzeile ist, wird die Zeile vergrössert, ausser für die Zeilenhöhe wurde in den Tabelleneigenschaften ein genauer Wert gesetzt. Ist für die Zeilenhöhe ein genauer Wert gesetzt und die automatische Grössenanpassung ausgeschaltet, so wird das Bild runterskaliert, damit es in die Zelle passt.

Hier nachfolgend eine Übersicht über die Skalierungen:

Als HTML-formatierter Text z.B. aus Textbausteinen wird im Python Code als TextField bzw. OclTextField deklariert. Im Bericht-Dokument wird er mit dem Präfix html: eingefügt.

Beispiel Felddeklaration:

 OclTextField('textbaustein', "zusatzfeldobj('textbaustein').oclAsType(Textbaustein).text"),

In der Vorlage:

Der Wert wird als formatierter HTML-Text interpretiert und das Ergebnis in den Bericht geschrieben.

Es werden (mit einigen vermerkten Ausnahmen) die im Artikel Textbausteine beschriebenen Elemente unterstützt, auch innerhalb des HTML berechnete OCL-Expressions.

Office-Berichte können ab Vertec 6.3 auch im Excel-Format ausgegeben werden. Der zugrunde liegende Python-Code ist dabei derselbe wie bei Word-Berichten; die beiden Formate unterscheiden sich nur durch die Vorlage.

Bands

Um ein Band zu setzen, markieren Sie die entsprechenden Zellen und fügen im Feld oben links den Bandnamen ein.

Es gibt immer ein Main-Band, welches alles umfasst und sich auf das Hauptobjekt bezieht, also die Haupttable enthält.

Die anderen Bänder und Sub-Bänder werden gleich gesetzt: Zellen markieren und oben links den Namen einfügen:

Wichtiger Hinweis: Achten Sie beim Setzen der Bänder darauf, dass nicht die gesamten Zeilen (hinten rechts bis unendlich) markiert sind, sondern nur die Zellen, die tatsächlich benötigt werden. Sonst dauert der Aufbau des Berichts länger, da Vertec durch alle Zellen iterieren muss, um herauszufinden, ob irgendwo ein Wert gesetzt ist.

Um ein Band zu löschen, öffnen Sie über Formeln den Namens-Manager:

Band-Expressions

Es gibt zwei Arten von Band-Expressions: Cond- und Exp-Bands.

• Der Text beginnt mit dem Namen des Bands, auf welches sich die Expression bezieht, gefolgt von Exp oder Cond, je nachdem, um welche Art von Expression es sich handelt (siehe unten).
• Die Expression (Referenz auf die Daten) wird mit :name angegeben

Als Band-Expression wird also zum Beispiel bndProjekteExp:projekte geschrieben, dieser Text markiert und mit einem leeren Kommentar versehen.

Excel fügt beim Anlegen eines Kommentars den Autor automatisch ein. Es ist wichtig, dass Sie diesen lassen und nicht rauslöschen. Mit "leerem" Kommentar ist also kein gänzlich leerer Kommentar gemeint, sondern einer, bei dem nur der Autor drin steht:

Notiz oder Kommentar?

In Excel-Versionen ab Office 365 gibt es "Notes", welche die "Comments" ablösen. Comments gibt es nach wie vor, sind aber neu eine Art Thread, wo sich mehrere User darüber unterhalten können.

Steht beides zur Verfügung, sollte man für die Vertec-Vorlagen die "Notes" verwenden.

Felder

Ein Feld ist ein durch einen Kommentar markierter Text innerhalb eines Bandes, der beim Ausführen des Berichts durch Daten aus Vertec ersetzt wird. Der markierte Text enthält dabei die Referenz auf die im Python-Code definierten Felder. Der Kommentar selbst ist leer (siehe oben) oder enthält das Schlüsselwort translation, um die Übersetzung für dieses Feld zu aktivieren.

Pro Zelle kann jeweils nur ein Begriff gesetzt werden. Es können also nicht in einer Zelle gleichzeitig ein Feld und eine Band-Expression gesetzt werden. Im Beispielbericht in Abbildung 3 wurde das so gelöst, dass in der Zelle am Ende der Zeile die Band-Expression eingefügt und das Band um eine Spalte breiter gemacht wurde.

Context-Variablen

Auch die Context-Variablen werden unterstützt. Statt einem Python-Feld enthält die Zelle den Text context:, gefolgt von der entsprechenden Variable:

Datentypen in Excel

Im Gegensatz zu Word gibt es in Excel verschieden Datentypen. Die automatische Erkennung von Excel ist dabei nicht immer sinnvoll. Deshalb kann in der Excel-Vorlage die entsprechende Zelle mit der gewünschten Formatierung versehen werden. Beim Einfügen der Daten bzw. Kopieren der Zellen nach unten wird die Formatierung mitkopiert.

Minuten-Felder

In Vertec Versionen vor 6.4.0.22 werden Minutenwerte gemäss Systemeinstellungen Projekt / Mandat > Anzeige Minuten exportiert.

Ab Vertec 6.4.0.22 wird das Format Stunden Minuten (HH:MM) nicht mehr berücksichtigt, sondern als Stunden Dezimal mit 2 Dezimalstellen exportiert. Anzeige Minuten wird nach wie vor als Minuten exportiert.

Summierung

Summierung in Excel funktioniert mit der gewohnten Excel Formel =Summe(<Band>).

Zeilensummen werden wie üblich mit den Zell-Bezügen gemacht:

Bei den Summen in den Spalten gelten folgende Richtlinien:

• Es werden sämtliche Excel-Operatoren akzeptiert. Das Format muss aber =Operator(<Band>) lauten
• Die Formel muss sich ausserhalb des durch die Summe referenzierten Bands befinden, aber innerhalb des dieses einschliessenden Bands, also eine Ebene tiefer.
• Summiert wird die Spalte, in der sich die Formel befindet.
• Zwischensummen sind möglich, aber nur innerhalb desselben Datensatzes.
• Summierung aller Teilsummen in derselben Spalte wird nicht unterstützt.

Aufgrund der Formatierung der Datentypen (siehe den Abschnitt Datentypen in Excel) kann es bei den Zellbezügen zum Hinweis kommen "Ein in der Formel verwendeter Wert ist vom falschen Datentyp."

Dies ist deshalb so, weil in den Feldern z.B. leistwertint, leistwertext etc. steht, was ja nicht summiert werden kann. Nach der Generierung des Berichts funktioniert die Summierung, da dann die Zahlenwerte drin stehen.

Summierung über mehrere Stufen

Die Summierung von Zellen in Excel Berichten via Band-Summen summiert alle Zellen einer Spalte innerhalb eines Bands.

In vielen Fällen möchten man einzelne Zellen eines Bands summieren, welches durch mehrere Hierarchiestufen von der Summe entfernt ist.

Ab Vertec 6.4 wird bei Summierung von nur einer Zelle eine Summe über alle Kopien dieser Zellen gemacht.

Beispiel

Die Summierung bezieht sich auf die Total-Zelle

Beim Ausführen wird eine Summe über alle Kopien dieser Zelle gemacht: