# Mobile API: Workbook Task Completion Documentation

## Overview

The Workbook Task Completion API provides endpoints for viewing today's task lists with completion status, tracking who completed tasks and when, and adding comments. This is the mobile equivalent of the Workbook dashboard.

**Key Features:**
- View today's scheduled task lists with real-time completion status
- See who completed each task and when
- Mark tasks as Not Started, In Progress, or Completed
- Add notes/comments to tasks
- View carryover (incomplete) tasks from earlier lists

## Base URL

```
/api/mobile/workbook
```

## Authentication

All endpoints require an `APIKey` parameter in the POST body.

---

## Endpoints

### 1. Get Today's Task Lists

Retrieves all task lists scheduled for the current day with tasks and their completion status.

```
POST /api/mobile/workbook/:typeNum/lists
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/lists" \
  -d "APIKey=your_api_key"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "groupId": 1,
      "displayName": "OPENING",
      "scheduledDays": "SUN MON TUE WED THU FRI SAT",
      "startTime": "08:00:00",
      "effectiveStartTime": "08:00:00",
      "sortOrder": 1,
      "isActive": 1,
      "groupName": "OPENING",
      "totalCount": 11,
      "completedCount": 5,
      "completionPercentage": 45,
      "tasks": [
        {
          "id": 1,
          "taskName": "Open All Registers",
          "comment": "Test Comment",
          "taskGroup": 1,
          "recurOn": "MON TUE WED THU FRI SAT SUN",
          "priority": 1,
          "sortOrder": 0,
          "completionId": 501,
          "status": 2,
          "completedBy": 35194463,
          "completedAt": "2025-12-01 08:15:32",
          "completionNotes": "All registers opened successfully",
          "completedByFirstName": "John",
          "completedByLastName": "Smith",
          "assignedToEmployeeId": null,
          "dueDate": null,
          "dueTime": null
        },
        {
          "id": 4,
          "taskName": "Turn ON Open Sign",
          "comment": "After Unlocking Door",
          "taskGroup": 1,
          "status": null,
          "completedBy": null,
          "completedAt": null,
          "completionNotes": null,
          "completedByFirstName": null,
          "completedByLastName": null
        }
      ]
    },
    {
      "id": 2,
      "groupId": 2,
      "displayName": "CLOSING",
      "startTime": "17:00:00",
      "totalCount": 35,
      "completedCount": 0,
      "completionPercentage": 0,
      "tasks": [...]
    }
  ]
}
```

#### Task List Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Task list configuration ID |
| `groupId` | int | Task group ID |
| `displayName` | string | Display name for the list |
| `groupName` | string | Task group name |
| `scheduledDays` | string | Days this list is scheduled |
| `startTime` | string | Default start time (HH:MM:SS) |
| `effectiveStartTime` | string | Actual start time for today |
| `sortOrder` | int | Display order |
| `isActive` | bool | Whether list is active |
| `totalCount` | int | Total number of tasks |
| `completedCount` | int | Number of completed tasks |
| `completionPercentage` | int | Percentage complete (0-100) |
| `tasks` | array | Array of task objects with completion data |

#### Task Object Fields (with Completion)

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Task ID |
| `taskName` | string | Task name/title |
| `comment` | string\|null | Task description/instructions |
| `taskGroup` | int | Parent task group ID |
| `priority` | int | Priority level (1=High, 2=Normal, 3=Low) |
| `sortOrder` | int | Display order |
| `recurOn` | string | Days this task appears |
| `completionId` | int\|null | Today's completion record ID |
| `status` | int\|null | `0`=Not Started, `1`=In Progress, `2`=Completed |
| `completedBy` | int\|null | Employee ID who completed |
| `completedAt` | string\|null | Completion timestamp |
| `completionNotes` | string\|null | Notes about completion |
| `completedByFirstName` | string\|null | Completer's first name |
| `completedByLastName` | string\|null | Completer's last name |
| `assignedToEmployeeId` | int\|null | Assigned employee ID |
| `dueDate` | string\|null | Assignment due date |
| `dueTime` | string\|null | Assignment due time |

---

### 2. Get Active Task List with Carryover

Retrieves the currently active task list based on the current time, plus any incomplete tasks from earlier lists (carryover tasks).

```
POST /api/mobile/workbook/:typeNum/lists/active
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/lists/active" \
  -d "APIKey=your_api_key"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "activeList": {
    "id": 2,
    "groupId": 2,
    "groupName": "CLOSING",
    "displayName": "CLOSING",
    "startTime": "17:00:00",
    "effectiveStartTime": "17:00:00",
    "totalCount": 35,
    "completedCount": 10,
    "completionPercentage": 29,
    "tasks": [...]
  },
  "carryoverTasks": [
    {
      "id": 55,
      "taskName": "make sure items from previous night were completed",
      "status": 0,
      "carryoverFromList": "OPENING",
      "carryoverFromListId": 1,
      "originalStartTime": "08:00:00"
    }
  ],
  "nextListTime": null,
  "nextListName": null
}
```

#### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `activeList` | object\|null | Currently active task list (null if none) |
| `carryoverTasks` | array | Incomplete tasks from earlier lists |
| `nextListTime` | string\|null | Start time of next list |
| `nextListName` | string\|null | Name of next list |

---

### 3. Update Task Status

Updates the completion status of a task for today.

```
POST /api/mobile/workbook/:typeNum/tasks/:taskId/status
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |
| `status` | int | Yes | `0`=Not Started, `1`=In Progress, `2`=Completed |
| `employeeId` | int | No | Employee completing the task |
| `notes` | string | No | Completion notes |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/tasks/101/status" \
  -d "APIKey=your_api_key" \
  -d "status=2" \
  -d "employeeId=35194463" \
  -d "notes=All lights working properly"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "completionId": 501,
  "status": 2,
  "date": "2025-12-01"
}
```

#### Error Response

```json
{
  "success": false,
  "error": "Invalid status. Must be 0 (Not Started), 1 (In Progress), or 2 (Completed)"
}
```

---

### 4. Add Task Comment

Adds a comment to a task for today.

```
POST /api/mobile/workbook/:typeNum/tasks/:taskId/comment
```

#### POST Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `APIKey` | string | Yes | Your API key |
| `comment` | string | Yes | Comment text (max 1000 characters) |
| `employeeId` | int | No | Employee adding the comment |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/tasks/101/comment" \
  -d "APIKey=your_api_key" \
  -d "employeeId=35194463" \
  -d "comment=Found a burnt out bulb in section B"
```

#### Success Response (HTTP 201)

```json
{
  "success": true,
  "commentId": 15
}
```

---

### 5. Get Task Comments

Retrieves all comments for a task on a specific date.

```
POST /api/mobile/workbook/:typeNum/tasks/:taskId/comments
```

#### POST Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `APIKey` | string | Yes | - | Your API key |
| `date` | string | No | today | Date to get comments for (Y-m-d) |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/tasks/101/comments" \
  -d "APIKey=your_api_key" \
  -d "date=2025-12-01"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "date": "2025-12-01",
  "data": [
    {
      "id": 15,
      "taskId": 101,
      "date": "2025-12-01",
      "employeeId": 35194463,
      "employeeFirstName": "John",
      "employeeLastName": "Smith",
      "comment": "Found a burnt out bulb in section B",
      "createdAt": "2025-12-01 08:20:15"
    }
  ]
}
```

---

### 6. Get Completed Tasks

Retrieves all completed tasks for a specific date.

```
POST /api/mobile/workbook/:typeNum/completed
```

#### POST Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `APIKey` | string | Yes | - | Your API key |
| `date` | string | No | today | Date to get completions for (Y-m-d) |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/mobile/workbook/pc00/completed" \
  -d "APIKey=your_api_key"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "date": "2025-12-01",
  "data": [
    {
      "id": 1,
      "taskName": "Open All Registers",
      "comment": "Test Comment",
      "taskGroup": 1,
      "listName": "OPENING",
      "status": 2,
      "completedBy": 35194463,
      "completedAt": "2025-12-01 08:15:32",
      "completionNotes": "All registers opened successfully",
      "completedByFirstName": "John",
      "completedByLastName": "Smith"
    },
    {
      "id": 4,
      "taskName": "Turn ON Open Sign",
      "comment": "After Unlocking Door",
      "taskGroup": 1,
      "listName": "OPENING",
      "status": 2,
      "completedBy": 35194463,
      "completedAt": "2025-12-01 08:18:45",
      "completionNotes": null,
      "completedByFirstName": "John",
      "completedByLastName": "Smith"
    }
  ]
}
```

---

## Task Status Values

| Value | Name | Description |
|-------|------|-------------|
| `0` | Not Started | Task has not been started |
| `1` | In Progress | Task is being worked on |
| `2` | Completed | Task is finished |

---

## Usage Notes

1. **Time-Based Active List**: The active list is determined by the most recent `startTime` that has already passed for the current day.

2. **Carryover Tasks**: Incomplete tasks from earlier lists appear in `carryoverTasks`. These should be displayed prominently (e.g., in red) to indicate they are overdue.

3. **Date-Based Tracking**: Task completion is tracked per date. The same task can have different completion states on different days.

4. **Timezone Awareness**: All times are interpreted in the store's configured timezone.

5. **Employee Names**: Completion records include `completedByFirstName` and `completedByLastName` for display purposes.

---

## Endpoint Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/mobile/workbook/:typeNum/lists` | Get today's task lists with completion status |
| POST | `/api/mobile/workbook/:typeNum/lists/active` | Get active list with carryover tasks |
| POST | `/api/mobile/workbook/:typeNum/completed` | Get completed tasks for a date |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/status` | Update task completion status |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/comment` | Add comment to task |
| POST | `/api/mobile/workbook/:typeNum/tasks/:taskId/comments` | Get task comments |

---

## Related Documentation

- [Mobile API: Task Management](mobile-api-task-management.md) - Create, update, and delete task definitions
- [Mobile API: Workbook Notes](mobile-api-workbook-notes.md) - Store announcements and notes