# Opsgenie {% hint style="danger" %} Atlassian is deprecating the Opsgenie product and encouraging their customers to migrate to Jira Service Management. Read more about moving from Opsgenie to Jira Service Management on [Atlassian's web site](https://support.atlassian.com/jira-service-management-cloud/docs/start-shifting-from-opsgenie-to-jira-service-management/). Cortex is actively working on developing an integration with Jira Service Management. {% endhint %} [Opsgenie](https://www.atlassian.com/software/opsgenie) is an alert and on-call management platform from Atlassian. Integrating Opsgenie with Cortex allows you to: * Pull in on-call rotation data and escalation policies * The on-call user or team will appear in the **Current On-call** block on an entity's details page. * You can also view on-call information on an entity page in its side panel under **Integrations > On-call**. * View alerts from Opsgenie in an entity's event timeline * Create [Scorecards](#scorecards-and-cql) that track progress and drive alignment on projects involving your on-call schedules and alerts ## How to configure Opsgenie with Cortex ### Prerequisite Before getting started, create an [Opsgenie API key](https://support.atlassian.com/opsgenie/docs/api-key-management/) with the following permissions: * `Read` * `Configuration Access` ### Configure the integration in Cortex 1. In Cortex, navigate to the [Opsgenie settings page](https://app.getcortexapp.com/admin/integrations/opsgenie): * Click **Integrations** from the main nav. Search for and select **Opsgenie**. 2. Configure the Opsgenie integration form: * **Subdomain**: Enter the subdomain assigned to your Opsgenie instance. * **API key**: Enter your Opsgenie API key. * **Use European service region**: Optionally, toggle this setting on to enable the EU region of Opsgenie. 3. Click **Save**. ## How to connect Cortex entities to Opsgenie ### Discovery By default, Cortex will use the [Cortex tag](https://docs.cortex.io/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" value for the `backend` and `service` tags on your alerts. For example, if your alert in Opsgenie has the tag `backend:my-entity`, the alert will be automatically associated with the entity in Cortex with a unique identifier of `my-entity`. If your Opsgenie tags don’t cleanly match the Cortex tag, or you use different identifying tags, you can override this in the Cortex entity descriptor. ### Entity descriptor ```yaml x-cortex-alerts: - type: opsgenie tag: different-tag value: my-entity-override-tag ``` | Field | Description | Required | | ------- | ------------------------------------------------- | :------: | | `type` | Type of alert (in this case, `opsgenie`) | **✓** | | `tag` | Type of tag in Opsgenie (e.g. `backend`) | **✓** | | `value` | Alert in Opsgenie (e.g. `my-entity-override-tag`) | **✓** | For example, for the tag `different-tag:my-entity-override-tag`, the entity descriptor would have `different-tag` in the **tag** field and `my-entity-override-tag` in the **value** field. You can add a list of tags to use for lookup. Cortex will use an `OR` operator when querying Opsgenie (e.g. `backend:my-entity OR service:another-value`). The `value` field also supports wildcards (e.g. `value: my-entity*`). **Adding a schedule** You can define the following block in an entity descriptor to add an Opsgenie schedule. Cortex supports adding a schedule by ID or UUID. You can add one schedule per entity. The UUID for the schedule can be found in URL when viewing schedule details by clicking on the schedule name under who is on-call. ```yaml x-cortex-oncall: opsgenie: type: SCHEDULE id: Cortex-Engineering ``` | Field | Description | Required | | ------ | --------------------------------------------------------- | :------: | | `type` | Opsgenie component being added (in this case, `SCHEDULE`) | **✓** | | `id` | Schedule ID or UUID | **✓** | #### Ownership ```yaml x-cortex-owners: - type: group name: My Opsgenie Team provider: OPSGENIE description: This is a description for this owner ``` | Field | Description | Required | | ------------- | --------------------------------------------------------- | :------: | | `type` | Ownership type (in this case, `group`) | **✓** | | `name` | Name of the team defined in Opsgenie (\*\*case-sensitive) | **✓** | | `provider` | Identity provider (in this case, `OPSGENIE`) | **✓** | | `description` | Description for the team, to be displayed in Cortex | | #### Identity mappings Cortex maps email addresses in your Opsgenie instance to email addresses that belong to team members in Cortex. When identity mapping is set up, users will be able to see their personal on-call status from the developer homepage. ## Using the Opsgenie integration After setting up the integration, Opsgenie information will appear in several places across Cortex. ### Viewing on-call information for an entity On an [entity details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details), current on-call information from Opsgenie will display in the **On-call** block. Escalation policy, the level associated with the policy, and other on-call information will also appear in the entity's sidebar in the "On-call & incidents" page. Owners assigned to each level will also be hyperlinked to the user or team page in Opsgenie.
On-call information appears on the right side of an entity details page.
### Viewing recent Opsgenie events Click **Events** in an entity's sidebar to view recent events pulled in from Opsgenie. ### Viewing on-call information on the dev homepage The Opsgenie integration enables Cortex to pull on-call information into the on-call block on the Dev homepage. On-call data from Opsgenie is refreshed every 1 minute. ### Scorecards and CQL With the Opsgenie integration, you can create Scorecard rules and write CQL queries based on Opsgenie on-call schedules and alerts. See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.
Check if on-call is set Check if entity has a registered schedule. **Definition:** `oncall (==/!=) null` **Example** For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities: ``` oncall != null ``` This rule will pass if an entity has an on-call schedule set.
Number of alerts Number of alerts for a given lookback period that match a given [search query](https://support.atlassian.com/opsgenie/docs/search-queries-for-alerts/). **Definition:** `oncall.numOfAlerts(lookback=,query=).length` **Example** For a Scorecard focused on maturity or quality, you can use this expression to make sure a given entity has fewer than two alerts in the last month: ``` oncall.numOfAlerts(lookback=duration("P1M"),query="status: open").length < 2 ``` You could also refine this rule by specifying priority level: ``` oncall.numOfAlerts(lookback=duration("P1M"),query="priority: P1").length < 2 ``` Entities will pass this rule if they have fewer than 2 alerts with priority level "P1" in the last month.
Number of escalations Number of escalation tiers in escalation policy. **Definition:** `oncall.numOfEscalations()` **Example** This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup: ``` oncall.numOfEscalations() >= 2 ``` While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.
On-call metadata On-call metadata. * ID * Name * Type **Definition:** `oncall.details()` **Example** To find all entities without a schedule-type on-call registration, you can use this expression in the Query builder: ``` oncall.details().type =! "schedule" ``` If you're migrating on-call policies, you could use this rule to check for outdated policies. Let's say, for example, all outdated Opsgenie policies start with "Legacy" in their titles. ``` oncall.details().id.matches("Legacy*") == false ``` Entities with on-call policies that start with "Legacy" will fail, while those with other policy names will pass.
**Ownership CQL**
All ownership details A special built-in type that supports a null check or a count check, used to enforce ownership of entities. **Definition:** `ownership: Ownership | Null` **Example** An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner: ``` ownership.teams().length > 0 ```
All owner details List of owners, including team members and individual users, for each entity **Definition:** `ownership.allOwners()` **Example** The Scorecard might include a rule to ensure that entity owners all have an email set: ``` ownership.allOwners().all((member) => member.email != null) ```
Team details List of teams for each entity **Definition:** `ownership.teams(): List` **Example** The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived: ``` ownership.teams().all(team => team.description != null and team.isArchived == false) ```
### View integration logs {% hint style="info" %} This feature is available to Cortex cloud customers. {% endhint %} On the integration settings page, click the **Logs** tab to view logs from the last 7 days. Learn more in [Troubleshooting with integration logs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/..#troubleshooting-with-integration-logs). ## Background sync Cortex performs the following background jobs: * **Ownership**: A sync for Opsgenie teams every day at 9 a.m. UTC. * **Identity mapping**: A sync for Opsgenie identities every day at 10 a.m. UTC. ## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) The following options are available to get assistance from the Cortex Customer Engineering team: * **Email**: , or open a support ticket in the in app Resource Center * **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly. Don’t have a Slack channel? Talk with your Customer Success Manager.