Introduction
There seems to be a lot of requests in the forums for tips on how to send E-Mail from ABAP. Based upon these requests, I thought I would pull together some resources and samples on the subject. The setup and samples are quite different on different releases. This first weblog will cover SAP Basis releases 46D and lower. All samples came from a 46C system (Although the ABAP code is very much the same as the code we used to use back on our old 3.1H system). There will be another weblog later that covers this same topic for WebAS Version 610 and higher.
Configuration
Before we start with any ABAP coding, we first have to setup and configure a few things. Much of this configuration may have already been completed by your Basis group.
Internet Mail Gateway
The first thing we want to setup is probably the Internet Mail Gateway. Since the Basis layer at these releases doesn't have any native SMTP abilities we will need an executable at the OS level to perform the sending of the mail for us. These executables are commonly referred to as the Internet Mail Gateway. I suggest that anyone doing this setup start by reading OSS note 99965. This has a quite good, step-by-step implementation guide to setting up the Internet Mail Gateway. To complete this part of the setup we need to make sure that we have our mail gateway configuration file (default name mailgw.ini) setup and available to the executables. That means using one of the two default directories or the GWCONFIG environment variable. The configuration file can be created or modified using the program MLSOMADM. Finally we need to make sure that we have the program that does the mail sending itself: MLUNXSND. If you need to know where you can go to get the latest patch level of these executables, please read OSS note 101573.
RFC Connection
Next we need to configure a RFC destination so that we can exposed these executables to ABAP. The instructions in OSS note 99965 describe setting up this TCP/IP RFC destination as Direct Start or via Registration. The following is a screen shot of our RFC Destination. We use the Direct Start Option, calling a shell script as described in the OSS Note:
SAPConnect
Well we are finished with all the low level setup. Now we need to connect the lowest layer (the Internet Mail Gateway) to SAP's middle message layer: SAPConnect. SAPConnect sits between the application layer (such as SAP Office) and the lowest layer hiding all the technical details. All of the SAPConnect monitoring and configuration can be reached from one transaction called SCOT. First SCOT has several different views that can be used. One shows the Jobs that have been setup, the other shows setup by routings, etc. I prefer to start SCOT in System Status View. This shows a tree with the communication types, the nodes setup for each type and the number of messages in each status. The following is a screen shot of this view:
We want to create a new node in SAPConnect for our E-Mail. In 46C you have a quite nice Wizard that walks you through the process. However you can also control all settings directly in a dialog maintenance window. This is a screen shot of our Email Node.
You can see at this point we connect the processing for this node to our RFC destination setup before. You also can set the supported address types and their settings.
For the supported address type of Internet, we really have a very plain setup. We don't do any outbound filtering to different nodes. Therefore the address areas is set to the wildcard '*'. We support all formats except those listed in OSS note 99965 (ALI, SCR, OTF, OBJ and URL) and use the PDF device type to format outputs. If you are interested in PDF Device Type in 46C or lower have a look at OSS note 317851.
One special note on code pages. If you are a MDMP system or you use a double byte code page, I'm afraid you could be in a little bit of trouble. Have a look at OSS note 331418 for the details on the support (or lack there of) for these special code page situations. I can tell you that the 610 and higher mail interface does solve this problem.
Next we need to schedule a job that will transmit out E-mails. E-Mails will only go out when this job runs, so you probably want to schedule it quite frequently. In our production system we run this job every 5 minutes. The job setup can also be done from SCOT. Switch your view to JOBS. You can then hit CREATE to start the process of scheduling a new Send Job.
Running a Test
We are just about ready to run our first test. The only other requirement is that the sender of any E-mail, must have their return address setup in their user master. If you don't maintain this data, you will get a send error. If you want an SAP program to generate these addresses for you, have a look at OSS note 104263. Also in 46C you have the option to configure the system to generate the sender address on the fly. OSS note 320443 gives you the details of this solution. You can see from the following screen shot the field that must be maintained in the user master:
Let's try a test now. I like to start by testing using the SAP short message functionality. You will want to use menu System->Short Message. From here we will prepare a short test message. If you don't want to wait for your batch job to run to find out if your message went through, just jump back to transaction SCOT. From the System Status view you can choose Ctrl+F7 or the Execute Icon to start the send process for a communication type. You should receive you test message if everything is setup fine.
Trouble Shooting
Let's say that everything didn't go fine. Where do we start trouble shooting? Once again start with the transaction SCOT. The system status shows us our status overview. You can see the number of messages in Error or Waiting. If you have a lot of messages in Waiting status, your send job probably isn't scheduled.
The overview screen is nice, but you probably want more details. From SCOT you can choose Utilities->Overview of Send Orders (Or Tcode SOST). This transaction will give a detailed report by Address type, status, date, time and sender. For each message we can view the transmission history, the message itself, and the tracelog. You can also try and resubmit the message from here.
If you need to activate tracing, you want to return to transaction SCOT. You then choose Utilities->Trace->Internal Trace. You can also view all traces from here without having to go through SOST.
ABAP Coding
If everything has worked up to this point, then you are ready to start writing your own E-mail calls in ABAP. There are two SAP function modules that are commonly used: SO_NEW_DOCUMENT_ATT_SEND_API1 and SO_NEW_DOCUMENT_SEND_API1. The main difference between these two function modules is that SO_NEW_DOCUMENT_ATT_SEND_API1 allows you to send attachments along with your message. This is especially useful for including outputs and reports in your e-mail. To tell you the truth though, I always use SO_NEW_DOCUMENT_ATT_SEND_API1 even if I don't have any attachments. This just keeps my code very similar from application to application (I have a habit of cutting and pasting the email code most of the time).
Both of these function modules are quite well documented in SE80. The document even includes a sample program. The key to using this function module is putting your content for your email in the correct place. You have three "contents" table parameters: CONTENTS_BIN, CONTENTS_TXT, and CONTENTS_HEX. CONTENTS_TXT contains all you ASCII text based content. CONTENTS_BIN and CONTENTS_HEX are for binary based data such as PDF document attachments. You can use CONTENTS_HEX, however if you do the function will clear CONTENTS_BIN and copy CONTENTS_HEX to CONTENTS_BIN. I generally just focus on CONTENTS_BIN and CONTENTS_TXT. The key here is that all of your content must go into these two tables. Let's assume that you have two PDF file attachments that you want to send. The binary data for both attachments must be put into the single instance of the CONTENTS_BIN table parameter.
This is where another table parameter called the PACKING_LIST comes into play. The PACKING_LIST will be used by the function module to break up the individual pieces of content that are all forced together in your CONTENTS_BIN and CONTENTS_HEX files. Each piece of content should have a single record in the PACKING_LIST that specifies the content type (binary or ASCII), the starting position, the size, the name, etc. In the end this allows for a very flexible (but slightly complicated) E-mail interface.
The following is a simple code sample to complement the ones from the SAP help. I will create a simple mail message. In addition I will take a spool output and convert it to HTML and attach it to my message.
Global Data Statement
The following are my global data statements. You will see that I declare areas for my Packing List (objpack), Email header information (objhead), Binary Content (objbin), Text Content (objtxt), and my receiver list (reclist).
ABAP List as HTML
In this next section we will submit a program and capture its ABAP list output. We then convert this list output to HTML for inclusion as an attachment in our E-mail.
Building our Email
In this next section we will build the text body of our email.
Now we will create the packing list entry for our text body.
We already have our HTML content provided for us by the function module WWW_HTML_FROM_LISTOBJECT. We just need to create the packing list entry for this object.
In this next section we create our recipient list. I get my recipient from a select option on the screen. Now most user's forget to supply the person's full e-mail address and just give the SAP user id. I then take this SAP user id and call the BAPI of User Details to lookup their External E-Mail address. If I don't find an entry in their User Master, I will create one using our standard company domain.
Finally we can make the call to our API function module:
Closing
Hopefully this little tutorial on sending E-Mail from ABAP will help users get started. If you are on release 610 or higher and are feeling left out by this weblog, just wait. Tomorrow I should post a version of this weblog for those releases. The good news is that 610 has native SMTP support built into the ICM and that sending E-mail is overall much simpler and nicer.
There seems to be a lot of requests in the forums for tips on how to send E-Mail from ABAP. Based upon these requests, I thought I would pull together some resources and samples on the subject. The setup and samples are quite different on different releases. This first weblog will cover SAP Basis releases 46D and lower. All samples came from a 46C system (Although the ABAP code is very much the same as the code we used to use back on our old 3.1H system). There will be another weblog later that covers this same topic for WebAS Version 610 and higher.
Configuration
Before we start with any ABAP coding, we first have to setup and configure a few things. Much of this configuration may have already been completed by your Basis group.
Internet Mail Gateway
The first thing we want to setup is probably the Internet Mail Gateway. Since the Basis layer at these releases doesn't have any native SMTP abilities we will need an executable at the OS level to perform the sending of the mail for us. These executables are commonly referred to as the Internet Mail Gateway. I suggest that anyone doing this setup start by reading OSS note 99965. This has a quite good, step-by-step implementation guide to setting up the Internet Mail Gateway. To complete this part of the setup we need to make sure that we have our mail gateway configuration file (default name mailgw.ini) setup and available to the executables. That means using one of the two default directories or the GWCONFIG environment variable. The configuration file can be created or modified using the program MLSOMADM. Finally we need to make sure that we have the program that does the mail sending itself: MLUNXSND. If you need to know where you can go to get the latest patch level of these executables, please read OSS note 101573.
RFC Connection
Next we need to configure a RFC destination so that we can exposed these executables to ABAP. The instructions in OSS note 99965 describe setting up this TCP/IP RFC destination as Direct Start or via Registration. The following is a screen shot of our RFC Destination. We use the Direct Start Option, calling a shell script as described in the OSS Note:
SAPConnect
Well we are finished with all the low level setup. Now we need to connect the lowest layer (the Internet Mail Gateway) to SAP's middle message layer: SAPConnect. SAPConnect sits between the application layer (such as SAP Office) and the lowest layer hiding all the technical details. All of the SAPConnect monitoring and configuration can be reached from one transaction called SCOT. First SCOT has several different views that can be used. One shows the Jobs that have been setup, the other shows setup by routings, etc. I prefer to start SCOT in System Status View. This shows a tree with the communication types, the nodes setup for each type and the number of messages in each status. The following is a screen shot of this view:
We want to create a new node in SAPConnect for our E-Mail. In 46C you have a quite nice Wizard that walks you through the process. However you can also control all settings directly in a dialog maintenance window. This is a screen shot of our Email Node.
You can see at this point we connect the processing for this node to our RFC destination setup before. You also can set the supported address types and their settings.
For the supported address type of Internet, we really have a very plain setup. We don't do any outbound filtering to different nodes. Therefore the address areas is set to the wildcard '*'. We support all formats except those listed in OSS note 99965 (ALI, SCR, OTF, OBJ and URL) and use the PDF device type to format outputs. If you are interested in PDF Device Type in 46C or lower have a look at OSS note 317851.
One special note on code pages. If you are a MDMP system or you use a double byte code page, I'm afraid you could be in a little bit of trouble. Have a look at OSS note 331418 for the details on the support (or lack there of) for these special code page situations. I can tell you that the 610 and higher mail interface does solve this problem.
Next we need to schedule a job that will transmit out E-mails. E-Mails will only go out when this job runs, so you probably want to schedule it quite frequently. In our production system we run this job every 5 minutes. The job setup can also be done from SCOT. Switch your view to JOBS. You can then hit CREATE to start the process of scheduling a new Send Job.
Running a Test
We are just about ready to run our first test. The only other requirement is that the sender of any E-mail, must have their return address setup in their user master. If you don't maintain this data, you will get a send error. If you want an SAP program to generate these addresses for you, have a look at OSS note 104263. Also in 46C you have the option to configure the system to generate the sender address on the fly. OSS note 320443 gives you the details of this solution. You can see from the following screen shot the field that must be maintained in the user master:
Let's try a test now. I like to start by testing using the SAP short message functionality. You will want to use menu System->Short Message. From here we will prepare a short test message. If you don't want to wait for your batch job to run to find out if your message went through, just jump back to transaction SCOT. From the System Status view you can choose Ctrl+F7 or the Execute Icon to start the send process for a communication type. You should receive you test message if everything is setup fine.
Trouble Shooting
Let's say that everything didn't go fine. Where do we start trouble shooting? Once again start with the transaction SCOT. The system status shows us our status overview. You can see the number of messages in Error or Waiting. If you have a lot of messages in Waiting status, your send job probably isn't scheduled.
The overview screen is nice, but you probably want more details. From SCOT you can choose Utilities->Overview of Send Orders (Or Tcode SOST). This transaction will give a detailed report by Address type, status, date, time and sender. For each message we can view the transmission history, the message itself, and the tracelog. You can also try and resubmit the message from here.
If you need to activate tracing, you want to return to transaction SCOT. You then choose Utilities->Trace->Internal Trace. You can also view all traces from here without having to go through SOST.
ABAP Coding
If everything has worked up to this point, then you are ready to start writing your own E-mail calls in ABAP. There are two SAP function modules that are commonly used: SO_NEW_DOCUMENT_ATT_SEND_API1 and SO_NEW_DOCUMENT_SEND_API1. The main difference between these two function modules is that SO_NEW_DOCUMENT_ATT_SEND_API1 allows you to send attachments along with your message. This is especially useful for including outputs and reports in your e-mail. To tell you the truth though, I always use SO_NEW_DOCUMENT_ATT_SEND_API1 even if I don't have any attachments. This just keeps my code very similar from application to application (I have a habit of cutting and pasting the email code most of the time).
Both of these function modules are quite well documented in SE80. The document even includes a sample program. The key to using this function module is putting your content for your email in the correct place. You have three "contents" table parameters: CONTENTS_BIN, CONTENTS_TXT, and CONTENTS_HEX. CONTENTS_TXT contains all you ASCII text based content. CONTENTS_BIN and CONTENTS_HEX are for binary based data such as PDF document attachments. You can use CONTENTS_HEX, however if you do the function will clear CONTENTS_BIN and copy CONTENTS_HEX to CONTENTS_BIN. I generally just focus on CONTENTS_BIN and CONTENTS_TXT. The key here is that all of your content must go into these two tables. Let's assume that you have two PDF file attachments that you want to send. The binary data for both attachments must be put into the single instance of the CONTENTS_BIN table parameter.
This is where another table parameter called the PACKING_LIST comes into play. The PACKING_LIST will be used by the function module to break up the individual pieces of content that are all forced together in your CONTENTS_BIN and CONTENTS_HEX files. Each piece of content should have a single record in the PACKING_LIST that specifies the content type (binary or ASCII), the starting position, the size, the name, etc. In the end this allows for a very flexible (but slightly complicated) E-mail interface.
The following is a simple code sample to complement the ones from the SAP help. I will create a simple mail message. In addition I will take a spool output and convert it to HTML and attach it to my message.
Global Data Statement
The following are my global data statements. You will see that I declare areas for my Packing List (objpack), Email header information (objhead), Binary Content (objbin), Text Content (objtxt), and my receiver list (reclist).
ABAP List as HTML
In this next section we will submit a program and capture its ABAP list output. We then convert this list output to HTML for inclusion as an attachment in our E-mail.
Building our Email
In this next section we will build the text body of our email.
Now we will create the packing list entry for our text body.
We already have our HTML content provided for us by the function module WWW_HTML_FROM_LISTOBJECT. We just need to create the packing list entry for this object.
In this next section we create our recipient list. I get my recipient from a select option on the screen. Now most user's forget to supply the person's full e-mail address and just give the SAP user id. I then take this SAP user id and call the BAPI of User Details to lookup their External E-Mail address. If I don't find an entry in their User Master, I will create one using our standard company domain.
Finally we can make the call to our API function module:
Closing
Hopefully this little tutorial on sending E-Mail from ABAP will help users get started. If you are on release 610 or higher and are feeling left out by this weblog, just wait. Tomorrow I should post a version of this weblog for those releases. The good news is that 610 has native SMTP support built into the ICM and that sending E-mail is overall much simpler and nicer.
50 Comments
