StaffMagic

Shifts Guide

Learn how to create, manage, and assign shifts within schedules.

This guide explains how to create, manage, and assign shifts within schedules in StaffMagic.

Overview

A Shift represents a single work period assigned to an employee (or left open for pickup). Shifts are the building blocks of schedules - they define when employees work, what position they'll fill, and for how long.

Key Concepts

  • Shift: A specific time slot for work (e.g., 9 AM - 5 PM)
  • Open Shift: A shift not assigned to anyone, available for pickup
  • Position: The role/job for the shift (Server, Cook, Host, etc.)
  • Break Time: Unpaid break duration subtracted from total hours

Shift Statuses

| Status | Description | |--------|-------------| | Scheduled | Shift created but not yet confirmed by employee | | Confirmed | Employee has acknowledged the shift | | Completed | Shift has been worked | | Cancelled | Shift was cancelled |

Creating Shifts

Who Can Create Shifts

Managers, Admins, and Owners can create shifts.

Prerequisites

  • A draft schedule must exist (shifts can only be added to drafts)
  • At least one position must be configured for your organization

Steps

  1. Navigate to the schedule you want to add shifts to
  2. Click Add Shift or drag on the calendar
  3. Fill in the shift details:
    • Position: Select the job role (required)
    • Employee: Select an employee or leave empty for an open shift
    • Start Time: When the shift begins (required)
    • End Time: When the shift ends (required)
    • Break: Duration of unpaid break in minutes (optional)
    • Notes: Instructions or details for the shift (optional)
    • Color: Custom color override for display (optional)
  4. Click Create

Creating Open Shifts

To create a shift that anyone can pick up:

  1. Follow the steps above
  2. Leave the Employee field empty
  3. The shift will appear as "Open" and can be assigned later

Bulk Creating Shifts

To add multiple shifts at once:

  1. Use the Bulk Create option
  2. Define the shifts in batch
  3. Submit to create all shifts simultaneously

This is useful for setting up a full week of shifts quickly.

Creating Shifts from Templates

For even faster shift creation, use Shift Templates:

  1. Navigate to the schedule
  2. Click Apply Template or drag a template from the sidebar
  3. Select dates and optionally assign an employee
  4. The template's position, times, and break settings are applied automatically

See Shift Templates User Guide for details on creating and managing templates.

Viewing Shifts

For Employees

Employees can view their assigned shifts in published schedules:

  1. Navigate to My Schedule
  2. View your upcoming shifts
  3. Click on a shift for details

Note: Employees cannot see shifts in draft schedules or shifts assigned to others.

For Managers

Managers can see all shifts in all schedules:

  1. Open any schedule
  2. View all shifts including open shifts
  3. Use filters to narrow down:
    • By Employee: See shifts for a specific person
    • By Position: See shifts for a specific role
    • By Status: Filter by scheduled/confirmed/completed

Editing Shifts

Who Can Edit

Managers, Admins, and Owners can edit shifts.

What Can Be Edited

  • Draft schedules: All shift properties can be changed
  • Published schedules: Shifts cannot be edited (create a new draft instead)

Steps

  1. Open the schedule containing the shift
  2. Click on the shift to edit
  3. Modify the desired fields
  4. Save changes

Reassigning Shifts

To assign a shift to a different employee:

  1. Edit the shift
  2. Change the Employee field to the new person
  3. Save changes

Converting to Open Shift

To make an assigned shift available for pickup:

  1. Edit the shift
  2. Clear the Employee field
  3. Save - the shift is now "Open"

Deleting Shifts

Who Can Delete

Managers, Admins, and Owners can delete shifts.

Constraints

  • Shifts in draft schedules can be deleted
  • Shifts in published schedules cannot be deleted

Steps

  1. Open the schedule
  2. Select the shift
  3. Click Delete
  4. Confirm the deletion

Conflict Detection

StaffMagic automatically detects potential scheduling conflicts when creating, editing, or publishing shifts.

Types of Conflicts

| Conflict | Default Severity | Description | |----------|------------------|-------------| | Double Booking | Error | Employee already has a shift at this time | | Overtime | Warning | Shift would result in more than 40 hours/week | | Rest Time | Warning | Less than 8 hours rest since last shift | | Max Daily Hours | Warning | More than 12 hours of work in a single day |

Conflict Severity Levels

  • Errors block the action (e.g., publishing a schedule with double-booked shifts)
  • Warnings allow the action but alert you to potential issues (can be overridden)

Configurable Thresholds

Organizations can customize conflict detection thresholds:

| Setting | Default | Range | Description | |---------|---------|-------|-------------| | Overtime Weekly Hours | 40 | 20-80 | Hours before overtime warning | | Minimum Rest Hours | 8 | 4-12 | Required rest between shifts | | Max Daily Hours | 12 | 8-16 | Maximum hours per day | | Overtime as Error | No | - | Treat overtime as blocking error | | Rest Time as Error | No | - | Treat rest violation as blocking error |

How It Works

  1. On Shift Creation: The system checks for conflicts against existing shifts
  2. On Validation: Use the validate endpoint to preview conflicts before saving
  3. On Schedule Publish: All shifts are validated; errors block publishing

Validating Individual Shifts

Use the Validate feature before creating to preview conflicts:

  1. Fill in shift details
  2. Click Validate (instead of Create)
  3. Review any conflicts shown
  4. Adjust times or assignment as needed
  5. Create the shift

Validating Entire Schedules

Before publishing, validate the entire schedule:

  1. Open the draft schedule
  2. Click Validate Schedule
  3. Review the conflict summary:
    • Error Count: Issues that must be fixed before publishing
    • Warning Count: Issues that can be overridden
    • Conflicts by User: See which employees have issues
  4. Fix any errors by editing shifts
  5. Publish (with force=true to override warnings)

Open Shifts and Conflicts

Open shifts (shifts without an assigned employee) do not trigger conflicts:

  • No double booking check (no employee assigned)
  • No overtime check (no employee to track hours)
  • No rest time check (no previous shifts to compare)

Once you assign an employee to an open shift, conflict detection applies.

Duration and Breaks

How Duration is Calculated

Duration = (End Time - Start Time) - Break Time

Example:

  • Start: 9:00 AM
  • End: 5:00 PM
  • Break: 30 minutes
  • Duration: 7.5 hours (not 8 hours)

Break Guidelines

  • Breaks are entered in minutes
  • Breaks are unpaid time
  • Common breaks: 30 minutes (short shift), 60 minutes (long shift)

Open Shifts Workflow

Open shifts are powerful for flexible scheduling:

Creating Open Shifts

  1. Create shift without assigning an employee
  2. Shift appears as "Open" in the schedule

Filling Open Shifts

  1. View open shifts in the schedule
  2. Edit the shift
  3. Assign an available employee
  4. Save to convert to assigned shift

Best Practices

  • Create open shifts when you know you need coverage but not who
  • Fill open shifts as employees become available
  • Consider open shifts for on-call or variable needs

Permissions Summary

| Action | Employee | Manager | Admin | Owner | |--------|----------|---------|-------|-------| | View own shifts | ✓ | ✓ | ✓ | ✓ | | View all shifts | | ✓ | ✓ | ✓ | | Create shifts | | ✓ | ✓ | ✓ | | Edit shifts | | ✓ | ✓ | ✓ | | Delete shifts | | ✓ | ✓ | ✓ | | Validate shifts | | ✓ | ✓ | ✓ |

API Reference

For developers integrating with StaffMagic, shifts are managed via these endpoints:

Shift Endpoints

GET    /api/v1/organizations/{org}/schedules/{schedule}/shifts           # List shifts
GET    /api/v1/organizations/{org}/schedules/{schedule}/shifts/{id}      # Get shift
POST   /api/v1/organizations/{org}/schedules/{schedule}/shifts           # Create shift
POST   /api/v1/organizations/{org}/schedules/{schedule}/shifts/bulk      # Bulk create
PATCH  /api/v1/organizations/{org}/schedules/{schedule}/shifts/{id}      # Update shift
DELETE /api/v1/organizations/{org}/schedules/{schedule}/shifts/{id}      # Delete shift

Validation Endpoints

POST   /api/v1/organizations/{org}/validation/shifts                           # Validate shift
GET    /api/v1/organizations/{org}/locations/{loc}/schedules/{id}/validate     # Validate schedule
POST   /api/v1/organizations/{org}/locations/{loc}/schedules/{id}/publish?force=true  # Force publish

Validation Response Example

{
  "valid": false,
  "error_count": 1,
  "warning_count": 2,
  "conflicts": [
    {
      "type": "double_booking",
      "message": "Employee already has a shift from 2024-01-15 09:00 to 2024-01-15 17:00",
      "severity": "error",
      "shift_id": "abc123",
      "conflicting_shift_id": "def456",
      "user_id": "user789",
      "details": {
        "overlapping_start": "2024-01-15T09:00:00Z",
        "overlapping_end": "2024-01-15T17:00:00Z"
      }
    },
    {
      "type": "overtime",
      "message": "Would result in 45.0 hours this week (limit: 40)",
      "severity": "warning",
      "user_id": "user789",
      "details": {
        "total_hours": 45.0,
        "limit_hours": 40.0,
        "excess_hours": 5.0
      }
    }
  ]
}

Frequently Asked Questions

Can I copy shifts from last week?

This feature is planned for a future release. In the meantime, use Shift Templates to quickly recreate common shift patterns. See Shift Templates User Guide.

What happens to shifts when a schedule is published?

Shifts remain with the schedule. Once published, shifts cannot be modified - create a new draft schedule to make changes.

Can employees see open shifts?

Currently, employees only see their own assigned shifts. Open shift marketplace is planned for a future release.

How do I handle split shifts?

Create two separate shifts with a gap between them. Split shift support with automatic linking is planned for a future release.

Can I set recurring shifts?

Recurring shifts are planned for a future release. Currently, use Shift Templates to quickly apply the same pattern across multiple dates. Templates can be applied to up to 31 dates at once.

What's the maximum shift length?

There's no hard limit, but the system will warn about shifts resulting in overtime (>40 hours/week).

Can employees decline shifts?

Currently, shift confirmation and decline workflows are not implemented. This is planned for a future release.

Are employees notified when their shifts change?

Yes! When a schedule is published, all employees with shifts receive an email notification. See Notifications User Guide for details.

Related Guides

Last updated: December 2024 (Task 19: Email Notifications)