About PDQ mailing functions in the IUIE
- Overview
- Security
- PDQ coding
- IUIE mailing request file sections
- Section summary
- Sample PDQ mailing request output
Overview
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.
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 output type radio button appears on the parameter entry screen.
If you select the
output type, MAIL is supplied to the 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 (for example, a web browser, Completed Reports
, a printer, 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 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
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 (that is, 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 (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:
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:
|
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:
|
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 (that is, 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:
|
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 the Knowledge Base.
Last modified on 2023-07-18 14:45:07.