Skip to content

Latest commit

 

History

History
247 lines (163 loc) · 10.2 KB

README.md

File metadata and controls

247 lines (163 loc) · 10.2 KB
Raw

Alf.io extensions

this repository contains all the official alf.io extensions

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 {
        id: 'myExtensionIdentifier', // optional: id and version will be used later as a mechanism for checking if the script has a newer version
        displayName: 'My Extension', //mandatory: the name displayed in the configuration page
        version: 0, // optional
        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_CANCELLED', //fired when ticket(s) (but not the entire reservation) are cancelled
            //'TICKET_ASSIGNED', //fired on ticket assignment. No results expected.
            //'TICKET_CHECKED_IN', //fired when a ticket has been checked in. No results expected.
            //'TICKET_REVERT_CHECKED_IN', //fired when a ticket has been reverted from the checked in status. No results expected.
            //'WAITING_QUEUE_SUBSCRIPTION', //fired on waiting queue subscription. No results expected.
            //'STUCK_RESERVATIONS', //fired when the system has detected stuck reservations. No results expected.
            //'OFFLINE_RESERVATIONS_WILL_EXPIRE', //fired when an offline reservation will expire. No results expected.
            //'EVENT_CREATED', //fired when an event has been created. Return boolean for synchronous variant, no results expected for the asynchronous one.
            //'EVENT_STATUS_CHANGE', //fired when an event status has changed (normally, from DRAFT to PUBLIC). Return boolean for synchronous variant, no results expected for the asynchronous one.
            'INVOICE_GENERATION' //, //fired on invoice generation. Returns the invoice model.
            //'TAX_ID_NUMBER_VALIDATION' //fired in case a TAX ID (VAT/GST) Number has to be formally validated
        ]
        //,
        //parameters: {fields: [{name:'name',description:'description',type:'TEXT',required:true}], configurationLevels: ['SYSTEM', 'ORGANIZATION', 'EVENT']} //parameters
    };
}

/**
 * Executes the extension.
 * @param scriptEvent
 * @returns Object
 */
function executeScript(scriptEvent) {
    log.warn('hello from script with event: ' + scriptEvent);
    log.warn('extension parameters are: ' + extensionParameters);
    //this sample calls the https://csrng.net/ website and generates a random invoice number
    var randomNumber = simpleHttpClient.get('https://csrng.net/csrng/csrng.php?min=0&max=100').getJsonBody()[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:

  • log Log4j logger
  • extensionLogger a logger that write in the extension_log table. It implement the ExtensionLogger interface.
  • httpClient instance of a OkHttpClient
  • simpleHttpClient instance of a SimpleHttpClient
  • GSON Google's JSON parser/generator
  • returnClass java.lang.Class<?> the expected result type
  • extensionParameters a map containing the parameters of an extension
  • event: Event
  • eventId: event id
  • organizationId: organization id
  • Utils: various utilities, see ExtensionUtils

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.

additional global variables

RESERVATION_EXPIRED

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

additional global variables
  • reservationIds: String[] - the reservation IDs
expected result type

boolean

RESERVATION_CANCELLED

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

additional global variables
  • reservationIds: String[] - the reservation IDs
  • reservations: TicketReservation[] - the TicketReservations
expected result type

boolean

TICKET_CANCELLED

extension will be invoked synchronously once one or more tickets (but not the entire reservation at once) have been cancelled

additional global variables
  • ticketUUIDs: String[] - the cancelled tickets UUIDs. Please note that once a ticket has been cancelled, its UUID is reset.

TICKET_ASSIGNED

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

additional global variables

TICKET_CHECKED_IN

extensions will be invoked asynchronously once a ticket has been checked in.

additional global variables

TICKET_REVERT_CHECKED_IN

extensions will be invoked asynchronously once a ticket has been reverted from the checked in status.

additional global variables

WAITING_QUEUE_SUBSCRIBED

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

additional global variables

INVOICE_GENERATION

extensions will be invoked synchronously while generating an invoice.

additional global variables
  • 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.

TAX_ID_NUMBER_VALIDATION

extensions will be invoked synchronously when a Tax ID (VAT/GST) number has to be validated. Please note that alf.io already supports EU VAT validation (by calling the EU VIES web service). In these cases, the TAX_ID validation will be called only as fallback.

Important

Your extension should return a failed validation result if the country is not supported

additional global variables
  • countryCode: String - the country code of the organizer.
  • taxIdNumber: String - the Tax ID number
expected result type

boolean - The validation result.

STUCK_RESERVATIONS

extensions will be invoked asynchronously when the system will detect a stuck reservation.

additional global variables

OFFLINE_RESERVATIONS_WILL_EXPIRE

extensions will be invoked asynchronously

additional global variables
  • reservationIds String[] - list of reservation ids

EVENT_CREATED

extensions will be invoked asynchronously and synchronously when an event has been created.

EVENT_STATUS_CHANGE

extensions will be invoked asynchronously and synchronously when an event status change.

additional global variables
  • status: String - possible values: 'DRAFT', 'PUBLIC', 'DISABLED'

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. Return types are event-dependent. Will always receive a single parameter (scriptEvent) which is the event that triggered the script.