Skip to content

🛎️ Manage Tasks

Operational task orchestration for hospitality teams

This guide provides an overview of the task management system and common integration workflows. For detailed API specifications, see the Task Management API Live Docs.

Required OAuth2 Scopes

The API requires specific OAuth2 scopes for different operations:

Operation Required Scope
Read tasks task.read
Create/update tasks task.write
Read actors actor.read
Read actor groups actor_group.read
Read task logs task_log.read
Read task templates task_template.read

Tasks - Overview

Understanding task types is crucial for proper integration. Each type has a specific purpose and lifecycle:

Staff Tasks

  • MANUAL_TASK: The default type for tasks created directly by an employee. For example, a front desk agent creating a one-off task for a porter to deliver a package to a room. If the task is assigned to the housekeeping assignee group, it will also appear in the housekeeping UI under additional tasks.

Housekeeping & Operations

These tasks are automatically generated based on the guest's reservation lifecycle and are fundamental to hotel operations.

  • DEPARTURE_CLEANING: A core housekeeping task created automatically when a guest checks out to prepare the room for the next arrival.
  • STAYOVER_CLEANING: The scheduled cleaning for a room during a guest's multi-night stay, ensuring the room is serviced daily.
  • SERVICE_TASK: Represents other scheduled services tied to a reservation, such as turndown service or delivering a recurring amenity that isn't a standard cleaning task. If the task is assigned to the housekeeping assignee group, it will also appear in the housekeeping UI.

Guest-Initiated Tasks

These tasks originate directly from a guest's actions, typically through a guest-facing app or interface (the "Guest Journey").

  • GUEST_TASK: Used for two specific scenarios:

    • To capture a note or comment a guest leaves during the digital checkout process.
    • To handle a guest's request for luggage pickup.

  • FOOD_AND_BEVERAGE_ORDER: Represents a guest's order for room service through 3rd parties.

    • The main task's description contains the overall order information (like delivery location and time).
    • Individual items from the order (e.g., "Cheeseburger," "Fries," "Coke") are created as subtasks.

  • SHOP_ORDER: Used for guest purchases made through the hotel's digital shops (part of the Guest Journey).

    • Similar to F&B orders, the main task holds general order information.
    • Individual purchased items (e.g., extra amenities, minibar items, souvenirs) are created as subtasks.

System

These tasks are generated by internal system processes.

  • AUTOMATED_TASK: Created by backend services for internal processes and system monitoring. Use cases include:
    • Monitoring online door systems and creating tasks if a door goes offline or reports a low battery.
    • Running other scheduled, system-level jobs that require tracking.

Task Status and Priority Values

Status Options:

  • TODO - Task is created and ready to be worked on
  • IN_PROGRESS - Task is currently being worked on
  • DONE - Task has been completed

Priority Levels:

  • LOW - Low priority task
  • MEDIUM - Medium priority task
  • HIGH - High priority task
  • URGENT - Urgent task requiring immediate attention

Integration Workflow

IMPORTANT: Follow this sequence when integrating:

  1. First:

    1. Call GET /properties/{propertyId}/actors to get available employees OR
    2. Call GET /properties/{propertyId}/actor-groups to get available teams/departments

  2. Then: Use the IDs from step 1 to create/update tasks with proper assignment

Example: Creating an Assigned Task

# 1. Get actor groups
curl -X 'GET' \
  '{{monitoringUrl}}/api/task-management-service/properties/DEMO/actor-groups' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# Response includes: {"id": "housekeeping", "displayName": "Housekeeping Team", ...}

# 2. Create task with assignment
curl -X 'POST' \
  '{{monitoringUrl}}/api/task-management-service/properties/DEMO/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "title": "Clean Room 101",
    "status": "TODO",
    "priority": "MEDIUM",
    "due": "2025-09-10T14:00:00Z",
    "assigneeGroupId": "housekeeping",
    "links": {
      "pmsUnitIds": ["room-101-uuid"]
    }
  }'

Webhook Integration

LIKE MAGIC sends webhook notifications for the following task events:

  • TASK_CREATED - When a new task is created
  • TASK_UPDATED - When task details are modified (status, assignment, priority, etc.)
  • TASK_COMPLETED - When a task is marked as done

Benefits of Using Webhooks

  • Real-time Updates: Get instant notifications when tasks change
  • Automation: Trigger your own workflows based on task events
  • Synchronization: Keep your system in sync with LIKE MAGIC's task management
  • Efficiency: Avoid polling the API for changes

Example Webhook Payload

{
  "event": "TASK_UPDATED",
  "taskId": "task-123",
  "propertyId": "property-456",
  "changes": {
    "status": {
      "old": "TODO",
      "new": "IN_PROGRESS"
    },
    "assigneeId": {
      "old": null,
      "new": "actor-789"
    }
  },
  "timestamp": "2025-01-14T15:55:59.547Z"
}

Common Integration Patterns

  1. Task Progress Tracking
  2. Subscribe to TASK_UPDATED events
  3. Monitor status changes

  4. Update your local system's task status

  5. Workload Management

  6. Listen for TASK_CREATED events
  7. Track task assignments

  8. Balance workload across teams

  9. Performance Analytics

  10. Capture TASK_COMPLETED events
  11. Calculate completion times
  12. Generate performance reports

See Listening on Events for integration details.

Common Use Cases

Auditing Task History

To understand what happened to a task in detail, subscribe to webhook events and follow up by reading task logs:

1. Monitor Task Changes in Real-Time:

Subscribe to task-related webhook events to receive real-time notifications:

  • TASK_CREATED - New task created
  • TASK_UPDATED - Task details changed (status, assignment, etc.)
  • TASK_COMPLETED - Task marked as done

See Listening on Events for integration details.

2. Read Task Logs (Follow-up):

When you receive a webhook event, use the task ID from the event to retrieve detailed logs:

GET /properties/{propertyId}/tasks/{taskId}/task-logs

Task logs show all modifications, including who made changes and what was updated. This is useful for: - Auditing task history - Understanding task lifecycle - Tracking who made specific changes and when

API Reference

For complete API documentation including all endpoints, request/response schemas and interactive testing:

👉 Task Management API - Live Docs

The Live API Docs provide: - Interactive API testing - Complete request/response examples - All available filters and query parameters - Detailed field descriptions