starred/documenso

Fork 0

mirror of https://github.com/documenso/documenso.git synced 2026-04-24 21:36:01 +03:00

[GH-ISSUE #2526] Signature Flow - Approver Role Should Block Signature Requests Until Completed #700

New issue

Open

opened 2026-02-26 18:48:07 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 18:48:07 +03:00

Owner

Originally created by @NDCallahan on GitHub (Feb 22, 2026).
Original GitHub issue: https://github.com/documenso/documenso/issues/2526

Feature Description

🧩 Summary

When a document includes both approvers and signers, Documenso currently sends requests to all recipients at the same time. This allows signatures to occur before approvals, which breaks expected governance workflows. Approvers should act as a blocking step before any signature requests are sent.

🎯 User Story

As a document creator,
I need Documenso to enforce an approval-first workflow when approvers are included,
so that signatures are not requested until all approvals are completed.

🐛 Current Behavior

Approvers and signers receive their requests simultaneously.
Signers can sign a document that has not yet been approved.
The presence of approvers does not change the workflow order.

✅ Expected Behavior

When a document includes any approvers:

1. Approval Phase

Only approvers receive notifications.
Document enters a "Pending Approval" state.
Signers receive nothing yet.

2. Transition

Once all approvers approve, the workflow advances.

3. Signature Phase

Signature requests are sent to signers.
Document moves to "Awaiting Signatures."

Use Case

🧪 Use Cases

Use Case 1 — Internal Policy Approval Before External Signature

A property management company sends a lease addendum to a tenant for signature.
Before the tenant signs, the document must be approved by the regional manager.

Recipients:

Approver: Regional Manager
Signer: Tenant

Expected:
The regional manager approves the document first. Only after approval does the tenant receive the signature request.

Current Behavior:
Both the regional manager and the tenant receive requests at the same time, allowing the tenant to sign a document that has not been approved internally.

Use Case 2 — Legal Review Before Executing Vendor Contracts

A small business sends a vendor contract that must be reviewed by legal counsel before the vendor signs.

Recipients:

Approver: Legal Counsel
Signer: Vendor Representative

Expected:
Legal counsel reviews and approves the contract. Once approved, the vendor receives the signature request.

Current Behavior:
Legal counsel and the vendor receive requests simultaneously, enabling the vendor to sign a contract that has not yet passed legal review.

Proposed Solution

🧠 Proposed Solution

Implement a two‑phase workflow engine that evaluates recipient roles and enforces approval as a blocking step before signatures are requested.

1. Workflow Evaluation

When a document is created, Documenso checks the recipient list.
If any approvers are present, the system automatically enters an approval-first workflow mode.
If no approvers exist, the workflow behaves exactly as it does today.

2. Approval Phase (Blocking Step)

Only approvers receive notifications and access to the document.
Document status is set to Pending Approval.
Signers are not notified, cannot access the document, and do not appear in the active workflow until approvals are complete.

3. Transition Trigger

When all approvers have approved:
- The system fires a workflow event (e.g., approvals.completed).
- This event triggers the same logic currently used to send signature requests.

4. Signature Phase

Signers receive their signature requests in the defined signing order (if any).
Document status transitions to Awaiting Signatures.
The rest of the workflow proceeds unchanged.

5. Rejection Handling

If any approver rejects:
- The workflow halts.
- Signers are never contacted.
- Document status moves to Rejected (or similar).

6. UI/UX Adjustments

Display a clear two‑phase workflow in the document timeline:
- Phase 1: Approvals
- Phase 2: Signatures
Prevent signers from appearing “active” until approvals are complete.
Provide visual indicators showing which approvers have approved or rejected.

7. Backward Compatibility

Existing documents without approvers are unaffected.
API behavior remains consistent unless approvers are included.
No breaking changes to existing signature-only workflows.

Alternatives (optional)

No response

Additional Context

No response

Please check the boxes that apply to this feature request.

I have searched the existing feature requests to make sure this is not a duplicate.
I have provided a detailed description of the requested feature.
I have explained the use case or scenario for this feature.
I have included any relevant technical details or design suggestions.
I understand that this is a suggestion and that there is no guarantee of implementation.
I want to work on creating a PR for this issue if approved

Originally created by @NDCallahan on GitHub (Feb 22, 2026). Original GitHub issue: https://github.com/documenso/documenso/issues/2526 ### Feature Description ## 🧩 Summary When a document includes both **approvers** and **signers**, Documenso currently sends requests to *all* recipients at the same time. This allows signatures to occur before approvals, which breaks expected governance workflows. Approvers should act as a blocking step before any signature requests are sent. --- ## 🎯 User Story **As a document creator, I need Documenso to enforce an approval-first workflow when approvers are included, so that signatures are not requested until all approvals are completed.** --- ## 🐛 Current Behavior - Approvers and signers receive their requests simultaneously. - Signers can sign a document that has not yet been approved. - The presence of approvers does not change the workflow order. --- ## ✅ Expected Behavior When a document includes **any approvers**: ### 1. Approval Phase - Only approvers receive notifications. - Document enters a "Pending Approval" state. - Signers receive nothing yet. ### 2. Transition - Once **all approvers** approve, the workflow advances. ### 3. Signature Phase - Signature requests are sent to signers. - Document moves to "Awaiting Signatures." --- ### Use Case ## 🧪 Use Cases ### **Use Case 1 — Internal Policy Approval Before External Signature** A property management company sends a lease addendum to a tenant for signature. Before the tenant signs, the document must be approved by the regional manager. **Recipients:** - Approver: Regional Manager - Signer: Tenant **Expected:** The regional manager approves the document first. Only after approval does the tenant receive the signature request. **Current Behavior:** Both the regional manager and the tenant receive requests at the same time, allowing the tenant to sign a document that has not been approved internally. --- ### **Use Case 2 — Legal Review Before Executing Vendor Contracts** A small business sends a vendor contract that must be reviewed by legal counsel before the vendor signs. **Recipients:** - Approver: Legal Counsel - Signer: Vendor Representative **Expected:** Legal counsel reviews and approves the contract. Once approved, the vendor receives the signature request. **Current Behavior:** Legal counsel and the vendor receive requests simultaneously, enabling the vendor to sign a contract that has not yet passed legal review. ### Proposed Solution ## 🧠 Proposed Solution Implement a two‑phase workflow engine that evaluates recipient roles and enforces approval as a blocking step before signatures are requested. ### 1. Workflow Evaluation - When a document is created, Documenso checks the recipient list. - If **any approvers** are present, the system automatically enters an **approval-first** workflow mode. - If no approvers exist, the workflow behaves exactly as it does today. ### 2. Approval Phase (Blocking Step) - Only approvers receive notifications and access to the document. - Document status is set to **Pending Approval**. - Signers are not notified, cannot access the document, and do not appear in the active workflow until approvals are complete. ### 3. Transition Trigger - When all approvers have approved: - The system fires a workflow event (e.g., `approvals.completed`). - This event triggers the same logic currently used to send signature requests. ### 4. Signature Phase - Signers receive their signature requests in the defined signing order (if any). - Document status transitions to **Awaiting Signatures**. - The rest of the workflow proceeds unchanged. ### 5. Rejection Handling - If any approver rejects: - The workflow halts. - Signers are never contacted. - Document status moves to **Rejected** (or similar). ### 6. UI/UX Adjustments - Display a clear two‑phase workflow in the document timeline: - Phase 1: Approvals - Phase 2: Signatures - Prevent signers from appearing “active” until approvals are complete. - Provide visual indicators showing which approvers have approved or rejected. ### 7. Backward Compatibility - Existing documents without approvers are unaffected. - API behavior remains consistent unless approvers are included. - No breaking changes to existing signature-only workflows. ### Alternatives (optional) _No response_ ### Additional Context _No response_ ### Please check the boxes that apply to this feature request. - [x] I have searched the existing feature requests to make sure this is not a duplicate. - [x] I have provided a detailed description of the requested feature. - [x] I have explained the use case or scenario for this feature. - [x] I have included any relevant technical details or design suggestions. - [x] I understand that this is a suggestion and that there is no guarantee of implementation. - [ ] I want to work on creating a PR for this issue if approved