Scheduling an event via ESPF API

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.

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/Netaccess/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.

Make sure that the EventSender handler is configured and enabled to provision events to the Application. Refer to the ESPF configuration handbook.

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, please refer to the ESPF configuration handbook for details.

1. Create a custom event via the command-line interface. To create a custom event, execute the following command:

   /home/provisioning-framework/utils/evctl-old.pl type create <custom_event_name>

   Note that the name of the event must start with "Custom/" (e.g., Custom/NextMonth). Example

   /home/provisioning-framework/utils/evctl-old.pl type create Custom/NextMonth
   Created event type #10001 Custom/NextMonth

2. 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 <i_env> <handler_name> <custom_event_name>

   The administrators whose login is added to the “superusers” list, can check the environment number (i_env value) in the top right corner of the PortaBilling web interface.

   Example

   /home/provisioning-framework/utils/evctl.pl handler subscribe 3 EventSender Custom/NextMonth Handler EventSender is subscribed to Custom/NextMonth

3. To send notifications to the Application when the quota is reached, enable the Account/Service/Netaccess/QuotaExceeded event and subscribe the EventSender handler to it. Find more details on how to subscribe the handler to the event here.
4. Now, when the Application receives a notification about the event Account/Service/Netaccess/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:

Here is an example of the response:

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.