SuiteScript 2.1 Event Subscriber Scripts Setup Guide

SuiteScript 2.1 Event Subscriber scripts run asynchronously after supported record events and are intended for follow-up work that need not finish before the originating operation completes. This guide covers documented use cases, the required script and SDF definition files, subscription criteria, and the SuiteCloud project deployment sequence.

What are Event Subscriber scripts?

Event Subscriber scripts are server scripts that run asynchronously after supported events occur. They support record events, including events in which a record of a selected type is created, updated, or deleted.

The timing is the defining characteristic. An Event Subscriber script runs after the originating operation is complete, so it is suited to processing that does not need to finish before that operation completes. The subscription criteria in the Event Subscriber definition determine which supported events trigger the script.

This script type is therefore a fit when the record operation can complete first and the remaining work can occur afterward. Oracle identifies three core uses:

• Send notifications after subscribed events.
• Update related data after record changes.
• Start external or long-running processing without delaying the record operation.

For example, a script can send a notification after an invoice is created. It can also update related information after a record changes.

How does this differ from a User Event script?

The documented distinction is when the script runs. User Event scripts run during record processing, whereas Event Subscriber scripts run after the originating operation is complete.

That distinction should drive the design choice. Use an Event Subscriber script for follow-up processing that does not need to finish before the originating record operation completes. If the work must occur during record processing, this script type does not provide that timing model.

What files are required for an Event Subscriber script?

An Event Subscriber implementation requires two files in a SuiteCloud project: the SuiteScript file that contains the script and an Event Subscriber SDF object definition that subscribes it to events.

The script file has two required identifying elements: the Event Subscriber script-type declaration and the handle(options) entry point.

@NScriptType EventSubscriber
handle(options)

The SDF object definition is equally important because it connects the script file to its subscriptions. A script file alone does not express which events should invoke the script; the definition must reference the file and include one or more subscription criteria.

How do subscription criteria control execution?

Subscription criteria determine which supported events trigger the Event Subscriber script. The source material describes supported record events such as creation, update, and deletion of a record of a selected type.

This makes the Event Subscriber definition part of the implementation rather than a separate administrative detail. The script file supplies the SuiteScript logic, while the definition identifies the events to which that logic subscribes.

Before deployment, confirm that the definition contains at least one criterion and that it references the intended script file. The documented requirements do not describe every possible criterion configuration, event payload, or API behavior, so implementation work should stay within the supported event subscriptions required by the definition.

What is the deployment sequence?

The required setup sequence is straightforward:

1. Create the Event Subscriber script file.
2. Create an Event Subscriber definition that references that file.
3. Add one or more subscription criteria to the definition.
4. Add both files to a SuiteCloud project.
5. Deploy the project to the target account.

The order matters because the definition references the script file. Both artifacts are then added to the same SuiteCloud project and deployed to the target account.

This workflow also separates two decisions that should be made together: what the handle(options) logic will do after an event, and which subscribed events are allowed to invoke it. For notification use cases, the script can perform the notification after the subscribed event. For related-data use cases, it can update the related information after the record change. For external or long-running work, it can start that processing without delaying the originating record operation.

Who This Affects

• SuiteCloud project contributors: They must create and deploy both the SuiteScript 2.1 script file and the Event Subscriber SDF object definition.
• Teams implementing notifications: They can use this script type for notifications after subscribed events, such as an invoice creation event.
• Teams maintaining related data: They can use follow-up processing to update related information after record changes.
• Teams starting external or long-running processing: They can begin that work after the originating operation rather than requiring it to finish first.

Key Takeaways

• Event Subscriber scripts are asynchronous server scripts that run after supported record events.
• Supported record-event examples include creation, update, and deletion of a record of a selected type.
• Use this script type for follow-up work that does not need to finish before the originating record operation completes.
• The script file must use SuiteScript 2.1, declare @NScriptType EventSubscriber, and define handle(options).
• The Event Subscriber SDF object definition must reference the script file and include one or more criteria identifying subscribed events.
• Add both files to a SuiteCloud project and deploy the project to the target account.