Getting Started with Boomerang Notification Framework

In corporate environments there is an eternal need to automate and improve business processes and information management. IT shops everywhere are asked to do more, faster, with less or unchanged amounts of resources. In just about every development project that we have come across, there has been a demand for notification, communication or distribution of information. This ranges from a simple printout in a shipping application, to complex email thread handling in a tech support center.

With these insights we set out to build a notification/communication framework that is flexible, fast, dependable and that takes complexity out of the equation. We also wanted to provide a service oriented structure for easy management of all notifications/communications solutions once deployed.

About Boomerang – A Notification Framework

Boomerang is a software framework providing communication services for distribution through e-mail, twitter, printers, fax devices and file channels. Boomerang alleviates integration by offering a simple SQL database interface to developers and system integrators. Boomerang blends easily with Microsoft SQL Reporting Services. It was designed and developed by IT professionals for IT professionals. It is as simple as it gets. All you need is to insert records into ubiquitous SQL tables in order to make Boomerang “talk”.

The heart of Boomerang comprises a set of heavy-duty background Windows services which can quickly and efficiently process thousands of output tasks on a daily basis. Each service is multi-threaded and caters to a specific kind of output. There is one service for print, one for e-mail, one for twitter, one for fax, and one for file tasks. Services work independently from each other, although one Boomerang task may comprise of several kinds of output. The following picture depicts the architecture of Boomerang services.

Boomerang services implement pull technique. I.e. database tables are polled on specific time interval set independently for each delivery service.

Working with Boomerang

Interactions from your application with Boomerang services are done via database interface. This implies that any programming language can be used as long as it provides support to MS SQL Server. You will communicate with Boomerang in exactly the same way whether is it with ASP.Net application, bar-code device running a Mobile OS, or TomCat application connecting over Ruby on Rails, such as Confluence.

Notification Framework Objects

The unit of work implemented by Boomerang is called Event. You can think of Event as an application task. The Event is represented by a single record in the EVENT_MASTER table. These Event records do not carry delivery data, however they may carry application specific keys used to tie events to sources which generated them. Examples of such keys may include a helpdesk id, an application source id, a customer order number, a client lead unique identifier, etc.

Each event comprises one or more jobs. A job represents an actual unit of delivery, such as e-mail, or print. Each job declares delivery data of its own kind. For example, a print job will define at the minimum an applicable printer path. Although several jobs make up a single event, no specific order is guaranteed in which the jobs will fire. Because of the multi-threaded nature of Boomerang services, chances are they will fire all at once as soon as the corresponding event record is marked “ready”.

Some jobs may extend data to one or more auxiliary tables. For example e-mail jobs list the target recipients in a separate table called OUT_EMAIL_RECIPIENT.

Many jobs will have content or attachments for which a common storage table is designed and called EVENT_CONTENT. For example, a fax job may be set to deliver a MS SQL Reporting Services report by means of facsimile transmission. In this case the event content table would feature corresponding URL path, where a RDL report has been deployed.

Each job maintains its own status and repetition schedule in a table called EVENT_STATUS. Such schedule defines whether or not a job should fire immediately or wait a certain time delay. Also it defines whether or not the job should be retried or not in the case of failure and if so, then also the number of times and interval.

As jobs are processed an event log is being generated regardless of the completion outcome. Some jobs establish a feedback mechanism with target device. For instance, the fax service will alternate job status based on notifications it receives from MS Fax Server. The e-mail service will “listen” to the delivery reports from SMTP relay agent and will log them in association with the original e-mail job.

The illustration below depicts how various Boomerang objects (with tables they are hosted by) fit together.

Basic Process

The process below demonstrates how to create a Boomerang notification in 4 simple steps.

Create Event | Step 1

In the first step you create a new task record. Simply insert a new row in the table EVENT_MASTER. The only required field in EVENT_MASTER is the gKey (uniqueidentifier). This record will tie output jobs together as we will see in further steps. There are several columns in EVENT_MASTER that you may use to help you organize and manage different tasks. In this example we will use Created_By and Str1.

E.g.:

-------------------- Step 1 -------------------------------------------
declare @gKey uniqueidentifier; set @gKey = newid();
Insert EVENT_MASTER (gKey, Created_By, Str1)
values (@gKey, 'domain\username', 'Weekly Sales Report')

Another useful field would be Source. If you maintain a list of applications in your environment with unique integer id for each, the Source column is an ideal candidate to reference your applications.

In the above example we declared a local T-SQL variable @gKey of certain type and assigned it a value by means of the built-in T-SQL newid() function. We will need this variable in the steps below. If you are a beginner with T-SQL, you may find a lot of useful articles explaining T-SQL variables by searching this website.

Create Job | Step 2

In the second step you will select the destination. For example, e-mail, or printing, or faxing. As discussed above this will be referred to as a job. Depending on the job destination you will insert the new job into an appropriate table. The following are your options: OUT_EMAIL, OUT_FAX, OUT_FILE, OUT_TWIT or OUT_PRINT. While fields vary slightly depending on the destination nature, the job key jKey and the event key gKey are common. In this example we have chosen to send an e-mail.

E.g.:

-------------------- Step 2 -------------------------------------------
declare @jKey uniqueidentifier; set @jKey = newid();
insert OUT_EMAIL (gKey, jKey, [ReplyTo], [From], Subject, Body)
values (@gKey, @jKey, 'Boomerang_account@domain.com',
'"e-mail display name" <Boomerang_account@domain.com>',
'Weekly Sales Report', 'Message body test test test' )

Since this is an e-mail job we also need to add recipients to it. You will do this by adding one or more rows to OUT_EMAIL_RECIPIENT. An optional Type column designates recipient as either To (default), Cc, or Bcc. E-mails can be represented either by simple SMTP address or full SMTP notation, i.e. “name” <email@domain.com>. Do not forget to pass along the job reference key jKey.

E.g.:

insert OUT_EMAIL_RECIPIENT (jKey, [Email])
values (@jKey, 'e-mail_address@domain.com')

Add Content | Step 3

Albeit optional, a SQL Reporting Services report can be easily attached to our e-mail. You will do this by adding one or more rows to EVENT_CONTENT. Multiple attachments maybe added. Akin jobs, events and attachments are also identified by the key aKey. Should you add multiple attachments consider passing along the same gKey and jKey you have used in the above steps. EVENT_CONTENT is designed to accommodate the different kinds of jobs, i.e. e-mail, fax, print and file out.

E.g.:

-------------------- Step 3 -------------------------------------------
declare @aKey uniqueidentifier; set @aKey = newid();
insert EVENT_CONTENT (gKey, jKey, aKey, Src_Type, Path, [Format])
values (@gKey, @jKey, @aKey, 2, 'SALES/Weekly Sales Report', 'PDF' )

By default the report will attach itself as a file to your e-mail. To render a report in-line with HTML body, pass 0 (zero) to an optional IsAttachment column of EVENT_CONTENT table. Should the report require input parameters to control its content, add these into CONTENT_PARAMETER.

E.g.:

insert CONTENT_PARAMETER (aKey, [Name], [Value])
values (@aKey, 'Week', '12')

Release task | Step 4

The last step is to release our task for processing. This is done simply by updating the flag in EVENT_MASTER. When the record was inserted in step 1, the Status column defaulted to -1 (negative one). This indicated to Boomerang services that our event is a work in progress and hence should be ignored for the time being. It is now time to set Status value to 0 (zero).

E.g.:

-------------------- Step 4 -------------------------------------------
update EVENT_MASTER set Status=0 where gKey=@gKey

Entire Process | Step 1-4

The whole transaction put together would look something like this:

---- Declare keys -----------------------------------------------------
declare @gKey uniqueidentifier; set @gKey = newid();
declare @jKey uniqueidentifier; set @jKey = newid();
declare @aKey uniqueidentifier; set @aKey = newid();
 
---- New task ---------------------------------------------------------
Insert EVENT_MASTER (gKey, Created_By, Str1)
values (@gKey, 'domain\username', 'Weekly Sales Report');
 
---- Create e-mail job ------------------------------------------------
insert OUT_EMAIL (gKey, jKey, [ReplyTo], [From], Subject, Body)
values(@gKey, @jKey, 'Boomerang_account@servername.domain.com',
'"e-mail display name" <Boomerang_account@domain.com>',
'Weekly Sales Report', 'Message body test test test');
 
---- Add recipients to e-mail -----------------------------------------
insert OUT_EMAIL_RECIPIENT (jKey, Email)
values (@jKey, 'e-mail_address@domain.com');
 
---- Add report attachment as a PDF to e-mail -------------------------
insert EVENT_CONTENT (gKey, jKey, aKey, Src_Type, Path, [Format])
values (@gKey, @jKey, @aKey, 2, 'SALES/Weekly Sales Report', 'PDF');
 
---- Add parameters to report -----------------------------------------
 
insert CONTENT_PARAMETER (aKey, [Name], [Value])
values (@aKey, 'Week', '12');
 
---- Release task to be processed -------------------------------------
 
update EVENT_MASTER set Status=0 where gKey=@gKey;

Stored Procedures

Although not required by Boomerang, stored procedures are known as a convenient way to encapsulate business logic. They may reside in Boomerang database or other databases of choice. They can either be invoked by database triggers, or run on SQL Agent schedule, or called directly from your application. Please refer to the MS SQL Server documentation, or articles on this site on how to manage stored procedures.

Event Scheduling

Boomerang jobs may be set to delay their processing in time or to retry upon an unsuccessful attempt. This behavior defaults to the service settings, however it may be individually tuned for each job via EVENT_STATUS table. Alternatively you may use any available scheduling tool, such as MS SQL Server Agent. For more information on the MS SQL Agent please refer to the MS SQL Server documentation.

Configuration

Boomerang services ship with Microsoft Management Console snap-in. You can use snap-in to configure important service parameters, as well as Boomerang database. You may also manage Boomerang printers and attached fax servers. Boomerang MMC snap-in is provided for your convenience, although is not required to configure Boomerang services.

Boomerang configuration component is implemented as a DCOM Windows service. You can perform virtually any Boomerang configuration task in XML format by means of a scripting language which supports Automation. Many Boomerang Service parameters can also be configured directly by manipulating SYSTEM_VARS table, which in some cases may require restart of corresponding Boomerang services.

Monitoring Events

You can monitor progress of your tasks by checking either with EVENT_STATUS, which holds the last job state, or by looking into the EVENT_LOG table. There are 4 key fields which help you identify the state of your task.

Contrary to system errors (Type=2), jobs resulted in logical error (Type=1) will not be retried no matter what and any arbitrary settings in EVENT_STATUS will be ignored.

E-mail In | E-Mail to Database

Boomerang Notification Framework has an ability to receive any e-mail into a SQL database. The message will be parsed into multiple tables i.e. message head, recipients, attachments, body etc. In addition to comprehensive parsing, Boomerang’s e-mail engine uniquely tags outgoing messages so that any response (replies) can be recognized and matched. This has proven to be valuable in call centers and help desk applications built with the Boomerang notification framework for automatic tracking of case history. To configure Boomerang to receive e-mails please refer to this instruction.

Twitter In | Twitter to Database

The Twitter In service will capture status updates in real time. These messages will be parsed and stored in database tables. Two methods to capture updates are supported, filter and track. By filtering one or more key words will be used to define the scope. By tracking one or more Twitter user id’s will be referenced. The two methods may be combined. After each Twitter status update have been received post processing may be performed with the help of event handlers. To configrue Boomerang to receive twitter messages please refere to this instruction.

Learn More

• Getting Started Videos
• Application/Business Scenarios
• Installation and Configuration
• Administration
• Code Samples
• Database Overview
• Database Tables – Detailed Functional Documentation
• Helpers and Event Handlers – Detailed Function Documentation