OpenWhisk triggers and rules bring event-driven capabilities to the platform. Events from external and internal event sources are channeled through a trigger, and rules allow your actions to react to these events.
Triggers are a named channel for a class of events. The following are examples of triggers:
- A trigger of location update events.
- A trigger of document uploads to a website.
- A trigger of incoming emails.
Triggers can be fired (activated) by using a dictionary of key-value pairs. Sometimes this dictionary is referred to as the event. As with actions, each firing of a trigger results in an activation ID.
Triggers can be explicitly fired by a user or fired on behalf of a user by an external event source. A feed is a convenient way to configure an external event source to fire trigger events that can be consumed by OpenWhisk. Examples of feeds include the following:
- Cloudant data change feed that fires a trigger event each time a document in a database is added or modified.
- A Git feed that fires a trigger event for every commit to a Git repository.
A rule associates one trigger with one action, with every firing of the trigger causing the corresponding action to be invoked with the trigger event as input.
With the appropriate set of rules, it's possible for a single trigger event to invoke multiple actions, or for an action to be invoked as a response to events from multiple triggers.
For example, consider a system with the following actions:
classifyImageaction that detects the objects in an image and classifies them.
thumbnailImageaction that creates a thumbnail version of an image.
Also, suppose that there are two event sources that are firing the following triggers:
newTweettrigger that is fired when a new tweet is posted.
imageUploadtrigger that is fired when an image is uploaded to a website.
You can set up rules so that a single trigger event invokes multiple actions, and have multiple triggers invoke the same action:
newTweet -> classifyImagerule.
imageUpload -> classifyImagerule.
imageUpload -> thumbnailImagerule.
The three rules establish the following behavior: images in both tweets and uploaded images are classified, uploaded images are classified, and a thumbnail version is generated.
Triggers can be fired when certain events occur, or can be fired manually.
As an example, create a trigger to send user location updates, and manually fire the trigger.
- Enter the following command to create the trigger:
- Check that you created the trigger by listing the set of triggers.
So far you've created a named "channel" to which events can be fired.
- Next, fire a trigger event by specifying the trigger name and parameters:
A trigger that is fired without an accompanying rule to match against has no visible effect. Triggers cannot be created inside a package; they must be created directly under a namespace.
Rules are used to associate a trigger with an action. Each time a trigger event is fired, the action is invoked with the event parameters.
As an example, create a rule that calls the hello action whenever a location update is posted.
- Create a 'hello.js' file with the action code we will use:
- Make sure that the trigger and action exist.
- Create the rule. Note that the rule will be enabled upon creation, meaning that it will be immediately available to respond to activations of your trigger. The three parameters are the name of the rule, the trigger, and the action.
At any time, you can choose to disable a rule.
- Fire the locationUpdate trigger. Each time that you fire an event, the hello action is called with the event parameters.
- Verify that the action was invoked by checking the most recent activation.
You see that the hello action received the event payload and returned the expected string.
You can create multiple rules that associate the same trigger with different actions. Triggers and rules cannot belong to a package. The rule may be associated with an action that belongs to a package however, for example:
You can also use rules with sequences. For example, one can create an action
recordLocationAndHello that is activated by the rule
Large portions of this page is copied from the Apache OpenWhisk documentation on April 23rd 2021 - where there have been customisations to match Hypi's deployment this has been noted. Apache OpenWhisk and the Apache name are the property of the Apache Foundation and licensed under the Apache V2 license .