AddEvent

Creates an xMatters event based on the supplied parameters. An xMatters event is used to initiate notifications from external integration points.

Sample SOAP Request

Request Parameters

Name

Description

Type

Optional

eventTokens

List of key/value pairs to associate with the new event.

EventTokens

no

The parameters required in the eventTokens list are dependent on your Event Domains and requirements. Each token you pass in must have a corresponding parameter in the Action Script. For example, the sample SOAP request linked above passes in the parameters required for the "messaging" Event Domain provided with a default installation.

The following table lists common event tokens and their default values (if not specified):

Token

Description

Optional

Default Value

agent_client_id

Event Domain for this event

no

default

incident_id

Incident ID of this event (maximum length is 250 characters)

yes

INCIDENT_ID-<number>

xm_priority

Event priority; one of LOW, MEDIUM, or HIGH. This token is not case-sensitive, and also determines the default priority level of notifications associated with the event.

Added in xMatters version 5.0

yes MEDIUM

recipients

List of recipient target names.

no

(none)

debug

When present, activates script debugging

yes

(none)

devicefilter

Device type to filter

yes

(none)

Delimiter for recipients token

The default delimiter for items in the recipients list is a comma. If you have target names that include commas, you must change the delimiter used by the list by passing in another delimiter as the value for a "recipients-list-item-delimiter" event token.

For example, to use a semi-colon as the delimiter for items in the recipients list, you would include the following in the event tokens list:

<sch:eventToken>
  <sch:name>recipients-list-item-delimiter</sch:name>
  <sch:value>;</sch:value>
</sch:eventToken> 
 

Sample SOAP Response

Response Parameters

Name

Description

Type

eventIdentifier

Long identifier for the created event, if an event was created (otherwise, -1)

long

incidentIdentifier

Long identifier for the incident with which the new event is associated, if an event was created (otherwise, -1)

string

serverTimestamp

Time corresponding to the server time when the request was made (this should match the associated persisted audit event)

string

status

Final status of the request

string

Standard SOAP Parameters

SOAP Response Status Messages