Zum Hauptinhalt springen

Formate

Metadaten können mit dem Upload-API bzw. Download-API in unterschiedlichen Formaten importiert bzw. exportiert werden. Referenzen zwischen Metadatenobjekten werden über ihre fachlichen Schlüssel abgebildet. Reports können in gängigen Formaten generiert werden.

Fachlicher Schlüssel​

Beim Upload oder Download werden Metadatenobjekte über ihre fachlichen Schlüssel identifiziert (im Gegensatz zur technischen UUID). Ein fachlicher Schlüssel wird aus einer oder mehreren Bezeichnungen (label) zusammengesetzt und stellt einen eindeutigen, hierarchischen Pfad zu einem Metadatenobjekt dar. Fachliche Schlüssel werden in Beziehungen (z.B. inCollection, hasDomain) und Verknüpfungen (z.B. Herkünfte) verwendet, um Metadatenobjekte zu referenzieren.

Zum Beispiel, das Metadatenobjekt BusinessAttribute (im Format JSON) referenziert andere Metadatenobjekte über ihre eindeutigen fachlichen Schlüssel Rechnung und /Datentypen/Datum:

{
  "_type" : "BusinessAttribute",
  "hasDomain" : "Rechnung",
  "label" : "Buchungsdatum",
  "hasRange" : "/Datentypen/Datum"
}

Fachliche Schlüssel haben folgende Merkmale:

  • Die einzelnen Bezeichnungen werden bei zusammengesetzten fachlichen Schlüsseln durch / getrennt.
  • Falls das referenzierte Metadatenobjekt in einem anderen Modell liegt, dann beginnt der fachliche Schlüssel mit / und der Bezeichnung des Modells. Anderenfalls wird das Modell im fachlichen Schlüssel weggelassen.
  • Bei Metadatenobjekten, die nur innerhalb des übergeordneten Metadatenobjekts jedoch nicht im Modell eindeutig sein müssen (z.B. Subsammlungen, Subsysteme), muss das übergeordnete Metadatenobjekt (z.B. Sammlung, System) durch / getrennt vorangestellt werden.
Erklärung

Aus der letzten Regel ergibt sich, zum Beispiel:

BezeichnungenFachlicher Schlüssel
AdresseAdresse
Fachdatenmodell, Person/Fachdatenmodell/Person
Enterprise Model, Billing, Invoice, Date/Enterprise Model/Billing/Invoice/Date

Trennzeichen​

Falls in einer Bezeichnung eines einfachen oder zusammengesetzten fachlichen Schlüssels das Zeichen / oder . vorkommt, dann muss gekennzeichnet werden, dass es sich dabei um einen Teil der Bezeichnung und nicht um ein Trennzeichen des fachlichen Schlüssels handelt. Dazu wird die jeweilige Bezeichnung innerhalb des fachlichen Schlüssels unter Hochkomma (") gesetzt. Zum Beispiel:

BezeichnungenFachlicher Schlüssel
dataspot."dataspot."
Technische Objekte, INPUT/OUTPUTTechnische Objekte."INPUT/OUTPUT"
Datei bzw. Schnittstelle, Zeiterfassung"Datei bzw. Schnittstelle".Zeiterfassung
Datei bzw. Schnittstelle, Mitarbeiter.csv"Datei bzw. Schnittstelle"."Mitarbeiter.csv"

Falls in einer Bezeichnung eines zusammengesetzten fachlichen Schlüssels das Zeichen " vorkommt, dann muss gekennzeichnet werden, dass es sich dabei um einen Teil der Bezeichnung handelt. Dazu wird die jeweilige Bezeichnung innerhalb des fachlichen Schlüssels unter Hochkomma (") gesetzt und jedes Hochkomma innerhalb der Bezeichnung wird verdoppelt. Zum Beispiel:

BezeichnungenFachlicher Schlüssel
Kategorie, 28" City BikeKategorie."28"" City Bike"
Projekte, Projekt "Zeus"Projekte/"Projekt ""Zeus"""
Codename "Kronos"Codename "Kronos"
Hinweis

Die Bezeichnung Codename "Kronos" wird als fachlicher Schlüssel Codename "Kronos" (ohne zusätzliche Hochkomma) abgebildet, weil Bezeichnungen mit " nur dann unter Hochkomma gesetzt werden müssen, wenn es sich um einen zusammengesetzten fachlichen Schlüssel handelt.

Hinweis

Falls am Anfang (bzw. am Ende) einer Bezeichnung das Zeichen " vorkommt, dann ergibt sich aufgrund der beschriebenen Regeln, dass am Anfang (bzw. am Ende) der Bezeichnung im zusammengesetzten fachlichen Schlüssel drei Hochkomma (""") stehen. Zum Beispiel, die Bezeichnungen Projekte und Projekt "Zeus" werden zu Projekte/"Projekt ""Zeus""".

Import/Export​

Metadaten können in folgenden Formaten importiert bzw. exportiert werden:

Die Properties richten sich nach dem Modell, für welches Metadaten importiert bzw. exportiert werden, und bestehen aus allen Properties, die laut Metamodell standardmäßig definiert sind, ergänzt um alle kundenspezifischen Custom-Properties, die in der jeweiligen Datenbank konfiguriert sind.

Hinweis

Die Properties eines Modells in einem bestimmten Format können auch praktisch mittels Download in der Benutzeroberfläche im jeweiligen Format ermittelt werden.

Beziehungen zwischen Metadatenobjekten (z.B. inCollection, hasDomain) werden über fachliche Schlüssel dargestellt. Verknüpfungen zwischen Metadatenobjekten (z.B. Herkünfte) werden als eigene Objekte abgebildet:

FormatVerknüpfungen
XLSXVerknüpfungen werden als fachliche Schlüssel in einer eigenen Tabelle abgebildet. Verknüpfungsattribute sind Spalten in dieser Tabelle.
CSVVerknüpfungen werden als fachliche Schlüssel in einer eigenen CSV-Datei abgebildet. Verknüpfungsattribute sind Spalten in dieser CSV-Datei.
XMLVerknüpfungen werden als fachliche Schlüssel in einem eigenen XML-Element abgebildet. Verknüpfungsattribute sind untergeordnete XML-Elemente.
JSONVerknüpfungen werden als fachliche Schlüssel in einem eigenen JSON-Objekt abgebildet. Verknüpfungsattribute sind JSON-Properties in diesem JSON-Objekt.

XLSX (Microsoft Excel)​

Der Import/Export im Format XLSX (Microsoft Excel) ist ein Spreadsheet, welches für jeden Typ von Metadatenobjekten eine eigene Tabelle enthält (z.B. Sammlungen, Geschäftsobjekte, Attribute, Beziehungen, usw.). Jede Tabelle enthält eine Liste der ausgewählten Metadatenobjekte des jeweiligen Typs. Die Beziehungen zwischen den Metadatenobjekten werden über fachliche Schlüssel dargestellt.

Hinweis

Die einzelnen Tabellen in XLSX (Microsoft Excel) sind analog zu den einzelnen CSV-Dateien im Format CSV zu sehen.

Im Format XLSX entsprechen die Namen der Properties den angezeigten Beschriftungen in der Benutzeroberfläche. Für Properties, die als Datentyp literal haben, wird die Bezeichnung des Codes (wie in der Benutzeroberfläche angezeigt) erwartet.

Tooltipp

Die Tabellennamen und Überschriften entsprechen den angezeigten Beschriftungen in der Benutzeroberfläche und können in unterschiedlichen Sprachen importiert und exportiert werden (z.B. Sammlungen oder Collections, Schreibgeschützt oder Read-only). Die Sprache kann im Upload-API und im Download-API mit der Option language bzw. mit dem HTTP-Header Attribut Accept-Language definiert werden.

Achtung

Nicht nur die gewählte Sprache sondern auch die Konfiguration wird berücksichtigt, um die Tabellennamen und Überschriften zu ermitteln. Benutzer oder Schnittstellen, die das Format XLSX verwenden, müssen daher einrechnen, dass die Beschriftungen nicht festgelegt sind sondern kundenspezifisch angepasst sein könnten.

Hinweis

Aus Gründen der Übersichtlichkeit sind in den folgenden Beispielen bestimmte Spalten ausgeblendet.

Die Verknüpfungen zwischen Metadatenobjekten (z.B. Herkünfte) werden als fachliche Schlüssel in einer eigenen Tabelle abgebildet (z.B. die Tabelle Herkünfte mit den Spalten Herkunft zu und Herkunft von). Verknüpfungsattribute sind Spalten in dieser Tabelle (z.B. die Spalten Favorit und Kennzeichnung).

XLSX

Tooltipp

Alle Properties, die aufgrund der Konfiguration Pflichtfelder sind, werden mit der Hintergrundfarbe "Flieder" gekennzeichnet. Diese Felder müssen beim Upload verpflichtend befüllt sein.

Hinweis

Das Format XLSX (Microsoft Excel) schränkt die Größe einer Zelle auf 32,767 Zeichen ein.

CSV (Gezippt)​

Hinweis

Für CSV wird eine Kodierung in UTF-8 verwendet. Falls bestimmte Zeichen (z.B. Umlaute, ß, €, usw.) nach dem Import fälschlicherweise als ? dargestellt werden, dann sollte die CSV-Datei vor dem Import in UTF-8 umgewandelt werden.

Der Import/Export im Format CSV ist eine ZIP-Datei, welche für jeden Typ von Metadatenobjekten eine eigene CSV-Datei enthält (z.B. Collection.csv, BusinessObject.csv, BusinessAttribute.csv, Relationship.csv, usw.). Jede CSV-Datei enthält eine Liste der ausgewählten Metadatenobjekte des jeweiligen Typs. Die Beziehungen zwischen den Metadatenobjekten (z.B. inCollection, hasDomain, hasRange) werden über fachliche Schlüssel dargestellt.

Hinweis

Die einzelnen CSV-Dateien sind analog zu den einzelnen Tabellen im Format XLSX (Microsoft Excel) zu sehen.

Im Format CSV entsprechen die Namen der Properties den (internen englischen) Attributsnamen (laut Metamodell) und weichen daher von den angezeigten Beschriftungen in der Benutzeroberfläche ab. Für Properties, die als Datentyp literal haben, wird der jeweilige Code (laut Metamodell) erwartet. Der Typ von jedem Metadatenobjekt (Collection, BusinessObject, BusinessAttribute, usw.) entspricht dem Namen der jeweiligen CSV-Datei.

Hinweis

Aus Gründen der Übersichtlichkeit sind in den folgenden Beispielen bestimmte CSV-Spalten ausgeblendet.

Die Verknüpfungen zwischen Metadatenobjekten (z.B. Herkünfte) werden als fachliche Schlüssel in einer eigenen CSV-Datei abgebildet (z.B. die CSV-Datei Derivation.csv mit den Spalten derivedTo und derivedFrom). Verknüpfungsattribute sind Spalten in dieser CSV-Datei (z.B. die Spalten favorite und qualifier).

Collection.csv:

label,title
Abrechnung,Verrechnung und Fakturierung

BusinessObject.csv:

label,inCollection
Rechnung,Abrechnung

BusinessAttribute.csv:

hasDomain,label,hasRange
Rechnung,Buchungsdatum,/Datentypen/Datum
Rechnung,Summe,/Datentypen/Betrag

Derivation.csv:

derivedTo,derivedFrom,favorite,qualifier
Rechnung,/Enterprise Model/Billing/Invoice,false,SPOT

Fachliche Schlüssel in CSV​

Das Format CSV definiert, dass eine Zeichenkette, in welcher das Zeichen " vorkommt, unter Hochkomma (") gesetzt werden muss und jedes Hochkomma innerhalb der Bezeichnung verdoppelt wird.

Zum Erzeugen von syntaktisch korrekten fachlichen Schlüsseln im Format CSV ergibt sich daraus folgende zweistufige Vorgehensweise:

  1. Bezeichnungen in fachlichen Schlüssel umwandeln
    • Falls in einer Bezeichnung eines einfachen oder zusammengesetzten fachlichen Schlüssels das Zeichen / oder . vorkommt, dann wird die Bezeichnung innerhalb des fachlichen Schlüssels unter Hochkomma (") gesetzt.
    • Falls in einer Bezeichnung eines zusammengesetzten fachlichen Schlüssels das Zeichen " vorkommt, dann wird die Bezeichnung innerhalb des fachlichen Schlüssels unter Hochkomma (") gesetzt und jedes Hochkomma innerhalb der Bezeichnung wird verdoppelt.
  2. Fachlichen Schlüssel nach CSV konvertieren
    • Jeder fachliche Schlüssel, in dem das Zeichen " vorkommt, wird unter Hochkomma (") gesetzt und jedes Hochkomma innerhalb des fachlichen Schlüssels wird verdoppelt.

Ausgehend von den vorigen Beispielen, werden die fachlichen Schlüssel in CSV folgendermaßen abgebildet:

Fachlicher SchlüsselCSV
AdresseAdresse
Fachdatenmodell/PersonFachdatenmodell/Person
Enterprise Model/Billing.Invoice/DateEnterprise Model/Billing.Invoice/Date
/Fachdatenmodell/Person/Fachdatenmodell/Person
/Enterprise Model/Billing/Invoice/Date/Enterprise Model/Billing/Invoice/Date
Technische Objekte.ABTEILUNGTechnische Objekte.ABTEILUNG
Enterprise Model/Entities.Person/birthDateEnterprise Model/Entities.Person/birthDate
"dataspot.""""dataspot."""
Technische Objekte."INPUT/OUTPUT""Technische Objekte.""INPUT/OUTPUT"""
"Datei bzw. Schnittstelle".Zeiterfassung"""Datei bzw. Schnittstelle"".Zeiterfassung"
"Datei bzw. Schnittstelle"."Mitarbeiter.csv""""Datei bzw. Schnittstelle"".""Mitarbeiter.csv"""
Kategorie."28"" City Bike""Kategorie.""28"""" City Bike"""
Projekte/"Projekt ""Zeus""""Projekte/""Projekt """"Zeus"""""""
Codename "Kronos""Codename ""Kronos"""
Vereinfachte Vorgehensweise

Beim fachlichen Schlüssel darf grundsätzlich jede Bezeichnung unter Hochkomma (") gesetzt werden, egal ob die Zeichen /, . oder " darin vorkommen oder nicht. In CSV darf grundsätzlich jede Zeichenkette unter Hochkomma (") gesetzt werden, egal ob das Zeichen " darin vorkommt oder nicht.

Daraus ergibt sich folgende vereinfachte (weniger konservative) Vorgehensweise zum Erzeugen von fachlichen Schlüsseln in CSV:

  1. Jede Bezeichnung innerhalb des fachlichen Schlüssels wird unter Hochkomma (") gesetzt und jedes Hochkomma innerhalb jeder Bezeichnung wird verdoppelt. Dieser Schritt entfällt, falls der fachliche Schlüssel einfach (nicht zusammengesetzt) ist und weder / noch . enthält.
  2. Der gesamte fachliche Schlüssel wird unter Hochkomma (") gesetzt und jedes Hochkomma innerhalb des fachlichen Schlüssels wird verdoppelt.

XML​

Der Import/Export im Format XML enthält eine flache, nicht-hierarchische Liste aller ausgewählten Metadatenobjekte. Die Beziehungen zwischen den Metadatenobjekten (z.B. inCollection, hasDomain, hasRange) werden über fachliche Schlüssel dargestellt.

Hinweis

Beim Export im Format XML ist eine Referenz auf das vollständige XML Schema (XSD) enthalten. Basierend auf dem Metamodell enthält das XML Schema eine technische Beschreibung aller Strukturen, Properties und Beziehungen.

Im Format XML entsprechen die Namen der Properties den (internen englischen) Attributsnamen (laut Metamodell) und weichen daher von den angezeigten Beschriftungen in der Benutzeroberfläche ab. Für Properties, die als Datentyp literal haben, wird der jeweilige Code (laut Metamodell) erwartet. Der Typ von jedem Metadatenobjekt (Collection, BusinessObject, BusinessAttribute, usw.) entspricht dem Namen des jeweiligen XML-Elements.

Hinweis

Aus Gründen der Übersichtlichkeit sind in den folgenden Beispielen bestimmte XML-Elemente ausgeblendet.

Die Verknüpfungen zwischen Metadatenobjekten (z.B. Herkünfte) werden als fachliche Schlüssel in einem eigenen XML-Element abgebildet (z.B. das XML-Element Derivation mit den untergeordneten XML-Elementen derivedTo und derivedFrom). Verknüpfungsattribute sind untergeordnete XML-Elemente (z.B. die untergeordneten XML-Elemente favorite und qualifier).

<?xml version="1.0" encoding="UTF-8"?>
<BusinessDataModel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:noNamespaceSchemaLocation="/api/test/meta/schemas/BusinessDataModel.xsd">
  <Collection>
    <label>Abrechnung</label>
    <title>Verrechnung und Fakturierung</title>
  </Collection>
  <BusinessObject>
    <label>Rechnung</label>
    <inCollection>Abrechnung</inCollection>
  </BusinessObject>
  <BusinessAttribute>
    <hasDomain>Rechnung</hasDomain>
    <label>Buchungsdatum</label>
    <hasRange>/Datentypen/Datum</hasRange>
  </BusinessAttribute>
  <BusinessAttribute>
    <hasDomain>Rechnung</hasDomain>
    <label>Summe</label>
    <hasRange>/Datentypen/Betrag</hasRange>
  </BusinessAttribute>
  <Derivation>
    <derivedTo>Rechnung</derivedTo>
    <derivedFrom>/Enterprise Model/Billing/Invoice</derivedFrom>
    <favorite>false</favorite>
    <qualifier>SPOT</qualifier>
  </Derivation>
</BusinessDataModel>

JSON​

Der Import/Export im Format JSON enthält eine flache, nicht-hierarchische Liste aller ausgewählten Metadatenobjekte. Die Beziehungen zwischen den Metadatenobjekten (z.B. inCollection, hasDomain, hasRange) werden über fachliche Schlüssel dargestellt.

Im Format JSON entsprechen die Namen der Properties den (internen englischen) Attributsnamen (laut Metamodell) und weichen daher von den angezeigten Beschriftungen in der Benutzeroberfläche ab. Für Properties, die als Datentyp literal haben, wird der jeweilige Code (laut Metamodell) erwartet. Der Typ von jedem Metadatenobjekt (Collection, BusinessObject, BusinessAttribute, usw.) steht in der Property _type.

Hinweis

Aus Gründen der Übersichtlichkeit sind in den folgenden Beispielen bestimmte JSON-Properties ausgeblendet.

Die Verknüpfungen zwischen Metadatenobjekten (z.B. Herkünfte) werden als fachliche Schlüssel in einem eigenen JSON-Objekt abgebildet (z.B. das JSON-Objekt Derivation mit den JSON-Properties derivedTo und derivedFrom). Verknüpfungsattribute sind JSON-Properties in diesem JSON-Objekt (z.B. die JSON-Properties favorite und qualifier).

[ {
  "_type" : "Collection",
  "label" : "Abrechnung",
  "title" : "Verrechnung und Fakturierung"
}, {
  "_type" : "BusinessObject",
  "label" : "Rechnung",
  "inCollection" : "Abrechnung"
}, {
  "_type" : "BusinessAttribute",
  "hasDomain" : "Rechnung",
  "label" : "Buchungsdatum",
  "hasRange" : "/Datentypen/Datum"
}, {
  "_type" : "BusinessAttribute",
  "hasDomain" : "Rechnung",
  "label" : "Summe",
  "hasRange" : "/Datentypen/Betrag"
}, {
  "_type" : "Derivation",
  "derivedTo" : "Rechnung",
  "derivedFrom" : "/Enterprise Model/Billing/Invoice",
  "favorite" : false,
  "qualifier" : "SPOT"
} ]

DDL/SQL​

Geschäftsobjektmodelle können als DDL/SQL exportiert werden. Datenmodelle können als DDL/SQL exportiert und importiert werden. Der Import/Export ist eine .ddl oder .sql Datei.

Beispiel Abrechnung.sql​

CREATE SCHEMA "Abrechnung"; 

CREATE TABLE "Abrechnung"."Rechnung" ("Buchungsdatum" DATE); 

ALTER TABLE "Abrechnung"."Rechnung"
ADD COLUMN "Summe" DOUBLE PRECISION;

Die Metadatenobjekte (Sammlungen, Datenobjekte, Geschäftsobjekte, usw.) werden in entsprechende Definitionen (Schemas, Tabellen, Spalten, usw.) in der Datenbank abgebildet - und umgekehrt.

Hinweis

Die konkrete SQL-Syntax ist abhängig von der gewählten Datenbank (PostgreSQL, Oracle, Microsoft SQL Server, MySQL) und wird mit der Option targetDatabase definiert.

XSD (Gezippt)​

Datenmodelle können als XSD (XML Schema Definition) importiert werden. Der Import ist eine ZIP-Datei, welche eine oder mehrere .xsd Dateien enthält.

Beispiel Abrechnung.xsd​

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Rechnung">
    <xs:complexType>
      <xs:attribute name="Buchungsdatum" type="xs:date"/>
      <xs:attribute name="Summe" type="xs:float"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Die Komponenten des Schemas (xs:element, xs:attribute, xs:complexType, usw.) werden in entsprechende Metadatenobjekte (Datenobjekte, technische Attribute, Enumerationen, usw.) abgebildet.

JSON Schema (Gezippt)​

Datenmodelle können als JSON Schema importiert werden. Der Import ist eine ZIP-Datei, welche eine oder mehrere .json Dateien enthält.

Beispiel Abrechnung.json​

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$id": "https://dataspot.io/test/abrechnung.json",
  "title": "Rechnung",
  "type": "object",
  "properties": {
    "Buchungsdatum": {
      "type": "string"
    },
    "Summe": {
      "type": "number"
    }
  }
}

Die Komponenten des Schemas (type, properties, usw.) werden in entsprechende Metadatenobjekte (Datenobjekte, technische Attribute, Enumerationen, usw.) abgebildet.

Reports​

Die vorgefertigten Reports können in folgenden Formaten generiert werden:

Tooltipp

Zusätzlich zu den vorgefertigten Reports können kundenspezifische Reports in XSLT implementiert und beim Mandanten hochgeladen und bearbeitet werden. Kundenspezifische Reports können weitere, zusätzliche Formate unterstützen.

Hinweis

Bei bestimmten Reports handelt es sich um proprietäre Formate während andere Reports sich an gängige Standards oder Anforderungen halten (z.B. DSGVO Verarbeitungsverzeichnis).