In the IUIE, what are PDQ mailing functions?

Username:
Password:

Note: To take advantage of the IUIE mailing functionality, a PDQ developer must do the following:

Publish a PDQ that produces an IUIE mailing request file.
Specify the "Mail" output type for the PDQ.
Ensure the intended users are part of the IE_MAILING_R user group.

On this page:

General information

If the "Mail" output type is enabled for a PDQ, or if the user of the PDQ is a member of the Mailing user group (IE_MAILING_R), a Mail output type radio button appears on the parameter entry screen.

If you select the Mail output type, MAIL is supplied to the SQR, Perl, or sh query as the output type. The PDQ code must be written to recognize the output type requested and to generate appropriate output. If the PDQ can only generate a mailing request, then "Mail" should be the only output type, and the PDQ code can ignore the output type that is passed.

"Mail" output is formatted text, so you can direct it to any output destination (e.g., a web browser, Completed Reports, a printer, or Mailing).

By directing output to a destination other than Mailing, you can verify/validate the output produced from the specified PDQ parameter values before actually performing a mailing.

When you are satisfied that the specified PDQ parameters generate the appropriate set of records, you can send the resulting mailing request to the Mailing output destination to cause mail messages to be sent. A browser screen similar to the one for sending to Completed Reports will inform you that the request has been routed to the mailing queue.

When the mail queue processes a mailing request, the address(es) specified in the "NOTIFY" section will receive notice of completion through an email message which includes information on the number of mailings done, the type of mailing (create, mass, merge), and RO metadata sufficient to recognize which mailing request is being referenced. The same information in the notification email message is included in the message text of the IUIE job log.

Security

The Mailing user group is not a typical IUIE user group. Rather, it is a list of people with mailing privileges. It should not be assigned as an access group for a report object.

You must be a member of this group for the Mailing output destination to appear as an option on the PDQ parameter entry screen. If you are not in this mailing group, you can still run the PDQ and see the mailing request file that is generated, but you cannot send the request to the mailing queue to cause mail to be sent.

PDQ coding

Three mailing functions are available to the publisher of a PDQ:

Create mailing list: This function applies if the mailing request file has a "MAILINGLIST" section.
The IUIE sends the initial creation request to LISTSERV. All subsequent management of the list occurs through direct interaction with LISTSERV (i.e., through commands sent by email).
Merge mail: This function applies if the mailing request file has a "FIELDS" section.
Each email message of a merge is sent individually since no two merges are necessarily identical. The ADDR record supplies values for variables declared in the "FIELDS" section. Variables of the "FIELDS" section can be referenced in the "SUBJECT" and "BODY" sections by prefixing "$" to a FIELDS variable name.
Mass mail: As the default function, this will perform in the absence of a "MAILINGLIST" or "FIELDS" section.
All mails in a mass mail are identical, so you can group the recipients into the "BCC:" header (currently in batches of 100).

IUIE mailing request file sections

An IUIE mailing request file is a series of sections meeting these criteria:

Each section is a section header line, followed by the value lines to be associated with that section.
A section is terminated by detection of another section, or the end of the file.
The values supplied for a section must begin on the line following the section header, and not on the same line as the section header.
The section header itself shouldn't have leading or trailing blanks, because an equality test is being used on the whole line.
The order of the sections (e.g., "FROM", "TO", or "SUBJECT") is important; the ADDR record should come last.
Because the file is read line by line to retrieve section values, placing the ADDR before other sections would require the entire ADDR record to be read once for each section that follows it. Since the ADDR is typically longer than the other sections, that would be inefficient. However, any section order will work. If the ADDR is short, the order of sections is unimportant.

Section summary

The following is a summary of what sections may be supplied (mandatory, optional, and unused), and the types of values expected.

Mandatory sections

The following table shows all mandatory sections; all generated email messages must identify themselves, their content, and their recipients:

FROM	Without a "FROM" section, recipients of the email message will not know who sent it.
SUBJECT	The "SUBJECT" section can contain references to names specified in the "FIELDS" section, just as in the "BODY" section. This feature allows the "Subject:" line of generated messages to include values from the current ADDR record being processed.
BODY	In the "BODY" section, the value of a column in the current ADDR record can be referenced by prepending `$` to a name listed in the "FIELDS" section, for example: Dear Student $student_id, Your $course_number in $building room $room has been changed to meet at $meeting_time.
ADDR	The first column of an ADDR record must always be an email address column. This value is used to supply values for the "To:" header in the generated messages. Note the following: Delimit ADDR records with newlines. Delimit columns of ADDR records with tabs. Code tabs and newlines in ADDR column values as Perl escape sequences; see below for the most common ones. In the future, it may become possible to set arbitrary delimiters with "ROW_DELIMITER" and "COLUMN_DELIMITER" sections, but for now they are constant. There should be no column header generated for the ADDR. The ADDR should contain only valid data. ADDR columns can contain Perl escape sequences to aid in formatting output; see below for common sequences.

Consult Perl references for detailed Perl information; following are the most useful escape sequences:

Escape sequence	Effect
`\n`	Newline
`\t`	Tab
`\Odd`	Octal representation of an ASCII character (`d` stands for digit)
`\xdd`	Hexadecimal representation of an ASCII character
`\l`	Make the following character lowercase.
`\L ... \E`	Make all characters until `\E` lowercase.
`\u`	Make the following character uppercase.
`\U ... \E`	Make all characters until `\E` uppercase.
`\Q ... \E`	Take everything between `\Q` and `\E` literally (i.e., turn off interpretation of escape sequences).

Optional sections

The following table shows optional sections; these sections determine how the mailing request will be processed:

REPLYTO	This section is mandatory with "MAILINGLIST" because it informs LISTSERV of the list owner. It is optional for mass and merge mails, but if supplied, "REPLYTO" determines the addresses that will receive replies from recipients of the mailing.
FIELDS	If present, "FIELDS" specifies that a merge mail is to be done; it also specifies the order of fields in the ADDR section. The list in the "FIELDS" section can be compared to a column header for the records in the ADDR: Names in the "FIELDS" section are used as variable names, so they should not contain embedded blanks. For example, `student_email` would be a good substitute for `student email` . "FIELDS" names should begin with an alphabetic character. "FIELDS" names are case sensitive, so be consistent. It is best to use the technical names columns in the "FIELDS" section, but since they are stand-ins, they can be anything that is distinct.
NOTIFY	Notification email messages contain the number of messages sent to addresses listed in the ADDR. Notification email messages are not part of the count.

Unused sections

Never specify the following sections:

AUTH	This section is not currently used, so it is unneeded.
TO	This information always comes from column 1 of the ADDR, so you should never specify it.

Sample PDQ mailing request output

Below is an example output file that uses some of these sections, along with the output that is produced. Notable features include:

Forcing the first character of the "FIELD" reference in the "SUBJECT" section to lowercase
Showing three ADDR records, the last "FIELD" of which, TEST_FORMATTED_FIELD, contains escape sequences to do formatting
The first shows upper- and lowercase blocks, and all examples use tabs and newlines.

Note that "this is uppercase" is in lowercase in the ADDR record, and that "THIS IS LOWERCASE" is in uppercase in the ADDR record.

Example file

FROM jdoe@indiana.edu SUBJECT Test Merge \l$PRSN_PRM_1ST_LST_35_NM. REPLYTO jdoe@indiana.edu NOTIFY jdoe@indiana.edu BODY Network ID:\t $PRSN_USER_ID Name :\t $PRSN_PRM_1ST_LST_35_NM Department:\t $JOB_DEPT_DESC Position :\t $POS_DESC Address :\t $PRSN_CMP_LN1_ADDR \t $PRSN_CMP_LN2_ADDR \t $PRSN_CMP_LN3_ADDR

Resulting mail message

Record 1 -------- To: jdoe@indiana.edu From: jdoe@indiana.edu Subject: Test Merge darth Vader. Network ID: DVADER Name : Darth Vader Department: Vice President Information Tec Position: Software Analyst/Prog Address : 2709 E TENTH UITS BL Formatted Field: line1 line2 THIS IS UPPERCASE line3 this is lowercase Record 2 -------- To: jdoe@indiana.edu From: jdoe@indiana.edu Subject: Test Merge luke Skywalker. Network ID: SKYLUKE

This is document anwp in domain all.
Last modified on June 01, 2011.