Ein Integrationsbriefing am Berichtsauftrag ausfüllen
Füllen Sie Umfang, Beispieldaten, Rückmeldungen und Abnahmefälle für eine Verbindung zwischen Projektportal und Dokumentendienst aus.
Beschreiben Sie ein Integrationsvorhaben an einem vollständigen Ablauf, bevor Sie Angebote vergleichen. „Das Portal braucht eine API-Anbindung“ lässt offen, welche Daten übertragen werden, wann der Auftrag erledigt ist und wer einen Fehler bearbeitet. Ein ausgefülltes Briefing macht diese Entscheidungen besprechbar.
Einen Ablauf für die erste Lieferung festlegen
Im folgenden fiktiven Projekt soll ein Portal einen monatlichen PDF-Bericht bei einem Dokumentendienst anfordern. Alle Namen, Felder und Antworten sind eigene Beispiele, keine Anbieter-API.
Briefingfeld | Ausgefüllte Vereinbarung |
|---|---|
Ziel | Ein berechtigter Projektmitarbeiter kann den angeforderten Monatsbericht im Portal herunterladen. |
Quelle | Das Projektportal liefert Projekt, bestätigten Berichtsmonat und freigegebene Vorlagenkennung. Das Portalteam verantwortet diese Auswahl. |
Zielsystem | Der Dokumentendienst erstellt die PDF-Datei. Sein Plattformteam verantwortet Verarbeitung und Fehlerstatus. |
Auslöser | Eine ausdrückliche Anforderung im Portal; kein Auftrag bei jedem Seitenaufruf. |
Lieferumfang | Auftrag anlegen, Zustand abfragen und fertige Datei abrufen. |
Ausgenommen | E-Mail-Versand und Übernahme sämtlicher historischer Berichte. |
Damit lässt sich auch ein Zusatzwunsch einordnen: Eine spätere E-Mail-Funktion wäre ein eigener Arbeitsschritt mit eigener Fehlerbehandlung. Sie verschwindet nicht im Wort „Anbindung“.
Eingaben mit Werten und Bedeutung angeben
Für POST /report-jobs wird dieser Beispielinhalt vereinbart:
{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}Die Anfragekennung bezeichnet diesen Erstellungswunsch. Projekt und Vorlage sind stabile Referenzen; der Zeitraum ist hier ein Kalendermonat im Format Jahr–Monat. Anzeigenamen oder ein frei formulierter Zeitraum ersetzen diese Werte nicht. Welche Vorlagen freigegeben sind, muss das Portal mit dem Dokumentendienst klären.
Der Zugriff wird für Auftrag, Status und Datei auf das berechtigte Projekt begrenzt. Ein bekannter Link allein erlaubt keinen Download. In das Briefing gehören Rollen und Zugriffsverfahren; echte Tokens und Passwörter bleiben außerhalb des Dokuments.
Annahme und Ergebnis getrennt beschreiben
Nach dauerhafter Aufnahme antwortet der Beispieldienst mit HTTP 202 und Location: /report-jobs/J-52:
{"jobId":"J-52","status":"queued"}MDN beschreibt 202 als Annahme einer noch nicht abgeschlossenen Verarbeitung. Im eigenen Vertrag gibt es deshalb queued (wartend), running (in Bearbeitung), succeeded (erfolgreich) und failed (fehlgeschlagen). Erfolgreich ist der Auftrag erst, wenn die Datei erstellt und zum Abschlusszeitpunkt berechtigt abrufbar ist. Microsoft beschreibt für asynchrone Arbeit einen getrennten Statusabruf; die konkreten Zustandsnamen hier sind unsere Festlegung.
Dieselbe Anfragekennung mit identischem Inhalt im selben berechtigten Umfang verweist auf denselben Auftrag. Bei abweichendem Inhalt wird im Beispiel HTTP 409 vereinbart. Diese Wiederholungsregel muss implementiert und geprüft werden; der Feldname allein schafft keine Idempotenz.
Vier Abnahmefälle vor der Umsetzung ausfüllen
Fall | Erwartetes Ergebnis |
|---|---|
Gültige Anforderung | Aufnahme, sichtbarer Verlauf und schließlich ein abrufbarer Bericht zum vereinbarten Projekt und Monat. |
Vorlagenkennung fehlt | HTTP |
Antwort auf eine angenommene Anforderung geht verloren | Wiederholung mit gleichem Inhalt und gleicher Anfragekennung findet den vorhandenen Job; kein zweiter Berichtslauf. |
Vorlage wird nach der Annahme entfernt | Verarbeitung endet mit |
Im letzten Fall prüft das Plattformteam die Vorlage. Eine korrigierte neue Anforderung bekommt eine neue Anfragekennung; der fehlgeschlagene Vorgang bleibt nachvollziehbar. Ist nur der Statusabruf gestört, zeigt das Portal einen unbekannten aktuellen Zustand und behauptet weder Erfolg noch Fehlschlag.
Offene Betriebsfragen vor einer Zusage klären
Ergänzen Sie erwartete Auftragsmenge, typische Dateigröße, zulässige Wartezeit, Abrufintervall sowie Aufbewahrung von Dateien und Statusdaten anhand des tatsächlichen Einsatzes. Diese Werte sind im Beispiel noch offen und müssen vor einer belastbaren Zusage geklärt werden. Eine geschätzte Dauer wird nicht als gemessene Eigenschaft übernommen.
Eine OpenAPI-Beschreibung kann Operationen, Eingaben und erwartete Antworten präzisieren. Die fachliche Ergebnisdefinition und die Teamzuständigkeiten müssen zusätzlich feststehen. Mit den ausgefüllten Fällen können Portal- und Plattformteam anschließend dieselbe Lieferung beurteilen.
Quellen
Weiterlesen
Alle Beiträge
Schnittstellen & Integration mit ASES
ERP, CRM und Shop sauber verbunden