Event Handlers

Event Handlers are scripts that run automatically when entities in DonorPoint are created, loaded, inserted, or updated. They are the primary mechanism for applying account-specific business logic to every record of a given type — without modifying any code.

How Event Handlers Work

An Event Handler links a named event to a Script Module. When DonorPoint performs the corresponding operation on any entity of the named type, the script runs automatically.

Event Handlers are configured on the Integration tab in the DonorPoint sidebar, and are scoped to your specific account.

Event Naming Convention

Event names follow this pattern: {prefix}{EntityClassName}

Prefix	When It Fires
`onCreate`	When a new entity is created in memory (before saving)
`postLoad`	After an entity is loaded from the database
`postInsert`	After a new entity is saved to the database
`postUpdate`	After an existing entity is updated in the database

Entity Class Names

DonorPoint class names (for historical reasons) sometimes differ from their display names:

Display Name	Class Name	Example Event Name
Page / Form	Campaign	`postInsertCampaign`
Transaction	PurchaseOrder	`postInsertPurchaseOrder`
Contact	Contact	`postInsertContact`
Organization	Organization	`postUpdateOrganization`
Fund	Fund	`postInsertFund`
Volunteer Record	VolunteerInstance	`postInsertVolunteerInstance`
Recurring Donation	RecurringDonationInstance	`postInsertRecurringDonationInstance`

For a complete list of entity class names, see the DonorPoint API Reference.

Variables Available in Event Handler Scripts

When a Script Module runs as an Event Handler, the following variables are automatically injected:

Variable	Description
`this`	The entity that triggered the event
`{entityName}Home`	The entity’s Home object (e.g., `campaignHome`, `purchaseOrderHome`)
`user`	The currently logged-in user (UserAccount)
`account`	The current account
`log`	Logger for debug output
`elProcessor`	EL evaluation utilities
`messages`	Externalized text
`ReferenceData`	System-wide reference values

Note: The user variable may be null for system-generated events (e.g., scheduled jobs or webhook calls). Always guard against null: if (user != null) { ... }

Creating an Event Handler

Go to Integration in the sidebar and select Event Handlers.
Click Create New Event Handler.
Enter the Name (the event name, e.g., postInsertContact).
Select the Script Module to run.
Ensure Active is checked.
Save.

Example: Send a Custom Email After Every New Donation

// Script Module: "SendThankYouEmail"
// Used by Event Handler: postInsertPurchaseOrder

import "mailer";

// Only send for RECEIVED transactions (not pledges or adjustments)
if (this.type == 'RECEIVED' && this.status == 'ACTIVE') {
    var campaign = this.campaign;
    var contact = this.contact;
    
    if (contact != null && contact.email != '') {
        mailer.sendEmail(
            contact.email,
            'Thank you for your gift!',
            'Dear ' + contact.firstName + ', your gift of $' + this.amount + ' was received.'
        );
    }
}

Example: Set a Custom Field on New Contacts

// Script Module: "SetDefaultDepartment"
// Used by Event Handler: postInsertContact

import "contactService";

// Set a default value for a custom field
var dept = this.get('Department');
if (dept == null || dept.value == '') {
    // Set via service call — this persists the change
    contactService.setCustomProperty(this, 'Department', 'General');
}

Multiple Event Handlers per Event

Multiple Event Handlers can be registered for the same event name. They are executed in the order they appear in the Event Handlers list. To control execution order, use the list re-order controls.

Deactivating Event Handlers

Uncheck the Active checkbox to disable an Event Handler without deleting it. This is useful during testing or troubleshooting.

Troubleshooting

If an Event Handler script fails, the error is logged to the DonorPoint server log with the script name, error message, and line number. Contact help@donorpoint.com to request a log review if an Event Handler is not behaving as expected.

« Integrations

Scripting Guide »