Listeners

Listeners allow to hook up to different events in the app. For example you can listen to the creation of records or the arrival of an event from an endpoint and perform some action when that happens.

Apart from listening to events, it is possible to execute listeners periodically based on the CRON expression.

Label

This is the human-readable name of the listener.

Name

This is the internal name of the listener.

The name cannot contain special characters or spaces. Only letters and numbers.

Type

The type of the listener indicates the type of events it will be listening to. Available types are:

• Data: data listeners can hook into data events like the creation of a record, update of a record or the execution of an action over some records. When this type is selected it is possible to indicate more settings to filter which data events will be handled:
  • Entity: the listener will be listening to events in records under this entity.
  • Events: indicates which data events will be taken into account by the listener. See Data events for more information.
• Endpoint: endpoint listeners can listen to events sent from endpoints. For example an HTTP endpoint can generate an event when a webhook is hit that can be process with a listener. When this type is selected it is possible to indicate more settings to filter which events will be handled:
  • Endpoint: the listener will be listening to events generated by this endpoint.
  • Event: indicates which event will be taken into account.
• UI plugin: these listeners can listen events and callbacks coming from UI plugins. When this type is selected it is possible to indicate more settings to filter which events will be handled:
  • Plugin: the plugin to listen to.
  • Event: the event/callback coming from the plugin.
• Job: job listeners can hook to user events like started or job finished. When this type is selected it is possible to indicate more settings to filter which job events will be handled:
  • Job: the type of job the listener will be listening to.
  • Event: indicates which event will be taken into account.
• Time: time listeners will be executed based on a CRON expression. When this type is selected it is possible to indicate more settings:
  • Timezone: the timezone used for the CRON expression.
  • Expression: the expression to determine when the listener will be executed. Please check this documentation for more information on the format of the expression.

Execute in the background

For some type of events (like Data) it is possible to decide if the listener has to be executed in a synchronous way or if it has to be sent to the background.

For example if this flag isn’t set and the listener is for the creation of a record, when that happens (for example a record was created from the UI), the operation won’t return until the listener is executed.

So you should set this flag when the execution of the listener might take more time that it is acceptable for the operation in place.

Avoid trigger UI events

If this flag is set, when the listener is triggered in the background it will skip sending notifications to the UI. This is useful to avoid overhead during execution. A common scenario will be to execute a listener for batch processing in which it is not required to notify end users about data changes.

Action

This is the script that will be executed when the event is triggered. Depending on the type of event, the context of the script will change.

Data listeners

Parameters

{
  "type": "DATA",
  "dataEvent": "RECORD_CHANGED"
}

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());

Endpoint listeners

Parameters

{
  "type": "ENDPOINT",
  "date": 1486673333420,
  "endpoint": "sample",
  "endpointEvent": "inboundEvent",
  "data": {
    "token": "123456",
    "number": 4468
  }
}

Samples

// logs the data sent by the endpoint

sys.logs.info('*** ENDPONT: '+event.endpoint);
sys.logs.info('*** EVENT: '+event.endpointEvent);
sys.logs.info('*** DATA: '+event.data);

UI plugin listeners

Parameters

{
  "type": "PLUGIN",
  "date": 1486673333420,
  "plugin": "sample",
  "event": "event1",
  "callback": "callback1",
  "data": {
    "originalMessage": {
      "companyId": "ABC"
    },
    "callbackData": {
      "number": 1234,
      "text": "hello"
    }
  }
}

Samples

// logs the data sent by the plugin

sys.logs.info('*** PLUGIN: '+event.plugin);
sys.logs.info('*** DATA: '+event.data);

Job listeners

Parameters

{
  "type": "JOB",
  "jobType": "IMPORT_RECORDS",
  "jobEvent": "FINISHED",
  "jobId": "589cdb2ae201af1d75ec2d83"
}

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

{
  "type": "TIME"
}

Samples

// logs something when the timer is triggered

sys.logs.info('*** TIME LISTENER!');

Custom event listeners

Parameters

{
  "type": "CUSTOM",
  "customEvent": "newNote",
  "customData": {
    "noteId": "589cdb2ae201af1d75ec2d83"
  }
}

Samples

// log note ID create

sys.logs.info('*** NOTE CREATED: '+customData.noteId);