Skip to main content

DEXPRO AWF Externe Genehmigungen — SharePoint-Integrationsvertrag

Dieses Dokument beschreibt den SharePoint-Listen-Vertrag zwischen Business Central (der AWF-Erweiterung) und jedem externen System, das Genehmigungsanfragen konsumiert oder beantwortet. Er ist transportneutral: Die Referenzimplementierung verwendet Power Automate + Microsoft Teams (siehe SETUP-GUIDE.de-DE.md), aber jedes System, das SharePoint-Listenelemente über die Microsoft Graph API — oder die native SharePoint-REST-API — lesen und schreiben kann, kann teilnehmen.

Zielgruppe: Integrationsentwickler. Die Endbenutzereinrichtung ist in SETUP-GUIDE.de-DE.md beschrieben.

1. Designprinzipien

  1. Die SharePoint-Liste ist die Warteschlange. BC schreibt ein Listenelement, wenn ein externer Genehmiger entscheiden muss; der Konsument schreibt die Entscheidung in dasselbe Element zurück; der Job-Queue-Poller von BC liest sie ab.
  2. BC ist das System of Record. Das SP-Element ist transient — BC löscht es nach der Verarbeitung. Konsumenten dürfen sich nicht auf den SP-Verlauf verlassen.
  3. Stabile interne Spaltennamen. Der Spalten-name (nicht displayName) ist der Vertrag. Anzeigenamen sind lokalisiert und dürfen nicht verwendet werden.
  4. Vorwärtskompatibilität. BC schreibt einen SchemaVersion-Wert in jedes Element. Konsumenten sollten Elemente mit einer nicht unterstützten Version ablehnen / protokollieren, anstatt sie stillschweigend falsch zu verarbeiten.
  5. Idempotenz. BC berücksichtigt nur den ersten terminalen Status, den ein Konsument schreibt. Denselben Status zweimal zu schreiben ist ein No-Op.

2. Abfragemodell

  • BC führt einen Aufgabenwarteschlangenposten (Codeunit 70954832 "DXP AWF Ext. Approval Poller") in einem wiederkehrenden Intervall aus (Standard: alle 2 Minuten).
  • Der Poller ruft Elemente ab, die Processed eq false and ApprovalStatus ne 'Pending' entsprechen (serverseitiger Filter; fällt auf clientseitigen Filter zurück, wenn Graph den Filter ablehnt).
  • Für jedes übereinstimmende Element aktualisiert BC den entsprechenden AWF-Eintrag, ruft die Workflow-Engine auf, setzt dann Processed = true auf dem SharePoint-Element und versucht, es zu löschen (DELETE).
  • Schlägt DELETE fehl, reicht das Flag Processed = true aus, um das Element aus nachfolgenden Abfragen auszuschließen; verwaiste Elemente werden von CleanupOrphanedSPItems in jedem Zyklus erneut versucht.

Auswirkungen für Konsumenten: Zwischen dem Schreiben der Entscheidung und der BC-Verarbeitung liegen zwischen 0 und N Minuten (wobei N das Abfrageintervall ist). Erwarten Sie keine synchrone Bestätigung. Wenn Sie eine Rückmeldung benötigen, beobachten Sie das Processed-Feld des Elements oder dessen Verschwinden.

3. Spaltenreferenz

Jede Spalte unten verwendet den internen name — das ist der Vertrag. Anzeigenamen können lokalisiert sein.

3.1 Eingaben (BC → Konsument)

BC befüllt diese beim Erstellen des Elements. Konsumenten dürfen sie nicht ändern.

Name Typ Hinweise
SchemaVersion Text Aktuell "1". Erhöhung zeigt eine brechende Änderung in diesem Vertrag an.
BCCompanyName Text Das BC-Unternehmen, dem der Eintrag gehört. Immer bei neuen Zeilen gesetzt; darf von Konsumenten nicht geändert werden. Der unternehmensspezifische Poller von BC verwendet dies, um Elemente anderer Unternehmen zu ignorieren (siehe § 7a).
Title Text Kurze Datensatzbeschreibung (z. B. Bestellnummer). Teil der integrierten SharePoint-Spalte.
BCEntryNo Text Lfd. Nr. des AWF-Externen Genehmigungseintrags innerhalb von BCCompanyName. Nicht global eindeutig — immer mit BCCompanyName kombinieren, wenn Elemente korreliert werden.
BCApprovalEntryNo Text Lfd. Nr. des zugrundeliegenden BC-Standard-Genehmigungspostens (Tabelle 454). Identisch über alle Peer-Zeilen in einer Gruppe — nützlich zum Gruppieren von Zeilen nach ihrer zugrundeliegenden Entscheidungseinheit (z. B. Peer-Elemente stornieren, wenn einer übernimmt).
BCInstanceID Text AWF-Workflow-Instanz-GUID — global eindeutig über alle Unternehmen.
Description Text Kontextbezogene Dokumentbeschreibung (Kreditor/Debitor usw.).
ApproverEmail Text UPN / E-Mail-Adresse. Benachrichtigungen an diese Adresse weiterleiten.
ApproverDisplayName Text Für Menschen lesbarer Name.
AttachmentsUrl Text SharePoint-Freigabelink zu einem Ordner mit Dokumentanhängen. Leer, wenn der Upload deaktiviert ist oder keine Anhänge vorhanden sind.
BCDocumentUrl Text Direktlink zum Quelldatensatz in Business Central. Nützlich für BC-lizenzierte Genehmiger; nicht lizenzierte Benutzer sehen eine Anmeldeseite. Leer, wenn BC keine Kartenseiten-URL für den Datensatz ableiten konnte.
RecordDetails Mehrzeiliger Text CommonMark-Markdown-Darstellung der eigenen Felder des genehmigten Datensatzes (z. B. für eine Einkaufszeile: Art, Nr., Beschreibung, Menge, Einkaufspreis, Zeilenbetrag). Direkt in einem Adaptive-Card-TextBlock mit wrap=true darstellbar. Auf die häufigsten Verkaufs-/Einkaufskopf- und Zeilentabellen zugeschnitten; fällt für andere Tabellen auf einen generischen Feld-Walk zurück.
IsGroupApproval Boolesch true, wenn dieses Element eines von mehreren für eine übernahmebasierte Gruppengenehmigungs-Anfrage ist.
GroupCode Text Code der externen Genehmigergruppe (nur gesetzt, wenn IsGroupApproval = true).
Amount Text Formatierter Betrag (sprachabhängig).
AmountRaw Zahl Maschinenlesbarer Betrag (immer Punkt als Dezimaltrennzeichen). Hierfür gegenüber Amount bevorzugen.
DueDate Text Formatiertes Datum.
DueDateRaw Datum/Uhrzeit ISO 8601, UTC. Hierfür gegenüber DueDate bevorzugen.
CreatedRaw Datum/Uhrzeit ISO 8601, UTC. Wann das Element von BC erstellt wurde.
SenderName Text BC-Benutzer-ID des Anforderers.
StageName Text Beschreibung des Workflow-Schritts.
LblTitle … LblAlreadyHandledMsg Text Vorübersetzte UI-Zeichenfolgen und Nachrichtenvorlagen für die Sprache des Genehmigers (siehe 3.4). Die LblAlready…Msg-Spalten enthalten Nachrichtenvorlagen mit {title}- / {claimer}-Platzhaltern, die der Konsument (z. B. Power Automate) zur Laufzeit ersetzt.

3.2 Antwortfelder (Konsument → BC)

Der Konsument schreibt diese einmal, wenn eine Entscheidung getroffen wurde. Nur ApprovalStatus ist erforderlich.

Name Typ Erforderlich Hinweise
ApprovalStatus Auswahlfeld Ja Eines von Approved, Rejected, Claimed. BC-seitig Groß-/Kleinschreibung unempfindlich. SharePoint zeigt ein Dropdown mit allen gültigen Werten; der anfängliche/Standardwert ist Pending. Jeder nicht-terminale Wert wird von BC protokolliert und das Element wird in Ruhe gelassen.
ResponseComment Mehrzeiliger Text Nein Freitext, max. 2048 Zeichen auf der BC-Seite. SharePoint zeigt einen mehrzeiligen Textbereich zur Bearbeitung. Wird in BCs Genehmigungskommentarverlauf angezeigt.
ResponseDateTime Datum/Uhrzeit Nein ISO 8601 UTC über Graph, native Auswahl in SP. Wenn weggelassen, verwendet BC die aktuelle Uhrzeit.
ClaimedBy Text Ja, wenn ApprovalStatus = Claimed E-Mail des Gruppenmitglieds, das den Eintrag übernommen hat. BC schreibt diese Spalte auch in Peer-Elemente, die storniert werden, weil jemand anderes in der Gruppe zuerst übernommen hat — in diesem Fall identifiziert sie den Benutzer, der den Eintrag übernommen hat (der ApprovalStatus des SP-Elements ist dann gleichzeitig Cancelled).

Nicht schreiben: Processed, SchemaVersion, BCEntryNo, BCInstanceID oder irgendeine Lbl*-Spalte. BC besitzt diese.

3.3 BC-verwalteter Zustand

Name Typ Geschrieben von Zweck
Processed Boolesch Nur BC true, sobald BC die Antwort konsumiert hat. Der Poller schließt diese aus nachfolgenden Abrufen aus. Konsumenten müssen diese als schreibgeschützt behandeln.

3.4 Lokalisierte Beschriftungsspalten

BC übersetzt die Adaptive-Card-/UI-Beschriftungen für die Sprache des Genehmigers vor und schreibt sie als Klartext. Konsumenten können sie direkt verwenden, ohne BC oder einen Übersetzungsdienst aufzurufen.

Name Typischer englischer Wert
LblTitle Approval Request
LblApprove Approve
LblReject Reject
LblComment Comment
LblClaim Claim
LblRelease Release
LblAmount Amount
LblSender Requested by
LblDueDate Due Date
LblStage Stage
LblDescription Description
LblAttachments Approval Documents
LblOpenInBC Open in Business Central
LblDetails Details
LblAlreadyClaimedByMsg This approval ({title}) has already been claimed by {claimer}. You can safely ignore this card.
LblAlreadyHandledMsg This approval ({title}) has already been handled by another approver or cancelled in Business Central. You can safely ignore the earlier card.

4. ApprovalStatus-Zustandsautomat

       ┌─────────┐   Konsument schreibt      ┌──────────┐
       │ Pending │──────────────────────▶    │ Approved │ ─┐
       └────┬────┘                           └──────────┘  │
            │                                              │  BC-Poller
            │ Konsument schreibt                           │  liest ab,
            ▼                                              │  setzt Processed=true,
       ┌──────────┐                                        │  dann DELETE
       │ Notified │──────────────▶ Approved / Rejected ────┤
       └────┬─────┘                                        │
            │                                              │
            │ Gruppenübernahme                             │
            ▼                                              │
       ┌─────────┐                                         │
       │ Claimed │──────────────▶ Approved / Rejected ─────┘
       └─────────┘
  • Pending — von BC beim Erstellen geschrieben.
  • Notified (optional) — Konsument kann dies setzen, nachdem der Genehmiger benachrichtigt, aber noch nicht geantwortet hat. Rein informativ; BC reagiert nicht darauf.
  • Claimed — nur Gruppengenehmigungs-Anfragen. Konsument muss auch ClaimedBy setzen.
  • Approved / Rejected — terminal. Konsument kann auch ResponseComment und ResponseDateTime setzen.
  • Processed, Error, Cancelled — BC-interne terminale Zustände. Nicht schreiben.

4a. Direkt in SharePoint genehmigen (ohne Konsumentenanwendung)

Da die Liste typisierte Spalten verwendet, kann ein Mensch einen Eintrag genehmigen, indem er das Listenelement in SharePoint öffnet und bearbeitet — kein Teams, kein Power Automate, kein BC-Zugang erforderlich:

  1. Öffnen Sie die SharePoint-Genehmigungsliste im Browser.
  2. Klicken Sie auf das ausstehende Element. SharePoint öffnet das Bearbeitungsformular.
  3. Wählen Sie einen terminalen Wert aus dem ApprovalStatus-Dropdown (Anzeigename auf Deutsch: Genehmigungsstatus): Approved, Rejected oder (für Gruppengenehmigungs-Anfragen) Claimed.
  4. Geben Sie optional einen Grund in das ResponseComment-Textfeld ein (Anzeigename: Antwortkommentar).
  5. Setzen Sie optional ResponseDateTime (Anzeigename: Antwort am) (wenn leer gelassen, verwendet BC die aktuelle Uhrzeit).
  6. Klicken Sie auf Speichern.

Der Aufgabenwarteschlangen-Poller von BC liest die Änderung beim nächsten Zyklus ab (Standard: alle 2 Minuten) und verarbeitet sie durch den Genehmigungsworkflow identisch zu einem Power-Automate-Rückschreib.

Berechtigungen: Der SharePoint-Benutzer benötigt Bearbeitungsberechtigungen für die Liste. Da die Spalten Processed, SchemaVersion, BCEntryNo und Lbl* BC-eigentum sind, sollten Sie eine SharePoint-Ansicht oder Spaltenebenformatierung verwenden, um sie aus dem Bearbeitungsformular auszublenden — Benutzer benötigen nur ApprovalStatus (Genehmigungsstatus), ResponseComment (Antwortkommentar), ResponseDateTime (Antwort am) und (für Übernahme) ClaimedBy (Übernommen von).

5. Minimale Antwort-Payload

Genehmigen

PATCH /sites/{siteId}/lists/{listId}/items/{itemId}/fields HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json

{
  "ApprovalStatus": "Approved",
  "ResponseComment": "Sieht gut aus.",
  "ResponseDateTime": "2026-04-22T10:15:00Z"
}

Ablehnen

{ "ApprovalStatus": "Rejected", "ResponseComment": "Doppelte Bestellung." }

Übernehmen (Gruppengenehmigungs-Anfrage)

{ "ApprovalStatus": "Claimed", "ClaimedBy": "maria@contoso.com" }

6. Alternative: Native BC-API

Die SharePoint-Liste ist der empfohlene Integrationspunkt, da sie keine BC-Lizenzen auf der Konsumentenseite erfordert. Wenn Ihr System über einen BC-Service-to-Service-Prinzipal verfügt, können Sie SharePoint vollständig umgehen und direkt an BC senden:

  • Publisher: dexpro
  • Group: advancedWorkflow
  • Version: v1.0
  • Entity: externalApprovalEntries
  • Gebundene Aktionen: approve, reject, claim, releaseClaim, markNotified

Beispiel:

POST /api/dexpro/advancedWorkflow/v1.0/companies({id})/externalApprovalEntries({entryNo})/Microsoft.NAV.approve
{ "comment": "Sieht gut aus." }

Beide Wege — SharePoint-Rückschreib und BC-API — laufen auf demselben ProcessApprovalResponse-Codepfad zusammen und sind vollständig austauschbar.

7a. BC-Installationen mit mehreren Unternehmen

Eine einzelne SharePoint-Liste kann mehreren BC-Unternehmen dienen. Der Aufgabenwarteschlangen-Poller jedes Unternehmens läuft unabhängig in seinem eigenen Unternehmenskontext, und der serverseitige $filter des Pollers enthält fields/BCCompanyName eq '<aktuelles Unternehmen>', sodass ein Unternehmen nur seine eigenen Elemente abruft. Es gibt eine zusätzliche clientseitige Prüfung auf jeder Seite — Zeilen, deren BCCompanyName nicht mit dem aktuellen Unternehmen übereinstimmt, werden verworfen, auch wenn der serverseitige Filter umgangen wurde.

Auswirkungen für Konsumenten:

  • Behandeln Sie immer (BCCompanyName, BCEntryNo) als zusammengesetzten Schlüssel. BCEntryNo allein ist nur innerhalb eines einzelnen Unternehmens eindeutig.
  • Schreiben oder ändern Sie BCCompanyName nicht. BC setzt es bei der Elementerstellung und ändert es nie.
  • BCInstanceID (GUID) ist global eindeutig und ein sicherer Korrelationsschlüssel ohne BCCompanyName.
  • Wenn Sie einen Power-Automate-Flow aufbauen, der Elemente schreibt (z. B. eine benutzerdefinierte Aufnahme), setzen Sie BCCompanyName auf das Zielunternehmen, sonst sieht der BC-Poller Ihre Elemente nie.

 

8. Problembehandlungs-Checkliste für Integratoren

Symptom Wahrscheinliche Ursache
BC verarbeitet eine Antwort nie ApprovalStatus ist keines von Approved/Rejected/Claimed; oder der Konsument hat Processed=true geschrieben; oder AWF-Einrichtung hat SP Approvals Enabled = Nein.
Element erscheint immer wieder in Abfragen Processed wurde vom Konsumenten nicht berührt (erwartet) und DELETE schlägt serverseitig fehl — prüfen Sie Graph-App-Berechtigungen (Sites.ReadWrite.All). BC setzt Processed=true vor dem Löschen, sodass ein einzelner Processed-Flip in der UI typischerweise nicht benötigt wird.
Übernahme gelingt für zwei Mitglieder Konsument hat ApprovalStatus=Claimed geschrieben, ohne den aktuellen Status zuerst zu prüfen. Bevorzugen Sie die gebundene BC-API-Aktion claim — sie erzwingt optimistisches Sperren.
Back to top