Skip Headers

Oracle Workflow API Reference Release 2.6.4 Part Number B15855-02

Home Book List Contents Index Master Index Feedback

---

Previous Next

View PDF

Skip Headers

Oracle Workflow API Reference Release 2.6.4 Part Number B15855-02

Contents

Previous

Next

Notification System APIs

Overview of the Oracle Workflow Notification System

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 Model

Notification Document Type Definition

Notification APIs

Notification Mailer Utility API

Notification Model

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.

Sending Notification Messages

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, for Oracle Applications only, 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.

Users who view their notifications from the Notifications 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: In Oracle Applications, 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.

Processing a Notification Response

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.

Forwarding a Notification

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.

Transferring a 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.

Requesting More Information About a 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.

Processing a Timed Out 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.

Special Handling of Voting Activities

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.

Notification Document Type Definition

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.

Notification APIs

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.

• Send - PL/SQL and Java

• SendGroup - PL/SQL

• Forward - PL/SQL and Java

• Transfer - PL/SQL and Java

• Cancel - PL/SQL and Java

• CancelGroup - PL/SQL

• Respond - PL/SQL and Java

• Responder - PL/SQL and Java

• NtfSignRequirementsMet - PL/SQL

• VoteCount - PL/SQL and Java

• OpenNotificationsExist - PL/SQL and Java

• Close - PL/SQL and Java

• AddAttr - PL/SQL and Java

• SetAttribute - PL/SQL and Java

• GetAttrInfo - PL/SQL and Java

• GetInfo - PL/SQL and Java

• GetText - PL/SQL and Java

• GetShortText - PL/SQL

• GetAttribute - PL/SQL and Java

• GetAttrDoc - PL/SQL and Java

• GetSubject - PL/SQL and Java

• GetBody - PL/SQL and Java

• GetShortBody - PL/SQL

• TestContext - PL/SQL

• AccessCheck - PL/SQL and Java

• WorkCount - PL/SQL and Java

• getNotifications - Java

• getNotificationAttributes - Java

• WriteToClob - PL/SQL

• Denormalize_Notification - PL/SQL

• SubstituteSpecialChars - PL/SQL

Note: The Notification System raises business events when a notification is sent, closed, canceled, or reassigned, or when a user responds to a notification. 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 Define an Event Subscription (for standalone Oracle Workflow), Oracle Workflow Developer's Guide or To Create or Update an Event Subscription (for Oracle Applications), Oracle Workflow Developer's Guide.

Send

PL/SQL Syntax

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;

Java Syntax

public static BigDecimal send
  (WFContext wCtx,
   String role,
   String messageType,
   String messageName,
   String dueDate,
   String callback,
   String context,
   string sendComment,
   BigDecimal priority)

Description

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 procedure 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.

Arguments (input)

Custom Callback Function

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;

Arguments (input)

Examples

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);

SendGroup

PL/SQL Syntax

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;

Description

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 Send procedure 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.

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.

Arguments (input)

Forward

PL/SQL Syntax

procedure FORWARD
  (nid in number,
   new_role in varchar2,
   forward_comment in varchar2 default null);

Java Syntax

public static boolean forward
  (WFContext wCtx,
   BigDecimal nid,
   String newRole
   String comment)

Description

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.

Arguments (input)

Example

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.");

Transfer

PL/SQL Syntax

procedure TRANSFER
  (nid in number,
   new_role in varchar2,
   forward_comment in varchar2 default null);

Java Syntax

public static boolean transfer
  (WFContext wCtx,
   BigDecimal nid,
   String newRole
   String comment)

Description

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.

Attention: Existing notification attributes (including due date) are not refreshed or otherwise changed except for ORIGINAL_RECIPIENT, which identifies the owner of the notification.

Arguments (input)

Example

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.");

Cancel

PL/SQL Syntax

procedure CANCEL
  (nid in number,
   cancel_comment in varchar2 default null);

Java Syntax

public static boolean cancel
    (WFContext wCtx,
     BigDecimal nid,
     String comment)

Description

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.

Arguments (input)

CancelGroup

PL/SQL Syntax

procedure CancelGroup
  (gid in number,
   cancel_comment in varchar2 default null);

Description

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.

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.

Arguments (input)

Respond

PL/SQL Syntax

procedure  RESPOND
  (nid in number,
   respond_comment in varchar2 default null,
   responder in varchar2 default null);

Java Syntax

public static boolean respond
  (WFContext wCtx,
   BigDecimal nid,
   String comment,
   String responder)

Description

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.

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.

Arguments (input)

Responder

PL/SQL Syntax

function RESPONDER
  (nid in number)
  return varchar2;

Java Syntax

public static String responder
  (WFContext wCtx,
   BigDecimal nid)

Description

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 an e-mail address. See: Respond.

Arguments (input)

NtfSignRequirementsMet

PL/SQL Syntax

function NtfSignRequirementsMet
  (nid in number) 
  return boolean;

Description

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'.

Arguments (input)

Related Topics

Respond

VoteCount

PL/SQL Syntax

procedure VoteCount
  (gid in number,
   ResultCode in varchar2,
   ResultCount out number,
   PercentOfTotalPop out number,
   PercentOfVotes out number);

Java Syntax

public static WFTwoDArray voteCount
  (WFContext wCtx,
   BigDecimal gid,
   String resultCode)

Description

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.

Arguments (input)

OpenNotificationsExist

PL/SQL Syntax

function OpenNotificationsExist
  (gid in number)
  return boolean;

Java Syntax

public static boolean openNotificationsExist
  (WFContext wCtx,
   BigDecimal gid)

Description

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.

Arguments (input)

Close

PL/SQL Syntax

procedure Close
  (nid in number,
   responder in varchar2 default null);

Java Syntax

public static boolean close
  (WFContext wCtx,
   BigDecimal nid,
   String responder)

Description

This procedure closes a notification.

Arguments (input)

AddAttr

PL/SQL Syntax

procedure AddAttr
  (nid in number,
   aname in varchar2);

Java Syntax

public static boolean addAttr
  (WFContext wCtx,
   BigDecimal nid,
   String aName)

Description

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.

Arguments (input)

Example

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.");
}

SetAttribute

PL/SQL Syntax

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);

Java Syntax

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)

Description

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.

Arguments (input)

Example

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.");
}

GetAttrInfo

PL/SQL Syntax

procedure GetAttrInfo
  (nid in number,
   aname in varchar2,
   atype out varchar2,
   subtype out varchar2,
   format out varchar2);

Java Syntax

public static WFTwoDArray getAttrInfo
  (WFContext wCtx,
   BigDecimal nid,
   String aName)

Description

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.

Arguments (input)

Example

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);

GetInfo

PL/SQL Syntax

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);

Java Syntax

public static WFTwoDArray getInfo
  (WFContext wCtx,
   BigDecimal nid)

Description

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.

Arguments (input)

Example

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);

GetText

PL/SQL Syntax

function GetText
  (some_text in varchar2,
   nid in number,
   disptype in varchar2 default '')
  return varchar2;

Java Syntax

public static String getText
  (WFContext wCtx,
   String someText,
   BigDecimal nid,
   String dispType)

Description

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.

If an error is detected, this function returns some_text unsubstituted rather than raise exceptions.

Arguments (input)

GetShortText

PL/SQL Syntax

function GetShortText
  (some_text in varchar2,
   nid in number)
  return varchar2;

Description

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.

Arguments (input)

GetAttribute

PL/SQL Syntax

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;

Java Syntax

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)

Description

Returns the value of the specified message attribute.

Arguments (input)

Example

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 + 
    "'");

GetAttrDoc

PL/SQL Syntax

function GetAttrDoc
  (nid in number,
   aname in varchar2,
   disptype in varchar2)
  return varchar2;

Java Syntax

public static String getAttrDoc
  (WFContext wCtx,
   BigDecimal nid,
   String aName,
   String dispType)

Description

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().

Arguments (input)

GetSubject

PL/SQL Syntax

function GetSubject 
  (nid in number)
  return varchar2

Java Syntax

public static String getSubject
  (WFContext wCtx,
   BigDecimal nid)

Description

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.

Arguments (input)

GetBody

PL/SQL Syntax

function GetBody
  (nid in number,
   disptype in varchar2 default '')
  return varchar2;

Java Syntax

public static String getBody
  (WFContext wCtx,
   BigDecimal nid,
   String dispType)

Description

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 Applications 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).

Arguments (input)

GetShortBody

PL/SQL Syntax

function GetShortBody
  (nid in number)
  return varchar2;

Description

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.

Arguments (input)

TestContext

PL/SQL Syntax

function TestContext
  (nid in number)
  return boolean;

Description

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.

Arguments (input)

AccessCheck

PL/SQL Syntax

function AccessCheck
  (access_str in varchar2)
  return varchar2;

Java Syntax

public static String accessCheck
  (WFContext wCtx,
   String accessString)

Description

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.

Arguments (input)

WorkCount

PL/SQL Syntax

function WorkCount
  (username in varchar2)
  return number;

Java Syntax

public static BigDecimal workCount
  (WFContext wCtx,
   String userName)

Description

Returns the number of open notifications assigned to a role.

Arguments (input)

getNotifications

Java Syntax

public static WFTwoDArray getNotifications
  (WFContext wCtx,
   String itemType,
   String itemKey)

Description

Returns a list of notifications for the specified item type and item key.

Arguments (input)

getNotificationAttributes

Java Syntax

public static WFTwoDArray getNotificationAttributes
  (WFContext wCtx,
   BigDecimal nid)

Description

Returns a list of notification attributes and their corresponding values for the specified notification ID.

Arguments (input)

Example

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);

WriteToClob

PL/SQL Syntax

procedure WriteToClob
  (clob_loc in out clob,
   msg_string in varchar2);

Description

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.

Arguments (input)

Related Topics

To Define a Document Attribute, Oracle Workflow Developer's Guide

"PL/SQL CLOB" Documents, Oracle Workflow Developer's Guide

Denormalize_Notification

PL/SQL Syntax

procedure Denormalize_Notification
  (nid in number, 
   username in varchar2 default null, 
   langcode in varchar2 default null);

Description

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 language in which the notification should be delivered matches the current session language, and stores the denormalized information according to this setting only if the languages match. You can indicate the language 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.

If the notification language and the current session language do not match, the procedure does not store any denormalized information. In this case, the viewing interface through which the notification recipients access notifications must check the language and perform the denormalization. The Oracle Workflow Worklist will perform these tasks for you if your users access their notifications through the Worklist Web pages.

Arguments (input)

SubstituteSpecialChars

PL/SQL Syntax

function SubstituteSpecialChars
  (some_text in varchar2) 
  return varchar2;

Pragmas

pragma RESTRICT_REFERENCES(SubstituteSpecialChars, WNDS);

Description

Substitutes HTML character entity references for special characters in a text string and returns the modified text including the substitutions.

You can use this function as a security precaution when creating a PL/SQL document or a PL/SQL CLOB document that contains HTML, to ensure that only the HTML code you intend to include is executed. If you retrieve any data from the database at runtime for inclusion in the document, use SubstituteSpecialChars() to replace any HTML tag characters in that data, so that those characters will not be interpreted as HTML code and executed.

Note that you should not substitute entity references for HTML tags that you include in the document yourself. Otherwise, the document will not be displayed with your intended HTML formatting. You only need to perform this substitution for data that is retrieved from the database at runtime, which may be entered from an external source.

The following table shows each special character and the entity reference with which it is replaced.

Arguments (input)

Notification Mailer Utility API

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.

Note: This package is only available if your database version is Oracle9i Database or higher. The Oracle8i Database does not support base64 encoding.

EncodeBLOB

PL/SQL Syntax

procedure EncodeBLOB 
  (pIDoc in blob,
   pODoc in out nocopy clob);

Description

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.

Note: This API is only available if your database version is Oracle9i Database or higher. The Oracle8i Database does not support base64 encoding.

Arguments (input)

Related Topics

Standard APIs for "PL/SQL" Documents, Oracle Workflow Developer's Guide

Copyright © 2003, 2005, Oracle. All rights reserved.

---

Previous Next

Home Book List Contents Index Master Index Feedback