Opera Cloud
Opera Cloud is an hotel management software that can be integrated in HSYCO with an API connection. The current release of the I/O Server has been tested with the Opera Hospitality API
HSYCO Configuration
Add a Opera Cloud I/O Server in the I/O Servers section of the Settings and set its parameters:
Authentication
The driver authenticates using the OAuth 2.0 Client Credentials flow, as required by the current Oracle Hospitality Integration Platform (OHIP) environments. There is no username/password login: the credentials are supplied through the options below (clientid, clientsecret, applicationkey, enterpriseid) and the driver requests a bearer token from the environment's /oauth/v1/tokens endpoint, refreshing it automatically before it expires.
High Availability
- Shutdown when inactive: defaults to false.
Options
| ID | Default | Values | Description |
|---|---|---|---|
| startupevents | false | true | Generate IO events also during the driver’s start-up phase |
| false | Do not generate IO events during start-up (default) | ||
| clientid | <String> | Opera Cloud client ID from Oracle Hospitality Developer Portal > Environments | |
| clientsecret | <String> | Opera Cloud client secret from Oracle Hospitality Developer Portal > Environments | |
| applicationkey | <String> | Opera Cloud application key from Oracle Hospitality Developer Portal > Applications | |
| enterpriseid | <String> | The Enterprise ID of your Opera Cloud environment, used in the token request. It is usually embedded in the client ID (e.g. the UNAE segment in UNA-UAT-UNAE-...-Client) and is not the same value as the hotel ID | |
| gatewayurl | <String> | The URL of your Opera Cloud environment as shown in Oracle Hospitality Developer Portal | |
| hotelid | <String> | The hotel ID of your Opera Cloud environment as shown in Oracle Hospitality Developer Portal | |
| scope | urn:opc:hgbu:ws:myscopes | <String> | OAuth scope requested when obtaining the token. The default requests all scopes granted to the client and rarely needs to be changed |
| maxtransactions | 9999 | <Int> | Maximum number of transactions that the driver will use in the current calendar month |
Oracle bills the OPERA Cloud REST APIs per API call, on a calendar month cycle, and every call is charged except those answered with a 429, 500, 502, 503 or 504 response. The maxtransactions parameter is the driver's monthly budget of billable calls: set it to the number of transactions included in your OHIP plan (the entry level plan includes 10000, hence the 9999 default).
The driver spreads that budget over the month by itself, so the refresh interval is not configurable. Before every refresh it divides the calls still available by the cost of the last refresh, and spreads the remaining cycles over the time left in the month. A refresh cycle costs one call for the rooms request, one for the business date, one per page of the housekeeping overview (100 rooms per page) and one per page of each of the two reservations requests (200 reservations per page), so a 300 room property typically spends 7 calls per cycle and, with the default maxtransactions, is refreshed about every 31 minutes. A larger property spends more calls per cycle and is therefore refreshed less often for the same budget; raise maxtransactions to refresh more frequently. The interval is clamped between 1 minute and 24 hours, and the current value is published in the requests_interval datapoint. The token requests are billable too, and are counted in the same budget.
The counter resets on the first day of each calendar month (UTC). If the budget is exhausted before then, the driver stops the automatic refresh until the reset, and no longer renews the token by itself.
maxtransactions limits the automatic refresh only. Refreshes requested explicitly by writing the refresh or room.[roomId].refresh datapoints are always carried out, even beyond the budget: these calls are still counted (the counter can read e.g. 10012/9999) and are billed by Oracle. Each of them logs the message <ioserver>: <request> beyond the monthly budget, transactions <used>/<max> and, when the token has expired, renews it first, at the cost of one more call. To keep the bill predictable, size maxtransactions on the expected load and avoid writing refresh from frequent events: room.[roomId].refresh costs a single call.
Datapoints
| ID | Value | R/W | Description |
|---|---|---|---|
| connection | online | R | HSYCO connection socket is open |
| offline | R | HSYCO cannot create the connection socket | |
| businessdate | <String> | R | the current business date of the hotel (ISO YYYY-MM-DD), as reported by Opera Cloud |
| room.[roomId].checkedin | true | R | a guest is currently checked in (in-house) in the room |
| false | R | the room is not currently occupied | |
| room.[roomId].reservedtomorrow | true | R | there is a confirmed arrival for the room on the day after the current business date |
| false | R | no arrival is scheduled for the room on the day after the current business date | |
| room.[roomId].outoforder | true | R | the room has at least one open repair and is therefore out of order |
| false | R | the room has no open repair | |
| room.[roomId].guest | <String> | R | name of the guest currently checked in and occupying the room, formatted as Surname, Given Name (original case preserved). When the room is shared by more than one reservation the names are joined with -. Empty when the room is not occupied, so it clears automatically on check-out |
| room.[roomId].accompany | <String> | R | names of the accompanying guests of the current stay (the profiles attached to the reservation as accompanying guests, without a reservation of their own), formatted and joined as in guest. Empty when there are none or the room is not occupied |
| room.[roomId].checkout.date | <String> | R | check-out (departure) date of the current stay (ISO YYYY-MM-DD). When the room is shared by more than one reservation the farthest date (the one that frees the room) is reported. Empty when the room is not occupied, so it clears automatically on check-out |
| room.[roomId].arrival.date | <String> | R | arrival date (ISO YYYY-MM-DD) of the next reservation due to arrive in the room (status Reserved or Due In, not yet checked in), looking from the current business date to the following 2 days. Empty when no arrival is due in that window |
| room.[roomId].arrival.guest | <String> | R | name of the guest of that reservation, formatted as Surname, Given Name. When more reservations of the room arrive on that same day the names are joined with -. Once the guest is checked in, the name moves to guest |
| room.[roomId].arrival.accompany | <String> | R | names of the accompanying guests of that reservation, formatted and joined as in arrival.guest |
| room.[roomId].arrival.checkout.date | <String> | R | check-out (departure) date of that reservation (ISO YYYY-MM-DD); with more reservations arriving the same day, the farthest one |
| room.[roomId].housekeeping.roomstatus | <String> | R | Current housekeeping status of the room (e.g., Clean, Dirty) |
| room.[roomId].housekeeping.roomstatus.frontofficestatus | <String> | R | Front office status of the room (e.g., Vacant, Occupied) |
| room.[roomId].housekeeping.roomstatus.housekeepingstatus | <String> | R | Housekeeping-side occupancy status of the room (e.g., Vacant, Occupied) |
| room.[roomId].housekeeping.roomstatus.reservationstatus | <String>,...,<String> | R | the reservation status(es) affecting the room today (e.g., Arrival, StayOver, Departure) |
| room.[roomId].housekeeping.roompersons.frontofficepersons | <Int> | R | number of persons in the room according to the front office |
| room.[roomId].housekeeping.roompersons.housekeepingpersons | <Int> | R | number of persons in the room according to housekeeping |
| room.[roomId].roomtype.pseudo | true | R | non-inventory room types not tracked in availability |
| false | R | normal room | |
| room.[roomId].roomtype.housekeeping | true | R | the room type is flagged as a housekeeping room type in Opera Cloud |
| false | R | normal room type | |
| room.[roomId].roomtype | <String> | R | the type of the room |
| room.[roomId].roomtype.roomclass | <String> | R | the class or category of the room |
| room.[roomId].roomid | <String> | R | the unique identifier for the room |
| room.[roomId].connectingrooms.roomid | <String>,...,<String> | R | the ID(s) of any rooms connected to this room |
| room.[roomId].roomfeatures.code | <String>,...,<String> | R | the code(s) for specific features or amenities available in the room |
| room.[roomId].roomoccupancyinfo.laststaydate | <String> | R | the date of the last stay in the room (ISO YYYY-MM-DD) |
| room.[roomId].roomoccupancyinfo.vacantdays | <Int> | R | the number of consecutive days the room has been vacant |
| room.[roomId].smokingpreferencedescription | <String> | R | description of the smoking preference for the room (e.g., Non-Smoking) |
| room.[roomId].smokingpreference | <String> | R | code for the smoking preference (e.g., NS for Non-Smoking) |
| token_refresh_interval | <Int> | R | interval in milliseconds the driver waits between automatic OAuth token refreshes (the token lifetime minus a 5 minute safety margin) |
| refresh | 1 | W | force an immediate refresh of every room (a full cycle); the datapoint resets itself to 0 once the refresh is done. Carried out even beyond the monthly maxtransactions budget, see the note above |
| room.[roomId].refresh | 1 | W | reread the current stay and the upcoming arrival of a single room (guest, accompany, checkout.date, arrival.*) with a single call, instead of a full cycle; the datapoint resets itself to 0 once done. Carried out even beyond the monthly maxtransactions budget, see the note above. If the driver has not completed a full cycle yet, a full cycle is run instead |
| room.[roomId].refreshed | <Long> | R | time (milliseconds since the epoch) at which the last room.[roomId].refresh was completed, whatever its outcome: watch it changing to know when the room datapoints are up to date |
| transactions | x/maxtransactions | R | number of transactions used in the current calendar month / total number of transactions available |
| requests_interval | <Int> | R | interval in milliseconds the driver currently waits between two room status refreshes, recalculated after each refresh from the monthly budget still available |
Room data is collected from three Opera Cloud endpoints. The housekeeping overview provides the status, occupancy and reservation datapoints (including checkedin, outoforder and the housekeeping.* values) for every physical room. The rooms endpoint additionally provides the roomoccupancyinfo.*, connectingrooms.roomid and smokingpreferencedescription datapoints, but only for assignable rooms; as a result these last datapoints are typically not present for rooms that are currently occupied. Pseudo rooms are only returned by the rooms endpoint, and are therefore parsed from it in full. The reservations endpoint is queried twice: the arrivals from the business date to the following 2 days provide the reservedtomorrow flag and the arrival.* datapoints, the reservations currently in-house (including the ones due out on the business date) provide guest, accompany and checkout.date. These values are written alongside the housekeeping datapoints, so they are only reported for rooms present in the housekeeping overview. room.[roomId].refresh reads the same values for a single room, from one search of the reservations of that room.
Release Notes
4.2.0
- initial release
Oracle Opera Cloud is a registered trademark of Oracle