This chapter describes the APIs for the Oracle Workflow Notification System. The APIs include PL/SQL and Java functions and procedures that you can use to access the Notification System.
This chapter covers the following topics:
Oracle Workflow communicates with users by sending notifications. Notifications contain messages that may request users to take some type of action and/or provide users with information. You define the notification activity and the notification message that the notification activity sends in the Workflow Builder. The messages may have optional attributes that can specify additional resources and request responses.
Users can query their notifications online using the Notifications Web page in an HTML browser. Users can also receive notifications in their e-mail applications. E-mail notifications can contain HTML content or include other documents as optional attachments. The Notification System delivers the messages and processes the incoming responses.
Related Topics
Notification Document Type Definition
Notification Mailer Utility API
A notification activity in a workflow process consists of a design-time message and a list of message attributes. In addition, there may be a number of runtime named values called item type attributes from which the message attributes draw their values.
The Workflow Engine moves through the workflow process, evaluating each activity in turn. Once it encounters a notification activity, the engine makes a call to the Notification System Send() or SendGroup() API to send the notification.
The Send() API or the SendGroup() API is called by the Workflow Engine when it encounters a notification activity. These APIs do the following:
Check that the performer role of the notification activity is valid.
Identify the notification preference for of the performer role.
Look up the message attributes for the message.
If a message attribute is of source SEND, the Send() or SendGroup() API retrieves its value from the item type attribute that the message attribute references. If the procedure cannot find an item type attribute, it uses the default value of the message attribute, if available. The Subject and Body of the message may include message attributes of source SEND, which the Send() or SendGroup() API token replaces with each attribute's current value when creating the notification.
If a message includes a message attribute of source RESPOND, the Send() or SendGroup() API checks to see if it has a default value assigned to it. The procedure then uses these RESPOND attributes to create the default response section of the notification.
'Construct' the notification content by inserting relevant information into the Workflow notification tables.
Update the notification activity's status to 'NOTIFIED' if a response is required or to 'COMPLETE' if no response is required.
Note: If a notification activity sends a message that is for the performer's information only (FYI), where there are no RESPOND message attributes associated with it, the notification activity gets marked as complete as soon as the Notification System delivers the message.
Note: In the case of a voting activity, the status is updated to 'WAITING' instead of 'NOTIFIED'. See: Special Handling of Voting Activities.
Raise the oracle.apps.wf.notification.send event. When this event is processed, a notification mailer generates an e-mail version of the notification if the performer role of a notification has a notification preference of MAILTEXT, MAILHTML, MAILHTM2, or MAILATTH, and sends the e-mail to the performer. For roles with a notification preference of SUMMARY or SUMHTML, a summary e-mail is sent when the oracle.apps.wf.notification.summary.send event is raised. See: Implementing Notification Mailers, Oracle Workflow Administrator's Guide.
Note: The notification mailer does not send e-mail notifications to roles with a notification preference of QUERY or DISABLED. Users with a notification preference of QUERY only access their notifications through the Worklist Web page. Users whose notification preference has been set to DISABLED must correct their e-mail address and reset their notification preference before a notification mailer can send them e-mail notifications.
Users who view their notifications from the Worklist Web page, regardless of their notification preferences, are simply querying the Workflow notification tables from this interface.
A notification recipient can perform the following actions with the notification:
Respond to the notification or close the notification if it does not require a response. See: Processing a Notification Response.
Forward the notification to another role. See: Forwarding a Notification.
Transfer ownership of the notification to another role. See: Transferring a Notification.
Request more information about the notification from another role, or respond to such a request with more information. See: Requesting More Information About a Notification.
Ignore the notification and let it time out. See: Processing a Timed Out Notification.
Note: You can use the WF: Notification Reassign Mode profile option to determine whether users can reassign notifications by forwarding (also known as delegating) the notifications, transferring the notifications, or both. See: Setting the WF: Notification Reassign Mode, Oracle Workflow Administrator's Guide.
After a recipient responds, the Notification Details Web page or a notification mailer assigns the response values to the notification response attributes and calls the notification Respond() API. The Respond() API first calls a notification callback function to execute the notification activity's post-notification function (if it has one) in VALIDATE mode. In this mode, the post-notification function can validate the response values before accepting and recording the response. For example, if the notification requires an electronic signature, the post-notification function can run in VALIDATE mode to verify the response values and inform the user of any errors before requiring the user to enter a signature. If the post-notification function raises an exception, the response is aborted. See: Post-notification Functions.
Next, Respond() calls the notification callback function to execute the post-notification function in RESPOND mode. The post-notification function may interpret the response and perform tightly-coupled post-response processing. Again, if the post-notification function raises an exception, the response is aborted.
If no exception is raised, Respond() marks the notification as closed and then calls the notification callback function again in SET mode to update the corresponding item attributes with the RESPOND notification attributes values. If the notification message prompts for a response that is specified in the Result tab of the message's property page, that response value is also set as the result of the notification activity.
Finally, Respond() calls WF_ENGINE.CompleteActivity() to inform the engine that the notification activity is complete so it can transition to the next qualified activity.
If a recipient forwards a notification to another role, the Notification Details Web page calls the Notification System's Forward() API.
Note: The Notification System is not able to track notifications that are forwarded via e-mail. It records only the eventual responder's e-mail address and any Respond message attributes values included in the response.
The Forward() API validates the role, then calls a notification callback function to execute the notification activity's post-notification function (if it has one) in FORWARD mode. As an example, the post-notification function may verify whether the role that the notification is being forwarded to has appropriate authority to view and respond to the notification. If it doesn't, the post-notification function may return an error and prevent the Forward operation from proceeding. See: Post-notification Functions.
Forward() then forwards the notification to the new role, along with any appended comments.
Note: Forward() does not update the owner or original recipient of the notification.
If a recipient transfers the ownership of a notification to another role, the Notification Details Web page calls the Notification System's Transfer() API.
Note: Recipients who view notifications from an e-mail application cannot transfer notifications. To transfer a notification, the recipient must use the Notifications Web page.
The Transfer() API validates the role, then calls a notification callback function to execute the notification activity's post-notification function (if it has one) in TRANSFER mode. As an example, the post-notification function may verify whether the role that the notification is being transferred to has appropriate authority. If it doesn't, the post-notification function may return an error and prevent the Transfer operation from proceeding. See: Post-notification Functions.
Transfer() then assigns ownership of the notification to the new role, passing along any appended comments. Note that a transfer is also recorded in the comments of the notification.
If a recipient requests more information about the notification from another role, the Notification Details Web page calls the Notification System's UpdateInfo() API, or a notification mailer calls the Notification System's UpdateInfo2() API.
The UpdateInfo() or UpdateInfo2() API calls a notification callback function to execute the notification activity's post-notification function (if it has one) in QUESTION mode. As an example, the post-notification function may verify that the request is directed to a role that has appropriate authority to view the notification. If it doesn't, the post-notification function may return an error and prevent the request for more information from being sent. See: Post-notification Functions.
If no error is returned, the API then sends the request for more information to the designated role. Note that a request for information is also recorded in the comments of the notification.
If the recipient of a request for more information responds with answering information, the Notification Details Web page calls the Notification System's UpdateInfo() API if the responder is logged in individually or the UpdateInfoGuest() API if the responder is logged in as the GUEST user, or a notification mailer calls the Notification System's UpdateInfo2() API.
The UpdateInfo(),UpdateInfoGuest(), or UpdateInfo2() API calls a notification callback function to execute the notification activity's post-notification function (if it has one) in ANSWER mode. As an example, the post-notification function may validate the answering information. If such validation fails, the post-notification function may return an error and prevent the answer from being sent. See: Post-notification Functions.
If no error is returned, the API then sends the answering information back to the recipient role of the original notification. Note that an answer to a request for information is also recorded in the comments of the notification.
Timed out notification or subprocess activities are initially detected by the background engine. Background engines set up to handle timed out activities periodically check for activities that have time out values specified. If an activity does have a time out value, and the current date and time exceeds that time out value, the background engine marks that activity's status as 'TIMEOUT' and calls the Workflow Engine. The Workflow Engine then resumes by trying to execute the activity to which the <Timeout> transition points.
A voting activity by definition is a notification activity that:
Has its roles expanded, so that an individual copy of the notification message is sent to each member of the Performer role.
Has a message with a specified Result, that requires recipients to respond from a list of values.
Has a post-notification function associated with it that contains logic in the RUN mode to process the polled responses from the Performer members to generate a single response that the Workflow Engine interprets as the result of the notification activity. See: Voting Activity, Oracle Workflow Developer's Guide.
Once the Notification System sends the notification for a voting activity, it marks the voting activity's status as 'NOTIFIED'. The voting activity's status is updated to 'WAITING' as soon as some responses are received, but not enough responses are received to satisfy the voting criteria.
The individual role members that each receive a copy of the notification message can then respond or forward the notification, or request or respond with more information, if they use e-mail or the Worklist Web pages to access the notification. They can also transfer the notification if they use the Worklist Web pages.
The notification user interface calls the appropriate Respond(), Forward(), Transfer(), UpdateInfo(), UpdateInfo2(), or UpdateInfoGuest() API, depending on the action that the performer takes. Each API in turn calls the notification callback function to execute the post-notification function in VALIDATE and RESPOND, FORWARD, TRANSFER, QUESTION, or ANSWER mode, as appropriate. When the Notification System finishes executing the post-notification function in FORWARD or TRANSFER mode, it carries out the Forward or Transfer operation, respectively. When the Notification System finishes executing the post-notification function in QUESTION or ANSWER mode, it sends the request for more information to the designated role or the answer to the requesting role, respectively.
When the Notification System completes execution of the post-notification function in RESPOND mode, the Workflow Engine then runs the post-notification function again in RUN mode. It calls the function in RUN mode after all responses are received to execute the vote tallying logic.
Also if the voting activity is reset to be reexecuted as part of a loop, or if it times out, the Workflow Engine runs the post-notification function in CANCEL or TIMEOUT mode, respectively. The logic for TIMEOUT mode in a voting activity's post-notification function should identify how to tally the votes received up until the timeout.
The following document type definition (DTD) describes the required structure for the XML document that represents a notification. The Notification System uses this structure to communicate messages to a notification mailer. The following table shows the level, tag name, and description for each element in the DTD.
| Level | Tag | Description |
|---|---|---|
| 1 | <NOTIFICATIONGROUP maxcount=""> | The <NOTIFICATIONGROUP> tag is the opening tag for the XML structure. The maxcount attribute defines the maximum number of <NOTIFICATION> tags to expect. This number may not be reached, but will not be exceeded within the <NOTIFICATIONGROUP> tag. |
| 2 | <NOTIFICATION nid="" language="" territory="" codeset="" nlsDateFormat="" nlsDateLanguage="" nlsNumericCharacters="" nlsSort="" priority="" accesskey="" node="" item_type="" message_name="" nidstr="" full-document="" reason="" callback=""> | The <NOTIFICATION> element defines a single message entity. A <NOTIFICATION> is a repeating structure within <NOTIFICATIONGROUP>, the number of which will not exceed the specified maxcount value. Each <NOTIFICATION> element for a notification sent by the Notification System is identified by its unique nid attribute, which is the notification ID. For messages received from an external source, such as responses from users, the notification ID should be zero (0). The language and territory values represent the language and territory preferences of the notification recipient. The codeset attribute is the preferred codeset associated with the language in the WF_LANGUAGES table. The value of the codeset attribute must be in the Oracle Database codeset notation. The nlsDateFormat, nlsDateLanguage, nlsNumericCharacters and nlsSort attributes represent the NLS date format, date language, numeric characters, and sort preferences used to format the notification. If the notification recipient is an Oracle E-Business Suite user marked with an originating system of FND_USR or PER, then Oracle Workflow takes the values for these attributes from the notification recipient's ICX: Date format mask, ICX: Date language, ICX: Numeric characters, and ICX: NLS Sort profile option settings, respectively. For notification recipients who are not Oracle E-Business Suite users, such as ad hoc users or roles, Oracle Workflow takes the values for these attributes from the site level settings for these profile options or from the NLS parameters of the database session. Note: When the Workflow Notification Mailer sends Oracle Alert e-mail messages, it takes the values for these attributes from the database session variables. The priority attribute is the relative priority for the message compared to other messages. A priority of 1 through 33 is high, 34 through 66 is normal, and 67 through 99 is low. The accesskey and node attributes store information for inbound response messages. These attributes are used together with the nid attribute to validate the response. The item_type attribute is the internal name of the item type that owns the notification. The message_name attribute is the internal message name for the notification within that item type. These two attributes are provided for reference only. The nidstr attribute is for internal use only. The notification mailer uses this attribute to send the notification ID in a custom header called X-oracle-workflow-nid. This header is used during processing of inbound messages to help identify bounced messages in cases where the original message may be included, but the notification ID is encoded in the inbound message body and cannot be recognized there by the notification mailer. The full-document attribute indicates whether the generated XML document is complete (Y) or incomplete (N). If the document is incomplete, the reason attribute describes why. The callback attribute specifies an optional business event to be raised as a callback to the calling application when the notification mailer finishes dispatching the e-mail message. |
| 3 | <HEADER> | <The HEADER> element defines the envelope information for the message, which contains the details of the recipients, where the message was sent from, and the subject for the message. |
| 4 | <RECIPIENTLIST> | The <RECIPIENTLIST> tag enables the message to be sent to more than one recipient. The first recipient in the list is treated as the primary recipient. Subsequent recipients will receive copies of the message. All recipients in the list will receive the same e-mail in the language and formatting of the primary recipient's preferences. |
| 5 | <RECIPIENT name="" type=""> | The <RECIPIENT> tag defines a recipient for the message. A <RECIPIENT> is a repeating structure within the <RECIPIENTLIST>. Each <RECIPIENT> is identified by its name attribute, which is the internal name of the recipient role. The type attribute contains the copy type for the recipient. Valid values for this attribute are to, cc, and bcc. If the type attribute is not provided, then the recipient is treated as having a copy type of to. |
| 6 | <NAME> </NAME> | The <NAME> tag defines the display name of the recipient. |
| 6 | <ADDRESS> </ADDRESS> | The <ADDRESS> tag defines the e-mail address of the recipient. |
| 5 | </RECIPIENT> | This tag marks the end of a <RECIPIENT> element. |
| 4 | </RECIPIENTLIST> | This tag marks the end of the <RECIPIENTLIST> element. |
| 4 | <FROM> | The <FROM> tag shows the sender of the message. For outbound notifications, the from role can be set using the #FROM_ROLE message attribute. The from role is also set to the role who reassigned the notification if this notification has been reassigned, to the requesting role if this notification is a request for more information, or to the responding role if this notification is a response to a request for more information. If no from role is specified for the notification, this attribute is set to the value of the notification mailer's From parameter. For inbound notifications, this information is determined by the From address of the incoming e-mail message. |
| 5 | <NAME> </NAME> | The <NAME> tag defines the display name of the sender. For Oracle Alert e-mail messages, the notification mailer either uses the sender display name provided by Oracle Alert, or, if no name is provided, the notification mailer uses the value of its own From parameter. |
| 5 | <ADDRESS> </ADDRESS> | The <ADDRESS> tag defines the e-mail address of the sender. For Oracle Alert e-mail messages, the notification mailer either uses the sender e-mail address provided by Oracle Alert, or, if no address is provided, the notification mailer uses the value of its own Reply-to Address parameter. |
| 4 | </FROM> | This tag marks the end of the <FROM> element. |
| 4 | <SUBJECT> </SUBJECT> | The <SUBJECT> element holds the subject line of the notification. |
| 3 | </HEADER> | This tag marks the end of the <HEADER> element. |
| 3 | <CONTENT content-type=""> | The <CONTENT> element holds the contents of the notification message. The <CONTENT> element contains one or more <BODYPART> elements. The content-type attribute contains the valid MIME type definition for the content within the <CONTENT> element. Valid values for the content-type attribute include multipart/mixed, text/plain and text/html. The first <BODYPART> element within the <CONTENT> tag is treated as the main content of the message, and will be the first component within a multipart/* message structure. Subsequent <BODYPART> elements are treated as attachments to the message or inline body parts (body parts that form MIME objects with the first body part). |
| 4 | <BODYPART content-type=""> | The <BODYPART> tag represents a MIME component of the final message. This element contains a <MESSAGE> tag and optionally one or more <RESOURCE> tags. If the <RESOURCE> tags are implemented, then the content-type attribute must be defined for the <BODYPART> tag to explain the relationship of the <RESOURCE> elements to the <MESSAGE> element. The only valid value for this content-type attribute is multipart/related. The first <BODYPART> element is treated as the main content of the message. This content will be either text/* or multipart/related. The subsequent <BODYPART> elements contain any attachments as required by the notification message definition and the recipient's notification preference. Attachments may include an HTML-formatted version of the notification, a Notification Detail Link, and any message attributes for which the Attach Content option is selected. For inbound messages, the <BODYPART> element contains the message and any attachments where appropriate. |
| 5 | <MESSAGE content-type="" content-transfer-encoding="" content-disposition="" src=""> | The content-type attribute contains the media type definition for the <MESSAGE> element. Valid values for this content-type attribute are text/plain, text/html, multipart/mixed, or multipart/related. The content-transfer-encoding attribute is an optional attribute to qualify further the encoding of the text/plain or text/html content. The content-disposition attribute specifies that the component is an attachment. The src attribute can optionally be defined if the content for the <MESSAGE> element is not readily available when the notification XML document is generated. The value of the src attribute must be a URL from which the content can be obtained during final e-mail message rendering. |
| - | <![CDATA[ ]]> | This structure holds the raw message content. If the content of a <RESOURCE> element should be merged into the content of the <MESSAGE> element, then the message content must include a token prefixed by an ampersand (&) to mark the position at which the resource content should appear. The token must match the token attribute value of the corresponding <RESOURCE> element. |
| 5 | </MESSAGE> | This tag marks the end of a <MESSAGE> element. |
| 5 | <RESOURCE content-type="" content-transfer-encoding="" content-disposition="" content-id="" src="" language="" territory="" page-type="" token=""> | The content-type attribute contains the media type definition for the <RESOURCE> element. This value should be a media-type/subtype definition. The content-transfer-encoding attribute is an optional attribute to qualify further the encoding of the text/plain or text/html content. The content-disposition attribute specifies that the component is an attachment. The content-id attribute holds the unique content identifier for the component. This identifier is referenced within the content of the <MESSAGE> element. The src attribute can optionally be defined if the content for the <RESOURCE> element is not readily available when the notification XML document is generated. The value of the src attribute must be a URL from which the content can be obtained during final e-mail message rendering. If the src attribute is defined to refer to Oracle Application Framework content, then the language and territory attributes hold the language and territory preferences of the recipient. Also, if the src attribute refers to Oracle Application Framework content, then the page-type attribute is set to the value fwk to identify Oracle Application Framework as the source of the content. The page-type attribute should be defined only if the src attribute is defined correspondingly. The token attribute holds the token value used to mark the position at which the content of the <RESOURCE> element will be merged into the content of the <MESSAGE> element. Within the <MESSAGE> element, the token value is prefixed by an ampersand (&). |
| - | <![CDATA[ ]]> | This structure holds the content for the <RESOURCE> element. |
| 5 | </RESOURCE> | This tag marks the end of a <RESOURCE> element. |
| 4 | </BODYPART> | This tag marks the end of a <BODYPART> element. |
| 3 | </CONTENT> | This tag marks the end of the <CONTENT> element. |
| 3 | <RESPONSE> | The <RESPONSE> tag is implemented only for inbound notifications and Oracle Alert e-mail responses. It is not part of the specification for outbound notifications. The <RESPONSE> element contains one or more <ATTRIBUTE> elements, which hold the response values found in the incoming e-mail message. There should be an <ATTRIBUTE> tag for each response attribute associated with the notification. However, only the RESULT message attribute is mandatory. The other respond attributes are optional. If no value is specified for a respond attribute, Oracle Workflow uses the default value defined for the message attribute. For Oracle Alert e-mail responses, the notification mailer parses the e-mail content for the ALR string specifier and then takes the response values directly from the appropriate lines within the e-mail. |
| 4 | <ATTRIBUTE name="" type="" format=""> | The <ATTRIBUTE> tag holds the response value found in the incoming e-mail message for a particular response attribute. An <ATTRIBUTE> is a repeating structure within the <RESPONSE>. The name attribute for this element is the internal name of the response attribute. The type attribute of this element is the Oracle Workflow data type of the reponse attribute, which can be either TEXT, NUMBER, DATE, DOCUMENT, or LOOKUP. The format attribute for this element contains the format string for the response attribute. For response attributes of type LOOKUP, the format is used to identify the lookup type code according to the value of the name attribute. For other data types, the format attribute is not used. |
| - | <![CDATA ]]> | This structure holds the response information to be assigned to the attribute. |
| 4 | </ATTRIBUTE> | This tag marks the end of an <ATTRIBUTE> element. |
| 3 | </RESPONSE> | This tag marks the end of a <RESPONSE> element. |
| 2 | </NOTIFICATION> | This tag marks the end of a <NOTIFICATION> element. |
| 1 | </NOTIFICATIONGROUP> | This tag marks the end of the <NOTIFICATIONGROUP> element. |
The following APIs can be called by a notification agent to manage notifications for a notification activity. The APIs are stored in the PL./SQL package called WF_NOTIFICATION.
Many of these notification APIs also have corresponding Java methods that you can call from any Java program to integrate with Oracle Workflow. The following list indicates whether the notification APIs are available as PL/SQL functions/procedures, as Java methods, or both. See: Oracle Workflow Java Interface.
Note: Java is case-sensitive and all Java method names begin with a lower case letter to follow Java naming conventions.
Note: The WF_NOTIFICATION.SubstituteSpecialChars() API from earlier versions of Oracle Workflow is replaced by the WF_CORE.SubstituteSpecialChars() API. The current version of Oracle Workflow still recognizes the WF_NOTIFICATION.SubstituteSpecialChars() API for backward compatibility, but moving forward, you should only use the new WF_CORE.SubstituteSpecialChars() API where appropriate.
The Notification System raises business events when a notification is sent, closed, canceled, or reassigned, or when a user responds to a notification, requests more information about a notification, or responds to a request with answering information. Although Oracle Workflow does not include any predefined subscriptions to some of these events, you can optionally define your own subscriptions to these events if you want to perform custom processing when they occur. See: Notification Events, Oracle Workflow Developer's Guide and To Create or Update an Event Subscription, Oracle Workflow Developer's Guide.
function SEND (role in varchar2, msg_type in varchar2, msg_name in varchar2, due_date in date default null, callback in varchar2 default null, context in varchar2 default null, send_comment in varchar2 default null priority in number default null) return number;
public static BigDecimal send (WFContext wCtx, String role, String messageType, String messageName, String dueDate, String callback, String context, string sendComment, BigDecimal priority)
This function sends the specified message to a role, returning a notification ID if successful. The notification ID must be used in all future references to the notification.
If your message has message attributes, the procedure looks up the values of the attributes from the message attribute table or it can use an optionally supplied callback interface function to get the value from the item type attributes table. A callback function can also be used when a notification is responded to.
Note: If you are using the Oracle Workflow Notification System and its e-mail-based or Web-based notification client, the Send() API implicitly calls the WF_ENGINE.CB callback function. If you are using your own custom notification system that does not call the Workflow Engine, then you must define your own callback function following a standard format and specify its name for the callback argument. See: Custom Callback Function.
If any message attributes are mapped by worklist flexfields rules, Send() stores denormalized values for those attributes in the designated worklist flexfields columns. See: Defining Specialized Worklist Views with Worklist Flexfields, Oracle Workflow Administrator's Guide.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| role | The role name assigned as the performer of the notification activity. |
| msg_type or messageType | The item type associated with the message. |
| msg_name or messageName | The message internal name. |
| due_date or dueDate | The date that a response is required. This optional due date is only for the recipient's information; it has no effect on processing. |
| callback | The callback function name used for communication of SEND and RESPOND source message attributes. |
| context | Context information passed to the callback function. |
| send_comment or sendComment | A comment presented with the message. |
| priority | The priority of the message, as derived from the #PRIORITY notification activity attribute. If #PRIORITY does not exist or if the value is null, the Workflow Engine uses the default priority of the message. |
A default callback function can be called at various points by the actions of the WF_NOTIFICATION APIs. You may provide your own custom callback function, but it must follow standard specifications.
If you do not need to handle attributes of type event through your callback function, the procedure must use the following standard API:
procedure <name in callback argument> (command in varchar2, context in varchar2, attr_name in varchar2, attr_type in varchar2, text_value in out varchar2, number_value in out number, date_value in out date);
If the callback function does need to handle attributes of type event, you can overload the procedure name with a second implementation that includes an additional argument for the event value. In this case you should also retain the original implementation for backward compatibility. However, it is recommended that you do not overload the procedure unless you have a requirement to handle event attributes.
The implementation of the procedure for event values must use the following standard API:
procedure <name in callback argument> (command in varchar2, context in varchar2, attr_name in varchar2, attr_type in varchar2, text_value in out varchar2, number_value in out number, date_value in out date event_value in out nocopy wf_event_t);
For ease of maintenance, you can define the procedure that does not include the event_value argument to call the procedure that does include that argument, so that you only need to maintain one version of your code. The following example shows one way to implement such a call:
procedure your_callback
(command in varchar2,
context in varchar2,
attr_name in varchar2,
attr_type in varchar2,
text_value in out varchar2,
number_value in out number,
date_value in out date)
is
event_value wf_event_t;
begin
your_package.your_callback(command, context, attr_name,
attr_type, text_value,
number_value, date_value,
event_value);
exception
when others then
Wf_Core.Context('your_package', 'your_callback',
command, context, attr_name, attr_type,
':'||text_value||':'||to_char(number_value)
||':'||to_char(date_value)||':');
raise;
end your_callback;
| Variable | Description |
|---|---|
| command | Specify GET, SET, COMPLETE, ERROR, TESTCTX, FORWARD, TRANSFER, QUESTION, ANSWER, VALIDATE, or RESPOND as the action requested. Use GET to get the value of an attribute, SET to set the value of an attribute, COMPLETE to indicate that the response is complete, ERROR to set the associated notification activity to a status of 'ERROR', TESTCTX to test the current context by calling the item type's Selector/Callback function, or FORWARD, TRANSFER, QUESTION, ANSWER, VALIDATE, or RESPOND to execute the post-notification function in those modes. |
| context | The context passed to SEND() or SendGroup(). The format is <itemtype>:<itemkey>:<activityid>. |
| attr_name | An attribute name to set/get if command is SET or GET. |
| attr_type | An attribute type if command is SET or GET. |
| text_value | Value of a text attribute if command is SET or value of text attribute returned if command is GET. |
| number_value | Value of a number attribute if command is SET or value of a number attribute returned if command is GET. |
| date_value | Value of a date attribute if command is SET or value of a date attribute returned if command is GET. |
| event_value | Value of an event attribute if command is SET or value of an event attribute returned if command is GET. Required only if the procedure name is overloaded with a second implementation that handles event attributes.
Note: The arguments text_value, number_value, and date_value, as well as event_value if you are using this argument, are mutually exclusive. That is, you should use only one of these arguments, depending on the value of the attr_type argument. |
Example 1
When a notification is sent, the system calls the specified callback function once for each SEND attribute (to get the attribute value).
For each SEND attribute, call:
your_callback('GET', context, 'BUGNO', 'NUMBER', textval,
numval, dateval);
Example 2
When the user responds to the notification, the callback is called again, once for each RESPOND attribute.
your_callback('SET', context, 'STATUS', 'TEXT',
'COMPLETE', numval, dateval);
Example 3
Then finally the Notification System calls the 'COMPLETE' command to indicate the response is complete.
your_callback('COMPLETE', context, attrname, attrtype,
textval, numval, dateval);
Example 4
For a SEND attribute of type event, call the implementation that includes the event_value argument.
your_callback('GET', context, 'RECEIVE_EVENT', 'EVENT',
textval, numval, dateval, eventval);
function SendGroup (role in varchar2, msg_type in varchar2, msg_name in varchar2, due_date in date default null, callback in varchar2 default null, context in varchar2 default null, send_comment in varchar2 default null priority in number default null) return number;
This function sends a separate notification to all the users assigned to a specific role and returns a number called a notification group ID, if successful. The notification group ID identifies that group of users and the notification they each received.
If your message has message attributes, the procedure looks up the values of the attributes from the message attribute table or it can use an optionally supplied callback interface function to get the value from the item type attributes table. A callback function can also be used when a notification is responded to.
Note: If you are using the Oracle Workflow Notification System and its e-mail-based or Web-based notification client, the SendGroup() API implicitly calls the WF_ENGINE.CB callback function. If you are using your own custom notification system, then you must define your own callback function following a standard format and specify its name for the callback argument. See: Custom Callback Function.
If any message attributes are mapped by worklist flexfields rules, SendGroup() stores denormalized values for those attributes in the designated worklist flexfields columns. See: Defining Specialized Worklist Views with Worklist Flexfields, Oracle Workflow Administrator's Guide.
Generally, this function is called only if a notification activity has 'Expanded Roles' checked in its properties page. If Expanded Roles is not checked, then the Send() function is called instead. See: Voting Activity, Oracle Workflow Developer's Guide.
| Variable | Description |
|---|---|
| role | The role name assigned as the performer of the notification activity. |
| msg_type | The item type associated with the message. |
| msg_name | The message internal name. |
| due_date | The date that a response is required. This optional due date is only for the recipient's information; it has no effect on processing. |
| callback | The callback function name used for communication of SEND source message attributes. |
| context | Context information passed to the callback function. |
| send_comment | A comment presented with the message. |
| priority | The priority of the message, as derived from the #PRIORITY notification activity attribute. If #PRIORITY does not exist or if the value is null, the Workflow Engine uses the default priority of the message. |
procedure FORWARD (nid in number, new_role in varchar2, forward_comment in varchar2 default null);
public static boolean forward (WFContext wCtx, BigDecimal nid, String newRole String comment)
This procedure delegates a notification to a new role to perform work, even though the original role recipient still maintains ownership of the notification activity. Also implicitly calls the Callback function specified in the Send or SendGroup function with FORWARD mode. A comment can be supplied to explain why the forward is taking place. Existing notification attributes (including due date) are not refreshed or otherwise changed. The Delegate feature in the Notification System calls this procedure. Note that when you forward a notification, the forward is recorded in the USER_COMMENT field of the notification.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| new_role or newRole | The role name of the person the note is reassigned to. |
| forward_comment or comment | An optional forwarding comment. |
The following code excerpt shows an example of how to call forward() in a Java program. The example code is from the WFTest.java program.
// forward to MBEECH
System.out.println("Delegate Test");
count = WFNotificationAPI.workCount(ctx, "MBEECH");
System.out.println("There are " + count +
" open notification(s) for" + " MBEECH");
System.out.println("Delegate nid " + myNid +
" from BLEWIS to MBEECH");
WFNotificationAPI.forward(ctx, myNid, "MBEECH",
"Matt, Please handle.");
count = WFNotificationAPI.workCount(ctx, "MBEECH");
System.out.println("There are " + count +
" open notification(s) for" +
" MBEECH after Delegate.");
procedure TRANSFER (nid in number, new_role in varchar2, forward_comment in varchar2 default null);
public static boolean transfer (WFContext wCtx, BigDecimal nid, String newRole String comment)
This procedure forwards a notification to a new role and transfers ownership of the notification to the new role. It also implicitly calls the Callback function specified in the Send or SendGroup function with TRANSFER mode. A comment can be supplied to explain why the forward is taking place. The Transfer feature in the Notification System calls this procedure. Note that when you transfer a notification, the transfer is recorded in the USER_COMMENT field of the notification.
Important: Existing notification attributes (including due date) are not refreshed or otherwise changed except for ORIGINAL_RECIPIENT, which identifies the owner of the notification.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| new_role or newRole | The role name of the person the note is transferred to. |
| forward_comment or comment | An optional comment to append to notification. |
The following code excerpt shows an example of how to call transfer() in a Java program. The example code is from the WFTest.java program.
// transfer to MBEECH
System.out.println("Transfer Test");
System.out.println("Transfer nid " + myNid +
" from BLEWIS to MBEECH");
WFNotificationAPI.transfer(ctx, myNid, "MBEECH",
"Matt, You own it now.");
count = WFNotificationAPI.workCount(ctx, "MBEECH");
System.out.println("There are " + count +
" open notification(s) for" +
" MBEECH after Transfer.");
procedure CANCEL (nid in number, cancel_comment in varchar2 default null);
public static boolean cancel
(WFContext wCtx,
BigDecimal nid,
String comment)
This procedure may be invoked by the sender or administrator to cancel a notification. The notification status is then changed to 'CANCELED' but the row is not removed from the WF_NOTIFICATIONS table until a purge operation is performed.
If the notification was delivered via e-mail and expects a response, a 'Canceled' e-mail is sent to the original recipient as a warning that the notification is no longer valid.
Note: You can optionally use the Send E-mails for Canceled Notifications mailer parameter to prevent notification mailers from sending any notification cancellation messages. See: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| cancel_comment or comment | An optional comment on the cancellation. |
procedure CancelGroup (gid in number, cancel_comment in varchar2 default null, timeout in boolean default FALSE);
This procedure may be invoked by the sender or administrator to cancel the individual copies of a specific notification sent to all users in a notification group. The notifications are identified by the notification group ID (gid). The notification status is then changed to 'CANCELED' but the rows are not removed from the WF_NOTIFICATIONS table until a purge operation is performed.
If the notification was delivered via e-mail and expects a response, a 'Canceled' e-mail is sent to the original recipient as a warning that the notification is no longer valid.
Note: You can optionally use the Send E-mails for Canceled Notifications mailer parameter to prevent notification mailers from sending any notification cancellation messages. See: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide.
Generally, this function is called only if a notification activity has 'Expanded Roles' checked in its properties page. If Expanded Roles is not checked, then the Cancel() function is called instead. See: Voting Activity, Oracle Workflow Developer's Guide.
| Variable | Description |
|---|---|
| gid | The notification group ID. |
| cancel_comment | An optional comment on the cancellation. |
| timeout | Specify TRUE or FALSE to indicate whether the cancellation was caused by a timeout event. |
procedure RESPOND (nid in number, respond_comment in varchar2 default null, responder in varchar2 default null);
public static boolean respond (WFContext wCtx, BigDecimal nid, String comment, String responder)
This procedure may be invoked by the notification agent (Notification Web page or e-mail agent) when the performer completes the response to the notification. The procedure marks the notification as 'CLOSED' and communicates RESPOND attributes back to the database via the callback function (if supplied).
This procedure also accepts the name of the individual who actually responded to the notification. This may be useful to know especially if the notification is assigned to a multi-user role. The information is stored in the RESPONDER column of the WF_NOTIFICATIONS table. The value stored in this column depends on how the user responds to the notification. The following table shows the value that is stored for each response mechanism.
| Response Mechanism | Value Stored |
|---|---|
| Response through the Worklist Web pages | <Oracle E-Business Suite user name> |
| Response through e-mail and the sender's e-mail address matches the e-mail address for exactly one user in WF_ROLES | <Oracle E-Business Suite user name> |
| Response through e-mail and the sender's e-mail address either does not match the e-mail address for any user in WF_ROLES, or matches the e-mail address for more than one user | email:<email_address> |
Additionally, the Respond() procedure calls NtfSignRequirementsMet() to determine whether the response meets any signature requirements imposed by the electronic signature policy of the notification. If the requirements have not been met, Respond() raises an error. See: #WF_SIG_POLICY Attribute, Oracle Workflow Developer's Guide and NtfSignRequirementsMet.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| comment | An optional comment on the response |
| responder | The user who responded to the notification. |
function RESPONDER (nid in number) return varchar2;
public static String responder (WFContext wCtx, BigDecimal nid)
This function returns the responder of a closed notification.
If the notification was closed using the Web notification interface the value returned will be a valid role defined in the view WF_ROLES. If the notification was closed using the e-mail interface then the value returned will be either a role or an e-mail address. See: Respond.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
function NtfSignRequirementsMet (nid in number) return boolean;
Returns 'TRUE' if the response to a notification meets the signature requirements imposed by the electronic signature policy for the notification. See: #WF_SIG_POLICY Attribute, Oracle Workflow Developer's Guide.
If the notification uses a signature policy that requires an electronic signature to validate a user's response, then a valid signature by a user who has authority to sign the response must be submitted in order for the response to meet the requirements. The signature must be of the appropriate type, either password-based or certificate-based, depending on the signature policy.
If the notification uses the default policy, which does not require a signature, or if no signature policy is defined for the notification, then a response without a signature meets the requirements.
However, if the signature policy for the notification requires an electronic signature, but a valid signature has not been submitted, then the response does not meet the requirements. In this case NtfSignRequirementsMet() returns 'FALSE'.
| Variable | Description |
|---|---|
| nid | The notification ID. |
Related Topics
procedure VoteCount (gid in number, ResultCode in varchar2, ResultCount out number, PercentOfTotalPop out number, PercentOfVotes out number);
public static WFTwoDArray voteCount (WFContext wCtx, BigDecimal gid, String resultCode)
Counts the number of responses for a specified result code.
Use this procedure only if you are writing your own custom Voting activity. See: Voting Activity, Oracle Workflow Developer's Guide.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| gid | The notification group ID. |
| ResultCode | Result code to be tallied. |
function OpenNotificationsExist (gid in number) return boolean;
public static boolean openNotificationsExist (WFContext wCtx, BigDecimal gid)
This function returns 'TRUE' if any notification associated with the specified notification group ID is 'OPEN', otherwise it returns 'FALSE'.
Use this procedure only if you are writing your own custom Voting activity. See: Voting Activity, Oracle Workflow Developer's Guide.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| gid | The notification group ID. |
procedure Close (nid in number, responder in varchar2 default null);
public static boolean close (WFContext wCtx, BigDecimal nid, String responder)
This procedure closes a notification.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| responder | The user or role who responded to the notification. |
procedure AddAttr (nid in number, aname in varchar2);
public static boolean addAttr (WFContext wCtx, BigDecimal nid, String aName)
Adds a new runtime notification attribute. You should perform validation and insure consistency in the use of the attribute, as it is completely unvalidated by Oracle Workflow.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| aname | The attribute name. |
| avalue | The attribute value. |
The following code excerpt shows an example of how to call addAttr() in a Java program. The example code is from the WFTest.java program.
if (WFNotificationAPI.addAttr(ctx, myNid, myAttr) == false)
{
System.out.println("Add attribute " + myAttr + " failed.");
}
procedure SetAttrText (nid in number, aname in varchar2, avalue in varchar2); procedure SetAttrNumber (nid in number, aname in varchar2, avalue in number); procedure SetAttrDate (nid in number, aname in varchar2, avalue in date);
public static boolean setAttrText (WFContext wCtx, BigDecimal nid, String aName, String aValue) public static boolean setAttrNumber (WFContext wCtx, BigDecimal nid, String aName, BigDecimal aValue) public static boolean setAttrDate (WFContext wCtx, BigDecimal nid, String aName, String aValue)
Used at both send and respond time to set the value of notification attributes. The notification agent (sender) may set the value of SEND attributes. The performer (responder) may set the value of RESPOND attributes.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| aname | The attribute name. |
| avalue | The attribute value. |
The following code excerpt shows an example of how to call a setAttribute method in a Java program. The example code is from the WFTest.java program.
if (WFNotificationAPI.setAttrDate(ctx, myNid, myAttr, value)
== false)
{
System.out.println("set attribute " + myAttr + " to " +
value + " failed.");
}
procedure GetAttrInfo (nid in number, aname in varchar2, atype out varchar2, subtype out varchar2, format out varchar2);
public static WFTwoDArray getAttrInfo (WFContext wCtx, BigDecimal nid, String aName)
Returns information about a notification attribute, such as its type, subtype, and format, if any is specified. The subtype is always SEND or RESPOND to indicate the attribute's source.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| aname | The attribute name. |
The following code excerpt shows an example of how to call getAttrInfo() in a Java program. The example code is from the WFTest.java program.
dataSource = WFNotificationAPI.getAttrInfo(ctx, myNid,
myAttr);
displayDataSource(ctx, dataSource);
// the first element is the attribute type
myAttrType = (String) dataSource.getData(0,0);
procedure GetInfo (nid in number, role out varchar2, message_type out varchar2, message_name out varchar2, priority out number, due_date out date, status out varchar2);
public static WFTwoDArray getInfo (WFContext wCtx, BigDecimal nid)
Returns the role that the notification is sent to, the item type of the message, the name of the message, the notification priority, the due date and the status for the specified notification.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
The following code excerpt shows an example of how to call getInfo() in a Java program. The example code is from the WFTest.java program.
// Notification Info
System.out.println("Notification Info for nid " + myNid);
dataSource = WFNotificationAPI.getInfo(ctx, myNid);
displayDataSource(ctx, dataSource);
function GetText (some_text in varchar2, nid in number, disptype in varchar2 default '') return varchar2;
public static String getText (WFContext wCtx, String someText, BigDecimal nid, String dispType)
Substitutes tokens in an arbitrary text string using token values from a particular notification. This function may return up to 32K characters. You cannot use this function in a view definition or in an Oracle Forms Developer form. For views and forms, use GetShortText() which truncates values at 1950 characters.
Note: If the text string includes tokens for attributes of type date, then GetText() formats the date values for those tokens according to the calendar preference specified for the notification recipient in the FND: Forms User Calendar profile option, if this profile option has been set.
If an error is detected, this function returns some_text unsubstituted rather than raise exceptions.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| some_text or someText | Text to be substituted. |
| nid | Notification ID of notification to use for token values. |
| disptype or dispType | The display type of the message body that you are token substituting the text into. Valid display types are:
The default is null. |
function GetShortText (some_text in varchar2, nid in number) return varchar2;
Substitutes tokens in an arbitrary text string using token values from a particular notification. This function may return up to 1950 characters. This function is meant for use in view definitions and Oracle Forms Developer forms, where the field size is limited to 1950 characters. Use GetText() in other situations where you need to retrieve up to 32K characters.
If an error is detected, this function returns some_text unsubstituted rather than raise exceptions.
| Variable | Description |
|---|---|
| some_text | Text to be substituted. |
| nid | Notification ID of notification to use for token values. |
function GetAttrText (nid in number, aname in varchar2) return varchar2; function GetAttrNumber (nid in number, aname in varchar2) return number; function GetAttrDate (nid in number, aname in varchar2) return date;
public static String getAttrText (WFContext wCtx, BigDecimal nid, String aName) public static BigDecimal getAttrNumber (WFContext wCtx, BigDecimal nid, String aName) public static String getAttrDate (WFContext wCtx, BigDecimal nid, String aName)
Returns the value of the specified message attribute.
Note: If the text string includes returned by GetAttrText() includes formatted date values, then this API formats those date values according to the calendar preference specified for the notification recipient in the FND: Forms User Calendar profile option, if this profile option has been set.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| aname | The message attribute name. |
The following code excerpt shows an example of how to call the getAttribute methods in a Java program. The example code is from the WFTest.java program.
// we get the value according to the type.
if (myAttrType == "DATE")
{
value = WFNotificationAPI.getAttrDate(ctx, myNid, myAttr);
}
else if (myAttrType == "NUMBER")
{
value = (WFNotificationAPI.getAttrNumber(ctx, myNid,
myAttr)).toString();
}
else if (myAttrType == "DOCUMENT")
{
value = WFNotificationAPI.getAttrDoc(ctx, myNid, myAttr,
null);
}
else
value = WFNotificationAPI.getAttrText(ctx, myNid, myAttr);
System.out.println(myAttr.toString() + " = '" + value +
"'");
function GetAttrDoc (nid in number, aname in varchar2, disptype in varchar2) return varchar2;
public static String getAttrDoc (WFContext wCtx, BigDecimal nid, String aName, String dispType)
Returns the displayed value of a Document-type attribute. The referenced document appears in either plain text or HTML format, as requested.
If you wish to retrieve the actual attribute value, that is, the document key string instead of the actual document, use GetAttrText().
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| aname | The message attribute name. |
| disptype | The display type of the document you wish to return. Valid display types are:
|
function GetSubject (nid in number) return varchar2
public static String getSubject (WFContext wCtx, BigDecimal nid)
Returns the subject line for the notification message. Any message attribute in the subject is token substituted with the value of the corresponding message attribute.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
function GetBody (nid in number, disptype in varchar2 default '') return varchar2;
public static String getBody (WFContext wCtx, BigDecimal nid, String dispType)
Returns the HTML or plain text message body for the notification, depending on the message body type specified. Any message attribute in the body is token substituted with the value of the corresponding notification attribute. This function may return up to 32K characters. You cannot use this function in a view definition or in an Oracle E-Business Suite form. For views and forms, use GetShortBody() which truncates values at 1950 characters.
Note that the returned plain text message body is not formatted; it should be wordwrapped as appropriate for the output device. Body text may contain tabs (which indicate indentation) and newlines (which indicate paragraph termination).
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
| disptype | The display type of the message body you wish to fetch. Valid display types are:
The default is null. |
function GetShortBody (nid in number) return varchar2;
Returns the message body for the notification. Any message attribute in the body is token substituted with the value of the corresponding notification attribute. This function may return up to 1950 characters. This function is meant for use in view definitions and Oracle Forms Developer forms, where the field size is limited to 1950 characters. Use GetBody() in other situations where you need to retrieve up to 32K characters.
Note that the returned plain text message body is not formatted; it should be wordwrapped as appropriate for the output device. Body text may contain tabs (which indicate indentation) and newlines (which indicate paragraph termination).
If an error is detected, this function returns the body unsubstituted or null if all else fails, rather than raise exceptions.
Note: This function is intended for displaying messages in forms or views only.
| Variable | Description |
|---|---|
| nid | The notification ID. |
function TestContext (nid in number) return boolean;
Tests if the current context is correct by calling the Item Type Selector/Callback function. This function returns TRUE if the context check is OK, or if no Selector/Callback function is implemented. It returns FALSE if the context check fails.
| Variable | Description |
|---|---|
| nid | The notification ID. |
function AccessCheck (access_str in varchar2) return varchar2;
public static String accessCheck (WFContext wCtx, String accessString)
Returns a username if the notification access string is valid and the notification is open, otherwise it returns null. The access string is automatically generated by the notification mailer that sends the notification and is used to verify the authenticity of both text and HTML versions of e-mail notifications.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| access_str or accessString | The access string, in the format nid/nkey where nid is the notification ID and nkey is the notification key. |
function WorkCount (username in varchar2) return number;
public static BigDecimal workCount (WFContext wCtx, String userName)
Returns the number of open notifications assigned to a role.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| username | The internal name of a role. |
public static WFTwoDArray getNotifications (WFContext wCtx, String itemType, String itemKey)
Returns a list of notifications for the specified item type and item key.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| itemType | The internal name of the item type. |
| itemKey | A string derived from the application object's primary key. The string uniquely identifies the item within the item type. The item type and key together identify the process instance. |
public static WFTwoDArray getNotificationAttributes (WFContext wCtx, BigDecimal nid)
Returns a list of notification attributes and their corresponding values for the specified notification ID.
| Variable | Description |
|---|---|
| wCtx | Workflow context information. Required for the Java method only. See: Oracle Workflow Context. |
| nid | The notification ID. |
The following code excerpt shows an example of how to call getNotificationAttributes() in a Java program. The example code is from the WFTest.java program.
// List available Notification Attributes
System.out.println("List of Attributes for id " + myNid +
":");
dataSource =
WFNotificationAPI.getNotificationAttributes(ctx, myNid);
displayDataSource(ctx, dataSource);
procedure WriteToClob (clob_loc in out clob, msg_string in varchar2);
Appends a character string to the end of a character large object (CLOB). You can use this procedure to help build the CLOB for a PL/SQL CLOB document attribute for a notification.
| Variable | Description |
|---|---|
| clob_loc | The CLOB to which the string should be added. |
| msg_string | A string of character data. |
Related Topics
To Define a Document Attribute, Oracle Workflow Developer's Guide
"PL/SQL CLOB" Documents, Oracle Workflow Developer's Guide
procedure Denormalize_Notification (nid in number, username in varchar2 default null, langcode in varchar2 default null);
Stores denormalized values for certain notification fields, including the notification subject, in the WF_NOTIFICATIONS table. If you are using the Notification System to send a notification outside of a workflow process, you must call Denormalize_Notification() after setting the values for any notification attributes, in order to populate the denormalized fields.
Denormalize_Notification() tests whether the NLS settings according to which the notification should be sent match the NLS settings of the current session, and stores the denormalized information only if these settings match. The procedure tests the following NLS parameters:
nls_language
nls_date_format
nls_date_language
nls_calendar
nls_territory
nls_sort
You can indicate the language setting for the notification in a number of ways.
If you specify a role name when you call the API, the language setting for that role is used to determine the notification language.
If you do not specify a role name, you can specify a language code for the language you want.
Note: If you specify both a role name and a language code, the role name is used to determine the notification language, and the language code is ignored.
If you specify neither a role name nor a language code, the notification language defaults to the language setting for the recipient role of the notification.
For the other NLS parameters, the settings according to which the notification should be sent are those of the recipient role.
If NLS settings for the notification do not match the settings of the current session, the procedure does not store the denormalized information immediately. Instead, it raises the oracle.apps.wf.notification.denormalize event to defer the denormalization. The procedure sets all the NLS parameters into the event attributes so that the full NLS context will be available when the event is processed and the denormalization is performed.
Note: When a notification is denormalized, the only NLS parameter that is stored in the WF_NOTIFICATIONS table is the language setting. The other NLS parameters are not currently stored.
After notifications are sent, the user interface through which notification recipients access notifications should also call this procedure to check the language and perform denormalization if necessary. The Oracle Workflow Worklist performs these tasks for you if your users access their notifications through the Worklist Web pages.
Note: Because only the language parameter is stored in the WF_NOTIFICATIONS table, the language setting is the only setting that is tested against the current session when a notification is accessed and denormalized through a user interface.
| Variable | Description |
|---|---|
| nid | The notification ID. |
| username | An optional internal name of a role used to determine the notification language. |
| langcode | An optional language code used to determine the notification language if no role name is provided. |
The notification mailer utility API can be used to encode data in a binary large object (BLOB) to base64. This API is defined in a PL/SQL package called WF_MAIL_UTIL.
procedure EncodeBLOB (pIDoc in blob, pODoc in out nocopy clob);
Encodes the specified BLOB to base64 and returns the encoded data as a character large object (CLOB). You can use this procedure to store a BLOB in a PL/SQL CLOB document to be included in a notification message.
| Variable | Description |
|---|---|
| pIDoc | The BLOB to encode. |
| pODoc | The CLOB in which the encoded data should be stored. |
Related Topics
Standard APIs for "PL/SQL" Documents, Oracle Workflow Developer's Guide
The notification utility API can be used to format a date value according to a particular calendar preference. This API is defined in a PL/SQL package called WF_NOTIFICATION_UTIL.
function GetCalendarDate (p_nid number default -1, p_date in date, p_date_format in varchar2 default null, p_addTime in boolean default false) return varchar2;
Returns the specified date value as formatted text in the specified date format, using either a notification recipient's calendar preference or the current session user's calendar preference. For example, you can call this API within PL/SQL documents used in notifications, so that the Worklist pages and e-mail notifications display date values in the appropriate format for the notification recipients.
| Variable | Description |
|---|---|
| p_nid | Specify the notification ID if it is available. In this case, the API returns the date value according to the calendar preference of the notification recipient. If you do not specify a notification ID, the API returns the date value according to the calendar preference of the current session user. |
| p_date | The date value to format. |
| p_date_format | Optionally specify a date format mask in which to return the date value. |
| p_addTime | If the date format mask specified in the p_date_format parameter does not include a time format, you can use this parameter to specify whether to add a time element to the formatted date. Specify TRUE to add a time element based on the NLS time format of the current session, such as ' HH24:MI:SS'. Specify FALSE if you do not want to add a time element.The default value is FALSE.
Note: If the date format mask specified in the p_date_format parameter does include a time format, then the p_addTime parameter is not used. |
The Oracle Workflow XML message APIs are used to process messages to be sent through e-mail, including generating the XML message content. These APIs are defined in a PL/SQL package called WF_XML.
function Generate (p_event_name in varchar2, p_event_key in varchar2, p_parameter_list in wf_parameter_list_t default null) return clob;
Generates the XML message content as the event data for events in the Notification Send group (oracle.apps.wf.notification.send.group). The send events are then ready to be placed on the WF_NOTIFICATION_OUT agent to be processed by the notification mailer.
| Variable | Description |
|---|---|
| p_event_name | The internal name of the event. |
| p_event_key | The event key that identifies the specific instance of the event. |
| p_parameter_list | The list of additional parameters for the event. |
Related Topics
Notification Events, Oracle Workflow Developer's Guide
function SummaryRule (p_subscription_guid in raw, p_event in out nocopy wf_event_t) return varchar2;
Launches summary notifications for each role that has open notifications and a notification preference of SUMMARY or SUMHTML. This function calls the appropriate APIs to generate the summary content for each role and for each member of those roles. Oracle Workflow uses WF_XML.SummaryRule() as the rule function for a predefined subscription to the Launch Summary Notifications event (oracle.apps.fnd.wf.mailer.Mailer.notification.summary).
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription that calls this rule function. |
| p_event | The event message that triggers the subscription. |
Related Topics
Notification Mailer Events, Oracle Workflow Developer's Guide
function Error_Rule (p_subscription_guid in raw, p_event in out nocopy wf_event_t) return varchar2;
Catches and raises internal exceptions in message processing to force a rollback. This API helps prevent endless loops if failed messages result in error messages that also fail. Oracle Workflow uses WF_XML.Error_Rule() as the rule function for a predefined error subscription to the Notification Send Group event group (oracle.apps.wf.notification.send.group).
| Variable | Description |
|---|---|
| p_subscription_guid | The globally unique identifier of the subscription that calls this rule function. |
| p_event | The event message that triggers the subscription. |
Related Topics
Notification Events, Oracle Workflow Developer's Guide
The Oracle Workflow message API can be used to send messages through e-mail, whether the messages are associated with a workflow process or not. This API is defined in a PL/SQL package called WF_MAIL.
The Oracle Workflow message API uses a PL/SQL table composite datatype called wf_recipient_list_t, defined in the WF_MAIL package. The following table shows the column datatype definition for this PL/SQL table type.
| PL/SQL Table Type | Column Datatype Definition |
|---|---|
| wf_recipient_list_t | wf_recipient_rec_t |
The wf_recipient_list_t PL/SQL table type in turn uses a PL/SQL record composite datatype called wf_recipient_rec_t, which stores information about a recipient to whom an e-mail message should be sent. The following table lists the fields in this PL/SQL record type.
| Field Name | Field Datatype | Description |
|---|---|---|
| NAME | VARCHAR2(360) | Recipient name |
| ADDRESS | VARCHAR2(320) | E-mail address |
| RECIPIENT_TYPE | VARCHAR2(4) | Recipient type, either TO, CC, or BCC |
procedure send (p_subject in varchar2, p_message in out nocopy clob, p_recipient_list in wf_recipient_list_t, p_module in varchar2, p_idstring in varchar2 default null, p_from in varchar2 default null, p_replyto in varchar2 default null, p_language in varchar2 default 'AMERICAN', p_territory in varchar2 default 'AMERICA', p_codeset in varchar2 default 'UTF8', p_content_type in varchar2 default 'text/plain', p_callback_event in varchar2 default null, p_event_key in varchar2 default null, p_fyi_flag in varchar2 default null);
Sends a message to be dispatched through e-mail by a notification mailer. The message content and recipients provided in the parameters do not need to be associated with any workflow process or directory service roles. The message content must be complete, preformatted, and email-ready, and should conform to the content type specified in the p_content_type parameter. Where possible, Oracle recommends setting only the required parameters and using the default values for the optional parameters.
| Variable | Description |
|---|---|
| p_subject | The Subject header value for the message. |
| p_message | The message content as a character large object (CLOB). |
| p_recipient_list | The list of recipients to whom the message should be sent. |
| p_module | The program or application to which the message belongs. |
| p_idstring | An optional identifier for the message, used in response processing. |
| p_from | An optional From header value for the message. |
| p_replyto | An optional Reply-To header value for the message. |
| p_language | An optional language setting for the message. The default value is 'AMERICAN'. |
| p_territory | An optional territory setting for the message. The default value is 'AMERICA'. |
| p_codeset | An optional codeset encoding specification for the message. The default value is 'UTF8'. |
| p_content_type | An optional Content-Type header value for the message. The default value is 'text/plain'. |
| p_callback_event | The event raised to enable further processing, if needed, after the message is dispatched. |
| p_event_key | The key that identifies the message when the message is enqueued for dispatch. |
| p_fyi_flag | A flag to indicate whether the message is for your information (FYI) or requires a response. |