Skip to content

Latest commit

 

History

History
149 lines (104 loc) · 5.64 KB

extensions-howto.md

File metadata and controls

149 lines (104 loc) · 5.64 KB

How to write an extension

Extensions allows you to link alf.io with your existing tools, such as:

  • Billing/Accounting systems
  • CRMs
  • Additional Email marketing services (Mailjet, ...)
  • Custom notifications (Slack, Telegram, etc.)

how it works

Extensions can be added and modified only by the Administrator. For security and stability reasons, it is not possible to do that with less privileged users.

Each extension consists of a JavaScript script, you can find a sample below:

/**
 * The script metadata object describes whether or not your extension should be invoked asynchronously, and which events it supports
 * @returns {{ async: boolean, events: string[] }}
 */
function getScriptMetadata() {
    return {
        async: false,
        events: [
            //supported values:
            //'RESERVATION_CONFIRMED', //fired on reservation confirmation. No results expected.
            //'RESERVATION_EXPIRED', //fired when reservation(s) expired
            //'RESERVATION_CANCELLED', //fired when reservation(s) are cancelled
            //'TICKET_ASSIGNED', //fired on ticket assignment. No results expected.
            //'WAITING_QUEUE_SUBSCRIPTION', //fired on waiting queue subscription. No results expected.
            'INVOICE_GENERATION' //fired on invoice generation. Returns the invoice model.
        ]
    };
}

/**
 * Executes the extension.
 * @param scriptEvent
 * @returns Object
 */
function executeScript(scriptEvent) {
    log.warn('hello from script with event: ' + scriptEvent);
    //this sample calls the https://csrng.net/ website and generates a random invoice number
    var randomNumber = restTemplate.getForObject('https://csrng.net/csrng/csrng.php?min=0&max=100', Java.type('java.util.ArrayList').class)[0].random;
    log.warn('the invoice number will be ' + randomNumber)
    return {
        invoiceNumber: randomNumber
    };
}

each extension is registered to one or more Application Events, and is fired as soon as the Application Event occurs.

Scope Variables

alf.io provides some objects and properties to the script in the script scope:

other event-related variables are also injected in the scope

Supported Application Events

RESERVATION_CONFIRMED

extensions will be invoked asynchronously once a reservation has been confirmed.

params

RESERVATION_EXPIRED

extensions will be invoked synchronously once one or more reservations have expired.

params
  • event: Event
  • reservationIds: String[] - the reservation IDs
expected result type

boolean

RESERVATION_CANCELLED

extensions will be invoked synchronously once one or more reservations have been cancelled.

params
  • event: Event
  • reservationIds: String[] - the reservation IDs
expected result type

boolean

TICKET_ASSIGNED

extensions will be invoked asynchronously once a ticket has been assigned.

params

WAITING_QUEUE_SUBSCRIBED

extensions will be invoked asynchronously once someone subscribes to the waiting queue.

params

INVOICE_GENERATION

extensions will be invoked synchronously while generating an invoice.

params
  • event: Event
  • reservationId: String - the reservation ID
  • email: String - contact email
  • customerName: String
  • userLanguage: String - ISO 639-1 2-letters language code
  • billingAddress: String - the billing Address
  • reservationCost: TotalPrice
  • invoiceRequested: boolean - whether or not the user has requested an invoice or just a receipt
  • vatCountryCode: String - the EU country of business of the customer, if any
  • vatNr: String - Customer's VAT Number
  • vatStatus: VatStatus, see #278
expected result type

InvoiceGeneration - The invoice content, currently limited to the invoice number.

Methods

getScriptMetadata

This methods returns the actual configuration options and capabilities of the extension. It must return a JSON object with the following properties:

  • async boolean: whether or not the script should be invoked asynchronously.
  • events string[]: list of supported events
  • configuration {(key: string): string}: the extension configuration (WIP)

executeScript

the actual event handling. Parameters and return types are event-dependent.