Workflow event-specific functions

  • Release version: Yokohama
  • Updated January 30, 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 topic details key functions available in the ServiceNow Yokohama release for managing workflow events within the Workflow Executing Activity [wfexecuting] records. These functions allow workflow designers to register, unregister, fire, and broadcast events dynamically during workflow execution, enabling flexible and event-driven workflow behaviors.

    Show full answer Show less

    Key Functions and Their Uses

    • registerForEvent(eventName): Registers a workflow activity to listen for a specific event by adding the event name as a string to the wfexecuting.registeredevents field. Used to prepare activities to respond when that event is triggered.
    • unRegisterForEvent(eventName): Removes a previously registered event string from the wfexecuting.registeredevents field, stopping the activity from listening to that event.
    • fireEvent(eventName): Triggers an event by matching the event name against all registered events in the current context, queuing any matching executing records to handle the event.
    • fireEvent(eventRecord, eventName) and fireEvent(eventRecordSysId, eventName): Send an event directly to a specific Workflow Executing Activity record identified by a GlideRecord or sysid. Requires the activity to have an appropriate event handler (e.g., onMyEvent).
    • fireEvent(eventRecordSysId, eventName, optionalJSONObject): Extends the above by allowing additional JSON data to be passed with the event, enabling richer event handling scenarios.
    • broadcastEvent(contextId, eventName): Sends an event to all currently running Workflow Executing Activity records within a specified workflow context, regardless of their state.
    • broadcastEvent(eventName): Sends an event to all executing activities in the current workflow context only, accessible through the global workflow variable.

    Practical Application for ServiceNow Customers

    These workflow event functions empower ServiceNow customers to build complex, event-driven workflows that respond dynamically to runtime conditions. By registering for events, workflows can pause and wait for specific triggers. Firing events can initiate transitions or actions in multiple workflow activities simultaneously or selectively target specific executions. The ability to broadcast events across workflow contexts enhances coordination and synchronization of parallel workflow activities.

    Workflow designers typically use these functions within Run Script activities or custom workflow activity definitions via the global workflow variable or the Workflow script include. Understanding and leveraging these functions can significantly increase workflow flexibility, responsiveness, and maintainability.

    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