Versions Compared

Old Version 3

changes.mady.by.user Dina Baksheeva

Saved on

compared with

New Version Current

changes.mady.by.user Dina Baksheeva

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Merged branch "DOC0001203" into parent

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 both the needs listed above.

Tip

Role required: admin.

To use the system events in your tasks, you need to create complete the following steps:

  1. Create an event register record.
After this, you can handle it in one of these ways
  2. Define a server script for a system event by creating a record in the Event Script Actions (sys_event_script_action) dictionary table.
  3. Define a notification rule to send notifications.
  4. You can combine the options listed above so that the event register record trigger triggers actions and send sends notifications at the same time.

Event structure

Image RemovedImage Added

Create an event

To create an event, use the server-side API methods ss.eventQueueor 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.

tip
Note

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

Role required: admin.

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

Anchor
Event Record
Event Record
Event form fields

This field is

always

populated with the system user (which can also be displayed as 100000000000000000 on the forms).

This is the user

The system executes the script on behalf of

which the event should be executed. Information about the event originator (a user on behalf of which this event has been created) is written down to the Created by field

this user. 

Field

Description

Name

The name of the record called from the Event Register (sys_event_register) table.

Instance

The ID of the Record record object.

When creating an event via calling methods with the ss.eventQueue or ss.eventQueueScheduled method, you have to pass  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 at when the time the event was created. This field is populated automatically.

Process started at

The date and time of when the system event execution startstarted. As for the scheduled events, this field is populated with the value passed by the parameter of the ss.eventQueueScheduled method method.

The date and time of the Event (sys_event) script execution.

Process finished on

The date and time of when the system event execution finishfinished.

Param_1...Param_ Param1-5

The string parameters that can be

transmitted

passed to the

specified 

specified Event (sys_event)record via the SimpleOne server-side API (ss.eventQueue and ss.eventQueueScheduled methods).

Info

The maximum length of a string parameter is 4000 symbols. All symbols above this limit are cut in the Event record. The data of the record from which the string parameters were passed is not changed.


State

The event state:

  • Ready – event is pending for execution. Execution time is specified in the Process finished onstarted 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 have has failed. Processing time is specified in the Process finished on field.
  • Canceled – the event will not process after changing the states state changed from the Ready state to this one.

Processing duration, ms

The duration of the system event processing ( in milliseconds).

User

The script specified in the Event Script Action record will be executed with the permissions of this user, and the ACL restrictions will also be taken into account. 

Info

Related lists are bound with the event record containing 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 are referenced table that have references to the current record.

Anchor
Event Register
Event Register
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 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)

called for

record of this register

contain

contains this value in

the

its Name field.

Info

Name is the first parameter of the eventQueue method.


TableY

Specify the table that

contain records

contains records related to the events. 

If you are going to

To trigger email sending with this record,

then make sure

ensure that the value in the Table field in the Notification Rule record is the same as in this event register record.

DescriptionNAdd a description for the event register record
description
.
Disable script loggingN

Select the checkbox to disable script execution logging to the Script Logs (sys_log_script) table when the related event begins.

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

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

Anchor
Event Script Action
Event Script Action
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 exit to apply the changes.

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.

ActiveSelect this checkbox to activate the script.

Script

Specify the script that is executed when the event occurs.

Info

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

Code Block
languagejs
themeEclipse
linenumberstrue
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.

Code Block
languagejs
themeEclipse
titleScript example
linenumberstrue
(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);



Table of Contents
absoluteUrltrue
classfixedPosition

...