List Management Programming Concepts

List Types

List Manager contains the functionality to manipulate two types of lists, Generic lists and Mailing lists. Each type may also have User and Mailable attributes. Lists are designated as static or dynamic depending on when the data is imported.

You use a Mailing list with Direct Mailer. It contains a list of recipients who have been designated to receive an e-mail ad or a list of recipients that should not receive the mailing. The default flags value indicates a Mailing list; the LISTFLAG_GENERIC flag must be set when the list is created or when the list is imported if the list you are creating is not a Generic list. A Mailing list implies a list with a specific set of column names and types. Direct Mailer uses only Mailing lists, although a Mailing list may be automatically extracted from a Generic list so long as it is a Mailable Generic list.

A Generic list may have any set of column names and types — it essentially maps to a SQL Server database table. When a list is imported into List Manager from the Analysis reporting feature or the Predictor segment viewer, it is imported as a Generic list. Generic lists may be converted to Mailing lists if they meet certain requirements. A Generic list may be imported from an SQL query but cannot be imported from a flat file.

A Mailable list is any list with an rcp_email column. When you import or create a Mailable list, you indicate that it is a Mailable list by setting the LISTFLAG_MAILABLE flag. A Generic list may or may not be Mailable; a Mailing list is always Mailable. After importing a Generic list, ListManager automatically attempts to detect a Mailable list, and sets the appropriate flag. The Mailable list flag exists for integration with Direct Mailer features, so that Direct Mailer can identify which lists to use for e-mail recipients and opt-out lists.

A User list is any list with an rcp_guid column. When you import or create a User list, you indicate that it is a User list by setting the LISTFLAG_USER flag. A Generic list may or may not be a User list; a Mailing list is always a User list. After importing a Generic list, List Manager automatically attempts to detect a User list, and sets the appropriate flag. The User list flag exists for integration with User Profile Management features. For example, it is possible to import a list from the Segment Viewer module in Commerce Server Business Desk and set a property in the user profile of each user in that list to indicate their membership in a particular segment. This information is then available for targeting by the Content Selection Framework for advertising and discounts.

Lists may be created as either static or dynamic. In a static list, records are imported at the time the list is created. A dynamic list imports records on demand when referenced by another operation.

Flag Values

The following table lists the possible flag parameter values used to determine the type of list created. Values may be combined using the logical OR operator to specify more than one flag.

Import/Export

List Manager can import lists from the following sources:

• An SQL query run against an Open Database Connectivity (ODBC) data source.

• An Analysis report run from Commerce Server Business Desk.

• A Predictor resource segment.

• A text file (comma-separated value (CSV) format).

List Manager can export lists to the following destinations:

• A SQL Server 2000 table in an external database.

• A text file (CSV format).

Text Files

If an absolute file path and name is not specified when importing or exporting a list, List Manager looks for the file relative to a root folder named "CommerceLists" on the local computer running the List Manager service. If the folder does not exist, an error is returned.

List Manager recognizes the following input text file format:

<Mail-to Address>,<User ID>,<Format>,<Locale>,<Source URL><cr><lf>

The only required field is Mail-to Address. The optional Format field should be one of the following: 1 - text, 2 - MIME, or 3 - MHTML. Any double quotation marks surrounding a field will be stripped. A trailing comma will produce an error.

List Manager exports text files in the same format as described above with all fields enclosed in double quotation marks.

Asynchronous Mode

List Manager allows time-consuming operations to run in an asynchronous manner. When run asynchronously, the operation returns immediately after the process has started. An application that starts an operation asynchronously has the following additional methods available:

• The WaitOnOperation method returns when the operation is finished, or a timeout has occurred.

• The GetOperationInfo method returns all details of the operation including its current status.

• The CancelOperation method signals the operation to quit. If the operation does not quit in two minutes, the operation is terminated.

Database Tables

List Manager stores information about lists and operations in the lm_master and lm_master_operations database tables, respectively. For information on the format of these tables, see ListManager.GetLists and ListManager.GetOperations.

All rights reserved.