Statuses & Lifecycle

Learn the difference between lifecycle states and business outcomes, and how statuses and decisions work together during evaluation processing.

RiskOS™ uses statuses to track where an entity is in its lifecycle and decisions to track what action to take. These are distinct runtime concepts that operate independently.

A status is a lifecycle state — it describes where an evaluation, workflow, or case is in its processing journey.
A decision is a business outcome — it describes what action to take on the evaluated entity.

A case can have a REVIEW decision and an Open status with an "In Review" sub-status simultaneously. The decision says why the case exists; the status says where it is in the review process.

Evaluation lifecycle

The eval_status field on an evaluation tracks its runtime state:

stateDiagram-v2
    [*] --> evaluation_in_progress: POST /api/evaluation
    evaluation_in_progress --> evaluation_completed: Decision reached
    evaluation_in_progress --> evaluation_paused: Async step reached
    evaluation_paused --> evaluation_in_progress: User action / PATCH resume
    evaluation_paused --> terminated: PATCH end
    evaluation_in_progress --> failed: Unrecoverable error
    evaluation_completed --> [*]
    terminated --> [*]
    failed --> [*]

`eval_status` value	Description	How it transitions
`evaluation_in_progress`	Workflow is actively executing steps	Automatic — moves to `evaluation_completed` or `evaluation_paused`
`evaluation_paused`	Workflow is waiting for user action (OTP, DocV, Wait, Hosted Flow)	External — user completes action, or API `PATCH` resumes/ends
`evaluation_completed`	Workflow ran to completion and returned a decision	Terminal state

You can terminate a paused evaluation via PATCH /api/evaluation/{eval_id} with actions.end. The workflow_execution_failed webhook event indicates an unrecoverable error during execution.

Evaluation status vs decision

Concept	Question	Values	Set by	Mutable
Evaluation status (`eval_status`)	"Where is this evaluation in execution?"	`evaluation_in_progress`, `evaluation_paused`, `evaluation_completed`	Runtime engine	Yes — transitions automatically or via API
Decision	"What action should be taken?"	`ACCEPT`, `REJECT`, `REVIEW`, custom	Workflow step or human reviewer	Yes — reviewer can change via Case Management

Workflow lifecycle

A workflow configuration moves through these states:

stateDiagram-v2
    [*] --> Draft: Create workflow
    Draft --> Published: Publish
    Published --> Live: Set live
    Live --> Published: Remove from live
    Published --> Draft: Create minor version
    Published --> Published: Duplicate (major version)
    Draft --> Deleted: Delete

Workflow state	Description	Can be edited	Processes evaluations
Draft	Initial state. Can be edited and tested.	Yes	No
Published	Frozen configuration. Can be tested but not edited directly.	No	No
Live	Actively processes evaluations via the Evaluation API.	No	Yes
Deleted	Removed. Cannot be restored.	No	No

Workflow modes

Live workflows can operate in different modes:

Mode	Description
Live	Processes production evaluations and returns real decisions
Shadow	Processes evaluations in parallel without affecting the live decision
A/B (Champion-Challenger)	Splits traffic between two workflow versions to compare performance

Case lifecycle

A case tracks the post-decision review process:

stateDiagram-v2
    [*] --> Open: Evaluation routes to Manual Review
    Open --> OnHold: Pending information
    OnHold --> Open: Information received
    Open --> Closed: Decision made
    OnHold --> Closed: Decision made

RiskOS™ defines three top-level case statuses:

Case status	Description
Open	Newly created, awaiting assignment or review
On Hold	Paused pending additional information or action
Closed	Final decision made, case resolved

Each status supports sub-statuses that are fully customizable per organization. For example, the default sub-status for an Open case is "In Review." Organizations can configure additional sub-statuses such as "Escalated", "Pending Documents", or any label that fits their review workflow.

Case status vs decision

Concept	Example combination	Meaning
Decision = `REVIEW`, Status = Open	Case created, awaiting reviewer assignment
Decision = `REVIEW`, Status = Open, Sub-status = "In Review"	Reviewer is actively investigating
Decision = `ACCEPT`, Status = Closed	Reviewer accepted, case resolved
Decision = `REJECT`, Status = Closed	Reviewer rejected, case resolved

Webhook events and lifecycle transitions

Lifecycle transitions generate webhook events:

Event	Lifecycle transition
`evaluation_paused`	Evaluation: `evaluation_in_progress` → `evaluation_paused`
`evaluation_completed`	Evaluation: `evaluation_in_progress` → `evaluation_completed` (or `evaluation_paused` → `evaluation_in_progress` → `evaluation_completed`)
`workflow_execution_failed`	Evaluation encountered an unrecoverable error during execution
`decision_update`	Case: reviewer changes the decision
`case_status_updated`	Case: status or sub-status changes
`review_case_assigned`	Case: reviewer assigned
`review_case_unassigned`	Case: reviewer removed
`fraud_confirming`	Case: marked as fraud or non-fraud

Related concepts

Evaluations — The runtime entity whose lifecycle is tracked
Decisions — The business outcome, distinct from lifecycle status
Workflows — Workflow configuration lifecycle (Draft → Published → Live)
Cases & Manual Review — Case status lifecycle
Synchronous vs Asynchronous Evaluations — How async steps create paused states
Webhook Event Reference — Events triggered by lifecycle transitions
Resuming Paused Evaluations — API operations for paused → processing transitions

Updated 5 days ago