About PDQ mailing functions in the IUIE

• Overview
• Security
• PDQ coding
• IUIE mailing request file sections
• Section summary
  • Mandatory sections
  • Optional sections
  • Unused sections
• Sample PDQ mailing request output
  • Example file
  • Resulting mail message

Overview

If the "Mail" output type is enabled for a PDQ, or 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 Perl 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 (for example, a web browser, Completed Reports, or Mailing).

By directing output to a destination other than Mailing, you can verify or 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

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

• 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 "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 (for example, "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:

Dear Student $student_id,

Your $course_number in $building room $room has been changed to meet
at $meeting_time.

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

Optional sections

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

Unused sections

Never specify the following sections:

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