Managing Topics and Subscriptions
This section describes how to manage topics and their subscriptions .
A topic is a communication channel for sending messages to its subscriptions. A topic can have zero, one, or multiple subscriptions that are notified whenever a message is published to a topic.
Prerequisites
IAM policies: To use Notifications, 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. For Functions, you must have FN_INVOKE
permission against the function to be able to add the function as a subscription to a topic. To authorize your function for access to other Oracle Cloud
Infrastructure resources, such as Compute instances, include the function in a dynamic group and create a policy to grant the dynamic group access to those resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.
If you get a response that you don’t have permission or are unauthorized, check with your administrator. You may not have the required type of access in the current compartment . For more information on user authorizations, see Notifications Overview.
Creating Automation with Functions and Events
You can create automation by publishing messages to function subscriptions. For an example of a function subscription, see Scenario A: Automatically Resize VMs.
You can create also automation based on state changes of your topics and subscriptions (Notifications resources) by using event types, rules, and actions. For more information, see Overview of Events.
Using the Console
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- Click Create Topic at the top of the topic list.
-
In the Create Topic dialog box, configure your topic.
- Name: Required. Specify a friendly name for the topic. It must be unique across the tenancy; validation is case-sensitive. Avoid entering confidential information.
- Description: Optional. Enter a description for the topic. Avoid entering confidential information.
- Click Create.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- For the topic you want to delete, click the Actions icon (three dots), and then click Delete.
- Confirm when prompted.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- Click the name of the topic you want to update.
- On the topic detail page, next to Description, click the edit icon.
- Edit the description.
- Click the save icon.
Associated subscriptions remain in their current compartments. For more information, see Moving Topics and Subscriptions to a Different Compartment.
To move resources between compartments, resource users must have sufficient access permissions on the compartment that the resource is being moved to, as well as the current compartment. For more information about permissions for Notifications resources, see Details for the Notifications Service.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- In the Scope section, select a compartment.
- Find the topic in the list, click the Actions icon (three dots), and then click Move Resource.
- Choose the destination compartment from the list.
- Click Move Resource.
While new subscriptions must be created in the same compartment as the topic, you can move them to different compartments after creating them.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- Click the name of the topic that you want to add the subscription to.
- On the topic detail page, click Create Subscription.
-
In the Create Subscription dialog box, configure your subscription for the protocol you want:
Email subscriptionSends an email message when you publish a message to the subscription's parent topic .
- Protocol: Select Email.
- Email: Type an email address.
Function subscriptionRuns the specified function when you publish a message to the subscription's parent topic . For example, runs a function to resize VMs when an associated alarm is triggered.
Note
You must have
FN_INVOCATION
permission against the function to be able to add the function as a subscription to a topic.The Notifications service has no information about a function after it's invoked. For more details, see the troubleshooting information at Function not invoked or run.
Confirmation is not required for function subscriptions.
- Subscription Protocol: Select Function.
- Function Compartment: Select the compartment containing your function.
- Function Application: Select the application containing your function.
- Function: Select your function.
HTTPS (Custom URL) subscriptionSends specified information when you publish a message to the subscription's parent topic .
Endpoint format (URL using HTTPS protocol):
https://<anyvalidURL>
Basic access authentication is supported, allowing you to specify a username and password in the URL, as inhttps://user:password@domain.com
orhttps://user@domain.com
. The username and password are encrypted over the SSL connection established when using HTTPS. For more information about Basic Access Authentication, see RFC-2617.Query parameters are not allowed in URLs.- Protocol: Select HTTPS (Custom URL).
- URL: Type (or copy and paste) the URL you want to use as the endpoint.
PagerDuty subscriptionCreates a PagerDuty incident by default when you publish a message to the subscription's parent topic .
Endpoint format (URL):
https://events.pagerduty.com/integration/<integrationkey>/enqueue
Query parameters are not allowed in URLs.To create an endpoint for a PagerDuty subscription (set up and retrieve an integration key), see the PagerDuty documentation.
- Protocol: Select PagerDuty.
- URL: Type (or copy and paste) the integration key portion of the URL for your PagerDuty subscription. (The other portions of the URL are hard-coded.)
Slack subscriptionSends a message to the specified Slack channel by default when you publish a message to the subscription's parent topic .
Endpoint format (URL):
https://hooks.slack.com/services/<webhook-token>
The <webhook-token> portion of the URL contains two slashes (/).
Query parameters are not allowed in URLs.To create an endpoint for a Slack subscription (using a webhook for your Slack channel), see the Slack documentation.
- Protocol: Select Slack.
- URL: Type (or copy and paste) the Slack endpoint, including your webhook token.
-
Click Create.
The subscription has been created.
Subscriptions using protocols that require confirmation, such as Email, remain in "Pending" status until confirmation is received. For these subscriptions, a subscription confirmation URL is sent. For detailed steps, see To confirm a subscription.
Confirmation is not required for function subscriptions.
Navigate to the confirmation URL that is sent to the subscription's endpoint.
Some protocols provide confirmation URLs in unique ways:
- HTTPS (Custom URL): You can find the confirmation URL in the request header or body of the subscription confirmation message (request of content-type: "application/json") that is sent to the endpoint.
In the request header, see the value of the
X-OCI-NS-ConfirmationURL
field.Example request header:"X-OCI-NS-SignatureVersion":"1.0" "X-OCI-NS-Signature":"<example-signature>" "X-OCI-NS-SigningCertURL":"<example-url>" "X-OCI-NS-TopicOcid":"ocid.compartment.oc1..<unique_ID>" "X-OCI-NS-Timestamp":"2019-04-19T21:26:00.310+0000" "X-OCI-NS-MessageId":"<unique_ID>" "X-OCI-NS-TopicName":"mytopic" "X-OCI-NS-MessageType":"SubscriptionConfirmation" "X-OCI-NS-ConfirmationURL":"<exampleConfirmationURL>" "X-OCI-NS-SubscriptionId":"ocid1.onssubscription.oc1.phx.<unique_ID>" "X-OCI-NS-State":"Pending"
In the request body, see the value of the
ConfirmationURL
key.Example ConfirmationURL key and value (request body):
"ConfirmationURL":"<exampleConfirmationURL>"
- PagerDuty: Incident titled "Oracle Notification Service Subscription Confirmation". For more information, see the PagerDuty documentation for Oracle Cloud Infrastructure.
- Slack: Message sent to Slack channel containing the text "To confirm the subscription".
The ability to resend subscription confirmations is only applicable for pending subscriptions.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- For the subscription you want to resend the confirmation for, click the Actions icon (three dots), and then click Resend Confirmation.
The retry duration is part of the delivery policy for the subscription. By default, Notifications retries delivery of a message for up to two hours.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
-
For the subscription you want to update, click the Actions icon (three dots), and then click Update Delivery Policy.
- In the Update Delivery Policy dialog box, click the edit icon for Max Retry Duration in Minutes, type the new value, and then click the save icon.
The associated topic remains in its current compartment. For more information, see Moving Topics and Subscriptions to a Different Compartment.
To move resources between compartments, resource users must have sufficient access permissions on the compartment that the resource is being moved to, as well as the current compartment. For more information about permissions for Notifications resources, see Details for the Notifications Service.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- In the Scope section, select a compartment.
- Find the subscription in the list, click the Actions icon (three dots), and then click Move Resource.
- Choose the destination compartment from the list.
- Click Move Resource.
Every message sent out as email contains a link to unsubscribe from the related topic.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- For the subscription you want to delete, click the Actions icon (three dots), and then click Delete.
- Confirm when prompted.
Managing Tags for a Topic or Subscription
You can apply tags to your resources, such as topics and subscriptions, to help you organize them according to your business needs. You can apply tags at the time you create a topic or subscription, or you can update the topic or subscription later with the tags you want. For general information about applying tags, see Resource Tags.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- Choose the Compartment that contains the topic you want to tag, and then click the topic'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.
- Open the navigation menu. Under Solutions and Platform, go to Application Integration and click Notifications.
- Choose the Compartment that contains the subscription you want to tag, and then click the name of the topic that has the subscription.
-
For the subscription you want to tag, click the Actions icon (three dots), and then click Add Tags.
To view or edit existing tags, click the Actions icon (three dots), and then click View Tags.
For more information, see Resource 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 these API operations to manage topics:
Use these API operations to manage subscriptions: