Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Events allow executing creating tasks for server-side scripts at some point of time or a specific schedule.

Every script executing event consists of:

script executing, immediate or scheduled, 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.

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:

the script body (stored in the Event Script Action
  1. Define a server script for a system event by creating a record in the Event Script Actions
  1. (sys_event_script_action)
table);
  • the register record which the script (or the scripts) refers to;
  • the event record that calls the register record (the linked script is executed as a result)
    1.  dictionary.
    2. Define a notification rule to send notifications.
    3. You can combine the options listed above, so your event register record can trigger actions and send notifications cooperatively if you bind them with this record.

    Event structure


    Image Added

    Creating

    The event structure:

    Image Removed

    Note

    Role required: admin.

    How to create

    an event


    To create an event, add a new record into use the server-side API methods ss.eventQueueor ss.eventQueueScheduled. Create an event as described in the referenced articles. As a result, records in the Event (sys_event) table. For this, please complete the following steps:

    1. Navigate to System Definition -> Events
    2. Click New, fill in the form and then click Save.

    You can find the fields described below on this page.

    Also, the event can be created via server-side API methods ss.eventQueueor ss.eventQueueScheduled.

    table will be created.

    Note

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

    The example of such record is described below.

    Tip

    Role required: admin.

    Anchor
    Event Record
    Event Record
    Event form fields

    Event Record


    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 via calling methods ss.eventQueueor ss.eventQueueScheduled, you

    can

    have to pass on the Record object. The object ID will be saved in this field.

    You

    'll be able to

    can call

    on

    this value in

    the 

    the Event Script Action (sys_event_script_action) script body:

    event.instance

    Table

    The

    This field contains a reference to the record table that

    contains the record specified in the Instance field.

    was passed at the time the event was created. This field is populated automatically.

    Process started at

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

    Process on

    The date and time of the Event

    Script Action

    (sys_event

    _script_action

    ) script execution.

    Processed

    Process finished on

    The date and time

    when

    of the system event

    has been done

    execution finish.

    Param_1...Param_ 5

    The string parameters

    . The values of them are callable in the Event Script Action

    that can be transmitted to the specified Event (sys_event

    _script_action) script: event.param_1, event.param_2, and so on

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

    State

    Event state:

    ready
    • Ready – event is pending for execution. Execution time is specified in the Process
    on
    •  finished on field.
    processed
    • Processing – the event is being executed.
    • Processed – the event has been processed. Processing time is specified in the
    Processed field
    • Process finished on field.
    error
    • Error – the event processing
    has been failed
    • have failed. Processing time is specified in the Process finished on field.
    • Canceled - the event will not process after changing the states from the Ready state to this one.

    Processing duration, ms

    The sys_event_script_action script processing duration

    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

    This field is always populated with the system user (which can also be displayed as 100000000000000000 on forms). This is the user on behalf of which the event should be executed. 

    The Created by field contains the information about the event originator (a user on behalf of which this event has been created).

    The Related List on the form event contains the


    Related lists are bound with the event record containing the following lists:

    • 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
    • the Event Script Action (sys_event_script_action) table
    , that will be executed (or has been executed).
    • are referenced to the current record.

    Anchor
    Event Register
    Event Register
    Event Register form fields

    Event Register Record


    Field

    Description

    Name

    The name

    Name of the event register record

    on which the script will be referenced to and which will be used to call an event in the event record

    .

    Events (the Event (sys_event) table records) called for this register contain this value in the Name field.

    Table

    Starts with only those events that contain a record related to a specified table. 

    If you are going to trigger email sending with this record, then ensure that the value in the Table field in the Notification Rule record is the same as in this event register record.

    DescriptionEvent register record description.
    Disable script logging

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

    The Related List on the form event contains the

    Related lists area bound with the event register record containing the following lists:

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

    Anchor
    Event Script Action

    Record

    Event Script Action
    Event Script Action form fields


    Field

    Description

    Name

    The name

    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 make the script action active or inactive.
    Execution orderSpecify the event script action execution order if there is more than one record for the related Event Register (sys_event_register) table. Actions are executed in ascending order.

    Script

    The script is executed when the event occurs.

    Info

    In the Event Script Action, the event object is

    fired.

    There are five additional string parameters (Param_1 ... Param_5) available in the script body, so you can call their value in this way:

    event.param_1, event.param_2;

    You can also address to other field values of the following record:

    event.column_name

    available. The object is the instance of the SimpleRecord class and refers to a record from the Event (sys_event) table that started the script. To get the values of the record fields, use the dot-notation for the event object. To do this, you need to use properties with names corresponding to the names of 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 (Param_1...Param_ 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);
    Events are the objects of the Event (sys_event) table, so any fields can be addressed, as well as through the dot-walking feature.



    Table of Contents
    absoluteUrltrue
    classfixedPosition

    ...