"To Create a Configuration File for the Notification Mailer (Oracle Workflow Help)

Oracle Workflow Guide
Release 2.6.2
Part Number A95265-03


				Contents	Index	Glossary	Master Index	Feedback

To Create a Configuration File for the Notification Mailer

1. Oracle Workflow provides an example configuration file, called wfmail.cfg. If you are using the standalone version of Oracle Workflow, the file resides in your Oracle Workflow server directory structure, under the subdirectory res. For the version of Oracle Workflow embedded in Oracle Applications, the file resides in the resource subdirectory under $FND_TOP on your server. The file also resides on your PC in the <drive>:\<ORACLE_HOME>\wf\data subdirectory.

Note: If you are using the version of Oracle Workflow embedded in Oracle Applications and you have implemented Oracle Applications Manager, you can use Oracle Workflow Manager to configure and run the Notification Mailer. For more information, please refer to the Oracle Applications Manager online help.

2. The content of the configuration file is formatted as follows:

#Description

PARAMETER1=<value1>

#Description

PARAMETER2=<value2>

Any text preceded by # is not interpreted and can be used for including comments. List each parameter name on the left side of the equal sign (=) and specify a value for each parameter on the right.

3. The parameters are as follows:

CONNECT--(Required) The information to connect to the database account where the Oracle Workflow server is installed, using the format, username/password@connect_string (or alias).

Attention: The CONNECT parameter is not required if you submit the Notification Mailer as a concurrent program from the version of Oracle Workflow embedded in Oracle Applications. In this case, the concurrent manager passes in the database connection information for the Notification Mailer to use.

ACCOUNT--(Required) The information to connect to the mail account that the program uses to send notification messages. For MAPI-compliant mail programs, the account information is the mail account profile name and mail account password. For Sendmail, the account information would be the full file path of the mail spool file where incoming messages are stored, such as /var/mail/applmgr3. Note that this should correspond to the account from which you start the Notification Mailer, in this example, applmgr3.

Attention: If you want to start the Sendmail version of the Notification Mailer, you must also specify the full path of the Sendmail executable directory in your PATH environment variable.

Attention: If you are using the version of Oracle Workflow embedded in Oracle Applications, and want to start the Sendmail version of the Notification Mailer concurrent program, then the Account parameter must be set to the account from which you start the Concurrent Manager.

NODE--(Required) The node identifier name. The node name is included with the outgoing notification ID. The default name is wf.

If you have multiple workflow databases on one server, you must define a unique node name for each Notification Mailer configuration file to ensure that the Notification Mailer for each instance uses a different TMP file for processing. For example, if you already have a Notification Mailer on the server with the node name wf, you could assign the node name wf2 to the Notification Mailer for the next instance you set up.

Note: You can only run one Notification Mailer per instance, and each Notification Mailer must use a separate e-mail account to process responses.

FROM--The value that appears in the From: field of the message header when a notification message is delivered to a user. The default is Oracle Workflow.

Attention: The FROM parameter is only used to set the From: field value by the UNIX Sendmail version of the Notification Mailer. The MAPI-compliant version of the Notification Mailer uses the display value that is set up for the mail account specified in the ACCOUNT parameter.

SUMMARYONLY--(Required) Indicate whether this Notification Mailer processes only notifications assigned to users/roles with a notification preference of 'SUMMARY' or whether it only processes notifications for users/roles with a notification preference of 'MAILTEXT', 'MAILATTH', or 'MAILHTML'. Valid values are Y or N. The default is N. You should set up at least two Notification Mailers, one where SUMMARYONLY=Y and one where SUMMARYONLY=N if any of your workflow users or roles have a notification preference of 'MAILTEXT', 'MAILATTH', 'MAILHTML', or 'SUMMARY'. See: Setting Up Users and Roles from a Directory Repository: .

If you set SUMMARYONLY=Y, then the Notification Mailer will shut itself down after it polls the database and delivers any appropriate notification summaries. You must therefore schedule the Notification Mailer to run at the frequency you want notification summaries to be delivered. We recommend you run the summary Notification Mailer once a day, since the summary includes all open notifications. For Oracle Workflow running in the standalone environment, this would involve creating an operating system script, such as a cron job in UNIX, to schedule the Notification Mailer. For the version of Oracle Workflow embedded in Oracle Applications, this simply involves scheduling the Notification Mailer concurrent program in the Submit Request form.

DIRECT_RESPONSE--Specify N or n to send plain text notifications requiring a templated response to users with a notification preference of 'MAILTEXT' or 'MAILATTH'. Specify Y or y to send plain text notifications requiring a direct response to users with these preferences. The default is N.

For the templated response method, users must reply using a template of response prompts and enter their response values between the quotes following each prompt. For the direct response method, users must enter their response values directly as the first lines of a reply. See: Reviewing Notifications via Electronic Mail.

Attention: If you include the HTML_MAIL_TEMPLATE parameter in your configuration file, the Notification Mailer will ignore the DIRECT_RESPONSE parameter when sending messages to users with a notification preference of 'MAILATTH'. Instead, all users with this notification preference will receive the plain text message body defined for the Workflow Open Mail for Outlook Express template, which uses the templated response method. Consequently, if you do not need to use the Workflow Open Mail for Outlook Express template, you should comment out the HTML_MAIL_TEMPLATE parameter to let the DIRECT_RESPONSE parameter take effect.

AUTOCLOSE_FYI--Indicate whether this Notification Mailer automatically closes notifications that do not require a response, such as FYI (For Your Information) notifications, after sending the notifications by electronic mail. Valid values include Y or N. The default is Y.

If the value is N, all FYI notifications will remain open in the Notifications Worklist until users manually close these notifications.

ALLOW_FORWARDED_RESPONSE--Indicate whether to allow a user to respond to an e-mail notification that has been forwarded from another role. Valid values include Y or N. The default is Y.

If the value is N, the Notification Mailer will check if the "From:" e-mail address of the notification response exactly matches the e-mail address of the recorded recipient role (or the e-mail address of a user in that role). If the two e-mail addresses match exactly, meaning the notification was not forwarded or was forwarded according to a valid routing rule, the Notification Mailer treats the response as a valid response. If the two e-mail addresses do not match exactly, meaning the notification was simply forwarded using the e-mail Forward command, the Notification Mailer does not process the response and treats it as unsolicited mail.

If the value is Y, the Notification Mailer never checks the "From:" e-mail address of the notification response and always allows the response to be processed.

Warning: Note that there are limitations when you set ALLOW_FORWARDED_RESPONSE to N. For example, suppose a notification is sent to a distribution list mail alias that does not have a USER/ROLE relationship in the Oracle Workflow directory service. If any user from the distribution list responds to the notification, the Notification Mailer will always treat their notification response as unsolicited mail, because the "From:" e-mail address, which is an individual user's e-mail address, will never match the distribution list mail alias.

IDLE--The number of seconds to wait before checking for messages to send. The value must be an integer greater than or equal to zero. The default is 30.

LOG--The name of a log file to record activity. A valid value would be a filename. This parameter is valid only for the standalone version of the Notification Mailer. For the concurrent program version of the Notification Mailer, the activity output goes to the concurrent manager log file.

SHUTDOWN--The name of a file that cues the Notification Mailer to shut down. This lets you safely shut down the Notification Mailer without killing the process. The Notification Mailer always looks for the shutdown file in its current working directory before looking for notifications to process. If the file exists, then the Notification Mailer shuts down. You must remove the shutdown file to restart the Notification Mailer again. The default filename is shutdown.

For the standalone version of Oracle Workflow, the Notification Mailer's current working directory is the directory from which you start the Notification Mailer. For the version of Oracle Workflow embedded in Oracle Applications, the current working directory is the $APPLCSF/$APPLLOG directory. If you have not set the $APPLCSF environment variable, then place the shutdown file in the $FND_TOP/$APPLLOG directory.

FAILCOMMAND--The command to run if the Notification Mailer encounters a fatal error.

DEBUG--Indicate whether to print debugging information in the log. Valid values include Y or N. The default is N.

TEST_ADDRESS--Indicate a test e-mail address to direct all outgoing e-mail notifications. The test address overrides each recipient's e-mail address so that you can test a workflow process without having to change each recipient's e-mail address to access the test notifications.

REPLYTO--(Required) A default e-mail address to reply to, if the e-mail account that processes responses is different from the e-mail account that sends outgoing notifications.

Attention: The REPLYTO parameter is only used to set the reply-to address by the UNIX Sendmail version of the Notification Mailer. The MAPI-compliant version of the Notification Mailer uses the display value that is set up for the mail account specified in the ACCOUNT parameter.

HTMLAGENT--The base URL that identifies the HTML Web Agent that handles HTML notification responses. This URL is required to support e-mail notifications with HTML attachments. The default URL is derived from the Workflow Web Agent specified in the Global Preferences web page, but you can override this default by entering a different value for this parameter. See: Setting Global User Preferences.

DISCARD--The name of the mail folder or full path name of the mail file to put discarded messages. A '-' preceding the name causes the Notification Mailer to truncate the folder or file on startup. The default is -discard.

Note: For the UNIX Sendmail version of the Notification Mailer, the DISCARD value must always be the full path name of a mail file.

PROCESS--The name of the mail folder or full path name of the mail file to put processed notification messages. A '-' preceding the name causes the Notification Mailer to truncate the folder or file on startup. The default is processed.

Note: For the UNIX Sendmail version of the Notification Mailer, the PROCESS value must always be the full path name of a mail file.

UNPROCESS--The name of the mail folder or the full path name of the mail file to put unprocessed notification messages. A '-' preceding the name causes the Notification Mailer to truncate the folder or file on startup. The default is unprocessed.

Note: For the UNIX Sendmail version of the Notification Mailer, the UNPROCESS value must always be the full path name of a mail file.

TAGFILE--The full path and name of a tag file. The tag file lists strings of text found in unusual messages and the status you want to assign to a message response if it contains any of those strings. Unusual messages include bounced or returned messages, auto-reply messages such as those sent by vacation daemons, mass mailing lists, and so on. Since different mail systems vary in how they identify bounced, undeliverable, or otherwise invalid messages, you can use a tag file to specify how your mail system identifies those stray messages and how you want the Notification Mailer to handle those messages should it come across them.

Attention: Only a message response that contains a notification ID is checked by the tag file. If the Notification Mailer receives a message response that does not contain a notification ID, it moves the message response to the discard folder and sends a 'Warning' message to the sender that it received unsolicited mail. See: Workflow Warning Mail Message.

The format used in the tag file is

  Status "Matching string"

where Status can be the value: ERROR, IGNORE, or UNAVAIL and "Matching string" is the text to look for in the From: line, Subject: line, or body of the message. The Notification Mailer handles a message assigned one of these status values as follows:

IGNORE--moves the message to the discard folder and continues waiting for a valid reply to the open notification. The notification's status is still OPEN and its mail status is still SENT.

ERROR--moves the message to the discard folder and initiates an error process, if one is defined. The notification's status is still OPEN, but its mail status and activity status are updated to ERROR. Ideally, the workflow administrator corrects the problem and resends the notification by updating its mail status to MAIL.

UNAVAIL (or any other user defined tag)--moves the message to the discard folder and continues waiting for a reply to the notification since the notification's status is still OPEN, but its mail status is updated to UNAVAIL. This status is purely informative, as no further processing occurs with this notification.

The Notification Mailer can also assign an INVALID status to a message response, if the returned response value is not a valid value in the assigned lookup (result) type. In this case, it moves the message to the discard folder, and sends an 'Invalid' message but does not alter the notification's status or mail status, so that it continues to wait for a valid reply. See: Workflow Invalid Mail Message.

Attention: It is important that you uniquely identify bounced messages and auto-replies from normal responses in the tag file. If you do not identify bounced and auto-reply messages, the Notification Mailer can mistake these as invalid responses, send an 'Invalid' message and continue to wait for a reply. In both cases a perpetual loop would occur where the Notification Mailer keeps sending out an 'Invalid' message and the 'Invalid' message bounces back or is auto-replied.

As an example, if you want to mark all message responses that contain the string "-- Unsent message follows --" in the subject or body of the message as an error, you can include the following line in your tag file:

  ERROR "-- Unsent message follows --"

Attention: If a message response matches more than one string in the tag file, it gets tagged with the status of the first string it matches in the file. That is, the Notification Mailer performs a top to bottom comparison against the tag file. Due to this behavior, you should prioritize your strings listing the ERROR tags first, followed by the UNAVAIL and then IGNORE tags.

Oracle Workflow provides an example tag file called wfmail.tag. For the standalone version of Oracle Workflow, the file resides in your Oracle Workflow server directory structure in the subdirectory res. For the version of Oracle Workflow embedded in Oracle Applications, the file resides on your server in the resource subdirectory under $FND_TOP.

RESET_FAILED--Indicate whether this Notification Mailer should reset all notifications with a mail status of FAILED to a mail status of MAIL when the Notification Mailer is started. Valid values include Y or N. The default is N.

If the value is Y, the Notification Mailer will reset all FAILED notifications to a mail status of MAIL on startup and then attempt to process these notifications as usual.

RESET_NLS--Indicate whether the Notification Mailer should convert the NLS codeset for a notification message according to the notification recipient's preferences before composing the message. Valid values include Y or N. The default is N.

If the value is Y, the Notification Mailer will convert the message to the codeset listed in the WF_LANGUAGES table for the language and territory specified in the recipient's Workflow user preferences. If no preferred territory is specified, the Notification Mailer will use the codeset associated with the first entry it encounters for the user's preferred language. If neither a language nor a territory is specified in the user preferences, the Notification Mailer will use the codeset seeded in WF_LANGUAGES for the language AMERICAN and territory AMERICA. See: Setting User Preferences.

HTML_MAIL_TEMPLATE--Specify OPEN_MAIL_OUTLOOK to use the Workflow Open Mail for Outlook Express message as the template for e-mail notifications that require a response, for users with a notification preference of 'MAILHTML 'or 'MAILATTH'. You can select this message template if you use an e-mail application such as Microsoft Outlook Express as your e-mail client, in order to include a link to the Notification Details web page which lets users respond to the notification there. This template is provided to accommodate e-mail applications that cannot process the response links included in the Workflow Open Mail (Templated) and Workflow Open Mail (Direct) templates.

If you want to use the normal Workflow Open Mail (Templated) and Workflow Open Mail (Direct) templates, you can comment out this parameter in your configuration file and let the Notification Mailer use these templates by default.

Attention: If you include the HTML_MAIL_TEMPLATE parameter in your configuration file, the Notification Mailer will ignore the DIRECT_RESPONSE parameter when sending messages to users with a notification preference of 'MAILATTH'. Instead, all users with this notification preference will receive the plain text message body defined for the Workflow Open Mail for Outlook Express template, which uses the templated response method. Consequently, if you do not need to use the Workflow Open Mail for Outlook Express template, you should comment out the HTML_MAIL_TEMPLATE parameter to let the DIRECT_RESPONSE parameter take effect.

Note: The HTML_MAIL_TEMPLATE parameter does not apply to users with a notification preference of 'MAILTEXT'.

SEND_ACCESS_KEY--Specify Y to include an access key in the Notification Detail Link attachment that is sent with HTML e-mail notifications and with plain text e-mail notifications with HTML attachments. The access key allows users to access the Notification Details web page directly by clicking the Notification Detail Link, whether they are currently logged in or not. However, if users are not already logged in, they cannot access any other notifications except the notification with which the attachment was sent. Specify N to exclude the access key from the Notification Detail Link. When users click the link without the access key, they are prompted to log in, if they have not already done so, before they can access the Notification Details web page. The default is Y.

See: Implementing the Notification Mailer

See: Response Processing

See: Modifying Your Message Templates

See: Defining Rules for Automatic Notification Processing


	Previous	Next		Contents	Index	Glossary