NerdGraph tutorial: applied intelligence destinations

In addition to managing your applied intelligence 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
    }
  }
}

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
    }
  }
}

NerdGraph tutorial: applied intelligence 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

Webhook

Email

AWS EventBridge

PagerDuty

Update a destination

Testing a destination

Delete a destination