Getting started with Apama Queries and DES

In this blog I’ll describe a simple example to get you started with Apama queries and the Digital Event Service (DES). Two technologies within the SoftwareAG webMethods analytics Suite.

Following components were used in the setup (on version 10.0):

• Apama
• Universal Messaging (UM)
• webMethods Integration Server (IS)

For those new to the Digital Event Service (DES) and/or Apama, it may be helpful to read the introductions on documentation.softwareag.com.

The example setup: Our webMethods IS receives Car parking events for the City of Ghent and publishes the events to UM. An Apama query subscribes to the events, when Apama detects the predefined pattern it publishes an alert back to UM.

Configuring the project

Open the ‘Apama workbench’ workspace in Designer and create a new Apama project. Under ‘Connectivity and Adapters’, we’ll only need the ‘Digital event services’ and ‘Universal messaging’ packages. Find the ‘UMConnectivity.properties’ file and provide to url to the UM realm. To enable the query functionality add the Query Support Bundle to the project.

Now comes the DES magic, open the ‘EventTypeList.apamades’ file and click the ’Sync from Digital Event Services’. Eclipse will look for DES events on UM and generate the required Apama assets for you. Note that the 2 selected events (screenshot below) were created via the IS by defining publishable IS documents. These were synchronised to UM on the DES channel.

Sync and select the DES event types

Under the ‘autogenerated’ directory you’ll find the generated monitor files which defines the ParkingEvent and the GeneralAlert in the context of Apama.

Creating the CEP logic

There are 2 ways to define CEP logic in Apama, the conventional way using monitor scripts and via the query language. In this guide we’ll use a query to define the event pattern. Apama has a specific channel on which queries listen for incoming events. First create a Monitor script which sends every received event to this “com.apama.queries”-channel.

Create a monitor file under the ‘monitors’ directory:

using com.softwareag.connectivity.ConnectivityPlugins;
using MyApamaApp.docs.ParkingEvent;
using com.apama.queries.QueriesStarted;
monitor ParkingtMonitor {
   ParkingEvent ev;
 
   action onload() {
      print “Loading parking monitor …”;
 
      // Define the events to listen for and the action to perform
      on all ParkingEvent():ev processParkingEvent();
 
      ConnectivityPlugins.onApplicationInitialized();
      ParkingEvent.subscribe();
 
      print “Parking monitor ready!”;
   } 
 
   // Action to perform on all Parking events
   action processParkingEvent() {
 
      // For every print event print a statement to the console
      print “Parking event received for “ + ev.name;
 
     //Send the parking event the queries channel
     send ev to “com.apama.queries”;
   }
}

Let’s create the query itself. The query can be configured by a GUI or via the apama query language. Define the events on which to listen (ParkingEvent), a pattern, the condition and the action to be performed when the pattern is detected. In this case we’ll create a new event and print a log to the console (see screenshot and source code below).

using MyApamaApp.docs.ParkingEvent;
query MajorIncreaseOnSingleParking { 
 
// Define the ParkingEvent inputs partitioned by name 
// and with a window of 2 occurrences
inputs {
   ParkingEvent() key name retain 2;
}
// Define the pattern to look for
find ParkingEvent as p1 -> ParkingEvent as p2
 where (p2.availableCapacityPercentage.toFloat() — p1.availableCapacityPercentage.toFloat()) >= 0.20 {
 
   %send(  “eventType”:”.MyApamaApp.docs.GeneralAlert”,
           “title”:”Send General Alert”, “description”:””,
           “channel”:”\”des:MyApamaApp.docs.GeneralAlert\””,
           “fields”: {
             “type”:”\”MajorIncreaseOnSingleParking\””,
             “message”:”(p2.name).toString() + \” free capacity has dropped to \” + (p2.availableCapacityPercentage).toString() + \” \””
           } 
   );
 
   %custom( “title”:”Print to console”,”description”:””) {
        print “ALERT for “ + p1.name + “/” + p2.name + “ : “ + “It’s getting busy … “ + p2.availableCapacityPercentage + “ More 20% increase”;
   }
 }
}

Note that the source code is generated when you’ll configure it via the GUI. To test the setup, you can define some test events in a ‘.evt’ file under the events directory. Verify the setup by pressing the play button and looking at console output.

That’s all. Now you’re ready to dive deeper into the query language and start building more advanced CEP patterns!

Greetings

Samuel