All posts
Liferay · 12 min read · Mar 13, 2026

Designing File-Level Verification in Liferay Workflows

Per-file approval and rejection inside a workflow task

Almost every government, finance, and onboarding process shares the same shape. An applicant submits a form with attachments - identity proof, a quotation, a bank letter, a site photograph - and a reviewer has to check each attachment individually. One bad document should not invalidate the other six, and the applicant should be told precisely which file to fix rather than being sent back to start over.

Liferay's workflow engine does not model this directly, and that is not a defect. A workflow instance tracks one entity through one lifecycle. Your submission is that entity; the files are data belonging to it. Trying to make the engine hold per-file decisions is the single most common design mistake here, and it produces workflows that are impossible to change later.

Two decisions, not one

The clean mental model is that there are two distinct decisions in this process, operating at different levels:

  • The file decision: is this specific document acceptable? Made many times, by a reviewer, against one attachment.
  • The task decision: can this submission move to the next stage? Made once, derived from the file decisions.

The file decision belongs in your data model. The task decision belongs in the workflow. Once you draw that line, everything else follows - including the parts that are usually painful, like partial resubmission and audit history.

Modelling the documents

The submission and its documents are a straightforward one-to-many relationship, which makes this a natural fit for Liferay Objects or a custom entity, depending on how much logic you need around it. What matters is that each document row carries its own verification state rather than the parent carrying a list of problems.

FieldPurpose
documentTypeWhich requirement this file satisfies, from a picklist rather than free text
fileEntryIdThe actual uploaded file in the document library
verificationStatusPending, Verified, or Rejected
rejectionReasonA coded reason plus optional free text, shown to the applicant
verifiedBy / verifiedDateWho decided and when, for audit
revisionHow many times this specific document has been replaced
Verification state lives on the document, not on the submission.

Using a coded rejection reason rather than a free-text comment is worth insisting on early. Coded reasons can be reported on, translated, and used to drive the applicant-facing message. Free text cannot, and once reviewers have been typing paragraphs for a year you will not be able to retrofit it.

Deriving the task outcome

The reviewer approves and rejects individual files through your own screens, which call the entity API directly. None of that touches the workflow. Only when the reviewer completes the task does the aggregate decision get made, and that rule should be written down in exactly one place:

text
any document is Pending      -> the task cannot be completed
any document is Rejected     -> outcome = Send back for correction
all documents are Verified   -> outcome = Approve
One derivation rule, applied consistently, replaces per-file workflow branches.

Enforcing the Pending case in the user interface is not enough. The same rule has to be checked server side before the transition is allowed, because tasks can be completed through the API, by an administrator, or by a reassignment that bypasses your screen entirely.

Sending back only what is wrong

Send-back is where most implementations quietly get it wrong. The instinctive behaviour - reopen the whole submission for editing - punishes the applicant for the reviewer's precision and invalidates work that was already verified. The better behaviour is narrow:

  1. Documents marked Verified are locked. The applicant can view them but not replace them.
  2. Documents marked Rejected are unlocked, with the coded reason shown next to each one.
  3. Replacing a rejected document resets that document to Pending and increments its revision.
  4. Other fields on the submission stay read-only unless the rejection reason specifically concerns them.

The rule that makes this safe is that replacing a file always resets its status. A verified document that is later swapped must go back to Pending, or you have created a path where unreviewed content carries a verified stamp. That path is exactly the kind of gap an auditor will find.

Keeping history instead of overwriting it

Storing verificationStatus as a single mutable field answers what is the state now but destroys how did we get here. In a process that can loop several times, the second question is the one people actually ask - usually months later, when someone disputes a decision.

The fix is to append a verification event row every time a decision is made, and treat the field on the document as a cached view of the latest event. Each event records the document, its revision, the decision, the reason, the actor, and the timestamp. This gives you a defensible audit trail, a per-reviewer quality report, and the data to answer which requirement causes the most rework - which is usually the most valuable output of the entire system.

The cases that break naive implementations

SituationNaive behaviourWhat it should do
Reviewer rejects, then changes their mindStatus flips silentlyRecord both events; latest wins, history retained
Applicant replaces a verified fileKeeps the verified flagReset to Pending and require re-verification
A new document requirement is added mid-processSubmission looks completeNew requirement enters as Pending and blocks completion
Applicant resubmits without fixing anythingLoops foreverCount send-backs and escalate after a threshold
Two reviewers open the same submissionLast write winsLock at document level or detect concurrent edits

The resubmission loop deserves particular attention. Without a counter, a determined applicant and a patient reviewer can bounce a submission indefinitely, and nobody in the organisation will notice because each individual step looks normal. Counting send-backs on the submission and escalating after the second or third is a small amount of code that prevents a genuinely expensive failure mode.

What the reviewer actually needs on screen

The interface matters as much as the model here, because the reviewer is making many small decisions in sequence. Three things reliably reduce errors: showing the document preview next to the approve and reject controls so nobody decides from a filename, showing the previous rejection reason when a document is on its second revision, and making the completion button visibly blocked with an explanation rather than simply disabled.

It is also worth showing the applicant exactly what the reviewer saw. Most disputes in these processes come from an applicant believing they submitted something acceptable, and a shared view of the same document and the same coded reason ends the argument quickly.

Conclusion

File-level verification is not a workflow feature to be configured - it is a data model to be designed, with the workflow reading a summary of it. Keep per-file decisions in your own entities, derive the task outcome from one written rule, unlock only what was rejected, and append history rather than overwriting it. Do that and the workflow definition stays small and stable even as the document requirements change, which is exactly the property you want when the next stage of the process depends on this one.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar