Progress Apama Fundamentals
Developing Apama Scenarios with
Event Modeler
Presenter’s Name
Presenter’s Job Title and Association
Date
Objectives
 Describe an Apama scenario
 List the main components of a scenario
 Create a simple Apama scenario with a graphical tool
called the Event Modeler
2
© 2009 Progress Software Corporation. All rights reserved.
Apama Fundamentals: 3-Day Agenda
 Day 1
• Setting Up Your Development Environment
• Writing a MonitorScript Application
 Day 2
• Creating a Scenario Application
• Building a User Interface
 Day 3
• Interacting with External Software
3
© 2009 Progress Software Corporation. All rights reserved.
The Apama Application Model
 Core Processing Layer
• The correlator
• Instructions for the correlator
– Write code in MonitorScript
– Write code in Java
– Use a graphical tool (Event Modeler)
 Visualization layer
• Dashboard server
• Dashboard (or other) clients
 Integration layer
• Connection to external software components
– Integration Application Framework (IAF)
– Client APIs
4
© 2009 Progress Software Corporation. All rights reserved.
Day 2
Overview of Apama Components and Tools
Apama Development Tools
Event Modeler provides the ability
External software
for less-technical users
you want
to quickly create Apama applications
to integrate
in a graphical modelling environment –
rather than write event processing logic
directly in MonitorScript or Java.
Event Modeler includes
a library of standard blocks:
pre-tested code for common
event-processing
tasks.Adapter
Integration
Framework
Management
and Monitoring
(EMM)
Playback and
Analysis
Apama
Studio
Dashboard
Builder
• MonitorScript
•Java
• Scenario
Event
Modeler
GUIs and
Container Processes
using Client APIs
Event
Correlator
Dashboard GUI
5
© 2009 Progress Software Corporation. All rights reserved.
Dashboard Server
Topics
 What is an Apama Scenario?
 Creating a Scenario in Event Modeler
•
•
•
•
6
Defining States
Defining Variables
Using Blocks
Composing Rules
© 2009 Progress Software Corporation. All rights reserved.
What is an Apama Scenario?
 An Apama scenario is a description of a real-time
business strategy
• Event trigger and value analysis
• Action response
 An Apama application can consist of a single
scenario or several cooperating scenarios
• You can have an application with no scenarios in it
• You do not need to use scenarios
 In Apama Studio, a scenario is saved as an SDF file
• scenario definition file
7
© 2009 Progress Software Corporation. All rights reserved.
What is an Apama Scenario?
 Examples:
• A financial markets application that watches for changes in
the value of named stocks and emits an event should a
stock of interest fall below a parameterized value.
• A manufacturing plant monitoring application that ensures if
an error occurs on the plant floor (a machine breaks down,
missed production step) that the production plan is adjusted
and someone is notified to take action.
8
© 2009 Progress Software Corporation. All rights reserved.
Components of a Scenario

States
•
•

Variables
•
•

Integrate scenarios with the rest of Apama
Encapsulate reusable functionality
Rules – each rule is comprised of:
•
•
9
Used to contain working data and parameters
Can be marked as inputs and outputs
Blocks
•
•

A scenario is in one active state at a time
The state determines:
– The events that are listened for
– The active rules
A condition which is event-triggered
An action which:
– Sets variables
– Performs operations
– Causes state transitions
© 2009 Progress Software Corporation. All rights reserved.
Creating a Scenario in Event Modeler
Edit rules
Specify
sequence of
states –
Intuitive visual
user interface
design
Define variables –
Values can be
adjusted at run
time to specify
conditions to
monitor, analyze,
and act upon
Demonstration
Add Block Instances
– Encapsulated,
pre-packaged code
10
© 2009 Progress Software Corporation. All rights reserved.
Topics
 What is an Apama Scenario?
 Creating a Scenario in Event Modeler
•
•
•
•
11
Defining States
Defining Variables
Using Blocks
Composing Rules
© 2009 Progress Software Corporation. All rights reserved.
Defining States
 State transition programming paradigm
• A scenario instance moves through a set of states
 A state includes one or more “if…then” rules
• Determine the scenario instance’s behavior when
in that state
 Only one state is active at a time
• No branching or sub-states
 Special start and end states
• Start state is entered upon creation of a scenario
instance
• When the scenario instance reaches the end
state, it has finished processing
12
© 2009 Progress Software Corporation. All rights reserved.
Guidelines for Defining States
 Think of states as belonging to two categories:
• Wait state
– Scenario is waiting for an event (for example, a block update) to
trigger its next action
• Processing State
– A state which should always cause a transition to some other state
(for example, determine buy or sell)
13
© 2009 Progress Software Corporation. All rights reserved.
Guidelines for Defining States
 Try to minimize the number of states in a scenario
• Scenarios with more rules in fewer states often perform better
• If you have more than 20 states you probably need to refactor
(using a block, possibly exported from a scenario)
 Only add a state when the behavior of the strategy
changes
• Examples: Waiting for opportunity, submit order, wait for order to
finish
 Give states meaningful names
• For debugging purposes
14
© 2009 Progress Software Corporation. All rights reserved.
Defining States in Event Modeler
 To add a state, click the add button:
 To rename it, double-click the state:
 To remove it, select it and click the delete button:
 To move it, drag and drop
 To resize it, drag a resize handle:
15
© 2009 Progress Software Corporation. All rights reserved.
Exercise: Define States
 Objectives
• Create a new scenario in the Event Modeler
• Add states to the scenario
 Instructions
• Exercises 1 and 2 in the “Exercises: Scenarios“ handout
(file name: 2-115_CreateScenario.pdf)
Lab Exercise
16
© 2009 Progress Software Corporation. All rights reserved.
Topics
 What is an Apama Scenario?
 Creating a Scenario in Event Modeler
•
•
•
•
17
Defining States
Defining Variables
Using Blocks
Composing Rules
© 2009 Progress Software Corporation. All rights reserved.
Defining Variables
 Variables can be input, output, or neither
•
•
•
•
Inputs are specified when a scenario instance is created
Inputs can be edited by an end user from dashboards
Inputs and output values can be shown in dashboards
Variables marked neither input or output are private
– internal to the scenario
 Variables have default values
• Specified when you create the scenario in the Event Modeler
 Variables are typed
• string, number, choice, and boolean
• Variables are auto-typed
– To override, double-click
the green square next
to the variable name
18
© 2009 Progress Software Corporation. All rights reserved.
Defining Variables
 To add a variable, type its name in the empty row at the
bottom of the variable table:
 To remove a variable, select it and press the “Delete”
key or click the Delete button:
 To re-order variables, click the Up/Down buttons:
19
© 2009 Progress Software Corporation. All rights reserved.
Exercise: Define Variables
 Objective
• Define variables for your new scenario in the Event Modeler
 Instructions
• Exercise 3 in the “Exercises: Scenarios“ handout
(file name: 2-115_CreateScenario.pdf)
Lab Exercise
20
© 2009 Progress Software Corporation. All rights reserved.
Topics
 What is an Apama Scenario?
 Creating a Scenario in Event Modeler
•
•
•
•
21
Defining States
Defining Variables
Using Blocks
Composing Rules
© 2009 Progress Software Corporation. All rights reserved.
What is a Block?
 A block is encapsulated re-usable code
 Blocks provide integration between scenarios and the
rest of Apama
• They can send and receive events
 Blocks can also provide re-usable utility code
• For example: Averaging a signal over a time window
22
© 2009 Progress Software Corporation. All rights reserved.
What is a Block?
 Blocks are saved as BDF files
 Blocks are kept in catalogs
• Catalogs are directories
• Catalogs can contain subdirectories
• Blocks are stored in directories named <blockname>.BDF
– For example: ABlock.bdf
• The block files themselves use the same name, appended
with a version number
– For example: ABlock v1.0.bdf
– Allowing for multiple versions
23
© 2009 Progress Software Corporation. All rights reserved.
Why Use Blocks?
 Scenarios need to interact with the outside world
• Source input data
• Send output data
• Perform operations
 Blocks provide access to common pre-tested utility code
• Instead of writing it afresh in each scenario
Scenario
Logic
24
Actions
Block
© 2009 Progress Software Corporation. All rights reserved.
Events
Other
Apama
Application
Components
Components of a Block Interface

Parameters
•
•
•

Output feeds
•
•

Can be used to chain calculations in a scenario without using rules
Are structured like outputs, with multiple typed fields
Operations
•
•
25
Often represent an event received by the block, often an update
Contain multiple fields each of which is typed
Input feeds
•
•

Act like scenario variables and are typed in the same fashion
Affect the block’s operation
Often provide the parameters for operations
Cause things to happen, usually by causing an event to be sent to
the rest of Apama
Do not have parameters, but often use the block’s parameters
© 2009 Progress Software Corporation. All rights reserved.
Manipulating Blocks in Event Modeler
 To add an instance of a block to the scenario, select
the block in the catalog and click the Add button:
 To remove it from the scenario, select it from the
block list or block wiring view and click the Delete
button:
 You can set block parameter values in the same
ways that you set variable values: use literal value or
link to other variables
26
© 2009 Progress Software Corporation. All rights reserved.
Wiring Blocks Together
 To wire block input and output feeds to each other,
use the Block Wiring view and drag a line from an
output node to an input node:
 Use the Configure Block Wiring
dialog to map the individual fields
27
© 2009 Progress Software Corporation. All rights reserved.
Linking Blocks and Variables
 Linking variables to blocks
• Link scenario variables to a block output feed
– Via the right-click menu
• Whenever the block outputs an event on the given feed, the
variable is automatically updated
 Linking blocks to variables
• Link block parameters to scenario variables
– Via the right-click menu
• Whenever the variable’s value is modified, the block’s
parameter is automatically updated
28
© 2009 Progress Software Corporation. All rights reserved.
Exercise: Adding Blocks and Linking Variables
 Objective
• Add block instances to your scenario
• Link block parameters and variables
 Instructions
• Exercises 4 and 5 in the “Exercises: Scenarios“ handout
(file name: 2-115_CreateScenario.pdf)
Lab Exercise
29
© 2009 Progress Software Corporation. All rights reserved.
Topics
 What is an Apama Scenario?
 Creating a Scenario in Event Modeler
•
•
•
•
30
Defining States
Defining Variables
Using Blocks
Composing Rules
© 2009 Progress Software Corporation. All rights reserved.
Composing Rules
 Rules define scenario behavior
• A rule is an if-then statement
 Each rule contains three sections:
• Name and Description (optional)
– Recommended for debugging
• Condition - An event-triggered
boolean expression
• Action - An action that takes
place should the condition be true
– Sets variables and block parameters
– Performs operations on blocks
– The last action is always a state transition rule
 Rules are contained within each state
• Global rules are copied and pasted into every state
31
© 2009 Progress Software Corporation. All rights reserved.
How Rules are Evaluated
 Rules are evaluated sequentially (top to bottom)
• Global rules before state-specific rules
• When one rule’s condition holds, its action is executed
• When the transition action is “continue”, evaluation continues
downwards
• After the state changes, the new state’s rules are
immediately evaluated
 When no rule evaluates to true
• The scenario waits in the current state
• Whenever a relevant input variable or block output changes
rules are re-evaluated
32
© 2009 Progress Software Corporation. All rights reserved.
Rule Conditions
 A rule condition can refer to a field of an output feed
of a block
• For example: A rule can trigger when a statistics block
outputs an average value of 100 or higher
 Be aware that the semantics of this are subtle:
• Scenario instances are constantly saving a copy of the most
recent event from each output feed of each block instance
• When referring to an output feed, the test is on this copy
(which could have been taken before the current state was
entered)
• Any condition referring to an output feed that has not yet
fired an event always evaluates to false
– Even “X = X”!
33
© 2009 Progress Software Corporation. All rights reserved.
Rules and State Transitions
Different ways to move within the same state
State1
State1
? Condition A
? Condition A
! ...
! ...
? Condition B
? Condition B
! Continue
! Move to State1
? Condition C
? Condition C
! ...
! ...
“Continue”
“Move To <same state>”
Continues to the next rule in the state
Restarts with first rule in the state
(i.e. Condition C is checked)
(i.e. Condition A is checked)
Beware of creating infinite loops !
34
© 2009 Progress Software Corporation. All rights reserved.
Composing Rules in Event Modeler
 To add a rule, click the Add button:
 To re-order rules, click the Up/Down buttons:
 To remove a rule, press the Delete key or click
the Delete button:
35
© 2009 Progress Software Corporation. All rights reserved.
Right-click Rule Construction
 You build both the rule’s conditions and actions
using right-click menus
 Rule construction can be quicker using copy and
paste
 Rule expressions are trees
• By clicking more times on a leaf element, you can select
more of the tree
• The selection can be:
– Copied or pasted over
– Changed or reverted using the right-click menu
36
© 2009 Progress Software Corporation. All rights reserved.
Expressions in Rules
 Expressions are used in conditions and actions
 Expression are assembled by choosing:
• Operators
–
–
–
–
–
Numeric operators (<, ≤, >, ≥, =, ≠)
Text operators (=, ≠, contains)
Choice operators (=, ≠)
Logical operators (and, or, not)
Arithmetic operators (+,-,*,/)
• Values
–
–
–
–
–
37
Constants
Scenario variables
Block parameters
Function calls
Block output feed event fields
© 2009 Progress Software Corporation. All rights reserved.
Functions in Expressions
 Event Modeler provides some commonly-required
functions
 For example:
• abs(n), ceil(n), floor(n), round(n,dp)
• concat(t1,t2), replace(original,old,new)
• to_boolean(t), to_number(t), to_text(n)
 You can also add your own functions
38
© 2009 Progress Software Corporation. All rights reserved.
Example of Constructing a Condition
39
© 2009 Progress Software Corporation. All rights reserved.
Adding and Removing Actions
 To add an action
statement to a rule’s
body, left-click
on the circle
 To delete an action
statement from the
rule’s body, right-click
on the circle
40
© 2009 Progress Software Corporation. All rights reserved.
Exercise: Composing Rules
 Objective
• Compose rules in a scenario using the Event Modeler
 Instructions
• Exercises 6 and 7 in the “Exercises: Scenarios“ handout
(file name: 2-115_CreateScenario.pdf)
Lab Exercise
41
© 2009 Progress Software Corporation. All rights reserved.
Limit Lab Schematic: Day 2 Scenarios
Correlator
Input
Data
BestBidAsk
marketvents.evt
BestBidAsk
BestBidAsk
Off Market Limit Order
Scenario
NewLimitOrder
Market Data
Block
OrderFinished
User Console
(Apama Studio
views)
NewOrder
Simple
Simulator
OrderFinished
OMS
Block
OrderFinished
Position
42
© 2009 Progress Software Corporation. All rights reserved.
Position
Service
Where to Get More Information
 Apama 4 Documentation
Developing Apama Scenarios book
• From PC Desktop: Start Programs Apama 4
Documentation
• In Apama Studio: Help Help Contents Apama Studio
Documentation
 Online Tutorial
• Building an Application with Event Modeler
43
© 2009 Progress Software Corporation. All rights reserved.
Progress Apama Fundamentals
Developing Apama Scenarios with
Event Modeler
Presenter’s Name
Presenter’s Job Title and Association
Date