In this article
Booking process - ConfirmActivityAPI (single reservations)
Booking process - ConfirmGroupActivityAPI (Group reservations)
The web interface should require the client to log on to be able to actually book an appointment, but still be able to view activity types and product descriptions (and promotions). Without login, however, you should keep to a minimum any requests that might put a load on the Business Central back end environment. This would increase the security of the solution and minimize the possibility of fraudulent users putting unnecessary load on the Business Central environment. Therefore, only uploaded images and data can be reviewed without the client login.
Booking process - ConfirmActivityAPI (single reservations)
After the client has logged on as a user, the web user can start the booking process. This includes selecting the activity type and having the option to select the date via calendar.
Note: This process depends on the frontend handling.
This provides a list of products within that activity type with the option to see detailed information and images. No query has been sent to Business Central at this point, all could be working on uploaded data.
The product can then be selected, and the user is provided with a list of available times and prices for each time for the selected product only. This list is the result of a query to Business Central, retrieving time, availability, and price, using the GETAVAILABILITY API.
Depending on how Business Central is set up, this availability list could also include resources and locations. This lets the user select available slots from multiple locations or depending on a specific resource.
Some product types (for example courses and classes) could even return entries for more than 1 day, depending on Business Central setups.
Preferably, this list is uploaded and then used repeatedly within the same session for a specified length of time, to minimize repeated identical requests to the Business Central back end. That, however, is up to the front end logic to handle.
Note: Products may have an option setting to request for No. of persons, Quantity, or Comments that are passed on to the reservation. Prior to the confirmation, this should be requested to the client at the front end when date/time has been selected and the client continues to the booking process.
When a web reservation is confirmed, it can be specified to be Booked Only or Booked and Paid. The following process is then set in motion:
- The reservation as a whole is sent to Business Central, where its goes through the standard confirmation process. If everything is valid, Business Central sends a confirmation email. This would be using the CONFIRMACTIVITY API.
- If, at this point, the reservation fails confirmation and reservation of resources is not fulfilled, the system returns a message to the WEB API to indicate the failing activity, suggesting that the client book a different time.
- If Booked Only was selected, no further processes are performed.
-
If the reservation requires payment, the reservation response to the front end will include (using parameters) all the necessary details for the front end to add the booking to the retail basket: Activity No. (as Order reference), Quantity, Unit Price, Line Discount %, Total Net Amount.
The front end must then create a line in the basket using the above details. and the user can continue the booking process for another activity or add normal retail sales to the basket. NOTE: The API returns the "Order Reference" which must be returned to the Customer Order, "Order reference" field, so the payment/Deposit is processed correctly.
- When the basket is finalized using normal e-commerce payment processes, the sale is sent to the Commerce API, which will then deliver the payment confirmation to the Bookings module, and at that point the booking will be marked as paid. The Order Reference field on the LS Central sales order should include the Order Reference which was provided by the API respond (ConfirmActivity).
- In cases where the client does not finalize the basket or gets a payment refusal or errors, the Bookings reservation will still be in LS Central with the Transaction document payment setting as WEB, but it will not be marked as paid and it will have no document number as reference. A process Business Central can have entries, which have not been finalized within a set period of time, brought to the user’s attention for manual inspection. The process could also be set up to automatically cancel those activity reservations, and the reservations could send an email notification to the client as well.
Reservation Tokens
With Reservation Tokens it is possible to reserve any activity product for a given time (you specify in the activity setup how long the token is valid). By using the GETAVAILABILITYTOKEN API, the front end can reserve a product without further reservation information, and then apply the token as part of the CONFIRMACTIVITY parameters later in the process. Normally, this is done if the reservation process might take a longer time and you want to make sure the availability is kept open for the booking that is being processed. If the token is not used, it will automatically expire and the reserved product is made available for other bookings.
Payment handling
The Activity Setup defines if payments returned to BC using the CREATEORDER eCommerce API will be processed as booking payment (booking is then marked as fully paid), or if the payment is handled as deposit. This process is done by monitoring subscription event (see codeunit Activity Web Support - MonitorIncomingPayment subscriber), which based on the Order Reference in the Customer Order line decides if the line inserted is related to a booking payment. This is why it is very important that the Order Reference field returned by the CONFIRMACTIVITY API is populating the Customer Order line in the eCommerce for LS Central module by the front end basket process. If not populated correctly, the reservation's payment process is not aware of the payments and is not able to link to the related reservation and process payment status on the related activities and reservations.
Additional Items/Charges
By default, when creating activities or reservations using the APIs, the additional charges which are assigned automatically by product association are not applied. You can change this setting in the Activity Setup (see the Web Include Additional Charges field) which specifies the handling. Any management of the additional charges is then done by a specific API for this purpose, SetAdditionalCharges.
The SetAdditonalCharges API has the functionality to insert, edit, or delete additional charges.
Note: If additional charges are managed using this API, the pricing is set by the API caller. Note that inserted Activity Package offers (using the confirm Activity API) will always create the related additional items in the offer, regardless of the Web include Additional Charges setting.
Booking process - ConfirmGroupActivityAPI (Group reservations)
The booking process for group reservations is slightly different than for single reservations.
- Create a group reservation header, using the INSERTGROUPRESERVATION API.
- (Optional) Use the UPDATEGROUPRESERVATION API to modify the group reservation header.
- (Optional) Reserve the related products using the GETAVAILABILITYTOKEN.
Note: This can be done anytime in the process, just prior to the confirmation, and depending on how the front end is designed. - Insert and optionally confirm the Group lines using the CONFIRMGROUPACTIVITY API. If you are using tokens, make sure to populate the token parameter. Repeat step 4 for all your group reservation lines.
If you are not using tokens, the confirmation process will check for availability at this point. - When the last line of the reservation is inserted (see step 4), assign the API parameter to update the reservation status (normally Confirm). This also confirms and creates the related activities or reservations, if step 4 did not confirm each line individually.
We recommend to do this regardless in order to issue emails and tasks related to confirming the group reservation in whole. The API notifies whether the confirmation process was successful and how many activities were created and confirmed.
Reservation Tokens
With Reservation Tokens it is possible to reserve any activity product for a given time (you setup in the activity setup how long the token is valid). By using the GETAVAILABILITYTOKEN API, the front end can reserve a product without further reservation information, and then apply the token as part of the CONFIRMGROUPACTIVITY parameters later in the process. Normally, this is done if the reservation process might take longer time and you want to make sure the availability is kept open for the booking that is being processed. If the token is not used, it will automatically expire and the reserved product made available for other bookings.
Payment handling
The Activity Setup defines if payments returned to BC using the CREATEORDER eCommerce API will be processed as booking payment (booking is then marked as fully paid), or if the payment is handled as deposit. This process is done by monitoring subscription event (see codeunit Activity Web Support - MonitorIncomingPayment subscriber), which based on the Order Reference in the Customer Order line decides if the line inserted is related to a group booking payment. This is why it is very important that the Order Reference field returned by the CONFIRMGROUPACTIVITY API is populating the Customer Order line in the eCommerce for LS Central module by the front end basket process. If not populated correctly then the reservation's payment process is not aware of the payments and is not able to link to the related group reservation and process payment status on the related activities and reservations.