NerdGraph tutorial: Alerts channels

In addition to managing your alert notification channels in the UI, you can use our NerdGraph API.

Importante

This document refers to using Nerdgraph APIs for the new notification platform using destinations and notification messages. Notification messages are also referred to as channels, which are different from legacy notification channels.

Dica

For help getting started with NerdGraph, see Introduction to NerdGraph.

List and filter channels

The channels query allows you to paginate through all of your channels per account. It also allows some filtering functionality.

Here's an example:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels {
          entities {
            id
            name
          }
          error {
            details
          }
        }
      }
    }
  }
}

In order to paginate through your channels, you must request the nextCursor field on your initial query.

With cursor pagination, you continue to make a request through the result set until the nextCursor that is returned from the response comes back empty. This signifies that you reached the end of your results.

Here's an example:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

The code above returns a set of results like this:

{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "channels": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "entities": [
              {
                "id": "01c0cbe7-3d70-47c1-99e0-adf906eed6c2",
                "name": "Channel Name"
              },
              {
                "id": "05db0207-c137-4985-8cb5-f21e7e57b8cc",
                "name": "Another Channel Name"
              }
              // ... more channels here in reality
            ],
            "totalCount": 807
          }
        }
      }
    }
  }
}

So, in your subsequent request, provide the cursor like so, until the cursor is empty:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

The API allows channel queries by name. The name filter returns exact matches and partial matches. It's case insensitive. This will only return the information for the channels that match the name supplied.

In this example, we want to find channels with "DevOps" in the name:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { name: "DevOps" }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

The API lets you query by channel ID:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { id: YOUR_CHANNEL_ID }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

The API lets you query channels by destination ID:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { destinationId: YOUR_DESTINATION_ID }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

The API lets you query by channel type. The following query will return all email channels on the chosen account:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: { type: EMAIL }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}

Create a channel

In order to create a channel, different inputs must be supplied for each channel type. Each channel is connected to a destination. For information on destinations, see the NerdGraph tutorial on destinations.

The best practice is to use the channelSchema endpoint to see which fields must be sent under properties like so:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: CHANNEL_TYPE
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

Jira is a configurable ticketing system, and therefore there's no static way to create this channel.

There are two static fields - project and issuetype.

Fetch the project suggestions, and use one of the values as the constraint for issuetype, as shown here:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSuggestions(
          channelType: JIRA_CLASSIC
          destinationId: YOUR_DESTINATION_ID
          key: FIELD_NAME
          constraints: [{ key: "project", value: YOUR_PROJECT_VALUE }]
        ) {
          entities {
            value
          }
          error
        }
      }
    }
  }
}

The chosen values will be used as constraints to fetch the schema:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: JIRA_CLASSIC
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: [
            { key: "project", value: YOUR_PROJECT_VALUE }
            { key: "issuetype", value: YOUR_ISSUE_TYPE_VALUE }
          ]
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

After you've fetched each field and chosen a value from the suggestions or as free text, you can create a channel:

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: JIRA,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}

ServiceNow is a configurable ticketing system, and therefore there's no static way to create this channel.

The schema must be fetched like shown above, then each field must be filled with free text or by using suggestions:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: SERVICE_NOW
          destinationId: YOUR_DESTINATION_ID
          product: YOUR_PRODUCT
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}

After you've fetched each field and chosen a value from the suggestions or as free text, you can create a channel:

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: SERVICE_NOW,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: SLACK
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "channelId", value: YOUR_SLACK_CHANNEL_ID }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

The payload property is the payload that will be sent in the notification. It uses the handlebars syntax to dynamically insert information from the request.

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: WEBHOOK
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "payload", value: "{\"key\":\"value\"}" }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: EMAIL
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: []
    }
  ) {
    channel {
      id
      name
    }
  }
}

The eventSource must be the full url for an existing event source. The eventContent is the payload that will be sent in the body of the notification, as shown here:

mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: EVENT_BRIDGE,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "eventSource",
        value:  YOUR_AWS_EVENT_SOURCE
      },
      {
        key: "eventContent",
        value:  YOUR_EVENT_CONTENT/var>
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}

PagerDuty has two types of integrations, service level and account level. For more information see the PagerDuty integration docs.

Service level:

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_SERVICE_INTEGRATION
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [{ key: "summary", value: YOUR_PAGE_SUMMARY }]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Account level:

mutation {
  aiNotificationsCreateChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_ACCOUNT_INTEGRATION
      name: "Channel Name"
      destinationId: YOUR_DESTINATION_ID
      product: YOUR_PRODUCT
      properties: [
        { key: "summary", value: YOUR_PAGE_SUMMARY }
        { key: "email", value: EMAIL_OF_PD_USER }
        { key: "service", value: YOUR_PD_SERVICE_ID }
      ]
    }
  ) {
    channel {
      id
      name
    }
  }
}

Update a channel

When you update a channel, note that you don't need to supply all of the attributes on the channel. For example, if you only want to update the name, that's the only attribute you need to update, as shown here:

mutation {
  aiNotificationsUpdateChannel(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
    channel: { name: "Updated channel Name" }
  ) {
    channel {
      id
      name
    }
  }
}

Testing a channel

You can test channels via the NerdGraph API. This can be done before or after creating the channel.

mutation {
  aiNotificationsTestChannel(
    accountId: YOUR_ACCOUNT_ID
    channel: {
      type: PAGERDUTY_SERVICE_INTEGRATION
      name: "Channel Name"
      properties: [{ key: "summary", value: YOUR_PAGE_SUMMARY }]
    }
  ) {
    error {
      details
    }
    details
    result
  }
}

mutation {
  aiNotificationsTestChannelById(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
  ) {
    error {
      details
    }
    details
    result
  }
}

Delete a channel

You can delete channels via the NerdGraph API.

mutation {
  aiNotificationsDeleteChannel(
    accountId: YOUR_ACCOUNT_ID
    channelId: YOUR_CHANNEL_ID
  ) {
    ids
    error {
      details
    }
  }
}

Importante

Dica

List and filter channels

Listing all channels for an account

Paginating through channels with cursor pagination

Find all channels by name

Find channel by id

Find all channels by destination id

Find all channels by type

Create a channel

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Webhook

Email

AWS EventBridge

PagerDuty

Update a channel

Testing a channel

Delete a channel

NerdGraph tutorial: Alerts channels

Importante

Dica

List and filter channels .css-21sua1{background:none;border:none;width:0;padding:0;}

Paginating through channels with cursor pagination

Find all channels by name

Find channel by id

Find all channels by destination id

Find all channels by type

Create a channel

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Webhook

Email

AWS EventBridge

PagerDuty

Update a channel

Testing a channel

Delete a channel

List and filter channels