Difference between revisions of "Freeside:3:Documentation:Developer/FS/part event"

Revision as of 07:42, 24 March 2015

NAME

FS::part_event - Object methods for part_event records

SYNOPSIS

 use FS::part_event;

 $record = new FS::part_event \%hash;
 $record = new FS::part_event { 'column' => 'value' };

 $error = $record->insert( { 'option' => 'value' } );
 $error = $record->insert( \%options );

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

 $error = $record->do_event( $direct_object );
 

DESCRIPTION

An FS::part_event object represents an event definition - a billing, collection or other callback which is triggered when certain customer, invoice, package or other conditions are met. FS::part_event inherits from FS::Record. The following fields are currently supported:

eventpart - primary key; agentnum - Optional agentnum (see FS::agent); event - event name; eventtable - table name against which this event is triggered: one of "cust_main", "cust_bill", "cust_statement", "cust_pkg", "svc_acct".; check_freq - how often events of this type are checked; currently "1d" (daily) and "1m" (monthly) are recognized. Note that the apprioriate freeside-daily and/or freeside-monthly cron job needs to be in place.; weight - ordering for events; action - event action (like part_bill_event.plan - eventcode plan); disabled - Disabled flag, empty or `Y'

METHODS

new HASHREF

Creates a new invoice event definition. To add the invoice event definition to the database, see "insert".

Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.

insert [ HASHREF ]

Adds this record to the database. If there is an error, returns the error, otherwise returns false.

If a list or hash reference of options is supplied, part_export_option records are created (see FS::part_event_option).

delete

Delete this record from the database.

replace OLD_RECORD [ HASHREF | OPTION => VALUE ... ]

Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.

If a list or hash reference of options is supplied, part_event_option records are created or modified (see FS::part_event_option).

check

Checks all fields to make sure this is a valid invoice event definition. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

_rebless

Reblesses the object into the FS::part_event::Action::ACTION class, where ACTION is the object's action field.

part_event_condition

Returns the conditions associated with this event, as FS::part_event_condition objects (see FS::part_event_condition)

new_cust_event OBJECT, [ OPTION => VALUE ]

Creates a new customer event (see FS::cust_event) for the provided object.

The only option allowed is 'time', to set the "current" time for the event.

agent

Returns the associated agent for this event, if any, as an FS::agent object.

templatename

Returns the alternate invoice template name, if any, or false if there is no alternate template for this event.

targets OPTIONS

Returns all objects (of type FS::eventtable, for this object's eventtable) eligible for processing under this event, as of right now. The FS::cust_event object used to test event conditions will be included in each object as the 'cust_event' pseudo-field.

This is not used in normal event processing (which is done on a per-customer basis to control timing of pre- and post-billing events) but can be useful when configuring events.

initialize PARAMS

Identify all objects eligible for this event and create FS::cust_event records for each of them, as of the present time, with status "initial". When combined with conditions that prevent an event from running more than once (at all or within some period), this will exclude any objects that met the conditions before the event was created.

If an FS::part_event object needs to be initialized, it should be created in a disabled state to avoid running the event prematurely for any existing objects. initialize will enable it once all the cust_event records have been created.

This may take some time, so it should be run from the job queue.

CLASS METHODS

eventtable_labels

Returns a hash reference of labels for eventtable values, i.e. 'cust_main'=>'Customer'

eventtable_pkey_sql

Returns a hash reference of full SQL primary key names for eventtable values, i.e. 'cust_main'=>'cust_main.custnum'

eventtable_pkey

Returns a hash reference of full SQL primary key names for eventtable values, i.e. 'cust_main'=>'custnum'

eventtables

Returns a list of eventtable values (default ordering; suited for display).

eventtables_runorder

Returns a list of eventtable values (run order).

eventtables_cust_join

Returns a hash reference of SQL expressions to join each eventtable to a table with a 'custnum' field.

eventtables_custnum

Returns a hash reference of SQL expressions for the 'custnum' field when eventtables_cust_join is in effect. The default is "$eventtable.custnum".

check_freq_labels

Returns a hash reference of labels for check_freq values, i.e. '1d'=>'daily'

actions [ EVENTTABLE ]

Return information about the available actions. If an eventtable is specified, only return information about actions available for that eventtable.

Information is returned as key-value pairs. Keys are event names. Values are hashrefs with the following keys:

description

; eventtable_hashref:; option_fields:; default_weight:; deprecated

ADDING NEW EVENTTABLES

To add an eventtable, you must:

Add the table to "eventtable_labels" (with a label) and to "eventtable_pkey" (with its primary key).; If the table doesn't have a "custnum" field of its own (such as a svc_x table), add a suitable join expression to eventtables_cust_join and an expression for the final custnum field to eventtables_custnum.; Create a method named FS::cust_main->$eventtable(): a wrapper around qsearch() to return all records in the new table belonging to the cust_main object. This method must accept 'addl_from' and 'extra_sql' arguments in the way qsearch() does. For svc_ tables, wrap the svc_x() method.; Add it to FS::cust_event->join_sql and search_sql_where so that search/cust_event.html will find it.; Create a UI link/form to search for events linked to objects in the new eventtable, using search/cust_event.html. Place this somewhere appropriate to the eventtable.

See FS::part_event::Action for more information.

all_actions [ EVENTTABLE ]

Returns a list of just the action names

process_initialize 'eventpart' => EVENTPART

Job queue wrapper for "initialize". EVENTPART identifies the FS::part_event object to initialize.

SEE ALSO

FS::part_event_option, FS::part_event_condition, FS::cust_main, FS::cust_pkg, FS::svc_acct, FS::cust_bill, FS::cust_bill_event, FS::Record, schema.html from the base documentation.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 364:

=cut found outside a pod block. Skipping to next block.

Around line 523:

You forgot a '=back' before '=head1'

Around line 594:

'=item' outside of any '=over'