• Products
  • Get started
  • Documentation
  • Resources

The integration framework

Overview

An Opsgenie integration is a connection between your Opsgenie account and other apps in your IT environment. When they’re connected, you get alerts from your IT apps, all centralized in Opsgenie, and you can also access the alert bucket that’s created. You can create custom automation rules for each integration to update and edit data or take custom actions by triggering the connected apps.

What’s new in the experience

The latest version of Opsgenie introduces a new integration framework to help you install and configure integrations with much ease and provide you with more flexible capabilities. Check out the following table to see what's changed from the old integration experience to the new one.

Old experience

New experience

Setting up the connection

Both initial connection setup and additional configuration steps had to be completed at the beginning itself.

The initial setup and rule settings are split into two separate steps. You can focus on and finish the main step first which is setting up the connection before you move on to configuring the rules.

Guidance for configuring rules

The integation rules didn't come with enough help or guidance and they were spread out in too many places.

After setting up the connection, you can create both incoming and outgoing rules simultaneously during the next step. These rules ensure the connection functions properly and come with contextual guidance. Both sections also have "Learn more" links for additional help with setting up that specific integration.

Configuring and editing rules

The outgoing rules were grouped with instructions, authentication settings, and connection setup, while incoming rules were tucked away under the "Advanced" tab.

The advanced incoming rules are available right in the main setup area along with outgoing rules, all in a simplified, unified design. The rule editing modal is improved to support additional functionality.

Authentication settings

The authentication settings for the outgoing part of the integrations were combined with outgoing settings, rules, instructions, and other settings on the same page.

The integration and authentication settings are together available in the Integration settings section. A warning message shows to remind you that authentication settings are required for the outgoing rules to work.

You can set up the rules on the specific configuration page, while one-time setups like authentication settings are under the Integration settings section, since you usually only need to do these once. The configuration page is purely for setting up the rules.

List of configured integrations

The list of integrations already set up didn't offer enough information. For example, the statuses of notifications wasn’t clear and the responder team column repeated the team information.

The new version has quite a few improvements when it comes to showing the status of integrations. Instead of enable/disable, it now shows on/off states (more inclusive language), and you can filter the list of integrations in more ways than earlier. The status of the notifications is easier to see, and the responder team column now only appears for the global integrations.

Add integration

  1. Go to Settings > Integrations.

  2. Select Add integration.

  3. Run a search and select an application of interest.

  4. On the next screen, enter a name for the integration.

  5. Optional: Select a team in Assignee team if you want a specific team to receive alerts from the integration.

  6. Select Continue.
    The integration is saved at this point.

  7. On the next page, expand the Steps to configure the integration section.

  8. Follow the instructions to configure the integration for either end (if it’s an incoming or outgoing integration) or for both ends (if it’s a bidirectional integration) as applicable.

  9. Define rules for creating alerts and processing them and define actions to take actions against alerts.

  10. Select Turn on integration.
    The rules you create for the integration will work only if you turn on the integration.

Define rules for the integration

Opsgenie offers two rule sets:

  • The incoming part of the integration: To define rules for creating and processing alerts

  • The outgoing part of the integration: To define rules for taking actions in the integrated applications

Incoming | Rules for creating and processing alerts

These rules define how Opsgenie behaves when it receives data from an integrated application. In other words, it’s a way to automate the behavior of new or existing alerts in Opsgenie when they are triggered by an event that occurs in the integrated application. You can acknowledge or update an alert, add a note to an alert, close an alert, or create alerts.

When you first create the integration, some rules become available by default (Create alert, Close alert, Acknowledge alert, and Add note to alert). Unless you turn them off, they start working the moment you turn on the integration.

Incoming rule types

Create alert: Select this option to create an alert each time your predefined action occurs in the integrated application. For example, you can have an alert created for an incident raised in the application or when the status of an incident changes. For each action, you can customize the alert Opsgenie creates. Learn more about action filters.

Close alert: Closes the alert each time a predefined action occurs in the integrated application.

Acknowledge alert: Acknowledges the alert each time a predefined action occurs in the integrated application.

Add note to alert: Adds note to the alert each time a predefined action occurs in the integrated application.

Ignore: Select this option for the actions that you don’t want to receive alerts.

You can set the integration based on these rules and modify the alert fields depending on your requirements. Alert properties vary according to the capability of each rule type. Learn more about dynamic fields.

You can edit the default rules or add more rules in the incoming section. Once you set your rules and turn on the integration, Opsgenie applies the rule from top to bottom, in its set order - if your first rule is for “Ignore” action and second is “Create alert”, and, if the data you receive from the integrated application matches the conditions of both rules, Opsgenie stops at the first match – the “Ignore” action. It won’t create an alert.

Outgoing | Rules for taking actions in the integrated applications

Rules in the outgoing section define how Opsgeniealerts affect your integrated application. You can create two types of rules in the outgoing section:

Send alert updates back to the integrated application

Select this rule type to update the data in the integrated application. The following is what the flow looks like:

  1. A rule in the incoming section creates an alert in Opsgenie for some event occurring in the integration application

  2. Something about the alert changes in Opsgenie

  3. Opsgenie sends this update back to the integrated application and updates an associated entity.

In this section, the alert actions and their corresponding actions to be taken in the integrated application are presented in a natural language. Some actions such as “a tag is added to alert” might require user input to work properly. If you leave the input field empty, the rule applies to all values. If you want to limit the input, enter the values manually, then press Enter. This is similar to how you add tags to an alert.

Define actions for alerts manually created or by other integrations

Select this rule type to define actions for alerts that are either manually created or by other integrations you have set up in Opsgenie. However, with this option, you’re taking actions in an integrated application against alerts you received from your other integrated tools.

Create a filter to select which alerts you wish to apply this rule to. You can turn on and turn off each of these rules at any time, even when the integration is turned on. Similar to the rules in the incoming section, Opsgenie applies the rule from top to bottom and stops once it matches with a rule. So, how you order the rules matter. Very much like in the incoming section, you can order these rules by dragging and dropping them.

When you’re done with setting all the rules, turn on the integration from the top of the page.

Still need help?

The Atlassian Community is here for you.