Opsgenie
Port's Opsgenie integration allows you to model Opsgenie resources in your software catalog and ingest data into them.
Core support
Overview
This integration allows you to:
- Map and organize your desired Opsgenie resources and their metadata in Port (see supported resources below).
- Watch for Opsgenie object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
Setup
Choose one of the following installation methods: Not sure which method is right for your use case? Check the available installation methods.
The prerequisites required for installation are listed below.
An OpsGenie API token with the read and configuration access scopes is required. Port requires the read permission to allow the integration to access incidents and alerts. Port also needs the configuration access permission to allow the integration to access service, teams, and schedules. See here for more information on OpsGenie API key management.
-
Go to the Opsgenie Connectors page in Port.
-
Under
Select your installation method, chooseHosted by Port. -
Configure the
Installation parametersandAdvanced configurationas you wish (see below for details).
Installation parameters
Each integration requires specific parameters (such as an API token, a URL, etc.), as seen in Port's UI when installing it. Hover over the ⓘ icon next to each parameter to see more details about it.
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port secrets
Some integration settings require sensitive pieces of data, such as tokens. For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.
When filling in such a setting, its value will be obscured (shown as ••••••••).
For each such setting, Port will automatically create a secret in your organization.
To see all secrets in your organization, follow these steps.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
-
Go to the Opsgenie Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Scalable mode for large integrations
If you are deploying the integration at scale and want to decouple the resync process from the live events process (recommended for large or high-throughput environments), you can enable scalable mode by adding the following flags to your Helm install command:
--set workload.kind="CronJob" \
--set workload.cron.resyncTimeoutMinutes=60 \
--set scheduledResyncInterval="'*/60 * * * *'" \
--set liveEvents.worker.enabled=true
Required parameters:
port.clientId- Your port client id.port.clientSecret- Your port client secret.port.baseUrl- Your Port API URL -https://api.port.iofor EU,https://api.us.port.iofor US.integration.identifier- Change the identifier to describe your integration.integration.type- The integration type.integration.eventListener.type- The event listener type.integration.secrets.apiToken- The Opsgenie API token. Docs can be found here.integration.config.apiUrl- The Opsgenie API URL. If not specified, the default will be https://api.opsgenie.com.
Optional parameters (click to expand)
scheduledResyncInterval- The number of minutes between each resync.initializePortResources- Default true, When set to true the integration will create default blueprints and the port App config Mapping.sendRawDataExamples- Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true.
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the Opsgenie Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
api_token | The Opsgenie API token, docs can be found [here](https://support.atlassian.com/opsgenie/docs/api-key-management/). | ✓ | ✓ |
api_url | The Opsgenie API URL. If not specified, the default will be https://api.opsgenie.com. | ✓ | ✓ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Opsgenie API token, docs can be found [here](https://support.atlassian.com/opsgenie/docs/api-key-management/). | ✓ | ✓ |
OCEAN__ | The Opsgenie API URL. If not specified, the default will be https://api.opsgenie.com. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Opsgenie API token, docs can be found [here](https://support.atlassian.com/opsgenie/docs/api-key-management/). | ✓ | ✓ |
OCEAN__ | The Opsgenie API URL. If not specified, the default will be https://api.opsgenie.com. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the Opsgenie Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | The Opsgenie API token, docs can be found [here](https://support.atlassian.com/opsgenie/docs/api-key-management/). | ✓ | ✓ |
OCEAN__ | The Opsgenie API URL. If not specified, the default will be https://api.opsgenie.com. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Capabilities
Configure real-time updates
Currently, the OpsGenie API lacks support for programmatic webhook creation. To set up a webhook configuration in OpsGenie for sending alert notifications to the Ocean integration, follow these steps:
Prerequisites
Prepare a webhook URL using this format: {app_host}/integration/webhook.
The app_host parameter should match the ingress or external load balancer where the integration will be deployed.
For example, if your ingress or load balancer exposes the OpsGenie Ocean integration at https://myservice.domain.com, your webhook URL should be https://myservice.domain.com/integration/webhook.
Create a webhook in OpsGenie
- Go to OpsGenie.
- Select Settings.
- Click on Integrations under the Integrations section of the sidebar.
- Click on Add integration.
- In the search box, type Webhook and select the webhook option.
- Input the following details:
Name- use a meaningful name such as Port Ocean Webhook.- Be sure to keep the "Enabled" checkbox checked.
- Check the "Add Alert Description to Payload" checkbox.
- Check the "Add Alert Details to Payload" checkbox.
- Add the following action triggers to the webhook by clicking on Add new action:
- If alert is snoozed in Opsgenie, post to url in Webhook.
- If alert's description is updated in Opsgenie, post to url in Webhook.
- If alert's message is updated in Opsgenie, post to url in Webhook.
- If alert's priority is updated in Opsgenie, post to url in Webhook.
- If a responder is added to the alert in Opsgenie, post to url in Webhook.
- if a user executes "Assign Ownership in Opsgenie, post to url in Webhook.
- if a tag is added to the alert in Opsgenie, post to url in Webhook.
- .if a tag is removed from the alert in Opsgenie, post to url in Webhook.
Webhook URL- enter the value of theURLyou created above.
- Click Save integration.
Configuration
Port integrations use a YAML mapping block to ingest data from the third-party api into Port.
The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
Default mapping configuration
This is the default mapping configuration for this integration:
Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
- kind: team
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieTeam"'
properties:
description: .description
url: .links.web
- kind: schedule
selector:
query: 'true'
apiQueryParams:
expand: rotation
port:
entity:
mappings:
identifier: .id + "_" + .item.id
title: .name + "_" + .item.name
blueprint: '"opsGenieSchedule"'
properties:
timezone: .timezone
description: .description
startDate: .item.startDate
endDate: .item.endDate
rotationType: .item.type
relations:
owner_opsgenie_team: .ownerTeam.id
schedule_opsgenie_users: '[.item.participants[] | select(has("username")) | .username]'
schedule_users:
combinator: '"and"'
rules:
- property: '"_opsGenieUserId"'
operator: '"in"'
value: '[.item.participants[] | select(has("username")) | .username]'
itemsToParse: .rotations
- kind: service
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieService"'
properties:
description: .description
url: .links.web
tags: .tags
relations:
owner_opsgenie_team: .teamId
- kind: alert
selector:
query: 'true'
apiQueryParams:
status: open
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieAlert"'
properties:
status: .status
acknowledged: .acknowledged
priority: .priority
sourceName: .source
tags: .tags
count: .count
createdBy: .owner
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
integration: .integration.name
relations:
relatedIncident: if (.alias | contains("_")) then (.alias | split("_")[0]) else null end
responding_opsgenie_team: .responders | [.[] | select(.type == "team") | .id]
responding_team:
combinator: '"and"'
rules:
- property: '"opsgenie_team_id"'
operator: '"in"'
value: .responders | [.[] | select(.type == "team") | .id]
responding_opsgenie_user: .responders | [.[] | select(.type == "user") | .id]
responding_user:
combinator: '"and"'
rules:
- property: '"_opsGenieUserId"'
operator: '"in"'
value: .responders | [.[] | select(.type == "user") | .id]
- kind: incident
selector:
query: 'true'
apiQueryParams:
status: open
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieIncident"'
properties:
status: .status
priority: .priority
tags: .tags
url: .links.web
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
relations:
impacted_opsgenie_services: .impactedServices
impacted_services:
combinator: '"and"'
rules:
- property: '"_opsGenieServiceId"'
operator: '"in"'
value: .impactedServices
responding_opsgenie_team: .responders | [.[] | select(.type == "team") | .id]
responding_team:
combinator: '"and"'
rules:
- property: '"opsgenie_team_id"'
operator: '"in"'
value: .responders | [.[] | select(.type == "team") | .id]
responding_opsgenie_user: .responders | [.[] | select(.type == "user") | .id]
responding_user:
combinator: '"and"'
rules:
- property: '"_opsGenieUserId"'
operator: '"in"'
value: .responders | [.[] | select(.type == "user") | .id]
- kind: schedule-oncall
selector:
query: 'true'
port:
entity:
mappings:
identifier: .ownerTeam.id
title: .ownerTeam.name
blueprint: '"opsGenieTeam"'
properties:
oncallUsers: .__currentOncalls.onCallRecipients
relations:
schedule_opsgenie_users: .__currentOncalls.onCallRecipients
schedule_users:
combinator: '"and"'
rules:
- property: '"_opsGenieUserId"'
operator: '"in"'
value: .__currentOncalls.onCallRecipients
- kind: user
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .fullName
blueprint: '"opsGenieUser"'
properties:
email: .username
role: .role.name
timeZone: .timeZone
isVerified: .verified
isBlocked: .blocked
address: .userAddress
createdAt: .createdAt
Mapping & selectors per resource
Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the examples page.
- kind: alert
selector:
query: 'true'
apiQueryParams:
status: open
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieAlert"'
properties:
status: .status
acknowledged: .acknowledged
priority: .priority
sourceName: .source
tags: .tags
count: .count
createdBy: .owner
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
integration: .integration.name
relations:
relatedIncident: if (.alias | contains("_")) then (.alias | split("_")[0]) else null end
responding_opsgenie_team: .responders | [.[] | select(.type == "team") | .id]
responding_team:
combinator: '"and"'
rules:
- property: '"opsgenie_team_id"'
operator: '"in"'
value: .responders | [.[] | select(.type == "team") | .id]
responding_opsgenie_user: .responders | [.[] | select(.type == "user") | .id]
responding_user:
combinator: '"and"'
rules:
- property: '"_opsGenieUserId"'
operator: '"in"'
value: .responders | [.[] | select(.type == "user") | .id]
{
"seen": true,
"id": "886b285b-b35e-487b-afe6-3d5001370363-1724857097467",
"tinyId": "13",
"alias": "355f1681-f6e3-4355-a927-897cd8edaf8f_886b285b-b35e-487b-afe6-3d5001370363-1724857097467",
"message": "Test scaling alerts",
"status": "open",
"acknowledged": false,
"isSeen": true,
"tags": [],
"snoozed": false,
"count": 1,
"lastOccurredAt": "2024-08-28T14:58:17.467Z",
"createdAt": "2024-08-28T14:58:17.467Z",
"updatedAt": "2024-08-28T14:58:59.285Z",
"source": "dev@domain.com",
"owner": "",
"priority": "P3",
"teams": [],
"responders": [
{
"type": "user",
"id": "ce544b61-7b35-43ea-89ee-a8750638d3a4"
}
],
"integration": {
"id": "00c228b7-80a4-48ae-be9c-3a1471bad69d",
"name": "Default API",
"type": "API"
},
"ownerTeamId": ""
}
{
"identifier": "886b285b-b35e-487b-afe6-3d5001370363-1724857097467",
"title": "Test scaling alerts",
"icon": "OpsGenie",
"blueprint": "opsGenieAlert",
"team": [],
"properties": {
"description": null,
"status": "open",
"acknowledged": false,
"tags": [],
"responders": [
{
"id": "ce544b61-7b35-43ea-89ee-a8750638d3a4",
"type": "user"
}
],
"integration": "Default API",
"priority": "P3",
"sourceName": "dev@domain.com",
"createdBy": "",
"createdAt": "2024-08-28T14:58:17.467Z",
"updatedAt": "2024-08-28T14:58:59.285Z",
"count": 1
},
"relations": {
"relatedIncident": "355f1681-f6e3-4355-a927-897cd8edaf8f"
},
"createdAt": "2024-08-29T10:31:34.381Z",
"createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW",
"updatedAt": "2024-08-29T10:31:34.381Z",
"updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW"
}
Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.
| Selector | Type | Description |
|---|---|---|
exportEnvVariables | array | Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing. |
apiQueryParams | object | The query parameters to filter alerts or incidents |
apiQueryParams parameters
| Parameter | Type | Description |
|---|---|---|
createdAt | string | The date and time the alert or incident was created (e.g. 2024-01-31T12:00:00Z) |
lastOccurredAt | string | The date and time the alert was last occurred (e.g. 2024-01-31T12:00:00Z) |
snoozedUntil | string | The date and time the alert was snoozed until (e.g. 2024-01-31T12:00:00Z) |
message | string | The message of the alert or incident |
status | string | The status of the alert Allowed values: open, resolved, closed. |
is_seen | boolean | Whether the alert has been seen |
acknowledged | boolean | Whether the alert has been acknowledged |
snoozed | boolean | Whether the alert has been snoozed |
priority | string | The priority of the alert Allowed values: P1, P2, P3, P4, P5. |
owner | string | The owner of the alert. Accepts OpsGenie username |
teams | string | The teams associated with the alert. Accepts a comma-separated string of team names (e.g. 'team-a, team-b') |
acknowledgedBy | string | The user who acknowledged the alert |
closedBy | string | The user who closed the alert |
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.
Limitations
Maximum offset in OpsGenie APIs
The OpsGenie APIs for Alerts and Incidents have a pagination limit where the sum of offset and limit parameters cannot exceed 20,000 records. This means you can retrieve up to 20,000 records in a single query session for each resource type.
To access records beyond the 20,000 limit, use filters to narrow your result set. This approach reduces the number of records returned and helps you bypass the offset limitation. For implementation details and supported filter options, see the examples section.
Examples
To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your connectors page. Find the integration in the list of connectors and click on it to open the playground.
Examples of blueprints and the relevant integration configurations can be found on the opsgenie examples page
Alternative installation via webhook
While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from Opsgenie. If so, use the following instructions:
Webhook installation (click to expand)
In this example you are going to create a webhook integration between OpsGenie and Port, which will ingest alert entities.
Port configuration
Create the following blueprint definition:OpsGenie alert blueprint (click to expand)
Create the following webhook configuration using Port UI: Basic details tab - fill the following details: Integration configuration tab - fill the following JQ mapping: Click Save at the bottom of the page.OpsGenie alert webhook configuration (click to expand)
OpsGenie mapper.opsgenie_mapper.A webhook configuration to map OpsGenie alerts to Port.OpsGenie.
Create a webhook in OpsGenie
- Go to OpsGenie.
- Select Settings.
- Click on Integrations under the Integrations section of the sidebar.
- Click on Add integration.
- In the search box, type Webhook and select the webhook option.
- Input the following details:
Name- use a meaningful name such as Port Webhook.- Be sure to keep the "Enabled" checkbox checked.
- Check the "Add Alert Description to Payload" checkbox.
- Check the "Add Alert Details to Payload" checkbox.
- Add the following action triggers to the webhook by clicking on Add new action:
- If alert is snoozed in Opsgenie, post to url in Webhook.
- If alert's description is updated in Opsgenie, post to url in Webhook.
- If alert's message is updated in Opsgenie, post to url in Webhook.
- If alert's priority is updated in Opsgenie, post to url in Webhook.
- If a responder is added to the alert in Opsgenie, post to url in Webhook.
- if a user executes "Assign Ownership in Opsgenie, post to url in Webhook.
- if a tag is added to the alert in Opsgenie, post to url in Webhook.
- .if a tag is removed from the alert in Opsgenie, post to url in Webhook.
Webhook URL- enter the value of theurlkey you received after creating the webhook configuration.
- Click Save integration
In order to view the different payloads and events available in Opsgenie webhooks, look here
Done! any change that happens to an OpsGenie alert (created, acknowledged, etc.) will trigger a webhook event that OpsGenie will send to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.
Let's Test It
This section includes a sample webhook event sent from OpsGenie when an alert is created. In addition, it includes the entity created from the event based on the webhook configuration provided in the previous section.
Payload
Here is an example of the payload structure sent to the webhook URL when an OpsGenie alert is created: Webhook event payload (click to expand)
Mapping Result
The combination of the sample payload and the webhook configuration generates the following Port entity:
{
"identifier": "052652ac-5d1c-464a-812a-7dd18bbfba8c",
"title": "10 - test alert",
"blueprint": "opsGenieAlert",
"properties": {
"description": "Testing opsgenie alerts",
"lastChangeType": "Create",
"priority": "P1",
"sourceName": "web",
"sourceType": "API",
"tags": ["tag1", "tag2"],
"responders": ["recipient1", "recipient2"],
"teams": ["team1", "team2"]
},
"relations": {}
}
Ingest who is on-call
In this example we will create a blueprint for service entities with an on-call property that will be ingested directly from OpsGenie.
The examples below pull data from the OpsGenie REST Api, in a defined scheduled period using GitLab Pipelines or GitHub Workflows, and report the data to Port as a property to the service blueprint.
Migration Guide to Version 0.2.0
This guide outlines how to update your existing OpsGenie integration configuration to take advantage of the performance improvements and breaking changes introduced in version 0.2.0.
Key Improvements
- New Blueprints and Kinds: Added new kinds for team, schedule, and schedule-oncall.
- Data Filtering: Introduced support for filtering data from the OpsGenie API to fetch only the necessary information.
- Enhanced Logging: Added logs for easier debugging and better insight into integration issues.
Breaking Changes
- Optimized API Calls: Removed redundant API calls for fetching impacted services and alert-incident relationships, improving performance by leveraging existing relations and JQ
- Blueprint Changes: The
OpsGenieServiceblueprint no longer contains team properties likeoncallTeam,teamMembers, andoncallUsers. These have been moved to a newOpsGenieTeamblueprint, reflecting a new relation between services and teams.
Migration Steps
Step 1: Understand Existing Configuration
In versions prior to 0.2.0, your Port app's configuration may have used a mapping like the one below:
Existing configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: service
selector:
query: 'true'
port:
entity:
mappings:
identifier: .name | gsub("[^a-zA-Z0-9@_.:/=-]"; "-") | tostring
title: .name
blueprint: '"opsGenieService"'
properties:
description: .description
url: .links.web
tags: .tags
oncallTeam: .__team.name
teamMembers: '[.__team.members[].user.username]'
oncallUsers: .__oncalls.onCallRecipients
- kind: alert
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieAlert"'
properties:
status: .status
acknowledged: .acknowledged
responders: .responders
priority: .priority
sourceName: .source
tags: .tags
count: .count
createdBy: .owner
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
integration: .integration.name
relations:
relatedIncident: .__relatedIncident.id
- kind: incident
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieIncident"'
properties:
status: .status
responders: .responders
priority: .priority
tags: .tags
url: .links.web
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
relations:
services: '[.__impactedServices[] | .name | gsub("[^a-zA-Z0-9@_.:/=-]"; "-") | tostring]'
Step 2: Update to New Configuration
To adapt to version 0.2.0, you will need to update your configuration as follows:
New configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: service
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id # The identifier of the service now uses the unique ID from OpsGenie instead of the name
title: .name
blueprint: '"opsGenieService"'
properties:
description: .description
url: .links.web
tags: .tags
- kind: alert
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieAlert"'
properties:
status: .status
acknowledged: .acknowledged
responders: .responders
priority: .priority
sourceName: .source
tags: .tags
count: .count
createdBy: .owner
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
integration: .integration.name
relations:
relatedIncident: 'if (.alias | contains("_")) then (.alias | split("_")[0]) else null end' # We now use JQ logic to map alerts to incidents to avoid making extra API call
- kind: incident
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieIncident"'
properties:
status: .status
responders: .responders
priority: .priority
tags: .tags
url: .links.web
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
relations:
services: .impactedServices # We can now directly map incidents to impacted services using the data that is coming from the API
In the updated configuration, the opsGenieService blueprint no longer includes properties like oncallTeam, teamMembers, and oncallUsers. These properties are now part of the new OpsGenieTeam blueprint. If you need to track on-call teams and users for each service, follow the steps below.
Step 3: Create the OpsGenieTeam Blueprint
To manage team-related data, create a new OpsGenieTeam blueprint in Port using the following schema:
OpsGenie team blueprint (click to expand)
{
"identifier": "opsGenieTeam",
"description": "This blueprint represents an OpsGenie team in our software catalog",
"title": "OpsGenie Team",
"icon": "OpsGenie",
"schema": {
"properties": {
"description": {
"type": "string",
"title": "Description",
"icon": "DefaultProperty"
},
"url": {
"title": "URL",
"type": "string",
"description": "URL to the service",
"format": "url",
"icon": "DefaultProperty"
},
"oncallUsers": {
"type": "array",
"title": "Current Oncalls",
"items": {
"type": "string",
"format": "user"
}
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}
Step 4: Update the OpsGenieService Blueprint
Next, update the opsGenieService blueprint to reference the OpsGenieTeam blueprint by establishing a relation and mirroring relevant properties:
Updated OpsGenie service blueprint (click to expand)
{
"identifier": "opsGenieService",
"description": "This blueprint represents an OpsGenie service in our software catalog",
"title": "OpsGenie Service",
"icon": "OpsGenie",
"schema": {
"properties": {
"description": {
"type": "string",
"title": "Description",
"icon": "DefaultProperty"
},
"url": {
"title": "URL",
"type": "string",
"description": "URL to the service",
"format": "url",
"icon": "DefaultProperty"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"title": "Tags",
"icon": "DefaultProperty"
}
},
"required": []
},
"mirrorProperties": {
"oncallUsers": {
"title": "Current Oncalls",
"path": "ownerTeam.oncallUsers"
}
},
"calculationProperties": {
},
"aggregationProperties": {
"numberOfOpenIncidents": {
"title": "Number of open incidents",
"type": "number",
"target": "opsGenieIncident",
"query": {
"combinator": "and",
"rules": [
{
"property": "status",
"operator": "=",
"value": "open"
}
]
},
"calculationSpec": {
"calculationBy": "entities",
"func": "count"
}
}
},
"relations": {
"ownerTeam": {
"title": "Owner Team",
"target": "opsGenieTeam",
"required": false,
"many": false
}
}
}
Step 5: Update the Mapping Configuration
Update your configuration mapping to correctly populate the OpsGenieTeam blueprint with team and on-call data. This will enable you to view on-call team information at the service level:
Updated configuration to add teams and oncalls (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: team
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieTeam"'
properties:
description: .description
url: .links.web
- kind: service
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieService"'
properties:
description: .description
url: .links.web
tags: .tags
relations:
ownerTeam: .teamId
- kind: schedule-oncall
selector:
query: 'true'
port:
entity:
mappings:
identifier: .ownerTeam.id
title: .ownerTeam.name
blueprint: '"opsGenieTeam"'
properties:
oncallUsers: .__currentOncalls.onCallRecipients
Final Step: Full Configuration Example
After completing these changes, your configuration should look like this, incorporating blueprints for team, service, alert and incident:
Full configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: team
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieTeam"'
properties:
description: .description
url: .links.web
- kind: service
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .name
blueprint: '"opsGenieService"'
properties:
description: .description
url: .links.web
tags: .tags
relations:
ownerTeam: .teamId
- kind: alert
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieAlert"'
properties:
status: .status
acknowledged: .acknowledged
responders: .responders
priority: .priority
sourceName: .source
tags: .tags
count: .count
createdBy: .owner
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
integration: .integration.name
relations:
relatedIncident: 'if (.alias | contains("_")) then (.alias | split("_")[0]) else null end'
- kind: incident
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id
title: .message
blueprint: '"opsGenieIncident"'
properties:
status: .status
responders: .responders
priority: .priority
tags: .tags
url: .links.web
createdAt: .createdAt
updatedAt: .updatedAt
description: .description
relations:
services: .impactedServices
- kind: schedule-oncall
selector:
query: 'true'
port:
entity:
mappings:
identifier: .ownerTeam.id
title: .ownerTeam.name
blueprint: '"opsGenieTeam"'
properties:
oncallUsers: .__currentOncalls.onCallRecipients
Following this guide will ensure your integration is up-to-date and optimized for performance with version 0.2.0. For any issues during the migration, refer to the newly introduced debug logs to identify and contact your support personnel to resolve problems efficiently.