Metadata Upload/Download

Zur Integration bzw. zum Austausch von Daten mit anderen Applikationen wird das Importieren und Exportieren von ganzen Modellen bzw. das Erzeugen von Reports in unterschiedlichen, gängigen Formaten unterstützt.

Hinweis

In den nachfolgenden Beispielen werden zur Veranschaulichung der Server https://www.myserver.com und die Datenbank test sowie das Modell MyModel verwendet (z.B. im Pfad https://www.myserver.com/api/test/schemes/MyModel). Der Server und die Datenbank sowie das Modell sind in allen echten Aufrufen entsprechend zu ersetzen. Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/api/test/schemes/MyModel).

Das Upload-API und Download-API über HTTP sind nach dem REST Paradigma für Softwarearchitektur erstellt.

Metamodell

Das Metamodell dokumentiert alle Eigenschaften und Beziehungen der Metadatenobjekte und bildet die Grundlage für das Upload/Download-API. Das Metamodell ist in der Datenbank meta unter folgender URL erreichbar:

https://www.myserver.com/web/meta

Hinweis

Die Datenbank meta kann in der Admin-Konsole (https://www.myserver.com/web/admin) erzeugt werden.

Modelle

Folgende Modelle können per Upload-API importiert bzw. per Download-API exportiert werden:

Geschäftsobjektmodell
Referenzdatenmodell
Kennzahlenkatalog
Datenkatalog
Qualitätsmodell
Datentypmodell
Datenmodell
Systemkatalog
Verarbeitungsverzeichnis
Projektverzeichnis

Hinweis

Zusätzlich zu diesen Modellen können die DX Organisation (einschließlich aller Personen, Gruppen, usw.) und der Mandant ebenfalls importiert bzw. exportiert werden.

Upload-API

Das Upload-API ist eine Programmierschnittstelle, mit welcher (analog zum Upload in der Benutzeroberfläche) Metadaten importiert werden können:

Die Properties richten sich nach dem jeweiligen Modell, für welches Metadaten importiert werden.
Die zu importierenden Metadaten können in verschiedenen Formaten bereitgestellt werden.

Funktionsweise

Achtung

Ab Version 3 wird die Option agentId bei der Bestimmung obsoleter Metadatenobjekte berücksichtigt sowie die Option onDelete auch auf untergeordnete obsolete Metadatenobjekte angewendet.

Das Upload-API führt einen Abgleich mit den bereits vorhandenen Metadatenobjekten durch. Die Zuordnung der importierten Metadatenobjekte zu den bereits vorhandenen Metadatenobjekten erfolgt anhand deren Bezeichnungen. Über diese fachlichen Schlüssel werden die entsprechenden Metadatenobjekte ermittelt:

Falls ein Metadatenobjekt mit dieser Bezeichnung nicht vorhanden ist, wird es hinzugefügt.
Falls ein Metadatenobjekt mit dieser Bezeichnung bereits vorhanden ist, werden die relevanten Properties geändert.
- Es werden nur jene Properties geändert, die mit einem Inhalt angeliefert werden.
  - Properties, die nicht angeliefert werden, bleiben unverändert.
- Falls kundenspezifische Custom-Properties in der Datenbank konfiguriert sind, werden diese ebenfalls importiert.
- Die neue Version ist in der Versionshistorie ersichtlich.

Hinweis

Aufgrund der beschriebenen Funktionsweise ist das Umbenennen von Metadatenobjekten über das Upload-API nicht möglich. Stattdessen können Metadatenobjekte entweder über das Metadata REST/API oder direkt in der Benutzeroberfläche umbenannt werden.

Das Upload-API unterstützt die Modi Nur hinzufügen oder ändern, Elemente abgleichen und Modell abgleichen.

`Nur hinzufügen oder ändern` (`ADD`)

Alle importierten Metadatenobjekte werden im Modell hinzugefügt oder geändert (siehe oben).
- Falls die Option onInsert definiert ist, werden hinzugefügte Metadatenobjekte auf den angegebenen Status gesetzt. Falls die Option onUpdate definiert ist, werden geänderte Metadatenobjekte auf den angegebenen Status gesetzt.
Bereits vorhandene Metadatenobjekte, die im Modell nicht importiert werden, werden nicht geändert.

`Elemente abgleichen` (`REPLACE`)

Alle importierten Metadatenobjekte werden im Modell hinzugefügt oder geändert (siehe oben).
- Falls die Option onInsert definiert ist, werden hinzugefügte Metadatenobjekte auf den angegebenen Status gesetzt. Falls die Option onUpdate definiert ist, werden geänderte Metadatenobjekte auf den angegebenen Status gesetzt.
Bereits vorhandene Metadatenobjekte, die im Modell nicht importiert werden, gelten als obsolet (siehe auch Option agentId), falls ihr übergeordnetes Metadatenobjekt importiert wurde.
- Obsolete Metadatenobjekte werden aus dem Modell gelöscht oder, falls die Option onDelete definiert ist, auf den angegebenen Status gesetzt.
Bereits vorhandene Metadatenobjekte, die im Modell nicht importiert werden, gelten nicht als obsolet und werden nicht geändert, falls ihr übergeordnetes Metadatenobjekt nicht importiert wurde.

Erklärung

Bei jedem importierten Metadatenobjekt werden die untergeordneten Metadatenobjekte vollständig abgeglichen:

Alle importierten untergeordneten Metadatenobjekte werden im Modell hinzugefügt oder geändert (siehe oben).
Bereits vorhandene untergeordnete Metadatenobjekte, die im Modell nicht importiert wurden, gelten als obsolet.
- Obsolete untergeordnete Metadatenobjekte werden aus dem Modell gelöscht oder, falls die Option onDelete definiert ist, auf den angegebenen Status gesetzt.

`Modell abgleichen` (`FULL_LOAD`)

Alle importierten Metadatenobjekte werden im Modell hinzugefügt oder geändert (siehe oben)
- Falls die Option onInsert definiert ist, werden hinzugefügte Metadatenobjekte auf den angegebenen Status gesetzt. Falls die Option onUpdate definiert ist, werden geänderte Metadatenobjekte auf den angegebenen Status gesetzt.
Bereits vorhandene Metadatenobjekte, die im Modell nicht importiert werden, gelten als obsolet (siehe auch Option agentId).
- Obsolete Metadatenobjekte werden aus dem Modell gelöscht oder, falls die Option onDelete definiert ist, auf den angegebenen Status gesetzt.

Tooltipp

Der Modus wird beim Aufruf mit der Option operation sowie mit onInsert, onUpdate und onDelete definiert.

Optionen

Das Upload-API für ein Modell wird mit folgender URL aufgerufen:

https://www.myserver.com/api/test/schemes/MyModel/upload

Die Daten werden als multipart/form-data übertragen. Die Optionen werden als Query-Parameter in der URL übergeben.

Das HTTP-Header Attribut Content-Disposition definiert den Parameter name, um die Daten zu beschreiben und das Format zu bestimmen, sowie den optionalen Parameter filename, welcher den ursprünglichen Dateinamen der übermittelten Datei enthält.

Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datentypen.json"

Die Dateierweiterung des Parameters name im HTTP-Header Attribut Content-Disposition bestimmt das Format der Daten.

Dateierweiterung	Format	Internet Media Type
`.xlsx`	XLSX (Microsoft Excel)	`multipart/form-data`
`.zip`	Siehe Option `format`	`multipart/form-data`
`.xml`	XML	`multipart/form-data`
`.json`	JSON	`multipart/form-data`
`.ddl`, `.sql`	DDL/SQL	`multipart/form-data`

Hinweis

Falls die Dateierweiterung .zip ist, wird das Format der Daten mit der Option format definiert. In allen anderen Fällen wird die Option format ignoriert und das Format der Daten ausschließlich anhand der Dateierweiterung bestimmt.

gzip

Die Daten können mit gzip komprimiert übertragen werden. Die Dateierweiterung des Parameters name im HTTP-Header Attribut Content-Disposition muss in diesem Fall die ursprüngliche Dateierweiterung (.xlsx, .zip, .xml, .json, .ddl oder .sql) gefolgt von der Dateierweiterung .gz enthalten.

Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json.gz"; filename="Datentypen.json.gz"

Nach der Übertragung wird die Datei automatisch entpackt und verarbeitet. Das Format der Daten wird anhand der ursprünglichen Dateierweiterung (bzw. der Option format) bestimmt.

Hinweis

Die Komprimierung mit gzip wird nur unterstützt, wenn das Upload-API asynchron aufgerufen wird.

Option `v`

Die Option v definiert die Version des Upload-API.

`v`	Version	Beschreibung
`2`	Version 2
`3` (default)	Version 3	Siehe Optionen `onDelete` und `agentId`.

/upload?v=3&agentId=SalesProd

Option `format`

Die Option format definiert das Format der Daten, falls die Dateierweiterung .zip ist. Ansonsten wird das Format anhand der Dateierweiterung des Parameters name im HTTP-Header Attribut Content-Disposition bestimmt.

`format`	Dateierweiterung	Format	Internet Media Type
	`.xlsx`	XLSX (Microsoft Excel)	`multipart/form-data`
`CSV` (default)	`.zip`	CSV (Gezippt)	`multipart/form-data`
	`.xml`	XML	`multipart/form-data`
	`.json`	JSON	`multipart/form-data`
	`.ddl`, `.sql`	DDL/SQL	`multipart/form-data`
`XSD`	`.zip`	XSD (Gezippt)	`multipart/form-data`
`JSON_SCHEMA`	`.zip`	JSON Schema (Gezippt)	`multipart/form-data`

/upload?format=CSV
/upload?format=XSD
/upload?format=JSON_SCHEMA

Hinweis

Falls die Dateierweiterung .zip ist jedoch die Option format nicht definiert ist, werden die Daten standardmäßig als CSV (Gezippt) hochgeladen.

Option `operation`

Die Option operation definiert, ob bereits vorhandene Metadatenobjekte, die im Modell nicht importiert werden, als obsolet gelten.

Hinweis

Ab Version 3 wird die Option agentId bei der Bestimmung obsoleter Metadatenobjekte berücksichtigt.

`operation`	Modus
`ADD` (default)	`Nur hinzufügen oder ändern`
`REPLACE`	`Elemente abgleichen`
`FULL_LOAD`	`Modell abgleichen`

/upload?operation=ADD
/upload?operation=REPLACE
/upload?operation=FULL_LOAD

Option `onInsert`

Die Option onInsert definiert, ob hinzugefügte Metadatenobjekte auf einen angegebenen Status gesetzt werden.

`onInsert`	Beschreibung
	Hinzugefügte Metadatenobjekte werden auf den Anfangsstatus des zugewiesenen Workflows gesetzt.
`<STATUS>`	Hinzugefügte Metadatenobjekte werden auf den Status `<STATUS>` gesetzt.

/upload?operation=REPLACE&onInsert=WORKING

Hinweis

Ein Status, der in den importierten Daten explizit übergeben wird, übersteuert die Option onInsert sowie den Anfangsstatus des zugewiesenen Workflows, und wird beim hinzugefügten Metadatenobjekt gesetzt.

Option `onUpdate`

Die Option onUpdate definiert, ob geänderte Metadatenobjekte auf einen angegebenen Status gesetzt werden.

`onUpdate`	Beschreibung
	Geänderte Metadatenobjekte werden auf keinen neuen Status gesetzt.
`<STATUS>`	Geänderte Metadatenobjekte werden auf den Status `<STATUS>` gesetzt.

/upload?operation=REPLACE&onUpdate=SUBMITTED

Hinweis

Ein Status, der in den importierten Daten explizit übergeben wird, übersteuert die Option onUpdate, und wird beim geänderten Metadatenobjekt gesetzt.

Option `onDelete`

Die Option onDelete definiert, ob obsolete Metadatenobjekte gelöscht oder auf einen angegebenen Status gesetzt werden.

Hinweis

Ab Version 3 wird die Option agentId bei der Bestimmung obsoleter Metadatenobjekte berücksichtigt.

`onDelete`	Beschreibung
	Obsolete Metadatenobjekte werden gelöscht.
`<STATUS>`	Obsolete Metadatenobjekte werden auf den Status `<STATUS>` gesetzt.

Achtung

In Version 2 wird nur der Status des obsoleten Metadatenobjekts auf <STATUS> gesetzt. Der Status seiner untergeordneten Metadatenobjekte wird nicht geändert.

Ab Version 3 wird der Status aller seiner untergeordneten Metadatenobjekte hierarchisch ebenfalls auf <STATUS> gesetzt.

/upload?v=3&operation=REPLACE&onDelete=INACTIVE
/upload?operation=FULL_LOAD&onDelete=REJECTED

Option `dryRun`

Die Option dryRun definiert, ob der Upload als Probelauf durchgeführt wird, jedoch ohne Daten tatsächlich zu ändern. Wenn der Probelauf fertig ist können die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

`dryRun`	Beschreibung
`true`	Probelauf durchführen, ohne Daten tatsächlich zu ändern.
`false` (default)	Upload durchführen.

/upload?dryRun=true
/upload?operation=REPLACE&dryRun=false
/upload?operation=FULL_LOAD&onDelete=INACTIVE&dryRun=true

Option `agentId`

Die Option agentId definiert die Identifikation des Agenten. Die Agenten-Identifikation ist eine beliebige Zeichenfolge, die den Software-Agenten, der das Upload-API aufruft, eindeutig identifiziert. Die Agenten-Identifikation ermöglicht es, die Herkunft von importierten Metadatenobjekten zu verfolgen.

Hinweis

Die Option agentId wird ab Version 3 unterstützt.

`agentId`	Beschreibung
`<ID>`	Die Agenten-Identifikation `<ID>` wird zu jedem importieren Metadatenobjekt gespeichert, d.h. der Agent mit der Identifikation `<ID>` wird als Eigentümer der importierten Metadatenobjekte gekennzeichnet. Die Agenten-Identifikationen aller importierten Metadatenobjekte werden überschrieben, selbst wenn diese Metadatenobjekte zuvor von anderen Agenten importiert wurden.
	Die Agenten-Identifikation der importierten Metadatenobjekte wird nicht geändert oder gelöscht.

Hinweis

Beim händischen Anlegen oder Importieren von Metadatenobjekten in der Benutzeroberfläche wird keine Agenten-Identifikation gesetzt. Die Agenten-Identifikation von Metadatenobjekten, die zuvor von anderen Agenten importiert wurden, wird daher nicht geändert oder gelöscht.

Bei der Bestimmung obsoleter Metadatenobjekte (Elemente abgleichen und Modell abgleichen) werden nur Metadatenobjekte berücksichtigt, welche die gleiche Agenten-Identifikation wie die Option agentId haben (oder, falls die Option agentId nicht gesetzt ist, keine Agenten-Identifikation haben). Bereits vorhandene Metadatenobjekte, die nicht importiert werden, gelten nur dann als obsolet, wenn sie zuvor vom gleichen Agenten importiert wurden.

Tooltipp

Die Agenten-Identifikation ermöglicht es verscheidenen Agenten, Metadatenobjekte aus unterschiedlichen Quellen zu importieren (z.B. in das gleiche Modell oder in die gleiche Sammlung), ohne sich ihre Metadatenobjekte gegenseitig zu löschen oder zu inaktivieren.

Es wird verhindert, dass ein Agent versehentlich Metadaten, die einem anderen Agenten gehören oder die manuell über die Benutzeroberfläche angelegt wurden, löscht oder deaktiviert.

/upload?agentId=SalesProd

Tooltipp

Die Identifikation des Agenten wird gegebenenfalls beim Status des importierten Metadatenobjekts angezeigt.

Option `agentName`

Die Option agentName definiert den Namen des Agenten, der das Upload-API aufruft.

/upload?agentId=SalesProd&agentName=DatabaseConnector

Tooltipp

Der Name des Agenten wird gegebenenfalls im Dashboard als Bezeichnung des Jobs angezeigt.

Option `ignoreUnknownAnnotations`

Die Option ignoreUnknownAnnotations definiert, ob importierte Annotationen (kundenspezifische Stereotypen oder Properties), die im Modell nicht verfügbar sind, gelöscht werden oder zu einer Fehlermeldung führen.

`ignoreUnknownAnnotations`	Beschreibung
`true`	Importierte Annotationen, die im Modell nicht verfügbar sind, werden gelöscht.
`false` (default)	Importierte Annotationen, die im Modell nicht verfügbar sind, führen zu einer Fehlermeldung.

/upload?ignoreUnknownAnnotations=true

Tooltipp

Kundenspezifische Stereotypen und Properties werden typischerweise in Profilen definiert und Modellen zugeordnet. Die Option ignoreUnknownAnnotations ermöglicht es, Metadaten zu importieren, die kundenspezifische Stereotypen oder Properties enthalten, selbst wenn das entsprechende Profil noch nicht dem Modell zugeordnet wurde. Die unbekannten Annotationen werden gelöscht.

Sprache

Das HTTP-Header Attribut Accept-Language definiert die Sprache des Formats XLSX (Microsoft Excel), welches mit Tabellennamen und Überschriften in unterschiedlichen Sprachen importiert werden kann (z.B. Sammlungen oder Collections, Schreibgeschützt oder Read-only).

`Accept-Language`	Sprache
	Standardsprache des Servers
`de`	Deutsch
`en`	Englisch

Accept-Language: de
Accept-Language: en

Achtung

Falls die importierte Datei eine andere Sprache als die Standardsprache des Servers hat, muss die Sprache explizit angegeben werden. Ansonsten können die erwarteten Tabellennamen und Überschriften nicht erkannt und korrekt zugeordnet werden, wodurch die Metadaten nicht importiert oder möglicherweise falsch abgeglichen werden.

HTTP-Methoden

Die HTTP-Methode PUT bzw. POST definiert, dass das Upload-API synchron bzw. asynchron aufgerufen wird.

HTTP‑Methode	Beschreibung
`PUT`	Das Upload-API wird synchron aufgerufen. Der Aufruf wartet, bis der Upload vollständig durchgeführt ist, und gibt danach die Statistik oder eine Fehlermeldung zurück.
`POST`	Das Upload-API wird asynchron aufgerufen. Der Aufruf startet einen Job, der im Hintergrund läuft und den Upload durchführt. Wenn der Job fertig ist können die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Aufruf

Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet. Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.

Hinweis

Aus Gründen der Übersichtlichkeit sind die HTTP-Nachrichten in den Beispielen vereinfacht oder verkürzt dargestellt.

Hinweis

Für die Aufrufe sind Zugangsdaten (z.B. <user> und <password>) erforderlich. Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.

Der entsprechende Benutzer muss erfasst und als Administrator berechtigt sein.

Upload-API (synchron)

Das Upload-API kann mit der HTTP-Methode PUT aufgerufen werden, um den Upload synchron durchzuführen. Der Inhalt einer Datei kann mit der Option -F als multipart/form-data übertragen werden.

curl -X PUT -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/schemes/MyModel/upload"

Der Aufruf wartet, bis der Upload vollständig durchgeführt ist, und gibt danach die Statistik oder eine Fehlermeldung zurück.

Beispiel: Metadaten importieren (synchron)

curl -X PUT -u jdoe:s3cr3t -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X PUT -u jdoe:s3cr3t -H "Accept-Language: de" -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X PUT -u jdoe:s3cr3t -F import.zip=@MyModel.zip   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=ADD"
curl -X PUT -u jdoe:s3cr3t -F import.xml=@MyModel.xml   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=REPLACE&dryRun=true"
curl -X PUT -u jdoe:s3cr3t -F import.json=@MyModel.json "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=FULL_LOAD&onDelete=INACTIVE"

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Das Upload-API wird mit der HTTP-Methode PUT aufgerufen, um das Modell Datentypen synchron zu importieren. Der Inhalt der Datei Datentypen.json wird als multipart/form-data mit dem Namen import.json übertragen.

curl -X PUT -u jdoe:s3cr3t -F import.json=@Datentypen.json "https://www.myserver.com/api/test/schemes/Datentypen/upload"

PUT /api/test/schemes/Datentypen/upload HTTP/1.1
Host: www.myserver.com
Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datentypen.json"

Hinweis

Das Format wird aufgrund der Dateierweiterung .json des Parameters name automatisch als JSON festgelegt.

Der Aufruf führt den Upload vollständig durch und antwortet mit der Statistik:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "level": "DEBUG",
    "message": "1 *Sammlung* verarbeitet."
  },
  {
    "level": "DEBUG",
    "message": "1 *Datentyp* verarbeitet."
  }
]

Im Fehlerfall (HTTP-Statuscode: 400) enthält die HTTP-Antwort eine Fehlermeldung:

HTTP/1.1 400
Content-Type: application/json

{
  "type": "JobExecutionException",
  "message": "Ein Fehler beim Hochladen der Datei *import.json* ist aufgetreten",
  "errors": [
    {
      "error": "DataDomain.inCollection, line: 24: Sammlung *Personen* konnte nicht gefunden werden!"
    },
    {
      "error": "DataDomain.inCollection, line: 24: *Sammlung* muss angegeben werden!"
    }
  ]
}

Upload-API (asynchron)

Das Upload-API kann mit der HTTP-Methode POST aufgerufen werden, um den Upload asynchron durchzuführen. Der Inhalt einer Datei kann mit der Option -F als multipart/form-data übertragen werden.

curl -X POST -u <user>:<password> -F <name>=@<filename> "https://www.myserver.com/api/test/schemes/MyModel/upload"

Der Aufruf startet einen Job und gibt die entsprechende Job-ID zurück. Der Job läuft im Hintergrund und führt den Upload durch. Der Status des Jobs kann mit der Job-ID gepollt werden. Wenn der Job fertig ist können die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Beispiel: Metadaten importieren (asynchron)

curl -X POST -u jdoe:s3cr3t -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X POST -u jdoe:s3cr3t -H "Accept-Language: de" -F import.xlsx=@MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/upload"
curl -X POST -u jdoe:s3cr3t -F import.zip=@MyModel.zip   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=ADD"
curl -X POST -u jdoe:s3cr3t -F import.xml=@MyModel.xml   "https://www.myserver.com/api/test/schemes/MyModel/upload?operation=REPLACE&dryRun=true"
curl -X POST -u jdoe:s3cr3t -F import.json=@MyModel.json "https://www.myserver.com/api/test/schemes/MyModel/upload&operation=FULL_LOAD&onDelete=INACTIVE"

Beispiel: Ablauf und Fehlerbehandlung (asynchron)

Das Upload-API wird mit der HTTP-Methode POST aufgerufen, um das Modell Datentypen asynchron zu importieren. Der Inhalt der Datei Datentypen.json wird als multipart/form-data mit dem Namen import.json übertragen.

curl -X POST -u jdoe:s3cr3t -F import.json=@Datentypen.json "https://www.myserver.com/api/test/schemes/Datentypen/upload"

POST /api/test/schemes/Datentypen/upload HTTP/1.1
Host: www.myserver.com
Content-Type: multipart/form-data
Content-Disposition: form-data; name="import.json"; filename="Datentypen.json"

Hinweis

Das Format wird aufgrund der Dateierweiterung .json des Parameters name automatisch als JSON festgelegt.

Der Aufruf startet einen Job und antwortet mit der Job-ID:

HTTP/1.1 200
Content-Type: application/json

{ "id":"e5b5138c-748f-42ec-a1de-26aef7cf835c" }

Mit der Job-ID kann der Status des Jobs gepollt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics HTTP/1.1
Host: www.myserver.com

Wenn der Job fertig ist (HTTP-Statuscode: 200), enthält die HTTP-Antwort den Status des Jobs COMPLETED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "INFO",
      "message": "*import.json importieren* erfolgreich (00:00:00)."
    },
    {
      "level": "DEBUG",
      "message": "1 *Sammlung* verarbeitet."
    },
    {
      "level": "DEBUG",
      "message": "1 *Datentyp* verarbeitet."
    }
  ],
  "status": "COMPLETED"
}

Im Fehlerfall enthält die HTTP-Antwort den Status des Jobs FAILED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "ERROR",
      "message": "*import.json importieren* fehlgeschlagen (00:00:00)!"
    },
    {
      "level": "ERROR",
      "message": "2 *Fehler* aufgetreten!"
    },
    {
      "level": "DEBUG",
      "message": "1 *Sammlung* verarbeitet."
    }
  ],
  "status": "FAILED"
}

Die genaue Fehlerursache kann im Protokoll abgefragt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 2,
  "data": [
    {
      "level": "ERROR",
      "message": "DataDomain.inCollection, line: 24: Sammlung *Personen* konnte nicht gefunden werden!"
    },
    {
      "level": "ERROR",
      "message": "DataDomain.inCollection, line: 24: *Sammlung* muss angegeben werden!"
    }
  ]
}

Download-API

Das Download-API ist eine Programmierschnittstelle, mit welcher (analog zum Download in der Benutzeroberfläche) Metadaten exportiert und Reports generiert werden können:

Die Properties richten sich nach dem jeweiligen Modell, für welches Metadaten exportiert werden.
Die zu exportierenden Metadaten können in verschiedenen Formaten bereitgestellt werden.

Funktionsweise

Das Download-API liest alle Metadatenobjekte des Modells und exportiert sie nach folgenden Regeln:

Es werden nur jene Properties exportiert, die einen Inhalt haben.
- Leere Properties werden nicht exportiert.
Falls kundenspezifische Custom-Properties in der Datenbank konfiguriert sind, werden diese ebenfalls exportiert.

Optionen

Das Download-API für ein Modell wird mit folgender URL aufgerufen:

https://www.myserver.com/api/test/schemes/MyModel/download

Die Optionen werden als Query-Parameter in der URL übergeben.

Option `v`

Die Option v definiert die Version des Download-API.

`v`	Version
`2`	Version 2
`3` (default)	Version 3

/download?v=3&format=JSON

Option `format`

Die Option format definiert das Format der Daten.

`format`	Dateierweiterung	Format	Internet Media Type
`XLSX`	`.xlsx`	XLSX (Microsoft Excel)	`application/x-xls`
`CSV`	`.zip`	CSV (Gezippt)	`text/csv+zip`
`XML`	`.xml`	XML	`application/xml`
`JSON`	`.json`	JSON	`application/json`
`SQL`	`.sql`	DDL/SQL	`application/sql`

/download?format=JSON
/download?format=XLSX
/download?format=SQL&targetDatabase=SQLServer

Hinweis

Der Download im Format XLSX (Microsoft Excel) darf 65.536 Zeilen nicht überschreiten.

Hinweis

Beim Format SQL muss die Option targetDatabase ebenfalls definiert sein.

Option `xsl`

Die Option xsl definiert den generierten Report.

`xsl`	Name	Internet Media Type
`DataModel_xmi.xsl`	UML Export	`application/vnd.xmi+xml`
`DataQualityReport_pdf.xsl`	Datenqualitätsreport	`application/pdf`
`Impact_pdf.xsl`	Impact Report	`application/pdf`
`Lineage_pdf.xsl`	Lineage Report	`application/pdf`
`MappingReport_csv.xsl`	Mapping Report	`text/csv`
`MappingReport_pdf.xsl`	Mapping Report	`application/pdf`
`Metadata_pdf.xsl`	Metadaten Report	`application/pdf`
`Organization_pdf.xsl`	Organisationsreport	`application/pdf`
`ProcessingRecords_pdf.xsl`	DSGVO Verarbeitungsverzeichnis	`application/pdf`
`ProjectReport_pdf.xsl`	Projekt Report	`application/pdf`
`ReferenceValues_csv.xsl`	Referenzwerte Export	`text/csv`
`SearchReport_csv.xsl`	Suchergebnisreport	`text/csv`
`SearchReport_pdf.xsl`	Suchergebnisreport	`application/pdf`
`Statistics_csv.xsl`	Sammlungsstatistik	`text/csv`
`Statistics_pdf.xsl`	Sammlungsstatistik	`application/pdf`
`TicketReport_csv.xsl`	Ticketreport	`text/csv`
`TicketReport_pdf.xsl`	Ticketreport	`application/pdf`

Tooltipp

Zusätzliche, kundenspezifische Reports im Format .xsl (XSLT) können beim Mandanten hochgeladen und bearbeitet werden. Kundenspezifische Reports können mit dem Download-API generiert werden.

/download?xsl=Metadata_pdf.xsl
/download?xsl=Statistics_csv.xsl

Hinweis

Der generierte Report darf 100 MB nicht überschreiten.

Option `targetDatabase`

Die Option targetDatabase definiert die Zieldatenbank und die konkrete SQL-Syntax beim Download mit der Option format=SQL.

`targetDatabase`	Datenbank
`PostgreSQL`	PostgreSQL
`Oracle`	Oracle
`SQLServer`	Microsoft SQL Server
`MySQL`	MySQL

/download?format=SQL&targetDatabase=PostgreSQL
/download?format=SQL&targetDatabase=Oracle

Option `language`

Die Option language definiert die Sprache des Formats XLSX (Microsoft Excel), welches mit Tabellennamen und Überschriften in unterschiedlichen Sprachen exportiert werden kann (z.B. Sammlungen oder Collections, Schreibgeschützt oder Read-only).

`language`	Sprache
	Standardsprache des Servers
`de`	Deutsch
`en`	Englisch

/download?language=de
/download?language=en

Hinweis

Alternativ kann die Sprache im HTTP-Header Attribut Accept-Language definiert werden, wird jedoch von der gegebenenfalls vorhandenen Option language überschrieben.

Accept-Language: de
Accept-Language: en

Option `publicOnly`

Die Option publicOnly definiert, ob nur veröffentlichte Metadaten oder alle Metadaten exportiert werden.

`publicOnly`	Beschreibung
`true`	Nur veröffentliche Metadaten werden exportiert.
`false` (default)	Alle Metadaten werden exportiert.

/download?publicOnly=true

Hinweis

Alternativ kann das HTTP-Header Attribut Accept-PublicOnly definiert werden, wird jedoch von der gegebenenfalls vorhandenen Option publicOnly überschrieben.

Accept-PublicOnly: true

Option `version`

Die Option version definiert einen Zeitpunkt in der Historie, um die Metadaten im Zustand zum gewählten Zeitpunkt zu exportieren.

`version`	Beschreibung
	Die Metadaten werden im aktuellsten Zustand exportiert.
Zeitstempel (Epoche) in Millisekunden	Die Metadaten werden im Zustand zum gewählten Zeitpunkt exportiert.

/download?version=1698676897000

Hinweis

Alternativ kann der Zeitstempel im HTTP-Header Attribut Accept-Version definiert werden, wird jedoch von der gegebenenfalls vorhandenen Option version überschrieben.

Accept-Version: 1698676897000

HTTP-Methoden

Die HTTP-Methode GET bzw. POST definiert, dass das Download-API synchron bzw. asynchron aufgerufen wird.

HTTP‑Methode	Beschreibung
`GET`	Das Download-API wird synchron aufgerufen. Der Aufruf wartet, bis der Download vollständig durchgeführt ist, und gibt danach die exportierten Metadaten bzw. den generierten Report oder eine Fehlermeldung zurück.
`POST`	Das Download-API wird asynchron aufgerufen. Der Aufruf startet einen Job, der im Hintergrund läuft und den Download durchführt. Wenn der Job fertig ist können die exportierten Metadaten bzw. der generierte Report heruntergeladen sowie die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Aufruf

Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet. Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.

Hinweis

Aus Gründen der Übersichtlichkeit sind die HTTP-Nachrichten in den Beispielen vereinfacht oder verkürzt dargestellt.

Hinweis

Der entsprechende Benutzer muss berechtigt sein.

Download-API (synchron)

Das Download-API kann mit der HTTP-Methode GET und der Option format aufgerufen werden, um Metadaten synchron zu exportieren.

curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?format=<format>"

Das Download-API kann mit der HTTP-Methode GET und der Option xsl aufgerufen werden, um einen Report synchron zu generieren.

curl -X GET -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=<report>"

Der Aufruf wartet, bis der Download vollständig durchgeführt ist, und gibt danach die exportierten Metadaten bzw. den generierten Report oder eine Fehlermeldung zurück.

Hinweis

Bei binären Formaten (.xlsx, .zip, .pdf) wird empfohlen, die Daten mit der Option -o in eine Datei zu speichern, anstatt sie auf die Konsole auszugeben.

Beispiel: Metadaten exportieren bzw. Report generieren (synchron)

curl -X GET -u jdoe:s3cr3t -o MyModel.xlsx "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X GET -u jdoe:s3cr3t -H "Accept-Language: de" "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X GET -u jdoe:s3cr3t -o MyModel.zip "https://www.myserver.com/api/test/schemes/MyModel/download?format=CSV"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XML"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=JSON"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=SQL&targetDatabase=PostgreSQL"

curl -X GET -u jdoe:s3cr3t -o Metadata.pdf "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl"
curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=ReferenceValues_csv.xsl"

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Das Download-API wird mit der HTTP-Methode GET und der Option format=XLSX aufgerufen, um das Modell Datentypen synchron zu exportieren. Die Ausgabe wird mit der Option -o in die Datei Datentypen.xlsx gespeichert.

curl -X GET -u jdoe:s3cr3t -o Datentypen.xlsx "https://www.myserver.com/api/test/schemes/Datentypen/download?format=XLSX"

GET /api/test/schemes/Datentypen/download?format=XLSX HTTP/1.1
Host: www.myserver.com

Der Aufruf führt den Download vollständig durch und antwortet mit den exportierten Metadaten:

HTTP/1.1 200
Content-Type: application/x-xls
Content-Disposition: filename="Datentypen.xlsx"

Im Fehlerfall (HTTP-Statuscode: 400) enthält die HTTP-Antwort eine Fehlermeldung:

HTTP/1.1 400
Content-Type: application/json

{
  "message": "Die erzeugte Microsoft Excel Datei enthält zu viele Zeilen (max. 65.536). Bitte gib Filterkriterien ein oder wähle ein anderes Export-Format!"
}

Download-API (asynchron)

Das Download-API kann mit der HTTP-Methode POST und der Option format aufgerufen werden, um Metadaten asynchron zu exportieren.

curl -X POST -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?format=<format>"

Das Download-API kann mit der HTTP-Methode POST und der Option xsl aufgerufen werden, um einen Report asynchron zu generieren.

curl -X POST -u <user>:<password> "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=<report>"

Der Aufruf startet einen Job und gibt die entsprechende Job-ID zurück. Der Job läuft im Hintergrund und führt den Download durch. Der Status des Jobs kann mit der Job-ID gepollt werden. Wenn der Job fertig ist können die exportierten Metadaten bzw. der generierten Report heruntergeladen sowie die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Hinweis

Bei binären Formaten (.xlsx, .zip, .pdf) wird empfohlen, die Daten mit der Option -o in eine Datei zu speichern, anstatt sie auf die Konsole auszugeben.

Beispiel: Metadaten exportieren bzw. Report generieren (asynchron)

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X POST -u jdoe:s3cr3t -H "Accept-Language: de" "https://www.myserver.com/api/test/schemes/MyModel/download?format=XLSX"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=CSV"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=XML"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=JSON"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?format=SQL&targetDatabase=PostgreSQL"

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl"
curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/MyModel/download?xsl=ReferenceValues_csv.xsl"

Beispiel: Ablauf und Fehlerbehandlung (asynchron)

Das Download-API wird mit der HTTP-Methode POST und der Option format=XLSX aufgerufen, um das Modell Datentypen asynchron zu exportieren.

curl -X POST -u jdoe:s3cr3t "https://www.myserver.com/api/test/schemes/Datentypen/download?format=XLSX"

POST /api/test/schemes/Datentypen/download?format=XLSX HTTP/1.1
Host: www.myserver.com

Der Aufruf startet einen Job und antwortet mit der Job-ID:

HTTP/1.1 200
Content-Type: application/json

{ "id":"e5b5138c-748f-42ec-a1de-26aef7cf835c" }

Mit der Job-ID kann der Status des Jobs gepollt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/statistics HTTP/1.1
Host: www.myserver.com

Wenn der Job fertig ist (HTTP-Statuscode: 200), enthält die HTTP-Antwort den Status des Jobs COMPLETED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "INFO",
      "message": "*Datentypen.xlsx erzeugen* erfolgreich (00:00:00)."
    },
    {
      "level": "INFO",
      "message": "10 Zeilen exportiert."
    }
  ],
  "status": "COMPLETED"
}

Im Fehlerfall enthält die HTTP-Antwort den Status des Jobs FAILED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "ERROR",
      "message": "*Datentypen.xlsx erzeugen* fehlgeschlagen (00:00:00)!"
    },
    {
      "level": "ERROR",
      "message": "1 *Fehler* aufgetreten!"
    }
  ],
  "status": "FAILED"
}

Die genaue Fehlerursache kann im Protokoll abgefragt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/logs HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "data": [
    {
      "level": "ERROR",
      "message": "Die erzeugte Microsoft Excel Datei enthält zu viele Zeilen (max. 65.536). Bitte gib Filterkriterien ein oder wähle ein anderes Export-Format!"
    }
  ]
}

Wenn der Job erfolgreich fertig ist, können die exportierten Metadaten heruntergeladen werden. Die Ausgabe wird mit der Option -o in die Datei Datentypen.xlsx gespeichert.

curl -X GET -u jdoe:s3cr3t -o "Datentypen.xlsx" "https://www.myserver.com/api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/download"

GET /api/test/jobs/e5b5138c-748f-42ec-a1de-26aef7cf835c/download HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/x-xls
Content-Disposition: filename="Datentypen.xlsx"

Metamodell​

Modelle​

Upload-API​

Funktionsweise​

Nur hinzufügen oder ändern (ADD)​

Elemente abgleichen (REPLACE)​

Modell abgleichen (FULL_LOAD)​

Optionen​

gzip​

Option v​

Option format​

Option operation​

Option onInsert​

Option onUpdate​

Option onDelete​

Option dryRun​

Option agentId​

Option agentName​

Option ignoreUnknownAnnotations​

Sprache​

HTTP-Methoden​

Aufruf​

Upload-API (synchron)​

Beispiel: Metadaten importieren (synchron)​

Beispiel: Ablauf und Fehlerbehandlung (synchron)​

Upload-API (asynchron)​

Beispiel: Metadaten importieren (asynchron)​

Beispiel: Ablauf und Fehlerbehandlung (asynchron)​

Download-API​

Funktionsweise​

Optionen​

Option v​

Option format​

Option xsl​

Option targetDatabase​

Option language​

Option publicOnly​

Option version​

HTTP-Methoden​

Aufruf​

Download-API (synchron)​

Beispiel: Metadaten exportieren bzw. Report generieren (synchron)​

Beispiel: Ablauf und Fehlerbehandlung (synchron)​

Download-API (asynchron)​

Beispiel: Metadaten exportieren bzw. Report generieren (asynchron)​

Beispiel: Ablauf und Fehlerbehandlung (asynchron)​

Metamodell

Modelle

Upload-API

Funktionsweise

`Nur hinzufügen oder ändern` (`ADD`)

`Elemente abgleichen` (`REPLACE`)

`Modell abgleichen` (`FULL_LOAD`)

Optionen

gzip

Option `v`

Option `format`

Option `operation`

Option `onInsert`

Option `onUpdate`

Option `onDelete`

Option `dryRun`

Option `agentId`

Option `agentName`

Option `ignoreUnknownAnnotations`

Sprache

HTTP-Methoden

Aufruf

Upload-API (synchron)

Beispiel: Metadaten importieren (synchron)

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Upload-API (asynchron)

Beispiel: Metadaten importieren (asynchron)

Beispiel: Ablauf und Fehlerbehandlung (asynchron)

Download-API

Funktionsweise

Optionen

Option `v`

Option `format`

Option `xsl`

Option `targetDatabase`

Option `language`

Option `publicOnly`

Option `version`

HTTP-Methoden

Aufruf

Download-API (synchron)

Beispiel: Metadaten exportieren bzw. Report generieren (synchron)

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Download-API (asynchron)

Beispiel: Metadaten exportieren bzw. Report generieren (asynchron)

Beispiel: Ablauf und Fehlerbehandlung (asynchron)