The events.xml file

The events.xml file in <install directory>\conf manages publishing events to log files and JMS routers. You must understand this file if you want to customize event configurations.

Each event contains standard information, including:

• Event type
• Event level
• Time stamp
• Name and address of the node that spawned the event
• Name of the application that spawned the event

An event also may have specific information in the form of metadata content or extended event content.

The events.xml file that manages logged events is located at <Interchange install directory>\conf. You can edit this file to control what events are generated and where they are published. By default, some (but not all) events are configured in events.xml to determine how they are published to system log files in the logs directory (see Log file tracking). Using event routers, you also can publish events to a JMS queue.

In addition to using event routers that write events to log files or pass events to some other process, event filters provide a way for determining what events are delivered to a router. Events can be filtered based on type or level. You can build complex filters from multiple simple filters.

The default configuration of events.xml is to write an events log file for each system node to the logs directory. This results in the generation one or more log files that, for Activator, are named in the following format: <hostname>_te_events.log.

One of these event logs is the system control node events log. By default the name of the control node is the host name of the computer. The name of the events log file for the control node looks like this: <hostname>_cn_events.log.

• EventRouters section of events.xml
• MetadataProcessors section of events.xml
• EventFilters section of events.xml

EventRouters section of events.xml

The top portion of the events.xml file is for event routers. The following is an example of the default EventRouters section of the file.

For details on how to configure routers, see Log file event router and JMS event router.

An example of EventRouters section of events.xml follows:

• EventRouter attributes – The EventRouters element can contain any number of EventRouter elements, each defining an event router to be installed in the event system. Each EventRouter element must have an id attribute and a class attribute. Other attributes are optional.
  • id must specify a unique identifier for the router. If the configuration contains more than one EventRouter element with the same identifier, only the last router with the same identifier is installed.
  • class must specify the full name of a class that implements the com.cyclonecommerce.events2.router.EventRouter interface.
  • active is optional and specifies whether the event router should be made active when installed. Only an active router is started when the server starts. The value of the active attribute must be true (the default) or false.
  • priority is optional and specifies the priority of the router relative to other routers. The value of the priority attribute must be a positive integer. The system event dispatcher sends events to routers in priority order of highest to lowest. The lower the value of the priority attribute, the higher the priority, with 1 the highest priority. If multiple routers have the same priority, events are dispatched to those routers in no particular order. If the priority attribute is not specified, the priority for the router defaults to the middle between the highest and lowest possible integer value.
• Parameters element – An EventRouter element can have a Parameters element that defines parameters specific to the particular event router class. The Parameters element can contain attributes or sub-elements.
• EventFilterRef element – An EventRouter element can contain an EventFilterRef element that identifies the event filter to be applied to the event router. Only events that pass through the filter are passed to the event router. The EventFilterRef element, if present, must contain a ref attribute with the same value as an id attribute in an EventFilter element. If a EventFilterRef element is not defined, all events are passed to the event router.
• MetadataProcessorListRef element – An EventRouter element can have a MetadataProcessorListRef element that identifies what list of metadata event content processors should be used to determine what metadata processor to use for each event. The ref attribute must refer to a MetadataProcessorList element.

In the default configuration of events.xml, use MetadataProcessorListRef only when you want to publish events at the Messaging level. This element is not needed in other event router configurations.

MetadataProcessors section of events.xml

The MetadataProcesssors section follows the EventRouter section of the events.xml file. The following is an example of the default MetadataProcessors section.

The MetadataProcessors element can have any number of MetadataProcessorList elements, each defining a list of metadata processors. Each MetadataProcessorList element must have a unique id attribute and can contain multiple MetadataProcessor elements, but is not required to have any. Each MetadataProcessor element must have a type attribute specifying an event type and a class attribute specifying the name of a class that implements the com.cyclonecommerce.events2.metadata.MetadataProcessor interface.

When an event router needs a metadata event content processor, it searches the referenced MetadataProcessorList element for the first MetadataProcessor element with an event type that matches the type of the event being processed by the event router. The event type in the MetadataProcessor element can be the exact type or a super-type of the router's event type. The MetadataProcessor elements are searched in the order specified.

EventFilters section of events.xml

The EventFilters section follows the MetadataProcessors section of the events.xml file. The following code is a partial example of the default EventFilters section.

An example of the EventFilters section of events.xml follows:

The EventFilters element can have any number of EventFilter elements, each defining an event filter. Each EventFilter element must have an id attribute that specifies a unique identifier for the filter. Although more than one EventFilter element can have an id attribute with the same value, we recommend that each EventFilter element have its own id.

A filter defined by an EventFilter element only starts upon server startup when an EventRouter element references it directly or indirectly.

Each EventFilter element defines a single event filter. A single event filter can be simple or complex.

Simple filters

The following are simple event filters:

• <AllFilter/>

A filter that passes all events.

• <NoneFilter/>

A filter that passes no events.

• <EventTypeFilter type="type"/>

A filter that passes all events of a specified type or any of its sub-types. The type attribute must be specified and its value must be the name of an event type defined in Event tables.

For example, if you specify a type of Messaging.Message, all events with that prefix pass through the filter.

• <EventLevelFilter level="level"/>

A filter that passes all events at the specified level and above. The level attribute must be specified and its value must be, in order of least to most important, Low, High, Warning or Error.

For example, if you specify a level of Low, all Low level messages pass through the filter, as well as all High, Warning and Error events. Conversely, if you specify a level of Error, only Error level events pass.

• <EventFilterRef ref="filterId"/>

A filter that refers to another event filter. Using this mechanism supports the re-use of event filters. The ref attribute must be specified and its value must equal that of an id attribute in an EventFilter element. Circular filter references are not allowed.

Complex filters

The following are complex event filters:

• <NotFilter>
•    <!-- A single event filter definition must appear here. -->
• </NotFilter>

A filter that passes all events that do not pass the simple or complex event filter defined within.

• <AndFilter>
•   <!-- Any number of event filter definitions may appear here. -->
• </AndFilter>

A filter that passes all events that pass all the event filters defined within.

• <OrFilter>
•   <!-- Any number of event filter definitions may appear here. -->
• </OrFilter>

A filter that passes all events that pass any of the event filters defined within.

Log file event router

The event system comes with a standard event router in events.xml that sends events to log files in the logs directory (Log file tracking). This outbound event router is implemented by the following Java class:

com.cyclonecommerce.events2.router.LogFileRouter

The default log file event router is configured in a system file for managing events. The file is <install directory>\conf\events.xml. The following is an example of how the log file event router is set up in events.xml. For other details about this file, see The events.xml file.

The MetadataProcessorListRef element references an element in the MetadataProcessors section of events.xml. The EventFilterRef element references a filter in the EventFilters section of events.xml. The following explains the attributes of the EventRouter and Parameters elements in the router definition.

• EventRouter attributes
• Parameters attributes

EventRouter attributes

The following explains the attributes of the EventRouter element in a log file configuration in events.xml.

• id – A unique identifier of the router.
• class – Specifies the name of the Java class that implements the router interface.
• active – Specifies whether the router should be made active when the server starts.

Parameters attributes

The following explains the attributes of the Parameters element in a log file configuration in events.xml.

• file – Specifies the name of the event log file.
• rollOnStart – Specifies whether the log file should be rolled when the log file router is started. Rolling a log file means starting a new log file, saving the current log with an extension of .1 to the file name and renaming any older log files by incrementing the extension by 1. For example, a file with an extension of .1 is renamed .2, and so on. The default value is false. This attribute is optional.
• autoFlush – Specifies whether events are written immediately to the log file. Using a value of true is handy when tailing the log and you do not want to wait before events are displayed. The default value is false, which causes a delay in writing events to the log, a lag that varies depending on the operating system. This attribute is optional.
• gmt – Specifies whether time stamps should be GMT time. If not, time stamps use the local time zone. The default value is false if not specified. This attribute is optional.
• maxFileSize – Specifies the maximum size of a log file before it is rolled. The size is specified in bytes. The letters K, M or G (not case sensitive) can follow a numerical value to specify kilobytes, megabytes or gigabytes, respectively. This option only applies when logging to a file (not standard output). The default value is the maximum file size supported by the operating system. This attribute is optional.
• maxBackupFiles – Specifies the maximum number of rolled log files to retain. This is in addition to the current log file. The default behavior is to retain all archived log files. This attribute is optional.
• maxContentDepth – Specifies the maximum depth of extended content to display. A value of 0 displays no extended content, a value of 1 displays the top level of extended content, and so on. The default behavior is to display all extended content. This attribute is optional.
• rollTimes – Specifies when to roll the log, regardless of file size. Times are specified in hours and minutes, using a 24-hour clock. If the value of the gmt attribute is true, the times in this attribute are assumed to be GMT times; otherwise, they are assumed to be local times. This option only applies when logging to a file (not standard output). The default behavior is not to roll at any specific times. This attribute is optional.

JMS event router

With the help of Axway technical consultants, you can configure a router in events.xml to publish events to a JMS queue. To do so, you must have Java Message Service experience and a working JMS system.

Instructions for configuring a JMS event router are in the events.xml file.

Oracle AQ event router

With the help of Axway technical consultants, you can configure a router in events.xml to publish events to an Oracle Advanced Queuing facility (Oracle AQ) queue. To do so, you must have Java Message Service experience and a working Oracle AQ system.

Instructions for configuring an Oracle AQ event router are in the events.xml file.

XML for JMS and AQ event routers

Each event is serialized in XML form before being written to the JMS or AQ queue. Each event type can contain different data that is specific to the event type. The following is an example of such XML content:

Data common to all events

The following data are common to all events written to the JMS or AQ queue.

• id – Unique event ID. Each event has its own unique ID.
• type – The type of the event.
• level – The level of the event (low, high, warning, error).
• created – Date and time the event was created in yyyy-MM-dd’T’kk:mm:ss format.
• dispatched – Date and time the event was dispatched in yyyy-MM-dd’T’kk:mm:ss format.
• nodeid – The ID of the node that created the event.
• extendedContent – Extended content associated with the event. Name-values pairs that provide additional data for an event.

Data specific to message-related events

The following data are specific to message-related events written to the JMS or AQ queue.

• BackupFilename – Name of the message backup file.
• BusinessProtocolType – Business protocol for the current packaging state. The value depends on a message's state. For example, raw represents an unpackaged state and EDIINT AS1 represents a packaged state for the AS1 protocol.
• BusinessProtocolVersion – Version of the business protocol handler for the current packaging state of the message. The value depends on a message's current state. The value indicates the version of the ProtocolSender or ProtocolReceiver handling a message. The value does not necessarily coincide to a specific packaging specification or RFC.
• CompressionType – The type of compression used to compress a message.
• ConsumptionFilename – Name of the file consumed from the pickup exchange point.
• ContentMic – MIC value of the message.
• ContentMimeType – The MIME type of the message payload.
• CoreId – Unique message identifier within Activator.
• DigestAlgorithm – Digest algorithm used for the message.
• Disposition – Disposition modifier value used when packaging EDIINT MDN. Only set on MDNs that indicate an unpackaging error. Only set on an outbound MDN message.
• DocumentId – Control ID if the message payload is EDI.
• ebXMLAction – For ebXML, identifies a process within a service that processes the message. The action must be unique within the service in which it is defined. The service designer defines the value of the action element.
• ebXMLConversationId – For ebXML, a string identifying a set of related messages that comprise a conversation between two parties. It must be unique in the context of the specified CPA ID.
• ebXMLCpaId – For ebXML, identifies the CPA that governs the collaboration between the trading parties. This matches the CPA ID in the CPA, not the name of the CPA XML file.
• ebXMLMessageId – For ebXML, a unique identifier for a message that conforms to RFC 2822.
• ebXMLRefToMessageId – For ebXML, when present, this must have a MessageId value of an earlier message to which this message relates. If there is no related earlier message, this element must not be used.
• ebXMLService – For ebXML. identifies the service that acts on the message. The designer defines the service. A service is related actions for an authorized role within a party.
• EncryptionAlgorithm – Encryption algorithm used for the message.
• IntegrationId – Used to attach customer-specific ID to a message.
• IsFinalState – True if the message is in a terminal state (delivered, ignored, rejected, joined, resubmitting).
• IsResponsePositive – True if the response (acknowledgment) message was positive; false otherwise.
• MaxRetries – Maximum number of times to retry a message after a transport failure.
• MaxSendAttempts – The maximum number of times to resend a message after a failure to receive a response (acknowledgment).
• MessageContentSize – The size of the message content when the event was fired. Note that the message content size changes as the message flows through Activator; compression, signing, encryption, packaging affect size at one stage or another.
• MessageId – Business protocol message ID.
• MessageState – The state of a message within Activator. For example, consumed, produced, rejected.
• MicCheckFailed – True if MIC checking of inbound EDIINT message fails. Only set on an outbound MDN message.
• NextRetryNum – The next retry increment.
• NextRetryTime – The time to execute the next retry after a transport failure.
• ProductionFilename – Name of the file produced to the delivery exchange point.
• ReceiptMicAlgorithm – MIC algorithm used for the receipt.
• ReceiptRequested – The type of receipt requested for a message (NONE, SIGNED or UNSIGNED).
• ReceivedContentMic – Received content MIC value used when packaging EDIINT MDN. Only set on an outbound MDN message.
• ReceiverRoutingId – Routing ID of the receiving party.
• RefToCoreId – Unique message identifier that relates to this message. Typically set on a receipt message, RefToCoreId refers to the request message.
• RejectionDescription – Rejection reason for a rejected message.
• ResendInterval – The elapsed time to wait between resend attempts.
• ResponseCoreId – The core id of the response (acknowledgment) message for this message.
• SendAttempt – The number of sends attempted.
• SenderRoutingId – Routing ID of the sending party.
• TransportType – The type of transport that consumed or produced the message. For example, HTTP, HTTPS, FTP, MQSERIES, JMS, SFTP, FILESYSTEM and PLUGGABLE.

Persistence event router

Up until version 5.4.2, the router to persist events to the database was active in the events.xml file. Effective with version 5.4.2, the event persistence router is inactive by default. A change in the way the system reports events makes it possible to no longer have to store events in the database, freeing database space and reducing data traffic.

The persistence event router remains in events.xml, but is commented out and inactive. See the following code example.

The persistence event router example in events.xml follows.

Keeping the router inactive is recommended. The cases for activating the router are rare (for example, a third-party back-end system retrieves event data from the database). Before activating, consult technical support.

Related topics

• Event levels
• Log file event router
• Log file event router
• Oracle AQ event router
• XML for JMS and AQ event routers
• The alerts.xml file
• Event tables