Needs Attention: Reservation Conflicts Help
Overview
The Needs Attention tab is where facility managers resolve conflicts that occur when an externally-imported reservation (from Airbnb, Booking.com, or other OTAs via iCal) and a direct UnlockOS reservation overlap in the same time slot and room.
Why This Tab Exists
iCal feeds work by having UnlockOS periodically poll external platforms for new reservations. Because there is always a delay between when a booking is made externally and when UnlockOS picks it up, a guest can make a direct reservation on UnlockOS during that window — creating a collision. This race condition cannot be completely eliminated by design.
When a collision occurs, UnlockOS handles it as follows:
- First-arrival wins — The reservation that arrived at UnlockOS first is the "winner." The later-arriving reservation becomes the "loser" and its status is set to "Conflict (Action Required)" (pre-empted).
- Automatic detection — The system detects the conflict and sends an email notification to the facility owner.
- Conflict surfaces across the dashboard — The Needs Attention tab badge, calendar warning banner, and reservation list markers all display the conflict so you can spot it from any screen.
This tab acts as a safety net, preventing double-booking confusion and key mis-delivery to guests.
What you can do on this tab:
- Review all unresolved, actionable reservation conflicts
- Open a specific conflict directly from an email deep link (with highlight)
- Click a row to open the loser (later-arriving) reservation detail drawer and resolve the conflict
- Click the winner's name link to open the winner (earlier-arriving) reservation detail drawer and inspect or edit it
- Past conflicts (checkout date passed) are automatically hidden from the list and badge count
How to Access
When a conflict occurs, warnings appear in three places across the dashboard so you can't miss it:
| Surface | What you see |
|---|---|
| Needs Attention tab badge | A red count badge appears on the tab. It disappears when all conflicts are resolved. |
| Calendar (week view) warning banner | A red banner appears above the calendar grid. Click it to jump to the Needs Attention tab. Reservation bars for both the loser and winner also receive a ⚠️ marker. |
| Reservation list warning banner and ⚠️ markers | A red banner appears at the top of the list. Loser (Conflict) and winner reservation cards are highlighted with a red border and ⚠️ marker. |
To navigate directly to the Needs Attention tab:
- When a notification email arrives, click the "Review conflict" link in the email.
- In the admin dashboard, open the Booking Management section and click the "Needs Attention" tab (look for the red badge when there are unresolved conflicts).
Direct URL format: ?audit_id=... (email links use this format)
Features
Feature 1: Conflict List
Only actionable, unresolved conflicts are listed — conflicts whose loser reservation's checkout date has already passed are automatically excluded. Each row shows:
| Field | Description |
|---|---|
| Guest name / Confirmation code | The name or confirmation number of the unassigned (loser) reservation |
| Winner | The name or confirmation number of the prioritized (winner) reservation. This is a link — clicking it opens the winner's reservation detail drawer. |
| Overlap period | The start and end of the conflicting time window |
| Loser source | Origin of the later-arriving reservation (e.g. Airbnb (iCal), Direct) |
| Winner source | Origin of the earlier-arriving reservation |
| Detected at | When the conflict was detected |
Click anywhere on a row (except the winner name link) to open the loser reservation detail drawer. Click the winner's name link to open the winner reservation detail drawer. If you arrived via an email link, the target conflict row is highlighted in red.
Feature 2: Resolution Workflow
Step 1: Choose which reservation to open
Each conflict card has two clickable entry points:
| Click target | Opens | When to use |
|---|---|---|
| Row (anywhere except winner name) | Loser (later-arriving) reservation | When you want to cancel or change the room for the loser reservation |
| Winner name link | Winner (earlier-arriving) reservation | When UnlockOS' first-arrival decision is the opposite of what you intended, and you need to edit or cancel the winner instead |
Tip: First-arrival priority is determined mechanically. If the "wrong" reservation won, open the winner's drawer via the winner name link and take action there.
Step 2: Choose a resolution action
From the drawer, select one of the following:
| Resolution | When to use | How |
|---|---|---|
| Change room | Another room is available and you want to accommodate both guests | Click "Change room" (or "Edit") in the drawer, select a different room type, and save |
| Cancel | You want to remove this reservation | Click the "Cancel" button in the drawer |
Once resolved, the conflict card is immediately removed from the list. The tab badge count, calendar warning banner, and reservation list banner all update in real time.
Feature 3: Automatic hiding of past conflicts
When the loser reservation's checkout date has passed, the conflict is automatically removed from the list and excluded from the "◯ unresolved conflicts" badge and banner counts.
This is by design: once the checkout window has passed, there is no meaningful action to take on that conflict. The list stays focused on conflicts that still need attention.
Note: To review historical conflict records, see the Audit Log.
FAQ
Q: What determines which reservation wins?
Priority is determined by arrival order at UnlockOS (intent.created_at, first-arrival wins). The "winner" is the earlier arrival; the "loser" (unassigned/pre-empted) is the later arrival. Being an OTA reservation or a direct reservation does not automatically give either one an advantage.
Q: The wrong reservation won. How do I fix it?
Click the winner's name link on the conflict card to open the winner's reservation detail drawer. From there you can change the winner's room or cancel it. Resolving either reservation (loser or winner) will remove the conflict card from the list.
Q: Do the badge count and banners update immediately after I resolve a conflict?
Yes. The conflict card is removed from the list immediately upon resolution. The tab badge count, calendar warning banner, and reservation list banner all update in real time — no page reload required.
Q: A conflict card disappeared by itself. What happened?
If the loser reservation's checkout date has passed, the conflict is automatically removed from the list and excluded from the badge count. Conflicts that can no longer be acted on are hidden to keep the list focused. To review the record, check the Audit Log.
Q: Why are warnings shown in three places — the tab, the calendar, and the reservation list?
The warnings are shown across all dashboard surfaces so you can't miss a conflict regardless of which screen you are working on. All three surfaces draw from the same data source.
Q: What should I do if I don't receive the notification email?
Check the following:
- Confirm the notification email address is correctly configured in your facility settings.
- Check your spam/junk folder (sender:
noreply@unlockos.io). - Even without an email, the conflict is visible in the Needs Attention tab — check the tab regularly.
- Email notifications may take up to 5 minutes after a conflict is detected (see Troubleshooting for details).
Q: How do I move the loser reservation to a different room?
Click the conflict row (anywhere except the winner name) to open the loser detail drawer, then click "Change room" or "Edit." In the edit form, select a different room type and save. The reservation status will be updated from "Conflict (Action Required)" to its normal confirmed flow.
Q: Can a resolved conflict reappear in the list?
Resolved conflicts are removed from the list immediately. If the same time slot is imported again from an iCal feed re-sync (because the external cancellation has not yet been completed), a new conflict entry may appear. Complete the cancellation on the external platform before triggering another sync to avoid this.
Q: Can I resolve multiple conflicts at once?
Currently, conflicts must be resolved one at a time. If multiple conflicts exist, work through them from top to bottom in the list.
Troubleshooting
I resolved a conflict but the card is still showing
No page reload should be needed — the card disappears immediately on a successful resolution. If it persists:
- Check whether the drawer showed a success message (e.g. "Saved" or "Cancelled"). If not, the action may not have completed.
- Check your network connection and try again.
- Force-reload the page (Ctrl+Shift+R / Cmd+Shift+R) to re-fetch the list.
- If the problem persists, contact support with a screenshot.
Email notification is delayed
Conflict detection emails are sent by a background scheduled job (pg_cron) that checks for unresolved conflicts on a recurring basis. This job runs approximately every 5 minutes. As a result, there can be up to a 5-minute delay between when the conflict occurs and when you receive the notification email.
If you need to act immediately, go directly to the Needs Attention tab rather than waiting for the email.
I opened the drawer but see an error
- Check your network connection.
- Reload the page to refresh the conflict list and try again.
- Try in a different browser or in a private/incognito window.
- If the problem persists, contact support and include a screenshot of the error message.
The badge count is not going to zero
Resolved and past (checkout-passed) conflicts are both excluded from the count. If the badge remains, there are still unresolved, actionable conflicts in the list. Scroll through the full list to find them.
The conflict list is empty but I received an email
The conflict may have been resolved by another administrator between the time the email was sent and when you opened the tab. Past conflicts may also have been automatically removed because their checkout date passed. Check the Audit Log to review the resolution history.