Getting Started with Events

This topic introduces you to creating automation with Events. You create a simple rule that sends a notification whenever someone creates a bucket in a particular compartment in your tenancy.

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Setting Up for Events

To try out the Events service for this tutorial, you must have these things set up first:

  • Create IAM policy for Events
  • Create a topic and subscription to use as an action
Important

A tenancy administrator must configure your tenancy for Events. These configurations give you access to an Oracle Cloud Infrastructure tenancy with the necessary IAM policy and a resource to use as an action.

Create Users, Groups, and Compartments

You can use existing users, groups, and compartments or make new ones.

To create groups and users

If suitable users and groups for assigning users permissions to work with rules don't already exist, log in to the Console as a tenancy administrator and create them.

  1. Log in to the Console as a tenancy administrator.
  2. If you need a group for Events, perform these steps:
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups. A list of the groups in your tenancy is displayed.
    2. Click Create Group and create a new group (see To create a group). Give the group a meaningful name and description. Avoid entering confidential information.

      This image shows how to create a group.

  3. If you need user accounts for Events, perform these steps:
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Users. A list of the users in your tenancy is displayed.
    2. Click Create User and create one or more new users (see To create a user).

      This images shows how to create a user

  4. If users haven't been added to groups already, perform these steps:
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups. A list of the groups in your tenancy is displayed.
    2. Click the group you want to use for Events.
    3. Click Add User to Group.

      This image shows how to add a user to a group

    4. Select the users from the drop-down list, and then click Add.

To create a compartment

If suitable compartment for rules and the resources that emit events doesn't already exist, log in to the Console as a tenancy administrator and create it.

  1. Log in to the Console as a tenancy administrator.
  2. Open the navigation menu. Under Governance and Administration, go to Identity and click Compartments. A list of the compartments in your tenancy is displayed.
  3. Click Create Compartment and create a new compartment (see To create a compartment). Give the compartment a meaningful name and description. Avoid entering confidential information.

    This screenshot shows how to create a compartment

Create IAM Policy for Events

Before users can start using Events to create automation, as a tenancy administrator you must create IAM policy: 

To create a policy that allows users to create and manage rules

  1. Log in to the Console as a tenancy administrator.
  2. In the Console, open the navigation menu. Under Governance and Administration, go to Identity and click Policies. A list of the policies in the compartment you're viewing is displayed.
  3. Select the root compartment.
  4. Click Create Policy.
  5. Enter the following:
    • Name: A meaningful name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
    • Description: A meaningful description. You can change this later if you want to. Avoid entering confidential information.
    • Statement: Enter the following policy statements to give users in the group the ability to manage and create rules:

      This line gives the user inspect access to resources in compartments to select actions.

      allow group <RuleAdmins> to inspect compartments in tenancy

      This line gives the user access to defined tags to apply filter tags to rules.

      allow group <RuleAdmins> to use tag-namespaces in tenancy

      These lines give the user access to Streaming resources for actions

      allow group <RuleAdmins> to inspect streams in tenancy
      allow group <RuleAdmins> to use stream-push in tenancy
      allow group <RuleAdmins> to use stream-pull in tenancy

      These lines give the user access to Functions resources for actions.

      allow group <RuleAdmins> to use virtual-network-family in tenancy
      allow group <RuleAdmins> to manage function-family in tenancy

      This line give the user access to Notifications topics for actions.

      allow group <RuleAdmins> to use ons-topic in tenancy

      This line gives the user manage access to rules for Events.

      allow group <RuleAdmins> to manage cloudevents-rules in tenancy
  6. Click Create.

To create a policy that allows the Events service to deliver event messages to a topic

  1. Log in to the Console as a tenancy administrator.
  2. In the Console, open the navigation menu. Under Governance and Administration, go to Identity and click Policies. A list of the policies in the compartment you're viewing is displayed.
  3. Select the root compartment.
  4. Click Create Policy.
  5. Enter the following:
    • Name: A meaningful name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later. Avoid entering confidential information.
    • Description: A meaningful description. You can change this later if you want to. Avoid entering confidential information.
    • Statement: Enter the following policy statement to give the Events service the ability to deliver events messages to a topic:

      allow service cloudEvents to use ons-topic in tenancy

      The following lines provide policy for Events to deliver event messages to functions and streams: 

      allow service cloudEvents to use functions-family in tenancy
      allow service cloudEvents to use stream-push in tenancy 
      allow service cloudEvents to read streams in tenancy					
  6. Click Create.

Create Notifications Topic and Subscription

If a suitable Notifications topic doesn't already exist, then you must log in to the Console as a tenancy administrator and create it. Whether you use an existing topic or create a new one, add an email address as a subscription so that you can monitor that email account for notifications.

To create a topic

  1. Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
  2. Click Create Topic at the top of the topic list.

    This screenshot shows how to create a topic

  3. In the Create Topic dialog box, configure your topic.
    • Name: Required. Specify a friendly name for the topic. It must be unique; validation is case-sensitive. Avoid entering confidential information.
    • Description: Optional. Enter a description for the topic. Avoid entering confidential information.
  4. Click Create.

To create a subscription

  1. Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
  2. Click the name of the topic that you created in the previous step or the topic you intend to use for this tutorial.
  3. On the topic detail page, click Create Subscription.

    This screenshot shows how to create a subscription.

  4. In the Create Subscription dialog box, select Email, and then type an email address.

    This screenshot shows how to create an email subscription.

  5. Click Create.

    The subscription has been created and a subscription confirmation URL will be sent. The subscription remains in "Pending" status until it has been confirmed.

To confirm a subscription

  • In the confirmation email sent to the address you specified in the previous procedure, click the confirmation URL.  

Using the Console to Create a Rule

Use the Console to create a rule with a pattern that matches bucket creation events emitted by Object Storage. Specify the Notifications topic you created as an action to deliver matching events. To test your rule, create a bucket. Object Storage emits an event which triggers the action. Check the email specified in the subscription to receive your notification.

To create a rule
  1. Open the navigation menu. Under the Solutions and Platform group, go to Application Integration and click Events Service.
  2. 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.

  3. 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. Avoid entering confidential information.
  4. In Event Matching, select Event Type.
    1. In Service Name, select Object Storage.
    2. In Event Type, select Object Storage - Create Bucket.
  5. In Actions, specify the actions to trigger when the filter finds a match: 
    1. In Action Type, select Notifications.
    2. In Notifications Compartment, select the compartment that contains the topic.
    3. In Topic, select the topic.
  6. Click Create Rule.
To create a bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Select the compartment where you created your rule (or any of its subordinate compartments).
  3. Click Create Bucket.

    This screenshot shows how to create a bucket.

  4. In the Create Bucket dialog, specify the attributes of the bucket:
    • Name: Required. A user-friendly name or description. Avoid entering confidential information.
    • Storage Tier: Select the tier in which you want to store your data. Available tiers include:

      • Standard is the primary default Object Storage tier for storing data that is accessed frequently and requires fast and immediate access.
      • Archive is a special tier for storing data that is accessed infrequently and requires long retention periods. Access to data in the Archive tier is not immediate. You must restore archived data before it’s accessible. For more information, see Overview of Archive Storage.
  5. Click Create Bucket.
To receive your notification
  • Log in to the email account you specified in the previous procedure to receive the notification about the bucket being created.

    This screenshot shows a notification.

    Tip

    You will receive notifications each time a bucket is created in the compartment (or any of its sub compartments) until you disable the rule.

Using the CLI to Create a Rule

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.
To create an action file
  1. Create a file and add the following content.
    {
      "actions": [
          {
            "actionType": "ONS",
            "description": "string",
            "isEnabled": true,
            "topicId": "<topic_OCID>"
          }
      ]
    }

    Tip: You can specify functions, streams, or topics as an action.

    Example action file template
    {
      "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>"
          }
      ]
    }
  2. Fill in <topic_OCID> with actual topic OCID value from your tenancy.
  3. Add a description.
  4. Save the file with action.json as the file name.
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 the rule is evaluated.
  • condition a JSON formatted string used to indicate a pattern for event matching (see Examples for usage).

    Examples

  • compartment-id indicates the compartment where the rule applies. Events evaluates messages from resources in this compartment and any child 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 CLI-created_rule --is-enabled true --condition "{\"eventType\":[\"com.oraclecloud.objectstorage.createbucket\"]}" --compartment-id <compartment_OCID> --actions <path_to_json_formatted_actions_file> --wait-for-state=ACTIVE
Note

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

When you run the preceding command, the CLI prompts you about the rule and its display: 

 Action completed. Waiting until the resource has entered state: ACTIVE
{
  "data": {
    "actions": {
      "actions": [
        {
          "action-type": "ONS",
          "description": "Notifications action",
          "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": "{\"eventType\":[\"com.oraclecloud.objectstorage.createbucket\"]}",
    "defined-tags": {},
    "description": null,
    "display-name": "CLI-created_rule",
    "freeform-tags": {},
    "id": "ocid1.eventrule.oc1.phx.<unique_ID>",
    "is-enabled": true,
    "lifecycle-message": null,
    "lifecycle-state": "ACTIVE",
    "time-created": "2019-04-25T01:32:56.855000+00:00"
  },
  "etag": "<unique_ID>--gzip"
}
To create a bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Select the compartment where you created your rule (or any of its subordinate compartments).
  3. Click Create Bucket.
  4. In the Create Bucket dialog, specify the attributes of the bucket:
    • Name: Required. A user-friendly name or description. Avoid entering confidential information.
    • Storage Tier: Select the tier in which you want to store your data. Available tiers include:

      • Standard is the primary default Object Storage tier for storing data that is accessed frequently and requires fast and immediate access.
      • Archive is a special tier for storing data that is accessed infrequently and requires long retention periods. Access to data in the Archive tier is not immediate. You must restore archived data before it’s accessible. For more information, see Overview of Archive Storage.
  5. Click Create Bucket.
To receive your notification
  • Log in to the email account you specified in the previous procedure to receive the notification about the bucket being created.

    Tip

    You receive notifications each time a bucket is created in the compartment (or any of its sub compartments) until you disable the rule.