Events, Scheduled Jobs and Utils Script Includes

What it is

Three building blocks let an application do server work outside a single form save. An event announces that something happened so other logic can respond. A scheduled script execution (scheduled job) runs a script at set times. A Utils script include holds shared functions that both of them, and any other server script, can call.

The design question is always: does the work start when something happens (event) or at a time (scheduled job)?

How it works

Registering and firing an event

Every event is first defined in the Event Registry (System Policy > Events > Registry). In a scoped application the event name begins with the scope namespace, for example x_acme_travel.request.approved.

A server script fires the event with gs.eventQueue(), passing the event name, a GlideRecord and two optional parameters.

// after business rule on x_acme_travel_request
if (current.state.changesTo('approved')) {
    gs.eventQueue('x_acme_travel.request.approved', current,
        current.requested_for, current.number);
}

The event is written to the event queue and processed shortly after, not inside the user's transaction. That keeps the save fast.

Responding to an event

In a script action, current is the record passed to gs.eventQueue() and the extra values are event.parm1 and event.parm2.

// script action for x_acme_travel.request.approved
var util = new TravelUtils();
util.bookTrip(current, event.parm1);

Because one event can have several responders, a single gs.eventQueue() call can both send email and run a script.

Scheduled script executions

A scheduled script execution is created as an application file, or under System Definition > Scheduled Jobs. It holds the script and the schedule.

A scheduled job has no current record. It queries the records it needs, for example every request still open past its travel date.

A job can fire an event for each record it finds, which lets notifications and script actions handle the response.

Utils script includes

A script include stores reusable server code that runs only when called. A Utils script include groups helper functions for the application, often named after it, such as TravelUtils.

var TravelUtils = Class.create();
TravelUtils.prototype = {
    initialize: function() {},
    isOverBudget: function(req) {
        return req.estimated_cost > req.budget;
    },
    type: 'TravelUtils'
};

Business rules, script actions and scheduled jobs all call new TravelUtils(). One fix in the script include then changes every caller.

How the exam asks about this

• "Send an email and update a related record whenever a request is approved." Fire one event with gs.eventQueue and add a notification and a script action.
• "Every night, close requests older than 90 days." A scheduled script execution that queries and updates them.
• "Three business rules repeat the same calculation." Move it into a Utils script include.