Events, entities, and agents

Events

Think of an event as something that happens, or can happen. From a solution design point of view, an event is a specific action or measurement that occurred at a specific time and place.

Events are the representation of messages that are coming from the outside world, and must be processed before an action can be taken. Events must be defined in the Business model. To receive and send events from an external system, a solution must define the Inbound and outbound connectivity.

To send an event to a solution, you use the Solution gateway.

Events must have a representation that can be correlated, aggregated, and filtered. Decision Server Insights encodes events as objects, which have a time stamp that records when they occurred.

Entities

Entities are concepts that have an identifier. Entities are composed of a set of attributes and relationships to other concepts, and can inherit from existing concepts.

Agents

An agent in Decision Server Insights defines the business logic that is used to detect situations of interest. Agents form a solution by working with an agent host and other agents. An agent descriptor subscribes to the events that it needs to receive to detect situations. There are three types of agent supported: rule agents, Java™ agents, and predictive scoring agents. Java agents can be bound to an entity or not.

An agent descriptor always specifies the events that the agent needs to receive, and can set the priority of the agent. In rule agents, the bound entity must also be defined.

The following example agent descriptor defines a user as the bound entity:

'twitter_poster_agent' is an agent related to a user, whose priority is High 
processing events :
    - tweet
        when the day of week of the timestamp of this tweet is Monday, 
        	where this user comes from the poster of this tweet

The when part subscribes to all tweets that occur on a Monday. The where part defines how to resolve a user from an incoming tweet event. The where part is necessary because an incoming event might be related to multiple entities, or the bound entity might be within the incoming event. The priority of an agent is used to order the invocation of multiple agents that are subscribed to the same event and have the same bound entity. The bound entity is important because an agent can modify only the bound entity. It has read-access to all other entities and read/write access to the bound entity. The read/write access defines clear transactional semantics. Agents with a bound entity run on the computer that hosts the primary copy of that bound entity, which helps ensure performance and scalability.

A rule agent can include rules that query, filter, and correlate events from the past and use them to detect situations of interest. All the events that are routed to a rule agent are replicated for high-availability and are garbage collected subject to the time-horizon specified for the agent.

Java agents can be created with or without a bound entity. Java agents without a bound entity extend com.ibm.ia.agent.Agent and have access to the stream of events, but cannot update an entity. They can run on any host within the distributed topology, and have no data affinity. Java agents that require a bound entity extend com.ibm.ia.agent.EntityAgent, can update the bound entity, and receive a stream of events. The state for a Java agent must be stored in the bound entity to ensure that the state is highly available in the event of JVM failover. You must not store Java agent state in instance or static fields within the class itself, as the class is not replicated and is lost after a failure.

The predictive scoring agents extend com.ibm.ia.scoring.ScoringEntityAgent and are a special class of Java agent that is used to call an SPSS® scoring configuration.

The following figure shows how an example solution uses agents to process events. In this example, the first rule agent processes three different event types. The second rule agent processes a single event type, and the Java agent processes an event type that is emitted by the second rule agent. All three agents are bound to an entity.

An event must be recognized so that it can be received and processed by a Decision Server Insights solution. Ordinarily, an agent listens for specific events and then does something to the bound entity as a result of receiving them. An event is sent from inside or outside of the agents and must be recognized by the object model of the solution.

Business model

Your object model must contain all of the event types that your solution wants to process and the entity types that are impacted by the arrival of these events.

An entity is data about a real-world object of business interest with a set of related attributes, for example, a customer that has a piece of luggage. An entity has an ID, which determines the context in which it is processed. For example, a luggage entity might use a bar code number for the ID. Or, if the luggage entity is processed in the context of a passenger, it might use the ticket number that it is associated with.

The entity is the object that is modified by the event. Some entities contain reference data only that is loaded into the system. These reference entities cannot be modified.

For more information, see Designing entities and events.

Solution gateway

You use a solution gateway to submit events to the Decision Server Insights runtime environment. The runtime environment works with an object grid, which you must connect to, to locate a deployed solution and create a gateway. A Java gateway API is provided to make this connection and retrieve information about a solution. Each solution gateway represents a single solution that is connected to the object grid. For more information, see Solution gateway API.

Inbound and outbound connectivity

In a production environment, a Decision Server Insights solution must contain definitions for all the integration points with external systems. You define an endpoint as part of the inbound and outbound connectivity for the solution, where each endpoint represents an external system. Solution connectivity must also contain a definition of its binding. Each binding must reference an endpoint.

If an event arrives that does not conform to the expected event format, Decision Server Insights is unable to recognize the event and submit it for processing. In this case, Decision Server Insights can convert the event into a recognizable format by applying a transformation. Decision Server Insights uses a classifier (XPath expression) to decide which transformation to apply to unrecognized inbound events.

The following figure shows how inbound HTTP or JMS messages are classified as they arrive. Messages that match a classifier are transformed into events. Messages that do not match any classifier are either discarded or transformed. Messages that are transformed are submitted to the solution.

Decision Server Insights sends outbound events, in the form of serialized messages, to external systems. Each outbound event is sent to the destination (an external system) specified in the outbound endpoint. The outbound binding determines which outbound endpoint to use, and the message format.