Version 5.2

Business Logic Hooks

Custom Logic (or "Business Logic Hooks") allows you to add functionality to certain actions, such as before a bean save, in an upgrade-safe manner. This is accomplished by defining hooks, which are placed in the custom/ directory, which will be called in the SugarBean in response to events at runtime. Because the code is located separate from the core SugarCRM code, it is upgrade-safe.

See this SugarForge project for a complete example of a useful business hook.

Hook Definition

The code that declares your custom logic is located in: custom/modules/<CURRENT_MODULE>/logic_hooks.php. The format of the declaration follows.

$hook_version

All logic hooks should define the $hook_version that should be used. Currently, the only supported $hook_version is 1.

$hook_version = 1

$hook_array

Your logic hook will also define the $hook_array. $hook_array is a two dimensional array:

o	name: the name of the event that you are hooking your custom logic to

o	array: an array containing the parameters needed to fire the hook

A best practice is for each entry in the top level array to be defined on a single line to make it easier to automatically replace this file. Also, logic_hooks.php should contain only hook definitions; the actual logic is defined elsewhere.

For example:

$hook_array['before_save'][] = Array(1, test, 'custom/modules/Leads/test12.php', 'TestClass', 'lead_before_save_1');

Available Hooks

The hooks are processed in the order in which they are added to the array. The first dimension is simply the current action, for example before_save. The following hooks are available:

Application hooks

These hooks do not make use of the $bean argument.

o	after_ui_frame

o	Fired after the frame has been invoked and before the footer has been invoked

o	Available in version 4.5.0 and later

o	after_ui_footer

o	Fired after the footer has been invoked

o	Available in version 4.5.0 and later

o	server_round_trip

o	Fired at the end of every SugarCRM page

o	Available in version 4.5.0 and later

Module hooks

o	before_delete

o	Fired before a record is deleted

o	Available in version 4.5.0 and later

o	after_delete

o	Fired after a record is deleted

o	Available in version 4.5.0 and later

o	before_restore

o	Fired before a record is undeleted

o	Available in version 4.5.0 and later

o	after_restore

o	Fired after a record is undeleted

o	Available in version 4.5.0 and later

o	after_retrieve

o	Fired after a record has been retrieved from the database. This hook does not fire when you create a new record.

o	Available in version 4.5.0 and later

o	before_save

o	Fired before a record is saved. Note: With certain modules, like Cases and Bugs, the human-readable ID of the record (like the case_number field in the Case module), is not available within a before_save call. This is because this business logic simply hasn't been executed yet.

o	Available in version 4.5.0 and later

o	after_save

o	Fired after a record is saved. Note: With certain modules, like Cases and Bugs, the human-readable ID of the record (like the case_number field in the Case module), is not available within a before_save call. This is because this business logic simply hasn't been executed yet.

o	Available in version 4.5.0 and later

o	process_record

o

Fired immediately prior to the database query resulting in a record being made current. This gives developers an opportunity to examine and tailor the underlying queries. This is also a perfect place to set values in a record’s fields prior to display in the DetailView or ListView. This event is not fired in the EditView.

o	Available in version 4.5.0 and later

Hooks for Users module

o	before_logout

o	Fired before a user logs out of the system

o	Available in version 4.5.0 and later

o	after_logout

o	Fired after a user logs out of the system

o	Available in version 4.5.0 and later

o	after_login

o	Fired after a user logs into the system.

o	Available in version 4.5.0 and later

o	after_logout

o	Fired after a user logs out of the system.

o	Available in version 4.5.0 and later

o	before_logout

o	Fired before a user logs out of the system.

o	Available in version 4.5.0 and later

o	login_failed

o	Fired on a failed login attempt

o	Available in version 4.5.0 and later

Options array

The second dimension is an array consisting of:

o	Processing index => For sorting before exporting the array

o	Label/type => Some string value to identify the hook

o	PHP file to include => Where your class is located. Insert into ./custom.

o	PHP class the method is in => The name of your class

o	PHP method to call => The name of your method

Thus a given class may have multiple methods to fire, each within a single upgrade-safe PHP file.

The method signature for version 1 hooks is:

function NAME(&$bean, $event, $arguments)

 

Where:

o	$bean - $this bean passed in by reference.

o	$event - The string for the current event (i.e. before_save)

o	$arguments - An array of arguments that are specific to the event.

Packaging Custom Logic Hooks

There are no directives in the manifest.php file to safely install business logic hooks. You have to do it via the pre_install or post_install scripts. To do this, create a top-level directory in your installer called 'scripts' and in that directory place a file called pre_install.php.

A pre_install file could look like this:

<?php

if(!defined('sugarEntry'))define('sugarEntry', true);

function pre_install() {

   require_once('include/utils.php');

   check_logic_hook_file("Accounts", "after_retrieve", array(1, "update_description",
"include/FCKEditor/updateDescription.php", "updateDescription",
"updateDescription"));

}

?>

The check_logic_hook_file() command is looking for three things. First is the module that you want this hook to affect, in this case "Accounts". The second is the hook itself, in this case "after_retrieve". The third part is an array which mirrors the $hook_array like this:

o	Processing index => 1

o	Label/Type => update_description

o	PHP file to include => include/FCKEditor/updateDescription.php

o	PHP class the method is in => updateDescription

o	PHP method to call => updateDescription

Of course you can call the check_logic_hook_file() command as many times as you want. The logic behind the command check to make sure that your hook isn't already set and if it is then it replaces it, making it pretty upgrade-safe. If you have any questions about installing logic hooks look for me in the forums.

Using Custom Logic Hooks

Above we showed how to create a custom_logic_hook that runs the function updateDescription() from the class updateDescription (those don't have to be the same, they just are in this example) in the PHP file updateDescription.php. Below is the actual script from that PHP file.

class updateDescription {

function updateDescription(&$bean, $event, $arguments) {

$bean->description = html_entity_decode($bean->description);

$bean->fetched_row['description'] = $bean->description;

}

}

You see that the $bean is fed into the function and allows access to all of the fields for the currently selected record. Any changes you make to the array will be reflected in the actual data. For example in this script we are changing the description field. As you see above there is

$event is set to whatever event is currently running like after_retrieve or before_delete.

Tips & Pitfalls

A few cautions around using logic hooks apply:

o	It is not possible to hook logic to beans being displayed in a SubPanel.

o	There is no bean that fires specifically for the ListView, DetailView or EditViews user interface events. Use either the 'process_record' or 'after_retrieve' logic hooks.

o	In order to compare new values with previous values to see whether a change has happened, use $bean->fetched_row['<field>'] (old value) and $bean-><field> (new value) in the before_save logic hook.

o

Make sure that the permissions on your logic_hooks.php file and the class file that it references are readable by the Web server. If this isn’t done, the files will not be read by the SugarCRM application and your business logic extensions will not work. For example, for *nix developers who are extending the Tasks logic, that means you should do the following command for the logic_hooks file and the same command for the class file that will be called.

[sugarcrm]# chmod +r custom/modules/Tasks/logic_hooks.php

 

o	Make sure that the entire custom/ directory is writable by the Web server, otherwise the logic hooks code will not work properly.