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 installation, configuration, and implementation details when integrating xMatters On-Demand with HipChat Cloud or On-Premise.
This integration between xMatters and HipChat:
- Allows a user to invite an xMatters on-call resource to a HipChat room.
How it works
This integration installs an xMatters add-on into your HipChat account that automatically targets the xMatters connect application to pass information to the inbound integration.
Invite to room
Using the "+" button in a HipChat room, a user can launch a dialog to target an xMatters user or a group and invite them to the room to deliver some text.
The first step in setting up this integration is to configure xMatters.
Download the communication plan
To begin, download the communication plan attached to this article to a location on your local machine. You do not need to extract the contents.
This integration requires a REST API user to authenticate REST web service calls when injecting events.
This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to use the "REST Web Service User" role that includes the permissions and capabilities. (If this role does not exist in your deployment, contact your Client Success Manager to have it enabled.)
To create a REST API user:
- Log in to the target xMatters system.
- On the Users tab, click the Add New User icon.
- Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to HipChat; for example:
- First Name: HipChat
- Last Name: Integration
- User ID: hipchat
You can target users directly from an issue or supply a default group.using the EPIC feature.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Browse, and then locate the downloaded HipChatConnect-CommPlan.zip file.
- Click Import Plan.
- On the communication plan has been imported, in the Edit drop-down list, select Forms.
- In the Web UI and Web Service drop-down list, click Sender Permissions.
- Enter the REST API user you created above, and then click Save Changes.
The web service calls from HipChat are sent to inbound integration endpoints. These can be found by expanding the list of inbound integrations in the Integration Builder. Click the gear icon next to each integration, and then select Integration URL. Copy the URL displayed in the Integration URL dialog box.
When configuring HipChat, you will need the URL for the Invite to room inbound integration.
Install the add-On
You can now configure HipChat to integrate with xMatters.
To install the xMatters add-on in HipChat:
- Log in to HipChat as an administrator and navigate to the Integrations tab.
- Scroll to the bottom, find xMatters, then click Install.
- In the Install Integration dialog, select the room to install to, or select Global to make available to all rooms. Click Continue
- Review the actions xMatters will perform and click Approve.
Configure the add-on
On the xMatters Integration screen, select the Configure tab if it isn't already displayed. Enter the xMatters hostname and the username and password of the HipChat user created above. Click Test Authentication to verify the credentials are correct.
After successfully validating the credentials, a new text box appears for the Invite to Room URL. Paste in the Invite to room inbound integration URL and click Save Settings.
To test the Invite to room function, open HipChat and navigate to the room selected for the xMatters integration to be installed to. Click the "+" button next to the chat window and select xMatters Invite To Room.
The first time the integration is used in a room, the dialog asks for authorization to allow the integration into the room. Click Authorize xMatters Integration.
An admin screen to confirm account access to the xMatters Integration is displayed. Click Grant access to xMatters Integration.
After that, back in the room the xMatters Invite to Room dialog is displayed. Type in the xMatters Recipient box to do a lookup of the xMatters account and retrieve Groups or Users in real-time. Enter a description and click Send Invite.
On receiving the notification, click (or tap) Accept.
The response will be reflected in the HipChat room:
If the request successfully makes it to xMatters, then the Activity Stream for each of the inbound or outbound integrations is the best resource for troubleshooting.