Task Management

Create, assign, and track tasks for workers

Overview

The Task Management API allows managers and admins to create and assign tasks to workers, while workers can view and update their assigned tasks. All endpoints require authentication.

Get All Tasks

Retrieve all tasks with pagination and filtering.

Access: Private (Manager/Admin only)

Query Parameters

page · number · default: "1"

Page number for pagination

limit · number · default: "10"

Number of tasks per page

status · string

Filter by status: Pending, In Progress, or Completed

assignedTo · string

Filter by assigned worker ID

search · string

Search by task description

sortBy · string

Field to sort by

order · string

Sort order: asc or desc

Response

{
  "success": true,
  "message": "Tasks fetched successfully",
  "data": {
    "tasks": [
      {
        "_id": "65a1234567890abcdef12345",
        "description": "Restock dairy products",
        "status": "In Progress",
        "assignedTo": {
          "_id": "65a9876543210fedcba98765",
          "name": "John Doe",
          "email": "[e-mail]",
          "role": "Worker"
        },
        "assignedBy": {
          "_id": "65a1111111111111111111111",
          "name": "Manager User",
          "email": "[e-mail]",
          "role": "Manager"
        },
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T14:20:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalTasks": 25,
      "limit": 10
    }
  }
}

---

Get My Tasks

Get tasks assigned to the currently authenticated worker.

Access: Private (all authenticated users, but workers only see their own)

Query Parameters

page · number · default: "1"

Page number for pagination

limit · number · default: "10"

Number of tasks per page

status · string

Filter by status

Response

{
  "success": true,
  "message": "Your tasks fetched successfully",
  "data": {
    "tasks": [
      {
        "_id": "65a1234567890abcdef12345",
        "description": "Restock dairy products",
        "status": "In Progress",
        "assignedBy": {
          "name": "Manager User",
          "email": "[e-mail]"
        },
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 2,
      "totalTasks": 15,
      "limit": 10
    }
  }
}

---

Get Task by ID

Get a single task by ID.

Access: Private (Manager/Admin see all, Workers see only their own)

Response

{
  "success": true,
  "message": "Task fetched successfully",
  "data": {
    "task": {
      "_id": "65a1234567890abcdef12345",
      "description": "Restock dairy products",
      "status": "In Progress",
      "assignedTo": {
        "_id": "65a9876543210fedcba98765",
        "name": "John Doe",
        "email": "[e-mail]",
        "role": "Worker"
      },
      "assignedBy": {
        "_id": "65a1111111111111111111111",
        "name": "Manager User",
        "email": "[e-mail]",
        "role": "Manager"
      }
    }
  }
}

---

Create Task

Create a new task and assign it to a worker.

Access: Private (Manager/Admin only)

Request Body

description · string · required

Task description

assignedTo · string · required

ID of the worker to assign the task to

Example Request

{
  "description": "Restock dairy products in refrigerated section",
  "assignedTo": "65a9876543210fedcba98765"
}

Example Response

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "task": {
      "_id": "65a1234567890abcdef12345",
      "description": "Restock dairy products in refrigerated section",
      "status": "Pending",
      "assignedTo": {
        "name": "John Doe",
        "email": "[e-mail]"
      },
      "assignedBy": {
        "name": "Manager User",
        "email": "[e-mail]"
      },
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

Tasks can only be assigned to users with the “Worker” role. The assigned user must be active.

---

Update Task

Update a task’s description, assignedTo, or status.

Access: Private (Manager/Admin only)

Request Body

All fields are optional. Only provided fields will be updated.

description · string

Updated task description

assignedTo · string

Updated worker ID

status · string

Updated status: Pending, In Progress, or Completed

Example Request

{
  "description": "Restock dairy products and organize by expiry date",
  "status": "In Progress"
}

---

Update Task Status

Quickly update only the task status.

Access: Private (Workers can update their own tasks, Manager/Admin can update all)

Request Body

status · string · required

New status: Pending, In Progress, or Completed

Example Request

{
  "status": "Completed"
}

Example Response

{
  "success": true,
  "message": "Task status updated successfully",
  "data": {
    "task": {
      "_id": "65a1234567890abcdef12345",
      "description": "Restock dairy products",
      "status": "Completed",
      "assignedTo": {
        "name": "John Doe",
        "email": "[e-mail]"
      }
    }
  }
}

---

Delete Task

Delete a task.

Access: Private (Manager/Admin only)

Response

{
  "success": true,
  "message": "Task deleted successfully",
  "data": null
}

---

Task Analytics

Get Task Completion Rate

Get task completion analytics including overall statistics and breakdown by worker.

Access: Private (Manager/Admin only)

Response

{
  "success": true,
  "message": "Task completion analytics fetched successfully",
  "data": {
    "analytics": {
      "overall": {
        "total": 50,
        "pending": 10,
        "inProgress": 15,
        "completed": 25,
        "completionRate": 50.0
      },
      "byWorker": [
        {
          "_id": "65a9876543210fedcba98765",
          "name": "John Doe",
          "email": "[e-mail]",
          "tasks": [
            { "status": "Pending", "count": 2 },
            { "status": "In Progress", "count": 3 },
            { "status": "Completed", "count": 10 }
          ]
        }
      ]
    }
  }
}

---

Role-Based Access

Endpoint	Worker	Manager	Admin
GET /tasks	❌	✅	✅
GET /tasks/my-tasks	✅	✅	✅
POST /tasks	❌	✅	✅
PUT /tasks/:id	❌	✅	✅
PATCH /tasks/:id/status	✅ (own)	✅	✅
DELETE /tasks/:id	❌	✅	✅
GET /tasks/analytics/*	❌	✅	✅