Overview of Content Formatting

The "Component Configuration and the Phases of Processing" section (p. 61) in Chapter 3, "The Simplest Notification Application: Stock Quotes," describes the stages in the SQL-NS processing pipeline. The final stage is distribution, which encompasses the formatting and delivery of notification messages. Within the distribution phase, content formatters do the work of formatting the raw notification data.

When defining a notification class, you specify which content formatter should be used to format notifications of that class. You can choose to use the XsltFormatter, a built-in SQL-NS component that you customize through configuration settings, or you can build your own custom content formatter. At runtime (during the distribution phase), the SQL-NS engine loads the content formatter you specify and passes it raw notification data. The formatter processes this data and returns formatted strings that then become the content of the final notification messages.

From the perspective of the SQL-NS engine, a content formatter is like a black box: Raw data goes in one end, and a formatted message comes out the other. What happens inside the box is not important to the engine. A content formatter can employ any formatting strategy it needs to get the job done.

Content Formatters and Distributors

As you may recall from Chapter 3, distribution is handled by the part of the SQL-NS engine called the distributor. The distributor constantly looks for new batches of notification data produced by the generator and processes them when they become available.

The distributor hosts content formatters and passes the raw notification data to them. The distributor takes the formatted messages output by the content formatters and invokes delivery protocol components to deliver them. This is shown in Figure 9.1. The distributor runs in the SQL-NS engine, and therefore all content formatters run in the engine, too.

Figure 9.1. The distributor and the components within it.

Using Multiple Distributors

Even though an application can have more than one distributor, we still usually refer to "the distributor" in singular form. All distributors in an application are identical and perform the same functions. Think of each distributor as a clone of every other. Additional distributors serve as extra workers that share a common workload. The term "the distributor" refers to all the distributors in the application collectively.

You configure distributors in the <Distributors> element of your application's ADF. Having multiple distributors improves the performance of your application when each distributor runs on a separate machine. This gives each distributor dedicated hardware resources it can employ to format and deliver notifications. Because each distributor attempts to fully exploit the available resources of its host machine, it does not make sense to put multiple distributors on a single machine. The SQL-NS compiler prevents you from configuring more than one distributor on a single machine by raising a compile error if it finds two or more <Distributor> elements in the ADF with the same value for the <SystemName> subelement.

Only the Enterprise Edition of SQL-NS supports hosting components on multiple machines. If you are using Standard Edition, all components of the SQL-NS engine must run on a single machine, so you can configure only a single distributor in your ADF.

Content Formatter Input and Output

When you define a notification class, you specify a schema for the notification data. Using this schema, the SQL-NS compiler creates a notifications table and a notifications view in the application database. At runtime, your match rules generate notifications by inserting into the notifications view, providing values for the notification class fields. A trigger on the notifications view writes these values into the notifications table.

The data in the notifications table, along with some information about subscribers and target devices, form the input to the content formatter. When it processes a batch of notifications, the distributor reads each row from the notifications table and passes it to the content formatter.

You can augment the schema of your notification class by defining a set of computed fields in the ADF. Computed fields are similar to notification fields, but they are never materialized in the notifications table. Rather, computed field values are obtained (or "computed") by evaluating expressions when the distributor reads the notification data. The values of the computed fields are passed to the content formatter as input, along with the notification fields, subscriber data, and delivery device information. The examples you've seen in previous chapters have not used computed fields, but you will see them used in this chapter. The section "Adding Computed Fields" (p. 318) shows the declaration of computed fields.

The output from an invocation of a content formatter is a single string. This string is referred to as the notification body and will be passed to a delivery protocol for delivery to the subscriber. The notification body is the message that the subscriber will ultimately see. In forming the notification body, the content formatter can use all, or just portion of, the input data, as well as external data that it obtains on its own.

Formatting for Different Languages and Device Types

Different subscribers may want to receive their notifications in different languages. SQL-NS has support for content formatters that provide language-specific formatting. With each notification, SQL-NS tracks the target subscriber locale and passes this value to the content formatter when the notification needs to be formatted. The subscriber locale is a code that indicates a language and a specific country or region. For example, "en-US" is the subscriber locale code that refers to U.S. English, "en-ZA" refers to South African English, "fr-FR" refers to French as used in France, and "fr-CA" refers to French as used in Canada. The content formatter can use the subscriber locale code to choose an appropriate type of formatting for the given language and country or region.

Note

Refer to the "Subscriber Locales" topic in the SQL-NS Books Online for a complete list of all the supported subscriber locale codes. You can also obtain the list of supported locale codes programmatically using the SubscriberLocaleEnumeration class in the SQL-NS API, also documented in the SQL-NS Books Online.

In addition to the subscriber locale, it's also important to consider the target device type when formatting a notification. For example, a cell phone can receive notifications but is capable of displaying only a few lines of text. A desktop email client, on the other hand, can display longer notifications and render HTML. Because of the differences in display capabilities, it's a good idea to provide device-specific formatting in your content formatter. SQL-NS tracks the target device type for each notification and passes this to the content formatter in addition to the subscriber locale and the notification data.

Given the subscriber locale and the device type, the content formatter can make appropriate decisions about how to format the data. If you are building a custom content formatter, as described in the "Building a Custom Content Formatter" section (p. 334), you can use the subscriber locale and device type values to decide what formatting operations should be performed.

You can also do locale and device type-specific formatting if you're using the built-in XsltFormatter. You can write a different XSL transform for each language and device type your application supports, and the XsltFormatter will load the appropriate transform based on the locale and device type values it receives. More details on how to use the XsltFormatter this way are given in the "Using Locale and Device-Specific Transforms" section (p. 329).

For SQL-NS to pass the appropriate locale and device type information to the content formatter, you must ensure that your match logic provides the appropriate values for the DeviceName and SubscriberLocale columns when inserting into the notifications view. Recall that the match rule for the NewSongByArtist subscriptions in the music store application currently looks like this:

 INSERT INTO [SongAlerts].[NewSong] SELECT subscriptions.SubscriberId,        N'DefaultDevice',        N'en-US',        songs.SongTitle,        songs.ArtistName,        songs.AlbumTitle,        songs.GenreName FROM   [SongAlerts].[SongAdded] events JOIN   [Catalog].[SongDetails] songs     ON events.SongId = songs.SongId JOIN   [SongAlerts].[NewSongByArtist] subscriptions     ON subscriptions.ArtistName = songs.ArtistName 

The second and third fields in the select list specify the device name and subscriber locale, respectively. These values are inserted into the DeviceName and SubscriberLocale columns in the notifications view. The device name refers to a subscriber device record in the NSSubscriberDevices table, in the instance schema (the combination of the SubscriberId and DeviceName values effectively forms a foreign key into the NSSubscriberDevices table). The subscriber locale argument specifies a locale code.

When the distributor reads the notification data in preparation for formatting, it obtains the device type for each notification from the corresponding subscriber device record (identified by the subscriber ID and device name). The distributor passes the device type value, along with the locale (and the rest of the notification data), to the content formatter.

In the match rule we just examined, and all the other examples you've seen so far, the device name and the locale values have been hard-coded. This works if the application supports only one device and locale, but real applications usually need a more flexible strategy.

When designing an application, you must decide how the correct device and locale values will be obtained in the match rules. One common strategy is to allow subscribers to specify the desired device type and locale for their subscriptions. To implement this, you define fields in the subscription class for the device name and locale. When a subscriber creates a subscription, she can specify exactly which device she wants to use, and in what language she wants to receive the notification messages, by supplying values for these subscription fields. These are then stored in the subscriptions table, along with all the other subscription fields. The match rule can then obtain the stored device name and locale values from the subscriptions view (which is already part of the join). We use this strategy in the examples shown in this chapter.

Tip

The SQL-NS application model allows you to easily implement a more dynamic approach to selecting a subscriber device. Let's say that you want to support delivering notifications to different devices at different times of the day. For example, during work hours, the subscriber wants to receive notifications on her work email address, but after hours, she wants to receive them on her cell phone.

To implement this, you can store in a separate device profile table the various device names and the times of day at which they should be used. Instead of obtaining the device names from the subscriptions view, in your match rule, you join with the device profile table (using the current time of day to select the appropriate device row) and pass the device name to the notify function.

Formatting Digest and Multicast Notifications

As you may recall from Chapter 5, "Designing and Prototyping an Application," SQL-NS supports aggregation of notifications into digest and multicast groups (see "Aggregation Options: Digest and Multicast," p. 147 in Chapter 5). Digesting combines several notifications going to the same subscriber into a single message. Multicast detects when the same notification data is going to multiple subscribers, formats the data once, and then sends a copy of the formatted data to each subscriber. Multicast delivery enhances performance because it avoids unnecessarily formatting the same notification data over and over.

Note

Multicast delivery is available only in SQL-NS Enterprise Edition.

To format a digest message, SQL-NS passes several sets of notification data to the content formatter at once. The formatter must be able to handle more than one set of notification data at a time and aggregate it all into a single formatted message. This is shown in Figure 9.2. In this chapter, we'll look at how the built-in XsltFormatter and custom content formatters implement support for digesting.

Figure 9.2. Formatting digest notifications.

When doing multicast delivery, the distributor passes a single row of notification data to the formatter and reuses the formatter's output to deliver additional notifications. This is illustrated in Figure 9.3. To the formatter, a call to format a multicast notification looks the same as a call to format a single notification. The only difference is in the distributor's behavior: It will not call the formatter again for additional notifications with the same data.

Figure 9.3. Formatting multicast notifications.

Using a Content Formatter in a SQL-NS Application

In the <NotificationClass> element in the ADF, you declare the content formatter in the <ContentFormatter> subelement. In the examples in earlier chapters, you saw the <ContentFormatter> element used to declare the XsltFormatter. Each notification class can have only one content formatter, but different notification classes in the same application can use different content formatters.

When declaring a content formatter, you specify the content formatter class, assembly, and runtime arguments. The class can either be the XsltFormatter or the name of a class that implements a custom content formatter, as described in the "Building a Custom Content Formatter" section (p. 334). The assembly needs to be specified only if you're using a custom content formatter, as shown in the section "Declaring a Custom Content Formatter in the ADF" (p. 344). The runtime arguments specified in the declaration are passed to the content formatter when it starts. Each formatter defines its own set of arguments: the XsltFormatter has a set of arguments that it requires, and if you build a custom formatter, you determine the arguments that it needs.

Content Formatter Security

Because content formatters run within the SQL-NS engine, they run in the security context of the Windows account under which the engine runs. This is typically the SQL-NS service account (when the engine runs as a Windows service). As described in Chapter 2, "Getting Set Up," the engine should be configured to run under a low-privileged account, with only the minimum required database permissions.

To perform distributor operations in the database (including content formatting), the engine account needs to be a member of the NSDistributor database role. Alternatively, the engine account can be a member of the NSRunService role, which is a member of NSDistributor.