Index

This module implements the integration with the Opera system 'on premise' of the following functionalities:

This module adds a new payment method to the system with the name “(OPERA) Room Charges”. The word 'OPERA' has been added in parentheses to distinguish it from another payment method that is also called “room charges” and that corresponds to the integration with ORACLE OHIP.

This module requires the additional installation of the OPERA-GM local service executable, which is what will actually process the requests to the final OPERA server.

Back to top 👆🏼

The steps to follow are those:

Back to top 👆🏼

We only have two relevant options, the payment method option is under discussion whether
to eliminate it or not. The first is the ip address of the opera server. Normally it will be http://127.0.0.1:8081 but it can be any LOCAL IP address (be careful with local) that
points to a terminal with the Opera Local server running. The port of our local server is 8081.

It is MANDATORY to include the "HTTP://" header or else the connection will fail. The other option determines whether we send the itemized taxes to Opera, or whether we send the totals with taxes included directly.

We must create an API user with administrator permissions from the users section in the configuration and generate an API key for it. Once this key is generated, we must copy and paste it into the configuration file described below, in the "apiKey" property. This is not necessary if the mass billing functionality will not be used.

Opera Subtotals

The module extends a new field to the subfamily table called "operaSubtotalGroupId" of type integer. Opera allows you to use up to 16 different subtotals. As an example, we could have the subfamilies "Restoration-Drinks" and "Restoration-Foods" associated with subtotal "1" and the subfamilies "Store-Accessories" and "Store-Textile" associated with subtotal "2" so that Ópera receives the subtotals grouped in the way the club considers appropriate.

Back to top 👆🏼

Inside the installation directory of the local opera server we find the
config.json file. An example of this is:

"opera": {"address": "127.0.0.1:5001","apiUrl": "http://localhost:8080/demo","apiKey": "4E22FwC9JGytFZF0KFP1G2HypS65YMY2ADfYbEzacQ5CQYQbkcaBJ7vQzZPujqBV","mockAddress": "127. 0.0.1: 5001","sendPaymentsTimer": 600,"sequence": {"date": "2023-10-17T16:24:48+02:00","value": 4},"startingId": 1,"timeout" :30}

​Address : It is the IP address of the OFFICIAL opera server to which our local server
will process the final requests, that is, this is NOT the IP where our local program is installed.

​ApiURL : It is the URL of the club tenant to which the automated and
manual requests for sending payments will be sent. This tenant must have the Opera module installed, obviously.

​ApiKEY : The key generated from the API user with administrator permissions that we configured above. It is only necessary in case synchronization is to be configured.

SendPaymentsTimer : Every how many seconds the local server will try to obtain the billing not sent to Opera and send it to the final server. It is only necessary in case synchronization is to be configured.

Sequence : Required by opera. Used to serialize submitted sales in sequence.

​StartingId : Id of the Sales table from which the server will start looking for unsent lines. It is only necessary in case synchronization is to be configured.

Timeout : Maximum waiting time for requests in seconds. It is only necessary in case synchronization is to be configured.

Back to top 👆🏼

The module adds the "OperaTransaction" table where the results of the transactions will be collected. The model is the following:

OperaTransaction :

{
posCart: int, //OPERA ID of the sales linereservationID: string, //OPERA ID of the reservation roomID: string, //OPERA ID of the room success: boolean, //True or false depending on whether the transaction was ok or notype: int, // (1 -> "payment"; 2-> "refund"; 3->"rejected")*request: json, //JSON OBJECT of the request that was sent to Operaresponse: json, //JSON OBJECT with the response received, if any error was received: string, //Stores a description of the error if any occurred.}

* Internally the field type is integer; However, since it is a list of options, what will be displayed on the screen will be the translatable label. In the case of Spanish, we would see "Payment", "Return" or "Rejected" as appropriate. Payment and return are self-descriptive types. The "Rejected" type is used for cases in which the communication with the local and remote servers has been satisfactory and technically correct, but the final Opera server rejects the operation for some reason. Due to the way the "on premise" pattern works, in these cases we undo the operation on our side and do not save two Opera transactions (one canceling the other) because only one has really occurred; In these cases the transaction will be saved with the type "Rejected".

It is convenient to highlight, especially for the purposes of detecting possible errors or debugging, that room charges from the POS are made using a payment method like any other, in such a way that it will be reflected in the payment line (payment table). what is the transaction model (in our case, the OperaTransaction table) and what is the ID within that table that points to the OperaTransaction line descriptive of the transaction.

Back to top 👆🏼

Regarding the mass billing sending functionality, the
"operaSent" field, of type true or false, has been added to the "invoiceLine" and "sale" models (tables). Let's remember that in v3 "sale" does not group sales lines, but is the sales line itself, which is related and grouped with the id of the cart, or the associated invoice.​

As mentioned above, the field "operaSubtotalGroupId" has been added to the subFamily table. Its reason for being and its functionality are explained above.

Back to top 👆🏼

Once the local Opera server is installed in the default directory or the one we have chosen, we can use the following two commands to start and stop the service respectively: start and stop.

To do this, we must open a Windows command console in ADMINISTRATOR MODE, go to the installation directory and write "start.bat" or "stop.bat" as needed at any given time.

It should be noted that the start command does not "restart" the service but will always try to install it as if it were the first time and it did not exist. The stop command, consequently, not only stops the service, but also uninstalls it and removes it from the list of Windows services.

Once the local server has been configured and the start command has been successfully executed, we can go to the Windows service manager and locate the "OperaLocalServer" service to check its current status. Once the service is correctly installed, from said manager it can be configured so that it starts automatically when you log in to Windows or, on the contrary, manually. Except for advanced users or solutions, it is advisable to leave it on automatic start.

It is also worth highlighting here the importance of having the Windows firewall or any other network traffic monitoring software properly configured to allow incoming and outgoing connections to the PC where the local server is installed. The most common thing is that during the first connection attempt, a Windows firewall window is shown asking us what we want to do. If this is the case, incoming and outgoing traffic must be authorized both internally (which is usually enabled ) and remotely (so that the local server can communicate over the Internet with the final Opera server).

Back to top 👆🏼

The way room charges work is essentially identical in concept to
any other form of payment. Once the module is correctly installed and configured, when we go to the POS and finalize a sale we will have to choose the payment method "(OPERA) Room Charge".

Once this payment method has been chosen, the system will try to connect to the Opera local server, to request it to obtain the list of rooms with their main occupant. If this process has been resolved without incident, a modal window will be shown with a drop-down menu to choose the room to which we want to make the charge. At this precise moment, two possible error situations can occur: that the connection with the local server fails, in which case the following would have to be reviewed:- The status of the service. It should appear in the list of Windows services and be listed as "running." If not, the service must be reinstalled as explained above. - The configuration of the module on the GMV3 side. This configuration is relative TO THE LOCAL SERVER. The one relating to the final remote server is in the config.json file of the local server. Let's remember that you must always head the local server's IP with "http://".

It should be noted that if an error occurs at this time, no transaction will be generated in the module's transaction table. The most common error in these cases will be a TIMEOUT type error in cases where the configuration is formally correct but pointing to the wrong URL, for example, or due to poor URL formation (forgetting the header, misspelled IP addresses, etc.). etc..). In any case, it is worth reviewing what was said.

If the connection to the local server was successful, issues may still occur regarding communication with the final Opera server. These can be classified into two large groups.

​Errors handled by Opera

The communication has been satisfactory, but the final Opera server has
responded to us rejecting the operation for some reason, either due to a defect or error in the data or its form, or due to any policies of the
final Opera server that prevent that the data, although correct in form and type,
can be consolidated. In this case, the corresponding red pop-up should be shown alerting us of the error, containing the short description of the INTERNAL OPERA ERROR that has prevented the consolidation of the charge (or of return). In these cases, the context of the transaction and its information will be saved in the module's transaction table with the type "Rejected" that we already saw above. Due to the "on premise" scheme, at this point, the operation will have already been performed on our side, so the system will be in charge of canceling payments made and not finally accepted by Opera, leaving the unaccepted lines as "pending payment".

​Errors not handled by Opera

It may happen that the GM communication with the local server is good but
the communication between the local and remote Opera servers fails for some reason. The first thing to check is that the URL address of the remote Opera server is correct and that any necessary club/client side Opera configurations are done correctly. However, if everything seems correct, and we are clear that the problem lies at the moment of communication between the local server and the remote one, we can do the following to debug: a) Open a Windows command console in administrator mode. b) Go to the installation directory of the local server. Run the command "stop.bat". This will stop and uninstall the Windows service. c) Run the following command "sim opera.bin" In this way, we will have raised the server again, but not as a service, so that the errors and their traces will be displayed in the window console which can help "limit" or "precise" the error situation to support for cases that ultimately represent a bug and must be reviewed.

​Returns

The return is made as usual at the POS. We will see the
modal window that asks us if we want to return to the same payment method, we will obviously select yes, and if we want to permanently cancel the lines or leave them pending payment just as we have been doing with any other payment method. Regarding to Opera's transaction log and internal functioning, this is very similar to that of charges. It should be noted that in cases where the Opera server rejects the operation, even if it is already valid on our side, a negative payment will be generated on our side, but it will not be reflected as a "return" in the Opera transaction table, but as "rejected."

Back to top 👆🏼

For this functionality to operate correctly, it is necessary that the
server configuration file is correctly configured as detailed above.

Manual sending

Having verified the above, in the view of the sales table
two buttons will have been added after the generic ones and/or that already have the view. The one that interests us now is the "Send to Opera" button, at the moment the automation of this task is not implemented. The operation has no mystery, we press the button and the sales not already marked as sent (through the extended field) operaSent") are attempted to be sent to the local Opera server, so that it finally sends them to the remote Opera server.

​Auto Send

If we do not want to use automatic sending, we must edit the
server configuration file, config.json, in the installation directory and change the value of the sendPaymentsTimer property to zero. Otherwise, if the value of that property in the configuration file is non-zero, the automated sending cycle will simply start according to the parameters indicated in the same configuration.

Back to top 👆🏼

Likewise, so that the local opera server can obtain billing either through manual or automatic flow, multiple endpoints have been implemented on the server side.

The ones that should be mentioned here are those used by the local server: - opera/getPayments.json (GET) - opera/setSalesAsSent.json (POST)​

These two endpoints are authenticated using the user API key that was generated at
configuration time and which must be duly copied to the server configuration file.

In the debugging scenario where we run the server from the command line, it can be checked whether the server is actually passing authentication or not, since with each cycle the result of the operation will be displayed in the console.

Back to top 👆🏼