OSVL User Guide

Welcome to OSVL — the Operational Scheduling Visibility Layer for Placemakr. This guide walks new users from first sign-in through daily use, page by page. If you only have five minutes, read Quick Start and Your First Day.

---

Quick Start

OSVL in one paragraph. OSVL is a read-only operational view that pulls live occupancy and unit status from the PMS and combines it with shift schedules you build inside the app. It tells you, for any property and any day: how many units are ready, how many guests are arriving, who's working, who is Manager-on-Duty, and what's about to go wrong. It does not replace your PMS or payroll system.

Your three most-used pages:

Daily rhythm:

1. Open the Dashboard for your property.
2. Check Alerts — clear anything Critical or High before opening the doors.
3. Glance at the Schedule for today and tomorrow.
4. Mid-month: build and publish next period's schedule from the Schedule page.

---

Getting Started

Signing In

1. Go to your OSVL URL and click Sign in.
2. Use your work email and the password you set during invite, or click Sign up if your admin has enabled self-service.
3. After sign-in you'll land on the Dashboard for your default property.

Forgot your password? Use the Reset password link on the sign-in page — you'll get an email with a one-time link.

Switching Properties

The Property Switcher in the top of every operations page lets you jump between properties. The portfolio you can see is controlled by your role and the access your admin granted you.

Roles at a Glance

Navigation

The left sidebar is your map:

Collapse the sidebar with the chevron icon for more screen space. The current page is highlighted.

---

Your First Day

A short walkthrough you can do end-to-end in about 15 minutes the first time you log in.

1. Pick your property. Top-right Property Switcher → choose the property you manage.
2. Read the Dashboard. Occupancy, arrivals, departures, turns — confirm the numbers match what you see in the PMS. If they look stale, check the PMS source badge under the KPIs (see PMS Integration below).
3. Open Alerts. Triage anything in Critical/High. Most first-day alerts are missing MoD on weekends or close/open conflicts left over from the prior tool.
4. Open Schedule for the current week. The grid shows every manager and supervisor; each cell is a shift. Click any cell to edit, or drag-select a row to apply a template.
5. Open Daily Operations. Confirm the unit readiness grid makes sense. Hover any cell to see the unit number and status.
6. Bookmark the URL — OSVL works in any modern browser; no app to install.

Tip: If your screen shows the Demo PMS badge, you're seeing seeded sample data. Real PMS data flips on once your admin enables the Apaleo or Breezeway connector.

---

Property Dashboard

The Dashboard is your starting point each day. It's designed so any manager can understand the state of the property in under two minutes.

KPI Cards

Each card carries a small source badge (Demo / Apaleo / Breezeway / Azure) so you know whether the number is live or seeded.

Current Occupancy vs. Forecast: Current Occupancy reads live unit status from the PMS (who is actually in-house right now). The 14-Day Forecast anchors today to that same live in-house count and rolls forward using reservation arrivals and departures. The two numbers should agree on day 0.

14-Day Occupancy Forecast

Color-coded tiles, two weeks out:

• Green — under 75% (lighter load)
• Amber — 75–89% (moderate)
• Red — 90%+ (high; pre-staff)

Each tile shows date, occupancy %, arrivals (↓) and departures (↑). Today gets a ring border. Day 0 is anchored to the live in-house unit count (matches the Current Occupancy KPI). Each subsequent day rolls the previous day's occupied count by + arrivals − departures, clamped to total units. This carries hidden in-house population (extended stays, house/comp rooms, sync lag) forward so staffing and turnover math isn't understated.

Today's Coverage

Summary of staffing by department and shift type — assigned vs required, plus the MoD assignment for the day.

Unit Status Bar

A single horizontal bar shows the breakdown of every unit:

• Ready (green) — clean and inspected
• Dirty (amber) — needs cleaning
• In Progress (blue) — cleaning underway
• Maintenance Hold (red) — blocked for repairs
• Inspecting (purple) — post-clean inspection

Active Alerts

Standalone card at the bottom of the dashboard showing the top operational alerts for the property. Full triage lives on /alerts.

Tip: Use the forecast to anticipate high-demand days. Arrival spikes mean front-desk pressure; departure clusters mean housekeeping pressure.

---

Daily Operations Board

Task-level view of what needs to happen today.

KPI Cards

Maintenance Queue

Active work orders with unit, issue, priority (🔴 High / 🟡 Medium / 🟢 Low), and status.

Unit Readiness Grid

60 units at a glance. Hover any cell for unit number and status:

• Green = Ready · Red = Dirty · Amber = In Progress · Gray = Maintenance Hold · Blue = Inspecting

---

Housekeeping Planner

Calculates cleaning demand from departures and stayovers, then recommends staffing.

How demand is calculated

• Checkout cleans (turns) — one per departure, full clean
• Stayover cleans — lighter service for occupied units staying another night

KPI Cards

Today's Progress

Progress bar with ✓ Completed / ⟳ In Progress / ○ Pending.

Shift Workload Split

• Morning (7a–3p): ~70% of the day's workload
• Afternoon (3p–11p): ~30%

Cleaning Time Standards

Task Queue

Every HK task with unit, type, status, priority, and estimated minutes.

Note: Room attendants are not currently scheduled in OSVL. The Housekeeping Planner is demand-side only — recommended staff is informational.

Rolled Rooms

Placemakr policy is to clean every occupied room every day. If a room needs to be rolled (skipped), it requires management approval and the corresponding Breezeway task must be expired — not deleted, not left open. Expiring the task keeps the Apaleo↔Breezeway sync clean and lets OSVL show the correct clean load.

• The Rolled Today tile shows how many tasks were expired for the day.
• Rolled rows appear muted in the Task Queue with a "rolled" badge and do not count toward pending work, hours, or recommended staff.
• A low-severity alert appears on the Dashboard so leaders can verify each roll was approved.

---

Schedule Builder

The Schedule page is where you build, publish, and distribute the weekly schedule. This is the most-used page for managers.

Layout

• Week selector at the top — chevron arrows to move ±1 week, calendar to jump.
• Period banner — shows the current scheduling period (1st–15th or 16th–end) and whether it's draft, published, or overdue.
• Staff grid — one row per manager/supervisor, seven columns (Mon–Sun). Each cell is a shift.
• MoD meter — sidebar pill showing how many MoD shifts each manager has this week vs the weekly cap.
• On-Call card — who is the maintenance on-call this week.

Building a week

1. Pick the week in the selector.
2. Click Apply Template to drop a starting pattern based on your roster (the system auto-picks the right template: GM/OM + 1 Sup, GM/OM + 2 Sup, GM + 2 Mgr + 2 Sup, or Small Team).
3. Click any cell to add, edit, or delete an individual shift. The drawer lets you set start/end, role, and whether the shift is MoD.
4. Use the MoD Suggest button (✨) — OSVL recommends an MoD assignment per day based on weekly caps, role eligibility, and occupancy.
5. Watch for the ⚠ Close/Open badge — fires whenever someone is scheduled to close at 11 PM and open at 7 AM the next day. Resolve before publishing.

Publishing

1. When the period is complete, click Submit Period.
2. The period flips to Published and becomes the source of truth for Dashboard and Coverage.
3. Click Copy Engage Post to put a Markdown-formatted weekly summary on your clipboard — paste into the Saturday-8am Engage post.

Period due dates

• Period 1 (1st–15th): due by the 5th of the month.
• Period 2 (16th–end): due by the 20th of the month.

The Dashboard and Schedule page surface a yellow Period Due banner once you're inside the due window. Overdue periods raise a High-severity alert.

MoD rules (enforced in the builder)

• Exactly one AM and (often) one PM MoD per day at the property level.
• Managers only — FO Manager, HK Manager, GM/OM. Supervisors are not eligible.
• Weekdays: AM required; PM optional.
• Weekends (Sat/Sun): AM and PM required.
• Per-week caps: GM/OM 3 shifts, FO/HK Manager 2 shifts.

On-call

• Maintenance is scheduled AM/PM only in OSVL; overnight is covered by the on-call rotation.
• Set the week's on-call from the On-Call card in the Schedule sidebar.

---

Coverage Planner

A read-only roll-up of everything in the Schedule, optimized for review and conflict-spotting.

KPI Cards

Sections

• MoD schedule — 7-day view of who is MoD each AM/PM block.
• Close/Open conflict card — highlighted warnings with staff name, department, and date.
• 7-Day coverage overview — per-day shift count, MoD badge, and ⚠ conflict badge.

Best practice: Review Coverage every Friday for the upcoming week — it's faster than scanning the full Schedule grid.

---

Alerts & Exceptions

Aggregates every operational risk OSVL detects, automatically.

Severity Levels

Counts appear as badges at the top for quick triage.

Alert Types

• Schedule Conflict — close/open shift violation for a specific staff member
• Coverage — missing MoD on weekends or weekdays
• Housekeeping — dirty unit count exceeds 15% of inventory
• Maintenance — more than 3 units in maintenance hold
• Schedule Period — period overdue past its due date
• PMS Feed — no fresh PMS data in 60+ minutes
• PMS Join Miss — a Breezeway event arrived with a reference id that doesn't match any Apaleo property/unit

---

Admin (Admins only)

The Admin page is hidden from non-admins. It's the single place to manage everything that's not day-to-day operations.

Team & Access

• Invite a user — enter email + role; they get a magic-link invite.
• Change a user's role — inline dropdown on the user row.
• Resend invite / remove user — row actions.
• The system blocks removing the last admin and prevents admins from stripping their own admin role.

Properties, Staff, Shifts

• Inline tables for property metadata, staff roster, and standard shifts.
• Edits here drive what shows up in the Schedule grid and Coverage roll-up.

Coverage & MoD Requirements

• Set per-property minimum coverage levels by department/shift.
• Set MoD weekly caps and weekend rules (defaults reflect Placemakr policy).

Scheduling Rules

Six rules are enforced system-wide:

1. Close/Open Prevention — flags 11 PM close → 7 AM open
2. MoD Eligibility — managers only (supervisors excluded)
3. GM/OM MoD Frequency — max 3/week
4. FO/HK Manager MoD Frequency — max 2/week
5. Weekend Coverage — both AM and PM MoD required Sat/Sun
6. Overnight Maintenance — on-call required for overnight

PMS Connectors

• Demo PMS — seeded data; always available.
• Breezeway — staging connector via the Placemakr API Gateway.
• Apaleo — direct OAuth connector.
• Azure — curated data warehouse views (planned).
• Click Test connection to ping a source. Click Refresh now to bust the 60-second snapshot cache.
• PMS Webhook Receiver card shows signing-secret status, accepted/rejected counters, and the last 10 events.
• Property Mappings card lets you tie Breezeway reference_property_id values to Apaleo property/unit ids — the join key that powers the pms-join-miss alert.

---

Daily Workflow Cheatsheet

Morning (15 min)

1. Dashboard — read today's KPIs and forecast.
2. Alerts — clear Critical/High.
3. Coverage Planner — confirm today's staffing and MoD.
4. Housekeeping — check recommended vs actual staffing.
5. Daily Operations — scan unit readiness for any blockers.

Throughout the day

• Watch the HK progress bar.
• Re-check Alerts after any roster change.
• Use the Unit Readiness Grid to spot units not ready near check-in time.

End of day

• Confirm next-day readiness.
• Review tomorrow's Coverage.
• Scan for upcoming close/open conflicts.

Mid-month (Schedule due)

• By the 5th: publish period 1 (1st–15th).
• By the 20th: publish period 2 (16th–end).
• After publish: Copy Engage Post and paste into the Saturday Engage thread.

---

PMS Integration

Why OSVL needs PMS data

Occupancy, arrivals, departures, in-house guests, and unit housekeeping status all originate in the PMS. OSVL reads these signals and turns them into staffing and readiness decisions. It never writes back.

What OSVL reads

Sources

• Apaleo (direct) — OAuth 2.0 + webhooks. Near real-time.
• Breezeway (via Placemakr API Gateway) — OAuth2 client credentials. Polled every 2 days for tasks, daily for properties. Join key: reference_property_id = Apaleo Unit ID.
• Azure Data Warehouse — curated views via Entra ID service principal (planned).
• Demo PMS — seeded data for training and pilot UI work.

The source badge next to every KPI tells you which source produced the number. Once a real connector is enabled, the badge flips automatically.

Stale-feed alert

If the active source hasn't produced fresh data in 60 minutes, a High severity PMS Feed alert appears in /alerts.

Webhooks & live updates

OSVL exposes /api/public/pms-webhook for the Placemakr API Gateway to forward Apaleo + Breezeway events. Every request is HMAC-verified (X-Placemakr-Signature). A successful event invalidates the 60-second snapshot cache so the next dashboard read is fresh. Replays are deduped on X-Placemakr-Delivery.

pms-join-miss alert

If a forwarded Breezeway event carries a reference_property_id that doesn't match any Apaleo property or unit id, a High severity alert fires on /alerts with the unmatched id, the source event, and the occurrence count. Each unmatched reference is deduped for 24 hours.

---

Troubleshooting

---

Glossary

---

Need Help?

• In-app: Support → User Guide (this page), Release Notes, contact info.
• Bugs / requests: flag them to your Placemakr OSVL lead.
• Outages or stale data: check /alerts first — most issues surface there automatically.