Using the ESPF API, you can add events to the provisioning queue and schedule the time when they must be processed. You can use either standard system events or custom events created for specific tasks. Refer to the External System Interfaces Guide to see the list of available provisioning event types.
The ESPF API is available at this URL:
https://<portabilling-web.yourdomain.com>/espf/v1/
where:
- portabilling-web.yourdomain.com is the hostname of your PortaBilling web server;
- v1 is the provisioning API version.
The authorization is done using the PortaBilling administrative user’s API credentials.
Usage scenario
A CSP provides customers with Internet service in roaming with a monthly quota. When the quota for an account is reached, the service is blocked till the end of the month. The ESPF sends the
Account/Service/QuotaExceeded event to the Application, the Application queries the account and service details via PortaBilling API and then interacts with the HSS via the HSS API to block this service for the account.
At the beginning of the next month, the quota must be made available again, if the account has sufficient funds. PortaBilling allocates the quota after receiving the first authorization request in the new month (when a user tries to access the service). To receive this request, the service must be unblocked in the mobile core.
To unblock the service in the mobile core at the beginning of the new month, the Application can schedule an event with the specified start time via ESPF API.
Thus, when the quota is reached, e.g., on February 20, the Application receives a notification about this event from PortaBilling and notifies the HSS to block the service for the account. At the same time, the Application calls the ESPF API to add a custom event “the new month has started” scheduled for midnight of March 1, 2021. At this scheduled time, the Application receives a notification about this event from the ESPF. This means that the new month has started and now the Application must check whether the account has sufficient funds and unblock the service in the mobile core.
To configure this usage scenario, perform the following steps.
Make sure that the ESPF is configured to provision events to the Application. The EventSender handler must be configured on the Configuration server and enabled. Refer to the ESPF configuration handbook for details.
Note that to configure the ESPF components, the evctl.pl script is used. To run the script, connect to the server (where the ESPF provisioning is enabled) via SSH and run the following commands.
Note that the Application may require additional subscriptions (for example, Account/New to create an account in the mobile core). The configuration of these subscriptions is out of the scope of this scenario.
- Create a custom event via the command-line interface.To create a custom event, execute the following command:
/home/provisioning-framework/utils/evctl.pl type create <custom event name>
Note that the name of the event must start with “Custom/” (e.g., Custom/NextMonth). For example:
/home/provisioning-framework/utils/evctl.pl type create Custom/NextMonth
Created event type #10001 Custom/NextMonth
- Subscribe the EventSender to the created custom event (e.g., Custom/NextMonth). To do this, run the following command:
/home/provisioning-framework/utils/evctl.pl handler subscribe EventSender <custom event name>
/home/provisioning-framework/utils/evctl.pl handler subscribe EventSender Custom/NextMonth
Handler EventSender is subscribed to Custom/NextMonth
- To send notifications to the Application when the quota is reached, enable the Account/Service/QuotaExceeded event and subscribe the EventSender handler to it.To do this, run the following commands:
/home/provisioning-framework/utils/evctl.pl type enable <event name>
/home/provisioning-framework/utils/evctl.pl type enable Account/Service/QuotaExceeded
Triggers for table Account_VD_Counters AFTER INSERT were recreated
Triggers for table Account_VD_Counters AFTER UPDATE were recreated
Event Account/Service/QuotaExceeded was enabled
/home/provisioning-framework/utils/evctl.pl handler subscribe EventSender <event name>
/home/provisioning-framework/utils/evctl.pl handler subscribe EventSender
Account/Service/QuotaExceeded
Handler EventSender is subscribed to Account/Service/QuotaExceeded
Note that the Application may require additional subscriptions (for example, Account/New to create an account in the mobile core). The configuration of these subscriptions is out of the scope of this scenario.
- Now, when the Application receives a notification about the event Account/Service/QuotaExceeded, it connects to the ESPF via the API and sends a request to add the event Custom/NextMonth with the start time March
1, 2021, 00:00 and i_account attribute.
The start_time value displays time in the UTC time zone. When specifying the start_time value, convert the time of the customer’s time zone to the UTC time.
Here is an example of the HTTP POST request:
Authorization: Basic dXNlcm5hbWU6c2VjcmV0
Content-Type: application/json
POST /espf/v1/event/create HTTP/1.1
{
“event_type”: ” Custom/NextMonth “,
“variables”: {
“i_account”: 541
},
“start_time”: “2021-03-01 00:00:00”
}
Here is an example of the response:
{ “i_event”: 623623 }
As a result, on March 1, the Application receives a request from ESPF with the event Custom/NextMonth. The Application retrieves the account details from PortaBilling using the API method Account/get_account_info. If the application detects that the account has sufficient funds, it notifies the HSS to unblock this service for that specific account.
Now, the service is unblocked in the mobile core. When the account user attempts to access the service, e.g., on March 5, PortaBilling receives the authorization request and allocates the quota for March. The Internet service in roaming is available for the user.
Note that there’s a possible scenario when the account doesn’t have sufficient funds at the beginning of the month, e.g., on March 1, but the user tops up their service wallet later. In this case, additionally, configure the Account/Service/QuotaAvailable event type at step 3. After the service wallet top-up, the Application receives the notification about the Account/Service/QuotaAvailable event and notifies the HSS to unblock the service for this account.
