From Jomres v4 manual

External Notifications Plugin

Introduction

The External Notifications plugin allows Jomres to 'push' booking data from Jomres to a remote server. This is distinct from the API functionality which primarily has data pulled from it via an API key.

Why?

The API functionality is useful if you have a remote server that you can access and configure cron jobs to pull information from the Jomres server, or if you want to insert something into the system, however a remote API server would always be thought of as a kind of bridging server between Jomres and a remote system. For a lot of users this is probably overkill for most projects and it requires a 'push' from the remote server, so the information is only passed when it's requested which isn't really 'realtime'.

The external_notification plugin has been written to supply a simpler method of advising remote servers that a booking has been taken in the Jomres system. Incoming notifications would still require a call to the API plugin, this is because incoming calls to our Jomres server still need to be authenticated because they are capable of changing things on the system.

The external_notifications plugin has been written in such a way that intends to allow site managers to send information to a variety of remote servers and not one particular type. Unfortunately there are too many different types of system out there to be able to write specifically for a system, however it is anticipated that our method is sufficiently flexible to send data to most reasonably modern internet aware systems.

How?

Install the external_notifications plugin via the Jomres plugin manager. Once installed you'll have two new buttons in your administrator area called 'External notification profiles' and 'External notification Transactions'.

External notification profiles

Screenshot of the profile configuration page

This page allows us to configure a profile for sending information to remote servers. You can have multiple profiles, going to one or more remote servers. Depending on how much demand for the functionality there is, it is anticipated that we will add the ability to configure profiles so that they can only be triggered when certain properties have bookings made against them, but for now the notifications are triggered regardless of the property that has been booked.

Settings

Profile title

Any title you need that's meaningful to you.

Method

Current choices are 'get' or 'post'. At the time of writing, only 'get' is supported.

Protocol

Either http or https

Url

The url of the domain you are sending the information to. A valid example could be "localhost" or "localhost/test" but you must ensure that there isn't a trailing slash (/).

Script

The name of the script you are calling, for example 'index.php' or 'fred.php'. If the remote server allows or demands further information, for example an API key of it's own, to be attached to the query string, you can add that here so for example 'index.php?password=secret' is also valid.

Our variable names

Must be set.

At the time of writing this information can only be found in j03020insertbooking.class.php however it will be documented on this page later. On line 438 through line 454 you can see the values added to the componentArgs variable, these are all available to the profile when it sends the data.

See the next section for more information.

Outgoing variable names

Must be set

See the next section for more information.

Our variable names and Outgoing variable names

In Jomres our booking information is referred to via certain variables, for example the arrival date is called arrivalDate and is in the YYYY/MM/DD format internally. It may be that the remote server will require that the arrivalDate variable be referred to by some other variable name when it's sent to them such as arr or something similar. You can recast the outgoing variable name from arrivalDate to arr by setting the 'Our variable names' option to 'arrivalDate' and the 'Outgoing variable names' option to 'arr'.

Whatever the remote server's variable name should be, if you want to send data out you must complete both fields. Let's look at the example from the screenshot above :

"Our variable names"

cartnumber,arrivalDate,departureDate,contract_total,xn_customfield

"Outgoing variable names"

booking_number,arrival,departure,grand_total,secretxyz

In this example we're sending 5 distinct sets of information. The cartnumber (i.e. the booking number), the arrival and departure dates, the value of the booking in it's entirety, and a custom field. This is a comma separated list and the first item in "Our variable names" directly corresponds with the first item in "Outgoing variable names", the second, third, fourth and fifth do likewise. It is important that you maintain this correlation.

The fifth example is slightly different. This example shows how we're sending some custom data to go with the Jomres generated data. You might want to use this functionality if for example your remote server needs you to POST an API key or some other data. If external_notification sees that the variable in "Our variable names" starts with "xn_" it'll know that this is some information that you want to pass along that isn't from Jomres. Instead it will remove the "xn_" from the "Our variable names" and put that as one of the outgoing fields, and take the value in "Outgoing variable names" and treat it as the data to be passed.

Note: At the time of writing it's not possible to modify the data that's being output, so for example currently the date will still be sent out in the YYYY/MM/DD format. It is intended, if there is sufficient interest in the plugin's functionality, to add the ability for you to write code that will enable you to modify the data into a format that the remote server will accept.

External notification Transactions

This page lists all of the transactions and the responses passed back by the remote system.

Appendix

The test script

My 'remote server' simulator used during testing is very basic. It simply takes the data passed to it and passes it right back to external_notification.

$sent_data = "";
 
if (count($_POST)>0)
	{
	$sent_data .= "Posted : ";
	foreach ($_POST as $key=>$val)
		{
		$sent_data .= " ".$key." = ".$val." - ";
		}
	}
 
$sent_data .= "Getted : ";
 
foreach ($_GET as $key=>$val)
	{
	$sent_data .= " ".$key." = ".$val." - ";
	}
 
echo $sent_data;

Variables available to external_notification

To do.