Managing Rules for Events

This topic describes how to manage rules for the Events service. For more information about Events, see Overview of Events.

Prerequisites for Creating Rules

Action resources: You must have resources already set up to specify as an action. The Events service invokes the action specified in the rule by delivering the event message to action resources, which can include topics , streams, or functions. Every rule must have at least one action. The Events service can invoke any of the following services by delivering an event message for processing:
IAM policies: To manage or list rules, you must be given the required type of access in a policy written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform a task and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment you should work in. For more information, see Events and IAM Policies.
Event messages: To create rules, the resources you want to monitor with the rule must emit events. For more information, see Services that Produce Events.

Working with Rules

Note

Each rule can have a maximum of 10 actions.

A typical workflow for setting up rule might follow this pattern:

Identify action resources
Set up or identify whatever action resources you intend to use with the rule. For example, you might set up a Notifications topic and create subscriptions for the DevOps team so that they are notified when backups complete. If a topic already exists, you can use it instead of creating a topic. The resources you specify for actions do not have to be in the same compartment as the rule.
Plan filtering
Ensure the resources that you want to monitor emit events to the Events service and plan your pattern matching strategy. For example, you might want to monitor backups on Autonomous Data Warehouse instances in the ABC compartment. Ensure Autonomous Data Warehouse instances emit an event type you can use to create the automation you require. Review the example JSON event to determine the best way to identify those resources in filters. See Matching Events with Filters and Services that Produce Events.
Create the rule
Rules apply to events in the compartment in which you create them and any child compartments. Create a rule in the compartment with the resource you want to monitor and specify where to deliver matching events. For example, in the ABC compartment, you might create a rule that filters for Autonomous Data Warehouse backup events. Since Events has no requirement about the location of action resources, you could specify a topic in the XYZ compartment as the resource to deliver any matching events.

Managing Tags for Rules

You can add tags to your resources to help you organize them according to your business needs. You can add tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.

Tags and Event Filtering

With Events, you can also use tags to target resources in your tenancy. You target resources by adding the tag to a filter in a rule. A filter tag helps you hone automation by targeting only resources that contain a particular tag. For example, let's say you have dozens of Database instances in your tenancy, but only a few of the most critical of these instances have the tag "Operations." You could create a rule that triggers a particular action for resources that only contain the "Operations" tag.

Policy for working with filter tags is no different from policy for working with tags.

To manage filter tags

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click rule's name.
In the Resources menu, click Event Matching.
In the Filter Tags section, you can view or edit existing filter tags, or click Add Filter Tag to add new ones.

To manage tags for rules

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click rule's name.
Click the Tags tab to view or edit existing tags, or click Add Tags to add new ones.

For more information, see Resource Tags.

Move Rules to a Different Compartment

You can move rules from one compartment to another. When you move a rule to a new compartment, you stop monitoring events from resources in the current compartment and begin monitoring events in the new compartment (and any child compartments). After you move the rule to the new compartment, inherent policies apply immediately and affect access to the rules through the Console. Moving rules doesn't affect access by the Events service to actions defined in rules. For more information, see Working with Compartments.

Monitoring Rules

You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring Overview and Notifications Overview.

For more information about monitoring the rules you create, see Events Metrics.

Object Events and the Events Service

Events for objects are handled differently than other resources. Objects do not emit events by default. Use the Console, CLI, or API to enable a bucket to emit events for object state changes. You can enable events for object state changes during or after bucket creation.

Using the Console

To create a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click Create Rule.
Events compares the rules you create in this compartment to event messages emitted from resources in this compartment and any child compartments.
Enter the following.
- Display Name: Specify a friendly name for the rule. You can change this name later. Avoid entering confidential information.
- Description: Specify a description of what the rule does. You can change this description later.
In Rule Conditions, create a filter:
To add an event type
1. Select Event Type.
2. Select a Service Name.
3. In Event type, select one or more event types for this service.
4. Click + Another Condition and select Event Type to add event types for a different service.
  This filter will match events of the event types you specify.
To add an attribute
You must first select an event type to add an attribute.
1. Select Attribute.
2. Select an Attribute Name.
3. Enter an Attribute Value. Attribute values are optional.
4. Click + Another Condition and select Attribute to add another attribute.
  This filter will match events of the events types with the attributes you specify.
To add a filter tag
1. Select Filter Tag
2. Select a Tag Namespace.
  To specify a free-form tag, select None (apply a free-form tag).
3. Select a Tag Key.
4. Enter a Tag Value. Tag values are optional.
5. Click + Another Condition and select Filter Tag to add another filter tag.
  This filter will match events with the tags you specify.
Filter tags help you to hone automation by targeting only resources that contain a particular tag. If you want to use tags to organize your rules, use resource tags instead. For more information, see Managing Tags for Rules.
Tip

You can leave this field entirely blank to match all events. See Matching Events with Filters.
To validate this rule
You can only evaluate a rule against one event type at a time. To test different event types, repeat these steps as necessary.
1. Click Validate Rule. The Test Rule panel opens.
2. In Service Name, select a service if necessary.
3. In Event Type, select an event type, if necessary. A example event appears based on the selections you made. Edit the values in the event to match the values for any attributes and tags you added to your rule. For more information, see Contents of an Event Message.
4. Click Check if Example Event Matches Rule. If the rule doesn't match, use the rule editor to modify any of the following:
  - Add or remove event types
  - Add or remove values or attributes
  - Add or remove tags
  - Insert wildcards
  For more information, see Matching Events with Filters.
5. Click Close.
To view reference events
1. Click View example events (JSON). The View Example Events panel opens.
2. In Service Name, select a service if necessary.
3. In Event Type, select an event type, if necessary. An example event appears based on the selections you made. Use the events viewer to browse reference events.
4. Click Done.
For more information, see Contents of an Event Message and Matching Events with Filters.
To add an attribute
In Actions, specify the actions resources to trigger when the filter finds a match:
To select a topic
1. Select Notifications.
2. Select the Notifications Compartment.
3. Select the Topic.
4. Click + Another Action and select Notifications to add another topic.
To select a stream
1. Select Streaming.
2. Select the Stream Compartment.
3. Select the Stream.
4. Click + Another Action and select Streaming to add another stream.
To select a function
1. Select Functions.
2. Select the Function Compartment.
3. Select a Function Application.
4. Select the Function.
5. Click + Another Action and select Functions to add another function.
Click Create Rule.

To edit a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment that has the rule you want to edit.
For the rule you want to edit, click the Actions icon (three dots), and then click Edit.
Make your changes and click Save Changes.

To disable or enable a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment that has the rule you want to work with.
For the rule, you want change, click the Actions icon (three dots), and then take one of the following actions:
- Click Disable
- Click Enable
Confirm when prompted.

To move a rule to a different compartment

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
In the Scope section, select a compartment.
Find the rule in the list, click the the Actions icon (three dots), and then click Move Resource.
Choose the destination compartment from the list.
Click Move Resource.

To validate a rule

You can only evaluate a rule against one event type at a time. Repeat as necessary to test different event types.

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to test.
Click Validate Rule.
Take one or more of the following actions:
- If there are no event types in the rule, select the service and event type you want to test.
- If you want to test a different event type than the one selected by default, select the service and event type you want to test.
- If you added attribute values or filter tags to the rule, edit the example data in the event to match the values in your rule.
Click Check if Example Event Matches Rule.

For more information, see Matching Events with Filters and Contents of an Event Message.

To delete a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose the Compartment that has rule you want to delete.
For the rule you want to delete, click the Actions icon (three dots) , and then click Delete.
Confirm when prompted.

To add an action to a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Actions.
Click Add.
- The Add Action box appears. Configure the action resources:
  To select a topic
  1. Select Notifications.
  2. Select the Notifications Compartment.
  3. Select the Topic.
  To select a stream
  1. Select Streaming.
  2. Select the Stream Compartment.
  3. Select the Stream.
  To select a function
  1. Select Functions.
  2. Select the Function Compartment.
  3. Select a Function Application.
  4. Select the Function.
- Action State: Select to enable the action. Clear to disable.
Click Add Action.

To edit an action

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Actions.
Select an action.
Go to Actions and click Edit. The Edit Action box appears.
Make your changes and click Save Changes.

To enable or disable an action

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Actions.
Select an action.
Go to Actions and specify Enable or Disable.
Confirm when prompted.

To remove an action

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Actions.
Select an action.
Go to Actions and click Remove.
Confirm when prompted.
Each rule must have one action.

To add event types to a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Click Add Event Type.
In Service Name, select a service.
In Event Type, select an event type for this service.
Click Add Event Type.

To edit event types for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select an event type.
Click Edit. The Edit Event Type box appears.
Make your changes and click Save Changes.

To remove event types for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select the check box next to the event types you want to remove.
Tip

To select the entire list, select the check box in the header row.
Click Remove.
Confirm when prompted.

To add attributes to a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Click Add Attribute. The Add Attribute box appears. Configure the attribute:
- Attribute Name: Specify an attribute or tag to narrow matching results.
  - Select an attribute name. The list of attribute names is based on the event types you selected. If you select no event types, you cannot add an attribute.
  - If you specify an attribute here, you limit the events that match this rule.
- Attribute Values: Specify one or more values for the attribute name.
  1. Enter a value. As you type, the value appears under the field with (New) appended. Select the value with (New) appended to add the value to Attribute Values.
  2. Enter more values for attribute name in the same manner as before.
  Here are some things to consider about attribute values:
  - Use an asterisk to create a wildcard. See Examples of Wildcard Matching in Filters.
  - Multiple values for an attribute name broaden your results. If any of the values you enter here match a value in an event, the rule matches. See Examples of Arrays in Filters.
Click Add attribute.

To edit attributes for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select an attribute.
Click Edit. The Edit Attribute box appears.
Make your changes and click Save Changes.

To remove attributes for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select the check box next to the attributes you want to remove.
Tip

To select the entire list, select the check box in the header row.
Click Remove.
Confirm when prompted.

To add filter tags to a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Click Add Filter Tag.
In Tag Namespace, do one of the following:
- Select a namespace to add a defined tag as a filter.
- Select None (apply a free-form tag) to add a free-form tag as a filter.
In Tag Key, do one of the following:
- Select the tag key for the defined tag.
- Enter the tag key for the free-form tag.
Enter a Value.
Click Add Filter Tag.

To edit filter tags for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select a filter tag.
Click Edit. The Edit Attribute box appears.
Make your changes and click Save Changes.

To remove filter tags for a rule

Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
Choose a Compartment you have permission to work in, and then click the Name of the rule you want to update.
In the Resources menu, click Event Matching.
Select the check box next to the filter tags you want to remove.
Tip

To select the entire list, select the check box in the header row.
Click Remove.
Confirm when prompted.

Using the Command Line Interface (CLI)

When you use the CLI to create a rule, you work a little differently than using the Console.

To specify the actions for your rule, use a JSON formatted file. You create this file before you create the rule, and the file simplifies the amount of information you must type at the command line.
To specify an event to match, use a JSON formatted string. You type this right into the console as you create the rule.

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.

To create an action JSON file

To specify the actions for your rule, use a JSON formatted file. For more information, see Advanced JSON Options.

Create a file and add the following content. This content doesn't have to be escaped or on a single line, it just has to contain valid JSON.

{
  "actions": [
      {
        "actionType": "FAAS",
        "description": "string",
        "functionId": "<function_OCID>",
        "isEnabled": true
      },
      {
        "actionType": "ONS",
        "description": "string",
        "isEnabled": true,
        "topicId": "<topic_OCID>"
      },
      {
        "actionType": "OSS",
        "description": "string",
        "isEnabled": true,
        "streamId": "<stream_OCID>"
      }
  ]
}

Edit the file and remove any objects you don't want to use as an action. For example, if you wanted to only use Notifications as an action, then you would delete all the other objects.
```
{
  "actions": [
      {
        "actionType": "ONS",
        "description": "string",
        "isEnabled": true,
        "topicId": "<topic_OCID>"
      }
  ]
}
```

Edit the file and fill in any variables with actual values from your tenancy, as shown in the following example.

{
  "actions": [
      {
        "actionType": "ONS",
        "description": "string",
        "isEnabled": true,
        "topicId": "<topic_OCID>"
      }
  ]
}

Add a description.
Save the file as action.json

To create a rule and specify Notifications as an action, run the following command.

oci events rule create --display-name <friendly_name> --is-enabled true --condition "{}" 
--compartment-id <compartment_OCID> --actions file://action.json

To create a rule

Open a command prompt and run oci events rule create to create a rule.

Use the following options:

display-name indicates the name of the rule in the Console
is-enabled indicates whether Events should evaluate the rule.
condition a JSON formatted string used to indicate a pattern for event matching (see Examples for usage).

Examples

The following example shows how to pass a simple condition that matches all events. Everything between the double quotes (" ") is a string, while the brackets { } indicate JSON:
```
oci events rule create --display-name <friendly_name> --is-enabled true 
--condition "{}" --compartment-id <compartment_OCID> 
--actions file://action.json --wait-for-state=ACTIVE
```
To pass complex input to the CLI as a JSON string, you must enclose the entire block in double quotes. Inside the block, each double quote for the key and value strings must be escaped with a backslash (\) character. For example:
```
oci events rule create --display-name <friendly_name> --is-enabled true 
--condition "{\"eventType\":[\"com.oraclecloud.objectstorage.createobject\"]}" 
--compartment-id <compartment_OCID> --actions file://action.json 
--wait-for-state=ACTIVE
```
In PowerShell, to escape double quotes, you must use two characters: The backslash (\) and the back tick (`). For example, in Windows PowerShell:
```
oci events rule create --display-name <friendly_name> --is-enabled true 
--condition "{\`"eventType\`":[\`"com.oraclecloud.objectstorage.createobject\`"]}" 
--compartment-id <compartment_OCID> --actions file://action.json 
--wait-for-state=ACTIVE
```
Tip

The condition option does not support using a file to pass the JSON formatted string.

For information on creating filters, see Matching Events with Filters.
compartment-id indicates the compartment where the rule applies. Events evaluates messages from resources in this compartment and any subordinate compartments.
actions indicates the location in the local file system of the JSON formatted file you created to specify the actions for a rule.
wait-for-state= when used with ACTIVE indicates that the CLI should wait for the service to create the rule, do another GET operation, and then display the rule in the active state. Without the option, the CLI displays the rule immediately in the creating state.

For example:

oci events rule create --display-name <friendly_name> --is-enabled true 
--condition <json_formatted_string> --compartment-id <compartment_OCID> 
--actions <json_formatted_file> --wait-for-state=ACTIVE

Note

Replace the values in <compartment_OCID> and <json_formatted_file> with the actual values from your tenancy and the local file system.

To delete a rule

Open a command prompt and run oci events rule delete to delete a single rule. For example:

oci events rule delete --rule-id <rule_OCID>

The command returns a prompt, asking for confirmation. Type y to delete the rule.

To get rule metadata

You can get rule metadata using the CLI. The Console displays this metadata in the Rule Details tab.

Open a command prompt and run oci events rule get to get information about a single rule. For example:

oci events rule get --rule-id <rule_OCID>

The command returns the following information:

{
  "data": {
    "actions": {
      "actions": [
        {
          "action-type": "ONS",
          "description": null,
          "id": "ocid1.eventaction.oc1.phx.<unique_ID>",
          "lifecycle-message": null,
          "lifecycle-state": "ACTIVE",
          "topic-id": "ocid1.onstopic.oc1.phx.<unique_ID>"
        }
      ]
    },
    "compartment-id": "ocid1.compartment.oc1..<unique_ID>",
    "condition": "{\n  \"eventType\": [\n    \"com.oraclecloud.databaseservice.autonomous.datawarehouse.backup.end\",\n    \"CustomEventType\"\n  ]\n}",
    "defined-tags": null,
    "description": null,
    "display-name": "rule_name",
    "freeform-tags": null,
    "id": "ocid1.eventrule.oc1.phx.<unique_ID>",
    "is-enabled": true,
    "lifecycle-message": null,
    "lifecycle-state": "ACTIVE",
    "time-created": "2019-01-23T00:48:20.155000+00:00"
  },
  "etag": "<unique_ID>--gzip"
}

To get a list of rules

Open a command prompt and run oci events rule list to list the rules in a compartment. For example:

oci events rule list --compartment-id <compartment_OCID>

The command returns the following information:

{
  "data": [
    {
      "compartment-id": "ocid1.compartment.oc1..<unique_ID>",
      "condition": "{}",
      "description": "Example_Rule",
      "display-name": "rule_1",
      "id": "ocid1.eventrule.oc1.phx.<unique_ID>",
      "is-enabled": true,
      "lifecycle-state": "ACTIVE",
      "time-created": "2019-01-22T20:10:53.562000+00:00"
    },
    {
      "compartment-id": "ocid1.compartment.oc1..<unique_ID>",
      "condition": "{}",
      "description": null,
      "display-name": "rule_2",
      "id": "ocid1.eventrule.oc1.phx.<unique_ID>",
      "is-enabled": true,
      "lifecycle-state": "ACTIVE",
      "time-created": "2019-01-22T20:27:25.099000+00:00"
    },
    
    ...


    {
      "compartment-id": "ocid1.compartment.oc1..<unique_ID>",
      "condition": "{\"eventType\":[\"com.oraclecloud.objectstorage.createobject\"]}",
      "description": null,
      "display-name": "rule_75",
      "id": "ocid1.eventrule.oc1.phx.<unique_ID>",
      "is-enabled": true,
      "lifecycle-state": "ACTIVE",
      "time-created": "2019-01-22T23:08:12.379000+00:00"
    }
  ]
}

To update a rule

Open a command prompt and run oci events rule update to update a rule.

To update the condition for a rule:

oci events rule update --rule-id <rule_OCID> --condition <json_formatted_string>

For example:

oci events rule update --rule-id ocid1.eventrule.oc1.phx.<unique_ID> --condition "{}" --wait-for-state=ACTIVE

The previous command would update the condition of the rule to use an empty JSON string. The CLI updates the rule, waits for the rule to update and change to the active state (only if you used the --wait-for-state option), then displays the updated rule.

Use the following options to update a rule:

display-name
description
is-enabled
condition
actions
freeform-tags
defined-tags

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to manage rules:

Oracle Cloud Infrastructure Documentation