NerdGraph tutorial: Create and manage alert workflows

For New Relic alerts, you can create and manage workflows using our NerdGraph API.

List and filter workflows

The workflows query allows you to paginate through all of your workflows per account. It also allows some filtering functionality on the account workflows. Here are some example use cases:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows(filters: {}) {
          entities {
            id
            name
            workflowEnabled
            destinationConfigurations {
              channelId
              name
              type
              notificationTriggers
            }
            enrichments {
              configurations {
                ... on AiWorkflowsNrqlConfiguration {
                  query
                }
              }
              id
              name
            }
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

In order to paginate through your workflows, 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's returned from the response comes back empty. This indicates you've reached the end of your results.

First call:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows(filters: {}) {
          entities {
            id
            name
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

Response:

{
  "data": {
    "actor": {
      "account": {
        "aiWorkflows": {
          "workflows": {
            "entities": [
              {
                "id": <WORKFLOW ID>, 
                "name": <WORKFLOW NAME>
              },
              {
                "id": <WORKFLOW ID>, 
                "name": <WORKFLOW NAME>
              },
              // ... more workflows would be here 
            ]
          }
          "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM="
          "totalCount": 157
        }
      }
    }
  }
}

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows(filters: { id: WORKFLOW_ID }) {
          entities {
            id
            name
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows(filters: { name: WORKFLOW_NAME }) {
          entities {
            id
            name
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

Finds all the workflows that have at least a single destination configuration of a certain type.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiWorkflows {
        workflows(filters: { destinationType: DESTINATION_TYPE }) {
          entities {
            id
            name
            destinationConfigurations {
              type
            }
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}

Create a workflow

In order to create a workflow you should first create destinations and channels.

Important

A channel ID is unique and so can't be used in multiple workflows or used multiple times in the same workflow.

The issuesFilter attribute decides which issue events will be caught by the workflow.

By keeping the predicates attribute's value as an empty list, the workflow will catch all the possible issue events. When you select an attribute value you can then filter issue events.

For example, we can choose an attribute that only filters issues that are relevant to a specific team:

mutation {
  aiWorkflowsCreateWorkflow(
    accountId: YOUR_ACCOUNT_ID
    createWorkflowData: {
      destinationsEnabled: true
      workflowEnabled: true
      name: "API Demo Workflow"
      issuesFilter: {
        name: "team specific issues"
        predicates: [
          {
            attribute: "accumulations.tag.team"
            operator: EXACTLY_MATCHES
            values: ["security"]
          }
        ]
        type: FILTER
      }
      destinationConfigurations: {
        channelId: "CHANNEL_ID"
        notificationTriggers: [ACTIVATED, ACKNOWLEDGED, CLOSED]
      }
      enrichmentsEnabled: true
      enrichments: { nrql: [] }
      mutingRulesHandling: DONT_NOTIFY_FULLY_MUTED_ISSUES
    }
  ) {
    workflow {
      id
      name
      destinationConfigurations {
        channelId
        name
        type
        notificationTriggers
      }
      enrichmentsEnabled
      destinationsEnabled
      issuesFilter {
        accountId
        id
        name
        predicates {
          attribute
          operator
          values
        }
        type
      }
      lastRun
      workflowEnabled
      mutingRulesHandling
    }
    errors {
      description
      type
    }
  }
}

Update a workflow

When you update a workflow, note the only mandatory attributes you need to supply are the accountId under aiWorkflowsUpdateWorkflow and the id of the workflow under updateWorkflowData. The rest are optional. For example, you only need to supply the name if you only intend to update the name.

To get the workflow ID, go to the workflow table and click the icon at the end of the row. Then, choose Copy workflow id to clipboard.

Here's an example of updating a workflow's name and two channels:

mutation {
  aiWorkflowsUpdateWorkflow(
    accountId: YOUR_ACCOUNT_ID
    updateWorkflowData: {
      name: "UPDATED_WORKFLOW_NAME"
      id: WORKFLOW_ID
      destinationConfigurations: [
        {
          channelId: "12345abc-6de7-8f90-g123-4h56i78j9klm"
          notificationTriggers: [ACTIVATED]
        }
        {
          channelId: "zy0987xw-v65u-432t-10s9-r876qpo543n2"
          notificationTriggers: [ACTIVATED]
        }
      ]
    }
  ) {
    workflow {
      id
      name
      destinationConfigurations {
        channelId
        name
        type
        notificationTriggers
      }
      enrichmentsEnabled
      destinationsEnabled
      issuesFilter {
        accountId
        id
        name
        predicates {
          attribute
          operator
          values
        }
        type
      }
      lastRun
      workflowEnabled
      mutingRulesHandling
    }
    errors {
      description
      type
    }
  }
}

Delete a workflow

Here's an example of deleting a workflow:

mutation {
  aiWorkflowsDeleteWorkflow(id: WORKFLOW_ID, accountId: YOUR_ACCOUNT_ID) {
    id
    errors {
      description
      type
    }
  }
}

Test a workflow

The test searches for previous issues that match your inputs and creates a fake notification based on that. If no previous issue matching your inputs has been found it will return an error.

For example:

mutation {
  aiWorkflowsTestWorkflow(
    accountId: YOUR_ACCOUNT_ID
    testWorkflowData: {
      destinationConfigurations: { channelId: YOUR_CHANNEL_ID, type: SLACK }
      issuesFilter: { predicates: [], type: YOUR_FILTER }
    }
  ) {
    status
    notificationResponses {
      status
      evidence
      channelId
    }
    errors {
      description
      type
    }
  }
}

NerdGraph tutorial: Create and manage alert workflows

List and filter workflows

Listing all workflows for an account

Find workflow by ID

Find workflow by name

Find workflows by destination type

Create a workflow

Important

Create a workflow to catch all issues

Update a workflow

Delete a workflow

Test a workflow

NerdGraph tutorial: Create and manage alert workflows

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

Paginating through policies with cursor pagination:

Find workflow by ID

Find workflow by name

Find workflows by destination type

Create a workflow

Important

Create a workflow to catch all issues

Update a workflow

Delete a workflow

Test a workflow

List and filter workflows