GuestOps/docs/pms.md

OHIP reservations and approved changes

GuestOps supports exact confirmation lookup, internal reservation notes and stay-date changes for reservations in Reserved status. Each change is saved in MongoDB and reviewed by an owner before a single OHIP update attempt. Creation, cancellation, room/rate changes and payment links are not implemented in this milestone.

Server configuration

Copy deploy/pms.example.json to a private pms.local.json outside your checkout and populate this structure, replacing the hotel ID with the internal GuestOps ID shown on the Reservations page:

{
  "Pms": {
    "Hotels": {
      "REPLACE_WITH_32_CHARACTER_GUESTOPS_HOTEL_ID": {
        "BaseUrl": "https://YOUR-OHIP-GATEWAY",
        "HotelCode": "YOUR_PROPERTY_CODE",
        "ClientId": "YOUR_CLIENT_ID",
        "ClientSecret": "YOUR_CLIENT_SECRET",
        "AppKey": "YOUR_APPLICATION_KEY",
        "EnterpriseId": "YOUR_ENTERPRISE_ID",
        "Scope": "urn:opc:hgbu:ws:__myscopes__",
        "WritesEnabled": false,
        "NoteType": "RESERVATION",
        "NoteLocation": "GEN"
      }
    }
  }
}

Use the client-credentials grant and property permissions supplied for your OHIP environment. Confirm the note type and notification-location codes with the property. The gateway must be an HTTPS origin, without a path. There is no shared fallback configuration between hotels.

Set PMS_CONFIG_FILE_HOST in the deployment .env to the absolute private file path. Compose mounts it read-only into the API; the worker does not receive these credentials. Restrict host permissions to the administrator and the API container's user/group, while allowing that user to read the file. Obtain the image's user ID with docker run --rm --entrypoint id YOUR_API_IMAGE -u before assigning permissions. Never put credentials in the browser, repository or an image. Restart the API after configuration changes; this file is not hot-reloaded.

The default deployment mounts an empty example and makes no OHIP calls. Begin with sandbox credentials and WritesEnabled: false. Lookups can be tested without enabling writes. After sandbox acceptance, server write enablement and the hotel's owner-controlled MongoDB setting must both be enabled. Every operation still needs individual owner approval.

Review and recovery

1. Look up the exact confirmation number and check guest, property, dates and booking details.
2. Prepare an internal note or changed dates. Preparation saves a proposal; it does not update OHIP. Snapshots and approvals expire after ten minutes.
3. For date changes, check availability, rate consequences and guest agreement in the PMS. GuestOps does not calculate or guarantee the resulting price.
4. Review and approve. GuestOps re-reads the booking and rejects a changed snapshot before submitting. Only one active operation per hotel/reservation is allowed.
5. GuestOps reads the result back. An HTTP success alone is insufficient. A timeout, interrupted request or mismatched result is held for verification and is never automatically replayed.

Use Verify current PMS state for uncertain results. An interrupted Applying operation becomes eligible after five minutes; the request deadline is ninety seconds. Verification only reads OHIP. Matching dates prove the observed state, not who changed it. Disabling writes does not prevent verification. Rotating credentials or changing the property binding invalidates old proposals and requires administrator investigation of unresolved operations.

A proposal can be cancelled before application. An uncertain applied operation cannot be cancelled or force-cleared from the UI: an operator must reconcile it with the PMS and audit history. There is no background retry or unsafe override. Lookup snapshots expire from MongoDB after one day; operation journals retain embedded before/after snapshots. The UI displays the latest 500 journal entries.

Validation and limits

The adapter follows Oracle's property reservation schema, version 26.3.0.0 inspected on 2026-09-10 (SHA-256 8d95a8a060f2898eee7c9f749c83255ffde426258412c735e3f55180c0c000c1). Notes use putReservation, preserving the existing comment array; dates update arrival/departure without inventing rate data.

Automated fixture tests cover tenant isolation, concurrent approvals, changed reservations, payload preservation, write controls, interrupted results and read-only reconciliation. They do not call OHIP and are not vendor certification. Before live enablement, validate your property's sandbox responses, note codes and retention, date/rate/inventory effects, credentials and permissions, and interrupted-request handling.

The adapter does not have a vendor-guaranteed conditional-write transaction. Re-reading before submission reduces stale updates but cannot eliminate a change made by another PMS user between that read and the write. Reservation updates therefore remain explicitly reviewed, narrow operations. Preview mode shows a sample proposal and blocks real PMS actions.