Doc ID: Note:234436.1Subject: How-To Setup Workflow Mailer in an Oracle

Applications 11i environment .Type: HOWTOStatus: PUBLISHED

Content Type: TEXT/PLAINCreation Date: 02-APR-2003Last Revision Date: 16-MAY-2003

How-To Setup Workflow Mailer in an Oracle Applications 11i environment . Oracle Applications 11i Workflow Mailer GENERIC UNIX Symptom(s) ~~~~~~~~~~ The scope is to setup the Workflow Notification with Oracle Applications 11i . Change(s) ~~~~~~~~~~ Please see the fix . Fix ~~~~ ===ISSUE: Workflow Mailer setup in an OA 11i environment . The workflow mailer is a utility used to send notifications via e-mail . The workflow mailer can be started within Oracle Applications or from o/s command . This note will describe how to start/configure the mailer from O/S level (IBM AIX in our example). 1. Edit the $FND_TOP/resource/wfmail.cfg and make the right changes. Please see note 153229.1 for more details. An example of wfmail.cfg will be enclosed (see Appendix 1) . Please note that if you are running several WFMAIL on the same server (you have several 11i envs), the NODE entry in wfmail.cfg must be different for each environment . Otherwise, all of them will try to create the same file under the same directory: /tmp . Also, be notified that if you'll perform 'strings -a $FND_TOP/bin/WFMAIL | grep tmp' , you'll see that the temporary directory and the temporary file name is being hardcoded in the executable . :) 2. Create the directory where the shutdown, processed, unprocessed, will be located . touch /oa/sit/sitcomn/temp/WFMAIL/discard touch /oa/sit/sitcomn/temp/WFMAIL/processed touch /oa/sit/sitcomn/temp/WFMAIL/unprocessed 3. Create the startup and shutdown scripts for workflow mailer: ---startWFMAIL.sh rm /oa/sit/sitcomn/temp/WFMAIL/shutdown nohup /oa/sit/sitappl/fnd/11.5.0/bin/WFMAIL apps/apps@sit 0 Y /oa/sit/sitappl/fnd/11.5.0/resource/wfmail.cfg & ---stopWFMAIL.sh touch /oa/sit/sitcomn/temp/WFMAIL/shutdown Once the WFMAIL will find the shutdown file it will gracefuly shutdown . If you've started the WFMAIL more than once (by mistake, you've run startWFMAIL.sh several times), you'll find several WFMAIL unix processes . Try to run the stopWFMAIL.sh for the same number of times. If you're still not able to clean'em, use the 'kill' command.

document.doc, Created by Mochamad Isa, Page 1 of 13

Before you can include these scripts into the general startup/shutdown procedures for the entire OA environment please make sure they are functioning properly. Please note that we've disabled the Workflow Mailer and Summary Mailer Concurrent Managers prior to this procedure . ===Appendix 1: # $Header: wfmail.cfg 115.8 2001/03/29 20:24:06 pkm ship $ # Workflow Mailer Configuration File # All parameters are optional unless otherwise noted # Some have default values if left unspecified # Fill in all parameters according to site requirements # System Configuration # Database Login Information CONNECT=apps/apps@sit # Mail Account: mail account to send and receive mail from (required) # CHANGE THIS! # ACCOUNT=wfoffice/wfoffice ACCOUNT=/var/spool/mail/applsit # From: value of the from field in the header of mail message sent # by the Oracle Workflow Mailer FROM=SIT Oracle Workflow # Mailer Outbound Queues: This values indicates the number of outbound # SMTP queues the mailer will monitor. # QUEUE=1 # Mailer Node name: name to identify this mailer (required) NODE=APPLSIT # Send Notification Summary Only SUMMARYONLY=N # Direct Response Required (Only available for notifications to MAILTEXT and MAILATTH roles) DIRECT_RESPONSE=N # Idle time: time to wait between polling for new work (seconds) IDLE=30 LOG=/oa/sit/sitcomn/temp/WFMAIL/WFMAIL.log # Shutdown request file: when this file is detected, the mailer exits SHUTDOWN=/oa/sit/sitcomn/temp/WFMAIL/shutdown # Fail command: os command to run when exiting with error FAILCOMMAND=echo "Mailer has exited with error ... Please investigate . " # Debug mode: turns on extra debugging output # DEBUG=Y # Test Address: routes outgoing mail to the indicated address (for testing) # TEST_ADDRESS=testaccount # # Send Configuration # # Reply To email address: email address that responses should go to (required) # CHANGE THIS! REPLYTO=root@oracle.com # HTML Web Agent path: (required for mailed html support) # CHANGE THIS if you have a HTML web agent for HTML attachments that is # to be different to the HTML Agent speicified in Oracle Workflow # Global Preferences. # HTMLAGENT=http://hqsun.company.com/wf/owa HTMLAGENT=http://your_server.oracle.com:8060/pls/SIT # HTML Attachment desc: description of attachment type (required for Oracle Internet Messaging only) HTMLDESC=HTML

document.doc, Created by Mochamad Isa, Page 2 of 13

# HTML Attachment type: numeric attachment code (required for Oracle Internet Messaging only) HTMLTYPE=10003 # # Respond Configuration # # Discard Folder: folder in which unrecoginzed incoming mail is placed # (leading '-' truncates folder on startup) DISCARD=-/oa/sit/sitcomn/temp/WFMAIL/discard # Processed folder: folder in which successfully processed mail is placed PROCESS=/oa/sit/sitcomn/temp/WFMAIL/processed # Unprocessed folder: folder in which mail awaiting processing is placed UNPROCESS=/oa/sit/sitcomn/temp/WFMAIL/unprocessed # Response Tag file: file for response routing (optional) # CHANGE THIS! TAGFILE=/oa/sit/sitappl/fnd/11.5.0/resource/wfmail.tag # Reset NLS codeset per notification # It will use the codeset from WF_LANGUAGES base on recipient's language # and territory. # RESET_NLS=Y # Specify an alternate HTML Mail Template for mail reader that has # problem supporting certain features # HTML_MAIL_TEMPLATE=OPEN_MAIL_OUTLOOK References ~~~~~~~~~~~

document.doc, Created by Mochamad Isa, Page 3 of 13

goal: How to configure embedded workflow notification mailer with UNIX sendmail fact: Oracle Workflow Embedded 2 fact: Oracle Application Object Library 11.0 fact: Oracle Application Object Library 11.5 fact: UNIX sendmail fact: FNDWFMAIL - Notification Mailer

fix:

This setup assumes that the mailer will be running on the same machine on which the workflow server (database) is installed.

I. The operating system user that runs the mailer must possess the following:

1. Accessibility and permissions for the necessary files and directories to do the workflow mailer's job.2. The ability to log into the workflow server (on the same or different box) using a SQL*Net connection. 3. The ability to send and receive e-mail from the server on which it is running. 4. Freedom from the need to receive e-mail messages, not generated from Oracle Workflow.

II. Setup Workflow Notification Mailer:

1. Ensure that UNIX Sendmail is configured and users can send and receive email to externally.

2. Create a UNIX account for workflow that just receives mail.

For this example the user account is 'wfmailer'.

3. Add wfmailer to the 'dba' group.

4. Set umask for wfmailer to 022.

5. Test that wfmailer can logon and send and receive email. 6. Make certain that wfmailer's environment is setup the same as the UNIX user that installed workflow.

7. Source the same environment file that is sourced for the applmgr account

8. Ensure that wfmailer can log into the database.sqlplus apps/<pwd>@<dbname>

9. Ensure wfmailer has the following permissions.chmod 777 $FND_TOP/bin/WFMAILchmod 755 $FND_TOP/resource/wfmail.cfgchmod 755 $FND_TOP/resource/wfmail.tag

10. Make sure that wfmailer has permissions to read and write in the directory it will work in.

11. Configure the following parameters in the wfmail.cfg file located in $FND_TOP/resource/wfmail.cfg

CONNECT=apps/<pwd>@<dbname>

document.doc, Created by Mochamad Isa, Page 4 of 13

ACCOUNT=/var/mail/wfmailer -or- ACCOUNT=/usr/mail/wfmailer

SHUTDOWN=/home/wfmailer/work/shutdown

HTMLAGENT=http://<machine.domain.com>:<port>/<agent>/plsql

DISCARD=/home/wfmailer/work/discard

PROCESS=/home/wfmailer/work/processed

UNPROCESS=/home/wfmailer/work/unprocessed

TAGFILE=$FND_TOP/resource/wfmail.tag

12. Start the mailer: Logged on as wfmailer:$FND_TOP/bin/WFMAIL apps/<pwd>@dbname 0 Y $FND_TOP/resource/wfmail.cfg &amp;

NOTE:For a more detailed configuration paper see Configuring the Workflow Notification Mailer -- Sendmail

For instruction on how to configure embedded workflow notification mailer with UNIX sendmail see How to Configure Standalone Workflow Notification Mailer with UNIX Sendmail

For instructions on how to configure the MAPI version, see How To Configure Workflow Notification Mailer - MAPI

References:Oracle Workflow 2.0.3 Guide, Setting Up Oracle WorkflowOracle Workflow 2.5 Guide, Setting Up Oracle Workflow

document.doc, Created by Mochamad Isa, Page 5 of 13

Doc ID: Note:104198.1Subject: WF 2.x: Configuring the Notification Mailer v 2.0.3

- 2.6.2 (not OAM)- SENDMAILType: WHITE PAPERStatus: PUBLISHED

Content Type: TEXT/PLAINCreation Date: 02-APR-2000Last Revision Date: 02-OCT-2003

PURPOSE ------- The purpose of this document is to provide a step-by-step guide to a successful configuration of the Sendmail version of the Oracle Workflow Notification Mailer. This method is recommended for both a standalone install or Oracle Applications embedded install of Workflow. SCOPE & APPLICATION ------------------- The instructions below apply to versions Oracle Workflow 2.0.3 to 2.6.2 without Oracle Applications Manager (OAM.) This document is intended for System Administrators or Database Administrators responsible for the implementation of Oracle Workflow. The steps below are based on experience and testing in Workflow 2.0.3. However, the concepts should also be suitable for configuring the mailer for use with Workflow 2.5. A sample wfmail.cfg file for embedded as well as standalone workflow are provided at the end of this document. The configuration described below is not the only way to implement the mailer. For example, this document assumes that the mailer will be running on the same machine on which the workflow server (database) is installed. This is not necessarily the case. It is possible to setup the Sendmail or MAPI version of the mailer for a specific install of workflow running on a separate UNIX or Windows NT machine, respectively. The key factors for successful configuration, however, will remain the same. The operating system user that runs the mailer must possess the following: 1. Accessibility and permissions for the necessary files and directories to do the workflow mailer's job. 2. The ability to log into the workflow server (on the same or different box) using a SQL*Net connection. 3. The ability to send and receive e-mail from the server on which it is running. 4. Freedom from any necessity to receive important e-mail messages, not generated from Oracle Workflow. CONFIGURING THE WORKFLOW NOTIFICATION MAILER -- SENDMAIL -------------------------------------------------------- Before starting to setup the mailer, make sure that UNIX Sendmail is configured on the operating system such that users can send and receive e-mail to external recipients. 1. Create a UNIX account for workflow. This UNIX user should only receive mail generated by Oracle Workflow. For embedded workflow, it is not advised to run the mailer as a concurrent program from Applications, since concurrent programs always run under the applmgr account. (For details on the associated problems with other types of incoming mail for the workflow mailer account, see note#1011352.102.) For easy reference,

document.doc, Created by Mochamad Isa, Page 6 of 13

the user account created will be referred to as 'wfmailer'. Add wfmailer to the 'dba' group on the operating system and set the umask for wfmailer as 022. To ensure that the umask is always 022 for wfmailer, add the following line to the .profile or .login file: umask 022 2. Test that wfmailer is able to log onto the server and that a test e-mail can be sent and received from an external recipient using Sendmail. 3. Make sure that wfmailer's environment is setup in the same way as the UNIX user with which workflow was installed. a. Embedded: source the same environment file that is sourced for the applmgr account b. Standalone: source the same environment file that is sourced for the account that was used to install workflow 4. Ensure that wfmailer can log into the database as the Oracle user owning all of the workflow objects. a. Embedded: sqlplus apps/<pwd>@<dbname> b. Standalone: sqlplus <oracle_user>/<pwd>@<dbname> -- <dbname> is the SQL*Net service/TNS alias of the database where workflow is installed <oracle_user> is the oracle user owning the workflow objects <pwd> is the oracle password for the appropriate account 5. Ensure wfmailer has the necessary permissions over the mailer executable file, the wfmail.cfg and the wfmail.tag file. a. Embedded: chmod 777 $FND_TOP/bin/WFMAIL chmod 755 $FND_TOP/resource/wfmail.cfg chmod 755 $FND_TOP/resource/wfmail.tag b. Standalone: chmod 777 <path>/bin/wfmail.snd chmod 755 <path>/res/wfmail.cfg chmod 755 <path>/res/wfmail.tag -- <path> is the full path to the workflow directory structure on this server 6. Determine the directory in which the mailer will do it's work: By default the working directory for the mailer will be the directory from which the command to start the mailer is executed. The workflow mailer will create the spool files unprocessed, processed, and discard in the working directory. Also the working directory is periodically scanned by the mailer for the existence of the 'shutdown' file, which cues the mailer to shut down gracefully. It is recommended to determine a constant working directory at this point for the mailer regardless of the directory from which it is started. Once the directory is determined, make sure that wfmailer has permissions to read and write in this directory. As an example, creating a subdirectory called 'work' under wfmailer's home directory would be a good choice, since wfmailer will already have permissions in this location. 7. Edit the wfmail.cfg file: This file is located in the directory a. Embedded: $FND_TOP/resource/wfmail.cfg b Standalone: <path>/res/wfmail.cfg -- <path> is the full path to the workflow directory structure on this server

document.doc, Created by Mochamad Isa, Page 7 of 13

First save the original copy as a backup. There are many parameters which can be changed from the defaults. However, only eight are crucial to get the mailer running in a specific environment: CONNECT, ACCOUNT, SHUTDOWN, HTMLAGENT, DISCARD, PROCESS, UNPROCESS, and TAGFILE. These parameters are described below. For information on additional parameters in the file, refer to the Oracle Workflow Guide for the specific version of Workflow. CONNECT= provides the mailer access to the workflow schema in the database where the workflow server is installed. Format: a. Embedded: CONNECT=apps/<pwd>@<dbname> b. Standalone: CONNECT=<oracle_user>/<pwd>@<dbname> -- <dbname> is the SQL*Net service/TNS alias of the database where workflow is installed <oracle_user> is the oracle user owning the workflow objects <pwd> is the oracle password for the appropriate account ACCOUNT= provides the mailer access to the spool file where incoming messages for the UNIX user who starts the mailer are stored. The full path to this file must be specified. In most cases, the spool file will be the name of the user and located in either /usr/mail or /var/mail directory. Examples: ACCOUNT=/var/mail/wfmailer -or- ACCOUNT=/usr/mail/wfmailer SHUTDOWN= specifies the name or full path name of the file that cues the mailer to shut down gracefully. It is recommended to specify the full path of the directory chosen for the mailer's working directory, where read permissions have been ensured (see previous step). (Therefore, the mailer can be shut down when necessary, by going to the directory and using the UNIX 'touch' command to create a file named shutdown.) Example: SHUTDOWN=/home/wfmailer/work/shutdown HTMLAGENT= specifies the base URL that identifies the virtual path of the Web Server PL/SQL Agent that has been created to connect to the workflow server database as the Oracle user owning the workflow objects. This URL is required to support E-mail notifications with HTML attachments. (This is not absolutely critical to getting the mailer up and running. However, it is specific to a given environment. If not modified, links to URL attachments that may be contained in e-mail notifications will fail when clicked by the recipient.) Format: HTMLAGENT=http://<machine.domain.com>:<port>/<agent>/plsql -- <machine.domain.com> fully qualified name of web server machine <port> the port number for the agent's authenticated web listener <agent>/plsql virtual path for the PL/SQL agent Example: HTMLAGENT=http://emborc05.us.oracle.com:8100/VIS/plsql DISCARD= The name or full path name of the mail file to put discarded messages. It is recommended to specify the full path of the directory chosen for the mailer's working directory, where read permissions have been ensured (see previous step). A '-' preceding the name causes the mailer to truncate the file on startup. Once any troubleshooting phase for the mailer is

document.doc, Created by Mochamad Isa, Page 8 of 13

complete, it is a good idea to truncate the discard file on startup. Example: DISCARD=/home/wfmailer/work/discard PROCESS= The name or full path name of the mail file to put processed messages. It is recommended to specify the full path the directory chosen for the mailer's working directory, where read permissions have been ensured (see previous step). A '-' preceding the name causes the mailer to truncate the file at startup. Once any troubleshooting phase for the mailer is complete, it is a good idea to truncate the processed file on startup. Example: PROCESS=/home/wfmailer/work/processed UNPROCESS= The name or full path name of the mail file to put incoming, unprocessed messages. It is recommended to specify the full path the directory chosen for the mailer's working directory, where read permissions have been ensured (see previous step). A '-' preceding the name causes the mailer to truncate the file on startup (not recommended). Example: UNPROCESS=/home/wfmailer/work/unprocessed TAGFILE= specifies the name or full path name of the file that controls how the mailer will update the status of notifications with a valid NID that contain specific text strings. Common entries for the tagfile would be a standard text string found in bounced or returned messages and auto-reply messages such as those sent by vacation daemons and mass mailing lists. It is recommended to specify the full path of the directory where this file is stored and ensure that the mailer has read permissions for the file. Example: a. Embedded: TAGFILE=$FND_TOP/resource/wfmail.tag b. Standalone: TAGFILE= <path>/res/wfmail.tag -- <path> is the full path to the workflow directory structure on this server 8. Start the mailer: Logged onto the UNIX server as wfmailer with the appropriate environment set, the mailer can now be started using the command: a. Embedded: $FND_TOP/bin/WFMAIL apps/<pwd>@dbname 0 Y $FND_TOP/resource/wfmail.cfg & b. Standalone: <path>/bin/wfmail.snd <oracle_user>/<pwd>@dbname -f <path>/res/wfmail.cfg & -- <path> is the full path to the workflow directory structure on this server 9. Helpful tips: a. Use the TEST_ADDRESS parameter in the mailer configuration file to have all e-mail sent to the same address during the testing phase. Don't forget to comment this parameter out once testing is complete. b. Use the DEBUG parameter in the mailer configuration file to instruct the mailer to output additional debugging information to the screen during testing. Don't forget to leave the console open from which the mailer was started so that the output can be viewed. For more difficult implementation issues, this information can be extremely helpful if pasted into an e-mail to Oracle Support.

document.doc, Created by Mochamad Isa, Page 9 of 13

c. To keep the mailer running after logging out of the wfmailer account, use the UNIX nohup parameter before the startup command for the mailer. Only use this after troubleshooting is complete, since this will suppress any output to the screen. Example: nohup $FND_TOP/bin/WFMAIL apps/<pwd>@dbname 0 Y \ $FND_TOP/resource/wfmail.cfg & d. It is recommended to set up a perpetual shell script that restarts the mailer if it shuts down due to failure. For users of standalone workflow a sample script, wfmail.csh, is supplied for the C shell. This sample is located in the bin subdirectory of the workflow directory structure on the server. 10. Sample configuration files: A sample for embedded workflow and standalone workflow. A. Sample embedded workflow mailer configuration file: # Example of Workfow Mailer Configuration File For Sendmail # Workflow Mailer Configuration File # All parameters are optional unless otherwise noted # Some have default values if left unspecified # Fill in all parameters according to site requirements # # System Configuration # # Database Login Information CONNECT=apps/apps@VIS # Mail Account: mail account to send and receive mail from (required) # CHANGE THIS! ACCOUNT=/var/mail/wfmailer # From: value of the from field in the header of mail message sent # by the Oracle Workflow Mailer FROM=Oracle Workflow, wfmailer@emborc05.us.oracle.com # Mailer Node name: name to identify this mailer (required) NODE=WFVIS # Send Notification Summary Only SUMMARYONLY=N # Idle time: time to wait between polling for new work (seconds) IDLE=30 # Shutdown request file: when this file is detected, the mailer exits SHUTDOWN=/home/wfmailer/shutdown # Fail command: os command to run when exiting with error # FAILCOMMAND=echo "Mailer has exited" # Debug mode: turns on extra debugging output DEBUG=Y # Test Address: routes outgoing mail to the indicated address (for testing) # TEST_ADDRESS= # # Send Configuration

document.doc, Created by Mochamad Isa, Page 10 of 13

# # Reply To email address: email address that responses should go to # REPLYTO= # HTML Web Agent path: (required for mailed html support) # CHANGE THIS! HTMLAGENT=http://emborc05.us.oracle.com:8100/VIS/plsql # HTML Attachment file: used a as the filename to when attachement is saved HTMLFILE=attach.html # HTML Attachment desc: description of attachement type HTMLDESC=HTML # HTML Attachment type: numeric attachment code (oracle office) HTMLTYPE=10003 # # Respond Configuration # # Discard Folder: folder in which unrecoginzed incoming mail is placed # (leading '-' truncates folder on startup) DISCARD=/home/wfmailer/discard # Processed folder: folder in which successfully processed mail is placed PROCESS=/home/wfmailer/processed # Unprocessed folder: folder in which mail awaiting processing is placed UNPROCESS=/home/wfmailer/unprocessed # Response Tag file: file for respsonse routing (optional) # CHANGE THIS! TAGFILE=$FND_TOP/resource/wfmail.tag B. Sample standalone workflow mailer configuration file: # Example of Workfow Mailer Configuration File For Sendmail # Workflow Mailer Configuration File # All parameters are optional unless otherwise noted # Some have default values if left unspecified # Fill in all parameters according to site requirements # # System Configuration # # Database Login Information CONNECT=wf/wf@wfdb # Mail Account: mail account to send and receive mail from (required) # CHANGE THIS! ACCOUNT=/var/mail/wfmailer # From: value of the from field in the header of mail message sent # by the Oracle Workflow Mailer FROM=Oracle Workflow, wfmailer@stdorc05.us.oracle.com # Mailer Node name: name to identify this mailer (required) NODE=WFDB

document.doc, Created by Mochamad Isa, Page 11 of 13

# Send Notification Summary Only SUMMARYONLY=N # Idle time: time to wait between polling for new work (seconds) IDLE=30 # Shutdown request file: when this file is detected, the mailer exits SHUTDOWN=/home/wfmailer/shutdown # Fail command: os command to run when exiting with error # FAILCOMMAND=echo "Mailer has exited" # Debug mode: turns on extra debugging output DEBUG=Y # Test Address: routes outgoing mail to the indicated address (for testing) # TEST_ADDRESS= # # Send Configuration # # Reply To email address: email address that responses should go to # REPLYTO= # HTML Web Agent path: (required for mailed html support) # CHANGE THIS! HTMLAGENT=http://stdorc05.us.oracle.com:7700/WFDB/plsql # HTML Attachment file: used a as the filename to when attachement is saved HTMLFILE=attach.html # HTML Attachment desc: description of attachement type HTMLDESC=HTML # HTML Attachment type: numeric attachment code (oracle office) HTMLTYPE=10003 # # Respond Configuration # # Discard Folder: folder in which unrecoginzed incoming mail is placed # (leading '-' truncates folder on startup) DISCARD=/home/wfmailer/discard # Processed folder: folder in which successfully processed mail is placed PROCESS=/home/wfmailer/processed # Unprocessed folder: folder in which mail awaiting processing is placed UNPROCESS=/home/wfmailer/unprocessed # Response Tag file: file for respsonse routing (optional) # CHANGE THIS! TAGFILE=$ORACLE_HOME/wf/res/wfmail.tag RELATED DOCUMENTS -----------------

document.doc, Created by Mochamad Isa, Page 12 of 13

Oracle Workflow 2.0.3 Guide (A56104) Oracle Workflow 2.5 Guide (A75397) Note:1011352.102 NOTIFICATION MAILER FILLS UP & CRASHES FROM APPLMGR ACCOUNT

document.doc, Created by Mochamad Isa, Page 13 of 13