Skip to main content

Real-time triggers (Evaluator)

Overview​

The Genesis Evaluator is a microservice used for triggering events.

You can configure two types of trigger:

  • scheduled events (Cron rules) are run automatically at the specified dates and times
  • data-driven events (Dynamic rules) are run when data in a table meets the rules you have specified

When a trigger happens, an event handler event message is sent, and its business logic is run. You must configure the required logic in the event. For example, it could update the data model, it could trigger the generation and publishing of a file, or it could trigger another event. By configuring the Evaluator and Event Handler, you can meet your exact business requirements.

Unlike most server capabilities in the Genesis Application Platform, you don't have to configure a .kts file to set up Evaluator; it is entirely driven by records in these two tables:

  • CRON_RULE for time-based (scheduled) events; you specify the schedule as a Quartz Cron Expression
  • DYNAMIC_RULE for data-update-driven events; you specify which value is to be monitored in a table or view, the boolean logic for triggering the event, and the event to be triggered

Example configuration​

Scheduled events​

Example CRON_RULE table entry:

NAMECRON_EXPRESSIONDESCRIPTIONTIME_ZONERULE_STATUSUSER_NAMEPROCESS_NAMEMESSAGE_TYPERESULT_EXPRESSION
US desk position report0 45 6 ? * MON-FRI *Send position report to US deskAmerica/New_YorkENABLEDadminPOSITION_EVENT_HANDLEREVENT_POSITION_REPORT(DESK == 'US')

In this example, the EVENT_POSITION_REPORT event will be triggered with DETAILS parameter DESK == 'US' at 06:45 AM (EST/EDT) each week day.

Given its name, we can expect this event to generate and distribute a report for a particular desk's positions.

Data-driven events​

IDNAMEDESCRIPTIONUSER_NAMERULE_TABLERULE_STATUSRULE_EXPRESSIONPROCESS_NAMEMESSAGE_TYPERESULT_EXPRESSIONTABLE_OPERATIONIS_TEMPLATERULE_EXECUTION_STRATEGYRULE_TYPE
000000000000001DRLO1Warn large tradeTrigger warning event on notional traded over 1,000,000adminTRADE_VIEWENABLED(NOTIONAL > 1000000)EVENT_LARGE_TRADE_WARNING(TRADE_ID = TRADE_ID)INSERTfalseONCE_PER_RECORD

In this example, the EVENT_LARGE_TRADE_WARNING will be triggered with DETAILS parameter of TRADE_ID == <the record's trade id> when the TRADE table (the root table of the TRADE_VIEW in our example data model) has a new record inserted where the NOTIONAL is greater than 1,000,000.

Given its name, we can expect this event to trigger some business workflow for large trades with the desk.

The Genesis Evaluator's DYNAMIC_RULE data-driven events are used to power the notifications and alert component.

Configuration options​

Here, we look look more closely at the two tables and values that we can expect in their records.

CRON_RULE​

Field NameDescriptionExample ValueMandatory
NAMEName of the rule. This is a key, and so each entry must have a unique valueUS desk position reporttrue
CRON_EXPRESSIONQuartz Cron Expression defining when the rule triggers0 45 6 ? * MON-FRI *true
DESCRIPTIONDescription of the ruleSend position report to US desktrue
TIME_ZONEThe Time Zone of the cron expression. Be careful selecting time zones that don't shift with daylight savings, such as EST, which may or may not be desirable. Defaults to the system time where left blankAmerica/New_Yorkfalse
RULE_STATUSThe status of the rule. If anything other than ENABLED, the rule will not listen or trigger any event.ENABLEDtrue
USER_NAMEThe username that will be sent on the triggered event. User must have permission to use this event for it to be triggered successfullyadminfalse
PROCESS_NAMEThe name of the process to send the resulting eventPOSITION_EVENT_HANDLERtrue
MESSAGE_TYPEThe name of the event the rule should send when triggeredEVENT_POSITION_REPORTtrue
RESULT_EXPRESSIONThe details to send on the event message. The syntax is that event fields should be left of the = and you can use literal values to the right. Multiple event fields are separated by &&(DESK == 'US') && (TRIGGER == 'RULE')false

Rules are managed via the API, which exposes CRUD operations for maintaining the table.

DYNAMIC_RULE​

Field NameDescriptionExample ValueMandatory
IDID for the rule. Auto-generated where left unspecified on insert000000000000001DRLO1true
NAMEName of the ruleLarge tradetrue
DESCRIPTIONDescription of the ruleA large trade has been receivedtrue
USER_NAMEThe username that will be sent on the triggered event. User must have permission to use this event for it to be triggered successfullyadminfalse
RULE_TABLEThe table or view the rule listens to for updatesTRADE_VIEWtrue
RULE_STATUSThe status of the rule. If anything other than ENABLED, the rule will not listen or trigger any eventENABLEDtrue
RULE_EXPRESSIONBoolean logic for trigger. The expression can reference any of the fields on the updated table or view. The expression must be wrapped in brackets((NOTIONAL > 1000000))false
PROCESS_NAMEThe name of the process to send the resulting event. As of v8, this is optional; service discovery will be used to find the process to send the event. We recommend that you leave this blank to work in all environments, including those running compact processes, or for consul environmentsPOSITION_EVENT_HANDLERfalse
MESSAGE_TYPEThe name of the event the rule should send when triggeredEVENT_LARGE_TRADE_WARNINGtrue
RESULT_EXPRESSIONThe details to send on the event message. The syntax is that event fields should be left of the = and you can use literal values or field values from the RULE_TABLE to the right. Multiple event fields are separated by &&(TRADE_ID = TRADE_ID) && (TRIGGER = 'RULE')false
TABLE_OPERATIONThe table operations to trigger the rule on. Valid operations are INSERT, MODIFY and DELETE. You can configure more than one operation to trigger the rule; where you do this, these must be pipe-delimited. If this value is left blank, only INSERT table operations will trigger the ruleINSERT|MODIFY|DELETEtrue
IS_TEMPLATERelevant when using notifications and alert component where users can define rule templates to which users subscribe. Rules marked as true are templates, are never triggered (a subscription to a template creates a new dynamic rule)false
RULE_EXECUTION_STRATEGYDefines how many times the rule should trigger for a given record (record of root table where RULE_TABLE is a view). Valid values are UNLIMITED, ONCE_ONLY, ONCE_PER_RECORD. Default is UNLIMITED. This is helpful if TABLE_OPERATION must include MODIFY and the records may have many modifications to stop repeated alertsONCE_ONLYfalse
RULE_TYPEUsed to specify that this rule belongs to a group. For example, the notifications and alert component will set this value to NOTIFYNOTIFYfalse

Rules are managed via the API, which exposes CRUD operations for maintaining the table. Components such as notifications and alert component include a user interface that manages dynamic rule set-up and reads application metadata to help users populate table/view selection and expressions.

Client API​

Rules can be managed via the API.

In the examples below, responses are omitted for brevity; they are standard eventHandler acks/nacks.

CRON_RULE API​

EVENT_CRON_RULE_INSERT​

Insert a new Cron Rule.

All parameters, descriptions and defaults are listed under CRON_RULE configuration options

{
  "USER_NAME": "admin",
  "SOURCE_REF": "001",
  "MESSAGE_TYPE": "EVENT_CRON_RULE_INSERT",
  "DETAILS": {
    "NAME" : "US desk position report",
    "CRON_EXPRESSION" : "0 45 6 ? * MON-FRI *",
    "DESCRIPTION" : "Send position report to US desk",
    "TIME_ZONE" : "America/New_York",
    "RULE_STATUS" : "ENABLED",
    "PROCESS_NAME" : "POSITION_EVENT_HANDLER",
    "MESSAGE_TYPE" : "EVENT_POSITION_REPORT",
    "RESULT_EXPRESSION" : "(DESK == 'US')",
  }
}

EVENT_CRON_RULE_AMEND​

Amend an existing rule.

Changing the time to 7am from example above.

All parameters, descriptions and defaults are listed under CRON_RULE configuration options

{
  "USER_NAME": "admin",
  "SOURCE_REF": "002",
  "MESSAGE_TYPE": "EVENT_CRON_RULE_AMEND",
  "DETAILS": {
    "NAME" : "US desk position report",
    "CRON_EXPRESSION" : "0 45 6 ? * MON-FRI *",
    "DESCRIPTION" : "Send position report to US desk",
    "TIME_ZONE" : "America/New_York",
    "RULE_STATUS" : "ENABLED",
    "PROCESS_NAME" : "POSITION_EVENT_HANDLER",
    "MESSAGE_TYPE" : "EVENT_POSITION_REPORT",
    "RESULT_EXPRESSION" : "(DESK == 'US')",
  }
}

EVENT_CRON_RULE_DELETE​

Delete an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "003",
  "MESSAGE_TYPE": "EVENT_CRON_RULE_DELETE",
  "DETAILS": {
    "NAME" : "US desk position report",
  }
}

EVENT_CRON_RULE_ENABLE​

Enable an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "004",
  "MESSAGE_TYPE": "EVENT_CRON_RULE_ENABLE",
  "DETAILS": {
    "NAME" : "US desk position report",
  }
}

EVENT_CRON_RULE_DISABLE​

Disable an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "005",
  "MESSAGE_TYPE": "EVENT_CRON_RULE_DISABLE",
  "DETAILS": {
    "NAME" : "US desk position report",
  }
}

DYNAMIC_RULE API​

EVENT_DYNAMIC_RULE_INSERT​

Insert a new dynamic rule.

All parameters, descriptions and defaults are listed under DYNAMIC_RULE configuration options

{
  "USER_NAME": "admin",
  "SOURCE_REF": "006",
  "MESSAGE_TYPE": "EVENT_DYNAMIC_RULE_INSERT",
  "DETAILS": {
    "NAME" : "Warn large trade",
    "DESCRIPTION" : "Trigger warning event on notional traded over 1,000,000",
    "USER_NAME" : "admin",
    "RULE_TABLE" : "TRADE_VIEW",
    "RULE_STATUS" : "ENABLED",
    "RULE_EXPRESSION" : "(NOTIONAL > 1000000)",
    "MESSAGE_TYPE" : "EVENT_LARGE_TRADE_WARNING",
    "RESULT_EXPRESSION" : "(TRADE_ID = TRADE_ID)",
    "TABLE_OPERATION" : "INSERT",
    "IS_TEMPLATE" : "true",
    "RULE_EXECUTION_STRATEGY" : "ONCE_PER_RECORD",
  }
}

EVENT_DYNAMIC_RULE_AMEND​

Amend an existing rule.

Changing to also trigger on modifications to the record.

All parameters, descriptions and defaults are listed under DYNAMIC_RULE configuration options

{
  "USER_NAME": "admin",
  "SOURCE_REF": "007",
  "MESSAGE_TYPE": "EVENT_DYNAMIC_RULE_AMEND",
  "DETAILS": {
    "ID" : "000000000000001DRLO1",
    "NAME" : "Warn large trade",
    "DESCRIPTION" : "Trigger warning event on notional traded over 1,000,000",
    "USER_NAME" : "admin",
    "RULE_TABLE" : "TRADE_VIEW",
    "RULE_STATUS" : "ENABLED",
    "RULE_EXPRESSION" : "(NOTIONAL > 1000000)",
    "MESSAGE_TYPE" : "EVENT_LARGE_TRADE_WARNING",
    "RESULT_EXPRESSION" : "(TRADE_ID = TRADE_ID)",
    "TABLE_OPERATION" : "INSERT|MODIFY",
    "IS_TEMPLATE" : "true",
    "RULE_EXECUTION_STRATEGY" : "ONCE_PER_RECORD",
  }
}

EVENT_DYNAMIC_RULE_DELETE​

Delete an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "008",
  "MESSAGE_TYPE": "EVENT_DYNAMIC_RULE_DELETE",
  "DETAILS": {
    "ID" : "000000000000001DRLO1",
  }
}

EVENT_DYNAMIC_RULE_ENABLE​

Enable an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "009",
  "MESSAGE_TYPE": "EVENT_DYNAMIC_RULE_ENABLE",
  "DETAILS": {
    "ID" : "000000000000001DRLO1",
  }
}

EVENT_DYNAMIC_RULE_DISABLE​

Disable an existing rule.

{
  "USER_NAME": "admin",
  "SOURCE_REF": "010",
  "MESSAGE_TYPE": "EVENT_DYNAMIC_RULE_DISABLE",
  "DETAILS": {
    "ID" : "000000000000001DRLO1",
  }
}

Runtime configuration​

The Evaluator process is not enabled by default. Override the genesis-processes.xml file in your application and set <start> to have a value of true. During your next build or genesisInstall, the process will show up in your list of processes.

important

Evaluator should be left set to <primaryOnly>true</primaryOnly>; otherwise, if deployed into a multi-node environment, events will be triggered multiple times.