Using Generic Devices in xMatters

This article provides an explanation of Generic Devices, and illustrates how to implement them by describing a sample Generic Device deployment that sends messages via a Twitter account.

Summary

The xMatters (alarmpoint) engine provides the Generic Device functionality as a way for customers to incorporate notification systems that do not use one of the established protocols already available within the xMatters system. You can use almost any notification system, provided it can be called via a command line interface.

For example, if you have an in-house messaging gateway that has been configured so that each user has their own identifier, you could configure a Generic Protocol Provider to call the executable with a set of passed parameters. Each xMatters User would configure their messaging contact information (such as an email address) as a Device in their User Details. xMatters would then pass parameters to the executable, and send notifications to the appropriate recipient.

You could also use a Generic Device engine to post a message to a central message board or forum under certain conditions. Users could then log in to the board and view the message.

As a demonstration of the Generic Device functionality, this article describes how to post xMatters messages via Twitter, a popular social networking utility. A third-party Windows command-line interface tool for Twitter acts as the executable.

Concepts and Scenario

Twitter is a web-based social networking system that allows users to post short (140-character maximum) "tweets", or text messages, to a centralized site. Twitter users can "follow" each other, which allows them to quickly locate and read each others' posts. These updates are usually typed directly into the Twitter site or sent from an SMS-enabled phone.

This example uses the following scenario: a Help Desk manager uses the xMatters (alarmpoint) engine to notify employees in the office and in the field of incoming help calls and trouble tickets.The manager wants to be able to post non-urgent or relatively trivial updates and messages to Twitter from within xMatters, rather than send notifications to User's Devices. The manager will post the messages to a central Help Desk account on Twitter, and the employees who also use the service can "follow" the Help Desk account to read the posts when they have time.

Although Twitter's limitations (such as the 140-character maximum) may make it unsuitable as an alerting mechanism, this example illustrates how to use Twitter as a simple way to disseminate purely informational notices or other minor updates. A section at the end of the article discusses some possible methods of extending the example to provide real-world utility.

Preparation

This example uses a third-party freeware application to post messages to Twitter from the Windows command line. (A Unix version is also available.) The application consists of two parts: an executable file that provides the functionality required to send messages, and a batch file that passes the appropriate information into the executable. Both files must be in the same directory and on the system path; this example has the files located in C:\Windows.

Before configuring xMatters, the Help Desk account that will be used to post messages must also be created on Twitter.

Implementation

To configure a Generic Device in xMatters, complete the following steps:

  1. Configure the Device Engine.
  2. Configure the Protocol Provider.
  3. Add a new Device Type.
  4. Configure the User Service Provider.
  5. Configure the User Device.

Configuring the Generic Device Engine

The first step in this example configuration is to set up the Device Engine.

  1. Log in to xMatters as a Super Administrator.
  2. On the Admin tab, in the Configuration menu, click Nodes and Device Engines.
  3. On the Nodes page, click the Device Engines link in the All Nodes table.
  4. On the Device Engines page, click the Add New link, and then select Generic Device Engine in the drop-down list, and click Continue.
  5. On the Generic Device Engine Details page, type a name and description for the Device Engine, and then click Save.

Configuring the Protocol Provider

The next step is to configure the Protocol Provider, which identifies the executable file that sends the message. This example uses a batch file, twitter.bat, which passes the Twitter account name, password, and message into another executable file. (Before configuring the xMatters component, the Twitter account name and password must be hard-coded into the .bat file.)

  1. On the Admin tab, in the Providers menu, click Protocol Providers.
  2. On the Protocol Providers page, click the Add New link.
  3. In the Provider of Type drop-down list, select Generic, and then click Continue.
  4. On the Generic Provider Details page, type a name and description into the fields.
  5. In the Executable Path field, type C:\Windows\twitter.bat
  6. Click the Add New Argument button.
  7. In the Argument field, type$message
    • This variable will be replaced by the content of the notification. For more information about the possible arguments you can use, see the "Generic Protocol Provider Details" table in the xMatters installation and administration guide.
  8. Click Save.

Adding a new Generic Device Type

Before you can add a Twitter Device to a User, you must add Twitter as a Device Type. (If you do not have merged accounts, log out of xMatters now, and log in again using a Company Administrator account.)

  1. On the Admin tab, in the Configuration menu, click Device Types.
  2. On the Device Types page, click the Modify link.
    • If you have already configured a Generic Device Type on your system, click the GENERIC link instead, and go to step 5.
  3. On the Active Device Types page, in the Available Device Types list, select GENERIC, click Add, and then click Save.
  4. On the Device Types page, click the GENERIC link.
  5. On the Add Device Names for GENERIC page, in the Name field, type Twitter, and then click Add.

Configuring the User Service Provider

Once you have added the Protocol Provider and Generic Device Type, you must add a User Service Provider that identifies the correct Protocol Provider for Generic Devices.

  1. On the Admin tab, in the Providers menu, click User Service Providers.
  2. On the User Service Providers page, click the Add New link.
  3. On the User Service Provider Details page, type a name and description for the new provider.
  4. In the Device Types drop-down list, select Generic Device, and then click Continue.
  5. In the Protocol Providers section, click Add New, and then add your Twitter Protocol Provider to the Selected Providers list.
  6. Click Save, and then click Save again.

Configuring the User Device

You can now add a User and assign them a Twitter Device.

  1. Click the Users tab.
  2. On the Users tab, click Add User.
  3. On the Add a User page, enter the details for the Twitter User and assign them the Role of "No Access User".
  4. Click Save, enter a Web Login Password for the User, and then click Save again.
  5. On the Details for User page, in the Common Tasks pane, click User Devices.
  6. Click the Add New link.
  7. On the Add New Device page, in the Select the Device Type drop-down list, select Generic Device, and then click Continue.
  8. On the My Generic Device Details page, in the Device Name drop-down list, select Twitter (if it is not already selected).
  9. Type any two- or three-digit number in the PIN field (this field is required by xMatters, but not used in this example).
  10. Click Save.

Send a Test Message

You can now send a test message to the User using the Messaging panel, and the account's status on Twitter will be updated within a few seconds.

Extending the functionality

While this example is not intended to be used in a production environment, there are some ways of extending the functionality that may make such short, one-way messages useful in xMatters.The following ideas are broad outlines of possible ways to improve Generic Twitter Devices:

  • In the above scenario, the account name and password are hard-coded in the .bat file; this means that all Twitter Devices added to Users will post messages to the same Twitter account. If you wanted each User's alerts to go to a separate account, you could add two Custom Fields for each User: Twitter User Name and Twitter Password. You could then use the xMatters scripting features to dynamically build the message content to include the necessary information, and bypass the .bat file. This method has a separate issue, as detailed in the following point.
  • One of the inherent difficulties in using Twitter as a Device is that any message sent to a User's Twitter account is posted on that account as though it was the User who entered it. This could be confusing to other readers, and makes the example scenario, where a manager posts messages to a central account, the most likely usage of Twitter with xMatters. It is possible, however, to extract the name of a User who sends a message using the Quick Messaging Panel or a Custom Messaging Panel, and have the scripts send a message to the sender's Twitter Device so that any messages or responses a User sends in xMatters are also posted to their Twitter account.
  • Most Twitter messages are publicly accessible - any Twitter user can read the updates. However, Twitter includes the ability to send private messages to "followers". If each User had a separate Twitter account and was a follower of the main xMatters account, you could use the main account to send private messages to each User. This would involve adding arguments to the Protocol Provider details to ensure that the message started with the prefix that indicates a private message.
  • Although they cannot be formatted, Twitter messages can also include hyperlinks to any URL. You could add scripting to insert a URL alias that would enable Twitter users to navigate directly to a ticket or other page on your web site.

Further Information

  • For more information about Device Engines, Protocol Providers, and User Service Providers, see the xMatters installation and administration guide.
  • For more information about scripting in xMatters, see the xMatters Online Developer's Guide.

xMatters Reference

JDN-1315 Originally created by Don Clark

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk