Events

Itential Platform publishes events using an internal Event System.

To subscribe to an event topic, you need to provide a source and event handler. The format is source, topic, handler as shown in this example:

eventSystem.subscribe("@itential/app-workflow_engine", "jobStart", jobStartHandler);

Job events

The table below lists event topics published to the Itential Platform environment.

Event payload structure

All job event payloads contain a job property with the complete job document from the database at the time the system publishes the event. The job document's structure and content vary based on the workflow definition and the job's current state.

Standard job events

Standard job events (jobStart, jobComplete, jobError, jobFix, jobPause, jobResume, jobCancel) follow this structure:

{
  type: <number>,
  source: '@itential/app-workflow_engine',
  topic: '<event_topic>',
  instance: 'WorkFlowEngine',
  timestamp: <timestamp_in_milliseconds>,
  payload: {
    job: {
      // Complete job document from MongoDB
      _id: '<job_id>',
      name: '<job_name>',
      tasks: { /* task definitions */ },
      status: '<job_status>',
      // Additional job properties...
    }
  }
}

Subscribe to job events

You can subscribe to job events using the global eventSystem object available in applications and adapters. This example subscribes to multiple job events:

const util = require('util');

const inspect = msg => {
  console.log(util.inspect(msg, false, null, true));
}

// Subscribe to job lifecycle events
eventSystem.subscribe('@itential/app-workflow_engine', 'jobStart', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobComplete', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobError', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobFix', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobPause', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobResume', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobCancel', inspect);
eventSystem.subscribe('@itential/app-workflow_engine', 'jobSlaBreach', inspect);

Job SLA events

You can use the events defined above within the platform through Operations Manager triggers and the EventListenerJob task within a workflow. You can build automations in Operations Manager that trigger when a job breaches its service level agreement (SLA). For more information, see Event triggers.

jobSlaBreach payload structure

The jobSlaBreach event includes additional properties beyond the standard job document:

• job: The complete job document from the database at the time of the SLA breach.
• runTime: The job's runtime in milliseconds.
• slaDelta: The amount in milliseconds that the job overran its SLA threshold. For example, if you set the SLA threshold to 2000 ms and the job runs for 3086 ms, the slaDelta is 1086 ms.

Example jobSlaBreach event

This example shows a complete jobSlaBreach event message:

{
  type: 16,
  source: '@itential/app-workflow_engine',
  topic: 'jobSlaBreach',
  instance: 'WorkFlowEngine',
  timestamp: 1758819821241,
  payload: {
    job: {
      _id: '50329d1bc0594165b5b1825a',
      name: 'slaBreach',
      tasks: {
        '1132': {
          name: 'delay',
          canvasName: 'delay',
          summary: 'Delay a Job',
          description: 'Delay a Job for a duration by Job ID and number of seconds.',
          location: 'Application',
          locationType: null,
          app: 'WorkFlowEngine',
          type: 'operation',
          displayName: 'WorkFlowEngine',
          variables: {
            incoming: { time: null },
            outgoing: { time_in_milliseconds: '' },
            decorators: []
          },
          actor: 'Pronghorn',
          groups: [],
          nodeLocation: { x: 24, y: -84 },
          status: 'complete',
          previous: { incomplete: [], complete: [], error: [] },
          incomingRefs: [
            {
              type: 'static',
              pointer: '/variables/incoming/time',
              reference: { location: 'document', value: 2 }
            }
          ],
          outgoingRefs: [
            {
              type: 'taskOutgoing',
              status: 'success',
              pointer: '/variables/outgoing/time_in_milliseconds',
              taskVariableName: 'time_in_milliseconds'
            },
            {
              type: 'taskOutgoing',
              status: 'error',
              pointer: '/variables/error',
              taskVariableName: null
            }
          ],
          taskId: '1132',
          owner: 'Pronghorn',
          iterations: [ '440c69a5-e38b-495d-a0a2-00363f924fc1' ],
          transitions: { success: [ { task: 'workflow_end', type: 'standard' } ] },
          serverId: 'local_node1',
          start_time: '2025-09-25T17:03:38.957Z',
          end_time: 1758819820979,
          finish_state: 'success'
        },
        workflow_start: {
          name: 'workflow_start',
          groups: [],
          nodeLocation: { x: 0, y: -500 },
          x: 0,
          y: 0.5,
          status: 'complete',
          metrics: {
            start_time: 1758819818925,
            user: '667afeda7cd7b76286c0bfb5',
            finish_state: 'success'
          },
          taskId: 'workflow_start',
          owner: 'Pronghorn',
          iterations: [],
          transitions: { success: [ { task: '1132', type: 'standard' } ] }
        },
        workflow_end: {
          name: 'workflow_end',
          groups: [],
          nodeLocation: { x: 0, y: 500 },
          x: 1,
          y: 0.5,
          status: 'complete',
          previous: { incomplete: [], complete: [ '1132' ], error: [] },
          taskId: 'workflow_end',
          owner: 'Pronghorn',
          iterations: [],
          transitions: {},
          endTasks: { incomplete: [], complete: [], error: [] },
          metrics: { end_time: 1758819821011, run_time: 2086 }
        }
      },
      transitions: {
        '1132': { workflow_end: { state: 'success', type: 'standard' } },
        workflow_start: { '1132': { state: 'success', type: 'standard' } },
        workflow_end: {}
      },
      canvasVersion: 3,
      type: 'automation',
      font_size: 12,
      errorHandler: null,
      preAutomationTime: 0,
      sla: 1000,
      groups: [ 'default' ],
      last_updated: '2025-09-25T17:03:41.008Z',
      lastUpdatedVersion: '5.55.5',
      uuid: '82cbd255-86aa-4fc1-b403-6cc3a20e0986',
      created: '2025-09-25T17:03:10.090Z',
      created_by: '667afeda7cd7b76286c0bfb5',
      createdVersion: '5.55.5',
      encodingVersion: 1,
      last_updated_by: '667afeda7cd7b76286c0bfb5',
      description: '',
      status: 'complete',
      variables: {
        _id: { location: 'job_data', _id: '68d575ea51431df6af6c7e4e' },
        initiator: { location: 'job_data', _id: '68d575ea51431df6af6c7e4f' }
      },
      watchers: [ '667afeda7cd7b76286c0bfb5' ],
      ancestors: [ '50329d1bc0594165b5b1825a' ],
      mocked: false,
      decorators: [],
      metrics: {
        start_time: 1758819818925,
        user: '667afeda7cd7b76286c0bfb5',
        progress: 1,
        end_time: 1758819821011
      }
    },
    runTime: 2086,
    slaDelta: 1086
  }
}

In this example, the job had an SLA threshold of 1000 ms (1 second) but took 2086 ms to complete. This resulted in an SLA breach with a slaDelta of 1086 ms.

Configure the EventListenerJob task

Figure 1 shows how to configure the EventListenerJob task to receive the jobSlaBreach event.

Figure 1: Task Configuration

For additional SLA information, refer to Setting Job Metrics.