ESPF configuration

This chapter provides instructions on how to configure the ESPF (External system provisioning framework) to capture changes in customer/account configuration in PortaBilling and send provisioning events to the external system via the HTTP protocol.

ESPF sends HTTP POST requests with provisioning events using the EventSender handler. Service providers develop the web application that receives these requests, processes them, and updates the data in the external system. They can develop their web application in a programming language they prefer and can run it on any of their web servers or in a cloud.

In this document, we demonstrate how to configure the EventSender handler for ESPF to provision events to a custom web application.

To provision any of the supported external systems, it is necessary to choose an essential handler (e.g., Yate HSS) and configure this handler instead of the EventSender.

Let’s say that you operate as an MVNO and you now have an HSS of your own. You want to provision your subscriber details there when a mobile user is added to or modified in PortaBilling.

For example, provisioning events are sent when an administrator changes a phone number/SIM card or product for a user when the user has depleted their available funds or topped up their balance, or when an administrator temporarily blocks a user (e.g., for non-payment).

Use this checklist to check off the operations you have completed while performing the system setup according to the instructions in this chapter. Please be sure to perform all of the operations in the order designated (all of the boxes should be checked), otherwise, the service will not work.

To enable provisioning to external systems, create a new ESPF instance as follows:

1. On the Configuration server web interface, go to the Configurations tab.
2. Clone the current configuration.
3. In the node tree select Auxiliaries → ESPF and click Create instance.
4. Select the server and service IP for the instance.

   

5. Click Save.
6. You can configure multiple ESPF instances. Thus, repeat steps 1-5, in case you need to configure another ESPF instance.

   

7. Leave it as is and move on to the next step.

To provision data to your external web application, configure the EventSender handler.

1. On the PortaBilling web interface, go to Infrastructure and select Event handlers.

   

2. Open the Create event handler tab and fill in the details:
   • Name – type the event handler name, e.g., “EventSender”.
   • Type – select EventSender.
   • Leave the Enabled toggle on to enable the handler once it’s created.

     

3. Click Save.

To provision data to your external web application, configure the created EventSender handler.

1. Open the created event handler > Configuration and fill in the following information:
   • Concurrency – the number of concurrent task processing. The default value is “1”.
   • EventSender.AllowedTypes – here you can specify the name of the event type, e.g., Account/Blocked, or the pattern, e.g., Customer/* so only events of that type will be sent to the handler.
   • EventSender.APIVersion – define the version of the provisioning events used by the handler:
     • 1 – for standard provisioning events;
     • 2 (default value)– for simplified provisioning events (a limited set of events and variables).
   • EventSender.AsyncMode – leave this toggle on to send requests asynchronously (a handler sends a request as soon as it is processed, without waiting for a reply from a server). If you turn off the toggle, the requests will be sent synchronously (one by one once a server reply is received).
   • EventSender.AuthHeader – this is the name for the header that holds authentication details (e.g., authentication key/user/type/key ID) based on the authentication method. Leave the default Authorization header here.
   • EventSender.AuthMethod – specify the method used to authenticate HTTP requests. Refer to the Authentication methods section for more details. The possible options are:
     • Basic (default value) – authenticate by user ID and password.
     • Custom – authenticate by custom type and credentials.
     • Signature – authenticate by key and key ID.
     • None – when the external system requires another way for authorization, select this option to disable authorization header.
   • EventSender.BasicAuth.Key – specify the user password mandatory for the Basic HTTP authentication.
   • EventSender.BasicAuth.User – specify the user ID mandatory for the Basic HTTP authentication.
   • EventSender.CustomAuth.Credentials – specify the credentials mandatory for the Custom HTTP authentication.
   • EventSender.CustomAuth.Type – specify the authentication type mandatory for the Custom HTTP authentication.
   • EventSender.MaxWaitTime – this defines how long the handler waits for a response from a server in asynchronous mode. The timer starts once the last request from an iteration was sent (600 seconds by default).
   • EventSender.RequestTimeout – the number of seconds that the handler waits for the response from the server once a request is sent (300 seconds by default).
   • EventSender.SignatureAuth.Key – the key associated with the key ID that is used to create a signature. This field is mandatory for the Signature HTTP authentication.
   • EventSender.SignatureAuth.KeyId – the string that the server can use to look up the component required to validate a signature. This field is mandatory for the Signature HTTP authentication.
   • EventSender.TokenBurstiness – this value defines the maximum number of requests that can be sent per second in asynchronous mode (100 by default).
   • EventSender.TokenRate – this value defines the average number of requests that are sent per second in asynchronous mode (10 by default).
   • EventSender.URL – the IP address or host name of the server to which requests are sent (e.g., http://127.X.X.X:5000 or http://test.domain.com:5000).
   • EventSender.WithUniqueID – leave the toggle on to add a unique identifier to the event data so that the remote side can detect request retries.

     

2. Click Save.

When a handler is subscribed for specific events, the handler receives notifications only about events of that type and processes them. To subscribe EventSender to the required event types, perform the following steps:

1. Open the handler and go to Event subscriptions.
2. Turn on the toggle for specific events to subscribe to these events.
3. Click Save.

   

In our example, the following event types must be enabled:

• Account/New
• Account/SIMCardAssignment
• Account/ServicePassword/Changed
• Account/Password/Changed
• Account/ID/Changed
• Account/ZeroAvailableFunds
• Account/AvailableFundsAppear
• Account/Product/Changed
• Account/Blocked
• Account/Unblocked
• Customer/ZeroAvailableFunds
• Customer/AvailableFundsAppear
• Customer/Blocked
• Customer/Unblocked

Changes in customer or product configuration in PortaBilling may affect the account configuration, e.g., a customer reaches their credit limit and so their credit accounts no longer have access to services.

To provision changes that are caused by changes in customer/product and/or service configuration for an account, activate other ESPF components such as ProductToAccountsDispatcher, CustomerToAccountsDispatcher, and ServiceAttributeDispatcher handlers.

In our example, to provision account changes once a customer configuration changes, you need to additionally create the CustomerToAccountsDispatcher handler. Repeat the steps from Create a handler section, but in step 2, select the event type CustomerToAccountsDispatcher.

It may happen that the web application becomes unreachable due to network connectivity issues and therefore, that provisioning fails. To be informed about unsuccessful provisioning, configure the ESPF to notify you via email.

1. From Groups, select Provisioning.
2. Fill in the fields:
   • AlertRecepient – type in your email address to receive notifications.
   • send_options – specify the options passed to the command-line sendmail utility. This utility is used to send notifications about provisioning errors (if there are any).

     

3. Click Save.

When you are done, click Verify to view the changes, and then click Check/Apply to apply the configuration.

Create a new mobile account via the administrator web interface and see whether the request has been sent.

1. On your customer’s panel, click Accounts.
2. On the Create an account panel, specify the account’s details:
   • ID – type in the user’s mobile number.
   • Account role – select Mobile.
   • IMSI – click on the IMSI icon and select one of the available SIM cards from the SIM Card Inventory dialog box.
   • Product – select the LTE Product here.
   • Activation date – the date from which the account is usable.
   • Type – select Credit for your postpaid Internet users.
   • Balance control – select Subordinate from the list.

     

3. Click Save to create an account.
4. Check the log.

When an account has been added, you can check this event in the event log file.

1. Go to Toolbox > External provisioning > Provisioning events.
2. On the Search provisioning event panel, select the handler name from the dropdown list.
3. Click Apply filters to see a specific event log.

   

4. To obtain the details of the event log, hover over a specific event log, and click Arrow .