Xm410 Installadmin Guide

xMatters installation and
(text here)
administration
guide
(version 4.1)
This manual provides information about xMatters. Every effort has been made to make it as complete and accurate as
possible; however, the information it contains is subject to change without notice and does not represent a commitment on
the part of xMatters, inc. No part of this document may be reproduced by any means without the prior written consent of
xMatters, inc.
Current to:
xMatters version 4.1.0 patch 023
xMatters integration agent version 4.1 patch 008
For more information about the latest changes, features, and fixes, and instructions on how to install
xMatters patches, consult the release notes at the xMatters Community site: community.xmatters.com.
Thursday, June 19, 2014
Copyright 1994-2014. All rights reserved.
xMatters, xMatters lite, xMatters workgroup, xMatters enterprise, xMatters on demand, xMatters service provider,
xMatters mobile access, Relevance Engine, AlarmPoint Systems, AlarmPoint, AlarmPoint Java Client,
AlarmPoint Mobile Gateway, AlarmPoint Integration Agent, AlarmPoint Express, AlarmPoint Standard,
AlarmPoint Professional, AlarmPoint Enterprise, AlarmPoint Service Provider, and AlarmPoint Notification
Server are trademarks of xMatters, inc.
All other products and brand names are trademarks of their respective companies.
Contacting xMatters, inc.:

You can visit the xMatters web site at: http://www.xmatters.com
xMatters, inc.
Corporate Headquarters
12647 Alcosta Blvd, Suite 425
San Ramon, CA 94583
Telephone: 925.226.0300
Facsimile: 925-226-0310
Client Assistance:
Email: support@xmatters.com
International: +1 925.226.0300 and press 2
US/CAN Toll Free: +1 877.XMATTRS (962.8877)
EMEA: +44 (0) 20 3427 6333
Australia/APJ Support: +61-2-8038-5048 opt 2
Other Resources:
Join the xMatters Community: http://community.xmatters.com
Table of Contents
Chapter 1: Introduction to xMatters
About this document
Important xMatters Terms
Document Conventions
Introduction to xMatters
The xMatters Critical Event Notification Platform
The Role of xMatters in Service Availability
xMatters Features
Real-World Application Examples
How the xMatters system works
xMatters Products
Managed Devices, Systems, or Applications
Communication with the Management System
Sending a Request to xMatters
Chapter 2: Installing xMatters

Installation Overview
xMatters Products, Licensing, and Deployment Options
Product Licensing
xMatters Deployment Options
Language Support
Component Installation Order
xMatters System Requirements
Hard Disk Space
Software Requirements
Hardware Requirements
Pre-Installation Configuration
Hardware
Software
Oracle Database Configuration Considerations
Microsoft SQL Server Database Configuration Considerations
IBM DB2 Database Configuration Considerations
Configuration Checklist
Network Port Defaults
Installing Dialogic Voice Cards and Drivers
Analog Dialogic Cards
Installing Dialogic T-1 and E-1 Cards
Configuring T-1/E-1 Dialogic Cards
Installing xMatters
Synchronizing System Time (Required)
Configuring NTPon Windows Server 2003
Configuring NTPon Red Hat Enterprise Linux
Suggested Post-Installation Tasks
Text-To-Speech Engines
Using Microsoft SAPI
Using NeoSpeech TTS with xMatters
Virtual Devices
Modifying the common.properties File
Tuning Node Performance
Starting and Stopping xMatters Components From a Command Line
xMatters Nodes
xMatters web server
Uninstalling xMatters
Windows Uninstall
Console Uninstall
1
2
2
3
3
4
4
5
8
10
11
15
16
17
19
20
20
20
21
22
23
24
24
25
30
32
32
33
35
39
42
44
45
50
50
55
58
63
83
83
85
85
86
87
87
89
91
92
92
92
93
93
93
94
|i
xMatters installation and administration guide
Chapter 3: System Configuration

About System Configuration
Login to xMatters
Companies
Define company details
Delete a company
Change company states
View and change company quotas
Create company login pages
Customize the login error message
Configure Single Sign On
Map tenant user logins
Licenses
Nodes
View and manage nodes
Tune your node's performance
Configure node logging
Device engines
Device Engine Types
Resources
Resource types
Clusters
Define cluster details
Protocol providers
Protocol Provider Details Reference
User service providers
Define user service providers
LDAP servers
Define LDAP server details
Create LDAP search filters
Global Configuration
Health monitor messages
Constants
Global Constants
Company Constants
Event Domain Constants
Available Constants
Schedule Jobs
Schedule a Process Expired Data job
Clear runtime and historical data
Configuration Process Examples
Configure xMatters SMS
Configure automatic SMS device deactivation
| ii
95
96
96
97
98
100
100
101
104
106
107
108
109
110
111
116
117
118
120
150
151
156
157
157
161
191
192
193
194
197
198
204
209
210
211
212
212
215
216
219
220
220
224
Chapter 4: Administrating xMatters
227
About system administration

Permissions: functions and roles
Manage functions
Roles
Permissions: locking external data
Administrators
Super administrators
Company administrators
Log in as another user
Sites
Countries
Time zones
Languages
Company holidays
228
228
228
231
236
238
238
239
241
242
244
245
246
247
Custom holidays
Site holidays
Example:Create company holidays
Custom user information
Custom attributes
Custom fields
Password policy
Device types
Manage device names
Specify a whitelist of email domains
Event domains
Import and export event domain information
Define event domain details
Define response contribution values
Define predicates
Subscriptions
Preparing Subscriptions
Configuring Subscription Domains
Managing Subscriptions
Searching for Subscriptions
Message domains
Define message domain details
Custom messaging panels
Define custom messaging panel details
Custom pages
Define custom page details
Import data
Format spreadsheets
Import your data
Phone recordings
Propagation Details
Add a recording
Modify system voice recordings
Manage phone recordings
Chapter 5: Reporting
About reporting
Access reports
Work with reports
Available reports
Activity reports
Event Details Reports
Replaying an Event
Company reports
Domain summary report
Synchronization report
Application audit report
Low-use user report
System reports
Component status report
Node network statistics report
Audit reports
Security audit report
Web service audit report
247
248
249
251
252
253
255
257
258
259
260
261
262
263
264
267
268
269
275
283
284
285
286
287
288
288
289
289
292
294
294
296
299
300
301
302
302
302
305
306
311
316
321
323
324
327
328
329
329
330
331
331
332
Chapter 6: Advanced xMatters Administration
335
Disaster Recovery Deployment Considerations

Overview
Deployment Installation and Configuration
336
336
337
| iii
Upgrading an xMatters DR Deployment

Disaster Recovery Procedures
Configuring xMatters nodes for Failover
Use Case Scenario
Failover in xMatters
Considerations
Database Components
Summary
Fronting the xMatters web server
Forwarding Requests from Apache HTTP Server
Forwarding Requests from Microsoft's IIS
High Bandwidth Configuration for a Heavily Loaded Web Server
Serving Static Content From a Fronted Web Server
Caching static content
Configuring the Database Connection Pool
Monitoring and Configuring Web Server Usage
Determining Web Server Usage
Modifying the Web Session Timeout
Modifying the Web Continuation Timeout
Enabling and Disabling AJP, HTTP, HTTPS & JMX
Enabling AJP on the xMatters web server
Disabling HTTP on the xMatters web server
Enabling HTTPS on the xMatters web server
Enabling JMX on the xMatters web server and nodes
Deploying xMatters on WebSphere
Enable cookie-based session management
Increasing security by marking cookies as secure
Advanced SMS administration
SMS Responder Validation
Configuring SMS HELP and STOP Responses
Internationalizing SMS messages for MMAcompliance
Chapter 7: Data Synchronization

Introduction
Installing the Data Synchronization Module
Data Synchronization Components
Staging Area
Standard Fields
List Fields
External Keys Assigned via the Web User Interface
Staging Table Content
The Configuration File
alarmpoint-synchronization Element
company Element
staging_area Element
Table Elements and Related Field Elements
Example Configuration
Data Synchronization Command
Command Line report
Synchronization Report (Web User Interface)
Logging
Multiple-Company Environments
Creating Company Staging Areas
Concurrent Company Data Synchronization
Troubleshooting Data Synchronization
Error Flags
Resolving Specific Errors
List of Tables
| iv
338
339
340
342
343
343
345
347
348
348
350
355
356
357
357
360
360
360
361
361
361
362
362
363
364
368
369
370
370
371
372
377
378
378
379
379
380
381
382
382
414
414
414
415
416
431
434
435
437
438
438
438
440
441
441
443
445
List of Figures
Index
453
459
|v
vi |
About this document

The xMatters installation and administration guide is intended to help xMatters administrators install, configure, and
maintain an xMatters installation.
This guide is part of a set of xMatters manuals. The other guides in the set are:
n
xMatters user guide: intended for end users, this guide explains the basics of the xMatters web user interface, and
how to accomplish common tasks. The User Guide also includes a section for User and Group Supervisors about
more advanced tasks, such as Group creation and management.
xMatters Online Developer's Guide: this guide is intended for developers and administrators, and contains
instructions on using the xMatters scripting tools, web services, custom panel APIs, and integration components.
xMatters AlarmPoint Java Client Guide: this guide explains how to configure and use the custom features of the
AlarmPoint Java Client.
xMatters integration agent guide: this guide describes and explains how to use the integration agent to facilitate
bi-directional communication between xMatters and one or more management systems.
xMatters mobile access guide: this guide introduces the mobile access component, an xMatters module that allows
xMatters Users to access management systems remotely, via any web-enabled Device, such as a BlackBerry
Smartphone.
xMatters administrators may also refer to some of the advanced features described in the xMatters user guide.
Important xMatters Terms

This manual uses the following terms to refer to specific components within xMatters.
Event
An event is any kind of message generated by an external source that enters xMatters and describes a situation that
requires a notification. Event is also used to refer to an incident or situation as it progresses through the system, from
injection to notification to resolution. Each event requires at least one alert.
Event can also be a generic term used to refer to an incident, change request, message, or other specific item within a
management system.
Management system
Management system is a catch-all term for any external source of events that sends information into xMatters. This could
be an automated network monitoring program, a sophisticated help desk suite, or even a simple system of manually
entered messages.
Alert
An alert (or notification) is any message sent by xMatters to a device, in order to inform a user of an event that requires
attention. The alert contains information about the event, such the time and location, and may ask users to respond,
acknowledging that they have received the notification.
Devices
A device in xMatters is any means of receiving a notification message. Devices can include physical items like phones,
or intangible items such as email accounts.
Users
In xMatters, people who can receive notifications are called users. Every person in the xMatters system is a user
defined by a set of details, including ID number, user name, login password, and so on.
About this document | 2
Groups
In xMatters, groups are used for collecting users and devices and organizing them into notification schedules. Full
definitions of groups and group components, including an example of group creation, are included in the xMatters user
guide.
Document Conventions
This manual uses the following styles and conventions when discussing xMatters and other software components.
Styles
Some instructions appear in the following format: MENU > OPTION; for example, File > Open means click the File
menu, and then click the Open menu option.
Words in bold typically reference text that appears on the screen. Words in monospace font represent the following:
n
text that must be typed into the computer
directory and file names
code samples
Directory paths
Except when deliberately referring to an operating system path for a specific component or feature, directory paths in this
document are listed in Unix format. Windows users must substitute the given paths with the Windows equivalents.
The xMatters installation folder is referred to throughout the documentation as <xMHOME>.
n
On Windows systems, the default is C:\Program Files (x86)\xMatters
On Unix systems, the default is /opt/xmatters
The xMatters integration agent installation folder is referred to throughout the documentation as <IAHOME>.
n
On Windows systems, the default is C:\xMatters\IntegrationAgent
On Unix systems, the default is /opt/xmatters/integrationagent
Directory Path Example

On a default Unix installation, the xMatters node configuration file is located in the /opt/xmatters/node/config
folder.
In the xMatters documentation, this path is shortened for ease of reference to <xMHOME>/node/config
Introduction to xMatters
xMatters is the leading Actionable Information Delivery platform which accelerates decision making, improves
operational effectiveness and increases IT service and application availability across the real-time enterprise.
xMatters transforms event data, instantly notifying the appropriate personnel with information relevant to their role. This
intelligent targeting reduces false alarms and enables mobile IT personnel to complete the resolution process more
accurately and efficiently. The xMatters approach delivers business service information further increasing IT service
visibility, reducing the cost of operations and transforming traditional organizations into proactive, real-time enterprises.
The xMatters platform is used in a variety of ways, including IT Service Delivery, IT Service Support, Business
Continuity, Disaster Recovery and Enterprise Messaging. Over 800 global firms, including 7 of the 10 largest Global
2000, rely on xMatters to ensure the availability of their mission critical and virtualized systems, networks, applications
and processes.
Introduction to xMatters | 3
This part of the guide introduces xMatters to IT managers, business continuity professionals, and others who require a
sophisticated critical event communication system. The following sections first discuss how xMatters meets important
business needs, and then describe xMatters products, components, and features.
Note:
To learn about xMatters features from an end user perspective, refer to the xMatters user guide.
The xMatters Critical Event Notification Platform

xMatters has consistently focused on critical event resolution, developing unrivaled domain expertise in every major
event resolution category, including:
n
Network monitoring
Application management
Business continuity
Employee safety
Data center job scheduling
Network security
Help desk management.
xMatters is an interactive alerting application, designed to capture and enrich important events, to route those events to
the right person on any communication device, and to give that person the ability to solve, escalate or enlist others to
resolve.
xMatters allows you to take critical business information and contact the right people via voice phone, SMS, two-way
pagers, instant message, and email.
Through integrations, the xMatters system can become the voice and interface of an automation engine or intelligent
application (the Management System, such as BMC Remedy or HP OpenView). When a Management System detects an
event that requires attention, xMatters places phone calls, sends pages, messages, or emails to the appropriate personnel,
vendors or customers.
The xMatters system is also persistent, escalating through multiple devices and personnel until someone accepts
responsibility or resolves the event. Once contacted, the xMatters system gives the notified person instant two-way
communication with the Management System. Responses are executed immediately on the Management System,
enabling remote resolution of the event.
The Role of xMatters in Service Availability

xMatters automates the event resolution cycle within leading service management organizations. Built on the premise
that events must be resolved as a prerequisite to Business Service Management, xMatters provides numerous benefits at
multiple levels of an organization.
Providing real information to IT Management:
n
Business Service Management: xMatters allows IT Management to sign up to receive relevant information
when services are about to be interrupted, SLAs are about to breach or events go unresolved. Stop viewing the
dashboard, xMatters will find you if something goes wrong!
Compliance: xMatters facilitates Sarbanes-Oxley (SOX) compliance by providing one enterprise-wide event
resolution system. xMatters provides the bridge between all events and the people who solve them: one system for
all event reporting and SOX Compliance.
Delivering on ITIL Processes:

n
Incident & Problem Management: xMatters automates the incident and problem management process by enabling
personnel to solve events before the service degrades.
Configuration Management:xMatters may use a Configuration Management Database (CMDB) as a trusted

source of event, personnel and asset information. Using this repository, personnel can subscribe to events that may
occur on any asset in the organization. When the event occurs xMatters locates, informs and enables resolution of
the event.
Capacity Management: xMatters plays an important role in the performance process by providing proactive
information to IT personnel when performance thresholds are met or about to be exceeded. Personnel can interact
and increase the available resources with the press of a button.
Change Management: xMatters automates the change process by allowing personnel to sign up to receive
authorization alerts (e.g., A change is pending your approval, press or say 1) to approve, 2) to decline, 3) to
reschedule, etc.). Additionally, customers can subscribe to alerts when a change is approved or declined on a
service that impacts their business area.
Service Level Management: xMatters uses service level mappings to proactively inform IT service users of
potential interruptions in managed services. Additionally, xMatters uses sophisticated event handling to escalate
events where the service is governed by an SLA and may be about to breach.
Service Support / Service Desk (Incident Control and Communication): xMatters automates personnel dispatch
and ticket assignment and provides real time feedback as the incident is in process. xMatters also provides
proactive information, outbound, to affected users in real time, avoiding costly inbound service calls.
Continuity Management:Reducing the risk of disaster, xMatters provides a module focused on the Continuity of
Operations. xMatters allows personnel to build, test and initiate scenarios that may affect an organizations ability
to recover in the face of a disaster. The crisis communications ability of xMatters ensures personnel that meet
specific criteria are dispatched and respond immediately.
xMatters Features
xMatters is a three-tier application that accepts system events from any number of management systems. Those events
may be network down alarms from a network management tool or alerts that a significant order has been placed.
xMatters is the event notification and interaction platform between a management system and an enterprises global
personnel. To ensure that when events occur the right people are found, xMatters was engineered to include the industryleading features summarized below.
Open Integration Technologies

xMatters provides XML integration options and Application Programming Interfaces (APIs) to help ease integration of
xMatters into your environment. For more information on how to use the Java Client integration application, see the
Java Client User Guide. For information on using the integration agent, refer to the xMatters integration agent guide.
Web Based Application User Interface

Administrators and other Users with the appropriate permissions can use the xMatters web user interface to access their
key tasks. This web-based interface allows enterprises to manage the xMatters system remotely and access a single,
centralized application for event notification. In xMatters workgroup, customized, self-service home pages allow Users
the ability to view and modify their details (e.g., Device details, passwords).
Event Assignment and Subscription

xMatters provides APIs to design custom applications for event assignment and event subscription. This powerful feature
allows users to subscribe to specific events. xMatters can be configured as a self-service application. For example, Bob
Smith in London can subscribe to Critical network failures in Munich. If the network fails in Munich, he is notified on
his preferred device.
Supervisors may assign events to an existing group of personnel. The possibilities of event assignment and self-service
event subscription move event management from the management system into xMatters. Additional features include
subscription grouping of similar events and the ability to publish business rules. These features combine to allow other
users to search published subscriptions and published grouped subscriptions then sign up for those alerts. For more
information, see "Managing Subscriptions" on page 275.
Event Messaging and Custom Applications

xMatters provides APIs to design custom applications for messaging applications and for building custom panels. These
powerful capabilities allow personnel to send user-generated messages. The custom application can send messages to a
group, a person, or to people who have subscribed to messages that meet specific criteria. For more information on
messaging, subscription and custom applications, see the xMatters user guide.
Communication Device Support

xMatters supports many devices to ensure personnel are located. xMatters is a standards-based application and uses voice
devices, voicemail, wired phones, mobile phones, SMS devices, RIM paging devices, one- and two-way pagers, email,
electronic signboards, and public announcement systems.
Telephone
xMatters can create custom voice messages within a notification script for an end-user over the phone. This allows
xMatters to phone a person with a recorded voice (or Text-to-Speech) message explaining the problem and available
options. Two-way, real-time communication allows the person to respond and take action on the management system by
pressing buttons on the telephone keypad (or speaking a command via speech recognition).
Often when a person receives a notification by SMS, pager or email they will need to make a phone call to correct the
problem, so the xMatters systems two-way real-time communication streamlines the notification process. xMatters
supports multiple voice lines from eight up to several hundred, which may be distributed across multiple xMatters
Notification Server Nodes.
Paging and Text Messaging
xMatters can create custom messages within a notification script for an end-users alpha pager, numeric pager, SMS
device, RIM paging device, or other text-messaging devices. This provides the ability to page a person, and send the
problem details within the page. Two-way paging and messaging allows the user to respond to the event and perform
actions on the management system by pressing a button on their device. xMatters supports numerous network protocols
for two-way messaging and paging as well as multiple modem connections for digital pages.
MAPI and SMTP Email
xMatters can send emails using any MAPI compliant server, or directly via SMTP/POP or SMTP/IMAP. This provides
the ability to send the problem and the event information to people for informational purposes. Two-way email is
supported, which allows the user to respond to an event and take action on the management system.
Instant Messaging
xMatters has the ability to send an Instant Message to a user, which pops up a message on their desktop. Current support
includes Jabber.
Bi-Directional Message Support

Interactive alerting with two-way devices means users receive an event as voice or text, with a choice of actions, and
then choose an action for the management system. The Java Client (which resides on the management system) will
execute the requested action on the management system in real-time. Examples of actions include:
l
Acknowledge receipt of a message on the console of the management system.
Ping a device from xMatters, and then get the results back to the user via phone, pager or email.
Open, close, or update trouble tickets in a problem management database.
Perform a command line action on the management system in response to a notification.
Granular Staff and Device Scheduling

The xMatters system allows users to build complex schedules at the device level. Those schedules may include or
exclude days, holidays, time ranges, multiple time ranges, device hunt order, retries per device, time between retries and
many other scheduling options. Each person can have several notification devices, each with time and date parameters.
Example of Multiple Notification Devices
The table below shows how Network Operations Manager Ted Davis wants to receive notifications on his devices. M-F
stands for Monday to Friday, and the hours are listed in 24-hour format.
Day and Time Schedules for Devices
Time
Notification
M-F 0700-1730
Send a message to his alpha pager.
M-F 2200-0200
Email message only.
All other times
Queue notifications to next open time window.
Complex Group Scheduling and Escalation Processes

xMatters can contact a specific person or a group of people. An xMatters Group is a list of people to be notified in
certain situations. xMatters can contact Group members sequentially or simultaneously. xMatters can also alter its
notification process to escalate a situation if it is unable to contact someone within a specified time frame.
In addition, xMatters Group scheduling is extremely flexible, able to reflect even the most complex schedule. Calendarbased Group scheduling includes person-to-person escalations, Groups-in-Groups, recurring and one-time schedules,
automated rotations and round-robin scheduling. A Group creation wizard makes schedules simple to build, view, and
change in a graphical format that quickly reveals any coverage gaps.
Customizable Calendaring Functions

Holidays and Timeframes
xMatters has the following ways to define when people should be notified:
l
Holidays. Different hours and people to contact for specific days (e.g., Boxing Day in Canada).
Timeframes. Timeframes can be used to alter granular day and time settings for Users, Devices, and Groups.
Time Zone Support

Each person has a Time Zone set directly or through association with a particular Site of a Company. Timeframes for
notification Devices can be entered based on locale, which is the actual time for the person being notified. xMatters
calculates the correct time to notify a person, even when running in a different Time Zone than the person being
notified. When date and time information is sent, it will be converted to recipients local time.
Distributed, Modular Architecture

xMatters enterprise is scalable, supporting and managing one or more xMatters Notification Servers in geographically
dispersed locations. This configuration also allows for failover support across the xMatters notification servers, in
addition to message routing based on the location of the servers.
User-Defined Notification Scripting

xMatters provides a sophisticated but easy-to-use scripting language called Action Script that you can use to define how
information is handled. Action Scripts allow you to enhance and refine the data presented on various communications
devices. Action Scripts also allow you to define custom response choices so that the person being notified can take an
action back on the management system (e.g., assigning a Help Desk ticket or acknowledging an event on an operations
console).
The Action Script editing utility (xMatters Developer IDE) provides a remote Java-based user interface for checking out
and modifying scripts in the xMatters database. Once a script is complete, version control allows marking the new script,
and then importing it to the xMatters system and promoting it to production.
xMatters includes several out-of-the-box example Action Scripts that can be used as a basis for creating new scripts. In
addition, all xMatters integration modules include custom scripts specific to that particular network management, system
management, or help desk system.
Reports
Authorized personnel can generate real-time and historical reports to monitor and troubleshoot the system. Reports show
the success or failure of every notification, and track delivery and response to the Device level. This web-based, real-time
feedback enables help desk users, operations personnel and business continuity professionals to view the success of each
message sent from xMatters.
Security and Encryption

xMatters allows administrators to control web user interface access through user permissions. Additionally, users can be
authenticated natively or from within the application through a third-party LDAP or Active Directory server. Sensitive
data (e.g., passwords) is stored with strong encryption.
Flexible Licensing
Each xMatters product includes a specific set of licenses that control terms such as number of Users, Devices, and
Notification Servers. However, as your organizations needs grow and change, additional customized licenses can be
purchased and easily activated through the xMatters web user interface. For more information about purchasing
additional licenses, contact xMatters Sales.
Real-World Application Examples

The following examples highlight the actual and potential use of xMatters at Global 1000 enterprises.
Note:
Note that these examples often refer to features available only in xMatters workgroup and xMatters enterprise.
For full information on xMatters products and features, contact xMatters Sales.
Data Center Automation

The automated notification and event resolution capabilities of xMatters allow IT to manage monitoring systems
including: HP OpenView, BMC Software, Aprisma, Computer Associates, IBM Tivoli, NetIQ, Micromuse, and others.
With xMatters, organizations can automate event handling to distribute the workload around the globe, around the
clock, or within the data center. xMatters collects events from these systems, enriches them, routes them, ensures
responsibility, provides an interface to the applications from remote devices, and generally provides policy-driven
resolution scenarios.
The following key functions can be easily implemented using xMatters:
n
Creating a real-time two-way telephone menu allowing personnel to take action over the phone.
Building menus on a two-way pager for handling action requests.
Contacting programmers when a critical batch job fails.
Notifying management personnel in the event of a crisis; displaying status and resolution instructions.
Informing end users that a critical system is down so that they can work around the outage.
Escalating notifications to an operations manager when a batch job is behind schedule by a specific duration.
Global Systems Management

Enterprises considering the global management of IT operations based on skill set must consider a solid, proven,
enterprise-class event resolution system such as xMatters. IT organizations moving to follow the sun management of
certain IT infrastructure components will be able to capture events in a location and based on preset criteria (location,
time, skill, priority, etc.) to route the message across xMatters and deliver it to the right person.
For example: an alert generated in New York from HP OpenView could be routed to Munich and delivered via voice in
German to someone working there. That worker can then interact with the application in the US over the phone and
execute sophisticated event-curing commands.
Help Desk Automation

Help Desk Operations are tied into the majority of critical events within IT operations. Peregrine, Remedy, HP, Clarify,
and others provide solutions for recording events, creating tickets and documenting their closure. Deploying event
resolution solutions in conjunction with a help desk application can result in large cost savings. Consider the following
real-life scenario without the use of xMatters:
Tivoli TEC detects a problem and the on-duty IT Operations staff attempts to dispatch an Application Engineer.
Meanwhile, users are calling into the Help Desk with service issues. The Help Desk personnel use a manual
dispatch process to locate an on-duty technician.
Consider the time and resource savings with xMatters: the event is automatically dispatched to the correct person with
command options to take action on the primary application, accept responsibility and update the ticket, send out
proactive service information to users, escalate to additional personnel, and so on.
Security Management
Leading Security Administrators are just starting to discover the benefits of automated event resolution for their
environments. Security is a perfect application for event resolution systems because there are a limited number of
specialists within the company and time-to-resolution is critically important.
Consider the importance to preventing an intrusion into your network.
xMatters allows key personnel to receive critical event information to any device (voice is suggested for security,
interactivity, and guaranteed delivery considerations); the recipient can suspend a policy, run a test, ping a device, shut
down a block of IP addresses, notify on-site personnel and other concerned personnel. The event resolution systems
should support voice over telephones and should have pre-built support for the leading security vendors.
Mobile Worker Management and Device Management

A new challenge facing enterprises is managing the contact details, profiles, device types, access, and supported mobile
devices of a mobile work force. xMatters alleviates a large portion of the challenges by allowing self-registration of
devices, schedules, profiles, rotations, device escalations and other concerns.
Additionally, xMatters supports current and evolving protocols including MAPI, SMTP, TAP, UCP, SNPP, WCTP,
HTTP, Voice, RIM and Text to SMS devices. xMatters automatically formats the information for the device type based
on the standard or the provider, which alleviates a large burden on system administrators of Workforce Management
applications.
Business Continuity
Post 9/11 concerns in the United States and worldwide have refocused attention on business continuity, employee safety,
backup and restoration procedures, and other data security initiatives. xMatters provides a central portal for emergency
communications to a large number of employees on Disaster Response teams.
Customer Facing Solution

xMatters can be deployed as customer-facing solution. IT customers can log on and subscribe to events including SLA
and business interruption. When events occur that meet their requests they are contacted via the device of their choice.
xMatters can take a single event like node down and send different events to different stakeholders:
n
Darren, On-Call Technician Node down what would you like to do?
Trent, Manager The network is experiencing delays; Darren is working on it.
Keith, Help Desk Node 123 is down, Darren is assigned, estimated fix in 20 minutes.
End Users Network has delays; we anticipate normal service in 30 minutes.
How the xMatters system works

The xMatters system can be thought of as a management system employee trained to notify people when problems arise.
The management system can inform the xMatters system about situations in an organization that will trigger
notifications to people based on steps pre-defined in scripts.
The following table summarizes the key components of an xMatters deployment:
xMatters Components
Component Notes
xMatters
The application server (node) is the central xMatters component, running the business processes (i.e.,
application Action Scripts) that instruct other components in the system. The application server also includes an
server
integrated notification server that performs the same tasks as a separate notification server node.
(Node)
Whether your deployment requires an integrated notification server or separate notification server(s) will
depend on many factors, including licensing and expected throughput. Discuss these issues with your
xMatters representative prior to deployment.
notification An xMatters deployment can have one or many notification servers that communicate with the
server
application server and database to queue, route, and send notifications and their responses.
(Node)
Note that an all-in-one deployment does not have a separate notification server node. Also, an xMatters
workgroup all-in-one deployment on Windows does not require a separate notification server node.
Device
Engines
A sub-component of notification servers, Device Engines send notifications to various Devices (Phones,
Pagers, Email, etc.). A notification server may have several Device Engines; for example, a notification
server can have an Email and a Paging Engine. Note that due to thread availability, it is strongly
recommended that a notification server does not have more than one Device Engine of the same type.
xMatters
database
The xMatters database is the central storehouse of User, Device, Group, logging and auditing information
for the xMatters system.
Java
Client
The Java Client acts as a two-way bridge, translator, filter, and message enhancer between the external
management system (BMC Remedy, HP OpenView, etc.) and xMatters. The Java Client formats messages
into xMatters XML messages before being transmitted to xMatters.
xMatters dynamically selects and runs the script called an Action Script appropriate for an incoming event. Scripts
can contact one person, a group, or even a specific communication device. Some scripts establish contact with people or
services, while others provide a choice of actions specific to the situation. xMatters constantly updates the management
system on what is happening, including replies from real-time two-way telephones, messaging devices, two-way pagers,
or email.
An application called the Java Client is installed on the management system, allowing the management system to
communicate with xMatters. The Java Client is like a bridge, translator, and message enhancer between the management
How the xMatters system works | 10
system and xMatters. If the management system wants to start or stop a situation, it uses the Java Clientto send a
message. To respond, xMatters returns a message to the Java Client, which can log the information, run a command on
the management system, and so on.
The Java Client, running on the management system sends messages to xMatters on behalf of the management system.
xMatters splits the notification process into several basic components, which allows the administrator to reuse several
scripts, making Action Scripting more like piecing modules together than programming.
Note:
For details on Action Scripting, refer to the xMatters Online Developer's Guide .
The main processing component in xMatters is called an application server. The application server communicates with
one or many xMatters notification servers to manage sending and receiving of notifications. notification servers contain
Device Engines (e.g., Email Engine, Paging Engine). The application server and notification server use a node structure
easily deployed using the same installer.
The sections that follow describe xMatters components, and provide diagrams of example xMatters deployments for each
product version.
xMatters Products
Because xMatters product licensing is very flexible, different deployments of xMatters may not have the same feature set.
For a complete matrix of available features and related products, contact xMatters Sales.
The following sections provide a brief description of some sample deployments, and diagrams illustrating the different
components.
Basic xMatters deployments

xMatters can be designed and deployed for smaller groups that do not require voice or distributed load capability
(xMatters can be installed on a single computer). Even a basic deployment is a great way to get started with the xMatters
product family and includes many sophisticated notification options and a web user interface for the system
administrator. The following diagram shows a basic implementation:
Basic Deployment
xMatters workgroup
xMatters workgroup is a mid-level product intended for mid- to large-size ESM (Enterprise Service Management)
implementations that require voice capability, a rich feature set, greater flexibility, and user self-service (for full feature
details, contact xMatters Sales).
The following diagram shows an example xMatters workgroup deployment:
xMatters workgroup Example Deployment
The example deployment shows xMatters workgroup connected to the Management System through the integration
agent. In this case, two xMatters application server Nodes (a Primary and a separately-licensed Secondary) stay in
constant contact via the xMatters database to synchronize information and detect whether the any components have
failed. If the Primary Application Server fails, the Secondary Application Server detects this and takes over notification
tasks.
In this failover example, the database must be run on a separate system. If the xMatters application servers are installed
on Unix, the Voice Engines must run on additional Windows 2003 systems.
xMatters enterprise
xMatters enterprise is intended for sophisticated ESM implementations that require full voice and text capability, an
industry-leading feature set, unrivalled permissioning and scheduling flexibility, user self-service, customizable event
subscriptions, customizable messaging panels, highly-distributed load capability, and a potentially global deployment.
The following diagram shows an example xMatters enterprise deployment:
xMatters enterprise Example Deployment
This sample deployment shows how xMatters enterprise is scalable in a distributed implementation. Multiple
Notification Servers have been deployed to target specific Devices. Moreover, if a Notification Server or related Device
Engine fails, its load is automatically distributed to another Notification Server or Device Engine.
The xMatters enterprise architecture allows for global distribution of system components, providing additional failover
capability and local notifications.
Multiple-Company Deployments
With the xMatters service provider product, or an xMatters enterprise installation with additional Company licenses,
xMatters can be configured to support multiple Companies. This configuration allows a single xMatters installation to
host many distinct Companies, each with a unique feature set.
A multiple-Company deployment offers the following key features:
n
Single infrastructure
Unique company presence within the infrastructure:

l
corporate branding on login screens
Company-specific reporting
customizable business workflow
unique Users, Groups, Devices, and contact methods
unique password rules, Roles, and LDAP settings
uniquely-provisioned web services
data loading ability (Data Import and Data Synchronization)
minimum Reserved SIP telephony allocations for each Company
Unique company states to enable distinct company state management
Strict data segregation; Users in one Company cannot view any data about other Companies
Simple upgrade path for existing xMatters single-Company deployments
Streamlined administration with Super Administrators providing global host administration and Company
Administrators restricted to administrating a single Company or tenant in a multi-Company deployment.
This multiple company ability is particularly useful for Service Providers that will host xMatters on behalf of a number
of their own customers (i.e., the host service provider will have its own employees act as Company Administrators for
all tenant Companies).
Other uses include existing customers (e.g., Internal IT service management) who want to extend the existing offering to
include their external customers (e.g., external Public users), and want to ensure that all data visibility, event processing
and notification behavior is strictly segregated. (Note that this solution is not appropriate when sets of Users in different
Companies must interact with each other.)
Since the multiple-Company configuration is part of the existing xMatters infrastructure, all the scalability, resilience,
and load-sharing capabilities of xMatters are available.
Managed Devices, Systems, or Applications

The Managed Devices, Systems, or Applications are not part of the xMatters System. They are components maintained
by the Management System. These components initiate the events that are passed to the Management System.
Management System
The Management System is not part of the xMatters System. It is the automation engine or intelligent application that
manages other devices, systems or applications. Those other components initiate the events that are passed to the
Management System.
Event components
These definitions are used throughout this document.
Event
A message sent from the Management System to an integration agent (or Java Client) is termed an Event. The Event
represents the starting point and the highest level of internal tracking in xMatters.
Incidents
An Incident represents the larger business representation and/or grouping of Events as supplied by the Management
System. The Management Systems could share an Incident identifier to span multiple events. The association of events
to an <incident_id> element allows for the management of multiple Events at the same time.
Alert
An Event received by xMatters creates at least one Alert. An Alert is a pre-formatted Event for personnel subscribed
against the matched criteria. An Alert is the association of an Event to specific users/groups.
Notification
Alerts will create at least one Notification. A Notification is the association of a specific Alert to a Persons devices.
For each active device that matches the time profile of an event, a Notification record will be created.
xMatters notification server engines
Within the xMatters notification servers, each Server (one per Engine) runs the appropriate Contact and Action Scripts
with the Event information, which results in a message delivered to a person. The information is forwarded to the Engine
that allocates specific resources for delivery. Resources per engine and possible message delivery mechanisms are
detailed in the following sections.
Phone Engine
Uses Dialogic Voice Cards or SIP for telephony, or Virtual Phone for testing.
Paging Engine
Uses a modem for modem-based paging services, the network and HTTP for Internet-enabled paging services and/or the
xMatters internal Virtual Pager for testing.
Email Engine
Inserts a message into the outbox of a MAPI-compliant server, or to an SMTP server. If a MAPI-compliant server is used,
it will be told to send all outgoing mail. This engine can also use Virtual Email for testing. Reply messages can be read
from a MAPI inbox, POP server, or IMAP server.
Messaging Engine
Sent to the appropriate Instant Messaging (IM) server for delivery to the persons IM client.
Communication with the Management System

xMatters typically communicates with the Management System across an Ethernet network. This allows xMatters to run
at any location accessible from the local or wide area network.
The Java Client has two main applications for handling communications between xMatters and Management Systems.
The first is the xMatters Agent, which maintains a persistent connection with xMatters. The second is the xMatters
Client, used by simple Management Systems integrations to put events into the xMatters system, and retrieve responses
to the generated alerts.
The Management System can monitor network devices, network security, mission-critical applications, or any other
system. When it has an event that requires personnel notification, it can use the xMatters Client with parameters about
the event. The xMatters Agent then sends a message to xMatters to start the notification process.
The xMatters Agent sends notification requests to xMatters, and receives messages from it. The messages can contain
information regarding the status or progress of individual notification requests, reports of acknowledgements by notified
users, or requests from notified users to perform actions on the Management System.
Sending a Request to xMatters

The Java Client can be used to submit many types of messages to xMatters enterprise. For example, requests to start a
notification process, or cancel a prior request. The Java Client has three types of integration methods:
n
Command Line
HTTP
Remote Method Invocation (RMI)
The following sections summarize these methods, and the comparative time required for each.
Command-line
While the command-line method produces the loosest integration, it is also the fastest to implement. This method is
sometimes used because it reduces maintenance requirements when new releases of xMatters are implemented.
To use this method, the Management System must be able to:
n
Launch a command-line when an event occurs; and,
Pass arguments to the command-line program regarding the event.
HTTP
The HTTP integration method is more difficult than command-line, and requires programming. The APJC accepts an
HTTP post and get to send XML messages with all relevant data. A program must be written to post the messages
that start notifications, and to create a process that continuously checks the APJC response queue for actions that people
may want to take through xMatters.
Remote Method Invocation (RMI)
The RMI method represents the tightest level of integration, and requires Java programming. This method provides
callbacks that automatically allow reliable two-way interaction with the APJC. Messages are sent in an XML format.
Time Requirements
In general, command-line integrations can take from several hours to several days, and are relatively simple to
implement. HTTP or RMI integrations usually require at least a week or longer, depending on how the program is
written.
The rest of this chapter covers the use of the command-line integration option.
Application Specific Integration Modules

The Java Client is a quick solution for custom integrations. However, the xMatters system includes a number of prebuilt, Management System integrations. These are available from xMatters, or an authorized xMatters Partner (BMC, HP,
NetIQ, Peregrine, Remedy, and others). The integrations include the Java Client and custom Action Scripts and
recordings for the xMatters Notification Servers. Once installed, the integrations can be further customized for tighter
integration with the Management System.
18 |
Installation Overview
Before installing xMatters system components, it is strongly recommended that you review this entire chapter to help
ensure a successful xMatters deployment.
In general, it is recommended that at least one of each of the following personnel are available to address any issues
during the installation and configuration process:
n
Network administrator
Management System specialist
xMatters administrators (Super Administrator and Company Administrators)
Database administrator (e.g., Oracle DBA)
Unix technical personnel (for Unix installations only)
Note:
This guide is current to xMatters version 4.1 patch 022. Note that xMatters patches and updates are
cumulative; for more information about the changes in this release and previous updates, refer to to the 4.1
patch 022 release notes on the xMatters Community site at community.xmatters.com.
xMatters Products, Licensing, and Deployment Options

xMatters has created several xMatters applications to meet varying client needs. In addition, xMatters deployments are
highly flexible and scalable as requirements change. The following sections describe xMatters products and typical
deployments.
Product Licensing
Product licenses control xMatters versioning, capabilities, and features, including the following items:
n
Number of:
o
Nodes
Device engine connections (threads)
Companies
Groups
Users
Roles
Java Client or integration agent connections
Enhanced messaging (Scenarios)
Subscriptions
Advanced Reporting
Alerts tab
Languages
Failover
By default, only the xMatters super administrator has permissions for managing product licensing (for details, see
"Licenses" on page 109).
Installation Overview | 20
Note:
All Users in the xMatters database count towards the license limit. This means that Users not set as Active (i.e.,
on their User Details page) are still counted for licensing purposes. For further details on xMatters licensing,
contact xMatters Sales.
xMatters Deployment Options

xMatters installations are very flexible and will vary with an organizations needs. Depending on Device Engines,
throughput, salability, and other requirements, a system can be deployed on a single computer or distributed across
several local or remote computers.
Because xMatters licensing is managed through the web user interface, a single installer handles all installation tasks for
all xMatters components except the Java Client. For example, the same xMatters installer executable that installs an
Application Server in New York can be used to install Notification Servers in London and Tokyo and a web server in
Los Angeles.
Note:
The Java Client has its own installer. For details, refer to the xMatters AlarmPoint Java Client Guide.
xMatters enterprise Deployment Guidelines

Before deploying xMatters enterprise, note the following important guidelines:
n
Ensure that xMatters components (including the database server) are not co-hosted with each other (see also "Allin-One Deployment" on page 30).
Ensure that xMatters components are not co-hosted with third-party enterprise applications.
Ensure that all xMatters components are redundant (see "Failover in xMatters" on page 343).
Be aware that Microsoft SQL Server Express is not supported for use with xMatters enterprise
Configure SIP Device Engines on dedicated xMatters notification server Node computers (i.e., the xMatters
notification server Node must reside on a computer that is separate from other xMatters components such as web
servers, application servers, and the database). Note that a maximum of 100 "Number of Line Appearances" is the
tested limit for SIP Device Engines. (See also "Software Requirements" on page 25.)
Note:
xMatters does not support phone extensions on SIP.
Increase the database connection pool settings for all xMatters components (for details, see "Configuring the
Database Connection Pool" on page 357).
Optionally, use database replication for cold disaster recovery (see also "Disaster Recovery Deployment
Considerations" on page 336).
Front web servers with Apache or Microsoft IIS (for details, see "Fronting the xMatters web server" on page 348).
Use a load balancer to route traffic if multiple web servers are deployed.
Ensure that all xMatters nodes (Application Servers and Notification Servers) can intercommunicate.
Set the minimum JVMheap size to the same value as the maximum heap size to eliminate the cost of allocating
memory to the JVM (for details, see "Configuring xMatters Heap Size" on page 359).
Ensure that latency between the xMatters web server, Application Server and Database is lower than 30ms (see
also table entry for "Failover Connectivity" on page 33). xMatters requires a robust network infrastructure with no
measurable communication loss between components. If the network layer is unreliable or has high latency,
product performance and behavior will be impacted. Operating xMatters in such conditions is not a configuration
supported by xMatters.
Note:
It is strongly recommended that you discuss your xMatters enterprise deployment plan with your xMatters
representative prior to installation.
xMatters Products, Licensing, and Deployment Options | 21
Virtual Machine Deployment Guidelines

Before deploying xMatters in a virtualized environment, note the following guidelines and best practices:
n
Add 10-15% to CPU requirements to compensate for virtualization losses.
Use a virtual server with multiple processors and CPU cores.
Allocate two or more virtual CPUs to make use of multi-threading capability.
Pre-allocate or dedicate virtual CPUs and the maximum required memory to the xMatters Virtual Machine to
reduce contention between virtual machines and scheduling losses.
Do not over-commit virtual CPUs or memory on the virtual server.
Pre-allocate disk space for the xMatters Virtual Machine.
Disable screen savers and window animations.
Disable X Window Server if not required.
Disconnect unused devices on the virtual machine and Virtual Server, including:
l
COM ports
LPT ports
Floppy drives
CD-ROM drives
USB adapters
Schedule backups and anti-virus scans to run during off-peak periods.
Use separate network adapters for xMatters Virtual Machine communications and virtual server storage (i.e.,
Network Attached Storage).
Ensure the HAL/kernel installed on the xMatters Virtual Machine operating system is appropriate for the system
(i.e., uni-processor versus multi-processor).
Ensure specialized virtual server/machine drivers are installed on the xMatters Virtual Machine operating system
(i.e., virtualized network drivers).
Virtual machines with a close affinity should be co-located on the same virtual server to reduce communication
latencies. However, this must be balanced against resource contention. For example, virtual machines that demand
high levels of I/O should be located on separate virtual servers.
Distribute virtual machines over multiple disk spindles to reduce virtual machine I/O contention and request
queuing. If possible, place the virtual machines with highest disk I/O demands on separate disk spindles; if this is
not possible, use separate virtual servers.
Note:
Dialogic cards are not supported when using virtualization. Due to resource-contention that can affect call
quality and performance, xMatters SIP is not supported for virtualized environments.
Language Support
The following table summarizes xMatters language support:
Language Support
Component
Supported Languages
Web User Interface
English, French, German, Spanish, Italian, Brazilian Portuguese, Russian, Japanese, Korean,
Chinese
Language Support | 22
Component
Supported Languages
Pre-recorded
Languages
As above, with UK and US for English, and Mandarin and Cantonese for Chinese
Integration Modules
Integration modules are created only with pre-recorded US English
TTS (Text-To-Speech)
xMatters can support any SAPI 5.1-compliant TTS engine in any language. Additionally, the
xMatters Action Script allows you to control the language spoken based on the selected
language of each User; for details, refer to the xMatters Online Developer's Guide.
Note that the list of available languages is hard-coded in the voice recordings script. If you
change the languages available to a Company, you must also change the script listing the
available languages.
A voice-capable xMatters installation includes the Microsoft Text-To-Speech (TTS) SAPI5.1
engine with the following available English-only voices:
o
o
o
Microsoft Mary
Microsoft Mike
Microsoft Sam
For further details, see "Text-To-Speech Engines" on page 86.

xMatters recommends the NeoSpeech TTS engine, which can be purchased directly from
xMatters. By default, xMatters supplies the English-only Kate TTS voice (other voices are
available from NeoSpeech). For further details, see "Using NeoSpeech TTS with xMatters" on
page 87.
Database
When installed as recommended by xMatters, Oracle and IBM DB2 can concurrently support
all xMatters-supported languages. Microsoft SQL Server can concurrently support only a
subset of xMatters-supported languages. For configuration information, see the related
"Support for International Character Sets" sections for each database under "Pre-Installation
Configuration" on page 32.
Component Installation Order

The components of an xMatters deployment should be installed in the order listed in the following table:
xMatters Components Installation Order
Component
Notes
Dialogic voice cards and

drivers
If your deployment will include voice capability, Dialogic cards and drivers should
always be installed before Notification Server Nodes are installed and configured on
computers dedicated to Voice notifications. For details, see "Installing Dialogic
Voice Cards and Drivers" on page 50.
Note that Windows 64-bit installations are not supported by Dialogic.
Component Installation Order | 23
Component
Notes
Database
The xMatters application install requires you to enter parameters related to the
database installation. For installation details, refer to your database documentation.
n
For Oracle installations, review "Oracle Database Configuration

Considerations" on page 35.
For Microsoft SQL Server installations, review "Microsoft SQL Server
Database Configuration Considerations " on page 39.
xMatters application
The xMatters application install includes the xMatters database components, web
server, Application Server Node(s), and Notification Server Node(s). Depending on
your requirements and licensing, this installation can be on a single computer or
distributed across multiple computers (and different physical locations).
Java Client
The procedure for installing the Java Client on your Management System depends
on its type and the customization required. For information on the Java Client,
including installation, see the Java Client User Guide. If a customized integration
was provided, refer to the related documentation that accompanied the integration
package.
integration agent
The procedure for installing the integration agent on your Management System
depends on its type and the customization required. For information on the
integration agent, including installation, see the xMatters integration agent guide. If
a customized integration was provided, refer to the related documentation that
accompanied the integration package. Note that each version of xMatters must be
paired with its own version of the integration agent (e.g., xMatters 5.0 uses
integration agent 5.0.
xMatters System Requirements

Before installing xMatters, review the following sections to ensure that your software and hardware meet the system
requirements.
Note:
These requirements apply only to xMatters lite and xMatters workgroup. xMatters enterprise system
requirements should be determined with the assistance of xMatters Systems Sales and Professional Services.
Hard Disk Space

The following table summarizes xMatters installation hard disk space requirements (based on a default installation, with
some allowance for runtime operation):
Installation Hard Disk Space Requirements
Component
Disk Space Required
xMatters web server only
3 GB
xMatters node only
2 GB
xMatters System Requirements | 24
Component
Disk Space Required
xMatters web server and Node (i.e., All-in-One deployment)
5 GB
Software Requirements
This section details the software requirements for an xMatters deployment.
Supported Operating Systems

xMatters supports the operating systems detailed in the following table:
Supported Operating Systems for xMatters
Platform
Manufacturer
Operating System
Version
x86
Various
Windows
2003 Server SP2

2008 Server
LINUX
Red Hat Enterprise Linux 5.x

CentOS 5.x
SUSE Linux Enterprise Server 10.0 SP2
AMD, Intel
64-bit
Windows
2003 Server 64-bit SP2

2008 Server R2 64-bit (see "Windows 2008 deployment
considerations" on page 29)
LINUX
(64-bit versions
running 32-bit Java)
Red Hat Enterprise Linux 5.x and 6.4

CentOS 5.x
SUSE Linux Enterprise Server 10.0 SP2
Sparc
Sun
Solaris
10
PA-RISC
HP
HPUX
11.23
Itanium
(Integrity)
HP
HPUX
11.23, 11.31
POWER
Processor
IBM
AIX
5.3 (i.e., 5300-07), 6.1 (6100-GOLD) (traditional and IBM

LPAR environments)
Note:
xMatters currently supports the Dialogic 6.0 driver release running on Windows 2003 (32-bit only) and
Windows 2008 R2.
64-bit JVM Compatibility

If your deployment of xMatters will experience high load volumes, it is recommended that you use a 64-bit operating
system and JVM. The following table summarizes xMatters 64-bit JVM compatibility:
64-bit JVM Support
Platform
Manufacturer Operating System
Notes
AMD64
Various
Windows 2003
Runs only 32-bit JVM provided by xMatters installer
Various
RedHat Ent 5.2
Runs 64-bit JVM provided by xMatters installer
SUSE
Intel64
AMD64
Intel64
Sparc
Sun
Solaris
Not supported
PA-RISC
HP
HPUX
Not supported
Itanium
HP
HPUX 11.23, 11.31
POWER
Processor
IBM
AIX 5.3, 6.1
Requires manual JVM configuration for 64-bit (contact xMatters

systems for a Knowledge Base Article describing manual setup)
Virtualization Compatibility
xMatters has been successfully installed and run on several virtualization technologies (including Xen, VMWare,
RedHat, and others). Because the application does not check or otherwise attempt to determine whether it is being run
on a virtual machine, xMatters does not endorse any specific technology, brand, or version.
Due the nature of virtualization technology, the demands of other virtual machines running on the same physical hosts
as xMatters may impact xMatters components, and vice versa. In extreme cases, performance may degrade or become
erratic. Accordingly, careful monitoring and capacity planning are essential to avoid these situations; you must ensure
that sufficient resources are dedicated and available to the application. Your feature set may also be limited by the
virtualization layer if it cannot provide appropriate access to hardware resources, such as modems.
Also note that diagnosing and resolving virtualization issues are beyond the scope of xMatters Technical Support, and
are not covered by your support agreement. For help planning virtual installations, contact your virtualization vendor,
and refer to "Virtual Machine Deployment Guidelines" on page 22.
The following table summarizes current virtualization compatibility; note the following definitions:
n
Certified means that xMatters has tested the technology internally with complete functional/regression testing at
each release.
Validated means the technology has been implemented internally or in a customer environment with a baseline of
"known good state".
xMatters Components refers to the web server, application servers, and notification servers;
Operating System
xMatters Components
Java Client
Windows 2003 Server on VMWare ESX
Certified
Certified
Windows 2003 Server x64 on VMWare ESX
Validated
Validated
Windows 2008 R2 x64 on VMWare ESX
Validated
Validated
Linux RH 5.1 on VMWare ESX
Validated
Validated
Linux RH 5.1 x64 on VMWare ESX
Validated
Validated
AIX 5.3 on IBM LPAR
Validated
Validated
Note:
Dialogic cards are not supported when using virtualization. Due to resource-contention that can affect call
quality and performance, xMatters SIP is not supported for virtualized environments.
Databases
xMatters supports the databases detailed in the following table:
Supported Databases
Database
Versions
Oracle
11g Release 2 Enterprise
Microsoft SQL Server Server 2008 (Enterprise or Standard), Express 2008

Note that SQLServer Express has a maximum size of 4GB per database, and is not supported
for use with xMatters enterprise
IBM DB2
9.5 (Linux, Unix, Windows)
Web Servers
The following web servers can be used as a proxy for xMatters:
Web Server Proxy
Web Server
Version
Apache
2.2.2 & 2.2.3-31
Microsoft IIS (Internet Information Services)
6.0
Note:
On xMatters enterprise deployments, web servers must be fronted with Apache or Microsoft IIS (for details, see
"Fronting the xMatters web server" on page 348).
Web Browsers
xMatters supports Microsoft Internet Explorer 8 and Mozilla Firefox 3.
xMatters can be used with Internet Explorer 8 running in compatibility mode. To use this mode, navigate to
Tools > Compatibility View Settings and add the URL for your xMatters deployment (or select the Display all
websites in Compatibility View check box).
Note:
SIP Gateway
xMatters supports the following SIP gateways on Linux, Windows 2003, and Windows 2008:
Supported SIP Gateways
SIP Gateway
Details
Asterisk
xMatters has been validated against Asterisk 1.2.14.

xMatters has been validated against and supports Asterisk 1.4.25.1.
Avaya
The following versions of ACM are supported: 3.0, 3.0.1, 3.1, 3.1.1, 3.1.2, 3.1.3, 3.1.4, 4.0, and
5.2.1.
The following versions of SES are supported: 3.0, 3.1, 3.1.1, 3.1.2, 4.0, and 5.2.1.
xMatters has been compliance tested against SES 5.2.1 connecting to Avaya Communication
Manager (ACM) 5.2.1, and has been compliance-tested by Avaya for compatibility with Avaya
Aura Communication Manager 5.2.1 and Avaya Aura SIP Enablement Services 5.2.1. Additionally,
Avaya has granted xMatters with the Avaya Developer Connection Compliance Award for
successful compliance testing with Avaya Aura Communication Manager 6.0 (R016x.00.0.345.0),
Avaya Aura Session Manager 6.0 (6.0.0.0.600020), and Avaya Aura System Manager 6.0 (6.0.0.0556).
Cisco
xMatters has been validated against and supports Cisco Unified Communications Manager
(formerly CallManager) version 7.0.1 and version 9.
SIPGateway Considerations:
n
On Linux (32- or 64-bit), SIP is supported only when running the 32-bit JVM. SIP will not function properly
unless Call Progress Supervision is enabled on the PBX (otherwise, human and machine voice detection will not
work). For further details, see "SIP Requires Call Progress Supervision Support", below.
xMatters deployments that will experience high volumes of SIP traffic must have SIP Device Engines configured
on dedicated xMatters notification server Node computers (i.e., the xMatters notification server Node must reside
on a computer that is separate from other xMatters components such as web servers, application servers, and the
database).
Due to resource-contention that can affect call quality and performance, xMatters SIP is not supported for
virtualized environments.
If your deployment includes a firewall between the xMatters SIPDevice Engines and your SIPgateway, ensure
that the firewall has been configured to allow for traffic of SIPand RTP packets, and that packets can be
automatically forwarded to the correct xMatters IP address; the SIPGateway must use the same IPaddress to
communicate with the SIPDevice Engine. Note that SIPGateways external to the network where xMatters exists
are not supported.
Note that the xMatters SIPDevice Engine supports only RFC2833 for DTMF tones.
SIP Requires Call Progress Supervision Support

xMatters deployments installed with Phone or SIP Device Engines require a telephone environment that supports call
progress supervision. Call progress supervision is a telephony term that covers two telephony features: Answer
Supervision and Disconnect Supervision.
In particular, if the environment does not provide Answer Supervision, the xMatters SIP Device Engine cannot determine
when a call is answered. Instead, it starts playing the recording while the phone is still ringing.
Environments that have call progress supervision include those with direct T1/E1/J1 (ISDN PRI or BRI) connections,
analog Dialogic cards, and POTS lines that support call progress tones.
Note that problems can occur with PBXes and T1 cards that are connected to POTS lines through a channel bank that
does not support call progress supervision, and with PBXes that do not support call progress supervision that are directly
connected to POTS lines.
BlackBerry Enterprise Server (BES)

xMatters supports BlackBerry Enterprise Server 3.5, 4.x, and 5.x (requires Mobile Data Services (MDS) for browser push).
Client-side operating systems
In xMatters (as of 4.0 patch 017 and 4.1 patch 009), you can specify which BlackBerry OSversion should be targeted by
each Protocol Provider. For more information, see "BES Protocol Providers" on page 161.
Note:
If your system employs multiple BES servers, each of which has a unique list of users, sending a message to a
BES server that does not have the recipient user results in undelivered messages. To resolve this issue, you will
need to configure the BlackBerry MDS Connection Service central push server. This abstracts xMatters and
your users from having to know the BES server on which they are deployed/listed. For further details, contact
your BlackBerry vendor to obtain the latest BES planning guide.
Developer IDE
To install the xMatters Developer IDE, it must be possible to install and run J2SE 1.6; a JVM used by the latter is
installed by default. (Note that the Developer IDE is supported for Windows and Linux, but is no longer supported for
Solaris, AIX, or HP-UX).
Phone Recorder
The Phone Recorder utility allows you to re-record system recordings such as numbers and letters. To use the Phone
Recorder application, a supported Dialogic card must be installed.
Virtual Device Engine

The Virtual Device Server provides Virtual Device interfaces for Pager, Email and Text Phone Devices. On Unix
operating systems, the Virtual Device Server requires an X display server to function (it will not function on a headless
Unix system). Run the Virtual Device Server from an X desktop session on the system on which it is installed, or attach
the server display to a remote X server. This allows the server to create the Virtual Device interfaces when it receives
notifications.
Windows 2008 deployment considerations

Installing the xMatters relevance engine on a Windows Server 2008 (64-bit) deployment requires the xMatters installer
specific to Windows 2008. The installer's archive package filename will include "Win64"; e.g., xm410-WindowsWin64.zip.
Note that this installer does NOTfunction as method of upgrading an existing Windows 2003 xMatters installation.
You must install a new node on a Windows 2008 machine while decommissioning your Windows 2003 machine; this
requires that you have at least one extra machine to host the new node during transition.
If you require additional temporary licenses for the migration, contact xMatters Support.
If you are planning to use Virtual Devices on your test/development system, note that Windows 2008 security
restrictions prevent Windows Services interacting with some applications, including the xMatters Virtual Devices. For
instructions on how to modify your deployment so that Virtual Devices will work with Windows 2008, please refer to
the xMatters Community site at community.xmatters.com; search on the terms "Windows 2008" and "Virtual Devices".
Using Dialogic cards with Windows 2008
If you are planning on using Dialogic cards for a new xMatters installation, ensure that you acquire the correct (i.e.,
updated for Windows 2008) Dialogic/Syntellect license dongles appropriate for your new deployment.
If you are upgrading your Windows 2003 deployment to Windows 2008, note that your existing dongles will not work
with Windows 2008. For assistance with dongles purchased through xMatters, you can contact xMatters Support via the
Community site at community.xmatters.com to speak with an associate about acquiring a temporary set of dongles. If
you purchased your dongles through another supplier, you may need to contact your original supplier to obtain updated
licenses.
Hardware Requirements
The following sections outline the minimum and recommended hardware requirements for an xMatters deployment on
Unix and Windows.
Note:
Voice (i.e., phone) and MAPI email deployments require a Windows system. SIP requires Windows Server 2003
or Linux (32- or 64-bit) running the 32-bit JVM.
All-in-One Deployment
In an all-in-one deployment, all xMatters components (Application Server, web server, and database) are co-hosted on
the same machine. All-in-one deployments on Unix do not support voice notifications (voice components must be
installed on a Windows server).
Note:
Co-hosting the xMatters database and xMatters components is NOT supported for enterprise deployments. The
database server must be installed on a machine that is separate from xMatters.
The following table outlines the minimum hardware requirements for an all-in-one deployment:
Minimum All-in-One System Hardware Requirements
Platform
Vendor
CPU
GHz
RAM (GB)
x86
Intel
2x P4
3.6
x86-64
Intel
Core2 Duo
3.0
x86-64
AMD
K8-Opteron
3.0
PowerPC
IBM
2 xG5
2.5
Sparc
Sun
2x UltraSparc IV
1.6
PA-RISC
HP
4x PA-8700
0.875
Itanium
HP
Itanium 2 (Dual Core)
1.6
Multiple-System Deployments
This section outlines system requirements for larger enterprises that expect to experience extremely high concurrent
loads.
For high-volume xMatters deployments, ensure that xMatters components are not co-hosted with each other or
with third-party enterprise applications. For further details, see "xMatters enterprise Deployment Guidelines"
on page 21.
Note:
The following table outlines the minimum hardware requirements for a multiple-system deployment (xMatters
Application & Notification Server Nodes, Web Servers, and Databases):
Minimum Multiple-System Hardware Requirements
Platform
Vendor
CPU
GHz
RAM (GB)
x86
Intel
2x P4
2.8
x86-64
Intel
Core2 Duo
3.0
x86-64
AMD
K8-Opteron
3.0
PowerPC
IBM
2x G5
1.8
Sparc
Sun
2x UltraSparc IV
1.35
PA-RISC
HP
4x PA-8700
0.75
Itanium
HP
Itanium 2 (Dual Core)
1.4
Note:
To compare the performance of other types of CPUs with that of the benchmark Intel Xeon CPUs, visit
http://www.spec.org/cpu2006/results/cpu2006.html. Additionally, although the latter table lists the
recommended hardware requirements, it is strongly recommended that you work with your xMatters
representative to determine the hardware requirements of your organization's specific deployment.
Latency Requirements
For multiple-system deployments, it is recommended that the latency between remote Notification Server Nodes and the
xMatters application server/database not exceed 200ms. Slower connections will experience increased delays between
notification creation and the start of a call, increased delays between voice recordings, and slower text messaging
performance.
Note:
xMatters requires a robust network infrastructure with no measurable communication loss between
components. If the network layer is unreliable or has high latency, product performance and behavior will be
impacted. Operating xMatters in such conditions is not a configuration supported by xMatters.
Failover Connectivity
For failover between the Application Server Node, the Web Server, the Notification Server Node, and the database, the
minimum connectivity requirements between the sites are as follows:
n
Dedicated bandwidth for Application Server Node and database traffic: 2Mbps
Network latency between the Application Server Node and the database: below 30ms for a 1024 byte (1KB)
packet round-trip
Dedicated bandwidth for Web Server Node and database traffic: 2Mbps
Network latency between the Web Server Node and the database: below 30ms for a 1024 byte (1KB) packet
round-trip
Network latency between the Notification Server Node and the database: less than 200 ms for a 1024 byte (1KB)
packet round-trip
Network latency between the Notification Server Node and the Application Server Node: less than 200 ms for a
1024 byte (1KB) packet round-trip
Note that this typically means the Application Server Node, the web server and the database should all be located in the
same data center. The Notification Server Node is optimized for remote distribution.
Pre-Installation Configuration
The following sections describe hardware, general software, database, and configuration issues that should be considered
before installing xMatters.
Hardware
Before installing xMatters, install and test the following hardware:
Hardware Checklist
Hardware
Notes
Dialogic
voice cards
When purchasing Dialogic cards, ensure that each card will fit into the target computers case. Also,
note the bus speed for the card so that you can match it with your system (i.e., PCI, PCIx).
For more information about installing Dialogic cards, see "Installing Dialogic Voice Cards and Drivers"
on page 50.
Call
Progress
Supervision
xMatters deployments installed with Phone or SIP Device Engines require a telephone environment that
supports call progress supervision. Call progress supervision is a telephony term that covers two
telephony features: Answer Supervision and Disconnect Supervision.
In particular, if the environment does not provide Answer Supervision, the xMatters SIP Device Engine
cannot determine when a call is answered. Instead, it starts playing the recording while the phone is still
ringing.
Environments that have call progress supervision include those with direct T1/E1/J1 (ISDN PRI or BRI)
connections, analog Dialogic cards, and POTS lines that support call progress tones.
Note that problems can occur with PBXes and T1 cards that are connected to POTS lines through a
channel bank that does not support call progress supervision, and with PBXes that do not support call
progress supervision that are directly connected to POTS lines.
Envox
license key
(dongle)
Ensure that you have purchased an Envox license key (USB or parallel dongle) for the appropriate
number of licensed voice lines. The drivers for the license key are installed during the xMatters
installation.
Pre-Installation Configuration | 32
Hardware
Notes
Modems
xMatters uses only hardware modems with a direct connections to the operating system (Softmodem,
WinModem, and physical modems in virtualized environments are not supported). For paging modems,
xMatters recommends the US Robotics Courier or Sportster (ensure that Auto Answer is disabled, or that
the Telco/PBX does not allow inbound calls to the modem). Most GSM modems are supported for
direct communication with GSM mobile phone providers for text messaging.
The following lists identify some of the many modems that have been successfully tested and deployed
with xMatters:
TAP
l
US Robotics Sportster 33.600
US Robotics Courier (serial connection)
MultiTech Systems MultiModemUSB (MT5634ZBA-USB-V92 (USB) and MT9234ZBA-USB

(USB))
US Robotics v.90 56k
GSM
l
Enfora Spider SA-G GSM 1203-J (1900)
MultiModem MTCBA-G-F4
MultiModem MTCBA-G-U-F4 (USB)
MultiModem MTCBA-G2-U
Wavecom Fastrack Supreme 10 (serial)
For more information about supported modems, including examples of known good configurations, see
the xMatters Community site at community.xmatters.com.
Analog
phone lines
for voice
cards and
modems
The number of voice lines should match the number of license lines in your xMatters purchase and
licensing information.
Failover
For failover between the Application Server Node and the database, the minimum connectivity
Connectivity requirements between the two sites are as follows:
l
l
Dedicated Bandwidth for xMatters traffic: 2 MB/second

Network Latency between Application Server, web server, and database: below 30ms for a 1024
byte (1KB) packet round-trip
Also note that the recommended latency between Application Server Nodes and remote Notification
Server Nodes is less than 200ms.
Software
Install and test the following software before installing xMatters:
Software Checklist
Software
Notes
Operating System
If you are performing a clean OS install, ensure that any computer names reflect your
network naming conventions.
Database
The database you intend to use with xMatters (see "Software Requirements" on page 25
for a list of supported databases) must be installed and operational before you can
install xMatters.; Note that you will need the database administrator user name and
password for the installer to create the xMatters schema.
Confirm that the latest patches, service packs, and security updates have been installed
for supported databases.
SMTP or MAPI email

accounts
Define SMTP or MAPI email accounts and passwords. A unique mailbox must be
created for use by xMatters.
Note that xMatters version 5.x has been validated only with Microsoft Outlook 2010.
Management System
Create a list of all Management Systems that will connect to xMatters, and ensure that
you have the latest xMatters Integration Module for each.
Java
xMatters requires Java 6 or Java 7 to run the installer.
Multiple Node Deployment Considerations

For deployments with multiple Nodes and Disaster Recovery deployments, the time zone for the operating system must
be synchronized across all Application Server Nodes and web servers.
Note:
Ensure that all xMatters nodes (Application Servers and Notification Servers) can intercommunicate.
Example One
A deployment has Nodes in three physical locations:
n
San Francisco (Application Server Node, web server and database)
London (Notification Server Node)
Tokyo (Notification Server Node)
The time zones for the systems in San Francisco should all be set to US/Pacific.
Example Two
A deployment has Nodes in three physical locations:
n
San Francisco (Application Server Node, web server, and database)
Chicago with fast WAN connection to San Francisco (Application Server Node)
Tokyo (Notification Server Node)
The time zone for the Chicago Application Server Node should be set to be US/Pacific time (i.e., the same time zone as
the San Francisco database, web server, and Application Server Node). The Toyko Notification Server Node can be set to
a different time zone.
Oracle Database Configuration Considerations

If you are using an Oracle database with xMatters, the following recommended Oracle settings may require adjustment
based on your xMatters deployment and hardware sizing:
n
Oracle and its listener must start automatically after a system restart.
DBA must provide a path to where data files for the xMatters schema reside, and the Oracle instance must be able
to read/write to this location.
To help ensure a production-ready database, it is strongly recommended that the DBA and the host systems
System Administrator complete Oracles suggested post-installation set-up.
WARNING
The xMatters database name (where applicable), user name, and schema name MUSTMATCH, and the database user's
default schema must be assigned to the xMatters schema. Not following this practice may result in errors when
attempting the following:
n
Running the installer to upgrade xMatters
Running the installer to add a node or web server to an existing deployment
Applying a patch that includes database upgrade scripts
Using the xMatters Developer IDE to access the database
Support for International Character Sets

Currently, the database creation and configuration process determines how Oracle-supported languages are controlled:
n
If the database uses AL32UTF8 as the character set, all languages xMatters supports can be concurrently stored
(AL32UTF8 is the recommended method for installing Oracle).
If the database was configured to use a character set other than UTF-8, only a subset of languages are concurrently
supported.
To change the character set after database creation, a Database Administrator must issue an ALTER DATABASE
CHARACTER SET AL32UTF8 call.
WARNING: If AL32UTF8 is not a superset of your current character set, there is a risk of losing data when
performing this step.
Oracle Database Sizing

The database space usage can be divided into a number of areas for calculating the expected size, as shown in the
following table (database size estimations are for the data and all indexing):
Data Type
Estimated Size
Notes
Code Tables
500 MB
Represents a minimal size with few modifications.
Users
2.5 KB / User
Devices
3.0 KB / Device
Assume four Devices per User.
Groups
50 KB / Group
If no other metric is available, assume 10% of the number of Users.
Data Type
Estimated Size
Notes
Runtime
40 KB / Notification
Events generate multiple notifications; as a result, assume five notifications

per Alert if no other metric is available. This metric includes Audit Data.
Redo Logs
200 KB / Notification /
Hour per log file; three
files recommended
Redo log sizing is particularly sensitive to your installation. It is

recommended that you check the redo logs frequently and use Oracle's
OPTIMAL_LOGFILE_SIZE value from the V$INSTANCE_RECOVERY
system view.
Note:
These numbers are preliminary estimates. Each installation will have different requirements based on usage
patterns.
To determine database size:

1. Multiply all base installation items by the appropriate estimated number (described in the table above).
2. Add 100% for potential base installation growth.
3. Multiply the 'growth'- based numbers (Audit and History Data) by the length of time they will remain in the
system before being cleaned up.
Note:
These estimates do not include Archive logging.
Sample Calculation
This sample database calculation includes estimates for 50 Events per day and 90 days of Audit / History data:
Oracle Sizing Example
Data Type
Space Required (MB)
Code Tables
500
200 Users
20 Groups
*Runtime
900
**Redo Log
Base Install Estimate
1410
Potential Growth
1410
Total Estimated Disk Space
2820
* The Runtime calculation uses the following formula:

Events/Day * Notifications/Event * Days Held * KB/Notification
For this example: 50 * 5 * 90 * 40 = 900,000 KB
** The Redo Log calculation uses the following formula:

(Events/Day * Notifications/Event * KB/Notification * Files) / (Hours/Day * Files/Hour)
For this example: (50 * 5 * 200 * 3) / (24 * 1) = 6,250 KB
Oracle Statistics Gathering Recommendations

SQL is a declarative language, which means that queries define not how to retrieve the data, but rather what data the
queries should retrieve. As a result, Oracle can use many different paths (Query Plans) to retrieve the data, and some
Plans are more expensive than others. To identify the least expensive Plan, Oracle by default relies on the cost-based
optimizer (CBO).
The CBO is a vital component in controlling Oracle and, by extension, xMatters performance. The CBO estimates
costs for each available Plan. In Oracle, these estimates take I/O and CPU performance and utilization into consideration,
along with objects information. To make these estimates, statistics about the database and its host are needed. However,
these estimates, which determine performance, are only as accurate as the statistics provided to the CBO.
Because of the importance of statistics, Oracle includes the Advanced Workload Repository (AWR) to help automate
statistic gathering. The out-of-the-box AWR settings collect database statistics every 60 minutes, and retains them for
seven days. While specific AWR settings are at the discretion of each DBA, xMatters recommends that you capture
statistics during a typical load so that the CBO will base its cost calculations on realistic data. Additionally, statistics
should be retained for a reasonable amount of time (i.e., based on amount of data added daily).
For AWR to gather statistics properly, the statistics_level parameter should be set to TYPICAL or ALL. AWR relies on
the scheduled job GATHER_STATS_JOB to gather statistics regularly. To view Oracle's current settings, run the
following queries while logged in as a user that has permissions for system views.
SELECT a.job_name, a.enabled, c.window_name, c.schedule_name,
c.start_date, c.repeat_interval
FROM dba_scheduler_jobs a, dba_scheduler_wingroup_members b,
dba_scheduler_windows c
WHERE a.job_name='GATHER_STATS_JOB'
AND a.schedule_name=b.window_group_name
AND b.window_name=c.window_name;
Ensure this job is enabled if regular statistic gathering is required. To obtain basic information on the set of statistics
currently available to the CBO, run the following query while logged in as a user with permissions:
SELECT snap_id, begin_interval_time, end_interval_time
FROM dba_hist_snapshot
ORDER BY snap_id desc;
The available snapshots directly affect Oracle's performance, and it is important that they reflect Oracles typical running
condition. For example, when statistic gathering is disabled by setting the interval for GATHER_STATS_JOB to 0 or by
disabling the GATHER_STATS_JOB, it is highly likely that Oracle will not select the least expensive plan to execute
queries from xMatters. To ensure the highest accuracy, gather the Oracle object statistics after each xMatters archiving.
The AWR is very useful for automating statistic collection so that they are up to date; however, manual gathering is still
required. For system statistics, manual gathering should be done during normal workload (refer to the Oracle
documentation for information about System Statistics gathering options using DBMS_STATS.GATHER_SYSTEM_
STATS). Also, even though AWR gathers Object Statistics during the scheduled jobs, it is a good practice to collect
statistics manually after a large data load (refer to the Oracle documentation for information about the different levels
and options for gathering statistics using the DBMS_STATS package).
Oracle Real Application Cluster (RAC)

By default, the xMatters Installer connects to an Oracle database using an SID and specifies the creation of datafiles in
the default location. It is possible for a RAC database to connect by SID; however, only a specific instance can be
configured for the cluster, and this does not take advantage of the benefits of having a cluster. To use a cluster, xMatters
must first be installed against a single instance in the cluster. Post-installation, the common.properties file must be
modified to ensure that load balancing and failover are configured.
Local storage (i.e., rather than shared storage) is the default location for creating a datafile when connecting by SID. As a
result, on the xMatters installers xMatters database Creation Options page, the Generate .SQL script for manual
creation option must be selected (the instructions below provide further details).
Single Client Access Name (SCAN)
Single Client Access Name (SCAN) is a new Oracle Real Application Clusters (RAC) 11g Release 2 feature that
provides a single name for xMatters to access clustered Oracle databases. (SCAN is configured during the installation of
Oracle Database 11g Release 2; for details, refer to the relevant Oracle documentation.)
Using SCANto access the cluster allowsxMatters to use a simple JDBC thin URL independent of which servers in the
cluster are active. The benefit is that xMatters connect information does not need to change if you add or remove nodes
in the cluster.
To install xMatters against an Oracle RAC database, do the following:
1. Run the xMatters installer.
2. On the xMatters database Creation Options page, select Generate .SQL script for manual creation.
3. Open the createdb.sql file in a text editor and locate the following text:
create tablespace ALARMPOINT4 datafile 'ALARMPOINT4.dbf' size 450M autoextend on extent
management local uniform size 500K;
4. Do one of the following:

n
For ASM, modify the datafile value to be null or specify the ASMdisk group:
create tablespace ALARMPOINT4 datafile '<ASM_disk_group>' size 450M autoextend on extent

management local uniform size 500K;
Note:
Typically, when ASM is in use, Oracle Managed Files (OFM) is also in use and OFM does not use actual path
and file names when creating tablespaces.
For NFS, specify that the shared storage directory is used for the datafile option:
create tablespace ALARMPOINT4 datafile '/<shared_Storage>/<instance_name>/ALARMPOINT4.dbf'

size 450M autoextend on extent management local uniform size 500K;
5. Save the file.

6. Open an SQL editor against the Oracle round robin RAC host name and execute the scripts createdb.sql and
createuser.sql (created by the xMatters installer).
7. Continue with the xMatters installation (i.e., re-run the installer).
8. Specify the following on the xMatters database Properties page for the first instance of the Oracle cluster:
l
l
For Hostname, type the IP address of the first instance in the RAC database.
For SID, type the instance name/SID to the first instance in the RAC database (e.g., for a RAC service named
MYRAC, the default SID for the first instance is MYRAC1).
9. When the xMatters installation has completed, stop the xMatters node and web server.
10. Apply xMatters patches as required, start the node to ensure that xMatters database packets are executed, and then
stop the node.
11. Decrypt the common.properties file.
12. Open the decrypted file in a text editor, and replace the existing JDBC_URL content with the following RAC
content (replacing the placeholders below with the actual values; do not use line breaks):
JDBC_URL=jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)
(ADDRESS=(PROTOCOL=TCP)(HOST=ROUND_ROBIN_RAC_SCAN_HOST_NAME)(PORT=1521))
(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=KNOWN_WHEN_INSTALL_ORACLE)))
13. Encrypt the modified file.

14. Replace the existing common.properties file with the newly encrypted file.
15. Restart xMatters nodes and web servers.
16. Repeat steps 1015 for all installed xMatters nodes and web servers.
Microsoft SQL Server Database Configuration Considerations

If you are using a Microsoft SQL database with xMatters, it is recommended that you do the following:
n
Specify the Auto-start option for the Microsoft SQL and SQL Server Agent Services; these Services will then start
when Microsoft SQL Server starts.
Create Microsoft SQL Server Maintenance Plans that automatically deal with backups (e.g., database and
transaction log), automatic shrinking, integrity checks, and so on.
Create a separate SQLServer User login ID and password; xMatters does not support Windows authentication for
the SQLServer user. This user can also be created during installation of xMatters.
WARNING
n

The xMatters schema stores data in the char and varchar data types. The most important limitation to consider is that
only information from a single code page can be validated by the system. A code page is an ordered set of characters of
a given script in which a numeric index, or code point value, is associated with each character. A Windows code page is
commonly referred to as a character set or charset. The code page used to validate and store the data depends on the
database collation. If a character cannot be represented on the given code page, the character is replaced by a question
mark (?).
There is no collation family to concurrently support all listed xMatters languages. Note the following:
n
The Latin1_General collation family supports English, French, Italian, German, Brazilian Portuguese, and Spanish.
The Cyrillic_General collation family supports Russian
The Chinese_Taiwan collation family supports Traditional Chinese.
The Japanese collation family supports Japanese.
The Korean collation family supports Korean.
Note:
The 8-bit codepage character sets are a superset of the 7-bit ASCII code set. This implies that most collations
with also support English and other Latin-based languages. However, there may not be any single code page
that supports multiple languages like Japanese and Chinese.
If the default installation method (i.e., xMatters creates the database) is chosen, the database's collation is set according
to the locale of the database server. To specify a different collation type, use the Generate Database Script option during
installation (see "Database User/Schema Settings" on page 67.) After the script is generated, a Database Administrator
will have to modify the create database statement to use the desired collation.
WARNING: Currently for SQL Server, there are no xMatters-supported methods for switching the collation type
after database creation.
Microsoft SQL Server Database Sizing

The database space usage can be divided into a number of areas for calculating the expected size, as shown in the
following table (database size estimations are for the data and all indexing):
Data Type
Estimated Size
Notes
Code Tables
50 MB
This represents a minimal size with few modifications.
User
40 KB / User
Assume four Devices per User.
Group
50 KB / Group
If no other metric is available, assume 10% of the number of Users.
Runtime
40 KB / Notification
Events generate multiple notifications; as a result, assume five

notifications per Alert if no other metric is available. This metric
includes Audit Data.
Note:
These numbers are preliminary estimates. Each installation will have different requirements based on usage
patterns.
To determine database size:

1. Multiply all base installation items by the appropriate estimated number (described in the table above).
2. Add 100% for potential base installation growth.
3. Multiply the 'growth'- based numbers (Audit and History Data) by the length of time they will remain in the
system before being cleaned up.
Note:
These estimates do not include Archive logging.
Sample Calculation
This sample database calculation includes estimates for 50 Events per day and 90 days of Audit / History data:
Microsoft SQL Database Sizing Example
Data Type
Space Required (MB)
Code Tables
50
200 Users
20 Groups
*Runtime
900
Base Install Estimate
959
Potential Growth
959
Data Type
Space Required (MB)
Total Estimated Disk Space
1918
* The Runtime estimate uses the following formula:

Events/Day * Notifications/Event * Days Held * KB/Notification
For this example: 50 * 5 * 90 * 40 = 900,000 KB
Temporary Database Files

If you encounter data archiving issues on SQL Server, they may be due to limits imposed on the temporary database
(tempdb) files. To resolve these issues, use the following guidelines when determining runtime and configuration data
storage requirements.
Runtime Data Storage Requirements
The following table lists the recommended storage requirements, assuming that the data archiving and purging processes
are set to the default values of 7 days for archives, and 21 days for purging.
SQL Runtime Data Storage Requirements
Events per day
Primary Database Storage (MB)
Temporary Database Storage (MB)
100
200
20
1,000
2,000
200
10,000
20,000
2,000
100,000
200,000
20,000
Configuration Data Storage Requirements

The following table lists the recommended storage requirements, assuming each User has one Device. Note that in
versions prior to xMatters 3.0.2, the xMatters database Administrator must purge the revision data periodically. For more
information about how to purge revision data, contact xMatters Services and Support.
SQL Configuration Data Storage Requirements
Users
Primary Database Storage (MB)
Temporary Database Storage (MB)
100
50
10
1,000
80
20
10,000
100
30
100,000
1,000
100
Note:
If you still encounter data archiving issues, you can also set the tempdev and templog database files to
unrestricted growth.
SQL Server Express Post-Installation Configuration

If you plan to install Microsoft SQL Server Express and xMatters on separate computers, follow the steps in this section
to prepare SQL Server Express for the xMatters installation.
Note:
Microsoft SQL Server Express is not supported for use with xMatters enterprise. Also, be aware that SQLServer
Express has a maximum size of 4GB per database.
By default, SQL Server Express listens only to local connections. To allow SQL Server Express to work with xMatters
(installed on a separate computer), you must enable TCP/IP and configure SQL Server Express to listen on port 1433, as
described below.
To configure Microsoft SQL Server Express to work with xMatters:
1. Click Start > All Programs > Microsoft SQL Server > Configuration Tools > SQL Server Configuration
Manager.
2. In the left pane, expand the tree view for SQL Server Network Configuration.
3. Select Protocols for SQLEXPRESS ("SQLEXPRESS" is the name of the instance that xMatters will use. Note that it
may have a different name, as this is configurable during the SQL Server Express installation).
4. In the right pane, right-click TCP/IP and select Properties.
5. On the Protocol tab, set Enabled to Yes.
6. Click the IP Addresses tab.
7. In the IPAll section, change the TCP Port to 1433.
8. In all of the other IP sections, set the Enabled option to No.
Note:
If you are unsure about which IP address to change, make the change for all listed IP Addresses, except for the
loopback adapter and IPAll.
9. Click Apply.
10. Click OK.
11. In the left pane, select SQL Server Services.
12. In the right pane, right-click SQL Server (SQLEXPRESS) and select Restart.
13. After the service has restarted, close the SQL Server Configuration Manager.
l
You can now install xMatters against this SQL Server Express installation.
SQL Server Express Database Backup

After installing SQL Server Express on Windows, you can use the following files to back up or restore the database:
n
BackupAPDatabase.bat
BackupAPDatabase.sql
RestoreAPDatabase.bat
RestoreAPDatabase.sql
These files are located in the xMatters installation directory, in the backup folder. Running the batch files executes the
Windows osql command that calls the SQL scripts in this directory.
IBM DB2 Database Configuration Considerations

Before installing xMatters, the DB2 database administrator must perform the following tasks:
n
Create a database with page size of 32K:
CREATE DATABASE AP4 PAGESIZE 32 K;
Create a user to use with xMatters on the operating system hosting the database (for instructions, refer to the
operating systems documentation). Note that the database name and operating system username must match. These
are specified in the following lines of the common.properties file:
JDBC_URL=jdbc:db2://db2-server:50005/ALARMPOINT4 [Database name]

JDBC_USERNAME=ALARMPOINT4 [Operating system username]
WARNING
n
Archiving Issue
The xMatters default batch size of 1000 causes a stack trace when archiving xMatters data on DB2. However, you can
work around this issue by increasing the transaction log size.
To increase the transaction log size for DB2:
1. Logon (or remote) to the computer hosting DB2.
2. Open Control Center (e.g., on Windows, Start > All Programs > IBM DB2 > DB2_Name > General
Administration Tools > Control Center).
3. Right-click the xMatters database, and select Configure Parameters.
4. Click the LOGFILSIZ entry, and then click the ellipses (i.e., ...) in the Value column.
5. Type a larger value in the Log File Size field (e.g., 102400), and then click OK.
6. Stop DB2 and then start DB2 (do not use the Restart action).
Note:
This section will be expanded as information becomes available; check the xMatters customer support site
(community.xmatters.com) for updates.

Currently, the database creation and configuration process determines how DB2-supported languages are controlled:
n
If the database uses UTF-8 as the code page, all languages xMatters supports can be concurrently stored.
If the database was configured to use a character set other than UTF-8, only a subset of languages are concurrently
supported.
To change the character set after database creation:

1. Set the codeset and territory (e.g., CREATE DATABASE USING CODESET UTF-8 TERRITORY US (or select
the appropriate code set and territory in Control Center)).
2. Set the DB2CODEPAGE environment variable on the management console computer to 1208:
Note:
UNIX or Linux: use the command set DB2CODEPAGE=1208
Windows: use the command export DB2CODEPAGE=1208
If an existing database has data in it that you need to migrate to UTF-8, the following document can help:
http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?topic=
/com.ibm.db2.udb.admin.doc/doc/t0024033.htm
Ensure the following configuration items have been addressed:
Configuration Item
Notes
Phone Classes
Determine which Phone Classes to use for each Notification Server (for details, see
"Phone Class Resources" on page 153).
Clusters & Sites
Determine which Clusters will correspond to which Sites (for details, see "Clusters" on
page 156 and "Sites" on page 242).
IP addresses
Assign IP addresses, and ensure connectivity between system components (Management

System, xMatters, Nodes, database, web server, etc.). Note:The server machine on which
the Node will be installed must have a static IP address. A server machine with a
dynamically-assigned IP address is not a supported xMattersconfiguration.
Increase ulimit setting

(Linux/Unix)
Because of the relatively low default setting for open files on Linux/Unix servers, "Too
many open files" errors can occur. This can be resolved by increasing the ulimit (this is
an operating system setting that allows more concurrent files to be open at a given
time) to 90000 or unlimited. For further details, see the related knowledge base article
on the xMatters Community web site.
Firewall
Create firewall clearance for network paging. Port numbers vary based on the protocol
used. For more information about running xMatters behind a firewall, contact xMatters
Support. Alternatively, you can configure xMatters to work with a proxy server; for
details, see "Socket Proxy Resources" on page 152.
PBX (or PABX)
Confirm that the PBX allows DTMF tone generation on internal calls. This allows users
to log in with their password when calling in through a PBX to make phone-menu
selections. On many PBX systems, internal DTMF is disabled by default, but a manual
override can be done on a call-by-call basis. If this is the case, users may have to be
trained to override the default.
Configuration Item
Notes
Call Progress Supervision
xMatters deployments installed with Phone or SIP Device Engines require a telephone
environment that supports call progress supervision. Call progress supervision is a
telephony term that covers two telephony features: Answer Supervision and Disconnect
Supervision.
In particular, if the environment does not provide Answer Supervision, the xMatters SIP
Device Engine cannot determine when a call is answered. Instead, it starts playing the
recording while the phone is still ringing.
Environments that have call progress supervision include those with direct T1/E1/J1
(ISDN PRI or BRI) connections, analog Dialogic cards, and POTS lines that support
call progress tones.
Note that problems can occur with PBXes and T1 cards that are connected to POTS
lines through a channel bank that does not support call progress supervision, and with
PBXes that do not support call progress supervision that are directly connected to
POTS lines.
Voicemail system
Check the voicemail systems by listening to default greetings, and adjust scripts if
needed (for more information, see thexMatters Online Developer's Guide).
Inbound phone number
There should be at least one inbound telephone number, which should ring the highestnumbered Dialogic port first, then ring in descending order towards Dialogic port
number 1. xMatters places outbound calls with the lowest numbered-available Dialogic
port and then calls in ascending order. This maximizes telephone line selection for both
the xMatters and the PBX hunt group.
User and Group data
Define User and Group source data for the system. For details about synchronizing
system data, see "Data Synchronization" on page 377.
Business rules for Groups
Define and document business rules related to the creation of Groups, notification
workflow, and shift rotations. xMatters scheduling is highly flexible, and can be
complex to configure and deploy without a defined framework in place.
Naming conventions
Establish User and Group ID numbering and/or naming conventions.
Escalation
Define escalation policies and procedures.
Network Port Defaults

This section summarizes typical port and data flows throughout an xMatters installation. There are several software
packages involved in a typical installation, including:
n
Java Client
xMatters application server node
xMatters notification server node
xMatters web user interface
There are two different types of usages: listen and open. A software component that listens on a port is waiting for
incoming connections, whereas a component that opens a port is initiating communications.
The tables below outline the different ports, usages, and example data (when applicable) for each application; all ports
listed are shown as defaults.
xMatters Java Client Ports

The following components are a part of the Java Client:
n
xMatters Agent (APAgent)
xMatters Client (APClient)
xMatters Client (binary) (APClient.bin)
xMatters Admin (APAdmin)
Port usage details for each of these components follow.

Note:
You cannot configure specific outgoing ports (or a range of ports) that the Java Client should use when
connecting to the server (outgoing ports are determined by the operating system and Java).
xMattersAgent
The following table shows the default port usage for the xMatters Agent:
xMatters Agent Default Port Usage
Port
Listen Open Protocol
Usage
2004 N
TCP/XML Communications between APAgent and xMatters; defined in

<install>/etc/APAgent.xml and specified during installation
2009 Y
RMI
Java-based object communications, includes Administration and message submission

via APClient; defined in <install>/etc/APAgent.xml
2010 Y
HTTP
Provides an HTTP API for posting event messages and web administration, used
primarily by APClient.bin; <install>/etc/APAgent.xml
2110 Y
TCP
Communcations with Services Control Manager (Windows only); defined in

<install>/etc/APAgent.conf
25
SMTP
Communications between APAgent and an SMTP relay, used by the Health

Monitoring system; defined in <install>/etc/APAgent.xml and specified during
installation
The following table shows the default port usage for the xMatters Client:
xMatters Client Default Port Usage
Port
Listen Open Protocol Usage
2009 N
RMI
Java-based object communications, default facility for posting messages via APClient;
defined at runtime based on APAgent configuration
2010 N
HTTP
HTTP-based communications for message submission to APAgent (this is the alternate

facility); defined at runtime based on APAgent configuration
xMatters Client (binary)

The following table shows the default port usage for the xMatters Client (binary):
xMatters Client (binary) Default Port Usage
Port
2010 N
HTTP
HTTP-based communications for message submission to APAgent; defined at runtime

based on APAgent configuration
xMatters Administration Tool

The following table shows the default port usage for the xMatters Administration tool:
xMatters Admin Tool Default Port Usage
Port
2009 N
RMI
Java-based object communications for query and control APAgent; defined at runtime
based on APAgent configuration
xMatters Nodes
The following table shows the default port usage for the xMatters nodes (Application Servers and Notification Servers):
Note:
The Application Server and Notification Server Nodes have identical default port usage, with the exception
that Application Servers use port 2004 to accept input from the Java Client.
Port
Listen Open
Protocol
Usage
25
SMTP
Outgoing email relay
465
SMTP/SSL Secure Socket Layer (SSL) outgoing email relay
110
POP3
995
POP3/SSL Secure Socket Layer (SSL) email server communications port
139
MAPI
Email server communications port
143
IMAP
993
IMAP/SSL Secure Socket Layer (SSL) email server communications port
444
Paging
Default port for a generic network paging protocol (SNPP)
2775
SMPP
Default port for SMPP providers
5060
SIP
Default port for SIP Device Engine. Note that if you are using a firewall, you
must also open a range of ports based on the RTP Port (min) and RTP Port
(max) settings specified in the SIP Device Engine Details; default range is
102565535.
Port
Listen Open
Protocol
Usage
5222
Jabber
Default port for instant messaging communications
7777
Paging
Default port for Skytel communications (SNPP)
9901
TCP
Default port for Virtual Device Engine
1433
JDBC
Java Database Connectivity layer for communications with SQL Server
1521
JDBC
Java Database Connectivity layer for communications with Oracle
8081
HTTP/
SOAP
Direct external service requests from Action Scripts to an integration agent;

dynamically defined by the integration agent
50000 Y
Y (if
TCP
more
than one
Node)
Default value for node-to-node communications. Defined during installation.

The following table shows the default port usage for the xMatters web user interface:
xMatters Web Default Port Usage
Port
Listen Open Protocol
8887 Y
TCP
Usage
Listen for requests to stop the web server; defined in

<install>/common/webserver-start.conf
8888 Y
HTTP/SOAP Listen for requests from web browsers and web service clients; defined in
<install>/webserver/etc/jetty.xml and specified during installation
8443 Y
HTTPS
Listen for secure requests from web browsers and web service clients; defined in
<install>/webserver/etc/jetty-sslengine.xml
8899 Y
AJP
Communications with servlet engine (e.g., JSP processing); defined in

<install>/webserver/etc/jetty-ajp.xml
8081 N
HTTP/
SOAP
mobile access component requests to an integration agent; dynamically defined by

the integration agent
1433 Y
JDBC
Requests to SQL Server database

Note: Port is only listened to if SQL Server Express is installed.
1521 N
JDBC
Requests to Oracle database
Changing the default xMatters web server port

You can change the default port used by the xMatters web server by editing the jetty.xml file.
To change the default port for the web server:

1. Ensure the xMatters web server is stopped.
l
On Windows, the xMatters web server runs as a Windows Service. On Unix systems, it runs as a daemon.
2. Navigate to the etc subfolder in your xMatters installation directory, and open the jetty.xml file in an editor.
3. Locate the following section:
<Call name="addConnector">
<Arg>
<New class="org.mortbay.jetty.nio.SelectChannelConnector">
<Set name="port"><SystemProperty name="jetty.port" default="8888"/></Set>
<Set name="maxIdleTime">30000</Set>
<Set name="Acceptors">1</Set>
<Set name="statsOn">false</Set>
<Set name="confidentialPort">8443</Set>
<Set name="lowResourcesConnections">2000</Set>
<Set name="lowResourcesMaxIdleTime">1000</Set>
<Set name="headerBufferSize">3072</Set>
<Set name="requestBufferSize">8192</Set>
<Set name="responseBufferSize">49152</Set>
</New>
</Arg>
</Call>
4. Change the port number referenced in the <SystemProperty name="jetty.port" default="8888"/> section
to the port on which you want to access the xMatters web server.
5. Save and close the file.
6. Restart the xMatters web server.
7. In a browser, go to http://<xMattersIP>:<port number>/alarmpoint to test the connection.
Note that changing the default port for the xMatters web server may affect the ability of some Devices to communicate
with xMatters, specifically BlackBerry Devices. The out-of-box presentation scripts for BlackBerry Devices attempt to
post to the web server on port 8888. If you change your port settings as described in the steps above, you must also
change the presentation scripts. The following code illustrates the location within the default domain presentation
scripts; the $content.pushurl and the FORM action URL should be changed to reflect the new port:
....
ELSE-IF ($content.deviceclassification == "bes")
...
#Fill the html part for BES device
#Note: content.pushurl must be present, even if url is invalid
$content.pushurl = "http://localhost:8888/static"
$content.pushtitle = $content.subject
$content.htmlmessage = $content.htmlmessage & "<table width=\u0022100%\u0022
border=\u00221\u0022>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Incident ID: </b></td><td>" &
$event.incident_id & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Situation: </b></td><td>" &
$content.situation & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Device: </b></td><td>" &
$content.device & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Time of Incident: </b></td><td>" &
$userTime & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "</table>"
IF (EXISTS($content.choices))
$content.htmlmessage::add("<br>Your response choices are:")
#You may change the URL to point to the alarmpoint web
$content.htmlmessage::add("<FORM
action=\u0022http://localhost:8888/jsp/ProcessNotificationResponse.jsp\u0022
method=\u0022post\u0022>")
....
For more information about editing xMatters scripts, see the xMatters Online Developer's Guide.
Installing Dialogic Voice Cards and Drivers

If your xMatters deployment includes voice capability, install Dialogic voice cards and drivers on computers that will be
handling voice notifications before installing xMatters software on those computers.
Note:
xMatters currently supports the Dialogic 6.0 driver release running on Windows 2003 (32-bit only)or Server
2008 R2. Dialogic drivers are available on the xMatters installation DVD or on the xMatters web site.
xMatters supports the following Dialogic cards:

n
D/4PCIU
D/4PCIUF
D/4PCIUFW
D/4PCIUFEQ (PCI-Express)
D/4PCIU-Euro
D/4PCIUFEU
D/41JCT-LS Euro
D/4PCIU4S
D/240JCT-T1
D/240JCT-T1EW (PCI-Express)
D/300JCT-E1
Note:
xMatters supports only Dialogic cards purchased through xMatters.

Some of the listed Dialogic cards may not be available for purchase; check with your Dialogic vendor for
current availability. However, xMatters will continue to support these cards until end-of-lifed by Dialogic.
Except for the D/4PCIUFEQ and D/240JCT-T1EW models, all supported Dialogic cards are universal and will
work in both PCI and PCI-X slots.
Analog Dialogic Cards

The following instructions describe how to install analog Dialogic voice cards for use with xMatters.
Note:
If you are installing Dialogic voice cards, install them before installing xMatters, as it will be simpler to
troubleshoot any system problems.
To install an analog Dialogic voice card:

1. Locate the Dialogic instruction card included with your Dialogic hardware.
2. Follow the installation instructions on the Dialogic instruction card, using the following settings when indicated.
3. In part 3, Set the Hardware Switches, section A, Programmable Sequence, be sure each Dialogic card has a unique
board ID indicated on the rotary switch. This should be an issue only if you want to support more than four phone
lines. Each analog board supports 4 lines and must have a unique ID. For example, if you have 16 lines you would
install four cards and set the rotary switches as follows:
l
First Dialogic Card: Set to 0. This card supports lines 1-4.
Second Dialogic Card: Set to 1. This card supports lines 5-8.
Installing Dialogic Voice Cards and Drivers | 50
Third Dialogic Card: Set to 2. This card supports lines 9-12.
Fourth Dialogic Card: Set to 3. This card supports lines 13-16.
4. In part 3, section B, Set the Hook-Switch State for Start Up, be sure the slide switch is in the Off position.
5. Perform parts 4 and 5 as indicated on the instruction card.
6. Instead of part 6, Install Software, Configure and Test, see the procedure Install Dialogic Drivers below.
Installing Drivers for Analog Dialogic Voice Cards
This section covers the steps required to install software drivers for Dialogic Voice Cards.
To install drivers for an analog Dialogic voice card:
1. Insert the xMatters installation DVD (or Dialogic Drivers CD) into your drive.
2. On the Windows Start menu, select Run.
3. Type the location of the drive and the path to the Setup folder. For example, D:\Dialogic6\Setup.
l
The Dialogic Setup program begins with a Welcome dialog:
Dialogic version 6.0 Welcome Dialog
4. On the Welcome dialog, click Next to continue.

5. On the Registration dialog, enter your Name and Company, and then click Next.
6. Select the type of installation, and the location to install the Dialogic software: on the Choose Destination
Location page, select Next to accept the default installation directory. On the Select Components page, select
Core Runtime Package:
Dialogic version 6.0 Select Components page
7. In the Program Group Folder dialog, click Next to accept the default folder.
8. On the Summary dialog, review your choices, and then click Next to continue.
9. Click Yes in the third-party software installation dialog box:
Third-Party Software Installation dialog box
10. If the following dialog box appears (warning that some diagnostic utilities will not function), click OK:
11. On the Setup Complete page, select Yes (you must reboot), and then click Finish.
Configuring Analog Dialogic Cards
After installing the drivers for analog Dialogic Cards, run the Dialogic Configuration Manager to complete the setup
process.
To use the Dialogic Configuration Manager:

1. From the Windows Start menu, select Programs > Dialogic System Software > Dialogic Configuration Manager
DCM.
2. In the Computer Name - Dialogic Configuration Manager dialog box, click Connect to continue.
Computer Name Dialogic Configuration Manager Dialog

Note:
If you have an ASR-enabled board, see "Automated Speech Recognition (ASR)" on page 54.
Note:
In some cases, the Dialogic board is not initially found by the DCM. If this occurs, restart the computer, check
the Windows Device Manager for the appearance of an unknown device, and then update the driver for the
device. The system should locate the appropriate file in the Dialogic folder. The board will then appear in the
Device Manager as a Dialogic device. Run the DCM again to ensure that the board is properly detected.
Dialogic Driver version 6.0 Configuration Manager Dialog
3. Within the Configuration Manager dialog box, select the D/4PCI card in the tree view. The cards icon will have
a red dot on it, indicating that the service is not started.
4. To start the service, click the Green Triangle button as shown in Dialogic Driver version 6.0 - Configuration
Manager above.
5. The Configuration Manager displays a dialog box, showing its progress as attempts it to start the service.
Service Starting
6. If the dialog box closes and the bottom of the Configuration Manager displays a System status of Running, then
proceed to Step 8. If the dialog reports Failed, check your settings again, and call xMatters technical support.
7. You can use the Configuration Manager to enable automatic startup, which requests that the driver service runs
whenever the system reboots: in the Settings menu, ensure that Start devices preference > Start all device(s) or
Start none is selected:
Dialogic Configuration Manager 6.0 Automatic Startup Mode
8. Click Settings > System/Device autostart, and then click Start System.
9. Close the Dialogic Configuration Manager dialog.
10. Reboot the computer.
Automated Speech Recognition (ASR)
xMatters automatically installs and uses Microsoft's Speech Recognition engine. This engine works only with specific
Dialogic voice cards that support the additional speech requirements.
Please note the following restrictions:
n
ASR is supported on Dialogic cards only; it is not supported on SIP.
ASR is not currently supported on 64-bit installations of xMatters 5.0. This is due to a lack of support for the 64bit JREfrom the third-party libraries used to enable this feature.
xMatters supports the following Dialogic cards for Speech Recognition:

n
D/41JCT-LS
D/4PCIU4S
D/41JCT-LS Euro
D/240JCT-T1
Note:
Since ASR requires Continuous Speech Processing (CSP) configuration, CSP is limited to robbed-bit protocols
on JCT Media Boards (i.e., T1 boards). Due to hardware limitations, CSP and ISDN cannot run on the same
span on a JCT Media Board. Additionally, be aware that for E1 or T1 boards that support Continuous Speech
Processing (CSP), specifying an ISDN protocol and a CSP firmware file for the same span results in a
download failure to that span (the Intel Dialogic System Service will not start).
The Microsoft ASR engine is tied to the account under which it is running. To run the Microsoft ASR engine
interactively using "node start", the SAPI_5_1_English.exe installation must have been run under the local account.
Further, to run the engine as a service, the installation must have been run under the local computer administer account.
To configure ASR when running the node as a service:
1. Log in using an account that has local administrator privileges.
l
If xMatters was not installed using this account, run the SAPI_5_1_English.exe install file.
2. Using the Services applet, right-click xMatters node and select Properties.
3. Click the Log On tab, and then click the This Account radio button.
4. In the pop-up dialog box, click Browse, and then click the Look in drop-down list and select the local machine
name.
5. In the pane, select your login account and click OK.
6. Enter the password and click Apply to verify the entries.
7. Click OK to complete the setup.
To set up Speech Recognition:
1. Open the Intel Dialogic Product Configuration Manager (DCM) and follow these steps:
2. Right-click the entry for the Dialogic board and select Configure device.
3. Select the Misc tab.
4. Ensure that CSP_Enabled is set to Yes.
5. If the CSPExtraTimeslot option is enabled, set it to ON.
6. Set FirmwareFile to an option other than default (e.g., D41JCSP.fwl).
l
For CSP configurations, change the firmware file being downloaded to the proper CSP firmware file, and
ensure ISDNProtocol is set to NONE for that span.
7. After making the changes, run the xMattersScan Voice Resources utility (Start > Programs > xMatters > Scan
Voice Resources).
Installing Dialogic T-1 and E-1 Cards

Installing and configuring a Dialogic T-1 or E-1 card is more complex than installing an analog card and requires a
familiarity with the different settings on your particular T-1 or E-1 line.
Note:
xMatters supports only one T-1 or E-1 Dialogic card per computer.
The following detailed instructions are based on a specific line configuration; note that your settings may vary.
n
Dialogic board used: D/240-JCT (T1)
Dialogic software used: System Release 6; the Global Call Protocol Package version 4.2
Note:
Install any Dialogic voice cards before installing xMatters, as this will simplify system troubleshooting.
Installing the Dialogic Software

The Dialogic software should be installed in the order presented below.
System Release 6
1. Run the setup.exe program from the System Release 6.0 install directory (located on the xMatters CD in the
Dialogic folder).
2. Click Install Dialogic Software at the initial screen.
3. Click Next at the welcome screen.
4. Enter Registration information (Name, Company Name).
5. Accept the default install directory, and click Next.
6. On the Select Components screen, select Core Runtime Package and Documentation.
l
l
If an ISDN protocol will be used, expand the ISDN Protocols folder, and select the appropriate protocol.
If you are installing on Windows 2003 or 2008, select the Global Call Protocol check box, as illustrated by
the following figure. (This option is only available when installing on Windows 2003 and 2008.)
Selecting Global Call Protocols for Windows 2008 installation
7. Click Yes to accept third party software .

8. Click Next to select program folder.
9. Click Next to start copying files.
10. Click Yes to restart the system.
Global Call Protocol Package
The following instructions install the CDP (Country Dependent Parameter files for Global Call).The Global Call Protocol
Package is intended for users who use the Analog, E1 CAS, or T1 robbed bit technologies; it is not needed for ISDN.
Note that if you are installing on Windows 2003 or 2008, you can skip these steps as you would have installed the
Global Call Protocol during installation of the Dialogic software.
To install the Global Call Protocol Package:
1. Run the setup.exe application from the Global Call Protocol install directory.
l
Unzipping the package places setup.exe file in the \Windows\I386\ sub-directory.
2. Click Next at the welcome screen.

3. Click Next to accept the default destination directory.
4. Click Next to begin the installation process.
5. Click Finish to complete the installation.
Running the Dialogic Configuration Manager

After installing the Dialogic software, start the Dialogic Configuration Manager (Start > Programs > Intel Dialogic
System Release 6.0 PCI> Configuration Manager - DCM) to initiate the Board Locator program:
1. On the Computer Name screen, select Local computer name, and then click Connect.
l
l
The Dialogic Service should detect the board and download the firmware to the board.
You should see the board listed under the DCM with a red dot to indicate that the Dialogic Service is
currently stopped.
2. To start the Dialogic Service, click the green radio button on the top toolbar.
3. Wait until the red dot on the board icon changes to green.
l
The System Service Status at the bottom of the DCM window should say Running. This indicates that the
board and firmware are installed and running properly.
4. Set the Dialogic System to start automatically by clicking Settings > System/Device autostart and selecting Start
System.
Running the Universal Dialogic Diagnostics utility

The Universal Dialogic Diagnostics (UDD) utility runs several important board diagnostic tests, including DSP, RAM,
and T1 loop back tests. These tests further ensure that the board is working properly.
1. To start the UDD, click Start > Programs > Intel Dialogic System Software > Universal Dialogic Diagnostics
Utility.
2. Click Yes to clear the All Dialogic Boards will now be stopped warning.
l
The UDD downloads the board firmware, starts the board, and displays an option screen.
3. Under Products, find your Dialogic board under (the JCT board has a main board at ID 0 and a daughter board at
ID 1).
4. In the Specify Tests dialog box, select all tests for the base board at ID 0.
l
Ensure that the Use Default Parameters check box is selected for each test, and then click OK.
5. In the Specify Tests dialog box, select all tests for the daughter board at ID 20.
l
Ensure that the Use Default Parameters box is selected for each test.
6. Click OK to return to the main UDD options screen.

7. Click Run Tests.
l
The test process begins. Board Sanity, Shared Ram, Local Ram, DSP, Board Timer, Onboard Interrupt, CT812
(bus test), EEPROM, and the T-1 Loopback tests for the base board should all pass. Board Sanity, Shared
Ram, Local Ram, DSP, Board Timer, Onboard Interrupt, CT812 (bus test), and the EEPROM tests for the
daughter board should also pass.
8. After viewing the test results, click Done.

9. At the main UDD options screen, click Exit UDD to close the utility.
Configuring T-1/E-1 Dialogic Cards

To configure the Dialogic card, open the Intel Dialogic Product Configuration Manager - DCM and follow these
steps:
1. Stop the Dialogic board if it is running.
2. Right-click the entry for the Dialogic board and select Configure device.
3. If ISDN is used, select the Interface tab, and select the ISDN protocol.
4. Select the Country tab, and select the Country.
l
The Country Protocol may also need to be set depending on the ISDN protocol selected.
5. Select the Misc tab.

6. Set the FirmwareFile to default.
7. Set ParameterFile to an option other than default (e.g., spandti.prm; see samples below).
8. Set CSP_Enabled to YES.
9. If enabled, set CSPExtraTimeslot to ON.
10. Restart the Dialogic card.
Some modifications are required to set up the T-1 trunks to desired parameters. The following steps represent example
configurations; note that your settings may vary.
To Modify the Global Call Protocol

Define the Global Call Protocol on the main xMatters Phone Device Engine configuration form. By default, the Global
Call Protocol is set to isdn.
For more information about the Device Engine settings, see "Phone Device Engines" on page 132.
Configuring Global Call call-out parameter settings
When xMatters makes a phone call using Global Call, it uses default call setup parameters. In rare instances, these
default values may not be compatible with the telephone company. To configure these call setup parameters, edit the
GlobalCall.tzp and GlobalCall.cfg files. (Note that, by default, this feature is not enabled.)
Note:
These instructions apply to xMatters phone configurations using T1 or E1 Dialogic cards.
If you are upgrading from a previous version of xMatters, you can recreate the GlobalCall.tzp file with an additional
entry per line by running the Scan Voice Resources utility (on Windows, click Start > Programs > AlarmPoint
Systems > Scan Voice Resources).
To configure the Global Call call-out parameters:
1. Stop the xMatters node.
2. Open the GlobalCall.tzp file in a text editor, and change all occurrences of:
Techs[R4GcTrunk]\Devs[x]\UseMakeCallBlock=False
To:
Techs[R4GcTrunk]\Devs[x]\UseMakeCallBlock=True
3. Open GlobalCall.cfg in a text editor, and change:

ENABLE
FALSE
To:
ENABLE
TRUE
4. In the last section of the file, named [config], make any required changes.
l
For example, to change the Facility Code, change:
REGID_R4GcMKBFacilityCodingValue
ISDN_NOTUSED
To:
REGID_R4GcMKBFacilityCodingValue
0x00
5. Restart the xMatters node.

The following is a list of default call setup parameters:
m_IsdnMKB.isdn.BC_xfer_cap = BEAR_CAP_SPEECH;
m_IsdnMKB.isdn.BC_xfer_mode = ISDN_ITM_CIRCUIT;
m_IsdnMKB.isdn.BC_xfer_rate = BEAR_RATE_64KBPS;
m_IsdnMKB.isdn.usrinfo_layer1_protocol = ISDN_UIL1_G711ULAW;
m_IsdnMKB.isdn.usr_rate = ISDN_NOTUSED;
m_IsdnMKB.isdn.destination_number_type = LOC_NUMBER;
m_IsdnMKB.isdn.destination_number_plan = ISDN_NUMB_PLAN;
m_IsdnMKB.isdn.destination_sub_number_type = ISDN_NOTUSED;
m_IsdnMKB.isdn.origination_number_type = EN_BLOC_NUMBER;
m_IsdnMKB.isdn.origination_number_plan = UNKNOWN_NUMB_PLAN;
m_IsdnMKB.isdn.facility_feature_service = ISDN_NOTUSED;
m_IsdnMKB.isdn.facility_coding_value = ISDN_NOTUSED;
m_IsdnMKB.isdn.completion_point = 0xff ;
m_IsdnMKB.isdn.destination_sub_phone_number[0] = '\0';
m_IsdnMKB.isdn.origination_phone_number[0] = 0;
m_IsdnMKB.isdn.origination_sub_phone_number[0] = '\0';
m_IsdnMKB.isdn.usrinfo_bufp = 0 ;
m_IsdnMKB.isdn.nsfc_bufp = 0 ;
To Modify the CT ADE Profile

1. If you want to enable ANI/DNIS support, add or modify the following lines in the GlobalCall.tzp file located in
the xMatters installation sub-folder Datastore\Voice Configuration (the changes must be made for each physical
board line):
\Techs[R4GcTrunk]\Devs[0]\DNISSupported=True (enables DNIS support)
\Techs[R4GcTrunk]\Devs[0]\ANISupported=True (enables ANI support)
\Techs[R4GcTrunk]\Devs[23]\DNISSupported=True
\Techs[R4GcTrunk]\Devs[23]\ANISupported=True
2. Rerun Scan Voice Resources utility.
T-1 E&M (Robbed bit) Configuration Sample

A robbed-bit T-1 span with Extended Super Frame with the ICAPI us_mf_io protocol is used for this sample:
T-1 E and M (Robbed bit) Configuration Sample
Configuration
Setting
Value
xMatters
GlobalCall
us_mf_io
Dialogic
ISDN Protocol
none
Country
US
Firmware file
default
Parameter file
spandti.prm
CSP_Enabled
YES
Configuration
Note:
Setting
Value
CSPExtraTimeslot
ON
To change the GlobalCall setting, see "To Modify the Global Call Protocol" on page 58.
spandti.prm
The Spandti.prm file may have to be modified, especially for the Framing Format and Zero Code Suppression Mode (this
file is in the Data subdirectory of the Dialogic installation folder):
n
Parameter 0014 Framing Format selects D4 or ESF (Extended Super Frame) framing. The parameter is set to 01 for
this sample.
Parameter 0020 Zero Code Suppression Mode selects None, B8ZS or Bit 7 jamming. The parameter is set to 01 for
this sample.
Note:
Settings preceded by a semi-colon use the default setting.
us_mf_io.cdp
This file is the ICAPI protocol file for the United States Inbound/Outbound using MF and DTMF tones (this file is in the
Data subdirectory of the Dialogic installation folder). This file typically does not need to be modified.
T-1 Loop Start (Robbed bit) Configuration Sample

A robbed-bit T-1 span with Extended Super Frame with the ICAPI us_mf_io protocol is used for this sample:
Configuration
Setting
Value
xMatters
GlobalCall
pdk_us_ls_fxs_io
Dialogic
ISDN Protocol
none
Country
US
Firmware file
default
Parameter file
spandti.prm
CSP_Enabled
YES
CSPExtraTimeslot
ON
Note:
After you have changed GlobalCall to pdk_us_ls_fxs_io, start and stop the node to set the value into the registry. Before
the Voice (Phone) Engine can start, you must run the Voice Utility to apply the new protocol to the ProfileConfig.txt
and GlobalCall.tzp files. Once you have done this, restart the node and the Voice (Phone) Engine should start.
T-1 ISDN PRI (DMS) Dialogic Configuration Sample

ISDN DMS is used for this sample:

Configuration
Setting
Value
xMatters
GlobalCall
isdn
Dialogic
ISDN Protocol
DMS
Country
US
Firmware file
default
Parameter file
dms.prm
CSP_Enabled
YES
CSPExtraTimeslot
ON
Note:
E-1 ISDN PRI (EURO-ISDN CTR4) Dialogic Configuration Sample

ISDN EURO-ISDN is used for this sample:
Configuration
Setting
Value
xMatters
GlobalCall
isdn
Dialogic
ISDN Protocol
CTR4
Country
UK
Country Protocol
prot_BTCallStream
Firmware file
default
Parameter file
ctr4.prm
CSP_Enabled
YES
CSPExtraTimeslot
ON
Note:
Note:
The Parameter file for ISDN is the name of the ISDN Protocol followed by the .prm extension.
E-1 ISDN Q.SIG (ISO 11572, ISO 11574 - QTE) Dialogic Configuration Sample
ISDN Q.SIG is used for this sample:
Configuration
Setting
Value
xMatters
GlobalCall
isdn
Dialogic
ISDN Protocol
QTE
Country
UK
Country Protocol
prot_BTCallStream
Firmware file
default
Parameter file
qte.prm
CSP_Enabled
YES
CSPExtraTimeslot
ON
Note:
Dialogic PRI Protocol Reference

The following table provides a Dialogic PRI Protocol Reference (TE means Terminal Equipment; NT means Network
Termination):
Protocol
Firmware
Equipment Type
AT&T 4ESS custom switch TR41449/TR41459
4ESS
TE
T-1 Network Emulation TR41449/TR41459
NT1
NT
AT&T 5ESS custom switch 505-900-322
5ESS
TE
National ISDN-2 Bellcore Special Report SR-NWT-002343
NI2
TE
Northern Telecom custom switch A211-1 and A211-4
DMS/100 and
DMS/250
TE
Japanese National ISDN INS-Net 1500
NTT
TE
French National ISDN VN3
VN
TE
French National ISDN VN3
VNNT
NT
EURO-ISDN ETSI300-102
CTR4
TE
EURO-ISDN ETSI300-102
NE1
NT
Protocol
Firmware
Equipment Type
British National BTNR-190-1985
DASS2
TE
Australian National ISDN TS-0141 1990
TPH
TE
Australian National ISDN TS-0141 1990
TPHNT
NT
Q.SIG ISO 11572, ISO 11574
QTE
TE
Q.SIG ISO 11572, ISO 11574
QNT
NT
German National ISDN
1TR6
TE
British Private Branch Exchange DASS2 extension
DPNSS (can be
ordered
separately)
A and B side
EURO-ISDN ETSI300-102 for T-1
ETU
TE
EURO-ISDN ETSI300-102 for T-1
ETN
NT
Q.SIG ECMA-142/143 for T-1
QTU
TE
Q.SIG ECMA-142/143 for T-1
QTN
NT
Installing xMatters
This section describes how to install the xMatters application and components.
Note:
If you are installing Dialogic voice cards, install them before installing xMatters, as it will be easier to
troubleshoot any system problems.
To start the xMatters installation wizard on Windows, double-click the xmn_install.exe (where n is the version
number) file on the xMatters installation disc. Before running the installer on Windows 2008, ensure that you review the
section "Windows 2008 deployment considerations" on page 29.
Note:
If you want to install xMatters on Windows from a shared drive, first map that share as a local drive. If the
mapping failed, you will receive an error message ("The installer has detected one or more copies of the
Windows Services Control Manager, etc.) and you will not be able to proceed with the installation.
There are two installation methods for Unix-based operating systems:

Non-Windows Installation Methods
Method
Command
Description
Graphical user
interface
sh ./xmn_install.bin (where n is the version

number)
Runs a graphical user interface

installation.
Installing xMatters | 63
Method
Command
Description
Console
sh ./xmn_install.bin -i console (where n is

the version number)
Runs a text-based console

installation.
Note:
X-Server is required when performing a graphical user interface install on a Unix-based operating system.
Local and remote X-Server installs are possible; however, the user account used to launch the installer must
have appropriate rights to the X display to be used. In most cases, the user already has the appropriate rights.
If the installer will not run, use the "-i console" command to perform a console-based install.
xMatters Installer
This section guides you through the xMatters installation. You can install xMatters with the installation wizard (i.e.,
GUI installer) or through a console install. Although the sections below cover the wizard installer on Windows and the
console installer on Unix, both installation options are available on each platform. Additionally, the wizard and console
installers have identical choices and paths.
Note:
Before installing xMatters, ensure that the user account performing the install has permission to access the
installation directory, and that the installer will be run from a local drive.
Wizard Installation
The following sections describe each graphical wizard installation screen and related settings.
Introduction
After you launch the installer, the Introduction dialog box appears:
Installation Introduction Panel
License Agreement
After reading the introductory text, click Next to continue, which displays the License Agreement dialog box:
Installation License Agreement
After reading the license agreement, use the radio buttons to specify whether you consent to its terms. If you do not
accept the agreement, the installer prevents you from continuing.
Choose Install Folder
If you accepted the agreement, click Next to continue, which displays the Choose Install Folder dialog box:
Installation Choose Install Folder
If you want to use a path other than the one displayed, click Choose and browse to the desired folder.
Note:
Ensure that you have sufficient disk space to install xMatters at the specified location (for details, see
"Hardware Requirements" on page 30), and that the user running the installer has read/write permissions for
the destination folder.
Database Preparation
Click Next to continue.
The Database Installation Query dialog box is displayed (Windows only):
Installation Database Preparation
Click one of the database installation options (if you are installing SQL Server Express, specify the database instance
name, port number, and system administrator password), and then click Next.
Note:
If you choose to install Microsoft SQL Server Express, the sa Account Password must meet the guidelines
defined in "If you are installing Dialogic voice cards, install them before installing xMatters, as it will be
easier to troubleshoot any system problems." on page 63. The installation will prompt you with an error if your
password does not meet the guidelines.
Database User/Schema Settings

If you are using an existing Oracle or SQL database, the following dialog box is displayed:
Installation Database User/Schema Settings (Oracle shown)
Select one of the following options and then click Next:

n
Allow installer to automatically create: Select to create the User/Schema automatically. Note that you cannot
automatically create the database over an existing database. To install to an existing database, select Skip this step,
items already exist.
Generate .SQL Script for manual creation: Select to generate the scripts that will create the xMatters User and
Tablespace (the table below provides details for Oracle and SQL database settings).
o
After the scripts are generated, provide them to your DBA to create the User/Tablespace on the database
server. Then, start the installer again and select the Skip this Step, items already exist option (described
next). The installer will add the tables and data to your new Tablespace.
Skip this step, items already exist: Select if the User/Schema already exists.
The Upgrades will Archive All Runtime Data warning appears. This cautions you that upgrading from a previous
xMatters installation causes any current system events to be terminated and archived. Click OK if you want to
proceed.
If required, specify the following database settings:

Database Properties
Setting
Description
Hostname/IP
Host name or IP address of the computer where the database is to be installed.
Port
Port number on the computer where the database is to be installed (typically 1521 for
Oracle, 1433 for SQL, and 50000 for DB2).
SID
(Oracle only) System Identifier.
Setting
Description
DB Admin Account
Database administrator user name. Required only if you are allowing the installer to create
the database and user/schema.
DB Admin Password
Password for the DB Admin Account. Required only if you are allowing the installer to
create the database and user/schema.
Tablespace Name
(Oracle only) Name for the new tablespace. Required only if you are allowing the installer
to create the database and user/schema.
Tablespace Filepath
(Oracle only) Path and file name for the new database. Required only if you are allowing
the installer to create the database and user/schema.
Database Size (MB)
(Oracle only) Initial size of the database tablespace. Required only if you are allowing the
installer to create the database and user/schema.
xMatters Account
Schema user account name. Note that on SQL Server: maximum length is 123 characters;
allowable characters are a-z, A-Z, 0-9, (_), (@), and (#); and, you cannot start the account
name with 0-9, (_), (@), or (#).
Note that for SQLServer deployments, this account must be a SQLServer user; xMatters
does not support Windows authentication for SQLServer login.
xMatters Password
Schema user account password.
Click Next.
Merging Administrator Roles
If you are installing xMatters for the first time, the following dialog box appears:
Installation Merge Admin Accounts
This dialog box gives you the option of merging the xMatters super administrator and Company Administrator Roles in
your xMatters deployment. Multiple-Company deployments do not support merged Administrator accounts. For
deployments that do not require multiple Companies, merging these Roles simplifies system administration.
For more information about Roles, see "Permissions: functions and roles" on page 228.
Note:
Selecting Components
The Select Components dialog box is displayed next:
Installation Installing Optional Components
If you want to install the optional xMatters web server, a Node, or the Voice Engine, specify the following settings:
Optional Components Settings Windows installation
Component
Settings
Web Server
Select the Install xMatters web server check box to install the web server, and then type the port
number to use in the Port field.
Node
Select the Install xMatters node check box to install a Node, and then select one of the following
radio buttons:
Create New Node: Specify the settings on the tabs as described in the table below.
Use Existing Node: Click the Node Name drop-down list and select an existing node. Select this
option when you want to update a node or change a configuration setting.
If your xMatters deployment will be used for voice notifications, select the Install Voice Utilities
for VoIP-SIP and/or Dialogic check box (this option appears only on a Windows install). You may
need to scroll down in the dialog box to see this option.
New Node Component Settings

Tab
Setting
Description
General
Name
Identifier for the node being installed (this name appears in the node
administration portion of the web user interface). Note that if you attempt to use
the name of an existing node, you will receive a message listing node names that
you cannot use, and you will be prompted to type a new name for the node.
Host
The externally addressable name of the host where the node is being installed.
Used for inter-node communications.
Port
Port on which the node listens for messages from other nodes.
Protocol
Protocol for inter-node communications (currently, only TCP is supported).
Type
Application Server or Notification Server Node.
Email
Recipient
Email address that will receive a notification if a system health event occurs.
SMTP
Host of the email server that will route system health notifications.
Port
Port on which the email server listens for mail.
Execute
Fully-qualified path to an executable file to launch whenever a Health Monitor

event occurs ("C:\Working Folder\myScript.bat" will run a batch file; on a Linux
node computer, "/home/user/myScript.sh" runs a shell script). Note that the Health
Monitor does not accept parameters. You can also specify a path using the
Executable field on the Application Server Node Details page (see also "View
and manage nodes" on page 111).
Target
If available, the user name of the Company Administrator the Health Monitor
should attempt to notify via xMatters in the event of a system health event
Health Monitor
Note:
You can adjust the Health Monitor settings after installation on the Global Configuration page in the xMatters
web user interface. For more information, see "Global Configuration" on page 198.
Component Installation Progress

To install xMatters and any optional components, click Install, which displays the installation progress:
Installation Installation Progress
Depending on the components you have chosen to install, other installers are automatically launched and run.
Database Creation Progress
The installer then displays the database creation progress:
Installation Database Creation Progress
Install Complete
When the installation is finished, the Install Complete dialog box is displayed:
Installation Install Complete
To complete and exit the installation, click Done. If you installed the Voice Utilities, you will be asked to restart the
computer.
Note:
If the installation was unsuccessful, the information panel text provides a reason for the failure.
Console Installation
If you are planning a console install, it is recommended that you review the following sections before installing.
Introduction
After you launch the installer, the Introduction screen appears:
Installation (console) Introduction
The Introductory screen provides basic version and navigation instructions for the installation. Press Enter to continue to
the xMatters License Agreement.
License Agreement
Read the xMatters Licence Agreement (press Enter as necessary to move through the text):
Installation (console) License Agreement
If you do not accept the agreement, the installer prevents you from continuing.
Choose Install Folder
If you want to use an installation path other than the displayed default, type a different target folder:
Installation (console) Select Installation Directory

Note:
Ensure that you have sufficient disk space to install xMatters at the specified location, and that the user
running the installer has read/write permissions for the destination folder.
Database and User/Schema Creation Method

After you have specified the installation directory, the Database and User/Schema Creation Method setup screen appears:
Installation (console) Database and User/Schema Creation Method
Select one of the following options and then press Enter:
Allow installer to automatically create: Select to create the User/Schema automatically. Note that you cannot
automatically create the database over an existing database. To install to an existing database, select Skip this step,
items already exist.
Generate .SQL Script for manual creation: Select to create the User/Schema manually.
o
After the scripts are generated, and then run by your DBA, you must restart the installer and select the Skip
this Step, items already exist option (described next).
Skip this step, items already exist: Select if the User/Schema already exists.
The Upgrades will Archive All Runtime Data warning appears. This cautions you that upgrading from a previous
xMatters installation causes any current system events to be terminated and archived. Type 1 and press Enter to
proceed.
If required, select a database type and specify its settings (described in the table below).
Installation (console) Database Selection and Settings (SQL)
The following table summarizes the available database settings:

Database Properties
Setting
Description
Hostname/IP
Host name or IP address of the computer where the database is to be installed.
Port
Port number on the computer where the database is to be installed (typically 1521 for Oracle,
1433 for SQL, and 50000 for DB2).
SID
(Oracle only) System Identifier.
DB Admin Account
Database administrator user name. Required only if you are allowing the installer to create the
database and user/schema.
Setting
Description
DB Admin Password Password for the DB Admin Account. Required only if you are allowing the installer to create
the database and user/schema.
Tablespace Name
(Oracle only) Name for the new tablespace. Required only if you are allowing the installer to
create the database and user/schema.
Tablespace Filepath
(Oracle only) Path and file name for the new database. Required only if you are allowing the
Database Size (MB)
(Oracle only) Initial size of the database tablespace. Required only if you are allowing the
xMatters Account
Schema user account name. Note that on SQL Server: maximum length is 123 characters;
allowable characters are a-z, A-Z, 0-9, (_), (@), and (#); and, you cannot start the account name
with 0-9, (_), (@), or (#).
xMatters Password
Schema user account password.
Press Enter.
Merging Administrator Roles
If you are installing an xMatters database for the first time, you are given the option of merging the xMatters super
administrator and Company Administrator Roles in your xMatters deployment:
Installation (console) Merging Administration Roles Query
For deployments that do not require multiple Companies, merging these Roles can simplify system administration.
Note:
For more information about Roles, see "Permissions: functions and roles" on page 228.
Selecting Optional Components

Select which xMatters components to install:
Installation (console) Optional Component Selection
If you have chosen to install the optional xMatters web server and/or Node, specify the following:
Optional Components Settings Console Installation
Component Settings
Webserver
Type the Port number to use.
Node
Select one of the following:

o
Create New Node - Specify the settings for the new node as described in the "Node Settings" table
below.
Use Existing Node - Specify the name of the Node to use.
If applicable, select the type of node (Application Server or Notification Server) to install, and then specify the node
settings:
Installation (console) Optional Component Settings
The following table summarizes the Node settings:

Node Settings
Tab
Setting
Description
General
Name
Identifier for the node being installed (this name appears in the node
administration portion of the web user interface). Note that if you attempt to
use the name of an existing node, you will receive a message listing node
names that you cannot use, and you will be prompted to type a new name for
the node.
Host
The externally addressable name of the host where the node is being installed.
Used for inter-node communications.
Port
Port on which the node listens for messages from other nodes.
Type
Application Server or Notification Server Node.
Email Recipient
Email address that will receive a notification if a system health event occurs.
SMTP
Host of the email server that will route system health notifications.
Port
Port on which the email server listens for mail.
Execute
Full path of the executable that will be invoked if a system health event
occurs (note that the Health Monitor does not accept parameters).
Health Monitor
Tab
Setting
Description
Target
xMatters target that the node will attempt to notify if a system health event
occurs. For example:
mmcbride User name
mmcbride | work email User name and Device
SysAdmins Group name
After you have finished specifying the component settings, installation begins.
Install Complete
When the installation is finished, the Installation Complete screen appears:
Installation (console) Installation Complete

Note:
If the installation was unsuccessful, the information panel text provides a reason for the failure.
Strong Password Guidelines for Microsoft SQL Server Express

A strong password is any password that is not easily predicted, guessed or hacked. When creating a strong password,
use the following guidelines.
To create a strong password:
1. Do not use the following prohibited conditions or terms:
l
a blank, or NULL, condition.
password
admin
administrator
sa
sysadmin
the name of the user currently logged into the computer
the name of the computer
2. Use a minimum of six characters.

3. Use at least three of the following four options:
l
uppercase letters
lowercase letters
numbers
non-alphanumeric characters (#, %, or ^)
Default Administrator User Names and Passwords

After installing xMatters, you can use a default administrator user name and password combination to sign in to the
xMatters web user interface (ensure that you change the default password for each administrator):
Default Administrator Web Logins
Administrator Type
Username
Password
Usage
Super Administrator
root
tree
Company Administrator
admin
complex
If you chose to merge administrative

functions into a single account during
installation, only the Super Administrator
account is functional.
Note:
xMatters also includes a default Standard User with a web login ID of bsmith and a password of 1000.
You can change the password or login ID, or delete the default User in the web user interface.
xMatters init-generator.sh script

The xMatters Unix installation includes a script called init-generator.sh designed to generate files that can be copied into
your init.d directory on Unix-like platforms (e.g., Linux, Solaris, AIX, HP-UX). It generates a script for the installed
components (i.e., xMatters node, xMatters web server, or both) on the computer on which it is run.
Note:
Running the init-generator.sh script requires root account access and should be performed by a Unix system
administrator.
Running the Script

Running init.generator.sh creates the scripts "alarmpoint-node" and/or "alarmpoint-web" (depending on which xMatters
components you have installed) in the same directory. To ensure that the scripts act as expected in your environment,
review them before use.
To run the init.generator.sh script:
1. From a command prompt, change to the root directory of your xMatters installation (this is also the directory that
contains this document, README.init-generator).
2. Run the following command:
./init-generator.sh username
where "username" is the name of the user who will run the xMatters processes (if you do not provide a username to
the generator script, the user "nobody" is assumed).
Running Generated Scripts Automatically
The generated scripts can run automatically when the computer boots. Typically, this is done by copying the generated
"alarmpoint-*" scripts to the /etc/init.d directory and managing symbolic links between them and the /etc/rc.d runlevel
directories.
However, script automation is platform-dependent and many platforms have programs to help manage these links. It is
recommended that you consult your documentation.
Synchronizing System Time (Required)

You must synchronize all system clocks in a multi-node xMatters deployment. It is recommended that you use NTP
(Network Time Protocol), which is a protocol for synchronizing computer system time over packet-switched, variablelatency data networks.
Note:
Failing to synchronize system time in xMatters deployment can result in unexpected failover behavior,
duplicated or lost notifications, inaccurate notification schedules and reports, etc.
The sections below describe how to set up NTP on Windows Server 2003 and RedHat Linux (other *nix operating
systems have similar configurations; for further details, contact your vendor or refer to the operating system's
documentation).
Note:
Although NTP is the recommended protocol for synchronizing system clocks over data networks, other
protocols can achieve the same end result. When using a different protocol, considerations should include
implementation across supported operating systems where xMatters components (including databases) will be
deployed.
Configuring NTPon Windows Server 2003

Configuring NTPon Windows involves several high-level steps and sub-steps, as described below.
Note:
It is strongly recommended that you back up the Windows Registry before carrying out these steps.
Change the server type to NTP:

1. Click Start, click Run, type regedit, and then click OK.
2. Locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\Type
3. In the right pane, right-click Type, and then click Modify.

4. In Edit Value, type NTP in the Value data box, and then click OK.
Set AnnounceFlags to 5:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\
Config\AnnounceFlags
2. In the right pane, right-click AnnounceFlags, and then click Modify.

3. In Edit DWORD Value, type 5 in the Value data box, and then click OK.
Enable NTPServer:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\
TimeProviders\NtpServer
Synchronizing System Time (Required) | 83
2. In the right pane, right-click Enabled, and then click Modify.

3. In Edit DWORD Value, type 1 in the Value data box, and then click OK.
Specify the time sources:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters
2. In the right pane, right-click NtpServer, and then click Modify.

3. In Edit Value, type Peers in the Value data box, and then click OK.
Note:
Peers is a placeholder for a space-delimited list of peers from which your computer obtains time stamps. Each
DNS name that is listed must be unique. You must append ,0x1 to the end of each DNS name (e.g.,
us.pool.ntp.org,0x1 ). If you do not append ,0x1 to the end of each DNS name, the changes made in the "Select
the poll interval" step below will not take effect.
Select the poll interval:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\TimeProviders\
NtpClient\SpecialPollInterval
2. In the right pane, right-click SpecialPollInterval, and then click Modify.

3. In Edit DWORD Value, type TimeInSeconds in the Value data box, and then click OK.
Note:
TimeInSeconds is a placeholder for the number of seconds that you want between each poll. A recommended
value is 900 Decimal. This value configures the Time Server to poll every 15 minutes.
Configure the time correction settings:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
MaxPosPhaseCorrection
2. In the right pane, right-click MaxPosPhaseCorrection, and then click Modify.

3. In Edit DWORD Value, click to select Decimal in the Base box.
Note:
TimeInSeconds is a placeholder for a reasonable value, such as 1 hour (3600) or 30 minutes (1800). The value
that you select will depend upon the poll interval, network condition, and external time source.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
MaxNegPhaseCorrection
6. In the right pane, right-click MaxNegPhaseCorrection, and then click Modify.

7. In Edit DWORD Value, click to select Decimal in the Base box.
Note:
TimeInSeconds is a placeholder for a reasonable value, such as 1 hour (3600) or 30 minutes (1800). The value
that you select will depend upon the poll interval, network condition, and external time source.
9. Quit Registry Editor.
Synchronizing System Time (Required) | 84
Restart the Windows Time Service:

At a command prompt, type the following command to restart the Windows Time service, and then press ENTER:
net stop w32time && net start w32time
Configuring NTPon Red Hat Enterprise Linux

For the steps below, use your preferred NTP server (i.e., for the server parameter in /etc/ntp.conf). It is recommended that
you use a server located within your country. Note that some servers are not available to the public, and that others may
be to busy to handle new requests.
Note:
The following steps represent a basic NTP configuration; for more detailed NTP setup information, refer to the
man pages for ntpd and ntp.conf.
To configure NTP on Red Hat based on Network Time Protocol Version 4:

1. Open the /etc/ntp.conf file in a text editor and configure it as follows (where NtpServer is your preferred external
NTPserver, and IPAddrForNtpServer is the IPaddress for your preferred external NTP server):
/etc/ntp.conf
# A very simple client-only ntp configuration.
server 127.127.1.0 # local clock
fudge 127.127.1.0 stratum 10
driftfile /etc/ntp/drift
restrict default ignore
restrict 127.0.0.0 mask 255.0.0.0
authenticate no
server <NtpServer>
# e.g. us.pool.ntp.org
restrict <IpAddrForNtpServer> nomodify
# e.g. us.pool.ntp.org is
209.123.234.24
2. Using the following command, perform an ntpdate to update the local time (synchronization will not occur if the
initial times are too far out; this forces the times to be relatively close):
# ntpdate -u us.pool.ntp.org
3. Using the following command, turn on ntpd as a daemon for run levels 3, 4, and 5 (this ensures ntpd is started
when entering these run levels):
# chkconfig --level 345 ntpd on
4. Using the following command, start the ntpd daemon:

# /etc/init.d/ntpd start
Suggested Post-Installation Tasks

After you have installed xMatters, it is recommended that you perform the configuration tasks summarized in the
following table, in the order shown:
Task
Notes
Apply xMatters licenses
xMatters licenses control access to xMatters features and define deployment parameters
such as the number of Notification Servers. You can enter and manage xMatters licensing
in the xMatters web user interface. For details, see "Licenses" on page 109.
Suggested Post-Installation Tasks | 85
Task
Notes
Configure Protocol
Providers
xMatters automatically installs Protocol Provider sample data. Edit this data and add new
providers as required. For details, see "Protocol providers" on page 157.
Configure User Service

Providers
xMatters automatically installs User Service Provider sample data. Edit this data and add
new providers as required. For details, see "User service providers" on page 191.
Install additional Nodes

and Webservers
If your deployment requires multiple Application Server or Notification Server Nodes, or

Webservers, run the installer again on the target computers and install additional Nodes or
Webservers as required. Note: before adding nodes, you must apply an xMatters license
that allows additional nodes.
Configure Device Engines xMatters automatically installs the Device Engine for Virtual Devices (Voice, Email,
Pager; for details, see "Virtual Devices" on page 89). You can add other Device Engines
as required; for details, see "Device engines" on page 118.
Define Companies, Sites,
and Clusters
xMatters automatically installs a default Company and Site, which you can edit and add
to as required. For details, see "Licenses" on page 109, "Sites" on page 242, and "Clusters"
on page 156.
Define Roles
Roles control each xMatters Users permissions and access to xMatters features. xMatters
automatically installs several Roles, including Super Administrator, Group Supervisor, and
Standard User. For details, see "Permissions: functions and roles" on page 228.
Define Users
xMatters automatically installs a Restricted User called restricted restricted for testing
purposes. Depending on choices made during installation, Super Administrator and
Company Administrator are also created. Edit and add Users as required. For details, see
the Supervising Users and Groups chapter of the xMatters user guide.
Define Groups
xMatters automatically installs a Group called Operations. Edit and add new Groups as
required. For details, see the Supervising Users and Groups chapter of the xMatters user
guide.
Configure Connection
Pool
You can tune xMatters for increased throughput by optimizing the connection pool
configuration for your deployment. For details, see "Configuring the Database Connection
Pool" on page 357.
Other Items
Depending on your xMatters deployment and licensing, you may be able to define many
other configuration and administration items, such as Authentication Processes (e.g.,
LDAP), Failover, Password Policy, Company Holidays, Subscriptions, and so on. For
details on these and other settings, it is recommended that you review the remaining
chapters in this document.
The following sections identify the supported Text-To-Speech(TTS)engines that you can use to enable voice capability
on your deployment., and provide instructions and guidelines for each engine.
Text-To-Speech Engines | 86
Using Microsoft SAPI

xMatters complies with the Microsoft Speech Application Programming Interface (SAPI) version 5.1, and voice-capable
xMatters installations include this SAPI. This TTS engine is English-only, and includes the following voices:
n
Microsoft Mary
Microsoft Mike
Microsoft Sam
xMatters scripts control which voice is used for voice notifications.

For superior TTS performance, xMatters recommends the NeoSpeech TTS software package; for installation and
configuration instructions, see "Using NeoSpeech TTS with xMatters" on page 87. Using a Text-To-Speech engine on
Linux requires a separately licensed TTSengine (such as AT&TNatural Voice).
Note:
Dialogic cards only support TTS language engines with a voice rate of 8kHz. As a result, languages that use a
higher frequency are not supported and will not work with xMatters (e.g., Korean uses 16kHz). However, higher
TTS language engine voice rates are supported on SIP (SIP Device Engines must use a TTS engine).
Changing TTS speech rate

The following instructions apply to the Microsoft SAPI and TTS engine installed by default with xMatters.
The Microsoft TTS engine is tied to the account under which it is running. When using the Speech applet in the Control
Panel to change how quickly the voice speaks, it only applies to individual users, not the service account. Because the
xMatters node runs as a service, changes to the TTS rate using the Speech applet do not take effect if left to run in the
Local System account.
To configure the TTS speech rate when running the Node as a service:
1. If the Node is running, stop it using the Services applet.
2. Log in using an account that has local administrator privileges.
l
If xMatters was not installed using this account, run the SAPI_5_1_English.exe install file.
3. Using the Services applet, right-click xMatters node and select Properties.
4. Click the Log On tab, and then click the This Account radio button.
5. In the pop-up dialog box, click Browse, and then click the Look in drop-down list and select the local machine
name.
6. In the pane, select your login account and click OK.
7. Enter the password and click Apply to verify the entries.
8. Click OK to complete the setup.
9. If you have not already done so, log in using the account specified.
10. From the Windows Control Panel, launch the Speech applet.
11. On the Text to Speech tab, adjust the Voice Speed setting.
12. Click OK.
13. Restart the Node using the Services applet.
Using NeoSpeech TTS with xMatters

This section provides information about installing and using NeoSpeech TTS (Text-to-Speech) software with xMatters.
xMatters supports SAPI 5 compliant engines with their own installers (i.e., non-standalone TTS engines are not
supported). xMatters has tested several TTS packages and recommends NeoSpeech (see www.neospeech.com).
NeoSpeech is supported on Windows using SIP or a Dialogic card; it is not supported on Unix/Linux. NeoSpeech is a
32-bit application; as a result, it is compatible only with 32-bit xMatters running on Windows 2008 R2.
Note:
If a TTS engine does not have a standalone installer, you must write software to access the engine based on the
vendors developer toolkit.
Installing NeoSpeech
The NeoSpeech Kate TTS voice is available for download from the xMatters Community web site (click download icon
> Product Downloads, or use to the search field to find NeoSpeech products). By default, xMatters provides licenses
enabled with the Kate voice, as it most closely matches the existing xMatters recordings. If you would prefer the Paul
voice, contact your xMatters representative or xMatters Support. Other voices are available directly from NeoSpeech.
Note:
Each NeoSpeech license is associated with a specific version and voice package.
The following table summarizes the available files:

File
Description
NeoSpeech_WinHostID
Retrieves the unique MAC address from your system so that NeoSpeech can supply a
license key for the system.
NeoSpeech_Kate
Female TTS voice (this is the default NeoSpeech voice provided by xMatters, as it most
closely matches the existing xMatters recordings).
NeoSpeech_Paul
Male TTS voice (contact xMatters if you would prefer to have this voice instead of the
Kate voice).
SAPI_5_1_English
The Microsoft SAPI installer, which xMatters automatically installs. However, if there is
already a similar version of the file installed on the system, you may need to run this
installer again manually.
To retrieve your license file and install NeoSpeech:

1. Run WinHostID on the systems where you will use NeoSpeech, and note the unique MAC address WinHostID
provides for each system.
2. In a browser, navigate to http://verification.neospeech.com.
3. Enter your CD-Key and click Issue New License.
l
You may need to enable pop-up windows for the NeoSpeech site.
If prompted, accept and install the required ActiveX control.
4. Select File Download, enter the MAC address of the system where VoiceText will be installed, and then click
Next.
l
When entering the MAC address, omit any dashes and spaces.
5. Click Next to download the license file.

l
Save the license file as verification.txt, and note its location.
6. Enter your email address, and then click Done.

7. Navigate to the xMatters web site (Products > Add-on Components > NeoSpeech) and download the NeoSpeech_
Kate file.
8. Copy the file to your xMatters deployment, unzip the archive, and run the setup application.
9. Copy the verification.txt file to the <NeoSpeech-Install>\data-common\verify folder. By default, the
folder is located at:
C:\Program Files\VW\VT\Kate\M16-SAPI5\data-common\verify

11. If your xMatters deployment has more than one Node supporting voice, repeat the NeoSpeech installation on these
Nodes.
12. In the xMatters web user interface, select the voice that you want xMatters to use:
Note:
Sign on as an Administrator, click the Admin tab, and then click the Nodes and Device Engines menu item.
In the All Nodes table, click the Device Engines link for the Node on which you installed NeoSpeech.
In the All Components for Node table, click the link for the Phone Device Engine.
Type VW Kate in the TTS Engine Personality field.
Note that the first TTS phrase spoken by xMatters after a system restart can have several seconds of delay while
the TTS engine initializes. This is normal, and can be addressed by calling in to xMatters after a system restart,
and ensuring that the script used to answer the phone plays at least one voice phrase using text-to-speech.
Dictionary Editor
The NeoSpeech Dictionary Editor allows you to change the way certain words are pronounced. The Dictionary Editor is
provided as part of each voice installation. The Dictionary Editor is named UserDicEng.exe and can be found in the
lib directory.
Double-click UserDicEng.exe to start the program, and then click File > Open and select your user dictionary. By
default, the dictionary file is located at the following path:
n
C:\Program Files\VW\VT\Kate\M16-SAPI5\data-common\userdict
Refer to the NeoSpeech documentation or help file for assistance with selecting, modifying, and saving phrases.
Note:
You may need to restart the xMatters node before the change takes effect.
Reissuing a License
If you upgrade your system or change the network interface card, you may require a replacement license. For information
about obtaining a replacement license, send an email message to xMatters Support (support@xmatters.com).
Viewing your License Information

To view your license information:
1. In a browser, navigate to http://verification.neospeech.com
l
You may need to enable pop-up windows for the NeoSpeech site.
If prompted, accept and install the required ActiveX control.
2. Enter your CD-Key, and then click View License Record.
NeoSpeech Licensing Reminder

NeoSpeech licensing is based on phone line usage. Ensure that your xMatters deployment does not invoke more than the
maximum number of phone lines allowed by your NeoSpeech license. Failing to do so may result in loss of NeoSpeech
functionality, and multiple errors in the xMatters node log.
Virtual Devices
The main xMatters installer includes Virtual Devices (Email, Pager, Phone (Text), Phone (Voice)) that can be used for
training, testing, and troubleshooting.
Virtual Devices | 89
On Windows systems, all Virtual Devices are automatically configured during the installation process and will appear
when notifications are sent to them (note that the Virtual Phone (Voice) requires a sound card). On Unix, all Virtual
Devices except the Phone (Voice) are installed. The Virtual Phone (Voice) will appear only on the Window-based
computer that runs the Voice Engine.
Note:
You can use either the Virtual Phone (Voice) Device or live Dialogic lines, but you cannot use both
simultaneously. When a notification is sent to a Voice (Phone) Device for a person, xMatters will automatically
use the Virtual Phone or real Dialogic lines based on what is configured in the system.
Installing Virtual Devices on Remote Computers

You can install the Virtual Email, Pager, and Text Phone Devices on a networked computer and then configure the
connection to xMatters.
Note:
The Virtual Phone (Voice) will always work only on the Windows Voice Engine.
To install the Virtual Device Control Center on a remote computer:

1. On the remote computer, browse to the root folder of the xMatters installation disc.
2. Double-click the apx_vdevice_install.exe (where x is the version number) file to start the Virtual Device Control
Center installer.
3. In the Introduction dialog box, click Next.
4. To accept the license, click the I accept the terms of the License Agreement radio button, and then click Next.
5. Specify the installation folder (click Choose to browse to a folder), and then click Install.
6. When the installation has completed, click Done.
After installation, the Virtual Device Control Center needs to be configured to communicate with the main xMatters
system.
To configure the Virtual Device Control Center on the remote computer:
l
l
On Windows, click Start and navigate to AlarmPoint Systems > xMatters Virtual Device Control Center.
On Unix, navigate to the installation directory (default is /opt/alarmpoint/alarmpoint_vdevice) and run the
VDevice.sh start shell script.
2. In the xMatters Virtual Device Control Center dialog box, click System > Configuration.
3. In the Virtual Device Configuration dialog box, specify the following settings:
Virtual Device Configuration Settings
Setting
Description
Listen Port
Specifies the port number on which the Virtual Devices should listen for notifications. Note that this
must match the Port setting of the Virtual Device Protocol Provider, as described below.
Auto Reply
When selected, sets the Virtual Devices to respond automatically to notifications.
No GUI
When selected, specifies that the Virtual Devices will not be displayed when notifications are
received. This setting is meant to be used in conjunction with Auto Reply when testing system
performance under simulated load.
4. Click Save.
Virtual Devices | 90
Configuring the Virtual Device Protocol Provider

After specifying the settings of the Virtual Device Control Center on the remote computer, the xMatters super
administrator must configure the Protocol Provider for Virtual Devices.
To configure the Virtual Device Protocol Provider to use remote Virtual Devices:
1. Log on to xMatters as the Super Administrator.
2. On the Admin tab, in the Configuration menu, click Protocol Providers.
3. In the Protocol Providers list, click the link for the Virtual Device Protocol Provider (by default, this is MY_
VDEVICE_PROVIDER).
4. In the VDEVICE Providers details, set the Port to match the number of the Listen Port in the Virtual Device
Configuration settings (described above).
5. Specify the IP Address as that of the remote computer where the Virtual Devices have been installed and
configured.
6. Click Save.
Modifying the common.properties File

The encrypted common.properties file contains certain database information, as summarized in the following table:
Available Settings in common.properties
Property
Description
JDBC_USERNAME=
xMatters user login (schema) name. In Oracle, this can be any name;
in SQL Server, this name must be the same as the database name.
JDBC_PASSWORD=
The password for the xMatters user login (schema).
JDBC_DRIVER_CLASS_NAME=
The JDBC driver used to connect to the database. This string must
match the value for its database type:
o
o
Oracle: oracle.jdbc.driver.OracleDriver
SQL: net.sourceforge.jtds.jdbc.Driver
It is strongly recommended that users do not change this setting.

JDBC_URL=
The connection string used to connect to the Oracle or SQL Server

database. This string must match the value for its database type:
o
o
Oracle: jdbc\:oracle\:thin\:@<server>\:<port>\:<sid>
SQL: jdbc\:jtds\:sqlserver\://<server>\:<port>
Note: backslashes are required to escape the colons.
Using APSecure
To modify these properties after installation, you must first decrypt the common.properties file using the APSecure tool,
which is included with the xMatters installation.
The command line syntax for running APSecure is as follows:
n
Windows: APSecure.bat <operation> <infile> <outfile>
Unix: ./APSecure.sh <operation> <infile> <outfile>
Modifying the common.properties File | 91
The following table summarizes the command line parameters:

APSecure Command Line Parameters
Parameter
Description
<operation>
Must be either encrypt or decrypt; mandatory.
<infile>
File to decrypt or encrypt; mandatory, and must already exist.
<outfile>
File that is the target for the decrypted or encrypted file; mandatory.
Tuning Node Performance

This section explains some of the ways you can tune the performance of your xMatters node deployment:
n
If you are deploying against a production grade database, such as Oracle 11g or SQLServer, you can improve
performance by adjusting the database connection pool configuration as described in "Configuring the Database
Connection Pool" on page 357.
After configuring the database connection pool, you can further optimize throughput by distributing Device
Engine threads based on how much traffic each protocol supports. For more information, see "Configure concurrent
threads" on page 120.
You can adjust the maximum session size for Protocol Providers to specify the number of notifications that are
transacted within a single session. For more information, see "Set maximum session size" on page 160.
Note:
If required by your environment, see also "High Bandwidth Configuration for a Heavily Loaded Web Server"
on page 355.
Starting and Stopping xMatters Components From a

Command Line
The operating system starts xMatters nodes and the xMatters web server automatically. Under normal conditions, there is
no need to start these components from a command line. However, if you want to start these components from a
command line for troubleshooting purposes, the following sections describe the process.
Note:
Before using command-line instructions to start and stop xMatters components in Windows, use the Windows
Services tool to ensure that the related Service is stopped.
xMatters Nodes
To start or stop an xMatters node from a command line, navigate to the xMatters install directory and use the command
appropriate for the operating system:
Windows
node start
node stop
Note:
The xMatters installer creates an xMatters node entry in the Windows Service Manager that is set to start the
node automatically on bootup.
Tuning Node Performance | 92
Linux and Solaris

./node.sh start
./node.sh stop
./node.sh restart
To terminate the process using the Unix kill command, run:

./node.sh kill
Note:
The xMatters installer creates an init.d reference to start the node automatically on bootup (see "If you are
installing Dialogic voice cards, install them before installing xMatters, as it will be easier to troubleshoot any
system problems." on page 63).
xMatters web server

To start or stop an xMatters web server from a command line, navigate to the xMatters install directory and use
command appropriate for the operating system:
Windows
webserver start
webserver stop
Note:
The xMatters installer creates an xMatters web server entry in the Windows Service Manager that is set to
start the web server automatically on bootup.
Linux and Solaris

./webserver.sh start
./webserver.sh stop
./webserver.sh restart
To terminate the process using the Unix kill command, run:

./webserver.sh kill
Note:
The xMatters installer creates a sample init.d reference (used to start the web server automatically on bootup).
You may need to modify this script for your environment (see "If you are installing Dialogic voice cards, install
them before installing xMatters, as it will be easier to troubleshoot any system problems." on page 63).
If direct access to the xMatters web server is not possible (e.g., due to firewalls or other browsing restrictions), see
"Fronting the xMatters web server" on page 348.
Uninstalling xMatters
The xMatters installation includes an automated uninstaller (Windows and console) that you can use to remove xMatters
and its components from a computer. The uninstaller can also be configured to remove all components except for the
xMatters database. Removing the database requires the proper database credentials to be specified during the uninstall
process.
Windows Uninstall
It is recommend that you stop the node and web server before starting the uninstall process.
Uninstalling xMatters | 93
To uninstall xMatters on Windows:

1. In the Windows Control Panel, double-click Add or Remove Programs.
2. Click xMatters and then click Change/Remove.
l
The Uninstall xMatters Wizard opens.
3. Click Next.
4. Specify whether to delete the xMatters database and its associated data.
l
If you are uninstalling the database, you must specify its connection settings.
5. Click Uninstall.
6. Select a restart option, and then click Done.
l
Note:
The changes will take effect after the computer has been restarted.
Uninstalling the main xMatters application does not uninstall the xMatters Phone Engine Runtime Library,
SAPI 5.1 English, or the Sentinal System Driver. Use the Add or Remove Programs tool to remove these
applications.
Console Uninstall
Before running a console uninstall, ensure that you have stopped xMatters and the Java Client.
To perform a console xMatters uninstall:
1. Navigate (cd) to the Uninstall xMatters directory within the installation directory.
2. Run the following command (where x is the version number):
./Uninstall_AlarmPoint_x -i console
3. Press Enter to continue.

4. Specify whether to delete the xMatters database and its associated data, and then press Enter.
5. If you are deleting the database, confirm the database connection parameters, and then press Enter.
6. After the uninstall has completed, press Enter.
Uninstalling xMatters | 94
About System Configuration

System Configuration items are tasks required to set up an xMatters system after it has been installed. While the majority
of these tasks need only be performed once, the changing needs of your organization may at times require you to
readjust these settings and features.
This chapter includes the following sections:
n
Login:describes how to access the xMatters web user interface.
Companies: describes how to add and define Companies.
Licenses: explains how Licenses work in xMatters, and how to add them.
Nodes: describes the two types of xMatters nodes, and how to add and define them.
Device Engines: explains how to add and define Device Engines, which control how users send and receive
notifications, and describes the different types available.
Resources: describes the different types of Node Resources, and how to manage them.
Protocol Providers: explains how to define the Protocol Providers that determine how xMatters communicates
with service providers.
User Service Providers: describes how to create and manage the service provider accounts available to users when
creating their Devices.
Authentication Process: explains the authentication methods through which users can access xMatters, and how to
configure them.
Global Configuration: describes how to set the default logging and Health Monitor settings for the xMatters
system.
Constants:explains how to create and configure scripting and other values that can be shared across the system,
within Companies, or limited to a single event source.
Schedule Jobs: explains how to schedule system tasks to take place automatically.
This chapter also includes example walk-throughs of some common configuration processes.
Note:
Login to xMatters
The web user interface allows administrators to configure and maintain the features and components of their xMatters
deployment. This section describes how to access the web user interface via the login page.
To access the xMatters web user interface, you will need a web browser, the IP address or hostname of the web server on
which xMatters was installed, and the port on which xMatters can be accessed.
To access the xMatters web user interface:
http://<IP or hostname>:<port>/xmatters/
About System Configuration | 96
xMatters login page
For example, if you wanted to access the xMatters interface using a browser installed on the same machine as the
xMatters web server, you would type the following into your browser's address bar:
http://localhost:8888/xmatters/
Companies
Companies represent the highest level of organization in xMatters. As an xMatters super administrator, you can create,
modify, and manage Companies through the xMatters web user interface.
In a multiple-Company deployment, some system components are common to the xMatters infrastructure and controllable
only by the Super Administrator. These components are not Company-specific, and include Nodes, Device Engines,
Protocol Providers, and Clusters. Other features viewable only by the Super Administrator include Component Status
Reports, Scheduled Jobs, and Clear Runtime History. Where appropriate, this document identifies whether components
are Company-specific in the section introducing and describing each component.
In an xMatters deployment with multiple Companies, each integration agent or Java Client <agent_client_id> must be
unique across the deployment (i.e., not just unique across a Company), because agent client IDs are not qualified by
Company. This restriction is the responsibility of the host Company, and is not enforced by the xMatters application. If
this restriction is violated, external service requests and messages may not be routed properly.
Note:
The number of Companies available in an xMatters deployment is controlled by your licenses.
To view and manage the Companies list:

1. Click the Admin tab.
2. On the Company menu, click Companies.
l
xMatters displays a list of the Companies currently in the system.
Companies | 97
Companies page
3. From the Current Companies list, do any of the following:

l
Note:
To modify an existing Company, click the name of the Company in the list to view its Company Details. For
more information about editing Company Details, see "Define company details", below.
To remove a Company from the list, select the check box next to the Company or Companies you want to
remove, and then click Remove Selected. For more information, see "Delete a company" on page 100.
To create a new Company, click the Add New link, and specify the Company details for the new Company,
as explained in the Company Details settings table below. Click Save to create the Company.
When you add a new Company to a multiple-Company deployment, xMatters automatically creates the default
out-of-box Event Domains, script packages, Sites, and other required settings for the new Company.
Users, Groups, and Teams in Multiple-Company Deployments

In multiple-Company xMatters deployments, all Users, Groups, Teams, Team templates, and Dynamic Teams are
Company-specific. However, identifiers are only unique within a Company, not across the entire deployment.
For example, each User within a Company must have a unique User ID, but a User in one Company might have the
same User ID as a User within another Company in the same deployment.
Define company details

You can define the details for a company using the Company Details page. Depending on your permission level, you
may not be able to view the Company Details page, or you may not be able to view all of the settings on this page.
Note:
Changes to these fields may take up to five minutes to take effect. Consider this delay when attempting to finetune any settings, especially those that involve timing during outbound phone calls.
Once the company is created, configure a login page so the companys users can access it via the xMatters web user
interface. For more information, see "Create company login pages" on page 104.
You can also create a company administrator, who can then create sites, and assign countries, time zones, and languages.
For more information, see "Company administrators" on page 239.
To modify Company details:
1. On the Companies page, in the Current Companies table, click the name of the company you want to modify.
2. On the Company Details page, enter the following information into the form:
Companies | 98
Company Details settings

Setting
Description
State
Specifies the current state of the company and controls access; select one of the following
options:
o
o
o
o
o
Active
Test
Maintenance
Assigned
Terminated
For more information about these options, see "Change company states", below.
Name
Name of the company.

Note that if you rename a company, you must also update the companyName parameter in the
signOn.jsp file, as described in "Create company login pages" on page 104.
If you are using xMatters mobile access, you must also update the mobile access component's
login.jsp file for the Company; refer to the xMatters mobile access guide for more
information.
Description
Description of the company.
Call In Number
Specifies the companys call-in number. This number appears in notifications as the number
Users should call when responding to notifications or calling in to check for Alerts.
Note: When using SIP, if the specified Call In Number is set to a valid extension found in the
Asterisk Server configuration, callouts will fail with a 403 forbidden error.
Companies | 99
Setting
Description
Short Code
Compliance
Select an option to specify when xMatters should send a notification explaining terms of
service to each SMSDevice:
l
None: xMatters will not send a notification to the Device when it is added, modified, or
activated.
Send Welcome:xMatters will send a Welcome notification to an SMSDevice when it is
added, modified, or activated. (The content of this message is defined in the
SMSCONFIRMMSG Constant.)
Send Custom: xMatters will send a Custom notification to an SMSDevice when it is
SMSFIRSTMMSG Constant.)
Send Welcome and Custom: Sends both the Welcome and the Custom messages.
In addition to modifying the content of the custom message, you can modify its behavior and
other properties using the xMatters scripts. For example, you could extend the functionality of
the custom message to include a validation request, and then select the "Send Welcome and
Custom" option. Whenever a user added a new device, xMatters would send a Welcome
message containing the standard terms and conditions, and then automatically send a
validation request to the Device three seconds later.
Note that specific content for these messages may be required by local regulations or your
SMSprovider; for more information about specifying their content, see "SMSConfirmation
and First Alert Messages Constants" on page 213.
Allow Single Sign On When selected, permits Users accessing xMatters through an authorized portal to bypass the
xMatters Sign In screen. For more information, see "Configure Single Sign On" on page 107.
Note that xMatters does not support SSO for multiple-Company deployments.
Clusters
Specifies which Clusters are available for this Company. For more information, see "Clusters"
on page 156.
3. When you are satisfied with the information you have provided, click Save.
Delete a company
When you delete a company from xMatters, all company-specific objects (groups, users, events, etc.) and data are also
deleted from the database.
Note that companies are not removed from the system immediately. Instead, they are marked as "Delete Pending" (which
is similar to the "Terminated" state), and deleted during the next scheduled removal of runtime and archive data.
Change company states

When creating or modifying a Company in xMatters, Super Administrators can specify its state to control who can
access the Company. Whenever you modify a Companys state, xMatters sends a notification email to all Company
Administrators for the Company to notify them of the change.
Companies | 100
Active
When a Company is Active, all authenticated Users, SOAP activities, event processing, and voice calls can access and
use the Company normally.
Test
When a Company is in Test state, only Company Administrators and Developers can access it via the web user
interface or through voice call-in; SOAP activities and event processing occur normally.
Maintenance
When a Company is in Maintenance state, all logins are disabled except for the Company Administrator. SOAP
activities, events, and voice call-ins are rejected with appropriate error messages and logging functions. No data is
purged from the system.
Assigned
A Company is in the Assigned state when it has been created and assigned (or branded) to a particular customer; this
is the default state when creating a new Company. Only Company Administrators and Developers can access the
Company via the web user interface or voice call-in. All messaging panel events, SOAP activities, and Java Client inputs
are rejected with appropriate error messages and logging. For testing purposes, the Quick Messaging panel can send
events and Web Services are enabled.
Terminated
Terminated Companies cannot be accessed via the web user interface; all event, SOAP, and call-in inputs are rejected
with appropriate error messages and logging; data is purged based on a manual or scheduled purge. Note that Terminated
Companies count against the Company licensing count and Company Quotas.
View and change company quotas

In single- and multiple-Company deployments, Company Administrators can view the Company Quotas page to see how
many of the available licensed resources they are using in their Company. This allows Administrators to identify if and
when they will need more licenses.
Note:
In multiple-Company deployments, Super Administrators can use the Company Quotas page to assign
resources to separate Companies in the system, as described in "Assign company quotas", below.
To view Company quotas:

2. On the Company menu, click Company Quotas.
l
xMatters displays the Company Quotas page.
Companies | 101
Single Company Quotas
The page displays the following information for the current Company:
n
Maximum number of Groups, Users, and Mobile Users available according to the current licenses.
The number of Groups, Users, and Mobile Users currently in use, and how many are remaining.
The page also displays the following information for the system:
n
Maximum available number of Devices per User.
Total number of Devices configured in the system.
Maximum number of Event Domains, custom Subscription Panels, and Integration Services available according to
the current licenses.
The number of Event Domains, Subscription Panels, and Integration Services currently in use.
Assign company quotas

For each Company in a multiple-Company deployment, Super Administrators can define quotas for the following
parameters:
l
Maximum number of Users
Maximum number of Groups
Maximum number of mobile access component Users
Number of reserved inbound SIP lines
Number of reserved in- or out-bound SIP lines
These parameters are defined on the Company Quotas page.

To assign Company quotas:
2. On the Company menu, click Company Quotas.
l
Companies | 102
xMatters displays the Company Quotas page.
Modifying Company Quotas
3. Specify the maximum number of Users, Groups, etc. for each Company in the system.
l
The table displays the number of each item you have already allocated to each Company, and the maximum
number you can have based on your licenses.
4. When you are satisfied with your changes, click Save.
Set company quotas for SIP lines

The Reserved SIP Lines column in the Company Quotas table determines the minimum level of service for each type of
SIP voice line connection. The total number of SIP lines available in a deployment is based on your licensing.
These settings are not a fixed list, but a float based on actual usage. The following points explain how the Company
quotas are calculated:
l
l
l
l
l
l
l
Note:
When a Company receives SIP calls, the lines are allocated from the quota configured in the In column. Any calls
received over that quota will use the pool values specified by the In/Out column.
When a Company makes SIP calls, the lines used are those reserved by the In/Out column.
If the Company uses more lines than the reserved quota for In or In/Out SIP lines, incoming and outgoing calls
will attempt to use any SIP voice lines or appearances not reserved by another Company:
If no outbound unreserved lines are available, outbound calls will be delayed.
If no inbound reserved and unreserved lines are available, callers will receive a busy signal and can try again in a
few minutes.
As calls are completed, existing calls are considered to be working out of the Companys reserved quotas.
If the system capacity drops below the reserved quota limits, the system logs the error and ignores the quotas; any
inbound and outbound calls will be serviced on a first-come, first-served basis.
The total quota count is determined independently of the Company state; i.e., the quotas set for a Terminated
Company still count against the total SIP lines reserved.
Example:
A multiple-Company deployment has two Companies, A and B, with a total licensed capability of 20 SIP lines, split
evenly between two Notification Servers. Each Company has reserved one In line and four In/Out lines, leaving ten
unassigned SIP lines. Consider the following scenarios:
l
Company A is using one inbound line and four outbound lines while Company B is not using any. If Company A
requires another outbound line, the line used is assigned from the 10 unreserved lines.
Company A is using five inbound lines and ten outbound lines while Company B is not using any. If Company A
requires another outbound line, the dispatch is delayed because the only available lines are reserved by Company
Companies | 103
B. If Company A requires another inbound line, the caller receives a busy signal.
l
One of the Notification Servers is taken offline temporarily. Company A is using eight outbound lines while
Company B is using two outbound lines. The quota limits are not observed.
Create company login pages

Each Company in a multiple-Company deployment requires a separate, customized login page. After you create the login
page for a Company, you can add a system message, disclaimer text, and a company logo. You can also add a logo or
other image to the header section of each page within xMatters.
It is recommended that you create and configure the Company within xMatters before creating a customized login page.
To create a company-specific login page:
1. On the xMatters web server, navigate to the following folder:
<xMatters>/webserver/webapps/cocoon/alarmpoint/jsp/login/
2. Create a new subfolder in the login directory that identifies the Company for which you are creating the login
page. Note the following requirements:
l
Use lower-case characters only, and do not include any spaces in the folder name. This is important as
different operating systems do not process white spaces and upper-case characters in the same way.
The directory name will appear as part of the web user interface path for the Company. For example, if you
create a subfolder named company_a, the URL to access the web user interface for that Company would
resemble the following (note that if you want to use the classic AlarmPoint user interface, replace "xmatters"
with "alarmpoint" in the URL):
http://company.com:8888/xmatters/company_a/SignOn.do
3. Open the ../alarmpoint/jsp/login/default directory, and copy the following files from that folder into your
new Company folder:
Note:
SystemMessage.xml
SignOn.jsp
Disclaimer.xml
Do not modify the names of the files.
4. In your new Company folder, open the SignOn.jsp file in a text or Java Script editor, and locate the following
parameter:
<signon-page companyName=""
5. Insert a value between the quote marks to match the name of the Company you created within xMatters. For
example:
<signon-page companyName="Company A"
Note:
If you change the name of the Company (e.g., via the xMatters web user interface), you must also update this
parameter in the SignOn.jsp file.
6. Save and close the SignOn.jsp file.

You can now add message text or custom logos to your Company login page.
Companies | 104
Add system messages and disclaimers

You can customize Company login pages by adding system messages and disclaimers. System messages appear below
the Company and xMatters logos, immediately above the ID and password fields. Disclaimers appear below the login
area, immediately above the xMatters copyright notice.
Both messages are visible by every User that logs into xMatters using that Company login page. You can specify a
different system message and disclaimer for each Company in the system.
To add text to the xMatters login page:
1. On the xMatters web server, navigate to the folder containing the Company login page.
l
By default, this folder is located in the

<xMatters>/webserver/webapps/cocoon/alarmpoint/jsp/login/<Company Name>/ directory.
2. To add a system message, open the SystemMessage.xml file in an XML editor, and add your message text after
the <div id="sign-on-system-message"> tag.
3. To add a disclaimer, open the Disclaimer.xml file in an XML editor, and add your disclaimer text after the <div
id="sign-on-disclaimer"> tag.
Note:
If you want to change the appearance of the system message and disclaimer text, you can format the font using
standard XML parameters and the alarmpoint.css file located in the
<xMHOME>/webserver/webapps/cocoon/alarmpoint/css/ folder.
Customize company graphics

You can customize xMatters by adding company logos or other images to the web user interface. You can use separate
graphics for the login page and the page headers, and specify a different image for each Company in xMatters.
Add login page graphics
By default, xMatters looks for an image file named customer-logo.png in the following directory on the web server:
<xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/login/<Company Name>/
If the file exists, xMatters automatically displays the file within the login dialog on the login page for that Company.
To display an image on the login page, rename your image file to customer-logo.gif (use an image editor to convert the
file format if necessary) and copy it into the default directory on the xMatters web server. Note the following
recommended guidelines:
n
File size: There are no restrictions on the file size of the image, but larger files may affect the loading time of the
login page, depending on the available resources and number of concurrent logins.
Image size and resolution: For best results, use a high-resolution image 70 to 80 pixels tall and 80 to 100 pixels
wide. Because the image is relatively small, the higher resolution should not adversely affect the size of the file,
and loading times will not be an issue. Images larger than 80x100 pixels may displace other login page elements
and result in misaligned components.
To use a different image name or file type, open the /alarmpoint/jsp/login/<Company Name>/SignOn.jsp file and
locate the following code:
<div class="sign-on-logo-container">
<% if (application.getResource("/alarmpoint/" + loginPath + "/customer-logo.png") != null) {
%>
<table class="alarmpoint-logo">
<tr>
<td class="small-logo">
<img class="customer-logo" src="<%="/static/" + loginPath + "/customer-logo.png"%>"
/>
</td>
...
Companies | 105
</tr>
</table>
<% } else {%>
</div>
Change both occurrences of customer-logo.png to the file name of the image you want to display on the login page.
Add page header graphics
By default, xMatters looks for an image file named customer-logo2.gif in the following directory on the web server:
<xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/login/<Company Name>/
If the file exists, xMatters automatically displays the file within the page header of all pages for that Company.
The page header graphic is automatically scaled to 29x29 pixels, which may cause your image to distort if it is not
square.
To use an image wider than 29 pixels, you can edit the
<xMatters>/webserver/webapps/cocoon/alarmpoint/css/alarmpoint.css file. Locate the following section:
div.customer-banner-logo img {
z-index: 100;
position: absolute;
left: 6px;
top: 45px;
height: 29px;
width: 29px;
}
Edit the width line to specify the width of your image; for example, if you want to use an image that is 100 pixels
wide, change the line to the following:
width: 100px;
It is recommended that you do not use an image taller than 29 pixels, as larger images will skew the alignment of the
other header components.
To use a different image name or file type, open the /alarmpoint/sitemap.xmap file and locate the following code:
<map:action name="add-customer-logo"
src="com.invoqsystems.apex.web.cocoon.actions.AddCustomerLogoAction">
<map:parameter name="imageName" value="customer-logo2.gif"/>
</map:action>
Change the value for the map:parameter to the file name and type of the image you want to use.
Customize the login error message

When a User requests a URLthat does not have an existing custom SignOn.jsp (i.e., a customized Company login page),
xMatters displays the following default error message: "Requested login page not found. Ensure the URLwas entered
correctly." You can change the text of this error message to provide Users with more information.
To customize the login error message:

1. Navigate to the <xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/login directory.
2. Open the NotFound.xml file in a text editor.
3. Do one or both of the following:
l
To modify the title of the message, replace the signon.title.not.found key with the appropriate text.
To modify the message replace the signon.error.not.found key with the appropriate text.
Companies | 106
Configure Single Sign On

The Single Sign On (SSO) authentication method permits users to access pages in xMatters directly without first logging
in via the Sign In page. This method uses an external authentication module, and supplies an authentication string to
xMatters.
Note:
xMatters does not currently support SSO with xMatters on demand or xMatters enterprise deployments with
multiple Companies.
To use SSO authentication, the following criteria must be met:

n
A customer authentication module or portal authenticates the User independently of xMatters.
An HTTP Request passes HTTP headers (usually via a proxy server) containing the users web login ID and
authentication status to xMatters.
The user ID included in the HTTP header must exist in the xMatters database and be authorized to access
xMatters.
Note:
Before configuring SSO, ensure that the Allow Single Sign On check box is selected on the Company's details
page in the web user interface.
The HTTP headers must contain the following three lines:

HTTP_SM_AUTHENTIC = YES
HTTP_SM_AUTHORIZED = YES
HTTP_SM_USER = <User web login ID>
Note:
The HTTP_ portion of the header lines is optional, but all three lines must use the same convention.
When the criteria have been met, users can directly access any page that is normally accessed via the main xMatters
menus on the left side of the screen. For example, a user authenticated with SSO can navigate directly to their Active
Alerts page using the following URL:
<xMattersIP>/xmatters/Alerts/ActiveAlerts/ActiveAlerts.do
Note that the semi-colon and the session information that follows in the URL shown in your browser is not included in
the URL initially used to load a page using SSO.
To reach the Sign In page and log in to xMatters as a different user when an SSO deployment portal is in place, click the
Sign Out link at the top of any page. You can then sign in using any authorized xMatters web login ID and password.
xMatters also redirects to the default Sign In page in any of the following circumstances:
n
The user web login ID specified in the HTTP header does not exist in the xMatters database.
A user has been authenticated via SSO, but the Company is not configured to permit SSO access.
The page specified in the URL does not exist in xMatters.
If the user authenticated by SSO does not have permission to view the page specified in the URL, xMatters redirects
them to a standard access denied page. If the user accesses xMatters through the default URL, xMatters redirects them
automatically to their home page.
Configure SSO header variable names

By default, xMatters is configured to use SiteMinder Web Access Manager SSO headers; i.e., SM_AUTHENTIC, SM_
AUTHORIZED, SM_USER. You can modify the SSO header names that xMatters expects by adding a new properties
file and setting the modified header names as required.
Note:
These steps must be carried out on all web servers in your xMatters deployment.
Companies | 107
To change the SSO header variables:

1. Navigate to the <xMHOME>/webserver/webapps/cocoon/WEB-INF/classes folder and open the
default.properties file in an editor.
l
The properties file contains the following settings:
sso.config.authenticateHeader=SM_AUTHENTIC
sso.config.authorizedHeader=SM_AUTHORIZED
sso.config.userHeader=SM_USER
2. Modify the value entries as necessary and save the file as custom.properties.
Note:
Do not overwrite, delete, or modify the default.properties file; make changes to the custom.properties
file only.
3. Restart the web server.
Map tenant user logins

In a multiple-company deployment, one company (the Default Company created during initial installation)acts as a host
Company, and any other Companies in the system are considered to be "tenant" Companies. The "Service Provider
Support" Role can be assigned to Users in the host Company that you want to be able to log in to tenant Companies and
perform maintenance or testing functions. Only Users in the host Company may be assigned the Service Provider Support
Role; this means that a User from one tenant Company cannot log in to another tenant Company.
Logging in to a tenant Company is similar to the logging in as another User feature available to Company
Administrators (see "Log in as another user" on page 241): the Service Provider Support User, also referred to as an MSP
User, logs in to the tenant Company as an existing User. Once they have logged in, they view and interact with the web
user interface exactly as that User would. Any actions performed while logged in as that User are logged as being
performed by the MSP User on behalf of the tenant User.
While logged in to a tenant Company as an MSPUser, you can also add Users, Devices, Groups, and Dynamic Teams
from the host Company to Groups within the tenant Company. These host Company Group members are identified as
coming from the host Company; their details cannot be viewed or modified by Users or Administrators from within the
tenantCompany.
Each MSPUser account can be mapped to a single User account in a tenant Company. Note that this is a strict one-toone mapping between Users; the host Company User cannot be mapped to more than one tenant Company User, and the
tenant Company User cannot be used by, or mapped to, more than one MSPaccount.
Note:
Tenant Company Users who are mapped to a Service Provider Support User in the host Company cannot have
Devices assigned to them.
While the Service Provider Support Role cannot be assigned to a Company Administrator, MPS Users in the host
Company can be mapped to Company Administrators in a tenant Company, provided the Company Administrator does
not have any Devices assigned to them.
To map Service Provider Support Users to tenant Company Users:
1. Log in to the host Company as a Company Administrator, or a User with the Service Provider Admin Role, and
then click the Users tab.
2. Create a new User with the Service Provider Support Role, or assign the ServiceProvider Support Role to an
existing User that you want to be able to log into a tenant Company.
3. On the User's details page, in the Common Tasks menu, click Tenant Company Users.
l
Companies | 108
xMatter displays the Users Mapped for <User>page.
Tenant Company User Mapping
4. On the User Mapped page, do one of the following:

n
Start typing the name of a tenant Company User in the Add User field; when the User's name appears, click
it to assign the User mapping.
Click the Advanced Search link to specify a Company and then use the User Search dialog to locate the
User you want to assign.
5. To remove a mapping, select the check mark for the mapping, and then click Remove Selected.
The mapped host Company User can now use the Log In As User feature to log into the tenant Company as the tenant
Company User. For more information about this feature, see ."Log in as another user" on page 241
Licenses
You can view and add xMatters licenses using the Active Licenses page. Licenses determine what features are available,
how many users can access the system, the number of available Nodes, and so on.
For more information about Licenses and their function in xMatters, see "xMatters Products, Licensing, and Deployment
Options" on page 20.
If you apply a multiple-Company deployment license to an xMatters installation that has merged Administrator accounts,
the merged accounts are converted to Company Administrator accounts and a new Super Administrator account is
created. Note that a merged Administrator account can receive and respond to notifications, and counts towards the
license limit of Users in the system. With non-merged accounts, the Super Administrator cannot be notified and does not
count towards the license limit.
Note:
All Users in the xMatters database count towards the license limit. This means that Users not set as Active (i.e.,
on their User Details page) are still counted for licensing purposes. For further details on xMatters licensing,
contact xMatters Sales.
Licenses are distributed by xMatters in one of two ways: a short string of numbers and letters, which is used to add a
single feature, or a text file containing a list of strings, which is used to add a number of features or to upgrade the
deployment to a new version; e.g., upgrading from xMatters lite to xMatters workgroup.
To apply a license file:
1. Log in to xMatters as a Super Administrator.
2. Click the Admin tab, and then click Active Licenses.
l
xMatters displays the Active Licenses page.
Licenses | 109
Active Licenses page
3. On the Active Licenses page, do one of the following:

l
To add a license code for a single feature, click the Add New link. On the Add License page, type the
license key into the License Code field, and then click Save.
To add license codes from a file, click the From File link. On the Add License page, click Browse, and
locate the license file on your machine or network. Click Open, and then click Upload to apply the license
file. After the license file or license key is applied, xMatters displays an updated Licenses list.
To export your list of active licenses to a spreadsheet (e.g., to send to xMatters Support for help when
troubleshooting an issue), click the Export link. xMatters will export the licenses to an Excel spreadsheet
and the browser will then prompt you to save it to your local computer.
4. Restart all Application Servers, Notification Servers, and web servers.
License expiry warnings

xMatters will begin displaying a license expiry warning pop-up window when your license has 60 days remaining. For
Super Administrators, these pop-ups appear on the Companies page for multiple-Company deployments, or on the Active
Licenses page. For Company Administrators, the pop-up appears on their profile page when they log in to the web user
interface.
When the warning appears, you can choose to be reminded at a later date, but you cannot postpone the warning beyond
the expiry date.
Nodes
There are two kinds of nodes in xMatters:
Nodes | 110
Node Types
Node Type
Description
Application
Server
Receives events and converts them into notifications. Application server nodes may also contain
device engines.
Notification
Server
Contains device engines, solely responsible for delivering notifications and receiving responses
from devices.
Note:
For deployments with multiple nodes, the time zone for the operating system must be synchronized across all
application server nodes and web servers. For more information, see "Multiple Node Deployment
Considerations" on page 34
Failover
Depending on its licensing, an xMatters installation can include up to three application server nodes. When multiple
application servers nodes share the database, they are considered to be in failover configuration. Note that Clusters do
not affect failover; they are used strictly to specify message routing preferences.
Node failure detection
Every 10 seconds, each Application Server timestamps the database. At the same rate each application server examines
the timestamps of other application. If the last timestamp of a node is more than 30 seconds old, that node is considered
to have failed. The node that detects this assumes ownership of the processes of the failed node.
Undelivered Alerts
Alerts within the xMatters system are stored only in the database. If an Application Server Node fails, its Alerts remain
in the database until the Application Server Node restarts, or another Node detects its failure.
Note:
Whenever failover occurs, an email Alert is automatically sent to the recipient specified in the Health Monitor
settings. For more information, see "Global Configuration" on page 198.
View and manage nodes

You can modify node details using the xMatters web user interface.
To view and manage nodes:
2. On the Administration menu, click Nodes & Device Engines.
l
xMatters displays a list of the nodes currently in the system.
Nodes page
Nodes | 111
3. Note the Status column that indicates whether the Node is active (green check mark), or inactive (red 'x'); an
inactive Node cannot process notifications.
4. In the All Nodes list, do any of the following:
l
To modify an existing Node, click the name of the Node in the list to view its Node Details. For more
information, about editing Node Details, see "Define node details", below.
To remove a Node from the list, select the check box next to the Node you want to remove, and then click
Remove Selected.
To view and manage the list of Device Engines for a Node, click the Device Engines link in the View
Components column. For more information about adding and managing Device Engines, see "Device
engines" on page 118.
To view and manage the Resources for a Node, click the Resources link in the View Resources column. For
more information about adding and managing Resources in Nodes, see "Resources" on page 150.
To add a new Node, click the Add New link, and then select the type of Node you want to add from the
drop-down list. Click Continue to specify the details for the new Node. For more information about the
types of Nodes, and the specific details for each type, see the tables in "Define node details", below.
Nodes must be installed using the xMatters installer. You can add a Node in the web user interface before
installing it, but you must still run the installer against the target machine using the "Use Existing Node"
option; for more information, see "Installing xMatters" on page 63.
Note:
Activity states
The list identifies the possible values for the All Nodes table's "Activity States"column, and provides an explanation of
what each value means.
n
Running:Indicates that the Node is active, and maintaining its scheduled heartbeat activity with the xMatters
database.
Stopping:Indicates that the Node is in the process of completing required tasks in preparation for shutting down.
This status is usually the result of stopping the Node manually.
Stop: The Node has been successfully stopped or shut down, and is no longer processing notifications or
communicating with the database.
Warning:The Node is still running, but has not successfully completed a heartbeat with the database for more
than 30 seconds.
Unreachable:The Node has not successfully completed a heartbeat with the database for more than 60 seconds.
At this point, xMatters no longers considers the Node to be active, and will change its status to Inactive. Should
the heartbeat function resume, xMatters will reactivate the Node automatically.
Configure the maximum node shutdown timeout

Once the node manager receives a shutdown command, it tries to shut down all components in an orderly manner. By
default, if the manager cannot shut down a component after five minutes, the node will be terminated regardless of the
issue. However, if this five minute maximum node shutdown timeout is not appropriate for your environment, you can
modify it.
To modify the maximum node shutdown timeout:
1. If you do not already have a custom.properties file, copy (and rename) the custom.properties.sample file (located
at <xMHOME>\node\config\) to <xMHOME>\node\config\custom.properties.
2. Open the copied file in a text editor and add the following line (where <seconds> is the maximum number of
seconds to wait before shutting down the node):
nodeManager.shutdownTimeout=<seconds>
3. Save the file and restart the node.
Nodes | 112
Define node details

There are two types of nodes in xMatters; this section explains how to define each type of Node.
Define an application server node
Application Server Nodes are responsible for receiving events and translating them into notifications. Once the
notifications are prepared, the Application Server Node either delivers them via an integrated Device Engine or forwards
the notifications to a remote Notification Server Node for delivery to the appropriate Devices.
To modify Application Server Node details:
1. On the Nodes & Device Engines page, in the All Nodes table, click the name of the Node you want to modify.
l
xMatters displays the Node details:
Application Server Node details
2. On the Application Server Node Details page, enter the following information into the form:
Detail
Description
Callback Number
Type the phone number Users should call when responding to notifications sent by this Node.
Nodes | 113
Detail
Description
Active
Select this check box to activate the Node, or clear the check box to disable the Node.
Identifier
Type a unique identifier for the Node to be stored in the configuration database.
Description
Type a few words or a phrase that describes the Node. (Optional)
Select Cluster
Specify the Notification Server Cluster which will contain this Node. For more information, see
"Clusters" on page 156.
Client Connections
Maximum number of Java Clients that can connect simultaneously. This value is licensecontrolled.
Host
Specify the externally-addressable hostname or IP for this Node. (Used for inter-node
communications.)
Port
Type the port number to use for inter-node communications.
Hub Port
Type the port number to listen on for Java Client connections.
LOGGING
For an explanation of the Logging settings for Nodes, see "Configure node logging" on page
117.
Executable
Fully-qualified path to an executable file to launch whenever a Health Monitor event occurs
("C:\Working Folder\myScript.bat" will run a batch file; on a Linux node computer,
"/home/user/myScript.sh" runs a shell script). Note that the Health Monitor does not accept
parameters. For more information on the Health Monitor and the conditions that trigger an event,
see "About the Health Monitor" on page 198.
Defining a Notification Server Node
Notification Server Nodes contain Device Engines, which are responsible for sending notifications and receiving
responses via service providers and device protocols.
Note:
For more information about Device Engines, see "Device engines" on page 118.
To modify Notification Server Node details:

1. On the Nodes & Device Engines page, in the All Nodes table, click the name of the Node you want to modify.
l
Nodes | 114
xMatters displays the Node details.
Notification Server Node details
2. On the Notification Server Node Details page, enter the following information into the form:
Detail
Description
Callback Number
Type the phone number Users should call when responding to notifications sent by this Node.
Note: If a Call In Number is specified for the Company (as described on "Companies" on page
97), that number will take precedence over this setting.
Active
Select this check box to activate the Node, or clear the check box to disable the Node.
Identifier
Type a unique identifier for the Node to store in the configuration database.
Description
Type a few words or a phrase that describes the Node. (Optional)
Select Cluster
Specify the notification server cluster which will contain this Node.
Host
Specify the externally-addressable hostname or IP for this Node. (Used for inter-node
communications.)
Port
Type the port number to use for inter-node communications
Nodes | 115
Detail
Description
Logging
For an explanation of the Logging settings for Nodes, see "Configure node logging" on page
117.
Executable
Fully-qualified path to an executable file to launch whenever a Health Monitor event occurs.
For more information on the Health Monitor and the conditions that trigger an event, see "About
the Health Monitor" on page 198.
When a Notification Server Node is created using the web user interface, the displayed node status may remain
listed as "Not Deployed". To resolve this, delete the Node in the web user interface and recreate it using the
xMatters installer.
Note:
Tune your node's performance

You can improve the performance of xMatters notification and application server nodes by:
n
increasing the size of the database connection pool;
distributing device engine threads based on notification traffic;
adjusting the maximum session size for protocol providers.
The next sections describe these processes in detail.
Increase the database connection pool

If you are deploying against a production-grade database such as Oracle 11g or SQL Server, you can tune xMatters for
increased throughput by optimizing the connection pool configuration for your deployment. For information on
adjusting the database connection pool settings, see "Configuring the Database Connection Pool" on page 357.
Distribute device engine threads

You can optimize the throughput of your xMatters node deployment by configuring the Concurrent Threads settings of
the Device Engines. By distributing threads based on the amount of notification traffic each protocol receives, you can
balance the workload across the Device Engines that handle the most notifications. For example, if email is the most
common notification method, allocate the most threads to your email Device Engines.
You can adjust the settings for the Device Engines within the xMatters web user interface.
Note:
The Active Licenses control the maximum number of threads allowed, and the number of threads per Device
Engine.
Adjust maximum session size

You can help optimize the throughput of your xMatters node deployment by adjusting the maximum session size for
Protocol Providers.
The session size represents the number of notifications transacted within a single session. For example, if you set the
maximum session size of an email Protocol Provider to 20, and there are at least 20 notifications to dispatch, the Device
Engine connects to the email server, sends 20 notifications, and then disconnects.
To tune the performance of Protocol Providers, ensure that the session size is as large as possible for each Protocol
Provider in use. For email providers in particular, a session size of 20 to 50 is recommended.
Nodes | 116
Practice economical scripting

There are several ways an Administrator can manage the scripts to improve event throughput. In particular, many of the
out-of-the-box script packages contain external service requests and messages which may or may not be of value to a
particular deployment.
Because the creation and dispatch of an external service request or message comes with significant overhead, any
unnecessary external service requests or messages should be removed.
For example, in the default script the following situation is reported to the integration point:
$reportedFailure = @session::reportFailure($liveNotificationId,
"USER_HUNG_UP_AFTER_AUTHENTICATION")
@hangupEventMessage = @event::createExternalServiceMessage()
$hangupEventMessage.message = "Callout to " & $targetName & " ended
prematurely (USER_HUNG_UP_AFTER_AUTHENTICATION)."
@hangupEventMessage::send()
If this event is not of interest, this portion of the script should be removed. For more information about scripting in
xMatters, refer to the xMatters Online Developer's Guide.
Configure node logging

xMatters can create separate log files with details of all the transactions and communications for each Node. This section
explains the levels of logging available, and how to configure the Node log settings to adjust the logging output.
Configuration levels
There are three configuration levels within xMatters: Global, Node, and Device Engine. Most configuration settings
apply to only one level, but logging settings are an exception. Logging settings affect multiple levels, and changes on
one level may interact with or affect settings on another level.
Interactions between log settings take one of two forms: inherit or override. Lower-level components inherit the log
settings of higher-level components; that is, Device Engines inherit log settings from the Node to which they belong,
and Nodes inherit log settings from the global configuration. If you change the log level settings for a lower-level
component, you override the settings inherited from the higher-level component. If you then change a log setting at a
higher level, the change affects only the higher-level component.
For example, if you set a Nodes log level to Normal, all Device Engines for the Node inherit the Normal log level. If
you change the log level for a specific Device Engine to Detailed, then the log setting for the Device Engine overrides
the setting inherited from the Node. If you then turn off the global logging, the log settings for the Node and Device
Engine remain unchanged.
You can specify the logging settings for each Node independently when you add a Node or modify the details for an
existing Node. The settings described in the following table are available on the Details page for each Node:
Node Logging Settings
Detail
Description
Log Directory
Location to store the log files.
Script Log Directory
Default location to store log files created by logging within scripts. Some scripts
may override this location.
Nodes | 117
Detail
Description
Log Level
Level of detail required for the log files.

xMatters uses the logging utility log4j, in which log levels are assigned to
messages based on their severity. Select from the following options to specify the
minimum severity level of messages to record in the logs:
o
o
o
o
o
o
o
o
Off: no logs are generated.

Fatal
Error
Normal (Warn): logs include standard runtime output. (This option is
equal to the Normal setting available in previous versions of xMatters.)
Info
Debug
Trace
Detailed (All): logs include all debugging information, and line-by-line
script interpretation. (This option outputs a high volume of data; use with
discretion.)
The logs record any messages flagged with the specified severity level or higher.
For example, if you select Info, the logs will include all messages flagged with
Info, Warn, Error, and Fatal.
Note that more detailed log levels produce log files that cover a shorter time
period.
Detailed Statistics Logging
Includes detailed component statistics, such as queue size and average execution
times, in the log files. Note that enabling this feature can negatively impact
performance.
Enable XML logging

In some versions of xMatters, XML logging on nodes is disabled by default (this can increase performance in highthoughput scenarios). However, you can enable XML logging after installing xMatters and parse the resulting log files
with tools such as Chainsaw (the files are in standard log4j XML format).
To enable XML logging on a node:
1. Open the node's applicationContext.xml file in a text editor and change the logManager bean property usesXml
setting to true.
2. Open the node manager's nmApplicationContext.xml file in a text editor and change the nodeLogManager bean
property usesXml to true.
n
The node also has redirection for the STDOUT and STDERR streams into special log files, but they cannot
currently be output in XML format.
Device engines
Device engines are components that deliver notifications to different types of devices and, where applicable, receive and
process two-way replies and relay them to xMatters.
Each device engine implements a different protocol, and each protocol requires a dedicated device engine. When the
device engine is started, the protocol will be passed as a parameter and the device engine runs in that protocol mode.
Device engines | 118
To view and manage device engines:

1. Click the Administration tab.
2. In the Administration menu, click Nodes & Device Engines.
3. In the All Nodes table, click the Device Engines link in the View Components column for the Node you want to
modify.
l
The Node Components page displays a list of any Device Engines assigned to that Node.
Node Components page
4. In the All Components for Node list, do any of the following:

l
To modify an existing Device Engine, click the name of the Device Engine in the list to view its details. For
more information about editing Device Engine details, see the following section, "Device Engine Types" on
page 120.
To remove a Device Engine from the list, select the check box next to the Device Engine you want to
remove, and then click Remove Selected.
To add a new Device Engine, click the Add New link, and then select the type of Device Engine you want
to add from the drop-down list. Click Continue to specify the details for the new Device Engine. For more
information about the types of Device Engine, and the specific details for each type, see the tables in the
following section, "Device Engine Types" on page 120.
Start and stop device engines

You can start or stop a device engine at any time.
To start or stop a device engine:
1. On the Nodes & Device Engines page, in the All Nodes table, click the Device Engines link for the Node you
want to modify.
2. In the All Components for Node table, select the check boxes beside the components you want to stop or start.
l
You can see the current status of each component in the Activity State column.

l
Click Start Selected Components.
Click Stop Selected Components.
Enable device engine logging

Device engines in xMatters can create separate log files with details of all their transactions and communications.
You can specify the logging settings for each Device Engine independently, and set the logging details when you add a
Device Engine or modify the details for an existing Device Engine. The settings explained in the following table are
available on the Details page for each Device Engine:
Device Engine Logging Settings

Detail
Description
Generate Separate Log File Generates a separate log file for the current Device Engine.
Level of detail required for the log files.
Log Level
Note that more detailed log levels produce log files that cover a smaller window of time.
Expanded MAPI Logging
To assist in troubleshooting MAPI issues, additional logging has been added for the library file used by MAPI Device
Engines. Any activity that occurs in alarmpoint_mapi.dll is written to a log file located at:
<xMatters>/logs/mapi_dll_log.txt
The maximum size for this log file is 10MB, after which it is rolled over into a single backup file named mapi_dll_
log1.txt.
Configure concurrent threads

You can optimize the throughput of your xMatters node Deployment by configuring the Concurrent Threads settings of
the Device Engines. By distributing threads based on the amount of notification traffic each protocol receives, you can
balance the workload across the Device Engines that handle the most notifications. For example, if email is the most
common notification method, allocate the most threads to your email Device Engines.
Note:
Your Active Licenses control the maximum number of threads allowed.
Device Engine Types

The following tables describe the settings required for each type of Device Engine.
BES Device Engines

BES Device Engines enable xMatters to send notifications to and receive responses from service providers using the
BlackBerry Enterprise Server (BES) protocol for BlackBerry Devices.
BES Device Engine details
Details
Description
Name
Name used to identify this Device Engine.
Description
Brief description of this Device Engine (optional).
Notification Polling How often (in seconds) the Device Engine polls the notification node for new alerts. Must be a
whole number greater than or equal to 10 and less than or equal to 300.
Concurrent
Threads
Number of requests or tasks that this Device Engine can run at the same time. Your Active
Licenses control the maximum number of available threads.
Logging
For an explanation of Device Engine logging, see "Enable device engine logging" on page 119.
To use BlackBerry Enterprise Server notifications with xMatters:

1. Start the xMatters Developer IDE and set up the Database Connection. (For more information about installing,
configuring, and using the xMatters Developer IDE, refer to the xMatters Online Developer's Guide.)
2. Check out the script packages for the event domains you want to configure.
Note:
The following steps have to be applied to each of the Event Domains you want to use with xMatters and BES
notifications.
3. If you upgraded from a version prior to xMatters 3.1, add the following code to each of the presentation scripts (If
you are working with a new installation, skip this step.):
ELSE-IF ($content.deviceclassification == "bes")
@recipient = @event::getRecipient($content.recipient_target)
$recipientCategory = @recipient::getRecipientCategory()
IF ($recipientCategory == "DEVICE")
@person = @event::getRecipient($recipient.owner)
$userId = $person.id
ELSE
$userId = $recipient.id
ENDIF
$content.subject = "xMatters Message: " & $event.incident_id
$content.message = "Message"
#Fill the html part for BES device
#Note: content.pushurl must be present, even if url is invalid
$content.pushurl = "http://localhost:8888/static"
$content.pushtitle = $content.subject
$content.htmlmessage = $content.htmlmessage & "<table width=\u0022100%\u0022
border=\u00221\u0022>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Situation</b></td><td>" &
$content.situation & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Device</b></td><td>" &
$content.device & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "<tr><td><b>Time of Incident</b></td><td>" &
$userTime & "</td></tr>"
$content.htmlmessage = $content.htmlmessage & "</table>"
IF (EXISTS($content.choices))
$content.htmlmessage::add("<br>Your response choices are:")
#Change the URL to point to your web server
$content.htmlmessage::add("<P><SELECT name=\u0022responseChoice\u0022>")
FOR ($choice : $content.choices)
$content.htmlmessage::add("<OPTION>")
$content.htmlmessage::add($choice)
$content.htmlmessage::add("</OPTION>")
ENDFOR
$content.htmlmessage::add("</SELECT><br />")
$content.htmlmessage::add("<input type=\u0022hidden\u0022 name=\u0022notificationId\u0022
value=\u0022" & $content.notification_key &"\u0022>")
$content.htmlmessage::add("<input type=\u0022hidden\u0022 name=\u0022userId\u0022
value=\u0022" & $userId & "\u0022>")
$content.htmlmessage::add("<input type=\u0022hidden\u0022 name=\u0022deviceType\u0022
value=\u0022BES\u0022>")
$content.htmlmessage::add("<br><INPUT type=\u0022submit\u0022
value=\u0022Respond\u0022><INPUT type=\u0022reset\u0022></P></FORM>")
ENDIF
Note:
The above code applies to the default script package. For other script packages refer to the out-of-the-box
script packages delivered with xMatters.
4. In each of the presentation scripts, locate the following line and change localhost in the URL to the fully
qualified domain name of the xMatters web server.
#Change the URL to point to your web server
Note:
The URL must be in this form so a Blackberry Device can access it from its browser.
5. Save and validate the script, update the version number, and check in the script package.
6. Repeat steps 3 to 6 for each of the script packages you are planning to use in xMatters.
DTMF Device Engines

DTMF Device Engines enable xMatters to send notifications to service providers using Dual Tone Multi-Frequency
(DTMF) tones, which are keypad tones entered by a User from a voice telephone.
DTMF Device Engine details
Details
Description
Name
Description
Logging
Generic Device Engines

Generic Device Engines are provided to enable the integration of proprietary, in-house, or other protocols not currently
included with xMatters.
Generic Device Engine details
Details
Description
Name
Description
Concurrent
Threads
Logging
GSM Device Engines

GSM Device Engines enable xMatters to send notifications to and receive responses from service providers using an
SMS protocol.
For most protocols, the connection is transient, and each notification contains the required provider information. GSM
providers are different in that they require that connections are constantly established. In xMatters, this means that the
provider configuration must be performed at the Device Engine level, rather than the Protocol Provider level.
GSM modem technical issues

There are some technical considerations when using a GSM modem:
n
You can use remote antennas, as there may not be cellular reception in the data center.
GSM often has the lowest priority on a network, and message delivery can be substantially delayed (perhaps for
hours).
SMPP, SNPP, and WCTP are preferred methods of supporting two-way SMS, if the cellular provider supports these
protocols.
Many of the cellular service providers do not support two-way communications with other cellular service
providers, particularly providers in the United States. Select the provider for your GSM modem based on the
people with whom you need to communicate.
During implementation, delivery and response times have been unpredictable. Single delivery, and turnaround time
for a two-way message, has taken anywhere from a minute to several hours. SMS provides no confirmation on
receipt, meaning the message can get "lost" (without the sender being told) and can take hours to deliver. This
must be taken into consideration if you plan to use this as a method of critical event notification.
The Notification Polling setting specifies how often the Device Engine should check for new notifications. The
Polling Interval setting specifies how often the Device Engine should check for responses. If the Device Engine
attempts to do both at the same time, it causes a resourcing conflict, and the GSM modem cannot send any
messages. You can avoid this conflict by configuring the polling intervals so they do not overlap. For example, the
default setting for Notification Polling is 10 seconds. If you want to keep this default setting, the recommended
Polling Interval setting for the first serial device is 13 seconds.
GSM Modem Device Engine details

Detail
Description
Name
Description
Notification
Polling (sec)
How often (in seconds) the Device Engine polls the notification node for new alerts. Must be a
whole number greater than or equal to 10 and less than or equal to 300. (See related point in
GSM modem technical issues, above.)
Logging
Session Timeout
(min)
Length of time in minutes before the session times out. To have every session time out, enter 0.
To have sessions never time out, enter a negative value.
Carrier Wait
Time
How long, in seconds, to wait for provider to prepare before commencing transmission of
notifications.
Response Wait
Time
How long, in seconds, to wait for a response from the provider.
Detail
Description
Notification Key
String included in the body of the notification that identifies the original alert or notification to
which the User is responding.
Normally this key is enclosed with delimiting characters; e.g., the default value,
<%Notification Key%>.
If the delimiting character sequence is not guaranteed to be unique, the Device Engine may make
an incorrect match, causing an exception and response failure.
If you have configured simple SMSreplies, as described in "Configure simple SMS replies" on
page 143, this field is disabled.
If no delimiters are present, the first word of the response will be used as the notification key. If
the delimiters occur more than once in the body of the notification, the first instance is used as
the notification key.
Response Key
String included in the body of the notification that identifies the beginning of the response
portion of the Users return message.
Choice Message
Portion of the notification message that defines User options.

Response Message
Portion of the notification message that contains the response instructions.

page 143, this field should be changed to reflect the new response process. The recommended
value is "Reply %RESPONSECHOICES%".
Detail
Description
Serial Devices
This area displays an editable list of serial device resources available to the GSM Modem Device
Engine. Click Add New Device to create a new serial device, and specify the following settings:
o
o
o
o
o
o
o
o
o
o
Serial Port: Port to use to connect to the GSM modem (e.g., Windows: COM1, COM2,
etc.; Unix: /dev/ttyS0, /dev/USB0, etc.)
Init String: Initialization string or code required for the GSM modem.
Baud Rate: GSM modems baud rate.
Databits: GSM modems databits setting.
Stop Bits: GSM modems stop bits setting.
Parity: GSM modems parity setting.
Flow Control: GSM modems flow control setting.
Sim Pin: If required, the personal identification number for the SIM card in the GSM
modem.
Mode: Messaging mode supported by the GSM modem.
Polling Interval: How often, in seconds, the Device Engine polls the modem for responses
to notifications. (See related point in GSM modem technical issues, above.)
To remove a serial device, select the check box next to the device you want to remove, and then
click Remove Selected Devices.
Known Good Configurations
The following represent known good configurations for the indicated GSMmodems. Settings marked "Deploymentspecific" should be configured to reflect the needs of your deployment.
Note:
These known good configurations are only meant to provide examples of working deployments; your
deployment may require different configuration values.
Wavecom Fastrack GO
Setting
Configured Value
Name
(Deployment-specific)
Description
Notification Polling (sec)
10
Logging
Session Timeout (min)
-1
Carrier Wait Time
120
Response Wait Time
Notification Key
Setting
Configured Value
Response Key
Choice Message
Response Message
Serial Devices
o
o
o
o
o
o
o
o
o
o
Serial Port: COM3

Init String: AT
Baud Rate: 115200
Databits: 8
Stop Bits: 1
Parity: NONE
Flow Control: NONE
Sim Pin: <Empty>
Mode: ASCII
Polling Interval: 61
HTTPClient Device Engines

HTTP Client Device Engines allow you to integrate xMatters with web-based APIs that accept HTTP GET/POST with
xMatters; this Device Engine is intended for use with HTTPxMatters SMSand HTTP Generic Protocol Providers.
Configuration notes:
n
HTTPClient Device Engines support HTTPGETand HTTPPOST operations, which allow you to create requests
consisting of name/value pairs and send to them to a protocol provider.
The Device Engine does not include a separate or dedicated web server. It uses the xMatters web server to handle
responses.
Responses and other settings are configured using the related HTTPprotocol providers:
l
"HTTP Generic Protocol Providers" on page 166
"HTTP xMatters SMSProtocol Providers" on page 168
HTTPClient Engine details

Details
Description
Name
Description
(sec)
Concurrent
Threads
Details
Description
Response Message
Portion of the notification message that contains the response instructions.

Guidelines:
n
This field should inform Users that when responding to a plain-text alert, they should type
the keyword RESPONSE in the subject line, followed by a single space, and then one of
the options listed. For example, they might respond with "RESPONSE ACCEPT".
Also note that this response should be the only text in either the subject of the email, or
the first line in the body of the email message.
If you have configured simple SMSreplies, as described in "Configure simple SMS replies"
on page 143, this field should be changed to reflect the new response process. The
recommended value is "Reply %ResponseChoices%".
If you are configuring this Device Engine to work with a fax provider (e.g., Phaxio), the
response instructions should indicate that Users should not attempt to fax their response
back to xMatters, but should instead call in, or log in to the web user interface, to respond.
Logging
HTTPVoice Device Engines

HTTP Voice Device Engines allow you to integrate xMatters with web-based APIs that accept voice calls via HTTP
GET/POST; this Device Engine is intended for use with HTTPxMatters Conference and HTTP Conference Protocol
Providers.
Configuration notes:
n
HTTPVoice Device Engines support HTTPGETand HTTPPOST operations, which allow you to create requests
consisting of name/value pairs and send to them to a protocol provider.
The Device Engine does not include a separate or dedicated web server. It uses the xMatters web server to handle
responses.
Responses and other settings are configured using the related HTTPprotocol providers:
l
"HTTPConference Protocol Providers" on page 167
"HTTP xMatters Conference Protocol Providers" on page 171
HTTPVoice Engine details

Details
Description
Name
Description
Notification Polling
How often (in seconds) the Device Engine polls the notification node for new alerts. Must be
a whole number greater than or equal to 10 and less than or equal to 300.
Concurrent Threads
Logging
For an explanation of Device Engine logging, see "Enable device engine logging" on page
119.
Jabber Device Engines

Jabber Device Engines enable xMatters to send notifications to service providers using the Jabber instant messaging
protocol (one-way only).
Jabber Device Engine details
Details
Description
Name
Description
Concurrent
Threads
Logging
Server Address
URL or IP of the Jabber server.
Server Port
Port number of the Jabber server.
Account
Account name on the Jabber server.
Password
Password for the account on the server.
SSL Flag
Indicates whether the service provider uses Secure Socket Layer (SSL) encryption.
MAPI Device Engines

MAPI Device Engines enable xMatters to send notifications to and receive responses from service providers using the
MAPI email protocol. Note that MAPI is a Windows-only protocol and requires that you install a MAPI email client on
the system running the Device Engine. Because MAPI clients usually have a user interface and may popup dialog boxes
from time to time, it is recommended that you use SMTP/POP or SMTP/IMAP for email instead.
Note:
When using MAPI with Microsoft Outlook, ensure that you install the latest patches for Outlook, available
from the Microsoft web site. If you are using Microsoft Outlook 2007, ensure that you have applied Service
Pack 1 (SP1).
For most protocols, the connection is transient, and each notification contains the required provider information. MAPI
Expanded MAPI Logging
To assist in troubleshooting MAPI issues, additional logging has been added for the library file used by MAPI Device
Engines. Any activity that occurs in alarmpoint_mapi.dll is written to a log file located at:
<xMatters>/logs/mapi_dll_log.txt
The maximum size for this log file is 10MB, after which it is rolled over into a single backup file named mapi_dll_
log1.txt.
MAPI Device Engine details

Detail
Description
Name
Description
Concurrent
Threads
Logging
Profile
Your MAPI mail profile. (To configure profiles in Windows, click Start > Settings > Control
Panel > Mail.)
Note: It is strongly recommended that the profile specified for this account be used by only one
xMatters deployment; the contents of the Inbox for this account may be deleted without
warning.
Password
If required, the password for the specified mail profile.
Mailbox Polling
Interval (sec)
How often, in seconds, the Device Engine checks the mailbox for responses.
Notification Key
If the delimiting character sequence is not guaranteed to be unique, the Device Engine may
make an incorrect match, causing an exception and response failure.
Response Key
Choice Message
Portion of notification message describing the Users response options. This field should not
contain a valid response phrase, or any phrase that might be mistaken for a User's reply.
Detail
Description
Response Message
Portion of the notification message that contains the response instructions. This field should not
NOTE:
This field should inform Users that when responding to a plain-text alert, they should type the
keyword RESPONSE in the subject line, followed by a single space, and then one of the
options listed. For example, they might respond with "RESPONSE ACCEPT".
Also note that this response should be the only text in either the subject of the email, or the first
line in the body of the email message.
To use MAPI with xMatters:

1. Log on with a Domain user account with Admin rights on the computer (this Domain user must have full access to
the MAPI mailbox you are planning to use with xMatters).
2. Install Outlook on the system and configure the email Profile using the Domain account.
l
When creating the Profile, ensure that the Use Cached Exchange Mode check box is clear.
3. Start Outlook and confirm that you can send and receive email using the newly created profile (you must be able
to send and receive email with Outlook before xMatters will be able to use the new profile to do so).
4. Click Start > Control Panel > Mail > Show profiles and verify the Profile name (required for for xMatters).
5. Create the MAPI Device Engine in xMatters using the Profile name verified in the previous step.
6. Create a Protocol Provider of type MAPI, specifying your desired settings.
7. Create a User Service Provider that contains the Protocol Provider.
8. Stop the xMatters node service, and then set the Log On properties to log on as the Domain account used in steps
1 to 3.
9. Start the Node Service.
10. To test the MAPI setup, create an xMatters User with an Email Device, and then send a validation message to the
Device.
Notes Device Engines

Notes Device Engines enable xMatters to send notifications to and receive responses from service providers using the
Lotus Notes Domino protocol. xMatters requires the installation of the DIIOP Corba Services to connect to a Lotus
Domino server.
Note that this feature only supports the following installation defaults for Lotus Notes: the folder name must be $Inbox,
and IMAPmust be set to Inbox. This Device Engine does not support the use of other values for the folder name or
IMAP.
Note:
The Domino HTTP Server must allow anonymous connections.
The following figure illustrates the required setting in the Domino Server Setup program:
Domino Server Setup DIIOP CORBA Services
Notes Device Engine details

Detail
Description
Name
Description
Concurrent
Threads
Logging
Server Address
Address of the Lotus Notes Domino server.
Account
User account to use on the Domino server.

For Java IIOP session authentication, this value is specified by the first value in the User name
field of the users Person document.
Detail
Description
Password
If necessary, the password for the user account on the Domino server.
For Java IIOP session authentication, this value is specified in the Internet password field of
the users Person document.
Mailbox
Mailbox to use when sending and receiving email.
Two Way
Indicates whether the Device Engine should support two-way communication.
Use SSL
Specifies whether to use SSL when communicating with the Domino server.
Mailbox Polling
Interval
How often (in seconds) the Device Engine polls the mailbox for a response.
Notification Key
Response Key
Choice Message
Portion of the notification message that defines User options. This field should not contain a
valid response phrase, or any phrase that might be mistaken for a User's reply.
Response Message
NOTE:
Phone Device Engines

Phone Device Engines enable xMatters to send and receive notifications using voice to a telephone. Note that you must
add a Phone Line Class before you can add a Phone Device Engine. For more information, see "Phone Class Resources"
on page 153.
Phone Device Engine details

Detail
Description
Name
Description
Logging
Virtual Phone
Toggles between virtual and actual phone lines. Note that the Virtual Phone does not require a
Dialogic card, and is intended for demonstration and testing purposes only. Changing this
setting requires a restart of the Notification Server Node.
Number of Lines
Number of phone lines supported by installed Dialogic cards and licensed with dongles.
Machine Detection
Threshold
Length of time (in seconds) xMatters waits before considering the recipient of a phone call to be
a machine. Typically, a person answers with a brief response, such as Hello while an
answering machine response is relatively long. If the salutation is longer than this value after the
phone is picked up and the voice speaks, xMatters treats the answerer as a machine. The default
recommended value is 2.
Default Play/Date
Format
Default format to use when playing current time and date to Users as specified by the language
file using the index file for phrases. The following tokens are supported: yyyy, yy, MM, DD,
HH, mm, and ss; by default, the value is:
mm/dd hh:nn.
Global Call
Protocol
Protocol to use for communication on T1/E1 type lines.
TTS Engine
Personality
Personality or voice to use when playing Text-To-Speech (TTS). This setting can also be
changed in the xMatters script.
TTS engines typically provide several different voices, like a male and female, but may also
provide different languages. This requires that one or more TTS Engines are installed; SAPI is
installed by default.
For more information about installing and configuring TTS Engines, see "Text-To-Speech
Engines" on page 86.
ASR Engine Name
Name of an installed Automatic Speech Recognition (ASR) engine. ASR Engines must be
installed separately.
Default Initial
Country
With Default Initial Language setting, determines the regional language settings to use when
playing a language.
Default Initial
Language
With Default Initial Country setting, determines the regional language settings to use when
playing a language.
Detail
Description
Default PhoneLine
Class
Specifies the Phone Line Class to use by default, unless otherwise specified in the script or
Phone Line details.
Default Call-in
Script
Name of script to run when Users call in to xMatters to retrieve notifications.
Low2Ring
Minimum
Minimum long low duration of double ring, in milliseconds. This should be used in areas such
as the United Kingdom for double rings on the ringback tone.
Maximum Answer
Maximum allowable length of a salutation (greeting), in 10ms units. If this value is reached
during a salutation, the system will assume a connection with a machine and continue with the
script. The default of 1000 is equivalent to 10 seconds.
Required Prompt
Silence (ms)
Maximum silence period allowed between words in a salutation, in milliseconds. The default
value of 1500 is equivalent to 1.5 seconds.
For more information about creating and using scripts, refer to the xMatters Online Developer's
Guide.
After defining the Phone Device Engine details, click Continue. On the Phone Line Details page, specify the following
settings to define the phone lines for the Device Engine to use:
Phone Line details
Detail
Description
Callout
Specifies whether xMatters can use this line to call out. Clearing this check box reserves the line
for call-in only.
Line Number
Specifies the number for this phone line.
Answer on Ring
Number
Specifies on which ring xMatters should answer an incoming call.
Call-in Contact
Script
Specifies the script to run when a User calls in to this phone line. This setting overrides the callin script specified in the Device Engine details. In multiple-Company deployments, this setting
can be used to automatically identify the call-in Users Company.
For more information about scripts in xMatters, refer to the xMatters Online Developer's Guide.
Initial Country
Specifies the default country for this phone line.
Initial Language
Specifies the default language for this phone line.
Phone Line Class
Specifies the Phone Class to use for this phone line; if changed, overrides the default Phone Line
Class for this Device Engine specified in the Device Engine details.
For more information about Phone Classes, see "Phone Class Resources" on page 153.
Click the Add New Phone Line button to add more phone lines, and specify the details for each one.
Positive Voice Detection

To determine whether a phone is answered by a person or an answering machine, xMatters uses a feature called Positive
Voice Detection with the Intel Dialogic card to provide data about the length of the salutation, or greeting. The
following diagram illustrates a rough time line of the call process:
Approximate call process for Positive Voice Detection
1. When xMatters picks up the phone, it listens for a dial tone.

2. When the dial tone is confirmed, xMatters dials the appropriate phone number.
3. Assuming there is no error tone, xMatters listens for RINGBACK tone (i.e., the indication that the phone on the
other end of the line is ringing), which can be one or more.
4. When the phone is picked up, xMatters detects the connection.
5. The salutation (or greeting) is typically a person saying "Hello", or else the voicemail (or answering machine)
plays a greeting.
6. After the salutation, there is a period of silence.
Note:
The Dialogic card used in your deployment may not support all of the potential call progress results available
in the CTADE library used by xMatters to handle the call process. This may affect the error messages returned
by the CTADElibrary; for example, you may receive a "NO_RINGBACK"message instead of "NO_DIAL_
TONE" when no dial tone was detected. For more information about handling call progress results, see the
xMatters Online Developer's Guide.
There are some defaults in the system that assist in determining whether the connection has been established with a
human or a machine. The following settings can be adjusted on the Phone Device Engine page:
Machine Detection Threshold
This setting compares the salutation section of the above diagram. If the salutation is longer than the Machine Detection
Threshold setting, then xMatters results in a MACHINE DETECT. If the salutation is shorter, xMatters results in a
VOICE DETECT. Both of these values are tested in the default voice scripts so they can branch accordingly. (Default
setting is 2 seconds.)
Low2Ring Minimum
This value is the minimum long low duration of double ring, in milliseconds. This setting should be used in areas such
as the United Kingdom, for double rings on the RINGBACK tone. (Default setting is 2250, or 2.25 seconds.)
Maximum Answer
This value is the maximum allowable length of a salutation, in 10ms units. If this value is reached during a salutation,
the system will assume a connection with a machine, and continue with the script. (Default setting is 1000, or 10
seconds.)
Required Prompt Silence
After the salutation is complete, xMatters waits for the length of time specified by this setting before beginning to speak
(or leave a message). (Default setting is 1500 in milliseconds, or 1.5 seconds.)
Note that making this parameter too short can cause problems. For example, if you set this value to 50 (half of a second)
and the persons voicemail greeting has a half-second pause in the middle, xMatters will start leaving a message before
the greeting is complete. In some environments, this setting may work better with a one-second delay, while other
configurations may require two seconds.
PUCP Device Engines

PUCP Device Engines enable xMatters to send notifications to UCP protocol providers via serial ports. Universal
Computer Protocol (UCP), also known as External Machine Interface, is used to connect to short message service
providers to send SMS on mobile telephones.
UCP Serial Device Engine details
Detail
Description
Name
Description
(sec)
Logging
SIP Device Engines

SIP Device Engines enable xMatters to send notifications to and receive responses from service providers using the
Session Initiation Protocol (SIP). Be aware that each SIP account should have its own SIP Device Engine (i.e., each SIP
account User Name must be unique to its SIP Device Engine). Also, SIP Device Engines must use a TTS language
engine.
Note:
xMatters deployments that will experience high volumes of SIP traffic must have SIP Device Engines
configured on dedicated xMatters notification server Node computers (i.e., the xMatters notification server
Node must reside on a computer that is separate from other xMatters components such as web servers,
application servers, and the database). For further system requirement details, see "Software Requirements" on
page 25.
This protocol allows xMatters to make voice calls through a company PBX or SIP Gateway using Voice Over IP (VOIP)
rather than lines from the telephone company.
Note:
SIP routing for multiple-Company deployments

In multiple-Company deployments, incoming SIP calls are routed based on the value of the incoming calls CNAM
(Caller ID name). (In single-Company deployments, all incoming SIP requests are routed to the default callin script.) The
deployment PBX must be configured to create or replace the incoming CNAMvalue with the Company Name. This
value is parsed by the SIP Device Engine to identify the callers associated Company, and pass the incoming call to the
correct callin script. If the Device Engine receives a CNAM that does not match an existing Company Name, the Device
Engine invokes the default error script, which plays a recording indicating that the call could not be routed.
For outbound SIP calls, the default scripts automatically populate the Caller ID field of the outbound call with the name
of the Company associated with the Event, and use the Companys call-in number, as specified on the Company details
page.
Note:
For general information about SIP Caller ID, see the SIP FAQ at http://www.egyed.com/faq/sip_
faq.html#callerid.
SIPextension dialing
Secondary call progress is not supported for SIPDevices because the call progress results does not handle Machine
Detect or No Answer returns; all results are treated as Reached a Person (or VOICE_DETECT). Without access to
machine detection, you will have to configure the waitForSilence script method (available in all xMatters deployments
after version 4.0 patch 008) to time the duration properly so that the recipient will have time to answer. Even with the
most precise timing, however, xMatters may still occasionally leave a message to a ringing or dead line.
SIP Device Engine details
Detail
Description
Name
Description
(sec)
Logging
Number of Line
Appearances
Total lines available for outgoing and incoming SIP calls. The number of lines available for
outgoing calls is the total number of line appearances less those reserved for incoming calls.
Reserved for
Incoming Calls
The number of lines reserved for incoming SIP calls.
Default Play/Date
Format
Default format to use when playing current time and date to Users as specified by the language
file using the index file for phrases. The following tokens are supported: yyyy, yy, MM, DD,
HH, mm, and ss; by default, the value is:
mm/dd hh:nn.
TTSEngine
Specifies the TTSEngine to use when playing Text-To-Speech (TTS).

Note that the choices available in this list depend on your version, deployment configuration,
and licensing; for example SAPI is installed by default with xMatters version 4.1, but the option
to use AT&T Natural Voices only appears if you have purchased the appropriate Natural Voices
license.
TTS Engine
Personality
Personality or voice to use when playing Text-To-Speech (TTS). This setting can also be
changed in the xMatters script.
TTS engines typically provide several different voices, like a male and female, but may also
provide different languages. This requires that one or more TTS Engines are installed; SAPI is
installed by default.
For more information about installing and configuring TTS Engines, see "Text-To-Speech
Engines" on page 86.
ASR Engine
Personality
Personality or voice to use when playing Automatic Speech Recognition (ASR) methods. The
default setting is Microsoft English Recognizer V5.1.
TTSEngine Server
Identifies the IPaddress of your AT&TNatural Voices Server.
Detail
Description
TTSEngine Port
Identifies the port number for your Natural Voices Server.
TTSVersion
Identifies the version of AT&TNatural Voices you have installed.

Note that AT&TNatural Voices 5.1 requires that you obtain and install a license file from
xMatters before you can use the feature. If you attempt to use AT&T5.1 without first installing
a license file, the node will fail without issuing a warning message.
To install the AT&Tlicense file on your xMatters server:
1. If the xMatters node is running, stop it.
2. Copy the license file (the evaluation license file is typically called order.txt)to the
<xMHOME>/node folder on your server.
3. Restart the node.
Default Initial
Language
Determines the regional language settings to use when playing a language.
Call-in Silence
Threshold
The threshold used to determine silence on the line. Larger values are less sensitive to static.
Valid values are from 0 to 65535; the default value is 256.
Codec List
The codec list supported by the Device Engine. Select one of the following options:
Ulaw: standard telephone codec for North American calls.
Alaw: standard telephone codec for European calls.
Default Call-in
Script
Name of the script used to handle the communication for incoming calls. Note that this value
overrides the "Sip Call In Script"setting on the Company details page.
Inbound SIP
Registration List
This area displays an editable list of inbound SIP registrations available to the SIP Device
Engine. Click Add New Inbound SIP Registration to create a new registration, and specify the
settings as described in the table "Inbound SIP Registration settings", below.
To remove a registration, select the check box next to the registrations you want to remove, and
then click Remove Selected Inbound SIP Registrations.
The following table describes the Inbound SIPRegistration Settings:

Inbound SIP Registration Settings
Detail
Description
SIP Server Address IP address of the SIP server with which xMatters will register.
SIP Server Port
Port to use on the SIP server.
SIP Local Port
Local port to which the Device Engine will bind and which the SIP Server will use to
communicate with xMatters.
SIP Local Address
IP address that the Device Engine will bind to and listen for SIP calls.
Detail
Description
SIP Domain
Domain used by the SIP server; this domain name will be included in the SIP messages.
SIP Outbound
Proxy Address
If required, the IP address of the outbound proxy server.
SIP Outbound
Proxy Port
If required, the port of the outbound proxy server.
RTP Port (min)
The lower limit to the port number on which RTP is allowed (default is 1025). If you are using a
firewall, you must also open a range of ports based on the RTP Port (min) and RTP Port (max).
RTP Port (max)
The upper limit to the port number on which RTP is allowed (default is 65535). If you are using
a firewall, you must also open a range of ports based on the RTP Port (min) and RTP Port (max).
DTMF Payload ID
The default value is 101, though some SIP Server environments may require a different value.
Contact your SIP Server Administrator for more information. Note that the xMatters SIPDevice
Engine supports only RFC2833 for DTMF tones.
Registration
Attempts
How many times the Device Engine should attempt to register with the SIP server.
Registration
Timeout
How long, in seconds, the Device Engine should wait before timing out on a registration
attempt. The default is 60.
Session Timeout
How long, in seconds, the Device Engine should wait to timeout a SIP session. The default is
3600.
User Name
The user name to use on the SIP server.
Password
The password, if required, for the user name on the SIP server.
Display Name
Name displayed as source of call.
The xMatters SIPDevice Engine supports only RFC2833 for DTMF tones.
SMPP Device Engines

SMPP Device Engines enable xMatters to send text notifications to and receive text responses from service providers
using the Short Message Peer-to-Peer (SMPP) protocol. This protocol involves communicating via SMS-based messages
on text-enabled mobile phones. xMatters supports SMPPversion 3.4 only.
For most protocols, the connection is transient, and each notification contains the required provider information. SMPP
The xMatters SMPPDevice Engines support SMSshort codes. For information about HELPand STOPcodes and best
practices, see "Constants" on page 209.
Note:
SMPP Device Engines are single-threaded.
By default, SMPPDevice Engines can handle only one socket connection. You can manually configure the number of
socket connections handled by the SMPPDevice Engine by editing the configuration file.
To set the number of SMPPsocket connections:
1. On the xMatters server, open the

<xMHOME>/node/assets/resources/spring/integration/deSmppContext.xml file.
2. Locate the smppConfigurationAgent bean, and change the value for the numberConnections setting from 1 to
the maximum number of connections that the SMPPService Provider allows.
SMPPDevice Engine Details
Many of the settings required for the SMPP Device Engine may be specified by your SMPP service provider.
SMPP Device Engine details
Detail
Description
Name
Description
Logging
Server Address
IP address of the SMPP server to which xMatters should connect.
Server Port
TCP/IP port used to connect to the SMPP server.
Connection Mode
Specifies how the Device Engine should connect to the SMPP provider. Select Tranceiver to
send and receive messages over the same connection, or select Transmitter/Receiver to use
separate connections for sending and receiving.
System ID
Account ID provided by your SMPP service provider.
System Password
If required, the password for your SMPP account ID.
System Type
If required, the system type parameter provided by your SMPP provider.
Address Range
Range of addresses to use for SMPP messages, if provided by your SMPP service provider.
Address Range
TON
Type Of Number (TON) required for the address range as supplied by your service provider.
Address Range NPI Numbering Plan Identity (NPI) required for the address range as supplied by your service
provider.
Detail
Description
Source Address
Number associated with your SMPP account; used to indicate the sender for outgoing messages.
This setting may be overridden by the Source Address setting on the SMPPProtocol Provider
details.
Source Address
TON
Your SMPP accounts TON to be used during the server session. This setting may be overridden
by the Source Address setting on the SMPPProtocol Provider details.
Source Address
NPI
Clients NPI required by your service provider for the source address. This setting may be
overridden by the Source Address setting on the SMPPProtocol Provider details.
Default Dest
Address TON
TON required by your service provider for the default destination address. This setting may be
Default Dest
Address NPI
NPI required by your service provider for the default destination address. This setting may be
Session Timeout
Length of time in minutes before the session times out. To have every session time out, enter 0.
To have sessions never time out, enter a negative value.
Notification Key
For more information about how xMatters handles SMSmessages, see the section, "Configure
SMS messages and replies", below.
Response Key
Choice Message
Portion of notification message describing the Users response options.

Detail
Description
Response Message
Instructions to the recipient on how to respond to the notification.

page 143, this field should be changed to reflect the new response process. The recommended
value is "Reply %RESPONSECHOICES%".
Enquire Interval
Time in seconds between enquire packets sent to the SMPP service provider. Value must be a
multiple of 10, and cannot be less than 10 seconds.
Support Status
Report
Specifies whether the Device Engine should support incoming status reports from service
providers. When enabled, the status reports are displayed in the xMatters Reports and recorded
in the Node log.
Message ID
Location or
Delimiter
Indicates a method to identify the message ID within the incoming status report. This value can
be expressed in one of three ways:
o
<location><length>: indicates the starting position and length of the message ID

within the status report; e.g., 4610.
<delimiter>: indicates the delimiter that identifies the message ID; e.g., mess_id:.
<delimiter> (<length>): indicates the delimiter that identifies the message ID, and the
expected length of the ID; e.g., the default setting, id: (10).
Status Location or
Delimiter
Indicates a method to identify the status of the notification within the incoming status report.
This value can be expressed in the same three ways as the Message ID Location or Delimiter
field; the default value is stat: (7).
Error Code
Location or
Delimiter
Indicates how to identify the error code within the incoming status report. This value can be
expressed in the same three ways as the Message ID Location or Delimiter field; the default
value is
err: (3).
Delivery Word
Specifies the Status string value within the incoming status report that indicates the notification
message was delivered to the recipients Device; the default is DELIVRD.
Read Word
Specifies the Status string value within the incoming status report that indicates the notification
message was read by the recipient.
Failed Word
Specifies a list of Status string values within the incoming status report that indicate the
notification message has failed; the default list is EXPIRED;DELETED;UNDELIV;UNKNOWN. Note
that list values must be delimited with semi-colons.
Configure SMS messages and replies

The SMSprotocol was originally designed as a device-to-device messaging service. Unlike most paging protocols, SMS
is "stateless"and does not contain hidden information that can be used to link related messages together. As a result,
xMatters requires that SMS responses contain links or textual information that can be used to identify the original event.
This is accomplished by embedding a unique identifier, the "notification key", within the notification message that must
be included within the reply.
The following sections explain some different configuration options for replies to be accepted and processed correctly by
xMatters. In each of the following examples, the Response Key specified in the Device Engine settings is "RES".
Example One:
The following response includes the notification key as the first entry in the reply message (and therefore it does not
require delimiting characters); the User's response is contained on a separate line at the end of the message:
359055 SMPP 02 Reply <ID> , "Clear", "Ignore"
RES Acknowledge
xMatters would successfully process the above reply.

Example Two
The following response includes the notification key as the first entry in the reply message (and therefore does not
require delimiting characters); the User's response is appended directly following the notification key:
359067 RES Acknowledge Security Breach - Data Center 4 - SMPP 04 Reply <ID> RES "Acknowledge"
xMatters would be unable to process the above message, due to the User's response being indistinct from the body of the
message. To resolve the issue, and make the above message acceptable, a carriage return must be inserted after the User's
response:
359067 RES Acknowledge
Security Breach - Data Center 4 - SMPP 04 Reply <ID> RES "Acknowledge"
xMatters would successfully process the modified reply.

Example Three
The following response includes the notification key within delimiters inside the body of the reply message; the User's
response is on a separate line, and followed by a carriage return:
RES Acknowledge
{359067} Security Breach - Data Center 4 - SMPP 04 Reply <ID> RES "Acknowledge"
xMatters would successfully process the above reply.

Example Four
The simplest possible response message includes the notification key at the beginning of the message, followed
immediately by the User's response, with no other information included in the reply:
359077 RES Acknowledge
Configure simple SMS replies

You can configure xMatters to accept simple SMSresponses to notifications. These simple replies require Users to enter
only a single digit as a response to a notification, rather than entering a phrase that includes the notification key. For
example, the response choices for a notification with simple responses enabled might resemble the following:
Network Server 1211 is offline. Reply 1 toAcknowledge, 2 to Ignore, or 3 to Clear.
The User responding to this notification could respond with "1", and the event would be marked as acknowledged.
Because SMS is "stateless"and does not contain hidden information that can be used to link related messages together,
xMatters uses the phone number of the text phone Device to associate the response with the correct notification.
When simple SMSreplies are enabled, xMatters maintains a mapping of SMS Device numbers and response options,
retaining the information for 72 hours. Because a Device may receive multiple notifications for different events, the
integers used for the response options will change for each notification on a Device based on the number of response
choices and the number of active events.
For example, a User might receive a notification prompting them to respond with 1 to acknowledge or 2 to ignore. The
next notification, for a separate event, may prompt them to respond with 3 to acknowledge, and 4 to ignore. This
incrementing would continue based on the number of notifications received, possibly into double or triple digits as
required. Integers would not be reused until the event associated with them is no longer in an active or created state, and
is at least 72 hours old. The waiting period helps to reduce the possibility that Users could accidentally respond to an
active event by responding to old SMS messages (related to closed events) that may be waiting in their phone message
queues or inbox.
Note that this makes it impossible to accurately predict the specific integers required for an anticipated event, such as a
Scheduled Message.
Before implementing the simple SMSreplies feature, please note the following:
n
xMatters uses the country assigned to the Site with which a Device is associated to determine its country code. For
example, Devices associated with a Site based in Australia will have a country code of 61.
If the validation pattern and template specified on the Global Configuration page are not correctly configured,
notification responses will be ignored; for information about any ignored responses, review the xMatters logs.
The phone numbers specified in the Device details must be formatted consistently across all Devices for the
validation patterns and templates to work properly; if the validation results do not match a number in the system
(due to inconsistent formatting), responses may be ignored.
This feature requires the following configuration steps:

1. Ensure that all User Service Providers for Text Phone Devices do not have a mixture of protocols; for example, any
text phone User Service Provider that includes the SMPPprotocol must not also include GSMor HTTPClient.
2. Enable response validation and simple responses on the Global Configuration page, and specify the validation
pattern and template; for more information about these settings, see "Global Configuration" on page 198, and the
following section, "Specify SMS validation patterns and templates" on page 203.
3. Edit the Response Message field on the Device Engine to indicate the new response process for Users. The
notification message delivered is configured as <message payload>+"Response Message"(which must include the
key, %RESPONSECHOICES%). The recommended value is "Reply %RESPONSECHOICES%"; for more
information, see "Device engines" on page 118.
SMTP Device Engines

SMTP Device Engines enable xMatters to send notifications to and receive responses from service providers using MAPI
or POP protocols.
Note that the xMatters account to which email responses are sent handles deleted emails differently for IMAP and POP
accounts:
n
POP account: incoming email messages are checked for validity, processed, and then deleted from the server.
IMAPaccount: incoming email messages are checked for validity, processed, and then moved to the "Deleted
Items"folder. Thiscan result in significant storage space being required to store deleted email messages. To avoid
this, ensure that you configure your email server's storage policies and mailbox database defaults to periodically
purge the "Deleted Items"folder.
SMTP Device Engine details

Details
Description
Name
Details
Description
Description
Notification Polling
How often (in seconds) the Device Engine polls the notification node for new alerts. Must be a
Concurrent
Threads
Logging
Incoming Protocol
Protocol to use for incoming messages.
Note: If you specify a POP or IMAP Incoming Protocol, xMatters prompts you to specify the following additional
details for the SMTP Device Engine. The page with these settings will load after you click Continue.
Email Account
Email address used to send notifications.

Note: This email address must not be the same as the email account specified in the Mail Sender
field of the Bounced Mail Settings area on the Global Configuration page. It is also strongly
recommended that the email address specified for this account be used by only one xMatters
deployment; the contents of the Inbox for this account may be deleted without warning.
Email Format
Specifies which of the following formats is used by the POP/IMAP server to authenticate and
display email accounts in notification messages from xMatters:
o
o
o
user@domain
user
user
Note that different formats are required by different POP/IMAP servers; consult your providers
documentation to determine the correct format.
Password
Password to access the SMTP/POP server.
Incoming Email
Server
Email server to poll for responses.
Incoming Server
Port
Server port to use for incoming responses.
SSL Flag
Specifies whether the protocols SSL flag is enabled or disabled. When selected, the encryption
key supplied by the server as part of SSL is used for encryption; there is no need to install a
client certificate.
Note: The implementation of SSL in xMatters also supports Transport Layer Security (TLS).
Mailbox Polling
Interval (sec)
Indicates how often (in seconds) the Device Engine polls the mailbox for a response.
Details
Description
Notification Key
(%Notification Key%).
Response Key
Default Message
Default notification message displayed to the recipient.
Choice Message
Portion of the notification message that defines User options. This field should not contain a
valid response phrase, or any phrase that might be mistaken for a User's reply.
Response Message
NOTE:
SNPP Device Engines

SNPP Device Engines enable xMatters to send notifications to and receive responses from service providers using the
Simple Network Paging Protocol (SNPP).
SNPP Device Engine details
Details
Description
Name
Description
Concurrent
Threads
Details
Description
Logging
SUCP Device Engines

SUCP Device Engines enable xMatters to send notifications to service providers using a Universal Computer Protocol
(UCP) via an Internet socket.
SUCP Device Engine details
Details
Description
Name
Description
Concurrent
Threads
Logging
TAP Device Engines

TAP Device Engines enable xMatters to send notifications to service providers using the Telelocator Alphanumeric
Protocol (TAP). TAP is used for sending pages or SMS, and requires dialing up to a provider over a serial modem.
TAP Modem Device Engine details
Details
Description
Name
Description
Concurrent
Threads
Logging
TAP Leased Device Engines

TAP Leased Device Engines enable xMatters to send notifications to service providers using the TAP protocol via a
dedicated or leased line.
TAP Leased Device Engine details

Details
Description
Name
Description
Concurrent
Threads
Logging
Serial Ports
This area displays an editable list of serial ports available to the Device Engine. Click Add New
Port to specify a new serial port, and then type the port number in the field provided.
To remove a serial port from the list, select the check box beside the port or ports you want to
delete, and then click Remove Selected Ports.
Virtual Device Engines

Virtual Device Engines enable xMatters to send notifications to and receive responses from the virtual Devices included
with xMatters. These Devices are intended for demonstration and testing purposes only.
Virtual Device Engine details
Detail
Description
Name
Description
Concurrent
Threads
Logging
Incoming Port
The port for the Virtual Device Engine to receive incoming requests.
Detail
Description
Email Notification
Key
Email Response
Key
Email Default
Message
Email Choice
Message
Email Response
Message
NOTE:
Text Phone
Notification Key
Text Phone
Response Key
Detail
Description
Text Phone Default

Message
Text Phone Choice

Message
Text Phone
Response Message
Portion of notification message describing response instructions.
WCTP Device Engines

WCTP Device Engines enable xMatters to send notification to and receive responses over the network from service
providers using the Wireless Communication Transfer Protocol (WCTP).
WCTP Device Engine details
Details
Description
Name
Description
(sec)
Concurrent
Threads
Logging
Resources
Node Resources define the serial devices, proxy settings, and phone line settings available to the Device Engines within
the node.
To view and manage Resources:
1. Click the Administration tab.
2. In the Administration menu, click Nodes & Device Engines.
3. In the All Nodes table, in the View Resources column, click the Resources link for the Node you want to modify.
l
Resources | 150
xMatters displays the Resources for Node page, which lists all of the Resources available to that Node.
Resources for Node page
4. On the Resource for Node page, do any of the following:

l
To modify an existing Resource, type the new settings in the fields for that Resource. For an explanation of
the fields, see the following section, "Resource types" on page 151.
To remove a Resource, select the check box next to the Resource you want to delete, and then click Remove
Selected.
To add a new Resource, click the Add New button for the type of Resource you want to add. xMatters
creates a blank Resource on the page; you can then type the settings for the new Resource in the fields. For
more information about the fields and the available settings, see the following section.
Resource types
There are three types of Resources that you can assign to Nodes in xMatters:
Resources | 151
Node Resources
Resource Type
Description
Serial Devices
Serial Device Resources represent serial ports with attached modems/phone lines which are used
by devices engines for implementing dial-out protocols like TAP, DTMF, UCP, etc.
Socket Proxies
Socket Proxies identify any proxies required by the Device Engines to communicate with
external resources that are not directly accessible.
Phone Classes
Phone Classes specify the destination number and other information that phone lines need to dial.
Serial Device Resources

You can use the Resources for Node page to identify the serial devices and ports to use for each Node.
Serial Device Resource details
Detail
Description
Carrier Wait How long to wait, in seconds, before beginning transmission after contacting the provider. Note that
Time
this setting applies to all serial device resources.
Response
Wait Time
How long to wait, in seconds, for a response. Note that this setting applies to all serial device
resources.
Serial Port
The serial port to use for this resource.
Init String
The initialization string or code required for the serial port.

Note that for US Robotics modems, the following are the most important initialization values required
by some alpha paging services:
o
o
No error control options (for some US Robotics modems, the init string may require &M0)
No data compression (for some US Robotics modems, the init string may require &K0)
Socket Proxy Resources

You can use the Resources for Node page to identify and manage the Socket Proxies to use for each Node.
Resources | 152
Socket Proxy Resource details

Detail
Description
Protocol
Protocol to use when communicating with the proxy. xMatters supports the following
protocol proxy protocols:
o
o
o
o
o
o
o
IMAP/POP: SOCKS5
SMPP: SOCKS5
SNPP: SOCKS5
SUCP: SOCKS5
WCTP: HTTP
HTTP:HTTP
Jabber: SOCKS5
Note that the proxy protocol is assigned automatically and does not need to be specified in
the Web User Interface.
Proxy Server Address Address of the proxy server.
Proxy Server Port
Port to use on the proxy server.
Login ID
If required, the account name on the proxy server.
Password
Password for the proxy server account.
Resolve Server
Address Locally
Specifies whether to resolve the server address locally or by proxy. (The SOCKS5 protocol
allows hostnames rather than IP addresses to be sent in requests. This setting controls whether
the hostnames should be sent to the proxy server as names or should be resolved locally.)
Phone Class Resources

Phone Classes are associated to phone lines and used to dial out and represent the dialing rules, based on area codes and
country codes. Each phone line has a default Phone Class, which dials the destination number without any
modifications. You can define additional Phone Classes to handle local versus long distance calling, 10 digit local
calling, multiple local area codes, same area code for local/long distance dialing, etc.
Phone Classes are defined at the Node level and are used for any type of phone lines (serial device resources or voice
lines).
Device Engines use the Phone Class associated with a given phone line to determine the dialing methods to use. If all
the phone lines are identical, and in the same location, then only one Phone Class needs to be defined, and assigned to
all lines.
To accommodate for the various phone systems around the world, you can define exceptions to the Phone Class. To
create an exception, first define the number to match against, for example if the area code should be included when
evaluating the exception. The second step is to define a pattern to be used to match against the defined number. Lastly,
specify the dialing method to define how the phone number will be dialed when the exception is triggered.
Note that when expressions are evaluated the order is important and, starting from the top, the evaluation stops at the
first match found. This allows for defining a restrictive expression first, and then following it with more relaxed
exceptions if needed.
Resources | 153
Detail
Description
Name
Name of the phone class.
Description
Brief description of the phone class.
Country
Country in which the phone line is located. This setting is used to determine how to dial outside
the country.
Area/Std Code
Area or STD (Subscribers Trunk Dialing) code in which the phone line is located.
Local Dialing
Method
Method for the Phone Class to use when making local calls. For more information, see Dialing
Methods below.
Long Distance
Dialing Method
Method for the phone class to use when making long-distance calls.
International
Dialing Method
Method for the Phone Class to use when making overseas or international calls.
Phone Class
Exceptions
Phone Class exceptions define special dialing methods for certain Area/STD Codes. Click Add
New Phone Class Exceptions Setting to add a new exception, and then enter the following
information into the fields provided:
o
o
o
o
Description: A brief description or name for the exception.

Number Definition: Defines the number to match against; for example, if the area code
should be included when evaluating the exception.
Match Expression: Defines a pattern to use when matching against the number definition.
Dialing Method: Defines the special dialing method to use if the exception conditions are
met. See the following section for more information about dialing methods.
For an example of how to create a phone class exception, see "Phone Class Exceptions Examples"
on page 155.
Dialing Methods
xMatters supports and dials as is standard dialing codes, which include the following:
Standard Dialing Code
Dialing
Result
Code
0-9, *,
#
Dials the corresponding touch-tone digit.
Pauses.
&
Issues a hook flash (also known as a "recall"), that simulates quickly hanging up and then picking up again.
This can signal the telephone exchange to perform a function such as switching to an incoming call, or
indicating a request for voice conferencing.
Note that a hook flash is not currently supported over T-1 lines.
Resources | 154
In addition, xMatters supports the following case-sensitive special codes:

Special Dialing Codes
Dialing Code
Result
For pagers, dials the contents of the Phone Number field in the Protocol Provider settings. If that field
is blank, dials the contents of the Override Phone Number in the Device details for the User (numeric
pagers).
For phones, dials the contents of the Phone Number field in the Device details for the User.
For pagers, dials the contents of the Area Code field in the Protocol Provider settings. If that field is
blank, dials the contents of the Override Area Code field in the Device details for the User.
For phones, dials the contents of the Area Code field in the Device details for the User.
c
Dials the Country code associated with the User, or the Country Code Override defined on the Users
Phone Device.
Dials the extension number associated with the User.
eN
Dials the last N digits in the phone number associated with the User.
For example, a long distance dialing method may be defined as 1an, while an international dialing method may be
defined as 011can.
Phone Class Exceptions Examples

Example One
Assume that you need to create a number definition for PBX internal dialing. In this case, you want xMatters to dial
only the last four digits of a phone number whenever the area code and prefix match specific numbers.
n
The Number Definition is the number you want to evaluate. You can express the number as an, which represents
the area code and phone number as explained in the Special Dialing Codes table above.
The Match Expression represents what the system should look for in the number definition. For example, you
might specify the area code 925, and a prefix of 555.
The Dialing Method represents what is actually dialed. To dial only the last four digits of the number, you would
enter e4.
The settings for your phone class exception would then resemble the following:
Phone class exception example
If the number that enters the system is 925-555-0320, the phone class exception matches the area code and prefix, and
the system dials only 0320.
Example Two
Assume that you need to create an exception for a situation where xMatters is on the same PBX as the User, and can dial
the Users extension.
Resources | 155
The Number Definition can be expressed as an, which represents the area code and phone number.
The Match Expression should look for the main number so xMatters will dial an extension when the number
matches, rather than an entire number.
The Dialing Method would be expressed as x, which represents the Users assigned extension.
The settings for your phone class exception would then resemble the following:
Phone class exception extension example
If the number that enters the system is 925-555-0300, the phone class exception matches the area code and number,
and the system dials the Users extension.
Clusters
Clusters represent logical collections of one or more xMatters notification servers, which may be distributed around the
world. xMatters can manage multiple Clusters, each with multiple xMatters notification servers.
Using Clusters, xMatters routes alerts locally and around the world, using customized routing methods. This results in
cost savings on long distance charges, and provides the ability to load balance notifications across the system.
Typically, xMatters is installed in a single location, with multiple Notification Servers strategically located based on the
geographical profile of the organization. It is recommended that Clusters are named according to their location (e.g., by
city: MelbourneCluster, LondonCluster, TokyoCluster, LosAngelesCluster, etc.).
In a multiple-Company deployment, Clusters are part of the global data and can be created and assigned to Companies
only by Super Administrators. Company Administrators can specify a primary Cluster for a Sites to specify the preferred
routing of notifications, but cannot create Clusters or specify which Clusters are available for each Site.
Note:
Clusters are available only in an xMatters enterprise deployment.
Manage clusters
You can manage Clusters using the Clusters page.
To view and manage Clusters:
2. On the Administration menu, click Clusters.
l
Clusters | 156
xMatters displays a list of the Clusters for the Company:
Clusters page
3. From the All Clusters list, do any of the following:

l
To modify an existing Cluster, click its name in the list to view Clusters Details. For more information about
editing Cluster Details, see Defining Cluster Details, below.
To remove a Cluster from the list, select the check box next to the Cluster or Clusters you want to remove,
and then click Remove Selected.
To create a new Cluster, click the Add New link, and specify the Cluster Details for the new Cluster, as
explained in Defining Cluster Details, below. Click Save to create the Site.
Define cluster details

You can define the details for each cluster using the Cluster Details page.
To define cluster details:
1. On the Clusters page, in the All Clusters table, click the name of the cluster you want to modify.
2. On the Cluster Details page, enter the following information into the form:
Setting
Description
Name
Name of the cluster.
Description
Description of the cluster.
Protocol providers
Protocol Providers define how xMatters accesses servers for outgoing notifications. While User Service Providers restrict
protocol selection at the Company level, the Super Administrator can configure Protocol Providers that are available
throughout xMatters.
Supported protocols
xMatters supports the following industry-standard protocols:
DTMF, PSTN, and SIP
These are two-way protocols, used mainly for making and receiving voice calls, or interfacing with public address
systems:
Protocol providers | 157
DTMF: Dual Tone Multi-Frequency protocol, used for keypad signaling over a voice phone line.
PSTN: Public switched telephone network, used to make phone calls.
SIP: Session Initiation Protocol, used to send notifications via SIP-enabled telephone sets and other voice-over-IP
(VOIP) devices.
Jabber
This is a one-way instant messaging platform, used to send messages to desktop computers, or to mobile Devices using
apps (e.g., Bejive on the iPhone).
HTTPProtocols
These protocols are used to send notifications or create conferencing sessions over a cloud-computing provider:
n
HTTP Conference: Protocol used to create conferencing sessions using a voice cloud provider other than
xMatters.
HTTP Generic: Protocol used to send SMS notifications via a cloud SMS provider other than xMatters.
HTTP xMattersConference: Protocol used to create conferencing sessions using the xMatters voice cloud.
HTTP xMatters SMS: Protocol used to send SMSnotifications via the xMatters SMS cloud.
HTTPBlackBerry Push:Used to send push notifications to the xMatters application on BlackBerry Devices.
MAPI, Notes, and SMTP

These providers are used for two-way email message communications to any desktop computer or email-capable handheld Device:
n
MAPI: Messaging Application Programming Interface, used to send email notifications via Microsoft Outlook.
NOTES: Lotus Notes/Domino Protocol, used to send notifications via an IBM Lotus Domino server.
SMTP: Simple Mail Transfer Protocol, the de facto standard for transmitting email over the Internet.
These protocols are not recommended for sending SMSmessages to mobile phones as there is no guarantee that the
message will ever arrive on the intended Device. In the event that the message does arrive, it will usually result in a oneway message where no response is ever returned to xMatters. No tracking information is returned to xMatters during the
notification process, and a succession of email servers can be involved in each transmission.
BES
The BlackBerry Enterprise Server protocol can send two-way text messages to BlackBerry Devices as "Level
1"messages. These are not considered SMSor email messages; they are BES-specific messages that can be encrypted,
have a different ring tone or vibrate setting, and be replied to on the target Device.
SUCPand PUCP
These older, text-based protocols are less common, and typically used with pagers:
n
SUCP: Universal Computer Protocol, used to send notifications via an Internet socket.
PUCP: Universal Computer Protocol, used to send notifications via a serial port.
GSM
The Global System for Mobile Communications two-way protocol requires that xMatters have a GSMmodem attached
(this can be as simple as a mobile phone with a SIMcard built into a small box with an antenna). This allows xMatters
to send and receive text messages just as a User would from a mobile phone.
SMPP, SNPP, and WCTP
These protocols are the latest two-way network-based protocols for use with pagers and SMStext providers:
n
SMPP: Short Message Peer-to-Peer protocol, used to transmit SMS messages on text-enabled mobile phones.
SNPP: Simple Network Paging Protocol, used to send notifications to a pager over the Internet.
WCTP: Wireless Communication Transfer Protocol, used to send and receive responses over the network.
These protocols are recommended as the first protocols to use when xMatters is communicating with text Devices as
they provide a receipt IDfor each notification and, if the provider supports two-way notifications, xMatters can check
for responses from the target User on their Device.
Some providers also provide xMatters with additional information, such as read receipt information that can be logged
when the User reads the message on the Device, even if they do not respond.
TAPand TAPL
These one-way protocols are older, but can still provide a redundant option to get a text message out to an SMSphone
or pager:
n
TAP: Telelocator Alphanumeric Protocol, used to send pages or SMS messages via a serial modem.
TAPL: TAP Leased, used to send pages or SMS messages using the TAP protocol and a dedicated or leased line.
Even when a network is down, these protocols may still work because they use modems and analog phone lines. The
message displayed on the target Device can also include the call-in number for xMatters, so the User can call in and then
perform actions via two-way voice communication.
Other options
Another option when configuring protocols is to use an SMStext message aggregator company. xMatters can
communicate with these companies via a two-way protocol (typically SMPP/SNPP/WCTP) and will guarantee delivery
of the text message to a target mobile phone; in most cases, the aggregator will also handle all responses back into
xMatters. These aggregators charge for this service, but will provide service-level agreements for the message delivery
and response.
Any combination of the above protocols can be used with xMatters, and for each Service Provider, the Administrator can
define the preferred order of the protocols. xMatters will attempt to send the message out using the first protocol; if it
fails, the attempt is logged and xMatters moves on to the next protocol. The key to configuring xMatters for your text
message service providers is to find out what protocols they support, and to implement as many of them as possible so
that you have redundancy in place.
For details on configuring each Protocol Provider, see "Protocol Provider Details Reference" on page 161.
Manage protocol providers

You can manage the protocol providers in your deployment using the web user interface.
To manage your protocol providers:
2. On the Administration menu, click Protocol Providers.
l
xMatters displays a current list of Protocol Providers for the system.
Protocol Providers page
3. From the Protocol Providers list, do any of the following:

l
To modify an existing Protocol Provider, click its name in the list to view its details. For more information,
see "Define protocol provider details" on page 160 below.
To remove a Protocol Provider from the list, select the check box next to the Protocol Provider or Providers
you want to remove, and then click Remove Selected.
To add a new Protocol Provider, click the Add New link, click the Provider of Type drop-down list and
select a Provider Type, and then specify the Protocol Details. For settings details for each provider type, see
"Set maximum session size" on page 160, below.
Define protocol provider details

You can define the details for each Protocol Provider using the Protocol Provider Details page.
To modify Protocol Provider details:
1. On the List Service Providers page, in the Current Service Providers table, click the name of the Service Provider
you want to modify.
l
If you are creating a new Protocol Provider, xMatters displays the Select Your Protocol Providers page. In the
Available Protocol Providers box, select the Protocol Providers you want to add to the User Service Provider,
and then click Add. To save your work and return to the User Service Providers list, click Save.
2. Click Save.
Set maximum session size

You can help optimize the throughput of your xMatters node deployment by adjusting the maximum session size for
Protocol Providers.
The session size represents the number of notifications transacted within a single session. For example, if you set the
maximum session size of an email Protocol Provider to 20, and there are at least 20 notifications to dispatch, the Device
Engine connects to the email server, sends 20 notifications, and then disconnects.
To tune the performance of Protocol Providers, ensure that the session size is as large as possible for each Protocol
Provider in use. For email providers in particular, a session size of 20 to 50 is recommended.
Set maximum message length

Protocol Providers that support text messages include a Maximum Message Length setting. This setting specifies the
maximum number of characters in a single notification the Protocol Provider will handle before truncating the remaining
text.
There are two separate portions to the message text: the message body and the appended text. The message body is the
actual notification content and the appended text contains the notification key, response choices, etc.
If the Maximum Message Length setting is less than the total number of characters in the appended text portion of the
message, the recipient will not be able to reply to the notification. In effect, the notification becomes one-way. Consider
the following examples:
Example One
n
Maximum Message Length setting: 100 characters
Message body length: 50 characters
Appended text: 150 characters
In this case, the appended text is discarded because it exceeds the Maximim message length setting. The User will
receive the entire message body of the notification because it is less than the Maximum message length, but will be
unable to reply because the appended text portion of the notification is missing.
Example Two
n
Maximum Message Length setting: 350 characters
Message body length: 150 characters
Appended text: 300 characters
In this case, the entire appended text portion of the notification will be included, but the message body will be truncated
to 50 characters. The User will receive the notification and will be able to reply because the entire appended text portion
was included in the notification.
Protocol Provider Details Reference

The following tables describe the available settings for each Protocol Provider:
BES Protocol Providers

The following table describes the settings for BES Protocol Providers.
BES Provider Details
Setting
Description
Name
Name of the protocol provider.
Description
A brief description of the provider (optional).
Setting
Description
Maximum Retries
Number of times to resend a notification before potentially using an alternate service provider;
allowable values are from 0 to 10.
Retry interval
Amount of time in seconds to wait between retries.
MDS Host Address
IP address of the Mobile Data Service (MDS) on the BES Server.
MDS Host Port
Access port of the MDS on the BES Server. The default is 8080.
Device Port
Devices browser listening port. The default is 7874.
OSVersion
Specifies the BlackBerry OS used by the targeted Users' Devices. Select one of the following
options:
n
n
4.x, 5.x:supports BlackBerry OS4.x and 5.x.

6.0 and higher:supports all versions of BlackBerry OS6.x and higher. (This option also
provides limited support for some versions of BlackBerry OS5.x; it is recommended that
you select the previous option for any Users with OSversion 5.x.)
If your Users have a number of different OSversions, it is recommended that you create at least
two Protocol Providers, one for 4.x and 5.x and one for 6.0 and higher, and assign them to two
separate User Service Providers. When a User adds their Device to xMatters, they can then
specify their User Service Provider to ensure that they are ;using the correct OS version for their
BlackBerry.
DTMF Protocol Providers

The following table describes the settings for DTMF Protocol Providers.
DTMF Provider Details
Setting
Description
Name
Description
Maximum retries
Retry interval
Maximum session
size
Number of notifications per connection/session.
Split long message
Controls whether notifications that exceed the number of characters specified by the Split size
setting are split into multiple smaller messages or sent as a single message.
Setting
Description
Split size
Determines the maximum number of characters per message sent to this Protocol Provider. This
setting applies only if the Split long message check box is selected.
Maximum message
length
If enforced by this provider, the maximum number of characters allowed per notification. For
more information, see "Set maximum message length" on page 161.
Maximum PIN
length
If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is
longer than the maximum PIN length, the leading characters are truncated.
Country
Specifies the Country to associate with this provider.
Area Code
Service providers area code.
Phone Number
Server phone number (prefixed with country and area code).
Call center phone
Indicates whether the service provider uses a call center.
Wait time between

phone and PIN
and/or PIN and
message (sec)
When the service provider uses a call center, this specifies the amount of time in seconds to
pause between either phone and PIN, or PIN and message.
Wait finish timeout
When the service provider uses a call center, this specifies the amount of time in seconds to
pause before timing out the session.
Init String Override Specifies the initialization string for the modem used by this Protocol Provider. If not specified,
the provider uses the Init String defined in the Serial Device Resources list on the Resources for
Node page. For more information, see "Resource types" on page 151.
Generic Protocol Providers

The following table describes the settings for Generic Protocol Providers.
Generic Provider Details
Setting
Description
Name
Description
Maximum Retries
Retry Interval
Maximum Session
Size
Setting
Description
Split long message
Split size
Maximum message
length
Maximum Pin
Length
Executable Path
Path to the application executable that is to act as a Protocol Provider.

Note: The path cannot exceed 50 characters in length.
Wait Time
Amount of time in seconds to wait for the application to finish processing.
List of Arguments
Any arguments or switches to be passed to the executable when running the protocol provider
application.
Arguments can be in one of two forms:
$<value>: the argument is replaced by the corresponding value, in double quotes, from the
presentation scripts @content object. For example, $username would be replaced with the
contents of the $content.username variable in double quotes (e.g., bsmith).
The fixed exceptions are $message, which is replaced by the actual message, and $pin, which
is replaced by the actual Device PIN.
<value>: arguments not prefaced by the dollar sign ($) are passed directly to the executable
(e.g., command line switches).

Note:
If the Generic provider returns a value of zero, the notification is treated as successful. Any other value is
treated as an error.
GSM Protocol Providers

The following table describes the settings for GSMProtocol Providers.
GSM Provider Details
Setting
Description
Name
Description
Maximum Retries
Setting
Description
Retry Interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Split Method
Specifies the concatenation mechanism used by the provider when splitting and reassembling
long SMSmessages. With concatenation, it is possible to send a single long message to a
mobile station as a series of several short messages, and to display them as one message on the
target Device.
Concatenation is performed at the Device itself, which uses additional information fields within
the messages to identify, sort, and join the content into a single message. Up to a maximum of
255 short messages (of less than 160 characters each)can be joined in this way. xMatters
provides the GSMUser Data Headers (UDH) method of concatenating messages.
Select one of the following options:
l
l
None:do not specify a concatenation method.

UDH: split messages using UDHconcatenation. Note that this only works with
PDUmode; see "GSMUDH Split Size", below.
Important Deployment Considerations

While xMatters supports these protocols, it has no control over how carriers and aggregators
handle the requests. Generally, UDH concatenation does not work for Devices that reside in
CDMA network. You will have to work closely with your carriers to establish the appropriate
handling, and then thoroughly test your deployment and message delivery to ensure that you
have accounted for the different methods used by your required providers to handle long SMS
messages.
Prepend +to Dest
Indicates whether to add a plus symbol (+) to the beginning of each phone number sent to the
GSM engine.
This feature is available only on deployments where all text phone Devices were created after
4.1 patch 006 or later. If you have text phone Devices that were added prior to applying the
required patch, you must either delete the Devices (which will automatically enable this feature)
or work with xMatters Support to reconfigure your existing Devices.
GSMUDH Split Size

The UDH split mechanism for GSM requires that the actual message size be smaller than the pre-configured size (i.e., the
size specified in the Split Size field). The purpose of this size difference is to leave room for adding the UDH header. For
example, if you configure the Split Size setting to 160, the actual split size will be smaller than 160.
The precise size difference is determined by the type of characters within the message. There are two different character
types:7 bits for ASCII and GSM, and 16 bits for the rest of the world. The size specified in the Split Size field is for 7bit characters.
For example, if the Split Size field is set to 160:
n
If the Split Method field is set to None, the actual split size is 70 for 16-bit characters.
If the Split Method field is set to UDH, xMatters deducts more characters to leave room for the UDH header: 10
characters are deducted for 7- and 8-bit characters, and 5 characters are deducted for 16 bits. The payload size
after.splitting would then be 150 for 7-bit, 130 for 8-bit, and 65 for 16-bit characters.
HTTP Generic Protocol Providers

The following table describes the settings for HTTPGeneric Protocol Providers. For information on how xMatters
processes SMSmessages and responses, see "Configure SMS messages and replies" on page 142.
Example Use Cases:
For more information about how to configure this Protocol Provider, see the following:
n
"Configure xMatters SMS" on page 220
Note:
If you are configuring this Protocol Provider to work with xMatters SMS, you must have simple SMSresponses
enabled, as explained in "Configure simple SMS replies" on page 143.
HTTPGeneric Service Provider Details

Setting
Description
Name
Description
Maximum Retries
Retry Interval
Maximum Session
Size
Split long message
Split size
Maximum message
length
Setting
Description
Maximum PIN
length
APIURL
The target URL to which the Device Engine submits the HTTPPOST operation. initially (e.g.,
http://webapi.somecompany.com:8080).
Username
Typically, the username supplied by the web API provider; required if the URLuses HTTP
authentication.
Password
Typically, the password supplied by the web API provider; required if the URLuses HTTP
authentication.
Response URL
The URLof the xMatters web server to which the Device Engine forwards the web API's
response from the initial submission (e.g.,
http://<webserver>:<port>/services/clickatell or
http://yourwebserver/processResponse.jsp).
Note that the web server must be able to receive update information from the provider's server.
Request Parameters This area displays an editable list of HTTP request parameters available to this provider. This list
is typically specified by the web API.
Click Add New Name/Value Pair to create a new request parameter, and then specify a Name
and Value in the related fields. To remove a request parameter, select the related check box and
then click Remove Selected Name/Value Pair.
HTTPConference Protocol Providers

The following table describes the settings for HTTPConference Protocol Providers.
HTTPConference Provider Details
Setting
Description
Name
Description
Maximum Retries
allowable values are from 0 to 10. (Note that some providers may have separate retry logic; for
example, even if you set Maximum Retries to 0, the provider may run through its own retry
paradigm. Further, be aware that increasing Maximum Retries by one increment may result in
more than one retry, as the provider will still carry out its retry logic based on the nature of the
previous call failure.)
Retry Interval
Maximum Session
Size
Setting
Description
APIURL
URL to which the Device Engine initially submits (e.g., http://webapi.somecompany.com:

8080).
Username
authentication.
Password
authentication.
Response URL
Web server URL to which the Device Engine forwards the web API's response from the initial
submission (e.g., http://yourwebserver/exampleResponse.jsp).
Request Parameters This area displays an editable list of HTTP request parameters available to this provider. This list
is typically specified by the web API.
Click Add New Name/Value Pair to create a new request parameter, and then specify a Name
and Value in the related fields. To remove a request parameter, select the related check box and
then click Remove Selected Name/Value Pair.
HTTP xMatters SMSProtocol Providers

The following table describes the settings for HTTP xMatters SMS Protocol Providers. For information on how xMatters
processes SMSmessages and responses, see "Configure SMS messages and replies" on page 142.
Note that the HTTPxMatters SMSservice is provided by xMatters; contact your Client Assistance representative to set
up an account, and for help with the required values for this page.
Note:
The xMatters SMSservice requires that you have simple SMSresponses enabled, as explained in "Configure
simple SMS replies" on page 143.
HTTP SMS Provider Details

Setting
Description
Name
Description
Maximum Retries
Retry Interval
Maximum Session
Size
Split long message
Setting
Description
Split size
If you are using the SARconcatenation method, refer to the "HTTP xMatters SMSProtocol
Providers" note following this table for more information about this setting.
Maximum message
length
Maximum PIN
length
Short Code
Compliance
Select an option to specify when xMatters should send a notification explaining terms of service
to each SMSDevice:
l
activated.
In addition to modifying the content of the Custom message, you can modify its behavior and
the Custom message to include a validation request, and then select the "Send Welcome and
Custom" option. Whenever a User added a new Device, xMatters would send a Welcome
message containing the standard terms and conditions, and then automatically send a validation
request to the Device three seconds later.
SMSprovider; for more information about specifying their content, see "SMSConfirmation and
First Alert Messages Constants" on page 213.
After changing this value, you must restart any Device Engines using this Protocol Provider for
the changes to be applied.
APIURL

8080).
Username
authentication.
Password
authentication.
Setting
Description
From
The phone number to use as the caller IDthat identifies the source of outgoing messages. Must
be a valid outgoing caller IDfor your account.
Source TON
The type of number (TON) for the source address to be used during the server session.
Response URL
Web server URL to which the Device Engine forwards the web API's response from the initial
submission (i.e., http://yourwebserver/services/xmsms).
Request Type
Select one of the following options to specify how you want xMatters to create the
POSTrequest body:
Parameters: when selected, the page will display an editable list of HTTP request parameters
available to this provider. This list is typically specified by the web API. When the notification
request is submitted to the protocol provider, xMatters will build the POSTrequest body using
these parameters.
n
Click Add New Name/Value Pair to create a new request parameter, and then specify a
Name and Value in the related fields. To remove a request parameter, select the related
check box and then click Remove Selected Name/Value Pair.
For example, to add an APIID (as required by some providers to identify your account),
add an "api_id" parameter and set the value to your IDnumber.
Body:when selected, the page will display a Content Type and Content field that allow you to
create a custom string to use as the request body. For more information, see "Creating a custom
request body", below.
Country-Specific
Overrides
You can set country-specific overrides for the Protocol Provider's Source Address: if a country
override exists that matches the country specified for a User's text phone Device details, the
Protocol Provider will use the source address overrides.
To add a new country override, click Add New Country, and then select the country for which
you want to configure the override from the Country drop-down list. Select an option in the
Short Code Compliance if you want to send a welcome notification to Users whose Devices
match the specified country.
In the Source Address field, type the address you want to use for recipients in that country.
You can also specify a separate address to which recipients should send their responses. If you
specify an address in the Reply To field, the response portion of the SMSmessage includes
"Send reply to <address>." Note that this does not override or affect the original source of the
message; it provides a visual reminder to the recipient that they should respond to a different
address.
Note: This feature requires that you have configured simple SMS replies, as described in
"Configure simple SMS replies" on page 143.
Creating a custom request body

When you select the Body option in the Request Type drop-down list, the Protocol Provider page displays the Content
Type and Content fields. The following sections describe how to use these fields to build a customized request body.
Content Type
Type any valid MIMEtype (also known as Internet media type) to identify the format in which the content will be
submitted to the protocol provider; for example:
n
application/xml
text/html
text/javascript
applications/json
Note that xMatters does not perform any validation on this field; ensure that you have entered your MIMtype correctly.
Content
Type the body of the HTTPrequest in the field. You can include any of the following variables, which will be replaced
in the submitted request with the actual values:
n
$(from):the value specified in the From field on the Protocol Provider settings.
$(message):the message content of the notification.
$(node_id):the ID of the xMatters node sending the request
$(ntfn_id):the xMatters notification ID
$(password):the value specified in the Password field on the Protocol Provider settings
$(pin):the PINor phone number for the notification's target Device
$(source_ton):the value specified in the SourceTON field in the Protocol Provider settings
$(username):the value of the Username field in the Protocol Provider setting
$(webserverurl):the URL of the xMatters web server. Note that this value is determined by the
WEBSERVERGlobal Constant
Example
The following example illustrates the request body required to connect with the OpenMarket SMS provider using the
application/xml MIMEtype and a demonstration account:
<?xml version="1.0"?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="XML/SMS/1.0.0"/>
<account id="$(username)" password="$(password)"/>
<option charge_type="0" mlc="2" datacoding="UCS2" note="{ntfnId:$(ntfn_id), nodeId:$(node_
id)}"/>
<source ton="$(source_ton)" address="$(from)"/>
<destination ton="1" address="$(pin)"/>
<message data="$(message)"/>
<delivery receipt_requested="true" url="$(webserverurl)
/callbacks/openmarket/deliveryReceipt"/>
</request>
Note that you will need to modify the above settings to suit your production deployment. For more information, consult
your OpenMarket representative.
HTTP xMatters Conference Protocol Providers

The following table describes the settings for HTTPConference Protocol Providers.
The HTTPxMatters Conference service is provided by xMatters; contact your Client Assistance representative to set up
an account, and for help with the required values for this page.
HTTP Conference Provider Details

Setting
Description
Name
Description
Maximum Retries
Number of times to resend a notification before potentially using an alternate service

provider; allowable values are from 0 to 10.
Retry Interval
Maximum Session Size
APIURL

8080).
Username
authentication.
Password
authentication.
From
The phone number to use as the caller IDthat identifies the source of outgoing messages.
Must be a valid outgoing caller IDfor your account and formatted using "+" and a country
code; e.g., "+16175551212".
To
The target phone number for the notifications.
Status Call Back URL
Web server URLto which status responses should be sent.
Response URL
Web server URL to which the Device Engine forwards the web API's response from the
initial submission (i.e.., http://yourwebserver/voicexml/processResponse.jsp).
Interaction Script URL
Web server URL at which the responses can access the interaction script.
Request Parameters
This area displays an editable list of HTTP request parameters available to this provider.
This list is typically specified by the web API.
Click Add New Name/Value Pair to create a new request parameter, and then specify a
Name and Value in the related fields. To remove a request parameter, select the related
check box and then click Remove Selected Name/Value Pair.
Jabber Protocol Providers

The following table describes the settings for Jabber Protocol Providers (one-way only).
Jabber Provider Details

Setting
Description
Name
Description
Maximum Retries
Retry Interval
Maximum Session
Size
Split long message
Split size
Maximum message
length
Maximum Pin
Length
MAPI Protocol Providers

The following table describes the settings for MAPI Protocol Providers.
Note:
When creating a MAPI Protocol Provider, you must specify an account in the Log On Properties for the
xMatters node Windows Service. The account name and password must match the owner of the Outlook profile
on the machine running the Notification Server Node. Restart the Windows Service after specifying the account
details.
Setting
Description
Name
Description A brief description of the provider (optional).

Maximum
Retries
Number of times to resend a notification before potentially using an alternate service provider; allowable
values are from 0 to 10.
Retry
interval
Setting
Description
Maximum Number of notifications per connection/session.

session size
Split long
message
Controls whether notifications that exceed the number of characters specified by the Split size setting are
split into multiple smaller messages or sent as a single message.
Split size
Determines the maximum number of characters per message sent to this Protocol Provider. This setting
applies only if the Split long message check box is selected.
Maximum
message
length
If enforced by this provider, the maximum number of characters allowed per notification. For more
information, see "Set maximum message length" on page 161.
Maximum
PIN length
If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer
than the maximum PIN length, the leading characters are truncated.For email Protocol Providers (i.e.,
SMTP, Lotus Notes, and MAPI), the maximum pin length applies only if all of the characters before the
@ symbol are digits. In this case, the Maximum PINLength setting controls how many digits are allowed
before the @ symbol.
Notes Protocol Providers

The following table describes the settings for Notes Protocol Providers.
NOTES Provider Details
Setting
Description
Name
Description
Maximum
Retries
Retry interval
Maximum
session size
Split long
message
Split size
Maximum
message length
Setting
Description
Maximum PIN
length
longer than the maximum PIN length, the leading characters are truncated.For email Protocol
Providers (i.e., SMTP, Lotus Notes, and MAPI), the maximum pin length applies only if all of the
characters before the @ symbol are digits. In this case, the Maximum PINLength setting controls
how many digits are allowed before the @ symbol.
Reply To
Email address to which responses to notifications should be sent.

When a recipient responds to an email notification from this provider, the To: field on the reply
is automatically populated with this email account. If this account is not specified, responses are
sent to the Mailbox specified in the Notes Device Engine details.
PSTN Protocol Providers

The following table describes the settings for PSTN Protocol Providers.
PSTN Provider Details
Setting
Description
Name
Description
Maximum
Retries
Retry interval Amount of time in seconds to wait between retries.
PUCP Protocol Providers

The following table describes the settings for PUCP Protocol Providers.
PUCP Provider Details
Setting
Description
Name
Description A brief description of the provider (optional).

Maximum
Retries
Number of times to resend a notification before potentially using an alternate service provider; allowable
values are from 0 to 10.
Retry
Interval
Maximum Number of notifications per connection/session.

session size
Setting
Description
Split long
message
Controls whether notifications that exceed the number of characters specified by the Split size setting are
split into multiple smaller messages or sent as a single message.
Split size
Determines the maximum number of characters per message sent to this Protocol Provider. This setting
applies only if the Split long message check box is selected.
Maximum
message
length
Maximum
PIN length
If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer
than the maximum PIN length, the leading characters are truncated.
Originator
Code identifying the message source to the protocol provider.
User Name User name, if required by your service provider.

Password
Password, if required by your service provider.
Country
Area Code Service providers area code.

Phone
Number
Service providers phone number.
UCP Level UCP operation level required by the service provider; the default setting of 01 is implemented for
legacy operations.
Encoded
Select the method used to encode messages sent to the service provider: ENCODE_GSM will encode
messages using GSM 7-bits encoding, and ENCODE_HEX will encode messages using an ASCII-based
hex protocol.
Baud Rate
Specifies modem speed to match the paging service provider (many still use 1200 or 2400).
Databits
Specifies databits to match the paging service provider.
Stopbits
Specifies stopbits to match the paging service provider.
Parity
Specifies parity to match the paging service provider (typically even).
Flow
Control
Specifies the flow control between the modem and the serial port (similar to handshaking).
Init String
Override
Specifies the initialization string for the modem used by this Protocol Provider. If not specified, the
provider uses the Init String defined in the Serial Device Resources list on the Resources for Node page.
For more information, see "Resource types" on page 151.
SIP Protocol Providers

The following table describes the settings for SIPProtocol Providers.
SIP Provider Details
Setting
Description
Name
Description
Maximum Retries
Retry Interval
Use Device Engine

Settings
When selected, the Protocol Provider uses the settings specified in the Inbound SIP Registration
List on the SIP Device Engine Details page. Clear this checkbox to use specific settings for this
Protocol Provider, as described in the following table, SIP Provider - Inbound Registration
settings.
Note that xMatters attempts to use the specified settings to send a notification once, and then
attempts to use the settings specified in the SIP Device Engine details. These two attempts count
as one try toward the maximum number of retries as specified above. If these attempts fail
beyond the maximum number of retries, then xMatters will attempt to use the next Protocol
Provider specified in the User Service Provider, if available.
Call-out Script
Name of the script used to handle the outbound call.
Phone Class Details Defines the Phone Class to use for this Protocol Provider. For more information about Phone
Classes and a description of these settings, see "Phone Class Resources" on page 153.
Initial Silence
Maximum duration (in milliseconds) of silence before the greeting. If this duration is exceeded,
then xMatters treats the answerer as a machine.
Greeting
Maximum duration (in milliseconds) of the greeting phrase. If this duration is exceeded, then
xMatters treats the answerer as a machine.
After Greeting
Silence
Maximum duration (in milliseconds) of the silence after detecting a greeting. If this duration is
exceeded, then xMatters treats the answerer as human.
Minimum Word
Length
Minimum duration (in milliseconds) of voice to consider as a word.
Maximum Word
Length
Maximum duration (in milliseconds) of voice to consider as a word.
Maximum Number
of Words
Maximum number of words in a greeting. If this value is exceeded, then xMatters treats the
answerer as a machine.
Setting
Description
Between Words
Silence
Minimum duration (in milliseconds) of silence after a word to consider the audio that follows as
a new word.
Silence Threshold
The threshold to use to determine silence on the line; larger values are less sensitive to static. If
the amount of "noise" on the line is larger than this value, then the inbound is treated as a voice;
otherwise, it is treated as silence. Valid values are from 0 to 65535; the default value is 256.
The silence threshold required for Protocol Providers may vary. Some phones attempt to amplify
the speaker's voice, which can also amplify any ambient noise and make the default value of
256 too low. Other phones may be designed to suppress the noise, and unintentionally suppress
the voice as well. To determine the appropriate value for phones in your system, you may need
to enable detailed logging and experiment using different values.
Total Analysis
Time
Maximum amount of time (in milliseconds) allowed for the algorithm to determine whether the
answerer is HUMAN or MACHINE.
Phone Class
Exceptions
Defines any Phone Class Exceptions for this Protocol Provider. For more information about
Phone Class Exceptions, see "Phone Class Resources" on page 153.
The following table describes the settings for SIPProvider Inbound Registration.
SIP Provider - Inbound Registration settings
Setting
Description
SIP Server Address IP address of the SIP server.

SIP Server Port
Port to use on the SIP server.
Local Port
Local port to which the Device Engine will bind and which the SIP Server will use to
communicate with xMatters.
SIP Domain
Domain used by the SIP server.
SIP Outbound
Proxy Address
If required, the IP address of the outbound proxy server.
SIP Outbound
Proxy Port
If required, the port of the outbound proxy server.
RTP Port (min)
The lower limit to the port number on which RTP is allowed.
RTP Port (max)
The upper limit to the port number on which RTP is allowed.
DTMF Payload ID
Number identifying the DMTF payload. The default value is 101, though some SIP Server
environments may require a different value. Contact your SIP Server Administrator for more
information.
Setting
Description
Registration
Attempts
How many times the Protocol Provider should attempt to register.
Registration
Timeout
How long, in seconds, to wait before timing out on a registration attempt. The default is 60.
Session Timeout
How long, in seconds, to wait before timing out a SIP session. The default is 3600.
User Name
User name to use on the SIP server.
Password
Password, if required, for the user name on the SIP server.
Display Name
Name displayed as source of call.
Note:
Due to resource-contention that can affect call quality and performance, xMatters SIP is not supported for
virtualized environments (see also "Virtual Machine Deployment Guidelines" on page 22).
SMPP Protocol Providers

The following table describes the settings for SMPP Protocol Providers. For information on how xMatters processes
SMSmessages and responses, see "Configure SMS messages and replies" on page 142.
Note:
xMatters supports SMPPversion 3.4 only.
SMPP Provider Details

Setting
Description
Name
Description
Maximum Retries
Retry interval
Maximum session
size
Split long message
Split size
If you are using the SARconcatenation method, refer to the "SARSplit Size" note following
this table for more information about this setting.
Setting
Description
Maximum message
length
Maximum PIN
length
Split Method
Specifies the concatenation mechanism used by the provider when splitting and reassembling
long SMSmessages. With concatenation, it is possible to send a single long message to a
mobile station as a series of several short messages, and to display them as one message on the
target Device.
Concatenation is performed at the Device itself, which uses additional information fields within
the messages to identify, sort, and join the content into a single message. Up to a maximum of
255 short messages (of less than 160 characters each)can be joined in this way. xMatters
provides two methods of concatenating messages:GSMUser Data Headers (UDH) and SMPP
Segmentation and Reassembly (SAR).
l
l
None:do not specify a concatenation method.

Message Payload: deliver long messages using a separate parameter (message_payload)
that supports up to 64K worth of characters. This method does not split and reassemble the
message.
SAR: split messages using SAR concatenation. See the "SARSplit Size" note following
this table for more information about this setting.
UDH: split messages using UDHconcatenation.
Important Deployment Considerations

While xMatters supports these protocols, it has no control over how carriers and aggregators
handle the requests. You will have to work closely with your carriers to establish the
appropriate handling, and then thoroughly test your deployment and message delivery to ensure
that you have accounted for the different methods used by your required providers to handle
long SMS messages.
Note also that some CDMA Devices cannot receive messages longer than 160 characters. In
most cases, no warnings or errors are returned, but the SMS aggregator never delivers the
messages to the Device. Be sure to check your deployment for CDMA-compatibility before
configuring your long message settings.
Supports New Line
Indicates whether the Protocol Provider supports new line characters (line breaks).
Setting
Description
Short Code
Compliance
Select an option to specify when xMatters should send a notification explaining terms of service
to each SMSDevice:
l
activated.
In addition to modifying the content of the Custom message, you can modify its behavior and
the Custom message to include a validation request, and then select the "Send Welcome and
Custom" option. Whenever a User added a new Device, xMatters would send a Welcome
message containing the standard terms and conditions, and then automatically send a validation
request to the Device three seconds later.
SMSprovider; for more information about specifying their content, see "SMSConfirmation and
First Alert Messages Constants" on page 213.
After changing this value, you must restart any Device Engines using this Protocol Provider for
the changes to be applied.
Source Address
Number associated with your SMPP account. This number is used to indicate the sender for
outgoing messages. If specified, this value will override the Device Engine setting.
Source Address
TON
Your SMPP accounts TON to be used during the server session. If specified, this value will
override the Device Engine setting.
Source Address
NPI
Clients NPI required by your service provider for the source address. If specified, this value will
override the Device Engine setting.
Prepend +to Dest
Indicates whether to add a plus symbol (+) to the beginning of each phone number sent to the
SMPP engine.
Default Dest
Address TON
TON required by your service provider for the default destination address. If specified, this value
will override the Device Engine setting.
Default Dest
Address NPI
NPI required by your service provider for the default destination address. If specified, this value
will override the Device Engine setting.
Setting
Description
Dest Address
Subunit
Specifies where to store the message on the target Device (e.g., in a SIM card).
Deactivation Error
Codes
A comma-separated list of error codes that indicate a Device has been delisted or deactivated by
its service provider. If one of these codes is returned from the Protocol Provider, xMatters will
deactivate the targeted Device and, based on the selected option in the Notifiy Upon
Deactivation drop-down list, notify the User and their supervisors.
For more information about configuring this feature, see "Configure automatic SMS device
deactivation" on page 224.
Notify Upon
Deactivation
Specifies who should be notified when a Device has been marked as delisted or deactivated by
its service provider; select one of the following:
l
l
l
Supervisors and Device Owners:(default) notifies the User who owns the Device, their
direct supervisors, and the supervisor of any Groups to which the User belongs.
Device Owners:notifies only the User (or Users) who owns the Device.
Supervisors:notifies the direct supervisors and Group Supervisors for the User who owns
the Device.
Do Not Notify:does not send notifications.
Note that the notification will automatically be sent to the User or supervisor's email Device; if
the recipient does not have an email Device, the notification is sent to their default Device.
Add New
Tag/Value Pair
Allows you to define optional tag/value pairs that can be used to sort messages. For example,
XYZ Marketing, XYZ Sales, XYZ Data_Center.
When adding a new tag/value pair, select one of the following types:
n
n
n
n
n
C-String: any character string; e.g., "Billing Department"

Octets: any string in hex format; e.g., "233A4500112F"or "0A"
Integer: any integer between -2147483648 and 2147483647
Short: any integer between -32768 and 32767
Byte: any two characters in hex mode; e.g., "1A", "00", or "0C".
Setting
Description
Country-Specific
Overrides
You can set country-specific overrides for the Protocol Provider's Source Address, Source
Address TON and Source Address NPIsettings. If a country override exists that matches the
country specified for a User's text phone Device details, the Protocol Provider will use the
source address overrides.
To add a new country override, click Add New Country, and select the country for which you
want to configure the override from the Country drop-down list. Select the Short Code
Compliance check box if you want to send a welcome notification to Users whose Devices
match the specified country. (Note that this setting takes precedence over the Protocol Provider
setting.)
Set the Source Address, Source TON, and Source NPIyou want to use. You do not need to
enter information into all of the fields; if a field is left blank, the override will use the default
settings configured for the Protocol Provider.
You can also specify a separate address to which recipients should send their responses. If you
specify an address in the Reply To field, the response portion of the SMSmessage includes
"Send reply to <address>." Note that this does not override or affect the original source of the
message; it provides a visual reminder to the recipient that they should respond to a different
address.
Note: This feature requires that you have configured simple SMS replies, as described in
"Configure simple SMS replies" on page 143.
SARSplit Size
The SARsplit mechanism for SMPPrequires that the actual message size be smaller than the pre-configured size (i.e., the
size specified in the Split Size field). The purpose of this size difference is to leave room for adding the SARheader. For
example, if you configure the Split Size setting to 160, the actual split size will be smaller than 160.
The precise size difference is determined by the type of characters within the message. There are three different character
types:7 bits for ASCII and GSM, 8 bits for western Europe, and 16 bits for the rest of the world. The size specified in
the Split Size field is for 7-bit characters.
For example, if the Split Size field is set to 160:
n
If the Split Method field is set to None, the actual split size is 140 for 8-bit characters, and 70 for 16-bit characters.
If the Split Method field is set to SAR, xMatters deducts more characters to leave room for the SAR header: 10
characters are deducted for 7- and 8-bit characters, and 5 characters are deducted for 16 bits. The payload size
after.splitting would then be 150 for 7-bit, 130 for 8-bit, and 65 for 16-bit characters.
SMPP language encoding

SMPP Protocol Providers can detect the language used in the message, and you can modify the deSmppContext.xml file
to specify which language encodings are supported by an SMPP service provider.
To set up the language detection capability:

1. Stop the xMatters node.
2. Open the following file:
<xMHOME>\node\assets\resources\spring\integration\deSmppContext.xml
3. In the deSmppContext.xml file, locate the smppServiceProviderSupportEncoding bean.

4. For each encoding type, set the value to true for supported types and false for unsupported types (contact your
SMPP provider for details).
l
For example, if the SMPP Service Provider does not support latin1 encoding:
CHANGE:
<property name="latin1Encoding">
<value>true</value>
</property>
TO:
<property name="latin1Encoding">
<value>false</value>
</property>
5. Save and close the XML file.

In this case, xMatters will not do any encoding, and the SMPP data_encoding will be set as the default value (typically
0).
SMTP Protocol Providers

The following table describes the settings for SMTP Protocol Providers.
SMTP Provider Details
Setting
Description
Name
Description
Maximum Retries
Retry interval
Maximum session
size
Split long message
Split size
Setting
Description
Maximum message
length
Maximum PIN
length
longer than the maximum PIN length, the leading characters are truncated.For email Protocol
Providers (i.e., SMTP, Lotus Notes, and MAPI), the maximum pin length applies only if all of
the characters before the @ symbol are digits. In this case, the Maximum PINLength setting
controls how many digits are allowed before the @ symbol.
Authenticate
Specifies whether the service provider requires authentication.
Account
If authentication is active, the authentication account name.
Password
If authentication is active, the password for the associated account.
Email Sender
Email address used to send notifications (appears in the From: field on email messages).
Reply To
Email address to which responses to notifications should be sent.

When a recipient responds to an email notification from this provider, the To: field on the
reply is automatically populated with this email account. If this account is not specified,
responses are sent to the account specified as the Email Sender.
Server Address
URL or IP address for the Protocol Providers server.
Server Port
Port number of the Protocol Providers server.
Domain Name
If required, the domain name for the Email Sender address.
Use SSL
Indicates whether the service provider uses encryption.
Note:
The S/MIME (Secure/Multipurpose Internet Mail Extensions) standard is not supported for email responses.
SNPP Protocol Providers

The following table describes the settings for SNPP Protocol Providers.
SNPP Provider Details
Setting
Description
Name
Description
Maximum retries
Setting
Description
Retry interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Server Address
Server Port
Account
Account name, if required by your service provider.

Note: Some SNPPProviders, such as PageOne, require a password, but do not supply or require
an account name. If this is the case, enter your password in the Account field, and leave the
Password field blank.
Password
Password, if required by your service provider; see note in Account field, above.
Two Way
Specifies whether the service is two-way.
Multiple
Notifications per
Session
When selected, the provider will process multiple notifications per connection session. If this
option is not selected, the provider must reconnect with the SNPPserver for each notification
processed.
Default Poll Period
The providers default polling period, in seconds.
SUCP Protocol Providers

The following table describes the settings for SUCPProtocol Providers.
SUCP Provider Details
Setting
Description
Name
Description
Setting
Description
Maximum Retries
Retry interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Originator
Code identifying the message source to the protocol provider.
User Name
User name, if required by your service provider.
Password
Server Address
Server Port
UCP Level
UCP operation level required by the service provider; the default setting of 01 is implemented
for legacy operations.
Encoded
Select the method used to encode messages sent to the service provider: ENCODE_GSM will
encode messages using GSM 7-bits encoding, and ENCODE_HEX will encode messages using
an ASCII-based hex protocol.
TAP Protocol Providers

The following table describes the settings for TAPProtocol Providers.
TAP Provider Details
Setting
Description
Name
Description
Setting
Description
Maximum Retries
Retry interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Country
Area Code &

Phone Number
Service providers area code and phone number.
Baud Rate
Databits
Stopbits
Parity
Flow Control
Support CTL
Specifies whether the service provider supports control characters.
Password
If required, the password to access the account.
Init String Override Specifies the initialization string for the modem used by this Protocol Provider. If not specified,
the provider uses the Init String defined in the Serial Device Resources list on the Resources for
Node page. For more information, see "Resource types" on page 151.
TAP Leased Protocol Providers

The following table describes the settings for TAPLeased Protocol Providers.
TAP Leased Provider Details

Setting
Description
Name
Description
Maximum Retries
Retry interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Country
Baud Rate
Databits
Stopbits
Parity
Flow Control
Support CTL
Specifies whether the service provider supports control characters.
Password
If required, the password to access the account.
Virtual Protocol Providers

The following table describes the settings for Virtual Protocol Providers.
Virtual Device Provider Details

Setting
Description
Name
Description
Maximum retries
Retry interval
Maximum session
size
Split long message
Split size
Maximum message
length
Maximum PIN
length
Port
Port number on the computer where the virtual device software is installed.
IP Address
IP address of the computer where the virtual device software is installed.
WCTP Protocol Providers

The following table describes the settings for WCTPProtocol Providers.
WCTP Provider Details
Setting
Description
Name
Name of the service provider.
Description
Description of the provider.
Maximum Retries
Retry interval
Maximum session
size
Number of notifications per connection/session
Setting
Description
Split long message
Split size
Maximum message
length
Maximum PIN
length
Server Address
URL or IP address for the Protocol Providers server; e.g.:

http://100.100.100.100:8888/applications/myapp
https://wctp.url.com/wctp
Account
Account name, if required by your service provider.
Password
Default Poll Period
Specifies how long, in seconds, the Device Engine should continue to poll the WCTPserver
every minute for responses to each notification; the default is 3600 (one hour). Note that this
setting does notspecify how often the WCTPserver should be polled.
User service providers

User Service Providers are the Service Providers that can be selected at the User level for Devices. User Service Providers
are configured separately for each Company in the system.
To view and manage User Service Providers:
2. On the Administration menu, click User Service Providers.
l
xMatters displays a current list of User Service Providers for the Company.
User service providers | 191
User Service Providers page
3. From the User Level Providers list, do any of the following:

l
To modify an existing Service Provider, click its name in the list to view its Service Provider Details. For
more information about editing Service Provider Details, see the following section, "Define user service
providers".
To remove a User Service Provider from the list, select the check box next to the User Service Provider or
Service Providers you want to remove, and then click Remove Selected.
To add a new User Service Provider, click the Add New link, and specify the User Service Provider details
for the new User Service Provider, as explained in the User Service Provider Details settings table below.
After you click Save to create the User Service Provider, xMatters displays the Select Your Protocol
Providers page. In the Available Protocol Providers box, select the Protocol Providers you want to add to the
User Service Provider, and then click Add. To save your settings and return to the User Service Providers list,
click Save.
Define user service providers

You can define the details for each User Service Provider using the Service Provider Details page.
To modify User Service Provider details:
1. On the Service Providers page, in the Current Service Providers table, click the name of the Service Provider you
want to modify.
2. On the Service Provider Details page, enter the following information into the form:
User service providers | 192
User Service Provider Details settings

Setting
Description
Name
Name of the Service Provider. This is the name that Users will see in the Provider drop-down list on the
Device Details page (e.g., Email Device Details page).
Description Description of the Service Provider.

Device
Types
Device type to associate with this Service Provider.
PIN Mask
How many characters of the Users PIN are used for this provider.
3. Click Save.
l
If you are creating a new User Service Provider, xMatters displays the Select Your Protocol Providers page.
In the Available Protocol Providers box, select the Protocol Providers you want to add to the User Service
Provider, and then click Add. To save your work and return to the User Service Providers list, click Save.
4. To prevent the User Service Provider from using a Protocol Provider when notifying a Device, select the Protocol
Providers you want to disable, and then click Disable Selected.
l
This does not disable the Protocol Provider in xMatters, but deactivates it within the User Service Provider.
5. To change the order in which the User Service Provider uses the Protocol Providers, click the Reorder link above
the Protocol Providers table. On the Order Protocol Providers page, use the Move Up and Move Down buttons to
change the order of the Protocol Providers, and then click Save to return to the User Service Providers details.
l
When delivering a notification, xMatters will attempt to deliver a notification to the first Protocol Provider
in the list for the number of times specified in the Maximum number of retries setting on the Protocol
Provider details page. If all of these attempts fail, xMatters will attempt to deliver to the next Protocol
Provider in the list.
LDAP servers
If your organization uses LDAP authentication, you can set the parameters for communication between xMatters and
your LDAP servers in the web user interface. Before configuring the LDAP options, it is recommended that you discuss
requirements with your LDAP administrator.
In a multiple-Company deployment, LDAP servers and domains are Company-specific, and Company Administrators
must specify their LDAP settings separately for each Company in xMatters.
To view and manage LDAP servers:
1. Log in to xMatters.
2. On the Administration tab, in the Configuration menu, click LDAP Servers.
l
xMatters displays the LDAP Servers page.
LDAP servers | 193
LDAP Servers page
3. In the LDAPServers table, do any of the following:

l
To modify an existing LDAPserver, click its name to view its details. For more information about the
required settings, see "Define LDAP server details", below.
To remove a server from the list, select the check box next to the servers you want to remove, and then click
Remove.
To create a new LDAPserver, click the Add New link above the table, and specify the settings for the new
server on the LDAPServer Details page. For more information about the required settings, see "Define LDAP
server details", below.
To reorder the servers in the list, select the Move Up or Move Down button for the server you want to move.
When a User is logging in, and has the "ALL"option selected for the LDAPServer field for their web login
settings, xMatters attempts to authenticate the User against the listed LDAPservers beginning with the first
server, and continuing down the list.
To test the configuration for an LDAPserver, click the Authentication Test button in the Actions column for
the server you want to test. In the LDAPAuthentication Test dialog box, type a User Login and User
Password for a user in the target LDAPsystem. If the LDAPserver is properly configured, the dialog box
displays a confirmation message that the authentication was successful.
Define LDAP server details

You can define the details for each of the LDAPservers in your deployment on the LDAPServer Details page.
To define LDAPserver details:
1. On the LDAPServers page, click the name of the LDAPserver you want to modify, or click the Add New link to
create a new LDAPserver.
l
xMatters displays the LDAPServer Details page:
LDAP servers | 194
LDAPServer Details page
2. On the LDAP Server Details page, specify the following information:

Detail
Description
Name
The name of the LDAPserver used to identify the server on the LDAPServers page, and in Users'
Web Login details.
Description
A brief description of the LDAPserver.
Primary Host
IP address of the primary LDAP Server for xMatters.
Primary Port
Port number xMatters should use to communicate with the primary LDAP Server. (The default
port for LDAPis 389; the default port for LDAPover SSLis 636.)
Use SSL
When selected, uses the Secure Sockets Layer protocol when communicating with the primary
LDAP server.
Secondary Host
IP address of the secondary (failover) LDAP Server for xMatters. For more information about the
secondary LDAPserver settings, see "Secondary LDAPServers", below.
Secondary Port
Port number xMatters should use to communicate with the secondary LDAP Server. (The default
port for LDAPis 389; the default port for LDAPover SSLis 636.)
Use SSL
When selected, uses the Secure Sockets Layer protocol when communicating with the secondary
LDAP server.
LDAP servers | 195
Detail
Description
LDAP Type
Select one of the following option to specify the type of LDAPserver:

n
n
n
Base DN
Simple: Creates a template using the User's xMatters Web Login ID and sends it to the
LDAPdirectory for verification.
Anonymous: Queries the LDAPdirectory for the User's LDAPcredentials.
Bound: Queries the LDAPdirectory for the User's LDAPcredentials using a bound
distinguished name and password.
For simple LDAPservers, this value specifies the distinguished name (DN) when it is known, and
allows the user web login to be referenced directly as part of the DN by using the special
substitution token, %UID% within a template. For example, %UID%@company.com would replace
the token %UID% by the Web Login ID from each Users profile details, effectively using the
User's corporate email address as the LDAPlogin template.
For anonymous or bound LDAPservers, this value specifies the base DNof the FDAPdirectory
branch from which all searches should begin. At a minimum, this value should be set to the top of
your LDAPdirectory tree. For example,
ou=directory,dc=company,dc=com,o=users,ou=mycompany.
Search Filter
Specifies the user search filter, which must be a valid LDAPsearch filter. This parameter provides
greater flexibility in searching because it allows you to put the User Login ID(represented by the
special substitution token, %UID%) in any location within the search filter. For more information
about this field, see "Create LDAP search filters", below.
Required for anonymous and bound LDAPservers.
Bind DN
Distinguished name used in conjunction with the password value to bind to the server when
searching for entries.
Required for bound LDAPservers only.
Bind Password
Password used in conjunction with the bindDN parameter. Since the bind password is probably
sensitive data, it should be properly protected using APSecure. (For more information about using
APSecure, see "Using APSecure" on page 91).
Required for bound LDAPservers only.
3. Click Save to apply your settings.

If you have any difficulties configuring your LDAP details, you can view the
<xMHOME>/webserver/webapps/cocoon/WEB-INF/logs/AlarmPoint_WebApp.log file for information about the log
in attempts.
Secondary LDAPServers
In xMatters, the secondary LDAPserver settings provide redundancy for failover situations. The secondary server is
contacted only if there is a connection failure with the primary server; otherwise, responses from the primary server are
considered authoritative.
The following use cases provide examples of how and when xMatters contacts the secondary server.
LDAP servers | 196
Login Use Case One

1. The connection to the primary server succeeds.
2. An LDAPbind operation is requested for authentication based on the supplied user credentials.
3. A failed response is returned.
4. An error message is displayed, indicated that the user credentials are not valid.
Note that xMatters does not attempt to contact the secondary LDAPserver based on invalid user credentials.
Login Use Case Two
1. The connection to the primary server fails.
2. The connection to the secondary server succeeds.
3. An LDAPbind operation is requested for authentication based on the supplied user credentials.
4. A failed response is returned.
5. An error message is displayed, indicated that the user credentials are not valid.
Login Use Case Three
1. The connection to the primary server fails
2. The connection to the secondary server fails.
3. An error message is displayed, indicating that the server cannot be contacted.
Create an LDAP Base DN

xMatters uses the Base DN setting on the LDAPServer Details page with the login name and password to validate
against the LDAP Server. Unlike many applications with LDAP integration, xMatters attempts to log in the user.
For simple LDAPservers, xMatters substitutes the login name supplied by the User for the %UID% in the template
configured in the Base DNfield on the LDAP Servers page, and sends this and the password making the login request to
the LDAP directory. xMatters then examines the result to determine whether the user has valid credentials.
There are three standard formats for these templates:
n
Distinguished Name: If you know the format in which Distinguished Names are stored in your LDAP directory,
you can enter the DN format directly in the template field; for example,
dc=com,dc=company,ou=directory,uid=%UID%
Windows Domain: If you are using a Windows Active Directory Server for your LDAP server, then you will
typically use a template in the following format: DOMAIN_NAME/%UID%
Internet format: If you are using a Linux/Unix LDAP Server, then you will typically use a template in Internet
format: %UID%@company.com
Note:
If the User's Web Login ID is not part of the Distinguished Name, you must create either an anonymous or
bound LDAPserver to query the LDAP directory and bind the DN to the User. For more information, see
"Create LDAP search filters", below.
Create LDAP search filters

Search filters enable you to define search criteria and provide more efficient and effective searches as part of the LDAP
authentication for the web user interface. The Search Filter parameter provides greater flexibility in searching because it
allows you to put the user's web login IDin any location within the search filter. A special substitution token, %UID%,
indicates where the login IDshould be inserted.
LDAP servers | 197
Note:
Most LDAP servers support LDAP search filters; however, since LDAP servers are not created equal, the type of
LDAP search filter provided should be compliant with your LDAP server. For more information, see your
LDAP server documentation.
To specify a prefix, you could enter the following into the Search Filter field on the LDAPServer Details page:
sAMAccount=%UID%
To specify a more sophisticated filter, you could enter the following:

(&(objectClass=person)(!(objectClass=user))(sAMAccount=%UID%))
Match attributes
The following example illustrates how you could match for users distinguished by two objectClass attributes (one equal
to 'person' and another to 'user'):
(&(objectClass=person)(objectClass=user))
Notice the ampersand symbol (&) symbol at the start. Translated, this means: search for objectClass=person AND
object=user. Alternatively, you could use:
(|(objectClass=person)(objectClass=user))
Translated, this means: search for objectClass=person OR object=user. The pipe symbol (|) denotes 'OR'. As this is not a
special XML character, it should not need escaping.
Use wildcards
The following illustrates the use of wildcards:
(&(objectClass=user)(cn=*Marketing*))
This means: search for all entries that have objectClass=user AND a cn that contains the word 'Marketing'.
Exclude attributes
To exclude entities which match an expression, use an exclamation point (!). For example, the following will find all
Chicago groups except those with a "Wrigleyville" OU component (note the extra parentheses around the expression to
exclude):
(&(objectClass=group)(&(ou:dn:=Chicago)(!(ou:dn:=Wrigleyville))))
Global Configuration
You can set the logging and Health Monitor options for the entire xMatters system using the Global Configuration page.
Note that the settings on the Global Configuration page apply to the main xMatters logs and Health Monitor. Individual
components such as Nodes and Device Engines also have log settings to create and maintain separate log files. For more
information about logging configuration levels, see "Configure node logging" on page 117.
About the Health Monitor

The Health Monitor component is responsible for monitoring the community of nodes, generating Alerts when error
conditions are detected, and taking corrective action where possible. Its functions can be categorized as follows:
n
Monitoring includes detection of hardware failure, software defects, mis-configuration, and system resource
deficiencies.
Global Configuration | 198
Notification includes all the standard notification mechanisms provided by xMatters, and a set of default
notification mechanisms provided by the Health Monitor itself.
The Health Monitor triggers an Alert when any of the following conditions are met:
n
Database connectivity has been lost
Node has failed/Node connection has been lost
Node-to-node communication has failed
Component has been configured incorrectly
SIP Device Engine cannot register with SIPserver
Message in the message bus has expired
Unhandled exception has occurred
Carrier failure (e.g., Service Provider failure)
The latter list is not comprehensive; for detailed information about the conditions under which Health Monitor messages
are generated, see "Health monitor messages" on page 204.
Note:
When a disconnected database or Node is reconnected, the Health Monitor sends a notification indicating the
successful resolution.
The Health Monitor supports the following notification mechanisms:

n
Sending an email
Executing a program
Generating a notification
The Health Monitor generates two types of messages: detailed and terse. Detailed messages are used for emails sent by
the Health Monitor, and terse messages are used when sending a notification to non-email text Devices. All detailed
messages are also included in the xMatters log files.
Note:
The Health Monitor generates two messages for inter-node communication errors: one message that includes
the entire stack trace, and one that includes a simplified (terse) message. You can eliminate the stack trace
message by opening the hmApplicationContext.xml file (located at
node/assets/resources/spring/integration) in a text editor and setting
notifyNodeCommunicationExceptions to "false". After making the change, restart the node.
To set Global Configuration settings:

2. On the Administration tab, in the Configuration menu, click Global Configuration.
l
xMatters displays the Global Configuration page.
Global Configuration page
3. On the Global Configuration page, use the descriptions of the fields provided in the tables below to specify the
required information.
4. Click Save to apply your changes.
Health Monitor Settings

Setting
Description
Mail Host
Name of the mail host to use for email messages generated by the Health Monitor.
Mail Port
Port number to use for the Health Monitor mail.
Mail Sender
Email address that appears in the From field of the notification email message.
Mail Recipient
Email address of the default Health Monitor mail recipient.
Notification Target
If available, the user name of the Company Administrator the Health Monitor should attempt
to notify via xMatters in the event of a system health event.
Integration Agent
Heartbeat Failure
Threshold
Specifies how many consecutive "heartbeats" an Integration Agent can miss before the Health
Monitor sends a warning message. The value must be between 1 and 9999; the default is 5.
Notification Processing
Setting
Description
Notification
Processing Timeout
Length of time, in minutes, that a notification can remain in a serviceable state before it is
automatically delinked. The default setting is one hour.
Note that a live notification could remain serviceable but undispatched for several reasons.
For example, if a live notification for WCTP is created but the only configured WCTP engine
goes down for a period longer than the specified timeout, the notification will be delinked.
Specifying a value that is too short (e.g., five minutes) could result in notification delivery
failure if the Device Engines cannot process the number of notifications quickly enough. If
this happens, increase the Notification Processing Timeout setting, or increase the number of
available threads on your affected Device Engines.
Service Provider Failover

Setting
Description
Enable Notifications
Enables Health Monitor notifications for Service Provider failures.
Threshold
Number of failures per Check Period that must be met or exceeded to trigger a notification. To
prevent the Health Monitor from sending any notifications, enter 0.
Check Period
How often, in minutes, to check whether the conditions for provider failure have been met.
Suppression Period
Length of time, in minutes, to suppress notifications for a provider after an instance of

provider failure. The next time that provider fails after the suppression period will generate
another notification and restart the suppression period for that provider.
Bounced Mail Settings

Setting
Description
xMatters uses the Bounced Mail Settings to respond to emails that are not related to a notification. xMatters sends
a message using the Bounced Mail Settings to indicate that the email was invalid.
Mail Host
Name of the mail host to use for email messages responding to invalid
responses.
Mail Port
Port number to use for the invalid responses mail.
Mail Sender
Email address that appears in the From field of the invalid response
notification email message.
Note: This email address must not be the same as the email account used to
send notifications from an SMTP/POP Device Engine.

Node Network Monitor
Setting
Description
Sample Frequency
Specifies how often in seconds node network application layer latency is measured. This
setting is used by the Node Network Statistics Report and the Health Monitor. To minimize
impact on system resources, set this parameter to a larger value. To increase resolution when
diagnosing node network communication issues, set this parameter to a smaller value.
Default=30, Min=30, Max=300
Aggregation Period
Specifies how often in minutes node network application layer latency and network drop
statistics are calculated from the data collected. Latency data is averaged, and network drops
are totalled. This setting is used by the Node Network Statistics Report and the Health
Monitor. To minimize impact on system resources, set this parameter to a larger value. To
increase resolution when diagnosing node network communication issues, set this parameter
to a smaller value.
Round Trip
Threshold
Specifies the acceptable maximum duration in milliseconds for a round-trip communication

between two nodes during the Aggregation Period. This setting is used by the Node Network
Statistics Report and the Health Monitor; an alert is sent when this threshold is exceeded.
Network Drop
Threshold
Specifies the acceptable maximum number of dropped connections between nodes that can
occur during the specified Aggregation Period. This setting is used by the Node Network
Statistics Report and the Health Monitor; an alert is sent when this threshold is exceeded.
SMS Response Validation Settings

Setting
Description
Enable SMS Response When enabled, xMatters will validate that each incoming SMS response using atext phone
Validation
protocol is from an authorized xMatters User. This option must be selected to enable the
remaining SMS Response Validation Settings.
SMS Validation
Pattern
Specifies the validation pattern to use when validating incoming SMS responses. This pattern
uses regular expressions to define how xMatters should recognize incoming SMStext phone
numbers and compare them to the Device numbers stored in xMatters.
The pattern must contain one or more groups, defined by parentheses. For more information
and examples, see "Specify SMS validation patterns and templates", below.
SMS Validation
Template
Specifies the validation template to use when validating incoming SMS responses. The
template must contain one or more instances of "$n", where n is a digit corresponding to a
group defined in the pattern. For more information and examples, see "Specify SMS validation
patterns and templates", below.
Enable SMS Simple

Responses
Indicates whether you want xMatters to accept simple SMSresponses to notifications. These
simple replies require Users to enter only a single digit as a response to a notification, rather
than entering a phrase that includes the notification key.
xMatters replies to invalid response messages with the message "<response choice>is not a
valid response."
For more information and examples, see "Configure simple SMS replies" on page 143.
Specify SMS validation patterns and templates

The SMSValidation Pattern and SMS Validation Template fields define how xMatters should compare the text phone
Device numbers stored in xMatters with the text phone Device numbers returned by the Protocol Provider with an
incoming response.
xMatters stores all text phone Device phone numbers as a string of digits only, with no parentheses, symbols, or spaces
allowed, along with a country code appropriate to the Device. An incoming response from a provider may be formatted
differently, and include a country code, special characters, or spaces (e.g., +44 (555) 123-4567)
The SMSValidation Pattern defines how the incoming number is formatted by the provider, while the SMSValidation
Template defines how the number should be re-formatted to be recognized by xMatters. You can use these fields in
combination to remove white spaces, special characters and any groups of numbers from an incoming phone number that
are not part of the country code, area code, and phone number. Groups of characters must be delimited by a white space
or special character, or be of a known number of digits.
Note:
If the validation pattern or template is not configured correctly, xMatters will ignore the responses. To check
whether responses are being ignored, review the application server and notification server logs.
You can use the following examples as a guideline for specifying your validation pattern and template. In each of the
examples, the Device's phone number is stored in xMatters as "5551234567" with a country code of 44.
Example One
n
The inbound phone number (from the Protocol Provider) is +44 555 123 4567
Set the SMS Reply Validation Pattern to +(\d+) (\d+) (\d+) (\d+)
Set the SMS Reply Validation Template to $1$2$3$4.
Example Two
The following example illustrates how to specify the validation pattern and template for deployments using Clickatell:
n
The inbound phone number comes back as +445551234567
Set the SMS Reply Validation Pattern to +(\d+)
Set the SMS Reply Validation Template to $1
Example Three
n
The inbound phone number comes back as 5551234567 (note the absence of the country code in the returned
number).
Set the SMS Reply Validation Pattern to (\d+)
Set the SMS Reply Validation Template to 44$1
Health monitor messages

This section summarizes Health Monitor messages and the conditions under which they are generated (for general
information about the Health Monitor, see "About the Health Monitor" on page 198).
Note:
The exact text and availability of a Health Monitor message are dependent on the version of your xMatters
deployment; the text of the messages displayed on your system may not be identical to the message examples
described below.
Component Misconfigured
Device Engines report the following message when a configuration change has been applied that prevents notification
delivery (where possible, more detail about the source of the problem is included).
n
The xMatters Health Monitor on node <node name> has detected that the <device engine name> has been
misconfigured and can no longer function. Message: <detailed message>. Consult the node logs for further details.
Node Failure/Recovery
Nodes periodically update their database record with a timestamp. If a Health Monitor on a running node detects that
another node has failed to update its timestamp, the first message below is sent. When a node has failed, the processing
it was responsible for at the time of failure will be recovered by another running node (if there is one).
When a node that has previously failed (i.e., its heartbeats stopped) resumes its heartbeats, the second message below is
sent.
Messages
n
The xMatters Health Monitor on node <running node name> has detected that node <failed node name> has
stopped sending heartbeats. Ensure that the node process is still running and can access the database.
The xMatters Health Monitor on node <running node name> has detected that node <recovered node name> has
recovered.
Multi-Node Communication
In some cases, node-to-node communication can fail (e.g., due to regular maintenance, network outages, faulty
equipment, socket exhaustion, etc.), generating a Health Monitor message.
n
The xMatters Health Monitor on node <node name> has detected that communication with an xMatters node has
been lost: <node name>.
Node Network Monitor Parameters

The following Health Monitor Messages are triggered when the Node Network Monitor threshold parameters specified
on the Global Configuration page are exceeded (for details, see "Global Configuration" on page 198):
n
The xMatters Health Monitor on node <node name> has detected <communication defect> communication with
AlarmPoint node <node name> over the last <number of seconds> seconds. The affected nodes will not exchange
messages until bidirectional communication is established, which may result in apparent loss of service. Corrective
action should be taken to allow bidirectional communication between the affected nodes. Consult the logs of the
affected nodes for further details on communications errors.
The xMatters Health Monitor on node <node name> has detected that communication between <node name1> and
<node name2> has been interrupted <number of times> times for the last <number of minutes> minutes. If this
consistently occurs on a specific node, ensure that the node process is active. If this occurs erratically and/or
frequently, there may be networking issues affecting inter-node or node-to-database communication. Consult the
logs of the affected nodes for further details.
<node name2> is too slow. For the last <number of minutes> minutes, the average round trip latency was <number
of milliseconds> ms.
This may be caused by a networking problem, or the load on the servers or the network may be reaching capacity.
The following messages are sent when application layer latency has recovered to within the specified parameters:
n
<node name2> is recovered. Symmetric (i.e., bidirectional) communication has been restored.
<node name2> is recovered. For the last <number of minutes> minutes, the communication interruption time has
been below the configured threshold.
<node name2> is recovered. For the last <number of minutes> minutes, the average round trip latency was
<number of milliseconds> ms.
Node Licenses Exceeded

The following message is sent when a node could not be started without exceeding the licensed limit:
n
Startup of <node name> has been aborted because the number of active nodes would have exceeded the licensed
limit. Contact support @xmatters.com to obtain a license that allows more nodes.
Node Clock Off Sync

The system clocks for all components in your deployment must be synchronized; if xMatters detects that an internal
clock for a node has deviated from the database clock, the Health Monitor sends the following message:
n
The xMatters Health Monitor has detected that the internal clock for this node has deviated <number of
milliseconds>ms from the database's internal clock. As a result, messages may be lost. Adjust the node or database
clock to match. To avoid having to manually adjust the clock, consider, automatically synchronizing system
clocks against an NTPserver.
Unhandled Exception
The following message is sent when an unexpected error occurs.
Message
n
The xMatters Health Monitor on node <node name> has detected an error: <error>.
Consult the node logs for further details.
Example
The xMatters Health Monitor on node SISC_APP_NODE1 (10.10.60.78) has detected an error: No row
with the given identifier exists:
[com.invoqsystems.foundation.interpreter.invoqscript.persistance.
ScriptObjectProxy#214410]; nested exception is org.hibernate.
ObjectNotFoundException: No row with the given identifier exists:
[com.invoqsystems.foundation.interpreter.invoqscript.persistance.
ScriptObjectProxy#214410].
Consult node logs for further details.
Troubleshooting
To troubleshoot an unhandled exception alert, analyze the logs on the node that caused the exception:
1. Search the log for the exception detailed in the Health Monitor email.
2. Each log entry contains a thread number. Search the log for the entries corresponding to the thread number that
generated the exception, and look for an Event ID or a target name (Recipient) in those log entries.
l
In the following example, the thread numbers are in bold, the Event ID is italicized, and the recipient is
underlined:
2008-09-10 12:14:51,465 [_httpConnector#1297127._ManagerProvider.receiver.295] DEBUG EV

[282766] - NTFN[2134532] - BEGIN PROCESSING PERSON Target: U368222 Id: 2133915 State:
PROCESSING Event: SUCCESSFUL_DELIVERY
2008-09-10 12:14:51,480 [_httpConnector#1297127._ManagerProvider.receiver.324] DEBUG LIVE NOTIFICATION ID: 2134136 Change state from SERVICEABLE to SERVICEABLE.
3. If a recipient is found, log in to the xMatters web user interface and search for that recipient. You may find issues
with the Users Devices.
4. If an Event ID is found, log in and look at reports for that Event ID.
l
The Event Reports may contain explanations for the error in the log.
Expired Message Bus

Node components communicate with one another using messages. Most messages are eligible for processing by a number
of components; this means that if a component fails or is stopped, another can process any outstanding messages.
However, if a non-redundant component (e.g., a Device Engine that is the sole servicer of a protocol) is stopped,
messages may go undelivered for an extended period. When this condition is detected the message below is sent.
n
The xMatters Health Monitor on node <node name> has detected an error during message processing. This may
indicate that a non-redundant system component (node or device engine) was stopped or has failed.
Additional details:
Company:<Company name>
Message Type:<Message>
Message ID:<Message>
Source Component:<component>
Source Node:<node name>
TargetComponent:<component>
Target Node: <node name> (<details>)
Time Posted:<time>
Time-to-Live: <number> ms.
Database Connectivity Failure/Recovery

Each xMatters node periodically checks its connectivity with the database. If a check fails, the first message below is
sent, and checking continues. If another check is successful, the second message below is sent.
Messages
n
The xMatters Health Monitor on node <node name> has detected that database communication has failed.
Check the database server status and whether the node can ping the database server's host. Consult the node logs
for further details.

n
The xMatters Health Monitor on node <node name> has detected that database communication has been restored.
User Service Provider Empty

Through configuration it is possible to create an empty User Service Provider by either removing all of its Protocol
Providers or marking each of them as inactive. When this prevents notification, the Health Monitor reports the message
below (subject to the configuration documented in the "Global Configuration settings" table in "About the Health
Monitor" on page 198).
n
The xMatters Health Monitor on node <node name> has detected that the <provider name> User Service Provider
from Company <Company name> has no active protocol providers; as a result, notifications have not been
delivered.
Configure at least one Protocol Provider and a corresponding Device Engine to send messages to Devices that use
this User Service Provider.
User Service Provider Exhausted

When notification delivery fails for all Protocol Providers in a given User Service Provider, the Health Monitor sends the
message below (subject to the configuration documented in the "Global Configuration settings" table in "Global
Configuration" on page 198).
n
The xMatters Health Monitor on node <node name> has detected that notification to <recipient target name> of
company <company name> has failed because all Protocol Providers have been attempted and failed for User
Service Provider <provider>.
If this occurs whenever a message is sent to this provider, the most likely cause is a configuration problem with the
provider or its corresponding Device Engine. If this happens consistently only for this Device, the Device is likely
invalid or misconfigured. If none of the latter conditions apply, this may be a transient problem with the provider
or the network. Consult the node logs for further details.
Protocol Provider Failed

When delivery of a notification to a particular provider fails, the Health Monitor sends one of the messages below
(subject to the configuration documented in the "Global Configuration settings" table in "About the Health Monitor" on
page 198).
Messages
n
The xMatters Health Monitor on node <node name> has detected that notification to <User> of Company
<Company name> on <User Device name> has failed because all protocol providers have been attempted and
failed for user service provider <Service Provider name>. Consult the node logs for further details.
The xMatters Health Monitor on node <node name> has detected that the <protocol provider type> Protocol
Provider of Company <Company name> has failed beyond the configured threshold. The most recent failure
occurred on node <node name> with message <message text>. The service provider may be unavailable or the
Protocol Provider may be incorrectly configured. Consult the node logs for further details.
There is no Device Engine to process the notifications that target the Protocol Provider <Protocol Provider name>.
Configure at least one Device Engine that can handle the protocol.
The xMatters Health Monitor on node <node name> has detected that <Protocol Provider Name> protocol
provider has failed. Message <message text>. Consult the node logs for further details.
The xMatters Health Monitor on node <node name> has detected that the <SIP Service Provider name> SIP service
provider has failed beyond the configured threshold. The most recent failure occurred on node <node name>.
Ensure that the provider is operational and that the node is properly configured to use it. Consult the node logs for
further details.
The xMatters Health Monitor on node <node name> has detected that the <Phone Service Provider name> phone
service provider of Company <Company name> has failed beyond the configured threshold. The most recent
failure occurred on node <node name>. Ensure that the phone line is operational and that the node is properly
configured to use it. kConsult the node logs for further details.
Device Engine Failed

The Health Monitor for each node monitors the Device Engines, and sends one of the following messages whenever it
detects a failure:
n
The xMatters Health Monitor on node <node name> has detected that the <Device Engine name>has failed for
<#> consecutive registration attempts.
Message:<message>
The xMatters Health Monitor on node <node name> has detected that the <Device Engine name>has failed to
register with its associated server.
Check the configuration logs and network connectivity.
The xMatters Health Monitor on node <node name> has detected that the <Device Engine name>has recovered.
SIP Device Engine Cannot Register with SIPServer

When an xMatters SIP Device Engine cannot register with its associated SIP server, the Health Monitor generates a
message similar to the one below:
n
The xMatters Health Monitor on node <node name> has detected that SIP Device Engine protocol provider has
failed. Message Failed to register to SIP server <SIPSever IP address and port>
Message Queue Threshold Exceeded

The Health Monitor for each node monitors the capacity of internal message queues. When it detects that a message
queue is nearly full, the message below is sent:
n
The xMatters Health Monitor on node <node name> has detected that its host node is nearing its maximum
capacity. Incoming message acceptance may slow if the current load is maintained.
Node Startup Aborted

Each xMatters license includes a limit on the number of running nodes allowed. When this limitation is about to be
exceeded by node startup, the Health Monitor of the node starting up will send the message below and node startup will
be aborted.
n
Startup of <node name> has been aborted because the number of active nodes would have exceeded the licensed
limit.
Integration Agent/Service Failed/Recovered

The conditions under which these messages are sent are documented in the Reported Status and Health Monitor
Messages section of the xMatters integration agent guide.
Note:
The xMatters integration agent has its own Health Monitor and related notifications, which are summarized in
the xMatters integration agent guide.
Messages
n
At <timestamp>, No connection could be made between Integration Agent <URL> and any of the primary or
secondary xMatters Web Servers. The Integration Agent will continue sending heartbeats, and a notification will
be sent when the heartbeat recovers.
At <timestamp>, Integration Agent <URL> successfully sent a fully accepted heartbeat to primary xMatters Web
Server <URL>. The Integration Agent is fully functional. A notification will be sent if the heartbeat status
changes.
At <timestamp>, A connection was made between Integration Agent <URL> and primary xMatters Web Server
<URL>, but the heartbeat generated the following error: The xMatters Server at <URL> rejected the
heartbeat/registration with the following reason: AUTHENTICATION_ERROR. The Integration Agent will
continue to send heartbeats to the primary servers, but Integration Agent functionality may be limited until the
heartbeat is fully accepted. A notification will be sent when the heartbeat is fully accepted. Consult the Integration
Agent log for further details.
At <timestamp>, No connection could be made between Integration Agent <URL> and any of the primary
xMatters Web Servers. The heartbeat was fully accepted by secondary xMatters Web Server <URL>. The
Integration Agent is fully functional in failover mode. The Integration Agent will continue to send heartbeats to
the secondary servers. A heartbeat to the primary servers will be reattempted every 600 seconds (0 indicates
indefinitely), or if the secondary heartbeat fails. A notification will be sent when the primary heartbeat recovers.
At <timestamp>, No connection could be made between Integration Agent <URL> and any of the primary
xMatters Web Servers. A connection was made to secondary xMatters Web Server <URL>, but the heartbeat
generated the following error: The xMatters Server at <URL> rejected the heartbeat/registration of the following
Integration Services: Domain: ping, Name: ping, Reason: UNKNOWN_SERVICE . The Integration Agent will
continue to send heartbeats to the secondary servers, but Integration Agent functionality may be limited until the
heartbeat is fully accepted. A heartbeat to the primary servers will be reattempted every 600 seconds (0 indicates
indefinitely), or if the secondary heartbeat fails. A notification will be sent when the primary heartbeat recovers or
the secondary heartbeat is fully accepted. Consult the Integration Agent log for further details.
Invalid Event Received

When an Event Domain receives an invalid event, the Health Monitor sends the following message:
n
The xMatters Health Monitor on node <node name> has detected that an invalid event to Company <Company
name> has been received on the <domain name>Event Domain with an incident IDof <ID>. This is a summary
report; more invalid events may be rejected.
General Troubleshooting
When troubleshooting Health Monitor error messages, you may find the following reports useful:
n
Submitted Notifications Report: this report displays all notifications sent by the system across multiple events
during a specific time period. For more information, see "Submitted Notifications Report" on page 317.
Live Notifications Report: this report displays all notifications currently in progress. For more information, see
"Live Notifications Report" on page 319. Note that two-way pager notifications sent via SCTP and SNPP appear in
the Live Notifications Report for one hour after the notification is sent. This is due to the mechanism used by these
protocols to query for delivery updates and replies.
Application Audit Report: this report lists all changes made to any type of object within the system, such as Users,
Groups, Devices, Schedules, etc. For more information, see "Application audit report" on page 327.
Constants
xMatters uses constants in scripting in a manner similar to variables (i.e., the constant name is abstracted from the
constant value). Constants can be Global, applying across all Companies in an xMatters multi-tenancy deployment, or
Company-specific, applying only to the Company for which they are defined. They can also be defined for use within a
single Event Domain.
Constants | 209
Example
An xMatters administrator creates a constant named "BES_URL" with a value representing the current BlackBerry
Enterprise Server URL. The constant is then used in several xMatters scripting packages (i.e., the constant is used rather
than the actual BESURL). If the server's URL changes, the administrator can simply modify the value of the BES_URL
constant. The change will then be propagated to all instances of the BES_URLconstant in the scripting packages.
Constant Names
If a Global Constant and a Company Constant have the same name, the value of the Company Constant overrides the
value of the Global Constant for that Company. Additionally, Company Constants have independent values between
Companies; multiple Companies can define a constant with the same name, but different values.
Similarly, if an Event Domain Constant has the same name as a Company Constant or a Global Constant, the value of
the Event Domain Constant overrides the value of the other constants. Event Domain Constants also have independent
values between Event Domains; multiple Event Domains in the same Company can define a constant with the same
name, but assign different values.
Note:
When an existing constant is modified, it takes five minutes for the change to be reflected in the scripts.
Global Constants
xMatters super administrators can define Global Constants that will be available in scripting for all Companies in the
xMatters deployment.
Note:
If a Global Constant and a Company Constant have the same name, the value of the Company Constant
overrides the value of the Global Constant for that Company.
To configure Global Constants:

2. On the Admin tab, in the Configuration menu, click Global Constants.
l
xMatters displays the Global Constants page.
Global Constants page

l
Constants | 210
To modify an existing Global Constant, click its name in the list to view its details. For information about
the fields and values, see "Defining Global Constant Details" below.
To remove a Global Constant, select the check box next to it in the Global Constants list, and then click
Remove Selected.
To add a new Global Constant, click the Add New link above the list, and then specify the details on the
Add New Global Constant page. For information about the fields and values, see "Defining Global Constant
Details" below.
Define Global Constant Details

If you are modifying or adding a Global Constant, you can define the following settings (Constant Name and Value are
mandatory):
n
Name: the name of each Global Constant must be unique within the xMatters system, and will automatically be
converted to all upper-case when the constant is created. Constant names are limited to 100 characters or less, and
can contain only alphanumeric characters, underscores, and spaces (no punctuation or other special characters).
Value: Global Constant values are limited to a maximum of 1000 characters from the ASCII character set
(Decimal: 32 - 126).
Description: the description field is optional.
Company Constants
Company Administrators can define Company Constants that will be available in scripting for the Company that they
administrate.
Note:
If a Global Constant and a Company Constant have the same name, the value of the Company Constant
overrides the value of the Global Constant for that Company. Additionally, Company Constants have
independent values between Companies; multiple Companies can define a constant with the same name, but
different values.
To configure Company Constants:

1. Log in to xMatters as a Company Administrator.
2. On the Admin tab, in the Configuration menu, click Company Constants.
l
xMatters displays the Company Constants page.
Company Constants page

l
To modify an existing Company Constant, click its name in the list to view its details. For information about
the fields and values, see "Defining Company Constant Details" below.
To remove a Company Constant, select the check box next to it in the Company Constants list, and then
click Remove Selected.
Constants | 211
To add a new Company Constant, click the Add New link above the list, and then specify the details on the
Add New Company Constant page. For information about the fields and values, see "Defining Company
Constant Details" below.
Define Company Constant Details

If you are modifying or adding a Company Constant, you can define the following settings (Constant Name and Value
are mandatory):
n
Name: the name of each Company Constant must be unique within the Company, and will automatically be
converted to all upper-case when the constant is created. Constant names are limited to 100 characters or less, and
can contain only alphanumeric characters, underscores, and spaces (no punctuation or other special characters).
Value: Company Constant values are limited to a maximum of 1000 characters from the ASCII character set
(Decimal: 32 - 126).
Event Domain Constants

Company Administrators and Developers can create Event Domain Constants that will be available in scripting for all
event objects associated with an Event Domain.
To configure Event Domain Constants:
1. Log in to xMatters as a Company Administrator or Developer.
2. On the Developer tab, in the Domains menu, click Event Domain Constants.
3. In the Event Domain drop-down list, select the Event Domain for which you want to create or modify the
constants, and then click Continue.
l
xMatters displays the Event Constants page.

l
To modify an existing Constant, click its name in the list to view its details. For information about the fields
and values, see "Defining Event Domain Constant Details" below.
To remove a Constant, select the check box next to it in the Event Domain Constants list, and then click
Remove Selected.
To add a new Constant, click the Add New link above the list, and then specify the details on the Add New
Event Domain Constant page. For information about the fields and values, see "Defining Event Domain
Constant Details" below.
Define Event Domain Constant Details

If you are modifying or adding an Event Domain Constant, you can define the following settings (Constant Name and
Value are mandatory):
n
Constant Name: the name of each Event Domain Constant must be unique within the Event Domain, and will
automatically be converted to all upper-case when the constant is created. Constant names are limited to 100
characters or less, and can contain only alphanumeric characters, underscores, and spaces (no punctuation or other
special characters).
Value: Event Domain Constant values are limited to a maximum of 1000 characters from the ASCII character set
(Decimal: 32 - 126).
Available Constants
The following sections identify the pre-configured constants within xMatters. To use these constants, add the constant
name to the xMatters web user interface and assign a value to it; the scripts will apply the values automatically.
Constants | 212
SMSConfirmation and First Alert Messages Constants

Constants are used to define the messages that Users will receive as confirmation and first alert messages when they
create or modify a text phone Device in xMatters. The following table identifies the constants that you can edit to define
the confirmation and first alert messages, and the help text Users will see if they request more information.
You can define these constants as Event Domain Constants on the sms_confirmation Event Domain.
SMS Message Constants
Constant
Description
SMSCONFIRMMSG
Defines the confirmation message displayed to Users when they create, modify, or activate a
text phone Device in xMatters. To meet the best practices requirements of the Mobile
Marketing Association (MMA), this message should include the following information:
l
A clear identification of xMatters (or the company) as the message sender.
Contact details, such as how to get more information.
Details on how to opt out of the service. xMatters accepts the following stop codes:
STOP, END, QUIT, CANCEL, UNSUBSCRIBE, STOP ALL, and DISABLE.
Example:
Welcome to xMatters; the number of alerts you will receive varies with
usage. Send HELPfor more info; send STOPto opt out. Message & data
rates may apply.
SMSFIRSTMSG
Defines the text of the custom message displayed to Users when they create or modify a text
phone Device in xMatters. To meet the best practices requirements of the MMA, this message
should include the same information as the confirmation message; for example:
This is a sample message from xMatters. Send HELP for more information,
or send STOPto opt out. Message & data rates may apply.
Note that the behavior and content of this message can be further modified using the initial
process script of the sms_confirmation Event Domain. For more information about working
with scripts, see the xMatters Online Developer's Guide.
SMSHELPMSG
Defines the text of the message xMatters should send when a User responds to an xMatters
notification with HELP. To meet the best practices requirements of the MMA, this message
should include the following:
l
l
A clear identification of xMatters (or the company) as the message sender.

Contact details for the User to get more information about xMatters; for example, a web
address or a phone number.
A short description of the service provided, including pricing terms.
Opt-out information.
Example:
xMatters has been authorized to send notifications to this text phone.
The number of messages you receive may vary, and prices are determined
by your phone service provider. For more information, call 1-888-5555555. To opt-out, reply to this message with STOP.
Constants | 213
Constant
Description
SMSSTOPMSG
Defines the text of the message xMatters should send when a User responds to an xMatters
notification with STOP; for example:
Your Device will no longer receive SMS messages from the xMatters
notification service.
E-mail Presentation Constants

The e-mail presentation constants can be defined as Global, Company, or Event Domain Constants. If a Global Constant
and a Company Constant have the same name, the value of the Company Constant overrides the value of the Global
Constant for that Company. If an Event Domain Constant has the same name as a Company Constant (or a Global
Constant), then the value of the Event Domain Constant will override the value of the other Constants for messages sent
for that Event Domain.
Constant
Description
EMAILLOGOURL
Defines the URLat which the logo used at the top of the e-mail message is stored. If no
URLis defined, xMatters uses the following default path:
<xMHOME>/webserver/static/images/logos/xmatters_email.gif
If the value specified in the constant is not a fully qualified URL(i.e., it does not begin with
http://), xMatters will prepend the location of the xMatters web server, as defined by the
WEBSERVERURLGlobal Constant.
EMAILCSS
Defines the cascading style sheet (CSS)to use when formatting e-mail messages. If no CSSis
defined, messages are formatted using the default xMatters layout and styles.
EMAILFOOTER
Defines the message contained in the footer added to the bottom of each e-mail message. If no
message is defined, the default footer is "Powered by xMatters".
Note:
These constants replace the custom login page functionality from previous versions of xMatters.
Optional and additional functionality

Some of the optional features in xMatters are controlled by Constants. Note that, unless otherwise indicated, these
Constants can be set at a Global level, in which case they apply to all Companies in the system, or at a Company level.
Constant
Description
SHOWPERSONPROFILES
When set to true, displays the Person Profiles options and functionality on
the Admin and Users tabs.
SHOWGROUPPROFILES
When set to true, displays the Group Profiles options and functionality on
the Admin and Groups tabs.
Constants | 214
Constant
Description
REPORT_CARD_PASS_PERCENT
Specifies the percentage required for an event to Pass or Fail on the Report
Card tab of the Event report. If this is not defined, the Report Card will use
100% as the default Pass value. Note that this constant accepts both integer
and float values; e.g., both "88"and "87.5" are acceptable values.
POP_RESPONSE_INSTRUCTIONS
Specifies the message used for response instructions in SMTP/POPemail

notifications . The default message (which was previously hard-coded into
the notification content) is "If you are NOTable to connect to the web, use
the following method to record your response:"
Schedule Jobs
Super Administrators can use the Schedule Jobs feature to configure xMatters to perform specific administration tasks at
regular, pre-determined intervals.
Note:
Schedule Jobs tasks are processed on the xMatters application server.
Scheduled Job
Description
Process Expired Data
Allows you to configure how and when expired data is removed from the xMatters
system. For more information about the settings, see "Schedule a Process Expired Data
job" on page 216.
To schedule a job:
2. In the Configuration section of the Administration menu, click Schedule Jobs.
xMatters displays the Schedule Job Selection page.
Schedule Job Selection page
3. In the Select schedule job drop-down list, select the job you want to schedule, and then click Continue.
l
xMatters displays the Schedule for job page.
Schedule Jobs | 215
Schedule for Job page
4. Specify a start time for the job, the days of the week on which you want xMatters to perform the job, and how
often the job should occur.
Note:
The Start Time for the job is automatically adjusted by xMatters to correspond with your time zone.
5. When you are satisfied with your choices, click Save.
Schedule a Process Expired Data job

Using the Schedule Jobs feature, you can schedule a Process Expired Data job to automatically delete expired
information from the xMatters database.
The following table summarizes the available settings on the Schedule Job Details for Process Expired Data page:
Retention Time Setting
Description
Runtime data
Typically includes data such as events, notifications, and script objects. Data older than
the retention time will be moved to the corresponding archive tables. This data is used
for most reports, including most Activity Reports.
Archive data
Includes data moved from the corresponding runtime tables. Data older than the
retention time will be permanently removed. This data is used by reports that allow you
to select Runtime or Archive data (e.g., Event Activity).
Coverage data
Includes One-Time Coverages and Recurring Coverages that have an end date, and any
non-reusable Teams associated with these Coverages. Data older than the retention time
will be removed. Also includes data used in reports such as the Who's On Duty Report,
and Group Details.
Revision data
Typically includes data such as Users, Devices, Groups, Teams, and Roles. Data older
than the retention time will be removed. This data is used by the Application Audit
reports
Low-use User
This data is used by the Low-Use User report (for details, see "Low-use user report" on
page 328).
Schedule Jobs | 216
Retention Time Setting
Description
Performance Report data
This data is used by the User Performance and Group Performance Reports. For details
on these reports, refer to the xMatters user guide.
Statistics data
This data is used by the Node Network Statistics Report. For details on this report, see
"Node network statistics report" on page 330.
Security Audit
This data is used by the Security Audit Report. For details on this report, see "Security
audit report" on page 331.
How deleted data is processed

When you delete data from xMatters, such as Devices or Users, it is removed from the interface, but not immediately
deleted from the database. Instead, the item is marked as deleted and stored in the database until the system has removed
all other data that might be related to it. To determine when it is safe to completely delete this data, xMatters compares
the deletion date with the highest value specified in any of the above settings. Note that this feature ignores revision
tables, so the "Revision data retention time"setting is not included in this comparison.
The types of data included in this process are Users, Devices, and Teams.
For example, if all of your settings are set at 14 days except for the Low-use User Retention time, which is set for one
month, xMatters will purge the records for deleted Users, Devices, and Teams with a deletion date older than one month.
To schedule a Process Expired Data job:
2. In the Configuration section of the Administration menu, click Schedule Jobs.
l
xMatters displays the Schedule Job Selection page.
3. In the Select schedule job drop-down list, select Process Expired Data, and then click Continue.
l
xMatters displays the Schedule Job Details page.
Schedule Jobs | 217
Schedule Job Details for Process Expired Data
4. In the Runtime data retention time field, type the number of days that you want xMatters to retain runtime data.
5. In the Archive data retention time field, type the maximum number of days xMatters should retain archived data,
based on the creation date of the event. For example, specifying a value of "21" means that xMatters will purge all
data from the archive that is older than three weeks, regardless of how long the data was stored in runtime.
6. In the Coverage data retention time field, type the number of days that you want xMatters to retain expired
Coverages.
l
Note that when a Coverage is removed, the associated Team is also removed if the Team is not re-usable and
not being used by other active Coverages.
7. In the Revision data retention time field, type the number of days that you want xMatters to retain expired
application audit data.
8. In the Low-use User retention time field, type the number of months that you want xMatters to retain information
on Low-use Users.
9. In the Performance Report Data retention time field, type the number of months that you want xMatters to retain
information for the User and Group Performance Reports.
10. In the Security Audit retention time field, type the number of days that you want xMatters to retain Security
Audit information (the default value is 90 days).
11. In the Schedules table, click the name of a Schedule to set the times at which you want xMatters to run the Process
Expired Data job.
l
xMatters displays the Schedule for job page.
Schedule Jobs | 218
12. Specify a start time for the job, the days of the week on which you want xMatters to perform the job, and how
often the job should occur.
Note:
The Start time for the job is automatically adjusted by xMatters to correspond with your time zone.
Clear runtime and historical data

You can use the Clear Runtime / History page to delete all runtime data or all runtime and historical data from your
xMatters deployment. This tool is useful when you want to clear data related to system testing, troubleshooting, and so
on.
To delete runtime or runtime and history data:
1. Stop all xMatters nodes.
2. Log in to xMatters as the Super Administrator.
3. On the Admin tab, click Clear Runtime / History.
Clear Runtime / History page
4. Click the Select Purge Type drop-down list, and select one of the following options:
l
Delete All Runtime Data: removes current (i.e., unratified) information about Events, Alerts, Notifications,
etc.
Clear runtime and historical data | 219
Delete All Runtime Data and Historical Data: removes current and archived information about Events,
Alerts, Notifications, etc.
5. Click Purge (you will be prompted to confirm this action).

Note:
The Clear Runtime/History feature does not remove expired Coverages or revision data.
Configuration Process Examples

This section provides step-by-step instructions explaining how to configure specific xMatters components on your
deployment. Whenever possible, the steps include real world examples of working configurations.
Configure xMatters SMS

The following sections explain how to configure xMatters to send SMSmessages via HTTPusing the xMatters SMS
feature.
Note that the instructions in this section assume that you are using a default installation of xMatters; if you have
customized your installation, you may need to adjust the described process accordingly.
Overview
The HTTP protocol allows you to send and receive voice and text notifications and responses via HTTP requests. The
xMatters SMS feature uses the HTTPprotocol to provide global coverage of SMSand simple SMS replies. The service is
available on a subscription basis to xMatters customers; contact your xMatters Sales or Client Assistance representative
for more information.
Configuring external access
Note that you can also configure your system to receive inbound SMSresponses to your xMatters server without
exposing the web user interface to the Internet by reverse proxying a small portion of the xMatters URLspace. The
required syntax is as follows:
<protocol>://<domain>:<port>/services/xmsms
Note that the <protocol>should ideally be "https", and <domain> must be a fully qualified domain name that is
resolvable from the Internet. The <port>is required only if it does not match the specified protocol. For example:
https://myserver.xmatters.com:8443/services/xmsms
Note:
For more information about proxying your xMatters web server, see "Fronting the xMatters web server" on
page 348.
Get started
The first step in preparing your deployment for xMatters SMS is to contact the xMatters Client Assistance team and set
up your xMatters SMS account. The configuration settings in the xMatters web user interface will require your account
information.
Once you have your account information, perform the following steps to configure the xMatters SMS feature on your
deployment:
1. Create an HTTP-Client Device Engine.
2. Configure the HTTP-XM-SMSProtocol Provider to connect to the xMatters SMS service.
3. Create a new User ServiceProvider for xMatters SMS.
4. Configure SMSvalidation and simple SMSresponses in the Global Configuration settings.
5. Add a User and a text phone Device.
Configuration Process Examples | 220
These steps are explained in detail in the following sections.
Create the HTTP Client device engine

The first step in configuring your deployment for xMatters SMS is to create an HTTP Client Device Engine.
To create an HTTPClient Device Engine:
1. Log in to the xMatters web user interface as a Super Administrator, and in the Configuration menu, click Nodes
and Device Engines.
2. On the Nodes page, in the View Components column of the All Nodes table, click Device Engines.
3. On the Device Engines page, click the Add New link above the All Components table.
4. In the drop-down list, select HTTP-Client Device Engine, and then click Continue.
l
xMatters displays the HTTPClient Device Engine details page (for more information about the specific
settings on this page, see "HTTPClient Device Engines" on page 126).
HTTPDevice Engine settings
5. On the Device Engine Details page, accept the default settings and click Save.
Configuring the HTTP XM SMS protocol provider

Once you have configured the Device Engine, you must configure an HTTP-XM-SMSProtocol Provider. The following
steps explain how to reconfigure the existing settings on the default Protocol Provider installed by xMatters.
To configure the Protocol Provider:
1. In the Providers menu, click Protocol Providers.

2. In the All Protocol Providers list, click the xMatters HTTPSMS link.
l
xMatters displays the HTTPxMatters SMSService Provider Details page (for more information about the
specific settings on this page, see "HTTP xMatters SMSProtocol Providers" on page 168).
HTTPSMSProtocol Provider settings
3. Update the following settings as required for your deployment:

l
APIURL: Type the URLprovided by xMatters Client Assistance as the location of the xMatters SMS
service.
Username: Type the user name associated with your xMatters SMS account.
Password: Typethe password associated with your xMatters SMS account.
APIID: Type the account number of your xMatters SMS account.
From: Type the number xMatters should use as an outgoing caller ID; this must be a valid phone number
associated with your xMatters SMS account, and will be provided by xMatters Client Assistance.
Response URL: Type http://<xMattersIP:port>/services/xmsms (replace <xMattersIP:port>with
the IPaddress and port of your xMatters web server).
Note:
If you were configuring a different provider for your HTTPSMSmessages, you would need to add Request
Parameters, depending on the service. The Request Parameters for the xMatters SMS feature are already
configured.
4. Click Save.
Configure SMSvalidation and simple replies

The SMSValidation Pattern and SMS Validation Template fields define how xMatters should compare the text phone
Device numbers stored in xMatters with the text phone Device numbers returned by the Protocol Provider with an
incoming response.
To configure the SMSValidation settings:
1. In the Configuration menu, click Global Configuration.

2. On the Global Configuration page, in the SMSResponse Validation Settings area, select Enable SMSResponse
Validation.
3. In the SMSValidation Pattern field, type (\d+)
4. In the SMSValidation Template field, type $1
5. Select the Enable SMSSimple Responses check box.
l
The SMSResponse Validation area should resemble the following:
SMSResponse Validation example
6. Click Save.
7. Log out of the web user interface.
Create a user service provider

The final step in adding the xMatters SMS protocol is to add a User Service Provider for users to specify for their
SMSdevices.
To create a User Service Provider:
1. Login to xMatters as a Company Administrator, and then click the Admin tab.
2. In the Providers menu, click User Service Providers.
3. On the User Service Providers page, click the Add New link.
4. On the User Service Provider Details page, in the Name field, type xMatters SMS
5. In the Device Types drop-down list, select Text Phone Device.
6. Click Continue.
7. In the Protocol Providers for xMatters SMSsection click the Add New link.
8. On the Select Protocol Providers page, in the Available Protocol Providers field, select HTTPxMatters SMS, and
then click Add.
9. Click Save, and then, on the User Service Provider Details page, click Save again.
Add a user and a device

Once you have configured the HTTPcomponents, you can begin assigning SMSdevices to users that will send messages
via xMatters SMS.
For more information about adding users and devices, refer to the xMatters user guide. Note that when you are adding a
text phone device, ensure that you select xMatters SMSas the user service provider.
You should now be able to send SMSmessages to the user's text phone device via the xMatters SMS feature using the
HTTPprotocol.
Configure automatic SMS device deactivation

You can configure the SMPPprotocol on your deployment to automatically deactivate SMSdevices when specific error
codes are sent back from a protocol provider. xMatters can also automatically notify users and their supervisors about a
deactivated device.
Note:
This feature is available in xMatters version 5.0 (patch 004 and later) and version 4.1 (patch 014 and later).
Before you can configure this feature, you will need to obtain some information from your SMPP service provider:
n
The keywords present in a status report from the service provider that indicate the related message has failed.
The error codes contained within the message that indicate the reason for the failure was a delisted or deactivated
device.
Configure the SMPP device engine

The first step in implementing the automatic Device deactivation feature is to configure the SMPPDevice Engine to
accept service provider status reports and to recognize the status reports that indicate a delisted or deactivated Device.
To configure the SMPPDevice Engine:
1. Log in to the xMatters web user interface as a Super Administrator, and in the Configuration menu, click Nodes
and Device Engines.
2. On the Nodes page, in the View Components column of the All Nodes table, click Device Engines.
l
l
To configure an existing SMPPDevice Engine, click its name in the Device Engines table.
To configure a new SMPPDevice Engine, click the Add New link above the All Components table. In the
drop-down list, select SMPP Device Engine, and then click Continue.
4. On the SMPPDevice Engine details page, ensure that the Support Status Report check box is selected.
l
This feature relies on the status reports to determine when a Device has been delisted by a service provider;
if this option is not selected, you will not be able to use the automatic Device deactivation feature.
SMPPDevice Engine settings

5. In the Error Code Location or Delimiter field, specify how the Device Engine should parse an incoming status
report to identify an error code.
l
For example, the default setting is err:(3). Using this setting, xMatters will inspect an incoming status
report for a portion of the message that begins with "err:", and then use the three characters that follow as the
error code; e.g., a message containing the phrase "err: 023" would translate as the error code "023".
6. In the Failed Words field, specify the status string value that can be found within the incoming status report and
indicate the notification message has failed due to a delisted Device. (Use a semi-colon to separate multiple
values.)
l
Note that this status is identified using the Status Location or Delimiter field in the same way as the error
codes in the previous step. The default of stat:(7) inspects the status report for the phrase "stat:", and
then compares the seven characters that follow with the list of failed words.
7. Click Save.
Configure the SMPP protocol provider

The next step in configuring automatic Device deactivation is to configure the SMPPProtocol Provider with the error
codes that indicate when a Device has been delisted, and to specify who should be notified.
To configure the SMPPProtocol Provider:
1. In the Providers menu, click Protocol Providers.
l
l
To configure an existing Protocol Provider, click its name in the Protocol Providers table.
To configure a new Protocol Provider, click the Add New link at the top of the table. On the Add New
Protocol Provider page, in the Provider of Type drop-down list, , select SMPP, and then click Continue.
3. On the SMPPProvider Details page, in the Deactivation Error Codes field, specify the error codes that indicate a
Device has been delisted.
l
Use commas to separate values in the list.
4. In the Notify Upon Deactivation drop-down list, select Supervisors and Device Owners.
SMPPProtocol Provider settings
5. Click Save.
When xMatters sends a notification to this Protocol Provider and receives a status report indicating that the targeted
Device has been delisted or otherwise not registered with the service provider, it deactivates the Device, and sends
notifications to the Device owner, their direct supervisor, and to the supervisors of any Groups to which they belong.
Note that xMatters sends the deactivation notifications to the recipients' email Devices; if a recipient has no email
Device available, xMatters sends the notification to their Default Device.
226 |
About system administration

System administration addresses many of the common tasks performed by Company Administrators on a regular basis.
While many administrative items in the previous chapter need to be configured only once, Company Administrators may
need to adjust the setting and features in this chapter on an on-going basis.
This chapter includes the following sections:
n
Permissions, Functions, and Roles: explains how to use permissions to define Roles that control how your users
can access xMatters.
Company Administrators: describes how to create and manage Company Administrator accounts.
Clusters: describes how to add and define Clusters to distribute and route notifications.
Sites: explains how to create and manage Sites, and assign Countries, Time Zones, and Languages.
Company Holidays: describes how to define holidays for Sites and Companies, and how to create customized
holidays.
Custom User Information: explains how to create customized information to help find and organize Users.
Password Policy: describes how to set a company-wide password policy to apply to all xMatters Users.
Device Types: explains how to manage the list of Devices that Users are allowed to use.
Event Domains: describes how to configure Event Domains, which handle incoming messages from other sources
and management systems.
Subscriptions: explains how to configure the Subscription Domains required for Users to subscribe to different
kinds of Alerts.
Import Data: describes how to import information from Microsoft Office Excel 2003 XML spreadsheets.
Phone Recordings: explains how to create voice phrases, record names, and how to re-record system voice pieces.
Note:
Permissions: functions and roles

In xMatters, the features that a User can access are controlled by permissions. Specific permissions (e.g., the ability to
view Group membership) can be combined into a Function.
For example, a Function called Basic User might include several distinct permissions that allow access to features such
as defining personal User Details and Devices, and viewing Group membership. A Function named Advanced User
might include permissions that allow access to all of the enhanced messaging and Business Continuity Planning features
available in xMatters.
Just as permissions are combined to create Functions, Functions are combined to create xMatters Roles. For example, a
Role called Manager might combine Functions called Basic User and Advanced User.
Note:
xMatters product version and licensing control Role availability and modification privileges. It is
recommended that you discuss Roles and licensing requirements with your xMatters representative prior to
deployment.
Manage functions
Company Administrators can manage Functions on the Functions page in the xMatters web user interface.
About system administration | 228
Note:
The ability to create and define Functions is available only in xMatters enterprise deployments.
To view and manage functions:

2. On the Administration menu, click Functions.
3. If there is more than one Company in the system, select the Company for which you want to manage the
Functions, and then click Continue.
l
xMatters displays a list of the current Functions for the Company:
Functions page
4. From the Functions list, do any of the following:

l
To modify an existing Function, click the name in the list to view its details. For more information about the
settings, see "Define function details", below.
To remove a Function from the list, select the check box next to the Function or Functions you want to
Permissions: functions and roles | 229
To create a new Function, click the Add New link, and specify the Custom Field details for the new
Functions, as explained in the "Function Details" table below. Click Save to create the Function, and then
add the appropriate permissions.
Define function details

You can define the details and permissions for each Function using the Function Details and Permissions pages.
Note that when adding or removing Permissions from Functions, you may also need to update the Role Details for those
Users affected by the changes. For example, imagine that you modify the Permission settings to enable Group
Supervisors to view and generate Events for User Reports. When the supervisor searches for the User for whom they
want to generate the report, they will not be able to click the User's name in the Results table unless you have also
modified the RoleDetails to allow Group Supervisors to View Users.
Note:
For more information about Role Details, see "Define role details" on page 234.
To modify function details:

1. On the Functions page, in the Functions table, click the name of the Function you want to modify.
2. On the Function Details page, do one of the following:
l
In the Common Tasks pane, click Modify Permissions.
Enter the following information into the form, and then click Save:
Function details
Setting
Description
Name
Name of the Function
Description
Description of the Function
3. On the Permissions page, do one of the following:

l
Note:
To add permissions, select the permissions you want to add in the Available Permissions box, and then
click Add.
To remove permissions, select the permissions you want to remove in the Selected Permissions box, and
then click Remove.
To view a description of a Permission, hover the mouse pointer over its name.
Permissions page
Roles
Roles are User attributes that represent one or more Functions. For example, a Role called BCP Officer might include
Functions called Basic User and BCP User. In addition, Roles have another set of associated permissions that define
whether and how Roles can act on themselves and other Roles; for details, see "Manage role permissions", below.
xMatters includes the following predefined Roles (availability is based xMatters licensing):
Role
Description and Relationship to Other Roles
Read-Only User
Cannot edit their profile information, but are able to respond to alerts.
Cannot act on other Roles or send messages via messaging panels in xMatters.
No Access User
Cannot access or use the xMatters web user interface, but can be assigned to Groups and Teams,
and can respond to alerts on Devices.
Standard User
Can maintain their profile, respond to alerts, self-subscribe to Subscriptions, and send messages.
Can send messages to all users except Developers and the Super Administrator.
Role
Person Supervisor Can add and edit other users.

Full permissions to act on Read-Only Users, Standard Users, and other Person Supervisors, with
the exception of managing Subscriptions for these other Roles. Can view and send messages to
Group Supervisors, Subscription Supervisors, and Full Access users. Can send messages to
Company Administrators.
Group Supervisor
Can add and maintain Groups.

Full permissions to act on Standard Users, Read-Only Users, and Person Supervisor Users, with
the exception of managing Subscriptions for these other Roles. Can view and send messages to
Group Supervisors, Subscription Supervisors, and Full Access Users. Can send messages to
Company Administrators.
Scenario Initiator
Can view and launch Advanced Messaging Scenarios (when specified as an initiator in the
Scenario details).
Cannot access or use the xMatters web user interface unless combined with another Role with
appropriate permissions.
Scenario Tester
Can run tests of Advanced Messaging Scenarios.

Scenario
Supervisor
Can create, edit, manage, test, and launch Advanced Messaging Scenarios.
Subscription
Supervisor
Can add and maintain Groups and Subscriptions.
Web Service
Supervisor
Can add and edit Web Service Users.
Developer
Can maintain Event Domains and Subscription Domains
Full permissions to act on Standard Users, Read-Only Users, Person Supervisors, and Group
Supervisors. Can view, edit, and send messages to Subscriptions Supervisors. Can view and send
messages to Full Access Users. Can send messages to Company Administrators.
Cannot act on other Roles or send messages via messaging panels in xMatters unless combined
with another Role with appropriate permissions.
Can send messages to Company Administrators. Can edit, view, and send messages to Developers.
Full Access User
All permissions with the exception of administrative tasks.

Full permissions to act on all other Roles, except Super Administrators and Company
Administrators. Can send messages to Company Administrators.
Role
Support User
Can access, view, edit, and delete all Users, Teams, Dynamic Teams, and Groups within a single
Company. Can edit any locked data value, and access all Company-specific reports. Can log in
as another user (via the Login As User feature). Note that Users with the Support User Role
cannot edit or delete other Users that also have the Support User Role.
Service Provider
Support
Available only in the host Company on a multiple-Company deployment.
Company
Administrator
Can maintain and administrate a Company, with full permissions for company administrative
tasks, including data locking configuration for their Company.
Can log in to a tenant Company as a tenant Company User from the host Company via the Login
as Agent link on the Users tab.
Full permissions to act on all users, except the Super Administrator.

Super
Administrator
Can maintain and administrate the xMatters system; cannot configure external data locking.
Full permissions to act on Company Administrators (but not other Users). Can view all integration
agents on the Component Status Report.
Manage roles
You can manage roles using the Roles page.
To view and manage roles:
2. On the Administration menu, click Roles.
l
xMatters displays a list of the current Roles for the Company.
Roles page
3. From the Roles list, do any of the following:

l
To modify an existing Role, click its name in the list to view Role Details. For more information about
editing Role Details, see "Define role details", below.
To remove a Role from the list, select the check box next to the Role or Roles you want to remove, and then
To create a new Role, click the Add New link, and specify the details for the new Roles, as explained in
theRole Details settings table. Click Save to create the Role.
Define role details

You can define the details and permissions for each role using the Role Details and Permissions pages.
To modify role details:
1. On the Roles page, in the Roles table, click the name of the role you want to modify.
2. On the Role Details page, enter the following information into the form:
Role Details settings
Setting
Description
Role Name
Name of the Role
Description
Description of the Role
3. Specify the Role Permissions. For more information, see "Define role details" on page 234, below.
l
To modify the Functions assigned to the Role, click Assign Functions to this Role in the Common Tasks
pane. For more information, see "Assigning Functions to Roles", below.
Manage role permissions

There are three types of Permissions related to Roles, which can be summarized as follows (where "Role X" represents
the Role currently being viewed on the Role Details page):
n
How Role X can act on other Users who have Role X
How Role X can act on Users with other Roles
How other Roles can act on Role X
The following table provides further details and examples using the Person Supervisor Role:
Role Permission Types
Type
Description
Permissions Specifies the Permissions for the current Role that apply to all users assigned to this Role. For example,
Within this all Users who have the Person Supervisor Role will be able to take these actions on other Person
Role
Supervisors. If no Permissions are selected, then Person Supervisors would not be able to take any actions
on Users with the Person Supervisor Role, unless those Users had another Role that could be acted upon
by a Person Supervisor.
Permissions Specifies the Permissions for the current Role that apply to other Roles. For example, if you are
on Other
configuring Permissions for the Person Supervisor Role, the Permissions specified here define the actions
Roles
that Person Supervisors can take on the other Roles in the system.
Permissions Specifies the Permissions other Roles have that apply to the current Role. For example, by default a
Other
Group Supervisor Role has the following abilities to act on the Person Supervisor Role:Add Person and
Roles Have Use Person. This means that by default Group Supervisors can add the Person Supervisor Role to Users
and can see the names (but not the details) of Users with the Person Supervisors Role so that they can be
added to Groups or sent messages.
Note: it is recommended that this table be used only as a convenient summary of the permissions that
other Roles have on the current Role. If you want to change how a given Role actions on another Role,
use the former's Role Details page to define its "Permissions on Other Roles" settings.
To manage Role Permissions:
1. Navigate to the Role Details page for the Role for which you want to set permissions.
l
If you are adding the first Role for the Company, only the Permissions Within this Role settings are
available.
2. Specify Role Permissions settings for each Role Permission type:

Role Permissions Settings
Setting
Description
Add Person
Indicates whether the current Role can add Users to target Role.
Edit Person
Indicates whether the current Role can edit existing Users associated with the target Role. Note:
Users can always be edited by their Supervisor, regardless of this setting. Further, if Edit Person is
enabled, selecting (or clearing) View Person and Use Person has no effect.
Delete Person
Indicates whether the current Role can delete existing Users associated with the target Role. Note:
Users can always be deleted by their Supervisor, regardless of this setting.
Setting
Description
View Person
Indicates whether the current Role can view the details of Users associated with the target Role.
Note: if View Person is enabled, selecting (or clearing) Use Person has no effect.
Use Person
Indicates whether the current Role can see the names (but not the details) of Users associated with
the target Role to add them to Groups or send them messages.
Manage
Subscriptions
Indicates whether the current Role can manage Subscriptions associated with the target Role.
3. To save the settings, click Save.

Assign functions to roles
You can specify the functions that make up each role on the functions for this role page.
To specify functions for a role:
1. On the Roles page, in the Roles table, click the name of the Role you want to modify.
2. On the Role Details page, in the Common Tasks pane, click Assign Functions to this Role.
3. On the Functions for this Role page, in the Available Functions list, select the Functions you want to assign to
this Role, and then click Add.
l
You can also remove Functions from the Role by selecting Functions in the Selected Functions list, and then
clicking Remove.
4. When you are satisfied with your changes, click Save.
Permissions: locking external data

xMatters objects (e.g., Devices, Groups, Teams) have an associated ownership: xMatters can own objects (i.e., internal
ownership) or they can be owned by a Management System (i.e., external ownership). If you want your Management
System to retain external ownership of object data that is shared with xMatters, you can lock that data so that it cannot
be modified in xMatters.
When importing objects such as Users, Devices, and Groups into xMatters with the Data Synchronization tool, you can
flag certain data as being owned externally (for details, see "Data Synchronization" on page 377).
When objects are in an externally owned state, you can use the External Data page in the xMatters web user interface to
control which externally owned data fields Users can change. For example, if the Group object is externally owned and
you want to prevent Users from changing Group names, you can lock this setting so that it cannot be modified.
However, you cannot use the web user interface to remove objects that have been synchronized as externally owned.
Note:
Users who have a Role that includes the Data Lock Override function are not affected by the External Data
Lock settings (e.g., by default, the Company Admin (hidden) and Support User Roles have this function, and
thus are not affected). Even if a User has the Data Lock Override function, external data cannot be deleted via
the xMatters web user interface.
You can configure the following Object Types on the External Data page:
n
Person (User)
BES Device
Email Device
Permissions: locking external data | 236
Generic Device
Instant Messaging Device
Numeric Pager Device
Text Pager Device
Text Phone Device
Voice Device
Group
Team
Each Object Type has configurable sub-properties; for example, the Group Object Type allows you to configure the
following properties: Active, Name, Description, Time Zone, Use Default Device, and Allow Duplicates.
In a multiple-Company deployment, data locking must be configured independently for each Company.
Note:
The Custom Attributes and Custom Fields Property settings appear on the Persons Locked Properties page. To
be able to lock these settings, they must be flagged as externally owned separately from the Persons object
during the Data Synchronization process. For example, if the Persons object is not set as externally owned, but
the Custom Attributes object is, then you can lock the Custom Attributes setting. Alternatively, if Persons was
flagged as externally owned, but Custom Fields Property was not, you cannot lock the Custom Fields Property
setting.
To specify lock settings for externally-owned data:

1. Log in as a Company Administrator, and then click the Admin tab.
2. On the Administration menu, click External Data.
3. Click the Object Types drop-down list, select an object, and then click Continue.
l
xMatters displays the selected objects Locked Properties settings; the Group Object Type is shown here.
External Data Locked Properties page
4. Select or clear the check box in the Locked column for each Object Property as required.
5. Click Save.
Permissions: locking external data | 237
Administrators
There are two kinds of Administrators in xMatters:Super Administrators capable of configuring Nodes and Node
components, and Company Administrators capable of controlling Company-specific data and maintenance tasks.
Note that these Administrative Roles must be separated in a multiple-Company deployment; in deployments with a
single Company, these roles may be merged during installation, as described in "Installing xMatters" on page 63.
Super administrators
In xMatters, Super Administrators are a purely administrative role; they cannot be assigned to Groups, targeted by
notifications, or respond to messages. They are responsible for configuring all non-Company-specific components within
an xMatters deployment, including the following:
n
Company Quotas
Licenses
Nodes and Device Engines
Clusters
Schedule Jobs
Protocol Providers
Manage super administrators

In a multiple-Company deployment, Super Administrators can manage other Super Administrators using the Super
Administrators page.
To view and manage super administrators:
2. On the Administration menu, click Super Admins.
l
xMatters displays a list of the Super Administrators currently in the system:
Super Administrators page
3. In the Super Administrators list, do any of the following:

l
To modify an existing Super Administrator, click a name in the list to view its Details. For more information
about editing Super Administrators Details, see "Defining Super Administrator Details", below.
To remove a Super Administrator from the list, select the check box next to the Super Administrator or
Administrators you want to remove, and then click Remove Selected.
Administrators | 238
To create a new Super Administrator, click the Add New link, and specify the details for the new Super
Administrators as explained in the "Super Administrator Details settings" table below. Click Save to create
the Super Administrator.
Define super administrator details

You can define Super Administrators on the Super Administrators Details page.
To define Super Administrators details:
1. On the Super Administrators page, in the Super Administrators list, click the name of the Super Administrators you
want to modify.
2. On the Super Administrators Details page, enter the following information into the form:
Super Administrator Details settings
Setting
Description
Active
Select this check box to make the Super Administrator active (i.e., able to log into
xMatters) when you save the details. If you do not want to activate this Super
Administrator immediately, clear this check box.
User ID
Type the User ID for the Super Administrator (e.g., 5102 or Admin2).
First Name
Type the first name of the Super Administrator.
Last Name
Type the surname of the Super Administrator.
Language
Select the language with which you want to associate this Super Administrator.
Time zone
Select the time zone with which you want to associate this Super Administrator.
Web Login
Type the login name for this Super Administrator to use when logging in to xMatters.
(If you are modifying an existing Super Administrator, click the Change Web Login
link in the Common Tasks pane to access theWeb Login and Password settings.)
Web Password
Type the login password for this Super Administrator.
Verify Password
Re-type the login password for this Super Administrator. This helps to prevent
mistakes and typing errors.
Company administrators
After Super Administrators, Company Administrators have the greatest level of permissions in xMatters. Company
Administrators typically carry out configuration and maintenance tasks such as defining Device protocols and managing
Users. The following components and data are Company-specific, and controlled by Company Administrators:
n
Company and Custom Holidays
Sites
Countries, Languages, and Time Zones
Web Services Users
Roles and Functions
Custom Attributes and Custom Fields
Device Types and Device Names
Note:
In an xMatters service provider (i.e., multiple Company) deployment, Super Administrators provide global
host administration and Company Administrators are restricted to administrating a single Company or
tenant (see also "Multiple-Company Deployments" on page 15).
Manage company administrators

You can manage Company Administrators using the Company Administrators page.
To view and manage Company Administrators:
2. On the Administration menu, click Company Admins.
3. If you are logged in as a Super Administrator and more than one Company exists, click the Select A Company
drop-down list and select a Company, and then click Continue.
l
xMatters displays a list of the Company Administrators currently in the system:
Company Administrators in Default Company
4. In the Company Administrators list, do any of the following:

l
To modify an existing Company Administrator, click a name in the list to view its Details. For more
information about editing Company Administrators Details, see "Define company administrator details" on
page 241, below.
To remove a Company Administrator from the list, select the check box next to the Company Administrator
or Administrators you want to remove, and then click Remove Selected.
To create a new Company Administrator, click the Add New link, and specify the details for the new
Company Administrators as explained in the "Company Administrator Details settings" table below. Click
Save to create the Company Administrator.
Define company administrator details

You can define Company Administrators on the Company Administrators Details page.
To define company administrator details:
1. On the Company Administrator page, in the Company Administrators list, click the name of the Company
Administrator you want to modify.
2. On the Company Administrators Details page, enter the following information into the form:
Company Administrator Details settings
Setting
Description
Active
Select this check box to make the Company Administrator active (i.e., ready to
receive notifications) when you save the details. If you do not want to activate this
Company Administrator immediately, clear this check box.
User ID
Type the User ID for the Company Administrator (e.g., 5102 or Admin2).
First Name
Type the first name of the Company Administrator.
Last Name
Type the surname of the Company Administrator.
Site
Select the Site with which you want to associate this Company Administrator. The
available choices are limited to those associated with the related Company.
Language
Select the language with which you want to associate this Company Administrator.
The available choices are limited to those associated with the related Company.
Time zone
Select the time zone with which you want to associate this Company Administrator.
The available choices are limited to those associated with the related Company.
Web Login
Type the login name for this Company Administrator to use when logging in to
xMatters. (If you are modifying an existing Company Administrator, click the Change
Web Login link in the Common Tasks pane to access these settings.)
Web Password
Type the login password for this Company Administrator.
Verify Password
Re-type the login password for this Company Administrator. This helps to prevent
mistakes and typing errors.
3. To save the Company Administrator details, click Save.
Log in as another user

Company Administrators and Support Users can log in on behalf of other Users, allowing them to see xMatters as the
target User would. This feature helps Administrators to review reported problems (e.g., to repair a Group or Device
configuration error, or check Subscription settings) and to perform security reviews by viewing the permissions and
features available to a specific User.
Note:
Service Provider Support Users can also use this feature to log into tenant Companies as their mapped tenant
Company User.
While you are logged in as another User, the following conditions apply:
n
The footer on each page identifies the User you are logged in as beside your own account name.
You can access and modify only those settings and features available to that User.
The Security Audit Report tracks your activities as this User in the On Behalf Of column.
You can log in as one other User at a time.
When you log out, both accounts will be logged out of xMatters; to access xMatters, you must sign in again.
To log in as another User:

1. Log in as a Company Administrator or Support User, and click the Users tab.
2. Using the search tools, locate the User you want to log in as, and click their name to view their details page.
3. On the User details page, in the Common Tasks pane, click Login As User.
l
xMatters displays the Home Page for that User (note that the status text at the bottom right of the page
indicates who is logged in as whom).
Logged in as another User
Sites
Every user in xMatters belongs to a site. Each site represents a physical location and relates to users, clusters, and
companies as follows:
n
Each user belongs to a single site, which controls some of the choices available on each users details page, such
as language and time zone.
Each site can have a primary cluster associated with it. When a primary cluster is defined for a site, xMatters
attempts to route notifications through that cluster first.
Sites are created separately for each company.
Note:
It is strongly recommended that you do not use Sites as a substitute for Custom Attributes or Custom Fields
when defining Dynamic Teams (for more information, see "Custom user information" on page 251). As a best
practice, Sites should be used for larger concepts such as Building 5 or San Francisco Campus;
conversely, Sites should not be used for defining relatively small groupings such as Marketing Office or
Fifth Floor East.
Manage sites
You can create, manage, and modify Sites using the Sites page in the xMatters web user interface.
To view and manage Sites:
2. On the Administration menu, click Sites.
3. If more than one Company exists, click the Select A Company drop-down list and select a Company, and then
click Continue.
l
Sites | 242
xMatters displays a list of the Sites currently in the system.
Sites list
4. From the Current Sites list, do any of the following:

l
To modify an existing Site, click its name in the list to view Site Details. For more information about editing
Site Details, see "Define site details" on page 243, below.
To remove a Site from the list, select the check box next to the Site or Sites you want to remove, and then
To create a new Site, click the Add New link and specify the Site details for the new Site, as explained in
the"Site Details settings table below. Click Save Changes to create the Site.
Define site details

You can configure new or existing Sites on the Site Details page.
To create a new Site or modify an existing Site's details:
1. On the Sites page, in the Current Sites table, click the name of the Site you want to modify, or click Add New to
create a new Site.
2. On the Site page, specify the following information:
Setting
Description
Enabled
Select this check box to make the Site active (i.e., ready to receive notifications) as soon as the
Details are saved. If you do not want this Site to be immediately active, clear the check box.
Note: Users assigned to an inactive Site cannot log in to xMatters or receive notifications.
Name
Type a descriptive name for the Site. This name is used to identify the Site throughout xMatters.
Language
Select a language to associate with this Site from the list. The choices available are limited to
those associated with the related Company.
Time Zone
Select a time zone from the drop-down list to associate it with this Site. The choices available
are limited to those associated with the related Company.
Cluster
Select the primary Cluster to use for the Site.
Address 1
Type the physical location of the Site.
Address 2
Type the physical location of the Site.
Sites | 243
Setting
Description
City
Type the name of the city in which the Site is located.
State/Province
Type the region, state or province in which the Site is located.
Country
Select a country to associate with this Site from the list. The choices available are limited to
those associated with the related Company.
Zip/Postal Code
Type the SIP or postal code for the Site.
3. Click Save Changes.
Countries
Countries are components of sites, and cannot be deleted when they are associated with at least one site. The country
setting determines dialing codes, toll free numbers, and default languages.
Manage countries
You can use the Countries page to determine the countries you want to appear in xMatters.
To view and manage countries:
2. On the Administration menu, click Countries.
Countries, and then click Continue.
l
xMatters displays a list of the Selected Countries for the Company.
Assigning Countries to a Company
Sites | 244
4. From the Countries page, do one of the following:

l
To add Countries to the Selected Countries list, select them in the Available Countries box and then click
Add.
To remove Countries to the Selected Countries list, select them in the Selected Countries box and then click
Remove.
5. To save your selections, click Save.
Time zones
Each site has a default time zone. When a user is assigned to a site, their default time zone is set to match that of the
site. You can also assign other time zones, from which users can choose if they want to override the default time zone
setting.
Manage time zones

You can use the Time Zones page to define which time zones are available to users.
To view and manage time zones:
2. On the Administration menu, click Time Zones.
3. If there is more than one Company in the system, select the Company for which you want to manage the Time
Zones, and then click Continue.
l
xMatters displays a list of Time Zones for the Company.
Assigning Time Zones to a Company
4. On the Time Zones page, do one of the following:

l
l
To add Time Zones to the Company, select them in the Available Time Zones list and then click Add.
To remove Time Zones from the Company, select them in the Selected Time Zones list and then click
Remove.
Sites | 245
Languages
Languages are associated with sites, and countries have default languages. When configuring a users details, the
languages available are based on the company to which the user belongs.
Manage languages
You can manage languages on the Languages page in the xMatters web user interface.
To view and manage languages:
2. On the Administration menu, click Languages.
Languages, and then click Continue.
l
xMatters displays a list of Languages for the Company:
Assigning Languages to a Company
4. On the Languages page, do one of the following:

l
l
To add Languages to the Company, select them in the Available Languages list and then click Add.
To remove Languages from the Company, select them in the Selected Languages list and then click
Remove.
Sites | 246
Note:
During voice notifications, the default voice recording scripts prompt Users to select from a list of available
languages. This list is not updated automatically when you adjust the list of languages available in a
Company, but must be manually changed in the xMatters scripts. For more information about modifying
scripts, see the xMatters Online Developer's Guide.
Company holidays
Each country has a specific set of predefined holidays that you can modify to reflect company requirements.
Note:
For an example of how company, site, and custom holidays can be configured for a company, see
"Example:Create company holidays" on page 249.
Manage company holidays

You manage company holidays using the Company Holidays page.
To view and manage company holidays:
2. On the Administration menu, click Company Holidays.
3. If there is more than one Company in the system, select the Company in which you want to manage the holidays,
and then click Continue.
l
xMatters displays a list of the current Company Holidays for the Company.
4. In the Company Holidays list, do any of the following:

l
To remove a Company Holiday from the list, select the check box next to the Company Holiday or
Company Holidays you want to remove, and then click Remove Selected.
To add a new Company Holiday, click the Add New link, and then use the Find Holidays Search tool to
filter holidays. Select the holiday or holidays that you want to add in the Search Results box, click Add, and
then click Save.
Custom holidays
In addition to company holidays, you can create recurring or one-time custom holidays for companies.
Manage custom holidays

You can manage custom holidays using the Custom Holidays page.
To view and manage custom holidays:
2. On the Administration menu, click Custom Holidays.
3. If there is more than one company in the system, select the company for which you want to manage the holidays,
and then click Continue.
l
xMatters displays a list of the current custom holidays for the company.
4. In the Custom Holidays list, do any of the following:

l
To modify an existing custom holiday, click a name in the list to view its details. For more information
about editing custom holiday details, see "You can define the details for each custom holiday using the
Custom Holiday Details page.", below.
To remove a custom holiday from the list, select the check box next to the holidays you want to remove, and
then click Remove Selected.
Company holidays | 247
To use an existing custom holiday as a template to create a new custom holiday, click Copy Custom
Holiday.
To create a new custom holiday, click the Add New link, and specify the details for the new custom holiday,
as explained in "You can define the details for each custom holiday using the Custom Holiday Details
page.", below. Click Save to create the custom holiday.
Define custom holiday details

You can define the details for each custom holiday using the Custom Holiday Details page.
To modify custom holiday details:
1. On the Custom Holidays page, in the Custom Holidays table, click the name of the custom holiday you want to
modify.
2. On the Custom Holiday Details page, enter the following information into the form:
Custom Holiday Details settings
Setting
Description
Holiday Name
Type the name for the custom holiday. This name will be used to identify the custom
holiday throughout the company.
Description
Type a description of the custom holiday.
Country
Select the country to associate with this custom holiday. The available choices are
limited to those countries associated with the related company.
Frequency
Specifies the date of the custom holiday, and how it recurs:

l
Define by day of Month: select this option if the holiday occurs on the same
calendar day every year, and use the Every Year on drop-down list and field
to specify the date.
Define by day of Week: select this option if the holiday occurs on the same
day every year (e.g., first Monday in September), and use the drop-down lists to
specify the date.
One time only: select this option if the holiday is non-recurring, and use the
Once On drop-down list and field to specify the date.
3. To save the custom holiday details, click Save.
Site holidays
You can adjust the company holidays, including any custom holidays, for each site.
To modify site holidays:
1. Click the Admin tab, and then, in the Administration menu, click Sites.
2. In the Current Sites list, click the name of the site for which you want to modify the holidays.
3. On the Site Details page, in the Common Tasks menu, click Site Holidays.
l
xMatters displays the Site Holidays page.
4. To adjust the holidays, click the Modify link above the Site Holidays table.
5. On the Active Holidays page, do any of the following:

l
l
Select the holidays you want to add to the site from the Available Holidays list, and then click Add.
Select the holidays you want to remove from the site from the Selected Holidays list, and then click
Remove.
6. Click Save to apply your changes and return to the Site Holidays page.
Example:Create company holidays

The following section provides an example of how an administrator could use the custom holidays feature to add new
holidays to a company and assign them to sites. The holidays added in this tutorial are also used in the xMatters user
guide, which includes an example of how to use custom holidays when creating groups and building a schedule.
Define the holiday requirements
Assume that you need to create a new holiday to meet the following requirements:
n
A Company with two Sites (one in New York and one in Los Angeles) wants to have a professional development
day added each year for all of their employees to take advantage of an out-of-office seminar with the CEO.
Because the CEOneeds to attend both seminars, each Site must observe the holiday on a different day. The New
York Site will have their professional development day on the first Thursday in April, while the Los Angeles Site
will have theirs one week later.
Adding these holidays to a Company requires the following steps:

1. Create two new custom holidays.
2. Assign the appropriate holiday to its respective Site.
The steps in this example assume that you have created two new Sites, New York and Los Angeles, and that all of the
available Company holidays are already assigned to both Sites.
Create the custom holidays
The first step to using custom holidays is to create the holidays so they appear in the list of available holidays for a
Company.
To create the holidays:
1. Log in to the web user interface as a Company Administrator and click the Admin tab.
2. In the Calendars section of the menu on the left side of the screen, click Custom Holidays.
3. On the Custom Holidays page, click the Add New link.
l
Holiday Name: Pro Dev Day - NY
Description: Professional Development for New York Site
Country:United States
5. In the Frequency section, select Define by day of week, and then use the drop-down lists to specify the first
Thursday of April.
Example of Custom Holiday Details page
6. Click Save.
7. On the Custom Holidays page, click the Add New link.
l
Holiday Name: Pro Dev Day - LA
Description: Professional Development for Los Angeles Site
Country:United States
9. In the Frequency section, select Define by day of week, and then use the drop-down lists to specify the second
Thursday of April.
10. Click Save.
Both of the professional development days should now be listed on the Custom Holidays page.
Example of new custom holidays
The new holidays are also automatically added to the list of holidays for the Company.
Add custom holidays to a site
Once you have created the custom holidays, the next step is to add them to the Sites.
To assign holidays to a site:
1. On the Custom Holidays or Company Holidays page, in the Common Tasks menu, click Set Holidays for a Site.
2. On the Select Site Holiday page, in the Select the Site drop-down list, select New York.
3. On the Site Holidays page, click the Modify link.

4. On the Active Holidays page, in the Available Holidays list, select Pro Dev Day - NY, and then click Add.
l
The Pro Dev Day - NYcustom holidays is added to the Selected Holidays list.
5. Click Save.
6. In the Location section of the menu on the left side of the screen, click Sites.
7. On the Sites page, in the Current Sites table, click Los Angeles.
8. On the Site details page, in the Common Tasks menu, click Site Holidays.
9. On the Site Holidays page, click the Modify link.
10. On the Active Holidays page, in the Available Holidays list, select Pro Dev Day - LA, and then click Add.
l
The Pro Dev Day - LA custom holidays is added to the Selected Holidays list.
11. Click Save.

You can now use the custom holidays when building schedules for groups and users. For more information about using
site holidays with groups, see the "Supervising Users and Groups" section of the xMatters user guide for a continuation
of this tutorial.
Custom user information

You add custom user information to the xMatters system, and use the information to sort, find, and organize users, as
well as to build dynamic teams. You can add two types of custom information in xMatters:
n
Custom attributes: Custom attributes are groups of user details that can be assigned to users by administrators or,
depending on their assigned permissions, by users themselves. Custom attributes are useful for creating dynamic
teams based on similar skills or details.
Custom fields: Custom fields appear on each users details page, and can be flagged as optional or mandatory.
Useful as a means to store additional information about users or their preferences, custom fields can be text fields,
lists, check boxes, passwords, or numeric values, and used to create dynamic teams or find users.
The main difference between custom attributes and fields is that users can select multiple custom attribute values (i.e.,
from each category), but can select only a single value for each custom field.
Permissions to create custom user information

By default, only xMatters company administrators can create custom attributes and custom fields.
To give another role the ability to create custom attributes, you must add the following permissions to it:
n
view.screen.AddCustomAttributes
view.menuitem.CustomAttributes
view.screen.CustomAttributes
view.screen.CustomAttributeDetails
To give another role the ability to create custom fields, you must add the following permissions to it:
n
view.menuitem.CustomFields
view.screen.CustomFields
view.screen.CustomFieldDetails
For example, if you want to provide group supervisors with the ability to create custom attributes and fields, you can
add the permissions above to the Supervise Groups function (the latter function is one of several that define what a user
with the group supervisor role can do within xMatters). If you plan to add these abilities to several roles, the best
Custom user information | 251
practice would be to create a new function (e.g., "Create custom user information") that you could add to as many roles
as required.
To learn more about the relationship between permissions, roles, and functions, and how to modify them, see
"Permissions: functions and roles" on page 228.
Custom attributes
Custom attributes are additional details that can be associated with Users in the system, and used to organize or search
for Users. xMatters groups custom attributes into custom attribute categories for easier management.
For example, you can create a custom attribute category called Medical Training, with available custom attribute
choices of CPR, Basic First Aid, and Advanced First Aid. You can then assign the custom attributes to
appropriately-trained personnel through each users Custom Attributes page.
Manage custom attribute categories

You can manage custom attributes and categories on the Custom Attribute Categories page in the xMatters web user
interface.
To view and manage custom attributes:
2. In the Company menu, click Custom Attributes.
3. If there is more than one company in the system, select the company in which you want to manage the custom
attributes, and then click Continue.
l
xMatters displays a list of custom attribute categories.
Custom Attribute Categories page
4. In the Custom Attributes Category list, do any of the following:

l
To modify an existing custom attribute category, click a name in the list to view its details. For more
information about editing custom attribute details, see "Define custom attributes and categories", below.
To remove a custom attribute category from the list, select the check box next to the custom attribute
categories you want to remove, and then click Remove Selected.
To create a new custom attribute category, click the Add New link, and specify the details for the new
category, as explained in "Define custom attributes and categories", below. Click Save to create the category.
Define custom attributes and categories

You can define custom attributes and categories on the Custom Attributes Details page.
To define custom attributes and categories:

1. On the Custom Attribute Categories page, click the name of the category you want to modify, or click the Add
New link to create a new category.
l
xMatters displays the Custom Attributes Details page.
Custom Attribute Details page
2. On the Custom Attributes Details page, type a name for the category in the Category Name field.
l
To add a custom attribute, type a name into the New Attribute field, and then click Add Attribute. Repeat
until all required attributes have been added to the category.
To remove custom attributes, select the attributes you want to remove in the Attributes list, and then click
Remove Selected Attribute(s).
4. Click Save.
Custom fields
Administrators can define custom fields to store additional information on each users details page. Custom fields can be
mandatory or optional, and can also be used when searching for a user in the system.
Note:
Custom field names cannot be identical to the names of xMatters objects such as device types and groups.
Manage custom fields

You can manage custom fields on the Custom Fields page in the xMatters web user interface.
To view and manage custom fields:
2. On the Administration menu, click Custom Fields.
3. If there is more than one company in the system, select the company in which you want to manage the custom
fields, and then click Continue.
l
xMatters displays a list of the custom fields for the company:
Custom Fields page
4. In the Custom Fields list, do any of the following:

l
To modify an existing item, click its name to view its details. For more information about editing items in
the Custom Fields table, see "You can define custom fields on the Custom Fields Details page.", below.
To remove an item from the list, select the check box next to the custom fields you want to remove, and then
To create a new custom field, click the Add New link, and specify the details for the new custom field, as
explained in "You can define custom fields on the Custom Fields Details page.", below. Click Save to create
the custom field.
Define custom field details

You can define custom fields on the Custom Fields Details page.
To define custom field details:
1. On the Custom Fields page, in the Custom Fields list, click the name of the field you want to modify.
2. On the Custom Fields Details page, enter the following information into the form:
Custom Field Details settings
Setting
Description
Mandatory
When selected, indicates that each user must supply the information required by the field. Clear this
check box if you want the custom field to be optional.
Field Name
Name for the custom field, which is displayed on each users details page as the label for the field.
Setting
Description
Type
Type of custom field:

o
Text: creates a field for entering alphanumeric text. You can use the Min and Max fields to
specify the minimum and maximum length for the text.
Check box: creates a check box with two possible states: selected or cleared. When selected,
the Field Name statement is true. For example, the Field Name beside a check box might be
Available on Weekends.
Decimal: creates a field for entering a numeric value that can include a decimal. You can use
the Min and Max fields to specify the minimum and maximum value.
Integer: creates a field for entering a numeric value that cannot include a decimal. You can
use the Min and Max fields to specify the minimum and maximum value.
List: creates a drop-down list from which users can select a value. Select List and click Save
to view an Add/Remove List Values area. To add values, type a name in the New List Value
field and click Add List Value. To remove values, select the values in the List Values box,
and click Remove Selected Values.
Password: creates a field for entering alphanumeric text that is hidden under an asterisk mask.
When displayed on a users details page, the field is automatically paired with a second field,
prompting the user to re-enter the data to verify it.
Note: You cannot change the Type of a custom field after creating it.
3. To save the custom field details, click Save.
Password policy
You can set the password requirements for a company using the Password Policy page. The settings on this page
determine the rules each user in a company must follow when creating a login password. The password policy for each
Company must be set independently.
To set the password policy:
2. On the Administration menu, click Password Policy.
l
xMatters displays the current password policy settings:
Password policy | 255
Password Policy page
3. Enter the following information into the form:

Field
Description
Unique
History
Specifies how many passwords xMatters stores for each user. Users cannot reuse a password until they
have consecutively created as many unique new passwords as indicated in the field.
Minimum
Length
Minimum number of characters required for each password.
Required
Specifies how complex users passwords must be; select one of the following options:
Complexity
n None: no specific complexity is required.
n Non-Alpha: passwords must have at least one non-alphabetic character, such as a numeric digit or
a symbol (e.g., !, $, #, %, @).
n Strong: passwords must be at least six characters long, may not include any part of the Users
account name, and must include characters from at least three of the following four categories:
l
English upper-case letters
l
English lower-case letters
Base-10 digits
Non-alphanumeric characters (e.g., !, $, #, %, @).
Maximum
Age
How long (in days) each password will remain valid before the User must create a new password. If a
User's password has expired, they will be prompted to create a new one the next time they log into the
web user interface.
Minimum
Age
How long (in days) a User is required to use their password before they can change it again.
Password policy | 256
Field
Description
Lockout
Threshold
Specifies the maximum number of consecutive invalid logins a User can attempt before their account is
'locked out', preventing them from accessing the xMatters web user interface. To disable this feature and
grant Users an unlimited number of invalid login attempts, enter zero (0). The maximum value for this
field is 50.
xMatters administrators can manually unlock User accounts by navigating to the Change Web Login
page for the User and clicking Unlock.
Lockout
Duration
Specifies how long (in minutes) a User is prevented from accessing xMatters after they exceed the
number of invalid login attempts specified by the Lockout Threshold.
Lockout
Reset
Period
Specifies how many minutes must elapse after a User attempts an invalid login before the failed login
attempt count is reset to zero. This value must be equal to or less than the Lockout Duration.
Display
Last Login
When selected, displays the time and date of the Users previous login when the User logs in to
xMatters.
4. Click Save to apply your changes.

Note:
The password policy settings apply to User web logins only; they are not enforced for web services users, or
users added via the Data Synchronization and Import Data features. Super Administrators for merged and nonmerged accounts cannot be locked out. .
Device types
xMatters supports the following device types for notifications:
n
Email
Voice (Phone)
Text Phone
Text Pager
Numeric Pager
BES(BlackBerry)
Instant Messenger (Jabber)
Fax
You can specify at the company level which device types users can configure. For example, if Company XYZ does not
use email devices to send notifications, you can remove these devices from the available devices for the company; Users
within the company will not see these devices in the "Select the Type of Device" drop-down list on the Add New
Device page.
Manage device types

You can manage device types using the Device Types page.
Device types | 257
To view and manage device types:

2. On the Administration menu, click Device Types.
3. If more than one Company exists, click the Select A Company drop-down list and select a company, and then
click Continue.
l
xMatters displays a list of all device types for the company:
List of device types (your deployment may not support all types shown)
4. From the All Device Types list, do one of the following:

l
To add or remove device types, click the Modify link, select one or more entries in the Available Device
Types or Selected Device Types boxes, click Add or Remove as appropriate, and then click Save.
To modify an existing device type, click its name in the list. For more information, see "Manage device
names" on page 258.
Manage device names

You can manage device names using the Device Names page. This feature allows you to add as many device names as
you need and to standardize device naming conventions for all users.
Also, for security reasons, your organization may not want users to configure personal devices. In this case, you might
use this feature to limit configurable device names to "Work Email", "Work Mobile SMS", "Desk Phone", and so on.
To view and manage device names:
1. On the Device Types page, click the name of the device type you want to view or manage.
2. On the Device Names page, do one of the following:
l
To remove a device name, select the check box next to the device names you want to remove, and then click
Remove Selected.
To add a device name, click the Add New link to view the Device Name Details page. Specify a Name and
Description, and then click Save.
To modify an existing device name, click its name in the table to view its details. Modify the name and
description, and then click Save.
Note that if you are adding an email device name, you can also specify a list of acceptable domain names, as described
in "Specify a whitelist of email domains", below.
Device types | 258
Defining device names
Specify a whitelist of email domains

On the Device Name Details page for Email Device Types, you can specify a list of acceptable domain names (i.e., the
part of the email address following the @ symbol) for email devices in your system. When users add an email device,
they must use an email address that contains one of the approved domains.
Specifying an email domain "whitelist"
If you do not specify a list of domain names for an email device name, users can use any domain name they choose.
To specify domains names for an Email Device Type:
1. On the Device Types page, in the Name column of the All Device Types table, click EMAIL.
2. On the Add Device Names for EMAIL page, do one of the following:
l
l
To specify domain names for an existing device name, click the name you want to modify.
To add a new email device name with a list of approved domains, click the Add New link, and then specify
a name and description for the new email device name.
3. On the Device Name Details page, in the Email Domain field, type the domain names you want users to be able
to select for this device name; for example, "xmatters.com".
l
Do not include the @ symbol in the domain name.
Type a comma or press Enter after each domain to separate the entries in the list.
If you want to include the same domain with different extensions, you must type each domain and extension
pair separately; i.e., "xmatters.com, xmatters.org, xmatters.net".
You can specify up to approximately 250 domains (4000 characters).
Device types | 259
4. When you are finished adding domains, click Save.

l
Note that xMatters will automatically sort the list of domains alphabetically.
Event domains
An event domain is like an event resolution blueprint; all events that come into xMatters have a few pieces of
information that are always required (i.e., predicates). Each source of Events, such as a management system, requires a
separate event domain.
When you add a new Company to a multiple-Company deployment, xMatters automatically creates the following
default out-of-box event domains (and their associated script packages) for the new Company:
Out-of-box event domains
Name
Description and Purpose
advanced_messaging
This event domain is used to handle all notifications required by scenarios in the
Advanced Messaging component. For more information about this feature, refer to the
xMatters user guide.
default
This event domain handles all events that are injected without a domain, or with a
domain that xMatters does not recognize.
devicevalidation
This event domain handles all messages and responses that involve validating user's
devices.
error_responses
This event domain is responsible for generating and handling responses when
notifications encounter an error; for example, when a User attempts to respond to a
notification for which the event has already been terminated.
generic_responses
Thisevent domain is responsible for handling any incoming responses that do not
explicitly target any other event domain.
messaging
This event domain handles all notifications and responses for the Quick Message panel.
ping
This event domain is used to demonstrate two-way communication between xMatters

and the integration agent; used for testing only.
sms_confirmation
This event domain is used to send confirmation, help, and welcome messages to
SMSdevices in compliance with MMAregulations.
sms_deactivation
This event domain is used to send messages to SMSdevice owners and supervisors when
a device is deactivated or delisted by a service provider. For more information about this
feature, see "Configure automatic SMS device deactivation" on page 224.
voicerecordings
This event domain handles all calls and scripts required to manage the voice recordings.
Manage event domains

The Event Domains table identifies all of the event domains in the system, and provides a description for each one. The
table also displays the version of the integration, and the name and revision number of the script package associated
with the event domain. The Export Integration button (in the Action column) allows you to export the scripts and any
Event domains | 260
constants for an event domain to an XML file. For more information about this feature, see "Import and export event
domain information" on page 261.
Note:
The number in the Version column refers to the version number of the integration associated with that event
domain; this number is usually assigned by the xMatters integration developer, and will not generally apply to
the default event domains.
To view and manage event domains:

1. Click the Developer tab.
2. In the Manage Subscriptions menu, click Event Domains.
l
xMatters displays the Event Domains page.
Event domains list

l
To modify an existing event domain, click its name in the list to view its details. For more information, see
"Define event domain details", below.
To delete an event domain, select the check box for the Domains you want to delete, and then click Remove
Selected.
To export event domain information, click the Export Integration button for the event domain you want to
export. For more information, see "Import and export event domain information" on page 261.
To create a new event domain, click the Add New link, and then specify its details on the Event Domain
Details page, as explained in "Define event domain details", below.
Import and export event domain information

The Export Integration feature allows you to export the scripts and event domain constants for any of the event domains
in your system to an XML file. You can then import the XMLfile to another xMatters deployment and recreate the
event domain and its associated settings in a single step. This feature is particularly useful for anyone implementing an
integration on a test system before moving it into a production deployment.
To export event domain information:
On the Event Domains page, click the Export Integration icon for the event domain for which you want to export
the information.
Event domains | 261
xMatters will export the information to an XML file, and save it according to your browser settings; depending on your
configuration, this might include a dialog box prompting you to specify the location to which you want to save the file,
or your browser might automatically save the file directly to your hard drive.
Note:
The name of the event domain and the date and time at which it was created are included in the file name.
Once you have exported the event domain information, you can then use the web user interface to import it into another
deployment.
To import event domain information:
1. Copy the exported XML file to a location on the server to which you want to import it.
2. Log in to the web user interface on the target deployment and navigate to the Event Domains page.
3. Above the Event Domains table, click Import New.
4. On the Import Integration page, click the Choose File button.
5. Use the dialog box to locate and select the XMLfile you want to import.
6. On the Import Integration page, click Upload.
xMatters will create a new event domain and import the scripts and constants contained in the XML file. If an event
domain of the same name already exists in the target system, xMatters will add a number to the new domain; the
existing domain will not be changed in any way.
Define event domain details

You can define or modify the details for event domains on the Event Domain Details page.
To modify an event domain:
1. On the Event Domains page, in the Event Domains for Company table, click the name of the event domain you
want to modify.
2. On the Event Domain Details page, enter the following information into the form:
Event domain details
Detail
Description
Default
Specifies whether this event domain is the default.

When selected, you cannot clear this check box; you can have only one default event domain at any
time. To change your default event domain, navigate to the event domain you want to set as the
default, and select its Default check box.
Name
Name of this event domain. This name identifies the event domain in a drop-down list when creating
subscription domains.
Description
Brief description of the event domain.
Event domains | 262
Detail
Description
Script Package
Identifies the package of business scripts that should be run in response to a particular event.
If you are on a multiple-company deployment, do one of the following:
l
To use a company-specific script package for this event domain, select the Use <Company
Name>Script Package radio button, and then select the script package you want to use from
the drop-down list.
To use the script package from the system's template scripts, select the Use Template Script
Package radio button, and then select the template script package you want to use from the
drop-down list.
When you create a new company, xMatters automatically creates the default event domains, and
assigns the appropriate template script package to each new domain. Before you can assign a custom
script to an event domain, you must create a company-specific set of scripts using the event domain
export feature, as described in "Import and export event domain information", below, and then import
the created package back into your company. You can then modify the scripts using the xMatters
Developer IDE, and specify the scripts you want to use in the Use Template Script Package field.
For more information about script packages, consult the xMatters Online Developer's Guide.
Predicates
List of predicates available in this event domain. For more information about defining predicates, see
"Define predicates" on page 264.
Responses
List of response contributions used for statistical analysis in reports. For more information about
defining response contributions, see "Define response contribution values", below.
3. Click Save.
To manage predicates:
1. On the Event Domains page, click the name of the event domain for which you want to manage predicates.
2. On the Event Domain details page, do any of the following:
l
To reorder predicates, click the Reorder link above the predicates list. On the Order Event Domain
Predicates page, select a predicate in the list and then click Move Up or Move Down. When you are
satisfied with your changes, click Save.
To remove predicates from the list, select the check box next to the predicates you want to remove, and then
To edit a predicates details, click the name of the predicate you want to edit. On the Event Domain
Predicates page, retype the predicate name or select or clear the Important check box. Note that you cannot
change a predicates type; you must delete the predicate and create it again. Click Save to apply the changes
and return to the event domain details.
3. Click Save.
Note:
The predicate order on the Event Domain Details page affects the order in which predicates flagged as
Important are listed in the Event Activity Report, as explained in "Define predicates" on page 264.
Define response contribution values

You can define the contribution value of each possible user response on the Event Domain Details page and specify
whether a response contributes positively or negatively towards resolving an event, or identify a response that does not
Event domains | 263
affect resolution. This feature can help administrators perform statistical analysis on how events are resolved or delayed.
The default contribution values available to assign to a response are:Positive, Negative, and Not Applicable (N/A). The
contribution value for each response received is stored in the xMatters database and included in the event reports.
Note that the response contribution values defined on this page do not determine the response choices available to users.
Response choices are configured using the xMatters Action Scripts, as detailed in the xMatters Online Developer's
Guide.
To assign contribution values for responses:
1. On the Event Domains page, click the name of the event domain for which you want to define contribution
values.
2. On the Event Domain details page, do any of the following:
l
To add a new response contribution value, click the Add New link in the Response section. In the Response
field, type the text of the user response you want to add. In the Contribution field, select the contribution
value you want to assign to the response. Repeat for each response contribution setting you want to add.
To edit a response contribution, modify the values in the Response and Contribution fields for the response
you want to edit.
To remove a response contribution, select the check box next to a response, and then click Remove Selected.
Note that this will not affect responses and response contribution values already in the database.
3. Click Save to apply the changes.

Response contributions for annotated responses
To provide support for integrations and deployments that allow recipients to annotate their responses, a response is
matched to a contribution value if it matches the response choice exactly, or if it starts with the exact response text
followed by at least one space. For example, both "ACCEPT" and "ACCEPT-be there in ten minutes"would match a
response contribution defined for a response choice of "ACCEPT". A response of "ACCEPTING" would not match,
because there is no space after "ACCEPT".
Note:
The scripts for the event domain must still allow for responses with annotations, or the response may not be
recognized as a valid response choice.
This also means that response choices that begin with the same text as another response choice may not map to the
correct contribution value. For example, "ACCEPT"and "ACCEPT AND TERMINATE" will map to the response
contribution value specified for "ACCEPT", even if the two responses are set to different contribution values.
This is also the case if the short text of a response (followed by a space) matches the beginning of the long text of
another response; for example, if "ACC" is the short form of the "ACCEPT" response, and another response is "ACC
AND ESCALATE". Even if your scripts do not allow responses with annotations, you should ensure that none of the
responses with defined contribution values begin with the same text or text-and-space combination.
Define predicates
You can define the list of predicates for each event domain independently, and edit or add predicates at any time. Note
that if you are defining predicates for use with Scenarios (e.g., adding to the "advanced_messaging"domain), you will
also need to add the predicates to the related Message Domain (as described in "Define message domain details" on page
285), after you have added them to the event domain.
To add predicates to an event domain:
1. On the Event Domains page, click the name of the event domain for which you want to add a predicate.
2. On the Event Domain details page, click the Add New link above the predicates list.
l
xMatters displays the Event Domain Predicates details page:
Event domains | 264
Event Domain Predicates page

Detail
Description
Predicate Name Name of the predicate, as displayed in event domain details and on Subscription panels.
Important
Specifies whether the predicates value should be displayed in event reports.

An Event Report displays the first three predicates flagged as Important in each event domain as
Detail 1, Detail 2, and Detail 3. The order in which the predicates are listed on the page determines
their position in the report.
For example, if an event domain contains ten predicates, and numbers two, five, and eight are
flagged as important, then the value for Predicate Two is included in the event details report as
Detail 1, Predicate Fives value is included as Detail 2, and Predicate Eights value is included as
Detail 3.
If more than three predicates are flagged as Important, only the first three are included in the report.
Required
When selected, any injected event that does not contain this predicate will be rejected by the
system, and no notifications will be sent. xMatters will also send out a Health Monitor message
about the failure; for details about the failure, review the event details reports for the event.
Note:This feature is still in Beta release.
Event domains | 265
Detail
Description
Validate
When this option is selected, the system will compare each incoming predicate against either a
specified pattern for text predicates or the list entries for list predicates.
If the predicate value does not match the pattern, or if a list item does not match one of the
specified list values, the event will be rejected and no notifications will be sent. xMatters will also
send out a Health Monitor message about the failure; for details about the failure, review the event
details reports for the event.
To set the validation criteria for text predicates, specify the following settings:
n
Pattern Library:specifies a common input type against which the predicate value should be
compared.
Pattern:specifies the Java regular expression to compare against the incoming predicate
value.
For a list of the available pattern libraries and their default patterns, see "Validation patterns",
below. You can also select a pattern library and then modify the regular expression for custom
behavior.
Note:This feature is still in Beta release.
Type

l
l
Text: allows Users to specify operators to match values.

List: presents a predefined set of values from which Users can select one or more values. To
add a list value, type the value you want to add in the New List Value field and then click
Add List Value. To remove a value from the list, select the values you want to remove, and
then click Remove Selected List Values.
Note that you cannot change the predicates type after it has been created; you must delete the
predicate and create it again.
4. Click Save.
Validation patterns
The following table lists the available pattern libraries and the default regular expression for the validate feature. Note
that you can also select a pattern library and then modify the pattern using Java regular expression syntax for custom
behavior.
Pattern library options
Pattern Name
Default Value
Letters only
[A-Z,a-z]*
Numbers only
\d*
5 Numbers only
\d{5}
Basic Decimal number
[-\+]?\d+\.?\d
Event domains | 266
Pattern Name
Default Value
Basic IPAddress (no range checking)
\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}
Generic date time
\d{1,4}/\d{1,2}/\d{1,4} \d{1,2}:\d{2}(:\d{2}) (AM|PM)?
ISODate time (ISO 8601)
\d{4}\-\d{2}\-\d{2}T\d{2}:\d{2}(:\d{2})?(Z)?
Boolean (case-insensitive)
(?i:true|false|yes|no)
String 10 characters or shorter
.{0,10}
Other - Manual
Subscriptions
With subscriptions, xMatters can automatically notify Users whenever an event matches a predefined set of criteria. For
example, when a certain type of error occurs on a specific asset or service, xMatters can notify a particular Group.
Subscriptions allow users and managers to be notified every time an event occurs that matches specific criteria, even if
that person would not normally be notified for that event. For example, a building manager might want to know every
time a problem occurred in a specific building, even if they were not on duty at the time, or a product owner might want
to be informed of any customer issue that involved a particular model number.
Subscriptions can be used in one of two ways: managed, or self-managed. With self-managed subscriptions, Users with
proper permissions can create their own subscriptions for informational types of events and alerts. With managed
subscriptions, supervisors can define subscriptions and assign them to Groups or Users, who can then see what has been
assigned to them. You can also create subscriptions that are both self-managed and managed; supervisors can assign
them to Users, or Users can subscribe to them on their own.
Subscriptions terminology
The following are terms used by xMatters when referring to subscriptions and the relevant processes.
Subscription Terms
Term
Definition
Event Domain
Event Domains are used to identify the source of incoming events or incidents, and to indicate
which important information is included in the event. This information is then defined as a
predicate, or name/value pair.
Predicate
The important information in an event, presented to Users as name/value pairs when they are
subscribed to a Subscription Domain.
Note that different combinations of predicates make up the pattern for a Subscription Domain, but
the predicates must first be defined in the Event Domain.
Subscriptions | 267
Term
Definition
Subscription
Domain
Subscription Domains specify which Event Domain is associated with the events to which you
want to subscribe. They also allow you to control who can create subscriptions, how (and whether)
recipients can respond to subscription notifications, and which Event Domain predicates or form
properties can be used to create a subscription.
Roles
The Administrative Roles specified on each Subscription Domain identify which Users have
permission to act on Subscription Domains, and create or edit subscriptions for those domains.
Preparing Subscriptions
Before you can create and use Subscriptions, you will need to prepare by configuring the Event and Subscription
Domains and modifying the script package for the Event Domain.
The following steps must be repeated for each Event Domain for which you want to create Subscriptions.
To prepare Event and Subscription Domains:
1. Create an Event Domain for the source of the events to which you want to subscribe, and add predicates to the
Event Domain.
l
For more information about Event Domains and defining predicates, see "Event domains" on page 260.
2. Configure the Subscription Domain and define the details as described in the sections "Configuring Subscription
Domains" and "Specifying Administrative Roles", below.
3. Modify the script package for the Event Domain to ensure it is configured for Subscriptions, as explained in the
following section, Modifying Script Packages for Subscriptions.
4. To test the Subscription, create a Subscription on the new Subscription Domain as described in "Managing
Subscriptions" on page 275, and then inject a test event in the Event Domain.
Modifying Script Packages for Subscriptions

Each Event Domain has a separate Script Package that must be configured to handle subscriptions. Use the xMatters
Developer IDE to configure a Script Package (for more information on using the Developer IDE, refer to the xMatters
Online Developer's Guide ).
To enable subscriptions in a Script Package:
1. Using the xMatters Developer IDE, check out the Script Package for the selected Event Domain.
l
The default Script Package is configured to handle subscriptions out-of-the-box; no changes are necessary
if you are using the default Event Domain.
Add the following section to the PROCESS - initial script, immediately after the
@alert::performNotification() method:
#added for subscriptions handling

$subscriptionList = @event::getSubscriptions()
FOR ($subscriptionId : $subscriptionList )
@subscription = @event::getSubscription($subscriptionId)
@subscriptionAlert = @subscription::notification()
@subscriptionAlert::setHandlerScript("response")
@subscriptionAlert::setPresentationScript("messaging")
@subscriptionContent = @subscription::content()
$subscriptionContent.message = "undefined"
if (EXISTS($subscriptionContent.choices))
$main.subscriptionChoices = $subscriptionContent.choices
endif
@subscriptionAlert::setContent(@subscriptionContent)
@subscriptionAlert::performNotification()
ENDFOR
Subscriptions | 268
3. Ensure the response handler script exists and is configured to handle the responses defined in the two-way
responses section of the subscription.
l
Any handler script can be used for this purpose, as long as the @subscriptionAlert::setHandlerScript
() method is calling the correct script.
4. Ensure the messaging presentation script exists and generates the correct content.
l
Any presentation script can be used for this purpose, as long as the
@subscriptionAlert::setPresentationScript() method is calling the correct script.
5. Check in the modified Script Package as a production version.
Configuring Subscription Domains

Users can subscribe to a Subscription Domain, and whenever an Event occurs that matches the criteria, all Users who
have subscribed to that domain are notified.
To view and manage Subscription Domains:
1. Click the Development tab.
2. In the Domains menu, click Subscription Domains.
l
xMatters displays a list of Subscription Domains for the current Company:
Subscription Domains page

l
To modify an existing Subscription Domain, click its name in the Subscription Domains list to view its
details. For more information, see the Subscription Domain details table, below.
To delete a Subscription Domain, select the check box next to the domains you want to delete, and then
To add a new Subscription Domain, click the Add New link, and then specify its details on the Subscription
Domain details page as explained in the following section.
Defining Subscription Domain details

You can create new Subscription Domains or modify the details for existing Domains from the Subscription Domains
page.
To set Subscription Domain details:
1. On the Subscription Domains page, do one of the following:
l
To modify an existing Subscription Domain, in the Subscription Domains for Company table, click the name
of the Subscription Domain you want to edit.
Subscriptions | 269
To create a new Subscription Domain, click the Add New link. On the Add Subscription Domain page, in
the Event Domain drop-down list, select the Event Domain or on which you want to create the Subscription
Domain, and then click Continue.
2. On the Subscription Domain Details page, enter the following information into the form:
Subscription Domain details
Detail
Description
Name
Name of this Subscription Domain. This name should be descriptive enough so that
the nature of the issues caught by the domain is clear. For example, assume that you
want to create a Subscription Domain based on an Event Domain named Help Desk
with predicates of Software, Hardware, and Network. Your new Subscription Domain
will be limited to the Software predicate and its values (e.g., OS, Upgrades,
Applications, etc.). As a result, you name the new Subscription Domain Help Desk
Software Tickets.
Description
Brief description of this Domain. Although this field is optional, it is recommended

that you specify a description that will help Users understand the nature of the alerts
they will receive when subscribed. Following from the example above for the Name
field, you might specify a description of "Subscription Domain for Help Desk Tickets
related to software issues such as operating systems, upgrades, applications, and so
on".
One Way
When selected, indicates that alerts generated by this Subscription Domain are
informational only, and will not accept or require a response from Users. If this not
selected, you must specify response choices as described below.
Type of Management
Select one of the following options to specify who can manage subscriptions to this
domain:
l
Self-Managed: Subscriptions in this domain can be modified by the subscriber,

or by Users with Manage Subscriptions permissions for the subscriber.
Managed: Subscriptions in this domain can be modified only by Users that
have Manage Subscriptions permissions for the subscriber.
Both: This domain supports both managed and self-managed subscriptions.
These settings are based on Administrative Roles permissions, as explained below.

Custom Page URL
(Note:required only if you
are not using the default
Subscription panel.)
If you are not using the default Subscription panel, use this setting to specify the
location and file name of the custom subscription interface for this domain. This path
must be relative to the <xMHOME>/webserver/webapps/cocoon/alarmpoint
directory.
For example, if you created a new CustomSubscription.jsp file and stored it in
the <xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/
subscription/custom/ folder, the Custom Page URL would be:
jsp/subscription/custom/CustomSubscription.jsp
For more information about creating custom Subscription panels, see the xMatters
Online Developer's Guide.
Subscriptions | 270
Detail
Description
Suppressed Subscription Fields Specifies the elements that you do not want to appear as overrides on subscriptions
for this domain. Items that are not excluded here appear on the default Subscription
panel in the "Overrides" section, and allow subscription creators to modify
subscription notification handling. For example, if you want to ensure that
subscription creators cannot change escalations between Groups or specify that
Device delays should be ignored, you would select Group Escalation and Ignore
Device Delay here; as a result these settings would not appear as options in the
Overrides section of the default Subscription panel
Select the check box next to any of the following options to suppress them:
l
Timeframe (uses a default 24x7 timeframe)
Group Escalation
Notification Delay
Override Device Timeframe
Ignore Device Delay
Override Device Severity
You can specify default values for the Override Device Timeframe, Ignore Device
Delay, and Override Device Severity settings in the Subscription Defaults area, as
explained below.
Suppressed Devices
Specifies the names of Devices that will not be available to select as targets on the
Subscription Details page.
Subscription Defaults
Specifies the default settings for Subscriptions created on this domain. Select the
check box next to any of the following options to set a default value:
l
Override Device Timeframe: when selected, subscriptions created on this

domain will override Device Timeframes specified by the notification recipient.
Ignore Device Delay: when selected, subscriptions created on this domain will
ignore any Device delay settings specified by notification recipients.
Override Device Severity: when selected, subscriptions created on this domain
will override the Device severity settings specified by notification recipients.
Note that unless these settings are suppressed using the Suppressed Subscription
Fields as explained above, subscription creators can override the defaults on the
Subscription Details page. For more information, see "Defining Subscription Details"
on page 276.
3. Click Continue.
l
If you selected to create a one-way Subscription Domain, continue to Step 6 to add predicates. If you are
creating a two-way Domain, xMatters displays the Response Choices page.
Subscriptions | 271
Subscription Domain Response Choices
4. Do any of the following:
Note:
To add a response choice, type it in the Enter Response field, and then click Add Response.
To delete a response choice, select it in the Responses field, and then click Remove Selected Response.
If you add new subscription responses, you must modify the corresponding handler script. For more
information, see "Updating Subscription Response Handler Scripts" on page 274.
5. Click Continue.
l
xMatters displays the Select Predicates page, where you can specify (or exclude) predicates that are relevant
to the subscription you are creating. For example, if you are creating a Subscription Domain that focuses on
software problems and predicates such as Windows, Oracle, and SAP are available, you will likely want to
include these in your Subscription Domain. Conversely, for the same domain you may want to exclude
potentially irrelevant predicates such as Hardware and Medical from the Applied Predicates list.
Subscriptions | 272
Selecting Appropriate Predicates

l
To add predicates to the Subscription Domain, select them in the Available list, and then click Add.
To remove predicates from the Subscription Domain, select them in the Applied list, and then click Remove.
7. Click Continue to apply your changes and assign.

Note:
If you are creating a new Subscription Domain, be sure to assign Administrative Roles, as explained below.
Specifying Administrative Roles

By specifying Administrative Roles for a Subscription Domain, you can identify who can create subscriptions using that
domain. For example, if you include Group Supervisors as an Administrative Role, all Group Supervisors in xMatters
would be able to create subscriptions based on that Subscription Domain.
Note that Users who do not have permission to create subscriptions will not be able to view or use the Assign Alerts
page.
Note:
For information on creating Roles and assigning users to them, see "Permissions: functions and roles" on page
228.
To assign Roles to a Subscription Domain:

1. On the Subscription Domains page, click the name of the Subscription Domain for which you want to set the
Roles.
2. On the Subscription Domain Details page, in the Common Tasks panel, click Assign Roles.
l
xMatters displays the Assign Administrative Roles page.
Subscriptions | 273
Select Roles page
3. On the Subscription Domain Administrative Roles page, do the following:

l
To assign an Administrative Role, select the role you want to assign in the Available Roles list, and then
click Add.
To remove an Administrative Role, select the role you want to remove in the Applied Roles list, and then
click Remove.
4. Click Save.
Updating Subscription Response Handler Scripts

After modifying the response choices for a subscription, you must modify the corresponding handler script using the
xMatters Developer IDE. For more information about installing and using the Developer IDE, see the xMatters Online
Developer's Guide.
The following is an excerpt from the out-of-the-box messaging subscription response script:
IF ($reply == "Acknowledge" || $reply == "1")
@notification::delink($response.person_target)
ELSE
IF (EXISTS($event.debug))
@script::log($event.incident_id & ": Response unrecognized: " & $reply)
ENDIF
# get the recipient that responded and increment the
# number of invalid responses.
@recipient = @event::getRecipient($response.recipient_target)
@event::report("Received unrecognized response: " & $reply,
$notification.id)
@externalMessage = @event::createExternalServiceMessage()
$externalMessage.message = "Received unrecognized response from" & $response.recipient_
target & ": " & $reply
@externalMessage::send()
IF (EXISTS($recipient.invalidCount))
$recipient.invalidCount = $recipient.invalidCount + 1
ELSE
$recipient.invalidCount = 1
ENDIF
Subscriptions | 274
To add handling for an additional response, add an ELSE-IF section:

IF ($reply == "Acknowledge" || $reply == "1")
@notification::delink($response.person_target)
ELSE-IF ($reply == "Clear" || $reply == "2")
# Add handling for the 'Clear' response
ELSE
IF (EXISTS($event.debug))
@script::log($event.incident_id & ": Response unrecognized: " & $reply)
ENDIF
...
ENDIF
Managing Subscriptions
xMatters administrators (and Subscription Supervisors) can assign Subscriptions to Users, and manage Subscriptions in
Note:
For information about how Users subscribe to Alerts, or Self-managed Subscriptions, see the xMatters user
guide.
To view and manage the Subscriptions you have assigned:

1. Click the Alerts tab.
2. In the Subscribed Alerts menu, click Assign Alerts.
l
xMatters displays a list of the Subscriptions you manage for the domain listed in the Subscription Domain
drop-down list, with a summary of the conditions and recipients for each Subscription:
Assign Alerts page
Subscriptions | 275
3. In the Subscriptions that I Manage table, do any of the following:

l
To modify an existing Subscription, click its name to view its Subscription Details. For more information
about editing Subscriptions, see the following section, "Defining Subscription Details".
To view, add, and edit the Groups or Users to which a Subscription is assigned, click the Recipients link in
the Subscription summary. For more information about assigning and editing subscribers, see "Managing
Subscribers" on page 282.
To remove a Subscription, select the check box beside the Subscription or Subscriptions that you want to
To create a new Subscription, specify the type of Subscription you want to create by selecting a Subscription
Domain from the drop-down list, and then click the Add New link. (If you have already created a
Subscription on this domain, you can choose to copy the new Subscription from an existing one.) Specify
the Subscription details as explained in the "Subscription details table below. Click Save, and then specify
the Users, Groups, or Teams you want to assign to the Subscription as explained in section "Managing
Subscribers" on page 282.
Using the Subscriptions table

When viewing the Subscriptions table, you can do any of the following:
n
To view the Subscription list for a different Subscription Domain, select a domain in the Subscription Domain
drop-down list. Note that this option is visible only when other Subscriptions Domains are available.
To change the number of Subscriptions displayed at one time, select a number in the Results per page drop-down
list, and then click Apply.
If there are more values specified for a predicate than can be shown in the table, xMatters displays an ellipsis at the
end of the row. Mouse over the row to view a pop-up containing a list of all values that apply.
If there are more recipients than can be displayed in the Recipients row, xMatters displays an ellipsis at the end of
the row. Mouse over the row to view a pop-up containing a list of all recipients.
Predicate names longer than 18 characters are truncated. You can view full predicate names on the Subscription
Details page.
Each Subscription shows up to five predicates, with those predicates flagged as Important shown at the top of
each list. If a Subscription contains more than five predicates, click the More information link to view all
subscribed predicates.
Defining Subscription Details

You can use the Subscription Details page to define the details for each subscription.
To modify Subscription details:
1. On the Assign Alerts page, in the Subscriptions that I Manage list, click the name of the subscription you want to
modify.
l
xMatters displays the Subscription Details page.
2. On the Subscription Details page, enter the following information into the form.
Note:
Depending on the settings for the Subscription Domain, some of the subscription details may be suppressed
and not visible or editable on the Subscription Details page.
Detail
Description
Name
Name of the subscription.
Subscriptions | 276
Detail
Description
Attributes
Details within each alert to which you can subscribe. The available Attributes are based on the
predicates included in the Subscription Domain. Do one of the following:
l
For text-type attributes, select an operator from the drop-down list, and then type the text
string to match against in the Value field.
For list-type attributes, select a value (or use Ctrl-click to select multiple values) for each
attribute in the list beside it.
Any alerts that have a matching value for the specified attributes will be sent to subscribers as part
of the subscription.
For more information about specifying the available attributes for subscriptions and the expected
behavior, see the following section, "Specifying attributes and values in subscriptions" on page
278.
Devices
In the Devices area, specify the names of the Devices to which you want to send subscription
notifications. If the recipients you assign to this subscription do not have a Device with the
specified name, they will not receive notifications.
Select All Devices to send subscription notifications to any Devices configured for the recipients
in xMatters. (This is also the default behavior if you do not select any of the other check boxes.)
Note that if you add or change a Device name, you will need to update the subscription if you
want to receive notifications for the subscription on that Device.
Start Date
Date on which the subscription should begin; the default is the current date.
Start Time
Time of day at which the subscription begins, followed by the length of time, in hours and
minutes, for the subscription to last each day.
On the following
days
Select the days of the week for the subscription to be in effect.
Time Zone
The time zone on which to base this subscription.
Group Escalation
Escalation string (comma-delimited values) to use for any Groups subscribed to the subscription.
Note that this will override any existing escalation values set for Group recipients.
For example, a Group Escalation field value might resemble the following:
0,10,5
In this example, xMatters would immediately notify the first member of any Groups subscribed to
this Subscription. Ten minutes later, xMatters would begin notifying the next Group member, and
five minutes after that, would begin notifying the third.
xMatters uses the last value specified as the escalation value for any remaining Group members. In
the example above, xMatters would wait five minutes between notifications to all Group members
after the first three.
Subscriptions | 277
Detail
Description
Override User
Device
Timeframes
Select this check box to use the subscription timeframe instead of User-defined timeframes.
Ignore Device
Delays
Select this check box to ignore any User-defined Device delays.
Override Device
Select this check box to ignore any User-defined severity restrictions on the selected Device type.
Severities and Use
All
Notification
Delay
Specify the length of time, in minutes, that you want xMatters to wait before sending an alert for
this subscription.
Note that the delay is calculated from the point that xMatters receives the original event. For
example, if you specify a Notification Delay of ten minutes, and an event is submitted to xMatters
at 4:51pm, xMatters will treat the event as though it was received at 5:01pm. The delay you
specify for your subscription does not affect any other subscriptions or alerts in the system.
3. In the Recipients area, do either of the following:

l
To assign subscribers for this Subscription, click the Add Users, Add Groups, Add Devices, or Add
Dynamic Teams link and specify the recipients you want to add (note that xMatters ignores scheduling and
User preferences when notifying Devices added as subscription recipients).
To remove subscribers from this subscription, select the check box next to the recipients you want to remove,
and then click Remove Selected.
4. Click Save.
l
If you want other Users to be able to view and edit the subscription, assign Subscription Managers as
explained in "Setting Subscription Managers" on page 282.
Specifying attributes and values in subscriptions

The following sections explain how xMatters evaluates attributes and name/value pairs when determining recipients for
a subscription notification.
Specifying values for list-type attributes
When selecting values for a list attribute, you can select a single value, multiple values, ANY values, or leave the
field blank. xMatters considers it a match if any one selected value matches the attribute values in the event. If you
select ANY, xMatters will consider any value for the attribute a match for the Subscription, including values not
specified in the Subscription Domain.
For example, assume that a Subscription Domain includes a list attribute of Service, with pre-defined values of A,
B, and C. The following table summarizes the match results of different attribute values within an incoming event,
including a value not specified within the Subscription Domain:
Attribute in Event
Subscription Criteria
Match
ANY
Yes
Subscriptions | 278
Attribute in Event
Match
A, B, C
Yes
A, ANY (stored as ANY)
Yes
NULL (not specified)
Yes
No
ANY
Yes
A, B, C
No
A, ANY
Yes
NULL
Yes
No
Subscribing to attributes with multiple values

You can enable the integration agent to submit attributes with multiple values, and create subscriptions for those
attributes. (For more information about enabling this feature, see the xMatters integration agent guide.) When dealing
with these attributes, xMatters considers it a match if any subscribed value appears in the attribute.
For example, assume that an incoming event has a attribute with multiple values. The following table summarizes the
match results of different subscriptions for that attribute:
Determining Subscription Results for Attributes with Multiple Values
Attribute Values
Match
A, B, C
Yes
A, B, C
A, C
Yes
A, B, C
A, Z
Yes
A, B
B, C, Z
Yes
A, B, C,
No
Subscribing to multiple attributes

The relationship between attributes in a subscription is considered an AND. For the subscription to match, the
conditions must match for each attribute.
For example, assume that a Subscription Domain is created with two attributes, Service and Severity, and a
subscription is created against Service values of A or B, and Severity of ANY:
n
An event containing a Service value of C and a Severity value of Sev1 does not result in a match.
An event containing a Service value of B and a Severity value of Sev3 results in a match.
Subscriptions | 279
Subscriptions and missing attributes

It is possible that a submitted event will not contain the token or attribute needed for the Subscription Domain. If the
event token is missing it will be considered a match for all subscriptions that have subscribed to the value of ANY,
and any subscriptions that have a null value. A literal value does not result in a match.
The following table describes the results of different subscription criteria based on the value of the attribute contained in
the event:
Determining Subscription Results for Missing or Unspecified Predicates
Attribute in Event
Match
Unspecified
Non-empty
No
Unspecified
Empty
Yes
Unspecified
ANY
Yes
Specified, but empty
Non-empty
No
Empty
Yes
ANY
Yes
Specified
Non-empty, including specified value
Yes
Specified
Non-empty, not including specified value
No
Specified
Empty
Yes
Specified
ANY
Yes
Example
Assume that an incoming event contains the following tokens and values:
subject = Undeliverable: ServiceDesk Severity 4 ticket TKT14113460 assigned; SD_Global_SOXA_
BVL_HRDWQueries_Access
impact = Customer Broadband
market = Albuquerque,Charleston,Colorado Springs
os = AIX,Linux,Windows
The following table defines potential subscription parameters, the operators used, and whether the subscription would
match the event.
Subscription Details
Result
subject CONTAINS"Severity 4"
Match
subject CONTAINS"Severity4"
Does not match
subject CONTAINS"ServiceDesk, assigned"
Does not match
Subscriptions | 280
Subscription Details
Result
subjectCONTAINS"ServiceDesk ANDassigned"
Does not match
subject CONTAINS "ServiceDesk ORassigned"
Does not match
subject CONTAINS "ServiceDesk&assigned"
Does not match
subject CONTAINS "ServiceDesk|assigned"
Does not match
impact MATCHES"Customer Broadband"
Match
impact MATCHES"CustomerBroadband"
Does not match
impact MATCHES"Broadband"
Does not match
market = Albuquerque, Charleston, Colorado Springs
Match
market = Albuquerque
Match
market = Albuquerque, Portland
Match
market = Fresno, Portland
Does not match
subject CONTAINS "Severity 4"

os = AIX
Match
subject CONTAINS "Severity4"

os = AIX
Does not match
subject CONTAINS "ServiceDesk"

impact MATCHES"Broadband"
os = AIX
Does not match

market = Fresno, Portland
os = AIX
Does not match

os = Solaris, HP-UX
Does not match
Subscriptions | 281
Hierarchy property operators:
Setting Subscription Managers

By default, a subscription can be edited or assigned to additional subscribers only by its creator. To allow additional
Users to view and edit a subscription, you can assign Subscription Managers.
To assign Subscription Managers:
1. On the Alerts tab, click Assign Alerts.
2. On the Assign Alerts page, in the Subscriptions that I Manage table, click the name of the Subscription for which
you want to assign a manager.
3. On the Subscription Details page, in the Common Tasks pane, click Subscription Managers.
l
xMatters displays the View Managers page:
Subscription Managers

l
To add a manager for the subscription, click the Modify link. On the Find Managers page, use the search
tools to locate the User you want to add. Select the User in the Available Subscription Managers list and
then click Add. Click Save to apply your changes and return to the View Managers page.
To remove a manager from the subscription, select the check box next to their name in the Subscription
Managers table, and then click Remove.
5. When you are satisfied with your changes, click Back to Details in the Common Tasks pane.
Managing Subscribers
Once you have created a subscription, you can assign it to Groups, Users, Devices, or Dynamic Teams. You can also edit
the list of subscribers to existing subscriptions.
To modify subscribers:
1. On the Subscriptions page, in the Subscriptions list, click the Recipients link for the Subscription you want to
modify.
l
xMatters displays the Subscription details page.

l
To add subscribers to this subscription, click the Add Users, Add Groups, Add Devices, or Add Dynamic
Teams links. Use the search pages to find and specify the subscribers you want to add, and then click Save
to return to the subscribers page.
To remove a subscriber from the list, select the check box next to the subscribers you want to remove, and
then click Remove Selected.
3. When you are satisfied with your changes, click Finish.
Subscriptions | 282
Adding User Devices as Subscription Recipients

When you add a Users Device to a subscription, xMatters ignores the preferences set by the User, such as temporary
replacements, Device priority, and Device delays, and sends notifications directly to the Device.
Searching for Subscriptions

You can use the Look Up Assignments tool to find Subscriptions for specific Users or Groups, or to view all
Subscriptions based on a specific Subscription Domain.
To find Subscriptions based on a Subscription Domain:
1. On the Alerts tab, in the Subscribed Alerts menu, click Look Up Assignments.
l
xMatters displays the Search Subscriptions By Subscription Domain page:
Search Subscriptions by Subscription Domain page
2. Select a domain from the Subscription Domain drop-down list, and then click Select.
l
xMatters displays a list of the predicates in the Subscription Domain.

l
In the Value field for each predicate, type the value or list of values for which you want to search. If you are
searching for a list of values, type the character you use to separate list values in the Delimiter field. (Note
that you must specify all of the Predicate Values for an existing Subscription, or no results will be returned.)
To search for all Subscriptions based on the Subscription Domain, leave the Value fields blank.
4. Click Search.
l
xMatters displays the Subscriptions By Domain page, which lists all Subscriptions matching your criteria.
Subscriptions | 283

l
To adjust the number of Subscriptions displayed at a time, select a number from the Results per page dropdown list, and then click Filter.
To change the details of a Subscription, click its name in the Subscription column.
To add, edit, or remove a Subscription s managers, click the link in the Managers column.
To find Subscriptions for specific Users or Groups:

1. On the Alerts tab, in the Subscribed Alerts menu, click Look Up Assignments.
2. On the Search Subscriptions By Subscription Domains page, do one of the following:
l
To search for Subscriptions for a specific User, click the Search By Users link.
To search for Subscriptions for a specific Group, click the Search By Group link.
3. Use the search criteria to find the User or Group for which you want to view Subscriptions, and then click the
name in the Results table.
l
To adjust the number of Subscriptions displayed at a time, select a number from the Results per page dropdown list, and then click Filter.
To change the details of a Subscription, click its name in the Subscription column.
To add, edit, or remove a Subscriptions managers, click the link in the Managers column.
Message domains
Message domains are used by the Advanced Messaging feature to create and initiate scenarios based on a specific event
domain. For example, the default scenarios use the "Scenario" message domain to create scenarios based on the
"advanced_messaging" event domain.
You can use multiple message domains on the same event domain to limit the predicates available in the scenarios
associated with that domain. You can also specify which roles can create scenarios using each message domain.
Note that message domains are not used in conjunction with messaging panels; Custom messaging panels are a separate
feature, explained in "Custom messaging panels" on page 286, and discussed in detail in the xMatters Online
Developer's Guide.
Manage message domains

Each message domain is associated with an event domain, which in turn is associated with a specific script package.
Before creating a message domain, ensure that the script package associated with the event domain has the appropriate
handling configuration for notifications that use the Advanced Message feature. For an example of the code required, see
the "scenario" script package included with the default xMatters installation and associated with the "advanced_
messaging" event domain.
To manage and configure message domains:
1. Click the Development tab.
2. In the Domains menu, click Message Domains.
l
xMatters displays a list of message domains for the current company.
Message domains | 284
Message Domains page

l
To modify an existing message domain, click its name in the list to view its details. For more information,
see "Define message domain details", below.
To delete a message domain, select the check box next to the domains you want to delete, and then click
Remove Selected. Note that you cannot remove a message domain for which scenarios have already been
created. Delete the scenarios first, and then remove the message domain.
To add a new message domain, click the Add New link, and then specify its details.
Define message domain details

You can define or modify the details for message domains on the Message Domain Details page. This is also where you
can define which predicates from the associated event domain will be available when creating scenarios based on this
message domain.
To modify a message domain:
1. On the Message Domains page, click the name of the message domain you want to modify.
2. On the Message Domain Details page, enter the following information into the form:
Message Domain Details
Detail
Description
Name
Name of the message domain. This name is displayed in the Message Domain drop-down list on
the Scenario Details page when creating a scenario, and on the Message Domains page.
Description
Brief description of the message domain; this description appears in the list of message domains
displayed in the "Message Domains for <Company>" table.
Event Domain
Select the Event Domain on which this message domain will base its scenarios. Note that the
Event Domain's associated script package must have the appropriate handling configuration for
notifications that use the Advanced Message feature.
You cannot change the Event Domain for an existing message domain; you must create a new
message domain.
3. Click Continue.
l
xMatters displays the Select Appropriate Predicates page, where you can specify (or exclude) predicates that
are relevant to the scenarios you want to create. For example, if you are creating scenarios intended to assist
in disaster response, and predicates such as Medical Assistance, Location, and Event (Disaster Type) are
available, you will likely want to include these in your message domain. Conversely, for the same domain
Message domains | 285
you may want to exclude potentially irrelevant predicates such as Software Version from the Selected
Predicates list.
l
l
To add predicates to the message domain, select them in the Available Predicates list, and then click Add.
To create a new event domain predicate, click the Add New button to specify the predicate details; when
you are finished, xMatters will create the new predicate on the event domain, and automatically add it to the
Selected Predicates list.
To remove predicates from the message domain, select them in the Selected Predicates list, and then click
Remove.
5. Click Continue.
6. On the Select Appropriate Roles page, click Save.
Note:
The functionality that was controlled by the Roles assigned to a message domain has been replaced by the
Scenario Initiators page, and you can define these permissions when creating a scenario. Only roles that
include scenario in the name can use the Advanced Messaging feature.
7. Click Save.
Custom messaging panels

You can use the xMatters Messaging API to develop custom messaging panels that allow users to inject messages into
xMatters. The out-of-the-box Quick Message panel in the xMatters web user interface is an example of the Messaging
API output.
n
To view this example in the xMatters web user interface, log in as an xMatters administrator, and click the
Messaging tab. xMatters displays the default Quick Message panel (if deployed).
Manage messaging panels

The xMatters Online Developer's Guide includes detailed instructions for using the Messaging API to create custom
messaging panels. The following steps explain how to add the panels to the xMatters web user interface so that users can
access them.
To view and manage custom messaging panels:
2. In the Customization menu, click Messaging Panels.
l
xMatters displays the Messaging Panels page. In a new or default deployment, the Quick Message panel is
the only one listed.
Messaging Panels page
Custom messaging panels | 286

l
To modify an existing panel, click its name in the list to view its details. For more information, see "Define
custom messaging panel details", below.
To remove an existing panel from xMatters, select the check boxes for the panels you want to delete, and
then click Remove Selected. Note that you must have at least one messaging panel configured; you cannot
remove all messaging panels from xMatters.
To change the order in which panels are listed, click Reorder. On the Order Messaging Panels page, select a
panel in the list box and then use the buttons to reorganize the list. When you are finished, click Save to
return to the Messaging Panels page. For more information about reordering messaging panels, see the
following section, "Change the default messaging panel".
To create a new custom messaging panel, click the Add New link, and then specify the Event Domain you
want to associate with the new panel by selecting an event domain from the drop-down list. Click Continue,
and then specify the custom messaging panel details. Click Save, and then specify the roles you want to
have access to the new panel. Click Save to create the panel and return to the Custom Messaging Panels
page.
Change the default messaging panel

When Users click the Messaging tab in a default xMatters deployment, xMatters displays the Quick Message panel. You
can change this behavior in xMatters by reordering the list of panels on the Messaging Panels page.
Whenever a user clicks the Messaging tab (or clicks the Send a Message option available in the Common Tasks menu),
xMatters directs them to the first messaging panel listed on the Messaging Panels page. If you reorder the panels so that
a custom messaging panel is the first one in the list, or remove the other messaging panels from your deployment so that
your custom messaging panel is the only one remaining, then users will automatically be directed to that panel whenever
they send a message.
Define custom messaging panel details

You can define or modify the details for custom messaging panels on the Custom Messaging Panel Details page.
To modify a custom messaging panel:
1. On the Custom Messaging Panels page, click the name of the panel you want to modify.
2. On the Custom Messaging Panel Details page, enter the following information into the form:
Custom Messaging Panel details
Detail
Description
Name
Name of the panel. This name is displayed in the Custom Messaging Panel menu on the Messaging
tab.
Description
Brief description of the custom messaging panel.
Custom messaging panels | 287
Detail
Description
Page URL
Relative path and file name of the custom messaging panel, based on the location of the JSP file. The
path must be relative to the <xMHOME>/webserver/webapps/cocoon/ alarmpoint/jsp/custom
directory.
Examples
Assume that you create a custom messaging panel named MyCustomPanel.jsp:
l
If you copy the JSP file to the <xMHOME>/webserver/webapps/cocoon/alarmpoint/

jsp/custom directory, then you would type MyCustomPanel.jsp in the Page URLfield.
If you copy the JSPfile to a subfolder within the custom directory, such as
<xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/custom/myPages, then you would
type myPages/MyCustomPanel.jsp in the Page URLfield.

For more information about storing the JSP files for custom messaging panels, see the xMatters Online
Developer's Guide.
3. To set or change the roles allowed to use the custom messaging panel, click Assign Roles in the Common Tasks
pane, and then use the Add and Remove buttons to adjust the roles.
4. Click Save to apply the changes and return to the Custom Messaging Panels page.
Custom pages
You can add custom pages to provide a mechanism for users to see external content within the xMatters web user
interface. For example, you could create a list of frequently asked questions that explains how users should interact with
xMatters and your management system, and make it available from within xMatters as a custom page.
To view and manage custom pages:
2. In the Customization menu, click Custom Pages.
l
xMatters displays the Custom Pages page.

l
To modify an existing page, click its name in the Custom Pages list to view its details. For more information,
see "Define custom page details", below.
To remove an existing page from xMatters, select the check boxes for the pages you want to delete, and then
To create a new custom page, click the Add New link and then specify the details as explained in "Define
custom page details", below. Click Continue, and then specify the roles you want to have access to the new
page. Click Save to create the page and return to the Custom Pages page.
Define custom page details

You can define or modify the details for custom pages on the Custom Pages page.
To modify a custom page:
1. On the Custom Pages page, click the name of the custom page you want to modify.
2. On the Custom Page Details page, enter the following information into the form:
Custom pages | 288
Custom Page Details

Detail
Description
Name
Name of the custom page. This name is displayed to users when they view the custom page from
their profile.
Description
Brief description of the custom page.
Page URL
Relative path and file name of the custom page, based on the location of the JSP file. The path
must be relative to the <xMHOME>/webserver/webapps/cocoon/alarmpoint/ directory.
For example, if you created a new FAQ-xMatters.jsp file and stored it in the
<xMHOME>/webserver/webapps/cocoon/alarmpoint/jsp/mypages/ folder, the Page URL
would be:
jsp/mypages/FAQ-xMatters.jsp
3. To set or change the roles allowed to use the custom page, click Assign Roles in the Common Tasks pane, and
then use the Add and Remove buttons to adjust the roles.
4. Click Save to apply the changes and return to the Custom Pages page.
Import data
You can use the xMatters web user interface to import XML spreadsheets of user information or other data directly into
the xMatters database. The Import Data feature provides a quick way to import records without having to enter data into
the system manually, one record at a time.
If you need to import large amounts of data (i.e., in excess of 1,000 records), it is recommended that you use the Data
Synchronization feature. For more information, see "Data Synchronization" on page 377.
You can use the Import Data feature to import the following information from the spreadsheet:
n
User information: User ID, first and last name, site, role, phone ID, and up to five devices, including the service
provider for each device.
Group information: Group names, descriptions, and default time zones.
Group Member information: the users to assign to each group.
The following sections explain how to use the Import Data feature, including how to format the data for import and how
to correct any errors in the imported data.
Note:
In multiple-Company deployments, you can use the Import Data feature to add data to only one Company at a
time.
Format spreadsheets
The Import Data feature loads data into xMatters from Microsoft Office Excel 2003 XML spreadsheets. To load
correctly, each spreadsheet must have a consistent, specific format, as outlined in the following tables.
Persons Sheet
The following table explains the columns and fields on the Persons sheet in the spreadsheet.
Import data | 289
Column
Description
UserID
The User ID for the user you want to add. All entries in this row apply to this User ID.
Operation
Specifies whether you want to Add this Item or Remove this Item. The default is to add the
user.
FirstName
First name of the new user.
LastName
Last name of the new user.
Authentication
To indicate the authentication to use for this user, select one of the following options:
l
Native: uses standard xMatters authentication for this user.
LDAP: uses the users web login ID to authenticate against the LDAP servers.
WebLoginID
The web login ID to assign to this user. If not specified, xMatters assigns a default login ID
using the users first and last names in lower case and separated by a period (i.e.,
firstname.lastname).
WebLoginPwd
The web login password to assign to this user. If not assigned, xMatters assigns the uiser ID for
this user as a default web password.
Note that this field displays the password in clear text, but the Import Data feature stores an
encrypted version in the database.
LDAPDomain
If required, the name of the LDAP domain to authenticate for this user. For more information
about naming LDAP domains, see "LDAP servers" on page 193.
PhoneLoginID
The phone login ID to assign to this user. The contents of this field must be all integers, or the
Import Data operation will return an error.
If no value is specified, the phone credential for this user is not created, and the contents of the
PhoneLoginPwd field are ignored.
PhoneLoginPwd
The phone login Password to assign to this user. The contents of this field must be all integers,
or the Import Data operation will return an error.
If no password is specified, xMatters assigns the PhoneLoginID for this user as a default phone
password.
Site
The site to which the new user should be assigned. The choices available in this drop-down list
are based on the Sites column on the Admin sheet.
Role
The users primary role. The choices available in this drop-down list are based on the roles
column on the Admin sheet.
Import data | 290
Column
Description
DeviceName1-5
The name of each device you want to add for this User. The choices available in these dropdown lists are based on the Devices column on the Admin sheet.
Note that all devices are added with a default 24x7 Timeframe, and you can add up to five
devices for each user.
ServiceProvider1-5
The service providers for each new device you want to add. The choices available in these
drop-down lists are based on the Service Providers column on the Admin sheet.
Note that in the example spreadsheet, Phone Engine should be used for voice phone devices;
either MAPI EMail or SMTP Email should be used for email devices.
DeviceAddress1-5
The address or phone number for each new device.

Note: The format for phone number is the area code in brackets, followed by the phone number.
For example:
(925) 2260300
Extensions and other details, such as country codes, must be entered using the xMatters web
user interface.
Groups Sheet
The following table explains the columns and fields on the Groups sheet in the spreadsheet.
Column
Description
GroupName The name of the new group. All entries in this row apply to this group. Note that all groups are created
with a default 24x7 coverage.
Description
An optional, brief description for this group.
Timezone
The time zone to assign to this group. The choices available in this drop-down list are based on the
Timezones column on the Admin sheet.
Operation
Specifies whether you want to Add this Item or Remove this Item. The default is to add the group.
GroupMembers Sheet
The following table explains the columns and fields on the GroupMembers sheet in the spreadsheet.
Column
Description
GroupName The name of a group to which you want to assign a user. The choices in this drop-down list are based
on the GroupName column on the Groups sheet.
UserID
The user you want to add to the group. The choices in this drop-down list are based on the TargetID
column of the Persons sheet.
Admin Sheet
The following table explains the columns and fields on the Admin sheet in the spreadsheet.
Import data | 291
Column
Description
Sites
The entries in this column determine the choices available in the Site drop-down list for each user
entered on the Persons sheet.
Roles
The entries in this column determine the choices available in the Role drop-down list for each user
entered on the Persons sheet.
Devices
The entries in this column determine the choices available in the DeviceName drop-down lists for each
user entered on the Persons sheet.
Timezones
The entries in this column determine the choices available in the Timezone drop-down list for each
group entered on the Groups sheet.
Service
Providers
The entries in this column determine the choices available in the ServiceProviders drop-down list for
each user entered on the Persons sheet.
Note:
The information on the Admin sheet is not imported into xMatters. The information on the Admin sheet is used
only to populate the fields and drop-down lists on the first three sheets.
Spreadsheet template
xMatters includes a pre-formatted Excel 2003 XML spreadsheet you can use as a template when entering your data. The
template is named DataLoad_Example.xml, and is stored by default in the <xMHOME>\webserver\examples subfolder
of your xMatters installation folder.
Import your data

Once your data is formatted on the Excel 2003 XML spreadsheet, you can import it into the xMatters database using the
web interface.
To import a spreadsheet:
2. In the Configuration area of the Administration menu, click Import Data.
l
Import data | 292
xMatters displays the Import Data page.
Import Data page
3. On the Import Data page, enter the following information into the form:
Import Data page details
Detail
Description
Import
Name and location of the Excel 2003 XML spreadsheet you want to import. Type a path and a
file name into the field, or click Browse to locate a spreadsheet file on your system.
Default Site
Site to which all users will be assigned, unless otherwise specified in the spreadsheet.
Default Role
Role to which all users will be assigned, unless otherwise specified in the spreadsheet.
Default LDAP
Domain
LDAP domain to which all users will be assigned (this setting is available only if there is at least
one LDAPdomain defined).
Default Time Zone Time zone to which all groups will be assigned, unless otherwise specified in the spreadsheet.
Default Observer
Role
Observer role which will be assigned to all groups, unless otherwise specified in the spreadsheet.
4. Click Upload to import the spreadsheet data into xMatters.

l
l
l
xMatters attempts to upload the data and import it into the database. If the import process is successful,
xMatters displays a success message at the top of the Import Data page.
If the import process failed for any reason, xMatters displays a failure message.
You can click the Download Results button to generate and view an Excel 2003 spreadsheet with more
information about the errors.
Import data | 293
Data import with results report
Phone recordings
You can use the Manage Recordings and Add Recordings pages to manage and create voice recordings that are used in
scripts that target voice (phone) devices. For example, you can record specific phrases for specific situations and
locations such as Fire, Flood, Email server down, ... in Building Seven, etc. You can also re-record system voice
pieces such as numbers, months, days of the week, and so on.
Note:
Before creating voice recordings, ensure that a supported Dialogic card has been installed, or that SIP has
been properly configured. To play back VOX recording files within Firefox, you must have Apple QuickTime
installed (Windows Media Player will not play VOX files within Firefox).
Propagation Details
There is no need to propagate your recordings across xMatters nodes manually. If you create or modify recordings in one
of the Recordings subfolders, xMatters automatically propagates the recordings to all nodes. The following section
describes the propagation process in detail.
Phone recordings | 294
Locate your recordings

Voice recordings can be found in two areas on each node that has Phone/SIP installed: a staging area and a runtime area.
The primary purpose of the staging areas is to populate the database after an install. The runtime area is used at runtime
to play voice recordings during notifications.
The staging area is located at:
<xMatters>\node\assets\resources\runtime\common\recordings
The runtime area is located at:

<xMatters>\node\phone-engine\datastore\domains\common\recordings
The runtime area for Global voice recordings is located at:

<xMatters>\node\phone-engine\datastore\global\common\recordings
The runtime area for Company-specific voice recordings is located at

<xMatters>\node\phone-engine\datastore\<org_id>\common\recordings
(Where <org_id> is the Company database identifier available on the Company details page)
When a node starts, the staging area is scanned for voice recordings that are not represented in the database. If a
recording is missing from the database, it is added together with its descriptive recording phrase (if an associated
properties file is present; a recordings properties file has the same name as the recording, except that its postfix extension
is properties instead of vox). Phrase descriptions are located in the english\phrases subdirectory.
At regular time intervals, the database is scanned to ensure that all recordings defined are distributed to the runtime area.
Similarly, the runtime area is scanned for recordings not represented in the database. If new recordings or newer versions
of recordings are detected, the recording is added and the version is updated in the database. The version is represented
by an incremental number in the database and by a suffix appended to the name represented by a dash followed by the
number (for example, the recording severity version 3 is represented in the runtime area by severity-3.vox).
The voice recordings are also regularly scanned for resources that can expire. These represent recorded voice messages
associated with a given event, such as a recorded comment. By default, these recordings expire after 24 hours, after
which they are removed from the database and all runtime areas.
The Resource Broker on each node is responsible for synchronizing voice recording resources between the database and
its local runtime area. To do so, it implements the regular (i.e., time-based) polling functionality described above; and, it
uses a subscription mechanism to ensure resource changes are communicated to all nodes in a timely fashion. Each node
in a multi-node deployment subscribes to resource changes and is informed when the change event occurs, allowing the
node to update its resources. As a result, when communication problems occur or a node is temporarily offline, the timebased synchronization verification acts as a backup to ensure propagation.
Example
Assume that the xMatters web user interface has been used to create a new recording. The recording script is run on the
node creating the recording. After recording is complete, a message is sent to the Resource Broker, which then updates
the database with the change. In turn, Resource Brokers that maintain other nodes are informed and subsequently update
their local resources.
Upgrades (Copying Recordings)

During an upgrade (and for other situations that require copying voice recordings), copying voice recordings to the
runtime area of one of the Phone/SIP installed nodes adds the recordings to the database and distributes them to all other
nodes. However, phrase descriptions manually entered in the runtime area are not added to the database and are therefore
not available to display in the web user interface (note that you can add phrase descriptions manually through the web
user interface).
Alternatively, you can add the recordings to the staging area of one of the nodes and then restart that node. The benefit
of this approach is that if the associated properties files are included, the phrase descriptions are added to the database
and made available for display in the web user interface.
Deleted recordings
When you delete a recording using the web user interface, the recording file is removed, and the file reference in the
database is marked as deleted. If you attempt to restore the recording by manually copying it into the staging area, the
node will automatically remove the file and it will not be propagated to any other nodes in the system. You must re-add
the recording using the web user interface, which will also update the database reference.
Add a recording
You can create a voice recording using a voice device and the xMatters web user interface. Once you have specified the
details of the recording in the web user interface, "Add a recording" on page 296xMatters will call your Voice (Phone)
Device to make the recording. You can also upload an existing recording file (as a new recording, or to overwrite a
recording that is already in xMatters).
You must have an active voice (phone) device to create new recordings. Acceptable formats for uploaded
existing recordings are PCM 8000kHz, 8bit, Mono WAV or m-law 8000kHz, 8bit, Mono VOX.
Note:
To create a recording:
l
To add a recording for a specific company, sign in to xMatters as a Company Administrator, and then click
the Developer tab.
To add a global recording that will be available to all Companies within the xMatters Deployment, log in as
the Super Administrator, and then click the Developer tab.
2. On the Developer tab, click Add Phone Recording.

l
xMatters displays the Add a Phone Recording page:
Add a Phone Recording Page

Phone Recording General Details
Detail
Description
Recording
Phrase
The name of the phrase to be recorded. The name must be fewer than 100 characters long and may
include the following characters: " * < > | \ / ? : %. These characters are translated into %HEX (a percent
sign followed by a hexadecimal number).
Detail
Description
Event
Domain
The event domain to which you want to save the recording (default is ). If you logged in as a Super
Administrator, this option is automatically set to Global.
Description A brief description of the recording (optional).

4. Click Save to create the voice recording file.
l
xMatters automatically assigns the new recording an ID number and adds it to the Phone Recordings page.
5. Click Manage Recordings on the left-hand menu item and locate the new voice recording in the phone recordings
list.
Phone Recordings page
6. Click the ID number link for the recording.
Edit Phone Recording Details page
7. Click Add New.
Add Phone Recordings popup
8. In the Add Phone Recordings pop-up, click the Language drop-down list and select the language for which the
recording is intended (this setting is shown only if the Company uses multiple languages).
l
l
To add an existing recording, click Browse, navigate to the file, and then click Save.
To create a new recording, click the Phone Devices drop-down list to select the phone on which you want
to be called, and then click Initiate Callout. When you receive the call, follow the instructions and record
your message.
Edit Phone Recording Details New Recording Added
10. To listen to a recording, click its associated green and white play icon. Allow several seconds for the playback
application to start and the recording to load. If you do not have a playback application installed, you will
automatically be prompted to install one.
11. To remove the recording in all languages, click Delete Recording; to delete only specific language versions of the
recording, select their associated check boxes, and then click Remove Selected.
Record user names
You can use a similar process to create voice recordings for user names.
To create a recording for a user name:
1. Record the user name as described in Creating a Recording, above (e.g., Mary McBride).
2. Specify the users ID as the Recording Phrase (e.g., mmcbride).
3. Save the file to the following directory:
<xMatters>\node\phone-engine\Datastore\domains\common\recordings\names
Note:
By default, this directory already contains a file called bsmith.vox for default user Bob Smith.
Modify system voice recordings

Each installed language has system recordings for voice pieces such as numbers, letters of the alphabet, months, and days
of the week. In some cases, your organization may want to re-record system recordings (for example, to remain consistent
with a specific corporate 'voice'). These system voice pieces are stored in indexed IPF files (e.g., English_US.ipf) that can
be accessed, played, and re-recorded through the Phone Recorder utility.
Note:
The Phone Recorder utility works only on Windows, using a Dialogic card (i.e., it does not work on SIP). After
a system recording is re-recorded, it is propagated automatically throughout a multi-node deployment.
To re-record system voice recordings:

1. Shut down xMatters.
2. On the Windows machine where the recording utility is installed, start the Phone Recorder application (Start >
All Programs > AlarmPoint Systems > AlarmPoint > Phone Recorder).
3. In the ISI Phone Recorder dialog box, click Options and configure the settings:
n
Select Phone Number, specify the number of the phone to be called for recording, and then click OK.
If you want the utility to automatically play back the recording once you have recorded it, select Playback
Recording.
If you want the utility to automatically remove any extra silence from the beginning and ending of the
recording, select Trim Silence (if you find that the ends of recordings are trimmed too closely, clear this
checkbox).
4. In the ISI Phone Recorder dialog box, navigate to the Recordings folder (default path is AlarmPoint
Systems\AlarmPoint\node\phone-engine\Datastore\common\Recordings).
5. In the Recordings folder, select a language folder (e.g., English US) for the language you want to record.
6. Double-click the IPF file (e.g., English_US.ipf) to display the individual system recording files.
7. Click Connect, and wait for the Phone Recorder to call you.
8. Once you are connected, select a system recording file (e.g., "Seven") that you want to hear or re-record, and then
click Play or Record (note that you can re-record multiple files in series).
9. When you have finished re-recording the desired system files, click OK.
10. Close the Phone Recorder utility.
Manage phone recordings

You can use the Phone Recordings page to edit and re-record phone recordings.
To manage phone recordings:
1. Sign in to xMatters as the default Company Administrator and click the Developer tab.
2. On the Developer menu, click Manage Recordings.
l
xMatters displays the Phone Recordings page, as shown in "Phone recordings" on page 294 above.
3. To reorder the recordings in the list, click a column title.

4. Click the ID number of a recording and do one of the following:
l
Note:
Modify the settings on the Edit Phone Recording Details page, as described in the "Phone Recording
General Details" table, above. Click Save to apply your changes and return to the Phone Recordings page, or
click Reset to discard your changes and start over.
To re-record a recording, click the Phone Devices drop-down list to select the phone on which you want to
be called, and then click Initiate Callout. When you receive the call, follow the instructions and record your
message.
To replace a recording with an existing file, click Browse, navigate to the file, and then click Save.
(Acceptable formats for uploaded existing recordings are PCM 8000kHz, 8bit, Mono WAV or m-law
8000kHz, 8bit, Mono VOX.)
To listen to a recording, click the associated green and white play icon. Allow several seconds for the
playback application to start and the recording to load. If you do not have a playback application installed,
you will automatically be prompted to install one.
When you re-record or replace a recording for a given language, the version number of that recording will
increase by one. The version number of an existing recording is displayed on its Details page.
About reporting
xMatters provides a number of web-viewable reports for system monitoring and troubleshooting. The reports include logs
of incoming messages, actions taken within xMatters, notification status messages, component status, and other
interactions.
The following table summarizes some key terms used in xMatters Reports:
Key Reporting Terms
Term
Description
Incident
Represents one or many events. For example, a management system can use a single incident ID to span
multiple events.
Event
Events originate when the management system sends a message to the integration agent, or when the
event is generated from a messaging panel. Events represent the starting point and highest level of
internal tracking in xMatters. The event ID is assigned within xMatters.
Notification Generated based on events, and can target one or many recipients (users, groups, and devices).
Notifications are delivered based on the users settings (schedules, escalations, overrides, and so on) and
the business logic of the script used to process the event.
Understand how xMatters handles duplicate notifications

xMatters removes - or 'de-duplicates' - multiple notifications for a single event that are targeted at the same user within a
group. For example, assume that UserZ is a member of GroupA and GroupB, and GroupBis a member of GroupA. As a
result, notifications that target GroupA will target UserZ twice: once as a member of GroupA, and again as a member of
GroupB. However, xMatters includes logic that de-duplicates the the additional notification, and UserZ will be notified
only once.
While the latter is true for nested groups with common users, the situation is different when a user is also targeted
individually (i.e., not as part of a group). For example, assume that UserZ is a member of GroupC, and that a notification
targets GroupC as well as UserZ separately. In this case, UserZ will receive two notifications:one as a member of
GroupC, and one as an individually-targeted user.
Access reports
To access xMatters reports, log in to the xMatters web user interface and click the Reports tab. The left menu displays
links to all available reports.
Note:
Permissions control access to xMatters reports. If you do not see a Reports tab when you log in to xMatters,
your Rrole does not include permissions to access reports. If you require access to reports, contact your
xMatters administrator.
Work with reports

The following sections discuss xMatters Report features that will help you improve your queries and work efficiently
with results.
Use % as a search term

You can use a percent symbol (%) as a search term in xMatters reports, as summarized in the following table.
About reporting | 302
Note:
Wild cards are not supported in the type-ahead style Search fields, such as the feature on the events report.
Search reports using the percent sign as a search term

Search Term
Returns
filter_value
Items containing filter_value. When no percent symbol is present, xMatters searches for items
containing filter_value.
filter_value%
Items starting with filter_value.
%filter_value
Items ending with filter_value.
%filter_value%
Items containing filter_value. This returns the same result as not using a percent symbol.
All items.
%%
All items.
<nothing>
All items (i.e., leaving the search field blank returns all items).
Note:
Search terms in xMatters Reports are case-sensitive.
Sort and save results

The following sections describe reporting features that allow you to sort and navigate results quickly.
Reorder column entries
You can reorder report results by clicking on column headings. An arrow next to the column heading indicates whether
the results are sorted in ascending or descending order.
Use column fields
Some columns include a field below the column heading. Type text into this field and press the Enter key to narrow the
report results to rows containing columns that include the text entered into the field. For example, typing 170276 in a
reports Event column field and pressing Enter returns only those rows that contains 170276 in the Event column.
You can also use the field in any of the Detail columns to return events related to a specific predicate. Note that the
column fields are case-insensitive and work on a 'contains' basis: partial matches are included in the list of returned
events.
Use pagination
On some reports, query results that exceed the specified Results per page setting display page navigation buttons below
the results table. Click a page number or an arrow button to move through the results quickly.
Choose runtime and archive data

Some reports allow you to search runtime or archive data. In general, whether system data is considered runtime or
archive is controlled by two features available to the xMatters super administrator:
n
Schedule Jobs: for details, see "Schedule Jobs" on page 215
Clear Runtime / History:for details, see "Clear runtime and historical data" on page 219
For example, the default Schedule Jobs settings specify that data is runtime for the first 7 days it exists, archive for the
next 21 days, and deleted after a total of 28 days.
Note:
This setting also appears on the Past Alerts and Past Groups Alerts search pages.
Set refresh delay

Some reports that provide current information offer a periodic screen refresh functionality. After setting the Refresh
Delay, click Start. To change the Refresh Delay, select a new delay, and then click Save Change (or Change). If you
have set a very fast refresh rate, you may need to click Stop before changing the Refresh Delay.
Note:
Saving the change to the Refresh Delay rate resets the delay only for while you are on the page. If you browse
to another page, the rate is no longer saved.
Export report results to a spreadsheet

Some results pages for xMatters Reports include an Export Excel Document button that allows you to save report
results as a Microsoft Excel document.
Terminate, resume and suspend events

Some reports allow you to stop events that are currently in progress. To terminate one or more events, select the check
boxes next to the Events you want to end, and then click Kill Selected.
Note:
Any active notifications associated with a terminated Event will be removed.
In some situations, you may want to pause an event manually (e.g., to add to or change it, to allow certain Users to
respond, to check for false alarms, etc.). You can use the Suspend Selected and Resume Selected button (on the available
reports) to suspend and resume events. For more details about what happens when you suspend and resume events, see
About Suspending and Resuming Events, below.
To suspend one or more events, select the check boxes next to the events you want to suspend, click Suspend Selected,
and then click OK (the Status column will indicate a state of Suspended when the page is refreshed).
Similarly, to resume previously suspended events, select the check boxes next to the suspended events you want to
resume, click Resume Selected, and then click OK (the Status column will indicate a state of In Progress when the
page is refreshed).
When an Event is suspended, no new work is sent to device engines for processing. However, notifications that have
already been sent to a device engine will be processed. All message responses that occur after an event is suspended will
still be valid and executed.
When an event is resumed, processing will continue from the point at which it was initially suspended. However, the
current date and time will be used for processing. Note that if a suspended event is terminated by another application or
mechanism (e.g., via a Management System), resuming the event will not result in any further activity.
Example: Suspend an event
Ten users are notified via a single event, and then the event is immediately suspended. If an email notification was
submitted to a user prior to the event being suspended, and the user response is CLEAR or some other job control, the
requested activity will still be executed.
Example:Resume an event
An event causes Group1 (available 9am 4pm on business days) to be notified at 3pm, and then the event is
immediately suspended. The event is resumed at 8:30pm. No additional notification will occur until the next business
day at 9am.
DTMF notifications
The DTMF protocol cannot relay failure messages back to xMatters. As a result, if a DTMF message fails for any reason,
xMatters will not recognize the failure. For reporting purposes, this means that all DTMF notifications xMatters sends are
considered successful regardless of their outcome.
Available reports
xMatters includes many predefined reports with search criteria designed to help administrators and other users understand
the applications runtime status, historical performance and auditing capabilities. Users permission settings control their
access to reports.
The following table summarizes the available reports and provides a brief description of each:
Available Reports
Category
Report
Description
Activity
Events Activity
Returns events submitted to the system.
Events For User
Returns event details for a specific user based on a date and time range.
Events For Group
Returns event details for a specific group based on a date and time range.
Submitted Notifications
Returns all notifications sent within a specified date and time range.
Live Notifications
Returns notifications that are currently live in the system, at a specified

refresh rate (in seconds).
Company
Reports
System
Reports
Notification Throughput This report returns all notifications the system has submitted, sent, and
Details
received based on a date and time range.
Domain Summary
Returns all notifications the system has delivered based on a date and
time range, and sorted by the specified event domain.
Synchronization Report
Returns the results of data synchronizations based on a date and time

range.
Application Audit
Report
Returns any additions, deletions, or changes to the specified system item,

based on a date and time range.
Low-Use Users
Returns information on how many "low-use" users were active in the

system for a specified period of time. This report assists administrators in
complying with their xMatters licensing agreements.
Component Status
Returns the status of all xMatters components, at a specified refresh rate

(in seconds). By default, this report is available only to xMatters Super
Administrators.
Node Network Statistics Returns data regarding the number of network interruptions, application
layer latency between nodes, and whether the network connection was
symmetric for a specified period. By default, this Report is available only
to xMatters Super Administrators.
Audit
Security Audit Report
Returns login attempts (success/failure) by User ID and Web Login based

on a date and time range.
Category
Performance
Report
Description
Web Service Audit

Report
Returns xMatters web services activity, including Audit Time, WS User,

Status, Method Name, Client Timestamp. Client IP, and Client OS user,
based on a date and time range.
For more information about Performance Reports, see the xMatters user guide
Group Performance
Report
The Group Performance Report allows Administrators and Group

Supervisors to view statistics about how recipients (User, Groups,
Dynamic Teams, etc.) have responded to notifications. The report can be
used to identify recipients that are not performing as expected.
User Performance
Report
The User Performance Report allows Administrators and Supervisors to

view statistics about how Users they supervise have responded to
notifications. The report can be used to identify Users that are not
performing as expected.
Trending Reports
(Average Response
Times)
The Trending Reports (available from within the Performance Reports) for
Groups and Users allow Administrators and Supervisors to view statistics
about how their Groups and supervised Users have responded to
notifications over a specified period of time. The reports, which provide a
breakdown of average response times, can be used to identify trends in
responding performance over time.
In the sections that follow, reports are sorted and ordered by their web user interface menu category.
Reports in multiple-company deployments

The following reports are company-specific, and will display only data that is relevant to the current company in a
multiple-company deployment:
n
All Event reports (Events Activity, Events for User, Events for Group)
Live Notifications
Domain Summary
Synchronization Report
Application Audit Report
Low-Use User Report
Security Audit Report
Activity reports
The activity reports allow you to analyze events submitted to the system and notifications that the system generates.
You can also drill down and view detailed reports on key criteria (for more information, see "Event Details Reports" on
page 311).
Note:
The activity reports include a Kill Selected button that allows you to select currently live events and terminate
them. If the event is not live (or you do not have the required Permissions), no selection box appears.
The activity reports are:
Events Activity
Event Activity for User
Event Activity for Group
Live Notifications
Event Activity Report

The Event Activity Report returns Events submitted to the system based on a specified date range.
This report is the typical entry point when searching for data within the system, and is particularly useful when
attempting to find a specific Event or Incident ID within a certain time period. For example, you could use an Events
Activity Report to determine what happened with a particular management system ticket (based on an Incident ID), and
then use the links within the Report to branch into more detailed information about specific notifications or Events. You
can also suspend and resume events via this report.
Note:
Due to the way xMatters resolves Groups (i.e., calculating schedules for Groups within Groups), the numbers
on the Event Activity Report may not be accurate while an event is being processed.
To run an Events Activity Report:

1. Log in as a Company Administrator, and click the Reports tab.
2. On the Reports menu, click Events Activity.
3. Enter a date range in the Start Date and End Date.
l
To limit the Report results to a particular time of day, enter the hours to include in the Start Time and End
Time fields.
4. To specify the number of results to display on each page of the Report, select a number from the Results per page
drop-down list.
5. Click the Select From drop-down list to specify the data type on which to search (for details, see "Choose runtime
and archive data" on page 303).
6. Click Search to generate the Report.
l
The following table describes the information that appears in each column:
Event Activity Report Columns

Column
Displays
Time
Time at which the Event was submitted to the system.
Incident
Identifier that allows an Incident to be tracked. This ID is generated or assigned by the management
system or originator of the incident; when no ID is provided, xMatters assigns an ID. One Incident
can have many associated Events.
Event
xMatters-generated unique identifier for this Event.
Domain
The Event Domain targeted by the Event.
Sender
If the message originates from the xMatters web user interface, the Sender is the User who is logged
in when the message is sent. If the message comes from a Java Client, the Sender is the Agent ID
for that Java Client.
Status
Current status of the Event.
Notification
Summary
Link to notification details. For more information, see "Event Details Reports" on page 311.
Event Summary
Link to Event details. For more information, see "Event Details Reports" on page 311.
Exhaustive
Link to the Exhaustive summary. For more information, see "Event Details Reports" on page 311.
Detail 1-3
Custom information specified with a predefined system token or predicate. These columns are
displayed only if they are populated and marked as "Important"on the Event Domain Details page;
for more information, see "Define predicates" on page 264.
7. Refine or organize your Report results using the methods described in "Work with reports" on page 302.
Event Activity for User Report

The Event Activity for User Report returns Event details for a specific User based on a date and time range.
Like Event Activity, this Report is another entry point into the system when searching for information about a particular
User or Event, but can be especially useful when you do not know a specific Event or Incident ID.
To run an Events for User Report:
2. On the Reports menu, click Events for User.
l
xMatters displays the Find User for Event Report page.
3. Use the search feature on the Find User for Event Report page to locate the User for whom you want to generate a
Report.
Note:
This search page is identical to the Find Users page described in detail in the Supervising Users and Groups
chapter of the xMatters user guide.
4. Click the name of a User to display the Events for User Report page.
l
The following table describes the information that appears in each column.
Event Activity for User Report Columns

Column
Displays
Time
Time the Event was submitted to the system.
Incident
system or originator of the incident; when no ID is provided, xMatters assigns an ID. One Incident can
have many associated Events.
Event
Domain
Sender
If the message originates from the xMatters web user interface, the Sender is the User who is logged in
when the message is sent. If the message comes from a Java Client, the Sender is the Agent ID for that
Java Client.
Column
Displays
Status
Notification Link to notification details. For more information, see "Event Details Reports" on page 311.
Summary
Event
Summary
Exhaustive
Link to the Exhaustive summary. For more information, see "Event Details Reports" on page 311
Detail 1-3
Custom information specified with a predefined system token. These columns are displayed only if they
are populated.
Event Activity for Group Report

This report returns Event details for a specific Group based on a date and time range.
Like Event Activity, this Report is another entry point into the system when searching for information about a particular
Group or Event, but can be especially useful when you do not know a specific Event or Incident ID.
To run an Events for Group Report:
2. On the Reports menu, click Events for Group.
l
xMatters displays the Find Group for Event Report page.
3. Use the search feature on the Find Group for Event Report page to locate the Group for which you want to
generate a Report.
Note:
This search page is identical to the Find Groups page described in detail in the Supervising Users and
Groups chapter of the xMatters user guide.
4. Click on the name of a Group to display the Events for Group Report page as illustrated above.
l
The following table describes the information that appears in each column.
Event Activity for Group Report Columns

Column
Displays
Time
Incident
system or originator of the incident; when no ID is provided, xMatters assigns an ID. One Incident can
have many associated Events.
Event
Domain
Sender
If the message originates from the xMatters web user interface, the Sender is the User who is logged in
when the message is sent. If the message comes from a Java Client, the Sender is the Agent ID for that
Java Client.
Status
Notification Link to notification details. For more information, see "Event Details Reports" on page 311.
Summary
Event
Summary
Exhaustive
Link to the Exhaustive summary. For more information, see "Event Details Reports" on page 311
Detail 1-3
Custom information specified with a predefined system token. These columns are displayed only if they
are populated.
To specify the details displayed in these columns, predicates must be defined as Important when
created in an Event Domain. For more information, see "Define event domain details" on page 262.
Event Details Reports

The Events Activity, Events for User, and Events for Group Reports include links that provide access to more detailed
information, as described in the following sections.
Event Summary
Click link in the Event Summary column to display the Event Summary Report for the related entry.
Event Summary
For a description of the values in the Event Summary's "Details" column, see "Notification statuses", below.
Note:
If you receive a The notification is in process, please try again later error message, wait a few moments and
then refresh your browser window. The error is transient, and the report will display once the notification has
been resolved.
Event Summary Report Terms

Term
Description
# of people to contact
Total number of Users who might be contacted for the Event, including Groups within
Groups and Temporary Replacements. Some Users included in this number may not be
contacted for this event because their schedules do not match the notification period.
# failed
Number of Users that xMatters attempted to contact, but could not. This count is based
on results from the Device Engines. If, for example, a Paging Engine has failed, this
count will be affected. Additionally, Users with no active Devices configured, and Users
with Devices with Timeframes that do not fall within Coverages typically contribute to
this value
Term
Description
# success 1-way
Number of notifications successfully delivered to Users.
# success 2-way
Number of notifications successfully delivered to Users who successfully responded.

Note that each two-way success reduces the success 1-way count by one (success 2-way
has reporting priority). Additionally, Users responding via call-in or web browser
contribute to this value.
# not yet notified
Number of Users in # of people to contact figure that have not been sent a notification.
You can use the Replay Event link on the Event Summary Report to run an Event again; for more information, see
"Replaying an Event" on page 316.
Notification Summary
Click link in the Notification Summary column to display the Notification Summary Page for the related Event.
For a description of the values in the Notification Status's "Status" column, see "Notification statuses", below.
Exhaustive Report
Click link in the Exhaustive column to display the Exhaustive Report for the related Event.
Exhaustive Report
Note:
If you receive a The notification is in process, please try again later error message, wait a few moments and
then refresh your browser window. The error is transient, and the report will display once the notification has
been resolved.
The Exhaustive Report displays each key transaction in the formation, delivery, and termination of the Event. By default,
the report displays a hierarchical view that can be toggled with a chronological view by clicking the Show
Chronological (or Show Hierarchical) button.
Notification statuses
The "Status"column on the Notification Summary report and the "Details"column on the Event Summary report indicate
the changing state of each notification attempt. The following table identifies and explains the possible values for these
columns.
Notification Summary Statuses
Value
Description
CANCELLED
The notification was canceled or removed by the system.
NOTIFYING
The notification is currently in progress.
DELIVERED
The notification has been delivered to a User's Device.
DEVICE_DELIVERED
The notification has been delivered directly to a targeted Device; i.e., the notification was
sent to the Device directly and not to the User.
Value
Description
DEVICE_READ
The notification has been delivered to a Device and read by the User; note that this status
is available only on Devices and service providers capable of sending a "message read"
status back to the system.
RESPONDED
The User has responded to the notification.
FAILED
The notification could not be delivered to the Device; for more information, consult the
xMatters logs.
HAS_REPLACEMENT
The targeted User has a scheduled Temporary Replacement who will be notified on their
behalf.
NOT_DELIVERED
The notification was not delivered to the User or Device.
Replaying an Event
The Replay Event link on the Event Summary report allows you to launch an existing event again. This feature aids in
troubleshooting notifications or diagnosing delivery problems.
You can modify some event details before replaying it; the properties displayed on the Replay Event page depend on
the original event and event domain.
Note:
When replaying an event, xMatters treats the replay as a new, separate event, and will notify all recipients
using their devices; ensure that you do not accidentally duplicate a real emergency.
To replay an Event:
1. Click the Reports tab, and then click the event that you want to replay.
2. On the Event Report Summary page, click the Replay Event link.
l
xMatters displays the Replay Event page.
Replay Event page
3. On the Replay Event page, in the New Value column, modify the values to match the properties you want to
inject when replaying the event.
4. Click Replay to create a new event using the specified values.
Modify event properties
The Replay Event page displays a list of event properties you can modify before replaying the event, including the value
for each property on the original event.
The properties available to modify depend on the details of the Event you are replaying. For example, if you are
replaying an event based on a message sent from the default Quick Message panel, the Replay Event page would
include the message details, a recipients list, the name of the messaging panel, the name of the sender, etc.
Properties that can contain multiple values, such as a recipients list, have a related property that includes the term
"delimiter". These properties identify the symbol or punctuation mark (the default value is a comma) used to separate
items in the list.
Submitted Notifications Report

The Submitted Notifications Report displays all of the notifications that were sent during a specified date and time
range.
This Report is helpful if you are trying to find specific content that has been sent out to a Device. It also allows you to
narrow down the content to a specific Event. For example, if a User is trying to understand why they received a message
containing certain content, you can use the Submitted Notifications Report to track the notification back to the
originating Event, which will then allow you to view the detailed links.
To generate a Submitted Notifications Report:
2. On the Reports menu, click Submitted Notifications.
l
Time fields.
drop-down list.
5. Click the Select From drop-down list to specify the data type on which to search (for details, see "Choose runtime
and archive data" on page 303).
l
The following table describes the information that appears in each column:
Submitted Notifications Report Columns

Column
Displays
Time
Column
Displays
Incident
Identifier that allows an Incident to be tracked. This ID is generated or assigned by the management system
or originator of the incident; when no ID is provided, xMatters assigns an ID. One Incident can have many
associated Events. Click the link in this column to generate an Event Activity Report on this Incident ID.
Event
xMatters-generated unique identifier for this Event. Click the link in this column to generate an Event
Activity Report on this Event ID.
Domain
Recipient Identifies the recipient of the notification. Note that terms in the filtering field are applied only to User IDs.
Message
Displays the text or subject of the notification message.
Live Notifications Report

The Live Notifications Report returns all currently active notifications in the system. Note that in a multi-Company
deployment, Super Administrators have access to the Total Live Notifications Report.
This report can be used to monitor system activity during periods of load. The report contains data when the system is
busy creating and delivering notifications. The lifecycle of a Device notification is as follows (displayed in the Status
column of the report):
CREATED > SERVICEABLE > DISPATCHING > DELIVERED or FAILED
For Voice Device notifications the lifecycle is as follows:
CREATED > SERVICEABLE > DISPATCHING > PROCESSING > DELIVERED or FAILED
Note:
The final states of DELIVERED and FAILED are not displayed in the Status column of the Live Notifications
Report.
For two-way network paging protocols (e.g., SNPP and WCTP), the report displays notifications created for querying the
paging provider for status updates and responses. The lifecycle of these notification queries is as follows:
CREATED > QUERY_PROVIDER > DISPATCHING >DELIVERED_DEVICE or DEVICE_ READ or
RESPONDED
Note:
The final states of DEVICE_READ and RESPONDED are not displayed in the Status column of the Live
Notifications Report for two-way paging protocol notifications.
To generate a Live Notifications Report:

1. Log in as a Company Administrator or Super Administrator, and click the Reports tab.
2. On the Reports menu, click Live Notifications.
l
If you are logged in as a Super Administrator, on the System Reports menu, click Total Live Notifications.
drop-down list.
4. Click Start to generate the Report.
l
If you are logged in as a Super Administrator, click the name of a Company to view the live notifications for
that Company.
The following table describes the information that appears in each column of the report:
Live Notifications Report Columns

Column
Displays
Notification
Unique identifier for the notification.
Person Info
User to whom the notification was sent.
Device Info
Device to which the notification was sent.
Status
Current status of the notification (see table below for explanations).
Time Created
Date and time the system generated the notification.
Retries
Number of times the system has attempted to send the notification after sending the original
notification.
Note:
Two-way pager notifications sent via SCTP and SNPP appear in the Live Notifications Report for one hour
after sending. This is due to the mechanism used by these protocols to query for delivery updates and replies.
The following table explains the entries in the Status column of the Live Notifications Report:
Live Notifications Report Status Column Entries
Status Entry
Description
CREATED
Live notification has been generated.
SUSPENDED
Notification has been suspended due to an out-of-coverage situation.
Status Entry
Description
SERVICEABLE
Notification is awaiting processing by a Device Engine.
RETRY
Notification has been attempted but could not be delivered. An internal event will occur
in the future to requeue this notification for delivery.
PROCESSING
Notification is being processed by a Voice Device Engine.
QUERY_PROVIDER
Similar to the SERVICEABLE, but notifications in this state are waiting for Device
Engines to query a provider for delivery status (i.e., not waiting to send out a notification,
as in the SERVICEABLE state).
DELIVERED_
PROVIDER
Notification has been successfully delivered to a provider.
QUEUED_PROVIDER
Notification has been successfully delivered to a provider, but is currently queued at the
provider awaiting delivery to a Device. (note that this status applies only to two-way
paging protocols).
DELIVERED_DEVICE
Notification has been successfully delivered to a Device (note that this status applies only
to two-way paging protocols).
VIEWED_DEVICE
Notification has been successfully delivered to a Device and the notification has been
viewed (note that this status applies only to two-way paging protocols).
RECEIVED_
RESPONSE
A response was received from the recipient of the notification.
DISPATCHING
Notification is being sent to a Device Engine. Notifications are expected to transition from
this state within a configured threshold (default is 5 minutes); otherwise, they will be
moved back to SERVICEABLE for requeue.
Company reports
By default, only company administrators have access to the company reports. In multiple-Company deployments, Super
Administrators can access the Notification Throughput Report for all Companies in the system.
Company reports include the following:
n
Notification Throughput Details
Domain Summary
Synchronization
Application Audit
Low-Use User Report
Notification Throughput Details Report

This report returns all notifications the system has submitted, sent, and received based on a date and time range.
Notification Throughput Report
The Notification Throughput Report provides an overview of the Events and notifications for a Company handled by the
system for the specified time. This Report is useful for determining prime load times and how much the system is
handling at different times.
Super Administrators can view a Notification Throughput Report that includes all Companies in xMatters.
To generate a Notification Throughput Details Report:
1. Log in to xMatters as a Company Administrator or Super Administrator, and click the Reports tab.
2. On the Reports menu, click Notification Throughput Details.
l
If you are logged in as a Super Administrator, on the System Reports menu, click Notification Throughput.

l
Time fields.
drop-down list.
l
If you are logged in as a Super Administrator, click the name of a Company to view specific details about its
notification throughput.
Total Events Submitted Table
The Total Events Submitted table breaks down all of the submitted events into their respective sources as follows:
n
If the Event was injected by the integration agent, the Source column will contain the Event Domain and the
Integration Service name, separated by a pipe; e.g.: "default|helpdesk"
If the Event was injected by the APAgent (i.e., the Java Client), the Source column contains only the Event
Domain name; e.g.: "company_a"
If the Event was injected by a message panel (including Custom Messaging Panels), the Source column contains
the User ID of the User who sent the message; e.g., "bsmith"
If the Event was injected via web services, the Source column contains the User ID of the web service user used to
inject the event; e.g., "IA_User"
Domain summary report

This report returns all notifications the system has delivered based on a date and time range, and sorted by the specified
Event Domain.
Domain Summary Report
Domain Summary Reports are useful for knowing what each part of the system is being used in a specific time period.
For example, if you wanted to determine the relative load that the ticketing system is putting through the system as
compared to the xMatters Messaging component, you could generate a Domain Summary Report to review the
information.
Assuming that they are on the specified event domain and within the specified date range, live notifications are included
in the Total Notifications Sent column:
n
After a notification has been sent to the Device's Service Provider
When xMatters has received a reply from the Device
When an xMatters business script delinks or delivers a notification (i.e., when the script triggers a DELIVEREDor
DELINKED state)
When the event or notification is terminated
To generate a Domain Summary Report:

2. On the Reports menu, click Domain Summary.
l
Time fields.

5. To view domain results itemized by Device and Protocol, click the plus (+) sign associated with the domain.
Domain Summary Report Expanded
Synchronization report
This report returns the results of data synchronization processes run on the deployment.
Note:
For more information about the Data Synchronization feature, see "Data Synchronization" on page 377.
Synchronization Report Results
To generate a Synchronization Report:

2. On the Reports menu, click Synchronization Report.
l
The report is automatically generated.
3. Click the link of a specific data synchronization run to display success/failure summaries for each table.
Synchronization Report Success/Failure by Table
4. If failures are displayed, you can click the related Synchronizer Name link to display the Synchronization Failure
Summary for that row entry in the table.
Interpret the synchronization report

The following sections explain how to interpret the results returned in the Report.
A SUCCESSresult in the Final Status column of the Synchronization Report indicates that the Synchronization ran
successfully, but does not preclude the failure of individual objects. A FAILURE result indicates one of the following
errors:
n
The Synchronization process was halted before it could complete.
The Synchronization process exceeded the configured number of acceptable failures.
An invalid User was specified in the configuration file.
No objects were specified for processing in the configuration file.
Similarly, a SUCCESS result in a Synchronization Table Report does not mean that there were no failures of individual
objects, while a FAILURE result indicates one of the following errors:
n
The Synchronization process was halted before it could complete.
The Synchronization process exceeded the configured number of acceptable failures.
Failure Counts
The Failure Count result indicates the number of rows (objects) that failed to synchronize with xMatters; click the link
in the Synchronizer Name column to view more details on a failure.
Failure counts may be incremented by the following errors:
1. Missing a value for a required field.
l
Note:
Forexample, if IS_EXTERNALLY_OWNEDis null (or not Yor Nfor an Add or Update operation),
SITENAMEis null for DS_SITES, or WEB_LOGIN_TYPEis null for DS_USERS
For a comprehensive list of required fields, refer to "Data Synchronization" on page 377.
2. Attempting to remove objects that could not be removed.

l
For example, attempting to remove the last supervisor of a Group, or removing the last active Device that is
marked as the default Device for a User. (These rules are the same as those enforced in the web user
interface.)
3. Attempting to add objects to a missing or invalid parent.

l
For example, if the User referenced by DS_USER_CUSTOM_VALUESis missing, or if the Event Domain
referenced by DS_EVENT_DOMAIN_PREDICATEis invalid.
4. Adding or updating an object to have a duplicated name or ID.

l
For example, if the SITENAMEin DS_SITES,the USER_ID if DS_USERS, or the DEVICE_NAME in any
of the DS_%_DEVICES already exists in xMatters.
5. Adding or updating an object to have a property that is invalid or references something that does not exist.
l
For example, if the GROUP_KEY in DS_TEAMSdoes not reference an existing Group, or if the SITE_
LANGUAGE or SITE_TIMEZONE in DS_SITES does not reference existing values in xMatters.
6. Attempting to update a Custom Field from one type to another.

7. Using an invalid format for the date, time, and day of week.
8. Using an invalid value for WEB_LOGIN_TYPEin DS_USERS.
9. Using an invalid value for PREDICATE_TYPE in DS_EVENT_DOMAIN_PREDICATES.
10. Using an invalid MEMBER_SUB_TYPEin DS_TEAM_MEMBERSHIPS.
11. Using an invalid CUSTOM_FIELD_TYPEin DS_CUSTOM_FIELDS.
12. Using an invalid DT_OWNING_DEVICE in DS_DEVICE_TIMEFRAMES.
13. Using an invalid COUNTRY_CODEin DS_TEXT_PHONE_DEVICES.
14. Attempting to export a Dynamic Team.
Note that removing a non-existant object is considered a success; this includes the removal of Person Supervisors for a
non-existant User.
Partial Failure Counts
The Partial Failure Count indicates that an object may have synchronized successfully, but a property of the object has
encountered an error.
Partial failures may be caused by the following:
1. Including an invalid element in a comma-delimited list.
l
For example, if a User specified in the SUPERVISOR_LISTfield in DS_GROUPS is missing or has an

ineligible Role, or if a Role specified in the OBSERVER_LIST does not exist in xMatters.
2. Including an invalid element in a joined table.

l
For example, if an attribute in the DS_USER_JOIN_ATTRIBUTES table or an attribute in the DS_

CUSTOM_FIELD_JOIN_VALUES table does not exist in xMatters.
3. Including a team member in the DS_TEAM_MEMBERSHIPStable who does not exist in xMatters.
Application audit report

The application audit report returns any additions, deletions, or changes to the specified system item, based on a date
and time range.
Sample Application Audit Report (based on Node Component activity)

Note:
The application audit report is an exhaustive and comprehensive accounting of the behavior of users within
the system. As a result, the level of detail can be overwhelming for anyone unfamiliar with the xMatters data
model, and therefore difficult to interpret. It is recommended that you contact xMatters Support and
Professional Services to assist you when conducting an audit of this nature.
To generate an application audit report:

2. On the Reports menu, click Application Audit Report.
l
To limit the report results to a specific time of day, enter the hours to include in the Start Time and End
Time fields.
4. To specify the number of results to display on each page of the report, select a number from the Results per page
drop-down list.
5. In the Select Audit Report drop-down list, select the component for which you want to generate the report.
6. Click Search to generate the report.
7. Refine or organize your results using the methods described in "Work with reports" on page 302.
Low-use user report

This report is intended to help xMatters customers comply with their licensing agreements by identifying how many
users qualify as "low use"; that is, users who have limited access to the resources included in an xMatters deployment.
Low-use user report
Depending on a customer's licensing agreements, a low-use user is defined by one of the following metrics:
n
Notification:this method sets a maximum threshold for the number of notifications a user can receive and still
qualify as a low-use user. For example, a licensing agreement might define a low-use user as any user that is
targeted by fewer than 5 notifications per quarter (a three-month period).
Response: this method sets a maximum threshold for the number of replies a user sends to xMatters in response to
a notification. For example, a licensing agreement might define a low-use user as any user that responds to 2 or
fewer notifications within a quarter.
Device:this method sets a maximum threshold for the number of device types on which a user can receive
notifications. For example, a licensing agreement might define a low-use user as any user that received
notifications on only one device type; a user who received notifications on two separate email addresses would
qualify as a low-use User, while a user who received notifications via email and a phone would not.
To generate a low-use user report:

2. On the Reports menu, click Low-Use User.
3. Using the Start Month, Start Year, End Month, and End Year fields, specify the time period for which you want
to generate the report.
4. In the Report Type drop-down list, select one of the following metrics to specify which one you want to use to
identify low-use users:
l
Notification
Response
Device
5. In the Threshold field, type the maximum number of notifications, responses, or device types a user can have and
still be considered a low-use User. This value must be a positive integer.
6. Click Generate to generate the report.
7. Click Export to save the report to a spreadsheet (Microsoft Excel) file.
Note:
This report is capable of generating low-use user statistics only from the time at which this feature was
enabled (i.e., the date of upgrade to xMatters 4.1). Attempting to generate a report that predates that date will
result in inaccuracies.
System reports
By default, only the xMatters Administrator has access to the system reports. Note that for Super Administrators, the
Notifications and Throughput History Reports are considered System Reports. For details on these reports, see
"Notification Throughput Details Report" on page 321 and "Live Notifications Report" on page 319, respectively.
Component status report

This report returns the status of all xMatters components at a specified refresh rate (in seconds).
Component Status Summary Report
Super Administrators can also use the Component Status Report to view any integration agents that are providing
integration services to a company-specific event domain.
To generate a Component Status Summary Report:
1. Log in to xMatters as a Super Administrator, and click the Reports tab.
l
xMatters displays the Component Status Summary page as shown above.
2. To view an itemized list of component, click the plus (+) sign.
System reports | 329
Itemized Component Status Summary Report
Node network statistics report

The Node Network Statistics Report provides the ability to assess and troubleshoot the performance of node
communication over a specified time period. This report returns data regarding the number of network interruptions,
application layer latency between nodes, and whether the network connection was symmetric for a specified period.
Note:
The latency data captured in this report refers to application layer latency, which can be unrelated to network
latency. Additionally, to avoid reporting on the application layer latency associated with server startup, data
collection begins after the node has started.
By default, this report is available only to xMatters Super Administrators, who can also configure data parameters for this
report(see the Node Network Monitor settings described in "Global Configuration" on page 198).
Report Purpose
The purpose of this report is diagnostic: it is meant to provide a visual representation of historical node network
communication performance. It is not intended for the real-time monitoring of node network communication.
Further, this report is typically used by xMatters support to evaluate and assist with troubleshooting network
communication issues. If you are experiencing node network issues, you may be asked to supply xMatters support with a
screenshot of this report.
If it is suspected that the system is experiencing network layer issues, it is recommended that you use network
troubleshooting utilities or applications (e.g., Ping, Telnet, netstat) to resolve them.
To generate the node network statistics report:
1. Log in as a Super Administrator, and click the Reports tab.
2. On the Reports menu, click Node Network Statistics.
System reports | 330

l
To limit the report results to a particular time of day, enter the hours to include in the Start Time and End
Time fields.
Node Network Statistics Report
Audit reports
You can use the audit configuration page to enable and disable security and web services auditing.
To specify audit settings:
1. Log in as a company administrator, and click the Admin tab.
2. On the Administration menu, click Audit.
3. To disable auditing, clear the Security Audit Enabled check box, and then click Save (by default, auditing is
enabled).
Note:
To specify how long the system should retain Security Audit data, use the settings on the Schedule Jobs page.
For more information, see "Schedule Jobs" on page 215.

This report returns company login attempts (success/failure) by user ID and web login based on a date and time range.
Audit reports | 331
To generate a security audit report:

2. On the Reports menu, click Security Audit Report.
l
Time fields.
drop-down list.
6. Refine or organize your report results using the methods described in "Work with reports" on page 302.

This report returns xMatters web services activity based on a time and date range.
Audit reports | 332
To generate a web service audit report:

2. On the Reports menu, click Web Service Audit Report.
l
Time fields.
drop-down list.
6. Refine or organize your results using the methods described in "Work with reports" on page 302.
Audit reports | 333
334 |
This chapter covers advanced or special xMatters administration topics and is intended for experienced administrators or
technical personnel. It is recommended that you consult with your xMatters Technical or Professional Services
representative to plan and implement advanced deployment options.
Disaster Recovery Deployment Considerations

This section describes the recommended deployment for an xMatters enterprise installation consisting of multiple sites,
configured with Disaster Recovery, and the procedures required for moving the deployment from the primary site to the
Disaster Recovery site and back.
Overview
A typical xMatters enterprise Disaster Recovery deployment consists of the following:
Primary site:
n
xMatters application servers (one, two, or three)
xMatters web servers (one or more)
xMatters database Server (either Oracle or SQL Server)
xMatters notification servers (zero or more)
Java Clients or xMatters integration agents
Disaster Recovery site:

n
xMatters Disaster Recovery Application Servers (one, two, or three)
xMatters Disaster Recovery Web Servers (one or more)
xMatters Disaster Recovery Database Server (either Oracle or SQL Server)
xMatters notification servers (zero or more)
Java Clients or xMatters integration agents
One or more satellite sites (optional):

n
xMatters notification servers (one or more)
Considerations
There are several points to consider when planning an xMatters Disaster Recovery deployment:
n
The deployment requires that the latency between Application Servers, Web Servers and the Database Server
within one site is less than 50ms for a 1,024 bytes (1 KB) packet round trip.
There are no specific latency requirements between the satellite sites on one side and primary and Disaster
Recovery sites on the other.
Database replication should be configured between the primary and Disaster Recovery databases. The bandwidth
between the sites hosting the two database servers should be sufficient to handle transferring the replication data
between the two sites. Another option is to configure frequent database backups of the primary database, and ship
them continuously to the Disaster Recovery site.
The database under replication (DR site) must be in a mode that prevents it from accepting connections (i.e.,
NONRECOVERED for SQL Server; STANDBY for Oracle). When the DR database is promoted to production, the
mode must be changed to allow connections (i.e., switched out of NONRECOVERED on SQL Server; mounted
without the STANDBY clause on Oracle).
For replication under Oracle, it is recommended that Data Guard is used in Physical Standby mode.
Disaster Recovery Deployment Considerations | 336
The Primary Site database and the Disaster Recovery Site database must be the same type: i.e., both SQL Server or
both Oracle.
Operating system time zones must be synchronized across all Application Server Nodes and web servers. For more
information, see "Multiple Node Deployment Considerations" on page 34.
Note:
Configuring database replication and database backup/restore procedures is not in scope for this section. It is
assumed that these tasks are implemented by properly trained database administrators.
Deployment Installation and Configuration

This section describes the steps necessary for installing an xMatters Disaster Recovery deployment. Before beginning
system installation, ensure you have a proper xMatters license, with sufficient Application Server Nodes to accommodate
the Disaster Recovery deployment requirements.
Note:
Before proceeding with the following steps, ensure that your xMatters license key allows the combined number
of Application Servers (primary and DR) to be installed.
To install an xMatters Disaster Recovery deployment:

1. Install the primary database server (Oracle or SQL Server).
2. Install the xMatters application servers, Notification Servers and Web Servers in the primary site, using the primary
database server.
l
The first time you run the installer, it creates the xMatters database. The installers in the following steps will
use the database created in this step.
3. Install the xMatters application servers and Notification Servers in the Disaster Recovery site, using the xMatters
database created in Step 2.
l
If this is an All-in-One xMatters deployment, also install the xMatters web servers in the Disaster Recovery
site (i.e., using the Disaster Recovery xMatters database). You can then skip step 7.
4. Install the xMatters notification servers in all satellite sites, using the primary xMatters database server created in
Step 2.
Note:
All Nodes in the Disaster Recovery and satellite sites must be installed using the primary database. This is
because each node has a unique identifier, and they all need to be in the same database for the Disaster
Recovery process to function properly.
5. Install the Disaster Recovery database server.

l
This database can be Oracle or SQL Server, but must be the same as installed in Step 1.
6. Back up the primary xMatters database and restore it on the Disaster Recovery database server.
l
This creates the Disaster Recovery xMatters database.
7. Using the Disaster Recovery xMatters database, install the xMatters web servers in the Disaster Recovery site.
l
If this is an All-in-One xMatters deployment and you have already installed the xMatters web servers in the
Disaster Recovery site during step 3, you can skip this step.
8. Stop the Application Servers, Notification Servers, and Web Servers in the Disaster Recovery site. At this point
you have a fully functional system, with the following components running:
l
xMatters database in Primary Site
Application Servers in Primary Site
Web Servers in Primary Site
Notification Servers in Primary Site
Notification Servers in Satellite Sites
9. The following components are on stand-by or are not running:

l
xMatters database in Disaster Recovery Site (on stand-by; used only for replication)
Application Servers in Disaster Recovery Site (not running)
Notification Servers in Disaster Recovery Site (not running)
Web Servers in Disaster Recovery Site (not running)
10. Reconfigure Disaster Recovery Application Server nodes to connect to the Disaster Recovery xMatters database, as
described in "Disaster Recovery Procedures" on page 339.
11. Configure all Satellite Notification Servers for failover, as described in "Configuring xMatters nodes for Failover"
on page 340.
12. Configure database replication, or set up a database backup/restore mechanism between the primary and Disaster
Recovery xMatters databases. (The detailed procedures for these tasks are outside the scope of this section.)
Note:
The standby database should not accept client connections when acting as the Warm Standby. Instead, the
standby database should be put into a state that allows connections only after failover occurs.
On SQL Server, the standby database must be in the NONRECOVERED state when acting as the Warm
Standby. If replication is implemented using Log Shipping, the standby database must be in the
NONRECOVERED state, and the NO RECOVERY mode should be used, ensuring that no connections can be
made. After failover occurs, take the database out of the NONRECOVERED state.
On Oracle, the standby database must be mounted in the STANDBY mode when acting as Warm Standby. After
failover occurs, the standby database must be shut down, then mounted and opened without the STANDBY
clause.
13. Java Client Agents or integration agents can be installed at different locations. Ensure that they are reconfigured
and restarted when the system is switched to the Disaster Recovery site and when it is switched back to Primary.
Upgrading an xMatters DR Deployment

When upgrading an xMatters DR deployment, the DR nodes must rejoin production nodes during the upgrade process,
as described in the following steps.
To upgrade an xMatters DR deployment:
1. If replication is used, stop the replication process between the primary and DR site.
2. Stop all components.
3. Reconfigure DR Application Server nodes to connect to the production xMatters database, as described in
"Configuring xMatters to connect to a different database" on page 340.
4. Upgrade all components.
5. Ensure that all components are stopped (upgrading nodes causes them to restart).
6. Back up the primary xMatters database and restore it on the DR database server.
l
This creates the DR xMatters database.
7. Reconfigure DR Application Server nodes to connect to the DR xMatters database, as described in "Configuring
xMatters to connect to a different database" on page 340.
8. Configure database replication, or set up a database backup/restore mechanism between the primary and DR
xMatters databases.
9. Start all production components.
Disaster Recovery Procedures

This section describes the procedures to be followed if there is a need to switch from the primary site to the Disaster
Recovery site.
Switching the system from the primary to the Disaster Recovery site
The need for switching to the Disaster Recovery site may be determined by a complete site failure, or by a failure of the
primary database server. Any other xMatters components (Nodes) have failover capabilities, so if the deployment was
properly designed, they should not trigger a switch from the primary to the Disaster Recovery site.
To switch the xMatters deployment to the Disaster Recovery site:
l
l
If replication is used, stop the replication process between the primary and Disaster Recovery.
If using backup/restore, restore the most recent backup of the primary xMatters database on the Disaster
Recovery database.
2. Stop the Primary Site database.

3. Start the Disaster Recovery database.
Note:
After failover occurs, the standby database must put into a state that allows it to accept connections: on SQL
Server, take the database out of the NONRECOVERED state; on ORACLE, the standby database must be shut
down, then mounted and opened without the STANDBY clause.
4. Start the Application Servers and the Web Servers in the Disaster Recovery site. These have been installed or
reconfigured to use the Disaster Recovery database; therefore, no additional configuration should be required.
5. When the Satellite Notification Servers, which have been configured for failover, are unable to connect to the
Primary Site database, they will attempt to connect to the Disaster Recovery Site database.
6. Using the web user interface in the Disaster Recovery Web Servers, log in as a Super Administrator and ensure that
all Nodes are running, except for the Primary Application Server Nodes, which will be in either Stop or
Unreachable state.
After executing the Disaster Recovery procedure, the Health Monitor sends a notification regarding the failure of the
Primary Node. This is expected and is normal behavior.
Also, the following error may be written to the xMatters node log file:
ERROR - MisfireHandler: Error handling misfires
This is also expected, normal behavior.
Switching the system from the Disaster Recovery site back to Primary
When the primary site is operational again, perform the following steps to revert the xMatters deployment to the Primary
Site:
1. Shut down all xMatters components.
2. Back up the Disaster Recovery xMatters database and restore it on the Primary database.
3. Shutdown the Disaster Recovery Site database.
4. Start the Primary Site database.
l
All Nodes should detect that they are unable to connect to the Disaster Recovery Site database, and will
attempt to reconnect to the Primary Site database.
5. Using the web user interface in the Primary Web Servers, log in as a Super Administrator and make sure all Nodes
are running, except for the Disaster Recovery Application Server Nodes, which will be in Stop state.
Configuring xMatters to connect to a different database

This section describes the procedures for changing the database connection information. The database connection
information is stored in the common.properties file, located in
<xMHOME>/common.
The file is encrypted; to modify it, you must decrypt the file, make the modifications, and re-encrypt the file. For
decrypting/encrypting files, use the utility named APSecure located in the
<xMHOME> directory.
Note:
Secondary database details are not retained during xMatters upgrades and must be reapplied. It is
recommended that you record your settings.
To replace common.properties with the new version of the encrypted file:

1. From the <xMHOME> directory, run the following command; this creates an unencrypted file, common.txt:
APSecure.sh decrypt ./common/common.properties common.txt
2. Open the common.txt file and update the database information.

3. Save the updated file.
4. To encrypt the updated file, run the APSecure utility using the following syntax:
APSecure.sh encrypt common.txt ./common/common.properties
The common.txt file will consist of the following text:

#Tue Jan 23 15:17:24 PST 2007
JDBC_DRIVER_CLASS_NAME=net.sourceforge.jtds.jdbc.Driver
JDBC_USERNAME=alarmpoint4
JDBC_URL=jdbc\:jtds\:sqlserver\://192.168.168.55\:1433
JDBC_PASSWORD=pwdAlarmP01nt
When you are reconfiguring to connect to the Disaster Recovery database, the only entry that needs to be changed is
JDBC_URL (in this case, you would replace 192.168.168.55 with the IP address or host name of the Disaster
Recovery database).
The same utility can be used to change the password for the xMatters database user.
Note:
It is recommended that you prepare two versions of the common.properties file (common.properties.primary and
common.properties.dr), and have them ready in advance on all the Nodes that may need to be switched. When
the system needs to be switched one way or the other, the only task will be to copy the appropriate predefined
file over common.properties and restart the Node.
Configuring xMatters nodes for Failover

Configuring an xMatters node for failover requires the modification of two encrypted files: common.properties and
node.properties.
The common.properties file is located in <xMHOME>/common. The file is encrypted; to modify it, you must decrypt the
file, make the modifications, and re-encrypt the file. For decrypting/encrypting files, use the utility named APSecure
located in the <xMHOME> directory.
To replace common.properties with the new version of the encrypted file:
1. In the <xMHOME> directory, run the following command
APSecure.sh decrypt ./common/common.properties common.txt
2. APSecure creates an unencrypted file named common.txt.

3. Open the common.txt file and update the database information.
5. Run the APSecure utility using the following syntax to encrypt the updated file:
APSecure.sh encrypt common.txt ./common/common.properties
The common.properties file consists of the following text:

#Tue Jan 23 15:17:24 PST 2007
JDBC_DRIVER_CLASS_NAME=net.sourceforge.jtds.jdbc.Driver
JDBC_USERNAME=alarmpoint4
JDBC_URL=jdbc\:jtds\:sqlserver\://192.168.168.55\:1433
JDBC_PASSWORD=pwdAlarmP01nt
JDBC_URL.1=jdbc\:jtds\:sqlserver\://192.168.168.51\:1433
JDBC_DRIVER_CLASS_NAME.1=net.sourceforge.jtds.jdbc.Driver
JDBC_PASSWORD.1=alarmpoint4
JDBC_USERNAME.1=pwdAlarmP01nt
CONFIG_INDEX=0
DB_CONNECTION_FAILOVER_PERIOD=120000
DB_CONNECTION_FAILOVER_ATTEMPTS_MAX=10
DB_CONNECTION_FAILOVER_ATTEMPTS=0
Primary Site Configuration:

n
JDBC_DRIVER_CLASS_NAME: JDBC driver name for the Primary Site database
JDBC_USERNAME: user name for the Primary Site database
JDBC_URL: JDBC URL for the Primary Site database
JDBC_PASSWORD: password for the Primary Site database
Disaster Site Configuration:

n
JDBC_DRIVER_CLASS_NAME.1: JDBC driver name for the Disaster Site database
JDBC_USERNAME.1: user name for the Disaster Site database
JDBC_URL.1: JDBC URL for the Disaster Site database
JDBC_PASSWORD.1: password for the Disaster Site database
Failover Configuration:
n
CONFIG_INDEX: current database configuration.
DB_CONNECTION_FAILOVER_PERIOD: how long, in milliseconds, a database connection can be down before

failover occurs.
DB_CONNECTION_FAILOVER_ATTEMPTS_MAX: maximum number of times to attempt failing over before

stopping further attempts.
DB_CONNECTION_FAILOVER_ATTEMPTS: number of attempts made for failover.
The Disaster Recovery Configuration and Failover Configuration must be added to the common.properties file.
The node.properties file is located in <xMHOME>/node/assets/config. The file is encrypted; to modify it, you must
decrypt the file, make the modifications, and reencrypt the file. For decrypting/encrypting files, use the utility named
APSecure located in the <xMHOME> directory.
To replace node.properties with the new version of the encrypted file:
1. From the <xMHOME> directory, run the following command to use APSecure to create an unencrypted file named
node.txt:
APSecure.sh decrypt ./node/assets/config/node.properties node.txt
2. Open the node.txt file and update the database information.

4. To re-encrypt the file using APSecure, run the following command:
APSecure.sh encrypt node.txt ./node/assets/config/node.properties
The node.properties file consists of the following text:

NODE_ID=200000
NODE_ID.1=200000
LM_LOG_DIRECTORY=C:/Program Files/C:\Program Files (x86)\xMatters/log
SCRIPT_LOG_DIRECTORY=C:/Program Files/AlarmPointSystems/AlarmPoint/log
RB_RESOURCE_DIRECTORY=C:/Program
Files/AlarmPointSystems/AlarmPoint/node/assets/resources/runtime
PHONE_ENGINE_DIRECTORY=C:/Program Files/AlarmPointSystems/AlarmPoint/node/phone-engine
VERSION=3.1.0
Primary Site Configuration:

n
NODE_ID: Node Identifier on the Primary Site.
Disaster Site Configuration:

n
NODE_ID.1: Node Identifier on the Disaster Recovery Site.
The Disaster Recovery Configuration must be added to the node.properties file.
Use Case Scenario

The following use case scenario is based on an xMatters customer with three sites in different geographical locations.
xMatters Customer A has data centers in three sites: San Francisco, London and Tokyo.
San Francisco is the Primary site with the following components:
n
Oracle Server with Primary AP database
Two Application Server Nodes
Two Web Servers
Two Notification Server Nodes (configured for failover)
Two integration agents
London is the Disaster Recovery Site with the following components:

n
Oracle Server with Disaster Recovery xMatters database
One Application Server Node (Disaster Recovery mode, configured to use the Disaster Recovery database, not
started when San Francisco site is operational)
One Web Server (Disaster Recovery mode, configured to use the Disaster Recovery database)
Two Notification Server Nodes (configured for failover)
Two integration agents
Tokyo is a satellite site with the following components:

n
One Notification Server (configured for failover)
Database replication is configured between the San Francisco Primary database and London Disaster Recovery database.
This process ensures that the data in the London database is no more than 10 minutes behind the San Francisco database.
In the event of an outage that renders the San Francisco site unavailable, the following steps must be taken to switch the
system to the London site:
1. Stop the replication process on the London database.
2. Start or enable the London database.
3. Stop the San Francisco database.
4. Start the London Application Server Node and web server.
l
The Notification Server Nodes in Tokyo and London detect the Primary Site database failure and connect to
the Disaster Recovery Site database.
5. Reconfigure the London integration agents to point to the London Application Server, and then restart them.
Failover in xMatters
Failover is a design method that ensures continuous operation of a particular system or service. It may refer to a need to
keep a system available to its users during scheduled downtime, to keep it available despite single- or multiple-point
hardware failures, or even to keep availability during to the disruption of an entire site in the case of power loss,
network outage, or natural disaster.
n
xMatters has been designed to meet the requirements of high availability strategies, including the following
elements:
The Java Client or integration agent supports automatic failover between a primary and secondary Application
Server.
The xMatters application servers are load balanced with automatic failover of events and their processes if an
Application Server fails. They can also be configured at a secondary location that can take over if the primary fails.
The xMatters notification servers are similarly load balanced with automatic failover of notifications.
The xMatters web server provides everything necessary to use the standard web server failover abilities of load
balancers, a common component in deploying web applications.
The database layer of xMatters is designed to integrate into your database environment where there are many
options available for database failover.
Considerations
When planning for failover, the expense of implementation, the recovery time after failure, and the disruptive impact on
users and the business must all be balanced. The expense is not measured only by the initial implementation cost of a
particular strategy, but also by the on-going cost of supporting it during regular operation of the system.
After considering these factors, business managers should define a specific Service Level Agreement (SLA) that sets
acceptable boundaries and expectations for IT operations. IT departments can then manage and budget for systems to
meet these standards.
The following table describes various failover approaches and the attributes of each:
General Approach
Recovery Time
Human Intervention?
General Expense
User Impact
No Failover
Unpredictable
Yes
No cost to low cost
High
Cold Failover
Hours
Yes
Moderate
Moderate
Failover in xMatters | 343
General Approach
Recovery Time
Human Intervention?
General Expense
User Impact
Warm Failover
Minutes to
Seconds
Possibly
Moderate to high
Low
Hot Failover (High

Availability)
Seconds
No (automatic)
High
None
Each of these approaches for availability is implemented with specific technologies in the different layers of xMatters:
n
The Java Client or integration agent can be deployed on many systems, with management systems configured to
send events to several of them. Each Java Client can be configured to communicate with a primary and secondary
Application Server, automatically failing over to the secondary if the primary becomes unavailable.
The xMatters application server has been designed for hot failover by default. If one of the application servers
detects that another application server has stopped processing events, it picks up the unhandled events, even if
their processes were already in progress, and ensures they are fulfilled. This is referred to as Highly Available
Production Application Servers.
The xMatters notification server has been designed for hot failover by default. If one of the Notification Servers
detects that another Notification Server has stopped sending notifications that were assigned to it, the detecting
Server automatically takes control of those notifications and delivers them. (For strategies to avoid duplicate
notifications due to servers with temporary down time, see "Configuring Notification Dispatching Periods" on page
344, below.)
The xMatters web user interface can be deployed with high availability by running a load balancer in front of
multiple xMatters web servers. Failover of this portion is warm, as the load balancer will detect a failure of one of
the web servers and automatically reroute traffic to the other web server. It may have some impact on users (they
will have to log in again), but otherwise the change-over is transparent. The load balancer can also be configured
to start sending sessions to the failed web server once it detects that the server is up again.
The xMatters application servers can be duplicated at another location and manually switched on if the primary
servers fail for any reason. This is called an xMatters Mirror site.
From a failover perspective, the database component of xMatters is the most complicated. xMatters can integrate
into your database environment or you can use the database that comes bundled with the product, Microsoft's SQL
Server Express. The bundled database does not provide failover services, so if you want to implement a failover
strategy for the database tier you will need to do it with a database product you purchase separately.
In short, the xMatters servers have been designed from the ground up to ensure that events are always handled properly.
They allow you to support several complementary failover mechanisms so that many possible scenarios can be handled.
Configuring Notification Dispatching Periods
xMatters has a number of retry mechanisms to ensure the delivery of notifications. The dispatching period is a
configuration setting for one of these retry mechanisms. After a notification is dispatched to a Device Engine, the
dispatching period is the length of time xMatters waits for confirmation from the Notification Server before attempting to
send the notification again.
By default, the dispatching period is set to five minutes. If a server goes down after the notification is delivered but
before the results are returned to the Application Server, a short dispatching period setting may result in the Application
Server sending the notification again. Use the following steps to configure the dispatching period for your deployment
to reduce the chances of this occurring.
To configure the dispatching period:
1. On the xMatters server, locate the<xMHOME>/node/assets/resources/spring/integration/ folder:
2. Open the ndApplicationContext.xml file, and locate the following section:
<bean name="notificationDispatcher"
...
<property name="dispatchingPeriod">
<value type="long">300000</value>
</property>
3. Change the value to the length of time, in milliseconds, you want to set the dispatching period.
4. Save and close the file, and then restart the xMatters node.
Database Components
Dealing with failover of the database layer is complex and has many different options. Because the other layers of
xMatters already provide failover strategies, the remainder of this section discusses the different strategies available for
implementing database failover.
There are three major database elements that need to be considered with respect to failover:
n
The database server itself, composed of the hardware and the database software.
The network communication channels between the application and the database, the storage area networks, and the
networks between database servers.
The data controlled by the database server, which is typically stored on hard drives.
Failover is achieved by building redundancy into each of these components, and eliminating all single points of failure.
Database servers can be mirrored or clustered to provide redundancy at both the hardware and software level. In the case
of a failure, existing connections and workload simply fail over to a surviving server. Several such strategies are
described later in this section.
Networks can be teamed or bonded. For each required network, two identical networks are built using duplicate
interface cards, cables, switches and so on. Network bonding or multi-pathing software is then used to treat the two
physical networks as one, load balancing across the two and routing all traffic to one in the case of a single failure.
Data Storage
Data storage may be provided in one of three possible ways:
n
Data may be stored on hard drives that are local to the database server machine; this is called Direct Attached
Storage (DAS).
Data may be stored on hard drives that are remote from the local machine and accessed across a network. The
drives could be part of another computer that acts as a file server, or they could be part of a Network Attached
Storage (NAS) device that manages many drives and has its own Ethernet connection.
Data may be stored on hard drives that are attached to a Storage Area Network (SAN) device similar to a NAS, but
accessed across a Fibre Channel network requiring a proprietary Host Bus Adapter (HBA) to be installed on each
server.
Regardless of the data storage method, one of the most straightforward failover strategies for data is a RAID array. The
key issue to consider with RAID is that all hard drives in a particular array are kept together at one site. This works well
in the event of individual drive failures, but offers no protection in the event of a site failure or if the array controller
fails.
In addition to RAID, a Logical Volume Manager can be used to duplicate or mirror data on two or more RAID arrays,
preferably at different physical locations. In the event of any one site or controller failure, the other sites immediately
provide an exact copy of the data and continue processing. Many vendors offer this technology, including Veritas
Volume Replicator, Oracle ASM, EMC SRDF, Network Appliance Snap Mirror, and FalconStor.
Strategies
The most commonly used strategies for database failover fall broadly into five categories: backup/recovery, log file
transfers, replication/data mirroring, clustering/shared disk, and point in time recovery. These categories are not mutually
exclusive, and many true high availability strategies rely on a combination of them. Each of these strategies is discussed
in the following sections.
Note:
These terms can vary from one database vendor to another, and will often be used as marketing terms for a
particular feature offered by a database. The terms are used here in a generic sense.
Backup / Recovery
A valid, tested backup-and-recovery procedure is a mandatory part of any production database, and may well be
governed by law. Backup copies should be stored both on- and off-site to facilitate easy restoration to the primary
database, and safety in the case of a site disaster. The privacy and security of the backups may also be a significant issue.
In addition, by taking the regular backups from a primary production site and restoring them to another database at a
remote site, a backup server is available to take on duties as required. The restoration may be done as part of the backup
process, or it may be done manually when an outage is detected.
This strategy covers the range from no failover to cold failover. It is relatively easy to implement, and allows data to be
reliably restored from an earlier point in time in the case of user or system induced data errors or corruptions. However, it
also has the major disadvantage that data added or altered since the last backup may be lost when failover occurs.
Backup / Recovery options:
n
Microsoft SQL Server provides several types of backup and recovery, including Simple, Bulk Logged, and Full.
The Oracle database provides the Recovery Manager (RMAN), which offers this failover strategy at various levels.
Log File Transfers

Whenever a transaction is committed to a database, the details are recorded in a log file. The primary purpose of this log
is to protect the transaction against a subsequent database failure. The log can also be used to recreate the transaction on
another database server, thus maintaining a standby database.
This strategy can cover the range from cold to hot failover, depending on how frequently the logs are transferred and
applied to the secondary server, whether a synchronous transfer mode is available, and whether manual intervention is
required to have the backup server take over database duties.
Asynchronous transfers imply a lag between the primary and secondary sites, and a potential loss of recent data after
failover. Synchronous transfers effectively replicate the entire database in real time, but may have a significant
performance impact on the primary database.
Log File Transfers options:
n
Microsoft SQL Server provides Log Shipping as its mechanism for providing this failover strategy. This is also
used for Microsofts Data Mirroring in High Performance mode.
For the Oracle database, Data Guard provides for the transferring of transaction logs between databases, and offers
both synchronous and asynchronous modes, as well as other options.
Replication / Data Mirroring

Replication involves making sure that transactions commit on two separate databases at the same time, and is usually
based on individual tables or groups of tables rather than the entire database. Depending on how remote the two
databases are, network capacity, and other factors, this can have serious performance implications. Some replication
methods offer an asynchronous option to alleviate the performance problems, but this puts recently-committed data at
risk.
There are other benefits to maintaining a secondary database, whether through replication or log transfers. The secondary
site can take over some of the regular duties of the primary database, such as reporting or auditing, thus reducing the
load on the primary database.
Replication / Data Mirroring options:

n
Microsoft SQL Server provides Data Mirroring in High Safety mode, and offers replication through a variety of
means, including Transactional Replication and Merge Replication.
Oracle offers Streams, Materialized Views and Advanced Replication for table level replication, and Data Guard in
synchronous mode for entire database replication.
Clustering / Shared Disk

To eliminate the database server as a single point of failure, multiple database servers can be clustered to provide
multiple access points to a single database. The database resides on a shared SAN or NAS storage device. Modern
storage devices already have a certain amount of redundancy built in. By adding a Logical Volume Manager, the
database can be mirrored in real time to multiple storage devices with transparent failover at the data access level.
Applications connect to a database service, rather than to a specific machine or instance. Connections are load balanced
across all available database servers to make best use of resources. If a database server fails, connections are
automatically migrated or re-routed to surviving servers, and the surviving servers clean up any transactions that were in
progress on the failed server. When a new server joins the cluster, work requests are directed to that machine to evenly
balance load across the cluster.
This technique can greatly increase the reliability, performance and scalability of the database, and can be implemented
at both primary and secondary sites for maximum availability. This strategy provides hot failover at the primary site, and
when used in conjunction with other techniques such as Replication or Log File Transfers, can provide maximum
availability with hot failover to a secondary site as well.
Clustering / Shared Disk options:
n
Microsoft SQL Server provides Failover Clustering that assumes a Shared Disk.
Oracle provides Real Application Clusters (RAC) and Automatic Storage Management (ASM) to implement this
strategy.
Point In Time Recovery

Point In Time Recovery technology offers a safety net in the event of inadvertent data changes that would not otherwise
be considered failures, but could seriously impair a production database; for example, a user or program accidentally
altering or deleting records in a table. Point In Time Recovery technology works by recreating data as it existed at a
particular point in time, even after changes have been committed.
A certain amount of data change information is stored in the database, and is required to support read consistency and
transaction rollbacks. This change information can also be used to roll back data to a pre-existing state. The amount of
change information kept is configurable, but finite. Thus the retention period for rollback operations may not always be
guaranteed.
This strategy provides a fast and convenient alternative to using database backups to undo inadvertent data changes.
Point In Time Recovery options:
n
Microsoft SQL Server offers Database Snapshots to provide this functionality.
Oracle offers various forms of Flashback technology to restore rows, tables, transactions or the entire database to a
pre-existing state. Oracle also offers Log Miner to recreate transactions from the log files.
Summary
Out of the box, xMatters provides a robust, fault-tolerant solution to high availability strategies. The Java Client or
integration agent supports automatic failover between servers and the xMatters application servers are load balanced
with automatic failover of events and their processes if an Application Server fails. The Application Servers can also be
configured for cold failover using a secondary site as an xMatters mirror site.
The Notification Servers are also load balanced with automatic failover of notifications, and the xMatters web server
provides the necessary support for a load balancer to failover from one web server instance to another. Finally, the
database layer of xMatters is designed to integrate with the various failover options available within the database
environment.
Fronting the xMatters web server

There are a number of situations where direct access from the Users browser to the xMatters web server may not be
desirable. This may be because a firewall sits between the user and xMatters, it may be because of restrictions on the
servers to which browsers can connect, or it may be because another web server is adding extra services such as Single
Sign On.
Note:
On xMatters enterprise deployments, web servers must be fronted with Apache or Microsoft IIS.
This section provides methods for configuring the Apache HTTP Server and Microsoft Internet Information Services (IIS)
to forward web requests on to the xMatters web server, and for them to return the HTML to the Users' browsers as if it
had originated from them.
Note:
Customizations to the jetty.xml file are not retained during xMatters upgrades and must be reapplied. It is
recommended that you record your changes.
Forwarding Requests from Apache HTTP Server

The simplest way to provide access from an instance of Apache HTTP Server to the xMatters web server is to proxy the
requests from Apache to xMatters. This section includes instructions for setting up various versions of the Apache HTTP
Server to proxy requests.
Note:
You can also use URL Rewriting or the AJP Protocol to provide access. For information on these methods,
consult the Apache documentation.
The following versions of the Apache HTTP Server have been tested with the xMatters web server:
n
Apache 2.2.2
Apache 2.2.3-31
Although more recent versions of Apache may work, they have not been tested; it is recommended that you use the
latest version listed above.
Proxying to the xMatters web server

When installing, remember that the proxy module has to be compiled and available to the Apache HTTP Server in order
to support proxying of requests to xMatters. The module will either be statically linked into your server or it will be
available through dynamic loading. If the proxy module is not available to your server in either form, you may need to
recompile your server with the proxy module enabled.
On Linux, if the proxy module is statically linked into your HTTP Server, you can navigate to your server's installation
directory and run "./httpd -l". The output should include "mod_proxy.c". If it does not, the server does not have the
proxy module statically linked into it. See the instructions below for configuring the proxy module to load dynamically
on specific versions of Apache.
On Windows, the module is excluded by default. For newer versions of Apache, enable modules by uncommenting the
following lines:
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
Fronting the xMatters web server | 348
Once your server has access to the proxy module, you can add the proxy directives to your configuration. The insertion
point for these lines depends on the specific configuration of your Apache instance. In the default installation, the lines
can be inserted at the end of the httpd.conf file.
The host name (i.e., internal-host) below should be changed to reflect the actual host name; localhost should be used if
the xMatters web server and the fronting server are on the same computer.
Also, if you are using cookie-based session tracking for xMatters, and you have other applications running on your
Apache HTTP server under a different path (or your Apache HTTP server also proxies other applications under a
different path), you must add the following line to those indicated in the sections below:
ProxyPassReverseCookiePath / /alarmpoint/
To front the xMatters web user interface, insert the following lines:
ProxyPass /xmatters/ http://internal-host:8888/xmatters/
ProxyPassReverse /xmatters/ http://internal-host:8888/xmatters/
ProxyPass /rest/ http://internal-host:8888/rest/
ProxyPassReverse /rest/ http://internal-host:8888/rest/
ProxyPass /alarmpoint/ http://internal-host:8888/alarmpoint/
ProxyPassReverse /alarmpoint/ http://internal-host:8888/alarmpoint/
ProxyPass /static/ http://internal-host:8888/static/
ProxyPassReverse /static/ http://internal-host:8888/static/
ProxyPass /jsp/ http://internal-host:8888/jsp/
ProxyPassReverse /jsp/ http://internal-host:8888/jsp/
ProxyPass /ua/ http://internal-host:8888/ua/
ProxyPassReverse /ua/ http://internal-host:8888/ua/
ProxyPass /sp/ http://internal-host:8888/sp/
ProxyPassReverse /sp/ http://internal-host:8888/sp/
Note that each prefix listed above represents a different area of the web server that serves different types of information.
Each area has a different context path to ensure that requests can be routed correctly, and the context paths listed above
are mandatory for fronting the web user interface. The following sections identify optional context paths for other
features.
To front the xMatters web services, insert the following lines:
ProxyPass /api/services/ http://internal-host:8888/api/services/
ProxyPassReverse /api/services/ http://internal-host:8888/api/services/
To front the mobile access component, insert the following lines:

ProxyPass /mg/ http://internal-host:8888/mg/
ProxyPassReverse /mg/ http://internal-host:8888/mg/
To front the SMScallback URLsupport:

ProxyPass /services/ http://internal-host:8888/services/
ProxyPassReverse /services/ http://internal-host:8888/services/
To front the Voice XMLcallback URL support:

ProxyPass /voicexml/ http://internal-host:8888/voicexml/
ProxyPassReverse /voicexml/ http://internal-host:8888/voicexml/
To test your changes on Linux, run "apachectl configtest". If everything is configured correctly, you should see the
message "Syntax OK".
On Windows, restart Apache HTTP Server. If restart fails, read the comments in \logs\error.log.
After restarting your Apache HTTP Server, every request to http://your.publichost.com/alarmpoint/*,
http://your.publichost.com/static/* and
http://your.publichost.com/api/services/* will get passed through to xMatters, while all other content will be
served by your Apache instance.
Note:
Currently, it is not possible to use URL proxy-spaces other than the three specified by xMatters: "alarmpoint",
"static", and "api/services.
Instructions for the Apache 1.3 series

If the proxy module is dynamically loaded, the following code must be in one of the loaded configuration files
(typically, httpd.conf).
LoadModule proxy_module libexec/libproxy.so
AddModule mod_proxy.c
Instructions for the Apache 2.0 and 2.2.x series

If the proxy module is dynamically loaded, the following code must be in one of the loaded configuration files
(typically, httpd.conf):
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_http_module modules/mod_proxy_http.so
Adding Access Logs

This section describes how to add access logs in the fronting Apache server (note that these logs may already be
configured in Apache).
To add access logs to the fronting Apache server, the following code must be in one of the loaded configuration files
(typically, httpd.conf):
LogFormat "%h %l %u %t \"%r\" %D %>s %b" common
CustomLog logs/access_log common
Forwarding Requests from Microsoft's IIS

If you want to use IIS to access the xMatters web server, you must configure the AJP protocol to communicate between
them, as explained in the following sections.
Enabling IISFronting
In xMatters 5.0, IIS fronting in Jetty is disabled by default. To configure your xMatters deployment for IISfronting,
locate the <xMHOME>\webserver\etc\jetty-ajp.xml.tmpl file, and rename it to jetty-ajp.xml before performing
any of the configuration processes described in these sections.
Note that you will need to restart your web server for this change to take effect.
Pre-installation considerations
Before installing the IIS plug-in, machine- or system-specific information in the runme.reg and Default Website
Overwrite.xml files should be changed because values that contain paths to resources in the file system might not
match paths on other computers. Change all paths in these files to the path used by the computer on which you want to
install the plug-in. You should also search for other paths in the import files before using them.
Additionally, the Default Website Overwrite.xml file includes a ServerBindings property that is used to configure
the port number for a site. This property may need to be modified to reflect the settings on the new computer.
Step 1: Downloading the ISAPI plug-in for AJP

The supported version of the ISAPI plug-in can be downloaded from the xMatters Community at
community.xmatters.com (at Downloads > Product Downloads > Documents, or search for "IIS Plugin").
IISversion 6.0
It is recommended that you use the version of the ISAPI plug-in provided by xMatters, as the latest release may not be
compatible with the xMatters web server. Currently, xMatters supports version 1.2.26.0 of the plug-in.
IISversions 7.0 and 7.5

It is recommended that you use the version of the ISAPI plug-in provided by xMatters, as the latest release may not be
compatible with the xMatters web server. Currently, xMatters supports version 1.2.27.0 of the plug-in (for Windows
2008 R2 64-bit).
Step 2: Installing the plug-in

After downloading the plug-in, you must extract the file archive and add the appropriate registry entries to the Windows
registry.
The instructions in this and the following sections assume a default extraction path of C:\Program Files\; if you
extract the plug-in to a different location, you must edit the runme.reg file and adjust the paths accordingly.
To install the plug-in:
1. If you are using IIS7.0 or 7.5, extract the ISAPI_REDIRECT_IIS7_x64.zip file to C:\Program Files\.
2. If you are using IIS6.0, extract the ISAPI_REDIRECT.zip file to C:\Program Files\.
3. Navigate to the following folder:
C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\
4. Double-click the runme.reg file to add the required registry settings.
Step 3: Configuring the plug-in

If the web server to be fronted is not on the local machine, you will need to configure ISAPI. In a text editor, open the
workers.properties.minimal file located at:
C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\conf
Locate the following line and change localhost to the IP address of the web server you want to front:
worker.alarmpoint.host=localhost
Note:
Port 8899, which is specified in the worker.properties.minimal file for the ajp13 packets, should not be
confused with port 8888, which is used for the HTTP listener.
Step 4: Configuring the default web site

The next step in configuring IISis to set up the default web site. Depending on the version of IIS you are using, do one
of the following:
n
If you are using IIS6.0 and you do not have any configurations for your Default Web Site, follow the directions in
"Step 4A: Configuring IIS 6.0 for a new configuration", below.
If you are using IIS6.0 and you already have configurations for your Default Web Site, following the directions in
"Step 4B: Configuring IIS 6.0 for an existing configuration" on page 352.
If you are using IIS 7.0 or 7.5, follow the directions in "Step 4C: Configuring IIS 7.x" on page 352.
Step 4A: Configuring IIS 6.0 for a new configuration

Use the following steps to configure IIS6.0 if you do not currently have any configurations for your Default Web site.
To configure IIS6.0:
1. In IIS, right-click on Web Sites, select New, then select Website (from file).
2. Click Browse, and browse to:
C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector
3. Select Default Website Overwrite.xml and click Open.

4. Click Read file.
5. Select Default Web Site as the location and click OK.
6. Select Replace the existing site and click OK.
7. Right-click Default Web Site and select Start.
8. Proceed to Step 5: Restarting Website and Setting Extension Status below.
Step 4B: Configuring IIS 6.0 for an existing configuration
Use the following steps to configure IIS6.0 if you already have configurations for your Default Web site.
To configure IIS6.0:
1. In IIS, right-click the default web site, and then select Properties.
2. In the Properties dialog box, click the ISAPI Filters tab, and locate the entry for jakarta.
3. If there is no entry for jakarta, use the following steps to add a new entry:
l
On the ISAPI Filters tab, click the Add button.
In the New Filter dialog box, type jakarta in the Filter Name field.
For the Executable field, browse to the /bin subfolder of your installation directory and specify the isapi_
redirect.dll file.
Click OK to save the values, and ensure that you now have a jakarta entry in the list of filters.
4. Right-click Default Web Site, select New, and then select Virtual Directory.
5. Click Next.
6. Type jakarta as the Alias.
7. Type C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\bin\ as the path (the
trailing \ is needed)
8. Select the Read, Run scripts and Execute check boxes and select Next.
9. Click Finish.
10. Right-click on Default Web Site, and select Properties.
11. Click the Home Directory tab.
12. Select the Script Source Access check box and select Scripts and executables from the Execute Permissions dropdown list.
13. Click Apply.
14. Select Jakarta from the Child Nodes list and select OK.
15. Click OK.
Step 4C: Configuring IIS 7.x
Use the following steps to configure IIS7.0 or IIS 7.5.
To configure IIS7.x:
1. Open the IIS 7x Manager Interface.
2. If you do not have a Web Site defined, or would like to create a new one for fronting the xMatters web server do
the following:
l
In the Connections pane, right-click Sites, and then click Add Web Site.
Specify a Site name and Physical path. Note that any valid path will work; typically this is set to
C:\inetpub\wwwroot
Note:
If a Default Web Site already exists, please note that the default port number (80) may already be in use. The
rest of the instructions assume a port number of 80.
3. Add a Virtual Directory:

l
l
Right-click the web site, and then select Add Virtual Directory.
Type jakarta in the Alias field; do not alter this name as it must match the name added to the registry
earlier.
In the Physical path field, specify the location of the isapi_redirect.dll file, and then click OK; the path
should resemble the following:
C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\bin
4. Give the new Virtual Directory execute permission to run the DLL:
l
Select the newly created jakarta folder.
In the center pane, double-click the Handler Mappings icon.
If the ISAPI-dll entry is disabled, click Edit Feature Permissions in the Actions pane.
In the Edit Feature Permissions dialog box, ensure that all 3 checkboxes (Read, Script, and Execute are
selected, and then click OK. The ISAPI-dll entry should now be enabled.
5. Add an ISAPI filter to the web site:

l
In the Connections pane, click the web site.
In the center pane, double-click the ISAPI Filters icon.
In the Actions pane, click Add.
In the Add ISAPI Filter dialog box, type jakarta in the Filter name field.
In the Executable field, specify the location of the isapi_redirect.dll file; the default location should
be: C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\bin\isapi_
redirect.dll
Click OK to save the values, and ensure that you now have a jakarta entry in the list of filters.
6. Configure the ISAPI and CGI Restrictions:

l
Navigate to the Server Home (the top level of the navigation tree in the Connections pane).
In the center pane, double-click the ISAPI and CGI Restrictions icon.
In the Actions pane, click Add.
In the Add ISAPI or CGI Restriction dialog box, in the ISAPI or CGI path field, specify the same path to the
isapi_redirect.dll file you used in the previous step.
In the Description field, type ISAPI Redirect.
Select the Allow extension path to execute check box.
Click OK to save the values, and ensure that you now have an ISAPI Redirect entry in the list of
restrictions.
Step 5: Restarting the web site and setting extension status

To apply the IISconfiguration changes, you must restart your web site.
Note:
Before all changes take effect, you may also need to restart the IIS Admin service.
IISversion 6.0
The following instructions apply to IIS6.0 users.
To restart your website:
1. Click OK to close the Properties dialog box.
2. Right-click the default web site, and then click Stop.
3. Right-click the web site again, and then click Start.
4. Right-click it a third time, and then click Properties.
5. Click the ISAPI Filters tab and ensure that the jakarta filter is operating, as indicated by a green arrow in the
Status column.
If you are using IIS6.0, once you have added the jakarta entry and restarted the web site, you must also allow access to
the filter through the Web Service Extensions component.
To set extension status:
1. Open the IIS Manager and, under the appropriate server, click Web Service Extensions.
2. Under Tasks, click Add a new Web service extension.
3. Name the new extension jakarta.
4. Browse to the installed isapi_redirect.dll file, and select Set extension status to Allowed.
5. Click OK.
6. Ensure that both the Default web site and DefaultApp pool are running.
IISversion 7.x
The following instructions apply to IIS7.0 and 7.5 users.
To restart your web site:
1. In the Connections pane, select the Default Web Site.
2. In the Actions pane, click Stop.
3. Click Start.
Step 6: Test forwarding

Use a web browser to access the machine running IIS (the following examples use localhost as the machine address).
Verify that you can view the home page and that everything works as expected. You can test your configuration using
the following URL:
http://localhost/jkmanager
You should see a page on your browser with the line Worker Status for alarmpoint; if you do not, then the IIS has not
been configured correctly.If the filter is not active, you will need to restart your web site. When you change the
configuration to correct it, ensure that you restart the web server and not just the web site. To restart the web server,
open your Services Manager and stop the World Wide Web Publishing service, and then start it again.
Use one of the following URLs.
To test web user interface fronting, use:
http://localhost/xmatters/
Note:
The final slash is required.
If you can log in successfully, then IIS is configured properly. If you see the login page, but no logo and no styling, then
the /static portion of the uriworkermap.properties file is not configured properly.
To test web services fronting, use:
http://localhost/api/services/AlarmPointWebService?wsdl
If you can view the WSDL successfully, IIS is configured properly.
Step 7: Shutting off HTTP on xMatters (optional)

You can ensure that the only mechanism for accessing the xMatters web server is through the IIS server by shutting
down the HTTP listener in xMatters.
Note:
This process shuts HTTP off for both the xMatters web user interface and web services.
In the /etc subfolder in the xMatters web server installation directory, open the jetty.xml file in an XML editor. The
jetty.xml file contains three sections that start with the following tag:
There is one section for the HTTP listener, one for the HTTPS SSL listener, and a third for the AJP listener. The HTTP
listener contains the following tag:
Comment out the entire section, including the <Call> and </Call> tags, for that listener, and restart xMatters. It should
no longer respond to port 8888.
Note:
You may also want to remove the section for the HTTPS SSL connection. Do not remove the AJP listener
section in the jetty.xml file.
Microsoft IIS Cache Control

If you are setting cache control rules on Microsofts Internet Information Services (IIS) Web server, you must have access
to the IIS Metabase, which is typically accessed via the Internet Service Manager (ISM), the Microsoft management
console application that controls IIS administrative settings.
To set an expiration time in IIS:
1. Open the ISM and bring up the property sheet for the file or directory with the expiration time you want to
configure.
2. Click the HTTP Headers tab and select the Enable Content Expiration check box.
3. Select one of the radio buttons to expire the content immediately, to set a relative expiration time (in minutes,
hours, or days), or to set an absolute expiration time.
l
Note that both Expires and Cache-Control headers will be inserted into the affected responses.
Despite the user-friendliness of the GUI, it is time-consuming to set up different cache control policies for different
categories of files on IIS. This becomes a greater challenge if the sites files are not neatly segregated into directories
based on their expiration times.
If you have designed your site with caching in mind, and put different classes of files in different directories (such as
/images/dynamic, /images/static, /images/navigation, etc.), it is relatively easy to set up caching policies via the
Microsoft management console. However, if you have not done this, or if you are working to optimize an existing site,
you may need to literally set the policy on each file. There is also no easy way in IIS to delegate authority to developers
to set cache policy, as modification of the required settings requires MMC access.
High Bandwidth Configuration for a Heavily Loaded Web

Server
If your environment must handle a high volume of simultaneous web users on the xMatters web server, there are several
configuration changes you can make to scale up the number of page accesses that can be performed concurrently.
Note:
Deriving optimal performance from the xMatters web server depends partly on your environment. It is
recommended that for each of the changes described below, you run a benchmarking tool to ensure that the
implemented change has a measurable effect. If not, you may need to investigate your environment to isolate
the service request bottleneck.
High Bandwidth Configuration for a Heavily Loaded Web Server | 355
Serving Static Content From a Fronted Web Server

Before making any changes suggested in this section, refer to "Fronting the xMatters web server" on page 348 for details
about placing a web server in front of the xMatters web server. The latter instructions require some modification to have
the fronting web server serve the static content of the xMatters web application directly.
Serving Static Content from the Apache Web Server

When configuring Apache to serve the static content from the xMatters web server, you must indicate in which directory
the content in located. This requires that you add the following lines to your Apache configuration file (typically,
httpd.conf):
Alias /static/css "<xMatters>\webserver\webapps\
cocoon\alarmpoint\css"
Alias /static/images "<xMatters>\webserver\webapps\
cocoon\alarmpoint\images"
Alias /static/includes "<xMatters>\webserver\
webapps\cocoon\alarmpoint\includes"
Alias /static/resources "<xMatters>\webserver\webapps\
cocoon\alarmpoint\resources"
<Directory "<xMatters>\webserver\webapps\cocoon\
alarmpoint">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
ProxyPass /alarmpoint/ http://localhost:8888/alarmpoint/
ProxyPassReverse /alarmpoint/ http://localhost:8888/alarmpoint/
Note that you must replace <xMatters> with the directory in which xMatters is installed, and that the slashes that
follow <xMatters> must match the platform ("\" for Windows systems; "/" for all others). The port number on the
ProxyPass and ProxyPassReverse lines should match the port on which you installed the xMatters web server to run. If
you need to be more specific about who can connect to these static resources, change the "Order" and "Allow" options in
the Directory section.
"Fronting the xMatters web server" on page 348 mentions four lines to include in your httpd.conf file. As shown in the
list above, you do not need the two lines that refer to "/static/", but you still need the ProxyPass and ProxyPassReverse
lines for "/alarmpoint/".
Serving Static Content from Microsoft's IIS

Set up IIS as described in the section "Fronting the xMatters web server" on page 348. The only change required is to
remove the line /static/*=alarmpoint from the uriworkermap.properties file.
After removing the line, open the default web site and add a new virtual directory. Specify an alias of "static" and a
directory of <xMHOME>\webserver\webapps\cocoon\alarmpoint
where <xMHOME> is the xMatters installation directory. Permissions can be set to allow only "Read" access.
Testing Static Content

You can test the setup of the Apache or IIS web server for serving static content by monitoring the latest
<xMHOME>/webserver/logs/*_request.log file (its name mirrors today's date).
After your Apache or IIS server is configured and restarted, if you access xMatters only through the port on which your
Apache or IIS web server is running (typically, port 80), then few if any new lines should appear in the monitored log
file. Specifically, the log file should not contain any requests that start with "static/", nor should it have any requests for
files that end in .js, .css, .gif, or .png. Those requests should appear only if you access the xMatters web server
directly using port 8888 (or another port to which you have set it).
Caching static content

Configuring browsers to cache the static content that is served to them for some period of time increases the performance
of the xMatters web server. Caching can significantly reduce the number of requests that are made to the server. Most
browsers are able to ask for information to be downloaded only if it has changed since the last time it was retrieved.
However, network resources are used each time the browser makes this query. If the browser only asks once every few
hours, the improvement can be measurable.
Caching duration will vary with each deployment and is therefore subjective. These files change only when you upgrade
xMatters. If you do upgrades at night, setting the cache expiry to several hours is likely adequate. If you do upgrades on
the weekend, you can safely set the cache expiry to a day or two. If you require high availability, then you may only
want to cache for 15 minutes (or possibly less).
The following instructions assume that you have already configured your web server to serve static content through a
fronting web server.
To cache content with the Apache Web Server:
Add the following line immediately above the "</Directory>" line listed above:
ExpiresDefault "access 6 hours"
You can specify any number of "minutes", "hours", or "days". Configuring the cache expiry for more than a few days is
not recommended, as your users may see unexpected behavior after an upgrade.
To cache content with Microsoft's IIS Server:
1. From the Internet Information Server's configuration tool, open the Default Web Server and locate the "static"
folder you added above.
2. Right-click static and then click Properties.
3. Select the HTTP Headers tab and click Expire after.
4. Use the two drop-down lists on the right to specify the expiry time.
5. Click OK.
Testing Caching
After you have added caching, you can test whether it is working by monitoring the log files for the web server:
1. Load a set of pages in xMatters using the caching web server.
2. Now look at the request log files for the caching web server and note the time.
3. Return to the browser and load exactly the same set of pages.
l
The lines added after the noted time to the web server's request log should contain only URLs that begin
with "/alarmpoint/".
Configuring the Database Connection Pool

Incoming requests are only part of the load that the xMatters web server must handle. Queries and updates performed on
the database tables should also be considered. Increasing the number of threads that connect to the database is an
important element in scaling the load that the xMatters web server can handle. The exact number of connections allowed
is controlled by the database, but the recommended settings for a high-capacity system are a minimum of 10 and a
maximum of 100 for each node and web server.
Choose values that are appropriate for your hardware and operating system, as well as for the database to which you are
connecting. After you have made changes to the file, restart your xMatters web server and measure the effect the change
has had on the ability to handle the load.
Note:
Database connection pool customizations are not retained during xMatters upgrades and must be reapplied.
Connection pool parameters are configurable in xMatters by modifying the c3p0.properties file (found at
<xMatters>/node/assets/resources/spring/integration/), as summarized in the following table:
Connection Pool Parameters
Setting
Description
acquireIncrement
Specifies how many simultaneous connections the connection pool tries to

acquire when the pool is exhausted.
checkoutTimeout
Specifies the number of milliseconds a client calling getConnection() waits for

the connection to be checked in or acquired when the pool is exhausted. Zero
(0) means wait indefinitely, while setting any positive value causes the
getConnection() call to timeout and break with an SQLException after the
specified number of milliseconds.
idleConnectionTestPeriod
When greater than 0, specifies how often in seconds that xMatters will test all
idle, pooled connections that are not checked out.
maxIdleTime
Specifies the number of seconds the connection can remain pooled but unused
before being discarded. Zero (0) means idle connections never expire.
minPoolSize
Specifies the minimum number of connections a pool always maintains; the

recommended minimum is at least one connection per Company in the system.
For a high-capacity system, the recommended value is 10.
maxPoolSize
Specifies the maximum number of connections a pool always maintains.

Recommendations:
Microsoft SQL Express: 10
Microsoft SQL Server and Oracle: 100
For most basic and xMatters workgroup deployments, it is recommended that
you keep the default settings. For xMatters enterprise deployments, change the
maxPoolSize setting to 100.
initialPoolSize
Specifies the number of connections the connection pool tries to acquire during
startup (this number should be between the minPoolSize and the maxPoolSize).
testConnectionOnCheckout
Specifies whether xMatters should test the pool connection on each checkout.
On high-capacity systems, set the value to false to reduce the number of roundtrips to the database.
Configuring database connection pools for separate xMatters components

You can change the maximum number of connections separately for each xMatters component; i.e., the xMatters node,
the web user interface, web services, and the mobile access component.
xMatters node
To change the number of database connections available to the xMatters node, modify the c3p0.properties file in the
following directory:
<xMatters>/node/assets/resources/spring/integration/
Typically, you will want to alter the following settings:
minPoolSize=5
maxPoolSize=15

To change the maximum number of database connections available to the xMatters web user interface, modify the c3p0config.xml file in the following directory:
<xMHOME>/webserver/webapps/cocoon/WEB-INF/classes
Locate the default-config element, and change the value for maxPoolSize. Save the file, and then restart the
xMatters web server.
xMatters web services
<xMHOME>/webserver/webapps/axis2/WEB-INF/classes
mobile access component
<xMHOME>/webserver/webapps/mobilegateway/WEB-INF/classes
Pinging the Database Connection Pool Status

You can access a URL in the web user interface to check the status of the database connection pool. To ping the web
application, request the following URL in a browser:
http://<IP_Address>:8888/xmatters/PingStatus
The page will return one of the following responses:

n
200: the database connections are available; at least one connection is available to service requests.
503: the database connections are exhausted; the connection pool has reached its limit and all connections are
busy.
Special parameters
You can pass two special request parameters in the query string of the above URL:
n
debug (true or false; default is false): if true is specified, the JSP page generates log messages to the system
console containing information on the status of the connection pool (e.g., total connections, number of idle
connections, etc.).
wait (positive integer; default is 5: the number of seconds to wait to obtain a connection before aborting the
request. Under normal load, the check out of a connection should be relatively rapid, and this threshold may
change as load increases.
Sample Request:
http://<IP_Address>:8888/jsp/PingStatus?debug=true&wait=10
Configuring xMatters Heap Size

The Java Virtual Machine (JVM) uses a specified minimum value as the initial memory heap size. As memory is
allocated and the available heap reaches a certain threshold, the JVMwill allocate another heap to the VMprocess. This
will happen until the specified maximum value is reached.

You can gain a small benefit to a long running system, and reduce start-up time for other applications on an xMatters
enterprise deployment, by eliminating the cost of allocating memory to the JVMheap.
By default, the server memory settings are set to a minimum of 256 Mb, and a maximum of 1024 Mb. For xMatters
enterprise deployments, it is recommended that you set both values to 1024 Mb.
To configure the xMatters heap size for an xMatters enterprise deployment:
1. On the xMatters server, navigate to the <xMHOME>\common folder.
2. On Windows, open the node-start.conf and webserver-start.conf files, and change -Xmns256m to Xmns1024m in both files.
3. On Unix, open the node.sh and webserver.sh files, and change MINMEM=256m to MINMEM=1024m in both files.
4. Save and close the files.
5. Restart the xMatters web server.
Monitoring and Configuring Web Server Usage

The following sections provide more information about managing and configuring the way Users interact with the
xMatters web server and web user interface.
Determining Web Server Usage

You can examine the database tables to determine who is logged into the web server at any time. Note that this data is
only available at the database level; it is not available via the web user interface.
The EXT_USER_SESSIONtable contains the following columns:
n
USER_SESSION_ID: used as the primary key for the table.
SESSION_ID: random UUIDassigned by the web server for this session.
USER_NAME:the name of the User currently logged into the web server.
IP_ADDRESS:the IPaddress of the xMatters web server the User is accessing.
LOGIN_TIME:the time at which the User logged in to the web server.
WEB_LOGIN: the Login IDused to log in to the web server.
USER_AGENT: contains information about the User's browser and operating system; the exact content is
determined by the browser.
USER_ID: the User's database ID.
Note that the data contained in the database table is dependant on the web server's handling of sessions.
Modifying the Web Session Timeout

You can extend or reduce the web page session timeout to suit your preferences when working in the xMatters web user
interface.
To modify the web session timeout:
1. On the xMatters web server, locate the following file:
/webserver/webapp/cocoon/web-inf/web.xml
2. Open the web.xml file in an XML editor, and locate the following lines:
<session-config>
<session-timeout>30</session-timeout>
</session-config>
Monitoring and Configuring Web Server Usage | 360
3. Edit the <session-timeout> value to indicate how long, in minutes, xMatters should keep a web session open
without activity before it times out.
4. Save and close the web.xml file.
l
Repeat these steps for each web server in your xMatters deployment.
Modifying the Web Continuation Timeout

Continuations are used when web forms are loaded (i.e., displayed) and are awaiting User input. By default, the
continuation timeout period is set to 15 minutes (900,000 milliseconds). This means that 15 minutes after the application
is started, and then every two minutes, the system checks to see whether there are any continuations that have lived for
longer than 15 minutes.
To modify the web continuation timeout:
1. On the xMatters web server, locate the following file:
<xMHOME>/webserver/webapps/cocoon/WEB-INF/properties/core.properties
2. Locate the following continuations-manager settings:

continuations-manager.time-to-live = 900000
continuations-manager.expirations-check.offset = 900000
continuations-manager.expirations-check.period = 120000
l
time-to-live is the actual timeout period
expirations-check.offset is the length of time to wait before the first check (after the application has started)
expirations-check.period is the elapsed time between all subsequent checks
Units are in milliseconds (ms); for example, 15 minutes is calculated as follows:

15 x 60 x 1000 = 900,000
3. Modify the continuations-manager settings as required, and save and close the core.properties file.
l
Repeat these steps for each web server in your xMatters deployment.
Enabling and Disabling AJP, HTTP, HTTPS & JMX

The following sections describe how to enable and disable AJP, HTTP, and HTTPS on the xMatters web server, and how
to enable and disable JMX on the xMatters web server and Node.
Enabling AJP on the xMatters web server

By default, AJP is disabled on the xMatters web server.
To enable AJP:
1. Navigate to the directory where the web server is installed.
2. Open the etc directory.
3. Make a copy of the jetty-ajp.xml.tmpl and rename it to jetty-ajp.xml.
Note:
To disable AJP, remove the jetty_ajp.xml file.
Enabling and Disabling AJP, HTTP, HTTPS & JMX | 361
Disabling HTTP on the xMatters web server

By default, HTTP is enabled on the xMatters web server.
To disable HTTP:
3. Open the jetty.xml file and comment or remove the following lines:
<Arg>
<Set name="port">
<SystemProperty name="jetty.port" default="8888"/>
</Set>
<Set name="maxIdleTime">30000</Set>
<Set name="Acceptors">1</Set>
<Set name="confidentialPort">8443</Set>
<Set name="statsOn">false</Set>
<Set name="lowResourcesConnections">2000</Set>
<Set name="lowResourcesMaxIdleTime">1000</Set>
<Set name="headerBufferSize">3072</Set>
<Set name="requestBufferSize">8192</Set>
<Set name="responseBufferSize">49152</Set>
</New>
</Arg>
</Call>

Note:
To re-enable HTTP, uncomment or add the lines above back into the jetty.xml file.
Enabling HTTPS on the xMatters web server

By default, HTTPS is disabled on the xMatters web server. You can enable HTTPS by renaming the jettysslengine.xml file, located in the etc subfolder on the web server.
Note that when HTTPS is enabled, the default xMatters port changes from 8888 to 8443.
The following steps describe how to enable HTTPS using default certificates. To install your own certificates, consult
the following URL:
https://community.xmatters.com/knowledge-base/how-to/configuring-ssl-keys-and-certificatesfor-the
Also, these steps pertain to the xMatters web user interface, xMatters web services, and the mobile access component
(these components are all contained within Jetty).
To enable HTTPS:
3. Rename the jetty-sslengine.xml file to jetty-ssl.xml.
5. To ensure that the site is properly configured, use a web browser and navigate to
https://<host>:8443/<site_name> (where host is the website domain name or IP address, and site_name is
the site context with a default of alarmpoint).
Note:
To disable HTTPS, rename the jetty-ssl.xml file back to jetty-sslengine.xml.
Enabling JMX on the xMatters web server and nodes

By default, JMX is disabled on the xMatters web server and nodes.
Node
This section describes how to enable and disable JMX on xMatters nodes (Unix and Windows).
To enable JMX on a Unix system:
1. Navigate to the directory where the node is installed.
2. Open the node.sh file and uncomment or add the following line:
MANAGED_PARAMS="-Dcom.sun.management.jmxremote=true
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.port=9498"

Note:
To disable JMX again, comment or remove the line above from the node.sh file.
To enable JMX on a Windows system:

1. Navigate to the directory where the node is installed.
2. Open the common directory.
3. Open the node-start.conf file and uncomment or add the following lines:
-Dcom.sun.management.jmxremote=true
-Dcom.sun.management.jmxremote.port=9498

Note:
To disable JMX again, comment or remove the lines above from the node-start.conf file.
Web Server
This section describes how to enable and disable JMX on xMatters web servers (Unix and Windows).
To enable JMX on a Unix system:
Navigate to the directory where the web server is installed.
2. Rename the jetty-jmx-template.xml file to jetty-jmx.xml.
3. In the web server installation directory, open the webserver.sh file and uncomment or add the following line:
MANAGED_PARAMS="-Dcom.sun.management.jmxremote=true
-Dcom.sun.management.jmxremote.port=9498"

Note:
To disable JMX again, change the name of the jetty-jmx.xml file back to jetty-jmx-template.xml, and
comment or remove the line above from the webserver.sh file.
To enable JMX on a Windows system:

3. Rename the jetty-jmx-template.xml file to jetty-jmx.xml.

4. In the web server installation directory, open the webserver-start.conf file and uncomment or add the
following lines:
-Dcom.sun.management.jmxremote=true
-Dcom.sun.management.jmxremote.port=9498

Note:
To disable JMX again, change the name of the jetty-jmx.xml file back to jetty-jmx-template.xml, and
comment or remove the line above from the webserver-start.conf file.
Deploying xMatters on WebSphere

This section describes how to install and configure xMatters components on an IBM WebSphere application server.
xMatters 4.1 (patch 001 and higher) must be deployed on WebSphere 7.0.
The Optional folder on the xMatters installation disc includes the following files (where "X" represents WebSphere
version):
n
cocoon-websphereX.war: contains the xMatters application files and folders
mobilegateway-websphereX.war: contains the mobile access component application files and folders
axis2-websphereX.war: contains the xMatters web services files and folders
Each of the three archives is formatted to comply with WebSphere requirements, and can be installed separately, or
together with one or more of the other files.
The following processes explain how to deploy an xMatters WAR file on a WebSphere application server. Where
necessary, steps specific to one of the files are included as part of the overall process.
These instructions have been validated with WebSphere running under Windows Server 2003; your deployment may
vary. For complete WebSphere details, refer to its documentation.
To deploy an xMatters WAR file on WebSphere:
1. Start the WebSphere Application Servers Administrative console.
2. Log in as an administrator.
3. In the menu on the left side of the screen, expand Applications, and then click Install New Application.
4. Specify the file path, or click Browse to navigate to the WAR file you want to install.
5. In the Context Root field, do one of the following:
l
If you are deploying cocoon-websphereX.war , type / (i.e., forward slash). Note that WebSphere has
exclusive use of / in this context; you may need to modify settings in other applications to reflect this.
If you are deploying mobilegateway-websphereX.war, type /mg.
If you are deploying axis2-websphereX.war, type /api.
6. Click Next.
7. On the Select installation options page, replace the text in the Application name field with one of the following
entries:
l
If you are deploying cocoon-websphereX.war , type xMatters.
If you are deploying mobilegateway-websphereX.war, type APMG.
If you are deploying axis2-websphereX.war, type APWS.
8. Click Next.
Deploying xMatters on WebSphere | 364
9. On the Map modules to servers page, accept the default settings and click Next.
10. On the Map virtual hosts for Web modules page, accept the default settings and click Next.
11. On the Summary page, click Finish.
12. After a successful installation is indicated, click the Save link.
After installing the new application within WebSphere, you can specify the settings for the modules.
To specify the module settings in WebSphere:
1. In the menu on the left side of the screen, expand Applications, and then click Enterprise Applications.
2. Click the name of the application you are modifying.
3. Under the Detail Properties heading, click the Class loading and update detection link.
4. Under Polling interval for updated files, type 0 in the Seconds field.
l
Do NOT select the Reload classes when application files are updated check box.
5. Select Classes loaded with local class loader first (parent last).
l
Ensure that the WAR class loader policy is set to Class loader for each WAR file in application.
6. Click OK.
7. Under Modules, click the Manage Modules link.
8. Click the name of the WAR file you installed.
9. Click the Class loader order drop-down list and select Classes loaded with local class loader first (parent last),
and then click OK.
10. On the left-hand menu, expand Applications and click Enterprise Applications.
11. Click the name of the application you are modifying.
l
If you are modifying the mobile access component, skip to step 16.
12. Under Web Module Properties, click the Session Management link.
13. Under General Properties, select the following check boxes:
l
Override session management
Enable SSL ID tracking
Enable URL rewriting
Enable protocol switch rewriting
14. Under General Properties, clear the Enable cookies check box.
15. Click OK.
16. Under Modules, click Manage Modules.
17. Click the name of the WAR file you installed.
18. Click the Session Management link.
19. Ensure that the Override session management check box is cleared, and then click the Save link at the top of the
page.
Instructing the WebSphere web container
The following steps instruct the WebSphere web container not to add additional information to the jsession id. This
may affect applications that need this additional information.
Note that the following steps are not required for the mobile access component. If you are installing the mobile access
component, you can skip the following steps and proceed to the next section, Copying xMatters files.
To instruct the WebSphere web container:
1. On the menu on the left side of the screen, expand Servers, and then click Application servers.
2. On the Application Servers page, click the name link for the server on which you installed the new xMatters
WebSphere application.
3. On the Configuration tab, under Container settings, expand Web Container Settings, and then click the Web
container link.
4. Under Additional Properties, click the Custom Properties link.
5. Click New.
6. Under General Properties:
l
Type NoAdditionalSessionInfo in the Name field.
Type true in the Value field.
7. Click OK.
8. Click the Save link at the top of the page.
l
Do not close the WebSphere console; it must be open for the following steps.
Copying xMatters files

After you have configured the xMatters component in WebSphere, you must copy the required xMatters files into the
web module directory for each web application that is installed (xMatters, web services, and the mobile access
component).
This section uses the following conventions:
n
<xMHOME>: refers to the xMatters installation folder; for example, the default installation folder on Windows is
C:\Program Files (x86)\xMatters
$WEBHOME: refers to the web application's installation directory on the WebSphere application server
To copy the xMatters files (repeat for each installed web application):
1. Copy the following files from xMatters to WebSphere:
l
File:
<xMHOME>/webserver/webapps/cocoon/WEBINF/classes/resources/spring/integration/hibernate.properties
l
To:
$WEBHOME/WEB-INF/classes/resources/spring/integration
l
File:
<xMHOME>/webserver/webapps/cocoon/WEBINF/classes/resources/spring/integration/quartz.properties
l
To:
$WEBHOME/WEB-INF/classes/resources/spring/integration
l
File:
<xMHOME>/common/common.properties
l
To:
$WEBHOME/WEB-INF/classes
l
File:
<xMHOME>/common/dbPatchVersion.properties
l
To:
$WEBHOME/WEB-INF/classes
2. If you are deploying either xMatters or the mobile access component, do the following:
l
In the WebSphere console, expand Applications and click Enterprise Applications.
Select the check box for the component you are deploying, and then click Start.
3. If you are deploying xMatters web services, update the keystore files as follows:
l
l
Remove the $WEBHOME/WEB-INF/classes/APUniversal folder.

Copy the $WEBHOME/WEB-INF/classes/APUniversalAIX/ folder to $WEBHOME/WEBINF/classes/APUniversal/.
4. For all WebSphere deployments, locate the /java/jre/lib/ subfolder of the WebSphere's AppServer installation
directory; the default is <WebSphere Install Folder>\AppServer.
5. If it does not already exist, create a file named jaxp.properties in the subfolder, and add the following lines:
javax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
javax.xml.xpath.XPathFactory=org.apache.xpath.jaxp.XPathFactoryImpl
javax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
javax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
Note:
If the jaxp.properties file already exists in this directory, add the lines to the existing file.
Testing
After you have configured xMatters on WebSphere and copied the appropriate files, you can test the configuration.
To test an xMatters deployment:
1. Select Application Servers > server1 > Ports, and check the port number for WC_defaulthost
2. Using a web browser, navigate to: http://<IP>:<port>/xmatters/signOn.do
To test a mobile access component deployment:
1. Select Application Servers > server1 > Ports, and check the port number for WC_defaulthost
2. Using a web browser, navigate to: http://<IP>:<port>/mg
If you are deploying an xMatters component on a WebSphere Application Server that already has an xMatters
component installed, an exception may be thrown. If this occurs, do the following:
1. Open the WebSphere Application Server Administrative console, navigate to Servers > Application Servers >
server_name_link (typically, server1) > Java and Process Management > Process Definition > Java Virtual
Machine.
2. Set Generic JVM arguments to -Xverify:none
3. Restart the WebSphere Application Server.
Troubleshooting WebSphere Deployment
This section includes troubleshooting tips for common issues that may arise when deploying xMatters on WebSphere.
Issue:
Restarting an xMatters WAR file in WebSphere causes a bean creation error. To resolve this error, restart the WebSphere
application server.
Issue:
The following errors have no effect on xMatters, and can be ignored:
n
CWXRS0004E: Failed to resolve plug-in
Errors related to tld files, similar to the following:
Failed to parse Tag Library [/WEB-INF/classes/resources/tld/c.tld]: JSPG0235E: The JSP

container failed to load the TagExtraInfo class [org.apache.taglibs.standard.tei.ImportTEI]
Enable cookie-based session management

By default, the xMatters web user interface uses URL-based session management. After installing the web server, you
can switch to cookie-based session management as an alternative.
Note:
When using cookie-based session management, only one user may log in to xMatters per browser. You cannot
use tabs or other browser windows (of the same browser) to log in multiple users.
To switch to cookie-based session management, you must uncomment a line in the web server configuration file, and
then restart the web server. There are two available configuration options:
n
Try to use cookie-based session management first and if not available, use URL-based session management
(default)
Use cookie-based session management only
The steps below describe how to configure each cookie-based management option.
To enable cookie-based session management:
1. On the xMatters web server, open the web server configuration file in a text editor:
l
On Windows (by default): <xMHOME>\common\webserver-start.conf
On Unix (by default): <xMHOME>/webserver.sh
2. If you want to try to use cookie-based session management first and if not available, use URL-based session
management, ensure that the following lines are not commented out (i.e., delete the '#' at the beginning of each
line):
l
On Windows:
-Djetty.use.cookies=true
On Unix:
USE_COOKIES="-Djetty.use.cookies=true;"
3. If you want to use cookie-based management only, uncomment (i.e., delete the #) from the following lines, and
ensure that the URLparameter is set to none:
l
On Windows:
-Djetty.use.cookies=true
-Djetty.session.url=none
On Unix:
USE_COOKIES="-Djetty.use.cookies=true"
USE_COOKIES="${USE_COOKIES} -Djetty.session.url=none"
4. If you want to disable cookie-based session management and use only URL-based session management, comment
out the above lines, or set the values to false; i.e.:
l
On Windows:
#-Djetty.use.cookies=false
On Unix:
#USE_COOKIES="-Djetty.use.cookies=false;"

6. Stop and restart the web server.
Enable cookie-based session management | 368
Increasing security by marking cookies as secure

Cookies that are not marked as 'secure' can be sent over untrusted public networks in clear text and using unsecured
protocols (e.g., HTTP). In some contexts, this can be a security issue. In contrast, when cookies are marked as 'secure',
web browsers can send them only via secure network protocols (e.g., HTTPS).
When using cookie-based session tracking for xMatters, the jsessionid is contained in the cookie as a key value pair.
Once sent to the client (browser), it passes on subsequent requests so that the user session can be identified. However,
cookies are stored in cleartext and anyone with access to the computer can easily view these key value pairs. It is also
important to note that the HTTP protocol does not encrypt the headers in any way; if the connection is not SSL, then it
will not be protected.
When the secure option is used with a cookie, the browser (or other HTTP clients) will only send the cookie over SSL
connections. This means that the cookie will not be available to any part of the site that is not secure. As a result, it
much less likely that a user will accidentally send the cookie across as cleartext.
The alarmpoint.xml file (located at <xMHOME>/webserver/contexts/) is used to enable cookies for session
management ("Enable cookie-based session management" on page 368). Once cookies have been enabled for session
management, a system property can be added to secure cookies, as described below. Note that the instructions vary
depending on whether you are using a fronting server.
xMatters SSL (no fronting server)

Follow the steps in this section if you are using the SSL configuration in xMatters (i.e., instead of using a fronting
server).
To mark all xMatters cookies as secure, follow the appropriate steps for your operating system:
Windows
1. Open the common/webserver-start.conf file in a text editor and add the following line after the jetty.use.cookies
property:
-Djetty.secure.cookies=true
2. Save the file and restart the web server.

Unix
1. Open the webserver.sh file in a text editor and locate the following line:
USE_COOKIES="-Djetty.use.cookies=true"
2. Modify the line to the following:

USE_COOKIES="-Djetty.use.cookies=true -Djetty.secure.cookies=true"
3. Save the file and restart the web server.
Apache httpd 2.2 fronting server

If you are using the Apache httpd 2.2 (or higher) Web Server as a secure fronting server, securing cookies requires
Apache configuration (i.e., because xMatters is not aware of the the proxy server). Conversely, this means that there is no
applicable configuration for xMatters in this situation.
Note:
If you want to use a fronting server and you need to secure cookies, it is strongly recommended that you use
Apache httpd 2.2 (or higher) with xMatters (there is currently no solution on IIS).
Increasing security by marking cookies as secure | 369
To mark all xMatters cookies as secure:

1. When using cookie-based session tracking for xMatters, and you have other applications running on your Apache
HTTP server under a different path (or your Apache HTTP server also proxies other applications under a different
path), you must add the following line to those indicated in the sections below:
ProxyPassReverseCookiePath / /alarmpoint/
2. To use the mod_header module to add the secure attribute, open the httpd.conf file in a text editor and add the
mod_header to the module list at the top of the file:
LoadModule headers_module modules/mod_headers.so
3. Add the Header directive after the ProxyPassReverseCookiePath directive:

# Fix the cookie path and secure it
Header edit Set-Cookie "^(.*)" $1;Secure
Advanced SMS administration

The following sections contain information about advanced customization for the SMSconfiguration and behavior in
your deployment.
Basic SMSadministration content:
n
For more information about SMSconfiguration in xMatters, see "SMPP Device Engines" on page 139, and its
related topics, "Configure SMS messages and replies" on page 142, and "Configure simple SMS replies" on page
143.
For more information about SMSlanguage encoding, see "SMPP Protocol Providers" on page 179 and "SMPP
language encoding" on page 183.
For a complete overview of SMSin xMatters, and an example of how to configure thappre xMatters SMS feature,
see "Configure xMatters SMS" on page 220.
SMS Responder Validation

On SMS, if a User mis-keys a notification identifier but still inputs a valid identifier, it may cause incorrect action to be
taken on that valid identifier. SMS responder validation prevents this from happening by comparing inbound as well as
outbound phone numbers against notification identifiers. For a response to be validated, the inbound phone number must
match the outbound number for a given notification identifier.
Note:
SMSresponder validation does not work with GSMmodems.
Additionally, with validation on, Users can only validate a Device from that Device (i.e., the Device cannot be validated
from another Device simply by keying in the correct notification identifier).
To configure SMS responder validation:
1. In a text editor, open the nrpApplicationContext.xml file (located at node/assets/
resources/spring/integration/).
2. Locate the following bean:
<bean id="notificationResponseProcessorTarget" ...
3. Modify the pattern, template, and validation properties as required (for details, see "SMS Response Validation
Properties" below.
Advanced SMS administration | 370
SMSResponse Validation Properties

There are three validation modes:
n
OFF: no SMS responder validation occurs (OFFis the default mode for both new installations and upgrades).
LOG: the configured regular expression is used to match the outbound Device phone number with the inbound
Device phone number. If these numbers match, a log message is written.
ON: when the inbound/outbound Device phone numbers match, the behavior is the same as LOG; when the
numbers do not match, the response is ignored and the rejected response is logged.
When set to LOG or ON, the following two properties control how validation is applied to the numbers:
n
pattern: Perl 5 regular expression (e.g., ".* (\d+) (\d+)...")
template:variable corresponding to the groups specified in the pattern property (e.g., "1$2$...")
Example
Assume the following configuration in which validation has been set to ON:
<property name="pattern">
<value>.* (\d+) (\d+) (\d+)</value>
</property>
<property name="template">
<value>$1$2$3</value>
</property>
<property name="validation">
<value>ON</value>
</property>
The following list summarizes SMSresponder validation processing for phone number (555) 555-1212:
1. A notification is sent to phone number (555) 555-1212 (the outbound number).
2. An SMS response that matches the notification IDis received from phone number +1 (555) 555-1212 (the inbound
number).
3. xMatters preprocessess the outbound number, stripping out non-number characters and whitespace.
4. xMatters pattern matches the inbound number against the specified pattern (.* (\d+) (\d+) (\d+)).
5. Each of the back references specified in the template string are replaced with the pattern match groupings (each
back reference is identified by $X, where X is s number corresponding to a grouping in the pattern).
6. The results of steps 3 and 5 are then compared for equality.
7. In this case, the number will match and a validation message will be written to the log.
Configuring SMS HELP and STOP Responses

xMatters allows SMSHELPand STOPresponses to be configured for Users. By default, HELPand STOP responses from
Users have the following effects:
n
HELP: xMatters sends instructions about how to contact support to the SMS Device.
STOP: xMatters does the following:

l
l
l
l
Locates all Users whose SMS Device (i.e., Text Phone Device) corresponds to the source SMS Device.
Sends an SMS confirmation messages to the Device (this message is configurable either in scripting or in a
text file).
Disables the SMS Device for all Users who have this Device address configured.
Notifies all the affected Users' Supervisors and all their immediate Group Supervisors (excluding nested
Groups and Dynamic Teams) for Groups in which they belong that the Users' SMS Devices were remotely
disabled. Note that if the Supervisor has Email Devices configured, only these Devices will be notified. If no
Email Devices are configured, the Default Device will be notified (excluding Fax Devices).
To enable SMSHELPand STOPResponses, you must create a new Event Domain called generic_responses for the
related Company. You can modify the HELPand STOP responses by loading and editing the generic_responses script
package in the xMatters Developer IDE.
Internationalizing SMS messages for MMAcompliance

To meet MMAstandards, some xMatters administrators may need to translate the SMSmessaging contained within the
xMatters web user interface and targeted notifications. The following sections explain the components involved, and
describe how to modify them for your deployment.
Web application
In the Web application, the SMS-related messaging files are stored in the following folder:
<xMHOME>/webserver/webapps/cocoon/alarmpoint/translations/
The messages.xml file, located in the above folder, contains the English versions of the SMStext. The associated
language bundles, which xMatters uses to update the required MMA text, are stored in the custom subfolder. These files
must be named with the desired translation locale.
For example, to provide French translations, copy the messages.xml file to the custom subfolder, and rename it
messages_fr.xml. Open the file in a text editor, and then replace the values for the message keys from the English
bundle with the appropriate French translations.
When configuring a new Text Phone Device, xMatters uses the following keys (see the accompanying figures for an
illustration of where each key is represented in the SMSmessaging):
l
SMS.MMA.HEADING
SMS.MMA.OPT.OUT
SMS.MMA.HELP
SMS.MMA.RATE.WARNING
SMS.MMA.AUTH
SMS.MMA.TOS.TITLE
SMS.MMA.TOS.CLOSE
SMS.MMA.TOS.OPT.OUT.TITLE
SMS.MMA.TOS.OPT.OUT.1
SMS.MMA.TOS.OPT.OUT.2
SMS.MMA.TOS.HELP.TITLE
SMS.MMA.TOS.HELP.1
SMS.MMA.TOS.HELP.2
SMS.MMA.TOS.PRICING.TITLE
SMS.MMA.TOS.PRICING.1
SMS.MMA.TOS.CARRIERS.TITLE
SMS.MMA.TOS.CARRIERS.1
Note that all SMSkeys are prefixed with "SMS.MMA"; these prefixes have been omitted for legibility in the following
diagrams.
"About xMatters"page with SMStranslation keys
"Terms of Service" page with SMStranslation keys
"Text Phone Device Details"page with SMStranslation keys
When a Company is configured with a Short Code Compliance option enabled, xMatters uses the following keys to
configure the TermsAndConditions.xml file, which is shown in the "About" dialog box:
l
SMS.MMA.TAC.OPT.OUT.1
SMS.MMA.TAC.OPT.OUT.2
SMS.MMA.TAC.HELP.1
SMS MMA Keywords

The generic_responses Event Domain contains handling for SMS MMA keywords (STOP, HELP, etc). This
implementation is generic enough to meet other regulatory requirements and provide multi-lingual support by extending
the list of supported keywords in the scripting layer.
The initial process script in the generic_responses script package defines and checks the list of supported MMA
keywords in various languages; $isHelp and $isStop variables attached to the underlying Alert object are available for
processing in other scripts (i.e., primarily the handler and presentation scripts). This list is not exhaustive, and can be
customized to include other synonyms in any language. In order to function correctly for SMS responses, the keywords
must match those sent from message content in the sms_confirmation Event Domain and associated scripts.
SMS MMA Required Messages
The sms_confirmation Event Domain contains handling for sent messages related to MMA, including the initial message
sent to a new SMS Device, help content requested by an SMS Device's User, and the confirmation text sent when a User
deactivates a Device.
The $supportedLanguages variable contains a list of supported languages for which a client has provided translations,
and is specified in the "initializePreferredLanguage" script, which then sets the $preferredLanguage variable based
upon whether the User's preferred language or Site language is in the list of supported languages (in that order). In all
cases, English will be used as the default if no language is specified as supported in this script, or if the supported
languages do not match the User's preferred language or the Site language.
The English content can also be specified in the Constants: SMSFIRSTMSG, SMSHELPMSG, SMSSTOPMSG, and
SMSCONFIRMMSG (for more information, see "SMSConfirmation and First Alert Messages Constants" on page 213). If
these Constants are not defined, the scripts contain default content.
To enable internationalization of messaging, set the $supportedLanguages variable to a list of the language names for
which translations will be provided, as defined in the Company Languages configuration in the web user interface. For
example, to indicate that content will be provided for English, French and, German:
$supportedLanguages = "English, French, German"
You can consult and modify the $preferredLanguage variable in any presentation script to adjust the message content
appropriately. The only requirement is that if you require support for responses of type STOP or HELP, the messages sent
to the User regarding this functionality must specify keywords that are contained in the $stopString or $helpString
variables defined in the generic_responses initial script. Generally, this pattern should resemble the following block of
scripting code:
# Retrieve the preferred language for the notification
CALL initializePreferredLanguage
IF ($notification.isHelp)
IF ($preferredLanguage == "French" )
$preferred_language_message = "xMatters: # alerts varie en fonction de l'utilisation. Pour
plus d'info par courriel Support@xmatters.com. Rponse de QUITTER de se retirer. MSG & donnes
de taux peuvent s'appliquer. "
ELSE-IF ($preferredLanguage == "German" )
$preferred_language_message = "xMatters: Warnungen variiert je nach Nutzung. Fr mehr
Infos per e-Mail Support@xmatters.com. Antwort DEAKTIVIEREN zum opt-out. Msg & Daten Preise
anfallen."
ELSE
$preferred_language_message = @event::getProperty("SMSHELPMSG", "xMatters: # alerts varies
with usage. For more info email Support@xmatters.com. Reply STOP to opt out. Msg & data rates
may apply.")
ENDIF
$content.message = $preferred_language_message
ELSE-IF ($notification.isStop)
IF ($preferredLanguage == "French" )
$preferred_language_message = "Votre priphrique ne recevront plus SMS travers le
Service de Notification de xMatters."
ELSE-IF ($preferredLanguage == "German" )
$preferred_language_message = "Ihr Gert erhalten SMS nicht mehr durch die xMattersBenachrichtigungsdienst."
ELSE
$preferred_language_message = @event::getProperty("SMSSTOPMSG", "Your device will no
longer receive SMS through the xMatters Notification Service")
ENDIF
$content.message = $preferred_language_message
ELSE
$content.message = $event.response & " is not a valid response."
ENDIF
Introduction
Organizations deploying xMatters can regularly synchronize data between xMatters and existing systems. This chapter
describes how data can be synchronized with one or more external systems that are the data custodians for information
that xMatters uses (e.g., Users, Devices, Groups, Teams).
Using xMatters Data Synchronization, data administrators can bulk load and synchronize data in the xMatters System.
Additionally, system integrators can use the information in this chapter as a guide for integrating xMatters with existing
data sources.
Note:
If your xMatters deployment has more than one Company requiring data synchronization, see "MultipleCompany Environments" on page 438.
Installing the Data Synchronization Module

The xMatters Data Synchronization Module has an automated installer (Windows wizard or console). You must obtain
this installer from the xMatters web site or from xMatters Support. The following sections describe the steps for
installing the module.
Note:
The Data Synchronizer installer requires connection settings for the xMatters database. If you do not know
these values, contact your xMatters system Administrator (Super Administrator).
To install the Data Synchronization Module on Windows:

1. Navigate to the folder containing the installation file (ap4xx_datasync_install.exe).
2. Double-click the ap4xx_datasync_install.exe file.
l
The xMatters Data Synchronizer installer opens.
3. After reading the text on the Introduction page, click Next.

4. After reading the License Agreement, click the I accept the terms of the License Agreement radio button, and
then click Next.
5. Accept the default installation folder, or specify a new folder, and then click Next.
6. Ensure that the database settings will allow the Data Synchronizer to connect to the xMatters database, and then
click Install.
l
If you do not know these values, contact your xMatters system Administrator (Super Administrator).
7. When the installation is finished, click Done.

To perform a console install of the Data Synchronization Module:
1. Navigate (cd) to the folder containing the installation file (ap4xx_datasync_install.bin).
2. Run the following command:
./ap4xx_datasync_install.bin -i console
3. After reading the text on the Introduction page, click Next.

4. After reading the License Agreement, type Y to accept the agreement, and then press Enter.
5. Type Y to accept the default installation folder, or specify a new folder.
6. Select your database type (Oracle or SQL), ensure that the database settings will allow the Data Synchronizer to
connect to the xMatters database, and then press Enter.
l
If you do not know these values, contact your xMatters system Administrator (Super Administrator).
7. After the installation has completed, press Enter.
Introduction | 378
Note:
To uninstall the Data Synchronizer, in Windows use Add/Remove Programs, and under Unix use the following
command: ./Uninstall_AlarmPoint_3_Data_Synchronizer -i console
Data Synchronization Components

The Data Synchronization command invokes the xMatters Data Synchronization module, which allows you to import
and export data to and from the xMatters system. Importing and exporting is done through a Staging Area, and a
configuration file controls the direction of the data flow.
The Data Synchronization module has the following components:
n
Staging Area
Configuration File
Command Line Report
Synchronization Report (web user interface)
Log Files
The following sections describe each component and provide details about its use.
Note:
In some cases, you may want to prevent the Data Synchronization tables from becoming large. Deleting the
tables may not be advisable if the EXTERNAL_KEY cannot be re-generated exactly the same for all records (i.e.
because removing the records means that new users will be added when they synchronize). If records can be regenerated, then you can truncate or delete the tables, but be aware that with truncate there are no rollbacks.
Staging Area
The Staging Area consists of database tables in which data is placed to make it available for data synchronization.
xMatters currently supports up to 19 Staging Area tables, which can include tables for the following data:
n
Users
User Supervisor Relationships
Devices (BlackBerry, Email, Generic, Instant Messaging, Numeric and Text Pagers, Text and Voice Phones)
Groups
Group Recurring Coverages and Holiday Only Coverages
Device Timeframes
Teams
Team Membership
Sites
Custom Fields
Custom Attributes
Event Domain Predicates
All tables include certain standard fields with specific meanings.
Requirements
The database must be reachable using JDBC. In addition, only SQL Server and Oracle databases are currently supported.
Data Synchronization Components | 379
Data Type Equivalencies

This document uses Oracle data types. The following table provides Microsoft SQL Server equivalencies for these data
types:
Oracle Data Type
SQL Equivalent
VARCHAR2
VARCHAR
TIMESTAMP(6)
DATETIME
Standard Fields
The following table summarizes the standard fields in the Staging Tables:
Staging Tables Standard Fields
Field Name
Description
alarmpoint_action
Specifies the action to take on the record on the next synchronization, or

indicates the status of the row from the previous synchronization attempt.
is_externally_owned
Controls the ownership of the synchronized object. This flag provides

instructions for the xMatters web user interface.
last_sync_date
Time and date of the records last synchronization.
external_key
Unique identifier for all tables, except Membership and the join_ tables
(DS_USER_JOIN_ATTRIBUTES and DS_CUSTOM_FIELD_JOIN_
VALUES).
The following sections discuss each field in more detail.
alarmpoint_action Field
The alarmpoint_action field specifies the action Data Synchronization module should take on the record. It also specifies
information about whether a previous synchronization was successful. Prior to processing, the alarmpoint_action field
should be set to one of the following values (if it is not set to one of these values, the row will be ignored):
User Values for the alarmpoint_action Field
Value
Description
Specifies that this record should be processed. If a matching record exists in the database, that record
is updated to match this record. If no match exists, a new record is inserted.
Specifies that this record should be removed from the database. If a matching record exists in the
database, it is removed. If no match exists, no action is taken.
Note: this action completely removes the Users Details, Devices, and Team Memberships from the
database, even if there are active notifications or scheduled escalations for the User in the system.
During processing, the Data Synchronization module sets the alarmpoint_action field for records matching the latter
values to one of the following values:
Data Synchronization for the alarmpoint_action Field
Value
Description
Temporary value indicating that the record is being processed. Although this value is normally visible
only during processing, if the synchronization process is halted, the value may appear in the Staging
Tables.
Indicates that a record marked 'R' has been successfully removed from the xMatters database (or that it
never existed).
Indicates that the record was successfully inserted into or updated in the xMatters database.
Indicates that the record was not successfully inserted into, updated in, or deleted from the xMatters
database (for further information, see "Synchronization Report (Web User Interface)" on page 437).
Indicates that this record was extracted from xMatters.
is_externally_owned Field
xMatters objects have an associated ownership. xMatters can own objects (i.e., internal ownership) or they can be owned
externally. This flag specifies the ownership type for this synchronized object (value is Y or N). When objects are in
an externally owned state, you can use the External Data page in the xMatters web user interface to control which
externally owned data fields Users can change (for details, see "Permissions: locking external data" on page 236).
Note:
You cannot use the web user interface to remove objects that have been synchronized as externally owned.
last_sync_date Field
When the data synchronization process begins, it obtains the current date and time from the computer on which it is
running. The data synchronization process brands every record with this date and time information.
external_key Field
The data synchronization process uses the external_key field to identify the record in the xMatters database that matches
this record (the external_key value must be unique within the table). Because this comparison is case sensitive,
performing case-insensitive comparisons requires that strict case consistency be used when inserting or changing records
in the Staging Area.
The external_key field is also used to establish relationships between records in the Staging Area. As a result, to specify
a User as a Group Supervisor, that Users external_key value must appear in the Group Supervisor list.
List Fields
For fields that accept a comma-delimited list, the following special token can be used to specify an empty list:
<<<NONE>>>
This token causes the Data Synchronization process to create an empty list and assign it to that field. Note that a
"NULL" value in a list field that has control of optional is equivalent to setting overwrite=false.
Note that required fields will not take an empty list as value (e.g., the role_list for Users). However, there are some
situations that you may wish to use an empty list. For example, when setting the Person Supervisor relationship for a
User, you might want to use the synchronization update to specify that the User has no supervisors.
Note:
Users created using the Web User Interface do not have any external key association in the xMatters database.
If you have existing records in the database and want to use the Data Synchronization tool, you must first
export the records using data synchronization export. During the export process, records that were created
within the web user interface are assigned an external key.
External Keys Assigned via the Web User Interface

During the Data Synchronization export process, objects without external keys are assigned default values.
Note that, as of xMatters 4.1 patch 012 and 5.0 patch 001, all external keys that are generated and assigned during an
export use a universally unique identifier (UUID).
Staging Table Content

Each Staging Table has a standard layout that can be modified. The names of tables and fields are not required, and some
fields can be completely removed. The following sections describe the layout of the standard tables.
Note:
The join_ tables (DS_USER_JOIN_ATTRIBUTES and DS_CUSTOM_FIELD_JOIN_VALUES)) vary from the

standard layout, as they do not include the external_key field. The purpose of these tables is to represent
associations between objects (e.g., User to User Attributes).
ds_attribute_categories Table
The ds_attribute_categories table contains information necessary to create and maintain Custom Attribute Categories in
xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
See "Standard Fields" on page 380.
CATEGORY_NAME
VARCHAR2 (100)
Name of the Custom Attribute category.
IS_EXTERNALLY_OWNED
CHAR (1)
Specifies whether this object is externally

owned.
ALARMPOINT_ACTION
CHAR (1)
See "Standard Fields" on page 380 and

"External Keys Assigned via the Web User
Interface" on page 382.
LAST_SYNC_DATE
TIMESTAMP (6)
ds_attributes Table
The ds_attributes table contains information necessary to create and maintain Custom Attributes in xMatters:
ds_attributes Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
ATTRIBUTE_NAME
VARCHAR2 (100)
Name of Custom Attribute.
ATTRIBUTE_CATEGORY_KEY
VARCHAR2 (250)
Specifies to which Custom Attribute

Category this Attribute belongs (by
external key).
IS_EXTERNALLY_OWNED
CHAR (1)
Specifies whether this object is

externally owned.
ALARMPOINT_ACTION
CHAR (1)
See "Standard Fields" on page 380

and "External Keys Assigned via the
Web User Interface" on page 382.
LAST_SYNC_DATE
TIMESTAMP (6)
ds_bes_devices Table
The ds_bes_devices table contains information necessary to create and maintain BES (BlackBerry Enterprise Server)
Devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
ADDRESS
VARCHAR2 (100)
The Email Address or PIN that is

associated with this BES Device.
USER_KEY
VARCHAR2 (250)
The external_key for the User who owns

this Device.
DEVICE_NAME
VARCHAR2 (100)
The name for this Device (must be

selected from the organization's defined
Device names). Standard value for this is
"BlackBerry".
The xMatters super administrator and
Company Administrator specify in the
web user interface which Device names
are available (Admin > Device Types).
Column Name
Null
Data Type
Comments
SERVICE_PROVIDER_NAME
VARCHAR2 (100)
Service provider for this Device (must be

selected from a list associated with the
organization).
The xMatters super administrator specifies
in the web user interface which User
Service Providers are available (Admin >
User Service Providers).
STATUS
VARCHAR2 (30)
Indicates whether this Device is active or

inactive (ACTIVE or INACTIVE; casesensitive).
This value is specified on the User's Text
Phone Device Details page in the
xMatters web user interface.
DEFAULT_DEVICE
CHAR (1)
Indicates whether this Device is a Default

Device (Y or N).
DEVICE_ORDER
VARCHAR2 (38)
Integer sequence number specifying the

order of the Device in the list of this
User's Devices. The list starts at 0 (zero).
DELAY
VARCHAR2 (38)
Integer specifying the Delay in minutes

for this Device.
LOCK_24x7
CHAR (1)
The flag (Y or N) indicates to the web

user interface whether the Timeframe can
be modified. When set to 'Y', Timeframes
are locked to be on a 24 hour/day, 7
day/week schedule.
IS_EXTERNALLY_OWNED
CHAR (1)

owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_custom_field_join_values Table
The ds_custom_field_join_values table contains information necessary to create and maintain Custom Fields in xMatters:
Column Name
Null
Data Type
Comments
FIELD_EXTERNAL_KEY
VARCHAR2 (250)
Target Custom Field to associate the available

value on (by external key).
FIELD_VALUE
VARCHAR2 (200)
String value available for the Custom Field.

When values are associated with a Custom
Field of type list, a drop-down list is
displayed in the xMatters web user interface.
Note:
To associate Users with their Custom Field values, refer to the"ds_user_custom_values Table" on page 407.
ds_custom_fields Table
The ds_custom_fields table contains information necessary to create and maintain Custom Fields in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
CUSTOM_FIELD_NAME
VARCHAR2 (100)
Name of the Custom Field.
CUSTOM_FIELD_TYPE
VARCHAR2 (100)
Type of Custom Field; the available

types are: STRING, BOOLEAN,
INTEGER, FLOAT and LIST.
CUSTOM_FIELD_MANDATORY
CHAR (1)
Specifies whether this Custom Field

is a mandatory field in the xMatters
web user interface when modifying
or adding a User.
CUSTOM_FIELD_MAX
VARCHAR2 (38)
Optional maximum length constraint

for Custom Field. The values
meaning depends on the custom field
type:
STRING: Length
BOOLEAN: N/A
INTEGER: Size
FLOAT: Size
LIST: N/A
Column Name
Null
Data Type
Comments
CUSTOM_FIELD_MIN
VARCHAR2 (38)
Optional minimum length constraint

for Custom Field. The values
meaning depends on the custom field
type:
STRING: Length
BOOLEAN: N/A
INTEGER: Size
FLOAT: Size
LIST: N/A
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)

LAST_SYNC_DATE
TIMESTAMP (6)
ds_device_timeframes Table
The ds_device_timeframes table contains information necessary to create and maintain Device Timeframes in xMatters:
Column Name
Null Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
DT_OWNING_DEVICE_KEY
VARCHAR2 (250)
The external_key for the Device that

owns this Device Timeframe.
DT_OWNING_DEVICE_TYPE
VARCHAR2 (250)
The type of Device that owns this

Device Timeframe.
DT_NAME
VARCHAR2 (100)
The name of this Device Timeframe.
DT_OWNING_DEVICE_NAME
VARCHAR2 (250)
The name for the Device that owns

this Device Timeframe.
DT_OWNING_DEVICE_OWNER_UID
VARCHAR2 (250)
The UID (User ID) for the Device

that owns this Device Timeframe.
START_TIME
VARCHAR2 (5)
Time at which this Device Timeframe

begins on each recurrence. The
format for this field is HH:mm (e.g.,
18:00). The Group that owns this
Device Timeframe determines the
time zone.
Column Name
Null Data Type
Comments
DT_DURATION
VARCHAR2 (77)
Duration of each occurrence of this

Device Timeframe in the format
HH:mm. For example, a setting of
08:00 means that each occurrence of
this Device Timeframe lasts for eight
hours.
DT_DAY_PATTERN
VARCHAR2 (62)
Comma-delimited list of days of the

week on which this Device
Timeframe is in effect; values are the
names of the days of the week (i.e.,
Sunday, Monday, Tuesday,
Wednesday, Thursday, Friday,
Saturday). For example, a Device
Timeframe in effect from Monday to
Friday will have the following value:
"Monday, Tuesday, Wednesday,
Thursday, Friday". This field cannot
take the value of <<<NONE>>>.
DT_EXCLUDE_HOLIDAYS
BOOLEAN
Specifies whether the Device

Timeframe excludes the Site
Holidays for the Site associated wit
the Device.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
Referencing Device Timeframes

The reference between a Device Timeframe and the Device can be made using either of the following methods:
n
By the Device External Key: dt_owning_device_key
By the Device Name and the Device Owner's User ID: dt_owning_device_name and dt_owning_device_owner_
uid, respectively
Note:
It is recommended that you use only one of these methods for each record. If both are present, the first method
will be tried first; if it fails, the second method will be attempted.
Imports
Recommended usage involves modifying the configuration file for the style of identification you plan to use. For
example, if you are using method the first method above (i.e., by the Device External Key), then the <device_timeframe>
element in the configuration file should be similar to the following:
<device_timeframe>
<external_key control="required"/>
<dt_owning_device_key control="required"/>
<dt_owning_device_type control="required"/>
<dt_owning_device_name control="not-present"/>
<dt_owning_device_owner_uid control="not-present"/>
<dt_name control="required"/>
<dt_start_time control="required"/>
<dt_duration control="required"/>
<dt_day_pattern control="required"/>
<dt_exclude_holidays control="required"/>
</device_timeframe>
The latter specifies that the owning device external key is a required field, and ignores the Device name and owner user
ID.
Alternately, if you are using the second method above (i.e., by the Device Type and Device Name), the same element
should be similar to the following:
<device_timeframe>
<dt_owning_device_key control="not-present"/>
<dt_owning_device_name control="required"/>
<dt_owning_device_owner_uid control="required"/>
</device_timeframe>
Exports
Because xMatters includes all Device information, you can leave the configuration file as delivered; the <device_
timeframe> element would be similar to the following:
<device_timeframe>
<dt_owning_device_key control="optional"/>
<dt_owning_device_name control="optional"/>
<dt_owning_device_owner_uid control="optional"/>
</device_timeframe>
ds_email_devices Table
The ds_email_devices table contains information necessary to create and maintain email devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
ADDRESS
VARCHAR2 (100)
Email address for this Device.

This value is specified on the Users
Email Device Details page in the
USER_KEY
VARCHAR2 (250)
The external key for the User who

owns this Device.
Column Name
Null
Data Type
Comments
DEVICE_NAME
VARCHAR2 (100)

selected from the organizations defined
Device names). Standard values are
Work Email and Home Email.
VARCHAR2 (100)
Service provider for this Device (must

be selected from a list associated with
the organization). Standard values are
SMTP Email and MAPI Email.
The xMatters super administrator
specifies in the web user interface
which User Service Providers are
available (Admin > User Service
Providers).
STATUS
VARCHAR2 (30)
Indicates whether this Device is active

or inactive (ACTIVE or INACTIVE;
case-sensitive).
DEFAULT_DEVICE
CHAR (1)
Indicates whether this Device is a

Default Device (Y or N).
DEVICE_ORDER
VARCHAR2 (38)

Users Devices. The list starts at 0
(zero).
DELAY
VARCHAR2 (38)
Integer specifying the delay in minutes

for this Device.
Column Name
Null
Data Type
Comments
LOCK_24x7
CHAR (1)

user interface whether the Timeframe
can be modified. When set to 'Y',
Timeframes are locked to be on a 24
hour/day, 7 day/week schedule.
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_event_domain_predicates Table
The ds_event_domain_predicates table contains information necessary to create and maintain Event Domain Predicates
in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
EVENT_DOMAIN_KEY
VARCHAR2 (250)
The Event Domain that this Predicate falls

under (by external key).
PREDICATE_NAME
VARCHAR2 (100)
Name of the Predicate.
PREDICATE_TYPE
VARCHAR2 (100)
Specifies the type of this Predicate;

available choices are: STRING,
BOOLEAN, INTEGER, FLOAT and LIST.
RANKING
VARCHAR2 (38)
Specifies the ranking number for predicates.
IMPORTANT
CHAR (1)
Specifies whether the predicate is important

(value is Y or N). This flag affects
reports generated for notifications.
IS_EXTERNALLY_OWNED
CHAR (1)

owned.
ALARMPOINT_ACTION
CHAR (1)

LAST_SYNC_DATE
TIMESTAMP (6)
ds_generic_devices Table
The ds_generic_devices table contains information necessary to create and maintain Generic Devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
PIN
VARCHAR2 (100)
The PIN associated with this Generic

Device.
USER_KEY
VARCHAR2 (250)
The external_key for the User who owns

this Device.
DEVICE_NAME
VARCHAR2 (100)

selected from the organization's defined
Device names).
VARCHAR2 (100)
Service provider for this Device (must be

selected from a list associated with the
organization).
specifies in the web user interface which
User Service Providers are available
(Admin > User Service Providers).
STATUS
VARCHAR2 (30)
Indicates whether this Device is active or

DEFAULT_DEVICE
CHAR (1)
Indicates whether this Device is a Default

Device (Y or N).
DEVICE_ORDER
VARCHAR2 (38)

User's Devices. The list starts at 0 (zero).
Column Name
Null
Data Type
Comments
DELAY
VARCHAR2 (38)

for this Device.
LOCK_24x7
CHAR (1)

user interface whether the Timeframe can
be modified. When set to 'Y', Timeframes
are locked to be on a 24 hour/day, 7
day/week schedule.
IS_EXTERNALLY_OWNED
CHAR (1)

owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_groups Table
The ds_groups table contains information necessary to create and maintain Groups in xMatters:
ds_groups Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
GROUP_NAME
VARCHAR2 (100)
Target name that outside systems use

to identify this Group.
Note that a value in this column must
not match any USER_ID value in the
ds_users table.
DESCRIPTION
VARCHAR2 (200)
Description of the Group.

This value is specified on the Group
Details page in the xMatters web user
interface.
STATUS
VARCHAR2 (30)
Indicates whether this Group is active

case-sensitive).
interface.
Column Name
Null
Data Type
Comments
USE_DEFAULT_DEVICES
CHAR (1)
Specifies whether to use Default

Devices (Y or N).
interface.
TIMEZONE
VARCHAR2 (100)
Name of the time zone for this

Group.
which time zones are available
(Admin > Time Zones).
GROUP_SITE_NAME
VARCHAR2 (100)
External key for the Site the Group

uses for Site Holidays.
OBSERVED_BY_ALL
CHAR (1)
Indicates whether all Roles can

observe this Group (Y or N).
Note: if this field is set to Y, values
specified in OBSERVER_LIST will
be ignored.
OBSERVER_LIST
VARCHAR2 (2000)
Comma-separated list of Users (by

external key) who are Group
Observers for this Group (casesensitive). The <<<NONE>>> token
can be used with this field.
SUPERVISOR_LIST
VARCHAR2 (2000)

external key) who are Group
Supervisors for this Group (casesensitive). The <<<NONE>>> token
can be used with this field. A NULL
value with control of optional is
equivalent to setting
overwrite=false.
ALLOW_DUPLICATES
VARCHAR2 (30)
Indicates whether to allow duplicate

notifications (Y or N).
interface.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_holiday_coverages Table
The ds_holiday_coverages table contains information necessary to create and maintain Holiday Only Coverages in
xMatters::
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
OWNING_GROUP_KEY
VARCHAR2 (250)
The external_key for the Group that owns this

Holiday Coverage. This Group must have a Site
defined for it.
COVERAGE_NAME
VARCHAR2 (100)
The name of this Coverage. The Coverage name

must be unique within the Group to which it
belongs.
START_DATE
VARCHAR2 (10)
Date on which this Coverage begins. The format

is yyyy/MM/dd (e.g., 2007/05/15). If this value
null, the default start date is the synchronization
date.
START_TIME
VARCHAR2(5)
Time at which this Coverage begins on each

recurrence. The format for this field is HH:mm
(e.g., 18:00). The Group that owns this
Coverage determines the time zone.
DURATION
VARCHAR2 (77)
Duration of each occurrence of this Coverage in

the format HH:mm. For example, a setting of
08:00 means that each occurrence of this
Coverage lasts for eight hours.
RECURRENCE_END
VARCHAR2 (38)
Specifies date after which no Holidays will be

scheduled. This value can take on three formats:
NULL implies no end; INTEGER controls the
number of recurrences before ending; and, an
end date in the format yyyy/MM/dd.
WORK_TEAM_KEY
VARCHAR2 (250)
Specifies the Work Team (by external key) for

this Coverage.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_im_devices Table
The ds_im_devices table contains information necessary to create and maintain instant messaging Devices in xMatters:
ds_im_devices Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
ADDRESS
VARCHAR2 (100)
Instant messaging address for this

Device.
Instant Messaging Device Details page
in the xMatters web user interface.
USER_KEY
VARCHAR2 (250)
The external_key for the User who

owns this Device.
DEVICE_NAME
VARCHAR2 (100)

selected from the organizations
defined Device names). Standard value
for this is Instant Messaging.
web user interface which Device
names are available (Admin > Device
Types).
VARCHAR2 (100)

the organization). Standard value for
this is Instant Messaging.
Providers).
STATUS
VARCHAR2 (30)

case-sensitive).
DEFAULT_DEVICE
CHAR (1)

Column Name
Null
Data Type
Comments
DEVICE_ORDER
VARCHAR2 (38)
Integer sequence number specifying

the order of the Device in the list of
this Users Devices. The list starts at 0
(zero).
DELAY
VARCHAR2 (38)
Integer specifying the delay in minutes

for this Device.
LOCK_24x7
CHAR (1)

IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_numeric_pager_devices Table
The ds_numeric_pager_devices table contains information necessary to create and maintain numeric pager Devices in
xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
COUNTRY
VARCHAR2 (100)
The country name to use when dialing

this Device.
Numeric Pager Device Details page in
Column Name
Null
Data Type
Comments
PIN
VARCHAR2 (100)
The PIN (Personal Identification

Number) for this Device (non-negative
integers only).
AREA_CODE
VARCHAR2 (100)
The area code for dialing this Device.

PHONE_NUMBER
VARCHAR2 (100)
The phone number for dialing this

Device (non-negative integers only).
USER_KEY
VARCHAR2 (250)

owns this Device.
DEVICE_NAME
VARCHAR2 (100)

for this is Numeric Pager.
web user interface which Device
names are available (Admin > Device
Types).
VARCHAR2 (100)

the organization). An example value
for this is SkyPage Numeric Pager.
Providers).
Column Name
Null
Data Type
Comments
STATUS
VARCHAR2 (30)

case-sensitive).
DEFAULT_DEVICE
CHAR (1)
Indicates whether this Device is an

DEVICE_ORDER
VARCHAR2 (38)
Integer sequence number specifying

the order of the Device in the list of
this Users Devices. The list starts at 0
(zero).
DELAY
VARCHAR2 (38)
Integer specifying the Delay in

minutes for this Device.
LOCK_24x7
CHAR (1)

IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_person_supervisor Table
The ds_person_supervisor table contains information necessary to associate Users with their Supervisors:
Column Name
Null
Data Type
Comments
USER_EXTERNAL_KEY
VARCHAR2 (250)
Specifies the User to be targeted for

assigning Supervisors (by external key).
PERSON_SUPERVISOR_LIST
VARCHAR2 (2000)

external key) who will become
supervisor of the User identified in the
USER_EXTERNAL_KEY field. The
<<<NONE>> token can be used with
this field to indicate that this User has
no supervisor.
IS_EXTERNALLY_OWNED
CHAR (1)
Specifies whether this relationship is

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_recurrent_coverages Table
The ds_recurrent_coverages table contains information necessary to create and maintain Recurrent Coverages in
xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
OWNING_GROUP_KEY
VARCHAR2 (250)
The external_key for the Group that owns this

Recurrent Coverage.
COVERAGE_NAME
VARCHAR2 (100)
The name of this Coverage. The Coverage name

must be unique within the Group to which it
belongs.
START_DATE
VARCHAR2 (10)
Date on which this Coverage begins. The format

is yyyy/MM/dd (e.g., 2007/05/15). If this value
null, the default start date is the synchronization
date.
START_TIME
VARCHAR2(5)
Time at which this Coverage begins on each

recurrence. The format for this field is HH:mm
(e.g., 18:00). The Group that owns this
Coverage determines the time zone.
Column Name
Null
Data Type
Comments
DURATION
VARCHAR2 (77)
Duration of each occurrence of this Coverage in

the format HH:mm. For example, a setting of
08:00 means that each occurrence of this
Coverage lasts for eight hours.
DAY_PATTERN
VARCHAR2 (62)
Comma-delimited list of days of the week on

which this Coverage is in effect; values are the
names of the days of the week (i.e., Sunday,
Monday, Tuesday, Wednesday, Thursday,
Friday, Saturday). For example, a Coverage in
effect from Monday to Friday will have the
following value: Monday, Tuesday,
Wednesday, Thursday, Friday. This field
cannot take the value of <<<NONE>>>.
FREQUENCY
VARCHAR2 (10)
The frequency at which this Coverage recurs;

values are Monthly, Weekly and Daily.
INTERVAL
VARCHAR2 (38)
Specifies an integer multiple for the

FREQUENCY (e.g., "3 Weeks", where "3" is the
INTERVAL and "Weeks" is the FREQUENCY).
INCLUDE_SITE_
HOLIDAYS
BOOLEAN
Adds Site Holidays to the Coverage (i.e., based

on the Site associated with the Group).
RECURRENCE_END
VARCHAR2 (38)
Specifies when this Coverage will stop

recurring. This value can take on three formats:
NULL implies no end; INTEGER controls the
number of recurrences before ending; and, an
end date in the format yyyy/MM/dd.
WORK_TEAM_KEY
VARCHAR2 (250)
Specifies the Work Team (by external key) for

this Coverage.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_sites Table
The ds_sites table contains information necessary to create and maintain Sites in xMatters:
ds_sites Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
Column Name
Null
Data Type
Comments
SITENAME
VARCHAR2 (100)
Name of the site about to be

synchronized. This value is specified
on the Site Details page in the
SITE_STATUS
VARCHAR2 (30)
Indicates whether this Site is active or

inactive (ACTIVE or INACTIVE;
case-sensitive).
SITE_LANGUAGE
VARCHAR2 (100)
The Site language (name of an

existing Language used in the
organization) controls the default
language for Users within this Site.
SITE_TIMEZONE
VARCHAR2 (100)
The Site Time Zone (name of an

existing Time Zone used in the
organization) controls the default
Time Zone for Users within this Site.
SITE_ADDRESS_01
VARCHAR2 (100)
Line 1 of Site's address.
SITE_ADDRESS_02
VARCHAR2 (100)
Line 2 of Site's address
SITE_CITY
VARCHAR2 (100)
The city to which this Site belongs.
SITE_COUNTRY
VARCHAR2 (100)
Country in which this Site resides. If

specified, the value must correspond
to the name of a Country that is
available to the organization.
SITE_REGION_NAME
VARCHAR2 (100)
Region in which this Site resides.
SITE_MAIL_CODE
VARCHAR2 (10)
Mail code for Site.
SITE_CLUSTER_01
VARCHAR2 (100)
Notification Servers are in a logical

group of Clusters. This field specifies
which Cluster to use.
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)

LAST_SYNC_DATE
TIMESTAMP (6)
ds_team_memberships Table
The ds_team_membership table contains information necessary to create and maintain Team memberships in xMatters:
Column Name
Null
Data Type
Comments
TEAM_KEY
VARCHAR2 (250)
The external_key for this records

Team.
MEMBER_KEY
VARCHAR2 (250)
The external_key that identifies

this member.
Note that this may be a key for a
User, Group, Team, or Device.
MEMBER_TYPE
VARCHAR2 (30)
Specifies the object type for this

member (GROUP, TEAM,
PERSON, or DEVICE).
MEMBER_SUB_TYPE
VARCHAR2 (30)
Specifies the type of Device

(EMAIL, VOICE, TEXT_PHONE,
TEXT_PAGER, NUMERIC_
PAGER, or IM).
MEMBER_SEQUENCE_NUMBER
VARCHAR2 (38)
Integer sequence number

specifying the order in which this
member appears in the Team.
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)

and "External Keys Assigned via
the Web User Interface" on page
382.
LAST_SYNC_DATE
TIMESTAMP (6)
ds_teams Table
The ds_teams table contains information necessary to create and maintain Teams in xMatters:
ds_teams Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)

Note that all Teams, regardless of the
Group to which they belong, require a
unique key. It is recommended that
external_key value for a Team also
includes the external_key for the
Group to which it belongs.
Column Name
Null
Data Type
Comments
GROUP_KEY
VARCHAR2 (250)
The external_key for the Group that

owns this Team.
SUB_TARGET_NAME
VARCHAR2 (100)
Additional name the external systems

use to identify this Team within the
Group.
DESCRIPTION
VARCHAR2 (200)
Description of the Team.

This value is specified on the Team
interface.
USE_DEFAULT_DEVICES
CHAR (1)
Indicates whether to use Default

Devices (Y or N).
interface.
ESCALATION_SCHEDULE
VARCHAR2 (100)
Comma-separated list of integers

specifying the escalation schedule for
this Team.
This value is specified on a Groups
Coverage page in the xMatters web
user interface (each comma-separated
integer refers to the Wait (min) setting
associated with a Team member).
IS_ROUND_ROBIN
CHAR (1)
Indicates whether this is a Round

Robin Team (Y or N).
This value is specified on the Team
interface.
ADD_24X7_COVERAGE
CHAR (1)
If a Team does not exist, or does not

have a schedule associated with it,
then a 24x7 schedule will be added.
If there is no schedule for the team,
the Team cannot be notified (note that
a schedule can be added to the Team
in the web user interface after the data
synchronization is complete).
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
Column Name
Null
Data Type
Comments
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
Note:
Data Synchronization supports only Basic and Event Round Robin Teams; Rotation Teams are not supported.
ds_text_pager_devices Table
The ds_text_pager_devices table contains information necessary to create and maintain text pager Devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
PIN
VARCHAR2 (100)
The PIN (Personal Identification

Number) for this Device (non-negative
integers only).
Text Pager Device Details page in the
IS_TWO_WAY
CHAR (1)
Indicates whether this is a two-way

text pager (Y or N; case-insensitive).
USER_KEY
VARCHAR2 (250)
The external_key for the user who

owns this device.
DEVICE_NAME
VARCHAR2 (100)

for this is Pager.
Column Name
Null
Data Type
Comments
VARCHAR2 (100)

for this is GSM modem 2-way.
Providers).
STATUS
VARCHAR2 (30)

case-sensitive).
DEFAULT_DEVICE
CHAR (1)

DEVICE_ORDER
VARCHAR2 (38)

(zero).
DELAY
VARCHAR2 (38)

for this Device.
LOCK_24x7
CHAR (1)

IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_text_phone_devices Table
The ds_text_phone_devices table contains information necessary to create and maintain text phone Devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
TARGET_NUMBER
VARCHAR2 (100)
The target number for this Device

(non-negative integers only).
COUNTRY_CODE
VARCHAR2 (3)
The two-letter country code for this

Device. If not specified, the default is
to not set the country code override for
this Device, and to use the Site's
country code if required.
USER_KEY
VARCHAR2 (250)

owns this Device.
DEVICE_NAME
VARCHAR2 (100)

for this is SMS Phone.
VARCHAR2 (100)

for this is Cingular.
Providers).
STATUS
VARCHAR2 (30)

case-sensitive).
Text Phone Device Details page in the
Column Name
Null
Data Type
Comments
DEFAULT_DEVICE
CHAR (1)

DEVICE_ORDER
VARCHAR2 (38)

(zero).
DELAY
VARCHAR2 (38)

for this Device.
LOCK_24x7
CHAR (1)

IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
ds_user_custom_values Table
The ds_user_custom_values table contains information necessary to create and maintain relations between User and
Custom Field values in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
CUSTOM_USER_KEY
VARCHAR2 (250)
The User that this association is for (by

external key).
FIELD_KEY
VARCHAR2 (250)
The Custom Field for this association (by

external key)
Column Name
Null
Data Type
Comments
CUSTOM_VALUE
VARCHAR2 (100)
The value to set for this Custom Field

against the specified User.
IS_EXTERNALLY_OWNED
CHAR (1)

owned.
ALARMPOINT_ACTION
CHAR (1)

LAST_SYNC_DATE
TIMESTAMP (6)
ds_user_join_attributes Table
The ds_user_join_attributes table contains information necessary to associate User with User Attributes:
Column Name
Null
Data Type
Comments
USER_EXTERNAL_KEY
VARCHAR2 (250)
Specifies the User to be targeted for

Custom Attribute association (by
external key).
ATTRIBUTE_EXTERNAL_KEY
VARCHAR2 (250)
Specifies the Custom Attribute to be

associated with the User (by external
key).
ds_users Table
The ds_users table contains information necessary to create and maintain Users in xMatters:
ds_users Table
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
SITE_NAME
VARCHAR2 (100)
The Users Site (by external_key).

interface.
Column Name
Null
Data Type
Comments
ROLE_LIST
VARCHAR2 (2000)
Comma-separated list of Roles (by name)

for the User. Replaces all current Roles
for the User.
web user interface which Roles are
available (Admin > Roles).
STATUS
VARCHAR2 (30)
Indicates whether this User is active or

interface.
LAST_NAME
VARCHAR2 (100)
Users last name.

interface.
FIRST_NAME
VARCHAR2 (100)
Users first name.

interface.
LANGUAGE_OVERRIDE
VARCHAR2 (100)
If present, the name of the Users

preferred language for web user interface
and Device interaction. If not present,
the language specified for the Users Site
is used.
Company Administrator specifies in the
web user interface which languages are
available (Admin > Languages).
TIMEZONE_OVERRIDE
VARCHAR2 (100)
If present, the name of the Timezone

used for date and time information
presentation. If not present, the
Timezone specified for the Users Site is
used.
web user interface which time zones are
available (Admin > Time Zones).
Column Name
Null
Data Type
Comments
RECORDED_NAME
VARCHAR2 (100)
Recorded (Phone) name for this User.

interface (User ID).
It is recommended that the
RECORDED_NAME value match the
USER_ID value.
WEB_LOGIN_TYPE
VARCHAR2 (100)
The web login type for the User

(NATIVE, LDAP, or SSO).
Change Web Login page in the xMatters
web user interface (Authentication).
WEB_LOGIN
VARCHAR2 (100)
The web login user name for the User.

web user interface.
WEB_PASSWORD
VARCHAR2 (100)
The web login password for the User.

web user interface.
NOTE: Password fields are encrypted in
xMatters, and password columns in the
Staging Area populated by a Data
Synchronization export are in the
encrypted format. During
synchronization update-import, password
fields are never updated (i.e.,
overwrite='false'). During
synchronization insert-import, passwords
stored in the Staging Area are in plain
text (i.e., unencrypted) and the password
will be set on the imported object.
LDAP_DOMAIN
VARCHAR2 (100)
The LDAP domain name to use when

the User's login method is through
LDAP authentication.
web user interface.
Column Name
Null
Data Type
Comments
PHONE_LOGIN
VARCHAR2 (100)
The phone login user name for the User.

Change Phone Login page in the
PHONE_PASSWORD
VARCHAR2 (30)
The phone password for the User.

Change Phone Login page in the
NOTE: Password fields are encrypted in
xMatters, and password columns in the
Staging Area populated by a Data
Synchronization export are in the
encrypted format. During
synchronization update-import, password
fields are never updated (i.e.,
overwrite='false'). During
synchronization insert-import, passwords
stored in the Staging Area are in plain
text (i.e., unencrypted) and the password
will be set on the imported object.
USER_ID
VARCHAR2 (100)
Target name that outside systems use to

identify the User.
Note that a value in this column must
not match any GROUP_NAME value in
the ds_groups table.
IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
HAS_MOBILE_ACCESS
CHAR (1)
Specifies whether the User has access to

the mobile access component.
ds_voice_devices Table
The ds_voice_devices table contains information necessary to create and maintain voice Devices in xMatters:
Column Name
Null
Data Type
Comments
EXTERNAL_KEY
VARCHAR2 (250)
COUNTRY
VARCHAR2 (100)
The country name to use when dialing

this Device.
Voice Device Details page in the
AREA_CODE
VARCHAR2 (10)
Area code to use when dialing this

Device (non-negative integers only).
PHONE_NUMBER
VARCHAR2 (30)
The phone number for dialing this

Device (valid characters: 0123456789()
+-.<space>).
EXTENSION
VARCHAR2 (10)
Phone extension to use when dialing

this Device (must be 10 or fewer
characters).
USER_KEY
VARCHAR2 (250)
The external_key for the user who

owns this device.
DEVICE_NAME
VARCHAR2 (100)

defined Device names). Standard
values for this are Office Phone or
Home Phone.
Column Name
Null
Data Type
Comments
VARCHAR2 (100)
Service Provider for this Device (must

the organization). The standard value
for this is Phone Engine.
Providers).
STATUS
VARCHAR2 (30)

case-sensitive).
DEFAULT_DEVICE
CHAR (1)

DEVICE_ORDER
VARCHAR2 (38)

(zero).
DELAY
VARCHAR2 (38)

for this Device.
LOCK_24x7
CHAR (1)

IS_EXTERNALLY_OWNED
CHAR (1)

externally owned.
ALARMPOINT_ACTION
CHAR (1)
LAST_SYNC_DATE
TIMESTAMP (6)
The Configuration File

The configuration file is an XML document that specifies the tasks the Data Synchronization module performs (see
"Example Configuration" on page 431). This document is fully XML 1.0 compliant and specified by an XML Schema.
The following sections provide details for each element in the configuration file.
alarmpoint-synchronization Element
The alarmpoint-synchronization element is the base element in the configuration file. This element has a list of company
Elements and two attributes, summarized in the following table:
alarmpoint-synchronization Element Attributes
Attribute
Mandatory
Description
target
Specifies what area (Staging Area or xMatters database) the data synchronization
affects. The accepted values are "alarmpoint" and "staging".
failure_limit
Specifies a maximum number of errors that the synchronization process will

tolerate. If the process generates more than the maximum number of errors,
processing halts. For example, if the failure_limit is set to 0, the first error
encountered will halt processing.
Both attributes must be supplied.
company Element
The system supports one company element, which contains directions for synchronizing a Company. The following table
summarizes the attributes for the company element:
company Element Attribute
Attribute
Mandatory
Description
name
Specifies the name of the organization that is the target of the synchronization
process. This case-sensitive value must exactly match the name of the organization
in the xMatters database.
one_db
Controls whether the Staging Area is present in the xMatters database or in

another database. The default value true specifies that the <staging_area> element
should not be present or supplied on the command line; a value of false specifies
that the <staging_area> element should be present or that the path to the
properties file will be supplied on the command line.
user
Specifies which User will be logged as responsible for all actions taken by the
synchronization process. This attribute should take on a value that corresponds to
an external key or target name of an existing User within xMatters
The company element can also include the optional staging_area element (for details, see "staging_area Element",
below), followed by a list of table elements. At least one table element must appear, in the following order:
The Configuration File | 414
<site>
<attribute_category>
<attribute>
<custom_field>
<user>
<user_custom_value>
<person_supervisor>
<email>
<im>
<text_pager>
<numeric_pager>
<voice>
<text_phone>
<generic_device>
<bes_device>
<group>
<team>
<team_membership>
<recurrent_coverages>
<holiday_coverages>
<device_timeframe>
<event_domain_predicate>
Only table elements specified in the configuration file will be synchronized; remaining tables elements and their
associated staging tables will be ignored.
staging_area Element
This element should be present only when one_db is set to false.
If the staging_area element is present, then you must specify the properties_file attribute. The path and file name must
have the following syntax:
<staging_area properties_file="assets/config/alarmpoint-synchronizer.properties" />
Note:
Due to classpath concerns, the name common.properties is reserved and unexpected behavior will occur if a
name of common.properties is entered here.
The alarmpoint-synchronizer.properties file contains the information necessary to connect to the Company
staging area, as summarized in the following table:
alarmpoint-synchronizer.properties Settings
Setting
Mandatory
Description
JDBC_DRIVER_CLASS_NAME=
Specifies which JDBC driver to use. For an Oracle

database, this should be
oracle.jdbc.driver.OracleDriver. For an SQL Server
database, this should be
net.sourceforge.jtds.jdbc.Driver.
JDBC_URL=
Specifies the JDBC URL to access the database. For

an Oracle database, this should be of the following
form: jdbc:oracle:thin:@<host>:<port>:<sid>.
For an SQL Server database, this should be of the
following form: jdbc:jtds:sqlserver://
<host>:<port>.
Setting
Mandatory
Description
JDBC_USERNAME=
Specifies the user name used to log on to the

database. This User must be able to select from and
modify the data in the staging tables.
JDBC_PASSWORD=
Specifies the password used to log on to the database.
Note:
By default, the alarmpoint-synchronizer.properties file is not encrypted. If you would like to encrypt the
file for security reasons, you can use the APSecure.bat tool (see the next section for details).
By default, the values in the file are configured as follows:

JDBC_DRIVER_CLASS_NAME=%%%JDBC_CLASS%%%
JDBC_URL=%%%JDBC_URL%%%
JDBC_USERNAME=%%%JDBC_USER%%%
JDBC_PASSWORD=%%%JDBC_PASSWORD%%%
To point this file to a different staging area, replace the %%%JDBC_CLASS%%%, %%%JDBC_URL%%%, and so on
with values that point to the desired staging area.
Encrypting/Decrypting alarmpoint-synchronizer.properties
By default, the alarmpoint-synchronizer.properties file is not encrypted. However, you can use the APSecure
tool to encrypt and decrypt this file.
The command line syntax for running APSecure is as follows:
n
Windows: APSecure.bat <operation> <infile> <outfile>
Unix: ./APSecure.sh <operation> <infile> <outfile>
The following table summarizes the command line parameters:

Parameter
Description
<operation>
Must be either encrypt or decrypt; mandatory.
<infile>
File to decrypt or encrypt; mandatory, and must already exist.
<outfile>
File that is the target for the decrypted or encrypted file; mandatory.
Table Elements and Related Field Elements

Each table element has an ordered list of field elements and the following attribute:
Table Element Attribute
Attribute
Mandatory
Description
stage_table
Allows the use of a staging table (or updatable view) other than the default.
The following table gives the default table name for each table element:
XML Table Element Default Table Names

Table Element
Default Table Name
site
DS_SITE
attribute_category
DS_ATTRIBUTE_CATEGORIES
attribute
DS_ATTRIBUTES
custom_field
DS_CUSTOM_FIELDS
user
DS_USERS
user_custom_value
DS_USER_CUSTOM_VALUES
person_supervisor
DS_PERSON_SUPERVISORS
email
DS_EMAIL_DEVICES
im
DS_IM_DEVICES
textpager
DS_TEXT_PAGER_DEVICES
numeric_pager
DS_NUMERIC_PAGER_DEVICES
voice
DS_VOICE_DEVICES
text_phone
DS_TEXT_PHONE_DEVICES
generic_device
DS_GENERIC_DEVICES
bes_device
DS_BES_DEVICES
group
DS_GROUPS
team
DS_TEAMS
team_membership
DS_TEAM_MEMBERSHIPS
recurrent_coverages
DS_RECURRENT_COVERAGES
holiday_coverages
DS_HOLIDAY_COVERAGES
device_timeframe
DS_DEVICE_TIMEFRAMES
event_domain_predicate
DS_EVENT_DOMAIN_PREDICATES
The list of field elements for each table has a fixed order; however, some field elements may not appear.
Field elements
Each field element may have up to four attributes that control field behavior during synchronization: control, overwrite,
stage_name, and default.
Control Attribute
The control attribute must be present on every field element, and can have one of three values, as summarized in the
following table:
Field Element control attribute meanings
control value
Description
required
Indicates that a value must be present for this field in every row during synchronization, either
in the staging table or a default value from the field element.
optional
Indicates that a value may be present for this field during synchronization, either in the
staging table or a default value from the field element.
If no value is specified in the staging table, then any value in the xMatters database will not
be changed. This means that there is no way to clear optional fields in the xMatters database.
not-present
Note:
Indicates that no value for this field is present in the staging area, but a value may be provided
by a default value from the field element.
Some values are not allowed on some field elements.
Overwrite Attribute
The overwrite attribute controls the behavior when the record already exists in the xMatters database (i.e., there is a
record with the corresponding external_key value).
Overwrite attribute values
overwrite Value
Value Description
true
Indicates that the value specified in the Staging Area always overwrites data in xMatters
for the entity matched by external_key.
false
Indicates that the synchronization process will not change the value in xMatters. If no
match is found for external_key in xMatters, a new entry will be created.
For example, the following illustrates how to set the device_order element so it will not override an existing value in
xMatters:
<device_order control="required" overwrite="false"/>
Default Attribute
The default attribute allows specification of a default value for the field. This value will be used if the value in the
staging area is empty or not present. Some field elements will not allow this attribute.
Field Element Default Attribute

Default Value
Description
value
The specified value is used as the default. For example:

<ldap_domain default="LDAP_PORTAL"/>
indicates that if ldap_domain is empty for a particular row in the Staging Area, then the
value LDAP_PORTAL will be used.
Stage Name Attribute
The stage_name attribute allows specification of a different name in the Staging Area for the field element. By default,
the field element column in the Staging Area is the same as the field element.
Field Element stage_name Attribute
stage_name Value
Description
value
The specified value corresponds with the field name in the Staging Area. For example:
<ldap_domain stage_name="PORTAL"/>
indicates that the system can retrieve ldap_domain from the Staging Area under the field
name of PORTAL.
Note:
Note that the field elements are never attached to the alarmpoint_action and last_sync_date staging fields.
They must have those names in the staging area.
The Specific Table Elements

The following sections include tables that list each field element for the related element. The field elements are in order,
and the tables include information about which control values apply, whether default is allowed, and whether the field
element must appear.
attribute Element
The attribute element has the following fields:
attribute Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always false
No
Yes
attribute_name
Required
True or False
No
Yes
attribute_category_key
Required
True or False
No
Yes
attribute_category Element
The attribute_category element has the following fields:
attribute_category Element Field Elements

Field name
Control
Overwrite
Default
Required
external_key
Required
Always false
No
Yes
category_name
Required
True or False
No
Yes
bes_device Element
The bes_device element has the following fields:
bes_device Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
service_provider_name
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
address
Required
True or False
Yes
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
custom_field Element
The custom_field element has the following fields:
custom_field Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always false
No
Yes
custom_field_name
Required
True or False
No
Yes
custom_field_type
Required
True or False
Yes
Yes
custom_field_mandatory
Required
True or False
Yes
Yes
Field name
Control
Overwrite
Default
Required
custom_field_max
Required or Optional
True or False
Yes
No
custom_field_min
True or False
Yes
No
field_values*
Optional
N/A
No
No
Note:
The field_values field controls the processing of a joined table (DS_CUSTOM_FIELD_JOIN_VALUES) that
should contain all Custom Field Values that are to be associated with each Custom Field.
device_timeframe Element
The device_timeframe element has the following fields::
device_timeframe Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
dt_owning_device_key
Required
True or False
No
Yes
dt_owning_device_type
Required
True or False
No
Yes
dt_name
Required
True or False
No
Yes
dt_start_time
Required
True or False
Yes
Yes
dt_duration
Required
True or False
Yes
Yes
dt_day_pattern
True or False
Yes
Yes
dt_exclude_holidays
True or False
Yes
Yes
email Element
The email element has the following fields:
email Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
Field name
Control
Overwrite
Default
Required
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
address
Required
True or False
Yes
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
event_domain_predicate Element
The event_domain_predicate element has the following fields:
event_domain_predicate Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
predicate_name
Required
True or False
No
Yes
predicate_type
Required
True or False
Yes
Yes
ranking
True or False
No
Yes
important
True or False
Yes
No
predicate_value*
Optional
N/A
N/A
No
event_domain_key
Required
True or False
Yes
Yes
Note:
The predicate_value field controls the processing of a joined table (DS_PREDICATE_JOIN_VALUES) that
should contain all Predicate Values that are to be associated with each Event Domain Predicate.
generic Element
The generic_device element has the following fields:
generic_device Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
Field name
Control
Overwrite
Default
Required
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
pin
Required
True or False
Yes
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
group Element
The group element has the following fields:
group Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
group_name
Required
True or False
No
Yes
description
True or False
Yes
No
status
Required
True or False
Yes
Yes
use_default_devices
Required
True or False
Yes
Yes
timezone
Required
True or False
Yes
Yes
group_site_name
Optional
True or False
No
No
allow_duplicates
Required
True or False
Yes
Yes
supervisor_list
True or False
Yes
Yes
observed_by_all
True or False
Yes
No
observer_list
True or False
Yes
Yes
holiday_coverages Element
The holiday_coverages element has the following fields:
holiday_coverages Element Field Elements

Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
owning_group_key
Required
True or False
No
Yes
coverage_name
Required
True or False
No
Yes
start_date
True or False
Yes
Yes
start_time
Required
True or False
Yes
Yes
duration
Required
True or False
Yes
Yes
recurrence_end
True or False
Yes
Yes
worker_team_key
True or False
Yes
Yes
im Element
The instant messaging element has the following fields:
im Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
address
Required
True or False
Yes
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
numeric_pager Element
The numeric_pager element has the following fields:
numeric_pager Element Field Elements

Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
country
True or False
Yes
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
pin
Required
True or False
Yes
Yes
area_code
True or False
Yes
No
phone_number
Required
Always False
No
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
person_supervisor Element
The person_supervisor element has the following fields:
person_supervisor Element Field Elements
Field name
Control
Overwrite
Default
Required
user_external_key
Required
Always false
No
Yes
person_supervisor_list
Optional
True or False
Yes
No
recurrent_coverages Element
The recurrent_coverages element has the following fields:
recurrent_coverages Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
Field name
Control
Overwrite
Default
Required
owning_group_key
Required
True or False
No
Yes
coverage_name
Required
True or False
No
Yes
start_date
True or False
Yes
Yes
start_time
Required
True or False
Yes
Yes
duration
Required
True or False
Yes
Yes
day_pattern
Required
True or False
Yes
Yes
frequency
Required
True or False
Yes
Yes
interval
Required
True or False
Yes
Yes
include_site_holidays
Required
True or False
No
Yes
recurrence_end
True or False
Yes
Yes
worker_team_key
True or False
Yes
Yes
site Element
The site element has the following fields:
site Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
sitename
Required
True or False
No
Yes
site_status
Required
True or False
Yes
Yes
site_language
Required
True or False
Yes
Yes
site_timezone
Required
True or False
Yes
Yes
site_address_01
True or False
Yes
No
site_address_02
True or False
Yes
No
site_city
True or False
Yes
No
site_country
Required
True or False
Yes
Yes
Field name
Control
Overwrite
Default
Required
site_region_name
True or False
Yes
No
site_mail_code
True or False
Yes
No
site_cluster_01
True or False
Yes
No
team Element
The team element has the following fields:
team Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
sub_target_name
Required
True or False
No
Yes
description
True or False
Yes
No
use_default_devices
Required
True or False
Yes
Yes
escalation_schedule
True or False
Yes
Yes
is_round_robin
Required
True or False
Yes
Yes
group_key
Required
Always False
Yes
Yes
add_24x7_coverage
Required
N/A
Yes
Yes
team_membership Element
The team_membership element has the following fields:
team_membership Element Field Elements
Field name
Control
Overwrite
Default
team_key
Required
N/A
Yes
member_key
Required
N/A
Yes
member_type
Required
N/A
Yes
member_sub_type
N/A
Yes
member_sequence_number
Required
N/A
Yes
text_pager Element
The text_pager element has the following fields:
text_pager Element Field Elements

Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
pin
Required
True or False
Yes
Yes
is_two_way
Required
True or False
Yes
Yes
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
text_phone Element
The text_phone element has the following fields:
text_phone Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
target_number
Required
True or False
Yes
Yes
Field name
Control
Overwrite
Default
Required
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
user Element
The user element has the following fields:
user Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
first_name
Required
True or False
Yes
Yes
last_name
Required
True or False
Yes
Yes
user_id
Required
True or False
No
Yes
site_name
Required
True or False
Yes
Yes
role_list
Required
True or False
Yes
Yes
supervisor_list
True or False
Yes
No
status
Required
True or False
Yes
Yes
language_override
True or False
Yes
No
timezone_override
True or False
Yes
No
recorded_name
True or False
Yes
No
phone_login
True or False
No
No
phone_password
True or False (Default

false)
Yes
No
web_login_type
True or False
Yes
No
web_login
True or False
No
No
web_password
True or False (Default

false)
Yes
No
ldap_domain
True or False
Yes
No
user_attributes*
Optional
N/A
No
No
user_custom_value Element
The user_custom_value element has the following fields:
user_custom_value Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always false
No
Yes
field_key
Required
True or False
No
Yes
custom_user_key
Required
True or False
No
Yes
custom_value
Required
True or False
Yes
Yes
voice Element
The voice element has the following fields:
voice Element Field Elements
Field name
Control
Overwrite
Default
Required
external_key
Required
Always False
No
Yes
country
True or False
Yes
Yes
user_key
Required
True or False
No
Yes
device_name
Required
True or False
Yes
Yes
Required
True or False
Yes
Yes
status
Required
True or False
Yes
Yes
default_device
Required
True or False
Yes
Yes
device_order
Required
True or False
No
Yes
area_code
True or False
Yes
Yes
phone_number
Required
True or False
Yes
Yes
extension
True or False
Yes
No
delay
Required
True or False
Yes
Yes
lock_24x7
Required
True or False
Yes
Yes
Example Configuration
The following is a sample data synchronization configuration file (note that the order of the XML tags in the
configuration file must appear exactly as shown):
<alarmpoint-synchronizer
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
target="alarmpoint" failure_limit="100">
<company name="Default Company" one_db="true" user="superadmin">
<site>
<sitename control="required"/>
<site_status control="required"/>
<site_language control="required"/>
<site_timezone control="required"/>
<site_address_01 control="optional"/>
<site_address_02 control="optional"/>
<site_city control="optional"/>
<site_country control="required"/>
<site_region_name control="optional"/>
<site_mail_code control="optional"/>
<site_cluster_01 control="optional"/>
</site>
<category_name control="required"/>
</attribute_category>
<attribute>
<attribute_name control="required"/>
<attribute_category_key control="required"/>
</attribute>
<custom_field>
<custom_field_name control="required"/>
<custom_field_type control="required"/>
<custom_field_mandatory control="required"/>
<custom_field_max control="optional"/>
<custom_field_min control="optional"/>
<field_values control="optional" type="joined"/>
</custom_field>
<user>
<first_name control="required"/>
<last_name control="required"/>
<user_id control="required"/>
<site_name control="required"/>
<role_list control="required" overwrite="false"/>
<status control="required"/>
<language_override control="optional"/>
<timezone_override control="optional"/>
<recorded_name control="optional"/>
<phone_login control="optional"/>
<phone_password control="optional" overwrite="false"/>
<web_login_type control="required" default="NATIVE"/>
<web_login control="optional"/>
<web_password control="optional" overwrite="false" default="password"/>
<ldap_domain control="optional"/>
<user_attributes control="optional" type="joined"/>
</user>
<user_custom_value>
<field_key control="required"/>
Example Configuration | 431
<custom_user_key control="required"/>
<custom_value control="required"/>
</user_custom_value>
<person_supervisor>
<user_external_key control="required"/>
<person_supervisor_list control="optional"/>
</person_supervisor>
<email>
<user_key control="required"/>
<device_name control="required"/>
<service_provider_name control="required"/>
<default_device control="required"/>
<device_order control="required"/>
<address control="required"/>
<delay control="required"/>
<lock_24x7 control="required"/>
</email>
<im>
</im>
<text_pager>
<pin control="required"/>
<is_two_way control="required"/>
</text_pager>
<numeric_pager>
<country control="optional"/>
<area_code control="required"/>
<phone_number control="required"/>
</numeric_pager>
<voice>
<country control="optional"/>
<area_code control="required"/>
<phone_number control="required"/>
<extension control="optional"/>
</voice>
<text_phone>
<target_number control="required"/>
</text_phone>
<generic_device>
</generic_device>
<bes_device>
</bes_device>
<group>
<group_name control="required"/>
<description control="optional"/>
<use_default_devices control="required"/>
<timezone control="required"/>
<group_site_name control="optional"/>
<allow_duplicates control="required"/>
<supervisor_list control="required"/>
<observed_by_all control="optional"/>
<observer_list control="optional"/>
</group>
<team>
<sub_target_name control="required"/>
<description control="required"/>
<use_default_devices control="required"/>
<escalation_schedule control="required"/>
<is_round_robin control="required"/>
<group_key control="required"/>
<add_24x7_coverage control="required" default="Y"/>
</team>
<team_membership>
<team_key control="required"/>
<member_key control="required"/>
<member_type control="required"/>
<member_sub_type control="optional"/>
<member_sequence_number control="required"/>
</team_membership>
<recurrent_coverages>
<owning_group_key control="required"/>
<coverage_name control="required"/>
<start_date control="optional"/>
<start_time control="required"/>
<duration control="required"/>
<day_pattern control="required"/>
<frequency control="required"/>
<interval control="required"/>
<include_site_holidays control="required"/>
<recurrence_end control="optional"/>
<worker_team_key control="optional"/>
</recurrent_coverages>
<holiday_coverages>
<owning_group_key control="required"/>
<coverage_name control="required"/>
<start_date control="optional"/>
<start_time control="required"/>
<duration control="required"/>
<recurrence_end control="optional"/>
<worker_team_key control="optional"/>
</holiday_coverages>
<device_timeframe>
<dt_owning_device_key control="required"/>
</device_timeframe>
<event_domain_predicate>
<predicate_name control="required"/>
<predicate_type control="required"/>
<ranking control="optional"/>
<important control="optional"/>
<predicate_value control="optional" type="joined"/>
<event_domain_key control="required"/>
</event_domain_predicate>
</company>
</alarmpoint-synchronizer>

The command for data synchronization is:
DataSync.bat -f <config_file> -P <staging_area_properties_file>
Note:
Due to classpath issues, the properties file specified here cannot be named common.properties.
Data Synchronization Command | 434
Data Synchronization Command Flags

Flag
Description
-f
Specifies the XML configuration file; required for each data synchronization process.
-P
Optional flag that specifies the Staging Area properties file. If used, it overrides all settings in the
configuration file with the values in the properties file.
Note: the -P value overrides the one_db attribute specified in the configuration file. For example, if
the -P parameter is specified, then its value will be used even when one_db is set to true.
The following table summarizes the return codes:

Data Synchronization Command Return Codes
Return Code
Meaning
Indicates that data synchronization ran successfully.

Note that success is indicated if the process completes, even if some rows fail.
Any non-zero value
Indicates complete failure of data synchronization (e.g., due to problems with the
configuration file, or because the error failure limit was reached).
Command Line report

When the command line completes, it produces a standard output report of the process. The following is a sample
command line report:
======================================
Data-Synchronization Report
======================================
Company : Default Company
Tables :
: DS_SITES
Success : 2
Partial : 0
Failure : 0
: DS_ATTRIBUTE_CATEGORIES
Success : 2
Partial : 0
Failure : 0
: DS_ATTRIBUTES
Success : 5
Partial : 0
Failure : 0
: DS_CUSTOM_FIELDS
Success : 5
Partial : 0
Failure : 0
: DS_USERS
Success : 54
Partial : 0
Failure : 0
: DS_USER_CUSTOM_VALUES
Success : 57
Partial : 0
Failure : 0
: DS_PERSON_SUPERVISORS
Success : 54
Partial : 0
Failure : 0
: DS_EMAIL_DEVICES
Success : 44
Partial : 0
Failure : 0
: DS_IM_DEVICES
Success : 0
Partial : 0
Failure : 0
: DS_TEXT_PAGER_DEVICES
Success : 7
Partial : 0
Failure : 0
: DS_NUMERIC_PAGER_DEVICES
Success : 1
Partial : 0
Failure : 0
: DS_VOICE_DEVICES
Success : 8
Partial : 0
Failure : 0
: DS_TEXT_PHONE_DEVICES
Success : 5
Partial : 0
Failure : 0
: DS_GENERIC_DEVICES
Success : 0
Partial : 0
Failure : 0
: DS_BES_DEVICES
Success : 2
Partial : 0
Failure : 0
: DS_GROUPS
Success : 8
Partial : 0
Failure : 0
: DS_TEAMS
Success : 12
Partial : 0
Failure : 0
: DS_TEAM_MEMBERSHIPS
Success : 67
Partial : 0
Failure : 0
: DS_RECURRENT_COVERAGES
Success : 12
Partial : 0
Failure : 0
: DS_HOLIDAY_COVERAGES
Success : 1
Partial : 0
Failure : 0
: DS_DEVICE TIMEFRAME
Success : 1
Partial : 0
Failure : 0
: DS_EVENT_DOMAIN_PREDICATES
Success : 7
Partial : 0
Failure : 0
2007-05-14 14:05:26,795 INFO - Level=SYNCHRONIZER, type=SYSTEM_COMPLETE, status=SUCCESS
Interpreting the Command Line Report

The following table describes the data included in the command line report:
Command Line Report Data
Term
Description
Success
Represents the number of successfully updated rows (with the exception of DS_TEAM_
MEMBERSHIPS, which counts the number of Teams updated).
Partial
Represents the number of individual errors that would not completely fail a record.
Note that a record can have more than one partial error against it. Additionally, a record with at
least one partial will still be recorded as either a Success or a Failure. The total number of rows (or
Teams) processed for a table is the sum of the Success and Failure items.
Failure
Represents the number of rows that failed to update (with the exception of DS_TEAM_
MEMBERSHIPS, which counts the number of Teams updated).
Note that if both parent and child are marked for removal, the child record will result in a failure
count; however, the child record is still removed from xMatters. For example, marking the removal
of PersonA and PersonA's device (DeviceA) results in the removal of DeviceA being marked as
failure.
Synchronization Report (Web User Interface)

Audit records for each data synchronization process are recorded in the database. Company Administrators (and other
users with the appropriate permission) can access the Synchronization Report in the xMatters web user interface.
This report includes the following:
n
List of all data synchronizations with available audit data.
Summary of the actions the synchronization process performs (this is similar to the command line report described
above).
Detailed failure report showing all the failures for a particular table.
Note:
Although key information is saved during data processing, the complete Staging Area record is not saved. As a
result, if the Staging Area is modified after a data synchronization is run, the problem record may no longer
exist or may have been changed.
For further details about the Synchronization Report, see "Synchronization report" on page 324.
Logging
In addition to the Synchronization Report available in the xMatters web user interface, a separate set of log files are
stored in the logging subdirectory \logs. The specific location for \logs depends on where the xMatters Data
Synchronization Module is installed (e.g., for a default Windows installation: C:\Program Files\\AlarmPoint_
DataSync\logs).
The logs roll when they reach 5MB is size. For example, when a log reaches 6MB, the log folder will contain
two files: AlarmPoint.DataSync.log and AlarmPoint.DataSync.log.1 (AlarmPoint.DataSync.log contains
the latest data). By default, the logs will roll up to 20 times, after which the older data will be discarded.
Note:
You can control the logging detail level by modifying the Threshold attribute in the log4j.xml file (located in the
assets/config subfolder). From most to least detailed, the available log settings are DEBUG (default), INFO, WARN and
ERROR. For example, the following excerpt from the log4j.xml file modifies the logging level from the default
DEBUG to WARN:
<appender name="rootAppender" class="org.apache.log4j.RollingFileAppender">
<param name="maxBackupIndex" value="2"/>

<param name="maxFileSize" value="5242880"/>
<param name="Threshold" value="WARN"/>
<param name="File" value="logs/AlarmPoint.DataSync.log"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %p - %m%n"/>
</layout>
</appender>
Multiple-Company Environments
In a multi-Company environment, each Company must have its own set of staging tables (staging area) so that
Companies can import/export data concurrently. Each staging area can be in a completely different database. However, if
a Companys staging area is located in the xMatters Service Provider database instance, it needs to be kept in a separate
schema.
Creating Company Staging Areas

The first step is to create a staging area for each Company. The following sections describe how to create a Company
staging area for each database type.
The data_sync_staging.ddl file required for these instructions is located in the following directory:
<xMatters>\example\staging_ddl\<DatabaseType>
Where <xMatters> is your xMatters installation folder, and <DatabaseType>is the type of database on which you
want to create the staging area.
Oracle
To create a staging area for an Oracle database:
1. Log in to SQLPlus as sysdba (sqlplus / as sysdba).
2. Create a table space(replace %TABLESPACE_NAME% with desired name):
CREATE TABLESPACE %TABLESPACE_NAME% DATAFILE '%NAME%.dbf' SIZE 600M AUTOEXTEND ON NEXT 100M;
Multiple-Company Environments | 438
3. Create a user (replace %TABLESPACE_NAME% with the name you defined in the second step and replace %USER_
NAME% with desired name.):
CREATE user %USER_NAME% IDENTIFIED BY "%PASSWORD%" default tablespace %TABLESPACE_NAME% quota
unlimited on %TABLESPACE_NAME% account unlock;
4. Grant permissions to the user (replace %USER_NAME% with the name defined in the third step):
GRANT
GRANT
GRANT
GRANT
GRANT
CREATE
CREATE
CREATE
CREATE
CREATE
SESSION TO %USER_NAME%;
TABLE TO %USER_NAME%;
SEQUENCE TO %USER_NAME%;
TRIGGER TO %USER_NAME%;
VIEW TO %USER_NAME%;
5. Log out sysdba and log in as the new user.

6. Run the data_sync_staging_area.ddl script to create the staging tables.
Microsoft SQL
To create a staging area using SQL Server Management Studio Express 9:
1. Open SQL Server Management Studio Express and log in as sa.
2. Create the database:
l
Right-click Databases and select New Database.
Type in desired database name.
Click OK.
3. Create a login:
l
Under the Security folder, right-click Logins and select New Login.
Type a name, select SQL Server Authentication and enter a password.
Set the Default Database to the database in step 2.
Click OK.
4. Create a user:
l
Expand the newly-created database and expand Security
Right-click Users and select New User.
Type a name for User Name.
Type the login from step 3 for Login Name.
Select db_owner for schema and role.
Click OK.
5. Log out sa and log in as the new user

IBM DB2
To create a staging area for an IBMDB2 database:
1. Create a user: DB2 uses the operating systems user accounts for authentication. Create an OS User account on the
Server where DB2 is installed; this process varies depending on OS (refer to your operating system help files for
details). For example, on Windows systems:
l
Open Computer Management (Start > Administrative Tools > Computer Management)
Expand Local Users and Groups, and right-click Users.
Click New User.
Type the user name and password, and then click Save.
2. Use DB2's "Command Line Processor" to create a database; this process varies depending on the operating system
(refer to the DB2 documentation for information about how to use the "Command Line Processor" on different
operating system. For example, on Windows systems:

l
Open the Command Line Processor (Start > All Programs > IBM DB2 > DB2COPY1 (Default) >
Command Line Tools > Command Line Processor)
Within the Command Line Processor, type in the following command, modifying %DATABASE_NAME% with
the name of the user account created in the step 1, and press Enter.
CREATE DATABASE %DATABASE_NAME% PAGESIZE 32 K
3. Ensure that you see the following message: The CREATE DATABASE command completed successfully.
Note:
The same name is being used for the database as user account.
4. Login as admin to the database using a SQL client tool (e.g., SQuirreL). The database name is specified in the
URL (use the name of the database created in step 2). For example:
jdbc:db2://1.2.3.4:50000/database_name
5. Create a table space (replace %TABLESPACE_NAME% with the name of the user account created in the first step):
CREATE TABLESPACE %TABLESPACE_NAME% MANAGED BY AUTOMATIC STORAGE INITIALSIZE 650M INCREASESIZE
50M;
Note:
The same name is being used for the database as user account.
6. Grant permissions to the user (replace %USER_NAME% and %TABLESPACE_NAME% with the name of the user account
created in the step 1):
GRANT CONNECT, CREATETAB ON DATABASE TO USER %USER_NAME%;
GRANT USE OF TABLESPACE %TABLESPACE_NAME% TO USER %USER_NAME%;
7. Log out admin and log in to the database as the new user.
Concurrent Company Data Synchronization

After you have created staging tables for each Company, you are ready to run Data Synchronization on multiple
Companies.
To perform Data Synchronization on multiple companies concurrently:
1. Create a staging area for each Company. In a RDBMS where the staging area is supposed to be located, do the
following:
l
On Oracle, create a schema, or on SQL Server, create a database in a database instance (or the main database
instance).
Create a user for the schema or database.
Create staging tables in the schema or database.
2. For each Company, create a properties file in which the location of a staging area is specified.
l
For example, create companyA.properties for companyA, specifying that the staging area of companyA is
on server 1.2.3.4 and in the database schema for user datasync-user1:
#Wed Jan 25 10:12:45 PST 2012

JDBC_DRIVER_CLASS_NAME=oracle.jdbc.OracleDriver
JDBC_USERNAME=datasync-user1
JDBC_URL=jdbc\:oracle\:thin\:@1.2.3.4\:1521\:DB
JDBC_PASSWORD=datasync-user1pwd
3. After modifying and saving the properties file, the information is still in a decrypted format that datasync does not
use. In the main datasync folder, run the following to produce an encrypted file that datasync can use:
APSecure.bat encrypt "plain_properties_file_path"
"encrypted_properties_file_path"
4. For each company, create configuration files for import/export in which the staging area to be used by the
Company is specified.
l
If desired, you can copy the example configuration files (e.g., located on Windows at
<xMHOME>\\AlarmPoint_DataSync\example\config
) to the main datasync folder (e.g., located on Windows at <xMHOME>/ \AlarmPoint_DataSync. You can
then modify the files to refer to the Companies in your xMatters deployment.) For example, create
alarmpoint-import-companyA.xml for data import, indicating that companyA will use the staging area
specified by companyA.properties:
<alarmpoint-synchronizer xmlns:xsi=http://www.w3.org/2001XMLSchema-instance
target="alarmpoint" failure_limit="100">
<company name="companyA" one_db="false" user="superadmin">
<staging_area properties_file="assets/config/companyA.properties" />
<site>
......
</site>
......
</attribute_category>
......
</company>
</alarmpoint-synchronizer>
5. To import/export for different companies concurrently, run the Data Synchronizer with different configuration files.
l
For example, run the following in three different console windows pointing to the datasync folder location:
DataSync.bat -f alarmpoint-import-companyA.xml
DataSync.bat -f alarmpoint-import-companyB.xml
DataSync.bat -f alarmpoint-export-companyC.xml
Troubleshooting Data Synchronization

When running Data Synchronization for xMatters deployments, the data presented for synchronization may contain
errors. This section explains how these errors are presented to the user and, where possible, describes how to resolve
them.
Error Flags
The following tables describes the known error flags that can occur with Data Synchronization:
Data Synchronization Error Flags
Error Message
Description
EMPTY_CONFIG
Indicates an empty alarmpoint-synchronizer.xml configuration file.
Troubleshooting Data Synchronization | 441
Error Message
Description
INVALID_CONFIG
Indicates a problem with the configuration file.

Several conditions may generate this error, including the inability to
connect to the xMatters database.
NO_SYNC_TABLES
Indicates that no tables were specified for synchronization in the

configuration file.
NO_EXTERNAL_KEY
Indicates that the configuration file did not specify an EXTERNAL_KEY

member for the table.
BAD_ACTION
Indicates that an invalid alarmpoint_action was specified for the row.

This error is extremely unlikely.
REMOVE_MISSING_RECORD
Indicates that the record specified for removal was not present in the
xMatters database.
This is not an actual error, but an informational message.
BAD_OBJECT_TYPE
Indicates that the row referenced an object that was not of the expected
type (e.g., if a Device referenced its owner and the owner was a Group
instead of a User).
This error is extremely unlikely.
SAVE_FAILED
Indicates that a problem occurred when the Data Synchronization module

attempted to save a record.
The most likely problem is that the object references something that it
cannot reference.
NOT_FOUND
Indicates that the specified field references an object that cannot be found
in the database.
This means that either no object of that name exists (for non-synchronized
objects) or the external key specified was not found for this field (for
synchronized objects).
FAIL_TO_LOAD_SYNC_USER
Indicates that the User specified in the User attribute for Company in the
configuration file cannot be found. Ensure that the value specified in the
attribute matches an existing User ID or external key.
FIELD_ERROR
Indicates that the specified field value is either missing or incorrect.
NO_PROPERTY
Indicates a problem with the Data Synchronization module.

This should never appear in the field.
Error Message
Description
INVALID_VALUE
Indicates that the specified field contains an invalid value.

For example, if a boolean field (which should be either Y or N) has an
A in it.
NO_IS_NEW
Indicates a problem with the Data Synchronization module.

This should never appear in the field.
INACTIVE_PERSON
Indicates that the field specifies an inactive User.

Inactive Users cannot be in the specified list.
MISSING_REQUIRED
Indicates that the specified field or some required element of the row is
not present.
SPECIFIED_USER_HAS_NO_
PERMISSION_TO_BE_
SUPERVISOR
Indicates that the User specified to be a supervisor does not have the
proper Role associated with it. For more information about Roles, see the
xMatters installation and administration guide.
Resolving Specific Errors

The following section identifies specific error messages and their resolutions.
No FIELD level errors but ROW, COMPLETE, FAILED
This problem can often be traced to records in the xMatters database having the same key values as a Data
Synchronization record, but different external keys. Therefore, if a DS_USERS record has a USER_ID that matches an
existing record, you will see this behaviour.
When resolving this issue, consider the following:
n
USER_ID for Users and GROUP_NAME for Groups need to be unique even against each other.
Look for records in the xMatters database that have the same data but different external keys.
External keys are case sensitive. For example, rmt003 and RMT003 are different values.
NOT_FOUND for device_name fields

This error means that the specified device_name is not available in the database.
There are two sets of Device names: the standard set and the set for a particular Company. When a new Company is
created, the standard set is copied to the new Company and when installed the default Company has the standard set of
Device names. If you have changed the Device names, then you must use one of the new names.
The Device name must be associated with the Device type; you cannot use an Email Device name for a Voice Device.
MISSING_REQUIRED for Device ROW records
This error means that the USER_KEY specified for the Device does not exist in the xMatters database.
All references in the staging tables are made by external_key values. For the USER_KEY in a Device staging table you
must use the external_key from the DS_USERS table.
Note:
The referenced User does not have to be synchronized in this Data Synchronization run or even present in the
staging area, although it must have been synchronized at some time.
Immediate FAILURE after SYSTEM_START message.

If the Data Synchronizer fails immediately after the type=SYSTEM_START message, and without showing a type=FILE
message, it is likely that the common.properties file does not properly point to the xMatters database. Also, in this case
you will not see any Synchronization Report in the Web-UI for this run attempt.
To fix this problem, modify the database connection properties in the common.properties file in the common subfolder
of the Data Synchronization installation directory. If the file is encrypted, decrypt it using the APSecure utility.
List of Tables
Day and Time Schedules for Devices
xMatters Components
Language Support
7
10
22
xMatters Components Installation Order
23
Installation Hard Disk Space Requirements
24
Supported Operating Systems for xMatters
25
64-bit JVM Support
26
27
Supported Databases
27
Web Server Proxy
27
Supported SIP Gateways
28
Minimum All-in-One System Hardware Requirements
30
Minimum Multiple-System Hardware Requirements
31
Hardware Checklist
32
Software Checklist
34
35
Oracle Sizing Example
36
Microsoft SQL Database Sizing Example
40
SQL Runtime Data Storage Requirements
41
SQL Configuration Data Storage Requirements
41
44
xMatters Agent Default Port Usage
46
xMatters Client Default Port Usage
46
xMatters Client (binary) Default Port Usage
47
xMatters Admin Tool Default Port Usage
47
xMatters Web Default Port Usage
48
T-1 E and M (Robbed bit) Configuration Sample
59
60
61
61
62
List of Tables | 445
62
Non-Windows Installation Methods
63
Database Properties
68
Optional Components Settings Windows installation
70
New Node Component Settings
71
Database Properties
77
Optional Components Settings Console Installation
79
Node Settings
80
Default Administrator Web Logins
82
Virtual Device Configuration Settings
90
Available Settings in common.properties
91
92
Company Details settings
99
Node Types
111
113
Node Logging Settings
117
Device Engine Logging Settings
120
BES Device Engine details
120
DTMF Device Engine details
122
Generic Device Engine details
122
GSM Modem Device Engine details
123
Wavecom Fastrack GO
125
HTTPClient Engine details
126
HTTPVoice Engine details
127
Jabber Device Engine details
128
MAPI Device Engine details
129
Notes Device Engine details
131
Phone Device Engine details
133
Phone Line details
134
UCP Serial Device Engine details
136
SIP Device Engine details
137
Inbound SIP Registration Settings
138
SMPP Device Engine details
140
446 | List of Tables
SMTP Device Engine details
144
SNPP Device Engine details
146
SUCP Device Engine details
147
TAP Modem Device Engine details
147
TAP Leased Device Engine details
148
Virtual Device Engine details
148
WCTP Device Engine details
150
Node Resources
152
Serial Device Resource details
152
Socket Proxy Resource details
153
Standard Dialing Code
154
Special Dialing Codes
155
BES Provider Details
161
DTMF Provider Details
162
Generic Provider Details
163
GSM Provider Details
164
HTTPGeneric Service Provider Details
166
HTTPConference Provider Details
167
HTTP SMS Provider Details
168
HTTP Conference Provider Details
172
Jabber Provider Details
173
NOTES Provider Details
174
PSTN Provider Details
175
PUCP Provider Details
175
SIP Provider Details
177
SIP Provider - Inbound Registration settings
178
SMPP Provider Details
179
SMTP Provider Details
184
SNPP Provider Details
185
SUCP Provider Details
186
TAP Provider Details
187
TAP Leased Provider Details
189
Virtual Device Provider Details
190
WCTP Provider Details
190
User Service Provider Details settings
193
Health Monitor Settings
201
Notification Processing
201
Service Provider Failover
201
Bounced Mail Settings
202
Node Network Monitor
202
SMS Response Validation Settings
203
SMS Message Constants
213
214
Function details
230
Role Details settings
234
Role Permission Types
235
Role Permissions Settings
235
Super Administrator Details settings
239
Company Administrator Details settings
241
Custom Holiday Details settings
248
Custom Field Details settings
254
Out-of-box event domains
260
Event domain details
262
Pattern library options
266
Subscription Terms
267
Subscription Domain details
270
Determining Subscription Results for Attributes with Multiple Values
279
Determining Subscription Results for Missing or Unspecified Predicates
280
Message Domain Details
285
Custom Messaging Panel details
287
Custom Page Details
289
Import Data page details
293
Phone Recording General Details
296
Key Reporting Terms
302
Search reports using the percent sign as a search term
303
Available Reports
305
Event Activity Report Columns
308
Event Activity for User Report Columns
309
Event Activity for Group Report Columns
311
Event Summary Report Terms
312
Notification Summary Statuses
315
Submitted Notifications Report Columns
318
Live Notifications Report Columns
320
Live Notifications Report Status Column Entries
320
Connection Pool Parameters
358
380
Staging Tables Standard Fields
380
User Values for the alarmpoint_action Field
380
Data Synchronization for the alarmpoint_action Field
381
382
ds_attributes Table
383
383
385
385
388
390
391
ds_groups Table
392
394
ds_im_devices Table
395
396
399
399
ds_sites Table
400
402
ds_teams Table
402
404
406
407
408
ds_users Table
408
412
alarmpoint-synchronization Element Attributes
414
company Element Attribute
414
alarmpoint-synchronizer.properties Settings
415
416
Table Element Attribute
416
XML Table Element Default Table Names
417
Field Element control attribute meanings
418
Overwrite attribute values
418
Field Element Default Attribute
419
Field Element stage_name Attribute
419
attribute Element Field Elements
419
attribute_category Element Field Elements
420
bes_device Element Field Elements
420
custom_field Element Field Elements
420
device_timeframe Element Field Elements
421
email Element Field Elements
421
event_domain_predicate Element Field Elements
422
generic_device Element Field Elements
422
group Element Field Elements
423
holiday_coverages Element Field Elements
424
im Element Field Elements
424
numeric_pager Element Field Elements
425
person_supervisor Element Field Elements
425
recurrent_coverages Element Field Elements
425
site Element Field Elements
426
team Element Field Elements
427
team_membership Element Field Elements
427
text_pager Element Field Elements
428
text_phone Element Field Elements
428
user Element Field Elements
429
user_custom_value Element Field Elements
430
voice Element Field Elements
430
Data Synchronization Command Flags
435
Data Synchronization Command Return Codes
435
Command Line Report Data
437
Data Synchronization Error Flags
441
452 |
List of Figures
Basic Deployment
12
xMatters workgroup Example Deployment
13
xMatters enterprise Example Deployment
14
Dialogic version 6.0 Welcome Dialog
51
Dialogic version 6.0 Select Components page
52
Third-Party Software Installation dialog box
52
Computer Name Dialogic Configuration Manager Dialog
53
Dialogic Driver version 6.0 Configuration Manager Dialog
53
Service Starting
54
Dialogic Configuration Manager 6.0 Automatic Startup Mode
54
Selecting Global Call Protocols for Windows 2008 installation
56
Installation Introduction Panel
64
Installation License Agreement
65
Installation Choose Install Folder
66
Installation Database Preparation
67
Installation Database User/Schema Settings (Oracle shown)
68
Installation Merge Admin Accounts
69
Installation Installing Optional Components
70
Installation Installation Progress
72
Installation Database Creation Progress
73
Installation Install Complete
74
Installation (console) Introduction
75
Installation (console) License Agreement
75
Installation (console) Select Installation Directory
76
Installation (console) Database and User/Schema Creation Method
76
Installation (console) Database Selection and Settings (SQL)
77
Installation (console) Merging Administration Roles Query
78
List of Figures | 453
Installation (console) Optional Component Selection
79
Installation (console) Optional Component Settings
80
Installation (console) Installation Complete
81
xMatters login page
97
Companies page
98
Single Company Quotas
102
Modifying Company Quotas
103
Tenant Company User Mapping
109
Active Licenses page
110
Nodes page
111
113
Notification Server Node details
115
Node Components page
119
Domino Server Setup DIIOP CORBA Services
131
Approximate call process for Positive Voice Detection
135
Resources for Node page
151
Phone class exception example
155
Phone class exception extension example
156
Clusters page
157
Protocol Providers page
160
User Service Providers page
192
LDAP Servers page
194
LDAPServer Details page
195
Global Configuration page
200
Global Constants page
210
Company Constants page
211
215
216
217
454 | List of Figures
Schedule Job Details for Process Expired Data
218
219
Clear Runtime / History page
219
HTTPDevice Engine settings
221
HTTPSMSProtocol Provider settings
222
SMSResponse Validation example
223
SMPPDevice Engine settings
224
SMPPProtocol Provider settings
225
Functions page
229
Permissions page
231
Roles page
234
External Data Locked Properties page
237
Super Administrators page
238
Company Administrators in Default Company
240
Logged in as another User
242
Sites list
243
Assigning Countries to a Company
244
Assigning Time Zones to a Company
245
Assigning Languages to a Company
246
Example of Custom Holiday Details page
250
Example of new custom holidays
250
Custom Attribute Categories page
252
Custom Attribute Details page
253
Custom Fields page
254
Password Policy page
256
List of device types (your deployment may not support all types shown)
258
Defining device names
259
Specifying an email domain "whitelist"
259
Event domains list
261
Event Domain Predicates page
265
Subscription Domains page
269
Subscription Domain Response Choices
272
Selecting Appropriate Predicates
273
Select Roles page
274
Assign Alerts page
275
Subscription Managers
282
Search Subscriptions by Subscription Domain page
283
Message Domains page
285
Messaging Panels page
286
Import Data page
293
Data import with results report
294
Add a Phone Recording Page
296
Phone Recordings page
297
Edit Phone Recording Details page
297
Add Phone Recordings popup
298
Edit Phone Recording Details New Recording Added
299
307
309
310
Event Summary
312
314
Exhaustive Report
315
Replay Event page
317
318
319
Notification Throughput Report
322
Domain Summary Report
323
Domain Summary Report Expanded
324
456 | List of Figures
Synchronization Report Results
324
Synchronization Report Success/Failure by Table
325
Sample Application Audit Report (based on Node Component activity)
327
Low-use user report
328
Component Status Summary Report
329
Itemized Component Status Summary Report
330
Node Network Statistics Report
331
332
333
"About xMatters"page with SMStranslation keys
373
"Terms of Service" page with SMStranslation keys
374
"Text Phone Device Details"page with SMStranslation keys
374
458 |
Index
A
about
Dialogic voice cards 50
adding
licenses 109
Administrators
details 241
managing 239
alarms, network 5
analog Dialogic voice cards
automated speech recognition 54
configuring 52
installing 50
installing drivers 51
Application Server Node
definition 111
details 113
failover 111
automated speech recognition 54
C
c3p0.properties file 358
Clusters
about 156
managing 156
command-line
Data Synchronization report 435
method in integrations 17
common.properties file 91
Companies
about 97
Administrators 239
details 98
login pages 104
managing 97
new 98
configuration
T-1 Dialogic voice cards 59-62
configuring
analog Dialogic voice cards 52
Subscription Domains 269
console install 74
Countries
about 244
managing 244
Custom Attributes
about 252
categories 252
Custom Fields
about 253
managing 253
custom holidays 247
Custom User Information 251
D
Data Synchronization
alarmpoint-synchronization element 414
command 434
company element 414
configuration file 414
error flags 441
example configuration file 431
external interface 379
installing 378
introduction 378
staging area 379
staging_area element 415
troubleshooting 441
database
connection string 91
increasing the connection pool 357
modifying the common.properties file 91
dataload 289
default
passwords 82
usernames 82
default ports 45
Device Engines
about 118
distributing threads 116
logging 119
managing 118
types 120
Device Types
about 257
managing 257
Dialogic 56
voice card 16
| 459
Dialogic voice cards

about 50
ringing ports 45
See also analog Dialogic voice cards 50
See also T-1 Dialogic voice cards 55
disaster recovery
overview 336
procedures 339
use case 342
disk space 24
display status 8
Domains
Subscription 269
DR 336
drivers
analog Dialogic voice cards 51
E
elements
alarmpoint-synchronization 414
company 414
field elements 416
staging_area 415
table elements 416
Escalation
processes 7
Event
Java Client 16
messaging 6
Event Domain
adding predicates 264
external data locking 236
external_key Field 381
F
failover 111, 343
field elements
about 416
control attributes 418
Functions 8
about 228
customizable calendaring 7
managing 228
G
Global Call parameter settings 58
Global Configuration settings 198
460 |
GSM Modem
Protocol Provider details 164
H
hard disk space 24
Health Monitor 198
Holidays
about 247
custom 247
managing 247
Site 248
I
Import Data 289
importing data 289
improving Node performance 116
installation 56
installing
component order 23
Data Synchronization module 378
Dialogic voice cards 50
hard disk space 24
licensing 20
NeoSpeech TTS 88
overview 20
post-installation tasks 85
system requirements 24
T-1 Dialogic voice cards 55
via console 74
via wizard 64
integration
Java Client 5
XML 5
Integration
application specific modules 17
open technologies 5
interface
Data Synchronization 379
J
Java Client
Agent 16
Agent notification requests 17
bi-directional messaging 6
custom integrations 17
Event 16
integration 5
Index
integrations 17
main applications 16
Management Systems 16
message 11
port defaults 46
running on Management System 11
sending request 17
JDBC driver 91
L
Languages
about 246
managing 246
last_sync_date Field 381
latency requirements 31
LDAP
log file 196
LDAP Servers 193
licenses
adding 109
licensing 20
list predicates 266
load data 289
locking external data 236
logging
Device Engines 119
LDAP 196
Reporting 302
M
MAPI
email engine 16
support 6
messaging
Blackberry support 6
engine 16
Event 6
instant 6, 16
paging/text support 6
panels 8
multiple-Company deployment
Company login pages 104
multiple-Company deployments
Company-specific components 97
SIP routing 136
N
NeoSpeech TTS 87
network
alarms 5
Ethernet 16
event example 5
multiple notification, example 7
port defaults 45
protocol support 6
security management 9
Node
performance tuning 116
Nodes
Application Server details 113
default port usage 47
managing 111
Notification Server details 114
Resources 150
starting and stopping 92
types 110
Notification
custom Action Scripts 17
distributed 7
Event definition 16
example table 7
modular achitecture 7
on multiple devices 7
user-defined scripting 7
Notification Server
multiple 6
Notification Server Node
definition 111
details 114
numeric pager 6
P
Password Policy 255
password, default 82
Permissions
about 228
setting for Roles 235
phone engine
Dialogic voice card 16
Virtual Phone 16
port defaults
Java Client 46
| 461
network 45
Nodes 47
Web User Interface 48
post-installation tasks 85
Predicates
Important flag 265
managing 263
Protocol Providers
about 157
adjusting maximum session size 116
GSM Modem 164
managing 159
R
Reporting
available types 305
introduction 302
reports
about 302
accessing 302
sorting results 303
types 305
Reports
Important predicates 265
Resources
about 150
managing 150
types 151
Roles
about 228
managing 233
setting Permissions 235
S
SEND
Reporting 302
Single Sign On 107
SIP
routing 136
Sites
about 242
details 243
Holidays 248
managing 242
SMS 9
notifiction 6
support 6
462 |
SMTP 9, 16
SMTP support 6
SNPP 9
software
T-1 Dialogic voice cards 56
sorting
report results 303
Speech Recognition 6
SSO 107
staging area
about 379
requirements 379
status
Available Reports 305
Reporting 302
request 17
Subscription Domains
configuring 269
details 269
subscriptions
preparing panels 268
Subscriptions
configuring Domains 269
Domain details 269
system requirements 24
latency 31
T
T-1 Dialogic voice cards
configuration 59-62
Configuration Manager 57
installing 55
software 56
Universal Dialogic Diagnostics utility 57-58
table elements
about 416
changing speech rate 86
NeoSpeech 87
text predicates 266
Time Zone
support 7
Timezones
about 245
managing 245
troubleshooting
Data Synchronization 441
Index
U
Universal Dialogic Diagnostics utility
T-1 Dialogic voice cards 57-58
User Service Providers
about 191
managing 191
username, default 82
V
voice cards
SeeDialogic voice cards 50
VOIP 136
W
WCTP 9
Web Server
starting and stopping 93
web session timeout 360
Web User Interface
default port usage 48
wizard install 64
X
XML
integration 5
message 11, 16
| 463
464 |
www.xMatters.com
1 2 647 alcosta blvd., suite # 4 25 san ram on ca 945 83 usa
p : 1-87 7-xM attr s + 1. 87 7. 9 6 2 . 8 87 7
C e n t r al Co u rt 25 Southam pton Build i n g s , Lon d on WC2 A 1A L U K
p : + 44 (0 ) 80 0 6 52 7 7 1 1
Copyright 2014 xMatters. All rights reserved. All other products and brand names are trademarks or registered trademarks of their respective holders.

Xm410 Installadmin Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Xm410 Installadmin Guide

Încărcat de

Drepturi de autor:

Formate disponibile

xMatters installation and

Contacting xMatters, inc.:

Chapter 2: Installing xMatters

xMatters installation and administration guide

Chapter 3: System Configuration

Chapter 4: Administrating xMatters

About system administration

Chapter 6: Advanced xMatters Administration

Disaster Recovery Deployment Considerations

xMatters installation and administration guide

Upgrading an xMatters DR Deployment

Chapter 7: Data Synchronization

Chapter 1: Introduction to xMatters

xMatters installation and administration guide

About this document

Important xMatters Terms

About this document | 2

Chapter 1: Introduction to xMatters

text that must be typed into the computer

directory and file names

On Windows systems, the default is C:\Program Files (x86)\xMatters

On Unix systems, the default is /opt/xmatters

On Windows systems, the default is C:\xMatters\IntegrationAgent

On Unix systems, the default is /opt/xmatters/integrationagent

Directory Path Example

xMatters installation and administration guide

The xMatters Critical Event Notification Platform

Data center job scheduling

Help desk management.

The Role of xMatters in Service Availability

Chapter 1: Introduction to xMatters

Delivering on ITIL Processes:

Configuration Management:xMatters may use a Configuration Management Database (CMDB) as a trusted

Open Integration Technologies

Web Based Application User Interface

Event Assignment and Subscription

xMatters installation and administration guide

Event Messaging and Custom Applications

Communication Device Support

Bi-Directional Message Support

Acknowledge receipt of a message on the console of the management system.

Open, close, or update trouble tickets in a problem management database.

Perform a command line action on the management system in response to a notification.

Chapter 1: Introduction to xMatters

Granular Staff and Device Scheduling

Send a message to his alpha pager.

Email message only.

All other times

Queue notifications to next open time window.

Complex Group Scheduling and Escalation Processes

Customizable Calendaring Functions

Time Zone Support

Distributed, Modular Architecture

User-Defined Notification Scripting

xMatters installation and administration guide

Security and Encryption

Real-World Application Examples

Data Center Automation

Building menus on a two-way pager for handling action requests.

Contacting programmers when a critical batch job fails.

Chapter 1: Introduction to xMatters

Global Systems Management

Help Desk Automation

Mobile Worker Management and Device Management