Task Scheduling

Overview

Recurring tasks (schedules) automatically generate task instances based on defined patterns. This enables consistent execution of routine operations like daily inspections, weekly maintenance, or monthly audits. Key Concepts:

Parent Task: The template that defines the recurring pattern
Task Instance: Individual tasks generated from the parent
Schedule: The recurrence configuration (daily, weekly, monthly, etc.)
Series: All instances belonging to a parent task

Create a Recurring Task

Create a task with a recurrence pattern.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Safety Walkthrough",
    "description": "Complete morning safety inspection",
    "startDate": "2024-12-20T08:00:00Z",
    "dueTime": "10:00",
    "assignees": ["user-uuid"],
    "locationIds": ["location-uuid"],
    "recurringTask": true,
    "recurringByEvery": "daily",
    "timezone": "America/New_York",
    "notification": {
      "email": true,
      "push": true
    }
  }'

Recurrence Fields:

Field	Type	Description
`recurringTask`	boolean	Set `true` for recurring tasks
`recurringByEvery`	string	Frequency: `daily`, `weekly`, `monthly`, `quarterly`, `yearly`
`recurringOnDay`	number	Day of week (1-7) or day of month (1-31)
`intervalWeek`	number[]	Days of week for weekly recurrence (1=Mon, 7=Sun)
`timezone`	string	Timezone for schedule (e.g., `America/New_York`)
`endDate`	datetime	When the schedule should stop generating instances

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "parent-task-uuid",
    "title": "Daily Safety Walkthrough",
    "taskStatus": "Open",
    "recurringTask": true,
    "recurringByEvery": "daily",
    "isParent": true,
    "scheduleStatus": "active",
    "nextInstanceDate": "2024-12-21T08:00:00Z",
    "createdAt": "2024-12-19T10:00:00Z"
  }
}

Daily Schedule

Runs every day at the specified time.

{
  "recurringTask": true,
  "recurringByEvery": "daily",
  "startTime": "08:00",
  "dueTime": "10:00",
  "timezone": "America/New_York"
}

Weekly Schedule

Runs on specific days of the week.

{
  "recurringTask": true,
  "recurringByEvery": "weekly",
  "intervalWeek": [1, 3, 5],
  "startTime": "09:00",
  "dueTime": "17:00",
  "timezone": "America/New_York"
}

This creates tasks every Monday (1), Wednesday (3), and Friday (5).

Monthly Schedule

Runs on a specific day of each month.

{
  "recurringTask": true,
  "recurringByEvery": "monthly",
  "recurringOnDay": 15,
  "startTime": "08:00",
  "timezone": "America/New_York"
}

This creates tasks on the 15th of every month.

Quarterly Schedule

Runs every three months.

{
  "recurringTask": true,
  "recurringByEvery": "quarterly",
  "recurringOnDay": 1,
  "timezone": "America/New_York"
}

Get Scheduled Tasks

List All Schedules (Parent Tasks)

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/parent-schedules/list" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 20,
    "sort": {
      "field": "createdAt",
      "direction": "DESC"
    },
    "filters": {
      "scheduleStatus": ["active", "paused"]
    }
  }'

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "schedules": [
      {
        "id": "parent-task-uuid",
        "title": "Daily Safety Walkthrough",
        "recurringByEvery": "daily",
        "scheduleStatus": "active",
        "isPaused": false,
        "nextInstanceDate": "2024-12-21T08:00:00Z",
        "instancesCount": 45,
        "completedCount": 42,
        "missedCount": 3,
        "Assignees": [...],
        "Location": {...}
      }
    ],
    "meta": {
      "total": 15,
      "page": 1,
      "pageSize": 20
    }
  }
}

List Active Schedule Instances

Get all active (upcoming and current) task instances.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/all-schedules" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 20,
    "filters": {
      "dateFrom": "2024-12-01",
      "dateTo": "2024-12-31"
    }
  }'

List Overdue Schedule Instances

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/overdue-schedules" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 20
  }'

List Completed Schedule Instances

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/completed-schedules" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 20,
    "filters": {
      "dateFrom": "2024-12-01",
      "dateTo": "2024-12-31"
    }
  }'

Get Schedule History

Get all instances generated from a parent task.

curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/scheduled-tasks/{parentTaskId}/history" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "parentTask": {
      "id": "parent-task-uuid",
      "title": "Daily Safety Walkthrough",
      "recurringByEvery": "daily"
    },
    "instances": [
      {
        "id": "instance-uuid-1",
        "taskNumber": "T-2024-001250",
        "taskStatus": "Completed",
        "startDate": "2024-12-20T08:00:00Z",
        "completedAt": "2024-12-20T09:45:00Z"
      },
      {
        "id": "instance-uuid-2",
        "taskNumber": "T-2024-001249",
        "taskStatus": "Completed",
        "startDate": "2024-12-19T08:00:00Z",
        "completedAt": "2024-12-19T09:30:00Z"
      }
    ],
    "statistics": {
      "total": 45,
      "completed": 42,
      "missed": 3,
      "completionRate": 93.3
    }
  }
}

Manage Schedules

Pause a Schedule

Temporarily stop generating new instances.

curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/schedules/{scheduleId}/toggle-pause" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response (Paused):

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "isPaused": true,
    "scheduleStatus": "paused",
    "message": "Schedule has been paused"
  }
}

Response (Resumed):

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "isPaused": false,
    "scheduleStatus": "active",
    "message": "Schedule has been resumed"
  }
}

This endpoint toggles the pause state. Call it once to pause, call again to resume.

End a Schedule

Permanently stop a schedule from generating new instances.

curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/schedules/{scheduleId}/end" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "schedule-uuid",
    "scheduleStatus": "ended",
    "endedAt": "2024-12-20T10:00:00Z"
  }
}

Ending a schedule is permanent. Existing instances remain but no new ones will be created. To temporarily stop, use pause instead.

Archive a Task Series

Archive all tasks in a recurring series.

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{parentTaskId}/archive-series" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Edit a Schedule

Update the schedule template. Changes apply to future instances.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{parentTaskId}/edit" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Daily Safety Walkthrough",
    "description": "Updated inspection procedure",
    "dueTime": "11:00",
    "assignees": ["new-user-uuid"],
    "priority": "High"
  }'

Editable Schedule Fields:

title, description, additionalDescription
startTime, dueTime
priority
assignees
locationIds, AssetId
ChecklistId, isChecklistRequired
notification
endDate (to set when schedule should stop)

You cannot change the recurrence pattern (recurringByEvery, intervalWeek) after creation. Create a new schedule instead.

Statistics

Get Overdue Count

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/scheduled-tasks/overdue-count" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "overdueCount": 12,
    "bySchedule": [
      {
        "scheduleId": "parent-uuid-1",
        "title": "Daily Safety Walkthrough",
        "overdueCount": 5
      },
      {
        "scheduleId": "parent-uuid-2",
        "title": "Weekly Equipment Check",
        "overdueCount": 7
      }
    ]
  }
}

Get Due Stats

curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/due-stats" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "overdue": 12,
    "dueToday": 8,
    "dueThisWeek": 25,
    "dueThisMonth": 95
  }
}

Common Workflows

Create Daily Inspection Schedule

Weekly Multi-Day Schedule

Create a task that runs Monday, Wednesday, and Friday.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MWF Equipment Inspection",
    "startDate": "2024-12-23T08:00:00Z",
    "dueTime": "12:00",
    "recurringTask": true,
    "recurringByEvery": "weekly",
    "intervalWeek": [1, 3, 5],
    "assignees": ["user-uuid"],
    "locationIds": ["location-uuid"],
    "ChecklistId": "inspection-checklist-uuid",
    "isChecklistRequired": true,
    "timezone": "America/New_York"
  }'

Monitor Schedule Compliance

#!/bin/bash
# Check schedule compliance

WORKSPACE_ID="your-workspace-uuid"

# Get overdue scheduled tasks
OVERDUE=$(curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/overdue-schedules" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "pageSize": 100}')

# Count and report
OVERDUE_COUNT=$(echo $OVERDUE | jq '.data.tasks | length')
echo "Overdue scheduled tasks: ${OVERDUE_COUNT}"

# Get completion rates by schedule
curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/parent-schedules/list" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "pageSize": 50}' | \
  jq '.data.schedules[] | {title: .title, completionRate: (.completedCount / .instancesCount * 100)}'

Best Practices

Set appropriate timezones

Always specify the timezone field for recurring tasks. This ensures instances are created at the correct local time, especially important for multi-location organizations.

Use end dates for temporary schedules

For schedules that should run for a limited time (e.g., during a project), set an endDate to automatically stop instance generation.

Monitor overdue instances

Regularly check overdue scheduled tasks. High overdue counts may indicate staffing issues, unrealistic schedules, or process problems.

Pause instead of delete

If you need to temporarily stop a schedule, use pause instead of ending it. This preserves the configuration and allows easy resumption.

Attach checklists for consistency

Recurring tasks benefit greatly from attached checklists. This ensures each instance follows the same procedure and generates comparable data.

Review and adjust schedules periodically

Business needs change. Periodically review active schedules to ensure they still align with operational requirements.

Schedule Status Reference

Status	Description
`active`	Schedule is running and generating instances
`paused`	Schedule is temporarily stopped
`ended`	Schedule has been permanently stopped
`expired`	Schedule reached its end date

Task Management - One-off task operations
Work Orders - Facility request management
Project Management - Organize recurring work
Template Management - Create checklists for scheduled tasks

Getting Started

Workflows

Integrations

Overview

Create a Recurring Task

Daily Schedule

Weekly Schedule

Monthly Schedule

Quarterly Schedule

Get Scheduled Tasks

List All Schedules (Parent Tasks)

List Active Schedule Instances

List Overdue Schedule Instances

List Completed Schedule Instances

Get Schedule History

Manage Schedules

Pause a Schedule

End a Schedule

Archive a Task Series

Edit a Schedule

Statistics

Get Overdue Count

Get Due Stats

Common Workflows

Create Daily Inspection Schedule

Weekly Multi-Day Schedule

Monitor Schedule Compliance

Best Practices

Schedule Status Reference

Getting Started

Workflows

Integrations

​Overview

​Create a Recurring Task

​Daily Schedule

​Weekly Schedule

​Monthly Schedule

​Quarterly Schedule

​Get Scheduled Tasks

​List All Schedules (Parent Tasks)

​List Active Schedule Instances

​List Overdue Schedule Instances

​List Completed Schedule Instances

​Get Schedule History

​Manage Schedules

​Pause a Schedule

​End a Schedule

​Archive a Task Series

​Edit a Schedule

​Statistics

​Get Overdue Count

​Get Due Stats

​Common Workflows

​Create Daily Inspection Schedule

​Weekly Multi-Day Schedule

​Monitor Schedule Compliance

​Best Practices

​Schedule Status Reference

​Related Guides

Overview

Create a Recurring Task

Daily Schedule

Weekly Schedule

Monthly Schedule

Quarterly Schedule

Get Scheduled Tasks

List All Schedules (Parent Tasks)

List Active Schedule Instances

List Overdue Schedule Instances

List Completed Schedule Instances

Get Schedule History

Manage Schedules

Pause a Schedule

End a Schedule

Archive a Task Series

Edit a Schedule

Statistics

Get Overdue Count

Get Due Stats

Common Workflows

Create Daily Inspection Schedule

Weekly Multi-Day Schedule

Monitor Schedule Compliance

Best Practices

Schedule Status Reference

Related Guides