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 for the xMatters On-Demand integration with Roombot for ServiceNow.
Roombot is a full two way integration and gives users of the ServiceNow Collaboration tools the ability to:
- Invite all the users in a room to a conference bridge
- See the event status in real time
- Be informed of when each device was notified
- See user responses in the chat window
- Send ad hoc SMS messages
For a video of Roombot in action, check out this youtube link.
Out of the box, Roombot comes with several very useful commands:
- ENGAGEROOM <message> - Initiates a conference call to all the users in the room.
- SENDSMS "<user1,user2,user3>" <message> - Sends an SMS to the comma separated list of users. Note: user list must be in "s
- SENDEVENT "<user1,group1,group2>" <message> - Sends an event and targets the users or groups listed. Note user and group list must be in "s."
- 8BALL <question> - Consult the magic 8BALL
Before configuring anything in ServiceNow, you'll need to configure xMatters.
The first step in configuring xMatters is to create 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 have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or contact Client Assistance to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)
In the following example, this role is named "REST Web Service User".
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.
- Assign the user to the REST Web Service User role.
- Click Save.
- On the next page, set the web login ID and password.
Users and groups are targeted by name, so user names and group names in ServiceNow should match the user and group names in xMatters. The best way to do this would be to get the xMatters integration for ServiceNow, and leverage the data sync utilities to push and synchronize these entities in xMatters.
Alternatively, users and groups can be created manually in xMatters:
- To create a new group, see Create a New Group.
- To create a new user, see Add a New User.
- Multiple users and groups can be created using the EPIC feature.
The next step is to import the Roombot communication plan.
To import the Roombot communication plan:
- Download the attached Roombot.zip file.
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Browse, and then locate Roombot.zip file downloaded above.
- Click Import Plan.
- Once the communication plan has been imported, click Plan Disabled to enable the plan.
- In the Edit drop-down list, select Forms.
- For the Engage Room form, in the Not Deployed drop-down list, click Create Event Web Service.
- After you create the web service, the drop-down list label will change to Web Service Only.
- In the Web Service Only drop-down list, click Permissions.
- Enter the REST API user you created above, and then click Save Changes.
- Repeat steps 7-9 for the Send Event form.
To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.
- Note: The Access Web Service URL option may appear twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service.
Now that you've configured xMatters, it's time to configure Roombot.
This integration assumes the Collaboration plugin is enabled. To enable this plugin, click System Definition > Plugins > Collaboration > Activate/Upgrade.
Roombot is an app available on the ServiceNow store. The steps below detail how to download and install the app.
To install the app:
Navigate to the Roombot app on the ServiceNow app store. Click the BUY button and fill in any necessary details.
Then, navigate to the ServiceNow instance where Roombot should be installed, and navigate to System Applications > Applications.
In the Downloads section, click the blue Install button to begin the installation process.
Now that you've installed the package, it's time to configure Roombot on your system.
To configure Roombot:
The Roombot app contains a "roombot" user, so this section is only needed if a different user and profile are needed. Otherwise, skip to the "Configure Commands" section below.
First, create a new user with a username "roombot" and give it a password. Upload a robot looking photo. Searching google images for "bot icon" has some good examples, or you can use the one attached to the bottom of this article.
Then, click the impersonate icon and select the user just created. Impersonating the bot will generate the Social Profile (live_profile table) record that the Collaboration system uses in chats.
After successfully viewing the home page as the bot user, unimpersonate and navigate to the Social IT > Profiles table and search for the bot's profile:
Click to select the record and click the Additional Actions button and select copy sys_id. This will be needed in the configuration section.
Next, expand the Roombot menu and click Configuration. Populate the Profile sys_id and update any usernames and passwords needed.
|Property Name||Property Notes|
|Enable Roombot||When selected, enables the bot and evaluate commands.|
|Profile sys_id||Identifies the sys_id of Roombot's profile (live_profile table) record.|
|ServiceNow API User||Specifies the login name of the user in ServiceNow used to authenticate communications with the ServiceNow API. The username here should match the user in the profile record above.|
|ServiceNow API Password||Specifies the password of the ServiceNow API user.|
|Text Prefix||If specified, prevents Roombot's chat messages from triggering the commands. (This can help prevent infinite loops.)|
|xMatters REST API User||Specifies the user ID of the xMatters user used to authenticate communications with the xMatters REST API.|
|xMatters REST API Password||Specifies the password of the xMatters REST API user.|
The next step is to set the web service URLs for the individual commands. In the Roombot menu, click the Commands link to see the list of commands available.
Click ENGAGEROOM and enter the web service URL in the "endpoint" variable from the Engage Room form from the xMatters Communications Plan form. The SENDEVENT and SENDSMS both use the same web service url.
To test the integration:
Open a chat room with a user who exists in xMatters and invite at least one other user to the room. In the screen shot below, the users Travis and Alejandro have been invited.
Then send the ENGAGEROOM command with an optional message. Note that Roombot has responded that the event was successfully sent to xMatters and then adds event status, delivery status and responses to the conversation.
Also be sure to try out the SENDEVENT and SENDSMS commands.
If there is a failure sending the event to xMatters, Roombot will put a message to the chat window.
A ServiceNow administrator will need to check the system logs for details on why the event failed.
Additionally, company supervisors in xMatters can check the Reports > Web Service Audit report for failures.