Identifying Approval Notification Content

To display custom approval notifications in the Approvals app, you must first review your workflow definitions to identify the approval notifications that you want to include and the content that will appear for those notifications in the app. For notifications that include an embedded Oracle Application Framework region, you must also review the BC4J object implementation that retrieves notification content, using Oracle JDeveloper with Oracle Application Extension. For notifications that include PL/SQL document content, you must also review the PL/SQL procedures that retrieve notification content.

In some cases you might need to make changes in your workflow definitions, Oracle Application Framework view objects, or PL/SQL procedures to prepare the approval notification content to appear in the app. If so, you should take into consideration how such changes will affect the appearance of your approval notifications in the Worklist pages and in e-mail as well.

The content that appears in the Approvals app, in the order in which users see the content in the approval flow, is as follows:

arrow icon   Approval Types:

An approval type is a logical grouping of approval notifications that belong to a business flow in an Oracle E-Business Suite application. For example, seeded approval types include Expenses, Purchase Orders, Requisitions, and so on.

The name you assign to an approval type appears in the Approvals app on the Pending Approvals by Type screen, which approvers can access from the app's springboard. This screen lets approvers quickly filter the approval notifications they want to view. For example, an approver can select the Expenses type to view all approval notifications for expenses, or the Requisitions type to view all approval notifications for purchase requisitions.

Note: Approval types in the Approvals app are not the same as workflow item types. Unlike the Worklist pages, which show the workflow item type to which a notification belongs, the Approvals app uses approval types to provide a higher-level grouping of approval notifications for business transactions.

An approval type can include notifications for multiple related approval objects. For example, purchase requisitions and contract requisitions are two different approval objects whose approval notifications are included in the Requisitions approval type. Similarly, vacancies and offers are two different approval objects whose approval notifications are included in the Human Resources approval type.

Additionally, an approval object can have multiple approval notifications associated with it. For example, notifications can be sent to request approval for creating a vacancy and for updating a vacancy. Notifications from different workflow item types and message definitions can be included in one approval type to group together all the relevant approval notifications for related approval objects.

Follow these steps to determine what custom approval types you want to define. You can then use the approvals data services configuration tool to define the approval types you have planned.

  1. Identify all the approval objects in your business flows. For example, an approval object could be a contract requisition, a purchase requisition, creating a vacancy, updating a vacancy, and so on.

  2. Identify all the workflow notifications that request approvals associated with these objects. Check for notifications that may belong to different workflow item types but are associated with the same approval objects. Make a note of the workflow item type and message name that uniquely identify each message used to send these notifications.

  3. Decide which related approval objects and associated notifications you want to group together into an approval type.

  4. Select a name for the new approval type. Ensure that the name represents all the approval objects grouped within that type. To let approvers review and filter their approval notifications more easily, use a name related to the business flow. For example, an approval type can be named after a business object, such as Expenses or Purchase Orders, or after a functional area, such as Human Resources.

  5. Select an icon to identify the approval type visually within the Approvals app. The icon should be in PNG format. It should be monochromatic white and should consist of an image with a size of 48 x 48 pixels, surrounded by padding so that the full icon size is 64 x 64 pixels. Copy the icon file to the $OA_MEDIA directory on your Oracle E-Business Suite application server.

    After copying the file, verify that you can view the icon image by accessing the following URL:

    http://<ebshost>:<port>/OA_MEDIA/icon_filename.png

    The Approvals app uses this URL to load the image from the server.

    Note: The mapping of $OA_MEDIA is completed as part of the Oracle E-Business Suite installation and setup steps. For more information, see the installation documentation for your release.

  6. In some cases, a message definition is used by multiple notification activities in a workflow process. If all the notifications that use a particular message will be exposed in the Approvals app and belong to the same approval type, then you do not need to perform any further configuration. However, if you want to expose only some approval notifications sent by a workflow message in the Approvals app, or if the approval notifications sent by a workflow message should belong to different approval types, then you must perform additional steps to distinguish these notifications from each other.

arrow icon   Pending Approvals Information:

The Approvals app provides the following screens to list approval notifications:

These screens are analogous to the Worklist page in Oracle E-Business Suite. They display information about the approval notification information including the user from whom the notification was sent, the sent date, and the notification subject line. The approvals data services retrieve this information from the WF_NOTIFICATIONS table in the same way that it is retrieved for display in the Worklist.

The approval notification information is included automatically; you do not need to perform any steps for this information in the approvals data services configuration tool. However, you should follow these steps to prepare this information to be displayed in the Pending Approvals, Pending Approvals by Type, and Past Approvals screens.

  1. Ensure that the subject line defined for each notification in the workflow definition clearly summarizes the key information that an approver needs in order to understand the notification. The recommended format is as follows:

    <Object Type> <Object ID> for <Requester> (<Main Value>)

    For example:

    Requisition 12345 for Walker, John (564.26 USD)
Expense 56789 for Smith, Karen (345.65 USD)

  2. Ensure that the #FROM_ROLE message attribute is defined for each notification to identify the user from whom the notification is sent. See: #FROM_ROLE Attribute.

Note that if you update the message definitions for notifications that you intend to display in the Approvals app, those changes will appear in the Worklist pages as well.

arrow icon   Approval Notification Details:

The approval details screens display the content of an approval notification for the approver to review and make a decision. Approval details include the following:

These screens are analogous to the Notification Details page in Oracle E-Business Suite. However, the Notification Details page displays all the notification content in a single page. By contrast, due to the limited display area on a smartphone, the Approvals app displays the notification content in multiple screens, progressing from higher-level information to lower-level details. The first-level details screen, which appears when the approver selects a notification from the Pending Approvals list or one of the other lists, shows the header attributes for the notification. From that screen, the approver can drill down to the second-level details screen to view the body content of a specific region associated with the approval object. For example, expense report headers are shown in the first-level details screen for Expenses approvals, while expense report lines are shown in the second-level details screen.

You can optionally define a third-level details screen to show even more granular details. For example, for a requisition approval notification, the approver can drill down from the header information in the first-level details screen to the requisition lines in the second-level details screen. From that screen, the approver can drill down to the third-level details screen to view distributions corresponding to a given line.

The first-level details screen also lets the approver drill down to additional screens to view the action history for a notification and any attachments.

All the approval details screens include the response section, from which the approver can choose either the Approve or the Reject response action for the notification. This section also includes a Request Information option for the approver to request more information before making a decision. However, the approval notification is not completed until the approver chooses either the Approve or the Reject response action.

arrow icon   Header:

The first-level details screen for an approval notification displays the names and values of the header attributes, which are high-level attributes related to the approval object. Their values can be retrieved either from message attributes in the workflow definition or from the application tables that correspond to the approval object. For example, the header attributes for Expenses approval notifications include Person, Cost Center, Report Total, and Purpose. The header attributes for Purchase Orders approval notifications include Supplier, Site, Freight Terms, Amount, and Tax.

Follow these steps to prepare approval notification header information for display. You can then use the approvals data services configuration tool to configure the header information you have identified.

  1. Identify all the attributes related to the approval object that you want to display as headers in the first-level details screen. Make a note of the workflow message attribute or application table and column in which each attribute's value is stored.

    If you have defined special header attributes for a message whose internal names begin with #HDR_, then those attributes are automatically included as headers in the first-level details screen. See: Header Attributes. Additionally, if you have defined the special message function WF_NOTIFICATION(ATTRS,...) to include a table of message attributes in the message, then those attributes are automatically included as headers in the first-level details screen as well. See: WF_NOTIFICATION() Message Function. You can also use the approvals data services configuration tool to configure other message attributes and details stored in application tables as headers to appear in this screen.

    You can use Oracle Workflow Builder to review the attributes defined for a message in the workflow definition. You can also use the following SQL command to retrieve a list of attributes for a message:

    select name, type, subtype, value_type, text_default
from wf_message_attributes 
where message_type = '<item_type_name>' 
and message_name = '<message_name>';

    Note: If the approval object has a finite number of related attributes for the approver to review, it is recommended that you define them all as header attributes. In this way the approver can view all the relevant information in the first-level details screen without needing to drill down further.

    For example, an approval notification for a requisition can contain a variable number of requisition lines. In such a case, it is recommended to use a separate drill-down region to show the lines. By contrast, an approval notification for absences only has a given number of attributes to display, which does not vary at runtime. Consequently, for such a notification it is better to show all the attributes in the headers screen without requiring the approver to drill down.

    Additionally, if the message body for an approval notification is generated simply through text substitution of message attribute tokens, without any PL/SQL document content or embedded Oracle Application Framework regions, then you can define all the relevant message attributes as header attributes. In this case you do not need to define second-level or third-level details screens.

  2. Review the display name for each header attribute. It is recommended to keep these names short for better display on a smartphone screen. For example, use the name "Report Total" rather than "Expense Report Total". Update the display name for workflow message attributes in the workflow definition if necessary. For attributes drawn from application tables, choose an appropriate display name that you will enter later when you define the attributes in the configuration tool.

  3. Determine the order in which the header attributes should appear.

  4. If a header attribute requires a unit of measure, it is recommended that you concatenate the value and the unit of measure into one attribute. For example:

    Amount   1,400 USD
Quantity 1 EA

  5. For attributes that you want to display as headers and that are not defined as workflow message attributes but are stored in the underlying application tables, you must perform similar steps to those required for retrieving data from the tables for display in the body details.

    For more information, see: Body Details.

arrow icon   Body Details:

The second-level and third-level details screens can optionally be used for an approval notification to display more granular body content about the approval object, which is retrieved from the underlying application tables. For example, a second-level details screen can show requisition lines, expense lines, purchase order lines, and so on. A third-level details screen that is a child of a root or parent second-level details screen can show further details, such as distributions for each requisition line.

Note: To streamline the content presented to approvers, only two levels of body details screens are supported. That is, you cannot drill down any further from a third-level details screen.

You should configure body details to be displayed in the second-level and third-level details screens only if the number of records to display can vary at runtime. If the approval object has a finite number of related attributes for the approver to review, it is recommended that you define them all as header attributes so that the approver does not need to drill down to another details screen.

The Approvals app organizes body details for an approval object in the following hierarchy:

  1. Region - A region is the highest level of approval object details content. In the app, a root or parent region is available through a link in the first-level details screen that the approver can tap to drill down to view more details. A non-root or child region is available through a drill-down icon within the second-level details screen for its associated root region. An approval object can have one or more detail regions.

  2. View - A view is a group of records. A region is a collection of one or more views. Each view maps to an underlying view object from which approval object details records are retrieved. Each view within a region can optionally have a view title that is displayed before the view content.

  3. Row - A row is an approval object detail record that contains a collection of one or more attributes.

  4. Attribute - An attribute is an approval object data detail. An attribute is represented as a name - value pair in the Approvals app.

The approvals data services rely on the Oracle Application Framework BC4J implementation to retrieve data for an approval object from the underlying application tables . When you configure the body details for an approval notification to appear in the Approvals app, you must select the view object through which the content is retrieved from the tables.

The full notification body for a workflow notification can include several types of content when it is displayed in the Notification Details page in Oracle E-Business Suite. Content shown in the following formats can be easily converted to be displayed in the Approvals app:

However, the Approvals app cannot include the following:

Follow these steps to prepare your approval object body details for display in the app. You can then use the approvals data services configuration tool to configure the body details you have identified.

arrow icon   To determine what body details to display in the app:

  1. Review the notification body content displayed in the Notification Details page in Oracle E-Business Suite, and identify the regions needed to display body details for the approval object. To streamline the content presented to approvers in the app, it is recommended that you include only the most important body details necessary to allow approvers to make a decision.

  2. For each region, select a region name. The region name for a region displayed in a second-level details screen will appear as a link in the first-level details screen. It is recommended to keep the region name short for better display, such as "Expense Lines" or "Vacancy Details".

  3. If you plan to define more than one region for an approval object, determine the order in which the regions should appear.

  4. Identify the views to display within each region.

  5. For each view, select a view title that describes the content in the view to the approver. To streamline the content, it is recommended to keep the view title short, such as "Credit Card Expenses" or "Cash and Other Expenses".

    Note: If a region contains only one view, then you do not need to provide a view title.

  6. If a region contains more than one view, determine the order in which the views should appear.

  7. Identify the attributes to display in each row. To streamline the information presented to approvers, you should select only the most important details to appear as attributes in each row. For each attribute, select an attribute name to appear as a label before the attribute value. It is recommended to keep the attribute name short for better display.

  8. Determine the order in which the attributes should appear within the row. The key attribute that identifies the row should appear first. For example, in the row for an expense line, the key attribute could be "Expense Type".

  9. If a region displayed in a second-level details screen will have a child region displayed in a third-level details screen, determine which attribute in the root or parent region should have the drill-down icon displayed next to it for approvers to navigate to the child region details.

  10. If an attribute requires a unit of measure, it is recommended that you concatenate the value and the unit of measure into one attribute. For example:

    Amount   1,400 USD
Quantity 1 EA

  11. After you have identified the body details that you want to display in the app, you must determine how to retrieve the corresponding data from the underlying application tables. Begin by reviewing the message definition in Oracle Workflow Builder to determine how the message body is generated. For body content that is included through a message attribute token, including embedded Oracle Application Framework regions and PL/SQL documents, check how the message attribute value is set. You may need to review your related application code if you have implemented logic that sets specific values at runtime. Then prepare the objects needed to retrieve the data, depending on how the message body content is generated.

  12. If you want a particular region to be displayed in the apps only in certain circumstances, prepare the attribute you will use to configure that region for conditional display. See: To prepare a region for conditional display.

arrow icon   To use body details defined through an embedded Oracle Application Framework region:

  1. For body content defined through an embedded Oracle Application Framework region, the message attribute value should ultimately resolve to a Java Server Page (JSP) call in the following format that references that region.

    JSP:/OA_HTML/OA.jsp?OAFunc=<Function_Name>&<ParameterName1>=<ParameterValue1>&<ParameterName2>=<ParameterValue2>...

    Identify the JSP call for each Oracle Application Framework region embedded in the message body. Note that a message body can include multiple embedded Oracle Application Framework regions. If so, ensure that you identify the JSP call for each region.

  2. For each region, use Oracle JDeveloper to review the Oracle Application Framework region implementation referenced in the JSP call. In Oracle JDeveloper, identify the view objects used to retrieve the approval object data. The region may extend other regions that each use a separate view object. Select the view objects that you want to include in the approval notification body details. It is recommended that you include only the most important content to streamline the content displayed in the app.

    Note: If the existing view objects do not meet your needs for approvals data services configuration, you can optionally create new view objects to retrieve content specifically for approvals data services. However, in this case you must maintain both implementations separately going forward. In most cases, you can reuse the existing view objects to retrieve content for the Approvals app as well.

  3. Verify that the view attributes you want to reference are defined with the appropriate attribute types so that the client device can format their values according to the client locale. For example, the client device can display values marked as Date and Number attributes with the appropriate format masks for the locale that the user selected for the device. However, the client device cannot format date and number values contained in String attributes.

    For an attribute that contains a currency value, it is recommended that you format the amount and the currency code in the view object's SQL before returning the value as a String. For example:

    SELECT ... TO_CHAR((quantity * unit_price), 
                   FND_CURRENCY.GET_FORMAT_MASK(currency_code, 40),
                   'NLS_NUMERIC_CHARACTERS='''||FND_PROFILE.VALUE('ICX_NUMERIC_CHARACTERS')||'''') 
           || ' ' || currency_code as line_amount, ... 
FROM ...

    This SQL code can perform rounding of the currency amount based on the number (in this example, the number resulting from the quantity * unit_price calculation) and the currency code. For example, suppose the number resulting from the quantity * unit_price calculation is 123.45678 and the currency code is USD, which has a precision of 2 as defined in the FND_CURRENCIES table. In this case the SQL would return the amount as follows:

    select TO_CHAR(1234.56789, 
               FND_CURRENCY.GET_FORMAT_MASK('USD', 40),
               'NLS_NUMERIC_CHARACTERS='''||FND_PROFILE.VALUE('ICX_NUMERIC_CHARACTERS')||'''') 
from dual;

    The resulting rounded amount would be: 1,234.57

    Next, suppose the number is 123.45678 but the currency is JPY, which has a precision of 0 as defined in the FND_CURRENCIES table. In this case the SQL would return the amount as follows: 

    select TO_CHAR(1234.56789, 
               FND_CURRENCY.GET_FORMAT_MASK('JPY', 40),
               'NLS_NUMERIC_CHARACTERS='''||FND_PROFILE.VALUE('ICX_NUMERIC_CHARACTERS')||'''') 
from dual;

    The resulting rounded amount would be: 1,235

  4. Identify the BC4J application module that includes the view objects you have selected.

  5. Identify a method in the AM Implementation class (AMImpl) that can initialize the selected view objects, from which approvals data services can retrieve records. If no existing method meets your needs, add a new method in the AMImpl class to initialize the view objects.

    To be used for the approvals data services, the initialization method must accept one or more of the following input parameters and use those parameters to initialize and execute the selected view objects.

    For example, the oracle.apps.ap.oie.workflow.apexp.server.NotifAMImpl class used by embedded Oracle Application Framework regions for Expense approvals includes the following method, which accepts the report header ID and initializes all the view objects to retrieve expense lines:

     public void initExpQuery(Number nReportHeaderId);

    This method can be used in the message configuration without requiring any changes because the report header ID value is available as a message attribute.

    If you require certain business logic to be executed before the view objects are executed, you can implement that business logic within the initialization method as well.

    Note: It is recommended that you use the same initialization method for your existing embedded Oracle Application Framework regions in notifications displayed in the Worklist pages and for your approvals data services message configuration.

    For a view in a non-root or child region, the initialization method should include one or more parameters that will be mapped to view attributes from the related view in the parent or root region. That is, you must select at least one view attribute from the parent to pass to the initialization method for a child view. Other input parameters for the initialization method for the child can be drawn from the workflow attributes listed above or from constant values.

  6. When you configure the message in the approvals data services configuration tool, you will specify the view objects you selected and the AMImpl method that initializes each view object. At runtime, the approvals data services execute the initialization method which in turn executes the view object. The approvals data services then retrieve the records from the view object and return the XML response containing the approval object data to the client.

arrow icon   To use body details defined through a PL/SQL document:

  1. For body content defined through a PL/SQL document or PL/SQL CLOB document, the message attribute value should ultimately resolve to a PL/SQL procedure reference in the following formats, respectively:

    plsql:<procedure>/<document_identifier>

plsqlclob:<procedure>/<document_identifier>

    Identify the PL/SQL procedure and review the SQL queries within it to determine how they retrieve approval object data from the underlying application tables.

  2. Ensure that the PL/SQL procedure includes a SQL query that accepts one or more of the following input parameters:

    If necessary, rewrite the SQL with appropriate bind parameters to accept at least one of these parameters.

  3. Use Oracle JDeveloper to create a view object that implements this SQL query and retrieves the approval object data. Then incorporate this view object into an application module, either existing or new, and create a method in the AM implementation class that can initialize the view object for execution as described in step 14.

  4. When you configure the message in the approvals data services configuration tool, you will specify the view objects you selected and the AMImpl method that initializes each view object. At runtime, the approvals data services execute the initialization method which in turn executes the view object. The approvals data services then retrieve the records from the view object and return the XML response containing the approval object data to the client.

arrow icon   To prepare a region for conditional display:

In some cases, you may want a particular region to be displayed in the apps only in certain circumstances. For example, if the same message definition is used as a boilerplate template to send approval notifications for different approval objects, you may want to include different detail regions for the different types of approval notification content and display only the relevant regions for each approval notification in the app. When you configure the message in the approvals data services configuration tool, you can define rules for the regions to control whether the regions are displayed.

A rule compares a value that is set dynamically at runtime with a constant value called an operand to determine whether to display the region. You can use a message attribute to obtain the runtime value to use in the comparison.

For example, the workflow message PO_REQ_APPROVE_JRAD in the item type REQAPPRV is used to send Purchase Requisition approvals and Contract Requisition approvals. This message has a message attribute named "Is Contractor Requisition" that stores a value of either Y or N. If one region is defined to display purchase requisition details, and another region is defined to display contract requisition details, this message attribute can be used in region-level rules specifying that the first region should be displayed only when the "Is Contractor Requisition" attribute is set to N, and the second region should be displayed only when the "Is Contractor Requisition" attribute is set to Y.

Alternatively, the #APPROVALS_OBJECT attribute could be used to differentiate Purchase Requisition approvals and Contract Requisition approvals. In this case, the #APPROVALS_OBJECT attribute would need to be defined for the message and the workflow would include logic to set the #APPROVALS_OBJECT attribute to PURCHASE_REQ for purchase requisitions or to CONTRACT_REQ for contract requisitions. The #APPROVALS_OBJECT attribute can then be used in region-level rules to determine at runtime which region to display.

  1. To prepare to define a rule for a region, determine which message attribute can retrieve a value representing the approval object for the approval notifications at runtime.

  2. If you plan to use the #APPROVALS_OBJECT message attribute, update the workflow definition to add this attribute and include appropriate logic to set its value.

arrow icon   Action History:

The action history for a workflow notification shows what actions users have performed on the notification to date. See: Action History.

Oracle Workflow provides a default action history that records when the following actions have occurred:

To use the default action history, an approval object must be processed by a single workflow notification activity throughout its entire lifecycle. That is, if multiple levels of approval are required, the workflow process should loop back to the same notification activity to send a notification to each approver until all approvals are completed. In this way Oracle Workflow can record all the approvals as actions for the same notification activity.

If an approval object uses the default Oracle Workflow action history, then the Approvals app automatically includes that action history in the approval notification details. In this case you do not need to perform any further configuration for the action history. The approver can drill down from the first-level details screen to view the action history, including the following details:

You can optionally define a custom action history for an approval notification to replace the standard action history, using the special message attribute named #HISTORY. For example, if an approval object is routed from one notification activity to another or from one item type to another during its lifecycle, then the default action history does not apply, but you can track the actions performed on the approval object using a custom action history retrieved from the underlying application tables.

To display the custom action history in the Approvals app, review its contents and identify the attributes that you want to display in the app. Then you must perform similar steps to those required for retrieving data from the application tables for display in the body details.

For more information, see: Body Details.

You can then use the approvals data services configuration tool to configure the custom action history region with the content you identified.

arrow icon   Attachments:

The Approvals app can display two types of attachments for approval notifications:

If these types of attachments are defined for a notification in its workflow definition, then the Approvals app automatically includes them in the approval notification details. You do not need to perform any further configuration for the attachments. The approver can drill down from the first-level details screen to view the attachment contents.

arrow icon   Approval Response Actions:

In the response section, which appears in all the approval details screens, the approver can choose either the Approve or the Reject response action for the notification. The Approvals app supports only these two response actions. You can optionally configure different labels to be displayed for these actions, such as Yes and No instead of Approve and Reject, respectively. However, one action should still generally indicate approval or acceptance, while the other action should generally indicate disapproval or rejection. The app displays the same icon images regardless of the labels you specify: a green check mark icon for the Approve response action and a red X or cross icon for the Reject response action.

You can configure messages for the app that have additional possible results as part of their workflow definitions, but you must select only two of the results to map to the Approve and Reject actions within the app. To respond with other results, users must access messages through the Worklist pages or through e-mail.

After choosing the Approve or Reject response action, the approver can optionally enter a note with comments about the decision.

The response section also includes a Request Information option for the approver to request more information before making a decision. However, the approval notification is not completed until the approver chooses either the Approve or the Reject response action.

Note: The app does not support reassigning approval notifications. To reassign approval notifications, users must access the notifications through the Worklist web pages.

Follow these steps to prepare approval notification results for use as responses within the Approvals app. You can then use the approvals data services configuration tool to configure the responses you have identified.

  1. If the workflow notification definition includes more than two possible results, select only two to use within the app. For example, if the possible results are Approve, Reject, and Return for Correction, the Approve and Reject results would be most appropriate to use within the app, while approvers would need to access the notifications through the Worklist pages or e-mail to respond with the Return for Correction result.

    You can use Oracle Workflow Builder to review the lookup type used in the result for the message and the lookup codes available as possible results in that lookup type.

  2. Determine which result indicates approval or acceptance, to map to the Approve response action, and which result indicates disapproval or rejection, to map to the Reject response action. Also, decide what labels you want to display for these actions in the app. The most commonly used labels are Approve and Reject. You can optionally configure other labels appropriate to your approval notification, such as Yes and No.