this repository contains all the official alf.io extensions
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.)
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.
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
extensions will be invoked asynchronously once a reservation has been confirmed.
- reservation: TicketReservation
extensions will be invoked synchronously once one or more reservations have expired.
- reservationIds: String[] - the reservation IDs
boolean
extensions will be invoked synchronously once one or more reservations have been cancelled.
- reservationIds: String[] - the reservation IDs
- reservations: TicketReservation[] - the TicketReservations
boolean
extension will be invoked synchronously once one or more tickets (but not the entire reservation at once) have been cancelled
- ticketUUIDs: String[] - the cancelled tickets UUIDs. Please note that once a ticket has been cancelled, its UUID is reset.
extensions will be invoked asynchronously once a ticket has been assigned.
- ticket: Ticket
extensions will be invoked asynchronously once a ticket has been checked in.
- ticket: Ticket
extensions will be invoked asynchronously once a ticket has been reverted from the checked in status.
- ticket: Ticket
extensions will be invoked asynchronously once someone subscribes to the waiting queue.
- waitingQueueSubscription: WaitingQueueSubscription
extensions will be invoked synchronously while generating an invoice.
- 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
InvoiceGeneration - The invoice content, currently limited to the invoice number.
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.
Your extension should return a failed validation result if the country is not supported
- countryCode: String - the country code of the organizer.
- taxIdNumber: String - the Tax ID number
boolean - The validation result.
extensions will be invoked asynchronously when the system will detect a stuck reservation.
- reservations: TicketReservationInfo
extensions will be invoked asynchronously
- reservationIds String[] - list of reservation ids
extensions will be invoked asynchronously and synchronously when an event has been created.
extensions will be invoked asynchronously and synchronously when an event status change.
- status: String - possible values: 'DRAFT', 'PUBLIC', 'DISABLED'
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)
The actual event handling. Return types are event-dependent. Will always receive a single parameter (scriptEvent) which is the event that triggered the script.