Quality assurance API — review and status transitions - PRMS — Planning, Reporting & Management System

The Quality Assurance (QA) module controls the transition of results from the Editing stage through to Quality Assessed and ultimately Submitted. QA reviewers examine result content, record structured comments, and make go/return decisions. All actions are tracked in an immutable review history for audit purposes. All endpoints require the auth: <JWT> header. Endpoints that record QA decisions additionally require the authenticated user to hold an appropriate QA reviewer role.

Authentication and roles

QA decision endpoints require the user to hold an appropriate reviewer role for the result’s owning initiative or action area. Read-only endpoints (review history, pending queue) are accessible to any authenticated user with visibility of the result. Role enforcement is applied via ValidRoleGuard and the @Roles decorator on the server.

auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Status transition model

Results move through statuses as QA decisions are made:

Editing (1) ──────────────────────────────────────────────────────────────────────►
                │ positive QA decision                                              │
                ▼                                                                   │ returned with comments
        Quality Assessed (2)                                                        │
                │ submission                                                        │
                ▼                                                                   │
          Submitted (3) ◄─────────────────────────────────────────────────────────►│
                                                                                    │
                      Discontinued (4) — terminal state                             │
                                                                                    │
Billing-specific statuses (W3/Bilateral results only):                              │
   Pending Review (5) ──► Approved (6)                                             │
                    └───► Rejected (7) ─────────────────────────────────────────────

ID	Name	Description
1	Editing	Result is being authored. Default on creation.
2	Quality Assessed	QA reviewer has assessed the result positively.
3	Submitted	Result has been formally submitted to the reporting cycle.
4	Discontinued	Result has been discontinued (terminal state).
5	Pending Review	Bilateral result awaiting reviewer decision.
6	Approved	Bilateral result approved by a reviewer.
7	Rejected	Bilateral result rejected; returned for revision.

A standard result progresses: Editing (1) → Quality Assessed (2) → Submitted (3). A positive QA decision advances the status to Quality Assessed; returning a result with comments resets it to Editing.

QA log endpoints (`/api/result-qaed/*`)

The result-qaed module persists result_qaed_log records. Each log row captures the date, the reviewing user (qaed_user), and any comments made at the time of assessment.

The result-qaed controller is currently a minimal scaffold. The QA workflow is primarily surfaced through the result review history (see below) and submission endpoints. The log table result_qaed_log is written by the service layer when QA transitions occur.

QA log record fields (from the result_qaed_log entity):

number

Primary key (bigint).

result_id

number

The result this log entry belongs to.

qaed_date

string

Date the QA action was taken (YYYY-MM-DD).

qaed_comments

string

Free-text comments recorded by the QA reviewer. Nullable.

qaed_user

number

User id of the QA reviewer who made the decision.

Review history endpoints

The review history provides an immutable audit trail of every QA decision and bilateral review action taken on a result. Records are written each time a status transition occurs (approve, reject, or update).

Get review history for a result

GET /api/results/result-status/get/:resultId

Review history records are stored in the result_review_history table and surfaced via the result-status sub-module. Each record captures the action taken, the reviewer’s comment, and the timestamp.

resultId

number

required

Internal result id whose review history you want to retrieve.

Response fields

response

array

Array of review history records, ordered by created_at descending.

Show Review history record fields

number

Primary key of the history record.

result_id

number

The result this record belongs to.

action

string

One of "APPROVED", "REJECTED", or "UPDATE". Maps to the ReviewActionEnum.

comment

string

Reviewer comment. Required for REJECTED actions; optional for APPROVED and UPDATE.

created_by

number

User id of the reviewer who recorded this action.

created_at

string

ISO-8601 timestamp of when this record was created.

Example

curl https://prms.example.org/api/results/result-status/get/1042 \
  -H "auth: $TOKEN"

Example response

{
  "response": [
    {
      "id": 201,
      "result_id": 1042,
      "action": "APPROVED",
      "comment": "Result data is complete and well-evidenced.",
      "created_by": 15,
      "created_at": "2024-04-12T10:23:00.000Z"
    },
    {
      "id": 198,
      "result_id": 1042,
      "action": "REJECTED",
      "comment": "Evidence links are broken. Please update and resubmit.",
      "created_by": 15,
      "created_at": "2024-04-10T14:05:00.000Z"
    }
  ],
  "message": "Successful response",
  "status": 200
}

Submission endpoints (QA lifecycle triggers)

Status transitions are triggered through the submissions sub-module. These are the endpoints that advance or retract QA status.

Submit a result for QA

Advances a result toward Submitted (3) status. The result must already be Quality Assessed (2) or pass server-side validation to proceed.

PATCH /api/results/submissions/submit/:resultId

resultId

number

required

Internal result id to submit.

comment

string

Optional submission comment recorded in the review history.

Example

curl -X PATCH https://prms.example.org/api/results/submissions/submit/1042 \
  -H "auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "All sections complete. Submitting for the 2024 reporting cycle." }'

Unsubmit (retract) a result

Returns a submitted result to Editing (1) status, allowing the author to make further changes.

PATCH /api/results/submissions/unsubmit/:resultId

resultId

number

required

Internal result id to retract.

comment

string

Optional comment explaining the retraction.

Submit an IPSR innovation package

Submits an innovation package to the reporting cycle.

PATCH /api/results/submissions/submit-ipsr/:resultId

resultId

number

required

Internal result id of the innovation package.

Unsubmit an IPSR innovation package

Retracts an innovation package submission.

PATCH /api/results/submissions/unsubmit-ipsr/:resultId

resultId

number

required

Internal result id of the innovation package.

Bilateral review decision endpoints

W3/bilateral results (source = "API") use a separate review workflow with Pending Review (5), Approved (6), and Rejected (7) statuses. These endpoints require the reviewer role for the respective bilateral portfolio.

Approve or reject a bilateral result

PATCH /api/results/bilateral/:resultId/review-decision

resultId

number

required

Internal result id. The result must be in Pending Review (5) status.

decision

string

required

"APPROVED" to advance to Approved (6), or "REJECTED" to move to Rejected (7).

justification

string

Explanation of the decision. Required when decision is "REJECTED". Stored in the review history.

Example — reject with comment

curl -X PATCH https://prms.example.org/api/results/bilateral/512/review-decision \
  -H "auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "REJECTED",
    "justification": "The geographic scope does not match the grant agreement. Please revise."
  }'

Update bilateral data standard fields under review

Updates ToC fields and Minimum Data Standard fields of a bilateral result that is in Pending Review status. Requires an update explanation when any field is modified.

PATCH /api/results/bilateral/review-update/data-standard/:resultId

resultId

number

required

Internal result id.

updateExplanation

string

required

Explanation of what was updated and why.

title

string

Updated result title.

description

string

Updated result description.

geographic_scope_id

number

Updated geographic scope identifier.

Update bilateral ToC metadata under review

Updates the result_toc_result ToC metadata for a bilateral result in Pending Review status.

PATCH /api/results/bilateral/review-update/toc-metadata/:resultId

resultId

number

required

Internal result id.

updateExplanation

string

required

Explanation of the metadata change.

toc_result_id

number

Updated ToC result node id.

Validation module

Before a result or package can be submitted, a server-side validation check confirms that all required sections are complete. The validation module is accessible through the result sub-resources:

GET /api/results/results-validation/:resultId

Returns a field-by-field validation summary indicating which sections are complete, incomplete, or have warnings. The submission endpoints internally invoke this validation and will return an error if required sections are missing. Validation response fields

response

object

Validation summary object.

Show Validation fields

is_valid

boolean

true when all required sections are complete.

validation

array

Array of validation check objects, one per section.

Show Section check fields

section

string

Section name (e.g. "general_information", "geographic_scope", "partners").

completed

boolean

Whether the section passes validation.

message

string

Human-readable validation message shown in the UI.

Similarly, IPSR packages use:

GET /api/ipsr/results-innovation-packages-validation-module/:resultId

Home / aggregate QA metrics

The home module exposes aggregate QA metrics used on the PRMS landing page. These give initiative leads and PMU staff a high-level view of QA pass rates per phase.

GET /api/home

The home endpoint returns, among other things:

response.qa_summary

object

QA pass rate aggregates for the current reporting phase.

Show QA summary fields

total_results

number

Total active results in the current phase.

quality_assessed

number

Results with status Quality Assessed (2) or higher.

submitted

number

Results with status Submitted (3).

qa_pass_rate

number

Percentage of results that have passed QA (quality_assessed / total_results * 100).

Pending review count

Returns the count of results currently awaiting QA review for a specific Science Program.

GET /api/results/pending-review

programId

string

required

Program identifier (e.g. SP01).

Example

curl "https://prms.example.org/api/results/pending-review?programId=SP01" \
  -H "auth: $TOKEN"

Response

{
  "response": {
    "programId": "SP01",
    "pending_count": 14
  },
  "message": "Successful response",
  "status": 200
}

QA workflow summary

The typical QA lifecycle for a standard result:

Author creates result — status_id = 1 (Editing).
Author completes all sections — validation module confirms completeness.
Author submits — PATCH /api/results/submissions/submit/:resultId advances toward QA queue.
QA reviewer examines result — checks content, evidence, geographic scope, partners, ToC alignment.
Reviewer approves — result transitions to Quality Assessed (2). A APPROVED record is written to result_review_history.
Reviewer returns with comments — result reverts to Editing (1). A REJECTED record with the comment is written to result_review_history. The author sees the comment and revises.
Repeat steps 3–6 as needed until approval.
Final submission — from Quality Assessed (2) the author submits again, advancing to Submitted (3).

Only users with the appropriate QA reviewer role assignment for the result’s owning initiative or action area can record QA decisions. Authors cannot approve their own results. The server enforces this via ValidRoleGuard.

Overview

Results

Reporting Surfaces

Administration

Quality assurance API — review and status transitions

Authentication and roles

Status transition model

QA log endpoints (`/api/result-qaed/*`)

Review history endpoints

Get review history for a result

Submission endpoints (QA lifecycle triggers)

Submit a result for QA

Unsubmit (retract) a result

Submit an IPSR innovation package

Unsubmit an IPSR innovation package

Bilateral review decision endpoints

Approve or reject a bilateral result

Update bilateral data standard fields under review

Update bilateral ToC metadata under review

Validation module

Home / aggregate QA metrics

Pending review count

QA workflow summary

Build docs developers (and LLMs) love

Overview

Results

Reporting Surfaces

Administration

Documentation Index

​Authentication and roles

​Status transition model

​QA log endpoints (/api/result-qaed/*)

​Review history endpoints

​Get review history for a result

​Submission endpoints (QA lifecycle triggers)

​Submit a result for QA

​Unsubmit (retract) a result

​Submit an IPSR innovation package

​Unsubmit an IPSR innovation package

​Bilateral review decision endpoints

​Approve or reject a bilateral result

​Update bilateral data standard fields under review

​Update bilateral ToC metadata under review

​Validation module

​Home / aggregate QA metrics

​Pending review count

​QA workflow summary

Build docs developers (and LLMs) love

Authentication and roles

Status transition model

QA log endpoints (`/api/result-qaed/*`)

Review history endpoints

Get review history for a result

Submission endpoints (QA lifecycle triggers)

Submit a result for QA

Unsubmit (retract) a result

Submit an IPSR innovation package

Unsubmit an IPSR innovation package

Bilateral review decision endpoints

Approve or reject a bilateral result

Update bilateral data standard fields under review

Update bilateral ToC metadata under review

Validation module

Home / aggregate QA metrics

Pending review count

QA workflow summary