# Interview Lifecycle {#interview-lifecycle}


**Version:** 2.0
**Last Updated:** 2026-10-14

This guide is intended for Enumerators, Supervisors, Project Managers, and Administrators who work with survey interviews in MQUAD.

---


## What is an Interview? {#what-is-an-interview}


An interview represents a single survey session conducted with a respondent. It is the entity that tracks:

- The survey being completed
- The respondent being interviewed
- The progress of the interview (which questions have been answered)
- The overall lifecycle status (from creation to submission)

Every interview is created when you start a form, and MQUAD keeps it in sync so its state survives closing the browser, losing connectivity, or switching devices. When completed, the interview is associated with a `SurveyResponse`.

Interviews are managed in two places in the web application:

- The **Resume Center** (`/resume`) - best for continuing work in progress.
- The **Interviews** page (`/interviews`) - a complete list of all interviews with search, filtering, and per-interview details.

---


## Interview Statuses {#interview-statuses}


| Status | Shown as | Meaning |
|--------|----------|---------|
| `created` | Not Started | The interview exists but no questions have been answered yet. |
| `in_progress` | In Progress | The interview is actively being conducted; heartbeats are being sent. |
| `paused` | Paused | Temporarily suspended by the user; all data is kept and can be resumed. |
| `interrupted` | Interrupted | Disrupted unexpectedly (heartbeat was lost - for example a crash or connectivity loss). |
| `completed` | Completed | All questions answered and the interview ended normally. |
| `needs_revision` | Needs Revision | A supervisor rejected the interview and flagged questions for correction. |
| `terminated` | Terminated | Ended early before completion (for example, the respondent refused). |


### Created {#created}
The interview has been initialized but not started. No questions have been answered.


### In Progress {#in-progress}
The interview is actively being conducted. While in progress, MQUAD sends a **heartbeat every 30 seconds**. If heartbeats stop (for example, the browser is closed or connectivity drops) the interview is marked **Interrupted**.


### Paused {#paused}
Temporarily suspended. All entered answers are preserved and the interview can be resumed exactly where it was left off.


### Interrupted {#interrupted}
The interview was disrupted unexpectedly, usually because heartbeats stopped. When you reopen a form that has an incomplete session, a recovery banner appears (see [Recovering an Incomplete Session](#recovering-an-incomplete-session)).


### Completed {#completed}
All questions have been answered and the interview ended normally. If a review workflow is enabled, the response proceeds into review; otherwise it is stored directly.


### Needs Revision {#needs-revision}
A supervisor rejected the interview and flagged specific questions. Only the flagged questions remain editable; the rest stay read-only to preserve approved answers.


### Terminated {#terminated}
Ended early before completion. Partial data is either retained or discarded depending on the termination reason (see [Terminating an Interview](#terminating-an-interview)).

---


## Status Transitions {#status-transitions}


A status can only change to specific next statuses. The **Actions** available on an interview reflect these rules:

| Current status | Allowed next statuses |
|----------------|-----------------------|
| Not Started (`created`) | In Progress, Interrupted |
| In Progress (`in_progress`) | Paused, Completed, Terminated, Interrupted |
| Paused (`paused`) | In Progress, Terminated, Interrupted |
| Interrupted (`interrupted`) | In Progress, Terminated |
| Needs Revision (`needs_revision`) | In Progress |
| Completed (`completed`) | (final - no further changes) |
| Terminated (`terminated`) | (final - no further changes) |

An interview is **completed only from In Progress**. To finish a paused or interrupted interview, resume it first.

---


## The Resume Center {#the-resume-center}


Open the Resume Center from **Fill Forms → Resume Center**, or go directly to `/resume`. It is the fastest way to continue work that is not finished.


### Grouping {#grouping}
Interviews are grouped so the ones that need you most appear first:

1. **Needs Attention** - highlighted in amber (for example, an in-progress interview with no recent activity).
2. **Active** - currently in progress.
3. **Paused**
4. **Interrupted**
5. **Needs Revision**
6. **Completed** - completed and terminated interviews.


### Filters and controls {#filters-and-controls}
- **Search** by session token.
- **Sort by**: Last Activity, Started, Completion %, or Created.
- **Status filter** (All Statuses, In Progress, Paused, Interrupted, Needs Revision, Completed, Terminated).
- A running count of interviews.


### Interview cards {#interview-cards}
Each card shows:

- A **status badge** (and a **Needs Attention** badge when applicable).
- The survey and session token.
- When it was last active (for example, "2 hours ago").
- A **progress bar** and the percentage complete, with `answered / total` questions.
- A checkbox for selecting multiple interviews.
- A card action:
  - **Start** for Not Started interviews.
  - **Resume** for In Progress, Paused, Interrupted, and Needs Revision interviews.
  - **Done** (disabled) for Completed interviews.

Clicking a card (outside the action buttons) opens the interview's details page.


### Batch actions {#batch-actions}
Select two or more interviews with the checkboxes to reveal the batch action bar. It shows how many are selected and offers:

- **Terminate** - terminates all selected interviews (with confirmation).
- **Clear** - clears the selection.

---


## The Interviews Page {#the-interviews-page}


The **Interviews** page (`/interviews`) lists all interviews you can view. Use it when you need the full history rather than just unfinished work.

- **Search** and **status filter** (All statuses, In Progress, Paused, Interrupted, Needs Revision, Completed, Terminated).
- A running count of interviews, with pagination for long lists.
- Click any interview to open its **Interview Details** page.

---


## Interview Details {#interview-details}


The Interview Details page (`/interviews/{id}`) shows everything about a single interview.


### Interview Info {#interview-info}
- **Survey** name
- **Session Token**
- **Progress** (`answered / total`)
- **Current Page**


### Timeline {#timeline}
- **Started**, **Paused**, **Completed**, and **Terminated** timestamps (whichever apply)
- **Termination Reason** (if terminated)
- **Data Action** - whether partial data was **Retained** or **Discarded**
- **Supervisor Notified** - Yes or No
- **Explanatory Notes** (if provided)
- **Created** and **Updated** timestamps

When an interview has been terminated, a red **Termination Details** card is also shown, summarising the reason, who terminated it and when, the data action, and whether the supervisor was notified.


### Actions {#actions}
Available actions depend on the current status:

| Action | Shown when | What it does |
|--------|-----------|--------------|
| **Start** | Not Started | Begins the interview and opens the form. |
| **Resume** | Paused | Resumes the interview and opens the form where you left off. |
| **Pause** | In Progress | Suspends the interview, keeping all data. |
| **Terminate** | In Progress, Paused, Interrupted | Opens the two-step termination dialog. |
| **Delete** | Not Started only | Permanently deletes the interview (cannot be undone). |
| **Resume Revision** | Needs Revision | Reopens the form to edit only the flagged questions. |


### Tabs {#tabs}
- **Event History** - every status change, shown as `from → to` badges with timestamps.
- **Audit Timeline** - the field-level change history for the interview (read-only).

---


## Typical Interview Flow {#typical-interview-flow}


1. **Create** - you start a form; MQUAD creates the interview with status **Not Started** (`created`).
2. **Start** - you begin answering. Status becomes **In Progress**, `started_at` is recorded, and heartbeats begin (every 30 seconds).
3. **Answer** - each answered question updates progress; `current_page` tracks your position; the session is saved automatically.
4. **Complete** - you finish the last question. Status becomes **Completed** and `completed_at` is recorded.
5. **Submission** - if a review workflow is enabled the response proceeds into review; otherwise it is stored directly.

---


## Pausing and Resuming {#pausing-and-resuming}



### When to pause {#when-to-pause}
- You need to break off temporarily (sharing a device, taking a break).
- Connectivity is unreliable.
- The respondent asks to pause.


### What happens while paused {#what-happens-while-paused}
- All entered answers are preserved.
- The interview stays in **Paused** and can be resumed at the exact point you left off.


### How to resume {#how-to-resume}
1. Open the Resume Center (or the interview details page).
2. Click **Resume**.
3. The form opens at the point where you left off and the status returns to **In Progress**.

---


## Recovering an Incomplete Session {#recovering-an-incomplete-session}


If an interview was left unfinished (for example the browser was closed), MQUAD detects the incomplete session when you open the form again and shows a recovery banner:

- **"We found an incomplete session"** with **Restore** and **Dismiss** buttons.
- While restoring, it shows **"Restoring your interview session..."**.

Choose **Restore** to bring back your previous work, or **Dismiss** to start fresh. An interview whose heartbeats stopped is shown as **Interrupted**, and you can also resume it from the Resume Center or its details page.

---


## Revising a Rejected Interview {#revising-a-rejected-interview}



### What happens when rejected {#what-happens-when-rejected}
When a supervisor rejects an interview:

1. The associated response is marked as rejected.
2. The review notes and rejection reason are recorded.
3. The interview status changes to **Needs Revision**.
4. The flagged questions are marked as requiring correction.


### Resuming a rejected interview {#resuming-a-rejected-interview}
1. Open the interview from the Resume Center or the Interviews page.
2. Click **Resume Revision**.
3. The form reopens with your previous answers pre-filled.
4. Only the flagged questions are editable; other questions display read-only with their original answers.


### Why only some questions are editable {#why-only-some-questions-are-editable}
- Prevents unnecessary re-entry of valid data.
- Ensures supervisor feedback is specifically addressed.
- Maintains data integrity by preserving approved answers.


### Resubmitting after revision {#resubmitting-after-revision}
1. Complete all required corrections to the flagged questions.
2. Submit the form again.
3. The response is updated and re-enters review if required.

---


## Terminating an Interview {#terminating-an-interview}


Terminate an interview when it cannot be completed - for example, the respondent refuses, they are not available, or there is a technical or safety issue.


### The two-step termination dialog {#the-two-step-termination-dialog}
1. On the interview details page, click **Terminate**.
2. **Step 1 - choose a reason.** Each reason shows whether data is retained or discarded and whether the supervisor is notified.
3. **Step 2 - confirm.** The dialog shows the selected reason. If the reason requires an explanation (the "Other" reason), you must enter explanatory notes before proceeding. Click **Confirm Termination**.


### Termination reasons {#termination-reasons}


| Reason | Data action | Supervisor notified |
|--------|-------------|---------------------|
| Respondent refused to continue | Retained | Yes |
| Respondent not available (after 3+ attempts) | Retained | Yes |
| Safety concern for interviewer or respondent | Retained | Yes |
| Device or application failure | Retained | Yes |
| Suspected data integrity issues | Discarded | Yes |
| Started interview with wrong person | Discarded | Yes |
| Ineligible / quota already reached | Retained | Yes |
| Supervisor instructed termination | Retained | Yes |
| Other (requires explanation) | Retained | Yes |


### After termination {#after-termination}
- The status changes to **Terminated**.
- The **Data Action** recorded on the interview shows whether partial data was **Retained** or **Discarded**.
- The supervisor is notified.
- A terminated interview cannot be resumed or "un-terminated". A new interview must be created to collect again.

---


## Frequently Asked Questions {#frequently-asked-questions}


**Q: Why can't I edit every field?**

A: When revising a rejected (Needs Revision) interview, only the questions flagged by the supervisor are editable. Other questions remain read-only to preserve valid data and maintain audit integrity.

**Q: Why is an interview Interrupted?**

A: An interview is marked **Interrupted** when its heartbeats stop - typically because the browser was closed or connectivity was lost. Reopen the form and use the recovery banner, or resume it from the Resume Center.

**Q: Why was my interview rejected?**

A: Common rejection reasons include missing required answers, failed validation rules, suspected data-quality issues, or incomplete sections. Check the reviewer comments for specific feedback.

**Q: How do I submit again after revision?**

A: After correcting the flagged questions, submit the form again. The response is updated and, if review is required, re-enters the review queue.

**Q: What happens if I close the browser mid-interview?**

A: The interview keeps its state:
- Answered questions are preserved.
- The interview becomes **Interrupted** once heartbeats stop.
- Reopening the form offers to restore your session, or you can resume it from the Resume Center.