Workflow event-specific functions

  • Release version: Zurich
  • Updated July 31, 2025
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Workflow event-specific functions

    This content describes several key functions used in ServiceNow workflows to manage and interact with workflow events. These functions enable workflow designers to register for, unregister from, fire, and broadcast custom events within workflow activities, using event names as string identifiers. They operate primarily on theWorkflow Executing Activity [wfexecuting]records, allowing workflows to respond dynamically to events during execution.

    Show full answer Show less

    Key Functions and Their Uses

    • registerForEvent(eventName): Registers the current workflow activity to listen for a specified event by adding the event name string to the wfexecuting.registeredevents field. This allows the activity to react when the event is triggered.
    • unRegisterForEvent(eventName): Removes a previously registered event name from the wfexecuting.registeredevents field, stopping the activity from responding to that event.
    • fireEvent(eventName): Fires an event globally within the current workflow context, queuing all executing activities registered for that event to handle it.
    • fireEvent(eventRecord, eventName) and fireEvent(eventRecordSysId, eventName): Sends an event to a specific workflow executing activity record, triggering the corresponding on event handler. This targets a single activity instance rather than broadcasting.
    • fireEvent(eventRecordSysId, eventName, optionalJSONObject): Extends the previous method by allowing an optional JSON object to pass additional data with the event.
    • broadcastEvent(contextId, eventName): Sends an event to all currently running workflow activities within a specified workflow context, irrespective of their state.
    • broadcastEvent(eventName): Sends an event to all running workflow activities in the current context. This method is only accessible via the global workflow variable and affects all executing activities in the current workflow.

    Practical Application for ServiceNow Customers

    These workflow event functions empower ServiceNow customers to design highly interactive and responsive workflows. By using these functions, you can:

    • Control which workflow activities respond to specific events dynamically.
    • Trigger events that cause other parts of the workflow to react, enabling complex coordination and synchronization.
    • Pass contextual or custom data with events to specific activities for tailored processing.
    • Broadcast events to multiple workflow activities to propagate changes or signals across the workflow execution.

    These capabilities allow for more flexible and maintainable workflows that can adapt to complex business logic and runtime conditions.

    There are several functions that relate specifically to workflow events.

    Table 1. Workflow event-specific functions
    Function Description Purpose Use Thread Source
    registerForEvent (eventName) Function in the workflow environment that writes events represented as strings to the wf_executing.registered_events field. The workflow events are just strings. When an activity that has registered for an event executes, a comma delimited set of events is stored with the Workflow Executing Activity [wf_executing] record. When the event is triggered in the workflow context, the wf_executing table looks for all executing records that contain the string that represents the event in the wf_executing.registered_events field The global variable workflow that is available to all Workflow Activity [wf_activity] records is the source of the call. For example, from inside a Run Script activity, a designer can write: workflow.registerForEvent('myEventName'); Current thread, current mutex Global variable workflow
    unRegisterForEvent (eventName) Function in the workflow environment that removes a string value representing an event that has been written to the wf_executing.registered_events field. The workflow events are just strings that are written to the wf_executing.registered_events field. When an activity unRegisters for an event, the comma delimited set of events stored with the Workflow Executing Activity [wf_executing] record is searched, and if that string is found, it is removed. The global variable workflow that is available to all Workflow Activity [wf_activity] records is the source of the call. For example, from inside a Run Script activity, a designer can write: workflow.unRegisterForEvent('myEventName'); Current thread, current mutex Global variable workflow
    fireEvent (eventName) Function in the workflow environment that examines the contents of the wf_executing.registered_events field, comparing its contents to the eventName passed in. The workflow events are just strings that are written to the wf_executing.registered_events field. When fireEvent(eventName) is called by a workflow activity, the workflow engine queues up any executing records that contain the string in the registered field. The global variable workflow that is available to all Workflow Activity [wf_activity] records is the source of the call. For example, from inside a Run Script activity, a designer can write: workflow.fireEvent('myEventName'); Current thread, current mutex Global variable workflow
    fireEvent (eventRecord, eventName) Function in the workflow environment that sends an event to a specific Workflow Executing Activity [wf_executing] record. The eventRecord is a GlideRecord of the type wf_executing. This event call expects an onMyEvent event handler in the activity represented in the event record (Workflow Executing Activity [wf_executing] table). When fireEvent(eventRecord, eventName) is called by a workflow activity, the workflow engine queues up the specific executing record with that event and passes the event into the activity definition for the on<eventName> handler to manage. This event is queued up in its own mutex, so the current queue completes before this event is processed. The workflow script include contains the call for this. For example, from inside a Run Script activity, a designer can write: var w = new Workflow(); w.fireEvent(executing, eventName); Current thread, current mutex Workflow script include
    fireEvent (eventRecordSysId, eventName) Function in the workflow environment that sends an event to a specific Workflow Executing Activity [wf_executing] record. The eventRecordSysId is the sys_id of a GlideRecord of the type wf_executing. This is the same as the fireEvent above, except that it accepts an ID and returns the Workflow Executing Activity [wf_executing] record. The Workflow script include contains the call for this. For example, from inside a Run Script activity, a designer can write: var w = new Workflow(); w.fireEvent(executing, eventName); Current thread, current mutex Workflow script include
    fireEvent (eventRecordSysId, eventName, optionalJSONObject) Function in the workflow environment that sends an event to a specific Workflow Executing Activity [wf_executing] record. The eventRecordSysId is the sys_id of a GlideRecord of the type wf_executing. This is the same as the fireEvent above, except that it accepts a JSON object as a third parameter. This object can specify any data expressible as JSON. You can also specify additional functionality when creating a workflow activity. The Workflow script include contains the call for this. For example, from inside a Run Script activity, a designer can write: var w = new Workflow(); w.fireEvent(executing, eventName, JSONObject); Current thread, current mutex Workflow script include
    broadcastEvent (contextId, eventName) Function in the workflow environment that sends an event to all currently running Workflow Executing Activity [wf_executing] records in a specified context, regardless of their state. This is the same as the fireEvent above, except that it accepts an ID and returns the Workflow Executing Activity [wf_executing] record. The Workflow script include contains the call for this. For example, from inside a Run Script activity, a designer can write: var w = new Workflow(); w.broadcastEvent(contextId, eventName); Current thread, current mutex Workflow script include
    broadcastEvent (eventName) Function in the workflow environment that sends an event to all currently running Workflow Executing Activity [wf_executing] records in the current context, regardless of their state. This should not be confused with broadcastEvent above. This event is only available to current Workflow Executing Activity [wf_executing] records. This is available only through the global workflow variable of the current context. The following is an example of its use from within an activity definition's script: workflow.broadcastEvent(eventName) Current thread, current mutex Global variable workflow