The documentation below describes Maintenance Release %XX%. Click here for the documentation on the latest software version.
Custom Event Handler Configuration for Data Provisioning
Enable ESPF on the Configuration server
Create an event handler from scratch
Enable the handler you created
Enable the modified DemoHandler
Enable the trigger for the required event
Subscribe the event handler for the event
This chapter provides an example for how to configure a custom event handler for the External systems provisioning framework (ESPF) to provision an external system.
You can configure your event handler in two ways: either by developing your own handler from scratch or by modifying the DemoHandler supplied in PortaBilling®.
This chapter covers both cases. The configuration steps are named accordingly. Select the ones that are relevant.
Let’s say you configure ESPF to send a POST request to the external system each time an account’s balance changes in PortaBilling® (when either a service has been used or a payment made). The request will have the following information:
· The unique ID of the account database record (i_account);
· The current balance (current_balance);
· The previous balance (previous_balance).
Your configuration will likely differ from the one described in this example, but the general steps will be as follows:
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 Verify to verify the configuration.
6. Click Check/Apply to apply the new configuration.
All event handlers are located in the following folder on the server where you configured the ESPF instance:
/home/provisioning-framework/site_lib/Porta/Event/Handler/
We recommend that you modify DemoHandler.pm to your needs, since it is already registered in PortaBilling® and can be used immediately.
The event handler in our example is as follows:
package Porta::Event::Handler::DemoHandler;
use strict;
use warnings;
use Data::Dumper;
use Porta::Event::Constants qw(:status);
use base qw(Porta::Event::Handler);
# ------------------------------------------------------------------------------
# called by superclass to process one event from the queue
# queue -- Queue instance
# notification -- event to process
sub process_one {
my ( $self, $queue, $notification ) = @_;
my $event_name = $notification->{event}->type_object->name;
my $vars = $notification->{event}->variables;
$self->log_info( 'event %s', $event_name );
# make a SOAP request to fetch additional information
my $soap_client = $self->new_api_client();
return INTERNAL_FAILED if ( !$soap_client );
if ( exists $vars->{i_customer} ) {
$self->log_info( 'get_customer %d env %d', $vars->{i_customer}, $vars->{i_env} );
my $customer_info = $soap_client->get_customer( $vars->{i_customer}, $vars->{i_env} );
if ($customer_info) {
my $c_class_info = $soap_client->get_customer_class( $customer_info->{i_customer_class}, $vars->{i_env} );
$self->log_info(
'Customer #%d %s (class %s), balance %.4f %s',
$customer_info->{i_customer}, $customer_info->{name},
$c_class_info->{name},
$customer_info->{balance}, $customer_info->{iso_4217},
);
}
}
if ( exists $vars->{i_customer} ) {
$self->log_info( 'get_customer %d env %d', $vars->{i_customer}, $vars->{i_env} );
my $customer_info = $soap_client->get_customer( $vars->{i_customer}, $vars->{i_env} );
if ($customer_info) {
my $c_class_info = $soap_client->get_customer_class( $customer_info->{i_customer_class}, $vars->{i_env} );
$self->log_info(
'Customer #%d %s (class %s), balance %.4f %s',
$customer_info->{i_customer}, $customer_info->{name},
$c_class_info->{name},
$customer_info->{balance}, $customer_info->{iso_4217},
);
}
}
if ( exists $vars->{i_account} ) {
$self->log_info( 'get_account %d env %d', $vars->{i_account}, $vars->{i_env} );
my $account_info = $soap_client->get_account( $vars->{i_account}, $vars->{i_env} );
if ($account_info) {
$self->log_info(
'Account #%d %s, balance %.4f %s',
$account_info->{i_account}, $account_info->{id}, $account_info->{balance}, $account_info->{iso_4217},
);
}
}
return OK;
} ## end sub process_one
1;
You can create your own event handler from scratch (e.g., MyOwnHandler). In this case, add this handler to the folder with the handlers:
/home/provisioning-framework/site_lib/Porta/Event/Handler/
Register your event handler in the database
After you created your own handler, you must add it to the database for ESPF to recognize it.
1. Login to the master database via ssh.
2. Run the following command to create a record for your handler:
INSERT INTO Event_Handlers (i_event_handler, name, description) VALUES (1001,'MyOwnHandler','MyHandlerDescription');
where 1001 is the internal ID of your handler, MyOwnHandler is its name and MyHandlerDescription is the description of your handler.
NOTE: After the system update, you must manually restore your handler in the database.
Each time you introduce changes to the event handler you must restart the ESPF process:
sudo service provisioning restart
To enable your new handler, first insert information about it and the event type into the database.
1. Login to the master database via ssh.
2. Run the following command to create a record in the Event_Subscriptions table:
INSERT INTO Event_Subscriptions (i_event_type, i_event_handler) VALUES (132,1001);
where 132is the internal ID of the event type and 1001 is the internal ID of your handler.
NOTE: Use the Event_Types table to find the ID of the event type and the Event_Handlers table to find the ID of your handler in the database.
Enable your handler by running the following command:
/home/provisioning-framework/utils/evctl.pl handler enable MyOwnHandler
To enable the modified DemoHandler, use the following command:
/home/provisioning-framework/utils/evctl.pl handler enable DemoHandler
At this step, you enable provisioning events that your event handler monitors and provisions to the external system.
For this example, we enable the following events:
· Account/BalanceChanged
· Customer/BalanceChanged
· Invoice/AmountPaid/Changed
· Invoice/Adjustment/Changed
· PaymentTransaction/New
To enable an event, run the following command:
/home/provisioning-framework/utils/ evctl.pl type enable Account/BalanceChanged
where Account/BalanceChanged is the name of the event.
Repeat the command to enable all other events.
Find the full list of supported events in the External Systems Interfaces guide.
/home/provisioning-framework/utils/evctl.pl handler sub DemoHandler Account/BalanceChanged
Repeat this command to subscribe the handler for other events as well.
Check that the required handler is enabled and subscribed to for all specified events:
/home/provisioning-framework/utils/evctl.pl matrix
· “.” shows that the event handler can subscribe for the event;
· “+” shows that the event handler is already subscribed for the event.
When an account’s balance changes, you see this event in the log file:
/porta_var/<server_IP_address>/log/provisioning.log