StaffMagic

Availability Guide

Set up and manage employee availability to avoid scheduling conflicts.

This guide explains how to set up and manage employee availability in StaffMagic.

Overview

Availability lets employees communicate when they're available to work. Managers can then view team availability when building schedules and receive warnings when scheduling someone outside their availability.

Key Benefits

  • For Employees: Set your working hours once, update as needed
  • For Managers: See who's available before assigning shifts
  • Fewer Conflicts: Automatic warnings prevent scheduling mistakes
  • Flexibility: Support for recurring patterns and date-specific exceptions

Key Concepts

  • Availability Rule: A recurring weekly pattern (e.g., "Available Mondays 9-5")
  • Availability Exception: A date-specific override (e.g., "Unavailable December 25")
  • Effective Date Range: When a rule applies (allows future changes)
  • Organization-Scoped: Availability can differ per organization

For Employees

Setting Up Weekly Availability

Your weekly availability defines your regular working hours.

Using the Setup Wizard

  1. Click My Availability in the sidebar
  2. Click Set Up Availability (or Edit Hours if updating)
  3. Choose a quick preset or configure manually:
    • Full-time (Mon-Fri, 9-5): Standard work week
    • Part-time Morning: Mon-Fri, 9 AM - 1 PM
    • Part-time Evening: Mon-Fri, 5 PM - 10 PM
    • Weekend Only: Sat-Sun, 9 AM - 5 PM
  4. Toggle individual days on/off
  5. Adjust start and end times per day
  6. Click Save Availability

Stats Dashboard

Once set up, you'll see:

  • Days per week: How many days you're available
  • Hours available: Total weekly hours

Example: Standard Full-Time Schedule

| Day | Start | End | Available | |-----|-------|-----|-----------| | Monday | 09:00 | 17:00 | Yes | | Tuesday | 09:00 | 17:00 | Yes | | Wednesday | 09:00 | 17:00 | Yes | | Thursday | 09:00 | 17:00 | Yes | | Friday | 09:00 | 17:00 | Yes | | Saturday | - | - | No rules (unavailable) | | Sunday | - | - | No rules (unavailable) |

Example: Part-Time Student Schedule

| Day | Start | End | Available | |-----|-------|-----|-----------| | Monday | 14:00 | 22:00 | Yes (after classes) | | Wednesday | 14:00 | 22:00 | Yes | | Friday | 14:00 | 22:00 | Yes | | Saturday | 08:00 | 16:00 | Yes (full day) |

Blocking Specific Times

You can mark certain hours as unavailable even within your working days:

  1. Create an availability rule with is_available: false
  2. This blocks that time slot

Example: Block lunch break 12:00-13:00 on all days:

Day: Monday (repeat for each day)
Start: 12:00
End: 13:00
Available: No
Notes: "Lunch break"

Requesting Time Off

Use Exceptions to block specific dates:

  1. Go to My Availability and click the Time Off tab
  2. Click Add Time Off
  3. Choose Single Day or Date Range
  4. Pick the date(s) using the calendar
  5. Toggle Full day off if you only need part of the day blocked
  6. Add a reason (optional but helpful for managers)
  7. Click Add Time Off

Your upcoming time off will be displayed in a list showing:

  • Date with day of week
  • Whether it's a full day or partial
  • Your reason (if provided)
  • Delete button to remove

Single Day Off

Date: December 25, 2024
Available: No
Reason: "Holiday"

Vacation (Multiple Days)

Use bulk create to add multiple days at once:

Dates: December 23-27, 2024
Available: No
Reason: "Family vacation"

Partial Day

Need time off for just part of a day?

Date: January 15, 2024
Start Time: 09:00
End Time: 12:00
Available: No
Reason: "Doctor appointment"

This blocks only 9 AM - 12 PM; you're still available the rest of the day.

Updating Availability

Changing Weekly Hours

If your schedule changes:

  1. Click Edit Hours to open the setup wizard
  2. Adjust your days and times
  3. Click Save Availability

The wizard will automatically reset your old rules and create new ones.

Resetting Availability

To start over completely:

  1. Click the Reset button (next to Edit Hours)
  2. Confirm in the dialog
  3. Your availability will be cleared
  4. Set up new availability using the wizard

Temporary Schedule Change

Use effective dates for temporary changes:

# Current availability (ending soon)
Day: Monday
Start: 09:00, End: 17:00
Effective From: 2024-01-01
Effective Until: 2024-01-31

# New availability (starting next month)
Day: Monday
Start: 12:00, End: 20:00
Effective From: 2024-02-01
Effective Until: null (indefinite)

Viewing Your Availability

  1. Navigate to My Availability
  2. View your current rules and upcoming exceptions
  3. Use the week view to see how it all comes together

For Managers

Viewing Team Availability

  1. Navigate to Team > Availability or view from the schedule page
  2. Select an employee to see their availability
  3. View:
    • Rules: Recurring weekly patterns
    • Exceptions: Upcoming date-specific blocks

Week View

The week availability view shows:

  • Which time slots each employee is available
  • Days with exceptions flagged
  • Computed availability combining rules and exceptions

Using Availability When Scheduling

When creating or assigning shifts:

  1. The system checks if the employee is available
  2. If available: Shift is created normally
  3. If unavailable: You'll see a warning (not blocked)

Note: Availability conflicts are warnings, not errors. Managers can override when necessary (e.g., special events, emergencies).

Conflict Detection Integration

When validating shifts, the system checks:

  • Double booking (ERROR - blocks)
  • Overtime (configurable)
  • Rest time (configurable)
  • Availability (WARNING)

Availability conflicts appear as:

"Employee not available: Outside availability hours"

or

"Employee not available: Exception: Doctor appointment"

Day of Week Convention

StaffMagic uses ISO weekday numbers:

| Number | Day | |--------|-----| | 0 | Monday | | 1 | Tuesday | | 2 | Wednesday | | 3 | Thursday | | 4 | Friday | | 5 | Saturday | | 6 | Sunday |

This matches Python's date.weekday() method.

Availability Logic

Rule Evaluation

  1. Check for exceptions first (date-specific overrides)
  2. If no exception, check rules for that day of week
  3. If multiple rules exist, check if shift overlaps any "available" window
  4. If no rules exist, employee is assumed available (opt-out model)

Exception Priority

Exceptions always override rules:

| Scenario | Rule | Exception | Result | |----------|------|-----------|--------| | Has rule, no exception | Available Mon 9-5 | - | Available | | Has rule, has exception | Available Mon 9-5 | Unavailable Dec 25 | Unavailable Dec 25 | | No rule, has exception | - | Available Dec 25 | Available Dec 25 |

Effective Date Ranges

Rules can have start and end dates:

Effective From: 2024-01-01
Effective Until: 2024-06-30
  • Rule only applies for dates within this range
  • If effective_until is null, rule applies indefinitely
  • Allows planning future schedule changes

Permissions Summary

| Action | Employee | Manager | Admin | Owner | |--------|----------|---------|-------|-------| | View own availability | ✓ | ✓ | ✓ | ✓ | | Set own availability | ✓ | ✓ | ✓ | ✓ | | View team availability | | ✓ | ✓ | ✓ | | Override availability | | ✓ | ✓ | ✓ |

API Reference

My Availability Endpoints (Employee Self-Service)

# Rules
GET    /api/v1/organizations/{org}/my-availability/rules
POST   /api/v1/organizations/{org}/my-availability/rules
POST   /api/v1/organizations/{org}/my-availability/rules/bulk
PATCH  /api/v1/organizations/{org}/my-availability/rules/{id}
DELETE /api/v1/organizations/{org}/my-availability/rules/{id}
DELETE /api/v1/organizations/{org}/my-availability/rules        # Delete all

# Exceptions
GET    /api/v1/organizations/{org}/my-availability/exceptions
POST   /api/v1/organizations/{org}/my-availability/exceptions
POST   /api/v1/organizations/{org}/my-availability/exceptions/bulk
PATCH  /api/v1/organizations/{org}/my-availability/exceptions/{id}
DELETE /api/v1/organizations/{org}/my-availability/exceptions/{id}

Member Availability Endpoints (Manager View)

GET    /api/v1/organizations/{org}/members/{user_id}/availability
GET    /api/v1/organizations/{org}/members/{user_id}/availability/week?week_start=2024-01-15

Create Rule Request

{
  "day_of_week": 0,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "is_available": true,
  "effective_from": "2024-01-01",
  "effective_until": null,
  "notes": "Regular work hours"
}

Bulk Create Rules Request

{
  "rules": [
    {"day_of_week": 0, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "effective_from": "2024-01-01"},
    {"day_of_week": 1, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "effective_from": "2024-01-01"},
    {"day_of_week": 2, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "effective_from": "2024-01-01"},
    {"day_of_week": 3, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "effective_from": "2024-01-01"},
    {"day_of_week": 4, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "effective_from": "2024-01-01"}
  ]
}

Create Exception Request

{
  "exception_date": "2024-12-25",
  "is_available": false,
  "reason": "Holiday"
}

Partial Day Exception

{
  "exception_date": "2024-01-15",
  "start_time": "09:00:00",
  "end_time": "12:00:00",
  "is_available": false,
  "reason": "Doctor appointment"
}

Rule Response Example

{
  "id": "abc123",
  "user_id": "user456",
  "organization_id": "org789",
  "day_of_week": 0,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "is_available": true,
  "effective_from": "2024-01-01",
  "effective_until": null,
  "notes": "Regular hours",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

User Availability Response

{
  "user_id": "user456",
  "rules": [
    {"id": "...", "day_of_week": 0, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "...": "..."},
    {"id": "...", "day_of_week": 1, "start_time": "09:00:00", "end_time": "17:00:00", "is_available": true, "...": "..."}
  ],
  "exceptions": [
    {"id": "...", "exception_date": "2024-12-25", "is_available": false, "reason": "Holiday", "...": "..."}
  ]
}

Best Practices

For Employees

  1. Set availability early: Don't wait until the schedule is posted
  2. Keep it current: Update when your schedule changes
  3. Use exceptions for one-offs: Don't change rules for single events
  4. Add reasons: Helps managers understand and plan
  5. Plan ahead: Submit vacation requests early

For Managers

  1. Check availability before scheduling: Avoid conflicts upfront
  2. Respect availability when possible: Builds trust and retention
  3. Communicate overrides: Let employees know if you need them outside availability
  4. Review team availability regularly: Spot coverage gaps early

For Organizations

  1. Set expectations: Communicate that availability should be kept current
  2. Define deadlines: When must availability be submitted by?
  3. Create policies: How far in advance for vacation requests?

Frequently Asked Questions

Can I have different availability for different organizations?

Yes! Availability is scoped per organization. If you work at two organizations in StaffMagic, you can have different availability at each.

What if I don't set any availability?

You're assumed available (opt-out model). If you want to restrict your hours, you must create rules.

Can managers edit my availability?

No, only you can set your own availability. Managers can view it and choose to schedule you outside your availability (with a warning), but they cannot change your preferences.

Do exceptions expire automatically?

No, past exceptions remain in the system for history. You can delete them if desired.

Can I set availability months in advance?

Yes, use the effective_from date to schedule future availability changes.

What happens if I'm scheduled outside my availability?

The shift is still created, but managers see a warning. The conflict doesn't block the shift creation.

Can I mark specific hours as unavailable within an available day?

Yes, create a rule with is_available: false for that time range. For example, block 12:00-13:00 for lunch.

How do I request recurring time off (e.g., every Wednesday)?

Create an availability rule with is_available: false for Wednesday. This is better than creating individual exceptions.

Last updated: December 2024 (Task 22: Availability UI)