business events v5.0

Opera Hotel Edition

Business Events

Version 5.0 September 2007

BUSINESS EVENTS

OPERA HOTEL EDITION PAGE 2 SEPTEMBER 2007

Copyright 2007 MICROS Systems, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express prior written consent of the publisher. MICROS Systems, Inc. retains the right to update or change the contents of this document without prior notice. MICROS Systems, Inc. assumes no responsibility for the contents of this document.

OPERA is a trademark of MICROS Systems, Inc.

On Oracle and the On Oracle logo are trademarks of Oracle Corporation.

Information in this document is subject to change without notice.

MICROS Systems, Inc. makes no warranty of any kind with regard to this material, including but not limited to the implied warranties of marketability and fitness for a particular purpose.

MICROS Systems, Inc. shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

Document Number:

MICROS Systems, Inc.

Fidelio Technologies Inc.

2640 Golden Gate Parkway, Suite 211

Naples, FL 34105

Voice: (239) 643-7999 / Fax: (239) 643-7911

BUSINESS EVENTS

OPERA HOTEL EDITION PAGE 3 SEPTEMBER 2007

Table of Contents

OVERVIEW.....................................................................................................................................4

EXTERNAL SYSTEM SET-UP ............................................................................................................5

BUSINESS EVENT CONFIGURATION...............................................................................................6 Business Event Setup Screen................................................................................................................ 6 Business Event Setup Edit Screen.......................................................................................................... 7

OUTBOUND MESSAGE FORMAT .......................................................................................................... 10 Dequeing Messages ........................................................................................................................... 10 Sample New Reservation XML Message:............................................................................................... 10 Basic Header Information ................................................................................................................... 10 Data Element Information .................................................................................................................. 11 Inbound Data received by OPERA PMS ................................................................................................. 13 License Codes and Permissions ........................................................................................................... 13 Data Sent from OPERA PMS................................................................................................................ 13

BUSINESS EVENT SYNCHRONIZATION.........................................................................................14 Business Event Synchronization XML Message....................................................................................... 15 Business Events Workflow .................................................................................................................. 16 Business Events Workflow .................................................................................................................. 16 Data Element Tables (Listed at end of this document)............................................................................ 16 Trouble Shooting: ............................................................................................................................. 17

BUSINESS EVENTS

OPERA HOTEL EDITION PAGE 4 September 2007

Overview

Opera Business Events provide third party vendors the ability to extract data on over 2500 configuration combinations on the following Opera modules: Availability, Block, Cashiering, Configuration, Housekeeping, Night Audit, Profile, Rate, and Reservation. In order to begin collecting business event data, an external system or third party license code is required, such as a Micros-Fidelio or third party Central Reservation System, Spa System, or Yield Management system. Once the license code(s) is activated, subscription of business events can commence. In addition to subscribing to the over 2500 module/business event/data element combinations, Business Event setup configuration allows for optional customization of subscribed data by using where clauses to further filter business event data.

Once configuration is complete, only transactions whose modules/data elements/action type combinations are subscribed to will generate a message in Extensible Markup Language (XML) format to the Business Event Out Queue for dequeuing by the third party vendor or external system.

Important Note: This document is a continuous work in progress and new business events, data elements, and action types will continue to be amended over time as the need arises from external systems such as for a central reservation system (CRS). In developing an extract process, third party vendors should modify their code so that in the event a hotel should switch on a business event/data element for the subscriber, that the third party vendors’ dequeue process ignore and not simply stop dequeuing all other messages.

A separate spreadsheet is available for a listing of all available Modules, Business Events, and corresponding Data Elements that an External System may subscribe. When developing the external dequeue process, vendors should use the exact XML tag names to pull the Opera data subscribed to.

As there are over 2500 business event / data element / action type combinations, all third party vendors should carefully review the business event configuration with the hotel before subscribing to business events to ensure that only data required is captured by the third party vendors’ dequeue process.

BUSINESS EVENTS


External System Set-up

External Systems set-up - Path: System Configuration -> Set up- > Business Events ->External Systems

This form will allow the Initial Set-up, Activation, or Deactivation of External Systems.

Publisher Subscribing to other External Systems – Path: System Configuration- > Set up -> Business Events ->External Systems->Publisher->New->select External System and Property. If in a multi property environment, the other External System must be active in order to select.

This area is designed to identify the desire for an External System to receive messages originating from another External System. In order to receive messages for events that originate outside OPERA PMS, this relationship must be established. For example: Property ABC has two External Systems: Yield System (YS) and Central Reservations (CRS).

Scenario of why a Property would set-up a relationship between two External Systems:

If the YS would like to get Business Events that are generated from both OPERA PMS and the CRS. The Publisher would then be set on YS External System. Highlight YS->Publisher->New->select the External System YS would like to receive generated Business Events from (CRS in this scenario)->select a Property->Close

If the CRS would like to receive Business Event messages when the YS sets restrictions or Hurdle Rates. The Publisher would then be on CRS External System. Highlight CRS->Publisher->New->select the External System CRS would like to receive generated Business Events from (YS in this scenario)->select a Property->Close

BUSINESS EVENTS


Business Event Configuration

Three layers or tiers exist in Business Event Set-up. First, there are the Business Event Modules (Availability, Block, Cashiering, Configuration, Housekeeping, Night Audit, Profile, Rate, and Reservation). Within each module there are the actual Business Events (Action Types) that can be subscribed to – New Reservation, Update Reservation, New Profile, etc.. And finally, there are Data Elements corresponding to each Action Type – Room Type, Rate Code, Name, etc.. The Business Events generated are based on a customizable configuration that the business event user determines. The result is a user configurable flow of data that is available for third party vendors to extract (dequeue) from the Opera database on a regular basis.

Note: Business Events subscribed to with no Data Elements attached will generate an XML message with header information only for the Business Event. It is imperative that third party systems carefully consider this before programming their dequeue process from Opera. It is highly suggested that the third party dequeue application is programmed to ignore Modules / Business Events (Action Types) / Data Elements that the hotel may subscribe to but that the data recipient does not recognize. In this way you can insure an uninterrupted process of data flow. To set up Business Events, Data Elements and Where Clauses in the Opera application select System Configuration>Setup>Business Events>Configuration.

Business Event Setup Screen

An External System and Module must be selected before configuring business events. This may be done by entering the name or selecting from the list of values. Modules available include Availability, Block, Cashiering, Configuration, Enrollment, Housekeeping, End of Day, Profile, Rate and Reservation. Select the New/Edit button to select Data Elements and establish Where Clause Conditions.

BUSINESS EVENTS


Search Criteria External System. Select the down arrow to select the external system from a single-select list of values. Module. Select the down arrow to select the module from the single-select list of values.

Grids Business Event. Displays the Business Events that are configured for the External System and Module that are showing in the Search Criteria. Data Element. Displays the Data Elements that are configured for the Business Event, that is part of the External System and Module showing in the Search Criteria.

Button Functions Search. Searches for the criteria that is entered in the External System and Module search criteria fields. Button is inactive until both of the search criteria fields have been selected and filled. New. Adds a new data element for the selected business event. This does not mean that the Business Event that is highlighted is the one that the new data element will be applied to. As seen in the Business Event Setup Edit Screen section below, the Business Event that the data element is applied to is selected from the Business Event list of values. Edit. Edits the selected business event that is highlighted in the Business Event grid. Button is not available when no records are displayed in the grids. Delete. Deletes the selected business event that is highlighted in the Business Event grid. A Yes/No prompt is displayed to confirm deletion of the business event. Button is not available when no records are displayed in the grids. Close. Closes out of the Business Event functionality.

Business Event Setup Edit Screen

BUSINESS EVENTS


Note: This setup will determine the data received in the XML Message. The event items will be sent if at least one of the selected items is changed.

Data Elements can be selected by highlighting one element at a time (and left click) or using the Space Bar. An X will appear next to the Data Elements indicating the selection. The Element Search field is available for searching on a specific data element name. Where Conditions. To configure a Where Condition, select the Condition button on the Business Event Setup screen.

Values for each column on the System Configuration form. Column 1. List of values containing all data elements for the Business event selected. Column 2. The following operators are available for use when setting up Where conditions:

BUSINESS EVENTS


Operator Description Example = Equality test. Checks for equality of two operands. Room Type = 'PM' != Inequality test (i.e., not equals). Checks for

inequality of two operands. Room Type != 'PM'

Like/Not Like Case sensitive, character-string pattern matching with wild cards - to match exactly one character and % to match zero or more characters.

Departure Carrier Code Like 'Delta' (all or part of the word can be entered)

In Selects rows in which the column value is equal to any one of a list.

Departure Carrier Code In 'Delta', 'Northwest', 'American Airlines'

Between Select rows in which the column value is greater than or equal to a and less than or equal to b.

Arrival Estimate Time Between '01-05-00' and '02-01-00'

And To filter more than one column. New Room Type != 'PM And New Reservation Type = 'Due In'

Or To retrieve rows that match either condition. New Room Type != 'PM Or New Reservation Type = 'Due In'

Column 3. Descriptive text may be entered into the text field. Text must be separated using a comma (,) when specifying multiple objects. For example, Delta, Northwest. Column 4. (Not Required) And/Or used for multiple Where Conditions pertaining to one module/data element combination.

Button Functions Add. Select the Add button to configure a new Where Condition. After entering values in the appropriate fields, select the OK button to save the condition. Multiple Where Conditions may be configured by simply continuing these steps. Update. Highlight the condition you wish to modify and make the appropriate changes. Select the Update button and OK to save these changes. Delete. Highlight the condition you wish to delete and select the Delete button. Multiple Where Conditions can be deleted at one time by marking the conditions with an ‘X’ and then selecting Delete.

Note: Where Conditions should be constructed with the understanding that if the conditions are met that a message will be triggered.

Example: The result of this condition would be to send reservations that have a block code of Test Block.

Data Element

Operator Descriptive Text And/Or

Block Code = Test Block When the business event set-up is complete and all of the above assumptions are met, messaging will begin. Messages will be sent to the business event queue for retrieval from the External System.

Note: Business Events (also referred to as a trigger) will only be sent and contain the specific data elements established during set up.

BUSINESS EVENTS


Outbound Message Format Once Business Events configuration is complete, the Opera database is ready to generate outbound messages in XML format. This data will be sent to the Out Queue. External systems will dequeue data from this Out Queue. The content of the API messages dequeued will be contingent on the subscription to Business Events and Data Elements. The configured “Where” clauses will also be taken into consideration, if established to filter by additional conditions. Each time an action takes place; a Business Event is triggered including all data elements that were subscribed to in setup. It is imperative the subscribing third party vendors be mindful of how the data is extracted from the dequeue process as the data listed in the Data Element tables below will continue to grow over time.

Dequeing Messages Special Characters: In order to have the capability to parse the output of messages containing special characters (for example, foreign language correspondence), the client PC that dequeues should have the same NLS_LANG registry setting as the database. If multiple Oracle Homes exist, then all the Oracle Homes should have the same NLS_LANG configured as above.

Sample New Reservation XML Message: iResult : 0 No wait iResult : 0 length(vEvent) : 7728 <?xml version="1.0"?> <BusinessEvent eventType="RESERVATION" action="NEW RESERVATION" eventState="STANDARD"> <HotelReference> <hotelCode>Fiesta Hotel</hotelCode> </HotelReference> <key>10833</key> <creationDate>2001-08-10T13:27:02.000</creationDate> <business Date>2001-08-01T16:15:09.000</businessDate> <Name dataType="string"> <newValue>Ted Johnson</newValue> <oldValue></oldValue> </Name> <ConfirmationNo dataType="string"> <newValue>10873</newValue> <oldValue></oldValue> </ConfirmationNo> <CompanyName dataType="string"> <newValue>The World Corporation</newValue> <oldValue></oldValue> </CompanyName> <GroupName dataType="string"> <newValue>EXPO Convention</newValue> <oldValue></oldValue>

Basic Header Information Business Event Type. Module (Example: Reservations). Action. Business Event Title (Example: New Reservation).

BUSINESS EVENTS


Property Reference. Property code usually defined in 3 or 4 characters though could be up to 20. Key. Internal numeric identifier. Creation Date. Date and time event was created.

Data Element Information Data Element. Name of data element. Begin Scope. Beginning of the date scope for this element. End Scope. Ending of the date scope for this element. Old Value. Value prior to this Business Event. New Value. New Value (current as of this event).

Note: When changing a status of Out of Order or Out of Service, a business event will be triggered for both the new room status and the previous status. This is done because if a property is not subscribed to both the Out of Order and Out of Service business events and only one, then if the room status is changed to the other, the business event will not be triggered and the external system would never know that the room status had been updated.

API extension in business_event_ext

New initialization function Function InitSettings (vExtSystem in varchar2, boShowOld in boolean default False, boIgnoreNull in boolean default True) return integer; Procedure QuerySettings (vExtSystem out varchar2, boShowOld out boolean, boIgnoreNull out boolean);

Dequeue function Function get_event_XML out_event out varchar2, --size limitations? in_wait_mode in varchar2 default 'FOREVER', in_commit_inside in varchar2 default 'Y') return integer; This procedure should delete the records of the dequeued message from business_events table once it successfully delivered the xml string. The parameter in_commit_inside will always be passed as ‘N’ when it is across the instance of the database.

Remarks: Function InitSettings: Needs to check if the given resort id is valid, if the given external system id is valid; if the given values are valid stores the values in the global variables; needs to call pms_init ? Store result in iInitStatus

BUSINESS EVENTS


Returncodes 0 OK / given values valid -2 Resort id unknown, store NULL in sResort -3 External system unknown, store NULL sExternalSystem -4 PMS initialization failed? -99 unknown error initialization failed Procedure QuerySettings: To check the actual settings Function get_event_XML: get next event from BE queue as XML string, if the dequeue and the formatting as XML was successful, then delete the BE from the BE table(s)/queue. No multiple dequeue of the same event! Check iInitStatus if successfully initialized Returncodes 0 OK, out_event contains XML formatted event -1 InitSettings not called / Initialization invalid -2 request timed out no event available (out_event null) -99 unknown error, dequeue failed (out_event -> error msg) Example: Declare vResort varchar2(20) := ‘FDH’; vExtSystem varchar2(20) := ‘OPUS2’; vEvent varchar2(32000); boShowOld boolean := True; boIgnoreNull boolean := False; iResult integer; begin iResult := Business_Event_Ext.InitSettings (vResort, vExtSystem, boShowOld, boIgnoreNull); if iResult=0 then loop iResult := Business_Event_Ext.Get_Event_XML(vEvent, null, null) if iResult=0 then -- call logic to send / store / process XML else -- call logic to handle / log return code Exit; end if; end loop; else -- call logic to handle / log return code end if; end;

Part I I External system -> OPERA PMS

Package : pms_p PROCEDURE initialize(in_user IN VARCHAR2, in_password IN VARCHAR2, in_resort IN VARCHAR2 DEFAULT NULL, in_business_date in date default null) in_user ---'XXXXX' in_password = '$$$XXXXX$$' in_resort = 'FDH' in_business_date --null. Note: X’s represent user and password established for your company. Note: The external system needs to call this initialization routine every time they login into PMS system.

BUSINESS EVENTS


Inbound Data received by OPERA PMS Data sent to Opera from a yield third party vendor is done using an application program interface (API) to communicate, and a data string to transmit values. This data will be received in the Business Event Queue in the Opera application. Hurdle rate information submitted to Opera will be submitted in local currency as defined in Configuration>Property>Property Details (See Property Details for more information).

License Codes and Permissions

Requirements for using Business Events are:

Business Event License Code or other pre-defined License Code

Data Sent from OPERA PMS The processing of the XML messages retrieved from the business event queue should not be done on the Opera servers as it could impact performance and disk utilization on these systems. All code to retrieve, parse, manipulate, or interpret the business event messages is the responsibility of the vendor and the vendor systems. This task can be completed by the vendor and vendor systems with, for example, Oracle ODBL, JDBC, or SQLNET, to name a few.

Note: Purging Data - The Business Event Queue will purge messages that are 96 hours old. This job will be triggered by night audit in PMS. Data will not be purged UNTIL the End of Day routine is completed in Opera; therefore it is feasible to accumulate data beyond the 96-hour threshold as in the case of a new install not running the night audit for more than 96-hours.

BUSINESS EVENTS


Business Event Synchronization

This functionality is accessible by accessing the separate Utilities module>select the Synchronize Utilities drop down menu >select Business Event Synchronization. The display of the Business Event Synchronization menu option is dependent on the license code being activated for either generic business events or an External System existing in the Property.

Business Event Synchronization provides the user with the ability to capture or recapture past Business Event data. The following Opera modules offer data synchronization:

Reservations

Blocks

Profiles

Availability

Night Audit

Rates

Profiles History

Configuration

With the exception of Profiles History, all the above are standard modules in Business Event Setup. Data synchronization is dependent on the subscription of Business Events and Data Elements within each module. Profiles History consists of stored reservation history records from a legacy system that has migrated to Opera and is stored in the Reservation History table. This is assuming data migration took place.

Upon entry to the Business Event Synchronization menu, a message will display to warn the user of the affect this will have on the Opera application. This is a warning message only. The message display reads as follows:

“Please ensure all users are logged out of Opera. This process will cause a slowdown of the application and large amounts of data to be placed in the action logs.”

To capture messages generated by the Business Event Synchronization, the Business Events Processor must be running. Select the appropriate External System from the drop-down menu. Check the appropriate Business Event Module(s) that the data is being requested for and enter the corresponding dates for the data being requested. Multiple modules can be selected at a time. The generated XML messages will be sent in the standard format and can be dequeued in the normal manner. The messages sent to the Out Queue will be grouped per Module. For instance, if Reservations and Availability Resynchronization was run, first all Reservation messages will be generated and then Availability messages will be generated.

BUSINESS EVENTS


Note: As synchronized data can carry a high volume of transactions, it is essential that this utility is executed during off peak processing, when limited access can be restricted to Opera so as to not adversely affect system performance. In addition it should be noted that due to the nature of the amount of data being passed between the systems, it is essential that archive logs are constantly being monitored and that sufficient space exists.

Business Event Synchronization XML Message In order to differentiate synchronized and standard data, the eventState ‘SYNC’ has been added to the XML header message.

Below is sample of the Business Event Synchronization XML message with the eventState = ‘SYNC’.

iResult : 0 No wait iResult : 0 length(vEvent) : 7184 <?xml version="1.0"?> <BusinessEvent eventType="RESERVATION" action="UPDATE RESERVATION" eventState="SYNC"> <HotelReference> <hotelCode>FDH</hotelCode> </HotelReference>

BUSINESS EVENTS


<key>10460</key> <creationDate>2001-08-07T13:59:26.000</creationDate> <businessDate>2001-07-24T13:42:20.000</businessDate> <Name dataType="string"> <newValue>Johnson</newValue> <oldValue>Johnson</oldValue> </Name> <ConfirmationNo dataType="string"> <newValue>10480</newValue> <oldValue>10480</oldValue> </ConfirmationNo> <TravelAgentName dataType="string"> <newValue>Seven Seas Travel</newValue> <oldValue>Seven Seas Travel</oldValue> </TravelAgentName> <CompanyName dataType="string"> <newValue>Atlas Corporation</newValue> <oldValue>Atlas Corporation</oldValue> </CompanyName>

Note: Non-synchronized business events will continue to display the eventState = ‘STANDARD’.

Business Events Workflow The following diagram describes the flow of Business Events data from the Opera PMS database. Only data subscribed to in Setup>System Configuration>Setup>Business Events>Configuration will be available to retrieve (dequeue) from the Opera PMS database.

Business Events Workflow

Data Element Tables (Listed at end of this document) The Data Element tables representing the eight Business Event modules maintained in Opera PMS are listed below. Each of the eight tables is comprised of the following:

Module (Availability, Block, Cashiering, Configuration, Housekeeping, Night Audit, Profile, Reservation, Rate)

Data Element.

Tag Name (data element tag from the XML messages).

BUSINESS EVENTS


Data Type (N = Number, C = Character, D = Date, and T= Time).

Action Types (Action Types for each module are located to the right of the Data Type column).

Trouble Shooting: In Queue:

To delete subscriptions from the backend – must do in the following order due to child/parent relationships

BEGIN

DELETE FROM ACTION_TYPE_SUBSCRIPTION_WHERE WHERE EXT_SYSTEM_CODE = 'FTCRS';

DELETE FROM ACTION_TYPE_SUBSCRIPTION_DTLS WHERE EXT_SYSTEM_CODE = 'FTCRS';

DELETE FROM ACTION_TYPE_SUBSCRIPTION WHERE EXT_SYSTEM_CODE = 'FTCRS';

COMMIT;

END;

business events v5.0

Documents

trademark of micros

opera pms

business event configuration

business event synchronization

business event setup

document number

data element information

oracle logo