Skip to main content
Version: 5.2.0.0

Database Listener

Description​

The Database Listener is an inbound channel which scans a database table for records matching certain conditions.

Whenever records are found matching the search condition, the records are read and their content is returned from the channel as structured message. The recognized records then are marked as read by setting a flag on a column to avoid that the records are processed a second time.

Purpose of object​

The Database Listener serves as means to start a process model whenever the content of a database table changes.

Creation​

To create a Database Listener channel follow the steps described in the general description of Channels.

Step by Step​

  • Database: The selected database connection.

  • Inbound Message the Message type representing the table and possible dependent child tables of the database. Click on the button denoted by three dots to open a dialog where you can select a message type and the Root table of that structure. Only Message types which are imported from the database are selectable.

(add image)

The channel regularly selects the Root table to search for records which fulfill the Wait condition.

  • Timing

Typically the channel searches its source for available data periodically:

(add image)

To change the intervals at which the channel searches its data, the user clicks on the button labeled with three dots and then can edit the timer properties.

There are two types of timers, periodical timers and absolute timers. Both are configured using the same dialog. In most cases a periodically timer is used which regularly creates a signal.

(add image)

  • Description for the timer, e.g. polling timer

  • Valid from/to Here the user can state a time span where the timer is valid. Outside of this time span, the timer is invalid and doesn't create events.

  • Mode This Option is only sensible if the timer dialog is used to configure a timer event. In the context of channels it is disabled.

  • Trigger type The user may restrict the timer to work only at certain days:

    • Daily Here the user may restrict the timer to fire events on certain days of the week
    • Monthly Here the user may restrict the timer to fire events at a particular day of the month

  • Absolute If an absolute timer is configured, the user must enter a fixed time at which the timer raises an event. E.g. one could declare the timer to run every day at 6:00 in the morning.

  • Periodically If an Periodical timer is used the user has to configure the following properties:

    • Start/End time A time span of the day where the timer shall be active
    • Repeat count Here the user may restrict the timer to fire only a certain amount of events after start. E.g. one could declare the timer to start at 6:00 AM an fire exactly 2 times. The standard value is infinite, that means there is no restriction.
    • Repeat interval the time interval after which an event is fired periodically.

  • Threshold The maximum number of records which are read at once within a polling interval. You can select 1, 10, 50, 100, 250 and infinite here.

  • Mode There are two working mode which you can select here: One message per record or Create one message with all available records.

  • Primary key The columns of the Root table identifying a record. Click on the button denoted by three dots to open a dialog where you can select the columns which together form the unique key.

(add image)

  • Wait condition A SQL condition used in the where part of the polling statement to select the columns to read. Typically Wait condition and a processed action are complementary. In the example above the Wait condition is READSTAT = 0 and the processed action READSTAT = 1.

•- Order by a list of column names of the Root table defining the order of the result. Because this is simply added to the generated SQL statement to select the Root table, you can add the key words ASC or DESC to the column list.

  • processed action You may select either Delete or Update here. If you select Update you must enter an Update action like <columnname = <value>

  • Start error process

If the channel encounters an error you can connect it in the process model with an error start event to create a process instance for handling that error.

If you leave the error hold time field as blank then the process instance will be created every time an error occurs. If errors occur rapidly, a lot of process instances will be created. You can avoid this by entering a period of time in the field. Any further errors occur within this period, no further error process instance will be created.

  • Foreign key definition In this panel the user has to define the relationship between a parent table (e.g. the RootTable) and its details. You have to click on the buttons denoted by three dots to open a dialog where the foreign key relationship has to be defined.

(add image)

A foreign key is a reference to a primary key on the referenced table, so a foreign key can consist of several columns. In this dialog you can add all the columns which are part of the foreign key and the related columns of the references primary key.

You also may add an optional where condition to constrain the records selected from the detail table.

Throttling​

This channel is supported by throttling limit feature that described in chapter Throttling designer.

See also​

Use the Database Target or the Database outbound channel to write data to a database.

Use the Outbound channels Database Reader, Database Source Reader or the Database outbound channel to read data from a database.