Provisioning via event handlers

Event handlers are special Perl modules in PortaBilling to provision specific external systems. Each event handler is subscribed to the provisioning events required by its corresponding external system, e.g., account creation, and continuously monitors the event queue for these events. In addition to specific event handlers, you can provision any external system using webhooks.

An event may be triggered as a result of data manipulation or directly from the code that performs some operation. Each event is created in the database, and it is stored in the Event_Queue_Combined table with the following details:

• Unique identifiers for the event, event type, event handler, and other related objects
• Timestamps indicating when the event was created and when it is scheduled for provisioning
• Event status (e.g., opened, accepted, finished)
• Processing attempt counter showing how many times the system has tried to process the event
• Event variables, such as the account ID, product name, event name, message details, and other relevant parameters

When a relevant event occurs, the event handler automatically triggers the appropriate API call to the external system to perform the necessary action (e.g., activating a SIM card). To provision data to your external system, configure an event handler and subscribe it to the required events. You can do this through the PortaBilling web interface. For detailed instructions, refer to the ESPF configuration handbook.

An ESPF event may be triggered as a result of data manipulation (step 1) or directly from the code that performs some logic (resulting directly in step 2).

1. Admin subscribes the event handler to the provisioning events, e.g., Account/New.
2. A database trigger is created for a specific table, which is automatically executed in response to some data changes, e.g., a new account is added
3. When the data has changed, the trigger inserts a record into the Event_Queue_Combined table for each event handler subscribed to the event. This design allows multiple event handlers to be subscribed to and process the same event.
4. A handler subscribed to this provisioning event reads the record from the table and notifies the external system.
5. External system processes the request by retrieving the required account or customer information from PortaBilling via the API. This information differs for each external system (e.g., an HSS requires SIM card details while an IPTV platform requires a channel package name).
6. The handler provisions both the event and its data to the external system and receives a return code (whether the event was processed successfully or not) from it.
7. If the return code is successful, then ESPF changes the event status to "finished" for this handler in the Event_Queue_Combined table. Otherwise, the handler tries to provision the event again until it is either provisioned or the amount of retries reaches its limit.
8. When all handlers provision this event, the ESPF removes the processed event from the Event_Queue_Combined table.

If multiple events for the same account/customer are added to the Event_Queue_Combined table, only the latest event in the queue will be processed for the following event types:

• 'Account/ProductAddon/Changed'
• 'Account/ProductAddon/Deleted'
• 'Account/Service/Msg/QuotaExceeded'
• 'Account/Service/Netaccess/QuotaExceeded'
• 'Account/Service/QuotaExceeded'
• 'Account/Service/QuotaExpired'
• 'Account/Service/Msg/QuotaExpired'
• 'Account/Service/Netaccess/QuotaExpired'
• 'Customer/Status/Limited'
• 'Customer/Status/Suspended'

PortaBilling is supplied with these handlers to provision data to external systems:

• AricentHSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to the Aricent HSS and Adax HSS. It also provisions subscriber’s service configuration (static IP address, quality of service information).
• Calix – this handler provisions ONT device information such as FSAN serial number plus account and service configuration data (e.g., account status, bandwidth profile ID within the Internet service policy) to the Calix Management System, the platform that controls Internet service availability for subscribers in fiber-optic networks such as GPON/Active Ethernet.
• Cgates::CLDB – this handler provisions subscriber information (account ID, MAC address), billing status and service configuration data (e.g., product, speed limit changes) to the external database CLDB.
• Conax – provisions channel information to Conax when either new or existing customers sign up for the IPTV service.
• EventSender – this is a universal handler to provision any external system, refer to the Provisioning via webhook chapter. 
• Huawei::HSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to the Huawei HSS.
• Huawei::PCRF – this handler provisions the subscriber’s service configuration (service and policy name, QoS parameters) to Huawei PCRF.
• IPTV – this handler provisions available channel information to one of the PortaSwitch supported IPTV platforms (i.e. MatrixStream, Minerva, Telebreeze IPTV) when either new or existing customers sign up for the IPTV service.
• Jasper –  this handler provisions subscriber and SIM card information to the Cisco Jasper connectivity management platform.
• Odoo::CRM – provisions the subscriber’s information such as the user’s status, and invoice-related events such as “invoice is generated” to Odoo CRM.
• Sandvine – this handler provisions subscriber details such as username, static IP address/netmask, service provider identifier, and Internet access policy details to Sandvine SPB (Subscriber Policy Broker). Sandvine SPB is a component of the Sandvine DPI (Deep Packet Inspection) solution. It enables you to shape network traffic and introduce policy enforcement on a per-subscriber basis.
• SeaChange –  provisions channel information to SeaChange when either new or existing customers sign up for the IPTV service.
• Titan::HSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to NetNumber Titan HSS. It also provisions subscriber’s service configuration – Regular upload/download limits for Internet access, APN (Access Point Name) ID, Roaming profile ID.
• YateHSS – this handler provisions subscriber information such as the user’s phone number, their SIM card details, and user’s status to Yate HSS/HLR.
• ZXUN::HSS – this handler provisions subscriber information such as the user’s phone number, SIM card details, and their account status to the ZTE HSS.
• ZXUN::SPR – this handler provisions the subscriber’s service configuration, user’s phone number, and SIM card details to the ZTE SPR.