REST-Schnittstelle

Mit dem Systemtyp REST-Schnittstelle holt DDM Dokumente aus einem System, das sie über eine HTTP-Schnittstelle anbietet – ein DMS, ein PIM, ein Shop, eine eigene Anwendung. Anders als bei SharePoint oder FTP kennt DDM den Aufbau dieser Schnittstelle nicht. Sie beschreiben ihn in einer Request-Kette: welche Adressen DDM aufruft, wo in der Antwort die Liste der Dokumente steht und welcher Wert was bedeutet.

Das klingt technischer als die anderen Quellen – und ist es auch. Rechnen Sie mit jemandem, der die Schnittstelle kennt und ihre Dokumentation zur Hand hat.

Was die Schnittstelle können muss

DDM braucht von ihr zwei Dinge:

1. Eine Liste der Dokumente als JSON (oder XML) – mit mindestens einem Namen und einer Adresse, unter der die Datei liegt.
2. Die Datei selbst unter dieser Adresse, abrufbar mit einem einfachen GET.

Angemeldet wird mit einem festen Header, z. B. einem API-Token. Eine Anmeldung, die erst ein Token holt, lässt sich als eigener Schritt abbilden – siehe Beispiel 3.

1. Quelle anlegen

Legen Sie unter Einstellungen › Externe Quellen mit Neue Quelle eine Quelle an, geben Sie ihr einen Namen und wählen Sie als Systemtyp REST-Schnittstelle.

DDM schickt diesen Header nur an die Basis-URL – genauer: an Adressen mit demselben Protokoll, Host und Port. Ruft ein Schritt eine andere Adresse auf oder liegt eine Datei auf einem anderen Server, geht der Header dort nicht mit.

Klicken Sie auf Verbindung testen. DDM ruft die Basis-URL mit GET und dem Header auf.

2. Die Request-Kette verstehen

Unter Request-Kette & Feld-Zuordnung legen Sie mit + Schritt einen oder mehrere Schritte an. Jeder Schritt ist ein Aufruf der Schnittstelle. Die Schritte laufen nacheinander:

• Ein Schritt kann über eine Liste in seiner Antwort iterieren – für jeden Eintrag läuft der nächste Schritt einmal.
• Ein Schritt kann Werte als Variablen an die folgenden weitergeben, z. B. die ID eines Ordners.
• Eine Feld-Zuordnung sagt, welcher Wert der Antwort welche Angabe eines Dokuments ist: Name, Datei-URL, Kategorie …

Am Ende entsteht aus jedem Eintrag des letzten Schritts, der Einträge geliefert hat, ein Dokument – sofern es einen Namen und eine Datei-URL hat.

Ein Schritt

Mit den Pfeilen Nach oben / Nach unten ändern Sie die Reihenfolge.

Pfad und Basis-URL

Der Pfad eines Schritts hängt immer unter der Basis-URL – ob er mit / beginnt oder nicht:

Anders die Datei-URL eines Dokuments: Sie kommt aus der Antwort Ihrer Schnittstelle und wird gelesen wie ein Link. Liefert die Schnittstelle /dateien/4711, lädt DDM https://dms.firma.de/dateien/4711 – vom Server aus, nicht unter /api/v1. So meinen Schnittstellen solche Adressen.

Pfade in der Antwort

Wo ein Wert steht, geben Sie als Pfad mit Punkten an – kein JSONPath, kein XPath:

{
  "data": {
    "items": [
      { "id": 4711, "title": "Preisliste 2026", "file": { "url": "/files/4711" }, "tags": ["vertrieb"] }
    ]
  }
}

Pfade in Variablen und Feld-Zuordnungen gelten immer für einen Eintrag der iterierten Liste, nicht für die ganze Antwort.

Variablen

Unter Variablen für Folgeschritte legen Sie mit + Variable einen Variablennamen und einen JSON-Pfad fest. In jedem späteren Schritt setzen Sie den Wert mit {{name}} ein – im Pfad, im Header oder im Body:

• Pfad: ordner/{{ordnerId}}/dateien
• Header: Authorization: Bearer {{token}}
• Body: { "ordner": "{{ordnerId}}" }

DDM setzt die Werte passend ein: im Pfad URL-kodiert, im Body je nach Inhalt als JSON- oder XML-Text. Ein Variablenname darf nur Buchstaben ohne Umlaute, Ziffern, _, . und - enthalten. Unter Eingangs-Variablen sieht jeder Schritt, welche Variablen die früheren liefern; eine, die er verwendet, ist hervorgehoben.

Ein Pfad, der nur aus einer Variablen besteht und eine vollständige Adresse enthält – {{naechsteSeite}} –, wird unverändert aufgerufen.

Feld-Zuordnung

Unter Feld-Zuordnung (JSON → Attribut) ordnen Sie mit + Zuordnung einen Pfad einer Angabe des Dokuments zu:

Zuordnungen in früheren Schritten gelten für alle Einträge, die darunter entstehen. So kann z. B. Schritt 1 den Kategorie-Pfad aus dem Ordnernamen liefern und Schritt 2 Name und Datei-URL der Dateien darin.

Transformationen

Jede Variable und jede Zuordnung kann den Wert umformen, bevor er verwendet wird:

Neben jeder Zeile zeigt eine Vorschau, was aus dem ersten Eintrag der Beispiel-Antwort wird.

3. Kette testen

Klicken Sie auf Kette testen (oder bei einem einzelnen Schritt auf Testen). DDM ruft die Schritte auf, ohne etwas zu importieren, und zeigt

• je Schritt einen Status: ok, fehlgeschlagen, übersprungen, nicht erreichbar, abgelehnt, weitergeleitet oder Adresse gesperrt,
• unter Beispiel-Antwort die Antwort des Schritts (die ersten 20 000 Zeichen) – Grundlage für die Vorschauen,
• wie viele Datensätze entstanden sind,
• im Import-Umfang unter Struktur-Vorschau, welcher Pfad in welche Kategorie käme,
• unter Gruppen-Zuordnung die erkannten Gruppen.

Schlägt ein Schritt fehl (HTTP-Status ab 400 oder keine Antwort), hält die Kette an, und die folgenden Schritte stehen auf übersprungen. Unter dem fehlgeschlagenen Schritt steht, was zurückkam – der Status und der Anfang der Antwort, etwa die Fehlermeldung der Schnittstelle. Die Beispiel-Antwort behält dabei die letzte erfolgreiche Antwort, damit die Vorschauen nicht verloren gehen. Die Beispiel-Antwort können Sie auch von Hand einfügen – etwa aus der Dokumentation der Schnittstelle –, um Zuordnungen vorzubereiten, bevor die Verbindung steht.

Steht die Kette, gleichen Sie im Import-Umfang einmal mit Jetzt synchronisieren ab und schalten Quelle aktiv ein – siehe Überblick.

Beispiele

Beispiel 1: Eine Liste, ein Aufruf

Die Schnittstelle liefert unter GET /dokumente:

{ "items": [ { "id": "4711", "titel": "Preisliste.pdf", "url": "/dateien/4711", "ordner": "Vertrieb/Preise" } ] }

Schritt 1 – „Dokumente": GET dokumente, Liste iterieren über items.

Beispiel 2: Erst die Ordner, dann ihre Dateien

GET /ordner liefert die Ordner, GET /ordner/{id}/dateien die Dateien eines Ordners.

Schritt 1 – „Ordner": GET ordner, Liste iterieren über items.

• Variable id = id
• Zuordnung name → Kategorie-Pfad

Schritt 2 – „Dateien": GET ordner/{{id}}/dateien, Liste iterieren über dateien.

• Zuordnungen titel → Dokumentname, url → Datei-URL, dateiId → Fremd-ID

Schritt 2 läuft einmal je Ordner aus Schritt 1; jede Datei bekommt den Kategorie-Pfad ihres Ordners.

Beispiel 3: Erst anmelden, dann abrufen

Die Schnittstelle gibt nach POST /auth/token ein kurzlebiges Token zurück:

{ "access_token": "eyJhbGc…", "expires_in": 3600 }

Schritt 1 – „Anmelden": POST auth/token, Body:

{ "client_id": "ddm", "client_secret": "…" }

• Variable token = access_token
• Liste iterieren über: leer

Schritt 2 – „Dokumente": GET dokumente, Header Authorization: Bearer {{token}}, Liste iterieren über items, Zuordnungen wie in Beispiel 1.

Die heruntergeladenen Dateien bekommen nur den Header aus Authentifizierung (Header) – nicht das Token aus Schritt 1. Verlangt Ihr Server auch für die Dateien das Token, muss die Datei-URL selbst den Zugang enthalten (etwa eine signierte Adresse), oder der Server muss Dateien mit dem festen Header ausliefern.

Gruppen-Zuordnung

Liefert Ihre Schnittstelle zu jedem Dokument eine Gruppe – eine Abteilung, eine Rolle, eine Kundengruppe –, kann DDM daraus Leserechte machen:

1. Ordnen Sie in der Kette den Pfad der Gruppe dem Attribut Externe Gruppe zu.
2. Klicken Sie auf Kette testen. Unter Gruppen-Zuordnung erscheinen die erkannten Gruppen.
3. Klicken Sie auf eine erkannte Gruppe (oder auf + Zuordnung und tippen Sie ihren Namen) und wählen Sie die DDM-Gruppe, die sie bekommt.

Beim Abgleich bekommt jedes Dokument Leserecht für die DDM-Gruppe, die seiner externen Gruppe zugeordnet ist – zusätzlich zu den Rechten seiner Kategorie. Groß- und Kleinschreibung zählen dabei nicht.

• Ohne Zuordnung, mit Keine Gruppe oder bei ausgeschalteter Zuordnung aktiv vergibt der Import für diese Gruppe keine Rechte.
• Jedes Dokument kann eine externe Gruppe haben.
• Der Import vergibt Rechte nur, er entzieht keine. Ändert sich die Gruppe eines Dokuments in Ihrem System, behält die alte DDM-Gruppe ihr Leserecht – entziehen Sie es bei Bedarf am Dokument.

Grenzen

Weiterleitungen (HTTP 3xx) folgt DDM nicht – tragen Sie die Zieladresse direkt ein.

Eine Blätterfunktion (Pagination) gibt es nicht eingebaut: Jeder Schritt läuft einmal je Eintrag des vorigen, nicht „bis nichts mehr kommt". Liefert Ihre Schnittstelle Seiten, fragen Sie möglichst große Seiten ab (z. B. ?limit=200), oder bilden Sie eine feste Zahl von Seiten als eigene Schritte ab – etwa mit der Variablen {{naechsteSeite}} aus der Antwort der ersten Seite als Pfad des zweiten Schritts. Wird die Höchstzahl an Aufrufen erreicht, meldet der Test Abgebrochen bei der Höchstzahl an Aufrufen …; teilen Sie die Quelle dann auf.