Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/onecgiar_pr/llms.txt

Use this file to discover all available pages before exploring further.

The versioning API controls the lifecycle of reporting phases in PRMS. Each phase represents a discrete reporting window — identified by a year and sub-phase name — within which results can be created and submitted. Admins use these endpoints to open or close phases, create new ones, and trigger the replication process that carries results forward into the next cycle. All endpoints under /api/versioning/* require a valid JWT in the auth header. Write operations (create, update, delete, replication) additionally require the Admin role (RoleEnum.ADMIN) scoped to the Application role type (RoleTypeEnum.APPLICATION). Requests that fail role checks return 403 Forbidden.
Triggering annual replication (PATCH /api/versioning/execute/annual/replicate/*) is a long-running, portfolio-wide operation. It copies results from the current active phase into the next phase. Run it only once per cycle and only after verifying that the target phase is configured correctly.

​
Phase object

A phase (stored in the version table) has the following fields:
​
id
number
Auto-generated primary key (bigint).
​
phase_name
string
Human-readable label for the phase, for example "Reporting 2024".
​
phase_year
number
The four-digit reporting year this phase belongs to (MySQL YEAR type).
​
start_date
string
ISO date string marking when the phase opens for result submission.
​
end_date
string
ISO date string marking the submission deadline for this phase.
​
status
boolean
Whether the phase is currently open (true) or closed (false). Closing a phase prevents new submissions.
​
previous_phase
number
Foreign key referencing the phase that preceded this one. Used during rollover to determine which results are eligible for replication.
​
app_module_id
number
Links the phase to an application module: 1 = Reporting, 2 = IPSR.
​
reporting_phase
number
Self-referential FK pointing to the parent reporting phase. Sub-phases nest under a top-level reporting phase.
​
toc_pahse_id
string
Identifier of the corresponding Theory of Change phase in the external ToC system.
​
portfolio_id
number
Optional CLARISA portfolio this phase is associated with.

​
Endpoints

​
List phases

GET /api/versioning
Returns phases filtered by module type, submission status, and active state. All query parameters are optional and default to module=all, status=open, active=active.
​
module
string
Filter by application module. One of all (default), reporting, ipsr.
​
status
string
Filter by submission window status. One of open (default), close, all.
​
active
string
Filter by active state. One of active (default), inactive, all.
Auth: JWT required (auth header). No special role needed.

​
List all phases (unfiltered)

GET /api/versioning/all
Returns every phase record without filtering. Use this to build admin UIs that need a full phase inventory. Auth: JWT required. No special role needed.

​
Get version of a result

GET /api/versioning/result/:resultId
Returns the phase version associated with a specific result.
​
resultId
number
required
PRMS result ID.
Auth: JWT required. No special role needed.

​
Get result counts by status and type

GET /api/versioning/number/results/status/:statusId/result-type/:resultTypeId
Returns the number of results replicated for a given status and result type. Useful for monitoring rollover progress.
​
statusId
number
required
Result status ID (for example 1 = Editing, 3 = Submitted).
​
resultTypeId
number
required
Result type ID matching ResultTypeEnum (for example 1 = Policy Change, 6 = Knowledge Product).
Auth: JWT required. No special role needed.

​
Create a phase

POST /api/versioning
Creates a new reporting phase. Only admins may call this endpoint. Auth: JWT required. RoleEnum.ADMIN + RoleTypeEnum.APPLICATION enforced by ValidRoleGuard. Request body:
​
phase_name
string
required
Display name for the new phase.
​
phase_year
number
required
Four-digit reporting year.
​
start_date
string
required
Phase open date (ISO date string).
​
end_date
string
required
Submission deadline (ISO date string).
​
app_module_id
number
required
Module association: 1 = Reporting, 2 = IPSR.
​
previous_phase
number
ID of the phase that precedes this one. Required when rollover replication will be used.
​
reporting_phase
number
ID of the parent reporting phase for sub-phase nesting.
​
toc_pahse_id
number
Corresponding Theory of Change phase identifier.
​
portfolio_id
number
CLARISA portfolio ID to associate with this phase.

​
Update a phase

PATCH /api/versioning/:id
Updates settings on an existing phase. Use this to open or close submission windows, rename a phase, or change its portfolio link. Auth: JWT required. RoleEnum.ADMIN + RoleTypeEnum.APPLICATION.
​
id
number
required
Phase ID to update.
Request body:
​
phase_name
string
New display name.
​
status
boolean
Set to true to open the phase for submissions; false to close it.
​
previous_phase
number
Update the predecessor phase reference.
​
portfolio_id
number
Update the CLARISA portfolio association.

​
Delete a phase

DELETE /api/versioning/:id
Removes a phase record. Use only on phases that have no associated results. Auth: JWT required. RoleEnum.ADMIN + RoleTypeEnum.APPLICATION.
​
id
number
required
Phase ID to delete.
Deleting a phase that already has results linked to it will leave those results in an inconsistent state. Verify the phase has no results before calling this endpoint.

​
Process phase change for a result

PATCH /api/versioning/phase-change/process/result/:resultId
Rolls over a single result into the next phase. Supports both the v1 and v2 code paths depending on whether entityId is supplied in the body.
​
resultId
number
required
ID of the result to roll over.
Request body (optional):
​
entityId
number
When provided, uses the v2 replication path (versionProcessV2) which targets a specific IPSR entity. Omit for the standard v1 path.
Auth: JWT required. No special admin role needed — the calling user’s token is passed through to the service.

​
Replicate annual results (Reporting)

PATCH /api/versioning/execute/annual/replicate/result
Triggers portfolio-wide annual replication for all standard Reporting results. Copies eligible results from the current active phase to the next phase. Auth: JWT required. RoleEnum.ADMIN + RoleTypeEnum.APPLICATION.
This is an irreversible, portfolio-wide operation. Confirm that the target phase is open and correctly configured before triggering replication.

​
Replicate annual innovation packages (IPSR)

PATCH /api/versioning/execute/annual/replicate/innovation-package
Triggers portfolio-wide annual replication for Innovation Package (IPSR) results. Mirrors the behavior of the result replication endpoint but targets the IPSR module. Auth: JWT required. RoleEnum.ADMIN + RoleTypeEnum.APPLICATION.

​
Update QA status for results

PATCH /api/versioning/change/status/qa
Bulk-updates the Quality Assessment status on a set of results. Used internally during QA phase transitions. Auth: JWT required. No additional role guard — coordinate usage with the QA workflow team. 
PATCH /api/versioning/update/links-result/qa
Refreshes linked-result entries for QA. Called after QA status changes to keep cross-result linkages consistent. Auth: JWT required. No additional role guard.

​
URI versioning

The PRMS server enables URI-based API versioning (/v2/api/*). The apiVersionMiddleware reads the ?version= query parameter and writes req['apiVersion']. The phase-change process endpoint (PATCH /api/versioning/phase-change/process/result/:resultId) uses this to switch between the v1 and v2 replication paths based on whether entityId is present in the request body.
Result submitters must complete and submit their results before the phase end_date. Once an admin sets status: false on a phase, the submission window closes and results can no longer be submitted for that cycle.

Build docs developers (and LLMs) love

Get started for freeTalk to us