The core Bookings configuration is managed via a single
The
For example, a Bookings configuration end point set up in a development environment will have the namespace
The end point contains the following properties.
Example
There's an example configuration end point you can copy at
Email Links
These links are used in the confirmation email (see Email and Message Template Configuration) and allow the booker to manage their booking.
| Property | Type | Description |
|---|---|---|
| anonymousUpdateUrl | String, optional | Required if |
| bookingOverviewLiveFormId | Integer, optional | Required if |
| userRequestsUrl | String, required | The full URL of a User Requests article that the bookers can access, set up to display the Bookingv1 workflow process |
Core Settings
| Property | Type | Description |
|---|---|---|
| anonymousId | Integer, required | The ID of the site's public/anonymous user. This is needed if you would like users to be able to make bookings without logging in |
| BookingFormDelay | ISO-8601 duration string, required | This setting is used to end the booking workflow if a booking is never made. The booking workflow process uses two forms, chained together as two workflow tasks. The first form lets a user select tickets and enter their contact details. It is this form that is subject to the timeout set here. As soon as a user presses the "Book" button and moves to the payment form, the |
| bookingText | Object, required | One or more named objects holding text overrides for the booking forms. The name of each set of overrides will appear in the drop-down on the form used to create event occurrences. See Bookings Text Overrides for the full list of options and the "Default" set of overrides |
| cashPaymentGroup | String, optional | The name of the website user group who will see the "Paid offline" button on the payment forms. This must be a group of staff users, not members of the public. If enabled, you will also need to set the |
| copyInstance | Boolean, required | true: Event instances can be copied via a task in the Self Service template (generally only used with Contribute Event) false: Event instances cannot be copied and the task will not appear |
| ctmApplication | String, required | The name of the Comms Template Application. If you have followed the standard installation this will be "Book and Pay" |
| discountsEnabled | Boolean, required | Whether or not the discount functionality will be enabled. If false the "apply discount" field will be hidden on the payment forms. If enabled discounts are enabled globally across all events. See also the showDiscountCode setting below |
| discountsUser | String, required | Set an empty string to disable. The name of an iCM user. This user needn't have any privileges or content roots. The user is only used by the discount management form if it is published on the site rather than as an iCM shortcut |
| enableBasket | Boolean, optional | If you have Multiple Payments installed, set this as true to show the "enable basket" option when scheduling events |
| basketArticleID | Integer, required if enableBasket is true | The article ID of the payment basket. See Using the Payment Basket for more information about setting up this article |
| basketProcessDefinition | String, optional | The process definition that should be started, representing the booking while it is in the payment basket. Leave this as an empty string to use the default "order_bookings_item" process |
| enableConfirmEmail | Boolean, required | Default: true. Turns the "confirm email" field on or off on the booking form |
| enableReservations | Boolean, required | Default: false. Set as true to enable Reservations |
| eventLocation | Boolean, required | true: An option to use the event's default address, set in its article extra tab, will appear in the "location" drop-down when creating event instances false: Only articles using the Location template will appear in the list |
| eventTemplate | Integer, required | The ID of the Event template definition |
| finishInstanceGracePeriod | ISO-8601 duration string, required | The time after an occurrence's end time that it will be automatically marked as "complete" (ie if the event organiser doesn't do this manually via the "Manage single occurrence" form) |
| formatDateTime | Object, optional | Used in the "Take booking" and "Manage occurrences" forms to set the date and time formats. If not set dates will appear as Example: { |
| fromAddress | String, optional | The "from" address the emails generated by Bookings should appear to come from. This should always be an address allowed to send from your domain |
| fromName | String, optional | The name emails will appear to come from |
| includeCalendarFile | Boolean, required | Default: true. You will also need to set the |
| includePackages | Boolean, required | true: Tickets and packages (ie the full Bookings functionality) will be enabled. false: Tickets and packages will be disabled. Set false if Bookings is only being used to schedule events with no booking options |
| locationTemplate | Integer, required | The ID of the Location template definition |
| maintenanceMessage | String, optional | If Bookings is put into maintenance mode (using iCM system maintenance), this message will appear on all of the forms. This value can be an i18n token on multilingual sites |
| newInstanceArticleID | Integer, required if using Contribute | A form service article ID that has the "Create new occurrence" form related to it. When creating events via Contribute the "Event default prices" form will redirect to the create occurrence form once it's submitted |
| offlineRefNumber | Boolean, required | If payments made offline require a reference number to be recorded at the time of booking. This setting can be overridden in the occurrence scheduling form. We recommend this is always set to true |
| offlineTypes | Array, required if | An array of offline payment types. If more than one value is included, the payment details form will include a drop-down field with these values in it. "Card" is always an option |
| organiserEmail | String, required if | This will appear in the iCal appointment emailed to bookers |
| organiserName | String, required if | This will appear in the iCal appointment emailed to bookers |
| PaymentFormDelay | ISO-8601 duration string, required | Once a user has made a booking they are immediately taken to the payment form. If no payment is made, the active booking (ie the process instance) remains active and is visible as a "take payment" task in the Self Service (booking overview) template. Bookings in this state have, effectively, reserved tickets in the name of the user. When the duration entered here elapses the booking instance will be cancelled, returning the tickets to the available pool to be booked by other users. If payment is made prior to this time elapsing this value has no effect |
| showDiscountCode | Boolean, optional | Default true. When a booker views their booking, or updates it, any applied discount code will be visible in the read-only summary. Set this property as false to hide the code. You might want to do this if bookings are made by staff members on behalf of users, and those users shouldn't see the code that was applied. This global settings will apply to all bookings |
| ticketCosts | Boolean, required | Set as true to allow ticket costs to be edited separately to packages |
| ticketCostCentres | Array, required | Set an empty array to disable. An array of objects. Each should have an |
| ticketExpenseCodes | Array, required | Set an empty array to disable. An array of objects. Each should have an |
| ticketVatCodes | Array, required | Set an empty array to disable. An array of objects. Each should have an |
| timezone | String, required | Sets the timezone in the "Take booking" and "Take payment" forms. These forms use the moment-timezone.js library. Default: |
| plugins | Array of Objects | Each JSON object represents one plugin. See the final section of Writing Bookings Plugins for more information |
Payment Provider Configuration
The
- Adelante Smart Pay (Multi-Item)
- Capita Paye.net (Pay360)
- Capita SCP (Pay360)
- Capita SCP Multi Item (Pay360)
- Civica
- Civica eStore
- PayPal
- GOV.UK Pay
- Secure Trading Payments
- WorldPay
| Property | Type | Description |
|---|---|---|
| paymentProvider | String | The name of the payment provider that Bookings will link to. The names are defined in the For example, to enable the PayPal provider, enter: config.paymentProvider = PaymentProviders.PAYPAL; |
| staffPaymentProvider | String | The name of the payment provider t ouse if a staff member is interacting with the payment form. Staff members are identified by being members of the |
| enablePaymentReconciliation | Boolean | Only supported by the Civica, Worldpay and Capita SCP Multi-Item payment fields. If true, reconciliation will be enabled. Additional setup and configuration is also required, see below |
| paymentReference | String | An additional reference number that can be saved with the payment |
| providerSettings | JSON Object | The settings for each payment provider are stored as a JSON Object. These are retrieved by the TAKEPAYMENT form and will typically include security keys, IDs and request URLs |
Payment Reconciliation
Several payment provider field types support payment reconciliation. Sites that use these providers follow the same booking and payment steps as other payment providers, but in the background additional calls are made to the payment provider portal to confirm the success of the payment. If the payment is not successful the booked tickets are cancelled.
All website users who need to pay for bookings must be added to a user group called PAYMENT RECONCILIATION for the reconciliation workflow to start.
Overrides
The main Bookings configuration provides a default for all of your events to use (ie they'll all use the same payment provider, the same "from address" etc).
Overrides let you create alternative blocks of configuration, overriding the main settings. Overrides can then be picked when you are The Event Scheduling Form - Scheduling Event Occurrences. Your override doesn't have to duplicate the entire configuration, you can just override a single property if you need to.
The
config.overrides = {
'Example 1': {
paymentProvider: PaymentProviders.ADELANTE,
staffPaymentProvider: PaymentProviders.ADELANTE
}
};
When scheduling an event, the "Config override" drop-down has these options:
It's anticipated that overrides will be used when different organisations/teams/subsites are using a single installation of Bookings and they each need to set up their own events.
