Listeners

Explains what listeners are and how they can be used to work with events of the app.

Listeners allow you to connect with various events within the app. For instance, you can listen to the creation of records or the reception of an event from an legacy service and take certain actions when these events occur.

Apart from event listening, it’s also possible to schedule listeners to run periodically based on a CRON expression.

Label

This represents the human-readable name of the listener.

Name

This serves as the internal name of the listener.

The name cannot include special characters or spaces, only letters and numbers are allowed.

Type

The listener type indicates the category of events it will be observing. The available types include:

  • Data: Data listeners can tap into data-related events such as record creation, record updates, or the execution of actions on records. When selecting this type, additional settings can be configured to filter the specific data events to be handled:
    • Entity: The listener will focus on events within records under this entity.
    • Events: Specifies which data events the listener will process. Refer to the Data events for more details.
  • Legacy service: Legacy service listeners can intercept events sent from legacy services. For example, an HTTP legacy service can generate an event when a webhook is triggered, which can then be processed by a listener. When choosing this type, further settings can be customized to filter the events to be managed:
    • Legacy services: The listener will be attuned to events generated by this specific legacy service.
    • Event: Indicates the specific event to be considered.
  • UI plugin: These listeners can capture events and callbacks originating from UI plugins. When opting for this type, you can specify additional settings to filter the events to be handled:
    • Plugin: The plugin to which the listener will be attuned.
    • Event: The event/callback emanating from the plugin.
  • Job: Job listeners can respond to user events like job start or job completion. When selecting this type, additional settings can be defined to filter the job events to be handled:
    • Job: The category of job that the listener will be observing.
    • Event: Specifies the particular event to be considered.
  • Time: Time listeners execute based on a CRON expression. When selecting this type, additional settings can be configured:
    • Timezone: The timezone employed for the CRON expression.
    • Expression: The expression determining when the listener will execute. For more information on the expression format, please review this documentation.

Execute in the background

For certain event types (such as Data), you can decide whether the listener should execute synchronously or be sent to the background.

For instance, if this flag isn’t enabled and the listener pertains to a record creation, the operation won’t conclude until the listener’s execution is finished. Therefore, you should enable this flag when the listener’s execution might surpass an acceptable time frame for the ongoing operation.

Avoid Triggering UI events

Enabling this flag ensures that when the listener is triggered in the background, it bypasses sending notifications to the UI. This feature proves valuable in avoiding additional overhead during execution. A typical use case is executing a listener for batch processing, where notifying end users about data changes isn’t necessary.

Action

This refers to the script that will be executed when the event is triggered. Depending on the event type, the script’s context will differ.

Data listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “DATA”,
  “dataEvent”: “RECORD_CHANGED
}

- Possible values for dataEvent are: RECORD_CREATED, RECORD_CHANGED, RECORD_DELETED, CONDITION_MET, ACTION_PERFORMED.
recordsys.data.RecordThe record involved in the data operation.
There is one case where this variable will be empty, which when the event.dataEvent is ACTION_PERFORMED and the action executed was of type Many records. In this case, as the action is executed over a group of records, it isn’t possible to set a single record.
oldRecordsys.data.RecordIf the event is of type RECORD_CHANGED, ACTION_PERFORMED, or CONDITION_MET, this variable will hold the version of the record before the event occurred.
Samples 
// logs a message when there is a data event (the listener is configured accordingly)
sys.logs.info('*** EVENT: '+event.dataEvent);
sys.logs.info('*** RECORD: '+record.label());

Legacy services listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “ENDPOINT”,
  “date”: 1486673333420,
  “endpoint”: “sample”,
  “endpointEvent”: “inboundEvent”,
  “data”: {
    “token”: “123456”,
    “number”: 4468
  }
}


date is the timestamp when the event was sent.
endpoint is the name of the endpoint.
endpointEvent is the name of the event.
data is data sent by the endpoint which is specific for each event and you should check the documentation for each endpoint.
Samples 
// logs the data sent by the endpoint
sys.logs.info('*** ENDPOINT: '+event.endpoint);
sys.logs.info('*** EVENT: '+event.endpointEvent);
sys.logs.info('*** DATA: '+event.data);

Service listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “SERVICE”,
  “date”: 1486673333420,
  “service”: “sample”,
  “serviceEvent”: “inboundEvent”,
  “data”: {
    “token”: “123456”,
    “number”: 4468
  }
}


date is the timestamp when the event was sent.
service is the name of the service.
serviceEvent is the name of the event.
data is data sent by the endpoint which is specific for each event and you should check the documentation for each service.
Samples 
// logs the data sent by the package
sys.logs.info('*** SERVICE: '+event.service);
sys.logs.info('*** EVENT: '+event.serviceEvent);
sys.logs.info('*** DATA: '+event.data);

UI service listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “UI_SERVICE”,
  “date”: 1486673333420,
  “uiService”: “sample”,
  “event”: “event1”,
  “callback”: “callback1”,
  “data”: {
    “originalMessage”: {
      “companyId”: “ABC”
    },
    “callbackData”: {
      “number”: 1234,
      “text”: “hello”
    }
  }
}


date is the timestamp when the event was sent.
uiService is the name of the uiService.
event is the name of the event.
callback is the name of the callback.
data is data sent by the callback request.
Samples 
// logs the data sent by the ui service
sys.logs.info('*** UI_SERVICE: '+event.uiService);
sys.logs.info('*** DATA: '+event.data);

UI plugin listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “PLUGIN”,
  “date”: 1486673333420,
  “plugin”: “sample”,
  “event”: “event1”,
  “callback”: “callback1”,
  “data”: {
    “originalMessage”: {
      “companyId”: “ABC”
    },
    “callbackData”: {
      “number”: 1234,
      “text”: “hello”
    }
  }
}


date is the timestamp when the event was sent.
plugin is the name of the plugin.
event is the name of the event.
callback is the name of the callback.
data is data sent by the callback request.
Samples 
// logs the data sent by the plugin
sys.logs.info('*** PLUGIN: '+event.plugin);
sys.logs.info('*** DATA: '+event.data);

Job listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “JOB”,
  “jobType”: “IMPORT_RECORDS”,
  “jobEvent”: “FINISHED”,
  “jobId”: “589cdb2ae201af1d75ec2d83”
}


jobType is the type of job
jobEvent is the event of the job that triggered the listener.
jobId is the ID of the job. You can use it to find the job and get more information about it.
Samples 
// finds job and checks if it had errors
var job = sys.jobs.findById(event.jobId);
sys.logs.info('*** ERRORS: '+job.hasErrors());

Time listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “TIME”
}
Samples 
// logs something when the timer is triggered
sys.logs.info('*** TIME LISTENER!');

Custom event listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “CUSTOM”,
  “customEvent”: “newNote”,
  “customData”: {
    “noteId”: “589cdb2ae201af1d75ec2d83”
  }
}


customEvent is the name of custom event that triggered the listener.
customData is an object sent by user as data opf this custom event.
Samples 
// log note ID create
sys.logs.info('*** NOTE CREATED: '+customData.noteId);

Package event listeners

Parameters
NameTypeDescription
eventobjectContains information about the event. It has the following structure:
{
  “type”: “CUSTOM”,
  “packageEvent”: “newNote”,
  “package”: “newNote”, 
  “data”: {
    “messageContent”: “589cdb2ae201af1d75ec2d83”
  }
}


packageEvent is the name of the package event that triggered the listener.
data is an object sent by user as data of this package event.
package is the name of the package.
Samples 
// log message content
sys.logs.info('*** NEW MESSAGE CREATED: '+data.messageContent);

Edit this page on GitHub
← Actions
Libraries →