Approval Plugins: Add Structured Rejection Reasons to Approval Workflows
This article explains how to add structured rejection reasons to approval cards and review plugins so that approval outcomes are explainable, auditable, and ready for automation. It covers reason-field design, approval-card display, server-side state consistency, concurrency and idempotency, plugin recovery, test coverage, and ways to use rejection data to improve workflow design.
In many approval systems, “approve” and “reject” are only outcome states. The factor that actually affects collaboration efficiency is the reason behind the state.
If an approver clicks “Reject” and the system records only a boolean value, the requester often sees vague messages such as “Approval not passed” or “Operation rejected.” The requester may then need to ask the approver again to confirm whether the issue is missing materials, insufficient permissions, noncompliant formatting, or unmet business conditions. For occasional requests, this may mean only a few extra messages. For high-frequency approval workflows, however, a large amount of repeated confirmation directly slows down processing and makes problems harder to trace.
Therefore, adding a “rejection reason” to an approval card or approval plugin is not simply adding an input field. It is an improvement to the explainability of the approval process, data integrity, and the ability to support later automation.
1. Define the Problem First: Rejection Is Not Complete Information
An approval action contains at least three types of information:
- Approval result: approved, rejected, or additional materials required;
- Actor: who completed the action and when;
- Basis for the decision: why the decision was made.
The first two usually already exist in the system, but the third is often ignored. Without a rejection reason, the approval result lacks context, and later participants cannot accurately determine the next action.
For example, the following rejections actually correspond to completely different handling paths:
- “Application content is incomplete”: the requester supplements the materials and resubmits;
- “The current role is not authorized to apply”: permissions need to be adjusted, or another person needs to initiate the request;
- “The time range does not meet the rules”: the application dates need to be modified;
- “Duplicate submission”: close the current request and keep the original approval record;
- “Business conditions are not met”: the requirement needs to be reassessed rather than simply supplemented with materials.
If the system saves only “rejected,” these scenarios are compressed into the same result. Subsequent handling then depends on manual communication, and problems such as repeated submissions, duplicate approvals, and unclear responsibility boundaries may occur.
2. How Should the Rejection Reason Field Be Designed?
1. It Must Be Bound to the Rejection Action
The most reliable interaction is to show a reason input area after the user clicks “Reject,” validate the content, and then submit the rejection result.
It is not recommended to place the rejection reason in the ordinary notes area of the approval card. Ordinary notes are usually optional and may be ignored by users. A rejection reason is a required condition of the rejection action and should be explicitly enforced at the workflow level.
The basic flow can be abstracted as:
Click Reject↓Open rejection reason input↓Validate content↓Submit rejection status and reason↓Refresh approval card↓Write audit record and notify relevant people
If any step fails, the interface must not show “Rejected successfully.”
2. Do Not Use Free Text Only
Free text is the most flexible option, but it is also the most prone to inconsistent expression. Different approvers may write:
- “No”
- “Does not meet requirements”
- “Incomplete materials”
- “Please supplement materials and resubmit”
These messages are barely understandable to humans, but they are not friendly for statistics, search, or automated processing.
A more reasonable approach is to use a combination of “standard reason + additional detail”:
{"result": "rejected","reason_code": "MISSING_MATERIAL","reason_label": "Incomplete materials","reason_detail": "Missing budget explanation and owner confirmation"}
Here:
reason_codeis used for program recognition and statistics;reason_labelis used for interface display;reason_detailis used to provide specific context.
Standard reasons can be configured according to actual business needs, such as “Incomplete information,” “Permission mismatch,” “Duplicate request,” “Does not meet time requirements,” and “Business conditions not met.” The number of reasons should not be too large; otherwise, approvers will repeatedly search through the list, which reduces efficiency instead.
3. Set Reasonable Validation for Custom Detail
Rejection detail should usually meet the following rules:
- It cannot be empty;
- It cannot contain only spaces or line breaks;
- A reasonable minimum length should be set to avoid invalid information such as “none” or “not approved”;
- A maximum length should be set to prevent large amounts of irrelevant content;
- Clear feedback should be shown for overlong text rather than silently truncating it after submission;
- Line breaks should be preserved, but obviously meaningless repeated characters should be filtered;
- Unprocessed special content should not be displayed directly on the frontend.
The minimum length should not be set mechanically too high. The goal of a rejection reason is clarity, not forcing approvers to write long reports. For simple scenarios, one specific sentence may be enough. For complex scenarios, approvers should be allowed to add necessary background.
3. Approval Card Status Display Must Be Updated at the Same Time
Adding an input field is not enough. After submission succeeds, the rejection reason must be visible in the approval card. Otherwise, the data may be saved, but users still cannot receive feedback.
It is recommended to distinguish two stages of the approval card:
Before Approval
Display:
- Current approval status;
- Available action buttons;
- Key summary of the approval object;
- Necessary risk notices.
After Approval
Display:
- Final result;
- Actor;
- Processing time;
- Standard rejection reason;
- Specific additional detail;
- Whether resubmission or appeal is allowed.
For example:
Approval result: RejectedProcessed by: [approver]Processed at: 2025-XX-XX XX:XXRejection reason: Incomplete materialsAdditional detail: Missing budget explanation and owner confirmationNext step: Resubmit after completing materials
In this way, the requester can understand the problem without asking the approver again. For auditing, retrospective review, and customer support, this structured display is also more reliable.
4. Data Consistency Is the Most Easily Missed Issue in Plugin Development
Approval plugins usually involve frontend interaction, server-side processing, message updates, and persistent records. If any part is not updated in sync, state inconsistency may occur.
Common problems include:
- The frontend shows rejected, but the server does not save the reason;
- The reason is saved, but the approval card is not refreshed;
- Repeated clicks create multiple rejection records;
- A network timeout followed by another submission causes duplicate processing;
- The approval status has changed, but an old page still shows actionable buttons;
- The database write succeeds, but notification delivery fails, so relevant people are not informed in time.
Therefore, a rejection operation should not be treated only as an interface event. It should be handled as a business transaction with a complete lifecycle.
The recommended server-side processing order is:
Validate request identity↓Validate that the approval object exists↓Validate that the current status allows rejection↓Validate rejection reason and additional detail↓Update approval main record↓Write operation log↓Send status-change notification↓Return latest approval card data
If the system uses transactions, the main record update and operation log should be kept consistent as much as possible. Notification delivery can use a reliable asynchronous mechanism according to the system architecture, but it must support failure retry and status tracking. The approval result must not be silently lost because notification delivery fails.
5. Handle Concurrency and Duplicate Submissions
Approval scenarios often involve concurrent operations. For example, two approvers open the same approval card at the same time. One completes a rejection first, and the other still clicks the button afterward. If the server trusts only the frontend state, overwrites or duplicate processing may occur.
The server must confirm the current state again and must not rely only on disabled buttons in the frontend.
The following strategies can be used:
- Add a version number to each approval record;
- Include the version information read at submission time;
- Check whether the version still matches during update;
- Return “Approval status has changed” when it does not match;
- Use an idempotency identifier to prevent the same request from being executed repeatedly;
- For an approval operation that has already been completed, return the current final state instead of writing again.
Pseudo-code example:
if request.version != record.version:return status updated, refresh pageif record.status != PENDING:return approval already completedvalidate(reason_code, reason_detail)update recordinsert audit_logreturn latest_record
This avoids serious problems such as “the submission appears successful but actually overwrites another person’s approval result.”
6. Recovery After Plugin Crashes Is Equally Important
In actual development, plugins may crash because of data structure changes, invalid input, rendering errors, or incomplete state handling. This is especially important when adding new fields: if old data has no rejection reason and the frontend reads nested properties directly, the page may fail.
Therefore, new fields must be compatible with historical data:
const detail = record.reason_detail || "No additional detail provided";
At the same time, note the following:
- Use safe defaults on the frontend when the server returns missing fields;
- Do not assume that all historical records have the new fields;
- Perform type checks when parsing external input;
- Escape user input during rendering;
- Record context for abnormal requests to help locate problems;
- Preserve the original approval card content as much as possible when partial errors occur;
- Provide reload or recovery actions instead of showing a blank page.
If the plugin has debug logs, distinguish information logs, validation failure logs, and system exception logs, and avoid writing complete sensitive content to logs. The goal of logging is to locate problems, not to copy all business data.
7. Testing Must Go Beyond “Can It Submit”
The rejection reason feature should cover at least the following test scenarios:
Normal Scenarios
- Select a standard reason and enter detail, and the rejection succeeds;
- Submit with only a standard reason when allowed;
- After successful submission, the card displays the latest result;
- The requester and relevant people receive the status update.
Input Validation
- Submit without selecting a reason;
- Additional detail is empty;
- Only spaces or line breaks are entered;
- Input exceeds the maximum length;
- Special characters are entered;
- Repeated meaningless content is entered.
State Anomalies
- Click reject again after approval is already completed;
- Multiple people operate at the same time;
- Resubmit after a network timeout;
- The server returns an unknown state;
- A historical record lacks the rejection reason field.
System Exceptions
- Database update fails;
- Log write fails;
- Notification delivery fails;
- Page refresh fails;
- Whether state remains consistent after the plugin reloads.
The focus of testing is not simply confirming that the button can be clicked, but verifying that “result, reason, display, logs, and notifications” remain consistent.
8. Extract More Business Value from Rejection Reasons
Once rejection reasons are recorded in a structured way, they are no longer just prompts for the requester. They can also help managers identify process problems.
For example, you can analyze:
- Which reason types occur most frequently;
- Which step most often causes incomplete materials;
- Which request types are often resubmitted;
- Which rules are unclear and cause approvers to repeatedly write similar details;
- Where judgment standards differ significantly among approvers.
If a certain type of rejection accounts for a high proportion over a long period, the problem may be in process design rather than in the requester. For example, the form may not prompt required materials in advance, the rule description may not be clear enough, or the system may not perform basic validation before submission.
Therefore, the ultimate goal of adding rejection reasons is not to make rejection messages longer. It is to give the approval system better explanation, traceability, and improvement capabilities.
Conclusion
The value of an approval card is not only in telling users “approved” or “rejected.” It also lies in explaining how the result was produced and what should be done next.
Adding standard reasons and specific detail to the rejection action can reduce repeated communication, improve processing efficiency, complete audit records, and provide reliable data for later process optimization. For plugin developers, the real focus is not only the input field itself, but also the data model, state consistency, concurrency control, exception recovery, and test coverage.
When approval results no longer require guessing, the approval workflow has a real foundation for being explainable, actionable, and reviewable.
