This is an alternative approach to data provisioning. Webhooks allow your external application to receive notifications about provisioning events happening in PortaBilling.
For simplicity, provisioning events are grouped into four category types:
-
Customer – the event types of this group notify that a customer record has been created, updated, or deleted in PortaBilling.
-
Subscriber – the event types of this group notify that an account record has been created, updated, or deleted in PortaBilling.
-
DID – the event types of this group notify that a DID number has been added, updated (assigned to / unassigned from a customer or account), or deleted in PortaBilling.
-
Invoice – the event types of this group notify that an invoice has been created or updated (paid fully or partially, or refunded) in PortaBilling.
An external application subscribes to receive these event types. Once an event occurs, the ESPF maps it to the corresponding event type and sends the HTTP POST request to the application’s URL. The request body contains the event type and the ID of the provisioned entity in JSON format.
For example, when a new SIM card is assigned to a subscriber in PortaBilling, the ESPF sends an HTTP POST request as follows:
http://127.X.X.X:5000:
{
"event_type": "Subscriber/Updated",
"variables": {
"i_event": "5"
"i_account": "1000889"
}
}
Your application receives the request, queries the information related to this event type (SIM card details such as IMSI, MSISDN) from PortaBilling via the API, and triggers the API call in the HSS to activate the SIM card.
The i_event variable in the request enables the application to determine whether it is a new request or a retry. The application must be able to store requests, identify them by the i_event variable and check for retries.
In the case of a retry, the application verifies the request’s status. If the request was already processed, the application responds with 200OK. Otherwise, the application treats it as a new request and processes it accordingly.
To illustrate the flow in detail, consider the following example:
An administrator creates a new account record in PortaBilling. The ESPF sends the HTTP POST request with the Subscriber/Created event type and i_event:5 to the external application. The application retrieves the account service configuration from PortaBilling and provisions the external system. If the ESPF receives no response from the application during the timeout (e.g., 30 seconds), it resends the request.
The application determines that it is the same request (i_event:5) and searches its own event queue. If provisioning is successful but takes longer, the application does not attempt to provision that subscriber again. Otherwise, it re-provisions the external system.
When the ESPF sends several events that relate to the same entity (e.g., have the same i_account value), the application uses the i_event values to sort them in the correct order.
Note that using the ESPF API, you can add events to the queue and schedule the time when they must be processed. Refer to the Provisioning Application Reference guide to see the configuration details and the example of the usage scenario.
Components
Your external application operates as the middleware between PortaBilling and the external system it provisions. You can develop it in any programming language (e.g., Java, Python, etc.) and host it on a remote web server or in a cloud.
To provide an additional layer of security to communications between your external system and PortaBilling, you can use a cryptographic signature for HTTP requests.
The ESPF sends HTTP POST requests using the EventSender handler. It supports all provisioning events and operates in asynchronous mode by default. To prevent system overload in case of large numbers of events, the EventSender controls the number of parallel requests. And, if necessary, you can always change the handler to operate in synchronous mode.
The ESPF can send HTTP POST requests to more than one external application. This enables you to provision data to several external systems at the same time.
For example, you integrate PortaBilling with the HSS and the IPTV platform to provide both mobile and IPTV services. When you register a new account in PortaBilling, the ESPF sends a provisioning request to both the HSS and the IPTV platforms.
If a user’s service configuration includes only one service (e.g., IPTV), this request is useless for the HSS. Therefore, if a service is not used by a subscriber, make sure that the application to provision the HSS ignores it.
You can configure the ESPF to differentiate among provisioning data and send specific event types to each system. To make this happen, please contact PortaOne support. This configuration requires deep knowledge of ESPF architecture.
Provisioning event version
The EventSender handler supports both simplified and standard provisioning events. We recommend that you develop the external application to operate with the simplified events. If the simplified events do not meet the system’s requirements for provisioning, you develop a web application to process the standard provisioning events.
Depending on an application’s logic, you can now configure the ESPF to send a desired version of the provisioning events on the Configuration server. Simply select the value for the EventSender.APIVersion option, where:
-
1 stands for standard provisioning events, and
-
2 – for simplified provisioning events.
The external systems you provision may require different event versions. For example, the HSS requires standard events while the CRM system you integrate with PortaBilling can be provisioned using the simplified events. In this case, fine-tune the ESPF to send the correct version to either application:
-
Configure the default event version for the ESPF as described above. All applications operate with it when you add more external systems to your infrastructure.
-
Define the event version for a particular web application. Enter the following string in the ESPF.CustomIniOptions option on the Configuration server:
[EventSender]APIVersionForReceivers=https://mycompany.com=version,
where:
-
https://mycompany.com is the URL of the web application, and
-
version is the provisioning event version value.
-
Configuration
Please refer to the Provisioning Application Reference Guide for guidelines on how to develop an external application to provision data from PortaSwitch.
Supported event handlers
Built-in integrations
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).
-
AudioCodes – this handler provisions subscriber information such as the user’s phone number, SIM card details, status, registration (SIP parameters), mobile device (IMEI, language, etc.) and custom configurations to the AudioCodes CMMS (Clients’ Management Server).
- 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.
-
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.
-
ECConnect – this handler provisions subscriber information such as service configuration (allowed services), billing status and SIM card details (MSISDN, ICCID) to the ECConnect Access Portal (EAP) platform. EAP acts as the middleware between PortaBilling and the Optus mobile core to activate mobile services for subscribers.
-
EventSender – this is a universal handler to provision any external system. Since it sends HTTP POST requests with provisioning events to an external application, it’s the middleware between PortaSwitch and an external system. The application can be written in any programming language. It must be able to process provisioning events and communicate with PortaSwitch and the external system via their API.
-
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.
- NetNumber – this handler provisions ported-in numbers to the NetNumber SMS/MMS database.
-
ReadyWireless – this handler provisions the subscriber’s phone number and device (IMEI) to ReadyWireless MVNE to trigger device activation/deactivation.
-
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.
-
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.
Internal handlers
Changes in customer, product, and service configuration influence the configuration of accounts in PortaBilling. For example, when a customer reaches their credit limit, services are no longer available to their credit accounts until the customer’s balance is refilled.
To reduce the load on the system in such cases, ESPF is supplied with handlers that process product, customer, and service configuration events, and then create events for accounts and place them in the event queue:
-
CustomerToAccountsDispatcher – this handler processes customer status changes and provisions them to all customer accounts.
-
ProductToAccountsDispatcher – this handler processes all changes at the product level and provisions them to an account that has this product assigned to it.
-
ServiceAttributeDispatcher – this handler provisions changes in service configuration to both customers and accounts.
This handler processes events within PortaBilling:
-
SIPForwarder – this handler is used when an account is moved from one system to another. It provisions information about an account and/or the DID number location to the dispatching SBC in the Dual Version PortaSwitch deployment.
Supported event types
The ESPF is supplied with the following set of provisioning event types:
|
Name |
Description |
Variables |
Inherited from Customer |
|---|---|---|---|
|
AccessPolicy/Changed |
An Internet access policy was updated |
i_env, i_access_policy |
|
|
AccessPolicy/Phase/New |
A new Internet access policy phase was added |
i_env, i_access_policy |
|
|
AccessPolicy/Phase/Changed |
An Internet access policy phase was updated |
i_env, i_access_policy |
|
|
AccessPolicy/Phase/Deleted |
An Internet access policy phase was deleted |
i_env, i_access_policy |
|
|
Accessibility/Deleted |
The usage charges record has been removed from the account’s product. |
i_env, i_product, i_accessibility |
|
|
Accessibility/Inserted |
A usage charges record has been added to the account’s product. |
i_env, i_product, i_accessibility |
|
|
Account/ActivationDate/Changed |
The activation date has been changed for an account. (Accounts.activation_date has been changed) |
i_env, i_account, prev_activation_date, curr_activation_date |
|
|
Account/AccessPolicy/Changed |
The Internet access policy was updated for the account |
i_env, i_account, i_access_policy |
|
|
Account/Alias/Delete |
An alias has been removed from an account. |
i_env, i_master_account, id |
|
|
Account/AvailableFundsAppear |
An account’s available funds are restored when a debit account tops up the balance or when a postpaid customer pays their invoice. (Accounts.balance has been topped up from credit_limit.) I_account. |
i_env, i_account |
Y |
|
Account/BalanceChanged |
The balance of a debit or individual credit account has changed (e.g., a call has been charged, a refill has been received). A customer’s balance has changed for postpaid customers. |
i_env, i_account, prev_balance, curr_balance |
Y |
|
Account/Blocked |
An account has been blocked. (Accounts.blocked set to ‘Y.’) |
i_env, i_account |
|
|
Account/CustomField/Changed |
Custom information (e.g., ID card) has been added or changed for an account. (The Custom_Field_Values table has been updated for the account.) |
i_env, i_account, field_name, prev_value, curr_value |
|
|
Account/Discount/Changed |
An account’s discount plan has changed. |
i_env, i_account, prev_i_vd_plan, curr_i_vd_plan |
|
|
Account/ExpirationDate/Changed |
An account’s expiration date has changed. (Accounts.expiration_date has been changed.) |
i_env, i_account, prev_expiration_date, curr_expiration_date |
|
|
Account/FollowMe/Changed |
An account’s follow-me setting has changed (the Follow_Me table has been updated). |
i_env, i_account |
|
|
Account/FollowMeNumber/Inserted |
A new follow-me number has been added to an account. |
i_env, i_account, i_follow_me, i_follow_me_number, curr_redirect_number |
|
|
Account/FollowMeNumber/Changed |
An account’s follow-me number has changed. |
i_env, i_account, i_follow_me, i_follow_me_number, curr_redirect_number, prev_redirect_number |
|
|
Account/FollowMeNumber/Deleted |
An account’s follow-me number has been removed. |
i_env, i_account, i_follow_me, i_follow_me_number, prev_redirect_number |
|
|
Account/ID/Changed |
An account’s ID has changed. (Account.id has been updated.) |
i_env, i_account, prev_id, curr_id |
|
|
Account/IPDeviceAssignment |
An IP device has been assigned to an account (the UA_Links table has been updated). |
i_env, i_account, prev_ua, prev_port, prev_config, i_ua, port, config |
|
|
Account/New |
A new account has been created. |
i_env, i_account |
|
|
Account/Password/Changed |
An account’s password for the self-care interface has changed. (Accounts.password has been changed.) |
i_env, i_account, prev_password, curr_password |
|
|
Account/Product/Changed |
Another product was assigned to the account. An account’s product has changed. (Account.i_product has been updated.) |
i_env, i_account, prev_product, curr_product |
|
|
Account/ProductAddon/Changed |
An account’s add-on product has been changed. |
i_env, i_account, i_addon_product |
|
|
Account/ProductAddon/Deleted |
An add-on product has been removed from an account. |
i_env, i_account, prev_i_addon_product |
|
|
Account/ProductAddon/Inserted |
A new add-on product has been added for an account. |
i_env, i_account, curr_i_addon_product |
|
|
Account/Service/QuotaAvailable |
The user tops up their service wallet so that the account’s service usage quota becomes available. |
i_env, i_account, i_service, i_vd_dg |
|
|
Account/Service/QuotaExceeded |
An account has exceeded its service usage quota. |
i_env, i_account, i_service, i_vd_dg |
|
|
Account/Service/Msg/QuotaExceeded |
An account’s service usage quota for messaging service type has expired |
i_env, i_account, i_service |
|
|
Account/Service/Netaccess/QuotaExceeded |
An account’s Internet access quota has expired |
i_env, i_account, i_service |
|
|
Account/ServiceAttribute/Changed |
A service feature has been enabled / disabled for an account (the Service_Attribute_Values table has been updated). |
i_env, i_account, feature_name, attribute_name, old_value |
Y |
|
Account/ServiceFlags/Changed |
An account’s service features have changed. (Accounts.service_flags has been updated.) |
i_env, i_account, account_prev_service_flags |
Y |
|
Account/ServicePassword/Changed |
An account’s service password has been changed.(Accounts.h323_password has been changed.) |
i_env, i_account, prev_h323_pwd, curr_h323_pwd |
|
|
Account/SIMCardAssignment |
A SIM card has been assigned to, removed from or changed for an account. |
i_env, i_account, prev_i_sim, i_sim |
|
|
Account/Status/Changed |
An account’s billing status has been changed or affected by the customer’s billing status. A customer’s status has changed. (Customers.bill_status has changed.) |
i_env, i_account, prev_status, new_status |
Y |
|
Account/Status/Closed |
The status of the account has changed to Closed. The account has been removed from the web interface. (Accounts.bill_status set to ‘C.’) This event type appears when a customer is terminated. |
i_env, i_account |
Y |
|
Account/Status/Exported |
An account has been exported by Porter in Dual Version PortaSwitch.(Customers.bill_status set to E.) |
i_env, i_account |
Y |
|
Account/Status/Imported |
An account has been imported by Porter in Dual Version PortaSwitch. |
i_env, i_account |
Y |
|
Account/Status/Suspend |
An account’s status has changed to suspended because of a customer’s suspension. Caused by: Customer has unpaid invoice.(Customers.bill_status set to ‘S.’) |
i_env, i_account |
Y |
|
Account/Status/Unsuspend |
An account has been unsuspended; due to removing of the customer’s suspension. A customer’s account has been reinstated. (Customers.bill_status set to ‘O’ from ‘S.’) |
i_env, i_account |
Y |
|
Account/Unblocked |
An account has been unblocked. (Accounts.blocked set to ‘N.’) |
i_env, i_account |
|
|
Account/ZeroAvailableFunds |
An account’s available funds have been depleted. (Accounts.balance has reached credit_limit [for credit accounts] or 0 [for debit accounts.]) |
i_env, i_account |
Y |
|
Connection/Changed |
The connection information has been updated. |
i_env, i_vendor, i_connection, prev_remote_ip |
|
|
Connection/Deleted |
The connection has been removed from the vendor. |
i_env, i_vendor, i_connection, i_connection_type, prev_remote_ip |
|
|
Connection/New |
A new connection has been created for the vendor. |
i_env, i_vendor, i_connection, |
|
|
Custom/Jasper/CapReached |
External event received from Jasper Platform. |
i_env, i_account |
|
|
Customer/AvailableFundsAppear |
A customer has topped up his balance |
i_env, i_customer |
|
|
Customer/BalanceChanged |
A customer’s balance has changed (e.g., a subscription charge has been applied or a refund has been issued) |
i_env, i_customer, prev_balance, curr_balance |
|
|
Customer/CustomField/ Changed |
The data in a customer’s custom field has changed (the Custom_Field_Values table has been updated for the customer). |
i_env, i_customer, field_name, prev_value, curr_value |
|
|
Customer/Deleted |
The customer’s record has been removed from the customer list. |
i_env, i_customer, i_customer_class, name |
|
|
Customer/Name/Changed |
The customer’s name has changed. |
i_env, i_customer, prev_name, curr_name |
|
|
Customer/New |
A new customer has been created. |
i_env, i_customer |
|
|
Customer/ServiceAttribute/Changed |
A customer’s service setting has changed (the Service_Attribute_Values table has been updated). |
i_env, i_customer, feature_name, attribute_name, old_value |
|
|
Customer/ServiceFlags/Changed |
A customer’s service features have changed. (Customers.service_flags has been updated.) |
i_env, i_customer, prev_service_flags |
|
|
Customer/Status/Activated |
A customer’s record has been activated. (Customers.bill_status set to ‘O’ from ‘D.’) |
i_env, i_customer |
|
|
Customer/Status/Changed |
A customer’s status has changed. (Customers.bill_status has been updated.) |
i_env, i_customer, prev_status, new_status |
|
|
Customer/Status/Closed |
A customer has been terminated and their status changed to closed. (Customers.bill_status set to ‘C.’) |
i_env, i_customer |
|
|
Customer/Status/Deactivated |
A customer’s record has been deactivated. (Customers.bill_status set to ‘D’ from ‘O.’) |
i_env, i_customer |
|
|
Customer/Status/Exported |
A customer’s record status has changed. (Customers.bill_status set to E.) |
i_env, i_customer, prev_status |
|
|
Customer/Status/Imported |
A customer’s record status has changed. (Customers.bill_status set to O.) |
i_env, i_customer, new_status |
|
|
Customer/Status/Suspended |
A customer record has been suspended (the Customers.bill_status has been updated to “Suspended”). If an admin manually sets a suspension delay, the Customer/Status/Suspend event is sent after the delay period is over (on the scheduled date). |
i_env, i_customer, delay_date |
|
|
Customer/Status/SuspensionRemoved |
A customer record has been reinstated (the Customers.bill_status has been updated from “Suspended” to “Open”). If an admin manually lifts the suspension, the customer status is changed to “Suspension delayed” and the Customer/Status/SuspensionRemoved event is sent with the delay period (the scheduled date “effective_to”). Note that this event is also sent when the admin changes the suspension delay that is already set. |
i_env, i_customer, effective_to |
|
|
Customer/Unblocked |
A customer’s account has been unblocked. (Customers.blocked set to ‘N.’) |
i_env, i_customer |
|
|
Customer/ZeroAvailableFunds |
A customer’s available funds have been depleted. (Customers.balance has reached credit_limit.) |
i_env, i_customer |
|
|
CustomField/Changed |
A customer’s custom data has changed (the Custom_Field_Values table has been updated). |
i_account, i_env, curr_value, prev_value, field_name |
|
|
CustomerSite/ServiceAttribute/Changed |
A service configuration has changed for a customer class (the Service_Attribute_Values table has been updated). |
i_env, i_customer_site, feature_name, attribute_name, old_value |
|
|
DID/New |
A new DID number has been added to the DID inventory. |
i_env, number |
|
|
DID/Status/Assigned |
A DID number has been assigned to a customer. |
i_env, number, prev_customer |
|
|
DID/Status/Unassigned |
A DID number has been removed from a customer. |
i_env, number, prev_customer |
|
|
DID/Status/Activated |
A DID number has been assigned to a customer’s account ID. |
i_env, number |
|
|
DID/Status/Canceled |
A DID number has been unassigned from a customer’s account ID. |
i_env, number |
|
|
DID/Status/Moved |
A DID number has been moved to another installation as a result of provisioning. |
i_env, number |
|
|
DID/Deleted |
A DID number has been removed from the DID inventory. |
i_env, number |
|
|
Invoice/Adjustment/ Changed |
An invoice has been adjusted (refunded) by an administrator. |
i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status, adjustments, prev_adjustments |
|
|
Invoice/AmountPaid/ Changed |
This is the amount a customer has paid. Use this event to track and provision: – manual payment information; – partially paid invoice changes. |
i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status, amount_paid, prev_amount_paid |
|
|
Invoice/New |
A new invoice has been generated. |
i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status |
|
|
Invoice/Status/Changed |
An invoice has changed its status (e.g., from unpaid to paid, from unpaid to overdue). Use this event to track and provision information:
Refer to the Invoice parameters and Invoices review chapters in the PortaBilling Administrator Guide for the description of these statuses. Note that if a customer pays their invoice in installments, the Invoice/Status/Changed event occurs twice for this invoice:
For example, a customer pays their $110 invoice in installments (e.g., $25+$20+$35+$30). Events occur when:
|
i_env, i_customer, invoice_number, amount_net, i_invoice_type, prev_i_invoice_status, i_invoice_status |
|
|
IPDeviceProfile/New |
A CPE profile has been created. |
i_env, i_ua_profile |
|
|
PaymentTransaction/New |
A customer has made a credit card payment. |
i_env, i_payment_transaction, test_mode, status, amount, iso_4217 |
|
|
PaymentTransaction/ResultCode/Changed |
A transaction has either started or finished. |
i_env, i_payment_transaction, test_mode, status, amount, iso_4217, result_code, prev_result_code |
|
|
PaymentTransaction/Status/Changed |
A transaction has changed its status. |
i_env, i_payment_transaction, test_mode, prev_status, status, amount, iso_4217 |
|
|
Product/AccessPolicy/Changed |
The Internet access policy has been updated for a product |
i_env, i_product, i_access_policy |
|
|
Product/Discount/Changed |
A discount plan has been changed for a product or an add-on product. |
i_env, i_product, prev_i_vd_plan, curr_i_vd_plan, addon_priority |
|
|
Product/ServiceAttribute/Changed |
A service feature has been enabled/disabled for a product or an add-on product. |
i_env, i_product, feature_name, attribute_name, old_value |
|
|
ServiceAttribute/Changed |
A service feature has been enabled/disabled for either a product, add-on product, customer, or account. |
i_savalue, i_foreign, i_attribute, old_value |
|
|
Subscriber/Address/Changed |
The address of a user registered as an account has changed. |
i_env, i_subscriber, prev_baddr1… prev_baddr5, curr_baddr1 … curr_baddr5, prev_state, curr_state, prev_zip, curr_zip, prev_city, curr_city, prev_country, curr_country |
|
|
Subscriber/ContactInfo/Changed |
The account’s contact information has been changed. |
i_env, i_subscriber, prev_phone1, curr_phone1, prev_phone2, curr_phone2, prev_cont1, curr_cont1, prev_cont2, curr_cont2, prev_faxnum, curr_faxnum, prev_email, curr_email, prev_bcc, curr_bcc |
|
|
Subscriber/Name/Changed |
The user’s name registered as an account has been changed. |
i_env, i_subscriber, prev_companyname, curr_companyname, prev_salutation, curr_salutation, prev_firstname, curr_firstname, prev_midinit, curr_midinit, prev_lastname, curr_lastname |
|
