# Mission Progress

Mission Progress records the **overall state** of a single end user's engagement with a specific mission. It tracks whether the mission is active, completed, or failed, along with task progress details and lifecycle timestamps.

:::info
Mission Progress records are **system-managed** — they are created and updated automatically as `Mission Log` entries are processed. They cannot be created, updated, or deleted via the API.
:::

The **Mission** defines the objectives and rules. The **Mission Progress** is the running summary of a specific user's journey against those rules.

---

## How it works

1. **First log entry arrives** — when a `Mission Log` is created for a user on a mission for the first time, a Mission Progress record is automatically created with `missionProgressStatus: in_progress` and `missionStartedAt` set.
2. **Progress accumulates** — each `Mission Log` entry updates the user's task progress toward mission milestones.
3. **Mission completed** — when all milestone objectives are achieved, status transitions to `completed` and `missionCompletedAt` is stamped.
4. **Mission failed** — if the mission time window closes before completion, status transitions to `failed` and `missionFailedAt` is stamped.
5. **Task progresses surfaced** — when listing Mission Progress records, the response includes `taskProgresses` inline, providing full visibility into sub-task progress.

---

## Fields

### Identity & linking

| Field | Type | Description |
|---|---|---|
| `missionId` | UUID | ID of the parent mission this progress record belongs to. Indexed. |
| `uniqueIdentifier` | string | Auto-generated composite key: `missionId + ownedById`. Ensures unique progress per user per mission. |

### Progress & status

| Field | Type | Default | Description |
|---|---|---|---|
| `missionProgressStatus` | enum | `in_progress` | Current status of the mission for this user: `in_progress` · `completed` · `failed` |
| `isMissionToBeFailedProcessed` | boolean | `false` | Internal flag indicating whether scheduled failure processing has run |

### Timestamps

| Field | Type | Description |
|---|---|---|
| `missionStartedAt` | datetime | Datetime when the user started the mission. Defaults to current time on creation. |
| `missionCompletedAt` | datetime | Stamped when `missionProgressStatus` transitions to `completed`. |
| `missionFailedAt` | datetime | Stamped when `missionProgressStatus` transitions to `failed`. |
| `missionToBeFailedAt` | datetime | Scheduled datetime when the mission will fail if uncompleted. |

### Ownership

| Field | Type | Description |
|---|---|---|
| `ownedById` | UUID | ID of the end user (`Member`) this progress record belongs to. |
| `ownedBy` | object | Read-only joined user object. |

---

## Status values

| Status | Meaning |
|---|---|
| `in_progress` | The mission is active — the user has started but has not completed all required activities or milestones. |
| `completed` | All mission tasks/milestones have been completed successfully. |
| `failed` | The mission aggregation window ended before all tasks/milestones were completed. |

---

## The `taskProgresses` field

When you list Mission Progress records, the response automatically includes a `taskProgresses` array inline. This gives a detailed view of each sub-task's progress within the mission.

```json
{
  "id": "progress-uuid-here",
  "missionId": "c123e456-e89b-12d3-a456-426614174000",
  "missionProgressStatus": "in_progress",
  "missionStartedAt": "2026-06-24T10:00:00+05:30",
  "missionCompletedAt": null,
  "missionFailedAt": null,
  "missionToBeFailedAt": "2026-07-01T23:59:59+05:30",
  "taskProgresses": [
    {
      "taskProgressStatus": "completed",
      "currentProgressValue": 1
    },
    {
      "taskProgressStatus": "in_progress",
      "currentProgressValue": 0
    }
  ],
  "ownedById": "019ac851-a7c0-75ad-a271-b37946a3e5ed"
}
```

---

## Real-world examples

**🛍️ E-commerce — Purchase Cycle Mission (In Progress)**

A user has completed 1 of 3 steps in a weekly purchase cycle mission:

```json
{
  "missionId": "c123e456-e89b-12d3-a456-426614174000",
  "missionProgressStatus": "in_progress",
  "missionStartedAt": "2026-06-24T10:00:00+05:30",
  "missionCompletedAt": null,
  "missionFailedAt": null,
  "missionToBeFailedAt": "2026-07-01T23:59:59+05:30",
  "ownedById": "019ac851-a7c0-75ad-a271-b37946a3e5ed"
}
```

---

**☕ Community Campaign — Daily Content Mission (Completed)**

A user completes all required tasks before the daily deadline:

```json
{
  "missionId": "c123e456-e89b-12d3-a456-426614174001",
  "missionProgressStatus": "completed",
  "missionStartedAt": "2026-06-24T08:00:00+05:30",
  "missionCompletedAt": "2026-06-24T17:30:00+05:30",
  "missionFailedAt": null,
  "ownedById": "019ac851-a7c0-75ad-a271-b37946a3e5ed"
}
```

---

## Fetching a user's mission progress

**As an end user — get your progress on a specific mission:**

```http
GET /api/v1.0/schema/mission_progress/record?filters={"operator": "and", "conditions": [{"operator": "and", "conditions": [{"fieldSlug": "missionId", "operator": "equals", "fieldValue": "<Mission Id>"}]}]}
x-enduser-access-token: <token>
x-account-id: <account-id>
```

**As an admin — list all progress records for a mission:**

```http
GET /api/v1.0/schema/mission_progress/record?filters={"operator": "and", "conditions": [{"operator": "and", "conditions": [{"fieldSlug": "missionId", "operator": "equals", "fieldValue": "<Mission Id>"}]}]}
x-api-key: <your-api-key>
x-api-secret: <your-api-secret>
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | GET · LIST | Read-only — no CREATE, UPDATE, or DELETE |
| End user | GET · LIST | Can only read their own progress records |
| Guest user | *(none)* | Not accessible to unauthenticated callers |

:::warning
Mission Progress records **cannot be created, updated, or deleted** via the API. They are managed automatically as `Mission Log` entries are logged.
:::

---

## Related resources

| Resource | Description |
|---|---|
| [Mission](/mission) | The parent mission configuration that this progress record belongs to |
| [Mission Log](/mission-log) | Activity log entries that update progress |
| [Milestone](/milestone) | Step-by-step progress checkpoints linked to the mission |
| [Reward Log](/reward-log) | Reward entries issued upon milestone or mission completion |

---

## API reference

See the [API Reference](/api/mission-progress) for full request/response schemas and interactive examples for:

- `GET /schema/mission_progress/record` — list mission progress records
- `GET /schema/mission_progress/record/{id}` — get a mission progress record by ID