Specify attributes and values

The following sections explain how xMatters evaluates attributes (or properties) 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

A

ANY

Yes

A

A, B, C

Yes

A

A, ANY (stored as ANY)

Yes

A

NULL (not specified)

Yes

A

B

No

Z

ANY

Yes

Z

A, B, C

No

Z

A, ANY

Yes

Z

NULL

Yes

Z

B

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.) Similarly, some communication plan properties, such as lists, can contain multiple values, and you can create subscriptions against a subset of those values. When dealing with these attributes or properties, 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

Subscription Criteria

Match

A, B, C

A

Yes

A, B, C

A, C

Yes

A, B, C

A, Z

Yes

A, B

B, C, Z

Yes

A, B, C,

Z

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:

  • 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 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

Subscription Criteria

Match

Unspecified

Non-empty

No

Unspecified

Empty

Yes

Unspecified

ANY

Yes

Specified, but empty

Non-empty

No

Specified, but empty

Empty

Yes

Specified, but empty

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
subject CONTAINS "ServiceDesk AND assigned" Does not match
subject CONTAINS "ServiceDesk OR assigned" 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"
impact MATCHES "Customer Broadband"
market = Albuquerque
os = AIX

Match
subject CONTAINS "Severity4"
impact MATCHES "Customer Broadband"
market = Albuquerque
os = AIX
Does not match
subject CONTAINS "ServiceDesk"
impact MATCHES "Broadband"
market = Albuquerque
os = AIX
Does not match
subject CONTAINS "ServiceDesk"
impact MATCHES "Customer Broadband"
market = Fresno, Portland
os = AIX
Does not match
subject CONTAINS "ServiceDesk"
impact MATCHES "Customer Broadband"
market = Albuquerque
os = Solaris, HP-UX
Does not match

Communication plan hierarchy properties

The properties and values available in a communication plan-based subscription use the same matching criteria specified in the preceding examples, with the exception of hierarchy properties. There are two unique operators available to use when subscribing to hierarchy properties: "is one type of" and "is one or more of". These are explained in detail below.

Assume that a communication plan includes the following hierarchy properties and values:

Property Name Category Labels Value Tree
Location

Country
| State or Province
| | City

USA
| New York
| | New York City
| | Buffalo
| California
| | Los Angeles*
| | San Francisco
Canada
| Quebec
| | Montreal
| Ontario
| | Toronto
| | Hamilton

Product

Manufacturer
| Brand
| | Model

WidgetCo
| Premium
| | B100
| | B309
| ValueRange
| | VG80
| | VF26
Gears and Cogs, Ltd
| Gear
| | Mark II
| | Mark IV
| Cog
| | Big Tooth Cog
| | Small Tooth Cog

Hierarchy property operators:
  • The "is one type of" option allows you to subscribe to any higher level branch of a hierarchy property. Any message that contains one of the values within that branch matches the subscription. Using the properties in the above table, if you subscribed to "USA | New York", then any message that included either of "New York City" or "Buffalo" would match the subscription. Similarly, if you subscribed to "WidgetCo", then any message that contained any of the values below WidgetCo in the hierarchy would match the subscription.
  • The "is one or more of" option allows you to subscribe to one or more of the lowest-level properties in the hierarchy. Any message that contains one of the selected values will match the subscription. For example, if you subscribed to "VF26" and "B309" in the WidgetCo category, then any message that contained either of the values would match the subscription.

Note that these options only compare values within a single property; if you selected "is one or more of" "Buffalo" in the Location property, and "is one or more of "VF26" in the Product Category, then any incoming message must still contain BOTH values to match your subscription.

The "is one or more of" option is also available when subscribing to list properties on a communication plan form, and is similar to the comparison within a hierarchy property. You can use the "is one or more of" option to subscribe to multiple values within a list; the subscription will match if at least one of the selected values is included in the communication plan message.