Post date: Sep 07, 2012 2:9:20 AM
Background
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
Example
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"/>
and
<DataListeners>
<Listener Name="Login" Statement="LoginListener" Class="Message" Operation="Save" Parameters="Object=Person&ObjectID={PersonID}&Message=Testing&BodyText=Whatever here"/>
</DataListeners>
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
Configuration
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