The alerts.xml file

The alerts.xml file is in <Activator_install_directory>\Activator\conf\. The default configuration allows certain events in the high, warning and error categories to publish to the user interface. You can edit the file to send the same events by email. This file is only for publishing events for the trading engine.

The default configuration of alerts.xml calls for publishing some but not all of the predefined events cataloged in Event tables. The default configuration reports events in the following general categories:

  • Certificates about to expire
  • Message errors involving packaging and invalid sender or receiver
  • JVM node errors
  • Accessing an unlicensed feature
  • Transport errors
  • Configuration errors
  • Unexpected errors
  • Fatal errors

From an XML editor, you can edit the file to extend reporting to other categories of events.

Send events by email

Use this procedure to configure alerts.xml to have the trading engine send events via email to any recipients. This procedure takes advantage of default settings and requires only minimal changes to alerts.xml to deliver events by email.

  1. Configure a community. Make sure to do the following:
    • Configure the global external SMTP server. This is required for emailing events. See Configure the global external SMTP/SMTPS server.
    • In the contact information for the community, use a valid email address. In some instances, alerts.xml uses this as the “from” address for emailed events.
    • Set up a secure email protocol exchange for the community for receiving messages from partners. Use a detached server for this transport; do not use an embedded server. Set up this exchange even though partners might not use it to send messages to your community. In some instances, alerts.xml uses the SMTP delivery address for this exchange as the “from” address for emailed events.
  2. Make a copy of alerts.xml and keep it as a backup.
  3. Open alerts.xml for editing.
  4. Near the top of the file, find the Interval minutes element. You might want to edit the value. This element limits the number of emails that can be sent for the same event. For example, if messages are repeatedly rejected because of an unknown receiver error, only one email message is sent per hour if interval minutes is set to 60.
  5. Scroll to the bottom of the file. Here you can find commented-out elements as in the following example for specifying “from” and “to” addresses for emailed events.
  6. The following code shows address parameters at the bottom of the alerts.xml file.
  1. The first block of commented-out elements, identified by Community id="PC1", is for specifying “to” addresses with a specific community as the “from” address. A community routing ID is the value of the Community id element. By virtue of the routing ID, the trading engine uses the email address of the secure email protocol exchange for the community as the “from” address. Configuring this block is optional. It is useful if you have two or more communities.
  2. The second block of commented-out elements, identified by Community id="default", is for specifying default “from” and “to” addresses for emailed events. Configuring default addresses is required even if you use the optional first block. This is because some events are not associated with a community routing ID and the default “to” and “from” addresses must be used for such events.
  3. Uncomment the second block of commented-out elements for the default “to” and “from” addresses. Configuring this is required.
    • For Parameter name="FromEmailAddress" value, enter a default “from” address for events.
    • For Parameter name="AlertEmailAddresses" value, enter one or more “to” email addresses. These are where the events are delivered. To enter two or more addresses, separate each address with a comma. For example, name1@domain.com, name2@domain.com.
  4. Optionally, uncomment the first block of commented-out elements for a community-specific “from” address and one or more “to addresses.
  5. Use a community routing ID as the value of Community id.
    • For Parameter name="AlertEmailAddresses" value, enter one or more “to” email addresses. These are where the events are delivered. To enter two or more addresses, separate each address with a comma. For example, name1@domain.com,name2@domain.com.
  6. The trading engine uses the address of the secure email delivery exchange for the community as the “from” address. If such an address is not available, the trading engine uses the contact email in the community as the “from” address.
  7. Save and close alerts.xml.
  8. Restart the trading engine server.
  9. When an event defined in alerts.xml is triggered, email messages about the event are delivered to the specified “to” addresses.

Edit alerts.xml

You can edit the alerts.xml file to alter the events that are published to the database or delivered by email. You must understand XML to change this file. The following describes some of the key elements in the file.

  • Interval minutesThe trading engine only fires one action (email or database) for multiple similar events that occur within a specified interval. If the following metadata matches, the events are considered duplicates. This is a way to limit the number of email messages sent for the same events in a given period of time.
    • AlertDefinition.Name
    • Event.EventType
    • Event.EventLevel
    • Event.ExtendedEventContent
    • Message.SenderRoutingId
    • Message.ReceiverRoutingId
    • Message.BusinessProtocolType
    • Message.BusinessProtocolVersion
  • AlertDefinition – AlertDefinition elements define the type of events to publish, where to deliver the events (database or email) and the information to include in event messages.
  • Events – Events elements refer to some of the predefined event types cataloged in Event tables.
  • Actions – One or more actions can be taken when an alert definition fires. Two actions are supported: database and email. The database action delivers triggered events to the user interface. The email action delivers events by email.
  • Address – Each email Action type element has an Address parameter. The default value of {AlertEmailAddressesses} means the “to” addresses in the Communities elements at the bottom of the file are used. You can substitute addresses without brackets for the bracketed parameter value.
  • Format – Format elements control the format and content of the email messages. Valid formats are text and XML. If the format is text, a list of Field elements can be defined that supply the content of the email message. Each Field element results in a new line in the email message. The field has a label and a hard-coded value or a reference to some metadata contained in the event. See Metadata for email events.
  • Communities – The Communities element defines the values for any bracketed Address parameters referenced in the Actions element. For every event, if there is a community ID and the action is email, then the name of the bracketed parameter is looked up for that community ID. This allows the email address to be configured for each community.

Metadata for email events

The following metadata are available to all events in alerts.xml.

Metadata

Description

AlertDefinition.Name

Name of the alert definition

Event.Name

Name of event

Event.EventType

Type of event (usually same as Event.Name)

Event.EventLevel

Level of event (high, warning, error)

Event.Timestamp

Time event was triggered.

Event.ExtendedEventContent

Extra information that may be with the event

Event.NumberOfOccurances

Number of times the event has been published

The following metadata are available to events at the Messaging level (see Messaging) in the default configuration of alerts.xml. All of these fields names are included in generated email messages. Fields without data display as blank in email messages.

  • Message.CoreId
  • Message.RefToCoreId
  • Message.SenderRoutingId
  • Message.ReceiverRoutingId
  • Message.DocumentId
  • Message.MimeType
  • Message.MessageState
  • Message.MessageContentSize
  • Message.TransportType
  • Message.PeerAddress
  • Message.MessageId
  • Message.BusinessProtocolType
  • Message.BusinessProtocolVersion
  • Message.EncryptionAlgorithm
  • Message.DigestAlgorithm
  • Message.ContentMic
  • Message.RejectedReason
  • Message.ReceivedContentMic
  • Message.MicCheckFailed
  • Message.Disposition
  • Message.SenderRoutingIdType
  • Message.ReceiverRoutingIdType
  • Message.TrueSenderRoutingIdType
  • Message.TrueSenderRoutingId
  • Message.TrueReceiverRoutingIdType
  • Message.TrueReceiverRoutingId
  • Message.ResponseCoreId
  • Message.IsResponsePositive
  • Message.IsFinalState
  • Message.EbxmlService
  • Message.EbxmlAction
  • Message.EbxmlCpaId
  • Message.EbxmlConversationId
  • Message.EbxmlRefToMessageId
  • Message.EbxmlMessageId
  • Message.MaxRetries
  • Message.NextRetryNum
  • Message.NextRetryTime
  • Message.CompressionType
  • Message.ReceiptTypeRequested
  • Message.SendAttempt
  • Message.MaxSendAttempts
  • Message.ResendInterval

Related Links