Skip to content

Latest commit

 

History

History
161 lines (115 loc) · 10.3 KB

event-notifications-events.md

File metadata and controls

161 lines (115 loc) · 10.3 KB
Raw
copyright lastupdated keywords subcollection
years
2023, 2024
2024-08-02
project events, needs attention, project attention, attention events
secure-enterprise

{{site.data.keyword.attribute-definition-list}}

Enabling event notifications for projects

{: #event-notifications-events}

As an administrator of projects, you might want to send notifications of events in projects to other users, or human destinations, by using email, SMS, or other supported delivery channels. You might want to send these notifications of events to other applications to build logic by using event-driven programming by using webhooks, for example. This is made possible by the integration between projects and {{site.data.keyword.en_full}}. {: shortdesc}

To send information to {{site.data.keyword.en_short}}, you must connect your projects instance to {{site.data.keyword.en_short}}. For more information about working with {{site.data.keyword.en_short}}, see Getting started with {{site.data.keyword.en_short}}.

How events are collected and sent by projects

{: #event-notifications-how}

When an event of interest takes place in your project instance, projects communicate with a connected {{site.data.keyword.en_short}} instance to forward a notification to a supported destination. Events are generated based on actions that users take within the project. For example, if the validation of a configuration is successful, an event is generated to notify users of this action.

Events for projects

{: #event-notifications-list}

The following table lists the projects events.

Event type Description
check.pipeline.failed Changes failed validation. An event is generated when a validation fails.
config.install-job.failed Changes failed to deploy. An event is generated when an architecture deployment fails.
config.uninstall-job.failed Destroy resources failed. An event is generated when the action to destroy configuration resources fails.
check.pipeline.ready Changes require approval. An event is generated when the latest changes require approval.
config.version.available A version update is available. An event is generated when a new version of a deployable architecture is available.
config.defn.updated Changes are ready to deploy. An event is generated when a configuration is updated in the project.
config.install-job.succeeded Deployment complete. An event is generated when a configuration is successfully deployed.
config.uninstall-job.succeeded Destroy resources complete. An event is generated when deployed resources are successfully destroyed.
{: caption="Table 1. Actions that generate event notifications in projects" caption-side="bottom"}

Enabling notifications

{: #event-notifications-enable}

Events that are generated by an instance of the {{site.data.keyword.cloud_notm}} Projects service can be forwarded to an {{site.data.keyword.en_short}} service instance that is available in the same account.

Connecting to {{site.data.keyword.en_short}} in the console

{: #event-notifications-enable-ui} {: ui}

Before you can enable notifications for projects, be sure that you have an {{site.data.keyword.en_short}} service instance{: external} that is in the same account as your projects instance. Then, you can connect to the {{site.data.keyword.en_short}} service from Manage > Notifications in your project.

  1. In the console, click the Navigation Menu icon Navigation Menu icon > Projects.

  2. Select the project that you'd like to connect to {{site.data.keyword.en_short}}.

  3. Click Manage > Notifications.

  4. In the Connected instance section, click Connect.

  5. Add a name to the connection and optionally provide a description.

  6. Select the resource group and {{site.data.keyword.en_short}} service instance that you want to connect.

    If an IAM authorization between projects and {{site.data.keyword.en_short}} doesn't exist in your account, a dialog is displayed. Follow the prompts to grant access between the services.

    1. To grant access between projects and {{site.data.keyword.en_short}}, click Authorize.
    2. Select {{site.data.keyword.en_short}} as the target service.
    3. From the list of instances, select the {{site.data.keyword.en_short}} service instance that you want to authorize.
    4. Select the Event Source Manager role.
    5. Click Review.
    6. Click Assign.

  7. Click Save.

Connecting to {{site.data.keyword.en_short}} with the API

{: #event-notifications-enable-api} {: api}

Before you can enable notifications for projects, be sure that you have an {{site.data.keyword.en_short}} service instance{: external} that is in the same account as your projects instance. Then, you can connect to {{site.data.keyword.en_short}} programmatically by calling the projects API.

The following example shows a query that you can use to register your projects source details with {{site.data.keyword.en_short}}. When you call the API, replace the ID variables and IAM token with the values that are specific to your projects instance.

You can find the event_notifications_instance_crn value in the console by going to the Resource list page and clicking the {{site.data.keyword.en_short}} instance row. {: tip}

[enter API example here]

A successful response returns the CRN value of your connected {{site.data.keyword.en_short}} service instance. For more information about the required and optional request parameters, see the API docs.

Delivering notifications to select destinations

{: #event-notifications-destinations}

After you enable notifications for projects, create topics and subscriptions in {{site.data.keyword.en_short}} so that alerts can be forwarded and delivered to your selected destinations.

For a complete list of supported destinations, see the {{site.data.keyword.en_short}} documentation. {: tip}

Email notifications

{: #event-notifications-email}

You can use the {{site.data.keyword.cloud_notm}} email service as a delivery channel for projects event notifications. Create an {{site.data.keyword.en_short}} subscription between an existing topic and the {{site.data.keyword.cloud_notm}} email service to forward your alerts to various recipients by email.

An email from {{site.data.keyword.cloud_notm}} that contains information about a projects event resembles the following example:

Subject: Validation successful for terrafrom-1234567890-a12a triggered by IBMid-12345ABCD1
Body: Validation is complete. Review and approve the validation results to deploy the changes.
    Project Service event details:
    Type: check.pipeline.succeeded
    Target: Config terrafrom-1234567890-a12a for Project example-email-notification-project
    Source: pipelinerun-123ab1ab-1a1a-1a11-1a12-ac1a1a12a12a
    Triggered by: IBMid-12345ABCD1
    Action URL: https://cloud.ibm.com/devops/pipelines/example
    Date: Fri April 10 2023 09:15:08 GMT-0500 (Eastern Standard Time)

{: screen}

To receive detailed information about an event notification in your email, select the Add notification payload option when you create an {{site.data.keyword.en_short}} subscription. Your email displays the notification payload details that are associated with the event. {: tip}

Webhooks

{: #event-notifications-webhook}

You can configure a webhook destination so that an incoming notification can be consumed programmatically by an app or service. For more information about setting up webhooks, check out the {{site.data.keyword.en_short}} documentation.

Notification payload details

{: #event-notifications-payload}

Successful events that are generated by projects contain various fields that help you to identify the source and details of an event.

Event notifications from projects contain only metadata properties, such as names or identifiers of resources. Sensitive data, for example API keys or passwords, are not included in generated events. {: note}

The properties that are sent to {{site.data.keyword.en_short}} vary depending on the event type. For example, if an check.pipeline.succeeded event takes place, projects sends a notification payload to {{site.data.keyword.en_short}} that is similar to the following example.

{
      "_id": "a7110265-88e5-4fda-8686-ae4d5bb3f86a",
      "event": "check.pipeline.succeeded",
      "target": "639d4201-8cf9-4e29-b076-5129b6a3f839:1:true",
      "source": "d1542c4b-533c-4276-9272-00ce5134a7a3",
      "triggered_by": "IBMid-test-notification",
      "action_url": "https://cloud.ibm.com/schematics/workspaces/us-south.workspace.projects-service.e7de98e8/jobs?region=us",
      "severity": "INFO",
      "timestamp": "2023-04-10T16:00:43.195Z"
}

{: screen}

Review following table for more information about event notification properties.

Property Description
event_sub_type The subtype that corresponds with the type of event that triggered a notification.
event_type The type of event that triggered a notification.
source_instance_api_url The dedicated endpoint URL that is assigned to your {{site.data.keyword.cloud_notm}} Projects service instance.
source_instance_crn The Cloud Resource Name (CRN) that uniquely identifies your {{site.data.keyword.cloud_notm}} Projects service instance.
source_instance_dashboard_url The URL to your {{site.data.keyword.cloud_notm}} Projects service dashboard in the console.
source_service The display name of the service that sent the event notification.
{: caption="Table 2. Properties in an event notification payload" caption-side="bottom"}