rXg with OPERA Cloud (OHIP) PMS integration

Introduction

Most hospitality deployments require the network to know who is staying in which room. Guests expect to join the wireless network by entering their room number and surname, charges raised on the network need to reach the guest folio, and access should end when the guest checks out. All of that depends on the gateway holding a current picture of the property’s reservations, and that picture comes from the property management system.

Oracle’s OPERA is the most widely deployed property management system in the industry. Older OPERA deployments were on-premise and integrated over a private socket protocol. Current OPERA deployments are cloud-hosted, and integration happens over an HTTPS API rather than a socket. This article covers connecting an rXg to a cloud-hosted OPERA property, what has to happen on the Oracle side before the rXg can be configured at all, and how to confirm the integration is working.

This article was written against rXg build 16.676. Check for a newer build before following it, as scaffold layouts and field names occasionally change.

OHIP and OPERA Cloud are the same interface

The most common question about this integration is whether OHIP and OPERA Cloud are two different things, and whether the rXg supports one, the other, or both.

They are the same thing. OHIP, the Oracle Hospitality Integration Platform, is the API gateway Oracle places in front of OPERA Cloud. Selecting OPERA Cloud as the interface on the rXg is selecting the OHIP integration. There is no separate OHIP option to look for, and its absence does not mean OHIP is unsupported.

The rXg speaks OHIP REST endpoints directly, requesting an OAuth2 token and then calling the reservation, room and charge endpoints. The token request carries the x-app-key header; every subsequent data request carries both x-app-key and x-hotelid.

Before you begin: Oracle-side prerequisites

Nothing can be entered into the rXg until Oracle has issued credentials, and obtaining them requires work from both the network provider and the property. This is where most deployments stall, so it is worth understanding the split before starting.

The network provider registers the application with Oracle. The property does not register anything. However, registering an application does not by itself grant access to any hotel — Oracle will not entitle a property just because an integrator asks for it. Several steps must come from the hotel or chain.

• Register the application. Network provider, in Oracle’s Partner Developer Portal. Partners self-register, and a single registered application can serve many properties.
• Request production access for that application. Network provider. See the subsection below.
• Provide the property details. Property or chain. Oracle needs the Enterprise ID, Chain Code, Hotel ID, Region, and SSD Identity Manager URL.
• Onboard the customer environment. Network provider together with Oracle, using the details above.
• Create the integration user in the customer’s tenancy. Network provider.
• Approve the integration user. Property or chain administrator. This step is frequently missed and blocks everything after it.
• Enter the resulting credentials in the rXg. Network provider.

Two points are worth raising with the property directly, because they are common sources of delay.

Properties sometimes decline to share their Enterprise ID, Chain Code, Hotel ID, Region and SSD URL, treating them as sensitive. Oracle’s own documentation states that these values contain no personally identifiable information and that it is appropriate to share them with an integration vendor. They are required for onboarding and cannot be worked around.

Credentials — Client ID, Client Secret and Application Key — only become retrievable after the customer environment onboarding has completed. If the portal shows no credentials, onboarding is not finished; this is expected rather than a fault.

Requesting production access

Production and non-production are separate application registrations. A non-production application cannot call production, and a production application cannot call non-production.

Non-production needs nothing beyond the Partner Developer Portal registration itself: no Oracle Partner Network membership, no Marketplace listing, no cost. This is the right starting point. Validate the integration against the property’s UAT environment first, then move to production once rooms, guest lookups and any charge posting are confirmed working.

Production carries prerequisites that sit entirely with Oracle and take time to satisfy:

• Join Oracle Partner Network at Level 0 — the digit zero, not the letter — which is an annual paid subscription.
• Publish the solution to the Oracle Cloud Marketplace under the OHIP product category.
• Notify Oracle that the listing exists.
• Register a separate production application, choosing Production as the environment.

The first three are per-partner rather than per-property; once done, later integrations reuse them. Oracle owns this process and has changed the final notification step before, so treat Oracle’s Partners Moving to Production documentation as the authority, and follow whatever the Partner Developer Portal shows you at the point of registration rather than any contact address reproduced elsewhere.

Integration users are scoped to a single OPERA tenant. Serving properties across more than one chain requires a separate integration user per chain; multiple hotels within a single chain can share one.

What this costs

Oracle bills OHIP to whoever registered the application — the network provider — rather than to the property. This surprises people, so price it before committing to a deployment. There are two components.

The first is Oracle Partner Network membership, an annual subscription required only for production. Non-production carries no membership cost.

The second is API traffic, billed per transaction, where a transaction is a single call through the OHIP gateway. Oracle publishes the rate on its storefront and bills monthly in arrears against actual usage, so there is no commitment to estimate against up front.

What drives the count is the two-minute background synchronisation, which runs at a fixed interval regardless of property size. Because the interval is fixed, cost per room falls as the property gets larger, and occupancy and turnover matter more than room count alone: both determine how many reservations each cycle returns and therefore how many pages of two hundred it has to fetch. Charge postings add one call each and are usually a small fraction of the total. Guest logins perform a live room inquiry and so add calls of their own, though the background synchronisation still dominates.

Oracle sets these rates and changes them. Confirm the current figures on Oracle’s storefront, and treat the first month’s actual bill as the real estimate rather than budgeting from any figure quoted second-hand.

Configuring the PMS Server in the rXg

Browse to 'Billing::Gateways::PMS Servers' and create a new record.

Set Interface to OPERA Cloud. The form contains a subgroup titled “OPERA Cloud (OAuth2 Client Credentials)”, and it is collapsed. Selecting the interface does not open it for you, so click to expand it; it is easy to miss.

The configuration is spread over three parts of the form, which is worth getting straight before filling anything in. Name sits on its own at the top. The Interface Specification and Web Service groups are open by default and hold, respectively, Interface, Transport protocol, Host, Port, Timeout and Database synchronization; and URL, Username/APIkey and Password. The nine fields specific to this integration — App Key, Client ID, Client Password, Enterprise ID, Scope, Auth Mode, Hotel ID, Cashier ID and Transaction Code — are in the collapsed OPERA Cloud (OAuth2 Client Credentials) group.

A new record is not a blank form. It arrives prefilled for a different interface: Interface itself defaults to MICROS HTNG, Host and URL both point at operademo3.microsdc.us, Username/APIkey and Password both contain HTNG, and Transaction Code in the OPERA Cloud group contains 3010. Each of these needs replacing. Leaving the HTNG credentials in place is a common cause of the token-request failure described under Troubleshooting.

At the top of the form, and in the Web Service group:

• “Name” — any label meaningful to you. It must be unique on the gateway.
• “URL” — the OHIP gateway URL supplied by Oracle for your region.
• “Username/APIkey” — the OAuth Client ID. Despite the name, this is not a user account; it is sent as HTTP basic authentication when requesting a token.
• “Password” — the OAuth Client Secret, paired with the field above.

In the Interface Specification group:

• “Host” and “Port” — required by the form, and Host is validated as an IP address or resolvable domain name, but neither is used by this interface. The integration calls the address in “URL”. Setting Host to the hostname from that URL and Port to 443 keeps the record self-consistent.
• “Timeout” — how long to wait for a response from Oracle, in seconds. Valid values are 1 to 60, and the field arrives prefilled with 30. Leaving it unchanged suits most deployments.
• “Database synchronization” — arrives ticked, and has no effect here. It belongs to the socket-based interfaces, where it sends a resync message after connect. It neither starts nor influences the synchronisation described below.

In the collapsed OPERA Cloud (OAuth2 Client Credentials) group, in the order the form presents them:

• “App Key” — the Application Key from your registered application. Sent as the x-app-key header on every request.
• “Client ID” and “Client Password” — used by SSD mode only. Leave both empty when using OCIM.
• “Enterprise ID” — supplied by the property. Used in OCIM mode only.
• “Scope” — leave blank unless Oracle told you otherwise. Blank applies the default scope.
• “Auth Mode” — OCIM or SSD. Choose OCIM unless you were specifically issued Shared Security Domain credentials. See below.
• “Hotel ID” — the property code, sent as the x-hotelid header. Enter it exactly as Oracle provided it, including letter case.
• “Cashier ID” and “Transaction Code” — required only if you intend to post charges to guest folios. The form carries a second pair of fields with these same two labels outside this group, belonging to other interfaces; the OPERA Cloud integration reads only the pair inside its own group. See “Charge posting” below.

The single most common configuration error is putting the OAuth credentials in the wrong pair of fields. In OCIM mode, the Client ID and Client Secret issued by Oracle go in “Username/APIkey” and “Password”. The separate “Client ID” and “Client Password” fields are used only by the older SSD authentication mode and must be left empty. Credentials placed in the wrong pair fail at the token request, before any data is exchanged.

Two authentication modes are offered:

• OCIM uses an OAuth2 client credentials grant. This is the current mode and the one to use for new deployments.
• SSD uses a legacy password grant against Oracle’s Shared Security Domain. It is retained for backward compatibility with older registrations.

One further point on scope. An rXg holds exactly one PMS Server record — a second cannot be created — and therefore one interface and one Hotel ID. A gateway cannot serve several properties through separate OPERA interfaces. Deployments covering multiple properties need either one gateway per property or a different design.

Starting the initial sync

Saving the record does not by itself populate the gateway. Use the Restart Interface action to trigger the initial sync. It sits in the toolbar at the top of the PMS Servers scaffold, alongside Columns, Refresh and Create New, rather than on the record itself.

The initial sync imports the property’s rooms first, then guests currently in house, then same-day departures.

Rooms and reservations are retrieved differently, and both have ceilings worth knowing before a large property is brought up. Rooms are fetched in a single request for up to one thousand physical rooms, with no paging, so a property with more rooms than that imports only part of its inventory. Reservations are paged two hundred at a time up to an offset of five thousand, at which point the sync stops and records in the log that it short-circuited. Neither ceiling raises an error in the interface; the symptom is a room or guest list that is quietly short.

The room import only adds. Rooms that disappear from OPERA are not removed from the rXg, so a room list that looks too long after a renumbering is expected rather than a fault.

After the initial sync completes, the gateway keeps itself current with a background synchronisation that runs every two minutes, and reconciles checkouts over a four day look-back so that late or amended departures are not missed.

Between synchronisation runs the gateway also performs a live room lookup when a guest attempts to log in, so somebody who checked in moments ago can authenticate immediately rather than waiting for the next cycle.

Verifying the integration

Three scaffolds on the same Gateways view populate from the synchronisation and together confirm whether it is working.

• 'Billing::Gateways::Rooms' fills once the room import completes.
• 'Billing::Gateways::PMS Guests' fills once in-house guests are retrieved.
• 'Billing::Gateways::Guest Matches' records attempts to match a guest logging in against a reservation.

The split between the first two is a useful diagnostic. If Rooms populates but Guests remains empty, the gateway URL and credentials are correct and authentication succeeded — the problem lies with reservation scope or the Hotel ID rather than with the connection.

Charge posting

If the deployment sells network services to the guest folio, the integration can post charges to Oracle. This requires the “Cashier ID” and “Transaction Code” fields inside the OPERA Cloud subgroup to be completed with values the property provides. The identically labelled pair outside the subgroup belongs to other interfaces and is not read here.

The gateway honours no-post and prepaid restrictions set on the reservation in OPERA. Where a reservation does not permit charge posting, the gateway will not attempt it.

Where a charge cannot be delivered, it is buffered rather than discarded and retried according to the general PMS buffering settings on the same record. Duplicate charge suppression is likewise governed by the general settings rather than by anything OPERA-specific.

Migrating from MICROS FIAS

Properties moving from an on-premise OPERA installation to OPERA Cloud are also moving from the MICROS FIAS interface to this one, and the two are not variations of the same configuration.

FIAS is a persistent socket connection to an interface box on the property network. OPERA Cloud is an outbound HTTPS connection from the gateway to Oracle. The firewall implications differ: FIAS requires reachability to a device on the local network, whereas OPERA Cloud requires outbound HTTPS to Oracle’s gateway.

The FIAS-specific fields on the PMS Server record do not carry over, as they describe framing on the socket protocol and have no equivalent in the API.

An rXg holds exactly one PMS Server record, so the OPERA Cloud interface cannot be stood up alongside the existing FIAS one. Either change the Interface field on the existing record to OPERA Cloud, or delete the FIAS record and create a fresh one. An attempt to create a second record is rejected with “A PMS server configuration already exists - currently only one server is supported”. Plan the changeover accordingly: there is no window in which both interfaces run.

Troubleshooting

Start with the log. The integration writes to /space/rxg/console/log/pms_webservice.log, recording authentication failures, the number of records retrieved per synchronisation, and paging offsets. This is the first place to look and usually identifies the failure without further investigation.

Authentication fails at the token request. Confirm the Auth Mode matches the type of credentials issued. OCIM credentials used in SSD mode, or the reverse, fail at the token endpoint before any data is requested. Confirm also that the Client ID and Secret are in “Username/APIkey” and “Password” rather than in the SSD-only fields.

Authentication succeeds but no data arrives. The integration user may not have been approved, and it is the property’s chain administrator who has to approve it. Under SSD this can be confirmed directly: sign in to the Shared Security Domain identity server as the integration user, open the “My Access” tab, and look for the <Tenant>-WSACCESS role. If that role is absent, the user has been created but not approved. Under OCIM there is no equivalent role to check — confirm approval from the customer environment’s status in the Partner Developer Portal instead.

Nothing works and credentials appear correct. Confirm the application registration matches the environment being called. A non-production application cannot call production, and the two are separate registrations with separate credentials.

Nothing happens at all after a restart, or the log reports unknown auth req type. One of the OPERA Cloud fields is empty. Unlike most of this form, the fields in the OPERA Cloud group are not checked when the record is saved: a record with a blank Auth Mode, URL, App Key or Hotel ID saves cleanly and then fails on the first request. Re-open the group and confirm every field it needs is populated.

The room or guest list is short. The log records both the total OPERA reported and the number actually retrieved for each synchronisation. A gap between the two identifies a truncated import rather than missing reservations — see the ceilings described under “Starting the initial sync”.

The log reports a certificate error. The gateway validates the TLS certificate presented by the address in the URL field. It checks both that the certificate is trusted and that the hostname in the URL matches a name on the certificate. Against Oracle’s production gateway this does not arise. It does arise when the interface is pointed at a test or staging endpoint using a self-signed or mismatched certificate, where the log shows either “certificate verify failed” or “hostname does not match the server certificate”. The address entered in the URL field must match a name on the certificate that endpoint presents.

Rooms populate but guests do not. Check the Hotel ID, including its letter case, exactly as Oracle supplied it. Property codes have been observed to be case sensitive on related integrations, so this is worth eliminating early.