Shift Templates Guide

Create reusable shift patterns to streamline schedule building.

This guide explains how to create, manage, and use shift templates to streamline schedule building in StaffMagic.

Overview

A Shift Template is a reusable shift pattern that defines common work periods. Instead of manually entering the same shift details repeatedly, you can create templates like "Morning Server" or "Evening Bartender" and apply them with a single click.

Key Benefits

Save Time: Create shifts in seconds instead of minutes
Consistency: Ensure standard shift times across your organization
Reduce Errors: No more typos in start/end times
Easy Onboarding: New managers have pre-defined patterns to use

Key Concepts

Template: A saved shift pattern with position, times, and break duration
Global Template: Available for all locations (location_id = null)
Location-Specific Template: Only appears for a specific location
Overnight Template: Shifts that span midnight (end time < start time)

Creating Templates

Who Can Create Templates

Managers, Admins, and Owners can create shift templates.

Steps

Navigate to Settings > Shift Templates
Click New Template
Fill in the template details:
- Name: Descriptive name (e.g., "Morning Server", "Night Bartender")
- Description: Optional notes about this template
- Position: The job role for this shift (required)
- Location: Leave empty for global, or select a specific location
- Start Time: When the shift begins
- End Time: When the shift ends
- Break: Duration of unpaid break in minutes
- Color: Optional color override for display
- Sort Order: Display order in template list
Click Create

Example Templates

| Name | Position | Start | End | Break | Notes | |------|----------|-------|-----|-------|-------| | Morning Server | Server | 07:00 | 15:00 | 30 min | Breakfast/lunch shift | | Afternoon Server | Server | 11:00 | 19:00 | 30 min | Lunch/dinner shift | | Evening Server | Server | 16:00 | 00:00 | 30 min | Dinner/close shift | | Night Bartender | Bartender | 20:00 | 04:00 | 30 min | Overnight bar shift | | Morning Cook | Cook | 06:00 | 14:00 | 30 min | Prep/breakfast | | Evening Cook | Cook | 14:00 | 22:00 | 30 min | Dinner service |

Overnight Shifts

Templates support shifts that span midnight:

If End Time < Start Time, the shift is treated as overnight
Example: 22:00 to 06:00 = 8-hour overnight shift
Duration is calculated correctly across the day boundary

Managing Templates

Viewing Templates

Navigate to Settings > Shift Templates
View all templates for your organization
Filter by:
- Position: Show only templates for a specific role
- Location: Show location-specific + global templates
- Active Only: Toggle to show/hide inactive templates

Editing Templates

Click on a template to open the edit view
Modify any field
Save changes

Note: Editing a template does not affect shifts already created from it.

Deactivating Templates

Instead of deleting, you can deactivate templates:

Edit the template
Set Active to No
Save

Inactive templates:

Don't appear in the template picker
Can be reactivated later
Preserve history for auditing

Deleting Templates

Select the template
Click Delete
Confirm deletion

Warning: Deletion is permanent. Consider deactivating instead.

Using Templates

Apply to Single Date

Open a draft schedule
Click Apply Template or drag a template onto the schedule
Select the template
Choose the date
Optionally assign an employee (or leave empty for open shift)
Click Apply

Apply to Multiple Dates

Open a draft schedule
Click Bulk Apply Template
Select the template
Choose multiple dates (up to 31)
Optionally assign an employee
Click Apply

This creates one shift per selected date.

Applying with Assignment

When applying a template:

With Employee: Creates an assigned shift, conflict detection applies
Without Employee: Creates an open shift, no conflict checks

Template Organization

Global vs Location-Specific

| Type | Use Case | |------|----------| | Global (no location) | Standard patterns used everywhere | | Location-Specific | Unique hours for specific locations |

When viewing templates for a location, you'll see:

All global templates
Templates specific to that location

Sort Order

Control template display order:

Lower numbers appear first
Use increments of 10 (10, 20, 30...) to allow insertions
Templates with same sort order are alphabetized

Naming Conventions

Recommended naming patterns:

[Time] [Position]: "Morning Server", "Evening Cook"
[Position] - [Location]: "Server - Downtown", "Cook - Airport"
[Shift Type]: "Opening Shift", "Closing Shift", "Mid Shift"

Template Properties

Duration Calculation

Template duration is calculated automatically:

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

Examples: | Start | End | Break | Duration | |-------|-----|-------|----------| | 09:00 | 17:00 | 30 min | 7.5 hours | | 08:00 | 16:00 | 60 min | 7.0 hours | | 22:00 | 06:00 | 30 min | 7.5 hours (overnight) |

Color Override

If set, overrides the position's default color
Useful for visually distinguishing similar shifts
Uses hex color format (#RRGGBB)

Permissions Summary

| Action | Employee | Manager | Admin | Owner | |--------|----------|---------|-------|-------| | View templates | | ✓ | ✓ | ✓ | | Create templates | | ✓ | ✓ | ✓ | | Edit templates | | ✓ | ✓ | ✓ | | Delete templates | | ✓ | ✓ | ✓ | | Apply templates | | ✓ | ✓ | ✓ |

API Reference

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

Template Endpoints

GET    /api/v1/organizations/{org}/shift-templates              # List templates
GET    /api/v1/organizations/{org}/shift-templates/{id}         # Get template
POST   /api/v1/organizations/{org}/shift-templates              # Create template
PATCH  /api/v1/organizations/{org}/shift-templates/{id}         # Update template
DELETE /api/v1/organizations/{org}/shift-templates/{id}         # Delete template
POST   /api/v1/organizations/{org}/shift-templates/{id}/apply   # Apply template

List Templates Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | position_id | string | Filter by position | | location_id | string | Filter by location (includes global) | | active_only | boolean | Only active templates (default: true) |

Apply Template Request

{
  "schedule_id": "uuid",
  "location_id": "uuid",
  "dates": ["2024-01-15", "2024-01-16", "2024-01-17"],
  "user_id": "uuid or null"
}

Apply Template Response

{
  "shifts_created": 3,
  "shift_ids": ["uuid1", "uuid2", "uuid3"]
}

Template Response Example

{
  "id": "abc123",
  "organization_id": "org456",
  "name": "Morning Server",
  "description": "Breakfast and lunch service",
  "position": {
    "id": "pos789",
    "name": "Server",
    "color": "#4CAF50"
  },
  "location": null,
  "start_time": "07:00:00",
  "end_time": "15:00:00",
  "break_minutes": 30,
  "duration_minutes": 450,
  "duration_hours": 7.5,
  "is_overnight": false,
  "color": null,
  "is_active": true,
  "sort_order": 10,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Best Practices

Template Strategy

Start with common patterns: Create templates for your most frequent shifts
Use descriptive names: Make templates self-explanatory
Set consistent break times: Match your organization's break policy
Review quarterly: Archive unused templates, add new ones

When to Use Templates vs Manual Entry

| Scenario | Recommendation | |----------|----------------| | Standard recurring shifts | Use templates | | One-off special event | Manual entry | | New position being tested | Manual entry, then template | | Training shifts | Create a template |

Template Maintenance

Audit regularly: Remove templates no longer in use
Update for policy changes: If break times change, update templates
Document in descriptions: Note any special instructions

Frequently Asked Questions

Can employees see templates?

No, templates are only visible to managers and above. Employees see the resulting shifts.

Do templates sync across locations?

Global templates (no location set) appear for all locations. Location-specific templates only appear for their assigned location.

What happens if I delete a position used by templates?

Templates using that position will also be deleted (cascade delete).

Can I import/export templates?

This feature is planned for a future release. Currently, templates must be created manually.

Are templates included in schedule copies?

No, copying a schedule copies shifts, not template associations. Templates are used only for creation.

Can I apply the same template multiple times to the same date?

Yes, you can create multiple shifts from the same template on the same date (for different employees or multiple open shifts).

How do I handle seasonal schedules?

Create templates for each season (e.g., "Summer Morning Server", "Winter Morning Server") and deactivate off-season templates.

Last updated: December 2024 (Task 17: Shift Templates)