Remedyforce Integration Guide

Benefits

  • Orchestrate responses and actions around Remedyforce incidents.
  • Customize when to notify the proper on-call team about relevant activities occurring Remedyforce.
  • Create and/or update Remedyforce incidents 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 Remedyforce so they can provide relevant updates to customers.
  • Work where you are: set incident priority, run response plays and reassign incidents, all within the Remedyforce 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.

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

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:
  • The Salesforce Cloud integration is only available to accounts on Business or Digital Operations plans. Please contact our Sales Team if you would like to upgrade to a plan featuring the Salesforce Cloud integration.
  • A Global Admin or Account Owner base role is required for configuration. If you’re not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

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 managed package. Instead, you can follow the instructions below to update the managed package.

In Salesforce:

Install the package by visiting this link:

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t4x000000YCIR

If you are installing to a sandbox, replace “login” with “test” in the link above.

Integration Walkthrough

In PagerDuty
    1. Navigate to the Configuration menu, select API Access 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.

PagerDuty New API Key

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

Named Credentials Search

    1. 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
      e. Password: Paste the PagerDuty API Key (generated in step 3 of the In PagerDuty section, above).
      f. Callout Options:

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

Callout Options

Click Save to continue.

    1. 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 to perform the following terminal command.

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

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 a 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.

    1. 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.

    1. 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.

OAuth Policies

Profiles

    1. 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.
    2. 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.

Permission Sets

Home Users

    1. 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.

App Manager

In PagerDuty (Cont.)

    1. Navigate to Configuration, select 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—–:
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCobiPCCpj3bir
rrhZybhD3gZq4UCJ4CxTjn/Uip+D1tkXAK6xZuVOoaAprAwzw/oHIoqUQ49aA9fn
rTS93LZ4Nh2yfdhlk3JIxxxxxxxxxxxxxxxxxFeJYodnXOmpMnIHPjV9E2Z0Gj3
LfqznEOEeVkZU8OpFcYXzuhI4dxTeLdfFi8nxKZwX6dDCDBOd/rUygOcM5MryDM2
GEba7JJpFGngfab/5enP8pToMK4uyT8zwer75zZPg1FC241Jr0MOeBpG8fGnmUmo
5zoY3glpbtTSLYUw72FAtggw95wTWEenNDMjWWtsvDeUOobpcmtO/a6qh56DoT5A
oDLEo16bAgMBAAECggEBAIAxxxxxxxxxxxxxxxxxxxmiGHC3HlPagOT80QYYpGnT
4WRJ+LbICD1dgHs5qfCffHSCL8/BwBpgYrjYfhcvOx061lFWzrJHF/OWqn7sIIXv
SM3ELrFxUPFE02rIvYxaWeYpaKo8XfiFW+UU9JJanmz1lohZ5dWN5kuqE9+pVf2V
5m/t1GpXZh746T47KpnZ6b3b2GwmTk9O2c+6MLLBHIiHRoCBwBLzNlegY1/o1Uz+
0mnDOXmCO7gqeEiM2e/s8A1c1PdYKj1LsI0EaQm9C/iMr7ep58TZwDPBWzdYG75I
YAkCNcfXqu7nohYiHMmzWHYUmTA9ukjsqZ34p7yE1gECgYEA1iClRbbcvG33dOby
3k/JQHQ/x4hYCITkrVeL1rk+Zxxxxxxxxxxxxxxxxxxxxxxx3PWqLDcnhnr94KiL
izPSAimtelKhIlMk4pty+BqHl4m5l11PdMI6YVMUMq19F1Mo4DNysR4vQFcQhIz2
Wi9joM3uj1fXuhVnH8s+FyPdpnsCgYEAyV3cJCKSX4fZuiRnM5h01etzLQ4To1UZ
ku3WhdG295ZkQnh+QeaaaABsP2nyu9jsYvp2TBBA1G4p0wObzmKAczQbbmQjUs+u
/D+1kiokliEXAj8r+KHsghiOxxxxxxxxxxxxxxxxxxxxxxxxaq+MqoXA2kKFULcW
hQR0rBTIvmECgYAAzpiw3ZKRZzyyhRhPPC++/XEsGFh0l8Og356YTZRtnm5SKUB8
+uXeI4DftGYCJF1BHu/oQMD2YcpJKXl1KdnVxkBwIJWY4oVWEU3qn3b5XDyF1IUz
JHRB36VI15yMFPUneyoofrug23MlfL6E8n7GoWAPzD305pW/6e0u+ySftwKBgQDD
2r3mi5WwwxJ7ITMblPp2orZ4qQtivr/MD/aqW8rJT4aevFGZSXD/HQIsP6FvIdLx
hkiPPPPBapDVg9oER/xFkPXxxxxxxxxxxxxxxxxxxxxxxxseTmgaNUaLt6jGyVUa
KncC2jqnipfmU6N2+94mcUedQjwmwJ1vrWDJisGhoQKBgB8qo3ivsmwoD9hTGPrE
CBudI7dFqU5V6MDl9xxxxxxxxxxxxxxxxxxxxxxxxvjpT9Xha7p7gXO30kwKVSBe
MDKPwKFD3icyby27TxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSDUaD8Sh5Owpzj2g8X
eg2HdKgU9bgV+fuei+zI34jZ
-----END PRIVATE KEY-----

 

      • Salesforce RestResource URL: Enter pagerdutyrf/pagerduty/webhook

Click Save to continue.

    1. 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

    1. In Salesforce Cloud, click the cog icon, select Setup, click Objects and Fields in the left hand menu and select Object Manager.
    2. Click the BMC Remedyforce Incident object and click Triggers in the left hand menu. Click New on the right side of the screen.
    3. Enter the following text as a trigger body:
trigger PagerDutyIncidentTrigger on BMCServiceDesk__Incident__c (after insert, after update) {
    if (!System.isFuture() && !System.isBatch()) {
        String oldStr = JSON.serialize(Trigger.oldMap);
        String newStr = JSON.serialize(Trigger.newMap);
        if (!Test.isRunningTest()) pagerdutyrf.PagerDutyEngineLauncher.launchByTrigger(oldStr, newStr, Trigger.isInsert, UserInfo.getUserEmail());
    }
}
    1. Click the BMC Remedyforce Incident History object and click Triggers in the left hand menu. Click New on the right side of the screen. Enter the following text as the trigger body:
trigger PagerDutyIncidentHistoryTrigger on BMCServiceDesk__IncidentHistory__c (after insert) {
  if (!System.isFuture() && !System.isBatch()) {
    Set<ID> ids = Trigger.newMap.keySet();
    if (!Test.isRunningTest()) pagerdutyrf.PagerDutyEngineLauncher.launchByCaseCommentTrigger(ids, UserInfo.getUserEmail());
  }
}

 

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.

In the SUMMARY tab, if the Named Credential was properly configured, the Connection should show an OK message in green text.

Summary

 

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.
    1. 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.
    2. 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.
    3. 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.
    1. Under When, depending on your preferences, select All conditions are met OR Any conditions are met.
    2. 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. Trigger, Acknowledge, Resolve, Assign, Escalate, Custom or Delegate.
      • 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. Triggered, Acknowledged or Resolved.
      • PagerDuty Service: Run the rule based on events generated by a selected PagerDuty service.
      • 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.
      • 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.
      • Urgency: Run the rule based on the selected incident urgency.

The available Salesforce Fields vary by object label and account configuration. Please search for your object’s fields in Salesforce’s documentation 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.

    1. 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.
      • 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 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 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.

Action Setup

Rulesets

  1. Finally, navigate back to your PagerDuty account and click Configuration, select Services 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.
  2. 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.

Service Mapping Edit

  • PagerDuty Service Mapping Name: Enter a descriptive name for the mapping.
  • Class API Name: The “API Name” of the Salesforce object class to be looked at for this mapping. You can find the API names for Salesforce object classes in Create > Objects. For Remedyforce incidents, the class name is BMCServiceDesk__Incident__c.
  • Field API Name: The API Name of the Salesforce object field to be looked at. The API names of object fields can be found in the Fields section of the object definition in Create > Objects. In Remedyforce, the incident Category field name is BMCServiceDesk__FKCategory__c, and the incident Template field name is BMCServiceDesk__FKTemplate__c.
  • Field Value: If the field is a Text field, this would just be the text to look for or set when the service mapping matches. Category and Template, however, are both “Lookup” fields, which means they have to get the ID of the desired Category or Template. You can find these ID’s by using the Query Editor in the Salesforce Developer Console. For example, to get a list of all the category names and ID’s, you can use the following SOQL query: SELECT Name, Id from BMCServiceDesk__Category__c (note that unlike SQL, SOQL does not want ; at the end of a query!) To find templates, you can use SELECT Name, Id from BMCServiceDesk__SYSTemplate__c
  • PagerDuty Service ID: This is the familiar PXXXXXX style ID of a PagerDuty Service.
  • Active on Inbound Incidents: If this box is checked, this mapping will be applied to incidents coming from PD to RemedyForce.
  • Active on Outbound Incidents: If this box is checked, this mapping will be applied to incidents going from RemedyForce to PD.

There is also a simplified alternate way to map PagerDuty Services to Remedyforce incident Categories. If you add a field labeled “PagerDuty Service ID” (API name PagerDuty_Service_ID__c) to your Category object, and then populate it with a PagerDuty PXXXXXX service ID, that Category will be mapped to the provided PagerDuty Service ID for both inbound and outbound incidents. (If a mapping exists on the Category object, it will take precedence over anything that is set in the PagerDuty Service Mappings table.)

 

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 4 permission sets included in the managed package that can be given to users.

 

PagerDutyAdministrator PagerDutyConfiguration read, write
PagerDutyIncident Mapping read, create, edit, delete
PagerDutyRules & Rulesets read, create, edit, delete
PagerDutyConfiguration Tab on
PagerDutyAuditor PagerDutyConfiguration read
PagerDutyIncident Mapping read
PagerDutyRules & Rulesets read
PagerDutyConfiguration Tab on
PagerDutyManager PagerDutyConfiguration read
PagerDutyIncident Mapping read, create, edit, delete
PagerDutyRules & Rulesets read, create, edit, delete
PagerDutyConfiguration Tab on
PagerDutyUser PagerDutyConfiguration read
PagerDutyIncident Mapping read, create, edit
PagerDutyRules & Rulesets read
PagerDutyConfiguration Tab 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 the 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:

New Case Form

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:

Log Level

 

Start Using PagerDuty Today

Try PagerDuty free for 14 days — no credit card required.