In the IUIE, what are PDQ mailing functions?

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.

Back to top

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.

Back to top

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).

Back to top

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.

Back to top

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).

Back to top

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.

Back to top

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.

Back to top

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

Back to top

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

Back to top

This is document anwp in the Knowledge Base.
Last modified on 2011-06-01 00:00:00.

  • Fill out this form to submit your issue to the UITS Support Center.
  • Please note that you must be affiliated with Indiana University to receive support.
  • All fields are required.

Please provide your IU email address. If you currently have a problem receiving email at your IU account, enter an alternate email address.

  • Fill out this form to submit your comment to the IU Knowledge Base.
  • If you are affiliated with Indiana University and need help with a computing problem, please use the I need help with a computing problem section above, or contact your campus Support Center.

Please provide your IU email address. If you currently have a problem receiving email at your IU account, enter an alternate email address.