Writing Bookings Plugins

Bookings plugins let you insert additional steps into the booking process. They are most commonly used to collect additional information from the person making the booking.

Standard Booking Flow

Without plugins enabled the booking process is the same for all events and users.

1. Find the event you'd like to book
2. Select tickets and enter your name and email address (other options appear here depending on configuration)
3. Either "Book now" (for free events) or be redirected to a payment provider (cash payment options also exist)
4. Receive a confirmation message and email

Pre-Payment Plugin

You can add an additional step to the booking process in between selecting tickets and booking.

This plugin form is used to collect additional information from the person making the booking. Examples include address, the names of attendees, vehicle registration details, dietary requirements or company information.

The Plugin Form

The name of your plugin form needs to be set as the prePaymentForm in the Bookings configuration (see below). Once added, it can be picked from the "Plugins" drop-down when you are scheduling events.

Events that have plugins cause the booking workflow to branch before taking payment:

The plugin form can contain as many fields and pages as you need. It must include a submit button and a "Workflow - Complete Task" action field on the final page.

Once the plugin form has been completed the booker is taken to the normal book/pay form. The success message set in the "Workflow - Complete Task" action field can be displayed on the payment page, although we normally delete the default message and leave it blank.

Remember that Bookings includes a one hour timeout that starts when someone presses the "Book" button of an event and is cancelled when they reach the payment page (when a separate timeout starts). Adding a plugin form doesn't increase this timeout.

Plugin Data in the Event Manifest

If you want your plugin data to be available and downloadable from the Event Manifest you should also include a database save action field with it's label set as as the business key of the booking. This blueprint  (ZIP) [4KB] will get you started.

Booking Management Form

Once a user has made their booking they can track it via the User Requests template. If a bookingManagementForm has been set in the configuration, the Booking Overview form will include a "View additional details" button. This form is optional and you can use pre-payment plugins without it.

This button links to your booking management form via a user task in the workflow:

Your management form could use the same form as the pre-payment plugin - this would let users update the information they supplied. Alternatively you could build a read-only version of the form if details shouldn't be updated. You can display values from the original booking by including form fields with the same names as those in the original form.

The form must include a submit button and complete task action which will return to the Booking Overview.

Event Management Form

This plugin is used by event organisers. It enables the "View additional information" button on the first page of the Occurrence Management form. The button will appear if there's a value for eventManagementForm in the configuration. It is designed to display the information captured by the pre-payment plugin.

goss.BookAndPay.v1.api.getOccurrenceBookersDetails End Point

Note that this End Point is part of the 1.6.7 release

This End Point returns information about the people booked onto an event, including the data entered into your plugin form. form_NAME and form_EMAIL are captured by the standard booking form. The End Point has the following parameters:

You must list the variables you want to return. These will be the names of the fields on your plugin form. Using the example plugin form above:

{
 "variableList": ["form_NAME", "form_REGISTRATION", "form_MAKE", "form_MODEL"],
 "occurrenceBk": "3320-9294-9451-6007"
}

Returns:

"result": {
    "count": 2,
    "list": [{
        "startUserId": "anonymous",
        "startTime": "2020-09-22T10:19:20Z",
        "id": "25916372",
        "businessKey": "8562-7889-1514-4958",
        "processDefinitionName": "Booking v1",
        "processVariables": {
            "form_REGISTRATION": "FG34FGH",
            "form_MAKE": "Nissan",
            "form_MODEL": "Micra",
            "form_NAME": "George"
        },
        "endTime": null,
        "processDefinitionId": "bookingv1:99:25915523"
    }, {
        "startUserId": "anonymous",
        "startTime": "2020-09-22T10:18:43Z",
        "id": "25916177",
        "businessKey": "0405-3793-1256-6724",
        "processDefinitionName": "Booking v1",
        "processVariables": {
            "form_REGISTRATION": "DE12DEF",
            "form_MAKE": "Mini",
            "form_MODEL": "Cooper",
            "form_NAME": "Tom"
        },
        "endTime": null,
        "processDefinitionId": "bookingv1:99:25915523"
    }]
}

Where:

• startUserId - the user who made the booking (anonymous of not logged in)
• startTime - the time the booking was made
• businessKey - the business key of the booking
• processDefinitionName/Id - the name and ID of the booking process
• processVariables - the variables requested (ie the data captured in the plugin form)

Example Form

This example displays the information captured by the plugin form in a table.

The form design includes an HTML template field (to display the data), a submit button (labelled "Close") and a complete task action to return you to the Occurrence Management form.

The template field calls the getOccurrenceBookersDetails End Point via the Manipulation Function. Note the use of helper.getSiteVariable('PROCESSBUSINESSKEY'); to get the business key of the event we are managing:

And displays the result using a Handlebars template:

<table style="width:100%">
    <tr>
        <th>Name</th>
        <th>Make</th>
        <th>Model</th>
        <th>Registration</th>
    </tr>
    {{#each list}}
        <tr>
            <td>{{processVariables.form_NAME}}</td>
            <td>{{processVariables.form_MAKE}}</td>
            <td>{{processVariables.form_MODEL}}</td>
            <td>{{processVariables.form_REGISTRATION}}</td>
        </tr>
    {{/each}}
</table>

Post Payment Workflows

It's possible to start another workflow process once a booking has been made.

In the plugin configuration, enter the process identifier of the workflow you want to start, for example "postPaymentWorkflow": "timsexampleprocess"

The postPaymentWorkflowVars property in the configuration is a list of process variables from the booking you'd like to pass to the new workflow. The default fields/variables collected by Bookings are:

• form_DATA
• form_EMAIL
• form_NAME
• form_TEL

See the Bookings section of Core Product Data Storage for more information.

The business key of the booking is always passed to the new workflow as the value of the BookingBK variable.

If your plugin has a pre-payment form (described above) you can include any values from that in exactly the same way.

In this example two fields from the booking form were passed to the new workflow:

        "postPaymentWorkflow": "timsexampleprocess",
        "postPaymentWorkflowVars": ["form_NAME", "form_EMAIL"],

Which resulted in:

Configuration

The details of each plugin are held as objects in the plugins array in the Bookings Configuration End Point.

config.plugins.push({
    "name": "Tim's plugin form",
    "code": "TGH",
    "prePaymentForm": "TIMSPLUGINFORM",
    "postPaymentWorkflow": "",
    "postPaymentWorkflowVars":  ["form_NAME", "form_EMAIL"],
    "bookingManagementForm": "MANAGETIMSPLUGIN",
    "eventManagementForm": "VIEWTIMSPLUGINDATA"
});