Creating, Editing, and Deleting Services and Integrations

Configuring Services and Integrations

Create a Generic Events API Integration

If an out-of-the-box integration for the tool you're using doesn't exist yet, you can create an Events API integration for just about anything, so as long as your system can make outbound HTTP calls.

To add a generic integration:

  1. Go to Configuration → Services.
  2. If you are creating a new service for your integration, click Add New Service. If you are adding your integration to an existing service, click the name of the service you want to add the integration to, go to the Integrations tab, then click New Integration.
  3. Select Use our API Directly from the Integration Type menu, select whether you would like to use our v1 or v2 Events API, and and enter an Integration Name. If you are creating a new service for your integration, under General Settings, enter a Name for your new service. Then, under incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.
  4. Click Add Service/Integration and and integration key will be generated. You'll find this key on the Integrations tab. The integration key is a unique service identifier used by the Events API to trigger, acknowledge, and resolve incidents. Use this key within your monitoring tool to send notifications to PagerDuty and create incidents within your service.

Events API v2

Our new Events API allows monitoring partners to directly send events in the PD-CEF format. If you are using custom monitoring you can also leverage this format to take advantage of the new PD-CEF display and workflow features in PagerDuty.

During your setup process you will be prompted to choose Events API v1 or v2 from a drop down menu after selecting Use our API directly from the Integration Type menu.

You must have Create alerts and incidents enabled to use our Events API v2. You will find this setting under Incident Behavior at the bottom of your service configuration screen. When an Events API v2 integration type is selected the Create incidents option will be grayed out.

Should I use API v1 or v2?

The Events API v2 is designed to handle machine-generated monitoring and event data, such as infrastructure monitoring (Nagios, SignalFX, Datadog), application performance monitoring (New Relic, AppDynamics), and external site checks (Pingdom, Wormly). PD-CEF events generate alerts in PagerDuty, which can then be grouped together into Incidents within PagerDuty.

For human-generated events, tickets, or incidents, such as those from ServiceNow or JIRA, we suggest using the Events API v2, which enables direct, streamlined creation of PagerDuty incidents.

If you are using a custom monitoring tool, library, or script that has not yet been updated to V2, you should use the Events API v1.

Configuring Services and Integrations

A service may represent an application, component or team you wish to open incidents against.

Many monitoring tools can integrate with PagerDuty using an API integration. However, if we do not offer an API Integration, you can use the generic email integration to integrate with any monitoring tool that has the ability to send emails (even in-house solutions).

Create a new service

You can access all services by going to ConfigurationsServices. If you are creating a new service, click Add New Service. Otherwise, you can skip to adding integrations to an existing service.

Give your service a name. Then select your app from the Integration Type menu and enter an integration name.

For the Integration Type, you have 3 options:

  1. Select a Tool. Check to see if we have an existing integration for your service. Search for your service by clicking on the drop down menu next to Integration Type.
  2. Integrate via Email. If you do not see your service in the drop-down, you can select Integrate via email. If your service can send out email alerts, you can create an integration email address in PagerDuty that you can point your service to for alerting.
  3. Use our API directly. If your service is able to make basic HTTP API calls, then you can interact directly with our API to trigger, acknowledge, and resolve incidents. Our developer documentation provides several examples of how to integrate with PagerDuty using our API.

You can then customize your service to include other attributes such as urgency, acknowledgment timeouts, auto-resolution, or alerts triage.

Add integrations to an existing service

PagerDuty allows you to add multiple integrations to a single service. This enables you to represent the actual entities you are monitoring, managing, and operating as services in PagerDuty, whether those entities are specific applications, individual micro-services in an application’s architecture, or cross-cutting shared infrastructure (such as networks, security, etc.).

With this functionality you are able to consolidate integrations under one service allowing you to share the service specific settings as well. Once these integrations are consolidated under the same service, you will get proper service-level reporting in our Reporting & Analytics UI.

  1. Navigate to Configurations → Services and select a service to add an integration to. Open the Integrations tab and click New Integration.
  1. Select your integration type as described above and name your integration. Click Save.

Once these integrations are added, you can also move integrations to other Services. For more information on this, please check out our article on moving integrations to another service.

For additional tips on how to use multiple integrations to best represent your internal systems, please check out our best practices article here.

Delete an integration from a service

If an integration is no longer needed, it can be deleted. After an integration has been deleted, it cannot be recovered and you will need to create a new integration of the same type on the service should you wish to use that integration again.

Note:

If you'd like to instead temporarily deactivate an integration, you can either place the service in maintenance mode, or temporarily move the integration to an inactive service.

  1. Find the integration to delete by navigating to ConfigurationsServicesIntegrations.
  2. Click the gear icon for the integration and select the Delete option.

When an integration is deleted, we do not remove the incidents. There are no changes to the open or resolved incidents.

Disable a Service

If a service is no longer in use and you want to preserve its settings for future use, or you would like to disable it so that incidents are not triggered, you can disable the service and re-enable it later with the settings intact.

Disabling a service is very similar to putting a service in maintenance mode, in that no incidents will be created and triggered when a service is in either of these states.

However, whereas when a service is in maintenance mode, PagerDuty can automatically bring the service back to an "Active" state so that incidents can be triggered, when a service is disabled, you will need to manually re-enable it so that incidents can be triggered.

To disable your service:

  1. Go to the Configuration menu and select Services.
  2. Click on the name of the service you would like to disable.
  3. Click Disable Service on the right-hand sight of the page and then click OK on the confirmation dialog.

To re-enable a service:

  1. Go to the Configuration menu and select Services.
  2. Click on the name of the service you would like to enable.
  3. Click on the Enable this service button, and your service will be enabled.

Move an Integration to Another Service

You have the ability to move an integration from one service to another if need be. You can move integrations between as many services as needed, as many times as needed and all incidents tied to that integration will follow.

Note

Your integration key will not change after moving the integration from one service to another.

  1. Go to Configuration → Services.
  2. Click on the service which contains the integration you would like to move.
  3. Go to the Integrations tab on the service's page. Then use the settings gear next to the integration to select Move to Another Service. You have the option rename the integration before or after moving it.

Note

If the settings on the service you are moving an integration to differ from the current service, you'll receive a warning message with the option to proceed or cancel.

  1. Select the Destination Service where you would like the Integration to move to, and click Move Integration.

Create a Vendor Specific Service via API

The easiest way to create a service and integration is in the PagerDuty web UI, however, you can create a service with a vendor-specific integration via the API.

You’ll need to know the vendor_id. Although we haven’t documented the vendor API, it follows the same pattern as our other APIs. Here's an example using PDJS to look up vendor_id: http://jsfiddle.net/8fxudqbj/6/.

Note: You will need a v1 API key to use this JSFiddle.

Here is a list of common vendor_ids:

AWS Cloudwatch

PZQ6AUS

Nagios

P5ZAJ2D

New Relic

PQFCJER

ServiceNow

PRC098W

Zabbix

PJOGQ4Q

After finding the right vendor_id, you'll need to POST the new service to the services endpoint with type: "integration", vendor_id: "PQFCJER"

Example: http://jsfiddle.net/eurica/sdL4wrob/

Creating, Editing, and Deleting Services and Integrations

Configuring Services and Integrations