ESPF configuration

This chapter provides instructions 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.

 Enabling the ESPF handlers and provisioning event types requires a deep knowledge of ESPF architecture. Therefore, please contact the PortaOne support team to configure the ESPF for you.

Let’s say that you operate as an MVNO and you now have an HSS of your own. You wish 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 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. In the node tree, select ESPF.
2. Select the environment (e.g., Global).
3. Move to Groups and select EventSender.
4. Fill in the following information:

   

   • AsyncMode – leave the default Yes value to send requests asynchronously (a handler sends a request as soon as it is processed, without waiting for a reply from a server) or change to No to send requests synchronously (one by one once a server reply is received).
   • AuthHeader – this is the name for the header that holds authentication details (e.g., authentication key / user / credentials / type / key ID) based on the authentication method. Leave the default Authorization.
   • AuthMethod – select the method used to authenticate HTTP requests:
     • Basic – authenticate with user ID and password;
     • Custom – authenticate custom type and credentials;
     • Signature – authenticate by key and key ID.
   • BasicAuth_Key –specify the user password for the Basic method only.
   • BasicAuth_User – specify the user ID for the Basic method only.
   • CustomAuth_Credentials – specify the credentials for the Custom method only.
   • CustomAuth_Type – specify the type for the Custom method only.
   • MaxWaitTime – this defines how long the handler waits for a response from a server in asynchronous mode. The time starts once the last request from an iteration was sent (600 seconds by default.)
   • RequestTimeout – the number of seconds that the handler waits for the response from the server once a request is sent (300 seconds by default.)
   • SignatureAuth.KeyId – the string that the server can use to look up the component required to validate a signature.
   • SignatureAuth.Key – the key associated with the key ID that is used to create a signature.
   • TokenBurstiness – this value defines the maximum number of requests that can be sent per second in asynchronous mode (100 by default).
   • TokenRate – this value defines the average number of requests that are sent per second in asynchronous mode (10 by default).
   • 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). Be aware that the ESPF sends requests to external systems in the order they are added here.

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.

To activate the ESPF components the evctl.pl script is used. To run the script, please connect to the server (where the ESPF provisioning is enabled) via SSH and run the commands named below:

Some changes in customer or product configuration in PortaBilling influence account configuration. For example, when a customer reaches their credit limit or depletes their available funds, their credit accounts no longer have access to services until the customer refills their balance.

If you must provision changes that are caused by changes in customer/product and/or service configuration for an account, please also run this command to enable the necessary handlers: ProductToAccountsDispatcher, CustomerToAccountsDispatcher, ServiceAttributeDispatcher.

In our example, it is necessary to provision account changes once a customer configuration changes. So these two commands must be run:

/home/provisioning-framework/utils/evctl.pl handler enable EventSender

/home/provisioning-framework/utils/evctl.pl handler enable CustomerToAccountsDispatcher

To meet the requirements 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

To activate an event type, run the following command:

/home/provisioning-framework/utils/evctl.pl type enable Account/SIMCardAssignment

Repeat this command for each event type to activate it. Change the event type name to the requisite one.

When subscribed for an event type, once a handler receives notifications upon event creation it processes them. To subscribe a handler for an event type, run this command:

/home/provisioning-framework/utils/evctl.pl handler sub EventSender Account/SIMCardAssignment

Repeat this command to subscribe a handler for other event types as well.

Alternatively, you can use the following command to subscribe the handler for all event types available for this handler:

/home/provisioning-framework/utils/evctl.pl handler sub EventSender all

Be aware that CustomerToAccountsDispatcher must also be subscribed for customer event types.

To make sure that a handler is now subscribed for a requisite event type, you execute the following command:

/home/provisioning-framework/utils/evctl.pl matrix

• “.” shows that the event handler can subscribe for an event;
• “+” shows that the event handler is already subscribed for an event.

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 view this event in the log file:

/porta_var/<server_IP_address>/log/provisioning.log

or see the provisioning status in the database (Account_Provisioning_Statuses table).