Integrating with Event Notifications
As an administrator of App Configuration, you might want to send notifications of events in App Configuration to other users, or human destinations, by using email, SMS, or other supported delivery channels. Additionally, you might want to send these notifications of events to other applications to build logic by using event-driven programming that uses webhooks, for example. This is made possible by the integration between App Configuration and Event Notifications.
To send information to Event Notifications, you must connect your App Configuration service instance to Event Notifications. For more information about working with Event Notifications, see Getting started with Event Notifications.
How events are collected and sent by App Configuration?
When an event of interest takes place in your App Configuration instance, App Configuration communicates with a connected Event Notifications instance to forward a notification to a supported destination.
Events for App Configuration
The following table lists the App Configuration actions that generate an event.
Event name | Event type | Subtype | Severity level |
---|---|---|---|
Test event | com.ibm.cloud.apprapp.test_event |
Low | |
Feature flag toggle | com.ibm.cloud.apprapp.feature_flag_toggle |
enabled disabled |
High |
Enabling notifications with Event Notifications
Events that are generated by an instance of the App Configuration service can be forwarded to an Event Notifications service instance that is available in the same account. You can configure only one App Configuration instance to one Event Notifications service instance. To get started, you need:
- Manage service access on the App Configuration service.
- Manage service access on the Event Notifications service. To view an existing Event Notifications service instance in your account, you also need Viewer platform access or higher.
Connecting to Event Notifications in the UI
Before you begin integrating Event Notifications with App Configuration, you need to create an Event Notifications service instance in the same account as your App Configuration instance. Make sure you have IAM role Manager for IBM App Configuration, and IAM service-to-service authorization.
If you are using App Configuration CLI or API to create integration with a Event Notifications service instance, ensure that you have enabled authorization to grant access between services before integrating with Event Notifications. For more information, see Using authorizations to grant access between services.
To integrate with a Event Notifications service, perform the following steps:
-
From your App Configuration service instance dashboard, click Integrations. By default, the integrations display the services that are supported along with integrations in the current App Configuration service.
-
From Event Notifications tile, click Connect +. This displays the Connect to Event Notifications side panel.
Create Event Notifications integration -
Enter the Source Details. The source details provided will be referenced in Event Notifications.
- Name - Enter the name for your App Configuration instance to be referenced in Event Notifications.
- Description - Optionally, provide a short description about this source.
-
Provide the following Event Notifications instance details, if you already have an Event Notifications instance. Otherwise, click the Create new instance.
- Resource Group - Select the resource group where your Event Notifications instance is created from the list.
- Event Notifications service instance - Select the Event Notifications service instance from the list.
-
Click Save to apply the integration.
An error is displayed if no IAM service-to-service authorization enabled, and the integration details will not be saved.
The integrated Event Notifications details are listed under Connected instance.
The overflow menu of the Connected instance consists of:
- Refresh - Select this option to refresh the details of Event Notifications instance integration.
- Disconnect - Select this option to disconnect the Event Notifications instance integrated earlier with your App Configuration service instance.
After successful integration, you need to create Topics, Destinations, and Subscriptions in Event Notifications to be notified of events that are generated by your App Configuration service instance. For more details, see Event Notifications documentation.
When you create a Topic in your Event Notifications service instance, do these steps:
- Select the Source as App Configuration.
- Select the Event type based on your requirement. For more information, see event type.
- Select the Event subtype, which is optional.
- Select the Severity, which is optional.
- Define the Advanced conditions, which is optional.
Using authorizations to grant access between services
Use IBM Cloud® Identity and Access Management (IAM) to create or remove an authorization that grants one service access to another service. Use authorization delegation to automatically create access policies that grant access to dependent services.
Creating an authorization in the console
-
In the IBM Cloud console, click Manage > Access (IAM), and select Authorizations.
-
Click Create.
-
Select a source account.
- If the source service that needs access to the target service is in this account, select This account.
- If the source service that needs access to the target service is in a different account, select Other account. Then, enter the Account ID of the source account.
-
Select a Source service as App Configuration.
-
Specify whether you want the authorization to be for all resources or Resources based on selected attributes. If you selected Resources based on selected attributes, then specify the Add attributes: only source resource group or only source service instance.
-
Select a Target service as Event Notifications.
-
For the target service, specify whether you want the authorization to be for all instances, only to a specific instance in the account, or instances only in a certain resource group.
-
Select a role to assign access to the source service that accesses the target service.
-
Click Authorize.
Creating an authorization by using the CLI
To authorize a source service to access a target service, run the ibmcloud iam authorization-policy-create
command.
For more information about all of the parameters that are available for this command, see ibmcloud iam authorization-policy-create.
Notification payload details
Successful events that are generated by App Configuration contain various fields that help you to identify the source and details of the event.
{
"subject": "flight-booking",
"type": "com.ibm.cloud.apprapp.feature_flag_toggle:disabled",
"severity": "HIGH",
"datacontenttype": "application/json",
"data": {
"environment_id": "staging",
"name": "Flight Booking",
"feature_id": "flight-booking",
"description": "Feature flag to enable flight booking in blue charge application",
"tags": "uat, v1",
"type": "BOOLEAN",
"enabled_value": true,
"disabled_value": false,
"segment_rules": [],
"rollout_percentage": 100,
"enabled": false,
"collections": [
{
"collection_id": "blue-charge",
"name": "Blue charge"
}
],
"created_time": "2024-02-10T20:06:45Z",
"updated_time": "2024-02-12T13:43:12Z",
"href": "http://us-south.apprapp.cloud.ibm.com/apprapp/feature/v1/instances/473de1e9-3ec0-47a4-9e44-a1508b4a09ec/environments/staging/features/flight-booking"
},
"ibmendefaultshort": "Your feature flag was disabled successfully",
"ibmendefaultlong": "The following feature flag was disabled in your App Configuration instance: flight-booking",
"ibmensmstext": "Your feature flag was disabled successfully",
"ibmensubject": "Your feature flag was disabled successfully",
"ibmenhtmlbody": "Hello,<br/><br/>The following feature flag was disabled in your App Configuration instance: flight-booking<br/><br/>You can view and manage your feature flags & properties by accessing <a href=https://cloud.ibm.com/services/apprapp/crn%3Av1%3Abluemix%3Apublic%3Aapprapp%3Aus-south%3Aa%2Fdc420e985bb849d6b8352f71dac26ab8%3A473de1e9-3ec0-47a4-9e44-a1508b4a09ec%3A%3A>App Configuration</a> in the console, or by using the CLI or APIs. For more information, check out the <a href=https://cloud.ibm.com/docs/app-configuration>docs</a>.<br/><br/>",
"source": "IBM Cloud App Configuration",
"ibmensourceid": "crn:v1:bluemix:public:apprapp:us-south:a/dc420e985bb849d6b8352f71dac26ab8:473de1e9-3ec0-47a4-9e44-a1508b4a09ec::",
"id": "e5bf8f16057d4677a0773cce92916d03",
"specversion": "1.0",
"time": "2024-04-25T18:27:51Z"
}
Review following table for more information about event notification properties.
Property | Description |
---|---|
subject |
The subject of the event. It can be the ID of the feature flag being toggled. |
type |
Describes the type of event. See table. |
severity |
The level of severity of the event. See table. |
datacontenttype |
The MIME type of the data content. |
data |
An object containing the metadata about the event. |
ibmendefaultshort |
The default short text of the event. |
ibmendefaultlong |
The default long text of the event. |
ibmensmstext |
The text that used as the body of the SMS if the event gets routed to a destination of type SMS. |
ibmensubject |
The subject text used for emails if the event gets routed to a destination of type SMTP. |
ibmenhtmlbody |
The html body of the event. |
source |
The source name of event. |
ibmensourceid |
The source identifier among multiple source(s) in Event Notifications. |
id |
Event identifier. |
specversion |
The version of CloudEvents specification that Event Notifications supports. |
time |
UTC timestamp of when the event occurred. |