Custom Event Handler Configuration for Data Provisioning

Example

Enable ESPF on the Configuration server

Create the event handler

Modify DemoHandler

Create an event handler from scratch

Restart the ESPF process

Enable the event handler

Enable the handler you created

Enable the modified DemoHandler

Enable the trigger for the required event

Subscribe the event handler for the event

Make tests

 

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.

Example

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:

Enable ESPF on the Configuration server

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.

 Create the event handler

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/

Modify DemoHandler

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;

Create an event handler from scratch

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, has_targets) VALUES (1001,'MyOwnHandler','MyHandlerDescription',0);

 

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.

Restart the ESPF process

Each time you introduce changes to the event handler you must restart the ESPF process:

 

sudo service provisioning restart

Enable the event handler

Enable the handler you created

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 132 is 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

Enable the modified DemoHandler

To enable the modified DemoHandler, use the following command:

 

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

Enable the trigger for the required event

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.

Subscribe the event handler for the event

/home/provisioning-framework/utils/evctl.pl handler sub DemoHandler Account/BalanceChanged

 

Repeat this command to subscribe the handler for other events as well.

Make tests

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