Page tree
Skip to end of metadata
Go to start of metadata



The USxS applications are based on an "Event Driven Architecture" which promotes loose coupling between components of the application.  A full explanation of events and event driven applications is beyond the scope of this document.  In essence, an event is published to represent a state change in the application.   Components interested in certain types of events may listen for an event and react to it.  

Events in USxS fall into these general categories:

  • Repository Events:  CRUD operations:
    • ValidationEvent()
    • RepositoryModificationEvents():
      • CreateObjectEvent()
      • UpdateObjectEvent()
      • DeleteObjectEvent()
  • Business Logic Events: Significant operations such as "Period Closed" or "Check Voided" 
    • PostingPeriodOpenEvent()
    • BudgetEvent()
      • BudgetInitialEvent()
      • BudgetAdjustmentEvent()
  • Application LifeCycle: Application started, Module Installed
  • Authentication Events: Authentication Success/Failure, Password Change

Components listening for events can perform any action needed by the component.  In general, listeners fall into one of these types:

  • Validation
  • Posting
  • Notification
  • Logging/Auditing

For repository (database) related events, the listeners are full participants in the database transaction.  Therefore, a listener may veto a transaction and cause the database transaction to rollback.

Rules Event Listener

One listener is always present and listens for all events and invokes the "Rules Engine".   Rules may perform the same functions as any other listener.   Generally, they are used for validation and notification.  A validation rule may, for instance, generate an error and cause the transaction to roll back.

Rules Engine

The rules engine is based on an open source project called Drools.  Drools provides an high performance, flexible rules engine based on a custom language.  The USxS application provides a user interface to allow users to inspect, enable or disable and even write their own rules.  Rules can be customized for individual districts by the SSDT, ITC or even district personnel.

Developing and implementing rules is a complex topic. Further documentation and training will be provided in the future.

Rule Sets

A "Rule Set" is a group of rules related to a specific business function or module.  Many rule sets are included with the software installation.  These are standard rules developed by the SSDT to implement standard and optional business rules.

A rule set has the following properties:

BundledIndicates the ruleset is distributed as part of the application and can not be modified. Bundled rules are automatically loaded when the application starts or when a module is installed.
MandatoryMandatory rules are integral to the business rules of the application. Mandatory rules are bundled rules which can not be disabled.
EnabledNon-mandatory or user-written rules can be enabled or disabled. The applications contain a number of optional rules which can be enabled or disabled to cause optional behavior.
StreamA special category of rule which processes streams of events over time. Currently only used by the authentication system to implement break-in detection and evation.

Security and Safe Mode

The rules engine is very powerful and flexible, but also potentially dangerous.   Rules are executed as part of a database transaction as the result of a user action.  However, as part of the business rules, they execute with elevated privileges.  Therefore, a user which has the ability to modify or create rules effectively has full administrator rights.  

Furthermore, it is possible to create a flawed or malicious rule that could effectively disable the application.  For example, a rule could cause all authentications to fail or all transactions to rollback.

For this reason, the applications provide a "safe mode" which disables all non-bundled rules.  This would allow the application to be usable to correct the problem.  Safe mode is enabled by creating setting a SAFE_MODE environment variable in the affected service in the docker-compose.override.yml:

   - SAFE_MODE=true

With this property in place, only rules provided by the SSDT will be enabled on the next application startup.   All user created rules will be disabled. After the offending rule is repaired or disabled, the environment variable should be removed and the application restarted.

It is important to not leave the application executing in safe mode for extended periods. If a district has any local rules, then they will not be activated and the system may not behave as expected.







  • No labels