When Document Search Results Change

Keep review progress tied to documents as the result list changes

Published

Cream, cobalt and teal illustration connects document search results, a separate progress checklist and a changed document marked for rechecking.

Procurement opens a list of supplier certificates awaiting renewal review. While one officer works through the first page, another approves a replacement and a new certificate arrives. The list has changed before the officer selects Next. A document's position in that list cannot serve as the record of whether it was reviewed.

Use the returned token to continue the same search, and keep review progress against the document being reviewed. Recheck current content, permissions and review state before recording a decision. A continuation token tells the application how to request another page; it does not freeze the repository or prove that a review is complete.

Keep three pieces of state separate

  1. 1 · Continue

    Keep the active search together

    Use its operation, site, filters and returned continuation token.

  2. 2 · Record

    Track the reviewed evidence

    Connect the document and reviewed version to its decision and owner.

  3. 3 · Recheck

    Resolve changes before acting

    Inspect replacements, changed permissions and competing decisions.

Follow the operation's continuation contract

For token-paginated FormKiQ metadata search, send the first request without next. Process its documents, then pass a nonempty returned next value back through the query parameter with the same search body and site. Treat it as opaque: do not decode it, edit it or calculate the next position yourself. Use the HTTP client's query-parameter encoding once.

Continue until the response has no continuation token. A short page is not enough to stop. A filtered search can even return an empty document page with a token because more candidates remain to be checked. The pagination reference documents these rules and explains why the cursor is not a snapshot.

A small metadata-search example

In this illustrative application, the procurement site has a populated string attribute named renewalReviewState. These are configured example names, not supplied default fields. Send this body to POST /search?siteId=procurement&limit=25 with the deployment's authentication:

{
  "query": {
    "attribute": {
      "key": "renewalReviewState",
      "eq": "awaiting-review"
    }
  }
}

If the response includes next, repeat the request with that returned value in the next query parameter. Preserve the body and page-size choice. An HTTP error is a failed request, not an empty final page; resolve it without recording the search as complete.

Check the Document Search API for the deployed release and query shape. The current reference documents eqOr searches without pagination and bounded documentIds requests that ignore limit. Full-text operations have their own contracts. Do not apply this loop to every endpoint or query mode.

Decide what a changed result means

Application behaviour for a live document review list.
ChangeSearch handlingReview handling
An earlier document appears againRecognise the document ID and avoid duplicating the displayed row.Keep its recorded decision; assess whether the content or review state has changed.
Filters, site or user context changeStart a new search, clear its prior continuation state and ignore late results from the old search.Keep saved decisions in their authorised context rather than in the browser's row positions.
A replacement arrives or another officer actsAllow a refresh to show current matches without claiming to preserve the earlier set.Check current evidence and decision state before accepting a new action.
A record is removed or access endsHandle the unavailable record and refresh or clear stale cached content as appropriate.Show an owned unresolved item where needed; absence from results is not a review decision.

Removing duplicate rows improves the screen, but cannot recover a document missed while the result set changed. Refreshing the search may also introduce new work. Make that behaviour clear, and avoid labelling the last returned page “all documents reviewed.” Enforce current authorisation and business preconditions when accepting a decision; a cached row does not supply either.

Worked example: a replacement arrives during renewal review

This fictional interaction extends VEN-1042's supplier renewal workflow. Procurement's configured queue lists certificates awaiting review.

  1. Open the current queue

    The officer searches the procurement site and receives the first page. The application keeps the search body, context and returned token together. It identifies each row by document ID.

  2. Record a review separately

    The officer opens a certificate, checks its current content and records the authorised outcome through the review workflow. The decision identifies the evidence reviewed. Its progress survives a refresh or a move to another result page.

  3. Continue while another officer acts

    A colleague approves Example Facilities Services' replacement. The next page request continues the original search, but does not promise the earlier list is unchanged. Repeated documents do not create duplicate review actions.

  4. Recheck the affected supplier file

    If the first officer opens an older result for VEN-1042, the application checks current state. It shows the accepted replacement and earlier evidence in the supplier file, so the officer can resolve the intended task against the correct certificate.

  5. Distinguish the end of the search from the end of the work

    When no token remains, that continuation has ended. The officer can still see saved outcomes and unresolved work, and refresh for new matches. A formal review of a fixed population needs its own agreed selection and completion checks.

Use an explicit selection for a fixed review or export

If a manager needs every certificate in an agreed monthly review, define how that population is established and checked. Retain the selected document IDs, required versions and any exceptions. If the repository keeps changing during enumeration, reconcile that selection against an authoritative inventory or another agreed capture process before declaring it complete.

A modification-date cutoff alone does not reconstruct historical state: a record updated after the cutoff may no longer match the query. A live token likewise provides no retained point-in-time result set. Confirm an appropriate capture or historical-data approach for that requirement instead of treating pagination as one. The bulk document export guide covers approval, version checks and delivery of an agreed selection.

Check one changing results screen

  • Preserve the operation, site, body and opaque token throughout one search.
  • Test a short or empty page with a continuation token, and handle HTTP errors separately.
  • Start again when the active search context changes and ignore obsolete responses.
  • Keep review outcomes against document identity and reviewed evidence, beyond the browser session.
  • Recheck permissions, content and competing decisions before accepting an action.
  • Verify fixed-population reviews separately from reaching the final search page.

Keep the search useful as work progresses

A live list helps staff find the next document. The review record explains what they decided about the evidence. Keep those responsibilities connected, and make changed or unresolved work visible without promising that a sequence of pages preserves the original population.

      Start with FormKiQ Core

      The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.

      Get Started Free

      Deploy FormKiQ Essentials or Advanced

      Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.

      Explore Options

      Plan an Enterprise Rollout

      For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.

      Book a Call