Creating Alert Monitors Programmatically

Programmatically creating alert monitors

Alert monitors enable automated notifications when specific events occur within an instance's flow execution. Most commonly, alert monitors are used to notify you when an execution fails.

This guide demonstrates how to programmatically create alert monitors across 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, retrieve all customer instances, including their flows, associated customers, and existing monitors. The following GraphQL query provides this information:

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 excludes test instances used in the integration designer
• enabled: true filters for currently active instances
• The combination of sortBy { direction: ASC, field: CREATED_AT }, after: $cursor, and pageInfo enables pagination through 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 alert trigger information

Next, retrieve information about the desired alert trigger. Alert monitors can be triggered by several events, such as execution failures, successful executions, or execution duration thresholds.

Query available alert triggers using:

{
  alertTriggers {
    nodes {
      id
      name
    }
  }
}

The returned id is required for creating the alert monitor. An example of this query is available in the example script.

Fetch notification recipient information

To configure user notifications, retrieve the recipient's information. The user must be registered in your Prismatic organization to receive email notifications.

Query a user by email address:

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 required for alert monitor creation.

Create the alert monitor

Finally, iterate through instances and their flows to create alert monitors. For each flow, check for existing monitors before creating a new one using 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
    }
  }
}

Required mutation parameters:

• name: Alert monitor identifier. Use a consistent naming pattern (e.g., [Generated] Alert on Error - FLOW NAME) to ensure idempotency
• instanceId: Target instance ID from the instance listing
• flowConfigId: Target flow ID from the instance listing
• triggerId: Alert trigger ID from the trigger listing
• userId: Notification recipient ID from the user query

Handle potential errors by checking the errors field in the response. See the example implementation for error handling.