Give people access to document records
Assign the Lifecycle.Reader role on the REFRACT Dispatcher API enterprise application to the people and groups who read REFRACT's records about documents.
SharePoint decides which documents a person can find. The Lifecycle.Reader role on the "REFRACT Dispatcher API" app decides whether the Dispatcher returns the records REFRACT holds about those documents: the timeline, signing and delivery status, workflow data, stored files, verification, and the rest listed under What the role protects. Signed-in people also need it to send a stored document for signature or delivery.
This page covers people. Source systems get the role as an application permission instead; see Connect a source system.
Assign the role to a group
- Sign in to the Microsoft Entra admin center as a Cloud Application Administrator, an Application Administrator, or an owner of the app.
- Open Enterprise applications and select REFRACT Dispatcher API (or the name your deployment gave the app registration).
- Select Users and groups -> Add user/group.
- Under Users and groups, choose the group whose members read document records, for example a group named "REFRACT Lifecycle Readers".
- Under Select a role, choose Lifecycle.Reader.
- Select Assign.
| Point | What it means |
|---|---|
| Groups need Microsoft Entra ID P1 or P2 | Without P1 or P2 on your tenant, the page only lets you assign users. Assign each person directly instead. |
| Direct members only | Only the group's direct members receive the role. Members of a group nested inside it do not. |
| Takes effect at the next sign-in | The role travels in the person's sign-in token, and a token issued before the assignment does not carry it. After you assign the role, each person should sign out of Microsoft 365, sign in again, and then reopen REFRACT Lifecycle. Removing someone takes effect once their current token expires. Microsoft Entra issues these tokens for 60 to 90 minutes by default. |
Users and groups is for people
The Users and groups page assigns roles to users and groups only. You cannot add an app registration there. To give a source system the role, grant it as an application permission on that system's own app registration: see Connect a source system.
Before you update the Dispatcher
infra/deploy.ps1 creates the Lifecycle.Reader role but assigns it to no one. At the end of each run it checks whether anyone holds the role. If no one does, it prints ACTION REQUIRED: NO ONE CAN READ DOCUMENT RECORDS. The deployment still completes. However, until someone holds the role, every Lifecycle window opens to its header and the Permission needed message, and no signed-in user can send a document for signature or delivery. Assign the role before you update the Dispatcher.
What a person without the role sees
The Dispatcher refuses the read with HTTP 403, code ROLE_MISSING, and "role": "Lifecycle.Reader". REFRACT Lifecycle shows a Permission needed notice with the message from that response, which names "REFRACT Dispatcher API". If your deployment gave the app registration a different name, look for that name in Enterprise applications. See The ROLE_MISSING message for the full response and where the notice appears.
REFRACT Lifecycle
REFRACT Lifecycle is a SharePoint-hosted workspace that provides a unified operational view of every document generated by REFRACT Platform, with search, filters, timeline, signing, delivery, workflow, and configuration in a single interface.
Workspace Tabs Reference
Detailed reference for every tab in the REFRACT Lifecycle workspace: search and filters, Summary, Properties, Audit Timeline, Signatures, Deliveries, Workflow, and Related Files.