Intercepting and Logging Email

1.  Abstract

To view an abstract of this document, click here.

2.  Introduction

The majority of SMTP (internet) email sent from the MIT R/3 systems is sent via the custom function module Z_SENDMAIL2. This function has been modified from its original state to enable programmers to instruct Z_SENDMAIL2 to intercept and/or log outgoing email that it processes.

Two custom tables, ZEHCAT and ZEMCTRL are used to control both interception and logging of email, and the log is written to a third custom table, ZEMLOG.

Interception of email is useful for debugging, testing, validating, and for providing training. The original motivation for adding this feature to Z_SENDMAIL2 was to provide a method of preventing email from being sent from non-production systems. When a new R/3 system is set up or refreshed, two entries should be established in custom table ZEHCAT to initially discard all email sent via Z_SENDMAIL2. Later, changes can be made as needed to support specific tests.

Logging of email, while useful for debugging purposes, particularly for intermittent problems or problems that occur in the R/3 production system, is intended to be used solely for short-term debugging purposes and should only be enabled when attempting to track down a problem. Logging is not intended, nor should it be used, as an audit trail of messages sent.

3.  How To setup ZSENDMAIL2 for Interception and Logging

WorksEach call to Z_SENDMAIL2 is associated with an email handling category taken either from parameter P_HNCAT or, if this parameter is not included in the function call, from table ZEMCTRL (see below for details on this distinction). The handling category is referenced in control table ZEHCAT, which contains the following instructions for processing the Z_SENDMAIL2 call based on the assigned handling category:

1. Whether to log the call to Z_SENDMAIL2.
2. Whether to intercept the email message, and if so, whether to:
   1. Discard the message.
   2. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by ZEHCAT).
   3. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by ZEHCAT).
   4. Write the message to an SAP printer spool file.
      (The printer name and spool settings are provided by ZEHCAT).

Email handling categories are assigned based on the type of email and the class of recipient to receive the email. The table of current handling category assignments can be found here. Requests for the assignment of an additional handling category should be directed to SAIS SAP Technical Service.There are currently two ways to specify the handling category associated with a call to Z_SENDMAIL2:

1. Explicitly pass an email handling category as parameter P_HNCAT.

Every new call to Z_SENDMAIL2 should pass an explicit email handling category as parameter P_HNCAT. Because many programs that call Z_SENDMAIL2 pre-date the intercepting and logging modifications, the P_HNCAT parameter is currently optional so that such programs do not require modification simply to add a handling category to the function call. It is intended, however, that every existing call to Z_SENDMAIL2 will eventually be modified to pass an explicit email handling category.

The table of current email handling category assignments can be found here.

The most direct way to associate a handling category with an existing call to Z_SENDMAIL2 is to modify the calling program to explicitly pass an email handling category as parameter P_HNCAT, and then transport the modified program to the R/3 test and other environments. 

2. Create an entry in table ZEMCTRL with the calling program name and the desired email handling category.

If a program that calls Z_SENDMAIL2 pre-dates the intercepting and logging modifications, such programs do not require modification simply to add a handling category to the function call. Although it is intended that every existing call to Z_SENDMAIL2 will eventually be modified to pass an explicit email handling category, programmers have the option of using table ZEMCTRL to map such programs to the appropriate handling category.

To map a calling program to a handling category, an entry is made in table ZEMCTRL with the calling program name as it appears in SY-CPROG and the desired email handling category. This method allows only a single handling category per program, and so is not suitable for programs that require more than one handling category. Also, this method does not require a transport to R/3 environments other than the environment in use.

The table of current email handling category assignments can be found here.

When a chain of programs is called, care should be taken in determining the value for field PROG, the calling program name as it appears in SY-CPROG. It is the first program within a chain of calls that is the calling program.

4.  Email Handling Categories

Each email handling category is a unique, two-letter assignment designated for use by particular ABAP programs for their exclusive use. Handling categories are assigned based on the type of email and the class of recipient to receive the email, and so a program not explicitly assigned to a particular handling category may not use that category.

The handling category (either passed as parameter P_HNCAT or retrieved from table ZEMCTRL) is referenced in table ZEHCAT, and the following instructions for processing the Z_SENDMAIL2 call are retrieved:

1. Whether to log the call to Z_SENDMAIL2.
2. Whether to intercept the email message, and if so, whether to:
   1. Discard the message.
   2. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by ZEHCAT).
   3. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by ZEHCAT).
   4. Write the message to an SAP printer spool file.
      (The printer name and spool settings are provided by ZEHCAT).

The table of current email handling category assignments can be found here.

If there are no existing handling category assignments for a program or if the existing assignments are not suitable, a request may be sent to the SAIS SAP Technical Service for the assignment of a new handling category.

New E-Mail Handling Categories may be requested from the SAIS SAP Technical Service team by suppling some information about how the new E-Mail Handling Categories will be used. For each E-Mail Handling Category requested, you need to provide the answers to four questions. The first two questions are usually answered by a business analyst and the last two questions are usually answered by a programmer. The four questions are:

1. To whom will the E-Mail be addressed? (This is usually answered with the person's role, not their name. Some example answers are "Card holders", "SAP users entering work orders", "Training & Events administrators", "Requisition approver", "HR Service Center", "Employee timesheet user", "Payroll distribution support", and "User who created the journal voucher")
2. The subject of the E-Mail? (Some example answers are "Staff out of balance report", "Problem with Lincoln HR feed to campus", "Purchase order is approved", "Duplicate MIT-IDs", "Leave balance status", and "Mass. Health Insurance report".)
3. What is the name of the ABAP source object containing the call to Z_SENDMAIL2?
4. What is the value of SY-CPROG when Z_SENDMAIL2 gets control?

   Special Handling Categories

Two particular email handling categories are assigned to address the special circumstance where there is no correlation between a handling category and an entry in table ZEHCAT. This may occur either because no handling category is specified, or because no entry exists in table ZEHCAT for a specified handling category.

1. <space><space>

Handling category <space><space> is imposed upon all email sent via Z_SENDMAIL2 for which no handling category is specified for the calling program (neither explicitly as parameter P_HNCAT nor mapped via an entry in table ZEMCTRL).

2. ++

Handling category ++ is imposed upon all email sent via Z_SENDMAIL2 for which a handling category is specified (either explicitly as parameter P_HNCAT or mapped via an entry in table ZEMCTRL), but no corresponding entry is found in table ZEHCAT.

How the imposed handling category is then processed depends on the contents of table ZEHCAT. If there are no entries in table ZEHCAT for the current R/3 system, all email sent via Z_SENDMAIL2 will be delivered normally, that is, will neither be intercepted nor logged. Table ZEHCAT in the production system, for instance, should typically contain no entries to allow for normal email delivery. If table ZEHCAT contains only the entries shown below for the <space><space> and ++ handling categories, all email sent via Z_SENDMAIL2 will be intercepted and discarded. Upon creating or refreshing a non-production R/3 system, these entries should be established in table ZEHCAT so that all email is discarded. Changes can later be made to support specific testing.

5.  The Tables

Programmers may view or modify the contents of the ZEMCTRL and ZEHCAT tables via utility program ZBRSMAIL. This program presents the following modification options for each table:

1. Delete all rows of the table.
2. Replace all table contents with the contents of a file.
3. Append a file to the table.
4. Write all table contents to a file.
5. Do nothing. In addition to the above options, ZBRSMAIL presents the following additional modification option for table ZEHCAT:
6. Modify all rows where email handling category, HNCAT, matches a select-option.

The modification option selected is applied based on the following action options:

1. Report the contents of the table before the modification is made.
2. Report the contents of the table as they will appear after the modification is made.
3. Make the modification to the table.

View the ZBRSMAIL selection screen for the ZEMCTRL or the ZEHCAT tables.

A separate utility program is currently under development that will enable programmers to selectively display or delete entries in the ZEMLOG table. Until that utility is available, transaction SE16 may be used to view email log entries in table ZEMLOG.

Table ZEMCTRL

For a program that does not pass an explicit P_HNCAT parameter in its call to Z_SENDMAIL2, custom table ZEMCTRL is used to map the calling program to its assigned email handling category. (If the P_HNCAT parameter is passed, ZEMCTRL is not referenced.) Eventually, all calls to Z_SENDMAIL2 will pass the P_HNCAT parameter and, at that time, table ZEMCTRL will no longer be needed.

To map a calling program to a handling category, an entry is made in table ZEMCTRL with the calling program name as it appears in SY-CPROG and the desired email handling category. Table ZEMCTRL allows only a single handling category per program, and so is not suitable for programs that require more than one email handling category.

When a chain of programs is called, care should be taken in determining the value for field PROG, the calling program name as it appears in SY-CPROG. It is the first program within a chain of calls that is the calling program.

Table ZEMCTRL contains the following fields:

Table ZEHCAT

For a program that passes an explicit P_HNCAT parameter in its call to Z_SENDMAIL2, custom table ZEHCAT is referenced to determine how the call should be processed. This determination is made by reading the control field settings that correspond to the email handling category specified in the P_HNCAT parameter.

The ZEHCAT control fields and what they specify are as follows:

1. LOG  Whether to log the call to Z_SENDMAIL2.
2. CMODE  Whether to intercept the email message.
   ACTION## Discard the message.
   1. Redirect the message to alternate "To" and "Cc" addresses.
      (The alternate addresses are provided by MAILTO and CCTO, respectively).
   2. Write the message to a UNIX file.
      (The UNIX path suffixed after "/usr/bridges/<system>/saptmp/" is supplied by MAILTO).
   3. Write the message to an SAP printer spool file.
      (The printer name is provided by PDEST, and the spool settings by PRIMM, PRREL, and PRNEW).

Table ZEHCAT contains the following fields:

Table ZEMLOG

Email logging uses the same email handling categories as interception and, while logging is controlled by table ZEHCAT, the email data to be logged is written to custom table ZEMLOG.

A utility program is currently under development that will enable programmers to selectively display or delete entries in the ZEMLOG table. Until that utility is available, transaction SE16 may be used to view email logs.

Please note that logging email is resource intensive and should only be enabled for diagnostic purposes. In order to manage the volume of data contained in this table, ZEMLOG is subject to periodic deletion of entries.

Table ZEMLOG contains the following fields:

 | E-MAIL HANDLING CATEGORIES | DEVELOPMENT RESOURCES |

6. How To Send HTML Messages Using ZSENDMAIL2

To send HTML message, add the following header texts into the "header" table in ZSENDMAIL2:

      MIME-Version: 1.0
      Content-Type: text/html; charset=us-ascii

In the message body, you can then enter HTML tags.