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 technical details for the implementation of xMatters On-Demand for 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.
Updates and features
- During the "Assign to me" flow, the integration will now update 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 the Configure Remedyforce section, below).
To enable OAuth2 communication between Remedyforce and the xMatters Integration Builder, you must first configure xMatters as a connected app within Remedyforce.
- Select or create a Remedyforce user account for xMatters to use in OAuth2 connections to Remedyforce.
- In the Salesforce setup page, under the Build category, expand Create, and then click Apps.
- In the Connection 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, address, phone),Access and manage your data (api) and Perform requests on your behalf at any time (refresh_token, offline_access).
- 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 Manage Apps, click Connected Apps.
- Beside the xMatters app, click Edit.
- In IP Relaxation, select Relax IP Restrictions and click Save.
Before configuring anything in Remedyforce, you'll 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 the + Add icon.
- Enter the appropriate information for your new user. BEcause this user will affect how messags appear for recipients, you may want to identify the user as specific to Remedyforce; for example:
- First Name: Remedyforce
- Last Name: Integration
- User ID: remedyforce
When you assign a ticket to a user or queue in Remedyforce, the integration will send a notification to the corresponding user or group in xMatters. You will 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.
For more information about creating users and groups in xMatters, refer to the On-Demand Help.
The next step is to import the Remedyforce communication plan.
To import the Remedyforce communication plan:
- Download the attached .zip file to your system; you do not need to extract the contents.
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Browse, locate the downloaded file, and then click Import Plan.
- In the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user you created above, and then click Save Changes.
- In Edit drop-down list, select Forms.
- For the Notifications to Groups form, in the Web Service Only drop-down list, click Sender Permissions.
- Enter the integration user you configured above, and then click Save Changes.
- Repeat steps 6-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 will 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 xMatters endpoint, and update the settings to use the credentials for the REST API user you created above.
- Click the Remedyforce endpoint, and apply the following settings:
- If you are installing in a sandbox, the Access Token URL must be: https://test.salesforce.com/services/oauth2/token
- Authentication: OAuth2 (Salesforce)
- Grant Type: Password
- Access Token URL: https://login.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 obtained when configuring the connected app.
- Client Secret: Enter the Consumer Secret you obtained 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 get a web service URL for an integration service:
- On the Integration Builder tab, expand the list of inbound integrations.
- Click the name of the first inbound integration (Inbound for Groups).
- In the screen that appears, set step 4 - Select authentication method to OAuth.
- Click Update Inbound Integration.
- Repeat steps 3-4 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 package:
Note: If you are installing into a sandbox organization, you must replace the initial portion of the URL with:
- Review the Package Components screen for any potential conflicts.
- Review the package API Access screen.
- 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 may report that it will continue installing in the background, and notify you by email when it is finished.
- After installation is complete, click Done.
Now that you've installed the package, it's time to configure Remedyforce on your system. You'll need to create a Remedyforce user specific to xMatters, and then create a configuration record.
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 Remedyforce user for xMatters:
- 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:
- 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
- Role: Any available role; e.g., "IT Director".
To create a configuration record:
- In the Salesforce setup page, 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.
- In the xMatters application, on the xMatters Config tab, click New.
- In the blank configuration record, enter the appropriate information, and then click Save.
- The xMatters Config 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 (and it's 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.
The username you used for the Remedyforce endpoint in xMatters.
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' will be 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, will have 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" will be 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, will have no effect.
|Enable Delivery Updates||
Enable if you want notifications delivery updates to be added to incident as notes.
A list of fields from which you can select items to include in the payload.
Available fields appear on the left; selected fields appear on the right.
Select a field and use the arrow buttons to move it between lists.
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, click the Search icon.
- In the dialog box, select the Staff or Queue radio button to display available owners, and then click the desired link to fill in the value.
- Click Save to commit the changes.
- Click Record Details at the top of the form. Verify that the Notes & Attachments section shows that you've requested the notification from xMatters.
- 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.