# Salesforce Service Cloud v2 Integration Guide

Configure the Salesforce Service Cloud v2 integration

## Salesforce Cloud + PagerDuty Integration Benefits

- Orchestrate responses and actions around customer issues, sales opportunities, and other activities across your organization.
- Customize when to notify the proper on-call team about relevant activities occurring in Salesforce Cloud.
- Create and/or update Salesforce Cloud objects with relevant information as soon as there's a PagerDuty update such as an acknowledge, resolve, reassign, etc.
- Keep your teams up-to-date with synced notes between PagerDuty and Salesforce Cloud so they can provide relevant updates to customers.
- Work where you are: set incident priority, run response plays and reassign incidents, all within the Salesforce Cloud interface.
- Compatible with any Salesforce Cloud standard object present in your account.
- Each PagerDuty subdomain can be connected to multiple Salesforce Cloud objects to streamline cross-organizational collaboration.

> **Pricing Plan:** The Salesforce Cloud integration is available to accounts on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. Please [contact our Sales Team](https://www.pagerduty.com/contact-us/) if you would like to upgrade to a plan featuring the Salesforce Cloud integration.

## Version

This guide outlines configuration for the **Salesforce Service Cloud v2** integration.

> **Looking for a Different Version?:** The [Salesforce Service Cloud v3](/integrations/salesforce-service-cloud-integration-guide) integration is also available.

## How it Works

- Once a Salesforce Cloud object is connected to your PagerDuty instance, new record creations and updates on that object are evaluated against rules that you predefine. If the rule criteria is met, PagerDuty will perform actions specified by those predefined rules.
- PagerDuty can also send information to Salesforce Cloud, where you can define the evaluation criteria against the updates made in PagerDuty and select an action to be performed in Salesforce Cloud.

## Requirements

### Required Permissions to Configure the Integration

**In Salesforce Cloud**:

- Permissions to Install Salesforce Managed Package applications.
- A Salesforce Professional, Unlimited or Enterprise edition, which can allow Apex classes to be run from a Managed Package.
- Ensure that API Access is enabled on your Organization. Salesforce Organizations in Trial Mode will normally not have API access enabled.

**In PagerDuty**:

- A Global Admin or Account Owner base role is required for configuration.

### Required Permissions to Use the Integration

Please see our [FAQ](#what-kind-of-permissions-do-users-need-to-use-this-integration) for more information.

## Updating the Salesforce Managed Package Version

> **Do Not Uninstall Previous Version:** If you have already configured the previous version, in order to preserve your previously created rules and rulesets, we recommend that you never uninstall the previous version of the Salesforce managed package. Instead, you can follow the instructions below to update the managed package.

**In Salesforce**:

1. Log in as a Salesforce Admin and search for the **PagerDuty** app in the AppExchange.
2. Click **Get It Now** to download most recent version of the app.
3. Continue with the **Integration Walkthrough** below.

## Integration Walkthrough

### In PagerDuty

1. Navigate to **Integrations**  →  **API Access Keys** and click **Create New API Key.**
2. Enter a **Description** (e.g. "Salesforce Cloud API Key") and click **Create Key**.
3. On the next screen, **copy the API Key** and **paste it in a safe place for future use**. **Note**: You will not have access to this key after this screen.

![Copy API key](/images/kb/aa741d5442281e92506b9a658d7801a656393eac2c37dfd65e295d5ddc7887f1-salesforce-ig-new-api-key.webp)
*Copy API key*

### In Salesforce Cloud

4. Next, you will set up the API connection between PagerDuty and Salesforce Cloud. In the Salesforce AppExchange, search **PagerDuty** and **install the app**.
5. Once installed, in your Salesforce Cloud account, click the **cog icon** on the right hand side and select **Setup**.
6. In the Setup console, search for and click **Named Credentials**.

![Search for Named Credentials](/images/kb/205218a1bd6d42ccccd6158876a35402a4c7a6ee51dcfd7a417c33b49badcb85-salesforce-ig-named-credentials.webp)
*Search for Named Credentials*

7. Click the **New Named Credential** button and enter the following information in the fields on the next screen:

   a. **Label**: PagerDuty_API
   b. **Name**: PagerDuty_API
   c. **URL**: `https://api.pagerduty.com`
   d. **Certificate**: null
   e. **Identity Type**: Named Principal
   f. **Authentication Protocol**: Password Authentication
   g. **Username**: PagerDutyAPI
   h. **Password**: Paste the PagerDuty API Key (generated in step 3 of the In PagerDuty section, above).
   i. **Callout Options**:

   - Generate Authorization Header: UNCHECK
   - Allow Merge Fields in HTTP Header: CHECK
   - Allow Merge Fields in HTTP Body: UNCHECK

![Check Allow Merge Fields in HTTP Header](/images/kb/ecd60399c55bdfa38ac503d19c55abd6e8a9a68b9b6d63e31d48385a2bee90d4-salesforce-ig-callout-options.webp)
*Check Allow Merge Fields in HTTP Header*

Click **Save** to continue.

8. Next, you will set up the PagerDuty extension using Salesforce Cloud OAuth.

- **Mac OS**: On your machine, open the **Terminal** app.
- **Windows OS**: You will need to download [OpenSSL](https://www.xolphin.com/support/OpenSSL/OpenSSL_-_Installation_under_Windows) to perform the following terminal command.

Enter the following command in the Terminal app or OpenSLL and press **Return/Enter**:

```shell
openssl req -x509 -nodes -subj "/C=US/ST=CA/L=San Francisco/CN=pagerduty.com" -days 3650 -newkey rsa:2048 -keyout nameOfSharedKey.pem -out nameOfSalesforceCertificate.pem
```

This will generate an X.509 certificate and a shared key as a local file on your computer (it will not generate in Terminal). To find the files, open **Finder** on Mac or click **File** on PC, search for `nameOfSalesforceCertificate.pem` and `nameOfSharedKey.pem` and open the files with a text editor program. These will display the certificate and shared key that you will be using in later steps, so leave the files open for now.

9. Next, in Salesforce Cloud, click the right hand **cog** and select **Setup**. In the left hand menu, select **Apps** then **App Manager** and click **New Connected App** on the right hand side. Enter the following details:

- **Connected App Name**: PagerDuty
- **API Name**: PagerDuty
- **Contact Email**: Your preferred email address.
- **API (Enable OAuth Settings)**: CHECK
- **Callback URL**: Can use any URL (e.g. `http://localhost`). This is a required field in Salesforce Cloud, but it is not used by PagerDuty.
- **Use Digital Signatures**: CHECK. Once checked, click **Choose file** and select the `nameOfSalesforceCertificate.pem` file that was created from the Terminal command in step 8.
- **Selected OAuth Scopes**:
  - Select `Access and manage your data (api)` and click **Add**.
  - Select `Perform requests on your behalf at any time (refresh_token, offline_access)` and click **Add**.

Click **Save**. You may see the following prompt after saving: `Allow from 2-10 minutes for your changes to take effect on the server before using the connected app.` Click **Continue**.

10. Click **Edit Policies** and select **Admin approved users are pre-authorized** in the Permitted Users field, click **Save**. On the next screen, click **Manage**, scroll down to the Profiles section and click **Manage Profiles**.

![Manage OAuth Policies](/images/kb/9c87497b700bf8903d0f4998c2ce203c38e850739dd5f616bdc6b75da3c08b9c-salesforce-permitted-users.webp)
*Manage OAuth Policies*

![Click Manage Profiles](/images/kb/fac457339f46afacba46497b8daba3bd3b9835ee5686574e56382430c76dfd7d-salesforce-manage-profiles.webp)
*Click Manage Profiles*

11. Next, **check** the box next to the Profile of the user who will be sending the request from PagerDuty to Salesforce Cloud and click **Save**.
12. If you do not have a `System Administrator` user role in Salesforce, navigate to your **User Profile**, and click **Edit Assignments** under the the Permission Set Assignments section. Add the `PagerDutyAdministrator` permission set from **Available Permission Sets** to the **Enabled Permission Sets** column, and click **Save**.

![Configure permission sets](/images/kb/e2e2b6127ab299966ac1c355cb7b8a37bf2e4c390d2f3d8e0c282b96ae8f471c-PD-Permission-Column.webp)
*Configure permission sets*

![Configure users](/images/kb/387ca6460e548461dbbeab15297487e033e1c4cd30596b58d67bab7cfb4e7a28-PD-PermissionSet.webp)
*Configure users*

13. Finally, navigate back to **Apps**  →  **App Manager**, click the dropdown to the right of the **PagerDuty** connected app and select **View**. You will be using information from this screen in the steps in PagerDuty, below.

![View PagerDuty connected app](/images/kb/b2938c95a9552fb76683c163c9861c7115c4ea18be4547695d36e011b7938801-salesforce-view-pd-app.webp)
*View PagerDuty connected app*

### In PagerDuty (Cont.)

14. Navigate to **Integrations**  →  **Extensions** and click **New Extension**. Enter the following information:

- **Extension Type**: Search and select **Salesforce (OAuth Flow)**.
- **Name**: Provide a name for this extension.
- **Service**: Select which **service** this webhook should be tied to.
- **Consumer Key**: Copy the **Consumer Key** from the Connected App screen in Salesforce Cloud and paste it in this field in PagerDuty.
- **Username**: Enter the Salesforce Cloud Username of the user who will be sending webhooks from PagerDuty.
- **Salesforce Shared Key**: Copy the shared key from the `nameOfSharedKey.pem` file you opened on your computer in earlier steps and paste the contents in here. It should look similar to the following, and you need to include the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`:

![Redacted Salesforce shared key](/images/kb/4d0f40ebbd3552518394892bf9251cbc7533b532fa79170bcc7c8514ae3f613b-salesforce-private-key.webp)
*Redacted Salesforce shared key*

- **Salesforce RestResource URL**: This can be left blank if you are using the PagerDuty out-of-the-box integration. If building a custom integration, you can specify where the PagerDuty webhooks will be delivered.

Click **Save** to continue.

15. If you would like to configure a connection between PagerDuty and **multiple Salesforce Cloud objects** in your account, continue to step 16 in the next section. If you are **only using the integration with the Case object**, skip to step 20.

### Configure Connection Between PagerDuty and Salesforce Cloud Objects

16. In Salesforce Cloud, click the **cog** icon, select **Setup**, click **Objects and Fields** in the left hand menu and select **Object Manager**.
17. Click the **Label** name of the object on which you would like to create a trigger and click **Triggers** in the left hand menu. Click **New** on the right side of the screen.
18. Enter the following text as a trigger body, replacing `[SALESFORCE-OBJECT]` with your Salesforce Cloud object:

```
trigger PagerDuty[SALESFORCE-OBJECT]Trigger on [SALESFORCE-OBJECT] (after insert, after update) {
    if (!System.isFuture() && !System.isBatch()) {
        String oldStr = JSON.serialize(Trigger.oldMap);
        String newStr = JSON.serialize(Trigger.newMap);
        if (!Test.isRunningTest()) pagerdutyinc.PagerDutyEngineLauncher.launchByTrigger(oldStr, newStr, Trigger.isInsert);
    }
}
```

**Example**:

![Example trigger](/images/kb/df4b5dcf1e6b528266abd24dc53a54b5edc6a62f36538be88e422dfcfbca9b5e-salesforce-apex-trigger.webp)
*Example trigger*

19. Click **Save**. Repeat steps 15-18 for each object on which you would like to create a trigger. Once you are finished, continue to step 19.
20. Next, you will set up rules to trigger the bi-directional integration. Click the **App Launcher** on the left hand side, search and then click **PagerDuty Configuration**.
21. In the SUMMARY tab, if the Named Credential was properly configured, the Connection should show an OK message in green text.

![Connection OK](/images/kb/7a089e31fade9d580a8e65bc9e79a2a5c1089e1c2c7cc05ed09d794d5fc02368-salesforce-ig-connection-ok.webp)
*Connection OK*

In the **OBJECT MAPPINGS** tab:

- **Integration User Email**: Provide the email that belongs to the integration user who will be creating and updating the incidents in PagerDuty.
- **Sync Salesforce Comments to PagerDuty Notes (optional)**: You can sync the Salesforce Cloud Case Comments to PagerDuty Notes, but please be aware that syncing between the two may consume your API request limits in Salesforce Cloud.

22. You are now ready to build rules that trigger actions bi-directionally between PagerDuty and Salesforce Cloud. Select the RULESETS tab. This is where you will build the rules that will specify what should happen to the object and fields when PagerDuty sends an update back to Salesforce Cloud. Click the **Add Ruleset** button on the right, enter a **Ruleset Name** and click **Save**. Click the **ruleset name** and click the **Add Rules** button. Enter a **Rule Name**, click **Save** and then click the **name** of the rule. Each rule will ask for conditions that should be met prior to performing the actions specified in the latter part of the rule definition.
23. In the **Choose SalesForce Object** field, search and select the **Salesforce Cloud object** that you would like to map to PagerDuty based on this rule's criteria.
24. Next, depending on the direction you would like actions to be triggered, make the following selection in the **Run rule on** section:

- **Salesforce to PagerDuty Actions**: Select **[OBJECT-LABEL] create or update**.

OR

- **PagerDuty to Salesforce actions**: Select **PagerDuty incident create or update**.

25. Under **When**, depending on your preferences, select **All conditions are met** OR **Any conditions are met**.
26. Click **Add Condition**. Under **Choose Field**, you will have the option to choose fields from PagerDuty or from your Salesforce Cloud object that this rule will run on.
    The following **PagerDuty Fields** are available:

- **Event Type**: Run the rule based on the [type of PagerDuty event](/incident-management/incidents/event-management). Trigger, Acknowledge, Resolve, Assign, Escalate, [Custom](/integrations/custom-incident-actions) or [Delegate](/incident-management/incidents/reassign-incidents).
- **Incident Title**: Run the rule based whether the PagerDuty incident Title matches a predefined string.
- **Incident Status**: Run the rule based on the [PagerDuty incident's status](/incident-management/incidents/event-management). Triggered, Acknowledged or Resolved.
- **PagerDuty Service**: Run the rule based on events generated by a [selected PagerDuty service](/incident-management/services/services-and-integrations).
- **PagerDuty Service Name**: Run the rule based on events generated by a PagerDuty service name that matches a predefined string.
- **PagerDuty Escalation Policy**: Run the rule based on incidents assigned with a [selected PagerDuty escalation policy](/incident-management/schedules/escalation-policies).
- **PagerDuty Escalation Policy Name**: Run the rule based incidents assigned with a PagerDuty escalation policy name that matches a predefined string.
- **PagerDuty Incident Priority**: Run the rule based on the selected [incident priority](/incident-management/incidents/incident-priority).
- **Urgency**: Run the rule based on the selected [incident urgency](/incident-management/incidents/dynamic-notifications).

The available **Salesforce Fields** vary by object label and account configuration. Please search for your object's fields in [Salesforce's documentation](https://help.salesforce.com/home) for more details.

Next, select an **Operation** and enter a **value** to complete the condition. You may choose to add multiple conditions for each rule. Once you are done adding your conditions, proceed to step 26.

27. Next, click **Add Action** and select a PagerDuty Action or Salesforce Cloud Action. You may choose multiple actions to be triggered from each rule.

**PagerDuty Actions**:

- **Create new Incident, if there are no linked incidents**: If rule conditions are met, create a PagerDuty [incident](/incident-management/incidents/event-management).
- **Acknowledge Incident**: If rule conditions are met, acknowledge the PagerDuty incident.
- **Resolve Incident**: If rule conditions are met, resolve the PagerDuty incident.
- **Set Incident Priority**: If rule conditions are met, set the PagerDuty incident's [priority](/incident-management/incidents/incident-priority) to a specified value.
- **Run Response Play**: If rule conditions are met, run a specified response play on the incident.
- **Reassign**: If rule conditions are met, [reassign](/incident-management/incidents/reassign-incidents) the PagerDuty incident.

**Salesforce Cloud Actions**:

- **Set [SALESFORCE-OBJECT] field value**: If rule conditions are met, set an object's specified field value.
- **Create new [SALESFORCE-OBJECT]**: If rule conditions are met, create a new specified object.

![Select PagerDuty action](/images/kb/0310b6ea1ae19818649998f96551a9a68f0a19e5dbc8c1a32a9e563cf32f2a02-salesforce-actions.webp)
*Select PagerDuty action*

28. Click **Save** to complete the rule configuration. Navigate back to the **RULESETS** tab and click the toggle switch next to your ruleset to **Enabled**.

![Enable ruleset](/images/kb/edd7e616be69f7fe318e21c4e6eb31d9b264ab99e4f03f9d2604e7fcadd8b9f9-salesforce-enable-ruleset.webp)
*Enable ruleset*

29. Finally, navigate back to your PagerDuty account and click **Services**, select **Service Directory** and click the **name** of the service that you just connected to the Salesforce OAuth Flow webhook. Manually trigger a test incident on this service.
30. Once the test incident has been triggered, return to Salesforce Cloud, click the **App Launcher** and search and select **PagerDuty Logs** to see if a webhook from PagerDuty arrives. When you receive the webhook, the integration is complete. If you do not receive the webhook, check your log management tool to troubleshoot why the webhook failed to deliver.

## FAQ

**Can you automatically create an incident in PagerDuty once a Salesforce Cloud object meets certain criteria?**

Yes. After specifying your evaluation conditions, select that you want to "Create an incident on a service in PagerDuty", and select a relevant service to notify.

**What kind of permissions do users need to use this integration?**

If you use custom permissions in Salesforce, you will need to ensure that agents have the correct permissions to use and access the PagerDuty integration. There are four permission sets included in the managed package that can be given to users.

| Permission Set | PagerDutyConfiguration | PagerDutyIncident Mapping | PagerDutyRules & Rulesets | PagerDutyConfiguration Tab |
| :--- | :--- | :--- | :--- | :--- |
| **PagerDutyAdministrator** | read, write | read, create, edit, delete | read, create, edit, delete | on |
| **PagerDutyAuditor** | read | read | read | on |
| **PagerDutyManager** | read | read, create, edit, delete | read, create, edit, delete | on |
| **PagerDutyUser** | read | read, create, edit | read | off |

If you do not want to add permission sets to your users, you may check their profiles and ensure the profiles have similar object permissions for their user type.

**If I'm a Managed Service Provider, or would like to create new cases in Salesforce Cloud based on information I get from other integrations, can I do that with this integration?**

Yes. When you're defining the rule, make sure you select On PagerDuty Update instead of object create/update, specify what conditions to look for on a PagerDuty update, and what you would like Salesforce Cloud to do when it meets that criteria. For example, if you want to automatically create a Salesforce Cloud Case object when a PagerDuty Incident is created on Service "XYZ", you would have a Ruleset that looks like the following:

![Example ruleset](/images/kb/fc71fe646c9efe64c7fecec9f196b001045164cfdc04ff7321f5e1f2d75fb356-salesforce-ig-faq-example.png)
*Example ruleset*

Make sure you also use Set [SALESFORCE-OBJECT] field value for ALL required fields in your Salesforce Cloud object.

**How can I troubleshoot my integration?**

We have provided a logging tool to help troubleshoot problems in the integration. Under the **LOGGER** tab in the PagerDuty Configuration, you can turn on logging by selecting one of the following levels and clicking **Save**:

![Select log level](/images/kb/2a79bd8628fd5eaac39b19bdab16d785f4b3b6858df4c29a3749c6282a1dc0f1-salesforce-logger.png)
*Select log level*