Create Alert Monitors Programmatically

An alert monitor allows you to be notified when something happens in a particular instance's flow. Most commonly, alert monitors are used to notify you when an execution fails.

Let's look at how to create alert monitors programmatically for all instances.

An example script that creates alert monitors for all flows of all instances is available in the examples repository.

List instances programmatically

First, we need to get a list of all of our customers instances, along with their flows, the customer the instance is deployed to and any monitors that currently exist. A full query to the Primsatic GraphQL API might look like this:

query myGetInstancesQuery($cursor: String) {
  instances(
    isSystem: false
    enabled: true
    sortBy: { direction: ASC, field: CREATED_AT }
    after: $cursor
  ) {
    nodes {
      id
      name
      flowConfigs {
        nodes {
          id
          flow {
            name
          }
          monitors {
            nodes {
              id
              name
              groups {
                nodes {
                  id
                }
              }
            }
          }
        }
      }
      customer {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Note three important details about this query:

• isSystem: false will ensure that we exclude test instances that are used in the integration designer.
• enabled: true will ensure that we only get instances that are currently enabled.
• A combination of sortBy: { direction: ASC, field: CREATED_AT }, after: $cursor, and pageInfo at the end of the query will allow us to paginate through the results.

If you'd like to see an example of how to paginate through results, check out the example script which implements the query above.

Fetch info about alert triggers

Next, we need to fetch information about the alert monitor we want to create. Alert monitors can be triggered by a number of events, including when an execution fails, when an execution succeeds, or when an execution takes longer than a certain amount of time.

You can fetch a list of all available alert triggers with the following query:

{
  alertTriggers {
    nodes {
      id
      name
    }
  }
}

The id returned by this query is what you'll use to create the alert monitor. An example of this query is available in the example script.

Fetch info about a user who should be notified

Assuming you want to notify a user when an alert is triggered, you'll need to fetch information about that user. That user's email address must be registered in your Prismatic organization in order to send emails to the user.

You can fetch a user by email address with a query like this:

query myGetUsersByEmail($email: String!) {
  users(email: $email) {
    nodes {
      id
      name
      email
    }
  }
}

Note that this query may return zero or one users - you'll need to check the length of the nodes array to determine if a user was found, like the example script does here. The user's id is important here, as it's what you'll use to create the alert monitor.

Create the alert monitor

Finally, we can loop over all instances and their flows and create alert monitors. For each flow of an instance, we'll check if an alert monitor already exists for that flow. If not, we can create one with the createAlertMonitor mutation:

mutation myCreateAlertMonitor(
  $name: String!
  $instanceId: ID!
  $flowConfigId: ID!
  $triggerId: ID!
  $userId: ID!
) {
  createAlertMonitor(
    input: {
      name: $name
      instance: $instanceId
      flowConfig: $flowConfigId
      triggers: [$triggerId]
      users: [$userId]
    }
  ) {
    alertMonitor {
      id
    }
    errors {
      field
      messages
    }
  }
}

This mutation takes a number of variables:

• name is the name of the alert monitor. To ensure your script is idempotent (doesn't create multiple monitors that all do the same thing), you can follow a specific naming scheme like [Generated] Alert on Error - FLOW NAME.
• instanceId is the ID of the instance you want to create the alert monitor for. We got that when we listed instances programmatically.
• flowConfigId is the ID of the flow you want to create the alert monitor for. We also got that when we listed instances programmatically.
• triggerId is the ID of the alert trigger you want to use. We got that when we fetched info about alert triggers.
• userId is the ID of the user you want to notify. We got that when we fetched info about a user who should be notified.

Catching errors that may crop up when creating the alert monitor is important - you can look for errors in the errors field of the response. See the end of the example script here.

Delete alert monitors

If you want to delete the alert monitors you created, you can look for alert monitors with a specific name with the alertMonitors query (example) and then issue deleteAlertMonitor mutations (example) on each one.

This is handy if you'd like to clean up and "reset" all alert monitors for all deployed instances.

Next steps

The script in our examples repo creates (or deletes) alert monitors for all instances. The alert monitor that it creates is triggered when an execution fails, and notifies a single user.

If you'd like to notify a webhook or a group of users instead of a single user, you can use the webhooks or groups fields of the createAlertMonitor mutation (docs).