NerdGraph tutorial: Alerts destinations

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

Tip

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

List and filter destinations

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

Here's an example:

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

In order to paginate through your destinations, 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 {
        destinations(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

The code above returns a set of results like this:

{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "destinations": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "entities": [
              {
                "id": "01c0cbe7-3d70-47c1-99e0-adf906eed6c2",
                "name": "Destination Name"
              },
              {
                "id": "05db0207-c137-4985-8cb5-f21e7e57b8cc",
                "name": "Another Destination Name"
              }
              // ... more destinations 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 {
        destinations(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}

The API allows destination queries by name. The name filter returns exact matches and partial matches. It is case insensitive. This will only return the information for the destinations that match the name supplied.

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

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

The API lets you query by destination ID:

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

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

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

Create a destination

In order to create a destination, different inputs must be supplied for each destination type. An optional two_way_integration property is available for integrations that allow two-way integration.

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: JIRA
      name: "Destination Name"
      auth: {
        type: BASIC
        basic: { user: YOUR_EMAIL, password: YOUR_PASSWORD }
      }
      properties: [
        { key: "url", value: "https://YOUR_INSTANCE.atlassian.net" }
        { key: "two_way_integration", value: "true" }
      ]
    }
  ) {
    destination {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: SERVICE_NOW
      name: "Destination Name"
      auth: {
        type: BASIC
        basic: { user: YOUR_EMAIL, password: YOUR_PASSWORD }
      }
      properties: [
        { key: "url", value: "https://YOUR_INSTANCE.service-now.com" }
        { key: "two_way_integration", value: "true" }
      ]
    }
  ) {
    destination {
      id
      name
    }
  }
}

Note

The Microsoft Teams integration is now available in both US and EU regions.

Before creating a New Relic destination that connects to Microsoft Teams, you must install the New Relic for Microsoft Teams app in your Microsoft Teams workspace. After installation, you'll receive a security code that is required for this mutation.

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: MICROSOFT_TEAMS
      name: "Destination Name"
      properties: [{ key: "securityCode", value: YOUR_SECURITY_CODE }]
    }
  ) {
    destination {
      id
      name
    }
  }
}

Important

After creating the New Relic destination, obtain the destinationId from the response. This ID is required to configure notification channels. See the Microsoft Teams channel configuration section for the complete workflow.

In this example, auth is optional, depending on the service being integrated.

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: WEBHOOK
      name: "Destination Name"
      auth: {
        type: BASIC
        basic: { user: YOUR_EMAIL, password: YOUR_PASSWORD }
      }
      properties: [
        { key: "url", value: YOUR_WEBHOOK }
        { key: "two_way_integration", value: "true" }
      ]
    }
  ) {
    destination {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: EMAIL
      name: "Destination Name"
      properties: [{ key: "email", value: YOUR_EMAIL }]
    }
  ) {
    destination {
      id
      name
    }
  }
}

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: EVENT_BRIDGE
      name: "Destination Name"
      auth: {
        type: BASIC
        basic: { user: YOUR_IAM_USER, password: YOUR_PASSWORD }
      }
      properties: [
        { key: "AWSAccountId", value: YOUR_AWS_ACCOUNT_ID }
        { key: "AWSRegion", value: YOUR_AWS_REGION }
      ]
    }
  ) {
    destination {
      id
      name
    }
  }
}

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

Service level:

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: PAGERDUTY_SERVICE_INTEGRATION
      name: "Destination Name"
      auth: {
        type: TOKEN
        basic: { token: YOUR_INTEGRATION_TOKEN, prefix: "Token token=" }
      }
      properties: []
    }
  ) {
    destination {
      id
      name
    }
  }
}

Account level:

mutation {
  aiNotificationsCreateDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: PAGERDUTY_ACCOUNT_INTEGRATION
      name: "Destination Name"
      auth: {
        type: TOKEN
        basic: { token: YOUR_API_KEY, prefix: "Token token=" }
      }
      properties: [{ key: "two_way_integration", value: "true" }]
    }
  ) {
    destination {
      id
      name
    }
  }
}

Update a destination

When you update a destination, note that you don't need to supply all of the attributes on the destination. For example, you only need to supply the name if you only intend to update the name:

mutation {
  aiNotificationsUpdateDestination(
    accountId: YOUR_ACCOUNT_ID
    destinationId: YOUR_destination_ID
    destination: { name: "Updated destination Name" }
  ) {
    destination {
      id
      name
    }
  }
}

Testing a destination

You can test destinations via the NerdGraph API. This can be done before or after creating the destination.

mutation {
  aiNotificationsTestDestination(
    accountId: YOUR_ACCOUNT_ID
    destination: {
      type: EMAIL
      name: "Destination Name"
      properties: [{ key: "email", value: YOUR_EMAIL }]
    }
  ) {
    error {
      details
    }
    details
    result
  }
}

mutation {
  aiNotificationsTestDestinationById(
    accountId: YOUR_ACCOUNT_ID
    destinationId: YOUR_DESTINATION_ID
  ) {
    error {
      details
    }
    details
    result
  }
}

Delete a destination

You can delete destinations via the NerdGraph API.

mutation {
  aiNotificationsDeleteDestination(
    accountId: YOUR_ACCOUNT_ID
    destinationId: YOUR_DESTINATION_ID
  ) {
    ids
    error {
      details
    }
  }
}

Important

If you receive a failure message stating Entity type channel is in use, you will need to identify the channels used by the destination and delete them before proceeding. To accomplish this, first find all the channels associated with the destination, then delete each channel individually.

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

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

NerdGraph tutorial: Alerts destinations

Tip

List and filter destinations

Listing all destinations for an account

Paginating through destinations with cursor pagination

Find all destinations by name

Find destination by ID

Find all destinations by type

Create a destination

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Microsoft Teams

Note

Important

Webhook

Email

AWS EventBridge

PagerDuty

Update a destination

Testing a destination

Delete a destination

Important

NerdGraph tutorial: Alerts destinations

Tip

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

Paginating through destinations with cursor pagination

Find all destinations by name

Find destination by ID

Find all destinations by type

Create a destination

Atlassian Jira

ServiceNow (Incident-Management)

Slack

Microsoft Teams

Webhook

Email

AWS EventBridge

PagerDuty

Update a destination

Testing a destination

Delete a destination

Important

List and filter destinations