# Willkommen Diese Dokumentation ist zweigeteilt – wählen Sie den passenden Bereich. This documentation has two parts – pick the one that fits.


Nutzer-Dokumentation	Anleitungen und Referenz für die QVANTUM-App – für Planer, Team- und Formularverwaltung.	Nutzer-Dokumentation
Developer Documentation	Public API tutorial for integrating your applications with QVANTUM.	Entwickler-Dokumentation

# Nutzer-Dokumentation Finden Sie schnell und einfach die Informationen, die Sie benötigen – durch eine klare Navigation und eine praktische Suchfunktion. Die Dokumentation bietet eine übersichtliche Struktur, sodass Sie bequem durch die einzelnen Kapitel navigieren können. Über die Menüleiste im linken Seitenbereich finden Sie schnell die gewünschten Informationen. Alternativ können Sie die Suchfunktion nutzen, um gezielt nach relevanten Inhalten zu suchen – klicken Sie dazu einfach oben rechts auf „Suchen“ oder verwenden Sie die Tastenkombination Strg+K. So gelangen Sie ohne Umwege zu den für Sie wichtigen Themen.

# Eingangsseite - Planungen & Benutzer Die Eingangsseite erscheint unmittelbar nach dem Login in QVANTUM. Wählen Sie zuerst, welche Planung Sie betreten wollen. Nach dem Login in **QVANTUM** gelangen Sie zunächst in die **Planungsübersicht**. Hier können **Planer** auswählen, welche Planung sie betreten möchten. **Owner** hingegen haben erweiterte Funktionen zur [Verwaltung von Planungen](/user/eingangsseite-planungen-and-benutzer/die-planungsverwaltung) und [Benutzern](/user/eingangsseite-planungen-and-benutzer/ubersicht-uber-den-tab-benutzer), die in den folgenden Abschnitten beschrieben werden.

# Die Planungsverwaltung Planungsdetails einsehen und Benutzer verwalten ### Planungsübersicht für den Owner Als **Owner** haben Sie die Möglichkeit, **neue Planungen anzulegen** oder **bestehende Planungen zu löschen**. Zudem können Sie im **Tab „Benutzer“** das Team verwalten. #### Planungs-Details Im **Tab „Planungen“** haben Sie als Owner eine Übersicht über alle bestehenden Planungen. Jede Planung besitzt einen **Status**, der den aktuellen Stand widerspiegelt: * **Aktiv** – Die Planung ist in Bearbeitung. * **Inaktiv** – Die Planung befindet sich in der Vorbereitung. * **Beendet** – Die Planung wurde abgeschlossen und kann weiterhin eingesehen werden.

Als Owner haben Sie jederzeit den Überblick über Ihre Planungen

#### Planerstatus Zusätzlich wird ein **Planerstatus** angezeigt, der den Fortschritt der einzelnen Planer widerspiegelt. Wenn beispielsweise zwei von drei Planern ihre Aufgaben abgeschlossen haben und Sie dieses durch die Abnahme auf dem Team-Tab der Planung bestätigt haben, wird ein Fortschritt von **67 % (2/3 abgenommen)** angezeigt. #### Planungen löschen Über das **Drei-Punkte-Menü** einer Planung können Sie eine **Planung vollständig löschen**. Dies empfiehlt sich aber nur für Testplanungen, die nie gestartet wurden oder wirklich veraltete Planungen, die nicht mehr benötigt werden. Abgeschlossene Planungen bleiben weiterhin abrufbar, auch nach mehreren Jahren.

Planung löschen über das drei Punkte Menü

#### Neue Planung anlegen Über die **Kachel „Neue Planung anlegen“** können Sie jederzeit eine neue Planung hinzufügen – sei es für eine **Testplanung** oder zur Vorbereitung der nächsten Planungsrunde.

Nach einem Klick auf die Kachel vergeben Sie einen **Namen** für die neue Planung und legen diese an.

## Die Benutzerverwaltung Im Tab „Benutzer“ verwalten Sie alle Planer mit ihren Stammdaten (Name und E-Mail-Adresse). **Beachten Sie: Die Anlage von Benutzern erfolgt unabhängig von den Planungen**. Ein Benutzer erhält erst dann Zugriff auf eine Planung, wenn er **auf dem Team-Tab der Planung zugewiesen** wurde und entsprechende **Berechtigungen** erhalten hat. Die Benutzerverwaltung erfolgt über den **Upload einer CSV-Datei**. Weitere Details zur Benutzeranlage finden Sie [hier](/user/team/ubersicht_uber_den_tab_team).

Die Verwaltung der Benutzer erfolgt unabhängig von den jeweiligen Planungen

# Duplizieren von Planungen Alle Inhalte in einem Schritt übernehmen Über das Drei-Punkte-Menü einer Planung kann eine komplette Duplikation durchgeführt werden. Dabei werden alle relevanten Bestandteile der Planung übernommen, im Einzelnen: * Das zugrundeliegende Modell * Alle Daten im Cube * Segmente und Kennzahlenformeln * Die zugehörigen Formulare * Die Benutzerzuordnungen inklusive ihrer Berechtigungen\* {% hint style="info" %} \***Achtung:** Die Benutzerzuordnung basiert auf den Benutzern, die auf Tenant-Ebene (also vor Betreten der Planung) mit Name und E-Mail-Adresse angelegt wurden. Werden Benutzer auf dieser Ebene gelöscht, wird auch ihre Zuordnung zu bestehenden Planungen entfernt. {% endhint %}

**Anwendungsbeispiele für Duplikate von Planungen** Das Duplizieren einer Planung dient nicht nur als Backup einer abgeschlossenen Planungsrunde. Überall dort, wo Planungswerte im Zeitverlauf überschrieben oder angepasst werden, kann es sinnvoll sein, einen bestimmten Stand **festzuhalten und abzusichern**. Ein Beispiel:\ Die **Worst-Case-Einschätzung für das Jahr 2027**, wie sie im Jahr **2025** getroffen wurde, könnte im darauffolgenden Jahr (2026) aufgrund neuer Erkenntnisse oder veränderter Rahmenbedingungen angepasst werden. Möchte man später nachvollziehen, welche Annahmen ursprünglich zugrunde lagen, hilft ein Blick in die **duplizierte Planung**, die den Stand von 2025 unverändert dokumentiert. # Übersicht über den Tab "Benutzer" Hier erfahren Sie, wie Sie die Benutzer unabhängig von einer späteren Zuweisung zur Planung verwalten können. Nach dem Login landen Sie zunächst auf der **Tenant-Ebene**, noch bevor Sie eine konkrete Planungsanwendung auswählen. Auf dieser Ebene können Sie: * Bestehende Planungen betreten * Neue Benutzer anlegen und bestehende verwalten Neu angelegte Benutzer sind zunächst keiner Planung zugeordnet. Die Benutzerverwaltung auf Tenant-Ebene dient dazu, sämtliche Personen zu hinterlegen, die später an einer Planung teilnehmen können. Die konkrete Zusammensetzung eines Planungsteams erfolgt erst in der jeweiligen Planung selbst Die Zusammenstellung eines Planungsteams geschieht später an [anderer Stelle](/user/team/ubersicht_uber_den_tab_team).\ \ \&#xNAN;*Auf dem Team-Tab in einer Planung können Sie dann aus den verfügbaren Benutzern diejenigen aussuchen, sie an der jeweiligen Planung teilnehmen sollen. Auch die Rechte werden dort vergeben.*

Die Benutzerverwaltung auf Tenant-Ebene (direkt nach dem Login)

### Benutzer bearbeiten oder löschen Die Ansicht ist in zwei Bereiche aufgeteilt: * **Linke Spalte**: Hier sehen Sie alle Benutzer mit ihrer E-Mail-Adresse. * **Rechte Spalte**: Hier werden die jeweils zugewiesenen Planungen angezeigt. Ein Klick auf eine Planung öffnet sie direkt (dient an dieser Stelle jedoch nur zur Information). Über das Drei-Punkte-Menü neben einem Benutzer können Sie diesen **bearbeiten** oder **löschen**.

Die Auswahl im Drei-Punkte Menü: Bearbeiten und Löschen

Klicken Sie auf **Bearbeiten**, um den folgenden Dialog zu öffnen. > **Hinweis:** Nach Anlage eines Benutzers kann die E-Mail-Adresse nicht mehr geändert werden. Im Bearbeiten-Dialog können Sie: * **Name** und **Nachname** jederzeit anpassen * Auf **SSO-Authentifizierung** umstellen Die Umstellung auf SSO erfordert zusätzliche Konfigurationen an mehreren Stellen. Wenden Sie sich bei Fragen gerne an unser Support-Team.

Über den Aufruf "+ Benutzer hinzufügen" (unter der Liste der Benutzer), rufen Sie den Dialog zum Erstellen eines neuen Benutzers auf.

#### Benutzer CSV-Export und -Import {% hint style="info" %} Die Benutzerverwaltung per CSV-Export und -Import bleibt erhalten und eignet sich besonders für **Massenänderungen**. {% endhint %} QVANTUM stellt standardmäßig bereits einige Testbenutzer zur Verfügung. Über die Schaltfläche **„Benutzer exportieren“** können Sie eine CSV-Datei herunterladen, mit der Sie Benutzer komfortabel hinzufügen, bearbeiten oder löschen können.

Die Benutzer Stammdaten werden über diese CSV Datei verwaltet

Die CSV-Datei enthält die Spalten `last-name`, `first-name` und `email`, die für jeden Benutzer befüllt werden müssen. Je nach Lizenzumfang können Sie beliebig viele Benutzer verwalten. #### Benutzer importieren Nach Ihren Änderungen speichern Sie die Datei einfach ab und laden sie über „Benutzer importieren“ wieder in QVANTUM hoch. > **Hinweis:** Benutzer werden **eindeutig anhand ihrer E-Mail-Adresse identifiziert**.\ > Wird die E-Mail-Adresse eines Benutzers geändert, behandelt das System ihn als **neuen Benutzer**.\ > Alle neu hinzugefügten Benutzer erhalten nach dem Import **automatisch eine E-Mail mit ihren Zugangsdaten**. # Authentifizierung über SSO Die SSO IDs der Benutzer werden in den Benutzer-Stammdaten ergänzt. **Wie können sich die Benutzer über SSO authentifizieren?** Voraussetzung für die Anmeldung per SSO ist, dass Ihre IT dieses Authentifizierungsverfahren unterstützt und Ihnen die im Folgenden benötigten ID's bereitstellt. Beachten Sie, dass Qvantum zunächst für den Login per SSO konfiguriert sein muss. Wenden Sie sich hierzu bitte an unseren [Support](mailto:support@qvantum-plan.de). Die Zugriffsberechtigungen für die **Owner** einer Planungsanwendung werden von der **Qvantum-IT** konfiguriert. Sobald das System entsprechend eingerichtet ist, können Sie die Zugriffsberechtigungen für die Planer selbstständig einrichten, indem Sie die jeweilige SSO-ID eintragen. Damit sich die Planer Ihres Teams jetzt per Single Sign-on authentifizieren können, müssen die Benutzer-Stammdaten erweitert werden. Exportieren Sie hierzu die Benutzer-Stammdaten auf dem Tab "Benutzer". In der CSV-Datei, in der die Stammdaten enthalten sind, wird nun eine weitere Spalte hinzugefügt, die mit "**single-sign-on-user-id**" betitelt werden muss. Achten Sie unbedingt auf die identische Schreibweise, da die IDs sonst nicht korrekt interpretiert werden können.

# Migration von Planungen Bis März 2025 war es nur möglich, eine zusätzliche Planung in einem separaten Tenant anzulegen. Erfahren Sie hier, wie Sie die Daten nun als neue Planung in Ihren bestehenden Tenant übernehmen. Sie haben sich bisher für die Personalkostenplanung in einen QVANTUM-Tenant eingeloggt und für die Kostenstellenplanung oder andere Planungsarten einen separaten Tenant verwendet?\ Ab sofort können Sie **mehrere Planungen in einem gemeinsamen Tenant** zusammenführen. Im Folgenden wird der Tenant, in dem die Planungen gebündelt werden sollen, als **Ziel-Tenant** bezeichnet. Alle Tenants, aus denen Sie Daten übernehmen möchten, werden als **Quell-Tenants** bezeichnet. #### Export der Daten aus einem Quell-Tenant Melden Sie sich mit Ihrem Owner-Zugang im Quell-Tenant an, um Daten und Konfigurationen zu sichern.\ Sobald Sie eingeloggt sind und die entsprechende Planung geöffnet haben, können Sie über das Cloud-Symbol oben rechts einen vollständigen Download aller Daten und Einstellungen starten.

Der Download aller Daten und Einstellungen im System

#### Nächster Schritt: ZIP-Archiv entpacken Entpacken Sie das heruntergeladene **ZIP-Archiv**. Im entpackten Ordner finden Sie die folgenden Dateien (siehe auch die Abbildung *„Dateien aus dem Backup“*): * **`QVANTUM_Export_xxxx.csv`**\ Enthält die Daten aus der Datenstruktur (Cube). Diese Datei ist in der Regel die umfangreichste. * **`QVANTUM_FORMS_EXPORT_xxxx.json`**\ Enthält die Konfiguration der Formulare. * **`QVANTUM_FORMULAS_EXPORT_xxxx.json`**\ Enthält die Konfiguration der Kennzahlenformeln sowie – falls vorhanden – die Definitionen von Segmenten. * **`QVANTUM_MODEL_EXPORT_xxxx.xlsx`**\ Stellt das Modell dar, das der Planung zugrunde liegt. * **`QVANTUM_Permissions_xxxx.csv`**\ Enthält die Berechtigungen der Benutzer, die dieser Planung zugewiesen sind.

#### Import der Planung in den Ziel-Tenant Melden Sie sich nun mit Ihrem Owner-Zugang im Ziel-Tenant an. In der Planungsübersicht klicken Sie auf „+ Neue Planung anlegen“ und vergeben einen Namen für die neue Planung. Nachdem die Planung erstellt wurde, klicken Sie auf „Planung betreten“, um sie zu öffnen und mit dem Import zu beginnen.

Wählen Sie im Ziel-Tenant "+ Neue Planung anlegen"

### Importieren der einzelnen Komponenten **Schritt 1: Modell importieren** Wechseln Sie in der geöffneten Planung zum **Tab „Modell“**.\ Klicken Sie dort auf **„Modell hochladen“**, um die Datei **`QVANTUM_MODEL_EXPORT_xxxx.xlsx`** auszuwählen und zu importieren.

#### Schritt 2: Formeln importieren Bleiben Sie im Tab „Modell“ und öffnen Sie dort das Untermenü „Formeln“ (siehe nachfolgende Abbildung). Klicken Sie auf „Importieren“, um die Datei `QVANTUM_FORMULAS_EXPORT_xxxx.json` hochzuladen.

#### Schritt 3: Team und Berechtigungen importieren Wechseln Sie nun in den **Tab „Team“**, um dort die Datei **`QVANTUM_Permissions_xxxx.csv`** zu importieren. > **Wichtig:** Vergewissern Sie sich vor dem Import, dass alle in der Datei enthaltenen E-Mail-Adressen bereits in den Benutzerstammdaten vorhanden sind. Fehlende Benutzer müssen zunächst über die zentrale [**Benutzerverwaltung** ](broken://pages/0e8DiSJPzZX0iEu37JOo)angelegt werden.

Zuordnung der Benutzer und ihrer Rechte an der Planung

#### Importieren der Formulare Auf dem Formulare-Tab müssen Sie zunächst die Seitenleiste öffnen, um die Formulare hochzuladen. Klicken Sie auf "Neues Formular" (links oben) und dann auf das Icon für den Import (in der nachfolgenden Abbildung rot gekennzeichnet). Wählen Sie dann die Datei QVANTUM\_FORMS\_EXPORT\_xxxx.json für den Import.

#### Schritt 4: Formulare importieren Wechseln Sie in den Tab „Formulare“ und öffnen Sie die Seitenleiste, indem Sie oben links auf „Neues Formular“ klicken. Anschließend starten Sie den Import über das Import-Icon (in der folgenden Abbildung rot markiert). Wählen Sie nun die Datei **`QVANTUM_FORMS_EXPORT_xxxx.json`**, um die Formular-Konfiguration zu importieren.

Je nach Umfang der Daten kann dieser Vorgang etwas länger dauern. Zusätzlich zur Upload-Zeit wird auch der vollständige Datencube berechnet, was weitere Zeit in Anspruch nimmt. # QVANTUM für Planer Alles, was Sie als Planer über QVANTUM wissen müssen, ist in dieser Kategorie gesondert beschrieben. Dieses Kapitel richtet sich an **Planer**, die aktiv an der Dateneingabe und -bearbeitung in QVANTUM beteiligt sind. Sie erfahren, wie Sie Formulare nutzen, Daten effizient erfassen und bearbeiten sowie Planungsprozesse strukturiert durchführen. Zudem erhalten Sie Einblicke in Berechnungen, Workflow-Mechanismen und hilfreiche Funktionen, die Ihre Arbeit erleichtern. Ziel ist es, Ihnen ein klares Verständnis der Planungsoberfläche zu vermitteln und Sie in die Lage zu versetzen, Ihre Aufgaben effizient und sicher umzusetzen.

# Erste Schritte vor der Planung Als Planer verwenden Sie ausschließlich die Kernfunktionen von Qvantum. Dieses Kapitel konzentriert sich auf die spezifischen Funktionen, die für Planer verfügbar sind. Alle andere Kapitel können Sie ### Vorbereitungsphase #### Erster Login vor Planungsbeginn Während der Planungsphase verwenden Sie QVANTUM als Planer zur Eingabe Ihrer Planwerte. Sie werden von Ihrem zentralen Controller mit den entsprechenden Formularen unterstützt. Vor Beginn der Planung bereitet der zentrale Controller alles vor, definiert das Modell, erstellt die Formulare und fügt die Namen und E-Mail-Adressen der Planer als Teammitglieder hinzu. Sobald Ihre E-Mail-Adresse dem Team zugeordnet ist, erhalten Sie eine automatisierte E-Mail von QVANTUM mit Ihren persönlichen Zugangsdaten.

Nachdem Sie sich das erste Mal mit Ihren Zugangsdaten angemeldet haben, werden Sie dazu aufgefordert, Ihr Passwort zu ändern.

Sobald Sie dies getan haben, sind Sie erfolgreich eingeloggt und können sich einen ersten Überblick über die Formulare verschaffen. Bitte beachten Sie, dass die Planung zu diesem Zeitpunkt wahrscheinlich noch nicht gestartet wurde, daher können noch keine Daten in die Formulare eingegeben werden. Beachten Sie, dass Ihr zentraler Controller die Bearbeitung der Formulare möglicherweise noch nicht abgeschlossen hat. Denn wir befinden uns noch in der Vorbereitungsphase. Nutzen Sie die **Vorbereitungsphase**, um sich mit den Funktionen vertraut zu machen. Bevor die offizielle Planung beginnt, können Sie allerdings noch keine Werte in die Formulare eintragen. Überblick Formulare Die Ansicht „Formulare“ untergliedert sich in die folgenden Bereiche, die wie in Abbildung 3 nummeriert sind: 1. [**Auswahl Formulare**](/user/qvantum-fur-planer/formulare_-_seitenaufbau#formularauswahl)\ Zeigt den Formulartitel an. Durch Anklicken öffnet sich die Auswahl an Formularen. 2. [**Planungsstatus**](/user/qvantum-fur-planer/formulare_-_seitenaufbau#der-planungsstatus)\ Erst mit Starten der Planung wird der Planungsstatus „Offen“ an dieser Stelle angezeigt. 3. [**Formular-Header**](/user/qvantum-fur-planer/formulare_-_seitenaufbau#der-formular-header)\ Alle Dimensionen, die nicht im Formular verwendet werden, sind hier referenziert. Für die Eingabe Ihrer Planwerte ist diese Auswahl entscheidend. So beziehen sich die unten stehenden Absätze allesamt auf Artikel 1.1/Gesamtjahr. 4. [**Toolbar**](/user/qvantum-fur-planer/formulare_-_seitenaufbau#die-toolbar)\ Erst wenn Sie auf Speichern geklickt haben, sind Ihre Eingaben gesichert. Bis zum Speichern können Sie auch wieder schrittweise zurück gehen (Undo/Redo). 5. **Link zur Online Hilfe/Wissens-Datenbank** 6. **Account Einstellungen**\ Hier können Sie Ihr Passwort ändern oder die Spracheinstellung ändern. 7. [**Das Formular**](/user/qvantum-fur-planer/eingabe_in_formularen)\ Bevor die Planung gestartet wurde, können Sie die Daten nur lesen.

# Eingabe in Formularen Erfahren Sie, welche Abkürzungen Sie bei der Eingabe von Zahlen verwenden können. Nutzen Sie unsere Zellfunktionen, um Werte bei der Eingabe automatisch zu berechnen. Als Planer müssen Sie sich nicht um die Einrichtung der Formulare kümmern. Ihr zentraler Controller hat sie bereits für Sie konfiguriert. Bevor Sie mit der Planung beginnen, sollte Ihnen Ihr Controller auch mitgeteilt haben, welche Formulare Sie bearbeiten müssen. In diesem Artikel erfahren Sie, wie Sie Daten in die Formulare eingeben und welche Funktionen Ihnen die Arbeit erleichtern. ### Zell Funktionen Als Planer müssen Sie sich nicht um die Einrichtung der Formulare kümmern. Ihr zentraler Controller hat sie bereits für Sie konfiguriert. Bevor Sie mit der Planung beginnen, sollte Ihnen Ihr Disponent auch mitgeteilt haben, welche Formulare Sie bearbeiten müssen. In diesem Artikel erfahren Sie, wie Sie Daten in die Formulare eingeben und welche Funktionen Ihnen die Arbeit erleichtern.

Abbildung 1 veranschaulicht noch einmal die Verwendung von Tastaturkürzeln.

*Abbildung 1 - Hilfreiche Abkürzungen für die Eingabe Ihrer Planwerte.*

#### Zellfunktionen in andere Bereiche übertragen Wenn Sie beispielsweise den Text „**add10%**“ markieren und ihn mit **STRG+C**(Kopieren) in die Zwischenablage kopieren, können Sie diese Funktion mit **STRG+V** (Einfügen) auf einen ausgewählten Bereich von Zellen anwenden. ### Weitere Funktionen auf dem Formular Um bei einem großen Formular den Überblick zu behalten, haben Sie die Möglichkeit, Teile der Struktur auf- oder zuzuklappen. So können Sie sich bei der Bearbeitung nur die relevanten Zeilen oder Spalten anzeigen lassen, die Sie benötigen. **Leere Zeilen und leere Spalten im Formular ausblenden** Qvantum bietet auch die praktische Funktion, leere Zeilen oder Spalten nach Bedarf ein- oder auszublenden, unabhängig von der Achsenkonfiguration. Dazu finden Sie in der oberen rechten Ecke der Formulare ein Filtersymbol zum Ausblenden leerer Spalten. Das Symbol zum Ausblenden von Zeilen befindet sich unten links. Bitte beachten Sie, dass die Anzeige einer großen Anzahl von leeren Spalten oder Zeilen zu einer spürbaren Leistungseinbuße führen kann. Qvantum zeigt daher die Anzahl der ausgeblendeten Zeilen unten links im Formular an. Um die Anzahl der ausgeblendeten Spalten zu sehen, fahren Sie mit der Maus über das Filtersymbol oben rechts. Ein Mouseover-Tooltip zeigt Ihnen dann die genaue Anzahl an.

*Abbildung 2- Filter- und Dropdown-Funktionen im Formular*

Die folgenden Aktionen können darüber aufgerufen werden: * **Alle aufklappen**\ Erweitert alle Knoten einer Struktur, so dass alle verfügbaren Zeilen/Spalten des Formulars angezeigt werden. * **Alle komprimieren**\ Klappt alle Knoten einer Struktur zusammen, so dass nur die Wurzelelemente und Knoten der untersten Ebene angezeigt werden. * **Leerzeilenfilter aktivieren**\ Wenn der Leerzeilenfilter aktiviert ist, werden nur Zeilen/Spalten angezeigt, die Werte enthalten. Dies verbessert die Übersichtlichkeit und blendet unnötige leere Bereiche aus. * **Deaktivieren des Leerzeilenfilters**\ Wenn Sie den Leerzeilenfilter deaktivieren, werden alle Zeilen/Spalten angezeigt, auch wenn sie keinen einzigen Wert enthalten. ### Verteilungsaktionen In Strukturen ist es oft notwendig, die Werte aller untergeordneten Elemente in den Knoten zu summieren. Dies kann in verschiedenen Dimensionen notwendig sein. Befindet sich z.B. die Dimension 'Monate' im Formularkopf und ist der Knoten 'Gesamtjahr' ausgewählt, so müssen alle eingegebenen Werte auf die einzelnen Monate verteilt werden; in der Regel müssen Sie sich darum nicht kümmern, da Qvantum die Werte in der Zeitdimension automatisch gleichmäßig verteilt (jeder der 12 Monate erhält 1/12 des Wertes). Wenn jedoch ein Wert auf andere Zellen im Formular verteilt werden soll, ist es oft unklar, wie diese Verteilung erfolgen soll. In solchen Fällen fordert Qvantum eine Referenzspalte an, in der die Kindelemente des betreffenden Knotens bereits ausgefüllt sind. ### Spaltenbreite ändern Sie können die Spaltenbreite leicht anpassen. Bewegen Sie dazu die Maus zwischen den Spalten in der Kopfzeile und passen Sie die Breite per Drag'n'Drop nach Ihren Wünschen an. Bitte beachten Sie, dass Änderungen an der Spaltenbreite nur vorübergehend erhalten bleiben. Wenn Sie sich das nächste Mal anmelden, wird das Formular in der vom zentralen Controller festgelegten Konfiguration neu geladen.

Bitte beachten Sie, dass Modelle, die vor März 2024 exportiert wurden, bald nicht mehr importiert werden können. Der Grund dafür ist die Formelspalte in der Dimension Kennzahlen, die den Import verhindert. #### Sortieren von Wertespalten Um eine Spalte auf- oder absteigend zu sortieren, bietet Qvantum im Spaltenmenü (drei Punkte Icon) die entsprechenden Aufrufe.

#### Filtern von Wertespalten Im drei Punkte Menü, das an jeder Wertespalte verfügbar ist, können Sie einen Filter aktivieren. Folgende Filter sind hier verfügbar: * Leer * Nicht leer * Gleich * Ungleich * Größer als * Größer als oder gleich * Kleiner als * Kleiner als oder gleich * Zwischen Im Rahmen der hierarchischen Strukturierung von Elementen in Qvantum ist es von entscheidender Bedeutung, dass beim Filtern von Werten auch alle übergeordneten Zeilen des gefilterten Elements angezeigt werden. Dies gewährleistet, dass der Kontext des gefilterten Wertes erhalten bleibt. Daher kann es vorkommen, dass auch Werte angezeigt werden, die nicht den Filterkriterien entsprechen. Im folgenden Beispiel ist es erforderlich, die Zeile „Support“ unabhängig von dem darin enthaltenen Wert anzuzeigen, um die Zuordnung der Mitarbeiter zu verdeutlichen.

*Beispiel für einen Filter, der nur Werte **unter** 5.000 in der Spalte anzeigt*

Der Filter kann über das 3-Punkte-Menü konfiguriert werden, das für jede Wertspalte verfügbar ist. ![](https://2163058718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjPBuhWj0weKi71UBawJq%2Fuploads%2Fgit-blob-17ff5658d9d85befffdf9aab8442660f9307bf65%2Fimage.png?alt=media) # Arbeiten mit Formularen Dieser Artikel beschreibt alle für den Planer benötigten Funktionen rund um das eigentliche Formular. In diesem Artikel werden alle Funktionen erläutert, die der Planer rund um das eigentliche Formular benötigt. ### Auswahl des passenden Formulars Wenn Sie auf den Titel des Formulars (1) klicken, wird die Formularliste (3) geöffnet. Möchten Sie die Liste immer im Blick behalten, können Sie die Pin-Funktion (2) verwenden. Wenn die Liste nicht gepinnt ist, wird sie sich automatisch schließen, nachdem Sie das gewünschte Formular ausgewählt haben oder einfach rechts neben die Liste klicken.

### Der Planungsstatus Aus Sicht des Planers stellt sich der Planungsstatus recht einfach dar. Vor Planungsbeginn *("Keine Planung aktiv")* wird noch kein Status angezeigt. Sobald der zentrale Controller die Planung gestartet hat, wird das Feld "Mein Planungsstatus" mit dem Status "Offen" angezeigt. Wenn Sie der Meinung sind, dass Sie Ihre Arbeit an dieser Planungsrunde abgeschlossen haben, wechseln Sie den Status auf "Abgeschlossen". Nachdem Sie Ihre Arbeit als "Abgeschlossen" gekennzeichnet haben, sind keine weiteren Änderungen mehr möglich. Die folgende Abbildung zeigt den Workflow aus Sicht des Planers.

### Der Formular-Header Alle Formulare sind nur verschiedene Perspektiven auf Teile des Datenwürfels. Stellen wir uns einen Würfel mit 3 Dimensionen vor (siehe Abbildung 3), von denen jede Dimension 3 Elemente aufweist.

Abbildung 3 - Vereinfachte Darstellung eines Datencube

In Abbildung 4 wird dargestellt, wie das Formular für diesen Datenwürfel gestaltet sein könnte. Hier werden die Artikel und Jahre in den Zeilen und Spalten angeordnet. Im Formular-Header wird die Dimension "Kennzahlen" angezeigt. Dadurch wird deutlich, welchen Unterschied es macht, ob Sie den Umsatz der Artikel in den verschiedenen Jahren oder den Absatz erfassen. Vor der Bearbeitung eines Formulars ist es wichtig zu überprüfen, welche Auswahl in den Dimensionen des Formular-Headers getroffen wurde.

*Abbildung 4 – Formular-Header und Formular*

#### Auswahl für eine Dimension treffen Für jede Dimension, die im Formular-Header aufgelistet ist, können Sie eine Auswahl treffen. Der zentrale Controller kann die verfügbaren Strukturen möglicherweise einschränken. Zum Beispiel könnte die Dimension "Kunden" nur Kunden aus Ihrer Region anzeigen. In diesem Fall wurden Ihre Zugriffsrechte entsprechend angepasst. #### Gesperrte Dimensionen Es kann vorkommen, dass eine Dimension gesperrt ist. In solchen Fällen hat der zentrale Controller bereits eine festgelegte Auswahl getroffen, die von Ihnen nicht geändert werden kann und daher als "abgeschlossen" gilt. Dies erkennen Sie an dem Schloss-Symbol neben der Auswahl. In der nachfolgenden Abbildung ist die Kennzahl "Absatz" mit einem Schloss markiert. Daher können Sie in diesem Formular weder Umsatz noch Preis (oder andere mögliche Kennzahlen) auswählen.

*Abbildung 5 – Die Dimensionen Kennzahl und Variante wurden gesperrt.*

#### Die Suchfunktion nutzen Wenn Sie ein Element in einer Dimension suchen möchten, können Sie einfach den gesuchten Begriff in das Suchfeld eingeben und dann die Eingabetaste drücken. Qvantum wird das Element finden und die entsprechenden Pfade anzeigen, um dorthin zu gelangen. Zum Beispiel suchen Sie innerhalb der Struktur "Kunden" nach "Berlin". Die Niederlassung "Ost" wird automatisch geöffnet, um "Berlin" als Suchergebnis hervorzuheben.

*Abbildung 6 – Suche nach „Berlin“ in der Dimension „Kunden“*

### Die Toolbar In der Toolbar finden Sie verschiedene Aktionen, die entweder die Daten oder die Formulare betreffen. In Abbildung 5 werden diese Aktionen näher erläutert. Jede Eingabe, die Sie im Formular tätigen, zählt als Dateneingabe. Wenn Sie jedoch ein Element im Formular-Header auswählen oder eine Spalte verbreitern, handelt es sich um Anpassungen am Formular selbst. Diese Änderungen können unabhängig voneinander rückgängig gemacht werden.

*Abbildung 7 – Die Toolbar mit den für Planer verfügbaren Aktionen*

# Video Tutorial Erfahren Sie in diesem Video-Tutorial, wie Sie ein Modell anlegen, Teammitglieder hinzufügen oder Ihre ersten Formulare erstellen. {% embed url="" %} Tutorial Qvantum {% endembed %} # Übersicht & Workflow Der Übersicht-Tab einer Planung zeigt den aktuellen Stand und ist die Stelle, an der Sie den Workflow der Planung steuern. Sobald Sie in eine Planung wechseln, gelangen Sie zum Tab **Übersicht**. Er zeigt Ihnen den aktuellen Stand der Planung und ist zugleich die Stelle, an der Sie den **Workflow** der Planung steuern – also die Planung vorbereiten, starten, pausieren oder beenden. Wie dieser Workflow im Detail funktioniert und welche Auswirkungen die einzelnen Status auf Owner und Planer haben, ist auf einer eigenen Seite beschrieben.

# Übersicht über den Tab Übersicht Planung vorbereiten & starten Auf dem Tab „Übersicht" behalten Sie die grundlegenden Daten einer Planung unter Kontrolle und steuern den Workflow der Planung. ## Planung vorbereiten Unmittelbar nach Erstellung einer neuen Planung dient der Übersicht-Tab primär als Checkliste für die weitere Vorbereitung der Planung bis hin zu einem produktiven Stand.

Übersicht-Tab initial nach Erstellung einer Planung

### Planung definieren Hier müssen Sie nun Ihre Planung definieren. Im Detail heißt das, Sie geben die gewünschten Planungseigenschaften Planungstitel und Abgabetermin ein. Diese werden Ihrem Team während der Eingabe der Plandaten und in allen Benachrichtigungs-Mails angezeigt. Bei dem Planungstitel handelt es sich um ein Pflichtfeld, welches Sie vergeben müssen bevor Sie mit der Planung starten können. Den Planungstitel können Sie nachträglich jederzeit editieren, ohne die Planung pausieren zu müssen. Optional können Sie einen Abgabetermin festlegen. Abgabetermine können nur für den aktuellen Zeitpunkt oder einen Zeitpunkt in der Zukunft ausgewählt werden. Nach Bedarf können Sie den Abgabetermin beliebig häufig neu wählen oder zurücksetzen. Ihre Planer werden automatisch über eine Änderung des Abgabetermins informiert. ### Daten vorbereiten Dieser Bereich gibt Ihnen eine Übersicht über alle für eine produktive Planung notwendigen Vorbereitungsschritte. Diese Schritte führen Sie auf einem der dafür vorgesehenen anderen Tabs einer Planung durch. Die jeweiligen Tabs sind von hier über Links direkt erreichbar. Für jeden Vorbereitungsschritt sehen Sie auf einen Blick, ob dieser bereits vorgenommen wurde und ob alle diesbezüglichen Voraussetzungen erfüllt wurden (grüner Haken) oder nicht (rotes Ausrufezeichen). Grundvoraussetzung für eine produktive Planung ist die Definition eines [Planungsmodells](/user/modell/ubersicht_uber_den_tab_modell). Erst mit Verfügbarkeit eines gültigen Planungsmodells können Sie sinnvoll ein [Team inkl. Berechtigungen](/user/team/nutzer-berechtigungen_in_qvantum_definieren) auf Ihr Planungsmodell sowie [Formulare](/user/arbeiten-mit-formularen/ubersicht_uber_den_tab_formulare) zur Bearbeitung Ihrer Planung definieren. ### Workflow starten Erst wenn alle Vorbereitungsschritte durchgeführt und alle notwendigen Voraussetzungen erfüllt sind, wird der Button "Planung starten" aktiviert. Mit Klick auf diesen Button starten Sie den Workflow Ihrer Planung.

Übersicht-Tab nach Vorbereitung einer Planung

Wie Sie Ihre Plandaten exportieren, ist auf der Seite [Der Workflow](/user/ubersicht-uber-die-planung/der_workflow#plandaten-exportieren) beschrieben. # Der Workflow Vom Starten der Planung bis zum Abschluss. Über den Übersicht-Tab steuern Sie den Workflow einer Planung: Sie bereiten sie vor, starten, pausieren und beenden sie. ### Planung starten (Planung aktiv) Sobald die notwendigen Anforderungen erfüllt sind, ist der Button „Planung starten“ aktiv. Erst wenn Sie auf „Planung starten“ klicken, wird Ihr Team per E-Mail informiert und der Status der Planung auf „Planung aktiv“ gesetzt. Nun ist der Workflow gestartet und Ihre Planer können Planzahlen eingeben.

Kennzeichnend für die Planungsphase ist, dass Benutzer, die als Planer angelegt wurden, jetzt in der Lage sind, Ihre Zahlen einzutragen und durch die verschiedenen Formulare zu navigieren. All die Aktionen, die zu Beginn unter "Planungsvorbereitung" gelistet warten, stehen jetzt nicht mehr zur Verfügung. Sollte dies aber nötig sein, weil z.B. Änderungen am Modell erforderlich sind oder IST-Daten eingespielt werden müssen, muss die Planung pausiert werden. ### Planung pausieren (Planung inaktiv) Sollten Sie nach dem Starten der Planung Änderungen an Modell, Team oder den Daten in QVANTUM hochladen wollen, müssen Sie die Planung pausieren. Dadurch sperren Sie den schreibenden Zugriff von Planern auf das System, während Sie die Planung aktualisieren. Mit dem anschließenden Fortsetzen der Planung werden die Sperren für Ihre Planer wieder aufgehoben. Um eine Planung fortzusetzen, müssen die gleichen Anforderungen bezüglich Modell, Daten, Team und Formularen erfüllt werden, wie beim Starten der Planung. ### Planung beenden (Planung inaktiv) Durch das Beenden der Planung wird die Eingabe in die Formulare für alle Planungsberechtigten gesperrt. In diesem Workflow-Status können Sie alle gesammelten [Plandaten exportieren](/user/ubersicht-uber-die-planung/ubersicht_uber_den_tab_ubersicht#plandaten-exportieren) und anschließend eine neue Planungsrunde vorbereiten.

### Plandaten exportieren Exportieren Sie die gesammelten Plandaten aus, um sie in anderen Programmen weiterzuverarbeiten. Wenn Sie den Button „Plandaten exportieren“ klicken, gelangen Sie in den Tab [Daten](/user/ubersicht_uber_den_tab_daten), wo Sie Ihre Daten exportieren können. Das bisherige [Modell](/user/modell/ubersicht_uber_den_tab_modell) und [Team](/user/team/ubersicht_uber_den_tab_team), sowie die gesammelten Plandaten bleiben erhalten, solange Sie sie nicht mit neuen Informationen überschreiben.

Sollten Sie direkt auf den Button „Neue Planung vorbereiten“ klicken, ohne vorher die Plandaten exportiert zu haben, können Sie dies noch nachholen.

### Auswirkungen Die folgende Tabelle zeigt, welche Auswirkungen das Starten, Pausieren oder Beenden der Planung haben. | Status | Auswirkungen auf Owner | Auswirkungen auf Planer | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Planung in Vorbereitung | Der Owner kann die Planung in Ruhe vorbereiten. | Planer haben aktuell noch keinen Zugriff auf die Planung. | | Planung gestartet | Der Owner kann den Planungs- und Onlinestatus seiner Planer verfolgen. Er kann aber keine Änderungen am Planungsmodell vornehmen. | Planer erhalten Zugang zur Planung und können Plandaten eingeben. | | Planung pausiert | Der Owner kann das Planungsmodell verändern. Nach Änderung des Planungsmodells wird der gesamte Planungswürfel neu gerechnet. | Das Speichern von Plandaten ist für Planer temporär gesperrt. Der lesende Zugriff ist aber weiterhin möglich. | | Planung beendet | Der Owner schließt die Planung ab. | Planer können die Planung nicht mehr Eingabe von Werten ist für Planer bis zur nächsten Planung nicht möglich. | | Planung beendet, exportiert | Der aktuelle Stand der Daten wurde erfolgreich exportiert. | Die Eingabe von Werten ist für Planer bis zur nächsten Planung nicht möglich. | {% hint style="warning" %} Insbesondere bei Wechseln des Workflow-Status, die das weitere Speichern von Plandaten durch Planer verbieten (z. B. Pausieren oder Beenden) sollten der Owner vorher die individuellen Online-Status seiner Planer auf dem Team-Tab der Planung überprüfen (vgl. [Team Tab](/user/team/ubersicht_uber_den_tab_team)). {% endhint %} ### Planungsstatus Mit Starten einer Planung werden die Zugänge der Planer aktiviert und ihr Planungsstatus initialisiert. Folgende Ausprägungen sind möglich: * *Offen*: der Planer arbeitet noch an seinem Beitrag zur Gesamtplanung. Initialer Status. * *Eingereicht*: der Planer hat seinen Beitrag zur Gesamtplanung zur Prüfung durch den Owner eingereicht. * *Angenommen*: der Owner hat den Beitrag des Planers geprüft und abgenommen. ### Planungsstatus aus Sicht des Planers In der Planer-Sicht wird der Planungsstatus prominent in der oberen Navigationsleiste angezeigt.

Ausschließlich im Zustand einer aktiven Planung kann ein Planer seinen Planungsstatus aktiv setzen. Sobald ein Planer seine Planung abgeschlossen hat, kann er seinen Planungsstatus über das Dropdown von "Offen" auf "Eingereicht" setzen. Damit signalisiert er dem Owner, dass sein Beitrag zur Prüfung bereitsteht. Mit Einreichung ist die weitere Eingabe von Planwerten für den Planer gesperrt. Eine Änderung des Planungsstatus durch den Planer ist ebenfalls nicht mehr möglich. Möchte der Planer seine Einreichung zurückziehen, so kann der Owner seinen Planungsstatus wieder auf "Offen" zurücksetzen und damit ein erneutes Verändern der Plandaten und Einreichung ermöglichen. Die Kommunikation über ein solches Zurücksetzen muss allerdings außerhalb der Anwendung erfolgen. ### Planungsstatus aus Sicht des Owners Der Owner kann über den [Team-Tab](/user/team/ubersicht_uber_den_tab_team) bei aktiver Planung für jeden Planer sowohl dessen Planungsstatus einsehen als auch beliebig verändern. Die Gesamtheit der individuellen Planungsstatus aller Planer dient dem Owner dabei als Fortschrittsanzeige für seinen gesamten Planungs-Workflow. Das Ändern individueller Planungsstatus gibt dem Owner die volle Kontrolle über alle Einreichungen von Planern. Auch wenn prinzipiell beliebige Statusänderungen durch den Owner möglich sind, kommen in der Praxis nur wenige gängige Statusänderungen vor: * "Eingereicht" -> "Offen": der Planer möchte seine Einreichung zurückziehen und fordert beim Owner eine erneute Öffnung an. * "Eingereicht" -> "Abgenommen": der Owner hat den Beitrag des Planers geprüft und akzeptiert. Mit der Änderung dokumentiert er für sich und den Planer die erfolgreiche Abnahme. * "Abgenommen" -> "Offen": der Owner stellt nach erfolgter Abnahme Mängel am Beitrag des Planers fest und fordert diesen zur Überarbeitung auf. # Modell Lernen Sie, wie Sie das Modell an Ihre Anforderungen anpassen können. Fügen Sie eine ganze Dimension oder auch nur fehlende Elemente hinzu. Das **Modell** bildet die strukturelle Grundlage Ihrer Planung in QVANTUM. In diesem Kapitel erfahren Sie, wie Sie ein Modell aufbauen, verwalten und an Ihre individuellen Anforderungen anpassen. Sie lernen die zentralen Konzepte von Dimensionen, Hierarchien und Planungseinheiten kennen und erhalten praktische Anleitungen zur Modellierung Ihrer Datenstruktur. Zudem wird erläutert, wie Sie bestehende Modelle optimieren, Berechnungen integrieren und die Datenbasis effizient für Ihre Planung nutzen können. Dieses Wissen ermöglicht es Ihnen, QVANTUM gezielt an Ihre geschäftlichen Anforderungen anzupassen und eine leistungsfähige Planungsumgebung zu schaffen.

# Übersicht über den Tab Modell Modell importieren, exportieren und die Modellvorlage herunterladen. > Der Tab „Modell“ ist nur für Benutzer mit der QVANTUM-Benutzerrolle „Controller“ verfügbar. Die Definition des Modells wird über eine Excel-Vorlage vorgenommen. Darin sind die einzelnen Dimensionen und deren Strukturelemente mitsamt Einstellungsmöglichkeiten beschrieben. Hilfe zur Modellerstellung finden Sie [hier](/user/modell/arbeiten_mit_der_modellvorlage). Auf dem Modell Tab stehen Ihnen folgende Funktionen zur Verfügung: * **Modell importieren** Mit dem Import können Sie das aktuell hinterlegte Modell überschreiben oder aktualisieren. * **Modell exportieren**\ Das Modell, das Ihrer Planungsanwendung zugrunde liegt, kann heruntergeladen werden. Wenn Sie Änderungen am Modell vornehmen wollen, sollten Sie vorher unbedingt immer das aktuelle Modell herunterladen und die Änderungen in diesem Dokument einpflegen. * **Standard-Vorlage herunterladen**\ Hierbei handelt es sich um eine Beispiel Modellvorlage, die aber nicht dem hinterlegten Modell entspricht. Diese Vorlage richtet sich an Anfänger, um ein Verständnis für die Struktur eines Modells zu schaffen. Unsere initiale Modellvorlage unterstützt Sie dabei mit vielen Beispielen und Erklärungen.

### Modell importieren (überschreiben/aktualisieren) Wenn Sie ein neues Modell importieren wollen, wählen Sie nach Klick auf "Modell importieren" den Pfad zu der Excel-Datei, in der Sie das Modell zuvor definiert haben. Qvantum fragt jetzt, ob das Modell überschrieben oder aktualisiert werden soll. * **Modell überschreiben**\ Das aktuelle Modell, das Ihrer Planungsanwendung zugrunde liegt, kann überschrieben werden. Beachten Sie, dass dabei sämtliche Inhalte (Daten, Formulare, Teammitglieder, ...) verloren gehen. Sichern Sie vorher unbedingt Ihre Daten und Konfigurationsdateien. Bei bestimmten Änderungen am Modell, wie z.B. dem Hinzufügen einer neuen Dimension, ist es allerdings erforderlich, das Modell zu überschreiben, da die bisherigen Daten nicht mehr in das neue Modell passen. * **Modell aktualisieren**\ Das aktuelle Modell, das Ihrer Planungsanwendung zugrunde liegt, kann aktualisiert werden. "Aktualisieren" Sie das Modell, wenn Sie das bisher eingerichtete System beibehalten wollen und lediglich den bisherigen Strukturen etwas hinzugefügt haben. In der Personalkostenplanung kann das z.B. ein neuer Mitarbeiter sein, der der bestehenden Organisationsstruktur hinzugefügt werden muss. Ein allgemeineres Beispiel ist das Hinzufügen eines neuen Jahres in der Dimension "Jahre". Beachten Sie hierbei, dass Ihre Änderungen am Modell auf die bisherigen Strukturen passen muss, damit Daten und Formulare weiterhin funktionieren. Sollte das nicht der Fall sein, nimmt Qvantum die Datei nicht an, um sicherzustellen, dass Ihre Daten und das System erhalten bleiben.

Nachdem Sie "Aktualisieren" oder "Überschreiben ausgewählt haben, startet der Import. Dieser Vorgang besteht aus zwei Teilen: * Hochladen der Modelldatei. * Neurechnen des gesamten Würfels, da sich die Zahlen durch die Änderungen am Modell geändert haben können. Dieser Vorgang kann je nach Größe des Modells und Umfang der hinterlegten Daten im System sehr lange dauern.

*Der Upload der Modelldatei war erfolgreich. Das Modell wird jetzt geprüft und der Würfel wird neu gerechnet.*

### Modell exportieren Laden Sie das aktive Modell, dessen Elemente und Merkmale herunter, um diese lokal zu bearbeiten. Über den Button "Modell herunterladen" wird eine Definition des aktiven Modells über eine Excel Datei erstellt, die Sie lokal sichern können. Nutzen Sie diese Datei...: * ...wenn Sie Änderungen am Modell vornehmen wollen und sicherstellen wollen, dass Sie das aktuelle Modell bearbeiten. * ...wenn Sie das Modell in einer weiteren Qvantum Planungsanwendung, z.B. zu Testzwecken hochladen wollen. * ...wenn Sie einfach nur das Modell lokal sichern wollen. ### Initiale Modellvorlage herunterladen QVANTUM stellt Ihnen eine Vorlage für Ihr Planungsmodell zur Verfügung. Dabei handelt es sich um eine speziell aufbereitete Excel Datei, die neben einem Beispielmodell auch viele Erklärungen und Hilfetexte beinhaltet. Mit einem Klick auf „Modellvorlage herunterladen“ öffnet sich die Datei in Excel und Sie können sie entsprechend Ihrer eigenen Wünsche anpassen. Wenn Sie mehr darüber erfahren möchten, wie Sie die Excel Datei füllen, finden Sie weitere Informationen auf der Seite [Modellvorlage](/user/modell/arbeiten_mit_der_modellvorlage). # Arbeiten mit der Modellvorlage Definition und Upload des Planungsmodells, Dimensionseigenschaften und Dimensionen definieren. Unsere Modellvorlage hilft Ihnen bei der Definition Ihres Modells anhand eines Beispiel-Vertriebsplans. In der folgenden Anleitung finden Sie eine detaillierte Schritt-für-Schritt-Anleitung. Wo Sie diese Datei finden, ist auf der Seite „[Modell](/user/modell/ubersicht_uber_den_tab_modell#initiale-modellvorlage-herunterladen)“ beschrieben. ### Aufbau der Modellvorlage Die Excel-Modellvorlage unterteilt sich in viele Tabs (Arbeitsblätter), die hier im Folgenden beschrieben werden.

*Die Excel-Modellvorlage ist in viele Arbeitsblätter zur Definition der einzelnen Dimensionen unterteilt*

Die Tabs im Detail: * **Info**\ Auf diesem Reiter finden Sie weitere Hilfestellungen zur Verwendung dieser Vorlage. * **Planungsmodell**\ Alle im Folgenden definierten Dimensionen (eine pro Arbeitsblatt) müssen hier gelistet sein. Außerdem muss jeder Dimension eine Rolle zugeordnet sein. Weitere Informationen zu den Rollen gibt es hier. * *Dimensionen (ein Blatt pro Dimension)*\* ### Planungsmodell Ein Planungsmodell beschreibt eine Anwendung in Form eines multidimensionalen Würfels. Die Dimensionen des Würfels sollten dabei alle Aspekte Ihrer Planung abdecken. Hierdurch wird sichergestellt, dass Sie Ihre Daten unter Berücksichtigung aller benötigten Perspektiven und in diversen Detaillierungsstufen betrachten und bearbeiten können. Jedes Datenelement (d.h. jede Zahl) in diesem multidimensionalen Würfel wird pro Dimension eindeutig einem Dimensionselement zugeordnet. Diese Dimensionselemente entsprechen somit anschaulich den Koordinaten einer Würfelzelle in der das Datenelement gespeichert wird. Zunächst gilt es ein **Modellkürzel** und eine **Modellbezeichnung** festzulegen. Das Modellkürzel dient der eindeutigen Identifikation Ihrer Planung. Wenn Sie z. B. nachträglich die Bezeichnung Ihrer Planung ändern möchten, geschieht dies unter der Angabe dieses Kürzels. Die Modellbezeichnung ist der Name Ihres Planungsmodells. Sie wird in QVANTUM an verschiedenen Stellen angezeigt. **Modellbeschreibung**: hier können Sie eine ergänzende Beschreibung für Ihr Planungsmodell hinterlegen. Dieses Feld ist nicht verpflichtend.

*Abbildung 2 - Der Tab "Planungsmodell" in der Modellvorlage*

Bevor wir uns den Tabs für die Dimensionen zuwenden, sollten Sie sich im Klaren sein, welche Dimensionen Ihre Planungsanwendung benötigt. Jede Dimension, die später auf einem eigenen Tab im Detail beschrieben wird, muss hier auf dem Tab „Planungsmodell“ gelistet sein. Dabei müssen die folgenden Spalten für jede verwendete Dimension befüllt werden: * **Nummer**\ Die gelisteten Dimensionen müssen aufsteigend durchnummeriert sein (1-x). Die Nummer dient der eindeutigen Identifikation der Dimension im Planungsmodell. Wenn Sie z. B. nachträglich die Bezeichnung Ihrer Dimension ändern möchten, geschieht dies unter der Angabe dieser Nummer. Ihr Planungsmodell besteht aus verschiedenen Dimensionen. * Die **Dimensionsbezeichnung**\ Die Dimensionen tauchen in QVANTUM an verschiedenen Stellen mit **Singular- oder Plural-Bezeichnung** auf. Hier können Sie die Bezeichnungen festlegen. Für jede Dimension müssen Sie ein weiteres Blatt in der Excel-Datei definieren. Dieses Blatt trägt den Pluralnamen der Dimension und dort können Sie Dimensionselemente definieren. * Die **Dimensionsrolle**\* * **Dimensionsbeschreibung** Wenn Sie zu Beginn noch unsicher sind, welche Dimensionen in Ihrer Planung enthalten sind, können Sie sich auch zuerst den im Folgenden beschriebenen Dimensionsblättern zuwenden und zum Schluss wieder zum Tab "Planungsmodell" zurückkehren. \***) Dimensionsrollen** Es gibt Dimensionen, die besondere Aufgaben in Ihrer Planung übernehmen. Diese Dimensionen werden über die Dimensionsrollen identifiziert. Folgende Dimensionsrollen gibt es: **Kennzahlen (Pflichtangabe):** Die Dimension, die Ihre Kennzahlen identifiziert. Diese Rolle muss genau einer Dimension zugeordnet werden. Kennzahlen sind die quantitativen Inhalte die typischerweise im Controlling abgebildet werden, wie z. B. Absatzmengen, Erlöse, Kosten. Diesen Kennzahlen können sogenannte [Wertetypen](/user/einstellungen/systemeinstellungen) (Betrag, Prozentsatz, Preis, Menge, Bestand) zugeordnet werden, die auf dem Excel-Blatt zu dieser Dimension anzugeben sind. In dieser Dimension können außerdem Formeln zur Berechnung der jeweiligen Kennzahl hinterlegt werden. So könnte z.B. für die Kennzahl "Umsatz" die folgende Formel gelten: Umsatz = Preis \* Menge **Planungseinheiten (Pflichtangabe):** Die Dimension mit der Dimensionsrolle Planungseinheiten deckt den organisatorischen Aspekt einer Planung ab und steht oft im Zusammenhang mit Planungsverantwortlichkeiten für bestimmte Planungseinheiten, z. B. Bereiche, Filialen, etc. Diese Rolle kann genau einer Dimension zugeordnet werden. Merkmale, die in Planungseinheiten-Dimensionen erstellt werden, können später auch von den Planern bearbeitet werden. Merkmale anderer Dimensionen hingegen können nur von den Ownern/Controllern erstellt werden. **Zeit (optional):** Diese Rolle können Sie genau einer Dimension mit Zeitcharakter zuordnen. Jahr- und Monatsdimensionen sind übliche Beispiele solcher Dimensionen. Möchten Sie mit Zeitversatzformeln arbeiten (z. B. Umsatz = Umsatz Vorjahr + 10%), so ist dies nur auf Dimensionen mit der Rolle Zeit möglich. **Ohne besondere Rolle:** Diese Rolle können Sie allen übrigen Dimensionen zuordnen. ### Ein Tab für jede Dimension Nachdem Sie den Tab "Planungsmodell" befüllt haben, muss sich für jede dort aufgeführte Dimension ein eigener Tab in der Modellvorlage befinden.

Schauen wir uns nun an, anhand welcher **Spalten** die Elemente einer Kennzahlen-Dimension definiert werden. In der folgenden Abbildung sind die **Spalten** gelistet, mit denen eine Dimension beschrieben werden kann. Dabei wird grundsätzlich unterteilt in die Dimension "Kennzahlen" und alle übrigen Dimensionen.

*Der Tab "Kennzahlen" in der Modellvorlage*

#### Schlüssel In dieser Spalte geben Sie den Schlüssel Ihrer Dimensionselemente ein. Schlüssel müssen nicht nur pro Dimension sondern innerhalb des ganzen Modells **eindeutig** sein. Eine als Schlüssel verwendete Zeichenkette darf also an keinem weiteren Element als Schlüssel verwendet werden. #### Übergeordneter Schlüssel Um hierarchische Dimensionen zu erhalten, können Sie in dieser Spalte für jedes Element ein übergeordnetes Element definieren. Dieses Element muss bereits vor der Verwendung oberhalb in der Tabelle als Schlüssel eingetragen worden sein. Verschiedene Elemente dürfen das selbe übergeordnete Element haben. In der folgenden Abbildung ist die Dimension "Monate" abgebildet. Ganz oben steht das Gesamtjahr, dem wir den Schlüssel "GJ" geben. Die einzelnen Quartale sitzen auf der zweiten hierarchischen Ebene und ihr übergeordneter Schlüssel heißt "GJ". Die Monate befinden sich auf der dritten hierarchischen Ebene. Der übergeordnete Schlüssel für die Monate Januar bis März wäre demnach "Q1".

*Eine hierarchische Struktur am Beispiel der Dimension "Monate"*

*Die Dimension Monate aus der Modellvorlage*

Wollen Sie statt einer hierarchischen Dimension lieber eine flache Dimension haben, lassen Sie die Spalte „übergeordneter Schlüssel“ in jeder Zeile leer. So werden alle Elemente auf oberster Ebene angelegt. #### Bezeichnung In dieser Spalte können Sie die Bezeichnung Ihrer Elemente festlegen.

*Bezeichnung der Elemente in der Dimension Monate*

In den Formularen werden die Elemente später anhand ihrer Bezeichnung gelistet. #### **Eingabe erlaubt?** Hier können Sie für jedes Dimensionselement festlegen, ob hierzu im Planungsmodell Daten eingegeben werden dürfen.

*Die Spalte "Eingabe erlaubt" in der Dimension Monate*

**Hinweis**: Bitte beachten Sie, dass eine Dateneingabe im multidimensionalen Würfel des Planungsmodells nur möglich ist, wenn alle einer Würfelzelle zugeordneten Dimensionselemente bei „Eingabe erlaubt?“ die Einstellung „**Ja**“ besitzen. Wählen Sie die Einstellung „**Nein**“, wenn Sie sicherstellen wollen, das auf dem Dimensionselement unabhängig von der Kombination mit Elementen anderer Dimensionen grundsätzlich keine Eingabe erfolgen soll. Oft empfiehlt es sich, die Eingabe auf Knoten zu sperren, um die Planer zur Eingabe der Werte auf den unteren Elementen zu verpflichten. Indem Sie z.B. auf den Knoten "Quartal 1", "Erstes Halbjahr" und "Gesamtjahr" die Eingabe unterbinden, ist der Planer gezwungen, seine Zahlen auf Monatsbasis einzutragen. Beachten Sie, dass Kennzahlen, auf denen eine Formel eingetragen ist, keine Eingabe erlauben. Denn der durch die Formel berechnete Wert würde nach dem Speichern jede Eingabe wieder überschreiben. Ein Element, auf dem grundsätzlich die Eingabe erlaubt ist, kann aber erst dann von einem Planer beschrieben werden, wenn es (a) ein Formular gibt, in dem sich das Element beschreiben lässt und (b) dem jeweiligen Benutzer nicht das Recht zum Beschreiben dieser Dimension/Elemente genommen wurde. Mehr zu den Benutzerrechten finden Sie [hier](/user/team/nutzer-berechtigungen_in_qvantum_definieren). #### Wertetyp Die Spalte Wertetyp gibt es nur auf dem Dimensions-Tab "Kennzahlen". Folgende Typen sind verfügbar: Betrag, Prozentsatz, Preis, Menge, Bestand. Wertetypen beschreiben, wie die Zahlen zu dieser Kennzahl formatiert werden. Sie können die Wertetypen in der Software konfigurieren. Hilfe dazu finden Sie [hier](/user/einstellungen/systemeinstellungen#wertetypen). #### Beschreibung In dieser Spalte besteht die Möglichkeit, zusätzlich eine Beschreibung pro Dimensionselement zu hinterlegen. Dieses Feld ist nicht verpflichtend. #### Ebenenname Die Befüllung der Spalte "Ebenenname" ist optional. Um in Formularen mit verschachtelten Ebenen arbeiten zu können, muss jede hierarchische Ebene einer Dimension, die dort verwendet wird, benannt sein. Die Dimension Monate kann z.B. hierarchisch in Gesamtjahr, Quartal und Monate unterteilt sein. Die drei hierarchischen Ebenen wären dann Gesamtjahr, Quartal und Monate. Es reicht aus, wenn jeweils das erste Element, das auf einer Ebene vorkommt, benannt wird.

#### Aggregation Wenn Sie in dieser Spalte für ein Dimensionselement den Wert "Summe" auswählen oder das Feld leer lassen, wird dieses Element durch die Addition seiner untergeordneten Elemente berechnet. Das sind die Elemente, die diesem Element untergeordnet sind (zum Beispiel sind die Elemente "Januar", "Februar" und "März" dem Element "Quartal 1" untergeordnet). Wenn Sie keine Addition wünschen, können Sie den Wert auf "Nicht aggregieren" setzen. Beachten Sie, dass die Aggregation in der Kennzahlen-Dimension über die Formelspalte definiert wird. **ACHTUNG!** In der Dimension "Kennzahlen" wird die Aggregationsregel in der Formelspalte festgelegt. Wenn Sie möchten, dass ein Knoten die Summe seiner untergeordneten Elemente enthält, tragen Sie in der Formelspalte die folgende Syntax ein: **SumOfChildren()** #### Formel Formeln können nur in der Dimension mit der Rolle Kennzahlen vergeben werden. Folgende Rechenoperationen sind erlaubt: * Addition (+) * Subtraktion (-) * Multiplikation (\*) * Division (/) * SumOfChildren() Wenn Sie auf andere Elemente der Kennzahlen-Dimension in einer Formel zugreifen möchten, setzen Sie den Wert vom "Schlüssel"-Feld des gewünschten Elements in eckige Klammern. **Beispiel:** Kennzahl Erlöse = \[VE]\*\[PPE]\ **VE** = Schlüssel für "Verkaufte Einheiten"\ **PPE** = Schlüssel für "Preis pro Einheit" Weitere Informationen zur Verwendung von Formeln finden Sie [hier](/user/modell/rechenoperationen_und_formelsyntax). #### Alternative Formel für aggregierte Ebenen In dieser Spalte können Sie optional eine Formel angeben, die statt der Formel in der Spalte "Formel" für all solche Zellen gerechnet werden soll, die für mindestens ein Dimensionselement einen Knoten mit darunterliegender Hierarchie adressieren. Die Formelsyntax ist dabei die gleiche wie für Formeln in der Spalte "Formel". ### Upload der Planungsanwendung Wenn Sie diese Vorlage nach Ihren Anforderungen ausgefüllt und (unter einem eigenen Namen) als Excel-Modell-Datei gespeichert haben, können Sie zurück zur QVANTUM Web-Anwendung wechseln und diese Modelldefinition hochladen. Anschließend steht Ihnen das hochgeladene Modell zur weiteren Bearbeitung in der Cloud zur Verfügung. **Die nächsten Schritte:**\ Sollte das in QVANTUM erzeugte Modell noch nicht Ihren (endgültigen) Anforderungen entsprechen, können Sie erforderliche Änderungen direkt in Ihre Excel-Datei einpflegen und den Upload wiederholen. Sofern Sie Daten (z.B. Ist-Daten vergangener Perioden) in das Modell übernehmen wollen, können Sie sich auf dem "Daten Tab" eine zur Ihrem Modell passende Datenimportvorlage herunterladen, diese mit Daten befüllen und wieder hochladen.

*Download der Datenvorlage auf dem "Daten Tab"*

Entspricht das Modell Ihren Vorstellungen, so öffnen Sie Ihre QVANTUM Web-Anwendung und fahren Sie dort mit der Vorbereitung Ihrer Planung fort. Laden Sie Ihre Benutzer im Tab „Team“ hoch, die dann bei Start der Planung automatisch eine Mail mit einem Einladungslink erhalten. Nach Erfassen der Plandaten durch die beteiligten Planer, können Sie die Planung in Qvantum beenden und Ihre Export-Berichte abrufen.

*Beenden der Planung auf dem Reiter "Übersicht"*

*Plandatenexport nach abgeschlossener Planung*

Mehr zum Workflow über den "Übersichts-Tab" finden Sie [hier](/user/ubersicht-uber-die-planung/der_workflow). # Bearbeiten des Modells in Qvantum Entdecken Sie die verschiedenen Anpassungsmöglichkeiten, die Ihnen in Qvantum zur Verfügung stehen, um Ihr Modell individuell zu gestalten. Im Bereich "Modell" auf dem Tab "Strukturen" haben Sie die Möglichkeit, die Strukturen sämtlicher Dimensionen einzusehen. Die nachfolgende Abbildung veranschaulicht den Aufbau dieser Ansicht. Auf der linken Seite finden Sie eine Liste aller verfügbaren Dimensionen. Wählen Sie eine Dimension aus, werden in der rechten Box die dazugehörigen Strukturelemente in einer hierarchischen Anordnung angezeigt. Hier können Sie zudem alle erforderlichen Einstellungen vornehmen.

\ Bearbeiten-Modus Durch Klicken auf den Bearbeiten-Button gelangen Sie in den Bearbeiten-Modus. In dieser Ansicht verwandelt sich der Bearbeiten-Button in einen Speichern-Button, sodass Sie nun Anpassungen am Modell vornehmen können.

Bitte beachten Sie, dass Ihre Änderungen erst wirksam werden, wenn Sie den Speichern-Button betätigen. Wir empfehlen Ihnen, auch die [Hinweise zum Speichern](#Speichern-Vorgang) am Ende des Kapitels zu lesen, um mögliche Unklarheiten zu vermeiden. ### Konfigurieren der Strukturen Wählen Sie zunächst die Dimension aus, in der Sie Anpassungen an der Struktur vornehmen möchten. Nach einem Klick auf die gewünschte Dimension werden in der rechten Konfigurationsbox die entsprechenden Elemente angezeigt. Es ist wichtig zu beachten, dass die verschiedenen Dimensionen unterschiedliche Funktionen erfüllen, wodurch sich auch die verfügbaren Konfigurationsmöglichkeiten unterscheiden. So wird beispielsweise der Wertetyp (siehe nachfolgende Abbildung) ausschließlich in der Dimension der Kennzahlen angezeigt.

*Die Dimension Kennzahlen erlaubt auf Strukturebene die Zuweisung der Wertetypen.*

*Um ein Strukturelement umzubenennen, genügt ein Doppelklick auf das jeweilige Element - vorausgesetzt, Sie befinden sich im Editiermodus.*

![](https://lp.qvantum-plan.de/hubfs/image-png-Nov-25-2024-04-41-20-2429-PM.png) Der Funktionsumfang der Ansicht "Strukturen" wird derzeit weiterentwickelt. In naher Zukunft werden zusätzliche Informationen bereitgestellt, darunter auch Anleitungen zum Verschieben von Elementen und weiteren Funktionen. ### Hinweise zum Speichern-Vorgang Änderungen wie das "Umhängen" von Strukturelementen erfordern eine vollständige Neuberechnung des Datenwürfels. Dieser Prozess ist notwendig, da die Umstrukturierung der Strukturelemente Auswirkungen auf die gesamte Datenarchitektur hat und somit die Integrität der Daten sicherstellen muss. Während der Neuberechnung werden alle betroffenen Daten neu aggregiert und analysiert, um die aktuellen Werte und Kennzahlen korrekt darzustellen. Die Dauer dieses Prozesses kann je nach Größe des Würfels, der verwendeten Kennzahlenformeln und der enthaltenen Daten erheblich variieren. Kleinere Datenwürfel mit einfachen Formeln können in nur wenigen Minuten aktualisiert werden, während komplexe Würfel mit umfangreichen Datensätzen und komplizierten Berechnungen möglicherweise bis zu einer Stunde oder länger für die Neuberechnung benötigen. Es ist wichtig, während dieser Zeit Geduld zu haben und sicherzustellen, dass keine weiteren Änderungen am Modell vorgenommen werden, um inkonsistente Daten oder Fehler zu vermeiden. # Segmente und Kennzahlenformeln Lernen Sie, wie sie eine Segmentierung erstellen und die Kennzahlen in Ihrem Modell mit Formeln belegen können. Mit dem Formelmanager von Qvantum haben Sie die Möglichkeit, die Kennzahlen in Ihrem Modell einfach und effektiv mit Formeln zu verknüpfen. Wir unterstützen Sie bereits während der Formeleingabe mit einer Echtzeit-Validierung, die überprüft, ob die Formel im Modell gültig ist. Die nachfolgende Abbildung zeigt, wie sich die Ansicht unter *Modell > Formeln* zusammensetzt.

*Segmente (1) und die darin enthaltenen Kennzahlenformen (2)*

### **Segmente** Lassen Sie uns zunächst klären, was mit dem Begriff „Segmente“ im Zusammenhang mit einem Datencube gemeint ist und welche Funktionen sie erfüllen. Ein **Segment** ist ein definierter Teilbereich des Datenwürfels, der spezifische Daten anhand von Dimensionen (z. B. Varianten, Jahre) umfasst. Segmente werden genutzt, um Berechnungen und Formeln gezielt auf bestimmte Bereiche des Datenmodells anzuwenden, anstatt auf den gesamten Würfel. #### Grund 1: Nicht rechnen Formeln können in Qvantum für jede Kennzahl definiert werden. Ohne die Verwendung von Segmenten gilt jedoch eine Kennzahlenformel für den gesamten Datenwürfel. Stellen Sie sich vor, Sie importieren die IST-Werte des vergangenen Jahres aus einem anderen System in Qvantum, sei es manuell oder automatisiert über eine API. Anschließend stellen Sie fest, dass die angezeigten Werte in Qvantum nicht mit den hochgeladenen Werten übereinstimmen. Der Grund dafür liegt in den Kennzahlenformeln, die auf den gesamten Würfel angewendet werden und somit die importierten Werte teilweise überschreiben können. Um dieses Problem zu vermeiden, können wir den Würfel in zwei Segmente aufteilen. * **Die IST-Variante**: In diesem Segment soll keine Berechnung stattfinden. * **Alle anderen Varianten**: Hier sollen Berechnungen durchgeführt werden. Die folgende Abbildung veranschaulicht das Konzept dieser Segmentierung.

*Die Ist-Variante wird von den übrigen Varianten abgeschnitten*

#### Grund 2: Anders rechnen Bestimmte Kennzahlen basieren auf Konstanten, die sich im Laufe der Zeit ändern können. Ein Beispiel hierfür könnte der durchschnittliche Sozialversicherungsbeitrag sein, der für die Planung des nächsten Jahres verwendet wird und jährlich angepasst wird. Für das Jahr 2025 möchten wir daher eine andere Konstante in die Berechnung integrieren als für 2024. Um diese Anpassungen vornehmen zu können, benötigen wir Segmente, die den Datenwürfel in Teilwürfel für die unterschiedlichen Jahre aufteilen. ### Das Schneiden von Segmenten Um den zuvor aufgeführten Beispielen zu folgen, schauen wir uns jetzt an, wie wir den Datenwürfel entsprechend aufteilen. In der linken Box „Segmente“ sehen wir bislang nur ein einziges Segment: den Datenwürfel, hier als „Komplettes Modell“ bezeichnet. **Edit Modus** Um Änderungen an der Segmentierung oder den Formeln vorzunehmen, müssen wir zuerst den Edit-Modus aktivieren, indem wir rechts oben auf „Edit“ klicken. Wenn wir jetzt die Maus über ein Segment oder zu Beginn über das Komplette Modell in der Segmente Box bewegen, erscheint ein Plus Icon, um einen ersten Schnitt zu setzen. Die nachfolgende Abbildung zeigt den Vorgang.

*Erst im Edit Modus kann eine neue Segmentierung erstellt werden.*

**Der erste Schnitt** Nachdem Sie das Plus-Icon über dem kompletten Modell angeklickt haben, öffnet sich das Schnittfenster, in dem wir unseren ersten Schnitt entlang einer Dimension vornehmen können. In unserem Beispiel wählen wir zunächst die Dimension „Varianten“ aus, um den ersten Schnitt durchzuführen. Jetzt haben wir die Möglichkeit, ein erstes Segment zu definieren. Wir benennen dieses Segment „IST-Variante“ und wählen im Dropdown-Menü rechts die entsprechenden Elemente aus der zuvor ausgewählten Dimension aus. In diesem Fall fügen wir lediglich das Element „Ist“ hinzu. Bitte beachten Sie, dass die Dimension nach der Belegung des ersten Segments nicht mehr geändert werden kann, wie in der nachfolgenden Abbildung veranschaulicht wird. Bitte beachten Sie, dass nur Elemente **aus der obersten Ebene der Hierarchie** einem Segment zugewiesen werden können.

Im Schnittfenster können Segmente erstellt und Elemente zugewiesen werden.

Beachten Sie, dass wir automatisch mit der Erzeugung des ersten Segments unter der Dimension „Varianten“ ein weiteres Segment „Restliche Varianten“ sehen können, welches unten ausgerichtet ist. Für unser Beispiel klicken wir nun auch schon auf „Anwenden“, um zur Hauptansicht zurückzukehren. Bitte beachten Sie, dass Ihre Änderungen erst dann gespeichert werden, wenn Sie auf die Schaltfläche „Speichern“ oben rechts klicken. Unser Modell wird nun, wie in der folgenden Abbildung zu sehen ist, deutlich dargestellt. Wir haben erfolgreich unser erstes Segment erstellt, und gleichzeitig wird das automatisch generierte Segment für die übrigen Elemente angezeigt.

*In der Hauptansicht wird der neue Schnitt mit seinen jeweiligen Elementen sofort dargestellt*

Im nächsten Schritt klicken wir in der Segmente-Box auf das neu erstellte Segment. Dadurch wird es hervorgehoben, und in der rechten Box erscheint die Überschrift: Kennzahlen und Formeln für: Ist-Variante

Der gesamte Inhalt der rechten Box bezieht sich auf das neu erstellte Segment „Ist-Variante“. Zunächst werden alle zuvor im Modell konfigurierten Formeln auch in diesem Segment angezeigt, jedoch sind sie hier lediglich „vererbt“. Da wir im Segment „Ist-Variante“ keine Berechnungen vornehmen möchten und die importierten Daten unverändert bleiben sollen, ist es notwendig, die geerbten Formeln anzupassen. Dazu bewegen Sie im Editiermodus die Maus über eine Formel, wodurch ein Editier-Icon (Stift) erscheint. Durch einen Klick auf dieses Icon können Sie den Bearbeitungsmodus aktivieren. Die Formel wird dann im oberen Eingabefeld angezeigt, ähnlich wie in Excel.

Im Dropdown-Menü auf der linken Seite können Sie den Modus auswählen. Zur Verfügung stehen die Optionen: „Formel erben“, „Freie Formel“ und „Nicht rechnen“. Für unser Beispiel wählen wir die Option „Nicht rechnen“.

Das Eingabefeld für die Formel wird daraufhin geleert und ausgegraut, um anzuzeigen, dass keine Berechnung stattfindet. Klicken Sie auf „Übernehmen“ und wiederholen Sie diesen Vorgang für alle Formeln in diesem Segment. In der Kennzahlenbox wird jede erfolgreich geänderte Formel mit einer grünen Checkbox markiert, was bestätigt, dass die Änderung gültig ist. #### Formel-Validierung Beim Ändern von Formeln erfolgt eine sofortige Validierung Ihrer Eingaben in Echtzeit. Dadurch können Sie sofort feststellen, ob Fehler vorhanden sind. Solche Fehler können beispielsweise ungültige oder nicht existierende Schlüssel für andere Kennzahlen umfassen, die in der Formel verwendet werden. Zudem besteht die Möglichkeit, dass es zu Zykelbildungen kommt, was ebenfalls zu einem Fehler führen kann und dazu führen könnte, dass Ihre Änderungen nicht gespeichert werden. ### Der zweite Schnitt Nachdem wir die Ist-Variante im ersten Schnitt erfolgreich als Teilwürfel definiert haben, der keine Berechnungen durchführt, wenden wir uns nun der zweiten Anforderung zu: In den verschiedenen Jahren sollen bestimmte Formeln mit unterschiedlichen Konstanten berechnet werden. Um dies zu erreichen, betrachten wir erneut die Segmente-Box und fügen eine zweite Segmentierung unterhalb der „restlichen Varianten“ hinzu. Dazu klicken wir auf das Plus-Icon über dem Segment „restliche Varianten“, woraufhin das Schnittfenster geöffnet wird. In diesem Schritt wählen wir die Dimension „Jahre“ aus. Anschließend erstellen wir für jedes Jahr, in dem abweichende Berechnungen erforderlich sind, separate Segmente. Diese Segmente werden dann entsprechend angeordnet und dargestellt.

Jetzt können die einzelnen Jahre unabhängig voneinander bearbeitet werden. Wenn Sie das gewünschte Segment auswählen, haben Sie die Möglichkeit, die Kennzahlenformeln spezifisch für jedes Jahr anzupassen. Hierzu müssen Sie lediglich die Formeln anpassen, die von den Standardberechnungen abweichen. Klicken Sie auf das Edit-Icon der entsprechenden Formel, um diese in das obere Eingabefeld zu übertragen. Ändern Sie anschließend den Modus von „Formel erben“ auf „Freie Formel“, nehmen Sie die erforderlichen Anpassungen vor und bestätigen Sie Ihre Eingaben mit „Übernehmen“. #### Details zur Formelbearbeitung In der nachfolgenden Abbildung wurde eine Formel über das Stift-Icon zur Bearbeitung ausgewählt.

*Das Eingabefeld zur Bearbeitung einer Formel*

Während Sie eine Formel bearbeiten, haben Sie die Möglichkeit, die Mouseover-Icons über den anderen Formeln in der Tabelle zu verwenden. Damit können Sie beispielsweise Kennzahlenschlüssel oder Teile anderer Formeln bequem in das obere Eingabefeld übertragen.

Kennzahlenschlüssel, die Sie über das Mouseover-Icon kopiert haben, können Sie einfach mit STRG+V in das obere Eingabefeld einfügen. Dabei werden die erforderlichen eckigen Klammern automatisch gesetzt, die für die korrekte Syntax unerlässlich sind. Während Sie eine Formel bearbeiten, erfolgt kontinuierlich eine Überprüfung der Eingaben, sodass Sie sofort erkennen, ob die Formel gültig ist. Weitere Informationen zur korrekten Verwendung der Syntax finden Sie unter: [Rechenoperationen und Formeln](https://lp.qvantum-plan.de/wissensdatenbank/rechenoperationen). Sobald Sie die Bearbeitung der Formel mit "Übernehmen" abgeschlossen haben, wird die bearbeitete Formel in der Liste in grüner Schrift angezeigt und erhält ein "Undo"-Symbol. Bitte beachten Sie, dass Ihre Änderungen erst gespeichert werden, wenn Sie auf den großen "Speichern"-Button oben rechts über der Tabelle klicken. Bis zu diesem Zeitpunkt haben Sie die Möglichkeit, bearbeitete Formeln über das Undo-Symbol zurückzusetzen.

So erscheint eine bearbeitete Formel in der Liste

Formeln, die in **grauer Schrift** dargestellt werden, sind **vererbt**, was bedeutet, dass sie von einem übergeordneten Segment abgeleitet sind. Diese Funktionalität reduziert den Aufwand für die Eingabe von Formeln erheblich, da nicht für jedes Segment alle Formeln neu eingegeben werden müssen. Stattdessen werden nur die Formeln angepasst und gespeichert, die spezifische Abweichungen für ein bestimmtes Segment aufweisen. Diese angepassten Formeln erscheinen dann in schwarzer Schrift.

#### Undo/Redo ![](https://lp.qvantum-plan.de/hubfs/image-png-Nov-19-2024-01-03-35-2655-PM.png) Die Bearbeitung von Formeln wird durch eine Undo/Redo-Funktion unterstützt, die es Ihnen ermöglicht, Ihre Änderungen schrittweise zurückzusetzen. Dies gewährleistet Flexibilität und Kontrolle über Ihre Eingaben. Nachdem Sie alle gewünschten Anpassungen vorgenommen haben, können Sie diese durch einen Klick auf die Schaltfläche „Speichern“ dauerhaft sichern. Bitte beachten Sie, dass solche Änderungen an Formeln oder Segmenten eine **vollständige Neuberechnung des Datenwürfels** erforderlich machen. Die Dauer dieses Prozesses kann je nach Größe und Komplexität Ihres Modells sowie der darin enthaltenen Daten variieren und entsprechend Zeit in Anspruch nehmen. ### Schematische Darstellung von Segmenten im Datenwürfel Der mehrdimensionale Würfel basiert auf den von Ihnen angelegten Dimensionen. Um ein Verständnis für das Erstellen von Segmenten zu schaffen, ist im Folgenden ein 3-dimensionaler Würfel abgebildet.

*Der Datenwürfel mit den Dimensionen Jahren und Kennzahlen*

Bisher wird die Kennzahl "Sozialversicherung" anhand einer Formel berechnet. In dieser Formel ist eine Konstante enthalten, die zur Berechnung im Jahr 2023 geeignet ist. Für 2024 muss diese Konstante abgeändert werden. Es gibt also den Bedarf, im Jahr 2024 eine andere Kennzahlenformel zu hinterlegen als im Jahr 2023. Um das zu erreichen müsste der Würfel in Segmente für die Jahre 2023, 2024 und 2025 geschnitten werden. Erst wenn für das Jahr 2024 ein eigenes Segment geschaffen ist, kann eine abweichende Formel (und somit auch eine abweichende Konstante) hinterlegt werden.

*Der Würfel wurde anhand der Dimension "Jahre" in 3 Segmente unterteilt*

# Rechenoperationen und Formelsyntax QVANTUM unterstützt die auf dieser Seite definierten Rechenoperationen und Formeln. Die hier aufgeführten Rechenoperationen und Formeln lassen sich sowohl im **Formelmanager** ([hier](https://lp.qvantum-plan.de/wissensdatenbank/segmente-und-formeln) finden Sie weitere Hilfe zur Eingabe von Formeln im Formelmanager) als auch in Berechnungsspalten von Formularen verwenden. ### Inhalt dieser Seite * Allgemeines zur Verwendung von Argumenten in Funktionen * [Rechenoperationen](#Rechenoperationen) * [Formeln und Funktionen](#Formeln-und-Funktionen) * [Vergleichsoperatoren](#Vergleichsoperatoren) ### ### Allgemeines zur Verwendung von Argumenten in Funktionen #### Allgemeine Regeln für Kennzahlformeln: * Für die Argumente einer Funktion werden in der Regel Kennzahlenschlüssel in eckigen Klammern verwendet (z.B. `ABS([DELTA])`). Alternativ können auch Konstanten genutzt werden. #### Benutzerdefinierte Zeilen- oder Spaltendefinitionen in Formularen: * In Formularen werden für die Argumente einer Funktion Zeilen- oder Spaltenbezeichner in eckigen Klammern verwendet (z.B. `ABS([3])` oder `ABS([B])`). Auch hier können Konstanten verwendet werden. #### Kombination von Ausdrücken: * Formelausdrücke können durch Kombination der oben genannten Angaben und durch Verwendung von Klammerungen gebildet werden (z.B. `ABS(([A]-[B])/[C])`). #### Funktionsaufrufe innerhalb von Formeln: * Auch Funktionsaufrufe können in den Formelausdrücken genutzt werden (z.B. `ABS(DIVIDE([1];[2];BLANK))`). #### Groß-/Kleinschreibung: * Die Groß- oder Kleinschreibung der Funktionsnamen spielt keine Rolle, sie können beliebig verwendet werden. #### Besonderheiten bei der Division: * Bei einer Division durch Null wird der Wert UNGÜLTIG erzeugt, es sei denn, die Funktion `DIVIDE` (siehe unten) wird für die Division genutzt. #### Leere Zellen: * Leere Zellen haben den Wert BLANK. #### Auswertung von Bedingungen: * Eine ausgewertete Bedingung (siehe `WENN`-Funktion) hat den Wert TRUE, wenn sie erfüllt ist, ansonsten FALSE. #### Beispiel: Eine Kennzahl für Erlöse könnte wie folgt definiert werden: `Erlöse = [VE]*[PPE]`, wobei `VE` der Schlüssel für „Verkaufte Einheiten“ und `PPE` der Schlüssel für „Preis pro Einheit“ ist. ### Rechenoperationen Addition (+)\ Subtraktion (-)\ Multiplikation (\*)\ Division ( / )\ Runde Klammern ### Formeln und Funktionen * [ABS](#abs) * [COALESCE](#coalesce) * [DIVIDE](#divide) * [RUNDEN](#runden) * [SIGN](#sign) * [WENN](#wenn) * [ZEITVERSATZ](#zeitversatz) * [isTimeElementWithoutChildren](#istimeelementwithoutchildren) * [MODULO](#modulo) * [QUOTIENT](#quotient) * [MINIMUM](#Minimum) * [MAXIMUM](#Maximum) * [SUMOFCHILDREN](#Sumofchildren) * [TIMEOFFSET](#timeoffset) * [ISBLANK](#isblank) * [ISVALID](#isvalid) * [AND](#and) * [OR](#or) * [NOT](#not) #### ABS Gibt den Absolutwert des Arguments zurück. Das bedeutet, dass alle negativen Vorzeichen entfernt werden und der positive Wert zurückgegeben wird. Syntax: ``` ABS() ``` **Sonderfälle:** * Betrag von UNGÜLTIG = UNGÜLTIG * Betrag von BLANK = BLANK #### COALESCE Gibt den ersten Ausdruck zurück, der nicht als BLANK ausgewertet wird. Wenn alle Ausdrücke als BLANK ausgewertet werden, wird BLANK zurückgegeben. Die Funktion hat mindestens 2 oder mehr Argumente. **Syntax:** ``` COALESCE(; [;…]) ``` #### DIVIDE Führt eine Division aus und gibt ein alternatives Ergebnis oder BLANK bei Division durch 0 zurück. **Syntax:** ``` DIVIDE(; [; [; ]) ``` Mit bestimmen Sie, welche Zahl gerundet werden soll. Die Anzahl der Stellen ist die Anzahl der Dezimalstellen, auf die Sie runden möchten. Bei einem negativen Wert werden Stellen links vom Dezimaltrennzeichen gerundet. Beim Wert 0 oder wenn die Anzahl der Stellen nicht angegeben wird, wird auf die nächste ganze Zahl gerundet. Die Anzahl Stellen muss eine Konstante sein. #### SIGN Gibt das Vorzeichen des gegebenen Wertes zurück. Die Funktion gibt -1, 0 oder 1 zurück, je nachdem, ob der Wert negativ, null oder positiv ist. Dies kann verwendet werden, um schnell das Vorzeichen eines Wertes zu bestimmen. Syntax: ``` SIGN() ``` **Sonderfälle:** * Betrag von UNGÜLTIG = UNGÜLTIG * Betrag von BLANK = BLANK #### WENN Prüft eine Bedingung und gibt einen Wert zurück, wenn diese TRUE ist; andernfalls wird ein zweiter Wert zurückgegeben. **Syntax:** ``` WENN(;;) ``` setzt sich zusammen aus einem und einem , die durch einen [Vergleichsoperator](#Vergleichsoperatoren) voneinander getrennt sind. **Sonderfälle:**\ Sind oder leer, wird das Argument als 0 interpretiert. #### ZEITVERSATZ Diese Funktion ermöglicht es, in einer Kennzahlenformel auf ein Vorgängerelement der Zeit-Dimension zuzugreifen. **Syntax:** ``` ZEITVERSATZ(;) ``` Voraussetzung ist die Definition einer Dimension mit der Dimensionsrolle Zeit. Typischerweise sind dies die Monate. Die Funktion wirkt nur auf den Blättern (unterste Ebene) dieser Dimension. Das muss ein Kennzahlschlüssel sein, ein Formelausdruck ist nicht erlaubt. In Formularformeln steht die Funktion nicht zur Verfügung. Der \ ist eine negative Konstante und bezeichnet die Schrittweite, um das Vorgängerelement ermitteln zu können. Das Vorgängerelement ist das in der Reihenfolge der Dimensionselemente relativ um die angegebene Schrittweite weiter oben liegende Blatt. Elemente, die keine Blätter sind, werden dabei nicht mitgezählt. Die Funktion wirkt gemäß der Reihenfolge der Dimensionselemente nicht auf dem 1. Blatt, welches aber auch nicht eingabefähig ist. Deshalb muss der Startwert in einer weiteren Kennzahl eingegeben werden. Eine Formel für eine Kennzahl x kann in der ZEITVERSATZ-Funktion ausnahmsweise die Zielkennzahl x auch als Argument verwenden (z.B. im Sinne von \[ANZAHL\_KUNDEN] = \[KUNDEN\_ZUGANG] + ZEITVERSATZ(\[ANZAHL\_KUNDEN];-1)). #### isTimeElementWithoutChildren Die Funktion `isTimeElementWithoutChildren()` prüft, ob ein Element der Zeitdimension auf der untersten Hierarchieebene (also ein sogenanntes *Blattelement*) liegt – also keine untergeordneten (Kind-)Elemente besitzt. Sie gibt den Wahrheitswert `TRUE` zurück, wenn das geprüfte Element zur Zeitdimension gehört **und** keine Kinder hat. Andernfalls gibt sie `FALSE` zurück. Dies ist besonders nützlich, wenn bestimmte Berechnungen oder Formeln **nur auf der untersten Ebene** einer Zeitdimension (z. B. einzelnen Monaten) angewendet werden sollen – beispielsweise zur Vermeidung doppelter Aggregationen oder zur gezielten Steuerung der Berechnungslogik innerhalb hierarchischer Zeitstrukturen. **Syntax:** ``` isTimeElementWithoutChildren() ``` **Besonderheiten:** * Die Funktion benötigt **keine Argumente**. * Die Funktion **kann nur für innere Formeln** verwendet werden (Formeln für aggregierte Ebenen) * Sie kann ausschließlich im Kontext einer Dimension mit der Rollenbezeichnung „Zeit“ verwendet werden. * Die Funktion eignet sich besonders für Bedingungen innerhalb von `WENN`-Formeln oder zur Kombination mit `AND`, `OR`, `NOT`, um gezielt die Berechnungsebene zu kontrollieren. **Beispiel:** ``` WENN(isTimeElementWithoutChildren(); [WERT]; BLANK) ``` → In diesem Beispiel wird der Wert `[WERT]` nur auf untersten Zeit-Elementen berechnet. Für alle übergeordneten Elemente (z. B. Quartale oder Jahre) bleibt das Ergebnis `BLANK`. #### MODULO Modulo gibt den Rest einer ganzzahligen Division zurück. **Beispiel:** 15 mod 12 = 3, da 15 : 12 = 1, 3 bleibt übrig **Syntax:** ``` MODULO(; ) ``` **Beispiel:** Im folgenden Beispiel wurde die Formel MODULO(\[B];\[A]) verwendet.

#### QUOTIENT Bildet den Quotient aus Divident und Divisor. Zurückgegeben wird immer eine Ganzzahl. **Syntax:** ``` QUOTIENT(; ) ``` **Beispiel:** QUOTIENT(5;3) Das Ergebnis ist 1, da die Nachkommastellen entfallen. #### MINIMUM Gibt das Minimum der gegebenen Argumente zurück. Syntax: ``` MINIMUM( [;;…]) ``` #### MAXIMUM Gibt das Maximum der gegebenen Argumente zurück. Diese Funktion ermöglicht es, den größten Wert aus einer Liste von Werten zu ermitteln. Syntax: ``` MAXIMUM( [;;…]) ``` #### SUMOFCHILDREN Summiert die Werte der Kinder des aktuellen Elements. Dies ist besonders nützlich für hierarchische Berechnungen, bei denen die Gesamtsumme aus den Werten der untergeordneten Elemente ermittelt werden muss. Syntax: ``` SUMOFCHILDREN() ``` #### TIMEOFFSET Nimmt den Wert der referenzierten Kennzahl von einem vorhergehenden Element in der Zeitdimension. Dies ermöglicht zeitbasierte Berechnungen, wie z.B. das Vergleichen von Werten über verschiedene Zeiträume hinweg oder auch das Fortschreiben von Werten für Bestände. Syntax: ``` TIMEOFFSET(; ) ``` #### ISBLANK Prüft, ob das gegebene Argument leer ist. Syntax: ``` ISBLANK() ``` #### ISVALID Prüft, ob das gegebene Argument eine gültige Zahl ist. Syntax: ``` ISVALID() ``` #### AND Funktionale Version von &&. Diese Funktion ermöglicht es, zwei Bedingungen in einer Funktionsform zu kombinieren. Syntax: ``` AND(; ) ``` #### OR Funktionale Version von ||. Diese Funktion ermöglicht es, mehrere alternative Bedingungen in einer Funktionsform zu kombinieren. Syntax: ``` OR(; ) ``` #### NOT Funktionale Version von !. Diese Funktion ermöglicht die Negation einer Bedingung in einer Funktionsform. Syntax: ``` NOT() ``` ### Vergleichsoperatoren #### > (Größer als) Vergleicht zwei Werte und gibt genau dann TRUE zurück, wenn der erste Wert größer als der zweite Wert ist. Syntax: ``` > ``` #### >= (Größer oder gleich) Vergleicht zwei Werte und gibt TRUE zurück, wenn der erste Wert größer oder gleich dem zweiten Wert ist. Syntax: ``` >= ``` #### < (Kleiner als) Vergleicht zwei Werte und gibt TRUE zurück, wenn der erste Wert kleiner als der zweite Wert ist. Syntax: ``` < ``` #### <= (Kleiner oder gleich) Vergleicht zwei Werte und gibt TRUE zurück, wenn der erste Wert kleiner oder gleich dem zweiten Wert ist. Syntax: ``` <= ``` #### = (Gleich) Vergleicht zwei Werte und gibt TRUE zurück, wenn beide Werte gleich sind. Syntax: ``` = ``` #### != (Nicht gleich) Vergleicht zwei Werte und gibt TRUE zurück, wenn die Werte ungleich sind. Syntax: ``` != ``` #### <> (Nicht gleich) Vergleicht zwei Werte und gibt TRUE zurück, wenn die Werte ungleich sind. Dies ist eine alternative Schreibweise für != und erfüllt denselben Zweck. Syntax: ``` <> ``` #### && (Und) Logisches UND, gibt TRUE zurück, wenn beide Operanden TRUE sind. Dieser Operator wird verwendet, um zu überprüfen, ob mehrere Bedingungen gleichzeitig erfüllt sind. Syntax: ``` && ``` #### || (Oder) Logisches ODER, gibt TRUE zurück, wenn mindestens einer der Operanden TRUE ist. Dies ist hilfreich, um Bedingungen zu formulieren, bei denen mindestens eine von mehreren Bedingungen zutreffen soll. Syntax: ``` || ``` #### ! (Logische Negation) Logische Negation, gibt TRUE zurück, wenn der Operand FALSE ist. Dieser Operator wird verwendet, um die Wahrheit einer Bedingung zu invertieren. Syntax: ``` ! ``` # Team Im Kontext einer Planung dient der **Team-Tab** dem Owner zur Verwaltung eines Planungs-Teams. Mithilfe des Team-Tabs * verwaltet der Owner seine Planer und deren Berechtigungen * behält der Owner den Überblick über den Planungsstatus

# Übersicht über den Tab Team Im Team-Tab verwalten Sie Ihr Planungsteam und kontrollieren den aktuellen Planungsstand. Im Kontext einer Planung steht dem Owner der Tab "Team" zur Verwaltung seines Planungsteams und zur Kontrolle des aktuellen Planungsstandes zur Verfügung. {% hint style="info" %} \*Der Tab „Team“ ist nur für Owner verfügbar. {% endhint %}

## Planungsteam verwalten Über den Button "Bearbeiten" kann der Owner einer Planung aus der Menge der für einen Tenant registrierten Benutzer ein Team von Planern zusammenstellen und pro Planer individuelle Berechtigungen zum Zugriff auf den Planungswürfel vergeben. Mehr dazu erfahren Sie im Kapitel [Planungsteam verwalten](/user/team/nutzer-berechtigungen_in_qvantum_definieren). ## Planungsstand kontrollieren Über die Planer-Tabelle auf dem Team Tab behält der Owner zu jedem Zeitpunkt den aktuellen Status seiner Planung unter Kontrolle. Für jeden Planer zeigt die Tabelle folgende Informationen: * Onlinestatus: aktueller individueller Onlinestatus des Planers. Folgende Ausprägungen sind möglich: * Offline: der Planer ist gerade nicht im Kontext der aktuellen Planung aktiv * Online: der Planer ist gerade im Kontext der aktuellen Planung aktiv, aber hat keine Änderungen am Datenbestand vorgenommen * Ungespeicherte Änderungen: der Planer ist gerade im Kontext der aktuellen Planung aktiv und hat bei sich lokal Änderungen vorgenommen, die noch nicht in den zentralen Datenbestand gespeichert wurden. * Name: Vorname und Nachname des Planers, inkl. seiner Email-Adresse * Berechtigungen: individuelle Berechtigungen auf ausgewählte Elemente der zur Berechtigung konfigurierten Planungsdimensionen * Planungsstatus: aktueller individueller Planungsstatus des Planers. Mehr dazu erfahren Sie im Kapitel [Workflow](/user/ubersicht-uber-die-planung/der_workflow). # Planer-Berechtigungen in QVANTUM definieren Im Rahmen der Verwaltung eines Planungsteams stellen Sie eine Menge von Planern zusammen und definieren deren Berechtigungen. Über den Button "Bearbeiten" auf dem Team-Tab kann der Owner einer Planung aus der Menge der für einen Tenant registrierten Benutzer ein Team von Planern zusammenstellen und pro Planer individuelle Berechtigungen zum Zugriff auf den Planungswürfel vergeben. ### In Bearbeitungsmodus wechseln Um die Konfiguration eines Teams anzupassen, klicken Sie zunächst auf **Bearbeiten**, um in den Bearbeiten-Modus des Team-Tabs zu wechseln.

### Benutzer auswählen Im Bearbeiten-Modus gelangen Sie mit einem Klick auf den Button **„Benutzer auswählen“** zu einer Liste aller für Ihren Tenant registrierten Benutzer. Durch gezieltes an-/abhaken der Checkboxen definieren Sie, welche Nutzer für die aktuelle Planung als Planer fungieren sollen.

Mit "Übernehmen" finalisieren Sie die Auswahl von Planern und gelangen zurück in den Bearbeitungs-Modus des Team Tab. {% hint style="info" %} Im Nachgang erhalten alle Nutzer eine Benachrichtigungsmail, die neu als Planer hinzugefügt oder gerade aus der Planung entfernt wurden. {% endhint %} {% hint style="info" %} Ein neu hinzugefügter Planer erhält per Default Zugriff auf den kompletten Planungswürfel. Im Folgenden schränken Sie diese Rechte gezielt ein. {% endhint %} ## Dimensionen für Berechtigungen wählen Im Bearbeiten-Modus gelangen Sie mit einem Klick auf den Button "Dimensionen auswählen" auf eine Liste aller im Planungsmodell definierten Dimensionen.

Durch gezieltes an-/abhaken der Checkboxen definieren Sie, welche Dimensionen zur gezielten Definition von feingranularen Berechtigungen auf Dimensionselemente einbezogen werden sollen. Wird eine Dimension nicht miteinbezogen, so wird angenommen, dass alle Planer kompletten Zugriff auf alle Elemente dieser Dimension erhalten sollen. Wird keine Dimension miteinbezogen, so ist das feingranulare Berechtigungssystem auf einzelne Dimensionselemente komplett deaktiviert, und es wird angenommen, dass alle Planer kompletten Zugriff auf das volle Planungsmodell erhalten sollen. Mit "Übernehmen" finalisieren Sie die Auswahl von Dimensionen für die Berechtigung und gelangen zurück in den Bearbeitungs-Modus des Team Tab. ## Pro Planer Berechtigungen vergeben Im Bearbeiten-Modus gelangen Sie über den Punkt "Bearbeiten" im **Drei-Punkte-Menü** eines Planers zur Verwaltung seiner Berechtigungen.

Für alle zur Berechtigung miteinbezogenen Dimensionen steht ein Dropdown zur Auswahl von Elementen zur Berechtigung zur Verfügung. * Wählen Sie "Alle Elemente" aus, um in betreffender Dimension keine Einschränkungen vorzunehmen. * Wählen Sie eines oder mehrere Elemente aus, um gezielte Berechtigungen zu definieren. Über die Checkbox "Schreibrechte" bestimmen Sie, ob der jeweilige Planer die berechtigten Bereiche des Datenwürfels nur lesend oder lesend und schreibend zugreifen darf. Mit "Übernehmen" finalisieren Sie die Vergabe von Berechtigungen und gelangen zurück in den Bearbeitungs-Modus des Team Tab. {% hint style="warning" %} Durch Modellupdates, bei denen Dimensionselemente entfernt wurden, auf die Planer berechtigt waren, kann die Situation entstehen, dass für Planer in betreffenden Dimensionen kein Element zur Berechtigung gewählt ist. Ist dies für mindestens eine Dimension der Fall, so können betroffene Planer effektiv nicht mehr auf den Planungswürfel zugreifen. Nach entsprechenden Modellupdates sollte der Owner sicherheitshalber die aktiven Berechtigungen seiner Planer überprüfen und ggfs. nachbessern. {% endhint %} # Konfiguration des Teams über CSV Bei einer hohen Anzahl an Teammitgliedern bietet sich immer noch die Konfiguration des Teams über den Download der team- oder permissions-CSV an. ### **Nutzerberechtigungen über CSV definieren** Die Möglichkeit, die Nutzerberechtigungen über CSV zu konfigurieren besteht nach wie vor und bietet vielleicht bei der Massenbearbeitung vieler Benutzer einen Vorteil. Grundsätzlich ist es aber nicht mehr erforderlich, Benutzerrechte über den CSV-Download und anschließendem -Upload einzustellen. **Über den CSV-Upload Berechtigungen definieren** Über den Berechtigungs-Upload im CSV-Format können Sie die Berechtigungen Ihres gesamten Teams auf einmal anpassen. Voraussetzung ist, dass Sie bereits Benutzer-[Stammdaten importiert](/user/eingangsseite-planungen-and-benutzer/ubersicht-uber-den-tab-benutzer) haben. Im Berechtigungs-CSV gibt drei „Basisspalten“, die immer gesetzt werden müssen. \| **email** | **\[Dimensionsname]** | **input** | Für die Berechtigungen sind die Spalte „\[Dimensionsname]“ und „input“ relevant. Hinweis: Alle Nutzer, die nicht explizit im Berechtigungs-CSV aufgeführt werden, verlieren nach dem Import alle bisher vorhandenen Berechtigungen in QVANTUM. ### Spalte „\[Dimensionsname]“ Bei dieser Spalte handelt es sich um einen Platzhalter, der mit dem Namen der Dimension mit der Rolle „Planungseinheiten“ gefüllt werden muss. Nutzen Sie den Berechtigungsexport, wird der Name der Dimension automatisch gesetzt. #### Besonderheiten der Dimension mit der Rolle „Planungseinheiten“ Pro Modell muss es eine Dimension geben, die Rolle „Planungseinheit“ besitzt. Diese definiert die Basis-Berechtigung für die Nutzer, die auch für den Workflow herangezogen wird. Jedem Nutzer muss ein beliebiges Element dieser Dimension zugewiesen werden. Auch der Wurzelknoten (z. B. „Alle Vertriebseinheiten“) kann als Berechtigung definiert werden, indem Sie entweder das genaue Element berechtigen oder das Schlüsselwort „alle“ oder „all“ (ohne Anführungszeichen oder eckige Klammern) in die betroffene Spalte schreiben.

### Spalte „Input“ Werte ja (Alternativen: yes oder y) geben an, dass die Berechtigung „lesen und schreiben“ gesetzt ist. Die Werte nein (Alternativen: no oder n) geben an, dass ausschließlich die Berechtigung zum Lesen von Werten vorhanden sind. Die tatsächlichen Berechtigungen werden als eigene Spalte im CSV definiert. Dazu wird der Singular-Name der Dimension als Spaltenüberschrift verwendet, z. B. „Vertriebseinheit“ oder „Produkt“. Als Werte der Spalte werden dann die Schlüssel der Dimensionselemente eingetragen. ### Auf mehreren Elementen einer Dimension berechtigen Sie können Berechtigungen auch auf mehr als ein Element einer Dimension setzen. Dies kann auf zwei Wegen geschehen: 1. Sie berechtigen einen Nutzer auf einem Element mit hierarchisch untergeordneten Elementen („Knoten“): Der Nutzer ist automatisch auf allen untergeordneten Knoten berechtigt. Geben Sie dazu einfach den Schlüssel des obersten Elements an, auf dem Sie berechtigen möchten. 2. Sie berechtigen einen Nutzer manuell auf mehreren Elementen: Geben Sie in eine Spalte beliebig viele Schlüssel der Dimension an. Einzelne Schlüssel werden durch eckige Klammern voneinander getrennt. Es können einzelne oder hierarchiche Elemente sein. Das Beispiel „\[Produkt1] \[Produkt2] \[Produktgruppe 2]“ in der Spalte „Produkt“ berechtigt auf den einzelnen Produkten 1 und 2 und zusätzlich auf der Produktgruppe 2. In allen Dimensionen außer der Dimension mit der Rolle „Planungseinheiten“ gilt: Wird ein Wert für einen Nutzer leer gelassen, gilt die Berechtigung automatisch für alle Elemente der Dimension. ### Besonderheiten für Formulare mit verschachtelten Ebenen Formulare mit verschachtelten Ebenen weisen einige Besonderheiten auf. Durch die Verschachtelung einzelner Ebenen unterschiedlicher Dimensionen, können Berechtigungen dem Aufbau einer logischen Struktur im Weg stehen. Es gelten zwei grundlegende Regeln, damit die Berechtigungen mit den im Formular verwendeten verschachtelten Ebenen kompatibel sind: * Die Berechtigungen müssen innerhalb einer Dimension auf der gleichen hierarchischen Ebene gesetzt sein. * Es darf keine Ebene im Formular verwendet werden, auf die der Planer nicht berechtigt ist. # Guide "Nutzerberechtigungen vergeben" Voraussetzung ist, dass Sie bereits einmal mit dem Team-CSV gearbeitet haben und Sie wissen, wie Berechtigungen auf Dimensionselemente gelegt werden können ([dazu hier mehr](https://lp.qvantum-plan.de/wissensdatenbank/tab-team)). ### Sie müssen in folgenden Fällen aktiv werden * Wenn Sie ein Element (und ggf. darunter liegende Elemente) berechtigen möchten, muss dieses Element ab sofort in eckigen Klammern (z. B. \[Nord] oder \[P10299] geschrieben werden. **Die bisherige Schreibweise ohne eckige Klammern ist nicht mehr gültig.** * Wenn Sie die [Berechtigungen in mehreren Dimensionen nutzen](https://lp.qvantum-plan.de/wissensdatenbank/nutzer-berechtigungen-in-qvantum-definieren), können Sie ab sofort zusätzlich das Kennwort „ALLE“ (oder „alle“, „ALL“, „all“) benutzen, um automatisch alle verfügbaren Elemente der Dimension zu berechtigen. (Bisher war dies durch eine „leere Spalte“ in der Berechtigung möglich gewesen). * Leere Spalten bedeuten nun, dass für diesen Nutzer **explizit keine** Berechtigungen mehr auf dieser Dimension vorhanden sein sollen. Achtung: Dies führt dazu, dass der Nutzer generell keinen Zugriff mehr auf Ihre QVANTUM-Planung haben wird. **Hinweis:** Ältere CSV-Dateien sind ebenfalls ungültig geworden, da die generische Spaltenüberschrift „planning-unit“ nun nicht mehr unterstützt wird. Stattdessen muss der Name der Planungseinheiten-Dimension verwendet werden. Dies wird im Team-Export automatisch berücksichtigt. Mehr Infos: [Benutzer anlegen in QVANTUM](https://lp.qvantum-plan.de/wissensdatenbank/tab-team). ### Warum wurden diese Anpassungen notwendig? Wir vereinfachen derzeit intern unsere Nutzerverwaltung, um Ihnen in Zukunft bessere Möglichkeiten zu bieten, Ihr Team zu verwalten und zu erweitern. Mit diesem Update haben wir einen Grundstein für Features wie eine interaktive Nutzerverwaltung ohne CSV-Dateien, einfachere SSO-Anbindung und mehrere Planungen ohne Accountwechsel geschaffen. **Category:** Team **Keywords:** Benutzer,Berechtigungen,CSV,Nutzer,Planungseinheiten,berechti [Original Article](https://lp.qvantum-plan.de/wissensdatenbank/guide-nutzerberechtigungen-vergeben) # Daten Übersicht über den Tab Daten **Daten importieren, exportieren und die Datenvorlage herunterladen.** > Der Tab „Daten“ ist nur für Benutzer mit der QVANTUM-Benutzerrolle „Owner“ verfügbar. Sobald Sie Ihre Modellvorlage hochgeladen haben, erhalten Sie im Tab Daten die Möglichkeit Ihre Daten zu [importieren](#importieren) oder [exportieren](#exportieren). Außerdem bietet QVANTUM Ihnen die Möglichkeit eine [Datenvorlage herunterzuladen](#herunterladen). Das ["Änderungsprotokoll"](#changelog) bietet die Möglichkeit, Änderungen an den Daten nachzuvollziehen.

## Importieren Laden Sie die Daten (z.B. IST- oder historische Daten) hoch, die Sie in QVANTUM weiterverarbeiten möchten. #### Hinweise zum manuellen Import von Daten Laden Sie zunächst die auf Ihr Modell zugeschnittene Datenvorlage herunter und tragen Sie Ihre Daten zum Importieren ein. Anschließend können Sie die ausgefüllte Vorlage hochladen, wodurch die Daten im System gespeichert und entsprechend Ihres Modells weiterberechnet werden. Sie können jederzeit – auch während einer aktiven Planung – weitere Daten durch erneutes Hochladen hinzufügen. Bestehende Daten bleiben dabei erhalten, sofern Sie sie nicht überschreiben. Sie können **xlxs-Dateien** mit einer Maximalgröße von **4MB** und **csv-Dateien** mit einer Maximalgröße von **1024MB** hochladen. ### Exportieren Exportieren Sie die gesammelten Daten in ein Excel-kompatibles Format. #### Hinweise **zum manuellen Export von Daten** Durch Klicken auf den Button "Daten herunterladen" im Daten-Tab können Sie den Export Ihrer gesammelten Daten initiieren.

Im ersten Schritt öffnet sich ein Dialog, in dem Sie den Umfang des Exports einschränken können. Wenn Sie die Daten in vollem Umfang herunterladen wollen, brauchen Sie hier keine weitere Auswahl zu treffen. Klicken Sie dann einfach auf "Exportieren".

*Abbildung: Der Export-Dialog, in dem sich die Daten filtern lassen*

Um einen bestimmten Teil des Datencubes herunterzuladen, haben Sie die Möglichkeit, die gewünschten Elemente für jede Dimension auszuwählen. Dabei können Sie nur Elemente auf der untersten Ebene wählen, die über mehr als ein Element verfügen. Angenommen, Sie möchten lediglich die Plandaten für das Jahr 2024 exportieren. In diesem Fall wählen Sie bei der Dimension "Jahre" die Option "2024" und bei der Dimension "Variante" das Element "Plan". Die anderen Dimensionen können Sie unverändert lassen, indem Sie die Auswahl auf "Alle Elemente" belassen.

*Abbildung: Filtern der Dimension "Jahre"*

Nach einem Export bleiben alle Daten weiterhin im System verfügbar und werden nicht gelöscht. ## Änderungsprotokoll/Changelog Im Export-Bereich des Daten-Tabs erscheint ein Link "Änderungsprotokoll herunterladen". Darüber laden Sie alle Protokoll-Einträge im CSV Format-herunter. Die Datei kann z.B. mit Excel geöffnet werden.

*Den Downloadlink für das Änderungsprotokoll finden Sie im Exportbereich auf dem Daten-Tab*

Das Änderungsprotokoll erscheint mit englischen Spaltenüberschriften und ist wie folgt aufgebaut: * **Time**\ Zeitpunkt an dem die Änderung vorgenommen wurde. * **User**\ Der Benutzer, der die Änderung vorgenommen hat. * **Type**\ Es gibt zwei unterschiedliche Arten von Änderungseinträgen: * Change in cell value\ Zellwertänderungen: Änderung an dem Wert, der in einer bestimmten Zelle sitzt. * Data import\ Eintrag, der darüber informiert, dass zu diesem Zeitpunkt ein Datenimport eingespielt wurde. **Achtung:** alle daraus resultierenden Zellwertänderungen werden nicht dokumentiert! * **Bezugsspalten für jede Dimension**\ Für jede Dimension gibt es eine Bezugsspalte, in der festgehalten ist, auf welchem Element der Wert eingetragen ist. * **Old value**\ In dieser Spalte steht der Wert, der vor der Änderung eingetragen war. * **New value**\ Der neu eingetragene Wert. * **Filename** (erscheint nur bei Einträgen der Art "Import")\ Der Dateiname der Datei, die importiert wurde.

### Datenvorlage herunterladen QVANTUM stellt Ihnen eine Vorlage für Ihr Planungsmodell zur Verfügung. Dabei handelt es sich um eine Excel Datei, die Sie mit einem Klick auf „Datenvorlage herunterladen“ erhalten und dann entsprechend Ihren eigenen Wünschen ändern können.

### Vorlage mit Daten füllen Beim befüllen Ihrer Vorlage müssen Sie den Schlüssel, welchen Sie vorher im Modell bestimmt haben, eintragen.

# Formulare Anleitung und Tipps zum effektiven Arbeiten mit Formularen in QVANTUM. In diesem Kapitel erfahren Sie, wie der Formulartab aufgebaut ist, welche Struktur er besitzt und wie Sie problemlos zwischen verschiedenen Formularen navigieren können. Zudem wird die Toolbar im Detail betrachtet, sodass Sie ihre Funktionen und Aufteilung besser verstehen. Sie lernen, wie Sie neue Formulare anlegen, bestehende bearbeiten und dabei effizient arbeiten. Ein zentrales Element ist die Suchfunktion, mit der Sie gezielt nach Elementen innerhalb einer Dimension suchen können, um schnell die gewünschten Daten zu finden. Darüber hinaus wird erläutert, wie Sie Zahlen im Grid passend formatieren und Zellfunktionen nutzen, um Werte auf Basis vorhandener Inhalte zu berechnen. Ein weiterer Schwerpunkt liegt auf den verschiedenen Verteilmöglichkeiten in verschachtelten Ebenen, die Ihnen helfen, Ihre Daten noch gezielter und strukturierter zu organisieren. Abschließend erhalten Sie einen Überblick über weitere Konfigurationsmöglichkeiten, mit denen Sie das System optimal an Ihre Anforderungen anpassen können.

# Übersicht über den Tab Formulare Lernen Sie, wie der Formulartab aufgebaut ist, wie Sie zwischen den Formularen wechseln und in welche Bereiche sich die Toolbar unterteilt. Die Ansicht unterteilt sich in die folgenden 4 Bereiche: 1. Der Formulartitel und die Auswahl in der Formularliste 2. Die Dimensionen des verwendeten Modells 3. Die Toolbar mit den verfügbaren Aktionen zum Speichern oder Formatieren, sowie die Freigabeeinstellungen des Formulars 4. Das Formular

### 1. Formulartitel und das Öffnen der Formularliste Mit einem Klick auf den Formulartitel öffnet sich die Formularliste. Die verfügbaren Formulare lassen sich über Ordner hierarchisch strukturieren, um die bestmögliche Übersicht zu behalten. Neben der Auswahl eines Formulars, das Sie durch einfaches Anklicken auswählen, sind folgende Aktionen möglich: **1.1 Neuen Ordner anlegen** **1.2** **Formularliste pinnen oder lösen**\ Durch Anklicken des Pins wird die Formularliste fixiert und bleibt somit permanent geöffnet. Bis der Pin wieder gelöst wird. Dieser Modus eignet sich zum parallelen Bearbeiten vieler Formulare. Also immer dann, wenn zwischen den Formularen schnell hin und her gewechselt werden muss. **1.3** **Formulare importieren/exportieren**\ Die Konfiguration der Formulare wird in Form einer json-Datei gesichert. **1.4 Anlegen eines neuen Formulars**

*Mögliche Aktionen in der Formularliste*

Wenn Sie bei der Auswahl eines neuen Formulars die Maus über einen der Formularnamen wegen, sind außerdem weitere Aktionen über Mouseover-Icons erreichbar: **1.5 Formular verschieben** **1.6 Formular umbenennen** **1.7 Formular löschen**

*Mouseover Aktionen innerhalb der Formularliste*

### 2. Die Dimensionen im Formularheader Von den Formularen sind Sie bereits gewohnt, dass bestimmte Dimensionen bereits in den Spalten oder Zeilen liegen. Nehmen wir an, die Dimension „Jahre“ liegt in den Spalten. Somit finden Sie in der Spaltenbeschriftung auch die Angabe des genauen Jahres (z.B. 2024) auf das die Werte, die Sie in dieser Spalte eintragen sich beziehen. Wenn eine Dimension allerdings nicht in den Zeilen oder Spalten des Formulars verwendet wird, ist es wichtig, zu wissen, welcher Wert für diese Dimension über dem Formular ausgewählt ist. Wenn z.B. für die Dimension „Jahre“ die „2024“ gewählt ist, gelten alle Angaben, die Sie im darunter liegenden Formular vornehmen für das Jahr 2024. Ändern Sie nach dem Ausfüllen des Formulars das Jahr auf 2025, verschwinden alle zuvor auf 2024 getätigten Eingaben. Das folgende Beispiel zeigt die Dimension „Artikel“, für die der „Artikel 1.1“ ausgewählt ist. Dadurch tätigen Sie alle Eingaben im Formular, wie z.B. Absatz oder Umsatz für genau diesen Artikel. Folgende Funktionen sind für jede der gelisteten Dimensionen möglich: **2.1 Auswahl fixieren**\ Wenn Sie die aktuelle Auswahl fixieren, kann ein Planer die Auswahl nicht mehr ändern. Jede Eingabe, die ein Planer in diesem Formular vornehmen würde, bezieht sich somit auf die von Ihnen fixierte Auswahl für diese Dimension. **2.2 Suchfunktion** **2.3 Auswahl durch Planer**\ Wenn Sie „Auswahl durch Planer“ für eine Dimension auswählen, muss der Planer zuerst selbst eine Auswahl treffen, bevor er etwas in dem Formular eintragen kann. Diese Option bietet sich an, um dem Planer deutlich zu machen, dass er für die Auswahl an dieser Stelle selbst verantwortlich ist. **2.4 Abbildung der hierarchischen Struktur dieser Dimension**

*Dimension im Header: Auswahl und weitere Funktionen*

### 3. Die Formular-Toolbar Die Toolbar unterteilt sich in die Bereiche: Daten, Formular, Formatierung und Freigabe.

*Die Toolbar unterteilt nach ihren Kategorien*

**3.1 Daten** Die Aktionen unter Daten beziehen sich auf Eingaben, die Sie im Formular vorgenommen haben. Werte, die Sie eingetragen haben. **3.2 Formulare** Jede Einstellung, die sie an den Formularen angepasst haben, lässt sich bis zum Speichern rückgängig machen. Die Speichern Aktion unter „Formulare“ bezieht sich auf Einstellungen wie: * Änderungen an der Achsenkonfiguration * Anpassungen am Auf-/Zuklappstatus * Konfigurieren manueller Achsen * Auswahl eines anderen Elements zu einer Dimension im Formularheader * Ändern der Spaltenbreite * … **3.3 Formatieren** Erst wenn im Formular ein oder mehrere Spalte(n) oder Zeile(n) ausgewählt sind, werden die Aktionen zur Formatierung aktiv. Erst dann kann der Hintergrund der gewählten Spalte/Zeile gefärbt oder die Schriftfarbe angepasst werden. **3.4 Freigabe des gewählten Formulars** Entscheiden Sie, welche Benutzer das Formular einsehen dürfen. Sie haben die Möglichkeit, das Formular entweder für alle Planer allgemein freizugeben oder nur für spezifische Planer zugänglich zu machen. [Weitere Hilfe dazu finden Sie auch hier!](/user/arbeiten-mit-formularen/formularkonfigurationen) # Ordner und Berechtigungen Dieser Artikel beschreibt, wie Sie eine Ordnerstruktur aufbauen und Berechtigungen für die Formulare vergeben können. ### Formularordner anlegen Die Ordnerstruktur kann am linken Rand im Reiter „Formulare“ bearbeitet werden. Über einen Klick auf das Stift-Symbol kann der Name des Ordners, wie auch seine Anordnung geändert werden. Die Ordner können jedoch auch per Drag & Drop verschoben werden. Klickt man auf das Mülleiner-Symbol, kann man so den Ordner löschen. Untergeordnete Formulare von einem übergeordneten Ordner können durch ein Häkchen verschoben statt gelöscht werden. Die derzeit ausgewählte Hierarchieebene ist lila eingefärbt.

### Formularberechtigungen festlegen Bei der Erstellung eines neuen Formulars kann über drei Schaltflächen entschieden werden, ob das Formular „Nur für Owner“, „Für bestimmte Team-Mitglieder“ oder auch „Für das gesamte Team“ einsehbar sein soll. Über den Button rechts in der oberen Ecke können die Freigaben für ein bereits bestehendes Formular geändert werden.

Bei der Wahl des Feldes „Für bestimmte Team-Mitglieder“ erscheint ein Dialog, bei dem man jeweils einen Haken bei den Team-Mitgliedern setzen kann, die die Berechtigung der Einsicht erhalten sollen. Über das Dropdown-Menü am oberen Rand des Dialogs kann man die Freigabe-Reglungen eines anderen, bereits bestehenden Formulars übernehmen, das nicht „Nur für Owner“ oder „Für das gesamte Team“ freigegeben sind.

### Ausblenden von leeren/nullwertigen Achsenelementen (Zeilen und Spalten) Durch die Filterfunktion ist es möglich, Zeilen oder Spalten aus dem Formular zu entfernen, wenn sie leer sind oder eine Null enthalten. Durch einen Klick auf die Schaltfläche „Zeile bearbeiten“ öffnet sich ein Feld, dass die Bearbeitung und Anpassung der Zeilen erlaubt. Setzt man ein Häkchen in der Checkbox „Leere Zeilen ausblenden“ blendet QVANTUM alle Zeilen die leer sind oder Null Werte haben aus. Wenn eine Kommentarzeile leer ist, die zugehörige Datenzeile jedoch Daten enthält, bleibt die Kommentarzeile eingeblendet. Dasselbe gilt für leere Reiter/Oberkategorien von Unterordnern, die gefüllt sind. Das Ausblenden kann temporär über den Button „Filter entfernen“ zurückgesetzt werden. Die Schaltflächen „Aufklappen“ und „Zuklappen“ dienen dazu, die Kategorienspalte ein und auszublenden.

# Konfiguration der Formulare In diesem Kapitel werden verschiedene Aspekte der Formular-Konfiguration in QVANTUM behandelt. Die **Grid-Formatierung** ermöglicht es, Zeilen oder Spalten visuell hervorzuheben, indem Schriftstil, -farbe und Hintergrundfarbe angepasst werden können. Bei der **Achsenkonfiguration** stehen drei Modi zur Verfügung: "Automatisch nach Dimensionen", "Automatisch nach Ebenen" und "Manuell", die unterschiedliche Strukturen und Anzeigemöglichkeiten bieten. Zudem wird erläutert, wie man **Formulare mit verschachtelten Ebenen** erstellt und dabei Berechtigungen korrekt zuweist, um sicherzustellen, dass Benutzer nur auf die für sie freigegebenen Daten zugreifen können. Weitere Themen umfassen das **Fixieren der Navigation** für Planer, um die Benutzerführung zu optimieren.

# Grid Formatierung Über die Schaltflächen im Bereich *Formatieren* des Toolbars können Sie Formatierungen von Grid-Zellen konfigurieren. QVANTUM unterstützt dabei Formatierungen für * einzelne Zellen * ganze Zeilen * ganze Spalten Mit Selektion einer einzelnen Zelle, einer ganzen Spalte oder einer ganzen Zeile wird der Formatierungsbereich aktiviert. Über einen Klick auf eine einzelne Zelle gilt diese als selektiert. Über einen Klick auf den Spalten- bzw. Zeilenheader gilt eine ganze Spalte bzw. Zeile als selektiert.

Toolbar-Bereich zum Formatieren von Grid-Zellen/Zeilen/Spalten

Die folgenden Formatierungsmöglichkeiten stehen zur Verfügung: * Schriftstil (fett/kursiv) * Schriftfarbe * Hintergrundfarbe Zum Entfernen von Formatierungen klicken Sie den Formatierung-Löschen Button ganz rechts im Bereich "Formatieren". Bei der Definition mehrerer Formatierungen für dieselbe Zelle gilt im Konfliktfall die Vorrangsregel **"Zelle vor Zeile vor Spalte"**.

Das obige Beispiel illustriert diese Regel. * Für alle Spalten wurden verschiedene Hintergrundfarben konfiguriert. * Für die Zeile "Alle Artikel" wurde eine hellblaue Hintergrundfarbe definiert. Diese überlagert die jeweiligen für die Spalten konfigurierten Hintergrundfarben. * Für die Zelle "Alle Artikel"/"Vorschau 2026" wurde schwarze, kursive, fette Schrift auf weißem Hintergrund konfiguriert. Dabei überlagert die weiße Hintergrundfarbe die für die Zeile definierte hellblaue Hintergrundfarbe. # Die drei Modi der Achsenkonfiguration Dieser Artikel beschreibt das Verhalten des jeweiligen Modus bei der Konfiguration der Spalten oder Zeilen. Beim Konfigurieren der Zeilen oder Spalten muss zunächst festgelegt werden, in welchem Modus die Achse konfiguriert werden soll. Folgende Modi stehen zur Auswahl: 1. [Automatisch nach Dimensionen](#automatisch-nach-dimensionen) 2. [Automatisch nach Ebenen](#automatisch-nach-ebenen) 3. [Manuell](#manuell)

*Der Modus im Dialog zu Konfiguration der Zeilen/Spalten*

Um das Verhalten des jeweiligen Modus anhand von Beispielen zu erklären, sind zunächst zwei Beispieldimensionen abgebildet, die in den meisten Modellen verwendet werden: Jahre und Monate.

*Die Dimensionen Monate (links) und Jahre (rechts)*

### Automatisch nach Dimensionen Im Modus "Automatisch nach Dimensionen" werden die gewählten Dimensionen nach dem folgenden Prinzip ineinander verschachtelt: Die Struktur der zuerst gewählten Dimension wird dargestellt. Für jedes Element auf der untersten Ebene wird nun die Struktur der darauf folgenden Dimension integriert. Im Beispiel mit den Monaten und Jahren bedeutet dies, dass wir zuerst die Struktur der Dimension Monate sehen, die Quartale und darunterliegende Monate umfasst. Unter jedem Monat, also auf der untersten Ebene, wird nun die vollständige Dimension "Jahre" untergliedert. In Abbildung 2 ist zu erkennen, dass diese Dimension nur die Elemente 2022, 2023 und 2024 enthält, da keine weiteren Elemente darunter platziert sind. In Abbildung 3 ist zu sehen, wie die Strukturen der Dimensionen Monate und Jahre verschachtelt werden.

*Prinzip des Modus "Automatisch nach Dimensionen"*

Konfigurieren wir die Zeilen in unserem Formular allerdings nach diesem Muster, zeigt sich, dass im Formular nur die 'Blätter' angezeigt werden. Damit sind alle Elemente gemeint, auf denen Werte eingetragen werden können. In der Dimension 'Monate' wären das die Monate (Ebene 2), denn bei den Quartalen handelt es sich **nicht** um Blätter sondern um Knoten (z.B. '1. Quartal'), auf denen alle darunter liegenden Elemente (für '1. Quartal' wären das 'Januar', 'Februar', 'März') aufsummiert werden.

*Die Konfiguration der Zeilen im Modus "Automatisch nach Dimensionen"*

Nach dieser Konfiguration wird das Formular anschließend wie folgt dargestellt.

*Die Blattverschachtelung im Modus "Automatisch nach Dimensionen"*

Im Modus "Automatisch nach Dimensionen" werden beim Verschachteln von zwei oder mehr Dimensionen nur noch die Zellen angezeigt, in denen Werte stehen. ### Automatisch nach Ebenen Es ist zunächst wichtig zu verstehen, was mit "Ebenen" gemeint ist. In der Dimension "Monate" werden zwei hierarchische Ebenen verwendet: Quartale (Ebene 1) und Monate (Ebene 2). Im Gegensatz dazu gibt es in der Dimension "Jahre" nur eine Ebene, auf der die Elemente 2022, 2023 und 2024 platziert sind. Mit Ebene ist im Zusammenhang mit der Verschachtelung immer die hierarchische Ebene einer Dimension gemeint. Qvantum ermöglicht es, diese Ebenen direkt im Modell zu benennen, was es später einfacher macht, die entsprechende Ebene bei der Verschachtelung auszuwählen. Im Modus "Automatisch nach Ebenen" können jetzt z.B. die Dimensionen "Monate" (mit den Ebenen "Quartale" und "Monate") und "Jahre" (mit der Ebene "Jahre") zu einer neuen Struktur verschachtelt werden (siehe Abbildung 6).

*Das Prinzip des Modus "Automatisch nach Ebenen"*

Die Konfiguration der Zeilen stellt sich damit wie folgt dar.

*Konfiguration der Zeilen im Modus "Automatisch nach Ebenen"*

Werfen wir einen Blick auf das Formular, welches nun generiert wird. Es fällt auf, dass bei dieser Verschachtelung keine Werte für die Quartale ermittelt werden können. Denn bei diesem Formularaufbau gibt es für die Quartale keinen Bezug zum Jahr.

*Die Darstellung der zuvor verschachtelten Ebenen im Formular*

### Manuell **Hinzufügen von benutzerdefinierten Zeilen und Spalten** Nachdem Sie die Dimensionen für die Spalten festgelegt haben, müssen Sie auf "Neue Zeile hinzufügen" bzw. "Neue Spalte hinzufügen" klicken, um konkret festzulegen, welche Zeile/Spalte angelegt wird. In diesem Dialog zum Anlegen einer neuen Zeile/Spalte, stehen Ihnen außerdem **weitere Optionen** zur Verfügung. Es ist möglich, die Eingabe zu verbieten oder eine Kommentarzeile/-spalte einzublenden. Wenn Sie die Eingabe verbieten, kann Ihr Planer in dieser Spalte keine Daten eingeben. Bei der Option "Kommentarzeile/-spalte einblenden" haben Sie die Wahl zwischen dem Kommentar-Typ "Freitext" oder "Freitext + Vorlage".

*Anlegen einer neuen Spalte im Modus "Manuell"*

#### Vorlagen für die Kommentarspalte Indem Sie den Kommentar-Typ "Freitext + Vorlagen" auswählen, können Sie dem Planer bestimmte Textbausteine vorgeben, welche er bei der Bearbeitung auswählen kann *(Abbildung 6)*.

Der Planer kann später Ihre Textvorlagen auswählen, indem er einen Doppelklick auf die Zelle durchführt und den entsprechenden Baustein auswählt *(Abbildung 7)*.

*Auswahl Ihrer Textvorlagen für den Planer*

#### Berechnungszeile oder -spalte Neben einer Datenspalte können Sie eine **Berechnungszeile/-spalte** in Ihr Formular einfügen. Geben Sie „Name der Zelle“/“Name der Spalte“ und die „Formel“ für die Berechnungszeile/-spalte an. Mehr zu Rechenoperationen und Formeln finden Sie [hier](/user/modell/rechenoperationen_und_formelsyntax).

*Formeleingabe in einer Berechnungsspalte*

#### Wertetyp für Berechnungsspalten Auch für Berechnungsspalten stehen die Wertetypen zur Verfügung, die in den [Grundeinstellungen von Qvantum](/user/einstellungen/systemeinstellungen) definiert sind. So können Sie sicherstellen, dass die berechneten Werte z.B. als Preise oder Prozentangaben ausgegeben werden. Über die Wertetypen lässt sich auch die Anzahl der Nachkommastellen bestimmen. Bei der Konfiguration einer Berechnungsspalte muss der gewünschte Wertetyp einfach zugewiesen werden. Beachten Sie, dass es je nach Konfiguration eines Formulars auch dazu kommen kann, dass sich berechnete Zeilen und berechnete Spalten kreuzen. Wenn einer Zelle sowohl durch die Spalten- als auch durch die Zeilenkonfiguration ein Wertetyp zugewiesen ist, hat immer die Konfiguration der Spalte Vorrang. **Option „Negative Werte hervorheben“** Diese Option hebt alle negativen Werte (-1 und niedriger) im Formular rot hervor, die sich in dieser Zeile oder Spalte befinden. # Formulardefinitionen exportieren und importieren **Formulare exportieren und importieren.** QVANTUM unterscheidet zwischen einem Export für Formulare und für die Formulardefinition. In diesem Artikel geht es um den Export für die Formulardefinitionen. ### Voraussetzungen Für den Export der Formulardefinitionen muss mindestens ein gespeichertes Formular in Ihrem QVANTUM-Account vorhanden sein. Für den Import von Formulardefinitionen sollte sich das Modell zwischen Export und Import so wenig wie möglich verändert haben. Ungültige Formulare sorgen zum Beispiel immer dafür, dass der Import nicht ohne weiteres möglich ist. Sie müssen dann die exportierte Formular-Datei reparieren. ### Formulardefinitionen exportieren Sobald die Voraussetzungen zum Export der Formulardefinitionen erfüllt sind, wird die Schaltfläche „Formulardefinitionen exportieren“ auf dem Tab „Formulare“ aktiv. **Inaktiver Definitionsexport:**

**Aktiver Definitionsexport:**

Klicken Sie anschließend auf das Download-Symbol. Der Export wird dann vorbereitet und anschließend heruntergeladen. Es handelt sich dabei eine Datei im Format JSON, die sie dann archivieren können. ### Formulardefinitionen importieren Den Formularimport können Sie auch dann ausführen, wenn noch keine Formulare vorhanden sind.\ **Aktiver Definitionsimport:**

Klicken Sie auf das Hochladen-Symbol und wählen Sie anschließend eine Export-Datei aus, die Sie in das System hochladen wollen. Es folgt ein Warnhinweis, denn die Importdatei ersetzt immer die bereits in Ihrem QVANTUM vorhandenen Formulare. **Warnhinweis zum Import von Formulardefinitionen:**

Sollte der Import erfolgreich sein, erhalten Sie eine Erfolgsmeldung und die neuen Formulare werden geladen. Wenn der Import nicht erfolgreich sein sollte, erhalten Sie eine Fehlermeldung. Das Scheitern kann mehrere Gründe haben: * Das im Account importierte Modell entspricht nicht dem Modell, mit dem exportiert wurde. * Es sind ungültige Formulare in der Exportdatei vorhanden, die nicht importiert werden können. Diese Fälle sind unter Umständen mit manuellen Eingriffen in die exportierte JSON-Datei reparierbar. # Navigation für den Planer fixieren Navigation fixieren, pinnen oder erzwingen ### Navigation fixieren (Controller/Owner) Für den Owner ist es jetzt möglich, die Navigation innerhalb einer Dimension für den Planer zu fixieren. Beachten Sie, dass das nur möglich ist, wenn sich die Dimension in der Kopfzeile (nicht in Zeilen oder Spalten) befindet. Hierzu wählen Sie im Dropdown der jeweiligen Dimension das gewünschte Element aus, das Sie im Formular fixieren wollen. Anschließend benutzen Sie das Schloss-Icon neben der Auswahl. Das Icon wechselt vom geöffneten in den abgeschlossenen Zustand. In der nachfolgenden Abbildung wurde in der Dimension "Szenario" das Element "Plan" ausgewählt.

Mit Klick auf das geöffnete Schloss Icon wird die Auswahl fixiert. Das Schloss-Icon wechselt in den geschlossen-Status.

### Fixierte Dimensionen aus Planer-Sicht Für den Planer stellt sich die Ansicht, wie in der folgenden Abbildung zu sehen, dar. Das Szenario "Plan" ist fixiert/abgeschlossen. Er kann die Auswahl nicht wechseln und tätigt seine Eingaben für das vorgesehene Szenario.

### Dimension pinnen und Auswahl erzwingen (Controller/Owner) Die Funktion "Dimensionen pinnen" eignet sich, wenn Sie den Planer zu einer Auswahl zwingen wollen. Im folgenden Beispiel wird die Dimension "Kennzahl" gepinnt. Durch Auswahl von "Kein Element" wird der Planer im Folgenden gezwungen, selbst die Auswahl zu treffen, für die er seine Eingaben tätigt.

Wird in mehreren Formularen die gleiche Dimension gepinnt (z.B. Kennzahl steht auf "Keine Auswahl"), so gilt die Auswahl des Planers später formularübergreifend.

### Gepinnte Dimensionen in der Ansicht des Planers Der Planer sieht die gepinnte Dimension wie folgt:

Er muss zunächst seine Auswahl treffen, für die er dann seine Planwerte eintragen kann. Im nachfolgenden Beispiel entscheidet er sich, zuerst die Umsatz Werte einzutragen. Das Pin-Icon zeigt an, dass es sich um eine angepinnte Auswahl handelt. Wechselt er jetzt zum Formular "Pinnen 2" würde die Auswahl "Umsatz" bereits eingestellt sein.

# Formulare mit verschachtelten Ebenen Im Modus "Automatisch nach Ebenen" können Ebenen beliebiger Dimensionen ineinander verschachtelt werden. Der Modus "Automatisch nach Ebenen" steht jetzt im Dialog zur Konfiguration der Zeilen/Spalten zur Verfügung.

Abbildung 1 – Der Modus bei der Belegung der Zeilen oder Spalten

Durch das Zusammenführen der hierarchischen Ebenen verschiedener Dimensionen zu einer neuen Struktur bieten sich neue Möglichkeiten für die Formularerstellung. Im nachfolgenden Beispiel wird gezeigt, wie die Verschachtelung von Ebenen funktioniert und wie Sie in nur wenigen Schritten eine neue Struktur für Ihre Zeilen oder Spalten erstellen können. #### Schritt 1 – Ebenen auswählen Wählen Sie zuerst im Modus "Automatisch nach Ebenen" eine Dimension aus. In unserem Beispiel orientieren wir uns am Modell der Personalkostenplanung und wählen die Organisationseinheiten. Diese Dimension besteht aus den folgenden Ebenen: Gesamtunternehmen, Bereiche, Kostenstelle/Team und auf der untersten Ebene die Mitarbeiter. Für unser Beispiel entscheiden wir uns für die Ebene 2 (Bereiche). **Achtung!** Wenn Sie an dieser Stelle keine Auswahl treffen können, könnte es sein, dass die Ebenen im Modell nicht benannt wurden. In diesem Fall kann durch ein einfaches Modellupdate Abhilfe geschaffen werden. [Hier](https://lp.qvantum-plan.de/wissensdatenbank/modellvorlage#Ebenenname-im-Modell) erfahren Sie, wie es funktioniert. Anschließend fügen wir die Dimension "Varianten" hinzu. Diese Dimension hat nur eine einzige Ebene, die dann standardmäßig bereits vorausgewählt ist. Zum Abschluss fügen wir eine weitere Ebene aus der Dimension "Organisationseinheiten" hinzu. Allerdings sind die Kostenstellen in unserem Beispiel weniger relevant, daher fügen wir als dritte Ebene unserer Verschachtelung die Ebene "Mitarbeiter" (Ebene 4 der Organisationseinheiten) hinzu.

*Abbildung 2 – Auswahl einer Ebene (rechts) nach Festlegen einer Dimension (links)*

#### Schritt 2 - Filtern in verschachtelten Ebenen Im vorliegenden Beispiel betrachten wir die Ausgaben für die Krankenkasse der Mitarbeiter in der Abteilung "Vertrieb". Die Mitarbeiter in anderen Abteilungen sind in diesem Zusammenhang nicht relevant. Nachdem Sie die Ebenen festgelegt haben, öffnen Sie die Kategorie "Filter festlegen", die sich direkt unter den Ebenen im gleichen Dialog befindet. Legen Sie fest, welche Einträge aus welcher Dimension Sie betrachten möchten. In unserem Beispiel wählen wir den "Vertrieb" in der Dimension "Organisationseinheiten".

*Abbildung 3 – Filtern in verschachtelten Ebenen*

#### Schritt 3 – Auswahl für die Belegung der Spalten Für die Spalten wählen wir jetzt wieder den Modus „Automatisch nach Ebenen“. Als erste Ebene wählen wir Ebene „Quartale“ aus der Dimension „Monate“. Unser Beispiel sieht vor, die Ausgaben für die Krankenversicherung unserer Vertriebsmitarbeiter gegenüberzustellen. In unserer Kennzahlenstruktur liegt die Kennzahl „Krankenversicherung“ auf Ebene 2 der Kennzahlen (siehe auch Abbildung 4). Da uns andere Kennzahlen in diesem Formular nicht interessieren, legen wir einen Filter auf die Kennzahl „Krankenversicherung“.

*Abbildung 4 - Die Kategorie Ebenen festlegen (links) und die Kategorie „Filter festlegen“ (rechts) beim Konfigurieren der Spalten*

Abbildung 5 zeigt das Resultat unserer Verschachtelung. Die Ausgaben für die Krankenversicherung unserer Vertriebsmitarbeiter werden quartalsweise gelistet. Dabei stellen wir IST- und Plan-Variante gegenüber.

Abbildung 5 – Ausgaben für die Krankenversicherung der Vertriebsmitarbeiter werden auf Quartalsebene gelistet. IST- und Plan-Variante werden verglichen.

# Berechtigungen für verschachtelte Ebenen **Formulare mit verschachtelten Ebenen unterliegen aufgrund ihrer speziellen Funktionalität bestimmten Regeln, die bei der Definition von Berechtigungen für Planer beachtet werden müssen.** In diesem Artikel wird erläutert, wie die Berechtigungen für einen Planer und ein Formular mit verschachtelten Ebenen zusammenwirken. Die Nutzung des Formulars durch den Planer hängt sowohl von den ihm zugewiesenen Berechtigungen als auch von den verwendeten Ebenen im Formular ab. Informationen zur Erstellung eines Formulars mit verschachtelten Ebenen finden Sie in der [Kategorie Formulare](/user/arbeiten-mit-formularen). Abbildung 5 verdeutlicht aber den Zusammenhang zur Formularerstellung und zeigt, wie ein Formular mit verschachtelten Ebenen konfiguriert werden kann. ### Regel 1: Berechtigungen müssen auf der gleichen Ebene liegen Damit ein Formular, das die verschachtelten Ebenen benutzt, für den Planer sichtbar ist, müssen die Berechtigungen auf Knoten der gleichen Ebene sitzen. Im folgenden Beispiel hat der Planer das Recht, die Region West und die Region Ost zu bearbeiten. Beide Knoten liegen auf Ebene 2 und das Formular wird für ihn angezeigt.

*Der Planer hat die Berechtigung, sowohl auf die Knoten "Region West" als auch auf die Knoten "Region Ost" zuzugreifen.*

Im nächsten Beispiel ist der Planer berechtigt, "Region West" und "Hamburg" zu sehen. Die beiden Knoten liegen nicht auf der gleichen Ebene. Der Planer wird das Formular nicht benutzen können.

*Die Berechtigungen sitzen nicht auf der gleichen Ebene*

Um dem Planer das Formular zugänglich zu machen, müssen die Berechtigungen auf Städte-Ebene vergeben werden. Abbildung 3 zeigt, wie die Berechtigungen gesetzt werden, um das gleiche Resultat wie in Abbildung 2 zu erzielen.

*Alle Berechtigungen liegen auf der Städte-Ebene*

### Regel 2: Es darf keine Ebene im Formular verwendet werden, auf die der Planer nicht berechtigt ist Die zweite Regel besagt, dass nur Ebenen verwendet werden dürfen, auf die der Planer berechtigt ist. Welche Ebenen das sind, lässt sich gut an Abbildung 4 erkennen. Da der Planer nur auf Knoten der dritten Ebene (Städte) berechtigt ist, kann Ebene 2 **nicht** für die Verschachtelung verwendet werden. Ebenen 3 und 4 dürfen - auch einzeln (!) - in verschachtelten Formularen verwendet werden. Der Planer würde bei der Verwendung von Ebene 3 die Kunden 1-3 und 7-8 sehen, da diese unter den Knoten sitzen, auf die er berechtigt ist.

*Ebene 2 kann nicht für die Verschachtelung verwendet werden, da der Planer erst auf Knoten der dritten Ebene (Städte) berechtigt ist.*

*Bei der Konfiguration der Zeilen lassen sich im Modus "Automatisch nach Ebenen" nach Auswahl der Dimension, die einzelnen Ebenen auswählen.*

# Arbeiten mit Formularen Formulare sind das zentrale Werkzeug zur Dateneingabe und -bearbeitung in QVANTUM. In diesem Kapitel erfahren Sie, wie Formulare aufgebaut sind, welche Funktionen sie bieten und wie Sie sie effizient

# Suche innerhalb einer Dimension **Mit der Suchfunktion auch in umfangreichen Dimensionen direkt das gesuchte Element finden** Dimensionen, wie die Organisationseinheiten in der Personalkostenplanung können extrem umfangreich sein. Um dort z.B. einen Mitarbeiter auf der untersten Ebene zu finden, kommt man um die Suchfunktion nicht herum. Die Dimensionssuche in Qvantum orientiert sich im Wesentlichen an der gewohnten Funktionalität der Browser-Suchfunktionen. Nach Eingabe der gesuchten Zeichenkette und anschließendem Drücken der Enter-Taste zeigt die Suche an, wieviele Treffer es gibt. Dabei wird sofort zum ersten Suchergebnis gescrollt. Durch erneutes Betätigen der Enter Taste, wird zum nächsten Treffer gescrollt.

*Suche nach "ha" in der Dimension Vertriebseinheiten zeigt zwei Suchergebnisse an.*

# Zahlformatierungen Übersicht über die möglichen Zahlenformatierungen in der Anwendung. ### Beachten Sie, dass sich Dezimaltrennzeichen und Tausendertrennzeichen von der **Spracheinstellung** ableiten. Englische Spracheinstellung: 1,000.00€ Deutsche Spracheinstellung: 1.000,00€ ### Punkte als Tausendertrennzeichen Punkte können grundsätzlich als Tausendertrennzeichen verwendet werden. Die falsche Platzierung von Tausendertrennzeichen führt allerdings zu einer Fehlermeldung.:

Richtig wären die Schreibweisen 1.000 oder 1.000,00.

### Komma als Dezimaltrennzeichen Es darf maximal ein Komma als Dezimaltrennzeichen verwendet werden. Vor und hinter dem Komma muss sich mindestens eine Ziffer befinden. Falsche Eingabe:

Richtig:

### Zellfunktionen Zellfunktionen können verwendet werden. Mehr über [Zellfunktionen](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/zellfunktionen). ### Minuszeichen Sie dürfen maximal ein vorangestelltes Minus verwenden. Ein Minuszeichen darf nicht mit einer [Zellfunktion](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/zellfunktionen) in derselben Formularzelle verwendet werden. Fehlermeldung mit zwei Minuszeichen:

Beispiel:

### Formatierung mit Einheiten Die Zeichenfolge, die zum Wertetyp der zu ändernden Zelle gehört, darf nach der Zahl verwendet werden. Jede Zelle hat genau einen von 5 möglichen Wertetypen. Der Owner kann für jeden dieser Wertetypen eine Zeichenfolge als Einheit definieren. Beispiel: Für den Wertetyp "Preis" könnte die Zeichenfolge "EUR" und für den Wertetyp "Prozentsatz" die Zeichenfolge "%" festgelegt worden sein. Dann wäre die Eingabe "3EUR" für eine "Preis"-Zelle erlaubt. Verboten wären für dieselbe Zelle "3€" oder "3$", weil das jeweils nicht die vorgegebene Zeichenfolge ist und auch "3%" ist nicht erlaubt, weil es keine "Prozentsatz"-Zelle ist. Wenn Sie die Zelle verlassen, formatieren wir die Zahl wie vom Owner festgelegt, daran können Sie die korrekte Zeichenfolge ablesen. Zwischen der Zahl und der Zeichenfolge dürfen beliebig viele Leerzeichen stehen. Beispiel:

### Multiplizieren von Zahlen mit K oder M Die Zeichen **K** und **M** dienen als Abkürzungen für **Tausend** und **Millionen**. #### Multiplizieren mit Tausend (K) ``` K oder k multipliziert mit 1.000 ``` Vorher:

Nachher:

Multiplizieren mit Million (M) ``` M oder m multipliziert mit 1.000.000 ``` Vorher:

Nachher:

# Zellfunktionen Bei Zellfunktionen handelt es sich um Funktionen, die Sie in den Formularzellen benutzen können, um Werte innerhalb der Zellen zu verändern. Klicken Sie auf eine Zelle mit einem Wert und geben Sie die gewünschte Funktion mittels der entsprechenden Syntax ein. ### Addieren ``` add addiert zur aktuellen Zahl in der Zelle den Wert dazu ``` Vorher:

Zwischenschritt:

Nachher:

### Subtrahieren ``` sub subtrahiert von der aktuellen Zahl in der Zelle den Wert ``` Vorher:

Zwischenschritt:

Syntax zur Subtraktion des Wertes "5" einfügen.

Nachher:

### Prozent addieren ``` add% erhöht den Zellenwert um % ``` Vorher:

Zwischenschritt:

Nachher:

### Prozent subtrahieren ``` sub% reduziert den Zellenwert um % ``` Vorher:

Zwischenschritt:

Nachher:

### Dividieren ``` div teilt den Zellenwert durch ``` ### Multiplizieren ``` mul multipliziert den Zellenwert mit ``` # DrillTab Mit DrillTabs gezielt in die Tiefe – ohne den Überblick zu verlieren In der Planung gibt es immer wieder Elemente, die auffallen – sei es durch ungewöhnliche Werte oder weil weitere Informationen nötig sind, die im aktuellen Formular nicht enthalten sind. Genau hier kommen die **DrillTabs** ins Spiel: Sie ermöglichen es, **für ein ausgewähltes Element** ein **neues, passendes Formular** in einem separaten Tab zu öffnen, um gezielt **Details zu diesem Element** einzusehen – ohne das ursprüngliche Formular zu verlassen. **Beispiel:**\ In der Personalkostenplanung fällt ein bestimmter Mitarbeiter durch ein ungewöhnliches Basisgehalt auf. Um sich ein umfassenderes Bild zu machen, möchten Sie auch die anderen Kennzahlen zu diesem Mitarbeiter sehen – ohne die aktuelle Ansicht zu unterbrechen.\ Über das **Mouseover-Icon** (Zoom, siehe nachfolgende Abbildung) öffnen Sie eine Liste mit verfügbaren Detailformularen.

Die angezeigten Formulare sind bereits **kontextsensitiv gefiltert**: Es erscheinen nur jene, die das gewählte Element (z. B. den Mitarbeiter) im Header anzeigen können – so sehen Sie direkt die relevanten Detailinformationen genau zu diesem Fall. Die folgende Abbildung zeigt die gefilterten Formulare für den Aufruf über die Zeile mit "Max Müller".

Es werden nur die Formulare angezeigt, bei denen das gewählte Element automatisch im Header platziert werden kann.

In unserem Beispiel wird jetzt das Formular **„Personalkosten – je Mitarbeiter & Monat“** ausgewählt. Es öffnet sich ein neuer Tab, in dem das gewählte Element – **„Max Müller“** – automatisch im **Header** des Formulars verankert ist. {% hint style="info" %} Auch die übrigen Filterkontexte aus dem ursprünglichen Formular werden übernommen: Das **Jahr 2025**, die **Plan-Variante** sowie das **Szenario „Best Case“** bleiben erhalten. {% endhint %} Im neuen Formular werden nun in den **Zeilen alle relevanten Kennzahlen zu Max Müller** angezeigt – für einen gezielten Blick auf alle Detailwerte.

Die Header Dimensionen sind - soweit möglich - aus dem aufrufenden Formular übernommen

Sobald Sie Ihre Analyse abgeschlossen und Ihre Fragen geklärt haben, können Sie den Tab einfach schließen und nahtlos im ursprünglichen Formular weiterarbeiten.

# Verteilmöglichkeiten in verschachtelten Ebenen Qvantum bietet verschiedene Möglichkeiten, auf aggregierte Strukturelemente zu schreiben, wobei die Werte über mehrere Dimensionen hinweg auf die Kindelemente verteilt werden können ### Die Aggregation auf inneren Knoten Schauen wir uns zunächst an, wie die Elemente innerhalb einer Struktur aggregiert werden. #### Beispiel Dimension 1: Aggregation in der Dimension „Monate“ Abbildung 1 veranschaulicht das für die Dimension „Monate“. Die einzelnen Elemente der Monate werden zu Quartalen zusammengefasst. Die Quartale selbst werden wieder zum Gesamtjahr aufsummiert. Das Strukturelement Q1 ist mit der Aggregationsregel „Summe“ belegt. Es enthält demnach immer die Summe seiner Kindelemente (Januar, Februar und März).

*Abbildung 1 – Die Monate werden zu Quartalen, die Quartale zum Gesamtjahr aufsummiert*

### Beispiel Dimension 2: Aggregation in der Dimension „Organisationseinheit“ Abbildung 2 zeigt, wie sich die einzelnen Elemente (Mitarbeiter) zu dem jeweils darüber liegenden Knoten (Abteilungen) aufsummieren.

**Abbildung 2 – Organisationsstruktur:** Die Mitarbeiter sind in Abteilungen unterteilt, welche zur gesamten Organisation zusammengefasst werden.

### Referenzen für die Verteilung Wird ein Wert auf seine Kindelemente verteilt, kann das durch Angabe einer Referenz (-Spalte oder -Zeile) geschehen. Abbildung 3 zeigt, wie die Verteilung unter Auswahl einer Referenzspalte/-zeile funktioniert. Wenn ich z.B. den neuen Wert „60“ für Q1 eintrage kann ich als Referenz Q2 auswählen. Damit übernehme ich das Verhältnis der drei Monate untereinander (April, Mai, Juni: 30, 40, 50), nicht aber die Werte! Diese müssen zusammen genau „60“ ergeben und im Verhältnis 3:4:5 stehen. Damit ergeben sich die Werte 15, 20 und 25 als neue Monatswerte für Q1.

*Abbildung 3 – Verteilung nach Referenzspalte/-zeile*

Nicht immer ist die Auswahl von Referenzen möglich. Werden die drei Monate (Jan, Feb, Mar) nicht im Formular angezeigt, kann ich trotzdem einen neuen Wert für das Quartal eintragen. Die Verteilung erfolgt dann als „Selbstreferenz“. Abbildung 4 verdeutlicht das. **Verteilung nach Selbstreferenz** Wenn ein Strukturelement die Werte seiner Kind-Elemente aufsummiert, lässt sich dieser aggregierte Wert nach der Selbstreferenz verteilen. In diesem Fall wird der neue Wert so auf die Kindelemente verteilt, dass sich das Verhältnis seiner Kindelemente untereinander nicht verändert. Abbildung 4 veranschaulicht, wie sich ein auf Q1 eingetragener Wert nach Selbstreferenz verteilt.

### Wie funktioniert jetzt die Verteilung von Eingaben im Formular? #### Verteilung in Formularen mit dimensionstreuen Achsen In Abbildung V1.1 ist ein Formular mit dimensionstreuen Achsen zu sehen. In den Zeilen liegt die Dimension „Organisationseinheiten“ und in den Spalten liegt die Dimension „Monate“. Alle weißen Zellen sind eingabefähig. Auch zu beachten ist der Formularheader mit der Kennzahl „Basisgehalt“, der Variante „Plan“, dem „Best Case“ Szenario, sowie dem Jahr „2023“.

*Formular mit dimensionstreuen Achsen – Eingabe auf Vertrieb/Januar*

#### 1. Verteilung der Summe für die Abteilung auf die einzelnen Mitarbeiter Wenn ich den Wert, den die Vertriebsabteilung im Januar 2023 ausmacht, auf 13.000 € erhöhen möchte, fragt Qvantum nach einer Referenzspalte (Abbildung V1.2). Die 13.000 € entsprechen natürlich am Ende der Summe Ihrer Kindelemente (der drei Mitarbeiter). Ich entscheide mich für die Referenzspalte „Januar“ und ändere damit das Verhältnis der Gehälter untereinander **nicht** (siehe Abbildung V1.3).

*Auswahl einer Referenzspalte für meine Eingabe*

Abbildung 1.3 zeigt, das die Gehälter der Mitarbeiter neu berechnet wurden, um in der Summe auf die 13.000 € zu kommen.

2\. Verteilung der Quartalssumme auf die einzelnen Monate In diesem Beispiel möchte ich für einen Mitarbeiter 14.000 € auf das Quartal 1 schreiben. Hierfür muss ich nun eine Referenzzeile auswählen.

*Verteilung der Quartalssumme der monatlichen Basisbezüge für Mitarbeiter Andre*

Indem ich dieses erhöhte Basisgehalt anhand der Referenzzeile „Gesamtunternehmen“ auf die Monate verteile, nehme ich den Anstieg der firmenweiten Gehälter in Q1 als Referenz für dieses Mitarbeitergehalt.

*Verteilung anhand der Referenzspalte „Gesamtunternehmen“*

Abbildung V2.3 zeigt das Ergebnis der Verteilung . Die Wahl der Referenzspalte hat dazu geführt, dass das Verhältnis der firmenweiten Gehälter für Januar, Februar und März untereinander übernommen wird. Die Summe der Gehälter dieses Mitarbeiters (von Januar – März) muss dabei trotzdem den eingetragenen 14.000 € entsprechen.

*Verteilung des Quartalswert auf die einzelnen Monate*

### Verteilung in Formularen mit verschachtelten Ebenen Um einen Eindruck der erweiterten Verteilmöglichkeiten in einem Formular mit verschachtelten Ebenen zu bekommen, eignet sich das nachfolgend abgebildete Formular. In den Zeilen ist lediglich eine einzige Ebene enthalten: Die Ebene „Abteilungen“ der Dimension „Organisationseinheiten“. In den Spalten liegen die Ebene „Jahre“ der gleichnamigen Dimension, sowie die Ebene „Quartale“ der Dimension „Monate“.

*Formular im Modus „Automatisch nach Ebenen“*

#### 3. Verteilung auf Mitarbeiter und Monate über verschachtelte Ebenen Für dieses Beispiel verwenden wir wieder die Dimensionen „Organisationseinheiten“ und „Monate“, deren Strukturen in Abbildungen 1 und 2 dargestellt sind. Allerdings verwenden wir in diesem Formular aus der Dimension „Organisationseinheiten“ nur die Ebene „Abteilungen“ und zeigen die Ebene „Mitarbeiter“ nicht an. Genauso werden die Quartale angezeigt, die Monate aber nicht.

*Eingabe auf Quartals- und Abteilungsebene*

Wenn ich jetzt die Bezüge für die Abteilung „Vertrieb“ in Q1 auf 43.000 € anhebe, kann ich diesen Wert einfach durch Drücken der Enter-Taste übernehmen. Im Formular ist von einer Verteilung nichts zu sehen. Das liegt daran, dass alle Elemente, auf die meine Eingabe verteilt wird, nicht im Formular liegen. Insofern kann ich auch keine Referenzzeile oder -spalte angeben . Die Verteilung erfolgt nach Selbstreferenz. #### 4. Mehrdimensionale Verteilung in den Zeilen Das nachfolgende Beispiel (siehe auch Abbildung V4.1) ist nur über den Modus „Automatisch nach Ebenen“ möglich und orientiert sich an den gleichen Beispielstrukturen, die auch in den anderen Beispielen verwendet werden. Die Zeilen enthalten hier lediglich die Ebene „Abteilungen“ (aus der Dimension „Organisationseinheiten“) und die Ebene „Quartale“ aus der Zeitdimension „Monate“. Abbildung V4.2 zeigt, wie die Achse für dieses Beispiel konfiguriert wurde. Mit dem Eintragen eines Wertes für Q1/2022 wird die folgende Verteilung angestoßen: * Der eingetragene Wert muss der Summe der Monate Januar, Februar und März entsprechen. Die Werte für Januar, Februar und März werden neu berechnet. Dabei gilt: * Das Vertriebsgehalt der drei Monate muss im gleichen Verhältnis stehen, wie es auch aktuell der Fall ist (Selbstreferenz). * Beispiel: Das Vertriebsgehalt (Summe der Gehälter aller drei Mitarbeiter) ist in den drei Monaten identisch. Damit wäre in jedem der drei Monate der Wert 10.816,67 eingetragen. Ein neu eingetragener Wert würde demnach einfach durch drei geteilt. * Der eingetragene Wert muss der Summe der einzelnen Bezüge aller drei Mitarbeiter des Vertriebs entsprechen. Die Gehälter werden neu berechnet: * Die Quartalsgehälter der drei Mitarbeiter müssen im gleichen Verhältnis stehen, wie es aktuell der Fall ist (Selbstreferenz).

*Mehrdimensionale Verteilung auf Monate und Mitarbeiter*

*Konfiguration für die mehrdimensionale Verteilung*

# Einstellungen Systemeinstellungen und der Benutzer-Account Die Systemeinstellungen betreffen hauptsächlich die Konfiguration der für Ihre Planung relevanten Wertetypen. Der zweite Teil enthält die Benutzereinstellungen.

# Systemeinstellungen Als Owner einer Qvantum Planungsanwendung können Sie verschiedene Einstellungen vornehmen. Als Owner einer Qvantum Planungsanwendung können Sie die Einstellungen aus der oberen Menüleiste (links) aufrufen.

*Abbildung 1 - Die Systemeinstellungen in der oberen Menüleiste*

Aktuell gibt es unter den Einstellungen nur die Kategorie "Wertetypen". ### Wertetypen Bei der Modellierung haben Sie bestimmt schon gesehen, dass man den verschiedenen Kennzahlen jeweils einen Wertetyp zuordnen kann. So werden bestimmte Kennzahlen als Beträge und andere als Prozentsatz oder Preis ausgegeben. Insgesamt gibt es die folgenden Wertetypen: * Betrag * Prozentsatz * Preis * Menge * Bestand Wie in der folgenden Abbildung zu sehen, können Sie neben der Einheit (z.B. € für einen Preis) auch die Anzahl Nachkommastellen bestimmen. Optional können Sie Trennzeichen zur Formatierung der Zahlen anzeigen (Standard) oder ausblenden.

# Account-Verwaltung Einstellungen zu Ihrem Benutzer **Wo befindet sich die Account-Verwaltung?** Die Account-Verwaltung öffnet sich in einem anderen Browser-Tab als die Planungsanwendung. Klicken Sie auf „Account verwalten“ um in die Account-Verwaltung zu gelangen.

Die Account Verwaltung unterteilt sich in das Nutzerkonto und die Zugangsdaten. ### Das Nutzerkonto Im Nutzerkonto tragen Sie ihre E-Mail-Adresse und Ihren Vor- und Nachnamen ein. Außerdem haben Sie die Möglichkeit, die Systemsprache von Qvantum zu konfigurieren.

**Achtung:** nach dem Speichern der Änderungen bleibt der Tab geöffnet. Schließen Sie den Browsertab, so dass der Tab mit Qvantum wieder in der Ansicht ist. Aktualisieren Sie nun zuerst Ihre Ansicht/den aktiven Browsertab, damit die Änderungen aktiv sind. Ein **Wechsel der Systemsprache** macht sich erst nach dem Aktualisieren des Browsertabs bemerkbar! ### Zugangsdaten Im Bereich Zugangsdaten können Sie jederzeit ein neues Passwort vergeben.

# Glossar Alle relevanten Begriffe rund um den Datencube auf einen Blick **Dieses Glossar erklärt die wichtigsten Begriffe, die im Kontext der Qvantum Wissensdatenbank und rund um den Datencube verwendet werden.** **Achsen im Formular**\ Formulare in Qvantum basieren auf den Achsen des Datencubes. Jede Achse repräsentiert eine Dimension, und die Felder eines Formulars werden entlang dieser Achsen angeordnet. Ein Planer könnte beispielsweise eine Kostenstelle (Spaltenachse) über verschiedene Zeiträume (Zeilenachse) planen.\ [Die drei Modi der Achsenkonfiguration](/user/arbeiten-mit-formularen/konfiguration-der-formulare/die_drei_modi_der_achsenkonfiguration) **Aggregation**\ Aggregation bezeichnet die Zusammenfassung von Daten auf einer höheren Ebene. So können z.B. die Gehälter der Mitarbeiter unter dem Knoten "Vertrieb" auf der Ebene "Abteilungen" aufsummiert werden. In Qvantum ist der "Durchschnitt" nur über einen Workaround verfügbar, da er nicht als Aggregationsregel hinterlegt ist. **Änderungsprotokoll (Changelog)**\ Das Änderungsprotokoll bietet eine Übersicht über alle vorgenommenen Änderungen an den Daten im Datencube. Es enthält Informationen darüber, wer welche Änderung zu welchem Zeitpunkt durchgeführt hat und kann als CSV-Datei exportiert werden.\ [Qvantum Wissensdatenbank, Tab „Daten“](/user/ubersicht_uber_den_tab_daten#anderungsprotokoll-changelog) **API (Application Programming Interface)**\ Eine API ermöglicht es, Softwarekomponenten miteinander zu kommunizieren. Sie wird verwendet, um Daten zwischen externen Systemen zu übertragen oder zu verarbeiten.\ [Qvantum Wissensdatenbank, API-Dokumentation](https://api.qvantum-plan.de/tutorial/index.html) **Authentifizierung**\ Authentifizierung bezeichnet den Prozess der Verifizierung eines Benutzers oder Systems, um Zugriff auf bestimmte Daten oder Funktionen zu gewähren. Dies sorgt dafür, dass nur berechtigte Nutzer auf die entsprechenden Daten zugreifen können. **Benutzerrechte**\ Benutzerrechte steuern den Zugriff auf Daten innerhalb des Datencubes. In Qvantum können Benutzerrechte so konfiguriert werden, dass Planer nur auf bestimmte Teilwürfel zugreifen können, basierend auf ihrer Rolle oder ihren Verantwortlichkeiten.\ [Qvantum Wissensdatenbank, Nutzer-Berechtigungen](https://lp.qvantum-plan.de/wissensdatenbank/guide-nutzerberechtigungen-vergeben) **Datenexport**\ Datenexport bezeichnet den Vorgang, bei dem Planungsdaten aus Qvantum in externe Systeme oder Formate (z. B. Excel) exportiert werden. Dies ermöglicht es den Benutzern, die Daten außerhalb des Systems weiter zu bearbeiten oder Berichte zu erstellen.\ [Qvantum Wissensdatenbank, Tab „Daten“](/user/ubersicht_uber_den_tab_daten#exportieren) **Datenimport**\ Datenimport ist der Prozess des Einlesens externer Daten in den Qvantum-Datencube. Dies erlaubt es Nutzern, vorhandene Datenquellen wie Excel-Dateien oder andere ERP-Systeme zu integrieren, um sie für Planungszwecke zu nutzen.\ [Qvantum Wissensdatenbank, Tab „Daten“](/user/ubersicht_uber_den_tab_daten#importieren) **Dimensionselement**\ Ein Dimensionselement ist eine spezifische Ausprägung innerhalb einer Dimension, wie z.B. ein bestimmtes Jahr in der Dimension *Jahre* oder eine Kostenstelle in der Dimension *Organisationseinheiten*.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/modell/arbeiten_mit_der_modellvorlage#aufbau-der-modellvorlage) **Dimensionsrollen**\ Dimensionsrollen geben einer Dimension eine spezielle Bedeutung und steuern, wie die Daten innerhalb dieser Dimension verarbeitet werden. Zum Beispiel hat die Dimension *Jahre* die Rolle der Zeitdimension. Wenn in einem Formular beispielsweise ein Jahresgehalt eingetragen wird, kann durch die Zeitrolle der Dimension eine automatische Verteilung des Gehalts auf die 12 Monate des Jahres erfolgen.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/modell/arbeiten_mit_der_modellvorlage) **Drill-Down**\ Der Drill-Down ist die Möglichkeit, von einer aggregierten Ansicht auf detailliertere Daten herunterzubrechen. In Qvantum könnte ein Planer von einer Gesamtvertriebszahl auf die Umsätze pro Region oder sogar pro Kunde drillen.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/verteilmoglichkeiten_in_verschachtelten_ebenen#verteilung-in-formularen-mit-dimensionstreuen-achsen) **Formulardefinitionen exportieren und importieren**\ Formulardefinitionen können in Qvantum exportiert und importiert werden, um Formularstrukturen zwischen verschiedenen Systemen zu übertragen. Dies erfolgt im JSON-Format und ist besonders nützlich für Backups und den Transfer von Formularkonfigurationen.\ [Qvantum Wissensdatenbank, Export und Import von Formulardefinitionen](/user/arbeiten-mit-formularen/konfiguration-der-formulare/formulardefinitionen_exportieren_und_importieren) **Formular**\ Ein Formular in Qvantum ist die Schnittstelle, über die Planer ihre Daten in den Datencube eingeben. Formulare sind vom Owner vorbereitet und enthalten Felder, die auf den Dimensionen des Datencubes basieren. Sie definieren, welche Daten der Planer eingeben kann und welche Daten nur angezeigt werden.\ [Qvantum Wissensdatenbank, Arbeiten mit Formularen](/user/arbeiten-mit-formularen) **Formularkonfigurationen**\ Qvantum ermöglicht es, Formulare nach den Anforderungen des Benutzers zu konfigurieren. Dies umfasst die Anpassung von Layouts, die Definition von zugänglichen Feldern und die Festlegung von Berechtigungen für die Eingabe.\ [Qvantum Wissensdatenbank, Weiteres zu den Konfigurationsmöglichkeiten](/user/arbeiten-mit-formularen/arbeiten-mit-formularen) **Grid Formatierung**\ Die Grid-Formatierung in Qvantum ermöglicht es, Formulare visuell anzupassen, um Planern eine übersichtliche Darstellung der Daten zu bieten. Dies umfasst z. B. die Anpassung von Farben, Schriftarten oder Zellgrößen.\ [Qvantum Wissensdatenbank, Arbeiten mit Formularen](/user/arbeiten-mit-formularen/konfiguration-der-formulare/grid_formatierung) **Hierarchie**\ Hierarchien ordnen die Elemente einer Dimension auf unterschiedlichen Ebenen an. Zum Beispiel könnte die Dimension *Organisationseinheiten* eine hierarchische Struktur haben, die von einer globalen Organisationseinheit bis hin zu spezifischen Unterorganisationseinheiten reicht. **Kennzahl**\ Kennzahlen befinden sich immer in der Dimension *Kennzahlen*. Diese Dimension hat auch die spezielle Rolle *Kennzahlen*. Eine Besonderheit dieser Dimension in Qvantum ist, dass Kennzahlen mit Formeln definiert werden können. Zum Beispiel könnte die Kennzahl *Umsatz* mit der Formel *Absatz \* Preis* berechnet werden. Diese Formeln können die Schlüssel anderer Kennzahlen verwenden, um Berechnungen durchzuführen.\ [Qvantum Wissensdatenbank, Formelmanager](/user/modell/segmente_und_kennzahlenformeln) **Kennzahlenformel**\ Eine Kennzahlenformel ist eine mathematische oder logische Berechnung, die auf einer oder mehreren Kennzahlen basiert. Diese Formeln erlauben es, komplexe Kalkulationen durchzuführen, wie z. B. *Umsatz = Absatz \* Preis*.\ [Qvantum Wissensdatenbank, Formelmanager](/user/modell/segmente_und_kennzahlenformeln) **Knoten**\ Ein Knoten ist ein Element innerhalb einer Hierarchie, das andere Elemente oder Detailstufen zusammenfasst. Ein Beispiel wäre eine regionale Vertriebsgruppe, die mehrere lokale Vertriebsstellen als untergeordnete Knoten hat. **Konsolidierung**\ Konsolidierung ist der Prozess der Zusammenführung von Daten über mehrere Dimensionen oder Ebenen hinweg. In Qvantum könnte dies bedeuten, dass Daten aus verschiedenen Kostenstellen oder Szenarien in einem Bericht zusammengeführt werden. **Modellvorlage**\ Die Modellvorlage ist das strukturelle Grundgerüst des Qvantum-Datencubes. Sie enthält alle Dimensionen und Elemente, die in den Planungsprozessen verwendet werden. Benutzer können in der Modellvorlage neue Dimensionen hinzufügen oder bestehende Elemente ändern, um das Modell den spezifischen Anforderungen anzupassen.\ [Qvantum Wissensdatenbank, Modellvorlage](/user/modell/arbeiten_mit_der_modellvorlage) **Owner**\ Der Owner ist eine Rolle, die in Qvantum die Funktion eines Administrators übernimmt. Der Owner ist für die Einrichtung und Pflege der Formulare verantwortlich, die den Planern zur Verfügung gestellt werden. Der Owner legt auch die Berechtigungen fest, die bestimmen, welche Planer auf welche Formulare und Teilwürfel zugreifen dürfen. **Planer**\ Ein Planer ist ein Benutzer, der in Qvantum Planungsdaten eingibt und bearbeitet. Der Zugriff des Planers ist auf die Formulare und Teilwürfel beschränkt, die ihm zugewiesen wurden. Planer haben in der Regel keine Berechtigung, das Modell zu ändern, sondern können nur auf die ihnen zugewiesenen Daten zugreifen und diese bearbeiten.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/qvantum-fur-planer) **Referenzspalte/-zeile**\ Bei der Formularbearbeitung in Qvantum kann der Benutzer zur Eingabe eines Wertes auf einem Knoten nach einer Referenzspalte oder -zeile gefragt werden. Wählt der Benutzer eine Referenz, wird der eingetragene Wert nach den gleichen Proportionen verteilt, wie die Verteilung in der Referenzspalte oder -zeile.\ [Qvantum Wissensdatenbank, Referenzspalte/-zeile](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/verteilmoglichkeiten_in_verschachtelten_ebenen#verteilung-in-formularen-mit-dimensionstreuen-achsen) **Segment**\ In Qvantum kann der Datenwürfel entlang einer Dimension wie *Jahre* geschnitten werden, um separate Teilwürfel, sogenannte Segmente, zu erstellen. Ein Segment kann beispielsweise die Daten für die Jahre 2024, 2025 und 2026 jeweils separat darstellen. Der Begriff "Segment" wird in Qvantum synonym für "Teilwürfel" verwendet.\ [Qvantum Wissensdatenbank, Modellvorlage](/user/modell/segmente_und_kennzahlenformeln#segmente) **SSO (Single Sign-On)**\ Single Sign-On (SSO) wird in großen Unternehmen häufig als Sicherheitsstandard eingesetzt, da es den Zugriff auf mehrere Anwendungen mit nur einer Authentifizierung ermöglicht. Dies verbessert die Sicherheit, da Benutzer nur ein starkes Passwort für alle Anwendungen benötigen, was das Risiko verringert. Qvantum kann als eine dieser Anwendungen integriert werden, sodass Benutzer nach der einmaligen Anmeldung auf alle verknüpften Systeme zugreifen können. **Systemeinstellungen**\ Systemeinstellungen in Qvantum ermöglichen es dem Owner, zentrale Konfigurationen für die gesamte Planungsumgebung vorzunehmen. Dazu gehören unter anderem die Verwaltung von Wertetypen, Formatierungen und weiteren Einstellungen, die das Verhalten der Software beeinflussen. [Systemeinstellungen in Qvantum](/user/einstellungen/systemeinstellungen) **Token**\ Ein Token ist ein digitales Authentifizierungsinstrument, das nach erfolgreicher Anmeldung verwendet wird, um den Zugriff auf bestimmte Daten oder Systeme zu gewähren. Es fungiert als Sicherheitsschlüssel in Netzwerken oder bei API-Zugriffen. **Verteilung im Würfel**\ Verteilung im Würfel bezieht sich auf die automatische Verteilung von Werten entlang einer Dimension. Zum Beispiel könnte ein eingegebener Jahreswert automatisch auf die Monate verteilt werden, wenn die Zeitdimension diese Funktion unterstützt.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/verteilmoglichkeiten_in_verschachtelten_ebenen) **Wertetypen**\ Wertetypen in Qvantum bestimmen, wie bestimmte Kennzahlen dargestellt und behandelt werden. Es gibt verschiedene Typen wie *Betrag*, *Prozentsatz*, *Preis*, *Menge* und *Bestand*. Diese Wertetypen definieren das Format und die Währungseinheit, in der die Kennzahlen dargestellt werden.\ [Qvantum Wissensdatenbank, Benutzereinstellungen](/user/einstellungen/systemeinstellungen) **Workflow zur Planung**\ In Qvantum gibt es drei Stufen im Planungs-Workflow: "Offen" (nachdem die Planung gestartet ist), "Eingereicht" (sobald ein Planer seine Arbeit eingereicht hat), und "Abgenommen" (sobald der Owner die Zahlen abgenommen hat). Dieser Workflow sorgt für einen klaren Ablauf der Planungsphasen.\ [Qvantum Wissensdatenbank, Qvantum für Planer](/user/ubersicht-uber-die-planung/der_workflow) **Zahlformatierungen**\ Zahlformatierungen in Qvantum hängen von den Spracheinstellungen ab. Zum Beispiel wird in der deutschen Einstellung das Format "1.000,00 €" verwendet, während in der englischen Spracheinstellung "1,000.00 €" üblich ist. Dies ist besonders bei der Darstellung von Finanzdaten wichtig.\ [Qvantum Wissensdatenbank, Benutzereinstellungen](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/zahlformatierungen) **Zellfunktionen**\ Zellen in Qvantum-Formularen können bestimmte Funktionen ausführen, wie z. B. Summenberechnungen oder Verknüpfungen mit anderen Feldern im Formular. Diese automatisierten Funktionen unterstützen eine effiziente Dateneingabe und -bearbeitung.\ [Qvantum Wissensdatenbank, Arbeiten mit Formularen](/user/arbeiten-mit-formularen/arbeiten-mit-formularen/zellfunktionen) # Entwickler-Dokumentation This tutorial targets developers intending to integrate their applications with QVANTUM via the QVANTUM Public API. With completion of this tutorial, readers will be able to use the QVANTUM Public API to prepare a QVANTUM plan, update data and metadata of a plan and export data collected with a plan in QVANTUM. ## Overview This tutorial is organized in the following topics: 1. [Getting a Tenant](/dev/get-tenant): request tenant 2. [General Information](/dev/general-information): general information about the structure of the API and how to access it 3. [Planning Models](/dev/model): upload, update and export of models 4. [Key Figures](/dev/key-figures): upload, update and export of key figures (formulas) 5. [Handling Cell Data](/dev/cell-data): uploading, deleting and exporting cell data 6. [Define Team](/dev/team): inviting an initial team an updating it 7. Managing Folders and Forms: import and export folders and forms {% hint style="info" %} Topic 7 is still being migrated from our previous mkdocs-based tutorial. Check back soon. {% endhint %} ## Tools For most relevant use cases, this tutorial documents the interaction with the QVANTUM Public API using the wide-spread tool [curl](https://curl.haxx.se/), thus allowing developers with access to a valid QVANTUM tenant context to follow along and prototype their integration. For each QVANTUM Public API call, this tutorial provides an executable curl command line and a description of the most relevant details of request and response payloads. ## Feedback If you have questions, comments, etc. please email us at . # Getting a Tenant First prerequisite to using the QVANTUM Public API is a valid QVANTUM *tenant* context. If you are interested in experimenting with the QVANTUM Public API, please contact us at to have a tenant context set up for you. Upon creation of your tenant context, you will receive an invitation mail, including URLs and initial login credentials for the QVANTUM Web App. Please follow the instructions in this invitation mail, perform a first login and change password immediately, before you use your username/password credentials with the QVANTUM Public API. This tutorial builds upon a set of expected environment variables, mainly derived from the information of a QVANTUM tenant context. For the included curl command lines to work properly, developers must make sure that the following environment variables are set correctly, in particular wrt. [authentication](/dev/general-information#authentication). * `API`: QVANTUM Public API endpoint URL; must be set to `https://api.qvantum-plan.de`. * `AUTH`: QVANTUM Authentication endpoint URL; must be set to `https://auth.qvantum-plan.de`. * `TENANT` : tenant identifier, as used in `https://app.qvantum-plan.de/tenants/${TENANT}`. * `CLIENTID`: identifier of OAuth 2.0 client, defaults to `api`. * `USERNAME`: username of your tenant account, stated as email address. * `PASSWORD`: password of your tenant account. # General Information This page lists information to access the API that is relevant for all endpoints. ## Authentication Authentication in QVANTUM relies upon the [OpenID Connect](https://openid.net/connect/) protocol, being a simple identity layer on top of the [OAuth 2.0](https://oauth.net/2/) protocol. For third-party client authentication with the QVANTUM Public API, we particularly employ the [OAuth 2.0 Password Grant](https://oauth.net/2/grant-types/password/). A valid access token is prerequisite to any use of the QVANTUM Public API. Such a token can be acquired in exchange for a set of credentials valid within the tenant context. The respective authentication request includes details such as tenant id, client id, credentials, and a fixed grant type. **Authentication Request with curl** ```sh curl --request POST \ --header "Content-Type:application/x-www-form-urlencoded" \ --data "grant_type=password" \ --data "client_id=${CLIENTID}" \ --data "username=${USERNAME}" \ --data "password=${PASSWORD}" \ "${AUTH}/auth/realms/${TENANT}/protocol/openid-connect/token" ``` In case of a successful authentication, the response body will include a JSON payload like the following. Most importantly, the payload includes an access token, which will be required in all subsequent calls to the QVANTUM Public API. For the rest of this tutorial, the environment variable `TOKEN` represents the value for a valid access token gathered by this initial request. By default, all access tokens will expire after 5 minutes. For refreshing an access token, the response also includes a refresh token, expiring after 30 minutes. **Authentication Response JSON Payload** ```json { "access_token": "", "expires_in": 300, "refresh_expires_in": 1800, "refresh_token": "", "token_type": "bearer", "not-before-policy": 0, "session_state": "7f97c7ba-aac8-4a26-854b-ecd833b67ac3", "scope": "profile email add_audience_plankit-service" } ``` For all subsequent requests to the QVANTUM Public API, access token information is passed as `Authorization` header with value `Bearer ${TOKEN}`. ## Navigation The QVANTUM Public API is designed as a REST-style API following the [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) principle. As such, endpoints represent *resources* relevant in a planning domain. Besides resource-specific information, each resource also includes a set of *links* to itself and other resources, thus allowing navigation by following links in series of requests. Every navigation starts with the tenant collection as an entry point. Next, link relations are followed to the relevant resources (e. g. plans or cubes). Navigation to further resources not explicitly documented here follows the same principle. {% hint style="warning" %} Clients using the QVANTUM API **must** use navigations via link since URLs can change at any time. Only the entry point URL `${API}/api/v1/tenants` is guaranteed to stay the same. The name of the links in the resources will not be changed or removed, therefore allowing for backward compatibility with older clients. If a client does not use navigation via links it may break at any time! {% endhint %} ### Navigating to a Tenant With the availability of an access token, navigation starts with a request to the tenants resource, representing the list of all available tenant resources. The access token is passed via an authentication header `Authorization` with value `Bearer ${TOKEN}`, acquired during [authentication](#authentication). **Retrieve Tenant Information** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ '${API}/api/v1/tenants' ``` The response payload includes a JSON representation of a one-element list of tenant representations. Besides an id, display name, and description, a tenant resource includes the following links: * `allPlans`: a link to a collection of all plan resources * `plans`: an array of links to the plan resources. * `allUsers`: retrieval link for user definition (cf. [retrieve user definition](/dev/team#retrieve-user-definition)) * `userUploads`: upload link for user definition (cf. [upload user definition](/dev/team#upload-user-definition)) * `planning-app`: link to planning web application **Tenant JSON Representation** ```json { "tenants":[ { "id":1, "displayName":"My Tenant", "description":"A tenant for me.", "_links":{ "self": { "href":"https://api.qvantum-plan.de/api/1/tenants/1" }, "allPlans":{ "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans" }, "plans":[ { "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans/1" } ], "allUsers":{ "href":"https://api.qvantum-plan.de/api/v1/tenants/1/users{?includeControllers}", "templated": true }, "userUploads":{ "href":"https://api.qvantum-plan.de/api/v1/tenants/1/userUploads" }, "planning-app":{ "href":"https://app.qvantum-plan.de/thinking-networks/" } } } ] } ``` ### Navigating to a Plan Within a tenant, QVANTUM supports a collection of plans. The `allPlans` link will return this collection. Alternatively, starting from a tenant resource, following a link in the `plans` array provides a shortcut to the URL of the plan resource. A request to this resource provides information about the respective planning application, including further navigation links. **Retrieve Plan Information** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ '${PLAN_LINK}' ``` The response payload includes a JSON representation of the plan resource. Besides an id, title, status and end date, a plan resource includes the following links: * `owner`: owning tenant * `uploads`: endpoint for planning model metadata (cf. [upload planning model](/dev/model#upload-planning-model)). * `allCubes`: list of all cube resources within this plan * `allStructures`: list of all structure resources within this plan * `allPermissions`: upload resp. retrieval link for permission assignment (cf. [upload permission assignment](/dev/team#upload-permission-assignment) resp. [retrieve permission assignment](/dev/team#retrieve-permission-assignment)) * `structuresUploads`: endpoint can be used to update structures * `userStates`: an array of links to the state of each planner in this plan (cf. planner status) The states of all planners are also embedded in the plan resource, so that a single request is sufficient to see who is still working on the plan. The "status" field may have only these values: * `NOT_STARTED` : the workflow has not been started yet. * `RUNNING` : the workflow is running. * `PAUSED` : the workflow has been paused. * `FINISHED`: the workflow has been finished. * `EXPORTED`: the workflow has been finished and the data has been exported. Updates of `title`, `endDate` and `status` can be updated with a PATCH request (cf. Update a Plan). ### Plan JSON Representation ```json { "id": 1, "title": "My Plan", "endDate": "2022-09-30T21:59:59Z", "status": "", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1" }, "owner":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1" }, "uploads":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/modelUploads?planId=1" }, "allStructures": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures?planId=1" }, "allCubes":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes?planId=1" }, "allPermissions": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/permissions?planId=1" }, "structuresUploads": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structuresUploads?planId=1" }, "userStates": [ { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/userStates/2" } ] }, "_embedded": { "userStates": [ { "status": "SUBMITTED", "submissionDate": "2022-09-28T14:21:07Z", "sessions": { "f0f7d13e-9d3d-4b3f-8ba1-59ee89b2d76e": { "lastOnline": "2022-09-28T14:20:53Z", "unsavedChanges": false } }, "_links": { "self": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/userStates/2" }, "plan": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1" }, "user": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/users/2" } } } ] } } ``` ### Navigating to a Cube Within a plan, QVANTUM supports a set of cubes. As for plans within tenants, this set is currently limited to one cube per plan. Starting from a plan resource, following the link `allCubes` leads to a cube collection resource, listing all available cubes. {% tabs %} {% tab title="Retrieve Cube List" %} ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ ${ALL_CUBES_LINK}' ``` {% endtab %} {% tab title="Retrieve Single Cube" %} ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ ${CUBE_LINK}' ``` {% endtab %} {% endtabs %} The response payload includes a JSON representation of a one-element array of cube representations. Besides an id, business key, display name, and description, each cube representation includes the following links: * `dimensions`: array of links to this cube's dimension resources. * `keyFigures`: export link for the key figures (cf. [export key figures](/dev/key-figures#export)) * `keyFiguresUploads`: upload link for the key figures (cf. [upload key figures](/dev/key-figures#upload)) * `dataUploads`: upload link for cube cell data (cf. [upload initial data](/dev/cell-data#upload-initial-data)) * `dataDeletions`: link for cell data deletions (cf. [deleting planning data](/dev/cell-data#deleting-planning-data)) * `data`: download link for cube cell data (cf. [export cell data](/dev/cell-data#exporting-planning-data) / [delete cell data](/dev/cell-data#deleting-planning-data)) * `template`: download link to cube cell data template (cf. [download data template](/dev/cell-data#download-data-template)) * `modelUploads`: upload link for full model updates (cf. [upload full model update](/dev/model#upload-full-model-update)) * `allExternalForms`: import/export link for forms (cf. export and import forms) **Single Cube JSON Representation** ```json { "id": 1, "businessKey": "MYCUBE", "displayName": "My Cube", "description": "A cube for me.", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1" }, "plan":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1" }, "dimensions":[ {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1"}, {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/2"}, {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/3"}, {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/4"}, {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/5"}, {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/6"} ], "keyFigures": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/keyFigures" }, "keyFiguresUploads": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/keyFiguresUploads?cubeId=1" }, "dataUploads": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/dataUploads?cubeId=1" }, "dataDeletions": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/dataDeletions?cubeId=1" }, "data":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/cells{?dimensionRestrictions,inputAllowedFilter}" }, "template":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/template" }, "modelUploads": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/modelUpdates?cubeId=1" }, "allExternalForms": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/forms" } } } ``` ### Navigating to a Dimension A cube is substantial part of the model behind a plan. A cube mainly consists of a set of dimensions. Detailed information on the structure of a planning model is available in section [Planning model definition](/dev/model#planning-model-definition). Starting from a cube, following one of the `dimension` links leads to a dimension resource. **Retrieve Single Dimension** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ ${DIMENSION_LINK}" ``` The response payload includes a JSON representation of a single dimension. Besides an id, business key, and description, each dimension representation includes singular and plural labels (`singularName`, `pluralName`) and a link `structure` enabling the navigation to the structure, defining the elements of a dimension (cf. next section). **Single Dimension JSON Representation** ```json { "id": 1, "businessKey": "KF", "singularName": "Key Figure", "pluralName": "Key Figures", "description": "A dimension for key figures.", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1" }, "cube":{ "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/cubes/1" }, "structure":{ "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/structures/1" } } } ``` ### Navigating to all Structures Within a plan, QVANTUM supports a set of structures. Starting from a plan resource, following the link 'allStructures' leads to a structure collection resource, listing all available structures with their elements as described [here](/dev/model#upload-more-than-one-structure). **Structure List** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.external-structures+json" \ '${ALL_STRUCTURES_LINK}' ``` ### Navigating to a Structure Conceptually, each dimension is defined by an underlying structure and its elements. Starting from a dimension, following the `structure` link leads to a structure resource. **Retrieve Single Structure** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ ${STRUCTURE_LINK}" ``` The response payload includes a JSON representation of a structure. Besides an id, business key, display name, description and further properties, each structure representation includes a link `upload`, allowing the upload of updates, in particular updates on the structure and the dimension based on it (cf. [updating planning models](/dev/model#updating-planning-models)). **Structure JSON Representation (extract)** ```json { "id": 1, "businessKey": "COSTCENTERS", "displayName": "Cost Centers", "description": "A structure defining a set of cost centers", ... "customAttributes": [ { "businessKey": "COSTCENTERCLASS", "displayName": "Cost Center Class", "description": "Attribute to document different classes of cost centers", "attributeType": "TEXT" } ], "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures/1" }, "plan":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plan/1" }, "upload": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structureUploads?structureId=1" } ... } } ``` ## Localization Some endpoints deliver localizable texts, e.g. log entries when [uploading planning models](/dev/model#upload-planning-model). The desired locale can be specified using the `Accept-Language` header. Supported locales are `en`, `de` (default) and `de-CH`. **Specifying Locale in Request** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept-Language:en" "${MODEL_UPLOAD_LINK}" ``` # Planning Models With the ability to authenticate and to navigate within a tenant context, the first actual use case is the preparation of a plan. Preparation consists of the following steps: 1. [*Build planning model*](#build-planning-model): build a planning model definition as set of CSV files 2. [*Upload planning model*](#upload-planning-model): upload prepared planning model definition 3. [*Upload data*](https://tn-gitlab-ci.buhl.de/tn-documentation/qvantum-public-docs/-/tree/master/dev/cell-data.md#upload-initial-data): upload initial planning data as CSV file 4. [*Upload team*](https://tn-gitlab-ci.buhl.de/tn-documentation/qvantum-public-docs/-/tree/master/dev/team.md#upload-user-definition): upload user information and permission assignments as CSV files 5. [*Import forms*](https://tn-gitlab-ci.buhl.de/tn-documentation/qvantum-public-docs/-/tree/master/dev/forms.md#folders-and-forms-import): import folders and forms as a JSON file ## Build Planning Model Each plan requires a definition of an [*OLAP cube*](https://en.wikipedia.org/wiki/OLAP_cube) model. Conceptually, a *cube* requires the definition of a set of *dimensions* on the top-level. Each dimension is modeled by a set of basic *dimension fields* and an underlying *structure*. A structure in turn is modeled as a set of structure *elements*, upon which a certain *structure* is imposed. The QVANTUM Public API expects a complete cube model definition as a set of CSV files. The following sections demonstrate how to build up a complete planning model and the set of corresponding CSV files. ### Planning Model Definition A planning model definition basically consists of a list of basic dimension definitions. A basic dimension definition includes the following fields: * *Number*: a number serving as dimension identifier * *Description*: a full-text dimension description * *Labels*: singular and plural dimension labels * *Role*: dimension role of fixed type. The following types are available: * `Kennzahlen`: special dimension role for key figures * `Planungseinheiten`: special dimension role for planning units * `Zeit`: special dimension role for time models * `ohne besondere Rolle`: regular dimension without special role The `Kennzahlen` and `Planungseinheiten` dimension roles must occur exactly once in every planning model definition. `Zeit` may appear once, but it is not required. There are no constraints on the occurrence of `ohne besondere Rolle`. {% hint style="info" %} In the context of a major planning model simplification, a number of special dimension role constraints were removed. For reasons of backward compatibility, models specifying dimensions with prior special dimension roles `Szenarien`, `Varianten`, `Jahre` and `Monate` are still accepted in planning model definitions, but effectively mapped to dimension role `ohne besondere Rolle`. {% endhint %} For later upload via the QVANTUM Public API, a cube model definition must be provided in the form of a valid CSV file, as shown in the example below. **Top-Level Model Definition CSV** ```csv number;singular-label;plural-label;role;description 1;Cost;Costs;Kennzahlen;All types of costs. 2;Cost Center;Cost Centers;Planungseinheiten;All cost centers. 3;Scenario;Scenarios;Szenarien;All scenarios. ``` #### Time Models A dimension defined with the special dimension role `Zeit` (time) allows for the definition of a one-dimensional time model. A time model is necessary to use the [`timeOffset` function](#key-figure-formulas), which allows modeling values that change over time, e.g. to track the stock of a product by planning the changes per month, not the absolute value. #### Display & Calculation Order During the design of a planning model, it is possible to control the display order of dimensions by their order of appearance in the planning model definition. The dimension number has no effect on display order. Calculation order, i.e. the order of applying aggregation and formula calculation operations in a dimension-by-dimension manner, is implicitly given by the respective dimension roles. Regular formulas in the key figure dimension are always calculated first, followed by aggregation calculations in all other dimensions. Formulas for inner nodes are calculated last. For more details on formula calculations, consult Section [Key Figure Formulas](#key-figure-formulas). Calculations take place with every change in plan data, e.g. directly by data uploads, or indirectly by model updates. ### Structure Definitions Furthermore, for each dimension, a structure must be defined. A structure definition includes a set of dimension *elements*, upon which a hierarchical *structure* is imposed. A single structure element definition includes the following fields: * *Child*: element identifier of this element * *Parent*: element identifier of a parent element * *Label*: element label * *Description*: full-text element description * *Input Allowed*: data input allowed for this particular element * *Layer Name*: the name of the hierarchical layer of this element (optional) * *Value Type*: value type (only for role `Kennzahlen`) * *Aggregation*: aggregation operation (forbidden for role `Kennzahlen`, optional for all other roles) * *Formula*: a formula with which to calculate this element (only for role `Kennzahlen`, optional) * *Formula for Inner Nodes in other Dimensions*: an alternative formula to use if an element in another dimension is an inner node (only for role `Kennzahlen`, optional) On top of the given fixed set of reserved fields, for structure elements it is possible to model *custom attributes* for all structure elements. Custom attributes allow to present or even collect additional information on structure elements that do not make sense to be modeled as separate structures. As an example, a dimension modeling sales units might include name and telephone number of relevant contact persons. This information can be configured to be shown or even edited in forms in the QVANTUM Web application. Each structure is modeled as a [*forest*](https://en.wikipedia.org/wiki/Tree_$graph_theory$#Forest) of elements. There is a list of root elements which have an empty *Parent* field. Those elements will be displayed on the first level of the structure in the QVANTUM Web application. Every other element must have exactly one parent, i.e. it is not allowed for an element to have multiple parents. The order of the root elements and the order of all elements with the same parent is determined by the order in which they appear in the structure definition. For later upload via the QVANTUM Public API, structure definitions must again be provided in form of valid CSV files, as shown in the examples below. CSV headers are the same for most dimension roles. Only the role `Kennzahlen` for key figures is exceptional, as its structure definition requires an additional column `valuetype` and don't include the `aggregation` column. More examples of structure definitions are available from the example data package in folder `csv/metadata`. {% tabs %} {% tab title="Structure CSV (Non-Key Figure)" %} ```csv child;parent;label;description;input ACTUAL;;Actual;Scenario for actual figures.;no FORECAST;;Forecast;Scenario for forecast figures.;yes PLAN;;Plan;Scenario for plan figures.;yes ``` {% endtab %} {% tab title="Structure CSV (Key Figure)" %} ```csv child;parent;label;description;input;valuetype;formula;formulaForInnerNodes CST000;;All costs;;yes;Betrag;[CST010]+[CST020]+[CST030]+[CST040]; CST010;CST000;Staff;;yes;Betrag;; CST010P;CST000;Staff Percent;;yes;Prozentsatz;[CST010]/[CST000]*100; CST020;CST000;Rent;;yes;Betrag;; CST020P;CST000;Rent Percent;;yes;Prozentsatz;[CST020]/[CST000]*100; CST030;CST000;Energy;;yes;Betrag;; CST040;CST000;Other;;yes;Betrag;; CST050;CST000;External;;yes;Betrag;; CST051;CST050;Catering;;yes;Betrag;; CST052;CST050;Beverages;;yes;Betrag;; ``` {% endtab %} {% endtabs %} #### Input Allowed Use of the *Input Allowed* field determines if data input on a particular structure element is allowed (value `yes`) or not (value `no`). In general, for a given cube cell addressed by an n-dimensional vector of structure elements, input is allowed iff input is allowed for all structure elements. For dimensions with permissions, this general input allowed notion is additionally combined with user permissions defined for each structure element. However, use of the QVANTUM Public API always involves a user with role `central controller` and thus full permissions on all cube cells. Evaluation of the input allowed property on a cube cell will thus effectively not involve any user-related permission restrictions. The definition of input allowed does not automatically propagate upwards or downwards in the hierarchy, but must rather be explicitly defined for each structure element. #### Layer Names Often, the hierarchy of a structure consists of elements in related layers. With the column `layerName`, those layers can be named, such as in the following example: **Month Structure with Layer Names** ```csv child;parent;label;description;input;layerName Y;;Year;;yes;Year Q1;Y;First Quarter;;yes;Quarter Jan;Q1;January;;yes;Month Feb;Q1;February;;yes;Month Mar;Q1;March;;yes;Month Q2;Y;Second Quarter;;yes;Quarter Apr;Q2;April;;yes;Month May;Q2;May;;yes;Month Jun;Q2;June;;yes;Month ``` Here, the first/top layer only contains the year. The second layer consists of the quarters and the third/bottom layer contains all months. To avoid unnecessary repetition, not all elements within the same hierarchical layer need to define a layer name. For example, it would be enough to set the layer name for january, but not for the other months. However, if the layer name feature is used for a structure, every layer must have at least one element with a specified layer name. **Month Structure with Minimal Layer Names** ```csv child;parent;label;description;input;layerName Y;;Year;;yes;Year Q1;Y;First Quarter;;yes;Quarter Jan;Q1;January;;yes;Month Feb;Q1;February;;yes; Mar;Q1;March;;yes; Q2;Y;Second Quarter;;yes; Apr;Q2;April;;yes; May;Q2;May;;yes; Jun;Q2;June;;yes; ``` #### Value Types Use of the *Value Type* field is only defined for dimensions of role `Kennzahlen`. Currently, QVANTUM supports five value types: * `Betrag`: an amount of money * `Menge`: a quantity * `Preis`: a price * `Prozentsatz`: a percentage * `Bestand`: a stock (inventory) Key figures of value types `Betrag` and `Menge` are aggregated across dimensions. Key figures of value types `Preis`, `Prozentsatz` and `Bestand` are not aggregated across dimensions. For `Preis` and `Protzentsatz` this follows the rationale that aggregation in terms of summing usually does not make sense. For `Bestand` this may change in the future, for example to only disable aggregation in dimensions which are part of the time model. #### Aggregation Use of the *Aggregation* field determines an operation used for aggregation. This field is not defined for dimensions of role `Kennzahlen`. Besides simple storage of the data explicitly uploaded, QVANTUM performs data aggregation in the OLAP sense over structures in different dimensions of a multidimensional cube. Aggregation involves computing hierarchical data relationships over one or more dimensions. For example, summing up all costs over all cost centers for a specific year to get yearly total costs is an aggregation operation over two dimensions (costs and cost centers). If we additionally sum up total yearly costs over multiple years to receive total costs ever, we even involved a third dimension into aggregation. Currently, QVANTUM only supports the following values for aggregation operations: * `sum` (default): aggregation sums up values of all children of this element, if any. * `no aggregation`: aggregation is suppressed for this element. The aggregation column may be omitted, thus effectively using `sum` as default aggregation operation. Individual values for aggregation may also be omitted in the same sense that sum is accepted as default aggregation operation. If `sum` is considered as default aggregation operation for all structure elements, the whole aggregation column can be omitted. Aggregation rule `sum` or `no aggregation` defined on leaves is effectless per definition and can thus be omitted. Following these specifications, all data examples shown below are equivalent. {% tabs %} {% tab title="Explicit aggregation" %} ```csv child;parent;label;description;input;aggregation ROOT;;All costs;;yes;sum CHILD1;ROOT;Staff;;yes;sum CHILD2;ROOT;Energy;;yes;sum ``` {% endtab %} {% tab title="Aggregation values omitted, effectless no aggregation" %} ```csv child;parent;label;description;input;aggregation ROOT;;All costs;;yes; CHILD1;ROOT;Staff;;yes;no aggregation CHILD2;ROOT;Energy;;yes;sum ``` {% endtab %} {% tab title="Aggregation column omitted" %} ```csv child;parent;label;description;input ROOT;;All costs;;yes CHILD1;ROOT;Staff;;yes CHILD2;ROOT;Energy;;yes ``` {% endtab %} {% endtabs %} #### Key Figure Formulas For dimensions defined with the special dimension role `Kennzahlen` (key figures), QVANTUM supports the definition of *formulas* on key figure structure elements. Modeling formulas is supported with the use of two optional columns `formula` and `formulaForInnerNodes`, allowing formulas on key figures in their respective cells. A formula is expressed as a *formula string* supporting the following syntax constructs: * integers (e.g. `1`) or floats using decimal comma (e.g. `29,99`) * key figure references by business key in square brackets (e.g. `[CST000]`) * supported named constants, currently `BLANK` * signed expressions (e.g. `-[CST000]` or `-1,1`) * basic algebraic operators `+`, `-`, `*`, and `/` * comparison operators `>`, `>=`, `<`, `<=`, `=`, `!=` and `<>` * boolean negation `!` * boolean operators `&&` and `||` * supported functions (e.g. `abs([CST000])`) * round brackets (e.g. `-(1+2)`) * white space (e.g. `1 + 2` as equivalent to `1+2`) Supported functions: * `abs`: absolute value of argument (e.g. `abs([A])` evaluates to `2`, given value of `A` is `-2`) * `sign`: computes the sign of the given number (e.g. `sign(-42)` evaluates to `-1`, `sign(42)` to `1` and `sign(0)` to `0`) * `round`: rounded value of first argument (e.g. `round([A])` evaluates to `2`, given value of `A` is `1.52`), optionally controlling for rounding digits with second argument (e.g. `round([A]; -3)` evaluates to `1000` given value of `A` is `995`; `round([A]; 3)` evaluates to `9.556`, given value of `A` is `9.5557`). * `divide`: divides the first by the second value and selects an alternative in case of a division by zero. Per default, this alternative is an empty value but it can be specific as a third argument to the function. For example, `divide(6;2;42)` evaluates to `3`, `divide(6;[A])` to empty if `A` is empty or zero and `divide(6;[A];42)` to `42` if `A` is empty or zero. * `quotient`: evaluates to the integer result of the division without remainder. For example, `quotient(5;2)` and `quotient(-5;-2)` evaluate to `2`, `quotient(-5;2)` and `quotient(5;-2)` to `-2`. If the second argument is empty or zero a division by zero would be performed so the function evaluates to the invalid value. * `modulo`: evaluates to the remainder of the integer devision while always having the same sign as the second argument. For example, `modulo(5;3)` evaluates to `2`, `modulo(5;-3)` to `-1`, `modulo(-5;3)` to `1` and `modulo(-5;-3)` to `-2`. If the second argument is empty or zero a division by zero would be performed so the function evaluates to the invalid value. * `coalesce`: evaluates to the first non-empty argument. For example, if `A` is empty `coalesce([A], BLANK, 42, 5)` evaluates to `42`. * `minimum`: evaluates to the minimum of the given arguments. Empty arguments are ignored. If one of the arguments is invalid, the function evaluates to invalid. For example, `minimum(BLANK;42;2)` evaluates to `2` and `minimum(2;1/0)` to invalid. * `maximum`: evaluates to the maximum of the given arguments. Empty arguments are ignored. If one of the arguments is invalid, the function evaluates to invalid. For example, `maximum(BLANK;-42;-2)` evaluates to `-2` and `minimum(2;1/0)` to invalid. * `sumOfChildren`: evaluates to the sum of the children of the current element. If the element has no children, it evaluates to the empty value. If any of the children has an invalid value, the function evaluates to invalid. For example, if `A` has the children `B` and `C` with values `3` and `2`, `sumOfChildren()` evaluates to `5` for `A` and to the empty value for `C`. * `timeOffset`: takes the value of the referenced key figure from a previous element in the time model dimension. For example, if the time model dimension is the usual month dimension, and the cube contains a value `42.42` for key figure `A` in `JANUARY`, then a formula of `timeOffset([A];-1) + 1` for key figure `B would result in value` 43.42`for`B`in`FEBRUARY`. In contrast to every other place in formulas, the reference of a` timeOffset\` formula may be a self-reference. The second argument determines the relative element in the time dimension. It must be negative, i.e. only access "past" values, not "future" ones. * `if`: takes a boolean argument and two number arguments. If the boolean argument evaluates to `true`, the first number argument is returned, otherwise the second argument is returned. For example, `if(3 > 1; 4; 2)` evaluates to `4` and `if(3 < 1; 4; 2)` to `2`. * `isBlank`: evaluates whether the given argument is empty. For example, `isBlank(BLANK)` evaluates to `true` and `isBlank(2)` to `false`. * `isValid`: evaluates whether the given argument is a valid number (or blank). For example, `isValid(2)` and `isValid(BLANK)` evaluate to `true` and `isValid(1/0)` evaluates to `false` * `isTimeElementWithoutChildren`: returns `true` if the element in the time dimension of the cell to calculate has no children, i. e. if it is a leaf. For example, if `isTimeElementWithoutChildren()` is executed on a cell where the element in the time dimension is January in a standard month structure, it would return `true`. For the first quarter, `false` would be returned, since it has children (January, February and March). If no time dimension is specified, the function will always evaluate to `false`. The function is only allowed in formuals for inner nodes, as it would always return `true` in regular formulas. * `and`: function version of `&&`. For example, `and(1 > 0, 2 = 2)` evaluates to `true` and `and(1 > 0, 2 != 2)` to `false`. * `or`: function version of `||`. For example, `or(1 > 0, 2 != 2)` evaluates to `true` and `and(1 > 5, 2 != 2)` to `false`. * `not`: function version of `!`. For example, `not(1 > 0)` evaluates to `false` and `not(2 > 3)` to `true`. Given by key-figure-first calculation order, *regular formulas* from column `formula` are calculated first for all cube cells. Then, aggregation calculations take place for all non-key-figure dimensions. After all previous calculations have taken place, an optional further calculation may be modeled to take place for all cube cells involving a key figure structure element with an additional *formula for inner nodes* and an inner node in at least one non-key-figure dimension, effectively overwriting cell values produced in all previous calculations. Typical use cases for this additional formula are key figures, for which regular aggregations do not make sense (e.g. for key figures of value type price), but that still require reasonable cell values to be calculated on inner nodes. Consider the following simple example, involving two dimensions *Key Figures* and *Products* with definitions as specified below. **Key Figure Dimension** ```csv child;parent;label;input;valuetype;description;formula;formulaForInnerNodes UNITS;;Units Sold;yes;Menge;;; PRICE;;Price per Unit;yes;Preis;;;"round([SALES]/[UNITS]; 2)" SALES;;Sales;no;Betrag;;[UNITS]*[PRICE]; ``` **Product Dimension** ```csv child;parent;label;input;description;aggregation ALL;;All Products;no;;sum P1;ALL;Product 1;yes;; P2;ALL;Product 2;yes;; ``` Now consider that values for key figures *PRICE* and *UNITS* are entered by a user for the leaf product structure elements *P1* and *P2*, as indicated below. | | SALES | UNITS | PRICE | | --- | ----- | ----- | ----- | | ALL | | | | | P1 | | 10 | 3 | | P2 | | 5 | 2 | In a first calculation step, key figure formulas from colum `formula` are calculated for *P1* and *P2*, thus effectively adding cell values for key figure *SALES* on *P1* and *P2*, as indicated below. | | SALES | UNITS | PRICE | | --- | ----- | ----- | ----- | | ALL | | | | | P1 | 30 | 10 | 3 | | P2 | 10 | 5 | 2 | In the next calculation step, aggregation takes place in the *Product* dimension. Effectively, this calculation adds key figure values for root element *ALL*. Note that key figure *PRICE* is not aggregated due to its value type, thus leaving the corresponding cell empty. | | SALES | UNITS | PRICE | | --- | ----- | ----- | ----- | | ALL | 40 | 15 | | | P1 | 30 | 10 | 3 | | P2 | 10 | 5 | 2 | In a final step, all formulas from column `formulaForInnerNodes` are calculated for inner nodes in all non-key-figure dimensions, in this example in the product dimension. Given the aggregated values for *SALES* and *UNITS*, the specified formula for inner nodes for key figure *PRICE* effectively calculates an average product price, weighted over the units sold per product, rounded to two decimal places, as indicated below. | | SALES | UNITS | PRICE | | --- | ----- | ----- | ----- | | ALL | 40 | 15 | 2.67 | | P1 | 30 | 10 | 3 | | P2 | 10 | 5 | 2 | The calculation of formulas takes place upon any operation effectively changing the planning data persisted within the context of a plan. Regular formulas are calculated according to the given calculation order. Formulas for inner nodes are always calculated after regular calculations over all dimensions. {% hint style="warning" %} With the given syntax, it is possible to define constant formulas, i.e. formulas without references to other key figures (e.g. `10` or `-(20+40)`) QVANTUM explicitly forbids the use of constant formulas. Any upload of a planning model defining constant formulas will thus fail. {% endhint %} {% hint style="warning" %} The definition of a formula system, i.e. a set of multiple formulas, entails the risk of modeling *cyclic dependencies* between formulas. Note that the two different formula columns `formula` and `formulaForInnerNodes` define separate formula systems. The most trivial example possible is shown in the example below for regular formulas (`A=B` and `B=A`). With cyclic dependencies it is impossible to perform formula calculation. Thus, any upload of a planning model defining a formula system involving cyclic dependencies will fail with an error message providing a hint on all detected cycles. {% endhint %} **Formula system with trivial cyclic dependency** ```csv child;parent;label;description;input;valuetype;formula;formulaForInnerNodes A;;Element A;;yes;Betrag;[B]; B;;Element B;;yes;Betrag;[A]; ``` #### Custom Attributes Custom attributes are modeled in the context of structure elements. As such, all structure elements of the same structure carry the same list of custom attributes. Each custom attribute defines a *key* unique among the custom attributes of the same dimension, a string *value*, and an optional *input allowed configuration* whether the value of the given attribute may be edited. As such, a custom attribute is modeled as two additional columns: a value column defining the attribute key in the header and an input allowed column for defining the input allowed property of the given attribute for a given structure element. Custom attribute list order is given with the order of appearance of the respective value columns. The syntax for column headers is given as * `` : string business key; must not exceed a maximum length 255 characters, must not contain square brackets, names of reserved fields must not be used as key. * `[ - input]` : input allowed column for the attribute; column may be omitted. The value of a custom attribute must not exceed a maximum length of 1024 characters. The input allowed property of a custom attribute can be defined as allowed (value `yes`) or not (value `no`). If no value is given, the property is interpreted as `no`. If the column is omitted, `no` is assumed for all structure elements. The following example of a planning unit structure defines a custom attribute "Representative". While some names for representatives of a planning unit are included with input allowed set to `no`, others are to be collected, thus modeled with input allowed set to `yes`. **Structure with Custom Attribute** ```csv child;parent;label;description;input;aggregation;Representative;[Representative - input] CCT000;;All Cost Centers;;yes;sum;Cevin Costner;no CCT010;CCT000;Sales;;yes;sum;Sally Sales;no CCT020;CCT000;Administration;;yes;sum;;yes CCT021;CCT020;General Administration;;yes;sum;;yes CCT022;CCT020;IT Administration;;yes;sum;Irvin Tecnic;no ``` ## Upload planning model A valid planning model definition consists of one top-level planning model definition CSV file and a set of *n* structure definition CSV files, with *n* being the number of dimensions defined. With a complete and valid set of definition files at hand, a planning model definition can be uploaded to QVANTUM in one single asynchronous API call with its result enabling status polling afterwards. {% hint style="warning" %} With a successful upload of a new planning model definition, any previously existing planning model including all forms, all data and all users will effectively be lost in favor of a new planning model. However, updating an existing planning model definition is supported, as described in [upload full model update](#upload-full-model-update). {% endhint %} The example data bundled with this tutorial consists of several CSV files, one for the top-level planning model definition and one for each of the involved dimensions. In the following request example, we assume an environment variable `MODEL_UPLOAD_URL` to hold the URL for uploading a planning model (cf. Section [Navigating to a plan](/dev/general-information#navigating-to-a-plan)). ### Asynchronous upload Technically, a planning model definition upload is formulated as a multipart request with some parts being defined as key-value pairs (`cubeKey` and `cubeLabel`) and the remaining parts being defined as files. The file parts relate to all files in a complete and valid planning model definition. The top-level planning model definition file must be configured for part `planning-model`. Each dimension is configured for the part according to the `number` column value, specified in the planning model top-level definition file, e.g. `1` for the costs dimension or `3` for the scenarios dimension. Each uploaded file allows to further specify the used charset with an additional parameter: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. {% tabs %} {% tab title="Upload Planning Model Definition" %} ```sh MODEL_META_PATH=/absolute/path/to/tutorial/data/csv/metadata PLANNING_MODEL_PATH=${MODEL_META_PATH}/planning-model.csv DIM_COSTS_PATH=${MODEL_META_PATH}/1.csv DIM_COST_CENTERS_PATH=${MODEL_META_PATH}/2.csv DIM_SCENARIOS_PATH=${MODEL_META_PATH}/3.csv curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:multipart/form-data" \ --form "cubeKey=1" \ --form "cubeLabel=Cube" \ --form "planning-model=@${PLANNING_MODEL_PATH};type=text/csv" \ --form "1=@${DIM_COSTS_PATH};type=text/csv" \ --form "2=@${DIM_COST_CENTERS_PATH};type=text/csv" \ --form "3=@${DIM_SCENARIOS_PATH};type=text/csv" \ "${MODEL_UPLOAD_LINK}" ``` {% endtab %} {% tab title="Upload Planning Model Definition with Explicit Charsets" %} ```sh MODEL_META_PATH=/absolute/path/to/tutorial/data/csv/metadata PLANNING_MODEL_PATH=${MODEL_META_PATH}/planning-model.csv DIM_COSTS_PATH=${MODEL_META_PATH}/1.csv DIM_COST_CENTERS_PATH=${MODEL_META_PATH}/2.csv DIM_SCENARIOS_PATH=${MODEL_META_PATH}/3.csv curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:multipart/form-data" \ --form "cubeKey=1" \ --form "cubeLabel=Cube" \ --form "planning-model=@${PLANNING_MODEL_PATH};type=text/csv;charset=UTF-16" \ --form "1=@${DIM_COSTS_PATH};type=text/csv" \ --form "2=@${DIM_COST_CENTERS_PATH};type=text/csv;charset=UTF-16" \ --form "3=@${DIM_SCENARIOS_PATH};type=text/csv" \ "${MODEL_UPLOAD_LINK}" ``` {% endtab %} {% endtabs %} Uploading a planning model definition with the above request is asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the `Location` header. In the next step, repeated status polling allows to monitor the status of planning model definition processing on QVANTUM side. The returned URL leads to an upload history entry resource. {% hint style="info" %} It might be tempting to misinterpret a successful response to the above upload request as successful processing of a planning model definition. Actual information on processing status and result is only available via status polling (cf. next section)! {% endhint %} ### Upload status polling Status polling should be done repeatedly to the same upload history entry resource URL, as demonstrated below. **Status Polling** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${UPLOAD_LINK}" ``` The response payload includes a JSON representation of a history entry resource with the following information fields: * `id`: identifier of current history entry * `userId`: subject identifier of uploading user * `cubeKey`: key of cube context * `uploadStarted`: UTC time of starting the upload on client side * `processingStarted`: UTC time of starting upload processing on QVANTUM side * `processingEnd`: UTC time of ending upload processing on QVANTUM side * `status`: current processing status with one of the following fixed values * `PROCESSING` : processing still ongoing * `COMPLETED`: processing complete * `PROCESSING_FAILED`: processing failed, usually due to passing invalid CSV files * `result`: current processing result with fixed value * `NOT_MODIFIED`: current planning model remains unmodified * `COMPLETE`: planning model definition completed successfully The example payloads below demonstrate status information for different situations, i.e. processing is still ongoing, processing completed successfully, and processing failed. In the case processing failed, the response payload includes embedded log entries containing error messages. These log entries are available in [different languages](/dev/general-information#localization). {% tabs %} {% tab title="Status Information - Processing" %} ```json { "id": 1, "userId": "dad642e5-aec5-4096-a9e3-008d8eff496b", "cubeKey": "1", "uploadStarted": "2019-08-22T08:55:47.805612Z", "processingStarted": "2019-08-22T08:55:47.999988Z", "processingEnd": null, "status": "PROCESSING", "result": "NOT_MODIFIED", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/uploads/1" } }, "_embedded": { "logEntries": [] } } ``` {% endtab %} {% tab title="Status Information - Complete" %} ```json { "id": 1, "userId": "dad642e5-aec5-4096-a9e3-008d8eff496b", "cubeKey": "1", "uploadStarted": "2019-08-22T08:55:47.805612Z", "processingStarted": "2019-08-22T08:55:47.999988Z", "processingEnd": "2019-08-22T08:55:49.691576Z", "status": "COMPLETED", "result": "CREATED", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/uploads/1" } }, "_embedded": { "logEntries": [] } } ``` {% endtab %} {% tab title="Status Information - Failed" %} ```json { "id": 1, "userId": "dad642e5-aec5-4096-a9e3-008d8eff496b", "cubeKey": "1", "uploadStarted": "2019-08-22T08:55:47.805612Z", "processingStarted": "2019-08-22T08:55:47.999988Z", "processingEnd": "2019-08-22T08:55:49.691576Z", "status": "PROCESSING_FAILED", "result": "NOT_MODIFIED", "_links":{ "self":{ "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/uploads/1" } }, "_embedded": { "logEntries": [ { "timeStamp": "2019-08-22T08:55:48.691576Z", "logLevel": "ERROR", "description": "No reader for 4. Have: [1, 2, 3, planning-model]" } ] } } ``` {% endtab %} {% endtabs %} ## Updating Planning Models Most planning processes require in-process updates of the planning model. Among the most common use cases are adding new elements or whole sub-structures into a structure (e.g. for a newly developed sales region with new branch offices), removing elements or substructures (e.g. after phase-out of a legacy product group), or moving elements or substructures to other places in an existing structure (e.g. reorganization of responsibilities in planning team hierarchies). After such updates, already gathered planning data must be re-organized and re-calculated to guarantee data consistency. For such situations, the QVANTUM Public API supports *single dimension updates* and *full model updates*. A single dimension update affects the underlying structure of a single dimension and triggers automatic re-organization and re-aggregation of cube cell data upon completion. A full model update allows to execute multiple single dimension updates in a batch and additionally changes in the overarching planning model. {% hint style="info" %} Dimension updates in turn have further implications. These implications should be well-known to API client developers and are thus documented in the next section as primer to the actual execution of dimension updates. {% endhint %} ### Implications of dimension updates Dimension updates can be understood as combinations of changes on the underlying structure of the dimension. Typical operations are *adding*, *deleting*, *modifying* and *moving* structure elements. While some operations typically have less critical or no further implications (e.g. adding or modifying), other operations (e.g. deleting or moving) have quite intense implications (e.g. loss of planning data, loss of user access, form invalidation). #### Implications of structure element addition **Loss of cell data**: If a dimension element is added as new leaf under an existing leaf, all cell data related to the existing leaf is lost. #### Implications of structure element deletion **Loss of cell data**: If a dimension element is deleted, all data cells involving this particular element are deleted as well. **Loss of access rights**: In particular for the planning unit dimension within a planning application (cf. [planning model definition](#planning-model-definition)), removal of elements can also cause partial or even complete loss of access rights for users assigned to these elements (cf. [define team](https://tn-gitlab-ci.buhl.de/tn-documentation/qvantum-public-docs/-/tree/master/dev/team.md#define-team)). In extreme cases, users can lose all access rights and are thus effectively removed from a plan. Consider the following simple example of a hierarchical planning region structure. {% tabs %} {% tab title="Simple Planning Region Structure" %} ``` * All regions * Europe * Germany * Austria * Switzerland * Asia ``` {% endtab %} {% tab title="Updated Structure (no Germany)" %} ```diff * All regions * Europe - * Germany * Austria * Switzerland * Asia ``` {% endtab %} {% tab title="Updated Structure (no Europe)" %} ```diff * All regions - * Europe - * Germany - * Austria - * Switzerland * Asia ``` {% endtab %} {% endtabs %} Furthermore assume that a decentral planner was assigned planning responsibility for Europe. Again, if we remove the element `Germany`, then this element is removed, including all related cell data. Additionally, the planner will effectively lose responsibility for Germany, but still remain responsible for Austria and Switzerland. If we remove the element `Europe`, along with its children, the planner loses all access rights and will effectively not be able to participate in the planning application anymore. **Change/invalidation of forms**: Dimension elements and their structural properties can play substantial roles in form definitions in QVANTUM. Removal of dimension elements involved in form definitions may cause form changes, i.e. form rows or columns disappear or previously selected form header elements are replaced with still existing elements. In extreme cases, whole forms can become invalid and thus unusable. #### Implications of structure element moves **Loss/gain of access rights**: in the same manner as for element deletion, moving elements can cause partial loss of access rights for decentral planners. Element move operations can also cause a gain of access rights for decentral planners. Consider the following simple example of a planning unit structure. {% tabs %} {% tab title="Simple Planning Unit Structure" %} ``` * Electronics * Smartphones * Tablets * Child Tablets * Toys * Puppets * Superhero Figurines ``` {% endtab %} {% tab title="Updated Structure" %} ```diff * Electronics * Smartphones * Tablets - * Child Tablets * Toys * Puppets * Superhero Figurines + * Child Tablets ``` {% endtab %} {% endtabs %} Furthermore assume that there are two decentral planners Alice and Bob, Alice responsible for electronics, Bob for toys. A move from tablets for children into the toys segment effectively causes a gain of access rights for Bob and a loss of access rights for Alice. **Change/loss of data**: in the same manner as for element deletion, moving elements can cause loss of data in cases where previous leaf elements become inner elements, because other elements or even subtrees were appended in the context of a move operation. If the new leaves did not contain data before, data in the now inner element is lost. If the new leaves did contain data, data in the now inner element is replaced by new calculation results. In general, QVANTUM makes best efforts to keep existing data where reasonable. ### Upload single structure update A structure update as such consists of the upload of an updated single structure definition in the form of a CSV file (cf.[structure definition](#structure-definitions)) or in form of a JSON-Representation. A valid structure can be uploaded to QVANTUM in one single asynchronous API call with its result enabling status polling afterwards. #### Asynchronous upload The update of a structure requires prior navigation to the structure of the dimension to be updated (cf. [navigating to a structure](/dev/general-information#navigating-to-a-structure)). In both cases the link to the update URL is given in the scope of a structure resource: ```sh # link to structure update URL in scope of structure resource STRUCTURE_UPLOAD_URL=$(curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${STRUCTURE_LINK}" | jq --raw-output ._links.upload.href) ``` #### Uploading a structure with a CSV file The upload of a single structure CSV file is a single request with the MIME type `application/x.de.qvantum-plan.aspect-with-structure`. Optionally, the format of the CSV file can be specified: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. {% tabs %} {% tab title="Upload Structure Update" %} ```sh CSVFILE="/path/to/dimension-update.csv" HISTORY_ENTRY_URL=$(curl --silent --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.aspect-with-structure" \ --data-binary "@${CSVFILE}" \ "${STRUCTURE_UPLOAD_LINK}" ``` {% endtab %} {% tab title="Upload Structure Update - Explicit Charset" %} ```sh CSVFILE="/path/to/dimension-update.csv" HISTORY_ENTRY_URL=$(curl --silent --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.aspect-with-structure;charset=UTF-16" \ --data-binary "@${CSVFILE}" \ "${STRUCTURE_UPLOAD_LINK}" ``` {% endtab %} {% endtabs %} #### Uploading a structure with a JSON representation The following representations describe the payload for a JSON structure upload. 1. The structure representation ```json { "businessKey": "structure", "displayName": "structureDisplayName", "type": "KEY_FIGURES | STANDARD", "layers" : [, ... , ], "customAttributes" : [, ... , ], "rootElements": [, ... , ] } ``` 2. The hierarchy layer definition (optional within the structure representation) : ```json { "businessKey": "layer name" } ``` 3. The custom attribute definition (optional within the structure representation) : ```json { "businessKey": "custom attribute name" } ``` 4. The structure representation contains a list of element definitions (one for every root node in the structure) : ```json { "businessKey" : "businessKey", "displayName" : "displayName", "description" : "description", "inputAllowed" : "MAYBE", "aggregationRule" : "SUM", "valueTypeReference": { "businessKey" : "valueType" }, "customAttributes" : [, ... ], "children : [, ..., ] } ``` 'businessKey', 'displayName' and 'inputAllowed' are mandatory properties. The other properties are optional depending on the structure type. 'children' and 'customAttributes' may be omitted if no children or custom attributes exist. 5. The custom attribute definition for structure elements (optional within a element representation): ```json { "customAttributeReference" : { "businessKey" : "attribute name in structure definition" }, "value" : "attribute value", "inputAllowed" : "MAYBE" } ``` 'value' and 'inputAllowed' are optional properties here. ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.external-structure+json" \ --data @/absolute/path/to/structure.json \ "${STRUCTURE_UPLOAD_LINK}" ``` Uploading structure updates with one of the above requests is asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the `Location` header. Polling for status updates works like for the [initial model upload](#upload-status-polling) ### Upload more than one structure An upload of more than one structure is quite similar to the asynchronous update of one structure with a JSON representation as described [above](#uploading-a-structure-with-a-json-representation). The link to the update URL is given in the scope of the [underlying plan resource](/dev/general-information#plan-json-representation): ```sh # link to structure update URL in scope of a plan resource STRUCTURES_UPLOAD_LINK=$(curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${PLAN_LINK}" | jq --raw-output ._links.structuresUploads.href) ``` The structures representation: ```json { "structures": [ ..., ] } ``` The structure definition is described in the chapter above. The upload can be performed with the following curl-statement: ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.external-structures+json" \ --data @/absolute/path/to/structures.json \ "${STRUCTURES_UPLOAD_LINK}" ``` ### Upload full model update A full model update consists of the upload of an updated full planning model definition as described in [planning model definition](#planning-model-definition). Given by the observation that some partial update operations factually create new models instead of changing existing ones and internal technical limitations, some update operations are not supported: * adding new/removing existing dimensions * changes of dimension roles, except for "Zeit" * changes in dimension singular/plural labels #### Asynchronous upload Technically, a planning model update upload is formulated in the same way as a model definition upload with the upload URL being the only difference. While a planning model definition upload is done in the scope of a plan, in which a cube must first be defined, a planning model update is done in the scope of a cube. The particular upload URL is available in the link section of a cube resource (cf. [navigating to a cube](/dev/general-information#navigating-to-a-cube)). As for planning model definitions, each uploaded file allows to further specify the used charset with an additional parameter: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. {% tabs %} {% tab title="Upload Planning Model Update" %} ```sh # link to model update URL in scope of cube resource MODEL_UPDATE_URL=$(curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_LINK}" | jq --raw-output ._links.modelUploads.href)`` # variable definitions analogous to planning model definition curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:multipart/form-data" \ --form "cubeKey=1" \ --form "cubeLabel=Cube" \ --form "planning-model=@${PLANNING_MODEL_PATH};type=text/csv" \ --form "1=@${DIM_COSTS_PATH};type=text/csv" \ --form "2=@${DIM_COST_CENTERS_PATH};type=text/csv" \ --form "3=@${DIM_SCENARIOS_PATH};type=text/csv" \ "${MODEL_UPDATE_LINK}" ``` {% endtab %} {% tab title="Upload Planning Model Update - Explicit Charsets" %} ```sh # link to model update URL in scope of cube resource MODEL_UPDATE_URL=$(curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_URL}" | jq --raw-output ._links.modelUploads.href)`` # variable definitions analogous to planning model definition curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:multipart/form-data" \ --form "cubeKey=1" \ --form "cubeLabel=Cube" \ --form "planning-model=@${PLANNING_MODEL_PATH};type=text/csv;charset=UTF-16" \ --form "1=@${DIM_COSTS_PATH};type=text/csv" \ --form "2=@${DIM_COST_CENTERS_PATH};type=text/csv;charset=UTF-16" \ --form "3=@${DIM_SCENARIOS_PATH};type=text/csv" \ "${MODEL_UPDATE_LINK}" ``` {% endtab %} {% endtabs %} Uploading a planning model update with the above request is again asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the `Location` header. In the next step, repeated status polling allows to monitor the status of planning model definition processing on QVANTUM side. In error cases, error messages are included in the corresponding history entry payloads. ## Exporting Planning Models Once a planning model has been defined in the context of a plan (cf. [planning model definition](#planning-model-definition)), it is possible to export individual structures or the complete model. ### Structure Export Individual structures can be exported as a CSV file or as a JSON representation with a single API request to the structure resource (cf. [navigating to a structure](/dev/general-information#navigating-to-a-structure)). The accept header must be set to `application/x.de.qvantum-plan.aspect-with-structure` and supports the following (optional) parameter: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. {% tabs %} {% tab title="Structure Export (CSV with Windows-1252 encoding)" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.aspect-with-structure;charset=Windows-1252" \ --output structure.csv \ "${STRUCTURE_LINK}" ``` {% endtab %} {% tab title="Structure Export (JSON)" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.external-structure+json" \ "${STRUCTURE_LINK}" ``` {% endtab %} {% endtabs %} The result of this request is the same structure representation as described in the structure upload (cf. [uploading a structure with a JSON representation](#uploading-a-structure-with-a-json-representation)). ### Export all Structures All structures in a plan can be exported with this single API request to the allStructes resource (cf. [navigating to all structures](/dev/general-information#navigating-to-all-structures)): ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.external-structures+json" \ "${ALL_STRUCTUREs_LINK}" ``` The result of this request is a JSON representation as described in the chapter (cf. [upload more than one structure](#upload-more-than-one-structure)). ### Full Model Export The complete model can be exported in two different formats, i.e. as an Excel file or as a ZIP-archived collection of CSV files. {% hint style="info" %} The export of a planning model only includes a [planning model definition](#planning-model-definition). Definitions of forms or planning teams are explicitly not included. {% endhint %} A planning model export is done with a single API request to the cube resource. The export format is controlled with the specification of an `Accept` header, as demonstrated in the requests below. {% tabs %} {% tab title="Planning Model Export (zipped CSV)" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/zip" \ --output model.zip \ "${CUBE_LINK}" ``` {% endtab %} {% tab title="Planning Model Export (Excel)" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \ --output model.xlsx \ "${CUBE_LINK}" ``` {% endtab %} {% endtabs %} # Key Figures As described in the section about [key figure formulas](/dev/model#key-figure-formulas), one of the main differences of key figure structures compared to other structures is the definition of formulas. To be able to support more complex formula systems, the definition of formulas will be separated from the model definition. This section describes the separate initial upload, update and export of these key figure formulas. ## Structure Key figures uploads and exports have the same structure and are specified in JSON. **Key Figures Definition** ```json { "rootCubeSegment": { "formulas": [ , ... ], "segmentation": } } ``` On the top level, the definition includes the `rootCubeSegment` property with the following nested properties: * `formulas`: Contains the formulas defined for the root cube segment. Key figures not present in `formulas` have no formula. The property is not optional but it may be empty. The order of the entries is not relevant. * `segmentation`: a division of the root segment into smaller segments along a dimension. This property is optional. ### Key Figure Formulas Definition One `KEY_FIGURE_FORMULAS_DEFINITION` defines the two formulas to be used for a single key figure. **Key Figure Formulas Definition** ```json { "keyFigureReference": { "businessKey": "CST010P" }, "formulaForLeavesInAllOtherDimensions": , "formulaForInnerNodeInAtLeastOneOtherDimension": } ``` All properties must always be present. * `keyFigureReference.businessKey`: the business key of the key figure for which the formulas are given * `formulaForLeavesInAllOtherDimensions`: the formula to use for calculations of cells where the elements in all other dimensions are leaves in their hierarchy. This is the equivalent of the `formula` column in the key figure structure definition (cf. [key figure formulas](/dev/model#key-figure-formulas)). * `formulaForInnerNodeInAtLeastOneOtherDimension`: the formula to use for calculations of cells where at least one element in another dimension is an inner node in its hierarchy. This is the equivalent of the `formulaForInnerNodes` column in the key figure structure definition (cf. [key figure formulas](/dev/model#key-figure-formulas)). ### Formula Definition There are three possible definitions for a formula. **No Formula Definition** ```json { "type": "NONE" } ``` If the formula should not be calculated, only the `type` property must be present and set to `NONE`. **String Formula Definition** ```json { "type": "DEFINED", "formula": "[CST010]/[CST000]*100" } ``` If the formula should be calculated, the `type` property must be set to `DEFINED` and the `formula` property must contain a non-blank formula string. This formula string can use the same constructs as previously shown for the [key figure structure definition](/dev/model#key-figure-formulas). **Inherited Formula Definition** ```json { "type": "INHERITED" } ``` If the formula definition of the parent segment should be used, only the `type` property must be present with a value of `INHERITED`. This is not allowed in the root cube segment, since it has no parent segment. ### Segmentation Definition A `SEGMENTATION_DEFINITION` defines how a cube segment is further divided into multiple child segments. **Segmentation Definition** ```json { "dimensionReference": { "pluralName": "Cost Centers" }, "children": [ , ... ], "remainder": } ``` All properties must always be present: * `dimensionReference`: a reference (by plural name) to the dimension along which the "parent" segment is divided into smaller segments. May not reference the key figure or time dimension. * `children`: an ordered list of child segments, each responsible for some trees in the dimension. May be empty. * `remainder`: a non-optional segment for all elements whose roots were not explicitly included in any of the child segments. ### Child Cube Segment A `CHILD_CUBE_SEGMENT_DEFINITION` defines a cube segment for some trees in a dimension. **Child Cube Segment Definition** ```json { "structureElementReferences": [ { "businessKey": "CCT000" }, ... ], "displayName": "a descriptive display name", "formulas": [ , ... ], "segmentation": } ``` All properties are required * `structureElementReferences`: references (by business key) to roots of the segmented dimension. All elements inside the trees under the roots are in this segment. May be empty. * `displayName`: a descriptive name for the segment to be displayed in the application * `formulas`: the formulas for this segment. Key figures which are not listed will behave as if they have the type INHERITED for both formulas. * `segmentation`: a further segmentation of this child segment according to a different dimension ### Remainder Cube Segment A `REMAINDER_CUBE_SEGMENT_DEFINITION` defines a cube segment for all elements in a dimension that were not explicitly assigned to other child cube segments. **Remainder Cube Segment Definition** ```json { "displayName": "a descriptive display name", "formulas": [ , ... ], "segmentation": } ``` The properties are the same as in the child cube segment, except for the missing `structureElementReferences` property since the structure elements in the remainder are implicitly defined by the other child cube segments in the segmentation. ## Upload A key figures upload works similar to an [asynchronous model upload](/dev/model#asynchronous-upload). However, for the key figures uploads, we do not employ multipart uploads, but rather use the content type `application/x.de.qvantum-plan.external-key-figures+json` to upload a single file. New uploads can be created at the `keyFiguresUploads` link in the cube resource (cf. [navigating to a cube](/dev/general-information#navigating-to-a-cube)). **Upload Key Figures** ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.external-key-figures+json" \ --data @/absolute/path/to/key-figures.json \ "${KEY_FIGURES_UPLOADS_LINK}" ``` The response contains a URL in the `Location` header. This URL can be used for [status polling](/dev/model#upload-status-polling). ## Export An export of the current key figures is available at the endpoint specified by the `keyFigures` link in the cube resource (cf. [navigating to a cube](/dev/general-information#navigating-to-a-cube)). **Export Key Figures** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.external-key-figures+json" \ "${KEY_FIGURES_LINK}" ``` # Handling Cell Data With a successfully uploaded planning model definition, a plan consists of a cube with all data cells being empty. In most cases, planners will require initial information as reference for their planning tasks. For example, planning the costs for the next year would usually require information about the planned costs for the rest of the current year (forecast) and actual costs of previous years. Thus, the empty cube should be prefilled with initial data, relevant for this particular plan. The compilation of such initial data is a substantial part of plan preparation. Additionally, export of planned data for further processing is often necessary. The next sections describe how operations for handling data can be performed with the QVANTUM public API. ## Compile Initial Data For later upload of initial data into a plan, it must be guaranteed that the uploaded data is compliant with the previously uploaded planning model definition. For this purpose, the QVANTUM Public API provides an endpoint for downloading a data template CSV with a structure compliant with the dimension definitions of the planning model. Afterwards, this data template must be prefilled with data vectors, compliant with the structure element definitions for the particular dimensions. This prefilling is usually the result of upstream [ETL](https://en.wikipedia.org/wiki/Extract,_transform,_load) processes. ### Download Data Template The endpoint for downloading a data template is available from the links section in a cube resource representation (cf. [Navigating to a cube](/dev/general-information#navigating-to-a-cube)). **Download Cube Data Template** ```sh curl --show-headers --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_TEMPLATE_LINK}" ``` ### Fill Data Template For the example planning model definition of this tutorial, the following excerpt from a valid sample initial data CSV file shows initial data for cost center `CCT020` (Administration). In particular, it includes actual and forecast costs for both staff costs (cost `CST010`) and energy costs (cost `CST030`). While staff costs went up from 50000.00$ (actual) to 60000.00$ (forecast), energy costs went down from 300.00$ (actual) to 250.99$ (forecast). **Sample Cube Data File** ```csv Cost;Cost Center;Scenario;Wert CST010;CCT020;ACTUAL;50000.00 CST030;CCT020;ACTUAL;300.00 CST010;CCT020;FORECAST;60000.00 CST030;CCT020;FORECAST;250.99 ``` ## Upload Initial Data With a valid cube cell data file at hand, initial data can be uploaded to QVANTUM in one single asynchronous API call with its result enabling status polling afterwards. Unlike in previous requests, the request must specify a MIME type of `application/x.de.qvantum-plan.cube-cell-data`. Two parameters allow to further specify the format of the uploaded file: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. * `decimalSeparator`: the character used as decimal separator in numeric values. May be explicitly specified as hexadecimal character code (e.g. `decimalSeparator=0x2c`) or as character in double quotes (e.g. `decimalSeparator=",")`. If omitted, defaults to dot character (`.`). {% hint style="warning" %} Cell data files involving mixed use of different decimal separators are considered invalid and will thus lead to failure upon upload. {% endhint %} {% tabs %} {% tab title="Default Cell Data Upload" %} ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.cube-cell-data" \ --data-binary "@${CUBE_DATA_PATH}" \ "${CUBE_DATA_UPLOADS_LINK}" ``` {% endtab %} {% tab title="Explicit Decimal Separator and Charset" %} ```sh curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:application/x.de.qvantum-plan.cube-cell-data;decimalSeparator=0x2c;charset=UTF-16" \ --data-binary "@${CUBE_DATA_PATH}" \ "${CUBE_DATA_UPLOADS_LINK}" ``` {% endtab %} {% endtabs %} Uploading cube cell data with one of the above requests is asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the `Location` header. In the next step, repeated status polling in possible as described for the model upload (cf. [Upload Status Polling](/dev/model#upload-status-polling)). Two additional fields are available for progress tracking: * `importProgress`: data import progress percentage (0 <= x <= 1). * `aggregateProgress`: data aggregation progress percentage (0 <= x <= 1). ## Deleting Planning Data During a planning process it might be useful to delete specific data in a plan. A reasonable request might be: delete all forecast data in the year 2023. {% hint style="info" %} Data can only be deleted, when the underlying plan is not running, i. e. it is either paused or ended. {% endhint %} Data deletion is possible using an asynchronous request to the `dataDeletions` link in a cube. The API will immediately send a response including a status polling URL in the `Location` header (cf. [Upload Status Polling](/dev/model#upload-status-polling)). **Default Data Deletion** ```sh curl --request POST \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_DATA_DELETIONS_LINK}" ``` {% hint style="info" %} It should be noted that with a default data deletion request like the above, all data in the cube will be deleted. This default behavior can be overridden with a set of filters, as described in the section [filtering planning data](#filtering-data). {% endhint %} ## Exporting Planning Data With the availability of data collected from user inputs in the context of a given plan, the export of the collected data becomes reasonable, either during a planning process for a preview or at the end for report generation. A default data export is possible with a single API request to the export link under a cube resource. The value for the variable `CUBE_CELLDATA_EXPORT_LINK` is retrieved by navigation to a cube resource, following its link `data`. In order to retrieve cube cell data, request header `Accept` must be set to the custom MIME type `application/x.de.qvantum-plan.cube-cell-data`. Two further parameters allow to configure the export format: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. * `decimalSeparator`: the character used as decimal separator in numeric values. May be explicitly specified as hexadecimal character code (e.g. `decimalSeparator=0x2c`) or as character in double quotes (e.g. `decimalSeparator=",")`. If omitted, defaults to dot character (`.`). {% tabs %} {% tab title="Default Data Export" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.cube-cell-data" \ "${CUBE_CELLDATA_EXPORT_LINK}" ``` {% endtab %} {% tab title="Charset UTF-16 and Decimal Separator ','" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.cube-cell-data;charset=UTF-16;decimalSeparator=\",\"" \ "${CUBE_CELLDATA_EXPORT_LINK}" ``` {% endtab %} {% endtabs %} In response to this request, cell data is downloaded in CSV format. {% hint style="info" %} It should be noted that with a default data export request like the above, all data of the cube will be exported. This default behavior can be overridden with a set of filters, as described in the section [filtering planning data](#filtering-data). {% endhint %} ## Filtering Data Data export and deletion of data can be further refined by specifying combinations of different types of *filters*. All filter types are expressed as additional query parameters, added to the cube data cell URL used for default data exports or deletions. In the following sections, these filter types are explained in detail. ### Filtering by Input Allowed Filtering by the input allowed property allows to either export data for *all* cube cells or only for those cube cells whose effective input allowed property evaluates to true (cf. [Input Allowed](/dev/model#input-allowed)) An input allowed filter can be expressed as request parameter `inputAllowedFilter` with one of the following values: * `ONLY_INPUT_ALLOWED`: only cube cells with effective input allowed true (default) * `ALL`: all cube cells The example request below exports / deletes only those cube cells, where input is allowed, thus overriding the default behavior that all cells are exported resp. deleted. {% tabs %} {% tab title="Data Export With Input Allowed Filter" %} ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.cube-cell-data" \ "${CUBE_CELLDATA_LINK}?inputAllowedFilter=ONLY_INPUT_ALLOWED" ``` {% endtab %} {% tab title="Deletion of Data With Input Allowed Filter" %} ```sh curl --request DELETE \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_CELLDATA_LINK}?inputAllowedFilter=ONLY_INPUT_ALLOWED" ``` {% endtab %} {% endtabs %} ### Filtering by Dimension Restrictions {% hint style="warning" %} Currently, the QVANTUM Public API does not support retrieval of information on structures or structure elements. Thus, this filtering feature is only usable, if the user has access to the full planning model definition. {% endhint %} Filtering by dimension restrictions allows to export or delete data based on restrictions for individual dimensions (cf. [Combining Multiple Dimension Restrictions](#combining-multiple-dimension-restrictions) for how several restrictions combine). The following four types of dimension restrictions are available, each defining a different set of elements to include. #### SINGLE Restricts a dimension to **exactly one element**. Only cell data for the specified element is included; no descendant elements are matched. ```json { "dimensionKey" : "", "type" : "SINGLE", "structureElementKey" : "" } ``` * `DIMENSION_KEY`: the plural label of the filter dimension * `STRUCTURE_ELEMENT_KEY`: business key of the structure element to filter for **Example:** Restricting the *Costs* dimension to element `CST020` (Rent) yields only cells for "Rent" — not for any other cost type: **SINGLE Dimension Restriction** ```json { "dimensionKey": "Costs", "type": "SINGLE", "structureElementKey": "CST020" } ``` #### SUBSET Restricts a dimension to an **explicitly enumerated set of elements**. Only the listed elements themselves are matched — their descendant elements in the dimension hierarchy are **not** included. ```json { "dimensionKey" : "", "type" : "SUBSET", "structureElementKeys" : [ "", "", ... ] } ``` * `DIMENSION_KEY`: the plural label of the filter dimension * `STRUCTURE_ELEMENT_KEY_N`: business keys of the structure elements to filter for **Example:** Restricting the *Scenarios* dimension to `ACTUAL` and `PLAN` yields only cells for these two scenarios, not for `FORECAST`: **SUBSET Dimension Restriction** ```json { "dimensionKey": "Scenarios", "type": "SUBSET", "structureElementKeys": ["ACTUAL", "PLAN"] } ``` {% hint style="success" %} **SUBSET vs. SUBTREES:** Unlike `SUBTREES`, the `SUBSET` type matches *only the explicitly listed elements themselves* — descendant elements are **not** included. See [SUBTREES](#subtrees) below for a direct comparison. {% endhint %} #### LEAVES Restricts a dimension to all its **leaf elements** — i.e., elements that have no children in the dimension hierarchy. This is a structural restriction and requires no element keys to be specified. ```json { "dimensionKey" : "", "type" : "LEAVES" } ``` * `DIMENSION_KEY`: the plural label of the filter dimension **Example:** In the *Cost Centers* dimension of the tutorial planning model, the hierarchy is: ``` CCT000 (All Cost Centers) ├── CCT010 (Sales) ← leaf └── CCT020 (Administration) ├── CCT021 (General Admin) ← leaf └── CCT022 (IT Admin) ← leaf ``` Restricting to `LEAVES` yields only `CCT010`, `CCT021`, and `CCT022`: **LEAVES Dimension Restriction** ```json { "dimensionKey": "Cost Centers", "type": "LEAVES" } ``` #### SUBTREES Restricts a dimension to one or more **subtrees** — that is, the specified root element(s) **together with all their descendants** in the dimension hierarchy. ```json { "dimensionKey": "", "type": "SUBTREES", "structureElementKeys": [ "", "", ... ] } ``` * `DIMENSION_KEY`: the plural label of the dimension to restrict * `STRUCTURE_ELEMENT_KEY_N`: business keys of the root elements of the subtrees **Example:** In the *Cost Centers* dimension, restricting to `SUBTREES: [CCT020]` matches `CCT020` (Administration) **and** all its descendants — `CCT021` (General Administration) and `CCT022` (IT Administration): ``` CCT000 (All Cost Centers) ├── CCT010 (Sales) ← not matched └── CCT020 (Administration) ← matched (subtree root) ├── CCT021 (General Admin) ← matched (descendant) └── CCT022 (IT Admin) ← matched (descendant) ``` **SUBTREES Dimension Restriction** ```json { "dimensionKey": "Cost Centers", "type": "SUBTREES", "structureElementKeys": ["CCT020"] } ``` {% hint style="success" %} **SUBTREES vs. SUBSET:** While `SUBSET` only matches the explicitly listed elements, `SUBTREES` additionally includes **all descendants** of those elements. This makes `SUBTREES` the right choice when targeting an entire branch of the hierarchy, while `SUBSET` is suited for selecting a fixed list of specific elements regardless of their position in the hierarchy. Using the example above: `SUBSET: [CCT020]` would match **only** `CCT020` (Administration) itself — **not** its children `CCT021` or `CCT022`. `SUBTREES: [CCT020]` matches all three. {% endhint %} #### Combining Multiple Dimension Restrictions A conjunctive combination of dimension restrictions is expressed as a JSON array, containing a JSON object for each restriction. The example below demonstrates a conjunction using the tutorial planning model. In particular, applying this filter will yield only cube cells describing planned and actual energy costs on the lowest level of cost centers, with no further restrictions on other dimensions. **Dimension Restrictions Filter with Restrictions on Multiple Dimensions** ```json [ { "dimensionKey":"Cost Centers", "type":"LEAVES" }, { "dimensionKey":"Costs", "type":"SINGLE", "structureElementKey":"CST020" }, { "dimensionKey":"Scenarios", "type": "SUBSET", "structureElementKeys": [ "ACTUAL", "PLAN" ] } ] ``` A dimension restrictions filter is passed as query parameter `dimensionRestrictions` with its value being the corresponding JSON array in URL-encoded form as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). URL-encoding is supported by default in most modern programming languages, command line tools like `urlencode` also exist for scripting purposes. The following example illustrates a valid request with a URL-encoding of the above dimension restrictions filter for illustrative purposes. **Request with URL-Encoded Dimension Restrictions Filter** ```sh dimensionRestrictionsFilterEncoded="%5B%20%7B%20%22dimensionKey%22%3A%22Cost%20Centers%22%2C%20%22type%22%3A%22LEAVES%22%2C%20%22structureKey%22%3A%22Cost%20Centers%22%20%7D%2C%20%7B%20%22dimensionKey%22%3A%22Costs%22%2C%20%22type%22%3A%22SINGLE%22%2C%20%22structureElementKey%22%3A%22CST020%22%20%7D%2C%20%7B%20%22dimensionKey%22%3A%22Scenarios%22%2C%20%22type%22%3A%22SUBSET%22%2C%20%22structureElementKeys%22%3A%5B%20%22ACTUAL%22%2C%20%22PLAN%22%20%5D%20%7D%20%5D" curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.cube-cell-data" \ "${CUBE_CELLDATA_EXPORT_LINK}?dimensionRestrictions=${dimensionRestrictionsFilterEncoded}" curl --request DELETE \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_CELLDATA_DELETE_LINK}?dimensionRestrictions=${dimensionRestrictionsFilterEncoded}" ``` {% hint style="info" %} Dimension restrictions filters are always expressed as JSON Arrays. Thus, even a dimension restrictions filter with just one involved dimension must be encapsulated in a JSON Array! {% endhint %} {% hint style="info" %} Given that dimension restrictions filters are conjunctions of individual dimension restrictions, specifying multiple different dimension restrictions for the same dimension will effectively lead to an empty result! {% endhint %} ## Combining Filters The combination of different filter types is possible and follows conjunction semantics in the sense of *"return only cube cells" that fulfill filter 1 AND filter 2 AND ... AND filter n"*. The following example demonstrates such a conjuntive combination. Goal of this example is to retrieve / delete data for all cube cells for scenario *Actual* (key `ACTUAL`) and for costs *Rent* (key `CST020`), as expressed in the following dimension restrictions filter. **Dimension Restrictions Filter for Scenario & Cost Dimensions** ```json [ { "dimensionKey":"Scenarios", "type":"SINGLE", "structureElementKey":"ACTUAL" }, { "dimensionKey":"Costs", "type":"SINGLE", "structureElementKey":"CST020" } ] ``` A query with this dimension restrictions filter only will yield / delete an empty result, since the scenario "Actual" is defined with input allowed set to false. In order to retrieve / delete the expected result set, an additional input allowed filter must be set to value `ALL`, as indicated below. **Combining Input Allowed & Dimension Restrictions Filters** ```sh curl --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/x.de.qvantum-plan.cube-cell-data" \ "${CUBE_CELLDATA_EXPORT_LINK}?inputAllowedFilter=ALL&dimensionRestrictions=${dimensionRestrictionsFilterEncoded}" curl --request DELETE \ --header "Authorization:Bearer ${TOKEN}" \ "${CUBE_CELLDATA_DELETE_LINK}?inputAllowedFilter=ALL&dimensionRestrictions=${dimensionRestrictionsFilterEncoded}" ``` # Define Team With all prior preparations done, it now makes sense to define a team of planning users. {% hint style="info" %} A plan can only be started once a planning team has been defined for it: at least one planner with write permission (`input` allowed) must exist. {% endhint %} This definition of a team takes place in two steps. First, all users must exist in the context of a tenant. Non-existing users must be created, providing their user information. Second, users must be assigned to a plan with respective permissions. Technically, these steps are realized with different API endpoints for user management and assignment to plans. ## Manage Users Users in a team are managed via user definition CSV files. A user definition CSV file includes the following fields: * `last-name`: Last name of planning user * `first-name`: first name of planning user * `email`: email address of planning user * `single-sign-on-user-id`: unique user id for Single Sign On This definition implicitly differentiates two types of possible users in QVANTUM: * QVANTUM-managed: define first name, last name and email, omit single sign on user id. * Single Sign On (SSO): define all fields, email and single sign on user id must refer to the same user. {% hint style="info" %} SSO must be actively configured for a tenant by the QVANTUM team in collaboration with the IT administration team in control of this tenant. The definition of SSO users is possible at all times. However, login for users with an SSO user definition will only be possible after successful SSO configuration for the respective tenant. {% endhint %} **Sample User Definition** ```csv last-name;first-name;email Checker;Chris;chris@example.com Seller;Sally;sally@example.com Adminsky;Adam;adam@example.com ``` ### Upload User Definition A valid user definition file is uploaded to QVANTUM in one single asynchronous API call with its result enabling status polling afterwards. The upload of users follows synchronization semantics, i.e. the current tenant in QVANTUM is synchronized with the users in the uploaded team file, according to the following synchronization rules: | User in QVANTUM | User in CSV | Synchronization Operation | | --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | no | no | - | | no | managed | User is created in tenant and an invitation email with the initial password is send. | | no | SSO | User is created in tenant and an invitation email without an initial password is send. | | managed | no | User is removed from tenant. | | managed | managed | User information is updated. | | managed | SSO | User information is updated and login via password is disabled. | | SSO | no | User is removed from tenant. | | SSO | managed | User information is updated and an invitation email with an initial password is send. Login via SSO no longer works. | | SSO | SSO | User information is updated. | {% hint style="warning" %} This effectively means that updating a team requires to upload a **complete** updated user definition file with **all** wanted planning users under a tenant, including the ones that existed before. {% endhint %} {% hint style="warning" %} Users are only matched via their email address. If the email for a user changed, the old user account will be deleted and a new account will be created with the new email address. {% endhint %} #### Asynchronous Upload Technically, the upload of a user definition file is a request with the user CSV file as the body. One additional parameter in the MIME type allows to further specify the format of the uploaded file: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. **Upload User Definition** ```sh USER_DEFINITION_PATH="/path/to/user/definition/users.csv" curl --show-headers --request POST \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:text/csv" \ --data-binary "@${USER_DEFINITION_PATH}" \ "${TENANT_USER_UPLOADS_LINK}" ``` Uploading user definitions with one of the above requests is asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the `Location` header. In the next step, repeated status polling allows to monitor the status of user definition processing on QVANTUM side. The returned URL leads to an upload history entry resource `${HISTORY_ENTRY_URL}`. Status polling works as described for the model upload (cf. [Upload Status Polling](/dev/model#upload-status-polling)). The only difference is the missing `cubeKey` field in the history entry. ### Retrieve User Definition User definition is retrieved with a simple GET request, serving user definition CSV content in its response body. An optional boolean request parameter `includeControllers` allows to control whether the retrieved user definition includes controller and planning users (default) or planning users only. {% hint style="warning" %} Retrieved user definitions including controller users cannot be uploaded again, as these users are created with a different workflow. {% endhint %} **Retrieve User Definition (planners only)** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${TENANT_USERS_LINK}?includeControllers=false" ``` The same resource also serves a JSON representation of the users, which in contrast to the CSV export includes the roles of each user and a link per user. As CSV is the default, the JSON representation has to be requested explicitly with an accept header: **Retrieve User Definition as JSON** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Accept:application/hal+json" \ "${TENANT_USERS_LINK}" ``` ### Retrieve a Single User Following the `self` link of a user, or the `user` link of a planner status, leads to a single user. **Retrieve a Single User** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ "${USER_LINK}" ``` **User JSON Representation** ```json { "emailAddress": "planner@example.com", "firstName": "Decentral", "lastName": "Planner", "singleSignOnUserId": null, "roles": [ "DECENTRAL_PLANNER" ], "_links": { "self": { "href": "https://api.qvantum-plan.de/api/v1/users/2" }, "owner": { "href": "https://api.qvantum-plan.de/api/v1/tenants/1" } } } ``` ## Assign Permissions In general, each planner must be explicitly granted sufficient permissions to view or even enter planning data, according to his planning responsibilities. In QVANTUM, a permission assignment is defined as a list of references to planning users including their respective permissions across dimensions. This list is then encoded in a permission assignment CSV file for later upload via the QVANTUM Public API. A permission assignment CSV file includes the following fields: * `email`: email address of planning user * The plural labels of the dimensions used to define permissions * `input`: input allowed for planning user Permissions in keyfigure and time dimensions are not allowed. There are three possible ways to define permissions in a dimension: * : an empty value means that the planner has no permission in the dimension * `[a] [b]`: a list of element keys. The planner has permissions on those elements and their descendants * `all`: the planner has permissions on all elements in the dimension **Sample Permission Assignment File** ```csv email;Cost Centers;Scenarios;input chris@example.com;[CCT000];[PLAN];no sally@example.com;[CCT000][CCT010];[FORECAST];yes adam@example.com;all;all;yes ``` The above example of a permission assignment CSV file defines the permissions for three planning users: * Sally is responsible for contributing forecast figures for the sales cost center. * Adam is responsible for contributing plan figures for the sales and administration cost centers. * Chris is responsible for checking all figure contributions across all cost centers. ### Upload Permission Assignment A valid permission assignment file is uploaded to QVANTUM in one single synchronous API call. The upload of a permission assignment follows upsert semantics, i.e. user permissions are either defined or updated. #### Synchronous Upload Technically, the upload of a permission assignment is a PUT request in the context of a plan, with contents of a permission assignment CSV file in the body. One additional parameter allows to further specify the format of the uploaded permission assignment file: * `charset`: the charset to be used. Valid values are `US-ASCII`, `ISO-8859-1`, `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, and `Windows-1252`. If omitted, defaults to `UTF-8`. As for files encoded in UTF-8, any optionally included [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail. **Upload Permission Assignment** ```sh PERMISSION_ASSIGNMENT_PATH="/path/to/permission/assignment/permissions.csv" curl --show-headers --request PUT \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:text/csv" \ --data-binary "@${PERMISSION_ASSIGNMENT_PATH}" \ "${ALL_PERMISSIONS_LINK}" ``` Uploading permission assignment with one of the above requests is synchronous. The operation either succeeds with a response with HTTP status 204 or a status 422 including an error message in the body. ### Retrieve Permission Assignment Permission assignments are retrieved with a simple GET request, serving permission assignment CSV content in its response body. **Retrieve Permission Assignment** ```sh curl --silent --request GET \ --header "Authorization:Bearer ${TOKEN}" \ --header "Content-Type:text/csv" \ "${ALL_PERMISSIONS_LINK}" ```