Amend a released report (§7.8.8)

Goal

Issue an amended version of an analysis report that has already been approved and released to the customer, in full compliance with ISO/IEC 17025 §7.8.8 (immutability: the original version is retained, the new version is appended with an incremented number).

Prerequisites

The analysis (AnalysisRecord) is in Approved (APPROVED) status.
Draft (DRAFT), cancelled (CANCELLED), under-review (REVIEWED), or already-amended (AMENDED) records cannot be amended from this entry point.
At least one original report version (ReportVersion v1) has been issued.
Created automatically on the first approval.
The current user holds the LAB_DIRECTOR role.
Reviewer / Analyst cannot amend a released report. The backend rejects the call with 403 Forbidden.
The amendment reason has been drafted as plain text.
Recommended minimum length: ≥ 20 characters.
Non-empty is enforced by the backend (validated via reason?.trim()).
The root cause of the amendment is identified. Typical examples:
Incorrect measurement detected after the fact.
Sample mis-identification (e.g. intake swap).
Method-selection correction.
Late QC data that flips the conformity decision.
After-the-fact instrument re-calibration.
The quality manager has been notified.
Amending a released report is a nonconformity and may trigger a corrective action (CAPA) under §8.7.

Steps

Open Analyses (/analyses) and locate the approved analysis. Filter by status Approved if needed.
Click the code to open the detail page (/analyses/:id).
Click the kebab menu (three vertical dots) in the top-right corner of the detail card.
Select "Amend". The action is visible only when status is APPROVED and the current user is LAB_DIRECTOR.
In the prompt, enter the amendment reason.

Example: "Correct pH from 6.8 to 7.2 following electrode re-calibration on 2026-05-22. Re-measured by analyst Papadopoulos."
State: what is changing, why, who, when.

Confirm. The backend:

transitions status to AMENDED,
clears the reviewedById/reviewedAt/approvedById/approvedAt columns,
returns success and fires a push notification to reviewers.

Edit the measurements / fields that require correction. The record is editable again.
Re-submit for Review (Reviewer) and then Approve (LAB_DIRECTOR).

On re-approval a new ReportVersion (v2, v3, ...) is created automatically.
The REPORT_AMENDED email is sent to the customer.

Verify in the Version History tab that the new version appears with the correct version number, timestamp, and generator identity.

What happens behind the scenes

Frontend mutation call. The kebab action invokes the Apollo mutation amendAnalysisRecord(analysisRecordId, reason).
Implementation: apps/agrometrisis/src/app/analyses/analysis-detail.ts:861-885 (amendRecord(), using window.prompt to collect the reason).
Backend mutation handler. Implemented in apps/agrometrisis-api/src/app/modules/analysis-records/analysis-record.resolver.ts:1451-1493 (amendAnalysisRecord, gated by @Roles('LAB_DIRECTOR')).
Validates APPROVED status.
Rejects an empty reason.
Updates the record with status=AMENDED, amendmentReason=reason.trim().
Clears reviewedById/reviewedAt/approvedById/approvedAt.
Real-time broadcast. The status change is published via pubSub.publish('analysisRecordStatusChanged', ...) so every connected client refreshes automatically.
Push notification to lab users. PushNotificationService.notifyReportAmended(sampleCode, analysisRecordId, reason, excludeUserId) is called (see push-notification.service.ts:315-332).
Sends an FCM message (report.amended.title / report.amended.body).
Target: every user with NotificationPreference.statusChanges = true.
Excludes the actor (excludeUserId).
New ReportVersion — not now, on the next approval. The new version is not created during the amendment step itself.
It is created on the next approval, at analysis-record.resolver.ts:1422 (this.reportVersionService.createSnapshot(analysisRecordId, userId)).
createSnapshot() computes nextVersion = lastVersion.version + 1 (see report-version.service.ts:22-34).
Persists a full JSON snapshot in the snapshot longtext column, together with generatedById.
This is what makes v1 immutable: v2 is appended as a separate row — the substantive requirement of §7.8.8.1.
PDF banner. The new version's PDF embeds an amendment banner.
Text: "This version amends the previous one — the original remains on record for historical reference."
Required by §7.8.8.2 (must be identifiable as an amendment).
Audit trail. AnalysisRecordStatusLog captures the APPROVED → AMENDED transition.
noteCode = REPORT_AMENDED, timestamp, actor, reason.
The same log table captures the subsequent AMENDED → APPROVED transition.
Customer email. ClientEmailService.queueEmail(ClientEmailType.REPORT_AMENDED, contactId, analysisRecordId, …) is triggered from the next approval.
Deduplication is per-AnalysisRecord.
A second amendment on the same record will not enqueue a duplicate email if the previous queue entry is still active.
Customer delivery. The customer receives an email of type REPORT_AMENDED with a link to the new version.
The original version remains accessible through the ReportVersion history (findAllByAnalysisRecord in report-version.service.ts:39-54).

Common pitfalls

Bypassing the kebab. Do not try to edit measurements through any other route.
While status is APPROVED the record is locked at the resolver level.
The only legitimate path is Amend from the kebab.
Reason < 20 characters. The backend accepts any non-empty string, but an ESYD auditor will require substantive justification.
State what, why, who, and when.
Deleting the original report. Not allowed and not possible.
v1 remains in the reportVersions table as an immutable row.
§7.8.8 mandates retention.
Using "Cancel" instead of "Amend". Cancel (cancelAnalysisRecord) is terminal and is reserved for cases where the analysis will never be re-issued.
If you want a corrected report, always use Amend.
Repeated amendments. Allowed (v3, v4, ...), but each additional amendment is a red flag in audit.
If 3+ amendments are needed, consider full retraction under §7.10 (nonconformities) and re-issuing a complete new report under §7.8.8.3.