Workflow event-specific functions

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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

    Workflow event-specific functions in ServiceNow enable workflow activities to manage and respond to events during workflow execution. These functions allow designers to register, unregister, trigger, and broadcast events tied to workflow activities, enhancing control and flexibility in automating processes.

    Show full answer Show less

    Key Functions and Their Use

    • registerForEvent(eventName): Registers an event string to a workflow activity’s wfexecuting.registeredevents field, enabling the activity to listen for that event. Used within the current workflow thread via the global workflow variable.
    • unRegisterForEvent(eventName): Removes a previously registered event string from the workflow executing record, stopping the activity from listening to that event. Called through the global workflow variable.
    • fireEvent(eventName): Triggers an event by queuing all executing records that have registered for this event name, allowing those activities to respond accordingly. Invoked using the global workflow variable.
    • fireEvent(eventRecord, eventName): Sends an event to a specific executing activity record (wfexecuting GlideRecord). It expects an event handler named on<eventName> within that activity. This call queues the event in its own mutex for isolated processing and is used via the Workflow script include.
    • fireEvent(eventRecordSysId, eventName): Similar to the above but accepts a sysid of the executing record instead of a GlideRecord object. Also part of the Workflow script include.
    • fireEvent(eventRecordSysId, eventName, optionalJSONObject): Extends the previous function by allowing a JSON object to pass additional data with the event, providing more context or parameters for event handling.
    • broadcastEvent(contextId, eventName): Sends an event to all currently running workflow executing activities within a specified context, regardless of their state. Useful for notifying multiple workflow activities within the same context.
    • broadcastEvent(eventName): Broadcasts an event to all currently running workflow executing activities in the current workflow context only. Available via the global workflow variable and differs from the context-specific broadcast above.

    Practical Implications for ServiceNow Customers

    These functions give workflow designers precise control over event management within workflows, enabling asynchronous and conditional processing of workflow steps. By registering for events, workflows can wait for external or internal triggers, and by firing or broadcasting events, workflows can coordinate complex sequences and parallel activities.

    Understanding when and how to use these event functions helps customers create more dynamic, responsive workflows that align with their business processes, improve automation reliability, and facilitate better orchestration of workflow activities.

    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