Scripting on Items

Items support three scripting hooks — one before the donor completes selection, one that validates at submit time, and one after the transaction is saved. Together these give you fine-grained control over every item’s behavior in a transaction.

For the variables available in each hook, see Scripting Contexts.

Pre-Processing Script

When it runs: When the donor selects this item on the form — at the moment it is added to their in-progress transaction.

What it can do:

  • Set default custom field values based on the donor’s record or other items already in the cart
  • Show or hide other items using the form’s item visibility rules
  • Apply a default fund designation based on the donor’s history
  • Calculate a suggested amount

Example — set default fund from donor history:

import "donationOrderItemService";
var lastFund = donationOrderItemService.getLastFundForContact(contact, account);
if (lastFund != null) {
    orderItem.fund = lastFund;
}

Validation Script

When it runs: When the donor clicks submit, before the transaction is saved — runs once per Order Item.

Return value: Return null or an empty string to allow submission. Return a non-empty string to block submission and show that string as an error message to the donor.

What it can do:

  • Enforce minimum amounts that depend on other data in the transaction
  • Validate fund selection combinations
  • Check that required attendee information is complete
  • Enforce capacity limits from external systems

Example — enforce minimum per designation:

if (orderItem.fund != null && orderItem.extendedPrice < 25) {
    return 'Minimum gift to ' + orderItem.fund.name + ' is $25.';
}
return null;

Post-Processing Script

When it runs: After the transaction is successfully saved — runs once per Order Item.

What it can do:

  • Perform item-specific post-save actions independent of the form-level script
  • Generate a unique identifier (ticket number, voucher code, confirmation ID)
  • Send an item-specific notification to a third party
  • Update inventory or capacity records in an external system
  • Create a linked record (for example, a task or opportunity)

Example — send notification for a specific item:

import "mailer";
mailer.sendEmail(
    orderItem.orderableItem.get('NotificationEmail').value,
    'New registration: ' + orderItem.orderableItem.name,
    contact.firstName + ' ' + contact.lastName + ' registered on ' +
    purchaseOrder.orderReceived
);

Where Scripts Are Configured

All three scripts are on the Integration tab of the Item edit page:

  • Pre-Processing Script — the customEL field
  • Validation Script — the validationEL field
  • Post-Processing Script — the persistEL field

The Scripting Guide covers the full language reference, available services, and patterns.