Release 2.6.4
Part Number B15853-01
Contents
Previous
Next
| Oracle Workflow Developer's Guide Release 2.6.4 Part Number B15853-01 | Contents | Previous | Next |
Depending on the workflow process you wish to create, you need to define all or some of the following types of components to make up the process:
Note: When defining internal names for workflow objects in Oracle Workflow Builder, use only characters from the ASCII character set.
An item type is a classification of the components that make up a workflow process. You must associate any component that you create for a process, such as a function activity or a message, with a particular item type. Often it makes sense to define an item type so that it describes the item being managed by your workflow process. For example, purchase order requisition can be an item type while a purchase order requisition identified by a particular ID number is an item of that item type. See: To Create an Item Type.
An item type attribute is a property associated with a given item type. It acts as a global variable that can be referenced or updated by any activity within a process. An item type attribute often provides information about an item that is necessary for the workflow process to complete. For example, the "Workflow Demonstration" item type has an item type attribute called "Requisition Amount." An activity in our example Requisition Approval process requires the value of this item type attribute to determine if a selected approver has the authority to approve a requisition of that amount.
Applications as well as function activities can reference and set item type attributes using the Oracle Workflow Engine APIs. You can define and maintain as many item type attributes as necessary for an item type. You should define as an item type attribute, any information that will be required by an activity in your process, or any information that will need to be sent in a notification message. See: To Define a Message Attribute and Item Attributes, Oracle Workflow Administrator's Guide.
There are ten attribute types, as shown below. The type determines what values are acceptable and how the attribute is used.
Text - The attribute value is a string of text.
Note: Due to security considerations, Oracle Workflow does not permit HTML content to be passed in attributes of type text. If Oracle Workflow encounters HTML tags in a text attribute, escape characters will be applied to display the content as plain text rather than executing the HTML. If you want to apply HTML formatting to your content, define an attribute of type document instead, and pass your HTML content as either a PL/SQL document or PL/SQL CLOB document.
Number - The attribute value is a number with the optional format mask you specify.
Date - The attribute value is a date with the optional format mask you specify.
Lookup - The attribute value is one of the lookup code values in a specified lookup type.
Form - The attribute value is an Oracle Applications internal form function name and its optional form function parameters. This attribute type is not relevant for the standalone version of Oracle Workflow.
If you include a form-type attribute in a notification message as a message attribute, the notification, when viewed from the Notification Details Web page, displays an attached form icon that lets users drill down to the referenced form. See: Overview of Menus and Function Security, Oracle Applications Developer's Guide.
URL - The attribute value is a Universal Resource Locator (URL) to a network location. If you reference a URL attribute in a notification message as a message attribute, the notification, when viewed from the Notification Details Web page or as an HTML-formatted e-mail, displays a link to the URL specified by the URL attribute. The user can complete an activity or see additional information related to the activity by accessing that URL. You can also use a URL attribute to display an inline image in a notification message, when the notification is viewed from the Notification Details Web page or as an HTML-formatted e-mail.
Document - The attribute value is an attached document. You can specify the following types of documents in the default value field:
PL/SQL document - A document representing data from the database as a character string, generated from a PL/SQL procedure.
PL/SQL CLOB document - A document representing data from the database as a character large object (CLOB), generated from a PL/SQL procedure. The CLOB can contain plain text, HTML, an Adobe Acrobat Portable Document Format (PDF) document, a Microsoft Rich Text Format (RTF) document, or, if your database version is Oracle9i Database or higher, binary data encoded to base64.
PL/SQL BLOB document - A document representing data from the database as a binary large object (BLOB), generated from a PL/SQL procedure. The BLOB can contain an image or other types of application files that are stored as binary data.
Oracle Applications Framework region - In Oracle Applications, a JSP call to an Oracle Applications Framework region for inclusion in a notification message
Role - The attribute value is the internal name of a role. If a message attribute of type role is included in a notification message, the attribute automatically resolves to the role's display name, eliminating the need for you to maintain separate attributes for the role's internal and display names. Also when you view the notification from a Web browser, the role display name is a hypertext link to the e-mail address for that role. To set a default value for the attribute, you must initially load roles from the database. See: Roles.
Attribute - The attribute value is the internal name of another existing item type attribute that you want to maintain references to in a process.
Event - The attribute value is a Business Event System event message in the standard WF_EVENT_T structure. See: Event Message Structure, Oracle Workflow API Reference.
Note: If you store an event message in an item attribute of type event, you can access the event data within that event message by creating an item attribute of type URL and setting the value of the URL attribute to reference the event data. See: SetItemAttribute, Oracle Workflow API Reference.
When you define an item type, you must also specify its persistence type. The persistence type controls how long a status audit trail is maintained for each instance of the item type. If you set Persistence to Permanent, the runtime status information is maintained indefinitely until you specifically purge the information by calling the procedure WF_PURGE.TotalPerm().
If you set an item type's Persistence to Temporary, you must also specify the number of days of persistence ('n'). The status audit trail for each instance of a Temporary item type is maintained for at least 'n' days of persistence after its completion date. After the 'n' days of persistence, you can then use any of the WF_PURGE APIs to purge the item type's runtime status information. See: WF_PURGE, Oracle Workflow API Reference.
If you set an item type's Persistence to Synchronous, Oracle Workflow expects instances of that item type to be run as forced synchronous processes with an item key of #SYNCH. Forced synchronous processes complete in a single SQL session from start to finish and never insert into or update any database tables. Since no runtime status information is maintained, you do not normally need to perform any purging for a process with the Synchronous persistence type. However, if you run the process with a unique item key in asynchronous mode for testing or debugging purposes, Oracle Workflow does maintain runtime status information for that process instance. You can purge this information by changing the item type's Persistence to Temporary and running any of the WF_PURGE APIs. Then change the item type's Persistence back to Synchronous. See: Synchronous, Asynchronous, and Forced Synchronous Processes, Oracle Workflow API Reference, WF_PURGE, Oracle Workflow API Reference, and Purging for Performance, Oracle Workflow Administrator's Guide.
Note: In Oracle Applications, you may also use the Purge Obsolete Workflow Runtime Data concurrent program to purge obsolete item type runtime status information. The executable name for this concurrent program is "Oracle Workflow Purge Obsolete Data" and its short name is FNDWFPR. See: Purge Obsolete Workflow Runtime Data, Oracle Workflow API Reference.
If your item type has or will have more than one runnable process activity associated with it, define a PL/SQL function that determines which process activity to run in a particular situation. For example, you may have two different requisition approval process activities associated with the same item type. The process that Oracle Workflow executes may vary depending on how and where the requisition originates. Your selector function would determine which process would be appropriate in any given situation.
You can also extend the Selector function to be a general callback function so that item type context information can be reset as needed if the SQL session is interrupted during the execution of a process. This is particularly important in the Oracle Applications scenario when you view a notification from the Notification Details Web page and attempt to launch a form that is associated with the notification. Oracle Workflow calls the selector/callback function for your item type in 'TEST_CTX' mode to test the Oracle Applications context before turning the form launch over to the Oracle Application Object Library function security system. In 'TEST_CTX' mode, the selector/callback function can perform whatever logic necessary to determine whether it is appropriate to launch the form. See: Standard API for an Item Type Selector or Callback Function.
Documents have an enormous impact in the operations of an organization. With the explosion of digital media and the worldwide Web, electronic documents of a wide variety of formats, including non-printed media, are forcing organizations to address the management of these documents. The value of information in these documents can be maintained only if the documents can be managed and shared.
In a workflow process, you can attach documents generated by a PL/SQL procedure, which we call PL/SQL, PL/SQL CLOB, or PL/SQL BLOB documents. You attach a document to a workflow process by referencing the document in a predefined item attribute or message attribute of type Document. See: Attribute Types, To Define an Item Type or Activity Attribute, and To Define a Message Attribute.
For PL/SQL, PL/SQL CLOB, or PL/SQL BLOB documents, the item or message attribute's value would be the name of the PL/SQL package and procedure used to generate the document. The PL/SQL procedure must follow an Oracle Workflow standard interface. See: Standard APIs for "PL/SQL" Documents.
For PL/SQL and PL/SQL CLOB documents that contain text or HTML, the document generated by the PL/SQL procedure can either be displayed within the text of a notification or included as an attachment. Other types of content in PL/SQL CLOB documents, as well as all PL/SQL BLOB documents, can only be included as attachments.
In addition to text or HTML, PL/SQL CLOB documents that are included as attachments can contain PDF or RTF documents or, if your database version is Oracle9i Database or higher, binary data encoded to base64.
PL/SQL BLOB documents that are included as attachments can contain images or other application files that are stored as binary data.
In Oracle Applications, Oracle Workflow also supports using attributes of type document to embed an Oracle Applications Framework region in a notification. See: Embedding Oracle Applications Framework Regions in Messages.
Note: An Oracle Applications Framework region can only be displayed within the message body of a notification. It cannot be included as an attachment to the notification.
You can create an attribute for any of the following workflow process components:
Item type. See: To Define an Item Type or Activity Attribute.
Function activity. See: To Define an Item Type or Activity Attribute.
Event activity. See: To Define an Item Type or Activity Attribute.
Notification activity. See: To Define an Item Type or Activity Attribute.
Message. See: To Define a Message Attribute.
To Create an Item Type
Open an existing data store or, select New from the File menu to create a new data store to define this new item type. Then define a new item type in the navigator tree by choosing New Item Type from the Edit menu. An Item Type property page appears.
Item Type Property Page
Every item type has an all-uppercase internal name, which is a maximum of eight characters long. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying an item type.
Attention: To update the internal name for an item type once it is defined, you must use a special SQL script called wfchitt.sql. You should only use this script to correct errors in an item type's internal name during design time. Do not use this script to rename item types that are involved in running instances of processes. See: Wfchitt.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Enter a translatable Display Name that is longer and more descriptive. You can also supply a description for the item type.
Specify a persistence type of Temporary or Permanent. If you set the persistence type to Temporary, then specify the number of days from the time the item instance completes before its status audit trail can be purged. See: Persistence Type.
If your item type has or will have more than one workflow process associated with it, you may specify a selector function using the syntax <package_name>.<procedure_name>. The selector function is a PL/SQL stored procedure that automatically identifies the specific process definition the Workflow Engine should execute when a workflow is initiated for this item type. You can also extend the selector function to be a general callback function that resets context information each time the Workflow Engine establishes a new database session to execute activities. See: Standard API for an Item Type Selector or Callback Function.
Choose Apply to save your changes.
Select the Roles tab page to specify the roles that have access to this item type. (This functionality will be supported in a future release.)
Select the Access tab page to set the access and customization levels for this item type. See: Allowing Access to an Object.
Choose Apply to save your changes, OK to save your changes and close the property page or Cancel to cancel your changes and close the property page.
A secondary branch appears in the navigator tree that represents the item type you just created. You can review or edit the properties of this item type at any time by double-clicking on the item type in the navigator tree or by selecting the item type and choosing Properties from the Edit menu.
Define as many item type attributes as necessary to use as global variables in your process. You use these item type attributes to pass values to and from your function, notification, and event activities. See: To Define an Item Type or Activity Attribute.
To Define an Item Type or Activity Attribute
To create an item type attribute, select an item type in the navigator tree, then choose New Attribute from the Edit menu.
Item Type Attribute Property Page
To create an activity attribute, select an activity in the navigator tree and choose New Attribute from the Edit menu.
Activity Attribute Property Page
An Attribute property page appears in both cases.
Provide an Internal Name in all uppercase with no leading/trailing spaces. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying an attribute.
Attention: To update the internal name for an attribute once it is defined, you must use special SQL scripts called wfchita.sql and wfchacta.sql. You should only use these scripts to correct errors in an attribute's internal name during design time. Do not use these scripts to rename attributes that are involved in running instances of processes. See: Wfchita.sql, Oracle Workflow Administrator's Guide and Wfchacta.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Enter a Display Name. This is the name that appears in the navigator tree.
Enter an optional description.
Select the data type of the attribute. Form, URL, and document data types are not relevant if you are defining an activity attribute.
Depending on the data type of your attribute, provide the following default value information:
Text - Specify the maximum length of the text attribute and an optional default text string.
Number - Optionally provide a format mask for your number and a default value.
Date - Optionally supply a format mask for the date and a default value.
Lookup - Choose a predefined Lookup Type from which to draw values. Choose a lookup code from that lookup type for the default value.
URL - Specify an optional Universal Resource Locator (URL) to a network location in the Default Value field and specify the frame target for the URL. See: To Define a URL Attribute.
Note: The Frame Target field is applicable only for message attributes of type URL. It is not used for item type attributes or activity attributes.
Form - This attribute is relevant only for the version of Oracle Workflow embedded in Oracle Applications.
Specify an optional developer form function name and optional argument strings (form function parameters) in the Default Value field. See: Overview of Menus and Function Security, Oracle Applications Developer's Guide and To Define a Form Attribute.
Document - Enter an optional string that identifies the document in the default value field. See: To Define a Document Attribute.
Note: The Frame Target field is not applicable for attributes of type document. For document attributes, this field is reserved for future use.
Role - Specify a role name. See: Roles.
Attribute - Specify the name of an item type attribute that you want to maintain references to in a process by choosing from the list of existing item type attributes.
Event - If you are defining an item type attribute, you cannot specify any default value for an event attribute. If you are defining an activity attribute, you can only specify an event item type attribute as the default value.
For item type attributes, the optional default value is a constant that you enter or select from a list of values. The constant, however, may be a text string that allows for token substitution at runtime.
For activity attributes, the optional default value may be a constant or an item type attribute. If you want the default to acquire its entire value from an item type attribute, choose Item Attribute in the Default Value region, then use the adjacent poplist field to choose the item type attribute. The item type attribute you select must be associated with the same item type that the activity itself is associated with. The item type attribute you select must also be of the same data type as the activity attribute.
Note: An activity attribute type of 'Text' is compatible with any item attribute type except the event type. All other activity attribute types must match the item attribute type exactly.
Note: For attributes of type Lookup, the default value must be a lookup code belonging to that lookup type.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
If you are defining an item type attribute, select the Access tab page to set the access levels allowed to modify this attribute. Activity attributes assume the access/protection level of their parent activity. See: Allowing Access to an Object.
Choose Apply to save your changes.
Any item type attribute you create appears beneath the Attributes branch in the navigator tree. Any function activity attribute you define appears beneath the activity you defined it for in the navigator tree. You can review or edit the properties of an attribute at any time by double-clicking on the attribute in the navigator tree or by selecting the attribute and choosing Properties from the Edit menu.
Attention: The order in which you list these attributes in the navigator tree correlate to the order in which they appear in any list of values that draw upon these attributes. You can use the drag and drop feature of the navigator tree to reorder a set of attributes, or select an attribute and choose Move Attribute Up or Move Attribute Down from the Edit menu.
To Define a URL Attribute
Specify a Universal Resource Locator (URL) to a network location in the Default Value field of the Attribute property page. The URL can be a constant or a value returned from another item attribute.
Note: If you define a URL attribute that points to an Oracle Applications Framework-based Web page, that page must use the self-secured security mode. A page that relies on the user session in its security mode may not be accessible when a user navigates to the URL from an e-mail notification. For more information about Oracle Applications Framework pages, refer to OracleMetaLink note 269138.1, Oracle Applications Framework Developer's Guide.
You can include argument strings in your URL that are text strings. Additionally, if you are defining a message attribute of type URL, you can include argument strings that are token substituted with other message attributes. The message attributes used for token substitution can have constant values or can reference the values returned from item type attributes. See: To Define a Message Attribute and To Token Substitute an Attribute.
To token substitute other message attributes in an argument string, specify the message attributes as follows:
-&message_attr-
For example, the following string represents a URL with two arguments called arg1 and arg2 that are token substituted with the runtime value of message attributes msgattr1 and msgattr2, respectively:
http://www.oracle.com?arg1=-&msgattr1-&arg2=-&msgattr2-Note: If you are defining a message attribute of type URL, you can also include a special token in your argument string called -&#NID- which Oracle Workflow substitutes with the notification ID of the runtime notification.
If your URL attribute contains an argument string, you must adhere to the following restrictions:
You cannot token substitute that argument string with another item attribute of type Document.
You can token substitute that argument string with another Form attribute or URL attribute. However, the argument string for the other attribute is not further token substituted.
If you need to pass a date and time as an argument to a URL, you should use TO_CHAR to format the string as YYYY/MM/DD+HH24:MI:SS. Similarly, you need to do the correlating format translation in the function that the URL calls, using TO_DATE. This formatting is required because in multibyte databases, the month portion of the DD-MON-YYYY format could potentially translate to a value that is not acceptable across a URL.
You can also use a URL attribute to include an image in a notification. Define a 'Send' message attribute of type URL that points to an image file with an extension of gif, jpg, png, tif, bmp, or jpeg. Then use a message attribute token to include the URL attribute in the HTML message body. When the notification is viewed from the Notification Details Web page or as an HTML-formatted e-mail, the image appears inline in the message body.
When defining a URL attribute to point to such an image, you must provide the complete URL for the image, either as a constant or as a value returned from another item attribute. You cannot token substitute any argument strings within the image URL.
Note: Oracle Workflow displays images only in the message body of a notification. If you check Attach Content for a URL attribute that points to an image file, the URL attribute appears as an attached link, just as other URLs do.
Also, Oracle Workflow displays images only in the HTML-formatted versions of a notification. A plain text e-mail notification displays all URL attributes as the display name of the attribute, followed by a colon and the URL.
In Oracle Applications, if you are defining a URL attribute that links to an Oracle Applications Framework page, the page must have the security mode Self secured. This security mode is required to ensure that the page can be accessed properly if the URL link is included in an e-mail notification.
By default, when a user chooses an attached URL link to an Oracle Applications Framework page in a notification, Oracle Applications displays a list of responsibilities assigned to that user that include that page. The user can then select the responsibility with which he or she wants to navigate to the page. When navigating from an e-mail notification, the user must also log into Oracle Applications before selecting a responsibility.
When you define a URL attribute for an Oracle Applications Framework page, you can optionally specify the responsibility through which you want users to access that page. In this case, users do not need to select a responsibility when they choose the attached URL link; instead, they can navigate directly to the page. However, you must ensure that the users who receive the notification have the specified responsibility assigned to them. Otherwise they will not be able to access the page from that attached URL link.
To specify a responsibility in the URL attribute, append two special arguments in the argument string for the URL.
#RESP_KEY - The responsibility key
#APP_SHORT_NAME - The application short name for the responsibility
The value for each of these arguments can be a text string enclosed in quotes (" ") or can be token substituted with another item type attribute using the following format: "&ITEM_ATTR"
Choose OK when you are done.
To Define a Form Attribute
Specify a developer form function name and any optional argument string (form function parameters) in the Default Value field of the form Attribute property page.
The default value must be entered using the following format:
function_name:arg1=value1 arg2=value2 ...argN=valueN
The value of argN can be a text string enclosed in quotes (" ") or can be token substituted with another item type attribute in any of the following ways, where &item_attr represents the internal name of the item type attribute:
argN="&item_attr"argN="Value &item_attr" See: To Token Substitute an Attribute.
Note: If you are defining a message attribute of type Form, you can also include a special token in your argument string called &#NID which Oracle Workflow substitutes with the notification ID of the runtime notification.
If your form attribute contains an argument string, you must adhere to the following restrictions:
You cannot token substitute the value of argN with another item attribute of type Document.
You can token substitute the value of that argument string with another Form attribute or URL attribute; however, the argument string for the other attribute is not further token substituted.
By default, when a user chooses an attached form link in a notification, Oracle Applications displays a list of responsibilities assigned to that user that include that form. The user can then select the responsibility with which he or she wants to navigate to the form. When navigating from an e-mail notification, the user must also log into Oracle Applications before selecting a responsibility.
When you define a form attribute, you can optionally specify the responsibility through which you want users to access that form. In this case, users do not need to select a responsibility when they choose the attached form link; instead, they can navigate directly to the form. However, you must ensure that the users who receive the notification have the specified responsibility assigned to them. Otherwise they will not be able to access the form from that attached form link.
To specify a responsibility in the form attribute, append two special arguments in the argument string for the form function.
#RESP_KEY - The responsibility key
#APP_SHORT_NAME - The application short name for the responsibility
The value for each of these arguments can be a text string enclosed in quotes (" ") or can be token substituted with another item type attribute using the following format: "&ITEM_ATTR"
For example, the following form attribute value specifies that the Users form should be opened from the System Administration responsibility.
FND_FNDSCAUS:#RESP_KEY="SYSTEM_ADMINISTRATION" #APP_SHORT_NAME="SYSADMIN"
Choose OK when you are done.
To Define a Document Attribute
Enter a string that identifies the document in the default value field of the Attribute property page.
You can identify the following types of document for a document attribute:
A PL/SQL document
A PL/SQL CLOB document
A PL/SQL BLOB document
An Oracle Applications Framework region (Oracle Applications only)
A PL/SQL document represents data from the database as a character string, generated from a PL/SQL procedure. Specify the default value of a PL/SQL document as
plsql:<procedure>/<document_identifier> Replace <procedure> with the PL/SQL package and procedure name, separated by a period. Replace <document_identifier> with the PL/SQL argument string that you want to pass directly to the procedure. The argument string should identify the document.
Note: The PL/SQL procedure must follow a standard API format. See: Standard APIs for "PL/SQL" Documents.
For example, the following string represents the PL/SQL document po_req:2034, generated by the procedure po_wf.show_req.
plsql:po_wf.show_req/po_req:2034
Note: The maximum length of the data that a PL/SQL document can contain is 32 kilobytes. If you expect your document to exceed 32 Kb, you should use a PL/SQL CLOB document to hold the data instead.
A PL/SQL document can either be displayed in the message body of a notification or included as an attachment to the notification.
A PL/SQL CLOB document represents data from the database as a character large object (CLOB), generated from a PL/SQL procedure. Specify the default value of a PL/SQL CLOB document as
plsqlclob:<procedure>/<document_identifier>Replace <procedure> with the PL/SQL package and procedure name, separated by a period. Replace <document_identifier> with the PL/SQL argument string that you want to pass directly to the procedure. The argument string should identify the document.
Note: The PL/SQL procedure must follow a standard API format. See: Standard APIs for "PL/SQL" Documents.
For example, the following string represents the PL/SQL CLOB document, po_req:2036, generated by the procedure po_wf.show_req_clob.
plsqlclob:po_wf.show_req_clob/po_req:2036
A PL/SQL CLOB document that contains text or HTML can either be displayed in the message body of a notification or included as an attachment to the notification.
PL/SQL CLOB documents do not support further substitution of message attribute tokens. The text or HTML contents of the CLOB are printed in a message body just as they are generated by the PL/SQL procedure.
Do not use tokens within the CLOB.
Ensure that the PL/SQL procedure performs any formatting you require.
A PL/SQL CLOB document that you include as an attachment to a notification can also contain a PDF or RTF document or, if your database version is Oracle9i Database or higher, other binary data encoded to base64. You should first store the document in the database as a binary large object (BLOB) and then convert the document into a CLOB as part of the PL/SQL procedure you use to produce the CLOB. See: Standard APIs for "PL/SQL" Documents.
You can use the UTL_RAW.Cast_To_VARCHAR2 function to convert PDF or RTF data from the BLOB into VARCHAR2 data that you write to a CLOB. If your database version is Oracle9i Database or higher, you can optionally use the WF_MAIL_UTIL.EncodeBLOB procedure to encode the binary data to base64. See: UTL_RAW, Oracle Supplied PL/SQL Packages and Types Reference and EncodeBLOB, Oracle Workflow API Reference.
Note: Oracle8i Database does not support base64 encoding, so if you are using Oracle8i Database, the WF_MAIL_UTIL.EncodeBLOB procedure is not available, and you cannot store binary data other than PDF or RTF documents in a PL/SQL CLOB document. This feature is available only if you are using Oracle9i Database and higher.
However, both Oracle8i Database and Oracle9i Database and higher support the UTL_RAW.Cast_To_VARCHAR2 function, so you can store PDF and RTF documents in an attached PL/SQL CLOB document on any of these database versions.
A PL/SQL BLOB document represents data from the database as a binary large object (BLOB), generated from a PL/SQL procedure. Specify the default value of a PL/SQL BLOB document as
plsqlblob:<procedure>/<document_identifier>
Replace <procedure> with the PL/SQL package and procedure name, separated by a period. Replace <document_identifier> with the PL/SQL argument string that you want to pass directly to the procedure. The argument string should identify the document.
Note: The PL/SQL procedure must follow a standard API format. See: Standard APIs for "PL/SQL" Documents.
For example, the following string represents the PL/SQL BLOB document po_req:2038, generated by the procedure po_wf.show_req_blob.
plsqlblob:po_wf.show_req_blob/po_req:2038
PL/SQL BLOB documents do not support further substitution of message attribute tokens.
A PL/SQL BLOB document can contain an image or an application file stored as binary data, such as a PDF or RTF document or other types of files. You can include a PL/SQL BLOB document as an attachment to a notfication. However, this type of document cannot be displayed in the message body of a notification.
If you wish to generate the document identifier for a PL/SQL, PL/SQL CLOB, or PL/SQL BLOB document dynamically, you can token substitute the document identifier with other item type attributes. The item attribute names must be in uppercase and must be separated by a colon. See: To Token Substitute an Attribute.
For example:
plsql:po_wf.show_req/&ITEM_ATTR1:&ITEM_ATTR2
Note: If you are defining a message attribute of type Document, you can also include a special token in your argument string called &#NID which Oracle Workflow substitutes with the notification ID of the runtime notification.
You can also use an attribute of type document to reference an Oracle Applications Framework region that you want to embed in a notification message. Specify the JSP call to reference the region as the default value for the attribute. See: Embedding Oracle Applications Framework Regions in Messages.
An Oracle Applications Framework region can only be displayed within the message body of a notification. It cannot be included as an attachment to the notification.
Choose OK when you are done.
To Copy an Item Type
Drag the item type, holding down your select mouse button, to the data store or workspace you want to copy it to.
You can also use the Copy and Paste commands in the Edit menu.
If you copy this item type back to the same data store, you get prompted to enter a new internal and display name for the item type in the Item Type property page. This is because every item type must have a unique internal and display name. When you are done, choose OK.
Note that when you copy an item type, you also copy all the components associated with the item type. Since most components must also have unique internal and display names, you may get prompted to update those components' internal and display names in their property pages as well.
If you copy an item type to a data store where a previous version of the same item type already exists, you update the existing version of the item type in that target data store with the changes in the version of the item type you are copying.
Attention: The order in which you drag two or more item types to a new store is important. For example, suppose an item type references objects in the Standard item type. If you plan to copy that item type and the Standard item type to a new data store, you should first drag the Standard item type to the new data store before dragging the other item type over; otherwise the other item type will have unresolved references to the Standard item type.
To Copy an Attribute
Drag the attribute, holding down your select mouse button, to the component branch you want to copy it to.
If you copy an attribute to a component associated with the same item type, the property page for the attribute appears.
Enter a new unique internal name and display name for the attribute.
When you are done, choose OK.
Note: You can also use the Copy and Paste options in the Edit menu.
Related Topics
Using the Edit Button in a Property Page
Access Property Page
In the Access tab page, the 'Range of Editable Access Levels' indicator bar provides a relative indication of the range of access levels that can edit the object. The shaded area represents the access levels that can edit the object, while the vertical bar represents your current access level. See: Overview of Oracle Workflow Access Protection, Oracle Workflow Administrator's Guide.
The indicator bar can be shaded solid green, or shaded with any combination of solid green and crosshatch grey. If the "Allow modifications of customized objects" check box in the "About Oracle Workflow Builder" dialog box of the Help menu is:
Checked - The range of editable access levels can appear as a combination of solid green and crosshatch grey areas. The levels depicted by grey crosshatches represent levels that usually cannot modify customized objects, but can now do so because Oracle Workflow Builder is operating in 'upload' mode. Upload mode means that Oracle Workflow Builder can save your edits, overwriting any protected objects that you have access to modify as well as any previously customized objects.
Unchecked - The range of editable access levels appears as a solid green area. This indicates that when you save your work, Oracle Workflow Builder is operating in 'upgrade' mode, only saving edits to protected objects that you have access to change and leaving objects that have been previously customized untouched.
These two modes match the upgrade and upload behavior of the Workflow Definitions Loader program. See: To Set the Access Level for an Object and Using the Workflow Definitions Loader, Oracle Workflow Administrator's Guide.
To Set the Access Level for an Object
Select the Access tab of the property page.
In the Options region, use the 'Preserve Customizations' and 'Lock at this Access Level' check boxes to define the access levels that can modify this object. The options that you check in this region directly affect the values that appear in the Levels region.
The following table illustrates how the customization and protection levels of an object are affected when you check different combinations of these options. This table assumes that the user setting the options has an access level of 100.
| Selected Checkbox | Resulting Levels | Levels Allowed to Modify the Object |
|---|---|---|
| NONE - Object can be updated at any time, by anyone. | Customization = 0, Access = 100, Protection = 1000 | Object may be updated by any access level (0-1000). |
| Preserve Customizations - Disallow customized objects from being overwritten during a workflow definition upgrade. | Customization = 100, Access = 100, Protection = 1000 | Object may only be updated by access levels from 100-1000. If the "Allow modifications of customized objects" checkbox is checked, customized objects can also be updated by access levels 0-99, as represented by grey crosshatches in the indicator bar. |
| Lock at this Access Level - Protect the object at the current access level and do not allow the object to be customized. | Customization = 0, Access = 100, Protection = 100 | Object may only be updated by access levels from 0-100. |
| BOTH - Object can only be updated by the access level at which the object is protected. | Customization = 100, Access = 100, Protection = 100 | Object cannot be updated by any access level other than 100. If the "Allow modifications of customized objects" checkbox is checked, customized objects can also be updated by access levels 0-99, as represented by grey crosshatches in the indicator bar. |
Choose the Apply button to save your changes.
Note: An object appears with a small red lock over its icon in the navigator tree to indicate that it is a read-only object if you are operating at an access level that does not have permission to edit an object, that is, your access level is in a white area of the 'Range of Editable Access Levels' indicator bar.
A lookup type is a static list of values. These lists can be referenced by activities and by item type, message or activity attributes. For example, an activity can reference a lookup type for its possible result values, while a message attribute can reference a lookup type as a means of providing a list of possible responses to the performer of a notification.
When you define a lookup type, you associate it with an particular item type. However, lookup types are not item type specific; when you create an activity or an attribute, you can reference any lookup type in your current data store, regardless of the item type that the lookup type is associated with.
To Create Lookup Types
Select an item type from the navigator tree and choose New Lookup Type from the Edit menu. A Lookup Type property page appears.
Lookup Type Property Page
Lookup types have an all-uppercase Internal Name with no leading/trailing spaces and a translatable Display Name. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying a lookup type.
Attention: To update the internal name for a lookup type once it is defined, you must use a special SQL script called wfchlut.sql. You should only use this script to correct errors in a lookup type's internal name during design time. Do not use this script to rename lookup types that are involved in running instances of processes. See: Wfchlut.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
You can supply an optional description for this lookup type.
Select the Access tab page to set the access levels allowed to modify this lookup type. See: Allowing Access to an Object.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
The lookup type you just defined now appears beneath the Lookup Types branch in the navigator tree. You can review or edit the properties of this lookup type at any time by double-clicking on the lookup type in the navigator tree or by selecting the lookup type and choosing Properties from the Edit menu.
Now define the lookup codes for your lookup type. See: To Create Lookup Codes for a Lookup Type.
To Create Lookup Codes for a Lookup Type
Select a lookup type from the navigator tree and choose New Lookup Code from the Edit menu. A Lookup Code property page appears.
Lookup Code Property Page
Enter an Internal Name with no leading/trailing spaces and a Display Name for the lookup code. You can also enter an optional description. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying a lookup code.
Attention: To update the internal name for a lookup code once it is defined, you must use a special SQL script called wfchluc.sql. You should only use this script to correct errors in a lookup code's internal name during design time. Do not use this script to rename lookup codes that are involved in running instances of processes. See: Wfchluc.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
The lookup code you just defined now appears beneath the lookup type you created it for in the navigator tree. You can review or edit the properties of this lookup code at any time by double-clicking on the lookup code in the navigator tree or by selecting the lookup code and choosing Properties from the Edit menu.
Repeat steps 1, 2, and 3 if you wish to create additional lookup codes for a specific lookup type.
To Copy a Lookup Type
Use the Copy and Paste options in the Edit menu to copy and paste the lookup type to the item type you want. You can also drag and drop the lookup type to the item type you want.
If you copy a lookup type back to the same item type, or if you copy a lookup type to an item type in a different data store when the lookup type already exists in any item type in that data store, then the property page appears for you to enter a unique internal and display name for the new lookup type. When you are done, choose OK.
If you copy a lookup type to an item type in a different data store, and that lookup type does not yet exist in any item type in that data store, then the new lookup type is copied with the same internal and display name as the original. You do not have to enter new names.
Note: Copying a lookup type also copies any lookup codes assigned to it.
Note: You cannot use the Copy and Paste options to copy a lookup type to another item type in the same data store. However, you can drag and drop a lookup type to another item type in the same data store; by doing so, you actually move the lookup type to the new item type.
To Copy a Lookup Code
Hold down your mouse select button as you drag the lookup code to the lookup type you want to copy it to.
If you drag the lookup code to the same lookup type or to a lookup type where this code already exists, then when you release your mouse button, a properties page appears for you to enter a unique internal and display name the new lookup code. When you are done, choose OK.
Note: You can also use the Copy and Paste options in the Edit menu.
The Messages branch of the navigator tree lists all available workflow messages for the current item type.
A message is what a notification activity sends to a role in a workflow process. A message can prompt a user for a reply or an action to take that determines what the next activity in the process should be. The recipient of a workflow message is called the performer.
Each message is associated with a particular item type. This allows the message to reference the item type's attributes for token replacement at runtime when the message is delivered.
When you define a message, you can specify that the message prompts a recipient for a special response value that the Workflow Engine then uses to determine how to branch to the next eligible activity in the process. You can create a message with context-sensitive content by including message attribute tokens in the message subject and body that reference item type attributes. You can also use message attribute tokens to embed inline images in the message body. A message function lets you include a formatted table of message attributes or an action history table in the message body. You can also attach message attributes that represent entire documents or URLs to a notification message. In addition, you can create message attributes that generate a response section that is unique to the message. In Oracle Applications, you can also embed an Oracle Applications Framework region within the message body.
You can drag a message onto the Notifications branch to create a new notification activity that sends that message. You can also drag a message directly onto an existing notification activity to update the message that the activity sends.
When you create a message for a notification activity, you should make note of whether the notification activity has a Result Type specified. If it does, then the message you create needs to prompt the notification recipient for a special response that is interpreted as the result of the notification activity. The Workflow Engine uses that result to determine how it should branch to the next eligible activity in the process.
To create a message that prompts for this special response, complete the Result tab in the message's property page. The information you enter creates a special 'Respond' message attribute for the message that has an internal name of RESULT. The RESULT message attribute has a data type of Lookup and must be set to the same lookup type as the notification activity's Result Type. This ensures that the performer of the notification can choose from a list of possible response values that matches the list of possible results that the notification activity is expecting. See: Send and Respond Message Attributes.
Once you create a message, you can define as many message attributes as necessary for that message. Message attributes are listed beneath a message in the navigator tree.
The source (Send or Respond) of a message attribute determines how the message attribute is used. When you define a message attribute with a source of 'Send', you can embed the message attribute in the subject and/or body of the message for token substitution. In addition, you can attach the message attribute to the message when the notification is sent.
Each message attribute has a specific data type. The value of a 'Send' message attribute can be a constant or can be a value returned by an item type attribute of that same data type. To embed a message attribute in a message's subject or body for token substitution, specify the internal name of the message attribute using the format &MESGATTR within the subject or body text.
Note: You should not embed a message attribute of type Document in a message's subject, since Document message attributes cannot be token substituted in the subject. Document message attributes embedded in the subject will be ignored.
You can, however, embed Document message attributes within the body of a message for token substitution.
A message attribute defined with a source of 'Respond' constitutes the response section of a message. A 'Respond' message attribute provides instructions that prompts a recipient for a response. When you define a 'Respond' message attribute, you must specify the data type of the attribute. You can also provide an optional default value for the response. The default value can be a constant or a value returned from an item type attribute of the same data type.
You can define 'Respond' message attributes of type URL or form if you want the notification recipient to respond to the notification through the specified Web page or form. In this case that custom Web page or form must mark the notification as closed and include a call to the Workflow Engine CompleteActivity() API to inform the Workflow Engine when the notification response is complete. Also, you must not define any 'Respond' message attributes of other types. Any response values that are required must be entered in the specified Web page or form. See: CompleteActivity, Oracle Workflow API Reference.
In Oracle Applications, if you define 'Respond' message attributes of type URL or form, the Notification Details page will display only the URL response links or form response icons and will not display any other response fields. However, users will still be able to reassign or request more information for the notification as usual, if the notification is defined to allow those options.
See: Message Attributes, Oracle Workflow Administrator's Guide.
A notification can include an action history table that shows what actions users have performed on the notification to date. The action history table contains a row for each previous execution of the same notification activity node in a process, as well as a row for the initial submission of the process. For example, for a requisition approval notification activity that sends a certain notification to several approvers in turn, the action history table would contain a row for each approver to whom the notification was sent, as well as a row for the process owner. Additionally, if a notification is reassigned to another user in either delegate or transfer mode, or if one user requests more information about the notification and another user answers that request, the action history contains rows for those actions also.
If the notification requires a response, then Oracle Workflow automatically includes the action history table in the notification.
If the notification does not require a response, then Oracle Workflow only includes the action history table automatically if the notification has been reassigned at least once or if at least one recipient has requested more information about the notification. However, you can manually include the action history table by calling the special message function WF_NOTIFICATION(HISTORY) in the message body.
The formatting of the action history table depends on whether the notification contains an embedded Oracle Applications Framework region.
If the notification contains an Oracle Applications Framework region, or if it contains only plain text and calls to the special WF_NOTIFICATION() message function, the table is formatted as an Oracle Applications Framework region.
If the notification does not contain any Oracle Applications Framework regions, but does contain references to other types of message attributes, then the table is formatted in a standard Oracle Workflow format. This category includes all notifications in standalone Oracle Workflow as well as any Oracle Applications notifications that reference values other than Oracle Applications Framework regions.
The standard action history table provided by Oracle Workflow includes the following columns:
Num - A sequence number indicating the order in which the actions on this notification took place, beginning at one (1) for the initial submission of the process by the process owner.
Action Date - The date that a user acted on the notification.
Action - The action performed on the notification.
From - The user who performed the action.
To - The next user who must act on the notification as a result of this action. For example, the next approver, the user to whom the notification was reassigned, or the user from whom more information was requested.
Details - An additional note from the user who performed the action. To allow a recipient to add a note for the action history table while responding, you must create a special 'Respond' message attribute with the internal name WF_NOTE.
Define the message attribute with the following properties:
Internal Name - WF_NOTE
Display Name - Note
Description - Note
Type - Text
Source - Respond
When the WF_NOTE attribute is defined with a source of 'Respond', it appears as part of the notification response section, and the recipient can enter a note there when responding to the notification. Oracle Workflow retrieves the note text stored in the WF_NOTE attribute and displays it in the action history table.
If the responder did not enter a note, or if the WF_NOTE message attribute was not defined for the notification, then the Note column in the action history table is left blank.
Oracle Workflow also lets users enter notes while reassigning a notification, requesting more information, or answering a request for more information. These notes are likewise displayed in the action history table.
To allow the process owner to add a note for the action of submitting the process and sending the initial notification, you must define a special message attribute named #SUBMIT_COMMENTS. See: #SUBMIT_COMMENTS Attribute.
You can optionally create a custom action history table to replace the standard action history table, using the special message attribute named #HISTORY. Your custom action history table must be formatted as an Oracle Applications Framework region, PL/SQL document, or PL/SQL CLOB document. See: #HISTORY Attribute, Embedding Oracle Applications Framework Regions in Messages, and WF_NOTIFICATION() Message Function.
In addition to message attribute tokens, you can also use a special message function called WF_NOTIFICATION() to add context-sensitive content to a message body. Depending on the parameters you provide, the WF_NOTIFICATION() function can produce either a table of message attributes or an action history table for the notification.
In Oracle Applications, the tables are created as Oracle Applications Framework regions, unless the message body also includes any message attribute tokens that reference values other than Oracle Applications Framework regions. In this case, the tables are created in a standard Oracle Workflow format. See: Embedding Oracle Applications Framework Regions in Messages.
In standalone Oracle Workflow, the tables are always created in the standard Oracle Workflow format.
Note: WF_NOTIFICATION() is not a PL/SQL function, but rather a special message function that can only be called within an Oracle Workflow message body.
To include a table of message attributes in a message body, call WF_NOTIFICATION() with the ATTRS option followed by the internal names of the message attributes, separated by commas. Use the following format:
WF_NOTIFICATION(ATTRS,<attribute1>,<attribute2>,<attribute3>,...)
Note: You must not include any spaces or carriage returns in the call to WF_NOTIFICATION(). You only need to use a comma to delimit the parameters in the list.
The message attribute table contains a row for each message attribute listed in the WF_NOTIFICATION() call, showing the display name and the value for each attribute.
To include an action history table in a message body, call WF_NOTIFICATION() with the HISTORY option in the following format:
WF_NOTIFICATION(HISTORY)
The action history table contains the standard action history information provided by Oracle Workflow, unless you have defined the #HISTORY attribute for a message in Oracle Applications to use a custom action history region instead. See: Action History and #HISTORY Attribute.
In Oracle Applications, you can use a special message attribute with the internal name #WF_REASSIGN_LOV to specify the users to whom a message can be reassigned. Create a role whose members are all the users that you want to allow as possible new recipients when the notification is reassigned, and assign this role as the value for the #WF_REASSIGN_LOV attribute. Then, when the notification recipient attempts to reassign the notification, only the users that belong to that role will appear in the list of values for the Assignee field. See: To Reassign a Notification to Another User (for Oracle Applications), Oracle Workflow User's Guide.
The #WF_REASSIGN_LOV attribute must be of type role and must have a source of Send. You can either specify a particular role as a constant value for the #WF_REASSIGN_LOV attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically sets that item type attribute to the role you want at runtime. If no existing role meets your needs, you can include logic in your process to create an ad hoc role at runtime and add the users you want to that role. See: CreateAdHocRole, Oracle Workflow API Reference and AddUsersToAdHocRole, Oracle Workflow API Reference.
Note: The Worklist pages that support the #WF_REASSIGN_LOV attribute are currently available only for the version of Oracle Workflow embedded in Oracle Applications.
You can use a special message attribute with the internal name #HIDE_REASSIGN to hide the Reassign button in the Notification Details Web page. The response section in the Notification Details page includes the Reassign button by default. If you want to restrict users from reassigning a notification, you can add the #HIDE_REASSIGN attribute to control whether the Reassign button is displayed or hidden. See: To Reassign a Notification to Another User (for standalone Oracle Workflow), Oracle Workflow User's Guide or To Reassign a Notification to Another User (for Oracle Applications), Oracle Workflow User's Guide.
Note: In Oracle Applications, the Notification Details page may include the Delegate button or the Transfer button instead of the Reassign button, depending on the setting of the WF: Notification Reassign Mode profile option. The #HIDE_REASSIGN attribute controls the Delegate button and the Transfer button in the same way as the Reassign button. See: Setting the WF: Notification Reassign Mode, Oracle Workflow Administrator's Guide.
In Oracle Applications, the #HIDE_REASSIGN attribute also controls whether a notification can be reassigned using the Reassign button in the Advanced Worklist, Personal Worklist, or self-service home page. The Reassign button in these pages will still be displayed, but an error message will appear if users attempt to reassign notifications for which the #HIDE_REASSIGN attribute has been set. See: To View Notifications from the Advanced Worklist, Oracle Workflow User's Guide and To View Notifications from the Personal Worklist, Oracle Workflow User's Guide.
Additionally, with this attribute you can specify whether or not the notification can still be reassigned through vacation rules. You can choose to both hide the Reassign button and prevent reassignment through vacation rules. In this case Oracle Workflow does not apply any vacation rules to reassign those notifications, but simpy delivers the notifications to the worklist of the original recipient. You can also choose to hide the Reassign button but still allow reassignment through vacation rules.
The #HIDE_REASSIGN attribute must be either of type text or lookup.
To hide the Reassign button in the Notification Details page, and to prevent reassignment from the Advanced Worklist, Personal Worklist, and self-service home page, as well as through vacation rules, set the value of this attribute to Y.
To hide the Reassign button in the Notification Details page, and to prevent reassignment from the Advanced Worklist, Personal Worklist, and self-service home page, but still allow reassignment through vacation rules, set the value of this attribute to B.
To display the Reassign button in the Notification Details page, and to allow reassignment from the Advanced Worklist, Personal Worklist, self-service home page, and vacation rules, set the value to N.
Note: If you want to prevent reassignment in all cases, it is recommended to define the #HIDE_REASSIGN attribute with a type of lookup and assign it the predefined Yes/No lookup type that is provided in the Standard item type. The Yes/No lookup type contains two lookup codes with the display names Yes and No, representing the values Y and N, respectively. However, if you want to set the value to B, you must either define the attribute with a type of text or define a custom lookup.
If you always want to restrict reassignment for notifications using a particular message, specify the value Y or B as a constant.
If you only want to restrict reassignment in certain cases, specify an item type attribute as the value. Then include logic in your workflow process that dynamically determines at runtime whether reassignment should be permitted or restricted and sets the item type attribute to Y, B, or N, accordingly.
In Oracle Applications, you can use a special message attribute with the internal name #HIDE_MOREINFO to hide the Request Information button in the Notification Details page. When users view a notification that requires a response from their Worklist page, the response region in the Notification Details page includes the Request Information button by default. If you want to prevent users from requesting more information about a notification, you can add the #HIDE_MOREINFO attribute to control whether the Request Information button is displayed or hidden.
Note: In both the standalone version of Oracle Workflow and the Oracle Applications version of Oracle Workflow, the #HIDE_MOREINFO attribute also determines whether the Request Information response link is included or excluded in HTML-formatted e-mail notifications. However, note that if the #HIDE_MOREINFO attribute is not defined for a particular notification, the default behavior is different for the Notification Details page and for HTML-formatted e-mail notifications. The Notification Details page displays the Request Information button if the #HIDE_MOREINFO attribute is not defined, while an HTML-formatted e-mail notification will exclude the Request Information response link by default if the #HIDE_MOREINFO attribute is not defined. To control this option in all interfaces where users access notifications, you should explicitly define and set the #HIDE_MOREINFO attribute. See: To Respond to an HTML E-mail Notification, Oracle Workflow User's Guide
The #HIDE_MOREINFO attribute must be either of type text or lookup. To hide the Request Information button, set the value of this attribute to Y. To display the Request Information button, set the value to N.
Note: It is recommended to define the #HIDE_MOREINFO attribute with a type of lookup and assign it the predefined Yes/No lookup type that is provided in the Standard item type. The Yes/No lookup type contains two lookup codes with the display names Yes and No, representing the values Y and N, respectively.
If you always want to hide the Request Information button for notifications using a particular message, specify the value Y as a constant.
If you only want to hide the Request Information button in certain cases, specify an item type attribute as the value. Then include logic in your workflow process that dynamically determines at runtime whether the button should be hidden or displayed and sets the item type attribute to Y or N, respectively.
Note: The Worklist pages that include the Request Information button are currently available only for the version of Oracle Workflow embedded in Oracle Applications.
You can use a special message attribute with the internal name #FROM_ROLE to specify the role that is the source of a notification. For example, if you have a notification that informs an approver that a requisition was submitted, you can set the requisition preparer as the From Role for the message.
If a notification with this attribute is reassigned through the Worklist Web pages, Oracle Workflow automatically sets the From Role to the previous recipient when sending the notification to the new recipient.
The From Role for each notification is displayed in the Worklist Web page and in e-mail notifications to give users additional information for reviewing and responding to the notifications. Additionally, the Find Notifications page, administrator Notification Search page, and Personal Worklist let you search for notifications based on the From Role. See: To View Notifications from the Worklist, Oracle Workflow User's Guide, and To Find Notifications, Oracle Workflow User's Guide.
The #FROM_ROLE attribute must be of type role and must have a source of Send. The display name and description of the attribute should both be From Role. You should specify an item type attribute as the value for the #FROM_ROLE attribute and include logic in your workflow process that dynamically sets that item type attribute to the role you want at runtime.
In Oracle Applications, you can use a special message attribute with the internal name #WF_SIG_POLICY to require that a user's response to a notification be signed electronically. This electronic signature is analogous to a written signature. If you define a notification to require an electronic signature, users must respond to the notification from the Notification Details Web page and enter the appropriate type of signature. Otherwise, the response will not be considered valid.
If you define a notification to require a password-based signature, users must sign their response by entering their Oracle Applications user name and password.
If you define a notification to require a certificate-based digital signature, users must sign their response with a valid X.509 certificate issued by a certificate authority. After the signed response is submitted, Oracle Workflow performs the following steps:
Verifies that the signature was well formed, that it was created with a private key corresponding to the offered signing certificate, and that it is signing the plain text that it purports to sign.
Confirms that this user is authorized to sign the notification by checking that the certificate is assigned to a user who is a member of the recipient role for the notification.
Confirms that the certificate used to create the signature was valid at the time the signature was received, meaning it had not expired or been revoked. To validate a certificate, Oracle Workflow checks that the certificate does not appear on a certificate revocation list (CRL) issued by the certificate authority after the time the signature was received.
Oracle Workflow records the status of requested and submitted signatures in an evidence store, for both password-based signatures and certificate-based digital signatures. This signature information is purged when you purge obsolete workflow runtime data for the associated notifications. See: Items, Oracle Workflow API Reference.
The #WF_SIG_POLICY attribute must be either of type text or lookup. To require a password-based signature, set the value of the #WF_SIG_POLICY attribute to PSIG_ONLY. To require a certificate-based digital signature, set the value of the #WF_SIG_POLICY attribute to PKCS7X509_ONLY. If you set the value to DEFAULT, leave the value blank, or if you do not define a #WF_SIG_POLICY attribute for the message, Oracle Workflow performs the default response processing that does not require a signature.
For ease of maintenance, you can define the #WF_SIG_POLICY attribute with a type of lookup and assign it the predefined Signature Policy lookup type provided in the Standard item type. The Signature Policy lookup type contains three lookup codes with the display names Password Signature, X509 Signature, and Default, representing the values PSIG_ONLY, PKCS7X509_ONLY, and DEFAULT, respectively.
You can also define the #WF_SIG_POLICY attribute with a type of text. In this case, you must manually maintain the values that you set for this attribute.
You can either specify a constant value for the #WF_SIG_POLICY attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically determines at runtime whether a signature should be required or not and sets that item type attribute accordingly.
Note: Electronic signatures are currently supported only for the version of Oracle Workflow embedded in Oracle Applications.
See: Setting Up for Electronic Signatures, Oracle Workflow Administrator's Guide, Electronic Signatures, Oracle Workflow User's Guide, and NtfSignRequirementsMet, Oracle Workflow API Reference.
In Oracle Applications, you can specify an electronic signature policy for notifications by defining the #WF_SIG_POLICY message attribute. If you specify a signature policy that requires an electronic signature to confirm a user's response to a notification, Oracle Workflow creates another message attribute named #WF_SIG_ID after the notification is signed. The #WF_SIG_ID attribute stores the identifier for the signature, which you can use to reference information about the signature later if necessary. This attribute is of type text and has a source of 'Respond'.
Note: Oracle Workflow automatically creates and sets the value of the #WF_SIG_ID attribute when a user submits a response to a notification with an electronic signature. You do not need to manually create or set this attribute.
You can use a special message attribute with the internal name #WF_SECURITY_POLICY to control whether notifications that include sensitive content can be sent in e-mail. If you specify that a notification's content must not be sent in e-mail, users receive an e-mail message that only informs them that they must access the notification through the Notification Details Web page instead to view its content and respond. See: Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide.
The #WF_SECURITY_POLICY attribute must be of type text. To prevent notification content from being sent in e-mail, set the value of the #WF_SECURITY_POLICY attribute to NO_EMAIL. If you set the value to EMAIL_OK or DEFAULT, leave the value blank, or if you do not define a #WF_SECURITY_POLICY attribute for the message, Oracle Workflow sends the full notification content in e-mail to users whose notification preference is set to receive e-mail.
You can either specify a constant value for the #WF_SECURITY_POLICY attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically determines at runtime whether the notification content can be sent in e-mail or not and sets that item type attribute accordingly.
In Oracle Applications, you can use special header message attributes to display key information in the notification header region of the Notification Details page. Header attributes are also displayed at the beginning of e-mail notifications. To identify a message attribute as a header attribute, you must define an internal name for it that begins with #HDR_ using the following format:
#HDR_<name>
The display order of any header attributes in the Notification Details page or the e-mail notification is determined by the sequence of those attributes within the navigation tree in the Workflow Builder. The display name of each header attribute will appear as a label before the attribute value in the notification header region. You can either specify a constant value for each attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically sets the item type attribute value at runtime.
Note: Header attributes are currently available only for the version of Oracle Workflow embedded in Oracle Applications.
In Oracle Applications, the notification header region by default contains general message information such as the from role, recipient, sent date, due date, and notification ID, together with any special header attributes defined for the notification and any linked Oracle Applications attachments. You can optionally use a special message attribute with the internal name #HDR_REGION to replace this default header with a custom header region.
Your custom header must be defined as an Oracle Applications Framework region. For more information about building an Oracle Applications Framework region, refer to OracleMetaLink note 269138.1, Oracle Applications Framework Developer's Guide.
The #HDR_REGION attribute must be of type document and must have a source of Send. Set the value of this attribute to a Java Server Page (JSP) call that references your custom header region. For detailed instructions on how to specify the attribute value, see: Embedding Oracle Applications Framework Regions in Messages.
Note: The Frame Target field is not applicable for message attributes of type document. Additionally, you must not select the Attach Content check box for the #HDR_REGION attribute.
Note: Custom header regions are currently available only for the version of Oracle Workflow embedded in Oracle Applications.
In Oracle Applications, the Related Applications region in Oracle Applications Framework-based notifications by default contains icons with links to attached URLS, documents, or forms. You can optionally use a special message attribute with the internal name #RELATED_APPL to replace this default region with a custom Related Applications region.
Your custom Related Applications region must be defined as an Oracle Applications Framework region. For more information about building an Oracle Applications Framework region, refer to OracleMetaLink note 269138.1, Oracle Applications Framework Developer's Guide.
The #RELATED_APPL attribute must be of type document and must have a source of Send. Set the value of this attribute to a Java Server Page (JSP) call that references your custom region. For detailed instructions on how to specify the attribute value, see: Embedding Oracle Applications Framework Regions in Messages.
Note: The Frame Target field is not applicable for message attributes of type document. Additionally, you must not select the Attach Content check box for the #RELATED_APPL attribute.
Note: Custom Related Applications regions are currently available only for the version of Oracle Workflow embedded in Oracle Applications.
Response-required notifications and some FYI notifications include an action history table. You can optionally use a special message attribute with the internal name #HISTORY to replace the default action history table provided by Oracle Workflow with a custom action history region. See: Action History.
Your custom action history table must be defined as an Oracle Applications Framework region, or as a PL/SQL or PL/SQL CLOB document that contains text or HTML. For more information about building an Oracle Applications Framework region, refer to OracleMetaLink note 269138.1, Oracle Applications Framework Developer's Guide.
The #HISTORY attribute must be of type document and must have a source of Send. For an Oracle Applications Framework region, set the value of this attribute to a Java Server Page (JSP) call that references your custom action history region. For detailed instructions on how to specify the attribute value, see: Embedding Oracle Applications Framework Regions in Messages.
For a PL/SQL or PL/SQL CLOB document, set the attribute value to the procedure and document ID from which the document is generated. See: To Define a Document Attribute.
Note: The Frame Target field is not applicable for message attributes of type document. Additionally, you must not select the Attach Content check box for the #HISTORY attribute.
The action history region for notifications begins with a row for the initial submission of the process, when the notification is first sent. You can optionally use a special message attribute with the internal name #SUBMIT_COMMENTS to display comments from the process owner for this initial action. See: Action History.
The #SUBMIT_COMMENTS attribute must be of type text and must have a source of Send. You should specify an item type attribute as the value for the #SUBMIT_COMMENTS attribute and include logic in your workflow process that dynamically sets that item type attribute to contain the comments at runtime. Ensure that you provide a way for the process owner to enter the comments when submitting the process and store the comments in the appropriate item type attribute.
In Oracle Applications, you can use special message attributes to apply personalizations at different levels to Oracle Applications Framework regions embedded in notifications.
#PERZ_FUNCTION_NAME - Define this attribute for a message to apply a personalization at function level to a region embedded in the notification. Set the attribute value to the function name.
#PERZ_ORGANIZATION_ID - Define this attribute for a message to apply a personalization at organization level to a region embedded in the notification. Set the attribute value to the organization ID.
#PERZ_LOCALIZATION_CODE - Define this attribute for a message to apply a personalization at localization level to a region embedded in the notification. Set the attribute value to the localization code.
You can also create personalizations for an Oracle Applications Framework region at site level. In this case the personalizations will automatically be applied when the region appears embedded in a notification, as well as when it appears in any other location.
You can use special message attributes to control how a notification mailer generates the e-mail message for a notification, if the recipient has a notification preference to receive e-mail notifications. For example, if you want to customize notifications from a particular department, you can define these attributes for those notifications.
#WFM_FROM - Define this attribute for a message to specify the value that appears in the From field of the message header when the e-mail notification message is delivered to a user. If the #WFM_FROM message attribute is defined for a notification, the notification mailer that sends the message will use the #WFM_FROM attribute value in the From field for that message, overriding the mailer's From Address parameter value.
#WFM_REPLYTO - Define this attribute for a message to specify the address of the e-mail account that receives incoming messages, to the which e-mail notification response should be sent. If the #WFM_REPLYTO message attribute is defined for a notification, the notification mailer that sends the message will use the #WFM_REPLYTO attribute value as the reply address for that message, overriding the mailer's Reply To parameter value.
#WFM_HTMLAGENT - Define this attribute for a message to specify the base URL that identifies the HTML Web agent that handles HTML notification responses. This URL is required to support e-mail notifications with HTML attachments. The default URL is derived from the Workflow Web Agent specified in the Global Preferences Web page in standalone Oracle Workflow, or from the Applications Web Agent (APPS_WEB_AGENT) profile option in Oracle Applications. However, you can override this default by defining a different value for this attribute. If the #WFM_HTMLAGENT message attribute is defined for a notification, the notification mailer that sends the message will use the #WFM_HTMLAGENT attribute value as the HTML Web agent for that message, overriding the mailer's HTML Agent parameter value.
#WFM_LANGUAGE - Define this attribute for a message to specify the value of the NLS_LANGUAGE database initialization parameter that determines the language for the e-mail notification. Set the attribute value to a language name supported by the Oracle Database, such as ARABIC. If the #WFM_LANGUAGE message attribute is defined with a valid value for a notification, the notification mailer that sends the message will use the #WFM_LANGUAGE attribute value when generating the e-mail message, overriding the language preference of the recipient role.
#WFM_TERRITORY - Define this attribute for a message to specify the value of the NLS_TERRITORY database initialization parameter that determines the territory-dependent formatting for the e-mail notification. Set the attribute value to a territory name supported by the Oracle Database, such as UNITED ARAB EMIRATES. If the #WFM_TERRITORY message attribute is defined with a valid value for a notification, the notification mailer that sends the message will use the #WFM_TERRITORY attribute value when generating the e-mail message, overriding the territory preference of the recipient role.
Note: The #WFM_LANGUAGE and #WFM_TERRITORY attributes function independently of each other. If you define only one of these attributes with an overriding value for the corresponding NLS parameter, the notification mailer still uses the recipient role's preference for the other parameter.
For more information, see the Oracle Workflow Manager online help and Locale Data, Oracle Database Globalization Support Guide.
You can use special message attributes to specify which message templates a notification mailer uses to generate the e-mail message for a notification, if the recipient has a notification preference to receive e-mail notifications. For example, if you want to customize notifications from a particular department, you can define these attributes for those notifications. The templates specified in these attributes for a particular notification override the templates specified in the configuration parameters for a notification mailer.
You can create your own message templates by using the Workflow Builder to define skeleton messages within an item type. See: Modifying Your Message Templates, Oracle Workflow Administrator's Guide.
The value for a message template attribute must be specified in the following format:
<item_type_internal_name>:<message_internal_name>
For example, to specify the Workflow Open Mail (Templated) message within the System: Mailer item type, you would enter the following value:
WFMAIL:OPEN_MAIL
You can either specify a constant value for a message template attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically determines at runtime which message template to use and sets that item type attribute accordingly.
You can define the following attributes to specify templates to be used for a notification message at various stages in e-mail notification processing.
#WFM_OPEN_MAIL - Specify the template to use for e-mail notifications that require a response, if you are using the templated response method.
#WFM_OPEN_MAIL_DIRECT - Specify the template to use for e-mail notifications that require a response, if you are using the direct response method.
#WFM_OPEN_MAIL_FYI - Specify the template to use for e-mail notifications that do not require a response.
#ATTACHED_URLS - Specify the template to use to create the Notification References attachment for HTML-formatted notification messages that include URL attributes with Attach Content checked.
#WFM_CANCELED - Specify the template to use to inform the recipient that a previously sent notification is canceled.
#WFM_OPEN_INVALID - Specify the template to send to a user when the user responds incorrectly to a notification.
#WFM_CLOSED - Specify the template to use to inform the recipient that a previously sent notification is now closed.
#WFM_OPEN_MORE_INFO - Specify the template to use to send a request for more information from one user to another user.
For more information, see the Oracle Workflow Manager online help.
Following are examples of how the Notification System generates the Response section of an e-mail notification using a sample set of 'Respond' message attributes that have no default values.
The following table lists some sample 'Respond' message attributes.
| Internal Name | Type | Format/Lookup Type | Display Name | Description |
|---|---|---|---|---|
| RESULT | lookup | WFSTD_APPROVAL | Action | Do you approve? |
| COMMENT | text | 2000 | Review Comments | |
| REQDATE | date | DD-MON-YYYY | Required Date | If there is no required date, leave this blank. |
| MAXAMT | number | Maximum Amount | This is the maximum approved amount. |
For the templated response method, the following boilerplate text is used to generate the Response template section of an e-mail notification:
<Description>
<Display Name>: " "
<list of lookup codes>
| Do you approve? |
| Action: " " |
| Approve |
| Reject |
| Review Comments: " " |
| If there is no required date, leave this blank. |
| Required Date: " " |
| This is the maximum approved amount. |
| Maximum Amount: " " |
For the direct response method, the following boilerplate text is used to generate the Response section of an e-mail notification:
Enter the <Display Name> on line <Sequence>. <Description> <Type_Hint> <Display Name> is replaced with the Display Name of the message attribute. <Sequence> is replaced with the relative sequence number of the 'Respond' message attribute as it appears in the Navigator tree among all 'Respond' message attributes (that is, the presence of 'Send' message attributes is ignored when determining the sequence). <Description> is replaced with the Description of the message attribute. In addition, <Type_Hint> is replaced with a hint statement if the message attribute matches a data type that has a hint. The following table shows the data types with hints and the corresponding hint statements.
| Type | Type Hint |
|---|---|
| Lookup | Value must be one of the following: <list of lookup codes> |
| Date | Value must be a date [in the form "<format>"]. |
| Number | Value must be a number [in the form "<format>"]. |
| Text | Value must be <format> bytes or less. |
| Enter the Action on line 1. Do you approve? Value must be one of the following: |
| Approve |
| Reject |
| Enter the Review Comments on line 2. Value must be 2000 bytes or less. |
| Enter the Required Date on line 3. If there is no required date, leave this blank. Value must be a date in the form "DD-MON-YYYY". |
| Enter the Maximum Amount on line 4. This is the maximum approved amount. Value must be a number. |
If you are using Oracle Applications and you have Oracle Applications Framework set up in Oracle JDeveloper for custom development, you can embed Oracle Applications Framework regions in a notification message. To embed a region, define a message attribute whose value is a Java Server Page (JSP) call that references the region.
The message attribute representing the region must be of type document and must have a source of Send. You can assign the attribute any appropriate internal name, display name, and description.
Specify the value for the attribute in the following format:
JSP:/OA_HTML/OA.jsp?OAFunc=<Function_Name>
where <Function_Name> is the self-service function name for the region you want to embed in the notification, as registered in the Form Functions window in Oracle Applications. For example:
JSP:/OA_HTML/OA.jsp?OAFunc=EMBED_WL_FUNC
To pass parameters to the region, specify the value for the attribute in the following format:
JSP:/OA_HTML/OA.jsp?OAFunc=<Function_Name>&<Name1>=<Value1>
&<Name2>=<Value2>...
where <Function_Name> is the function name for the region, <Name1> and <Value1> are the parameter name and value for the first parameter, <Name2> and <Value2> are the parameter name and value for the second parameter, and so on. For example:
JSP:/OA_HTML/OA.jsp?OAFunc=EMBED_WL_FUNC&Order_Type=12345
You can set the value for the message attribute in the following ways:
Specify the complete JSP call as a constant default value for the message attribute.
Specify an item type attribute of type document as the message attribute value, and include logic in your workflow process that dynamically sets the item type attribute value at runtime. This method lets you dynamically set the complete JSP call.
Use token substitution in the message attribute value to dynamically set the function name within the JSP call.
Create an item type attribute for the function name.
Create an additional message attribute for the function name, and specify the corresponding item type attribute as the value of that message attribute.
Include logic in your workflow process that dynamically sets the item type attribute value to the appropriate function name at runtime.
Specify the value for the message attribute representing the region in the following format:
JSP:/OA_HTML/OA.jsp?OAFunc=-&funcname_attr-
where funcname_attr is the internal name of the message attribute that specifies the function name.
Use token substitution in the message attribute value to dynamically set the parameter values for the function within the JSP call. In this case you must specify the function name and the parameter names as constants within the JSP call, and token substitute only the parameter values.
Create an item type attribute for each parameter value.
Create an additional message attribute for each parameter value, and specify the corresponding item type attribute as the value of that message attribute.
Include logic in your workflow process that dynamically sets the item type attribute values to the appropriate parameter values at runtime.
Specify the value for the message attribute representing the region in the following format:
JSP:/OA_HTML/OA.jsp?OAFunc=<Function_Name>&<Name1>
=-&msgattr1-&<Name2>=-&msgattr2-...
where <Function_Name> is the function name for the region, <Name1> and <Name2> are the first and second parameter names, msgattr1 and msgattr2 are the internal names of the message attributes that specify the first and second parameter values, and so on.
Note: The Frame Target field is not applicable for message attributes of type document. Additionally, you must not select the Attach Content check box for a message attribute that references a region. An Oracle Applications Framework region can only be displayed within the message body of a notification. It cannot be included as an attachment to the notification.
To embed the region in the message, enter the token for the message attribute in the HTML body for the message. A message can include multiple regions, which will be displayed in the sequence in which their tokens appear in the HTML Body field. Additionally, the message can include calls to the special message function WF_NOTIFICATION() to produce a table of message attributes or an action history table, which will also be rendered as Oracle Applications Framework regions. See: WF_NOTIFICATION() Message Function.
Note: If you embed an Oracle Applications Framework region in a message, then the message body can only contain message attribute tokens referencing such regions and calls to the special message function WF_NOTIFICATION(). The message body cannot contain any tokens for message attributes that do not reference regions.
Leave the Text Body field blank for an Oracle Applications Framework region message. Oracle Workflow does not use the text body for such messages. Instead, a text version of the message is derived directly from the included regions. Note that non-text content such as images, links, or special HTML formatting will not appear in the text version of a region.
Follow these guidelines when you are developing an Oracle Applications Framework region for inclusion in a notification message:
Oracle Workflow notifications support embedded Oracle Applications Framework regions only. You cannot include an entire Oracle Applications Framework page.
The region style must be Stack Layout. This region style lets users personalize the region with Oracle Applications Framework Personalization.
Ensure that the event handling in the controllers for the embedded Oracle Applications Framework region does not interfere with the event handling of the region controller for the main message body. To avoid such interference, when handling any events in the controller code, you must qualify those events with the region associated with the controller.
The embedded region must be complete within itself. You should associate the region with its own application module and assign it a region title.
The embedded region must be a view-only region. That is, it cannot contain elements that allow user input, such as buttons.
The embedded region must not contain any information that is specific to a particular user session.
If you do not want to send an embedded region in e-mail, you can exclude the message body from notification e-mail messages by assigning the notification a message template that directs recipients to access the notification through the Worklist Web pages instead.
For a notification that requires a response, define the special message attributes #WFM_OPEN_MAIL and #WFM_OPEN_MAIL_DIRECT, and set the values of these attributes to WFMAIL:VIEW_FROMUI to use the Workflow View From UI message template.
For a notification that does not require a response, define the special message attribute #WFM_OPEN_MAIL_FYI, and set the value of this attribute to WFMAIL:VIEW_FROMUI_FYI to use the Workflow View FYI From UI message template.
See: Notification Mailer Message Template Attributes, Workflow View From UI Message, Oracle Workflow Administrator's Guide, and Workflow View FYI From UI Message, Oracle Workflow Administrator's Guide.
If the embedded region includes subtabs or Hide/Show regions, ensure that you provide alternate representations of that content for inclusion in an e-mail message or in the plain text version of a notification used for electronic signatures. You can choose to exclude the message body from e-mail, or you can code alternate representations in the controllers for the embedded region.
For example, for a subtab region you can create a separate region displaying that content and include the separate region programmatically in the e-mail or plain text cases. For Hide/Show regions, you should remove the Hide/Show region and instead display all the child rows of the Hide/Show region directly in the current container.
For usability reasons, we recommend that if your Stack Layout region includes a Table Layout region, you should restrict to 200 the number of rows returned from the query for the Table Layout region.
If your Stack Layout region includes a region in the Table Layout region style, the Notification Details page displays the Table Layout region with the Next and Previous rowset functionality available when appropriate. However, because e-mail clients cannot interpret the rowset functionality, e-mail notifications display the Table Layout region with static row data, which is restricted to 200 rows.
Do not enable sorting or navigation features for table components programmatically at runtime.
Register your Oracle Applications Framework region as a self-service function (non-form function) in the Form Functions window in Oracle Applications. The internal name that you define for the function is the function name that you must include in the message attribute value to reference the region. See: Form Functions Window, Oracle Applications Developer's Guide.
When you register the function, enter the HTML Call in the Web HTML tabbed region of the Form Functions window, using the following format:
OA.jsp?page=/<directory_path>/<Region_Code>
&akRegionApplicationId=<Region_Application_ID>
For example:
OA.jsp?page=/oracle/apps/fnd/wf/worklist/webui/
WFNTFWORKLIST&akRegionApplicationId=601
For more information about building an Oracle Applications Framework region, refer to OracleMetaLink note 269138.1, Oracle Applications Framework Developer's Guide.
Related Topics
To View the Details of a Notification (for Oracle Applications), Oracle Workflow User's Guide
Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide
To Create a Message
Select the item type that you want to create a message for in the navigator tree, and choose New Message from the Edit menu. A Message property page appears.
Message Property Page
Provide an internal name for the message that is all uppercase with no leading/trailing spaces, and provide a display name. You may also enter an optional description. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying a message.
Attention: To update the internal name for a message once it is defined, you must use a special SQL script called wfchmsg.sql. You should only use this script to correct errors in a message's internal name during design time. Do not use this script to rename messages that are involved in running instances of processes. See: Wfchmsg.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Choose High, Normal, or Low for the default priority of the message. The priority level simply informs the recipient of the urgency of the message. It does not affect the processing or delivery of the message.
Note: When you assign this message to a notification activity and you incorporate the notification activity into a process diagram as a node, you can override this default message priority with a new priority that is constant or dynamically determined at runtime. See: To Define Nodes in a Process.
Note: In earlier versions of Oracle Workflow, the message priority was represented as a numeric value between 1 (high) and 99 (low). Oracle Workflow now automatically converts the priority values of all message definitions defined in earlier versions as follows: 1-33 = High, 34-66=Normal, and 67-99=Low.
Choose Apply to save your changes.
Select the Body tab to display the Body property page of the message.
Body Property Page
The subject gets its default value from the display name that you entered in the Message tab. You can choose to keep the default subject or enter a new subject for the message. The subject can include message attributes that get token replaced with runtime values when the message is delivered. To include a message attribute in the subject, use an ampersand (&) followed by the message attribute's internal name. See: Send and Respond Message Attributes and To Define a Message Attribute.
Suggestion: For clarity, you can assign a message attribute the same name as the item type attribute it references.
If the message will not contain any embedded Oracle Applications Framework regions, enter a plain text message body in the Text Body field. You can select the ellipsis button (...) to expand the view of the Subject and Text Body fields in another window.
Oracle Workflow uses the content you enter in the Text Body field to generate a plain text version of the notification message. The plain text message can be viewed from the from an e-mail reader that displays plain text messages.
Attention: If the message will not contain any embedded Oracle Applications Framework regions, ensure that you enter a plain text message body in the Text Body field. If Text Body is null, you get an empty notification when you view your message from a plain text e-mail reader. However, if the message does contain one or more embedded Oracle Applications Framework regions, then you should leave the Text Body field blank, because the text body is not used for this type of notification. See: Embedding Oracle Applications Framework Regions in Messages.
Enter an HTML-formatted message body in the HTML Body field by selecting the HTML Body tab and typing in the content, or by selecting Import to import the content from a .HTM or .HTML file. You can also select the ellipsis button (...) to expand the view of the Subject and HTML Body fields in another window.
If the message will contain an embedded Oracle Applications Framework region, then the HTML body is required. Otherwise, the HTML Body field is optional. See: Embedding Oracle Applications Framework Regions in Messages.
Attention: When you enter or import the HTML message body, you do not need to include the <Body>...</Body> HTML tags. If you do include these tags, Oracle Workflow simply extracts the content between these tags to use as the HTML message body. As a result, Oracle Workflow ignores any HTML tags or content prior to the <Body> tag.
Attention: Oracle Workflow Builder does not verify the HTML formatting of the message body.
Oracle Workflow uses the content you enter in the HTML Body field to generate an HTML-formatted version of the notification message. You can view an HTML-formatted notification message from the Notification Details Web page, or from an e-mail reader that displays HTML-formatted messages or HTML-formatted message attachments.
Note: If HTML Body is null, Oracle Workflow uses the message body entered in Text Body to generate the notification message. It inserts the plain text between the <pre>...</pre> HTML tags.
You can embed message attributes in the text or HTML body. Oracle Workflow token replaces the message attributes with runtime values when it delivers the notification. To embed a message attribute, enter an ampersand ("&") followed by the message attribute's internal name.
Attention: The text in a message body must be less than 4000 bytes. If you include message attributes in the text for token substitution, then the final message body can increase up to 32000 bytes.
Note: You can also include a special token in the message subject or body called &#NID. Oracle Workflow substitutes this token with the notification ID of the runtime notification.
Note: If you define a 'Send' message attribute of type URL that points to an image file with an extension of gif, jpg, png, tif, bmp, or jpeg, and you embed the URL attribute in the HTML body of the message, then Oracle Workflow displays the image inline in the Notification Details page and HTML-formatted e-mail notifications. See: To Define a URL Attribute.
Additionally, you can use the message function WF_NOTIFICATION() to include a formatted table of message attributes or an action history table in the text or HTML message body.
Choose Apply to save your changes.
Select the Roles tab page to specify the roles that have access to this message. (This functionality will be supported in a future release.)
Select the Access tab page to set the access levels allowed to modify this message. See: Allowing Access to an Object.
If you want the notification message to prompt the performer for a response value and you want Oracle Workflow to interpret that response value as the result of the notification activity, select the Result tab page and complete the information requested. Oracle Workflow uses the information you specify in the Result tab page to create a special 'Respond' message attribute called RESULT. See: Message Result.
Result Property Page
Specify a display name and description for RESULT. Select a lookup type from the poplist field. The lookup type you select should be identical to the lookup type specified for the notification activity's result type. Select a lookup code in the Default Value region. The lookup code you select appears as the default value of the RESULT message attribute.
Note: To create any other type of message attribute, see: To Define a Message Attribute.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
The message you just defined now appears beneath the Message branch in the navigator tree. You can review or edit the properties of this message at any time by double-clicking on the message in the navigator tree or by selecting the message and choosing Properties from the Edit menu.
If a message has a Result defined, then its message icon in the Navigator tree has a red question mark overlay to help you distinguish it from messages that do not have a Result defined.
You must now define all the message attributes that you have included in the subject and body of this message.
To create a message attribute that references an item type attribute, select the referenced item type attribute in the navigator tree, and hold down your mouse select button as you drag the item type attribute to your message.
Edit the property page that appears, making sure the message attribute has the proper Source. The Default Value region is automatically set to Item Attribute and references the originating item attribute.
You can also create message attributes that are not based on existing item type attributes. See: To Define a Message Attribute.
To Define a Message Attribute
To create a message attribute that does not reference an existing item type attribute, select a message in the navigator tree and choose New Attribute from the Edit menu.
An Attribute property page appears.
Message Attribute Property Page
Provide an Internal Name in all uppercase with no leading/trailing spaces. All Oracle Workflow APIs, SQL scripts, and PL/SQL procedures refer to the internal name when identifying an attribute.
Attention: To update the internal name for a message attribute once it is defined, you must use a special SQL script called wfchmsga.sql. You should only use this script to correct errors in a message attribute's internal name during design time. Do not use this script to rename message attributes that are involved in running instances of processes. See: Wfchmsga.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include leading/trailing spaces or reserved characters such as a colon (":"), ampersand ("&"), or number sign ("#") in the internal name of a message attribute. Additionally, do not include any spaces within the internal name of a message attribute.
Specify 'Send' or 'Respond' in the Source field to indicate whether this attribute should send information to the notification recipient or prompt a notification message recipient for a response, respectively.
Enter a Display Name. This is the name that appears in the navigator tree. If this is a 'Respond' message attribute, then this display name is also used as the response prompt. See: Example 'Respond' Message Attributes.
For 'Send' message attributes, the Display Name of the attribute appears in plain text e-mail notifications only if the attribute is of type URL, to describe what the URL drills down to.
Enter an optional description. If this is a 'Respond' message attribute, use this field to elaborate on response instructions. See: Example 'Respond' Message Attributes.
Depending on the Type of your attribute, provide the following default information:
Number - Optionally provide a format mask for your number and a default number value.
Date - Optionally supply a format mask for the date and a default date value.
Lookup - Choose the name of a predefined Lookup Type from which to draw values. Choose a lookup code for the default value.
URL - Specify a Universal Resource Locator (URL) to a network location in the Default Value field. See: To Define a URL Attribute.
Attention: 'Respond' message attributes of type URL do not appear properly when you view the notification from a plain text e-mail reader. You should advise your workflow users to view their notifications from the Notification Details Web page if you plan to create messages with 'Respond' message attributes of type URL.
Attention: A single 'Respond' message attribute of type URL replaces the Notification Details Web page response frame and takes the notification recipient to a custom HTML page to complete the notification response. Your custom HTML response page must include references to all your 'Respond' message attributes, including the special RESULT attribute, if one is defined, and must also include a call to the Workflow Engine CompleteActivity() API to inform the Workflow Engine when the notification response is complete.
Note: If you define a 'Send' message attribute of type URL that points to an image file with an extension of gif, jpg, png, tif, bmp, or jpeg, and you embed the URL attribute in the HTML body of the message, then Oracle Workflow displays the image inline in the Notification Details page and HTML-formatted e-mail notifications. See: To Define a URL Attribute.
Form - This attribute is relevant only with the version of Oracle Workflow embedded in Oracle Applications.
Specify a developer form function name and any optional argument string (form function parameters) in the Default Value field. See: Overview of Menus and Function Security, Oracle Applications Developer's Guide and To Define a Form Attribute.
Attention: 'Send' and 'Respond' message attributes of type Form appear only when your Worklist Web pages are launched from Oracle Applications. The attached form icon is enabled if a notification message includes a 'Send' message attribute of type Form. The notification recipient can click on the attached form icon to drill down to the form function defined by the message attribute.
Attention: If a message includes a 'Respond' message attribute of type Form, the attached form icon that appears in the notification's Response section simply drills down directly to the designated form function. This form function must be coded with a call to the Workflow Engine CompleteActivity() API to inform the Workflow Engine that the notification response is complete. See: Workflow Engine APIs, Oracle Workflow API Reference.
Document - Enter a string that identifies the document in the Default Value field. See: To Define a Document Attribute.
Role - Specify a role name. If a message attribute of type role is included in a notification message, the attribute automatically resolves to the role's display name, eliminating the need for you to maintain separate attributes for the role's internal and display names. Also when you view the notification from a Web browser, the role display name is a hypertext link to the e-mail address for that role. To set a default value for the attribute, you must initially load roles from the database. See: Roles.
Event - Specify an event item type attribute as the default value.
Attention: Do not specify a message attribute's data type as Attribute, as it serves no purpose in a notification message and is also not supported by the Workflow Notification System.
Attention: 'Respond' message attributes of type Date, Number, Text, Document or Role prompt the notification recipient to respond with a date, number, text value, document, role (internal or display name), respectively.
'Respond' message attributes of type Lookup prompt the notification recipient to select a response from a list of values.
If your message attribute is a URL attribute, specify a Frame Target. When you reference this message attribute in a message and the user who receives the message clicks the URL link in the message body, the URL opens according to what you specify as the frame target. The frame target can be:
New Window - the URL loads in a new, unnamed browser window.
Same Frame - the URL loads in the same frame as the element that references the URL attribute.
Parent Frameset - the URL loads into the immediate FRAMESET parent of the current frame. This value is equivalent to Same Frame if the current frame has no parent.
Full Window - the URL loads into the full, original window, thus cancelling all other frames. This value is equivalent to Same Frame if the current frame has no parent.
Note: In Oracle Applications, you should only choose New Window or Full Window as the frame target for URL attributes. In the Oracle Applications version of the Worklist, the Notification Details page does not use frames to display notifications. Consequently, choosing Same Frame or Parent Frameset is equivalent to choosing Full Window in this case.
Note: If the URL attribute points to an image file with an extension of gif, jpg, png, tif, bmp, or jpeg, and you embed the URL attribute in the notification message by token substitution, then Oracle Workflow displays the image inline in the Notification Details page and HTML-formatted e-mail notifications, rather than as a link. In this case the frame target value is not applicable.
If your message attribute is a Send attribute, is of type Document, and contains a PL/SQL, PL/SQL CLOB, or PL/SQL BLOB document, you can check Attach Content to attach the content of the attribute to the notification message. When you view your notification from the Notification Details Web page, you see a document icon following the notification message body that displays the contents of the attached message attribute when you click on it. If you view your notification from e-mail, the presentation of the attachment will vary depending on what your e-mail notification preference setting is. See: Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide.
Note: You can attach, as well as embed (by token substitution) PL/SQL document attributes in the notification message and are not limited to one or the other. However, a document attribute that references an Oracle Applications Framework region can only be embedded in the notification message. A region cannot be attached to a notification. See: Embedding Oracle Applications Framework Regions in Messages.
If your message attribute is a Send attribute and is of type URL, you can check Attach Content to attach the URL to the message.
In the Notification Details Web page, an attached URL appears with an attachment icon after the notification message body.
For a notification e-mail message that does not include an embedded Oracle Applications Framework region, Oracle Workflow appends an attachment called Notification References to the e-mail. This attachment includes a link to each URL attribute for the message that has Attach Content checked. You can navigate to a URL by choosing its link.
For a notification e-mail message that includes an embedded Oracle Applications Framework region, Oracle Workflow includes a Related Applications region in the e-mail after the message body. The Related Applications region displays a link to each attached URL attribute.
Note: You can attach, as well as embed (by token substitution) URL attributes in the notification message and are not limited to one or the other.
Note: If you check Attach Content for a URL attribute that points to an image file, the URL attribute appears as a link in the Notification References attachment or Related Applications region, just as other URLs do.
For message attributes, the default value may be a constant or an item type attribute. If the default references its entire value directly from an item type attribute, choose Item Attribute, then use the poplist field to choose an item type attribute. The item type attribute you select must be associated with the same item type that the message itself is associated with. The item type attribute you select must also be of the same data type as the message attribute.
Note: A message attribute type of 'Text' is compatible with any item attribute type except Event, but all other message attribute types must match the item attribute type exactly.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
Any message attribute you define appears beneath the respective message you defined it for in the navigator tree. You can review or edit the properties of an attribute at any time by double-clicking on the attribute in the navigator tree or by selecting the attribute and choosing Properties from the Edit menu. Respond message attribute icons in the Navigator tree have a red question mark overlay to help you distinguish them from Send message attribute icons.
Note: Message attributes assume the access/protection level of their parent message.
Attention: The order in which you list 'Respond' message attributes in the navigator tree correlates to the order in which they appear in the response section of the notification message. You can use the drag and drop feature of the navigator tree to reorder a set of attributes, or select an attribute and choose Move Attribute Up or Move Attribute Down from the Edit menu.
To Token Substitute an Attribute
Oracle Workflow supports runtime token substitution of attributes. You can embed attributes within an attribute as well as embed attributes within a message subject and body. To embed an attribute, specify the attribute that you want to have token substituted as &attr_name, where attr_name is the internal name of the attribute.
When performing token substitution, Oracle Workflow fetches the internal name of the attribute and its value. If an attribute requiring token substitution is nested with another attribute, Oracle Workflow orders the nested list of attributes according to the length of their internal attribute names and then begins substituting the attributes with the longest internal names first.
Attention: If you find that you need to nest message attributes more than two layers deep to display the necessary message body content, you should investigate creating a PL/SQL document-type message attribute. See: External Document Integration.
To Copy a Message
Hold down your mouse select button as you drag the message to the item type branch you want to copy to.
When you release your mouse button, a property page appears for the new message.
Note: You can also use the Copy and Paste options in the Edit menu.
Enter a new internal name and display name.
Make any additional modifications to the properties of the message.
When you are done, choose OK.
Note: Copying a message also copies any message attributes assigned to it.
Related Topics
Using the Edit Button in a Property Page
Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide
An activity is a unit of work that contributes toward the accomplishment of a process. An activity can be a notification, a function, an event, or a process. A notification activity sends a message to a workflow user. The message may simply provide the user with information or request the user to take some action. A function activity calls a PL/SQL stored procedure or some external program to perform an automated function. An event activity receives, raises, or sends a business event. A process activity is a modelled workflow process, which can be included as an activity in another process to represent a sub-process.
Activities are organized beneath their respective Processes, Notifications, Functions, or Events headings in the navigator tree. You can create, edit, and delete activity definitions in the navigator tree, and drag an activity from the tree into a Process window to create a new usage of that activity in a process diagram. Each activity is depicted as an icon in a process diagram
Oracle Workflow provides an item type called Standard that includes generic activities you can use in any process you define. For example, some of the activities perform standard functions such as comparing two values. See: Standard Activities.
Oracle Workflow also provides an item type called System:Error that includes standard error processes and activities you can use to create a custom error process. You can assign an error process to a process activity. If an error occurs, the error process informs Oracle Workflow how to handle the error. See: Error Handling for Workflow Processes.
When the workflow engine reaches a notification activity, it issues a Send() API call to the Notification System to send the message to an assigned performer. You define the message that the notification sends. The message can be an informative note or it can prompt the performer for a response. When a performer responds to a notification activity, the Notification System processes the response and informs the Workflow Engine that the notification activity is complete so that it can continue processing the next eligible activity. See: To Create a Notification Activity.
You specify the performer of a notification activity when you include the notification activity as a node in the process. You can either designate the performer to be a specific role or an item type attribute that dynamically returns the name of a role. See: To Define Nodes and Roles.
When you define a notification activity, you can also optionally:
Check Expand Roles to send an individual copy of the notification message to each user in the role. The notification remains in a user's notification queue until the user responds to or closes the notification.
Attention: You should expand roles to send out a broadcast-type message that you want all users of that role to see.
If you do not expand the role for a notification activity, Oracle Workflow sends one copy of the notification message to the assigned performer role and that notification is visible in the notification queue of all the users in that role. If one user in that role responds to or closes that notification, the notification is removed from the notification queue of all other users in that role.
Specify a post-notification function that the Workflow Engine executes in response to an update of the notification's state after the notification is delivered. The Workflow Engine runs the post-notification function in the following modes:
VALIDATE, RESPOND, and RUN - When a notification recipient responds to the notification.
The Workflow Engine initially runs the post-notification function in VALIDATE mode which allows you to validate the response values before accepting the response. Then the Workflow Engine runs the post-notification function in RESPOND mode to record the response. Finally, 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.
FORWARD - When a notification recipient forwards the notification.
TRANSFER - When a notification recipient transfers the notification.
QUESTION - When a notification recipient requests more information about the notification from another user.
ANSWER - When a request recipient responds with more information about the notification.
TIMEOUT - When the notification times out.
For example, if you wish to restrict the roles that a notification can be forwarded to, you can specify a post-notification function that the Workflow Engine executes in FORWARD mode when the notification recipient attempts to forward the notification. The post-notification function would audit the role and either allow the forward to occur or reject it with an error. See: Post-Notification Functions, Oracle Workflow API Reference and Notification Model, Oracle Workflow API Reference.
To create a post-notification function, you should use the same PL/SQL API required for function activities. See: Standard API for PL/SQL Procedures Called by Function Activities.
By both checking Expand Roles and specifying a post-notification function, you can create your own custom vote tallying activity. See: Voting Activity.
A function activity is defined by the PL/SQL stored procedure or external program that it calls. Function activities are typically used to perform fully automated steps in the process. As a PL/SQL stored procedure, a function activity accepts standard arguments and can return a completion result.
If you pass a parameter for the stored procedure, you can expose that parameter as an activity attribute. The activity attribute's value can be set when you define that activity as a node in your process. Note that these activity attributes are available only to the current activity and are not global like item type attributes. See: To Define Activity Attribute Values.
As an external program, a function activity is able to enqueue payload information into an Oracle Advanced Queuing outbound queue for some external agent to dequeue and consume. The external agent can similarly enqueue updated attributes and a completion result into an inbound queue that the Workflow Engine consumes and processes.
As an external Java program, a function activity is able to enqueue payload information into an Oracle Advanced Queuing outbound queue for the Java Function Activity Agent to dequeue and consume. The results of the Java program are enqueued into an inbound queue that the Workflow Engine consumes and processes. This functionality is currently only available for the standalone version of Oracle Workflow. See: To Create a Function Activity.
An event activity represents a business event from the Business Event System within a workflow process. Include event activities in workflow processes to model complex processing or routing logic for business events beyond the standard event subscription actions. See: Managing Business Events.
An event activity can either receive, raise, or send a business event.
A Receive event activity accepts an event sent from the Event Manager. You can send an event to launch one particular new process or continue one particular existing process identified by a specific item type, process name, and item key. You can also send an event to continue one or more existing processes based only on a business key attribute.
A Receive event activity can be marked as a Start activity for a process, meaning it is always enabled to receive events. Alternatively, a Receive event activity can be placed within the process, so that it is only enabled to receive events after the process transitions to that activity.
You can define a Receive event activity to accept only one specific event, to accept only an event that is a member of a specific event group, or to accept any event.
When an event subscription sends an event to a workflow process, the Workflow Engine performs the following processing:
Sets any parameters in the event message parameter list as item type attributes for the process, creating new item type attributes if a corresponding attribute does not already exist for any parameter.
Sets the subscription's globally unique identifier (GUID) as a dynamic item attribute so that the workflow process can reference other information in the subscription definition.
If the event was originally raised by a Raise event activity in another workflow process, the item type and item key for that process are included in the parameter list within the event message. In this case, the Workflow Engine automatically sets the specified process as the parent for the process that receives the event, overriding any existing parent setting. See: SetItemParent, Oracle Workflow API Reference.
Searches for receive event activities that are eligible to accept the event. For an activity to be eligible, the event must match the activity's event filter, and the activity must either be marked as a Start activity or have a status of 'NOTIFIED', meaning the process has transitioned to the event.
Note: If the event was sent to one or more existing workflow processes based on a business key, rather than to one particular workflow process, then to be eligible an activity must have an event filter that matches the event, a status of 'NOTIFIED' , and a #BUSINESS_KEY attribute that matches the event key. See: Event Subscriptions for Standalone Oracle Workflow or Event Subscriptions for Oracle Applications.
If an event arrives at a Start activity to launch a new process instance, the Workflow Engine also searches for all other receive event activities that are marked as Start activities and that do not have any incoming transitions, regardless of their event filter. For these activities, the Workflow Engine sets the activity status to 'NOTIFIED' so that they will be ready to receive an event if any more events are sent to this process. This feature lets you design a workflow process that requires multiple events to be received when you do not know in advance the order in which the events will arrive.
Stores the event name, event key, and event message in item type attributes, as specified in each eligible activity node's event details.
Marks all the eligible event activity nodes with a status of 'COMPLETED' and continues the thread of execution from each of those nodes.
If an event activity has already received an event and another matching event is sent to the process, then the On Revisit flag for the activity determines whether the Workflow Engine reexecutes the activity. See: To Define Optional Activity Details.
Example - Using a Business Key
Use a business key to identify which workflow processes should receive an event when the event applies to one or more processes that are already started and are awaiting input to continue. For example, a workflow process initiated for a purchase order with the number PO123 may be awaiting input such as credit card authorization from another workflow or from an external interface, through an event named po.credit.authorization. The authorization event should only continue the workflow process instance associated with the PO123 purchase order; it should not continue any other purchase order processes.
To achieve this purpose, the receive event activity in the purchase order workflow process should be defined to accept only the po.credit.authorization event and should include an activity attribute named #BUSINESS_KEY with a value of PO123. The other workflow process or external system that raises the event must set the event key to PO123. Additionally, the event subscription to the po.credit.authorization event must use the WF_RULE.Instance_Default_Rule rule function or, in Oracle E-Business Suite, the subscription must be defined with the Launch When Business Key Matches option. With this configuration, when the event arrives, it will continue only the workflow process instance associated with the specific purchase order number PO123 through the #BUSINESS_KEY activity attribute.
A Raise event activity retrieves information about the event and raises the event to the Business Event System, which will then execute subscriptions to the event. The activity retrieves the event name, event key, and event data as specified in the node's event details. The event details can be dynamically determined at runtime using item type attributes. You can also specify the event name as a predefined constant for the event activity node.
Additionally, the activity retrieves the names and values of any activity attributes defined for it and sets these attributes as parameters in the parameter list for the event message. If the event message is later received by another process, the Workflow Engine sets the event parameters as item type attributes for that process. See: Event Message Structure, Oracle Workflow API Reference.
The activity also automatically sets the item type and item key for the current workflow process in the parameter list for the event message. If the event message is later received by another process, the Workflow Engine uses that item type and item key to automatically set the process that raised the event as the parent for the process that receives the event. See: SetItemParent, Oracle Workflow API Reference.
If you want to raise the new event using the event data and parameter list from an existing event message, you can define a special activity attribute named #EVENTMESSAGE2 for the raise event activity. Set the existing event message as the value of the #EVENTMESSAGE2 attribute, which must be an attribute of type event. If this attribute is defined, the activity retrieves the event data and parameter list from the specified event and sets them into the new event message before it is raised.
Note: If you also specified event data in the node's event details, however, the activity sets that event data into the event, overriding any event data from the #EVENTMESSAGE2 attribute. If you specified any additional parameters in activity attributes for the raise event activity, the activity also sets those parameters into the parameter list for the event message, overriding the values of any parameters with the same names from the #EVENTMESSAGE2 attribute.
For example, if the process previously received an event and you want to raise a new event with that event data, you can define the #EVENTMESSAGE2 attribute for the raise event activity and set its default value to the item attribute where the received event is stored.
A Send event activity retrieves the event name, event key, event message, outbound agent, and inbound agent, as specified in the node's event details. If no correlation ID is initially specified in the event message, the correlation ID is automatically set to the item key of the process. Then the Send event activity sends the event directly from the outbound agent to the inbound agent. The event details can be dynamically determined at runtime using item type attributes. You can also specify the event name, outbound agent, and inbound agent as predefined constants for the event activity node. See: To Create an Event Activity and To Define Event Details for an Event Node.
Note: A Send event activity does not raise the event to the Business Event System, so no subscription processing is performed.
A process activity represents a collection of activities in a specific relationship. When a process activity is contained in another process it is called a subprocess. In other words, activities in a process can also be processes themselves. There is no restriction on the depth of this hierarchy. See: To Create a Process Activity and Subprocesses, Oracle Workflow Administrator's Guide.
Caution: Oracle Workflow does not support using a subprocess activity multiple times within a process hierarchy.
Each function activity and event activity has a cost associated with it. The cost is a value representing the number of seconds it takes for the Workflow Engine to execute the activity. If you do not know how long it takes for the Workflow Engine to perform the activity, you can enter an estimated cost and update it later as you accumulate more information about its performance. Generally, you should assign complex, long running activities a high cost.
The valid range for cost is 0.00 to 1,000,000.00.
Attention: Although the cost is entered and displayed in seconds in Oracle Workflow Builder, it is actually converted and stored in the database as hundredths of a second.
In normal processing, the Workflow Engine completes the execution of a single activity before continuing to a subsequent activity. In some cases, an activity might take so long to process that background processing would be more appropriate.
You can define your Workflow Engine to defer activities with a cost higher than a designated threshold to a background process. The engine then continues processing the next pending eligible activity that may occur in another parallel branch of the process.
The default threshold for the Workflow Engine is 50 hundredths of a second. Activities with a cost higher than this are deferred to background engines. A background engine can be customized to execute only certain types of activities. You can set the workflow engine threshold through SQL*Plus. See: Setting Up Background Engines, Oracle Workflow Administrator's Guide, To Set Engine Thresholds, Oracle Workflow Administrator's Guide, and Deferring Activities, Oracle Workflow Administrator's Guide.
To Create a Notification Activity
Select the item type that you want to create a notification for in the navigator tree, then choose New Notification from the Edit menu. Define your notification activity in the Activity property page that appears.
Notification Activity Property Page
You can also select a message in the navigator tree and drag and drop the message into the Notifications branch of the same item type to create a notification activity that sends that message.
A notification activity must have an Internal Name (all uppercase and no leading/trailing spaces) and a Display Name, which is the translatable name that appears in your process diagram. Use the description to provide an explanation about this activity.
Attention: To update the internal name for an activity once it is defined, you must use a special SQL script called wfchact.sql. You should only use this script to correct errors in an activity's internal name during design time. Do not use this script to rename activities that are involved in running instances of processes. See: Wfchact.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Indicate the result type (a predefined Lookup Type) for this activity. Result types list the possible results returned by this activity. Your workflow diagram may branch depending on the value returned by your completed activity. See: To Create Lookup Types.
You can choose <None> as the result type if your activity does not return a value, or if your workflow process does not depend on the value returned.
Select the name of the message you want this notification to send. See: To Create a Message.
If you plan to assign this notification to a role consisting of multiple users and you want to send an individual copy of this notification to each user in the role, then check Expand Roles. If you uncheck Expand Roles, then only one copy of the notification is delivered to the role as a whole. See: Notification Activity.
You can optionally specify a PL/SQL stored procedure in the Function field. The procedure is known as a post-notification function and lets you couple processing logic to the notification activity. See: Standard API for PL/SQL Procedures Called by Function Activities and Post-Notification Functions, Oracle Workflow API Reference.
If you check Expand Roles, and you assign a message that has a special Result to this notification activity, then use the Function field to specify the name of a custom PL/SQL stored procedure that tallies the responses you get back from each of the recipients of this notification. Specify the procedure using the format: <package_name>.<procedure_name>. See: Voting Activity.
Choose an icon that identifies your activity. You can use any icon, as long as the icon is stored in a .ico file, to symbolize the action of an activity. See: Adding Custom Icons to Oracle Workflow, Oracle Workflow Administrator's Guide.
Choose Browse to view the icon files listed in the workflow icons subdirectory.
You can also drag and drop icon files from the Windows Explorer or File Manager onto an activity in your navigator tree to assign that icon to the activity.
Choose Apply to save your changes.
Select the Details tab to display and modify optional Details of the activity. See: To Define Optional Activity Details.
Select the Roles tab page to specify the roles that have access to this notification activity. (This functionality will be supported in a future release.)
Select the Access tab page to set the access levels allowed to modify this notification. See: Allowing Access to an Object.
Choose OK to save your changes and close the property pages.
The notification activity now appears beneath Notifications in the navigator tree. You can review or edit the properties of this activity at any time by double-clicking on the activity in the navigator tree or by selecting the activity and choosing Properties from the Edit menu or by pressing Enter on your keyboard.
To Create a Function Activity
Select the item type that you want to create a function for in the navigator tree, then choose New Function from the Edit menu. Define your function activity in the Activity property page that appears.
Function Activity Property Page
A function activity must have an Internal Name (all uppercase and no leading/trailing spaces) and a Display Name, which is the translatable name that appears in your process diagram. Use the description to provide an explanation about this activity.
Attention: To update the internal name for an activity once it is defined, you must use a special SQL script called wfchact.sql. You should only use this script to correct errors in an activity's internal name during design time. Do not use this script to rename activities that are involved in running instances of processes. See: Wfchact.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Enter the name of the function you want this activity to execute. In the Type field, specify whether the function is a PL/SQL function, an External function, or an External Java function.
For a PL/SQL function, set the function type to PL/SQL and specify the function as <package_name>.<procedure_name>. The function must be defined according to a standard API. See: Standard API for PL/SQL Procedures Called by Function Activities.
For an external function activity, set the function type to External. The Workflow Engine enqueues an entry in the "Outbound" queue and sets the correlation value of that entry to a value composed of the Workflow schema name and the item type in the following format:
<schema_name><item_type>
See: Workflow Queue APIs, Oracle Workflow API Reference.
You must create your own queue handler to search for this type of record on the "Outbound" queue. The queue handler must execute the action associated with the record and seed the result of the action onto the "Inbound" queue. The background engine then takes care of messages on the inbound queue and restarts your original workflow process. See: Deferred Processing, Oracle Workflow API Reference.
For an external Java function activity, set the function type to External Java and enter the class name of your custom Java class as the function name. This functionality is currently only available for the standalone version of Oracle Workflow. If the custom class is within a package, prefix the class name with the package name in the following format:
<customPackage>.<customClass>
The Java class must be defined according to a standard API. See: Standard API for Java Procedures Called by Function Activities.
The Workflow Engine enqueues an entry in the 'Outbound' queue. The Java Function Activity Agent dequeues messages of this type, executes your Java program, and enqueues the results onto the 'Inbound' queue. The background engine then takes care of messages on the inbound queue and restarts your original workflow process. See: Setting Up the Java Function Activity Agent, Oracle Workflow Administrator's Guide and Deferred Processing, Oracle Workflow API Reference.
Note: These 'Outbound' and 'Inbound' queues are separate from the queues used for the Business Event System. See: Workflow Queue APIs, Oracle Workflow API Reference.
Note: To execute external Java function activities, you must include your JAR files in your CLASSPATH.
Indicate the result type (a predefined Lookup Type) for this activity. Result types list the possible results returned by this activity. Your workflow diagram may branch depending on the value returned by your completed activity. See: To Create Lookup Types.
You can choose <None> as the result type if your activity does not return a value, or if your workflow process does not depend on the value returned.
Specify the cost of this function activity. See: Activity Cost.
Choose an icon that identifies your activity. You can use any icon, as long as the icon is stored in a .ico file, to symbolize the action of an activity. See: Adding Custom Icons to Oracle Workflow, Oracle Workflow Administrator's Guide.
Choose Browse to view the icon files listed in the workflow icons subdirectory.
You can also drag and drop icon files from the Windows Explorer or File Manager onto an activity in your navigator tree to assign that icon to the activity.
Choose Apply to save your changes.
Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.
Select the Roles tab page to specify the roles that have access to this function activity. (This functionality will be supported in a future release.)
Select the Access tab page to set the access levels allowed to modify this function. See: Allowing Access to an Object.
The function activity now appears beneath Functions in the navigator tree. You can review or edit the properties of this activity at any time by double-clicking on the activity in the navigator tree or by selecting the activity and choosing Properties from the Edit menu or by pressing Enter on your keyboard.
If your function requires input arguments, you can expose those arguments in Oracle Workflow Builder as attributes of the function activity. Function activity attributes behave as parameters whose values you can modify for each usage of the activity in a process. Function activity attributes are specific to a function activity and are not global to a process. See: To Define an Item Type or Activity Attribute.
To create a function activity attribute that references an item type attribute, select the referenced item type attribute in the navigator tree, and hold down your mouse select button as you drag the item type attribute to your function activity. The Default Value region is automatically set to Item Attribute and references the originating item attribute.
When you include a function activity as a node in a process, you can assign a value to the function activity attribute that is specific to that node. See: To Define Activity Attribute Values.
To Create an Event Activity
Select the item type that you want to create an event for in the navigator tree, then choose New Event from the Edit menu. Define your event activity in the Activity property page that appears.
Event Activity Property Page
An event activity must have an Internal Name (all uppercase and no leading/trailing spaces) and a Display Name, which is the translatable name that appears in your process diagram. Use the description to provide an explanation about this activity.
Attention: To update the internal name for an activity once it is defined, you must use a special SQL script called wfchact.sql. You should only use this script to correct errors in an activity's internal name during design time. Do not use this script to rename activities that are involved in running instances of processes. See: Wfchact.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Choose an icon that identifies your activity. You can use any icon, as long as the icon is stored in a .ico file, to symbolize the action of an activity. See: Adding Custom Icons to Oracle Workflow, Oracle Workflow Administrator's Guide.
Choose Browse to view the icon files listed in the workflow icons subdirectory.
You can also drag and drop icon files from the Windows Explorer or File Manager onto an activity in your navigator tree to assign that icon to the activity.
Select the Event Action for the activity.
Receive - Receive an event from the Business Event System.
Raise - Raise an event to the Business Event System.
Send - Send an event directly from one Event agent to another agent without re-raising the event to the Business Event System.
Note: Depending on the event action you select, you may need to define item type attributes for some or all of the following event details:
Event Name
Event Key
Event Message
Event Data
Out Agent
To Agent
When you include the event activity as a node in a process, you can use the item type attributes to specify where to store or retrieve the required event detail information for that node. The item type attributes that you use for event details must be associated with the same item type as the event activity itself. See: To Define an Item Type or Activity Attribute and To Define Event Details for an Event Node.
If you are defining a Receive event activity, you can optionally enter an Event Filter to specify the event that the activity can receive.
To allow the activity to accept only one specific event, enter the full internal event name.
To allow the activity to accept any event that is a member of a specific event group. enter the full internal event group name.
To allow the activity to accept any event, leave the Event Filter field blank.
See: To Define an Event.
Enter an optional cost for the activity. For event activities with the event actions Raise or Send, you can use the cost to defer long running activities to a background engine. See: Activity Cost.
Choose Apply to save your changes.
Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.
Select the Roles tab page to specify the roles that have access to this function activity. (This functionality will be supported in a future release.)
Select the Access tab page to set the access levels allowed to modify this event. See: Allowing Access to an Object.
The event activity now appears beneath Events in the navigator tree. You can review or edit the properties of this activity at any time by double-clicking on the activity in the navigator tree or by selecting the activity and choosing Properties from the Edit menu or by pressing Enter on your keyboard.
For a raise event activity, if the event raised by the activity requires additional parameters to be included in the event message, you can define those parameters as attributes of the raise event activity. When the event is raised, the activity attributes are set as parameters in the parameter list for the event message. If the event message is later received by another process, the Workflow Engine sets the event parameters as item type attributes for that process. You can modify the values of the attributes for each usage of the raise event activity in a process. Event activity attributes are specific to an event activity and are not global to a process. See: To Define an Item Type or Activity Attribute.
Note: A Raise event activity also automatically sets the item type and item key for the current workflow process in the parameter list for the event message. If the event message is later received by another process, the Workflow Engine uses that item type and item key to automatically set the process that raised the event as the parent for the process that receives the event. See: SetItemParent, Oracle Workflow API Reference.
If you want to raise the new event using the event data and parameter list from an existing event message, you can also define a special activity attribute named #EVENTMESSAGE2 for the raise event activity. Set the existing event message as the value of the #EVENTMESSAGE2 attribute, which must be an attribute of type event. If this attribute is defined, the activity retrieves the event data and parameter list from the specified event and sets them into the new event message before it is raised.
Note: If you also specified event data in the node's event details, however, the activity sets that event data into the event, overriding any event data from the #EVENTMESSAGE2 attribute. If you specified any additional parameters in activity attributes for the raise event activity, the activity also sets those parameters into the parameter list for the event message, overriding the values of any parameters with the same names from the #EVENTMESSAGE2 attribute.
To create an event activity attribute that references an item type attribute, select the referenced item type attribute in the navigator tree, and hold down your mouse select button as you drag the item type attribute to your event activity. The Default Value region is automatically set to Item Attribute and references the originating item attribute.
When you include an event activity as a node in a process, you can assign a value to the event activity attribute that is specific to that node. See: To Define Activity Attribute Values.
For a receive event activity, if you want to match the event with one or more workflow processes based on a business key rather than sending the event to one particular workflow process, define a special activity attribute named #BUSINESS_KEY. This attribute must be of type text. Set the default value of the activity attribute to an item type attribute, and include logic in your workflow process to set that item type attribute to an appropriate business key value at runtime. For the workflow process to receive an event, this business key must match the event key. See: To Define an Item Type or Activity Attribute and Event Subscriptions for Standalone Oracle Workflow or Event Subscriptions for Oracle Applications.
To Create a Process Activity
Before you can draw a workflow process diagram, you must first create a process activity in the navigator tree to represent the process diagram.
Select the item type that you want to create a process activity for in the navigator tree, then choose New Process from the Edit menu. Define your process activity in the Activity property page that appears.
Process Activity Property Page
If a process activity is closed and you want to redisplay it, select the process activity in the navigator tree and press Enter or select Properties from the mouse menu button.
A process activity must have an Internal Name (all uppercase and no leading/trailing spaces) and a Display Name, which is the translatable name that appears in your process diagram. Use the description to provide an explanation about this activity.
Attention: To update the internal name of an activity once it is defined, you must use a special SQL script called wfchact.sql. You should only use this script to correct errors in an activity's internal name during design time. Do not use this script to rename activities that are involved in running instances of processes. See: Wfchact.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
Indicate the result type (a predefined Lookup Type) for this activity. Result types list the possible results returned by this process. See: To Create Lookup Types.
You can choose <None> as the result type if you do not need to record any specific result for the completion of your process.
Choose an icon that identifies your activity. You can use any icon, as long as the icon is stored in a .ico file, to symbolize the action of an activity. See: Adding Custom Icons to Oracle Workflow, Oracle Workflow Administrator's Guide.
Choose Browse to view the icon files listed in the workflow icons subdirectory.
You can also drag and drop icon files from the Windows Explorer or File Manager onto an activity in your navigator tree to assign that icon to the activity.
Check Runnable so that the process that this activity represents can be initiated as a top-level process and run independently. If your process activity represents a subprocess that should only be executed if it is called from a higher level process, then uncheck Runnable. See: CreateProcess, Oracle Workflow API Reference.
Caution: Oracle Workflow does not support reusing a subprocess activity multiple times within a process hierarchy. If you wish to use a subprocess more than once in a process, you must create a distinct copy of the subprocess for each instance needed.
Choose Apply to save your changes.
Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.
Select the Access tab page to set the access levels allowed to modify this process. The access you set for a process activity determines who has access to edit its process diagram. See: Allowing Access to an Object.
Choose Apply to save your changes, OK to save your changes and close the property page, or Cancel to cancel your changes and close the property page.
The process activity now appears beneath Processes in the navigator tree. You can review or edit the properties of this activity at any time by selecting the activity and choosing Properties from the Edit menu or by pressing Enter on your keyboard.
To Define Optional Activity Details
Select the Details tab in the activity's property pages.
Details Property Page
If you are creating a process activity, you can specify an error process to execute in the event that an error occurs in the current process. Enter the internal name of the item type that owns the error process and then specify the internal name of the error process activity to execute. Note that the error process item type does not need to be open in your current Oracle Workflow Builder session for you to define it here. See: Error Handling for Workflow Processes.
Note: Both the error item type and the error process must be specified for an error process to be launched when an error occurs. The error item type defaults to WFERROR, the internal name for the System: Error item type. If you want to launch one of the predefined error processes provided in this item type, you must enter the internal name of that process. You can also enter a custom error item type and process.
If you assign one of the predefined error processes to your activity, you can customize the behavior of the error process by defining two special item type attributes within your own item type. A WF_ADMINISTRATOR attribute lets you specify the role to which Oracle Workflow sends an error notification, and an ERROR_TIMEOUT attribute lets you specify whether the error notification times out. See: Customizing Error Notifications for an Item Type.
The effective date tells you when this version of the activity is available for the Workflow Engine to execute. If the Effective Date field is blank, the activity is effective immediately.
You set the effective date when you save your changes using the Save As option in the File menu. All your activity modifications share the same effective date when you save.
Select a value for On Revisit to determine how the Workflow Engine handles this activity when it is transitioned to more than once. If this activity is the first activity that is revisited, as in a loop, you should set On Revisit to specify how you want the Workflow Engine to process the loop. The first activity in a loop is also called the pivot activity. For all other activities in a loop, the value of On Revisit is irrelevant.
If On Revisit is set to Ignore, the Workflow Engine executes the activity only once, and ignores the activity for all subsequent revisits.
If On Revisit is set to Reset, the Workflow Engine resets the completed activities in the loop by traversing through the loop in forward order from the pivot activity, executing each activity in CANCEL mode. You can include special logic in each function's CANCEL mode to undo prior operations. The Workflow Engine then traverses through the loop in forward order, reexecuting each activity, starting with the pivot activity, in RUN mode.
If On Revisit is set to Loop, the Workflow Engine simply reexecutes the pivot activity and all activities that follow in the loop, without resetting, as if they have never been executed before. See: Looping, Oracle Workflow API Reference.
The version number identifies which revision of the activity you are examining. The engine ensures that it uses the most recent updates to an activity by using the latest effective version number of that activity.
Choose Apply to save your changes.
To Copy an Activity
Hold down your mouse select button as you drag the activity to the item type branch you want to copy it to.
If you copy the activity within the same item type, a property page will appear prompting you for a new unique internal and display name for the copied activity.
Note: You can also use the Copy and Paste options in the Edit menu.
When you are done, choose OK.
Note: Copying a function, event, or notification activity also copies any attributes or message associated with it, respectively.
Related Topics
Using the Edit Button in a Property Page
You can create a voting activity that lets you send a notification to a group of users in a role and tally the responses from those users. The results of the tally determine the activity that the process transitions to next.
A voting activity is a notification activity that first sends a notification message to a group of users and then performs a PL/SQL post-notification function to tally the users' responses (votes).
The activity attributes you define and the following four fields in the property pages of the notification activity determine its voting behavior:
Message field
Result Type field
Expand Roles check box
Function field
Creating a Voting Activity
Create a voting lookup type that contains the responses you want to tally in your voting activity. See: To Create Lookup Types.
Create a voting message that prompts a recipient to respond with one of the values in the voting lookup type. Complete the Result tab for the message. Set the lookup type in the Result tab to the voting lookup type defined in Step 1. See: To Create a Message.
Select the item type that you want to create a voting activity for in the navigator tree, then choose New Notification from the Edit menu.
Specify an Internal Name (all uppercase and no leading/trailing spaces) and a Display Name. Use the description to provide an explanation about this voting activity.
Attention: To update the internal name for an activity once it is defined, you must use a special SQL script called wfchact.sql. You should only use this script to correct errors in an activity's internal name during design time. Do not use this script to rename activities that are involved in running instances of processes. See: Wfchact.sql, Oracle Workflow Administrator's Guide.
Caution: Do not include colons ":" or leading/trailing spaces in your internal name.
The Result Type field must contain the lookup type that lists the responses that you want the voting activity to tally. This is the voting lookup type defined in Step 1.
In the Message field, select the name of the voting message you created in Step 2. The voting message prompts the recipient for a response. The response choices are one of the predefined values specified in your voting lookup type.
Check Expand Roles so that the Workflow Engine polls for responses from the multiple users in the role rather than just from the first user in the role that replies. See: Notification Activity.
In the Function field, specify a function that tallies the responses from users. You can use the PL/SQL procedure WF_STANDARD.VOTEFORRESULTTYPE that the Standard Vote Yes/No activity calls. WF_STANDARD.VOTEFORRESULTTYPE is a generic tallying function. The Result Type that you specify for the voting activity defines the possible responses for the function to tally. The activity attributes that you define for the voting activity determine how the function tallies the responses. See: Vote Yes/No Activity.
Alternatively, you can specify your own custom tallying function, but you should make sure it conforms to the standard API for function activities. Specify the procedure using the format: <package_name>.<procedure_name>. See: Standard API for PL/SQL Procedures Called by Function Activities.
Choose Apply to save your changes.
Select the Details tab to display and modify the Details property page of the activity. See: To Define Optional Activity Details.
Select the Roles tab page to specify the roles that have access to this notification activity. (This functionality will be supported in a future release.)
Select the Access tab page to set the access levels allowed to modify this notification. See: Allowing Access to an Object.
If you use the WF_STANDARD.VOTEFORRESULTTYPE tallying function, create a custom activity attribute of type Number for each possible voting response. Remember that each possible voting response is a lookup code associated with the voting activity's result type. Hence, when you define your custom activity attribute, the internal name of the activity attribute must match the internal name of the lookup code, that is, the response value.
The value of the activity attribute can either be blank or a number that represents the percentage of votes required for a particular result. If you provide a percentage, then the result is matched if the actual tallied percentage for that response is greater than your specified percentage. If you leave an activity attribute value blank, then the Workflow Engine treats the response for that activity attribute as a default. In other words, if no particular percentage is satisfied after the votes are tallied, then the response that received the highest number of votes among those associated with a blank activity attribute becomes the result.
Note: If the tallied votes do not satisfy any response percentages and there are no default responses (blank activity attributes) specified, the result is #NOMATCH. If a <No Match> transition from the voting activity exists, then the Workflow Engine takes this transition, otherwise, it takes the <Default> transition. If no <Default> transition exists, it raises an error that no transition for the result is available (ERROR:#NOTRANSITION).
Note: If the tallied votes satisfy more than one response percentage or if no response percentage is satisfied, but a tie occurs among the default responses, the result is #TIE. If a <Tie> transition from the voting activity exists, then the Workflow Engine takes this transition, otherwise, it takes the <Default> transition. If no <Default> transition exists, it raises an error that no transition for the result is available (ERROR:#NOTRANSITION).
If you use the WF_STANDARD.VOTEFORRESULTTYPE tallying function, then in addition to defining your set of custom activity attributes, you must also define an activity attribute called Voting Option, whose internal name must be VOTING_OPTION. You can also copy the Voting Option activity attribute from the Vote Yes/No standard activity.
The Voting Option activity attribute specifies how the votes are tallied. The possible values are:
"Wait for All Votes" - the Workflow Engine waits until all votes are cast before tallying the results as a percentage of all the users notified. If a timeout condition occurs, the Workflow Engine calculates the resulting votes as a percentage of the total votes cast before the timeout occurred.
"Tally on Every Vote" - the Workflow Engine keeps a running tally of the cumulative responses as a percentage of all the users notified. If a timeout condition occurs, then the responses are tallied as a percentage of the total number of votes cast. Note that this option is meaningless if any of the custom response activity attributes have a blank value.
"Require All Votes" - the Workflow Engine evaluates the responses as a percentage of all users notified only after all votes are cast. If a timeout condition occurs, the Workflow Engine progresses along the standard timeout transition, or if none is available, raises an error, and does not tally any votes.
Related Topics
Simple Majority
The following table shows the custom response activity attribute value assigned to each response for a simple majority voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| A | 50 |
| B | 50 |
| C | 50 |
The result is any response that gets more than fifty percent of the votes. If no response gets more than fifty percent, the result is that no match is found (#NOMATCH).
Simple Majority with Default
The following table shows the custom response activity attribute value assigned to each response for a simple majority with default voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| A | 50 |
| B | 50 |
| C | blank |
If response A gets more than fifty percent of the votes, A is the result. Similarly if response B gets more than fifty percent of the votes, B is the result. If neither response A nor B gets more than fifty percent of the votes, then C is the result.
Simple Majority with Multiple Defaults
The following table shows the custom response activity attribute value assigned to each response for a simple majority with multiple defaults voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| A | 50 |
| B | blank |
| C | blank |
If response A gets more than fifty percent of the votes, A is the result. If A gets fifty percent of the votes, or less, then response B or C is the result depending on which of the two received the higher number of votes. If A gets fifty percent of the votes, or less, and both B and C receive the same number of votes, then the result is a tie (#TIE).
Popularity
The following table shows the custom response activity attribute value assigned to each response for a popularity voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| A | blank |
| B | blank |
| C | blank |
The result is the response that gets the highest number of votes.
Black Ball
The following table shows the custom response activity attribute value assigned to each response for a black ball voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| YES | 100 |
| NO | 0 |
Any vote for response NO makes NO the result.
Jury
The following table shows the custom response activity attribute value assigned to each response for a jury voting method.
| Response | Custom Response Activity Attribute Value |
|---|---|
| GUILTY | 100 |
| NOT_GUILTY | 100 |
A unanimous response is required, otherwise no match is found (#NOMATCH).
Related Topics
You can delete an object in Oracle Workflow Builder even if the object is referenced by other objects, assuming the object is not protected against customizations. If the object you want to delete is referenced by other objects, a Workflow Error dialog box appears, warning you about the foreign key references that will break. You can proceed to delete the object anyway or cancel the action. If you choose to delete, then when you save or verify the workflow process definition, a Workflow Error dialog box appears, reporting all broken foreign key references that exist in the definition.
As a result of this behavior, you can load workflow definitions with invalid foreign keys into Oracle Workflow Builder to correct. Oracle Workflow Builder preserves the original internal name reference for any missing foreign key, and displays it in a validation error message when you load the process definition. You can restore a broken foreign key reference in a process definition by recreating the deleted object with its original internal name under its original item type.
You can also delete an entire item type definition in Oracle Workflow Builder.
Note: If you want to delete an item type attribute from a workflow definition in a database, you must use Oracle Workflow Builder to connect to that database in order to perform the deletion. Deleting an item attribute from a workflow definition stored in a flat file and then uploading that flat file definition to a database will not delete the item attribute from the definition stored in the database. To delete an item attribute completely, you must delete it from your flat file definition and also delete it specifically from any databases in which that workflow item type is loaded while connected to those databases.
Before you modify the definitions of any Workflow objects, you should ensure that your changes will not adversely affect any active work items that are based on those definitions. Changes to Oracle Workflow objects have different effects on active work items depending on whether or not the objects support versioning.
For a Workflow object, versioning means that either the object itself or the object that owns it supports multiple occurrences of the same object in the database, distinguished only by a version number, begin date, and end date. For example, the following table shows two versions of a Vote activity that could exist simultaneously in the WF_ACTIVITIES table.
| Name | Version | Begin Date | End Date | Message | Lookup Type |
|---|---|---|---|---|---|
| Vote | 1 | 01-JAN-1998 | 31-DEC-1998 | Vote Message | Yes/No |
| Vote | 2 | 01-JAN-1999 | <blank> | New Vote Message | Approval |
When you modify a Workflow object that supports versioning, both the original version and the new version exist in the database. Any active work items that reference that object will continue to completion still using the same version that was in effect when the work items were initiated. Only new work items initiated after the change will use the new version.
In the above example, work items that are initiated between January 1, 1998 and December 31, 1998 will send the message Vote Message with result options of Yes or No, whether the work items are completed before January 1, 1999 or not. Only work items that are initiated on or after January 1, 1999 will send the message New Vote Message with result options of Approve or Reject.
Note: All process definition information is versioned.
When you modify a Workflow object that does not support versioning, however, the previous definition of the object is updated and only the modified definition exists in the database. Any active work items that reference that object will use the modified object after the change.
If the modified object is no longer compatible with the rest of the workflow definition used by the work item, errors may arise. To avoid such errors, you must take all references to the object into consideration when planning your changes to ensure that the changes do not cause any incompatibility.
Note: If your situation allows, you can avoid the risk of backward incompatibility by aborting and restarting all active work items after you make your changes. This method forces the restarted work items to use the modified definitions of all Workflow objects, including those that support versioning as well as those that do not.
The following Workflow objects support versioning:
Notifications
Functions
Events
Processes and subprocesses
Process activities (nodes)
Activity attributes
Activity attribute values
Activity transitions
When you modify any of these objects in the Workflow Builder and save them to the database, the Workflow Loader does not update the existing definition of the object. Instead, a new version of the object or owning object is created.
As a result, you can modify any of these objects without affecting active work items that were initiated before the change.
For example:
If you update a notification activity to reference a new message, the notification will be versioned.
If you update a function activity to reference a new lookup type, the function will be versioned.
If you update a function activity to reference a new API, the function will be versioned.
If you remove a process activity, or node, from a process diagram, the owning process will be versioned, as well as all the process activities that exist within the process.
If you add an activity attribute to an activity, the owning activity will be versioned.
The modifications in all of these examples will affect only work items that are initiated after the changes are made.
The following Workflow objects do not support versioning:
Item attributes
Messages
Lookups
PL/SQL code referenced by function activities
When you modify any item attributes, messages, or lookups in the Workflow Builder and save them to the database, the Workflow Loader updates the existing definition of the object. Also, if you modify the existing PL/SQL API for a function activity, the function activity will reference the updated API stored in the database.
As a result, if you modify any of these objects, your changes immediately affect any active work items that reference the object. Plan your changes carefully to ensure that the changes do not cause any backward incompatibility.
Note: The Workflow Builder does not support the editing of PL/SQL code. PL/SQL code is listed as a Workflow object here solely for the purpose of explaining the consequences of changing the code referenced by a Workflow function activity.
When a work item is initiated, Oracle Workflow creates a runtime copy of each item attribute that is defined for that item type. The Workflow Engine refers to these runtime copies whenever an item attribute is referenced in the PL/SQL code for a function activity in the workflow process.
Adding a new item attribute after work items have been initiated will not affect the active work items. However, these work items will not include the new item attribute unless you specifically create the attribute for them by calling the AddItemAttr() or AddItemAttributeArray APIs. If you also add references to the new item attribute in the existing PL/SQL code within the workflow process, those references may cause errors in active work items that do not include the attribute.
For example, if you change the PL/SQL API for a function activity by calling a Workflow Engine API to communicate with a new item attribute, the function activity will fail for active work items that do not have the new item attribute defined.
You should plan carefully when making any modifications to the existing PL/SQL code within a workflow process to ensure that you do not add references to a new item attribute without also creating the item attribute for active work items that require it. See: PL/SQL Code.
Note: You can, however, add references to new item attributes in the API that starts a workflow process, without making special provisions for active work items. For example, you can call the SetItemAttribute or SetItemAttributeArray APIs to populate the new item attributes at the start of the process. Active work items will not be affected by such changes, since these work items have already passed through this code.
When the Workflow Engine requests the Notification System to send a message, the Notification System creates a notification attribute in the notification tables for every message attribute. The notification attribute rows contain the variable data that will be token-replaced into the message body, including the subject line and body text, at runtime.
The message body, however, is not copied into the notification tables. Instead, the message body is referenced by the various Notification System APIs at runtime, when the notification is displayed to the user. As a result, any modifications to a message body will affect notifications in active work items that were sent before the change, as well as notifications that are sent after the change.
You can make certain types of modifications to a message body without risking incompatibility errors. These modifications include:
Adding static text
Editing static text
Removing static text
Removing message attribute tokens
For example, if you add a static sentence such as "Please approve within five days" to a message body, all notifications in active work items will include the additional sentence when you access the notifications. The Notification System can display the modified message body without any errors because no further information is required to resolve the additional sentence.
However, inappropriate modifications, such as adding tokens for newly created message attributes, may cause notifications in active work items to be displayed incorrectly. You should plan your changes carefully to avoid errors.
If you need to add tokens for new message attributes to a message body, you should implement the change by creating a new message rather than by modifying the existing message. You can attach the new message to your existing notification activity without affecting active work items, since notification activities support versioning.
For example, if you create a new message attribute such as Approver Name and you add a token for that attribute in the message body, all notifications in active work items will include the new token when you access the notifications. However, notifications that were sent before the change will not include the new message attribute Approver Name as a notification attribute. The Notification System will not be able to resolve the reference to the new message attribute and will display the token "&APPROVER_NAME" in the notifications instead.
In this example, instead of modifying the original message body, you should create a new message that includes the new message attribute, add the token for the new attribute to the body of the new message, and attach the new message to your notification activity. When you save your changes, the notification activity will be versioned. Then active work items will continue to reference the old version of the notification activity, and the incompatible token will not appear in those notifications.
Lookup types have the following important uses in Oracle Workflow:
Determining the possible completion statuses (lookup codes) for workflow activities
Determining the possible completion statuses (lookup codes) for 'Respond' message attributes.
Inappropriate modifications to lookup types may cause active work items that reference those lookup types to fail.
To avoid errors caused by backward incompatibility, follow these guidelines for lookup types that are referenced by active work items:
Do not delete lookup types.
Do not delete lookup codes from existing lookup types.
Do not add lookup codes to existing lookup types.
If you need to make any of the above changes, you should implement the change by creating a new lookup type rather than by modifying the existing lookup type.
You can attach new lookup types to existing activities without affecting active work items, since activities support versioning. However, you should not attach new lookup types to existing message attributes, since Workflow messages do not support versioning.
The following examples show some errors that can be caused by inappropriate lookup type modifications:
If you add a lookup code to a lookup type that is referenced by a 'Respond' message attribute, the new lookup code will be available for users to select as a response to a notification. However, previous versions of the notification activity will not have branching logic modeled for the new lookup code. If a user selects the new code, the process will enter an 'ERROR' state.
If you delete a lookup code from a lookup type that is referenced by a 'Respond' message attribute, users will no longer be able to choose that result code to respond to a notification.
Although function activities support versioning, the underlying PL/SQL code does not support versioning, unless you implement versioning for your code yourself. Modifying PL/SQL code without versioning changes the business flow for active work items that reference that code. Inappropriate modifications may cause these work items to fail.
To prevent changes in the PL/SQL API for a function activity from affecting active work items, you should implement the changes by creating a new API rather than by modifying the existing API. You can attach the new API to your existing function activity without affecting active work items, since function activities support versioning.
If you need to modify an existing API and you cannot create a new API instead, you should plan your changes carefully to ensure that the changes do not cause any backward incompatibility.
For example, if you plan to add a lookup code to the group of values that an API can return, you should first ensure that the function activity node has an outgoing transition, such as 'Default,' that the Workflow Engine can follow when the API returns that value. Otherwise, the process will enter an 'ERROR' state when that value is returned. If there is no appropriate outgoing transition, you must implement the change in a new API and update the process to model branching logic for the additional return value.
Also, if you change the existing PL/SQL API for a function activity by calling a Workflow Engine API to communicate with a new item attribute, you should ensure that you also create the new item attribute for active work items. Otherwise, the function activity will fail for active work items which do not have the new item attribute defined.
Calls to any of the following APIs with newly created item attributes as parameters may cause the function activity to fail if active work items do not have the item attributes defined:
wf_engine.SetItemAttrText
wf_engine.SetItemAttrNumber
wf_engine.SetItemAttrDate
wf_engine.SetItemAttrEvent
wf_engine.SetItemAttrFormattedDate
wf_engine.SetItemAttrDocument
wf_engine.SetItemAttrTextArray
wf_engine.SetItemAttrNumberArray
wf_engine.SetItemAttrDateArray
wf_engine.GetItemAttrText
wf_engine.GetItemAttrNumber
wf_engine.GetItemAttrDate
wf_engine.GetItemAttrEvent
wf_engine.GetItemAttrDocument
wf_engine.GetItemAttrClob
wf_engine.GetItemAttrInfo
To create copies of a new item attribute for active work items, call AddItemAttr() or one of the AddItemAttributeArray APIs. You can place this call either in a custom upgrade script or in an exception handler.
Upgrade script - Before you modify your API, write and execute a custom upgrade script that creates and populates the new item attribute for any active work items that reference that API. The following example shows one way to structure an upgrade script.
for <each active work item>
begin
wf_engine.AddItemAttr(itemtype,
itemkey,
'<new_attribute_name>');
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
end;
end loop;
Note: Active work items are identified as those items for which WF_ITEMS.END_DATE is null.
Exception handler - After the reference to the new item attribute in your modified API, add an exception handler to create and populate the attribute when the attribute does not already exist. The following example shows one way to structure such an exception handler.
procedure <procedure_name>
(itemtype in varchar2,
itemkey in varchar2,
actid in number,
funcmode in varchar2,
result in out varchar2)
is
begin
--
-- RUN mode - normal process execution
--
if (funcmode = 'RUN') then
-- your run code goes here
null;
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<existing_attribute_name>',
'<Existing attribute value>');
begin
wf_engine.SetItemAttrText(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
exception
when others then
if (wf_core.error_name = 'WFENG_ITEM_ATTR') then
wf_engine.AddItemAttr(itemtype,
itemkey,
'<new_attribute_name>');
wf_engine.setitemattrtext(itemtype,
itemkey,
'<new_attribute_name>',
'<New attribute value>');
else
raise;
end if;
end;
-- example completion
result := 'COMPLETE:';
return;
end if;
--
-- CANCEL mode - activity 'compensation'
--
-- This is in the event that the activity must be undone,
-- for example when a process is reset to an earlier point
-- due to a loop back.
--
if (funcmode = 'CANCEL') then
-- your cancel code goes here
null;
-- no result needed
result := 'COMPLETE';
return;
end if;
--
-- Other execution modes may be created in the future. Your
-- activity will indicate that it does not implement a mode
-- by returning null
--
result := '';
return;
exception
when others then
-- The line below records this function call in the error
-- system in the case of an exception.
wf_core.context('<package_name>',
'<procedure_name>',
itemtype,
itemkey,
to_char(actid),
funcmode);
raise;
end <procedure_name>;
Related Topics
