REFRACT Lifecycle

REFRACT Lifecycle is a SharePoint Framework (SPFx) web part deployed to your SharePoint environment. It provides a real-time operational view of every document generated by REFRACT Platform, combining SharePoint list metadata, Dispatcher API data, and append-only REFRACT Audit records into a unified, searchable workspace. The Audit Timeline tab surfaces the REFRACT Audit event stream for each document, severity-classified, filterable by audience, and expandable to Level 2 sub-event trails for full operational detail.

One Lifecycle. Multiple Sources.

Business documents rarely originate from a single system - quotes from CRM, invoices from ERP, signed agreements from external workflows, operational documents from internal applications. REFRACT Platform ingests all of them into a single customer-controlled lifecycle with consistent governance, retention, and audit evidence.

Every ingested document moves through four phases:

Teams can search by business metadata, apply consistent governance and retention controls, review audit evidence, and navigate back to the originating system - all from one workspace.

What the Workspace Shows

Document Status Values

Each document in the workspace displays a status badge derived from its SharePoint list entry and dispatcher API state:

Data Sources

REFRACT Lifecycle aggregates data from three sources:

Access: the Lifecycle.Reader Role

Two separate checks decide what a person sees in REFRACT Lifecycle:

• SharePoint permissions decide which documents they can find. The workspace lists items from the REFRACT_Activity SharePoint list, so SharePoint's list permissions, the REFRACT.Admin group, and each item's restriction map still govern search results, item metadata, and what the SharePoint document library lets them open. See REFRACT Lifecycle Access Control.
• The Lifecycle.Reader app role decides whether they can read the records REFRACT holds about those documents in your Azure subscription. The Dispatcher checks the role on every such read. SharePoint access alone does not grant it, and the role alone does not reveal documents SharePoint hides from them.

What the role protects

Who passes without the role:

• A workflow's own participants (its initiator, approvers, reviewers, escalation contacts, and recipients) can read that workflow's data. Opening a workflow for review is also open to the workflow administrator, any approver a stage of the workflow names, and members of the current stage's group. Only signed-in people count as participants: an app token is never a participant, even of a workflow it created.
• When your Dispatcher runs with DOCUMENT_ACCESS_ENFORCEMENT=enforce, a person the document's own access record names as a participant can open that document through /api/doc and re-render its payload. In the default mode (off) and in shadow, nobody passes this way.
• People opening an emailed REFRACT link: portal links carry their own credentials.

Re-rendering a stored payload. A render reads its payload from your SharePoint Payloads library with the Dispatcher's own identity, so the Dispatcher records each payload it renders. When a signed-in user (a delegated token) renders a payload that has been rendered before, as Recreate and Generate Variant do, the role is required, and the render is refused with 403 and ROLE_MISSING before the payload is read. If the record of rendered payloads cannot be read, the render is refused with 503 and RENDERED_PAYLOAD_CHECK_UNAVAILABLE rather than allowed. The first render of a new payload, every render by an app token (re-runs included), and renders with inline data are unchanged. Payloads rendered before your Dispatcher was updated are not in the record until a one-time backfill is run on your deployment; until then, re-rendering them counts as a first render.

Not covered by the role: documents opened from SharePoint itself (SharePoint permissions govern them), the archive status check (which returns no contents or hashes), the first render of a new payload, and the signing session a render creates for itself through templateSettings.esign. A workflow's sealed PDF and attachments are open to its signed-in participants without the role. An app reads them with Render.Access and Lifecycle.Reader, as it reads any other stored document. Any other signed-in person needs the role and also the document-access administrator role named by the Dispatcher's DOCUMENT_ACCESS_ADMIN_APP_ROLE setting, which standard deployments do not configure. For everyone, the document's own restriction policy, when it has one, still applies.

Assigning the role

People get the role in Microsoft Entra ID, under Enterprise applications -> REFRACT Dispatcher API -> Users and groups, usually through a group. Assigning a group needs Microsoft Entra ID P1 or P2, only the group's direct members receive the role, and it takes effect at each person's next sign-in. infra/deploy.ps1 creates the role but assigns it to no one, so assign it before you update the Dispatcher. See Give people access to document records for the steps.

Integrations that use app tokens

An integration that calls the Dispatcher with client credentials (an app token, with no user signed in) should call as its own connector app, one per source system; see Connect a source system. The connector app needs application permissions on the "REFRACT Dispatcher API" app:

Only /api/healthz, /api/audience-config, /api/audit-config, GET /api/render?ping=true, the routes portal links use, and the eSign portal's signed callbacks are exempt. The participant exceptions above do not apply to app tokens, including callers that present a signed document assertion.

Decisions are made by people. An app token cannot approve, reject, request changes on, or escalate a workflow, make a governance decision, or decide a batch, whatever permissions it holds. These are refused with 403, code APP_CANNOT_DECIDE: "An application cannot make this decision. Approvals, rejections, requests for changes, governance decisions and escalations are made by a signed-in person."

To grant the permissions:

1. Open App registrations -> the system's connector app -> API permissions -> Add a permission -> APIs my organization uses -> REFRACT Dispatcher API.
2. Choose Application permissions, select Render.Access and, if the integration reads records, Lifecycle.Reader, and select Add permissions.
3. Select Grant admin consent.

infra/deploy.ps1 creates both roles but grants neither to any app. The permissions then appear in the roles claim of the connector's tokens. Grant the permissions on the connector app, never on "REFRACT Dispatcher API" itself: no source system should sign in as that app. Grant Render.Access before you update your Dispatcher to a version that requires it, or every call from the integration is refused.

The sealed workflow PDF actions (the connector's Download Sealed PDF, and the Business Central and Dynamics 365 Sales sealed-document actions) need Lifecycle.Reader as well as Render.Access. An app is never a workflow participant, so the role is what lets it read a workflow's sealed PDF and attachments. The document's restriction policy, when it has one, still applies.

The ROLE_MISSING message

Without the role, the Dispatcher refuses the read with HTTP 403:

{
  "error": "Forbidden",
  "code": "ROLE_MISSING",
  "role": "Lifecycle.Reader",
  "message": "You do not have permission to view document records. Your account needs the Lifecycle.Reader role on the \"REFRACT Dispatcher API\" app. Ask a Microsoft Entra administrator to assign it: Microsoft Entra admin center > Enterprise applications > REFRACT Dispatcher API > Users and groups > Add user/group, choose your account (or a group you are in) and the Lifecycle.Reader role. Then sign out and sign in again."
}

An app token is refused with the same status and code, naming Render.Access or Lifecycle.Reader in role. The Lifecycle.Reader message is written for a person; for an app, the fix is the application permission steps above.

REFRACT Lifecycle checks the role once, when a Lifecycle window opens (a document, eSign, workflow, delivery, or batch record). Without it, the window shows only its header (the document ID, or "Batch distribution" for a batch, the correlation ID, and Close) and a Permission needed notice with this message: no tabs, panels, actions, or exports, and nothing else is read for that window. If any call made while a window is open is refused for the role, the window closes to the same view. Outside those windows the same Permission needed notice appears in the Recreate PDF progress dialog (from Lifecycle Search and the dashboard), for Lifecycle Search's Open Document, and in Dispatch Review. A batch or document is never reported as "not found" because of a missing role. To fix it, assign the role as described in Give people access to document records, then sign out and sign in again. The message always names "REFRACT Dispatcher API"; if your deployment gave the app registration a different name, look for that name in Enterprise applications.

SharePoint Activity List

The workspace reads from the REFRACT_Activity SharePoint list populated automatically by the Dispatcher at render time. Key columns:

Deep Links

Source systems can open REFRACT Lifecycle with filters pre-populated by appending query parameters to the SharePoint page URL:

https://your-site/SitePages/Home.aspx?correlationId=d8cb1510-8290-40f8-8592-702eaa9838a6
https://your-site/SitePages/Home.aspx?batchId=082ab853-7852-47f0-b078-1927d2d92619
https://your-site/SitePages/Home.aspx?sourceSystem=D365_FO

The workspace opens automatically with the filter applied. CorrelationIds and BatchIds are globally unique UUIDs; no sourceSystem qualifier is needed to find a specific record by GUID. Deep links work from both the Home.aspx dashboard web part and list-view pages with the REFRACT Lifecycle command set installed.

See Deep Links in the Workspace Tabs reference for the full parameter reference and security model.