RuleCore Event Model

From RuleCore Support

Jump to: navigation, search

An event is a notification about something that has happened.

Normally an event is a notification about some business related activity which happens at an exact point in time.

Events are generated and published by event source immediately whenever some activity is detected at the source.

An event source is normally a business system and is responsible for publishing events and pushing them into ruleCore, optionally using various kinds of integration and event transport infrastructure. Multiple event sources can publish events using multiple event channels into ruleCore.

The ruleCore rule evaluation model operates on a single unified and ordered event stream created by the event sequencer located in the Event I/O module.

The ruleCore event model defines the semantics and syntax of events as used by ruleCore. The event model is formally specified using XML Schema descriptions and XML is used as the event representation.

System events are pre-defined and user events are event types created by the user.

Events can also be categorized to be either inbound or outbound. All events sent into ruleCore are inbound and events destined for delivery to systems outside ruleCore are outbound. This distinction is purely logical and not visible in the events as such. It is a feature of an event depending on which context it is used.

All events have a common structure with mandatory attributes defined in the root element.

All events are immutable. That is, they can't be modified after creation. If an event needs to be modified it must be assigned a new id and thus a new event is created.

When a new event is created it is created in response to another event. The event is said to be caused by another event. The new event, and the event that caused it, become linked by a causality relationship. This relation is automatically recorded in the header of outbound events, thus preserving event causality relations.

The ruleCore processing model does processing only in response to events. It makes ruleCore a truly event driven component. Thus all outbound events generated by ruleCore are caused by one particular event.

Events, as defined by the ruleCore event model have all the following characteristics:

  • Events are immutable.
  • All events have a globally unique id.
  • All events have a type.
  • An event happens at an exact point in time indicated by a time stamp.
  • An event is caused by another event.
  • Events are processed as a ordered stream.


Contents

Event Class

The event model of ruleCore divides events logically into two classes:

  • System events
  • User events

System events are pre-defined events which are used to for various system related tasks. System events are also generated in response to various task performed by the user. Outbound system events are used to report on error conditions or successfully executed operations requested by inbound system events. Outbound user events are the way ruleCore reports on a rule triggering.

As ruleCore is totally event driven, sending an event into ruleCore is they way you change its configuration. System events are used for various tasks, for example:

  • Creating new rules and their components such as situations and actions.
  • Query the state of a particular rule.
  • Report on the state of a particular rule, in response to a query.
  • Add new user defined event types.
  • Report on errors.


Event Type

All events have a type. The type of system events is fixed and pre-defined. An user can create new types of events which will automatically belong to the user event class.

The type of an user event is defined by assigning the user event a name. All user events must have an unique type. Examples of event types could include:

  • ServerError - Error event used to report on an error condition in a server.
  • OrderCreated - Event used to report that a new order have been created
  • AssetLocation - Event used to report on the location of an asset when it moves.

By creating (user) event definitions, you control which types of business events you are expecting to be sent into ruleCore.

The event type name can be any name allowed in an XML element. The type name is used as the name of the root element in the XML event format used to send events into ruleCore. If undefined events enter ruleCore, they are simply discarded and a warning message is logged.

Event Properties

An user event can have any number of properties defined. A property is a pair consisting of a name and an XPath expression.

When an user event enters ruleCore, the XPath expression is evaluated against the user defined body containing the payload of the user event.

The result of the XPath query is then assigned to the named property. One system property is reserved and have special meaning:

  • sys.entityId – This event represents a state change in the identified business entity.

All property names with the prefix sys. are reserved for system use.

Event Encoding

All events sent in and out of ruleCore are encoded in XML.

All inbound events must adhere to the ruleCore Event Format.

The body of the outbound events is created in the action part of the rule using an user defined XSLT transformation. Thus the body of the user event can be any valid XML fragment which is possible to create using XSLT.

Event Structure

The event format used by ruleCore is simple, yet powerful and flexible.

All events consists of only two parts; the header and the body. The event header is common for all events. For outbound reaction events, the header is automatically created and the contents of the body is filled in by executing the action defined for the rule. The action executes the user supplied XSLT transform which was defined when creating the action. The XSLT transform is executed in the context of the rule instance.

The general structure of any event is: 

<EventType
  base:eventId="3690cbe0-d36c-11dc-95ff-0800200c9a66"
  base:eventTimestamp="2008-12-10T10:20:10.34544"
  base:eventClass="system|user"
  xmlns="http://www.rulecore.com/schema/2008/user"
  xmlns:base="http://www.rulecore.com/2008/base">
 
  <base:EventHeader/>
  <base:EventBody/>
</base:EventType>

The overall structure of any ruleCore event is specified by the ruleCore XML Schema and the RuleCoreEvent complex type, every event inherits a number of common properties from this schema.

The root element of all events denotes their type. For example an user event of type ERROR would have the root element <ERROR>.

Common Attributes

The root element must also have the following attributes:

  • eventId - An UUID specifying the unique id of the event. By the nature of the UUID it is guaranteed that every event have an unique id. The UUID value for the eventId attribute can be created by the sending system or assigned by ruleCore. Multiple distributed systems can safely create event ids at the same time without any coordination. The eventId attribute belongs to the base namespace.
  • eventTimestamp - The point in time when the activity of which this event is an notification of occured. The time must be formatted according to ISO 8601 international standard for time and date representation. The combined date and time format, for example 2008-02-04T16:47Z, is used by ruleCore. The eventId attribute belongs to the base namespace.
  • eventClass - Every event belongs to wither system or user event class. Events in the system class are pre-defined and events in the user class must be defined using the AddEventDef system event. The eventId attribute belongs to the base namespace.

Event Body

The event body contains the user generated payload of the event. The contents can be any valid XML fragment as chosen by the sending system. The payload should be located under the EventBody element. The body can later on be queried with XPath to let the contents of the event body control certain aspects of rule evaluation. The EventBody tag belongs to the base namespace.

For example, events can be selected into the event stream view of an rule instance based on the contents in the event body.

Event Header

The EventHeader contains event meta data.

The Credentials element contains the access token which is received when creating a subscription to the ruleCore service.

Note: This access token is only needed when using the ruleCore subscription service.

The access token can also be found on your ruleCore Service subscription web page. Events sent into the ruleCore service without a correct security access token are discarded. Also note that the type of the service you subscribe to can limit the maximum size of events and maximum number of events per month.

The event header also contains information about the event which caused this particular event to occur. The <CausedBy> element contains an event id of the event which caused the event to be created. If it is not possible to determine the event causality relation, the CausedBy element can be omitted.

The EventHeader element, and all its sub-elements, belong to the base namespace.

Example of a typical event header: 

<base:EventHeader xmlns:base="http://www.rulecore.com/2008/user">
  <base:SecurityInfo>
    <base:Credentials>12345678-1234-1204-1234-123456789abc</base:Credentials>
  </base:SecurityInfo>
 
  <base:CausedBy>
    <base:Event eventId="e75cc700-d36f-11dc-95ff-0800200c9a66" eventType="SOAP_CALL_put" index="1"/>
    <v:Event eventId="a88cc945-d36f-44dc-95ff-2423423c9a66" eventType="SOAP_CALL_get" index="2"/>
  </base:CausedBy>
</base:EventHeader>

Event Transport Protocols

Events sent into ruleCore can be created with your favorite XML tools or libraries and transported to ruleCore using a wide range of transport protocols.

The semantics and representation of events are totally transport independent. Rules are evaluated exactly in the same way independently of the chosen event transport protocol.

The Event I/O module of ruleCore is highly flexible and comes with support for a large standard set of event transports such as TCP/IP sockets, JMS, XMPP, SOAP and e-mail. See the ruleCore service description for a complete list of supported event transports.

Example

Inbound events are sent to the ruleCore CEP Server as notifications of various business activity.

For example, a state change in a business process could be reported with a NewState event. The event body contains additional information about the activity. In this example, the process id and some additional detail about the state change can be found in the event body. 

<NewState
  base:eventTimestamp="2007-11-21T13:35:16.398+01:00"
  base:eventId="c4e00004-abb1-4bdd-8c54-8efbb1a5178b"
  xmlns="http://www.rulecore.com/2008/user"
  xmlns:base="http://www.rulecore.com/2008/base">
 
  <base:EventHeader>
 
    <base:SecurityInfo>
      <base:Credentials>3536ab16-393a-4447-a892-0a3e161f23a6</base:Credentials>
    </base:SecurityInfo>
 
    <base:CausedBy>
      <base:Event eventId="87b353e6-ad65-46fb-a108-765befcda05c" eventType="error" index="1"/>
      <base:Event eventId="0e04849e-c76d-4b94-ac0d-39c1db18b5a1" eventType="error" index="2"/>
      <base:Event eventId="18253034-3e4a-4178-b62d-6db0bf3904ad" eventType="error" index="3"/>
    </base:CausedBy>
 
  </base:EventHeader>
 
  <base:EventBody>
 
    <ProcessType>order_delivery</ProcessType>
    <ProcessInstanceId>1928374:3</ProcessInstanceId>
    <Size value="4300"/>
    <detail>
      <row>1234:22</row>
      <row>AA:2</row>
    </detail>
 
  </base:EventBody>
 
</NewState>
Retrieved from "http://rulecore.com/support/wiki/index.php?title=RuleCore_Event_Model"
Personal tools