WebApps:Planungsassistent

Erstellen eines XML-Templates für den Planungsassistenten
In CoPlanner besteht die Möglichkeit, einen Assistenten zu definieren, mit dem eine einfache Planung erstellt werden kann.
Damit man das Verhalten des Assistenten festlegen kann, wird derzeit ein XML-Template verwendet.
In diesem Abschnitt wird kurz beschrieben, wie man ein derartiges Template baut.
Grundlegender Aufbau des Templates
Die Datei, die für die Beschreibung eines Templates verwendet wird, ist gegliedert in folgende Abschnitte:
- Dimensionen (Tag PreselectedDimensions): hier werden die Dimensionen angegeben, welche in der Planung immer vorhanden sein müssen. Diese können vom Benutzer nicht gelöscht werden und müssen im System bestehen.
- Parameter (Tag Parameters): hier können vom Benutzer Eingaben eingefordert werden, die für das Weiterschreiben notwendig sind (z.B. welches Measure der neuen Planung entspricht dem Umsatz, den ich weiterschreiben will)
- Konstanten (Tag Constants): hier können fixe Werte definiert werden, die keine Eingabe des Benutzers brauchen.
- Formeldefinitionen (Tag FormulaTemplates): nachdem eine Planung alleinstehend oft nicht viel Sinn macht, kann man hier Formeln definieren, um die neuen Inhalte in den Rechenkern zu integrieren. Hier kann auf die Parameter zugegriffen werden.
- Tiles-Einbettung (Tag TilesInformation): in diesem Abschnitt kann definiert werden, wo die Kachel, hinter der die Matrixmaske zur neuen Planung hinterlegt ist, erzeugt werden soll
Erklärung anhand eines Beispiels
Wir wollen einen einfachen Assistenten bauen, mit dem der Benutzer einen Umsatz planen kann. Der Benutzer muss somit angeben, wo in der neuen Planung der Umsatz steht und wohin er diesen geschrieben haben will.
Um Berechnungen zu demonstrieren, wollen wir aber den doppelten Wert dieses neuen Umsatzes um n Monate versetzt in die Tabelle TBL_Ergebnis_PLAN schreiben. Den Wert für n gibt der Benutzer dabei auch im Assistenten an.
Zusätzlich soll der Benutzer angeben, auf welchem Element der GuVGKV der Umsatz landen soll. Die vom Benutzer erstellte Planung soll auch noch eine Projektedimension enthalten, die einfach 1:1 weitergeschrieben wird.
Abschnitt Dimensionen (PreselectedDimensions)
Bei den Dimensionen kann man festlegen, welche Dimensionen fix in der Planung hinterlegt sein müssen. Diese Dimensionen können vom Benutzer, der die Planung dann erstellt auch nicht entfernt oder umbenannt werden. Weitere Dimensionen die der Benutzer verwenden will können dann im Assistenten aber natürlich hinzugefügt werden.
Für das oben angeführte Beispiel werden in der erzeugte Planung die beiden Dimensionen Zeit und Projekte benötigt, dies wird durch folgenden Abschnitt sichergestellt. Hier in diesem Beispiel bekommen die Dimensionen in der Tabelle keinen anderslautenden Alias. Wollen wir einen anderen Alias in der Tabelle stehen haben, dann kann dieser einfach über den UniqueNameInTable angegeben werden.
<PreselectedDimensions>
<PreselectedDimension> Tag je Dimension
<UniqueNameInTable>Zeit</UniqueNameInTable> Hier wird der Alias der Dimension in der Tabelle vergeben
<CopDimensionName>Zeit</CopDimensionName> Hier wird der Name der Dimension im CoPlanner angegeben
</PreselectedDimension>
<PreselectedDimension>
<UniqueNameInTable>Projekte</UniqueNameInTable>
<CopDimensionName>Projekte</CopDimensionName>
</PreselectedDimension>
</PreselectedDimensions>
Abschnitt Parameter (Parameters)
Hier können Eingaben vom Benutzer eingefordert werden. Parameter können entweder die Auswahl eines Measures der neuen Planung sein (Measure), eine Zahleneingabe (Value) oder die Auswahl eines Dimensionselements (Dimension).
Im Beispiel muss der Benutzer folgende Festlegungen treffen:
- Auswahl des Measures, auf dem die Umsätze in seiner neuen Planung stehen
- Auswahl eines Dimensionselementes aus der Dimension GuVGKV
- Angabe eines Monatsversatzes, mit dem der Umsatz übernommen werden soll
Dies wird mit folgendem Abschnitt in der XML-Datei erreicht:
<Parameters> Mögliche Typen von Parametern: Measure, Dimension, Value
<Measure> Tag um ein Measure auswählen zu lassen
<Id>Umsaetze</Id> ID für Verwendung bei den FormulaTemplates
<Caption>Umsätze</Caption> Überschrift für die Oberfläche
<Description>Wählen Sie das Measure aus, das die Umsätze enthält</Description> Beschreibung in der Oberfläche
</Measure>
<Dimension> Tag um ein Dimensionselement zu wählen
<Id>GuvGKVSelection</Id> ID für Verwendung bei den FormulaTemplates
<Caption>Guv-Struktur</Caption> Überschrift für die Oberfläche
<Description>Bitte wählen Sie das passende Element aus der GuV-Struktur aus</Description> Beschreibung in der Oberfläche
<DimensionName>GuVGKV</DimensionName> Name der Dimension, aus der das Element gewählt werden soll
</Dimension>
<Value> Tag um eine Zahleingabe einzufordern
<Id>Monatsversatz</Id> ID für Verwendung bei den FormulaTemplates
<Caption>Versatz in Monaten </Caption> Überschrift für die Oberfläche
<Description>Geben Sie den Versatz in das Zahlungsziel in Monaten an</Description> Beschreibung in der Oberfläche
</Value>
</Parameters>
Abschnitt Konstanten (Constants)
Konstanten können wie Parameter verwendet werden. Der einzige Unterschied besteht darin, dass diese dem Benutzer auf der Oberfläche nicht angezeigt werden.
<Constants>
<Constant>
<Id>ConstantNameInternal</Id>
<Value>1.0</Value>
<Description>My constant description</Description>
</Constant>
</Constants>
Abschnitt Formeldefinitionen (FormulaTemplates)
Um die Planung auch in andere Bereiche weiterzuschreiben, müssen Überleitungen definiert werden. Dazu können beliebig viele Formeln angegeben werden. Auf die angegebenen Parameter kann mit #<ID des Parameters># zugegriffen werden (z.B. #Umsaetze#). Ebenso können Anwendungseigenschaften, Sessionvariablen und serverseitige Funktionen verwendet werden.
In unserem Beispiel wird eine einzige Formel benötigt, die den Wert aus der neu erstellten Planung weiterschreibt.
Der Aufbau dieses Bereiches orientiert sich dabei am Aufbau einer Mengenformel
Dies wird mit folgendem Abschnitt erreicht:
<FormulaTemplates>
<FormulaTemplate> Tag je Formel
<Name>Ergebnis</Name> Name der Formel
<TargetTable>TBL_Ergebnis_PLAN</TargetTable> Zieltabelle (muss im System existieren)
<MeasureAssignments> Zuweisung der Quell- zu den Zielmeasures
<MeasureAssignment> Tag je Measure
<Source>2.0 * #Umsaetze#</Source> Was soll weitergeschrieben werden
<Target>Wert LC</Target> Wohin soll es geschrieben werden
</MeasureAssignment>
</MeasureAssignments>
<DimensionAssignments> Zuweisung der Dimensionen
<AutoAssignMatchingDimensions>True</AutoAssignMatchingDimensions> Sollen Dimensionen, bei denen Name und Alias übereinstimmen und keine explizite Zuordnung gemacht wird, automatisch in die Zieltabelle geschrieben werden?
<DimensionAssignment> Tag je Dimension
<Source>#Projekte#</Source> Was soll weitergeschrieben werden
<Target>Projekte</Target> Wohin soll es geschrieben werden
</DimensionAssignment>
<DimensionAssignment>
<Source>FKT_TimeDimAdd('M',#Monatsversatz#, #Zeit#)</Source> Beispiel für eine Funktion, die die Dimension Zeit um die im Assistenten eingegebenen Monate verschiebt
<Target>Zeit</Target>
</DimensionAssignment>
<DimensionAssignment>
<Source>#GuvGKVSelection#</Source>
<Target>GuVGKV</Target>
</DimensionAssignment>
</DimensionAssignments>
<Conditions>
<Condition>Start einer Bedingung. Bedingungen werden nach dem Schema ExpressionLeft ComparisonOperator ExpressionRight mit dem Vergleichsdatentyp ComparisonType ausgewertet. (z.B. #MeasureNameInternal# not_equal 0.0 und der Typ für den Vergleich ist numeric.
<ExpressionLeft>#MeasureNameInternal#</ExpressionLeft>>
<ExpressionRight>0.0</ExpressionRight>
<ComparisonOperator>not_equal</ComparisonOperator> Gültig sind: equal, not_equal, less, greater, less_equal, greater_equal
<ComparisonType>numeric</ComparisonType> Gültig sind: numeric, integer, date, text, bool
</Condition>
</Conditions>
</FormulaTemplate>
</FormulaTemplates>
Um fixe Dimensionswerte (mit Hilfe einer Anwendungseigenschaft) zu schreiben, kann folgendes verwendet werden:
<DimensionAssignment>
<Source>@Session_Entity_ID@</Source>
<Target>Unternehmen</Target>
</DimensionAssignment>
Abschnitt Tiles-Einbettung (TilesInformation)
Damit der Assistent weiß, an welcher Stelle in den Tiles die neu erstellte Planung einfügt werden soll, wird folgender Abschnitt benötigt. Optionen für TilesInsertOption sind AsChild und SameLevel.
<TilesInformation>
<TilesId>@NAV_Target@</TilesId> Anwendungseigenschaft oder hardcodierte COPSYS_ID der Referenzelements in den NavigationTiles
<TilesImageName>Img\Tiles\investitionen.png</TilesImageName> Pfad (im Serverordner) zum Bild, welches verwendet werden soll
<TilesInsertOption>AsChild</TilesInsertOption> Soll das Element auf der gleichen Ebene oder unter dem Referenzelement angelegt werden
</TilesInformation>
Vollständiges Template für Copy&Paste
<?xml version="1.0" encoding="utf-8"?>
<PlanningAssistantDefinition>
<PreselectedDimensions>
<PreselectedDimension>
<UniqueNameInTable>Zeit</UniqueNameInTable>
<CopDimensionName>Zeit</CopDimensionName>
</PreselectedDimension>
<PreselectedDimension>
<UniqueNameInTable>Projekte</UniqueNameInTable>
<CopDimensionName>Projekte</CopDimensionName>
</PreselectedDimension>
</PreselectedDimensions>
<Parameters>
<Measure>
<Id>Umsaetze</Id>
<Caption>Umsätze</Caption>
<Description>Wählen Sie das Measure aus, das die Umsätze enthält</Description>
</Measure>
<Dimension>
<Id>GuvGKVSelection</Id>
<Caption>Guv-Struktur</Caption>
<Description>Bitte wählen Sie das passende Element aus der GuV-Struktur aus</Description>
<DimensionName>GuVGKV</DimensionName>
</Dimension>
<Value>
<Id>Monatsversatz</Id>
<Caption>Versatz in Monaten</Caption>
<Description>Geben Sie den Versatz in das Zahlungsziel in Monaten an</Description>
</Value>
</Parameters>
<FormulaTemplates>
<FormulaTemplate>
<Name>Ergebnis</Name>
<TargetTable>TBL_Ergebnis_PLAN</TargetTable>
<MeasureAssignments>
<MeasureAssignment>
<Source>2.0 * #Umsaetze#</Source>
<Target>Wert LC</Target>
</MeasureAssignment>
</MeasureAssignments>
<DimensionAssignments>
<AutoAssignMatchingDimensions>True</AutoAssignMatchingDimensions>
<DimensionAssignment>
<Source>#Projekte#</Source>
<Target>Projekte</Target>
</DimensionAssignment>
<DimensionAssignment>
<Source>FKT_TimeDimAdd(‚M‘,#Monatsversatz#, #Zeit#)</Source>
<Target>Zeit</Target>
</DimensionAssignment>
<DimensionAssignment>
<Source>#GuvGKVSelection#</Source>
<Target>GuVGKV</Target>
</DimensionAssignment>
</DimensionAssignments>
</FormulaTemplate>
</FormulaTemplates>
<TilesInformation>
<TilesId>@NAV_Target@</TilesId>
<TilesImageName>Img\Tiles\investitionen.png</TilesImageName>
<TilesInsertOption>AsChild</TilesInsertOption>
</TilesInformation>
</PlanningAssistantDefinition>
Exkurs XML
XML steht für Extensible Markup Language (https://de.wikipedia.org/wiki/Extensible_Markup_Language) und ist eine einfache Sprache zur Darstellung von hierarchischen Strukturen in Form einer Textdatei. Wichtig dabei zu wissen ist, dass XML mit Tags arbeitet, und Elemente jeweils mit einem Starttag beginnen und mit einem Endtag enden. Will man z.B. ein Element „Vorname“ definieren, dann kann das wie folgt aussehen:
<Vorname>
Josef
</Vorname>
Dabei ist <Vorname> das Starttag, „Josef“ der Wert des Elements und „</Vorname>“ das Endtag.
In XML kann man auch Kommentare in die Datei schreiben, Kommentare haben dabei folgendes Format
<!-- ein Bespielkommentar -->
Um gut mit XML arbeiten zu können, empfiehlt sich die Verwendung eines Editors, der XML unterstützt (z.B. Notepad++ mit XML Tools Erweiterung, VS Code, …)