Target Group Definition - Upload Recipients

This Target Group Definition wizard lets you define a target group of the "Upload Recipients" type that can then be used in the Define Recipients wizard.

The wizard for a target group of the "Upload Recipients" type has multiple pages:
General, Source, Source Details, Recipients Details, Duplicate Elimination, and Summary.

The top row of the wizard displays links to each of these pages. The page that is currently open is marked with a highlighted background color. Depending on the choices made on some of the wizard pages, other pages may become disabled or may be shown in different versions. If a wizard page is disabled, then it means that this page is not necessary with the current choices and can safely be ignored.

Source Page: Upload File or Supply Path to Server File

The following options are available:

• Upload recipients now:

  Use this option if the recipients file exists on your local computer and if you want to upload the recipients while defining this target group. The recipients are then exactly those recipients that are in the file at the moment when you upload it. Using this target group for a mail job always results in the same recipients receiving the email from the job. To select a file for uploading click the file select link at the bottom. Then on the next page, select the file from your local computer that you want to upload. If you select a text file (CSV file), you also need to select the file's character encoding from the drop-down menu. If you have already uploaded a file, then the file name is displayed on the Source page, as well as the date and time when it was uploaded.

• Load recipients just before sending, from a server file: This option is only available if your account has the necessary rights enabled to access server files at all.

  Use this option if the file exists on the LISTSERV Maestro server. The server reads the recipients from this file just-in-time before the mail job that uses the target group is being delivered. The recipients are exactly those recipients that are in the file at the moment when the mail job is being delivered. Therefore, it is possible to change the content of the file between the time when it is selected here in the wizard and the actual delivery time of the mail job. If the file changes between two mailings, then the resulting recipients are different. This option is especially useful if the file is created automatically by an external process, such as by extracting it from a different source.

  To select a server file, click the file select link at the bottom. Then on the next page, enter the full path name of the server file in the text box. Be aware that this path is interpreted by the Maestro server, and that your account must have the necessary rights enabled in order to access the file. (Check with the system administrator if you are unsure or receive an "Access denied" error.) If you specify a text file (CSV file), you also need to select the file's character encoding from the drop-down menu. If you already specified a server file, then the file name and path is displayed on the Source page.

Depending on the situation, either the Select a recipients file or the Select a different file link is available. Click it to select the recipients file, either to upload it, or for just-in-time loading, depending on the choice you made above.

If the selected file is an Excel or OpenOffice spreadsheet file (xls, xlsx or ods), and this spreadsheet file contains several non-empty datasheets, then after specifying the file, you also need to select the datasheet that contains the recipients. Only the recipients on this selected datasheet is used as recipients of the mail job. Any other recipients on other datasheets (in the same spreadsheet file) are ignored. The name of the selected datasheet is also displayed on the Source page.

Comma Separated Format Recipients Files

The term "comma-separated values" (or "tab-separated values" or "CSV") is often used as a catch-all term for all kinds of text-based data formats where the data is formatted in a line-by-line fashion. Each line contains one data record, and a number of columns per line, where the different columns are separated by comma, a tab, or some other separator character.

LISTSERV Maestro can correctly interpret comma separated text files in various formats as long as the following rules are applied:

• Any character may be used as the separator character, although comma, tab, or semicolon is conventional.
   
• The same separator character must be used in all lines for the entire file.
   
• All lines in the file must have the same number of columns, which means the same number of separator characters.
   
• Empty columns may be created in order that the same number of separator characters is present in every line of the file.
   
• Having two separator characters in direct succession, without any characters in between, creates an empty column.
   
• If a line begins with the separator character, Maestro assumes the line begins with an empty column.
   
• If a line ends with the separator character, Maestro assumes the line ends with an empty column.
   
• If the character that is used as the separator character also appears as part of the value of one or several of the column fields, then it is necessary to enclose the fields in quotation marks or another quote character.

The last rule listed above introduces the concept of "quoted values". As described, it is necessary to quote a value if the value contains the separator (because otherwise the separator would be interpreted as the start of another value). For Maestro to correctly know how to deal with quoted values, it is necessary to tell Maestro if the comma separated file contains any quoted values or not.

If a file does not contain any quoted values, then the additional rules explained below do not apply, i.e. even if one of the usual quote characters (for example quotation marks or the apostrophe) would appear anywhere in the file, they would be interpreted by Maestro as just another normal character.
However, such a file can also not have any value which contains the separator. If at least one value contains the separator, then this value must be quoted, and by this the file becomes a file with quoted values again.

If a file does contain quoted values (at least one of them), then it must follow these additional rules:

• Any character, except for the separator character, can be used as the quote character (quotation marks or apostrophe are conventional). This character must be used both as the opening and closing quote and must be used for all quoted fields in the file.
   
• A field must be quoted if it fulfills any of these two conditions:
   
  • If the field contains the separator character in the value, then the field must be quoted.
     
  • If the field contains the quote character in the value and this quote character is also the first character of the value, then the field must be quoted. (This however also means that if the field contains the quote character but not as the first character, then it is not necessary to quote the field.)
  
  
• It is not necessary that all fields are quoted. Only fields that fall into one of the two cases described above have to be quoted. However, it is legal to also quote fields which do not fulfill these conditions.
  Usually one of two styles is used: One style quotes all fields (both the ones that have to be quoted and the ones which do not), while the other style quotes only exactly those fields which have to be quoted (all others are left unquoted). Maestro is able to understand both of these styles (and also mixes of the two styles, as long as the rules described here are followed).
   
• If a field is a "quoted field" and the quote character also appears as part of the value of the field, then this character must be escaped. Escape the quote character by using it twice, in direct succession. The double appearance of the quote character will be interpreted as a single appearance that is part of the field value.
   
• If a field is an "unquoted field" and the quote character also appears as part of the value of the field, then this character must not be escaped. Quote-escaping is only necessary in quoted fields!
   
• A "quoted field" is parsed from the file as follows: The field starts with the opening quote and ends with the next appearance of a not-escaped quote character after the opening quote. (The end of the field must then be followed by a separator character or by the end of the line - trailing white space after the last field of the line is allowed.)
  The value of the field is the text between the two quotes, excluding the quotes. Any escaped quotes in the value will be unescaped.
   
• An "unquoted field" is parsed from the file as follows: The field starts with the first character and ends with the next appearance of the separator character (or the end of the line). The value of the field is the text with this start and end, excluding the separator character.

Here are some examples:

Simple values, separated by comma, not quoted:

John,Doe,Chicago,USA
Lucy,Summers,London,GB
Karl,Hauser,Frankfurt,D

This will be parsed as follows:

Simple values, separated by comma, not quoted, with empty fields:

John,,Chicago,USA
,Summers,London,GB
Karl,Hauser,Frankfurt,

This will be parsed as follows:

Values of which some contain a comma, separated by comma, quoted with <">:

Using the style that quotes all values:

"John","Doe","Chicago, Illinois","USA"
"Lucy","Summers","London, England","GB"
"Karl","Hauser","Frankfurt","D"

Or using the style that quotes only the values that have to be quoted:

John,Doe,"Chicago, Illinois",USA
Lucy,Summers,"London, England",GB
Karl,Hauser,Frankfurt,D

(The only values that have to be quoted in this example are the two values containing the separator character <,>.)

Both will be parsed as follows:

Values of which some contain a comma, separated by comma, quoted with <">, with empty fields:

Using the style that quotes all values:

"John","","Chicago, Illinois","USA"
"","Summers","London, England","GB"
"Karl","Hauser","Frankfurt",""

Or using the style that quotes only the values that have to be quoted:

John,,"Chicago, Illinois",USA
,Summers,"London, England",GB
Karl,Hauser,Frankfurt,

(The only values that have to be quoted in this example are the two values containing the separator character <,>.)

Both will be parsed as follows:

Values of which some contain a comma and some the quote character, separated by comma, quoted with <">:

Using the style that quotes all values:

"John","Doe","Chicago ""The Windy City"", Illinois","USA"
"""Little"" Lucy","Summers","London, England","GB"
"Karl ""Big Boy""","Hauser","Frankfurt","D"

Or using the style that quotes only the values that have to be quoted:

John,Doe,"Chicago ""The Windy City"", Illinois",USA
"""Little"" Lucy",Summers,"London, England",GB
Karl "Big Boy",Hauser,Frankfurt,D

(The values that have to be quoted in this example are the two values containing the separator character <,> and also the first value of the second row, which starts with the quote character <">. In comparison, the first value of the third row does contain the quote character too, but not as the first character. Therefore this field does not have to be quoted and the quote character is therefore also not escaped.)

Both will be parsed as follows:

Changing the Target Group's Type

The bottom of the screen contains a link to change the type of the target group that you currently are working on.

Click the link to open a dialog. In this dialog, you can choose the target group type that you want to change to.

Note: Your account may not have all types described below available, depending on how the system administrator has configured your account. You can choose:

• Send to Recipients in the Subscriber Warehouse: This target group type is based on a subscriber list in the subscriber warehouse.

  After clicking the [OK] button, the screen displays all of the list groups and their respective subscriber lists. Once a list is selected, the wizard will allow for conditions and parameters to be set in order to segment the list subscribers.
  Help pages for wizard of this type

• Send to Recipients in the Subscriber Warehouse: This target group type is based on a list group.

  After clicking the [OK] button, the screen displays all available list groups. Once a list group is selected, the wizard allows for conditions and parameters to be set in order to segment the list subscribers in the group.
  Help pages for wizard of this type

• Select Recipients from a Database or LDAP Directory:

  If you choose this target group type, in the target group wizard you will need to select a database or LDAP connection, a SQL statement (or LDAP search), merge column headers, and duplicate elimination, just as you would when using the underlying recipients type in the recipients wizard. Optionally, the SQL statement and LDAP search filters can be parameterized, meaning that you can define parameters for the SQL (or LDAP search) that are filled out by the user in the recipient wizard, when this target group is used for a recipient definition.
  Help pages for wizard of this type

• Send to a LISTSERV List:

  After clicking the [OK] button, the screen displays all available LISTSERV lists on the server assigned to the account group. Select a list from the drop-down menu, and then select the type of LISTSERV message to send, standard or mail merge.
  Help pages for wizard of this type

• Upload Recipients:

  The data administrator can set up a server file to be uploaded just before the job is delivered.
  Help pages for wizard of this type

• Let LISTSERV Select Recipients From a Database or LDAP Directory:

  After clicking the [OK] button, you will need to fill out a database name, a SQL statement, and merge column headers, just as you would when using the underlying recipients type in the recipients wizard. Optionally, the SQL statement may be parameterized, meaning that you may define parameters for the SQL that are filled out by the user in the recipient wizard, when this target group is used for a recipient definition.
  Help pages for wizard of this type

Note: The type of target group that you currently have selected in the target group wizard is omitted from the list of option shown in the dialog described above.