OSVL User Guide

Getting Started

What is OSVL?

The Operational Scheduling Visibility Layer (OSVL) is a centralized operational scheduling tool for Placemakr property-level coordination. It unifies demand signals across front desk coverage, housekeeping scheduling, and maintenance/tech coverage into a single shared view.

OSVL is not a PMS replacement, payroll system, or full workforce management platform. It is a decision-support system — a shared operational visibility layer that helps managers understand daily operations and connect demand to staffing decisions.

Who Is This For?

• Property Managers — oversee daily operations and staffing across departments
• Front Desk / Operations Managers — manage guest arrivals, departures, and front desk coverage
• Housekeeping Managers — plan cleaning demand and staff workloads
• Maintenance / Tech Ops Managers — track repair tasks and on-call coverage
• Central Operations Leadership — gain visibility across properties

Client Stakeholders

• Walter Stanley — VP, Property Operations
• Allie Ayers — Sr. Director, Property Operations

Navigation

The sidebar on the left provides access to all sections:

The sidebar can be collapsed for more screen space. Your current location is highlighted in the sidebar menu.

---

Property Dashboard

Overview

The Dashboard is your starting point each day. It provides a snapshot of the current operational state for a single property, designed so a manager can understand daily operations in under 2 minutes.

KPI Cards

Four cards appear at the top of the dashboard:

Unit Status Bar

A horizontal bar chart visualizes the distribution of all units by status:

• Ready (green) — clean, inspected, and available for guests
• Dirty (amber) — needs cleaning after checkout or stayover service
• In Progress (blue) — cleaning is currently underway
• Maintenance Hold (red) — unit is blocked for repairs and unavailable
• Inspecting (purple) — post-clean inspection in progress

The bar shows both the count and proportion for each status, giving you an instant read on property readiness.

Today's Coverage

A summary table shows staffing for all departments and shift types. Each row displays:

• Department (Front Desk, Housekeeping, Maintenance)
• Shift type (Morning, Afternoon, Evening, Overnight)
• Number of staff assigned vs. required
• Whether a Manager-on-Duty (MoD) is assigned for that slot

14-Day Occupancy Forecast

Color-coded daily tiles provide a two-week look-ahead:

• Green — occupancy below 75% (lighter operational load)
• Amber — occupancy between 75–89% (moderate load)
• Red — occupancy at 90% or above (high load, watch for staffing gaps)

Each tile displays the day of week, date, occupancy percentage, arrivals (↓), and departures (↑). Today's tile is highlighted with a ring border.

Tip: Use the forecast to anticipate high-demand days and pre-staff accordingly. Arrival spikes correlate with front desk demand; departure clusters increase housekeeping workload.

---

Daily Operations Board

Overview

The Daily Operations Board provides a task-level view of what needs to happen today. It shows unit readiness and active work orders for housekeeping and maintenance.

KPI Cards

Unit Readiness Bar

Same as the Dashboard unit status bar — shows proportional breakdown of all unit statuses.

Maintenance Queue

A table listing active maintenance work orders with:

• Unit — the unit number affected
• Issue — description of the maintenance problem
• Priority — 🔴 High, 🟡 Medium, 🟢 Low
• Status — current status badge (pending, in-progress)

Unit Readiness Grid

A compact color-coded grid showing 60 units at a glance. Each cell is colored by status and shows the unit number. Hover over any cell to see the full unit number and status in a tooltip.

Color coding:

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

---

Housekeeping Planner

Overview

The Housekeeping Planner calculates cleaning demand based on departures and stayovers, then recommends staffing levels per shift.

How Demand Is Calculated

• Checkout cleans (turns) — triggered by departures. Each departure requires a full clean.
• Stayover cleans — triggered by occupied units staying another night. Lighter service.

The system estimates total cleaning hours and recommends the number of housekeepers needed.

KPI Cards

Today's Progress

A progress bar tracks completion throughout the day:

• Shows tasks completed vs. total
• Percentage complete
• Breakdown: ✓ Completed, ⟳ In Progress, ○ Pending

Shift Workload Breakdown

Two cards show the estimated workload split:

• Morning Shift (7a–3p) — receives approximately 70% of the day's workload
• Afternoon Shift (3p–11p) — receives approximately 30% of the day's workload

Each card shows estimated hours and recommended staff count for that shift.

Cleaning Time Standards

Task Queue

A detailed table of all housekeeping tasks showing:

• Unit number
• Clean type (Checkout Clean or Stayover Clean)
• Status badge (pending, in-progress, completed, blocked)
• Priority indicator (🔴🟡🟢)
• Estimated completion time in minutes

---

Coverage Planner

Overview

The Coverage Planner shows staffing levels across all departments and shifts, with specific attention to Manager-on-Duty (MoD) scheduling and close/open shift conflict detection.

KPI Cards

Manager-on-Duty (MoD) Schedule

MoD is assigned at the property level — exactly one MoD AM and one MoD PM slot per day, regardless of department. The MoD role rotates daily across the eligible manager pool.

MoD Eligibility Rules

Only managers are eligible for MoD shifts:

• Front Office Managers
• Housekeeping Managers
• GM / Operations Managers

Important: Supervisors are NOT part of the MoD program per Placemakr policy. This is enforced system-wide.

Weekend Coverage Rule

• Weekdays: AM MoD required; PM MoD optional.
• Weekends (Sat & Sun): Both AM and PM MoD are required. A high-severity alert fires when either slot is missing.

MoD Frequency Limits

Maintenance Scheduling

Maintenance staff are scheduled AM and PM only. Overnight maintenance is handled via the on-call rotation and is not scheduled as standard shifts in OSVL.

Housekeeping Scope

The Coverage Planner housekeeping rows reflect managers and supervisors only. Cleaning staff (room attendants) are scheduled outside OSVL for now and are excluded from coverage gap calculations. The Housekeeping Planner page tracks task demand only — its staffing recommendations are informational.

Close/Open Shift Conflict Detection

The system automatically flags close/open conflicts — when any staff member is scheduled to:

1. Close at 11:00 PM one day
2. Open at 7:00 AM the following day

These conflicts appear in a highlighted warning card with staff name, department, date, and a destructive "Close 11PM → Open 7AM" badge. They also generate high-severity alerts.

Best Practice: Always review the Coverage Planner before finalizing close (11 PM) shift assignments. Use MoD rotation to distribute overnight coverage fairly among eligible managers.

7-Day Coverage Overview

A weekly grid showing each of the next 7 days with:

• Day of week and date
• Total shift count for that day
• MoD badge if a manager-on-duty is assigned
• ⚠ badge if a close/open conflict exists

Today is highlighted with a primary-colored border.

---

Alerts & Exceptions

Overview

The Alerts page aggregates all operational risks and flags that require attention. It surfaces issues automatically based on scheduling rules and operational thresholds.

Severity Levels

Severity counts appear as badges at the top of the page for quick triage.

Alert Types Currently Active

• Schedule Conflict — close/open shift violation detected for a specific staff member
• Housekeeping — dirty unit count exceeds 15% of total property inventory
• Maintenance — more than 3 units in maintenance hold (growing backlog)
• Coverage — no MoD coverage for Saturday overnight shift

Alert Details

Each alert shows:

• Severity badge with color coding
• Category label (Schedule Conflict, Housekeeping, Maintenance, Coverage)
• Summary message
• Detailed explanation text

---

Configuration

Overview

The Configuration page displays the current system settings. In this demo version, settings are read-only and defined in the demo data layer.

Properties

A table of all configured properties showing:

• Property name and short code (DC, WS, BA)
• Total unit count
• Manager allocation: Front Office managers, Housekeeping managers, GM/OM count

Demo Properties

Shift Templates

Standard shift times used across the system:

Coverage & Scheduling Rules

Six active rules govern scheduling behavior:

1. Close/Open Prevention — flags 11 PM close followed by 7 AM open
2. MoD Eligibility — managers only (FO, HK, GM/OM); supervisors excluded
3. GM/OM MoD Frequency — max 3 MoD shifts per week
4. FO/HK Manager MoD Frequency — max 2 MoD shifts per week
5. Weekend Coverage — at least 1 MoD shift required on Saturday and Sunday
6. Overnight Maintenance — on-call maintenance required for overnight shifts

---

Daily Workflow

Recommended Morning Routine

1. Open the Dashboard — review occupancy, arrivals, and departures for the day
2. Check Alerts — address any critical or high-severity items immediately
3. Review Coverage Planner — confirm all shifts are staffed and MoD is assigned
4. Open Housekeeping Planner — verify recommended staffing matches actual availability
5. Check Daily Operations — review unit readiness grid and any maintenance blockers

Throughout the Day

• Monitor the Housekeeping Planner progress bar as cleans are completed
• Watch for new alerts that may arise from changing conditions
• Use the Unit Readiness Grid to spot units not ready near check-in times

End of Day

• Verify unit readiness for next day's arrivals using the forecast
• Review the next day's coverage in the Coverage Planner
• Check for any close/open conflicts in upcoming shifts

Reading the 14-Day Forecast

• High-occupancy days (90%+): Pre-staff with additional housekeepers and front desk coverage
• Arrival spikes: Correlate with higher front desk demand — ensure adequate afternoon coverage
• Departure clusters: Drive increased housekeeping demand — plan extra morning staff
• Weekend patterns: Typically higher occupancy — verify MoD coverage is assigned

---

PMS Integration Readiness

Why OSVL needs PMS data

OSVL's value depends on visibility into the property management system. Occupancy, arrivals, departures, in-house guests, and unit housekeeping status all originate in the PMS. OSVL never replaces the PMS — it reads operational signals and turns them into staffing and readiness decisions.

What OSVL reads (read-only)

What OSVL never writes

OSVL is a read-only consumer. It does not create, modify, or cancel reservations, post charges, or update guest profiles.

Two viable integration paths

The client chooses one; OSVL's data-access seam supports either with no UI change.

• Apaleo (direct) — OAuth 2.0 + webhooks. Near real-time, light client setup, single-vendor coupling.
• Azure Data Warehouse — Read curated views via Entra ID service principal. Latency = client ETL cadence, heavier intake, PMS-agnostic.

Per-path intake checklists are available as downloadable PDFs.

Breezeway connector (staging)

A staging-tier connector to Breezeway via the Placemakr API Gateway ships in v0.0.5 and runs behind the same PmsSource seam.

• Auth: OAuth2 client credentials. Bearer token is fetched server-side only; the client key never reaches the browser bundle.
• Endpoints used: /v1/breezeway/properties, /v1/breezeway/tasks, /v1/breezeway/people, /v1/breezeway/templates.
• Refresh cadence: tasks polled with a 2-day rolling updated_at window (day-granularity is all the proxy supports today). properties polled daily.
• Rate limit: 300 req/min on the proxy — well above our polling needs.
• Join key: Breezeway property.reference_property_id = Apaleo Unit ID. This is the single source of truth for the cross-system join and drives the pms-join-miss alert rule once Apaleo lands.
• Webhooks: not available yet on the proxy; the client team can enable forwarding if polling freshness proves insufficient.
• Status: Connector is wired and reachable from the Configuration page's Test connection button. Demo PMS remains the default source for dashboards until the cross-system join is verified.

Apaleo connector (direct)

A direct connector to Apaleo ships in v0.0.6 and runs behind the same PmsSource seam.

• Auth: OAuth2 client credentials against identity.apaleo.com. APALEO_CLIENT_ID / APALEO_CLIENT_SECRET are read inside the server function handler; never bundled to the browser.
• Scopes: accounts.read properties.read reservations.read units.read unitgroups.read (granted by Alicia Barnash, June 2026).
• Endpoints used: /v1/inventory/properties, /v1/inventory/units, /v1/inventory/unit-groups, /v1/reservations, /v1/account.
• Refresh cadence: properties & unit-groups daily; units hourly; reservations on a 7-day forward window every 15 min.
• Join with Breezeway: getApaleoSnapshotFn returns a joinCoverage percentage comparing Breezeway reference_property_id against Apaleo property IDs. Drives the pms-join-miss alert in v0.0.7.
• Webhooks (requested): reservation.created, reservation.changed, reservation.checked-in, reservation.checked-out, reservation.canceled, unit.changed, unit.cleaning-status-changed. Receiver endpoint pending in v0.0.7.
• Activation: set VITE_PMS_SOURCE=apaleo to swap the active source app-wide. As of v0.0.10 the flag propagates to all four operator dashboards (Property Dashboard, Daily Operations, Housekeeping, Coverage). Units and occupancy come from the live Apaleo snapshot; staffing, shifts, and MoD continue to come from OSVL Configuration / demo seed since Apaleo doesn't own those.
• Refresh window: dashboards read through a 60-second snapshot cache — flipping a unit dirty in Apaleo will appear within a minute, or immediately if you click Refresh now on the Configuration page.

Fallback when data is stale

If the active source has not produced fresh data within 60 minutes, OSVL fires a high-severity PMS Feed alert. The Demo PMS badge near each KPI shows which source produced the number — once a real connector is wired in, the badge auto-flips to Apaleo, Breezeway, or Azure.

Active source visibility

The Configuration page lists every PMS source (Demo, Breezeway, Apaleo, Azure) with status, last sync, latency, and row counts.

Webhooks & live updates (v0.1.0)

OSVL exposes a public receiver at /api/public/pms-webhook for the Placemakr API Gateway to forward Apaleo + Breezeway events to. Every forwarded request is HMAC-verified (X-Placemakr-Signature) against the PMS_WEBHOOK_SIGNING_SECRET returned once when the subscription is created.

When an Apaleo reservation/unit/booking/maintenance event arrives, the 60-second snapshot cache is invalidated immediately — the next dashboard read pulls fresh data instead of waiting for the polling window. Replays are deduped on X-Placemakr-Delivery.

The Configuration page PMS Webhook Receiver card shows signing-secret status, accepted/rejected counters, and the last 10 received events. Click Copy URL to paste the receiver into the gateway subscription request.

pms-join-miss alert

If a forwarded Breezeway event carries a reference_property_id that does not match any Apaleo property or unit id in the current snapshot, a High severity pms-join-miss alert appears on /alerts with the unmatched id, source event, and occurrence count. This is the live version of the join-coverage check on the Configuration page — it catches missing tenant mappings the moment a real event references them, instead of waiting for a manual review. Each unmatched reference is deduped for 24 hours.

---

Glossary