Event manager

The event manager feature is intended to provide data interchange between Plesk and external systems. It allows the Plesk administrator to assign a specific command (event handler) to be executed on a certain system event. The events that can be processed are listed in Table 2.1.

Table 2.1

Event (action) name	Description
`client_create`	Client account created
`client_update`	Client account updated
`client_delete`	Client account deleted
`domain_create`	Domain created
`domain_update`	Domain properties updated
`domain_delete`	Domain deleted
`subdomain_create`	Subdomain created
`subdomain_update`	Subdomain properties updated
`subdomain_delete`	Subdomain deleted
`phys_hosting_create`	Physical hosting created
`phys_hosting_update`	Physical hosting account updated
`phys_hosting_delete`	Physical hosting account deleted
`mailname_create`	Mail name created
`mailname_update`	Mail name updated
`mailname_delete`	Mail name deleted
`webuser_create`	Web user created
`webuser_update`	Web user properties updated
`webuser_delete`	Web user account deleted
`client_limits_update`	Client limits updated
`domain_limits_update`	Domain limits updated
`maillist_create`	Mailing list created
`maillist_update`	Mailing list updated
`maillist_delete`	Mailing list deleted
`cp_user_login`	User logged in to control panel
`cp_user_logout`	User logged out of control panel
`dl_user_update`	Domain user properties updated
`siteapp_install`	Site application installed
`siteapp_reconfigure`	Site application reconfigured
`siteapp_unchain`	Information about site application removed from database; however, the application still functions on the domain
`siteapp_uninstall`	Site application uninstalled
`siteapppkg_install`	Site application package added to application vault
`siteapppkg_uninstall`	Site application package removed from application vault

You can assign an event handler by defining a command line and parameters of the invoked utility and specifying a user, on behalf of which the event handler is executed. Instead of event handler options, the <parameter> templates that you can use are presented in Table 2.2.

Table 2.2

Component name/description	Command line parameter		Notes

Component name/description	Old component value	New component value	Notes
For 'client_create', 'client_update', and 'client_delete' events
Login Name	old_login_name	new_login_name	required
Contact Name	old_contact_name	new_contact_name	required
Company Name	old_company_name	new_company_name
Phone	old_phone	new_phone
Fax	old_fax	new_fax
E-mail	old_email	new_email
Address	old_address	new_address
City	old_city	new_city
State/Province	old_state_province	new_state_province
Postal/ZIP Code	old_postal_zip_code	new_postal_zip_code
Country	old_country	new_country
For 'domain_create', 'domain_update', and 'domain_delete' events
Domain Name	old_domain_name	new_domain_name	required
For 'subdomain_create', 'subdomain_update', and 'subdomain_delete' events
Subdomain Name	old_subdomain_name	new_subdomain_name	required
Parent Domain Name	old_domain_name	new_domain_name	required
FTP account	old_system_user_type	new_system_user_type
Subdomain owner's login name	old_system_user	new_system_user
Hard disk quota	old_hard_disk_quota	new_hard_disk_quota
SSI support	old_ssi_support	new_ssi_support
PHP support	old_php_support	new_php_support
CGI support	old_cgi_support	new_cgi_support
Perl support	old_mod_perl_support	new_mod_perl_support
Python support	old_mod_python_support	new_mod_python_support
ColdFusion support	old_coldfusion_support	new_coldfusion_support
ASP support	old_apache_asp_support	new_apache_asp_support
SSL support	old_ssl_support	new_ssl_support
For 'phys_hosting_create' and 'phys_hosting_update' events
Domain Name	old_domain_name	new_domain_name	required
IP Address	old_ip_address	new_ip_address
IP Type	old_ip_type	new_ip_type
System User	old_system_user	new_system_user
System User Password	old_system_user_password	new_system_user_password
Access to system	old_system_shell	new_system_shell
MS FrontPage Support	old_fp_support	new_fp_support
MS FrontPage over SSL Support	old_fpssl_support	new_fpssl_support
MS FrontPage Authoring	old_fp_authoring	new_fp_authoring
MS FrontPage Admin Login	old_fp_admin_login	new_fp_admin_login
MS FrontPage Admin Password	old_fp_admin_password	new_fp_admin_password
SSI Support	old_ssi_support	new_ssi_support
PHP Support	old_php_support	new_php_support
CGI Support	old_cgi_support	new_cgi_support
Perl Support	old_mod_perl_support	new_mod_perl_support
ASP Support	old_apache_asp_support	new_apache_asp_support
SSL Support	old_ssl_support	new_ssl_support
Web Statistics	old_web_statistics	new_web_statistics
Custom Error Documents	old_apache_error_documents	new_apache_error_documents
Hard Disk Quota	old_hard_disk_quota	new_hard_disk_quota
For 'phys_hosting_delete' event
Domain Name	old_domain_name	new_domain_name	required
For 'mailname_create' and 'mailname_delete' events
Mail name	old_mailname	new_mailname	required (in the format mailname@domain)
For 'mailname_update' event
Mail name	old_mailname	new_mailname	required (in the format mailname@domain)
Mailbox	old_mailbox	new_mailbox
Password	old_password	new_password
Mailbox Quota	old_mailbox_quota	new_mailbox_quota
Redirect	old_redirect	new_redirect
Redirect Address	old_redirect_address	new_redirect_address
Mail Group	old_mail_group	new_mail_group
Autoresponders	old_autoresponders	new_autoresponders
Mail User Control Panel Access	old_mail_controlpanel_access	new_mail_controlpanel_access
For 'webuser_delete' event
Domain Name	old_domain_name	new_domain_name	required
Web User Name	old_webuser_name	new_webuser_name	required
For 'webuser_create' and 'webuser_update' events
Domain Name	old_domain_name	new_domain_name	required
Web User Name	old_webuser_name	new_webuser_name	required
Web User Password	old_webuser_password	new_webuser_password
SSI Support	old_ssi_support	new_ssi_support
PHP Support	old_php_support	new_php_support
CGI Support	old_cgi_support	new_cgi_support
Perl Support	old_mod_perl_support	new_mod_perl_support
Python Support	old_mod_python_support	new_mod_python_support
ASP Support	old_apache_asp_support	new_apache_asp_support
Hard Disk Quota	old_hard_disk_quota	new_hard_disk_quota
For 'client_limits_update' event
Contact Name	old_contact_name	new_contact_name	required
Maximum Number of Domains	old_maximum_domains	new_maximum_domains
Maximum Amount of Disk Space	old_maximum_disk_space	new_maximum_disk_space
Maximum Amount of Traffic	old_maximum_traffic	new_maximum_traffic
Maximum Number of Web Users	old_maximum_webusers	new_maximum_webusers
Maximum Number of Databases	old_maximum_databases	new_maximum_databases
Maximum Number of Mailboxes	old_maximum_mailboxes	new_maximum_mailboxes
Mailbox Quota	old_maximum_mailbox_quota	new_maximum_mailbox_quota
Maximum Number of Mail Redirects	old_maximum_mail_redirects	new_maximum_mail_redirects
Maximum Number of Mail Groups	old_maximum_mail_groups	new_maximum_mail_groups
Maximum Number of Mail Autoresponders	old_maximum_mail_autorespon ders	new_maximum_mail_autorespon ders
Maximum Number of Mailing Lists	old_maximum_mail_lists	new_maximum_mail_lists
Maximum Number of Web Applications	old_maximum_tomcat_web_appli cations	new_maximum_tomcat_web_appli cations
Expiration Date	old_expiration_date	new_expiration_date
For 'domain_limits_update' event
Domain Name	old_domain_name	new_domain_name	required
Maximum Amount of Disk Space	old_maximum_disk_space	new_maximum_disk_space
Maximum Amount of Traffic	old_maximum_traffic	new_maximum_traffic
Maximum Number of Web Users	old_maximum_webusers	new_maximum_webusers
Maximum Number of Databases	old_maximum_databases	new_maximum_databases
Maximum Number of Mailboxes	old_maximum_mailboxes	new_maximum_mailboxes
Mailbox Quota	old_maximum_mailbox_quota	new_maximum_mailbox_quota
Maximum Number of Mail Redirects	old_maximum_mail_redirects	new_maximum_mail_redirects
Maximum Number of Mail Groups	old_maximum_mail_groups	new_maximum_mail_groups
Maximum Number of Mail Autoresponders	old_maximum_mail_autorespon ders	new_maximum_mail_autorespon ders
Maximum Number of Mailing Lists	old_maximum_mail_lists	new_maximum_mail_lists
Maximum Number of Web Applications	old_maximum_tomcat_web_appli cations	new_maximum_tomcat_web_appli cations
Domain Expiration Date	old_expiration_date	new_expiration_date
For 'maillist_create', 'maillist_update', and 'maillist_delete' events
Domain Name	old_domain_name	new_domain_name	required
Mailing list name	old_mail_list_name	new_mail_list_name	required
Mailing list enabled	old_mail_list_enabled	new_mail_list_enabled
For 'cp_user_login' and 'cp_user_logout' events
Contact Name	old_contact_name	new_contact_name
For 'dl_user_update' events
Allow domain user access	old_allow_domain_user_access	new_allow_domain_user_access
Login Name	old_login_name	new_login_name	required
Domain Name	old_domain_name	new_domain_name	required
Contact Name	old_contact_name	new_contact_name
Company Name	old_company_name	new_company_name
Phone	old_phone	new_phone
Fax	old_fax	new_fax
E-mail	old_email	new_email
Address	old_address	new_address
City	old_city	new_city
State/Province	old_state_province	new_state_province
Postal/ZIP Code	old_postal_zip_code	new_postal_zip_code
Country	old_country	new_country
For 'siteapp_install', 'siteapp_reconfigure', 'siteapp_unchain', and siteapp_uninstall' events
Site application package name	old_site_application_package_ name	new_site_application_package_ name	required
Domain type (domain or subdomain)	old_site_application_domain_type	new_site_application_domain_type	required
Installation path (`httpdocs` or `httpsdocs`)	old_site_application_directory	new_site_application_directory	required
Installation path within destination directory	old_site_application_installation_ prefix	new_site_application_installation_ prefix	required
For 'siteapppkg_install' and 'siteapppkg_uninstall' events
Site application package name	old_site_application_package_ name	new_site_application_package_ name	required

Example of adding custom event handler

Let us set up an event handler for the 'client creation', which accepts a client name as the first parameter, and the client's login as the second. For simplicity we will write a program in C, which will be further compiled to the client_create.exe executable file. The following is the source code used:

#include <stdio.h>

#include <tchar.h>

int _tmain(int argc, _TCHAR* argv[])

{

if (argc < 2) {

printf (_T ("Usage: eventtest filepath, args, ...\n"));

return 1;

}

FILE *f = _tfopen (argv[1], _T("a+"));

if (!f) {

printf (_T ("Can't open %s\n"), argv[1]);

return 1;

}

for (int i = 2; i < argc; ++i)

fprintf (f, _T ("arg %d: %s\n"), i - 2, argv[i]);

return 0;

}

This program prints some information to a file so that we could control its execution (we cannot output information to stdout/stderr, as it is executed in the background mode).

Suppose, that our handler is located in the directory %plesk_dir%admin\bin (%plesk_dir% is a system variable containing the Plesk installation path). Let us register it using several SQL queries. You can do that by opening a connection to the machine with running Plesk and starting a MySQL client.

To see the list of available actions:

SELECT * FROM actions;

To find out the ID for the required action ('client_create'):

SELECT id FROM actions WHERE name='client_create';

ID will be equal to 1.

Let's register our handler for the event 'client_create' (ID=1), the handler will be executed, for instance, on behalf of the user "Administrator":

mysql> insert into event_handlers (action_id,priority,user,command) values ('1','10','Administrator','"c:\Program Files\SWsoft\Plesk\admin\bin\client_create.exe" "c:\result.txt" "param1" "Param2" "Parameter with spaces" <new_login_name> <new_contact_name>');

In the command prompt you may see the parameters in the angle brackets <new_contact_name> and <new_login_name>. Before handler execution, they will be replaced with name and login of created client respectively. The entire list of available parameters is listed in the Table 2.2. Keep in mind that with the removal operations, the parameters of type new_xxx, contain an empty string. And with creation operations the parameters of type old_xxx contain an empty string.

Now if you login to Plesk and create a new client, specifying the value 'Some Client' in the Contact name field, and 'some_client' in the field Login, the handler will be invoked, and the corresponding records will be added to the c:\result.txt file:

arg 0: param1

arg 1: Param2

arg 2: Parameter with spaces

arg 3: some_client

arg 4: Some Client

If you want to specify one or several handlers more, repeat the actions above for another handler. Note, you can set the handlers execution sequence using the priority field of the table event_handlers, the handlers are executed in accordance with the priority (smaller value corresponds to higher priority).

Note: Microsoft Windows does not have any standard mechanism of retrieving arguments transferred to programs. For this reason, implementation of this mechanism is totally up to its developers. We recommend that you follow the rules, used in Microsoft C-runtime library. Also, we do not recommend using the cmd.exe utility for running scripts with parameters, as this utility does not always interpret the transferred parameters correctly.