The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
This article provides you with the installation and configuration details you need to integrate the xMatters On-Demand service with Remedyforce on the force.com platform.
The integration is written primarily in Salesforce's Apex programming language, is built off of the BMC Incident records, and fires when they are created or updated. A configuration page contains the group and individual endpoints, as well as authentication information. It also contains the list of incident fields to include in the payload.
Event injection endpoints, user response handling, event status, and delivery updates are implemented using xMatters Integration Builder.
This version of the integration is closed-loop. It adds notes to the incident detailing event status changes, notifications delivery updates (if Enable Delivery Updates flag is set), and user responses. It also updates the ownership of the incident upon 'Assign to me' user response.
This version of the integration (version 2.6) includes a number of enhancements to the installation process. It also included the features and updates from previous versions, including:
- During the "Assign to me" flow, the integration updates the Remedyforce-specific "Staff" field, instead of the record's owner.
- Added new instructions and explanation for adding an integration-specific user in Remedyforce (see Configure Remedyforce, below).
To begin, download the communication plan attached to this article to a location on your local machine. The communication plan contains pre-configured integrations, forms, properties, and messages specifically designed for Remedyforce.
Don't extract the contents of the communication plan .zip file! You'll import it directly into xMatters.
To enable OAuth2 communication between Remedyforce and the xMatters Integration Builder, you must first configure xMatters as a connected app within Remedyforce.
To set up authentication:
- Select or create a Remedyforce user account for xMatters to use in OAuth2 connections to Remedyforce.
- At the top-right. click Setup.
- In the menus on the left, expand Build > Create, and then click Apps.
- In the Connected Apps section, click New.
- Under Basic Information, enter the Connected App Name, API Name, and Contact Email.
- Expand API (Enable OAuth Settings), and then select the Enable OAuth Settings check box.
- In the Callback URL field, enter the URL of your xMatters instance; for example: https://company.host.xmatters.com/xmatters/app.do
- In the Selected OAuth Scopes list, select Access your basic information (id, profile, email, address, phone), Access and manage your data (api) and Perform requests on your behalf at any time (refresh_token, offline_access) and click Add.
- Click Save.
- On the resulting Connected App Name screen, in the API (Enable OAuth Settings) section, note or copy your Consumer Key and Consumer Secret values. (These are required when configuring your Remedyforce Endpoint in xMatters.)
- In the Salesforce setup page, under Administer > Manage Apps, click Connected Apps.
- Beside the xMatters app, click Edit.
- For IP Relaxation in the OAuth policies section, select Relax IP restrictions and click Save.
You need to create a Remedyforce user specific to xMatters, and make note of the username and password - you'll need these when you configure xMatters.
Note: To guarantee that the user is able to write to and assign incidents in Remedyforce, we recommend giving them administrative privileges.
To create a user for xMatters in Remedyforce:
- In the top-right menu, click Setup, and then navigate to Manage Users > Users.
- Click New User, and then enter the following details in the General Information section (giving the user a first and last name that identifies it as the xMatters integration user):
- First Name: xMatters
- Last Name: Integration
- Alias: xMatters
- Email: An email address that you can access.
- Username: A unique username in email format.
- Nickname: xMatters
- User License: Salesforce
- Profile: ServiceDesk System Administrator
Make sure you select ServiceDesk System Administrator, not just System Administrator.
- Role: Any available role; e.g., "IT Director".
Before configuring anything else in Remedyforce, you need to configure xMatters.
This integration requires a user who can authenticate REST web service calls when injecting events.
This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the required permissions and capabilities.
Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in reports and the Communication Center, you may want to identify the user as specific to this integration. For example:
- First Name: Remedyforce
- Last Name: Integration
- User ID: remedyforce
- Make a note of the user ID and password details – you need them when configuring other parts of the integration.
When you assign a ticket to a user or queue in Remedyforce, the integration sends a notification to the corresponding user or group in xMatters. You need to create a user or group in xMatters for each Remedyforce user or queue you want to be able to notify. The integration expects usernames in xMatters and Remedyforce to match.
The next step is to import the Remedyforce communication plan.
To import the Remedyforce communication plan:
- In xMatters, click the Developer tab, and then click Import Plan.
- Click Choose File, then locate the plan you downloaded from this article (the .zip file).
- Click Import Plan.
- Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
- Click the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user you created above, and then click Save Changes.
- Click the Edit drop-down list again and select Forms.
- For the Notifications to Groups form, click the Web Service drop-down list, and select Sender Permissions.
- Add the integration user you configured above, and then click Save Changes.
- Repeat steps 7-8 for the Notifications to Individuals form.
After you have imported the communication plan, you need to set the authentication for the xMatters and Remedyforce endpoints in the Integration Builder.
Before configuring the endpoints, make sure you have set up xMatters as a connected app in Remedyforce. You'll need the information from the connected app configuration to set the endpoints in xMatters.
To configure the endpoints:
- On the communication plan, click the Integration Builder tab, and then click the Edit Endpoints button to display the endpoints for the integration.
- Click the Remedyforce endpoint, and apply the following settings:
- Authentication: OAuth2 (Salesforce)
- Grant Type: Password
- Access Token URL: https://login.salesforce.com/services/oauth2/token
If you are installing in a sandbox, the Access Token URL must be: https://test.salesforce.com/services/oauth2/token
- Username and Password: The login credentials for the Remedyforce user account that xMatters will use in OAuth connections.
- Client ID: Enter the Consumer Key you copied when configuring the connected app.
- Client Secret: Enter the Consumer Secret you copied when configuring the connected app.
Event injection endpoints are implemented as inbound integrations. Each inbound integration has its own URL that you can use to target it from Remedyforce.
To copy the URL for an inbound integration:
- In the Integration Builder, expand the list of inbound integrations.
- Click the Inbound for Groups integration to view its details.
- Under the Select authentication method step, select Basic.
- Click Update Inbound Integration.
- Scroll down to the bottom of the page, and click Copy URL beside the field (you'll need this later to configure the Remedyforce integration).
- Repeat steps 2-5 for the Inbound for Individuals integration.
Now that you've configured xMatters, it's time to configure the rest of the integration.
The installation package within Remedyforce contains all of the components required for the integration.
To install the package:
- Log in to the target Remedyforce instance.
- Click the following link to retrieve the xMatters installation package: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t1N000002GcO5
Note: If you are installing into a sandbox organization, you must replace the initial portion of the URL with:
- Click View Components to review the Package Components screen for any potential conflicts.
- On the main Install xMatters installation screen, select Install for Admins Only, and then click Install.
Note: End users should not use the xMatters Configuration page.
- The installation can take several minutes. During installation, the system might say that it can continue installing in the background, and notify you by email when it's finished.
- After installation is complete, click Done.
Now that you've installed the package, it's time to configure Remedyforce on your system. You need to create a configuration record for the xMatters application in Remedyforce.
To create a configuration record:
- In the Salesforce Setup page, under Administer, expand Security Controls, and then click Remote Site Settings.
- Click New Remote Site.
- Enter the appropriate information for your xMatters environment, and then click Save.
- Select the xMatters application in the application selector in the upper right corner.
- On the xMatters Config tab, click New.
- In the blank configuration record, enter the appropriate information, and then click Save.
- xMatters Config: This field must be set to 'xMConfig' for the integration to find this record.
- For details about the fields found on this page, see the Field Descriptions table, below.
|xMatters Config||The name of the configuration record. This MUST be xMConfig (which is also case-sensitive), otherwise the code will not be able to find the record and the integration will fail.|
|xMatters Group Endpoint||The integration URL of the Inbound for Groups integration, available on the Integration Builder tab in the Remedyforce communication plan.|
|xMatters Individual Endpoint||The integration URL of the Inbound for Individuals integration, available on the Integration Builder tab in the Remedyforce communication plan.|
|Remedy Username||The username you used for the Remedyforce endpoint in xMatters.|
|xMatters Username||The username you created for your integration user, above.|
|xMatters Password||The password you created for your integration user.|
A semicolon-separated list of priority levels that determines which notifications are sent. For example, if you specify only priority level '1' on this list, only notifications of priority '1' are sent.
Note: For this feature to work, the specified priority must already be a part of the incident. Citing a priority here that does not appear in the incident has no effect.
A semicolon-separated list of statuses that determines which notifications are sent. For example, if you specify only the status "OPENED" on the list, only notifications set to "OPENED" are sent.
Note: For this feature to work, the specified status must already be a part of the incident. Citing a status here that does not appear in the incident has no effect.
|Enable Delivery Updates||Select if you want notification delivery updates to be added to the incident as notes.|
A list of available fields that you can select to include in the payload.
To include a field, select it in the list on the left and use the arrow buttons to move it to the right.
You can test the integration by sending a notification email from within Remedyforce.
To test the integration:
- On your Remedyforce homepage, from the application selector in the upper right corner, select the BMC Remedyforce application.
- On the Remedyforce Console tab, click New.
- On the New Incident page, enter the appropriate information.
- At the bottom of the page, under Assignment Details, enter the name of the queue (group) or staff (user) you want to assign the incident to. You can also click the Search icon to see a list of available groups and users.
- Click Save to commit the changes.
You can view the requested notification from xMatters in the Notes & Attachments section on the Record Details tab. If you don't see this section, you can add it to your Record Details.
- The "/apex/bmcservicedesk__ConsoleIncidentDetail" operation shows the incident being saved and should show the call to the xMattersTrigger code.
- The "FutureHandler" makes all the HTTP requests to xMatters.
If you don't see the Notes & Attachments section in your Record Details, you can add it.
To add the Notes & Attachments section:
- At the top-right, click Setup.
- In menus on the left, expand Build > Create and click Objects.
- Select Incident from the list of Custom Objects.
- In the Page Layouts section, click Edit next to Remedyforce Incident Console version 1.0.
- Select Related Lists, then drag and drop Notes & Attachments to where you want it to appear in your Record Details (for example, above the Action History section).
- Click Save.