Data Listeners

posted Sep 6, 2012, 7:09 PM by Eric Patrick   [ updated Jul 5, 2017, 7:53 PM ]


Data Listeners are business rules invoked when data in the database changes. Examples include:
  • When a Bankruptcy is created, change parent Debt status to 'Awaiting Bankruptcy Notification'
  • When a Valuation enters a status of accepts, remove access from non-assigned agents
  • When a Custom Form is completed, complete a corresponding DecisionStep and process the Decision 


For demonstration purposes, the Person.config file contains a data listener called Login, that creates a Message bound to a Person when they log in. Person.config entries include:

<Statement Name="LoginListener" Query="SELECT PersonID FROM Person WHERE LastLogin >= @FromDate"/>


<Listener Name="Login" Statement="LoginListener" Class="Message" Operation="Save" Parameters="Object=Person&amp;ObjectID={PersonID}&amp;Message=Testing&amp;BodyText=Whatever here"/>

To schedule this listener, navigate to:

Person.ashx/Schedule/Listen?Listeners=Login&Schedule=Daily at 9am

This will queue the listener to execute daily at 9am, dynamically creating an appropriate schedule. Each time the listener is run, the schedule will be available to the listener, and the listener will update the schedule with the last run date, thus keeping track of the last time the listener was run.  This schedule last run date will be passed to the data listener's statement as a FromDate parameter.

To unit test this listener directly, navigate to:

Person.ashx/Listen?Listeners=Login&From=9/4/2012 -- change the date to something more appropriate for your database


Data listeners may be defined from the UI via Design > Configuration > Modules > {Module} > Listeners tab. Each Listener element includes the following properties:
  • Name: the name of a data listener; must be unique within the <DataListeners> element
  • Statement: a statement to execute to gather a list of rows that meet the listener conditions
  • Class: the name of an AbstractObject-derived class that will be invoked for each row returned by the statement
  • Operation: the operation to invoke for each row returned by the statement
  • Parameters: query-string formatted parameters to be passed to the Operation
  • Async: when true, the Class/Operation will be queued; otherwise it will be invoked immediately
  • StopOnError: when true, errors encountered when call Class/Operation will be thrown, stopping the processing of the listener.
Defining a data listener does not run the data listener; something else must trigger the execution of the listener. This may be done via:
  • a schedule job (see above)
  • a workflow step (e.g. a step calling Person/Listen?Listeners=Login&From={today}
  • a power user navigating to the appropriate URL
  • third party automation