System Events

The system events allow you to create tasks for server-side script execution, or notification sending at a specified point in time. These are the most common use cases of system events. You can also use one event register for the needs listed above.

tip

Role required: admin.

To use the system events in your tasks, you need to create an event register record.

Then, you can handle it in one of the following ways:

1. Define a server script for a system event by creating a record in the Event Script Actions (sys_event_script_action) table.
2. Define a notification rule to send notifications.
3. You can combine the options listed above so that the event register record triggers actions and sends notifications at the same time.

Event structure

Create an event

---

To create an event, use the server-side API methods ss.eventQueue or ss.eventQueueScheduled. Create an event as described in the referenced articles. As a result, new records in the Event (sys_event) table will be created.

caution

You cannot create, edit, or delete records in the Events (sys_event) table manually. Only users with the admin role can read them.

To read event records, navigate to System Events → Events.

Event form fields

Field	Description
Name	The name of the record called from the Event Register (sys_event_register) table.
Instance	The ID of the record object. When creating an event with the ss.eventQueue or ss.eventQueueScheduled method, pass on the Record object. The object ID will be saved in this field. Call this value in the Event Script Action (sys_event_script_action) script body: event.instance.
Table	A reference to the record table that was passed when the event was created. This field is populated automatically.
Process started at	The date and time when the system event execution started. As for the scheduled events, this field is populated with the value passed by the parameter of the ss.eventQueueScheduled method. The date and time of the Event (sys_event) script execution.
Process finished on	The date and time when the system event execution finished.
Param1-5	The string parameters that can be transmitted to the specified Event (sys_event) record via the SimpleOne server-side API (ss.eventQueue and ss.eventQueueScheduled methods).
State	The event state: Ready – event is pending for execution. Execution time is specified in the Process started at field. Processing – the event is being executed. Processed – the event has been processed. Processing time is specified in the Process finished on field. Error – the event processing has failed. Processing time is specified in the Process finished on field. Canceled – the event will not process after the state changed from Ready to this one.
Processing duration, ms	The duration of the system event processing in milliseconds.
User	This field is always populated with the system user (which can also be displayed as 100000000000000000 on the forms). The system executes the script on behalf of this user.

Related lists are bound with the event record and contain the following records:

• The list of all related event register records from the Event Register (sys_event_register) table.
• The list of all the scripts from the Event Script Action (sys_event_script_action) table that have references to the current record.

Event Register

To create an event register, complete the following steps:

1. Navigate to System Events → Event Registers.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

Event Register form fields

Field	Mandatory	Description
Name	Y	Specify the name of the event register. The Event (sys_event) record of this register contains this value in its Name field. Name is the first parameter of the eventQueue method.
Table	Y	Specify the table that contains records related to the events. To trigger email sending with this record, ensure that the value in the Table field in the Notification Rule record is the same as in this event register record.
Description	N	Add a description for the event register record.
Disable script logging	N	Select the checkbox to disable script execution logging to the Script Logs (sys_log_script) table when the related event begins.

The Related Lists area bound with the event register record contains the following records:

• A list of all the scripts from the Event Script Action (sys_event_script_action) table that have references to the current record.
• A list of all Notification Rules triggered by the record of the current event register.

Event Script Action

To create an event register, complete the following steps:

1. Navigate to System Events → Event Scripts.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

Event Script Action form fields

Field	Description
Name	Specify the name of the event script action.
Event register record	The reference to the record in the Event Register (sys_event_register) table.
Active	Select this checkbox to activate the script.
Script	Specify the script that is executed when the event occurs.

note

In the Event Script Action, the event object is available. The object is the instance of the SimpleRecord class and refers to a record from the Event (sys_event) table that initiated the script. To get the values of the record fields, use the dot-notation for the event object. To do so, use properties with the names corresponding to the names of the record fields. For example:

const currentRecord = new SimpleRecord(event.table_id.name);
currentRecord.get(event.instance);
if (String(currentRecord.state) !== event.param_1) {
    currentRecord.state = event.param_1;
    currentRecord.update();
}

You can also update the parameters (Param1-5) of the event object with the Event Script Action.

Script example

(function executeEventScript(event) {
  const lastComment = new SimpleRecord('sys_activity_feed_item');
  lastComment.addQuery('table_id', '156950677111866258'); // itsm_incident
  lastComment.addQuery('record_id', event.instance);
  lastComment.addQuery('type_id.name', '!=', 'history');
  lastComment.orderByDesc('sys_created_at');
  lastComment.setLimit(1);
  lastComment.query();
  event.param_5 = lastComment.next();
})(event);

Event Archives

To reduce the system load when processing the Events (sys_event) table, the mechanism archives the events that have already been processed into the Event Archive (sys_event_archive) table. Archiving is executed regularly at 01:00, 02:00, 03:00, 04:00, 05:00 and 06:00 UTC.

To open the Event Archive, navigate to System Events → Event Archive. To search for a specific event, use search boxes or the condition builder.