Run a Governed Approval Workflow
Use REFRACT Workflow to collect structured data from a participant, run schema-driven validation, route to an approver, and seal the final PDF on approval.
This tutorial covers a governed approval workflow: a participant fills a structured form across one or more steps, validation runs against the submitted data, the submission routes to an approver, and the final PDF is sealed automatically on approval.
Products used: REFRACT Workflow, REFRACT eSign (optional post-seal)
What You'll Need
- A REFRACT PDF licence with the
vaultWorkflowfeature gate enabled - A workflow schema YAML stored in your SharePoint assets library
- The schema's SharePoint path
- Participant and approver email addresses
Using a REFRACT Pack schema
The Payables, Receivables, and Order Management REFRACT Packs each include ready-to-use governance workflow schemas such as po-approval, invoice-approval, and quote-approval. Reference the schema blob path directly when creating a session.
Step 1: Create a Workflow Session
POST to /api/workflow with the template path and the workflow settings under templateSettings.workflow. The Dispatcher generates an invite token for the participant and sends them an invitation email.
POST /api/workflow
Authorization: Bearer <Entra ID JWT>
Content-Type: application/json{
"templatePath": "templates/po-approval.rpkg",
"templateSettings": {
"workflow": {
"schemaPath": "Workflows/po-approval.yaml",
"recipients": [
{ "email": "procurement@yourcompany.com", "displayName": "Procurement Officer" }
],
"requireOtp": false
}
},
"options": { "documentId": "PO-2026-0042", "docType": "po-approval" }
}The response returns a workflowId and the participant's portal URL, a link reference (/w/...) that the portal resolves:
{
"workflowId": "wf-xxxx...",
"correlationId": "auto-generated-or-yours",
"state": "in-progress",
"portalUrl": "https://portal.refractplatform.com/w/<linkReference>"
}Step 2: Participant Fills the Form
The participant opens their portal link and fills each step in sequence. Steps are defined in the schema YAML and may include vendor details, line items, cost centres, and any other fields declared in the schema.
Participants can save progress and return. Each step is submitted independently before the workflow advances to the next.
Step 3: Validation Runs
When the participant submits the final step, schema-driven validation evaluates all collected data. For governance-type workflows, validation also runs at session creation.
If validation passes, the workflow transitions to pending-approval and the designated approver receives a notification email.
Error vs. warning severity
error-severity rules block advancement; the participant must correct the data before resubmitting. warning-severity rules surface to the approver as advisory flags but do not block approval.
Step 4: Approver Reviews and Decides
The approver opens the submission via their portal link or the REFRACT Lifecycle workspace. They can:
- Approve - the workflow seals the final PDF immediately
- Reject - the workflow closes; no PDF is produced
- Request changes - the submission returns to the participant with structured correction instructions
Step 5: PDF is Sealed
On approval, REFRACT Workflow enqueues a seal message. The Dispatcher renders the final PDF using the workflow template and the complete collected data snapshot. The sealed document is stored in Azure Blob Storage and the correlationId is recorded in the REFRACT Lifecycle workspace.
Optional: Trigger REFRACT eSign After Sealing
Add templateSettings.esign to the same request to trigger a REFRACT eSign signing session automatically after sealing, with no additional API call required:
{
"templatePath": "templates/po-approval.rpkg",
"templateSettings": {
"workflow": {
"schemaPath": "Workflows/po-approval.yaml",
"recipients": [{ "email": "procurement@yourcompany.com", "displayName": "Procurement Officer" }]
},
"esign": {
"enabled": true,
"signers": [
{ "slotIndex": 0, "role": "manager", "email": "manager@yourcompany.com" }
],
"signingMode": "single",
"expiresInMinutes": 2880
}
}
}Delivering the sealed PDF
Triggering REFRACT Delivery from a workflow's post-seal settings does not currently send the recipient an invitation email (the mode is dropped before the processor reads it). Call POST /api/delivery yourself once the workflow reaches complete instead.
What Happens Next
The complete approval trail - each step submission, validation outcome, approver decision, and seal event - is recorded in the REFRACT Lifecycle workspace under the document's correlationId. The Workflow tab shows validation results, change request history, and approval stage progress.
REFRACT Workflow Reference
Schema reference, API endpoints, validation rule types, and approval routing configuration.
Send a Document for Electronic Signing
Render a signing document and create a REFRACT eSign session to collect electronic signatures from one or more signers via the centrally hosted signing portal.
Batch Document Dispatch
Render multiple documents from a single payload, get an intake receipt, route through an approver, and deliver each PDF to its recipient via REFRACT Delivery.