DEXPRO AWF External Approvals — SharePoint Integration Contract

This document describes the SharePoint list contract between Business Central (the AWF extension) and any external system that consumes or responds to approval requests. It is transport-neutral: the reference implementation uses Power Automate + Microsoft Teams (see SETUP-GUIDE.md), but any system that can read and write SharePoint list items via the Microsoft Graph API — or the native SharePoint REST API — can participate.

Audience: integration developers. End-user setup is covered in SETUP-GUIDE.md.

---

1. Design principles

1. The SharePoint list is the queue. BC writes a list item when an external approver must decide; the consumer writes back to the same item with the decision; BC's Job Queue poller picks it up.
2. BC is the system of record. The SP item is transient — BC deletes it after processing. Consumers must not rely on SP history.
3. Stable internal column names. The column name (not displayName) is the contract. Display names are localized and must not be used.
4. Forward compatibility. BC writes a SchemaVersion value on every item. Consumers should reject / log items with an unsupported version instead of silently misbehaving.
5. Idempotency. BC only cares about the first terminal status a consumer writes. Writing the same status twice is a no-op.

---

2. Polling model

• BC runs a Job Queue entry (Codeunit 70954832 "DXP AWF Ext. Approval Poller") on a recurring interval (default: every 2 minutes).
• The poller fetches items that match Processed eq false and ApprovalStatus ne 'Pending' and BCCompanyName eq '<current company>' (server-side filter; falls back to client-side if Graph declines the filter). The company clause is always applied — see § 7a.
• For each matched item, BC updates the corresponding AWF entry, calls the workflow engine, then sets Processed = true on the SharePoint item and attempts to DELETE it.
• If DELETE fails, the Processed = true flag is enough to exclude the item from subsequent polls; orphaned items are retried every cycle by CleanupOrphanedSPItems.

Implication for consumers: you have between 0 and N minutes (where N is the polling interval) between writing the decision and BC processing it. Do not expect synchronous confirmation. If you need a confirmation back, watch for the item's Processed field to flip or the item to disappear.

---

3. Column reference

Every column below uses the internal name — that is the contract. Display names may be localized.

3.1 Inputs (BC → consumer)

BC populates these when the item is created. Consumers must not modify them.

Name	Type	Notes
SchemaVersion	Text	Currently "1". Bump indicates a breaking change in this contract.
BCCompanyName	Text	The BC company that owns the entry. Always set on new rows; must not be changed by consumers. BC's per-company poller uses this to ignore items from other companies (see § 7a).
Title	Text	Short record description (e.g. purchase order no.). Part of the built-in SharePoint column.
BCEntryNo	Text	Entry No. of the AWF Ext. Approval Entry record within BCCompanyName. Not globally unique — always pair with BCCompanyName when correlating.
BCApprovalEntryNo	Text	Entry No. of the underlying BC standard Approval Entry (table 454). Identical across all peer rows in a group — useful for grouping rows by their underlying decision unit (e.g. cancelling peers when one claims).
BCInstanceID	Text	AWF workflow instance GUID — globally unique across companies.
Description	Text	Localized RecordId text of the approved record (Format(RecId, 0, 1), e.g. Purchase Line: Invoice,EKRECH1052,20000 with translated table/field captions). Shown on the card as the record line; works for any table.
ApproverEmail	Text	UPN / mail address. Route notifications to this address.
ApproverDisplayName	Text	Human-readable name.
AttachmentsUrl	Text	SharePoint sharing link to a folder containing document attachments. Empty when upload is disabled or no attachments exist.
BCDocumentUrl	Text	Direct link to the source record in Business Central. Opens for approvers whose Business Central licence grants web-client access; others see a sign-in wall. Empty if BC could not derive a card-page URL for the record.
RecordDetails	Multi-line text	CommonMark markdown rendering of the approved record's own fields (e.g. for a Purchase Line: Type, No., Description, Quantity, Direct Unit Cost, Line Amount). Renderable directly in an Adaptive Card TextBlock with wrap=true. Curated for the common Sales / Purchase header & line tables; falls back to a generic field walk for other tables.
IsGroupApproval	Boolean	true when this item is one of several for a claim-based group approval.
GroupCode	Text	External approver group code (only set when IsGroupApproval = true).
Amount	Text	Display-formatted amount (locale-dependent).
AmountRaw	Number	Machine-readable amount (always point-decimal). Prefer this over Amount.
DueDate	Text	Display-formatted date.
DueDateRaw	DateTime	ISO 8601, UTC. Prefer this over DueDate.
CreatedRaw	DateTime	ISO 8601, UTC. When the item was created by BC.
SenderName	Text	Display name of the requester (User."Full Name"); falls back to the BC user id when no full name is recorded.
StageName	Text	Workflow stage description.
LblTitle … LblClaimedSuccessMsg	Text	Pre-translated UI strings and message templates for the approver's language (see 3.4). The LblAlready…Msg and LblClaimedSuccessMsg columns carry message templates with {title} / {claimer} placeholders that the consumer (e.g. Power Automate) substitutes at runtime.

3.2 Response fields (consumer → BC)

The consumer writes these once a decision is made. Only ApprovalStatus is required.

Name	Type	Required	Notes
ApprovalStatus	Choice	yes	One of Approved, Rejected, Claimed. Case-insensitive on the BC side. SharePoint presents a dropdown with all valid values; the initial/default value is Pending. Any non-terminal value is logged by BC and the item is left alone.
ResponseComment	Multi-line Text	no	Free text, max 2048 chars on the BC side. SharePoint renders a multi-line text area for editing. Shown in BC's approval comment trail.
ResponseDateTime	DateTime	no	ISO 8601 UTC via Graph, native picker in SP. If omitted, BC uses the current time.
ClaimedBy	Text	yes when ApprovalStatus = Claimed	Email of the group member who claimed the entry. BC also writes this column on peer items that get cancelled because someone else in the group claimed first — in that case it identifies the user who took the entry over (the SP item's ApprovalStatus will simultaneously be Cancelled).
TeamsMessageId	Text	no	The Microsoft Teams message ID of the adaptive card the consumer posted for this item. A consumer that wants to close peer cards (replace a group member's still-open card once another member decides) writes this back right after posting the card, and reads peers' values during the claim cascade to target Update an adaptive card. BC also stores it (and accepts it via the setTeamsMessageId bound action) for diagnostics. Optional — leave empty if the consumer doesn't implement card-closing.

Do not write Processed, SchemaVersion, BCEntryNo, BCInstanceID, or any Lbl* column. BC owns them. (TeamsMessageId is the one consumer-writable transport column besides the response fields above.)

3.3 BC-managed state

Name	Type	Written by	Purpose
Processed	Boolean	BC only	true once BC has consumed the response. Poller excludes these from subsequent fetches. Consumers must treat as read-only.

3.4 Localized label columns

BC pre-translates the adaptive-card / UI labels for the approver's language and writes them as plain text. Consumers can use them directly without calling BC or a translation service.

Name	Typical English value
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.
LblClaimedSuccessMsg (display name Decision Confirmation)	The approval entry "{title}" has been successfully processed.
LblApprovedResult (display name Approved (Result))	Approved
LblRejectedResult (display name Rejected (Result))	Rejected
LblResultTitle (display name Result Title)	Approval Decision
LblClosedTitle (display name Closed Title)	No Longer Open
LblResponseSent (display name Response Sent)	Response sent.

---

4. ApprovalStatus state machine

       ┌─────────┐   consumer writes       ┌──────────┐
       │ Pending │──────────────────────▶  │ Approved │ ─┐
       └────┬────┘                         └──────────┘  │
            │                                            │  BC poller
            │ consumer writes                            │  picks up,
            ▼                                            │  sets Processed=true,
       ┌──────────┐                                      │  then DELETE
       │ Notified │──────────────▶ Approved / Rejected ──┤
       └────┬─────┘                                      │
            │                                            │
            │ group claim                                │
            ▼                                            │
       ┌─────────┐                                       │
       │ Claimed │──────────────▶ Approved / Rejected ───┘
       └─────────┘

• Pending — written by BC on creation.
• Notified (optional) — consumer can set this after the approver has been notified but before they respond. Purely informational; BC does not act on it.
• Claimed — group approvals only. Consumer must also set ClaimedBy.
• Approved / Rejected — terminal. Consumer may also set ResponseComment and ResponseDateTime.
• Processed, Error, Cancelled — BC-internal terminal states. Do not write them.

---

4a. Approving directly in SharePoint (no consumer app)

Because the list uses typed columns, a human can approve an entry by opening the list item in SharePoint and editing it — no Teams, no Power Automate, no BC access required:

1. Open the SharePoint approval list in a browser.
2. Click the pending item. SharePoint opens the edit form.
3. Pick a terminal value from the Approval Status dropdown: Approved, Rejected, or (for group approvals) Claimed.
4. Optionally type a reason in the Response Comment text area.
5. Optionally set Response DateTime (left blank, BC uses the current time).
6. Click Save.

BC's Job Queue poller picks up the change on the next cycle (default: every 2 minutes) and processes it through the approval workflow identically to a Power Automate write-back.

Permissions: the SharePoint user needs Edit permission on the list. Because the Processed, SchemaVersion, BCEntryNo, and Lbl* columns are BC-owned, consider using a SharePoint view or column-level formatting to hide them from the edit form — users only need ApprovalStatus, ResponseComment, ResponseDateTime, and (for claim) ClaimedBy.

---

5. Minimal response payload

Approve

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

{
  "ApprovalStatus": "Approved",
  "ResponseComment": "Looks good to me.",
  "ResponseDateTime": "2026-04-22T10:15:00Z"
}

Reject

{ "ApprovalStatus": "Rejected", "ResponseComment": "Duplicate PO." }

Claim (group approval)

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

---

6. Alternative: native BC API

The SharePoint list is the recommended integration point because the approver works entirely in Teams/SharePoint rather than the BC web client. Note that acting on BC data still requires each approver to hold an appropriate paid Business Central user licence — routing responses through a service account does not remove the per-user licence requirement (Microsoft multiplexing / indirect-access terms). DEXPRO makes no licensing representation; the customer and their Microsoft licensing partner are responsible for confirming licensing with Microsoft. If your system has a BC service-to-service principal, you can bypass SharePoint entirely and post directly to BC:

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

Example:

POST /api/dexpro/advancedWorkflow/v1.0/companies({id})/externalApprovalEntries({entryNo})/Microsoft.NAV.approve
{ "comment": "Looks good to me." }

Both paths — SharePoint write-back and the BC API — converge on the same ProcessApprovalResponse code path and are fully interchangeable.

---

7a. Multi-company BC installs

A single SharePoint list can serve multiple BC companies. Each company's job-queue poller runs independently in its own company context, and the poller's server-side $filter includes fields/BCCompanyName eq '<current company>' so a company only picks up its own items. There is a belt-and-braces client-side re-check on every page — rows whose BCCompanyName does not match the current company are discarded even if the server-side filter was bypassed.

Implications for consumers:

• Always treat (BCCompanyName, BCEntryNo) as the composite key. BCEntryNo alone is only unique within a single company.
• Do not write or modify BCCompanyName. BC sets it on item creation and never changes it.
• BCInstanceID (GUID) is globally unique and is a safe correlation key without BCCompanyName.
• If you build a Power Automate flow that writes items (e.g. a custom intake), set BCCompanyName to the target company or BC's poller will never see your items.

---

7. Versioning

• Additive changes (new columns, new optional response fields) will not bump SchemaVersion. Consumers must ignore unknown fields.
• Breaking changes (renamed columns, changed semantics, required response fields) will bump SchemaVersion. BC will continue to write the old schema version until a deprecation release is announced.
• Consumers should validate SchemaVersion on every item and refuse items whose version they do not understand.

---

8. Troubleshooting checklist for integrators

Symptom	Likely cause
BC never processes a response	ApprovalStatus not one of Approved/Rejected/Claimed; or consumer wrote Processed=true; or AWF Setup has SP Approvals Enabled = No.
Item keeps reappearing in polls	Processed was not touched by the consumer (expected) and DELETE fails server-side — check Graph app permissions (Sites.ReadWrite.All). BC marks Processed=true before delete, so a single Processed flip in the UI is typically not needed.
Claim succeeds for two members	Consumer wrote ApprovalStatus=Claimed without checking the current status first. Prefer the BC API claim bound action — it enforces optimistic locking.