Workflow States

All workflows in Ikamet OS use a shared set of 20 status values. This standardization means the same operational infrastructure (timeline events, renewal engine, task system, UI components) works across every service type.

The 20 states

Status	Meaning
`PENDING`	Created, not yet started
`AWAITING_DOCUMENTS`	Waiting for customer to upload required documents
`SUBMITTED`	Submitted to government or insurer — awaiting response
`UNDER_REVIEW`	Being reviewed internally or by the authority
`APPROVED`	Approved by the authority
`ISSUED`	Permit or policy document issued
`ACTIVE`	Currently valid and active
`RENEWAL_DUE`	Approaching expiry — renewal process should begin
`EXPIRED`	Past expiry date — no longer valid
`CANCELLED`	Cancelled before completion
`REJECTED`	Formally rejected by the authority or insurer
`APPEAL`	Customer has appealed a rejection
`REFERRED_TO_LEGAL`	Escalated to legal team
`LEGAL_REVIEW`	Under review by legal team
`COMPLIANCE_REVIEW`	Under compliance review
`AWAITING_INSURER`	Waiting on insurer decision
`AWAITING_EMPLOYER`	Waiting on employer action (work permit workflows)
`AWAITING_CANDIDATE`	Waiting on candidate action
`COMPLETED`	Successfully completed
`ON_HOLD`	Paused — reason documented in notes

Status transitions

Not all transitions are valid. The general progression is:

PENDING
  → AWAITING_DOCUMENTS
  → SUBMITTED
  → UNDER_REVIEW
  → APPROVED / REJECTED
  → ISSUED / APPEAL
  → ACTIVE
  → RENEWAL_DUE
  → COMPLETED / EXPIRED

Branching statuses (AWAITING_INSURER, AWAITING_EMPLOYER, ON_HOLD, REFERRED_TO_LEGAL) can be entered from most active states and return to the flow once resolved.

Status changes generate timeline events

Every status change calls writeStatusChange(), which writes a STATUS_CHANGE timeline event with the old and new status, the entity label, and the staff member who triggered the change.

await writeStatusChange(
  user_id,
  'Residency Application',
  oldStatus,
  newStatus,
  { staff_id, order_id }
);

Operational significance

State group	Operational action
`AWAITING_DOCUMENTS`	Trigger document request reminder
`RENEWAL_DUE`	Trigger renewal outreach sequence
`EXPIRED`	Flag for compliance review
`REJECTED`	Trigger appeal workflow or case closure
`ON_HOLD`	Create follow-up task with scheduled date