Oracle by Example brandingUse Cloud Notification Service with Exadata Cloud at Customer

section 0Before You Begin

This tutorial shows you how to use Cloud Notification Service in conjunction with Exadata Cloud at Customer.

Background

Oracle Database Exadata Cloud at Customer is integrated with Cloud Notification Service (CNS), which provides notification for events that affect the status of system components.

In this tutorial you will learn how to:

  • View CNS event notifications that are automatically posted in the My Services dashboard.
  • Use the CNS REST API to manage subscription to email notifications for events relating to Exadata Cloud at Customer.

What Do You Need?

An Exadata Cloud at Customer environment with the following characteristics:

  • Exadata Cloud at Customer release 18.1.4.3, or later.
  • A service instance is already created.
  • At least one VM cluster is already created.
  • At least one database is already created.

section 1View notifications in the My Services dashboard

  1. In the My Services dashboard, click the bell icon.

    Description of Notification1.png follows
    The My Services dashboard with the Notification (bell) icon highlighted.

  2. In the resulting pop-up, click Go to Notifications.

    Description of Notification2.png follows
    The My Services dashboard with the Notifications pop-up showing.

  3. In the Notifications page, use the Topic Messages tab to view notification messages. Use the filter to view specific notification messages for Exadata Cloud at Customer.

    Description of Notification3.png follows
    The Topic Messages tab in the Notifications page.

  4. You can click a notification entry to view further details for the event.

    Following is an example:

    Description of Notification4.png follows
    Notification details for an Exadata Cloud at Customer CNS event.

    The same message details are sent to users that are registered to receive the notification. In the remainder of this tutorial, you will use the CNS REST API to manage subscription to email notifications for events relating to Exadata Cloud at Customer.

section 2Get information about CNS topics for Exadata Cloud at Customer

Before you can use the CNS REST API, you must gather some basic information about your Exadata Cloud at Customer environment, and about the CNS topics that relate to Exadata Cloud at Customer.

  1. Connect to the My Services dashboard and select the View Details menu option from the menu associated with Exadata Cloud at Customer.

    Description of ViewDetails.png follows
    Selecting the View Details option

  2. Take note of the following values in the Additional Details section:

    • Identity Service Id: You will use this value to set the account context in your REST calls.
    • Service Instance ID: Also known as the Entitlement ID, you will use this value to identify relevant CNS topics.
    Description of idcsID.png follows
    The Identity Service Id and Service Instance ID

  3. Take note of the REST Endpoint that is associated with the Exadata Cloud at Customer instance that you are working with. You will use a modified version of this REST endpoint as the endpoint for the CNS REST calls.

    Description of REST.png follows
    The REST Endpoint

  4. In the action menu that is associated with the Exadata Cloud at Customer instance, click Manage Clusters.

    Description of ManageClusters.png follows
    Selecting the Manage Clusters option

  5. Take note of the Cluster Name of the VM cluster that you are working with. You will use this value to identify relevant CNS topics.

    Description of ClusterName.png follows
    The Cluster Name

  6. Perform a REST call to get CNS topic names and attributes.

    Substitute your previously gathered values for the following:

    • REST endpoint: Take the REST Endpoint value that you observed in the My Services application and replace the initial hostname (psm) with cns. Use the resulting endpoint value as the REST endpoint is your CNS REST calls. Note that the domain name for your Exadata Cloud at Customer environment will differ from the domain name used in this tutorial.
    • Identity Service Id: The examples in this tutorial use idcs-e1f969ba6de24d88a0a2d42c60c426c9 as the Identity Service Id. Substitute this value and use the value that is associated with your Exadata Cloud at Customer environment, which you observed in the My Services application.
    • User information: The examples in this tutorial use Username:Pa55word as the username and password for authentication to the service. Substitute these values and use your own user information.
    • X-USER-IDENTITY-DOMAIN-NAME header value: This header uses the same value as the Identity Service Id. The examples in this tutorial use idcs-e1f969ba6de24d88a0a2d42c60c426c9.

    For example:

    curl -X GET https://cns.ocm.scacaa08.testoraclecloudatcust.com/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences?expands=myPreferences -u Username:Pa55word -H 'content-type: application/json' -H 'X-USER-IDENTITY-DOMAIN-NAME: idcs-e1f969ba6de24d88a0a2d42c60c426c9'

    Following is a sample of the output from the REST call:

    {
    "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences", 
    "items": [
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162/additionalRecipients"
            }, 
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162", 
            "displayName": "Oracle Database Exadata Cloud at Customer Service", 
            "id": "6D7A4347F2357ECAE053EB3040646162", 
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162/myPreferences", 
                "email": "default", 
                "sms": "default"
            }, 
            "serviceEntitlementId": "500056812", 
            "serviceType": "ExadataCM"
        }, 
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical/additionalRecipients"
            },
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical",
            "displayName": "Critical",
            "id": "6D7A4347F2357ECAE053EB3040646162.critical",
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical/myPreferences",
                "email": "default",
                "sms": "default"
            },
            "parent": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162",
                "id": "6D7A4347F2357ECAE053EB3040646162"
            },
            "serviceEntitlementId": "500056812",
            "serviceType": "ExadataCM",
            "topic": {
                "description": "This is Critical",
                "displayName": "Critical",
                "id": "critical"
            }
        },
...
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients"
            },
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database",
            "displayName": "Critical exacc1.database",
            "id": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database",
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/myPreferences",
                "email": "default",
                "sms": "default"
            },
            "parent": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1",
                "id": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1"
            },
            "serviceEntitlementId": "500056812",
            "serviceType": "ExadataCM",
            "topic": {
                "description": "This is subtopic exacc1.database of topic Critical",
                "displayName": "Critical exacc1.database",
                "id": "critical.exacc1.database"
            }
        },
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c/additionalRecipients"
            },
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c",
            "displayName": "Critical exacc1.database.db12c",
            "id": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c",
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c/myPreferences",
                "email": "default",
                "sms": "default"
            },
            "parent": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database",
                "id": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database"
            },
            "serviceEntitlementId": "500056812",
            "serviceType": "ExadataCM",
            "topic": {
                "description": "This is subtopic exacc1.database.db12c of topic Critical",
                "displayName": "Critical exacc1.database.db12c",
                "id": "critical.exacc1.database.db12c"
            }
        },
...
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.informational/additionalRecipients"
            },
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.informational",
            "displayName": "Informational",
            "id": "6D7A4347F2357ECAE053EB3040646162.informational",
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.informational/myPreferences",
                "email": "default",
                "sms": "default"
            },
            "parent": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162",
                "id": "6D7A4347F2357ECAE053EB3040646162"
            },
            "serviceEntitlementId": "500056812",
            "serviceType": "ExadataCM",
            "topic": {
                "description": "This is Informational",
                "displayName": "Informational",
                "id": "informational"
            }
        },
...
        {
            "additionalRecipients": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.warning/additionalRecipients"
            },
            "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.warning",
            "displayName": "Warning",
            "id": "6D7A4347F2357ECAE053EB3040646162.warning",
            "myPreferences": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.warning/myPreferences",
                "email": "default",
                "sms": "default"
            },
            "parent": {
                "canonicalLink": "/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162",
                "id": "6D7A4347F2357ECAE053EB3040646162"
            },
            "serviceEntitlementId": "500056812",
            "serviceType": "ExadataCM",
            "topic": {
                "description": "This is a Warning",
                "displayName": "Warning",
                "id": "warning"
            }
        },
...

    Observe the following about the output:

    • Each item in the output contains a serviceEntitlementId. Items that relate back to your Exadata Cloud at Customer environment have a serviceType of ExadataCM, and a serviceEntitlementId that matches the Service Instance ID that you observed in the My Services dashboard (in step 2).
    • Each item represents a node in the hierarchical structure of CNS topics. The CNS topic name is contained in the item id. For example: 6D7A4347F2357ECAE053EB3040646162.critical.
    • Items that relate to a specific VM cluster contain the Cluster Name that you observed in the My Services dashboard (in step 5) embedded in the CNS topic name. For example: 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.
    • Items that relate to a specific Exadata Cloud at Customer database contain the database name (dbname) embedded in the CNS topic name. For example: 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c.
    • When you register to receive notifications for a CNS topic you receive notifications for that topic and all subtopics in the topic hierarchy. For example:
      • If you register for notifications using the topic 6D7A4347F2357ECAE053EB3040646162.critical, you then receive all critical notifications that are associated with the related serviceEntitlementId, which could include numerous Exadata Cloud at Customer instances and VM clusters.
      • If you register for notifications using a subtopic that identifies a specific VM cluster (for example: 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database), you then only receive critical notifications that are associated with the specified cluster (for example: exacc1), which could include numerous databases.
      • If you register using a subtopic that identifies a specific database (for example: 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.db12c), you then only receive critical notifications that are associated with the specified database (for example: db12c).

section 3List recipients that are registered with a CNS topic

  1. You can use the CNS REST API to list recipients that are registered with a CNS topic.

    For example, the following call lists the recipients that are registered to receive critical notifications relating to the Exadata Cloud at Customer VM cluster named exacc1, using the CNS topic 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.

    curl -i -X GET https://cns.ocm.scacaa08.testoraclecloudatcust.com/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients -u Username:Pa55word -H "Content-Type: application/json" -H 'X-USER-IDENTITY-DOMAIN-NAME: idcs-e1f969ba6de24d88a0a2d42c60c426c9'

    Following is a sample of the output from the REST call:

    {
"canonicalLink":./.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients", 
    "items": [
        {
            "canonicalLink": "./.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients/70da4a33-5018-8b64-e053-e9304064bdaa", 
            "channelType": "email", 
            "emailAddress": "user1@example.com", 
            "id": "70da4a33-5018-8b64-e053-e9304064bdaa", 
            "locale": "en_US", 
            "topicPreferenceId": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database"
        },
        {
            "canonicalLink": "./.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients/72bea56a-41a0-0860-e053-eb3040641f08", 
            "channelType": "email", 
            "emailAddress": "user2@example.com", 
	        "id": "72bea56a-41a0-0860-e053-eb3040641f08"
            "locale": "en_US", 
            "topicPreferenceId": "6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database 
        }
    ]
}

    In the output, note that every recipient has a unique ID, which can be used to unsubscribe if needed. In the above example, user1@example.com has the recipient ID 70da4a33-5018-8b64-e053-e9304064bdaa and user2@example.com has the recipient ID 72bea56a-41a0-0860-e053-eb3040641f08.

section 4Register a recipient to receive email notifications

  1. You can use the CNS REST API to register a recipient to receive email notifications for a CNS topic.

    For example, the following call registers user3@example.com to receive email notifications for critical notifications relating to the VM cluster named exacc1, using the CNS topic 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.

    curl -i -X POST https://cns.ocm.scacaa08.testoraclecloudatcust.com/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients -u Username:Pa55word -H "Content-Type: application/json" -H 'X-USER-IDENTITY-DOMAIN-NAME: idcs-e1f969ba6de24d88a0a2d42c60c426c9' -d '{"channelType":"email","emailAddress":"user3@example.com"}'

    Following is a sample of the output from the REST call:

    HTTP/1.1 201 Created
Server: LBAAS
Date: Mon, 11 Mar 2019 09:30:40 GMT
Content-Length: 0
Connection: keep-alive
Location: https://cns.ocm.scacaa08.testoraclecloudatcust.com:443/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients/80b2bb9b-6b41-3545-e053-e9304064f9d1
X-ORACLE-DMS-ECID: c03a2a34-2afe-41b8-9bdb-a35ad786f0a2-01f3cbed
X-ORACLE-DMS-RID: 0
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubdomains;

    In the output, you can see that user3@example.com is associated with the recipient ID 80b2bb9b-6b41-3545-e053-e9304064f9d1.

section 5Unsubscibe a notification recipient

  1. You can use the CNS REST API to unsubscibe a notification recipient by using their recipient ID.

    For example, the following call unsubscribes user1@example.com, using the recipient ID 70da4a33-5018-8b64-e053-e9304064bdaa, from receiving critical email notifications relating to the VM cluster named exacc1, using the CNS topic 6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database.

    curl -i -X DELETE https://cns.ocm.scacaa08.testoraclecloudatcust.com/notification/idcs-e1f969ba6de24d88a0a2d42c60c426c9/.Customer/api/v1/topicPreferences/6D7A4347F2357ECAE053EB3040646162.critical.exacc1.database/additionalRecipients/70da4a33-5018-8b64-e053-e9304064bdaa -u Username:Pa55word -H "Content-Type: application/json" -H 'X-USER-IDENTITY-DOMAIN-NAME: idcs-e1f969ba6de24d88a0a2d42c60c426c9'

    If the recipient is deleted successfully, the output from the REST call includes the HTTP response code: 204 No Content. For example:

    HTTP/1.1 204 No Content
Server: LBAAS
Date: Mon, 11 Mar 2019 09:44:12 GMT
Connection: keep-alive
X-ORACLE-DMS-ECID: c03a2a34-2afe-41b8-9bdb-a35ad786f0a2-01f3e924
X-ORACLE-DMS-RID: 0
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubdomains;

    If an invalid recipient entry is specified, the output from the REST call includes the HTTP response code: 404 Not Found. For example:

    HTTP/1.1 404 Not Found
Server: LBAAS
Date: Mon, 11 Mar 2019 09:45:14 GMT
Content-Type: application/json
Content-Length: 167
Connection: keep-alive
X-ORACLE-DMS-ECID: c03a2a34-2afe-41b8-9bdb-a35ad786f0a2-01f3eb59
X-ORACLE-DMS-RID: 0
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubdomains;

{"httpStatusCode":404,"httpMessage":"Not Found","errorCode":"urn:oracle:cloud:errorcode:notification:not-found","errorMessage":"Topic additional recipient not found."

more informationWant to Learn More?