11i Notification Mailer Setup and Testing - Definitive Step by Step Guide An Oracle White Paper April- 2002

11i Notification Mailer Setup and Testing Definitive Step by Step Guide
Purpose The purpose of this document is to systematically list out a procedure for setting up and testing the Notification Mailer with sendmail in UNIX. The procedure has been tested out on Oracle Applications 11.5.4 and 11.5.5 with Embedded Workflow. The procedure has not been tested out on Standalone Workflow but it should still work on a standalone version of Workflow. Notification Mailer What is it ? Notification Mailer is the tool used by Workflow to send and receive mails. The Notification Mailer makes use of the WFMAIL executable supplied with oracle applications. Concurrent Manager uses this tool to notify users of completed requests. How the Notification Mailer starts and what does it do ? The WFMAIL executable starts the WFMAIL process on the Server machine. While starting up, the executable expects certain parameters. These parameters are supplied to the executable through the wfmail.cfg file. wfmail.cfg file and its contents are discussed in detail in Step-3, Step-5 and Step-6 below. The WFMAIL process keeps looking for rows in the WF_NOTIFICATIONS Table for Notifications with mail_status=ACTIVE. For those notifications, the WFMAIL process acts, by sending mail to the address specified by the TO_USER column. For the incoming mails that come to the location specified by the ACCOUNT parameter the WFMAIL process specifically looks for the NID (Notification ID) in the Mail body. If it cannot find an NID, the process moves that mail to the DISCARD file. If there is an NID in the incoming mail, the mail is put to the UNPROCESSED file. The WFMAIL process acts upon these mails in the UNPROCESSED file after which , they are moved to the PROCESSED File.

Starting up the Notification Mailer Step by Step

In the following discussion , "ora8i" is the <applmgr> user. Step1 Start off by checking whether the sendmail executable is there in the $PATH . For this, login to UNIX as the <applmgr> user and issue the following command : $ which sendmail no sendmail in /home9/apps/actora/8.0.6/bin /usr /home9/apps/actappl/fnd/11.5.0/bin /home9/apps/actappl/ad/11.5.0/bin /home9/apps/actora/8.0.6/bin /home9/apps/actcomn/util/jre/1.1.8/bin /usr/ccs/bin /usr/sbin /usr/bin /ucb /etc .

/usr/ucb/cc

/usr/bin

The above output means that sendmail executable folder location is not appended to $PATH. To do this, first you need to locate, in which folder is the sendmail executable residing. See the following sequence of commands to locate the folder

$ pwd /home4/ora8i $ cd ../.. $ pwd / $ find . -name sendmail -print ./usr/lib/sendmail So from the above output, it is clear that the executable is inside the folder /usr/lib. If you get an output such as the above, you will need to add /usr/lib to the $PATH environment variable. Since the $PATH environment variable is defined within the .profile file of the <applmgr> user, it is advisable to modify the .profile file itself and login again into UNIX Then $echo $PATH Study the output of the above to ensure that /usr/lib included in the $PATH .

is

This time follows :

issuing

the

command

again,

should

reply

as

$ which sendmail /usr/lib/sendmail

If the command $which sendmail finds the sendmail executable, then you can proceed to the next step-2

Step2 Now test sendmail as follows : $ sendmail venkateswaran.krishnamoorthy@oracle.com hkld lkdf ghit <Terminate by typing in cntrl-D> $ This will send a mail to the specified address. Check that the mail has been duly received at the mailbox. Then you can reply to this mail from your mailbox and should be received at the UNIX <applmgr> account. To test this reply has been received, login as <applmgr> into UNIX and type mailx $ mailx mailx version 5.0 Wed Sep 5 16:10:06 PDT 2001 Type ? for help. "/var/mail/ora8i": 1 message 1 new >N 1 venkat.kris Tue Apr 2 16:53 56/1792 Re: ? 1 This step-2 ensures that sendmail is working correctly for sending and receiving mails. Step3 Now you need to create 3 Files at a location, which is readable and writeable by the <applmgr> user. /var/mail is a typical example of this location. So create 3 files at /var/mail as follows : $cd /var/mail $touch processed1 unprocessed1 discard1

After doing the above step verify the permissions for these 3 files : $ ls -l -rw-r--r-1 ora8i dba 0 Mar 28 -rw-r--r-1 ora8i dba 0 Mar 28 -rw-r--r-1 ora8i dba 0 Mar 28

ownership and file

15:39 discard1 15:23 processed1 15:40 unprocessed1

Ensure that <applmgr> user is the owner of these 3 files (notice that ora8i is the owner in the above output) and has privileges -rw-r--r-- on these 3 files (as given above in the output). The following will be now the setting for the parameters in the wfmail.cfg file : UNPROCESS = /var/mail/unprocessed1 PROCESS = /var/mail/processed1 DISCARD = /var/mail/discard1

Step4 While working, the Notification Mailer creates a file in the Folder /tmp. The name of this wfmlrwf.tmp. Check up at the folder /tmp; if exists ensure that the <applmgr> user owns it <applmgr> user has permissions -rw-r--r-- on this $cd /tmp $ls -l wfmlrwf.tmp -rw-r--r-1 ora8i

temporary file is the file and the file.

dba

0 Apr

2 18:56 wfmlrwf.tmp

If the file exists and is owned by a different user, you need to remove the file wfmlrwf.tmp. Otherwise the WFMAIL process will not be able to write the temporary file, and it will throw an error. So, login to UNIX as the user who created the file and remove it. $rm wfmlrwf.tmp If you remove the wfmlrwf.tmp file before mailer, as given above, the WFMAIL process temporary file wfmlrwf.tmp, as and when it to be ensured that <applmgr> user has write the folder /tmp as follows. $cd /tmp $cd .. $ls l starting up the will create the needs it. It is permissions for

drwxrwxrwt

9 sys

sys

6438 Apr

2 19:16 tmp

Notice drwxrwxrwt permissions in the output above. This is the default setting for /tmp folder and so it is sufficient if you merely verify it. Step5 The ACCOUNT parameter in the wfmail.cfg file actually points to a file inside the Folder /var/mail. The name of the file is same as the name of the <applmgr> user. So, in this case the file name is ora8i. And the resulting ACCOUNT parameter will be /var/mail/ora8i. If you are configuring the Notification mailer service to startup from a user other than the <applmgr> user, then ensure that there is a file by the same name as the user name in the folder /var/mail. And modify ACCOUNT parameter in the wfmail.cfg file accordingly. $cd /var/mail $touch ora8i $ls l -rw-rw---1 ora8i

mail 1216 Apr 20 12:41 ora8i

This file (in this case ora8i) is important because all the incoming mails for the <applmgr> user are received into this file. Then from this file the WFMAIL process will read the incoming mails for the user. As explained earlier, the mails with an NID are directed to the UNPROCESSED file and others to the DISCARD file. Step6 The first 5 steps complete the preparatory steps. Now you can proceed to make a wfmail.cfg file, which will be used by the WFMAIL process. The sample wfmail.cfg file supplied by the installer can be located at $FND_TOP/resource folder. Modify this file appropriately, to suit your environment. Here are the minimum parameters and the corresponding representative values that you need to make the mailer work : Connect provides the Database login information for the mailer process. Do not forget to change the APPS password, if you have modified it.

CONNECT=apps/apps@ACT Step-5 above gives the details of the ACCOUNT parameter. ACCOUNT=/var/mail/ora8i The FROM parameter is the "From" field in mails sent from the mailer. FROM=Oracle Workflow When messages get Queue, from where by one. Number of the default value QUEUE=1 NODE is the mailer Node name. but is mandatory. NODE=wf IDLE is in seconds and means that WFMAIL process will act every IDLE seconds. IDLE=20 This can be given any value piled up, they need to be put into a the mailer can pick up the messages one outbound SMTP queues can be retained as of 1.

SHUTDOWN is a very important parameter. It points to the location of the shutdown file. The WFMAIL process is shutdown smoothly in a very peculiar way. You need to login to the UNIX Server where WFMAIL Service is running as the user who started the WFMAIL service. Then navigate to the Folder where the SHUTDOWN parameter is pointing to (In this Example, it is /var/mail). Then create a SHUTDOWN file by the same name given for this parameter in the wfmail.cfg file. SHUTDOWN=/var/mail/shutdown1 For the above value of the SHUTDOWN parameter, you can do the following to stop the WFMAIL service : $cd /var/mail $touch shutdown1

Note that this is the only way to smoothly stop the WFMAIL Service. REPLYTO is the UNIX mail address of the <applmgr> user. This is an important parameter and will be used by the mailer to sent back replies. REPLYTO=ora8i@insn056q.idc.oracle.com

DISCARD, UNPROCESS and PROCESS parameters are as explained in Step-3 above. DISCARD=/var/mail/discard1 PROCESS=/var/mail/processed1 UNPROCESS=/var/mail/unprocessed1 It is recommended to include the following 2 parameters, to enable debugging. LOG= /home9/apps/actappl/fnd/11.5.0/resource/wfmail.log DEBUG=Y TAGFILE is supplied by the Oracle Applications Installer. It can be located inside the $FND_TOP/resource Folder. WFMAIL process uses the tags defined in this file at the time of response processing. A typical entry from the tagfile is given below : ERROR "-- Unsent message follows --" So, when ERROR results, the tag that gets added to the response mail will be -- Unsent message follows In 11.5.5, there are 9 such entries in the tagfile.

Step7 Consolidating the parameters explained in the previous Step-6, the following would be the contents of a valid WFMAIL.cfg file CONNECT=apps/apps@ACT ACCOUNT=/var/mail/ora8i FROM=Oracle Workflow QUEUE=1 NODE=wf IDLE=20

TEST_ADDRESS=venkateswaran.krishnamoorthy@oracle.com REPLYTO=ora8i@insn056q.idc.oracle.com DISCARD=/var/mail/discard1 PROCESS=/var/mail/processed1 UNPROCESS=/var/mail/unprocessed1 SHUTDOWN=/var/mail/shutdown DEBUG=Y LOG=/home9/apps/actappl/fnd/11.5.0/resource/wfmail.log TAGFILE=/home9/apps/actappl/fnd/11.5.0/resource/wfmail.tag

Step8 Having made a valid wfmail.cfg file, you can now proceed to start up the Notification mailer. There are 2 ways of starting up the mailer service : 1. From the $ prompt of the UNIX applmgr user. 2. As a concurrent request The first method of starting up the mailer from the UNIX command prompt, is recommended. This is because, as the Mailer processes any notification request, it will also display progress messages and errors on the UNIX session console. These messages are vital in diagnosis. So, if you are setting up the Notification Mailer for the first time, resort to this method. The following is the command : $cd $FND_TOP/resource $WFMAIL apps/apps@ACT 0

$FND_TOP/resource/wfmail.cfg

The downside of this method is, the WFMAIL executable will HOLD this UNIX session. So, basically you will not be able to do anything from this UNIX session console. ( It will appear to hang ! ) If you choose to start the Notification Mailer as a concurrent request, then you will not have an UNIX session to see the progress OR to see any debugging information necessary for diagnosis. So, this method of Startup is suitable, once you have established a working mailer setup. The above 8 steps will enable the Notification startup . The next step will be to test the setup. Mailer

Testing the Notification Mailer

There are 2 ways of testing the setup : 1. By submitting a concurrent request 2. By using a simple Workflow process. Before doing either of the 2 tests, ensure that the Notification Mailer has started and is running on the Applications Server. Testing by submitting a concurrent request The advantage of testing the Mailer using this Test is that, the test is very simple and that it can be done without using the Workflow Builder. The downside of this approach being that, this test only tests "sending" the mail from the mailer; receiving the mail by the Mailer and the appropriate routing on receipt of a mail, are not tested. If you do not have the Workflow builder, you will have to be content with this test of the Mailer. 1. To do this, first of all login to Oracle Applications as SYSADMIN/SYSADMIN and create a new user and Save. Security ==> User ==> Define. (Ex. STEVE) While creating this user, take care to input the correct E-mail address of this user at the E-mail field. Later, an E-mail will be sent to this user, to test the working of the Notification Mailer setup. 2. Now submit a request, specifying to notify the user created in Step-1 Concurrent ==>Requests ==>Submit a New Request ==>Single Request Choose the Name of an Example Request , say "Active Responsibilities" and choose to notify the User created at Step-1 : Notify ==> Options Button Name field, enter STEVE. in the same page ==> Against

3. After Step-2, proceed to submit the Request by clicking on Submit button. Once the submitted request completes, inspect the request log for a line, which specifies the NID (Ex. 21462). NID is the Notification ID generated by the Mailer. At this point, if you see the UNIX session running the Mailer, you can see a line such as the following : 01-04-2002 16:24:56 - Sending 'OPEN' for NID 21462 If there are no error messages at the UNIX console accompanying the above line, then it is certain that the mail has been correctly sent to STEVE. User STEVE can check his Mailbox at the E-mail address given in Step-1 for the receipt of the mail. Issue the following SQL as apps/apps user to confirm that the Notification with this NID has 'status' as 'CLOSED' : SQL>SELECT status,mail_status from WF_NOTIFICATIONS WHERE notification_id=21462 CLOSED SENT

This completes this Test and tests that the Mailer is working for sending mails.

Testing the Mailer using a simple Workflow model This method of testing is the comprehensive way of testing the Notification Mailer setup. This is also the test recommended by the Oracle Support team. To do this Test, you need to have the Workflow builder installed on a Windows client machine. The test can be downloaded from the following URL :
ftp://oracle-ftp.oracle.com/apps/patchsets/AOL/SCRIPTS/WORKFLOW/GENERIC/11i/

The File to be downloaded is supptest26.zip supptest26.zip supplies 2 files :

1. A *.wft file by name supptest26.wft This file defines the workflow process, which can be used to do this test. The supptest26.wft file defines an item type called SUPPTEST, which is the simplest item type one can think of, to do this testing of the Mailer. 2. A Readme file. This Readme file contains step-by-step instructions for doing the test. Steps mentioned in this Readme file are referred to, in the following instructions. Step by step instructions to carry out this Testing 1. Create an Oracle Applications user to whom Notifications will be sent for testing. To do this, first of all login to Oracle Applications as SYSADMIN/SYSADMIN and create a new user and Save. Security ==> User ==> Define. (Ex. STEVE) While creating this user, input the correct E-mail address of this user at the E-mail field. Later, from the mailer, a mail will be sent to this user, to test the working of the Notification Mailer setup. Also, see Step-1 in the Readme File. 2. Then we proceed to open the Workflow Builder and establish a Database connection as user apps/apps.(Steps 2 & 3 in the Readme File) 3. A Role will get created in the Database (You can Query the WF_USERS and WF_ROLES view, to verify) corresponding to the user created in Step-1. That Role will have to be loaded into the Workflow Builder session. Only then, we can assign the Role to the testing Notifications to be sent from this item type. So, when the item type is run, the mails generated by the Item Type will be directed to this Role (Meaning, to the user created in Step-1) . Follow Step-4 in the Readme to accomplish the Loading of this Role from the Database to this Workflow Builder session.

4. The next step is to open the supptest26.wft file into this Workflow Builder session. To do this, follow Step-5 and Step-6 of the Readme. 5. The very purpose of opening the supptest26.wft item type in a Workflow Builder session is to modify it, which modification in turn will enable us to sent the Notification to the user that was created in Step-1. To do this, we go to the "properties" of the "Support Test Notification" icon on the workflow process diagram, and appropriately modify its performer value. Step-7 in the Readme details the steps involved. 6. The above set of steps, complete the modifications to be made on the supptest26.wft file. It can be now loaded back into the Database. Step-8 in the Readme explains the details of loading this file back into the Database. After the above 6 steps, do not end the Workflow builder session. You will still need it to find out the parameters that are to be passed to WFRUN.SQL (next step) Having loaded the appropriately modified SUPPTEST item type back into the Database, we need to run the "Support Test Process" from the SQL prompt. That only will confirm whether the mailer setup is working or not. To run any Workflow process from the SQL prompt , Oracle Applications supplies an SQL file called WFRUN.SQL. This file can be located at $FND_TOP/sql. This SQL file takes in 3 parameters. <item_type> is the first parameter. This is the INTERNAL NAME of the item type "Support Item Type". In this case, you can get this by doing the following on the Workflow Builder Navigator : Support Test Item Type ==> Mouse Right Click ==> Properties ==> Internal Name ( You will find that SUPPTEST is the value in this case) The second parameter <item_key> can be any number, except that it should NOT have been used before for this type.

<process_name> is the 3rd parameter. The value of this parameter is the INTERNAL NAME of the "Support Test Process". In this case, you can get this by doing the following on the Workflow Builder Navigator : Processes ==> Support Test Process ==> Mouse Right Click ==> Properties ==> Internal Name (You will find that SUPPTEST_PROCESS is the value in this case ) If you either modify the Item Type or decide to create your own testing workflow process, the above information about the 3 parameters , will be helpful. Otherwise, follow Step-10 in the Readme, to RUN the SUPPTEST item type using WFRUN.SQL.

As suggested in the Readme Step-11, WFSTATUS.SQL is to be used to VERIFY THE STATUS of the SUPPTEST item type. The following WFSTATUS.SQL shows a typical output from running the

1. Output while the process is still ACTIVE 14-APR-02 19:22:59 ROOT/Support Test Process ACTIVE #NULL <== 14-APR-02 19:22:59 Support Test Process/Start COMPLETE #NULL 14-APR-02 19:22:59 Support Test Process/Support Test Notificatio COMPLETE REJECTED VENKAT n 14-APR-02 19:34:38 Support Test Process/Support Test Notificatio NOTIFIED VENKAT <== 2. Output while the process has been COMPLETED 14-APR-02 19:22:59 ROOT/Support Test Process COMPLETE #NULL <== 14-APR-02 19:22:59 Support Test Process/Start COMPLETE #NULL

14-APR-02 19:22:59 Support Test Process/Support Test Notificatio COMPLETE REJECTED VENKAT n 14-APR-02 19:34:38 Support Test Process/Support Test Notificatio COMPLETE REJECTED VENKAT n 14-APR-02 19:37:41 Support Test Process/End COMPLETE #NULL <== You can see from the above output that, in the first case, the ROOT Process is showing that it is ACTIVE (See the first line).From the 4th line, it is clear that VENKAT has been NOTIFIED and reply action is pending from his mailbox. In the second case, the ROOT Process is showing COMPLETE status (See the first line). And the last line confirms that the process has ended. Once you get an output such as this, you can be sure that the Notification Mailer is up and running correctly. Otherwise, you need to send the output of WFSTATUS.SQL to Oracle Support for Troubleshooting.

Trouble shooting
Listed below is a set of errors that you may encounter while configuring the Notification Mailer. As stated earlier, it is recommended to start the mailer from the UNIX command prompt for ease in diagnosis. Also start the mailer, stating DEBUG=Y and LOG=<log_file_name> in the wfmail.cfg file. 1. If you are using concurrent request to test the Notification mailer setup, make sure that you don't have a yellow bar on the client machine. If you do see a Yellow warning bar, then mails may not get sent. Solution => The solution in this case is to download the jinitiator from the same server from where you are accessing Oracle Applications using the URL. Remove the existing jinitiator by going through Start ==> Settings ==> Control Panel ==> Add/Remove Programs. Now when you access Oracle Applications afresh, jinitiator will get downloaded from your server and will show no Yellow bar.

2. You have the following scenario : Mails are correctly received. But the received mails have "ACCEPT" and "REJECT" tags in text Format.( But they should be in HTML Format so that you can respond ! ) Solution => Go to the Workflow Home page through Oracle Applications as SYSADMIN user, and modify "Send me Electronic mail notifications" to either HTML Mail OR Plain Text mail with HTML Attachments . 3. You might get the following error on the UNIX session where you started the WFMAIL Service. And the mailer will crash, when it tries to send the mail :

14-APR-2002 18:44:06 - Sending 'OPEN' for NID 19805 wferr: - 2009: Fatal error, mailer is exiting. - WFMLRSLOOP_FAIL - 2320: Setting context failed for notification 19805. - 210: Oracle Error: ORA-20002: 3102: Item Type '' does not exist. ORA-06512: at "APPS.WF_MAIL", line 2206 ORA-06512: at line 1 . SQL text: begin WF_MAIL.SetContext(:n); end; $ Solution => In 11.5.5 , to solve this, you need to Apply patch 2021605 as per Note:165058.1 4. If you have not followed this document in setting up the Notification Mailer, then you might get the following error on the UNIX session where you started the WFMAIL Service : - 2206: Mail service could not send mail message. - 207: Could not open file '/tmp/wfmlrwf.tmp' Solution => This problem arises because the WFMAIL executable is not able to write to the temporary file '/tmp/wfmlrwf.tmp'. Review Step-4 under "Setting up the Notification Mailer" section in this document and conform to the points in that step.

5. You can query up the Database views WF_USERS, WF_NOTIFICATIONS and WF_ROLES , for general troubleshooting. In issuing SQL queries against these views, use the Notification ID (NID) as the search criteria. 6. To isolate whether a problem arises due to the mailer or due to an item type supplied by any Oracle Applications Module, you can run the test mentioned under "TESTING THE MAILER USING A SIMPLE WORKFLOW MODEL" in this document. If it works correctly, then the problem is mostly in the Item type definition.

11i Notification Mailer Setup and Testing - Definitive Step by Step Guide
May 2002 Author: Venketeswaran.V.K Contributing Authors: Prashanth Naik (Testing), Madhu Sudhan (UNIX) Copyright Oracle Corporation 2002 All Rights Reserved Printed in the U.S.A. This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors herein to Oracle Corporation. Oracle Corporation does not provide any warranties covering and specifically disclaims any liability in connection with this document. Oracle is a registered trademark and Enabling the Information Age, [Add trademarks here] are trademarks o f Oracle Corporation. Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: 415.506.7000 Fax 415.506.7200 Copyright Oracle Corporation 1995 All Rights Reserved