Stammdaten

Anleitungen zur Administration, Integration und Verwendung von Stammdaten.

Stammdaten

Stammdaten dienen in Squeeze zur Erkennung und Plausiblisierung von Merkmalen auf den jeweiligen Dokumententypen.

Stammdaten werden in Squeeze in der Datenbank als Tabelle angelegt. Dabei können beliebig viele unterschiedliche Spalten konfiguriert werden.

Es können unbegrenzt viele Stammdatentabellen angelegt werden.

Klassische Beispiele für Stammdatentabellen:

Squeeze kann die auf dem Dokument gefundenen Merkmale in den Stammdaten plausiblisieren und / oder auf zugehörige Werte umsetzen.

Die Stammdaten können auf verschiedene Art und Weise aktualisiert / gepflegt werden:

In Sonderfällen ist auch der Import mittels Datenbank-Skript möglich, allerdings nicht im Standard-Cloudbetrieb.

Anlegen einer neuen Stammdatentabelle im Webclient

Das Anlegen einer neuen Stammdatentabelle in Squeeze muss initial via CSV-Upload aus dem Webclient erfolgen.

image-1649060596506.png

Beim Klick auf den Reiter Stammdaten öffnet sich der Dialog für die Stammdatenkonfiguration.

Die Oben aufgeführten Stammdatentabellen werden aktuell mit dem Invoice Template ausgeliefert.

image-1649060706716.png

Eine neue Stammdatentabelle wird über das Symbol "Neuer Eintrag" angelegt.

Im nächsten Dialog wird der technische Name und der Anzeigenamen angegeben.

image-1649060750960.png

 

 

Konfiguration und Initialisieren einer neuen Stammdatentabelle via CSV-Upload

Im Webclient wird die Konfiguration der Spalten für diese Stammdatentabelle durchgeführt.

Stammdateneigenschaften

Mit einem Klick auf den Eintrag in der Liste öffnet sich der Konfigurationsdialog für die Stammdatentabelle.

image-1649060918611.png

Spaltenkonfiguration

Zuerst werden die Spalten konfiguriert. Beim Klick auf den Reiter Spalten öffnet sich der Dialog zum Konfigurieren der Tabellenspalten.

image-1649061004570.png

Mit dem Symbol "Neuer Eintrag" können neue Spalten hinzugefügt werden.

image-1649061054415.png

Wichtig!: Beim Betätigen des Buttons "Tabelle anlegen/zurücksetzen" werden alle Datensätze innerhalb der Tabelle gelöscht.

Hier werden folgende Informationen benötigt:

Eigenschaft Beschreibung
Name Technischer Name für der Datenbankspalte
Beschreibung Anzeigenamen für der Datenbankspalte
Quelle externer Spaltenname (z.B. die Spaltenüberschrift in einer CSV-Datei)

Jede Stammdatentabelle in Squeeze benötigt mindestens eine ID-Spalte.

Es können dann beliebig viele eigene Spalten definiert werden.

Test-Tabelle mit id-Spalte + 2 weitere Spalten:

image-1649061129272.png

Nachdem die Spalten konfiguriert sind, wird eine CSV-Datei benötigt um die Tabelle auf dem Datenbankserver initial zu erstellen.

Die CSV Datei muss die selben Überschriften enthalten, wie in der Spaltenkonfiguration unter Quelle angegeben worden ist. Die Reihenfolge der Überschriften spielt keine Rolle.

WICHTIG: die Schreibweise der Spaltenüberschriften in der CSV-Datei ist case-sensitive. Das bedeutet Groß-Kleinschreibung ist relevant.

CSV-Datei Beispiel für die obige Tabelle:

image-1583510696508.png

Für die Werte-Zeilen müssen keine ID´s angegeben werden. Die ID Spalte ist eine Auto-Inkrement Spalte und erzeugt eigene fortlaufende ID´s beim Upload.

Nachdem die CSV-Datei erstellt wurde kann die Initialisierung der neuen Stammdatentabelle erfolgen mit einem Klick auf den Reiter Upload.

image-1649061188375.png

Die übergeben Werte können mit einem Klick auf den Reiter Daten geprüft werden.

image-1649062298131.png

Daten hinzufügen

Mit dem Webclient können manuell mit dem Symbol "NeuerEintrag" weitere Werte hinzugefügt werden.

image-1649062378547.png

Den neuen Datensatz mit dem Speichern Button bestätigen.

image-1649062412805.png

 

 

Export von Stammdaten als CSV

Neben dem Import von Stammdaten als CSV gibt es ab Squeeze 2.5 auch einen Export, der sich ähnlich verhält.

Voraussetzungen

Der CSV-Export steht nur dem Admin-User zur Verfügung, nicht normalen Usern.

Export per API

Am einfachsten kann man das ganze mit Hilfe der integrierten Swagger-UI ausprobieren:

image-1690882782971.png

Als Parameter tableId gibt man die numerische ID einer existierenden Stammdatentabelle an. Das resultierende File wird danach als Download-Link in der Swagger-UI angeboten.

Export per GUI

tbd

 

Stammdaten ab Squeeze 2.5

Mit dem Release von Squeeze 2.5 haben sich bei der Benutzung von Stammdaten ein paar Details geändert. Diese Seite soll eine Übersicht geben und helfen eventuelle Probleme beim Update zu umgehen.

Lese- und Schreiboperationen

Soweit die Stammdaten nur gelesen und geschrieben werden ist keine Anpassung notwendig. Das betrifft insbesondere auch die Verwendung in DB-Link Lokatoren, welche lesend auf die Daten zugreifen.

Änderungen der Datenstruktur

Alle Änderungen der Struktur werden direkt umgesetzt. Nach dem Erzeugen einer Tabelle oder Spalte können dort direkt Daten geschrieben werden, ein separates Initialisieren der Tabelle (mit dem Verlust aller Daten) ist nicht mehr erforderlich. Die Daten in einer Tabelle werden bei Änderungen auch beibehalten, beispielsweise wenn man nur eine Tabelle oder Spalte umbenennt.

Integration existierender Tabellen

In Squeeze bis Version 2.4 gab es on-premise die Möglichkeit existierende (also nicht von Squeeze angelegte und verwaltete) DB-Tabellen oder -Views als Stammdaten zu integrieren. Dieses Feature war nie konsequent umgesetzt, was zu Bugs führte und mit Squeeze 2.5 entfernt wurde, um die Benutzung zu vereinheitlichen.

Bei einem Update auf Squeeze 2.5 sollte eine existierende Integration zunächst nicht betroffen sein, Zugriff auf Daten also weiterhin funktionieren. Was man jedoch vermeiden sollte ist die Struktur dieser Tabellen über Squeeze anzupassen. Es besteht hier die Gefahr von Datenverlusten!

Falls für eine on-premise Installation eine derartige Integration notwendig ist, müsste das als Sonderanpassung umgesetzt werden.

Falls sie vor Squeeze Stammdatentabellen entweder auf ihre eigenen SQL Tabellen- und Views oder produktinterne Tabellen eingerichtet haben, berücksichtigen Sie, dass ein Update auf Squeeze > 2.5 mit Support-Aufwänden verbunden sein kann.

Systeminterne Stammdatentabellen

Squeeze hat ein paar Stammdatentabellen die Teil des Systems selbst sind, also nicht erst durch manuelle Konfiguration oder das Invoices-Paket erstellt werden. Diese Daten werden als Stammdaten bereitgestellt, damit man mit den existierenden Mechanismen auf die Daten zugreifen kann. Insbesondere kann man per UI die Daten Pflegen und DB-Link Lokatoren auf diesen Daten erstellen. Da interne Abhängigkeiten auf die Struktur dieser Daten besteht, sind diese Tabellen ab Squeeze 2.5 geschützt. Modifikationen der Struktur werden daher vom System nicht mehr zugelassen.

Betroffen sind hiervon die folgenden Tabellen:

Synchronisation von Stamm- und Bewegungsdaten mittels externer IDs

Zielsetzung

Für die Verdichtung und Synchronisation von Extraktionsergebnissen in Squeeze Extract müssen Stamm- und Bewegungsdaten effizient und konsistent bereitgestellt werden. Insbesondere bei großen Datenmengen ist es nicht sinnvoll, komplette Datenbestände regelmäßig neu zu importieren.

Stattdessen empfiehlt sich folgendes Vorgehen:

  1. Einmaliger Initialimport aller relevanten Daten.
  2. Anschließende Synchronisation über gezielte CRUD-Operationen (Create, Read, Update, Delete).
  3. Verwendung einer kundenseitigen Primärschlüsselreferenz über die Spalte externalid.

Dadurch können Datensätze eindeutig identifiziert und effizient aktualisiert oder gelöscht werden.

Verwendung einer externen ID

Standardmäßig verwendet Squeeze Extract die interne Spalte id als Primärschlüssel für API-Operationen.

Für Integrationsszenarien empfiehlt es sich jedoch, eine zusätzliche Spalte namens externalid anzulegen. Diese enthält den Primärschlüssel des Quellsystems und ermöglicht eine stabile Zuordnung zwischen externem System und Squeeze Extract.

Einrichtung der Spalte

  1. Öffnen Sie die Administration -> Stammdaten
  2. Öffnen Sie Tabelle, die Sie auf die Verwendung eines externen Primärschlüssels umstellen wollen  
  3. In den Bereich Spalten wechseln.
  4. Eine neue Spalte mit dem Namen externalid (ausschließlich Kleinbuchstaben) anlegen.
  5. Die Tabelle über „Tabelle anlegen / zurücksetzen“ erneut initialisieren (die bisher enthaltenen Daten werden dabei entfernt)

Nach der Initialisierung wird die Primärschlüssellogik angepasst:

Beispiel

Existiert bereits ein Datensatz mit der externen ID 001, kann kein weiterer Datensatz mit derselben externen ID angelegt werden.

image.png

Initialer Datenimport

Nach Einrichtung der externen ID sollte ein vollständiger Import aller Stammdaten über den Master-Data-Endpunkt durchgeführt werden.

Empfohlener Endpunkt

/rows/batch

Alternativ kann der Import auch initial über einen CSV Upload in der Squeeze Oberfläche durchgeführt werden.

Anforderungen

Der Batch-Import dient ausschließlich zur initialen Befüllung des Datenbestands.

Laufende Synchronisation

Nach dem Initialimport sollten Änderungen ausschließlich über einzelne Transaktionen verarbeitet werden.

Folgende Operationen werden unterstützt:

Dadurch können auch sehr große Datenbestände effizient synchronisiert werden, ohne regelmäßig komplette Tabellen neu zu übertragen.

Nutzung der API mit externer ID

Für Lookup-, Update- und Delete-Operationen muss der Parameter

useExternalId=true

übergeben werden.

Funktionsweise

Mit diesem Parameter wird der übergebene Wert in rowId gegen die Spalte externalid geprüft.

Beispiel:

...?rowId=4711&useExternalId=true

In diesem Fall sucht die API nach einem Datensatz mit:

externalid = 4711

Standardverhalten

Wird der Parameter nicht übergeben,

...?rowId=4711

prüft die API weiterhin gegen die interne Spalte:

id = 4711

Best Practices

Nutzen für Integrationen

Durch die Verwendung einer externen ID wird die Synchronisation zwischen Quellsystem und Squeeze Extract deutlich vereinfacht. Änderungen können gezielt auf einzelne Datensätze angewendet werden, wodurch Netzwerkverkehr, Verarbeitungszeit und Systemlast erheblich reduziert werden. Gleichzeitig bleibt die Zuordnung zwischen Quellsystem und Squeeze Extract dauerhaft konsistent.

Berechtigungen für Stammdatentabellen

Stammdatentabellen können in Squeeze mit einem feingranularen, rollenbasierten Berechtigungssystem geschützt werden. Damit lässt sich pro Tabelle und pro Rolle festlegen, wer die Daten einer Tabelle bearbeiten und wer die Tabelle selbst verwalten darf.

Dieses feingranulare System ist nur aktiv, wenn das Feature-Flag masterDataTablePermissions für den Mandanten aktiviert ist (siehe Features verwalten). Ist das Flag deaktiviert (Standard), gelten ausschließlich die globalen Berechtigungen (siehe unten).

Zwei Berechtigungsstufen

Das System unterscheidet zwei Aktionen auf einer Stammdatentabelle. Jede ist an eine globale Berechtigung (einen Scope, den eine Rolle erhalten kann) gekoppelt:

StufeGlobale Berechtigung (Scope)Erlaubt
Verwalten (manage)sqz_masterdata_manageTabellen anlegen, ändern und löschen; Spalten und Schema pflegen; die Berechtigungen der Tabelle pflegen
Bearbeiten (edit)sqz_masterdata_editDatenzeilen einer Tabelle anlegen, ändern und löschen (inkl. CSV- und Batch-Upload)

Die meisten lesenden Zugriffe (Tabellen auflisten, Spalten anzeigen, Zeilen suchen) sind nicht durch diese Berechtigungen geschützt und stehen jedem authentifizierten Benutzer offen. Ausnahme: der CSV-Export – dieser wird gesondert geprüft (siehe Abschnitt „Sonderfall: CSV-Export").

Verhalten bei deaktiviertem Feature-Flag (Standard)

Ohne aktiviertes Flag entscheidet ausschließlich die globale Berechtigung:

Eine tabellen- oder rollenspezifische Feinsteuerung findet nicht statt. Bereits hinterlegte Tabellen-Berechtigungen bleiben ohne Wirkung, bis das Flag aktiviert wird.

Verhalten bei aktiviertem Feature-Flag

Ist das Flag aktiv, wird der Zugriff auf die schreibenden Endpunkte (Tabelle verwalten bzw. Daten bearbeiten) in dieser Reihenfolge entschieden:

  1. Globale Berechtigung zuerst: Besitzt eine Rolle des Benutzers den globalen Scope (sqz_masterdata_manage bzw. sqz_masterdata_edit), ist der Zugriff auf alle Tabellen erlaubt. Die globale Berechtigung wirkt damit wie eine „Wildcard".
  2. Sonst tabellenspezifisch: Andernfalls werden die für die betroffene Tabelle hinterlegten Berechtigungen geprüft. Hat der Benutzer eine Rolle, für die in dieser Tabelle das passende Recht (canEdit bzw. canManage) gesetzt ist, wird der Zugriff gewährt.
  3. Andernfalls verweigert: Trifft nichts davon zu, wird der Zugriff mit „nicht autorisiert" (HTTP 403) abgelehnt.

Die tabellenspezifischen Berechtigungen sind also additiv zur globalen Berechtigung: Der globale Scope gibt Vollzugriff auf alle Tabellen, während tabellenspezifische Einträge einzelnen Rollen gezielt Rechte für einzelne Tabellen einräumen.

Der CSV-Export folgt dieser Reihenfolge nicht – siehe den nächsten Abschnitt.

Das Tabellen-Berechtigungsobjekt

Eine tabellenspezifische Berechtigung gilt jeweils für die Kombination aus einer Tabelle und einer Rolle:

FeldTypBedeutung
tableIdintegerID der Stammdatentabelle
roleIdintegerID der Rolle, für die die Berechtigung gilt
canEditbooleanDie Rolle darf die Datenzeilen der Tabelle bearbeiten
canManagebooleanDie Rolle darf die Tabelle verwalten (Struktur, Spalten, Schema und Berechtigungen)

Das Pflegen der Berechtigungen einer Tabelle zählt selbst zu „Verwalten". Nur wer canManage für die Tabelle (bzw. den globalen Scope sqz_masterdata_manage) besitzt, kann deren Berechtigungen ändern.

Sonderfall: CSV-Export

Der CSV-Export einer Tabelle (GET /masterData/tables/{tableId}/csv) wird bei aktiviertem Feature-Flag gesondert und abweichend von der übrigen Zugriffslogik geprüft:

Erhält ein Benutzer bei aktiviertem Feature-Flag ein HTTP 403 beim CSV-Export, obwohl er die Tabelle verwalten oder anderweitig darauf zugreifen kann, fehlt ihm mit hoher Wahrscheinlichkeit ein canEdit-Eintrag für genau diese Tabelle. Weisen Sie einer seiner Rollen eine Tabellen-Berechtigung mit canEdit = true zu.

Konfiguration über die API

Die tabellenspezifischen Berechtigungen werden über die REST-API gepflegt. Der Request-Body entspricht dem oben beschriebenen Objekt (roleId, canEdit, canManage).

Lesen:

Schreiben (erfordert Verwalten-Recht):

Verwandte Themen