unschedule(): Removing a scheduled event from the scheduler

Use the unschedule() predefined rule action when a previously scheduled event requires unscheduling, before it goes off. The general syntax is:

Argument 1: The <item_name>. All scheduled items (events) with this name are unscheduled. If one wants to select the events to be unscheduled by other properties than the name (see other arguments), then the event-name argument should be the NULL keyword.

Following arguments (optional): Event pattern definition. These arguments represent a list of named values, of form: <evt_attribute> :<value>. They have the same semantics over the reused event as for the generate() action, that is, they override any attribute value of the event specified in argument 2. If there is no argument 2 (reused event), then these named values define the event pattern.

Event argument (optional): "reused event" is an event variable that represents an incoming existing event (captured in the condition part of the rule) for reusing as an event pattern. All scheduled events that satisfy the pattern are removed from the scheduler. More precisely, in order to be removed, a scheduled event must:

Have attribute values similar to the ones of the reused event, except for the date. If argument 1 (name) is present, then only the scheduled events with this name, which also match the reused event, are unscheduled.

Note: As with the generate() call, special attributes of the reused event are not automatically reported in the event pattern: the event ID attribute and the PROCESSINSTANCEID attribute. Unscheduling based on event pattern can be combined with unscheduling based on name, if both arguments are present. Only the events with this name AND that match the pattern are removed.

Example 1: If the "Upgrade Memory" process is completed in time, then there is no need to activate the scheduled event to trigger the timeout check (see the examples for schedule() action above). In order to avoid unnecessary checking and event processing overhead, we unschedule this event as soon as the process completes.

rule job_done
activated by event1 of BP Server::PI_COMPLETED{PROCESSTEMPLATENAME = "Upgrade Memory}

We could give a more definitive name to the scheduled event, that is, the ID of the "Upgrade Memory" process itself, which is unique to each process. In that case, the action call would be:

Example 2: The following action removes all the "timeout" events currently scheduled for the "HelpDesk" process. We assume that the process name was stored in the context of the scheduled events.