Interface WorkflowService

All Known Implementing Classes:

WorkflowServiceImpl

public interface WorkflowService

Service surface for the 8-state workflow lifecycle (HANDOFF_WORKFLOW_STATE_STORAGE.md).

The state itself lives as a first-class column on INVESTIGATION (see Investigation.getWorkflowState()); the history is derived from the AUDIT_EVENT stream filtered on WorkflowStateChangedEvent.

Implementations are responsible for:

• validating transitions against the WorkflowState.canTransitionTo(WorkflowState) machine,
• persisting workflowState + workflowStateEnteredAt on advance(Investigation, WorkflowState, String, Long),
• emitting exactly one WorkflowStateChangedEvent per real transition (idempotent no-ops emit nothing),
• answering queue-style queries for the curator worklist (queue(WorkflowState, String, String, Date, int, int)).

Method Summary

Modifier and Type	Method	Description
WorkflowTransition	advance(Investigation dataset, WorkflowState targetState, String reason, Long ticketId)	Advance the given dataset to targetState.
WorkflowState	getCurrentState(Investigation investigation)
List<AuditEvent>	getHistory(Investigation investigation)	Retrieve the full chronological history of workflow transitions for a dataset, derived from the AUDIT_EVENT stream filtered to WorkflowStateChangedEvent rows.
Slice<WorkflowQueueEntry>	queue(WorkflowState state, String datasetType, String assignee, Date since, int offset, int limit)	Return datasets currently in state, oldest entry first (so the curator's "what's been waiting longest" view is the natural read).

Method Details

getCurrentState

WorkflowState getCurrentState(Investigation investigation)

Returns:

the current workflow state of investigation. Never null (legacy rows default to WorkflowState.Loaded).

getHistory

List<AuditEvent> getHistory(Investigation investigation)

Retrieve the full chronological history of workflow transitions for a dataset, derived from the AUDIT_EVENT stream filtered to WorkflowStateChangedEvent rows.

Parameters:

investigation - the dataset whose workflow history to fetch.

Returns:

zero-or-more events, oldest first. Empty list for a dataset that has never been transitioned via the workflow service (the backfilled 'Loaded' default is NOT a transition and does not appear in history).

advance

WorkflowTransition advance(Investigation dataset,
 WorkflowState targetState,
 @Nullable
 String reason,
 @Nullable
 Long ticketId)

Advance the given dataset to targetState.

Idempotent on targetState == current: returns a WorkflowTransition with previousState == currentState and a null audit-event id; no row mutation, no audit event.

The first argument is the Investigation (Auditable) target because @AuditedConditional requires the auditable to be on the argument list (the aspect locates it positionally). REST callers resolve the dataset id to an Investigation before invoking.

Parameters:

dataset - the dataset to advance.

targetState - the desired next state. Must satisfy current.canTransitionTo(targetState) OR equal current (idempotent no-op).

reason - optional human-readable rationale; recorded on the audit event note.

ticketId - optional ticket id (forward-compatible with the Ticket integration); the service currently records the value on the audit note but does not interpret it.

Returns:

the transition record; never null.

Throws:

DisallowedWorkflowTransitionException - if the transition is not permitted by the state machine.

queue

Slice<WorkflowQueueEntry> queue(WorkflowState state,
 @Nullable
 String datasetType,
 @Nullable
 String assignee,
 @Nullable
 Date since,
 int offset,
 int limit)

Return datasets currently in state, oldest entry first (so the curator's "what's been waiting longest" view is the natural read).

Parameters:

state - required; restrict to this workflow state.

datasetType - optional; "expression_experiment" or "preboarded_experiment". Currently only the former is implemented.

assignee - optional; restrict to datasets that have an OPEN ticket assigned to this user login.

since - optional; restrict to datasets whose workflowStateEnteredAt is on or after this instant.

offset - pagination offset.

limit - pagination page size.