Defining Workflow Process Components

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:

Workflow Process Components

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.

Item Types

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.

Item Type Attributes

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.

Attribute Types

There are ten attribute types, as shown below. The type determines what values are acceptable and how the attribute is used.

Persistence Type

When you define an item type, you must also specify its persistence type. The persistence type controls how long a status audit trail is maintained for each instance of the item type. If you set Persistence to Permanent, the runtime status information is maintained indefinitely until you specifically purge the information by calling the procedure WF_PURGE.TotalPerm().

If you set an item type's Persistence to Temporary, you must also specify the number of days of persistence ('n'). The status audit trail for each instance of a Temporary item type is maintained for at least 'n' days of persistence after its completion date. After the 'n' days of persistence, you can then use any of the WF_PURGE APIs to purge the item type's runtime status information. See: WF_PURGE, Oracle Workflow API Reference.

If you set an item type's Persistence to Synchronous, Oracle Workflow expects instances of that item type to be run as forced synchronous processes with an item key of #SYNCH. Forced synchronous processes complete in a single SQL session from start to finish and never insert into or update any database tables. Since no runtime status information is maintained, you do not normally need to perform any purging for a process with the Synchronous persistence type. However, if you run the process with a unique item key in asynchronous mode for testing or debugging purposes, Oracle Workflow does maintain runtime status information for that process instance. You can purge this information by changing the item type's Persistence to Temporary and running any of the WF_PURGE APIs. Then change the item type's Persistence back to Synchronous. See: Synchronous, Asynchronous, and Forced Synchronous Processes, Oracle Workflow API Reference, WF_PURGE, Oracle Workflow API Reference, and Purging for Performance, Oracle Workflow Administrator's Guide.

Note: You can also use the Purge Obsolete Workflow Runtime Data concurrent program to purge obsolete item type runtime status information. The executable name for this concurrent program is "Oracle Workflow Purge Obsolete Data" and its short name is FNDWFPR. See: Purge Obsolete Workflow Runtime Data, Oracle Workflow API Reference.

Item Type Selector Function

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.

External Document Integration

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.

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.

Attributes

You can create an attribute for any of the following workflow process components:

Defining Item Types and Attributes

To Create an Item Type

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

    the picture is described in the document text

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

  3. Enter a translatable Display Name that is longer and more descriptive. You can also supply a description for the item type.

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

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

  6. Choose Apply to save your changes.

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

  8. Select the Access tab page to set the access and customization levels for this item type. See: Allowing Access to an Object.

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

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

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

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

    the picture is described in the document text

    To create an activity attribute, select an activity in the navigator tree and choose New Attribute from the Edit menu.

    Activity Attribute Property Page

    the picture is described in the document text

    An Attribute property page appears in both cases.

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

  3. Enter a Display Name. This is the name that appears in the navigator tree.

  4. Enter an optional description.

  5. Select the data type of the attribute. Form, URL, and document data types are not relevant if you are defining an activity attribute.

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

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

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

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

  10. Choose Apply to save your changes.

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

  1. 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 e-mail 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.

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

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

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

  5. 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 e-mail.

    • 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 e-mail 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 e-mail notification displays all URL attributes as the display name of the attribute, followed by a colon and the URL.

  6. 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 e-mail 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 e-mail 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.

  7. Choose OK when you are done.

To Define a Form Attribute

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

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

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

  4. 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 e-mail 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"
    
  5. Choose OK when you are done.

To Define a Document Attribute

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

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

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

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

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

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

  7. Choose OK when you are done.

To Copy an Item Type

  1. Select the item type to copy in the navigator tree.

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

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

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

  1. Select the attribute to copy in the navigator tree.

  2. Drag the attribute, holding down your select mouse button, to the component branch you want to copy it to.

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

To Define a Message Attribute

Allowing Access to an Object

Access Property Page

the picture is described in the document text

In the Access tab page, the 'Range of Editable Access Levels' indicator bar provides a relative indication of the range of access levels that can edit the object. The shaded area represents the access levels that can edit the object, while the vertical bar represents your current access level. See: Overview of Oracle Workflow Access Protection, Oracle Workflow Administrator's Guide.

The indicator bar can be shaded solid green, or shaded with any combination of solid green and crosshatch grey. If the "Allow modifications of customized objects" check box in the "About Oracle Workflow Builder" dialog box of the Help menu is:

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

  1. Select the Access tab of the property page.

  2. In the Options region, use the 'Preserve Customizations' and 'Lock at this Access Level' check boxes to define the access levels that can modify this object. The options that you check in this region directly affect the values that appear in the Levels region.

    The following table illustrates how the customization and protection levels of an object are affected when you check different combinations of these options. This table assumes that the user setting the options has an access level of 100.

    Results of Access Option Combinations
    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.
  3. 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.

Lookup Types

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.

Defining Lookup Types

To Create Lookup Types

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

    the picture is described in the document text

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

  3. Select the Access tab page to set the access levels allowed to modify this lookup type. See: Allowing Access to an Object.

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

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

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

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

    the picture is described in the document text

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

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

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

  5. Repeat steps 1, 2, and 3 if you wish to create additional lookup codes for a specific lookup type.

To Copy a Lookup Type

  1. Select the lookup type to copy in the navigator tree.

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

  1. Select the lookup code to copy in the navigator tree.

  2. Hold down your mouse select button as you drag the lookup code to the lookup type you want to copy it to.

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

Messages

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.

Message Result

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.

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.

Action History

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.

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.

The standard action history table provided by Oracle Workflow includes the following columns:

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.

WF_NOTIFICATION() Message Function

In addition to message attribute tokens, you can also use a special message function called WF_NOTIFICATION() to add context-sensitive content to a message body. Depending on the parameters you provide, the WF_NOTIFICATION() function can produce either a table of message attributes or an action history table for the notification.

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.

Message Attribute Table

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.

Action History Table

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.

#WF_REASSIGN_LOV 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.

#HIDE_REASSIGN Attribute

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.

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.

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.

#HIDE_MOREINFO Attribute

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 e-mail notifications. However, note that if the #HIDE_MOREINFO attribute is not defined for a particular notification, the default behavior is different for the Notification Details page and for HTML-formatted e-mail notifications. The Notification Details page displays the Request Information button if the #HIDE_MOREINFO attribute is not defined, while an HTML-formatted e-mail notification will exclude the Request Information response link by default if the #HIDE_MOREINFO attribute is not defined. To control this option in all interfaces where users access notifications, you should explicitly define and set the #HIDE_MOREINFO attribute. See: To Respond to an HTML E-mail Notification, Oracle Workflow User's Guide.

The #HIDE_MOREINFO attribute must be either of type text or lookup. To hide the Request Information button, set the value of this attribute to Y. To display the Request Information button, set the value to N.

Note: It is recommended to define the #HIDE_MOREINFO attribute with a type of lookup and assign it the predefined Yes/No lookup type that is provided in the Standard item type. The Yes/No lookup type contains two lookup codes with the display names Yes and No, representing the values Y and N, respectively.

#MORE_INFO_PARTICIPANTS Attribute

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 e-mail 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:

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 E-mail Notification, Oracle Workflow User's Guide and To Request More Information From Another User, Oracle Workflow User's Guide.

#FROM_ROLE Attribute

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 e-mail 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.

#WF_SIG_POLICY Attribute

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.

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.

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.

#WF_SIG_ID Attribute

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.

#WF_SECURITY_POLICY 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 e-mail. If you specify that a notification's content must not be sent in e-mail, users receive an e-mail message that only informs them that they must access the notification through the Notification Details Web page instead to view its content and respond. 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 e-mail, set the value of the #WF_SECURITY_POLICY attribute to NO_EMAIL. If you set the value to EMAIL_OK or DEFAULT, leave the value blank, or if you do not define a #WF_SECURITY_POLICY attribute for the message, Oracle Workflow sends the full notification content in e-mail to users whose notification preference is set to receive e-mail.

You can either specify a constant value for the #WF_SECURITY_POLICY attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically determines at runtime whether the notification content can be sent in e-mail or not and sets that item type attribute accordingly.

Note: You can also choose to disable individual e-mails entirely for specific messages. In this case, no e-mail notifications are sent for those messages, even if a user has a notification preference that includes individual e-mails. If you disable individual e-mails 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 e-mail. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.

Header Attributes

You can use special header message attributes to display key information in the notification header region of the Notification Details page. Header attributes are also displayed at the beginning of e-mail notifications. To identify a message attribute as a header attribute, you must define an internal name for it that begins with #HDR_ using the following format:

#HDR_<name>

The display order of any header attributes in the Notification Details page or the e-mail notification is determined by the sequence of those attributes within the navigation tree in the Workflow Builder. The display name of each header attribute will appear as a label before the attribute value in the notification header region. You can either specify a constant value for each attribute, or specify an item type attribute as the value and include logic in your workflow process that dynamically sets the item type attribute value at runtime.

#HDR_REGION Attribute

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 check box for the #HDR_REGION attribute.

#RELATED_APPL 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 check box for the #RELATED_APPL attribute.

#ATTACHMENTS 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 e-mail. 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 e-mail 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:

Note: The Attach Content check box is not applicable for the #ATTACHMENTS attribute. If you define this attribute, the specified attachments are included in the e-mail notification, regardless of the setting of the Attach Content check box.

See: Using Attachments, Oracle E-Business Suite User's Guide.

#HISTORY Attribute

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 check box for the #HISTORY attribute.

#SUBMIT_COMMENTS 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.

#RELATED_HISTORY 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>

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.

Region Personalization Attributes

You can use special message attributes to apply personalizations at different levels to Oracle Application Framework regions embedded in notifications.

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.

Notification Mailer Attributes

You can use special message attributes to control how a notification mailer generates the e-mail message for a notification, if the recipient has a notification preference to receive e-mail notifications and the message is eligible to be sent by e-mail 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.

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.

Notification Mailer Message Template Attributes

You can use special message attributes to specify which message templates a notification mailer uses to generate the e-mail message for a notification, if the recipient has a notification preference to receive e-mail notifications and the message is eligible to be sent by e-mail 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 e-mail notification processing.

See: Notification Mailer Configuration Wizard, Oracle Workflow Administrator's Guide.

Additional E-mail Recipient Attributes

You can use special message attributes to specify additional recipients for a notification e-mail message, if the primary recipient has a notification preference to receive individual e-mail notifications. The message must also be eligible to be sent by e-mail 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.

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 e-mail addresses or role names of the additional recipients, separated by semicolons (;).

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 e-mail address at runtime and sets that item type attribute accordingly.

The notification mailer sends the CC and BCC recipients copies of the e-mail 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.

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.

See: E-mail Notification Security, Oracle Workflow Administrator's Guide.

Approvals Data Services Attributes

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.

For more information, see: Identifying Approval Notification Content.

Example 'Respond' Message Attributes

Following are examples of how the Notification System generates the Response section of an e-mail notification using a sample set of 'Respond' message attributes that have no default values.

The following table lists some sample 'Respond' message attributes.

Sample Respond Attributes
Internal Name Type Format/Lookup Type Display Name Description
RESULT lookup WFSTD_APPROVAL Action Do you approve?
COMMENT text 2000 Review Comments  
REQDATE date DD-MON-YYYY Required Date If there is no required date, leave this blank.
MAXAMT number   Maximum Amount This is the maximum approved amount.

For the templated response method, the following boilerplate text is used to generate the Response template section of an e-mail notification:

<Description> 
<Display Name>: " "
          <list of lookup codes>
Portion of Resulting Response Template as Shown in a Templated Response E-mail Notification
Do you approve?
Action: " "
Approve
Reject
 
Review Comments: " "
 
If there is no required date, leave this blank.
Required Date: " "
 
This is the maximum approved amount.
Maximum Amount: " "

For the direct response method, the following boilerplate text is used to generate the Response section of an e-mail notification:

Enter the <Display Name> on line <Sequence>. <Description> <Type_Hint> 

<Display Name> is replaced with the Display Name of the message attribute. <Sequence> is replaced with the relative sequence number of the 'Respond' message attribute as it appears in the Navigator tree among all 'Respond' message attributes (that is, the presence of 'Send' message attributes is ignored when determining the sequence). <Description> is replaced with the Description of the message attribute. In addition, <Type_Hint> is replaced with a hint statement if the message attribute matches a data type that has a hint. The following table shows the data types with hints and the corresponding hint statements.

Data Type Hints
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.
Portion of Resulting Response Section as Shown in a Direct Response E-mail Notification
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.

Embedding Oracle Application Framework Regions in Messages

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:

Note: The Frame Target field is not applicable for message attributes of type document. Additionally, you must not select the Attach Content check box for a message attribute that references a region. An Oracle 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:

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 e-mail 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 e-mail 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 e-mail notifications. See: Testing Mailer URL Access, Oracle Workflow Administrator's Guide.

Related Topics

To Create a Message

To Define a Message Attribute

To View the Details of a Notification, Oracle Workflow User's Guide

Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide

Defining Messages

To Create a Message

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

    the picture is described in the document text

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

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

  4. Choose Apply to save your changes.

  5. Select the Body tab to display the Body property page of the message.

    Body Property Page

    the picture is described in the document text

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

  7. 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 e-mail 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 e-mail 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.

  8. 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 e-mail reader that displays HTML-formatted messages or HTML-formatted message attachments.

    Note: If HTML Body is null, Oracle Workflow uses the message body entered in Text Body to generate the notification message. It inserts the plain text between the <pre>...</pre> HTML tags.

  9. 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 e-mail 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.

  10. Choose Apply to save your changes.

  11. Select the Roles tab page to specify the roles that have access to this message. (This functionality will be supported in a future release.)

  12. Select the Access tab page to set the access levels allowed to modify this message. See: Allowing Access to an Object.

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

    the picture is described in the document text

    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.

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

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

  16. You must now define all the message attributes that you have included in the subject and body of this message.

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

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

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

    the picture is described in the document text

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

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

  4. Enter a Display Name. This is the name that appears in the navigator tree. If this is a 'Respond' message attribute, then this display name is also used as the response prompt. See: Example 'Respond' Message Attributes.

    For 'Send' message attributes, the Display Name of the attribute appears in plain text e-mail notifications only if the attribute is of type URL, to describe what the URL drills down to.

  5. 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 e-mail 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.

  6. Select the data type of the attribute.

  7. Depending on the Type of your attribute, provide the following default information:

    • Text - Specify the maximum length of the text attribute.

    • 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 e-mail reader. You should advise your workflow users to view their notifications from the Notification Details Web page if you plan to create messages with 'Respond' message attributes of type URL.

      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 e-mail 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 e-mail address for that role. To set a default value for the attribute, you must initially load roles from the database. See: Roles.

    • Event - Specify an event item type attribute as the default value.

    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.

  8. 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 e-mail notifications, rather than as a link. In this case the frame target value is not applicable.

  9. If your message attribute is a Send attribute, is of type Document, and contains a PL/SQL, PL/SQL CLOB, or PL/SQL BLOB document, you can check Attach Content to attach the content of the attribute to the notification message. When you view your notification from the Notification Details Web page, you see a document icon following the notification message body that displays the contents of the attached message attribute when you click on it. If you view your notification from e-mail, the presentation of the attachment will vary depending on what your e-mail notification preference setting is. See: Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide.

    Note: You can attach, as well as embed (by token substitution) PL/SQL document attributes in the notification message and are not limited to one or the other. However, a document attribute that references an Oracle 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.

  10. If your message attribute is a Send attribute and is of type URL, you can check Attach Content to attach the URL to the message.

    • In the Notification Details Web page, an attached URL appears with an attachment icon after the notification message body.

    • For a notification e-mail message that does not include an embedded Oracle Application Framework region, Oracle Workflow appends an attachment called Notification References to the e-mail. This attachment includes a link to each URL attribute for the message that has Attach Content checked. You can navigate to a URL by choosing its link.

    • For a notification e-mail message that includes an embedded Oracle Application Framework region, Oracle Workflow includes a Related Applications region in the e-mail after the message body. The Related Applications region displays a link to each attached URL attribute.

    Note: You can attach, as well as embed (by token substitution) URL attributes in the notification message and are not limited to one or the other.

    Note: If you check Attach Content for a URL attribute that points to an image file, the URL attribute appears as a link in the Notification References attachment or Related Applications region, just as other URLs do.

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

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

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

  1. Select the message to copy in the navigator tree.

  2. Hold down your mouse select button as you drag the message to the item type branch you want to copy to.

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

  4. Enter a new internal name and display name.

  5. Make any additional modifications to the properties of the message.

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

To Copy an Attribute

Reviewing Notifications via Electronic Mail, Oracle Workflow User's Guide

Activities

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.

Notification Activity

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:

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

Event Activity

An event activity represents a business event from the Business Event System within a workflow process. Include event activities in workflow processes to model complex processing or routing logic for business events beyond the standard event subscription actions. See: Managing Business Events.

An event activity can either receive, raise, or send a business event.

Receive Event Activity

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:

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.

Raise Event Activity

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.

Send Event Activity

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.

Process Activity

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.

#ONDEMANDATTR Attribute

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.

Activity Cost

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.

Defining Activities

To Create a Notification Activity

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

    the picture is described in the document text

    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.

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

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

  4. Select the name of the message you want this notification to send. See: To Create a Message.

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

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

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

  8. Choose Apply to save your changes.

  9. Select the Details tab to display and modify optional Details of the activity. See: To Define Optional Activity Details.

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

  11. Select the Access tab page to set the access levels allowed to modify this notification. See: Allowing Access to an Object.

  12. Choose OK to save your changes and close the property pages.

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

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

    the picture is described in the document text

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

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

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

  5. Specify the cost of this function activity. See: Activity Cost.

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

  7. Choose Apply to save your changes.

  8. Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.

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

  10. Select the Access tab page to set the access levels allowed to modify this function. See: Allowing Access to an Object.

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

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

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

    the picture is described in the document text

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

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

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

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

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

  7. Choose Apply to save your changes.

  8. Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.

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

  10. Select the Access tab page to set the access levels allowed to modify this event. See: Allowing Access to an Object.

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

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

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

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

    the picture is described in the document text

    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.

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

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

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

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

  6. Choose Apply to save your changes.

  7. Select the Details tab to display and modify the optional details of the activity. See: To Define Optional Activity Details.

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

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

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

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

  1. Select the Details tab in the activity's property pages.

    Details Property Page

    the picture is described in the document text

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

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

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

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

  6. Choose Apply to save your changes.

To Copy an Activity

  1. Select the activity to copy in the navigator tree.

  2. Hold down your mouse select button as you drag the activity to the item type branch you want to copy it to.

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

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

Voting Activity

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:

Creating a Voting Activity

  1. Create a voting lookup type that contains the responses you want to tally in your voting activity. See: To Create Lookup Types.

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

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

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

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

  6. Choose an icon that identifies your voting activity.

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

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

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

  10. Choose Apply to save your changes.

  11. Select the Details tab to display and modify the Details property page of the activity. See: To Define Optional Activity Details.

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

  13. Select the Access tab page to set the access levels allowed to modify this notification. See: Allowing Access to an Object.

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

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

Example Voting Methods

Vote Yes/No Activity

Example Voting Methods

  1. Simple Majority

    The following table shows the custom response activity attribute value assigned to each response for a simple majority voting method.

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

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

    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.

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

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

  4. Popularity

    The following table shows the custom response activity attribute value assigned to each response for a popularity voting method.

    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.

  5. Single 'No' Vote

    The following table shows the custom response activity attribute value assigned to each response for a single 'No' vote voting method.

    Single 'No' Vote Voting Method
    Response Custom Response Activity Attribute Value
    YES 100
    NO 0

    Any vote for response NO makes NO the result.

  6. Jury

    The following table shows the custom response activity attribute value assigned to each response for a jury voting method.

    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

Voting Activity

Vote Yes/No Activity

Deleting Objects in Oracle Workflow Builder

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.

Modifying Objects in Oracle Workflow Builder

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.

Sample Activity Versions
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.

Workflow Objects That Support Versioning

The following Workflow objects support versioning:

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:

The modifications in all of these examples will affect only work items that are initiated after the changes are made.

Workflow Objects That Do Not Support Versioning

The following Workflow objects do not support versioning:

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.

Item Attributes

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:

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:

See: #ONDEMANDATTR Attribute.

Messages

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:

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 and Codes

Lookup types have the following important uses in Oracle Workflow:

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:

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:

PL/SQL Code

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:

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.

See: Item Attributes.