This chapter tells you how to use Oracle Workflow Builder to define the components necessary to compose a workflow process diagram.
This chapter covers the following topics:
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.
By default, when a work item is initiated, Oracle Workflow creates a runtime copy of each item attribute that is defined for that item type. You can optionally enhance performance for a process by specifying that the Workflow Engine should create runtime copies of item attributes only on demand. See: #ONDEMANDATTR Attribute.
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 E-Business Suite internal form function name and its optional form function parameters.
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 E-Business Suite 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 email, 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 email.
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 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 Application Framework region - A JSP call to an Oracle Application 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 email 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 a WF_PURGE API with the persistence type set to PERM
, calling the procedure WF_PURGE.TotalPerm( ), or running the Purge Obsolete Workflow Runtime Data concurrent program with the persistence type set to Permanent
.
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 the WF_PURGE APIs with the persistence type set to the default of TEMP
, or the Purge Obsolete Workflow Runtime Data concurrent program with the persistence type set to the default of Temporary
, 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 a WF_PURGE API. 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: The executable name for the Purge Obsolete Workflow Runtime Data 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, such as during background processing. 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 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.
PL/SQL documents can also be displayed in the subject line of a notification.
Oracle Workflow also supports using attributes of type document to embed an Oracle Application Framework region in a notification. See: Embedding Oracle Application Framework Regions in Messages.
Note: An Oracle Application 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.
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.
Important: 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.
Important: 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. In the format mask, use the number format element G
to represent the group separators and the number format element D
to represent the decimal character. See: Number Format Models, Oracle Database SQL Language Reference.
Date - Optionally provide a format mask for the date and a default value.
The format mask you specify must be among the date formats supported by Oracle E-Business Suite. To view the supported date formats, navigate to the Application Object Library Lookups window from the Oracle E-Business Suite Navigator by choosing Application Developer: Application > Lookups > Application Object Library, and query the ICX_DATE_FORMATS
lookup type. Oracle Workflow uses the format mask you specify when displaying the date attribute value in the user interface, such as in the Notification Details page, Respond to Notifications as Group page, and Vacation Rules page.
If you do not specify a format mask, or if you specify a format mask that is not supported by Oracle E-Business Suite, then Oracle Workflow displays the date attribute value according to the user's date format preference.
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 - 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 E-Business Suite 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, if you specify one, 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.
Important: 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 Application 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 email notification. For more information about Oracle Application Framework pages, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
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.example.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.
You can optionally add a prefix to the URL attribute value to control whether an image URL attribute appears in the message body as a link or as an inline image when the notification is viewed from the Notification Details Web page or as an HTML-formatted email.
LNK:
Oracle Workflow renders the URL attribute as a link with the <A HREF>
tag. Use the following format:
LNK:<image_URL>
For example:
LNK:http://www.example.com/redStar.gif
IMG:
Oracle Workflow renders the URL attribute as an inline image with the <IMG>
tag. Use the following format:
IMG:<image_URL>
For example:
IMG:http://www.example.com/redStar.gif
If you define a URL for one of the listed image types without a prefix, then the image appears inline in the message body by default.
When defining a URL attribute to point to 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.
Additionally, for inclusion in an email notification the image must be in a location to which the notification mailer has access, whether that location is on a Web server or on the local file system.
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 email notification displays all URL attributes as the display name of the attribute, followed by a colon and the URL.
If you are defining a URL attribute that links to an Oracle Application 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 email notification. The page should also explicitly validate all parameters provided in the URL. For more information, see: Advanced OA Framework Development Topics > Security > Accelerated Validation > Bookmarkable Pages in the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
By default, when a user chooses an attached URL link to an Oracle Application Framework page in a notification, Oracle E-Business Suite 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 email notification, the user must also log into Oracle E-Business Suite before selecting a responsibility.
When you define a URL attribute for an Oracle Application Framework page, you can optionally include Oracle Application Framework URL parameters to specify the responsibility and application context with 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.
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 E-Business Suite 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 email notification, the user must also log into Oracle E-Business Suite 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 Application Framework region
Note: If you define a message attribute of type document, you must assign that attribute a source of Send. You cannot use a document attribute as a respond message attribute.
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 be displayed in the subject line of a notification, 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 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. You can optionally use the WF_MAIL_UTIL.EncodeBLOB procedure to encode the binary data to base64. See: UTL_RAW, Oracle Database PL/SQL Packages and Types Reference and EncodeBLOB, Oracle Workflow API Reference.
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 Application 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 Application Framework Regions in Messages.
An Oracle Application 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.
Important: 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
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" checkbox 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
In the Options region, use the 'Preserve Customizations' and 'Lock at this Access Level' checkboxes 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.
Because lookup types can be referenced from multiple item types, the internal name and the display name for a lookup type must both be globally unique across all item types. You may find it useful to include a prefix such as the item type name to ensure that the lookup type internal name and display name are unique.
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.
The internal name and the display name for a lookup type must both be globally unique across all item types. You may find it useful to include a prefix such as the item type name to ensure that the lookup type internal name and display name are unique.
Important: 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.
Important: 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 result 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. You can also embed an Oracle Application 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.
Note: You can display message attributes specific to particular types of notifications in the Personal Worklist by using worklist flexfields. See: Defining Specialized Worklist Views with Worklist Flexfields, Oracle Workflow Administrator's Guide.
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: If your workflow process will be translated into other languages, you can embed PL/SQL document message attributes in the subject or body of a message to enable translation of context-sensitive content. Include code in your workflow process that determines the context-sensitive values and provides the corresponding translated values dynamically at runtime.
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.
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 that is sent to an unexpanded recipient role 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 or transfers that request, the action history contains rows for those actions also. If Oracle Workflow cannot apply a vacation rule because the rule would reassign the notification to the process owner or the from role for the notification and the WF: Disable Reassign to Submitter profile option is set to Yes
to disable such reassignments, then the action history contains a row showing that the reassignment was prevented and the rule was not applied.
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.
Note: Beginning in Release 12.2.10, Oracle Workflow also includes action history for standalone notifications that are sent by calling the WF_NOTIFICATION.Send() API directly outside of a workflow process.
The formatting of the action history table depends on whether the notification contains an embedded Oracle Application Framework region.
If the notification contains an Oracle Application 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 Application Framework region.
If the notification does not contain any Oracle Application Framework regions, but does contain references to other types of message attributes, then the table is formatted in a standard Oracle Workflow format.
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 Application Framework region, PL/SQL document, or PL/SQL CLOB document. See: #HISTORY Attribute, Embedding Oracle Application Framework Regions in Messages, and WF_NOTIFICATION() Message Function.
You can use the special message attribute named #RELATED_HISTORY
to include the action history of one notification in another notification. See: #RELATED_HISTORY Attribute.
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.
By default, the tables are created as Oracle Application Framework regions, unless the message body also includes any message attribute tokens that reference values other than Oracle Application Framework regions. In this case, the tables are created in a standard Oracle Workflow format. See: Embedding Oracle Application Framework Regions in Messages.
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 to use a custom action history region instead. See: Action History and #HISTORY Attribute.
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 fields in the Reassign Notifications page. See: To Reassign a Notification to Another User, 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: If the notification recipient has grants for the Oracle Workflow user list of values that allow access only to specific partitions within the Oracle Workflow directory service, then the recipient can only select roles from those partitions in the Assignee fields in the Reassign Notifications page and the Vacation Rule: Response page, even if the role you specify as the #WF_REASSIGN_LOV
attribute value also includes roles in other partitions. See: Configuring the Oracle Workflow User List of Values, Oracle Workflow Administrator's Guide.
However, note that the #WF_REASSIGN_LOV
attribute overrides any grants that restrict access to specific user and role values in the Oracle Workflow user list of values. If you define the #WF_REASSIGN_LOV
attribute, then the Assignee fields display the roles included in the #WF_REASSIGN_LOV
attribute value that are within the available partitions.
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, Oracle Workflow User's Guide.
Note: 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.
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 simply 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.
Note: Users who have workflow administrator privileges can reassign all notifications, regardless of any restrictions set through the #HIDE_REASSIGN
attribute. For users with workflow administrator privileges, Oracle Workflow always displays the Reassign button in the Notification Details page and allows reassignment from the Advanced Worklist, Personal Worklist, and self-service home page, even if the #HIDE_REASSIGN
attribute for a notification is set to Y
or B
. This ability to override restrictions on reassignment lets administrators intervene when necessary in exception cases.
Workflow administrator privileges are assigned in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
Note: The #HIDE_REASSIGN
attribute does not affect a user's ability to transfer a request for more information about a notification to another user. This attribute controls only the reassignment of the original notification.
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: The #HIDE_MOREINFO
attribute also determines whether the Request Information response link is included or excluded in HTML-formatted email 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 email notifications. The Notification Details page displays the Request Information button if the #HIDE_MOREINFO
attribute is not defined, while an HTML-formatted email 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 Email 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.
You can use a special message attribute with the internal name #MORE_INFO_PARTICIPANTS
to designate additional users or roles from whom the notification recipient can request more information. When a user chooses to request more information about a notification, the Request More Information From page or the email request template includes a list of workflow participants to whom the user can choose to send the request. By default, the list of workflow participants includes the following:
The owner of this workflow process and the owner of the parent process, if this process has a parent
The current recipient roles of all notifications sent by this workflow process or its parent process
The original recipient roles of all notifications sent by this workflow process or its parent process, if any notifications were reassigned
The From roles for all notifications sent by this workflow process or its parent process
If you want to designate additional users as participants from whom information about this message can be requested, create a role whose members are all the users that you want to add, and assign this role as the value for the #MORE_INFO_PARTICIPANTS
attribute. Then, when the notification recipient chooses to request more information, the users that belong to that role are added to the default list of workflow participants.
The #MORE_INFO_PARTICIPANTS
attribute must be of type role and must have a source of Send. You should specify an item type attribute as the value for the #MORE_INFO_PARTICIPANTS
attribute 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: To Respond to an HTML Email Notification, Oracle Workflow User's Guide and To Request More Information From Another User, Oracle Workflow User's Guide.
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. Also, Oracle Workflow automatically sets the From Role for a request for more information to the user who sent the request, and sets the From Role for a response providing more information to the user who sent the response.
The From Role for each notification is displayed in the Worklist Web page and in email notifications to give users additional information for reviewing and responding to the notifications. Additionally, the Notification Search page and Personal Worklist let you search for notifications based on the From Role. See: To View Notifications from the Advanced Worklist, Oracle Workflow User's Guide, Searching for Users' Notifications in Oracle E-Business Suite, Oracle Workflow Administrator's Guide, and To View Notifications from the Personal Worklist, Oracle Workflow User's Guide.
If the WF: Disable Reassign to Submitter profile option is set to Yes
, then Oracle Workflow does not allow a notification to be reassigned to the role specified as its From Role.
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.
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 E-Business Suite 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.
The signed response text for both types of signatures contains the notification header information and the response values entered by the user. You can optionally require the signed response text to include the notification message body as well.
Note: If the message body contains a link or an image, the signed response text includes the HTML code used to reference the link or image, rather than the content of the referenced file itself. The signed response text does not include notification attachments.
The #WF_SIG_POLICY
attribute must be either of type text or lookup.
To require a password-based signature without including the message body in the signed response text, set the value of the #WF_SIG_POLICY
attribute to PSIG_ONLY
.
To require a password-based signature and include the message body in the signed response text, set the value of the #WF_SIG_POLICY
attribute to PSIG_BODY
.
To require a certificate-based digital signature without including the message body in the signed response text, set the value of the #WF_SIG_POLICY
attribute to PKCS7X509_ONLY
.
To require a certificate-based digital signature and include the message body in the signed response text, set the value of the #WF_SIG_POLICY
attribute to PKCS7X509_BODY
.
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 five lookup codes with the display names Password Signature, Password Signature With Body, X509 Signature, X509 Signature With Body, and Default, representing the values PSIG_ONLY
, PSIG_BODY
, PKCS7X509_ONLY
, PKCS7X509_BODY
, 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.
Oracle Workflow records the status of requested and submitted signatures in the Signature Evidence Store, for both password-based signatures and certificate-based digital signatures. You can search for signatures in the Signature Evidence Store to check the status of a signature request and review details that provide evidence of the signature. If your business logic requires a signature to be validated as a prerequisite for other activities, your workflow can include a notification to an administrator to confirm the signature status before continuing. See: Reviewing Electronic Signature Details, Oracle Workflow Administrator's Guide.
To preserve electronic signature evidence for future reference, the Purge Obsolete Workflow Runtime Data concurrent program and the Oracle Workflow purging APIs by default do not delete any notifications that required signatures or their associated signature information. If you anticipate needing access to signature evidence after the associated workflow processes are complete, ensure that you choose to preserve signature data when purging. If you do not need to maintain signature evidence, you can choose to delete signature-related information when purging. See: Purging Workflow Data, Oracle Workflow Administrator's Guide and Workflow Purge APIs, Oracle Workflow API Reference.
For more information, see: Setting Up for Electronic Signatures, Oracle Workflow Administrator's Guide, Electronic Signatures, Oracle Workflow User's Guide, Viewing Responses, Oracle Workflow Administrator's Guide, and NtfSignRequirementsMet, Oracle Workflow API Reference.
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 sensitive notification content can be sent in email. If you specify that a notification's content must not be sent in email, users receive an email message that only informs them that they must access the notification through the Notification Details Web page instead to view its content and respond. To access the Notification Details page, users can either log into Oracle E-Business Suite separately, or, if their notification preference includes attachments and they are not assigned the WF_EXTERNAL_ROLE_NOEBS_ACCESS
role, use the Notification Detail Link. 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 email, 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 email to users whose notification preference is set to receive email.
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 email or not and sets that item type attribute accordingly.
Note: You can also choose to disable individual emails entirely for specific messages. In this case, no email notifications are sent for those messages, even if a user has a notification preference that includes individual emails. If you disable individual emails for a message, you do not need to set the #WF_SECURITY_POLICY
attribute for that message. Use the Email Notification Preference field in the Workflow Configuration page to configure the messages that are eligible to be sent in email. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
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 email 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 email 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.
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, if a notification with the #ATTACHMENTS
attribute is viewed in the Notification Details page, links to the specified Oracle E-Business Suite 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 Application Framework region. For more information about building an Oracle Application Framework region, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
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 Application 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 checkbox for the #HDR_REGION
attribute.
The Related Applications region in Oracle Application 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 Application Framework region. For more information about building an Oracle Application Framework region, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
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 Application 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 checkbox for the #RELATED_APPL
attribute.
In Oracle E-Business Suite, you can link attachments to a data record. For a workflow notification that includes an embedded Oracle Application Framework region, you can optionally use a special message attribute with the internal name #ATTACHMENTS
to include such Oracle E-Business Suite attachments when the notification is sent by email. In this case, the recipient does not need to log into Oracle E-Business Suite to view the attachments. Oracle E-Business Suite attachments of type Short Text and Long Text are attached to the email message as text files, Oracle E-Business Suite attachments of type URL are attached as HTML files, and Oracle E-Business Suite attachments of type File are attached as the file format in which they were uploaded.
If the recipient views the notification in the Notification Details page, the notification header displays an Attachment(s) heading with links to the Oracle E-Business Suite attachments.
The #ATTACHMENTS
attribute must be of type document and must have a source of Send. In the value for the attribute, specify the entity with which the attachments are associated and the primary keys used to identify the record with which the attachments are associated. Specify the #ATTACHMENTS
attribute in the following format:
FND:entity=<entity>&pk1name=<primary_key_1_name>&pk1value=<primary_key_1_value>&pk2name=<primary_key_2_name>&pk2value=<primary_key_2_value>&pk3name=<primary_key_3_name>&pk3value=<primary_key_3_value>&pk4name=<primary_key_4_name>&pk4value=<primary_key_4_value>&pk5name=<primary_key_5_name>&pk5value=<primary_key_5_value>
In the attribute value, replace the variables as follows:
<entity>
- Specify the entity name as it appears in the DATA_OBJECT_CODE column in the FND_DOCUMENT_ENTITIES table.
<primary_key_1_name>, <primary_key_2_name>, <primary_key_3_name>, <primary_key_4_name>, and <primary_key_5_name>
- Specify the names of the primary keys as they appear in the columns PK1_COLUMN, PK2_COLUMN, and so on in the FND_DOCUMENT_ENTITIES table.
<primary_key_1_value>, <primary_key_2_value>, <primary_key_3_value>, <primary_key_4_value>, and <primary_key_5_value>
- Specify the values of the primary keys as they appear in the columns PK1_VALUE, PK2_VALUE, and so on in the FND_ATTACHED_DOCUMENTS table.
Note: The Attach Content checkbox is not applicable for the #ATTACHMENTS
attribute. If you define this attribute, the specified attachments are included in the email notification, regardless of the setting of the Attach Content checkbox.
See: Using Attachments, Oracle E-Business Suite User's Guide.
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 Application Framework region, or as a PL/SQL or PL/SQL CLOB document that contains text or HTML. For more information about building an Oracle Application Framework region, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
The #HISTORY
attribute must be of type document and must have a source of Send. For an Oracle Application 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 Application 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 checkbox 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.
You can use a special message attribute with the internal name #RELATED_HISTORY
to include the action history of one notification in another notification. For example, if a workflow process contains a notification that submits a request for approval and another notification that informs the requestor whether the request was approved or rejected, the second notification can include the action history of the first notification to show the requestor more details about the approvers' decisions.
You can include related action history in both FYI (For Your Information) and response-required notifications. Each notification can only include the related action history for one related notification. The related notification can belong to the same work item or to a different work item, identified by the item type and item key.
The notification for which you define the #RELATED_HISTORY
attribute must be formatted using an embedded Oracle Application Framework region. See: Embedding Oracle Application Framework Regions in Messages.
The related action history table appears as an embedded Oracle Application Framework region. The default title for the table is Related Action History
. You can optionally specify a custom title to use instead. The related action history table includes the same columns as the default action history table for a notification's own action history. See: Action History.
The #RELATED_HISTORY
attribute must be of type text and must have a source of Send. Specify the value for this attribute in the following format:
{<title>}[<item_type>:<item_key>]<process_name>:<activity_label_name>
If you want to display a custom title for the related action history table, then replace <title>
with the custom title. If you want to use the default title, then you can omit {<title>}
from the attribute value.
If necessary, specify the item type and item key for the work item to which the related notification belongs.
If the related notification belongs to a different work item than this notification, then replace <item_type>
and <item_key>
with the item type and item key for that work item, respectively.
If the related notification belongs to a work item that is a parent of the work item to which this notification belongs, then replace <item_type>
with the item type for the parent work item. In this case Oracle Workflow derives the item key automatically, so you can omit :<item_key>
from the attribute value.
If the related notification belongs to the same work item as this notification, then you can omit [<item_type>:<item_key>]
from the attribute value.
If the activity node label name does not uniquely identify the activity node of the related notification within the item type, then replace <process_name>
with the internal name of the process to which the related notification activity node belongs. If the activity node label name is unique within the item type, then you can omit <process_name>:
from the attribute value.
Replace <activity_label_name>
with the label name of the related notification activity node whose action history you want to include.
For instance, the following example shows the attribute value for a related notification in another work item, fully qualified with the process name, specifying a custom table title.
{Approval History}[WFDEMO:1234]NOTIFYAPPROVER:NTF_APPROVE_REQUISITION
The following example shows the attribute value for a related notification in another work item, that is unique within its item type and does not require the process name to be specified, and that will be displayed with the default table title.
[WFDEMO:1234]NTF_APPROVE_REQUISITION
The following example shows the attribute value for a related notification in a parent work item, fully qualified with the process name, specifying a custom table title.
{Approval History}[WFDEMO]NOTIFYAPPROVER:NTF_APPROVE_REQUISITION
The following example shows the attribute value for a related notification in the same work item, fully qualified with the process name, specifying a custom table title.
{Approval History}NOTIFYAPPROVER:NTF_APPROVE_REQUISITION
The following example shows the attribute value for a related notification in the same work item, that is unique within its item type and does not require the process name to be specified, and that will be displayed with the default table title. Note that in this case only the activity node label name is required.
NTF_APPROVE_REQUISITION
You can either specify a constant value for the #RELATED_HISTORY
attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically determines the related notification details at runtime and sets that item type attribute accordingly. You can also token substitute individual arguments in the #RELATED_HISTORY
attribute value with other message attributes. The message attributes used for token substitution in turn can have constant values or can reference the values returned from item type attributes. See: To Token Substitute an Attribute.
For instance, the following example shows the attribute value using token substitution for a related notification in another work item, fully qualified with the process name, specifying a custom table title.
{&TITLE}[&ITEM_TYPE:&ITEM_KEY]&PROCESS_NAME:&ACTIVITY_LABEL_NAME
In this example the values for the title, item type, item key, process name, and activity label name are derived from the values of other message attributes named TITLE, ITEM_TYPE, ITEM_KEY, PROCESS_NAME and ACTIVITY_LABEL_NAME, respectively.
Note: The format for the #RELATED_HISTORY
attribute value has been extended to include enhancements introduced in Release 12.2, including the ability to display a custom title and to specify a related notification that belongs to a different work item. However, the enhanced format is backwardly compatible with the format used in previous releases, <process_name>:<activity_label_name>
. No changes are required to continue using any #RELATED_HISTORY
attributes that you defined previously.
You can use special message attributes to apply personalizations at different levels to Oracle Application 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 Application 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 email message for a notification, if the recipient has a notification preference to receive email notifications and the message is eligible to be sent by email according to the settings in the Email Notification Preference field in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
For example, if you want to customize notifications from a particular department, you can define the Notification Mailer 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 email 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 parameter value.
#WFM_REPLYTO
- Define this attribute for a message to specify the address of the email account that receives incoming messages, to which email notification responses 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 Address parameter value.
#WFM_HTMLAGENT
- Define this attribute for a message to specify the base URL that identifies the HTML agent that handles HTML notification responses. This URL is required to support email notifications with HTML attachments. The default URL for Oracle E-Business Suite is derived from the Applications Servlet Agent (APPS_SERVLET_AGENT
) profile option. You can define a different value for a particular notification mailer in the mailer's HTML Agent parameter. You can also override any other HTML agent value 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 agent for that message, overriding both the underlying default and the mailer's HTML Agent parameter value.
The HTML agent value for Oracle E-Business Suite should have the following format:
http://<server_name:port>/OA_HTML/
#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 email 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 email 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 email 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 email 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.
These message attributes are optional. You need to define them only when you do not want to use the recipient role's own language and territory preferences to generate the email notification.
Note: The notification mailer can only use installed languages. If you set the #WFM_LANGUAGE
attribute to a language that is not installed, the notification mailer generates the email notification with the base language for the database.
#WFM_RESET_NLS
- Define this attribute for a message to specify whether the notification mailer should encode the message with character encoding according to the notification recipient's preferred language.
Set the attribute value to Y
to encode the message with character encoding according to the language specified in the notification recipient's user preferences. Oracle Workflow takes the character encoding for the language either from the WF_LANGUAGES table or from the override settings specified in the Character Encoding Configuration page.
Set the attribute value to N
to send the message in the default character encoding for the database or the override character encoding specified in the Character Encoding Configuration page.
If the #WFM_RESET_NLS
message attribute is defined with a valid value for a notification, the notification mailer that sends the message will use the #WFM_RESET_NLS
attribute value when generating the email message, overriding the mailer's Reset NLS parameter value. For more information about how Oracle Workflow determines which character encoding to use, see: Configuring Character Encoding for Notification Mailers, Oracle Workflow Administrator's Guide.
Note: The #WFM_RESET_NLS
attribute takes effect at the notification message level. If the recipient role for the notification has multiple members, then the notification mailer applies the #WFM_RESET_NLS
attribute value for every email recipient.
Note: The notification mailer can only use installed languages. If you set the #WFM_LANGUAGE
attribute for a message to a language that is not installed, then the base language for the database takes effect. If you also define the #WFM_RESET_NLS
attribute for that message, it affects the encoding of the email message only for that base language.
#WFM_NODENAME
- Use this attribute in conjunction with the #WFM_FROM
and #WFM_REPLYTO
attributes, if required, to indicate that the response to a notification should be processed by a different mailer node than the one that sends the notification. If the #WFM_NODENAME
message attribute is defined for a notification, the response template generated from the notification will include the #WFM_NODENAME
attribute value in the NID line, overriding the sending mailer's Mailer Node Name parameter value.
#WFM_HTML_DELIMITER
- Define this attribute for a message to specify which characters the notification mailer uses to delimit response values in response templates for HTML-formatted email notifications. Valid values for the #WFM_HTML_DELIMITER
attribute are:
DEFAULT
- The notification mailer uses the default delimiters, currently set as the single quote ('
) for both the opening and the closing delimiter.
APOS
- The notification mailer uses the single quote, or apostrophe ('
), as both the opening and the closing delimiter. This setting is currently the same as the default.
QUOTE
- The notification mailer uses the double quote ("
) as both the opening and the closing delimiter.
BRACKET
- The notification mailer uses the left bracket ([
) as the opening delimiter and the right bracket (]
) as the closing delimiter.
Using single quotes as the delimiters accommodates email applications that cannot process double quotes in the <A HREF="mailto:"> tag for the response template link, but can accept single quotes. However, if you want users to be able to use apostrophes or single quotes in their response values without entering an escape character, you can use double quotes or brackets as the delimiters, depending on what your email application supports. For example, Microsoft Outlook Express does not support using double quotes, so if you use Microsoft Outlook Express, you can set the #WFM_HTML_DELIMITER
attribute to DEFAULT
, APOS
, or BRACKET
, but you should not set this parameter to QUOTE
. See: To Respond to an HTML Email Notification, Oracle Workflow User's Guide.
Note: If the #WFM_HTML_DELIMITER
attribute is set to an invalid value, the notification mailer throws an exception and uses the default delimiters instead.
If the #WFM_HTML_DELIMITER
message attribute is defined for a notification, the notification mailer that sends the message will use the #WFM_HTML_DELIMITER
attribute value to determine which delimiters to use for that notification, overriding the mailer's HTML_DELIMITER
parameter value.
Note: The #WFM_HTML_DELIMITER
attribute only controls the response templates for HTML-formatted notifications. This attribute does not apply to plain text notifications.
For more information, see: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide, Setting Up Notification Mailers, Oracle Workflow Administrator's Guide. 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 email message for a notification, if the recipient has a notification preference to receive email notifications and the message is eligible to be sent by email according to the settings in the Email Notification Preference field in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
For example, if you want to customize notifications from a particular department, you can define the message template 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 email notification processing.
#WFM_OPEN_MAIL
- Specify the template to use for email notifications that require a response, if you are using the templated response method.
#WFM_OPEN_MAIL_DIRECT
- Specify the template to use for email notifications that require a response, if you are using the direct response method.
Note: If you defined the #WF_SIG_POLICY
attribute for a message to require an electronic signature in users' responses, you do not need to define the #WFM_OPEN_MAIL
or #WFM_OPEN_MAIL_DIRECT
attributes for that message. The notification mailer always uses the Workflow Signature Required Mail message in the System: Mailer item type as the template for notifications that require an electronic signature, overriding any other template setting.
#WFM_OPEN_MAIL_FYI
- Specify the template to use for email 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.
See: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide.
You can use special message attributes to specify additional recipients for a notification email message, if the primary recipient has a notification preference to receive individual email notifications. The message must also be eligible to be sent by email according to the settings in the Email Notification Preference field in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.
#WFM_CC
- Define this attribute to specify one or more secondary recipients for a notification email message. These recipients are stored in the CC (Carbon Copy) field of the message header.
#WFM_BCC
- Define this attribute to specify one or more additional recipients for a notification email message whose identities are not included in copies of the message sent to the primary and secondary recipients. These recipients are stored in the BCC (Blind Carbon Copy) field of the message header.
The #WFM_CC
and #WFM_BCC
attributes must be of type text and must have a source of Send. Specify the attribute value as a list of the email addresses or role names of the additional recipients, separated by semicolons (;
).
If you specify email addresses, each address must be fully qualified with a valid domain. If any addresses are not fully qualified, the notification mailer treats them as role names.
If you specify role names, ensure that those roles have valid email addresses defined.
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 determines the email address at runtime and sets that item type attribute accordingly.
The notification mailer sends the CC and BCC recipients copies of the email message generated for the primary recipient. However, the CC and BCC recipients are not added to the recipient role for the notification in the Notification System.
CC and BCC recipients receive the notification email message only if the primary recipient has a notification preference of MAILTEXT
, MAILHTML
, MAILHTM2
, or MAILATTH
, and the format of the email is determined by the notification, language, and territory preferences of the primary recipient.
If the primary recipient has one of the listed notification preferences, the notification mailer sends the notification email message to CC and BCC recipients irrespective of their own notification preferences. However, the notification mailer does check whether any CC or BCC recipients that are specified as role names have a notification preference of DISABLED
, which indicates that the email address on record for the role is invalid. To help avoid unnecessary processing, the notification mailer does not send further emails to roles marked with the DISABLED
preference. See: Outbound Notification Mailer Processing, Oracle Workflow Administrator's Guide.
If the primary recipient is a role with multiple members, each of whom receives an individual notification email message, then the CC and BCC recipients receive copies of all the email messages sent to all the primary recipient role members.
The notification does not appear in the worklists of CC and BCC recipients.
CC and BCC recipients do not receive copies of any requests for more information about a notification, nor of any answers providing more information.
Adding CC and BCC recipients is recommended only for FYI notifications. If you do add CC or BCC recipients to a response-required notification, consider whether the additional recipients should be able respond to the notification, and set up your security options accordingly.
If the notification includes the Notification Detail Link attachment and you enable guest access to the Notification Details page, then CC and BCC recipients can use the Notification Detail Link attachment to access the Notification Details page, and view and respond to the notification there. If you do not want CC and BCC recipients to access the Notification Details page, then you should disable guest access, or require your users to set notification preferences that do not include the Notification Detail Link attachment, such as MAILTEXT
or MAILHTM2
, or assign the primary recipient the WF_EXTERNAL_ROLE_NOEBS_ACCESS
role.
If the notification allows responses by email and you select the Allow Forwarded Response mailer configuration parameter, then CC and BCC recipients can respond to the notification by email. If you do not want CC and BCC recipients to respond by email, deselect the Allow Forwarded Response mailer configuration parameter, or choose notification options that require users to respond through the Notification Details page. For example, users must use the Notification Details page to respond to notifications that require electronic signatures and notifications marked as including secure content not sent by email. See: #WF_SIG_POLICY_ATTRIBUTE and #WF_SECURITY_POLICY Attribute.
If the notification requires an electronic signature, then only a primary recipient who provides a valid signature in the Notification Details page can respond. In this case CC and BCC recipients cannot respond to the notification.
See: Email Notification Security, Oracle Workflow Administrator's Guide.
If you configure messages for use with approvals data services, you can use special message attributes to control how the approval notifications appear in the Oracle Mobile Approvals for Oracle E-Business Suite app. These message attributes let you specify how to handle content for a message that is used as a boilerplate template to send approval notifications from multiple notification activities for different approval objects.
#APPROVALS_GROUP
- If a message is used by multiple notification activities, define this attribute for the message to specify the approvals group value that identifies the approval type to which the various notifications sent from this message belong. For each notification activity that uses this message, include logic in your workflow process to set the value of the #APPROVALS_GROUP
attribute to a value representing the appropriate approval type. See: Approval Types.
#APPROVALS_OBJECT
- If a message is used by multiple notification activities for different approval objects, define this attribute for the message to specify the approval object to which the various notifications sent from this message pertain. For each notification activity that uses this message, include logic in your workflow process to set the message attribute value to a value that represents the approval object for the notification. You can then use this message attribute in rules that control which detail regions are displayed in the approval notification body details. See: To prepare a region for conditional display.
For more information, see: Identifying Approval Notification Content.
Following are examples of how the Notification System generates the Response section of an email 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 email 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 email 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 have Oracle Application Framework set up in Oracle JDeveloper for custom development, you can embed Oracle Application 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 E-Business Suite. 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 checkbox for a message attribute that references a region. An Oracle Application 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 Application Framework regions. See: WF_NOTIFICATION() Message Function.
Note: If you embed an Oracle Application 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 Application 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 Application Framework region for inclusion in a notification message:
Oracle Workflow notifications support embedded Oracle Application Framework regions only. You cannot include an entire Oracle Application Framework page.
The region style must be Stack Layout. This region style lets users personalize the region with Oracle Application Framework Personalization.
Ensure that the event handling in the controllers for the embedded Oracle Application 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 (AM) and assign it a region title.
You should retain the calling AM in the code of the application that owns the region. For example, if you create a custom attachments region to be displayed in a notification in the Notification Details page, the root AM as well as the subsequent nested AMs should be retained in the owning application's controllers and should not be refreshed. This is required to avoid issues when the owning application returns control to Oracle Workflow.
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.
The embedded region must not perform a form submit. The embedded region also must not include any Oracle Application Framework components that perform an implicit form submit, such as subtabs or hideShow beans.
If you do not want to send an embedded region in email, you can exclude the message body from notification email 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.
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 email clients cannot interpret the rowset functionality, email 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 Application Framework region as a self-service function (non-form function) in the Form Functions window in Oracle E-Business Suite. 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 E-Business Suite 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 Application Framework region, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.
When you configure a notification mailer, you can set certain parameters to control how the notification mailer includes Oracle Application Framework content in email notifications. For example, you can specify the user, responsibility, and application through which a notification mailer accesses Oracle Application Framework content. You can also specify whether to attach any stylesheet and images referenced in Oracle Application Framework regions to email notifications, or simply display the stylesheet and image references as URLs. See: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide.
You can use the Workflow Mailer URL Access Tester page to test whether Oracle Application Framework content can be generated correctly for email notifications. See: Testing Mailer URL Access, Oracle Workflow Administrator's Guide.
Related Topics
To View the Details of a Notification, Oracle Workflow User's Guide
Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide
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.
Important: 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. The maximum length for the complete token-substituted subject is 240 bytes. See: Send and Respond Message Attributes and To Define a Message Attribute.
Tip: 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 Application 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 email reader that displays plain text messages.
Important: If the message will not contain any embedded Oracle Application 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 email reader. However, if the message does contain one or more embedded Oracle Application 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 Application 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 Application Framework region, then the HTML body is required. Otherwise, the HTML Body field is optional. See: Embedding Oracle Application Framework Regions in Messages.
Important: 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.
Important: 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 email 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.
Important: 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 the prefix in the attribute value controls whether Oracle Workflow displays the image inline in the Notification Details page and HTML-formatted email notifications or displays the image URL as a link. 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.
Important: 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 email 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. Oracle Workflow includes this description to provide supplemental instructions to the notification recipient as follows:
The description appears as text along with the response prompt in the response section of an email notification. See: Example 'Respond' Message Attributes.
The description appears as a tooltip when a user positions the cursor over the response field or pull-down menu corresponding to this attribute in the Notification Details Web page. See: To View the Details of a Notification, Oracle Workflow User's Guide.
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.
Important: 'Respond' message attributes of type URL do not appear properly when you view the notification from a plain text email 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.
Important: 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 the prefix in the attribute value controls whether Oracle Workflow displays the image inline in the Notification Details page and HTML-formatted email notifications or displays the image URL as a link. See: To Define a URL Attribute.
Form - 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 E-Business Suite Developer's Guide and To Define a Form Attribute.
Important: 'Send' and 'Respond' message attributes of type Form appear only when your Worklist Web pages are launched from Oracle E-Business Suite. 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.
Important: 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.
Document attributes can only have a source of Send. You cannot use a document attribute as a respond 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 email 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.
Important: 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.
Important: 'Respond' message attributes of type Date, Number, Text, or Role prompt the notification recipient to respond with a date, number, text value, or role (internal or display name), respectively.
For 'Respond' message attributes of type Role, if an administrator has defined grants to restrict the Oracle Workflow user list of values, then when a notification recipient enters response values for the role attribute in the Notification Details page, Respond to Notifications as Group page, or Vacation Rule: Response page, only the values to which the notification recipient has access appear in the list of values. See: Configuring the Oracle Workflow User List of Values, Oracle Workflow Administrator's Guide.
'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.
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: You should only choose New Window or Full Window as the frame target for URL attributes. The Notification Details page no longer uses frames to display notifications, so choosing Same Frame or Parent Frameset is equivalent to choosing Full Window.
Note: If the URL attribute points to an image file with an extension of gif
, jpg
, png
, tif
, bmp
, or jpeg
, the attribute value has a prefix of IMG:
or no prefix, 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 email 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 email, the presentation of the attachment will vary depending on what your email 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 Application Framework region can only be embedded in the notification message. A region cannot be attached to a notification. See: Embedding Oracle Application 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 email message that does not include an embedded Oracle Application Framework region, Oracle Workflow appends an attachment called Notification References to the email. 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 email message that includes an embedded Oracle Application Framework region, Oracle Workflow includes a Related Applications region in the email 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.
Important: 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.
Important: 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. A role can correspond to a single user or contain multiple users as members. 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.
Important: 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.
CANCEL
- When the notification activity is reset to be reexecuted as part of a loop.
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.
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.
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, either the event subscription to the po.credit.authorization
event must use the WF_RULE.Instance_Default_Rule rule function, or 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.
When you create a top-level runnable process activity, you can use a special process activity attribute with the internal name #ONDEMANDATTR
to enhance performance for the process. By default, 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 during execution of the work item. However, depending on the process logic, an item type may contain many item attributes that are not used during execution of a particular work item. You can define the #ONDEMANDATTR
activity attribute for a process activity to specify that Oracle Workflow should create runtime copies of item attributes only when the process sets values for those item attributes. Otherwise, the Workflow Engine simply references the default values specified for the item attributes in the design-time workflow definition.
The Workflow Engine simply checks for the presence of the #ONDEMANDATTR
attribute to determine how to proceed. To create runtime copies of item attributes only on demand, define the #ONDEMANDATTR
attribute for the appropriate process activity. The attribute can be of any type and does not need to contain any particular value. To create runtime copies of all item attributes when the process is created, do not define this attribute for the process activity.
If you define a default value for the #ONDEMANDATTR
activity attribute, you must define the default value as a constant value. Do not define the #ONDEMANDATTR
attribute to take its default value from an item attribute.
See: Item Type Attributes andItem Attributes, Oracle Workflow Administrator's Guide.
Note: If you specify that a process should use on-demand item attributes, you should plan carefully when modifying the workflow definition to ensure that the changes do not adversely affect active work items. See: Workflow Objects That Do Not Support Versioning.
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.
Important: 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.
Important: 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 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.
Important: 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.
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: The External Java
function type is not currently used.
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 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.
Important: 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 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: Defining Events.
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.
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.
Important: 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 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.
For a runnable process activity, you can define a special process activity attribute named #ONDEMANDATTR
to enhance performance by having the Workflow Engine create runtime copies of item attributes only on demand. See: #ONDEMANDATTR Attribute and To Define an Item Type or Activity Attribute.
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 checkbox
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.
Important: 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.
Single 'No' Vote
The following table shows the custom response activity attribute value assigned to each response for a single 'No' vote 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-2006 | 31-DEC-2006 | Vote Message | Yes/No |
Vote | 2 | 01-JAN-2007 | <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, 2006 and December 31, 2006 will send the message Vote Message with result options of Yes or No, whether the work items are completed before January 1, 2007 or not. Only work items that are initiated on or after January 1, 2007 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.
By default, 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 workflow process. For such work items, keep in mind the following considerations:
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.
If the top-level runnable process for a work item has the special #ONDEMANDATTR
activity attribute defined, then Oracle Workflow creates runtime copies of item attributes only when the process sets values for those item attributes. Otherwise, the Workflow Engine simply references the default values specified for the item attributes in the design-time workflow definition. For such work items, keep in mind the following considerations:
Work items that use on-demand item attributes do have access to new item attributes added after the work items have been initiated. You do not need to create the attribute specifically for them through the AddItemAttr or AddItemAttributeArray APIs.
However, if you delete an item attribute from the workflow definition in the database after the work item has been initiated, and the work item did not already make a runtime copy of the item attribute on demand, then that work item can no longer access the item attribute. You should plan carefully when deleting any item attributes to ensure that you do not remove attributes that active work items may still require.
See: #ONDEMANDATTR Attribute.
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.
Note: This restriction only applies for work items that do not use on-demand item attributes.
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>;
See: Item Attributes.