14 Implement the UI Shell

This chapter discusses the UI Shell page template used to build web pages, and the components used to implement user interface features in Oracle JDeveloper (JDeveloper), such as menus and task flows.

This chapter includes the following sections:

For more information about the features, see:

14.1 Introduction to Implementing the UI Shell

The UI Shell is a page template containing default information, such as a logo, menus, and facets. To supplement the UI Shell template, there is a UIShellMainArea template. Because you can load information into dynamic tabs, the main area (the center and the right as shown in Figure 14-1) cannot be a part of the page itself because it is loaded dynamically.

The UI Shell design supports task-based and user-based navigation, and organizes screen real estate more effectively by collating tasks, providing dedicated spaces for primary-task supporting information, and maintains general order and appropriate hierarchy among various elements on the screen.

The UI Shell for Applications User Experience (Applications UX) patterns provides a system of containers that fulfill common layout and navigational requirements in a structured, consistent manner. The UI Shell focuses on providing detailed design for defining and organizing various types of navigation and other functionality such as search and auxiliary information for Oracle Fusion Middleware alone.

Note:

Two UI Shell templates are implemented: the classic shell and the Simplified Experience UI (usually called FUSE+). Items can be shown or hidden based on the template. The API getShellType() will return "simple" or "classic" depending on the page template used in the current page. Developers can determine the active template by using the Expression Language expression #{applcoreShellBean.shellType} to identify the shell type.

Before You Begin:

You should be familiar with JDeveloper, be able to create and run JavaServer Faces (JSF) pages, and be able to create an Oracle Application Development Framework (Oracle ADF) task flow.

14.1.1 Standard Related to the UI Shell

Almost all shipped Oracle Fusion Applications pages are built using the UIShell page template. Exceptions include the login page, and the password preferences page.

14.1.2 UI Shell Description

The UI Shell is composed of four default areas: global, regional, local, and contextual, as shown in Figure 14-1.

Figure 14-1 UI Shell Areas

Described in the surrounding text.

The basic information about the UI Shell includes:

  • The shell is optimized for a screen resolution of 1280x1024 pixels.

  • The four areas (refer to the circled numbers on the image) are:

    1. Global Area: The global area, across the full width at the top of the UI Shell, is static, consistent, and persistent for an individual user. It contains controls that generally affect the contents of the other three areas. See Global Area Standard Icons.

    2. Regional Area: The regional area is in the left-hand pane of the UI Shell. It has controls and content that generally affect the contents of the local and contextual areas. Tasks lists in the regional area automatically are bulleted to make it clear when a line item wraps to the next line.

    3. Local Area: The local area is in the center of the UI Shell where users do their work. It is the main work area and typically contains the transaction form with the menus and controls that enable users to be productive. Controls in, and the content or state of, the local area generally affect the contents of the contextual area.

      • Main Area: This term designates the combination of the local area and the contextual area.

    4. Contextual Area: The contextual area is in the right-hand pane of the UI Shell, with controls and contents that generally are affected by controls in, or the content or state of, the local area; although in specific cases the contextual area can also affect the contents of the local area (causing a local-area reload).

  • Application designers, customers, and administrators can set the regional and contextual areas as collapsed for specific applications. End users can expand those areas at runtime.

  • If there is no content in the regional or contextual area, the area is collapsed and the ability to expand it is disabled.

  • The contextual area is directly bound to the local area. The application developer can bind the contextual area content to the local area such that each invocation of a local area automatically causes a relevant contextual area in the correct state to appear alongside the local area.

14.1.2.1 Global Area Standard Icons

The global area incorporates several built-in icons, as shown here:

Figure 14-2 Global Area Standard Icons

Global Area Standard Icons

From 1 (Home) to 10 (User Name), the numbered icons are:

  • (1) Home

    Click this icon to return to the defined Home page. See Implementing the Oracle Fusion Home Page UI.

  • (2) Navigator

    The Navigator, shown in Figure 14-23, is rendered when the Navigator icon is clicked on the UI Shell. See Displaying the Navigator.

  • (3) Favorites, Recent Items and Tags

    This icon combines the Favorites, Recent Items and Tags functions. When you click this icon, the dialog shown in Figure 14-3 is displayed.

    Figure 14-3 Favorites, Recent Items and Tags

    Described in the surrounding text.
    • Favorites adds the currently-focused task flow to the Favorites list.

    • Recent Items tracks a list of the last 20 task flows visited by a user. See Implementing Recent Items.

    • Tags is a service that allows users to add tags to selected resources in Oracle Fusion Applications to contribute to resources other users have visited. See Implementing Tagging Integration.

  • (4) Watchlist

    Click the Watchlist icon to display a user-accessible UI that provides a summary of items the user can track using shortcuts. See Implementing the Watchlist.

  • (5) Notification

    Click the icon to display the Notification dialog shown in Figure 14-4.

    Figure 14-4 Recent Notifications Dialog

    Described in the surrounding text.
  • (6) Social

    Click the Social icon to display Oracle Social Network conversations. See Implementing Oracle Social Network Integration.

    Note:

    • The link displays only if Oracle Social Network is provisioned on the system and registered in the application topology.

    • The link is supplied automatically by the UI Shell; it requires no developer work.

  • (7) Accessibility

    The Accessibility icon appears on all pages. It will allow users to set their accessibility preferences because the Personalization menu, which includes preferences, is hidden for anonymous users.

  • (8) Search

    Click the icon to display the Global Search dialog shown in Figure 14-5.

    Figure 14-5 Global Search Dialog

    Described in the surrounding text.

    See How to Use Basic Search.

  • (9) Help

    When you click the Help icon, it turns orange. Then, if there is contextual help on the page, smaller orange icons will display, as shown in this figure.

    Figure 14-6 Context Help Icon in Application Page

    Described in the surrounding text.

    You then click the one you want for the context help topics, as shown below.

    Figure 14-7 Example of Context Help Links

    Described in the surrounding text.

    If there is no context help available on the page, the main Help icon turns orange, but no smaller icons are displayed.

    To turn off Help, click the main icon again.

  • (10) Settings and Actions

    Click the user name to display the Settings and Actions menu. The menu options are described in Using the Settings and Actions Menu.

14.2 Populating a UI Shell

The UI Shell is a page template with some facets for content that may be placed directly on the page, but it usually has its content inserted dynamically. The dynamic insertion happens by reading metadata in the form of menu metadata. This informs the UI Shell about which task flows to load and where. The UI Shell also can create a list of tasks, from the same metadata, that, when clicked, can load into the main area. All task flows and the page built by the UI Shell template follow the standard ADF Security framework.

When you create an application using the Oracle Fusion Web Application (ADF) template, two projects automatically are created for you: the model and the user interface projects. The default names for these projects that JDeveloper provides are Model and ViewController. You then add the Applications Core (ViewController) tag library to the user interface project. See Adding the Applications Core Tag Library to Your User Interface Project.

Related Links

The following document provides additional information related to subjects discussed in this section:

  • For more security framework information, see the Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework guide.

14.2.1 How to Create a JSF Page

Creating an Oracle Fusion application also creates your application's workspace, where you will later place your page fragments and task flows. For more information about task flows, see the "Getting Started with ADF Task Flows" section of the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about starting JDeveloper, see Chapter 2, "Setting Up Your Development Environment."

To create a JSF page:

  1. Select the user interface project in the Application Navigator.
  2. Choose File > New > Web Tier > JSF > JSF Page.

    The Create JSF Page dialog is displayed, as shown in Figure 14-8.

    Figure 14-8 Create JSF Page Dialog

    Described in the surrounding text.
  3. In the dialog:
    • Enter a file name and directory path. The file name should follow the naming patterns required by your group.

    • From the Use Page Template list, select UIShell.

    • Select Create as XML Document (*.jspx).

    • Click OK.

  4. The new JSF page is displayed in the editor. Note that the page headers in the Design view do not display exactly as they will at runtime.

    Note:

    This JSPX page is just the container for the UI Shell template. All other page content, such as the regional, local, and contextual area flows, and the dynamic task flows, are defined independently. At runtime, the menu definition assembles the various parts. All task flows are loaded into a page created with the UI Shell template by configuring the Menu file. This is done to control the behavior and the dynamic loading of task flows at runtime. It also creates the Navigator and Task List menu. See Working with the Global Menu Model and Working with the Applications Menu Model.

Now you can add components to the page. Table 14-1 lists the itemNode properties that can be used for a JSF page. See Working with the Applications Menu Model for how to add a menu to the page.

Table 14-1 itemNode Properties of a JSF Page

ItemNode Property Property Value Description

action

Name that has been assigned to the action.

Go to the page defined by the action.

dataControlScope

String

The values are shared (the default) or isolated.

This is set at the page level itemNode. When dataControlScope is set to isolated, the UI Shell loads the main area and regional area task flows with dataControlScope set to isolated. When dataControlScope is set to shared, the UI Shell loads the main area and regional area task flows with dataControlScope set to shared.

For example:

<itemNode id="itemNode_AppsPanelTests_TabsWA"
label="label_AppsPanelTests_TabsWA" action="AppsPanelTests_TabsWA"
focusViewId="/AppsPanelTests_TabsWA" dataControlScope="isolated">

isDynamicTabNavigation

True or False

This property provides an option to suppress dynamic tab navigation and just display one main area at a time. To do this, add the following property and value to the itemNode that represents your JSPX:

isDynamicTabNavigation="false"

Other menu metadata stays the same. The Task List menu will continue to render. Clicking a Task link will replace the current main area task flow with the new one.

Multiple defaultMain definitions are allowed and will open multiple tabs on page load. The first one with disclosed="true" will be the tab in focus.

If the property value is not defined, it defaults to true.

id

Unique identifier

 

label

String

This is what appears in the work area title.

Note: For all UI Shell work area pages with Data Visualization Tool (DVT) components in the default main area task flow, and for Home pages with DVT components, you must create the af:document title as an Expression Language expression that sets the title with the default main area task flow label, as shown in this example:

   <af:document id="d1"
   title="#{adfBundle['oracle.apps...resource.xyzGenBundle']['Header.DefaultMain']} -
   #{adfBundle['oracle.apps...resource.xyzGenBundle']['Header.WorkAreaLabel']} -
   #{adfBundle['oracle.apps.common.acr.resource.ResourcesGenBundle']['Header.OracleApplications']}" >

For UI Shell pages with DVT components in their dynamic main area task flows, the title is set on the AdfRichDocument by UI Shell code for the openMainTask, closeMainTask and tab switch.

focusId

Name of the view activity.

 

formUsesUpload

True or False (default)

To set the UI Shell's af:formUsesUpload value to "true," add the formUsesUpload="true" property to the itemNode that represents the JSPX (similar to the way isDynamicNavigation is set). You would use this property when you want to allow uploading of file features using the af:inputFile component.

regionalAreaWidth

Numeric value

See How to Control Regional Area Task Flows.

isRegionalAreaCollapsed

True or False

See How to Control Regional Area Task Flows.

14.2.1.1 Working with the Applications Menu Model

Page and task flow information are local to a particular Oracle Fusion application and are exposed using the Applications menu model.

An Applications menu is related to a local JSPX file and includes the task lists, defaultMain, and defaultRegional. A menu is created for each Java EE application.

14.2.1.1.1 How to Create an Applications Menu

The following information describes how to create an ADF menu to access page elements through the Navigator on JSF pages or task flows that are based on the UI Shell template.

Select the JSPX page in the Application Navigator, then right-click and select the Create Applications Menu option.

This step creates the menu file with one itemNode. The menu file will be named <view id>_taskmenu.xml. For example, if there is a PageA.jspx, its view ID in the adfc-config.xmlfile is PageA, and the menu file name is PageA_taskmenu.xml. This step also should add the ApplicationsMenuModel managed bean entry into the adfc-config.xml file. The managed bean entry should not have the topRootModel managed bean property set. Example 14-1 shows a sample of the generated content in the PageA_taskmenu.xml file.

Creating ADF Menus for Multiple JSF Pages

Use this alternate method to create menus for multiple pages at once. This will create an empty menu on each page.

  1. Right-click the adfc-config.xml file and choose Open to display the file in the JDeveloper editor.

    The adfc-config.xml file is located in the following location: <project_name> > WEB INF.

  2. Drag pages from the Application Navigator to the adfc-config.xml file in the editor.

    View nodes that represent the pages or task flows are displayed in the editor.

    When you drag the pages or task flows, they automatically are grouped into the same menu.

  3. Right-click the adfc-config.xml file and choose Create Applications Menus. An empty panel, as shown in Figure 14-9, is displayed.

    Figure 14-9 Initial Create Applications Menus Display

    Described in the surrounding text.
  4. Click Find Pages to populate the display with all the JSPX pages that have been added to the adfc_config.xml file. As shown in Figure 14-10, pages that do not yet have a menu associated with them will have a checkbox that defaults to being selected, and pages that already have an associated menu are shown with a checkmark to the right.

    Figure 14-10 Populated Create Applications Menus Display

    Described in the surrounding text.
  5. Click OK to automatically create a menu file for each selected page and to update the task flow with a managed bean.

    Note:

    Menu files will follow the <focusViewId>_taskmenu.xml naming standard. For example, the menu file for the Example.jspx file will be /WEB-INF/menus/Example_taskmenu.xml.

    When you create this menu file, the following occurs:

    • The menu file is generated and placed into the following directory: ViewController/public_html/WEB-INF/menus

    • The following are generated and appear in the adfc-config.xml file:

      • A new control-flow rule

      • A managed bean entry

    The new menu that contains your pages is now accessible from the Navigator panel.

Example 14-1 Example of Generated Content in a taskmenu.xml

<?xml version="1.0" encoding="UTF-8" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
  <!-- This is the page level node -->
  <itemNode id="itemNode_PageA" label="label_PageA" action="adfMenu_PageA"
            focusViewId="/PageA">
            <!-- Optional itemNode for Regional Task List task flow. Your task menu definition may omit this if your page does not display a Regional Task List. -->
            <itemNode id="__myProduct_RegionalTaskList"
                      focusViewId="/PageA"
                      label="#{applcoreBundle.TASKS}" taskType="defaultRegional"
                      taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/TasksList.xml#TasksList"
                      disclosed="true"
                      parametersList="fndPageParams=#{pageFlowScope.fndPageParams}"/>
            <!-- Typical itemNode entry for a task flow -->
            <itemNode id="__myProductTFId"
                      focusViewId="/PageA"
                      label="#{myBundle.myProductTFxyz}" taskType="defaultMain"
                      taskFlowId="<fully qualified-TFid>"
                      disclosed="true""/>
            <!-- .. Additional itemNodes for other task flows on PageA -->
  </itemNode>
</menu>

14.2.2 How to Add Default Main Area Task Flows to a Page

When a user opens an application, he or she expects something to be displayed automatically. A task flow in the main area accomplishes this.

To add a task flow to the default Main Area:

  1. Choose File > New > Web Tier > JSF > JSF Page Fragment.

    The Create JSF Page Fragment dialog shown here is displayed.

    Figure 14-11 Create New JSF Page Fragment Dialog

    Described in the surrounding text.
  2. In the Create New JSF Page Fragment dialog:

    1. Enter a page fragment name, for example:

      The file name should follow these patterns:

      • <Object><Function>.jsff, such as PoSearch.jsff.

      • <Object>.jsff, such as PurchaseOrder.jsff.

      The page name should convey the object it presents (an employee, a supplier, an item, a purchase order, an applicant, and so on), and the function being performed (search, promote, hire, approve, view). For some pages, the object is sufficient.

      For update or create pages, just the object is necessary (unless the create and update pages are different as shown in the examples).

      Never give pages step number names, such as PoCreateStep1.jsff or PoCreateStep2.jsff. Always describe the page function, such as PoDesc.jsff or PoLines.jsff.

    2. From the Use Page Template list, select UIShellMainArea.

      Note:

      The UIShellMainArea template is only for main area task flows, not regional area task flows.

  3. Click OK.

    The Local and Contextual area facets of the page fragment appear in the editor.

  4. Choose File > New > JSF > ADF Task Flow to create a default task flow.

    Note:

    Most applications will have multiple task flows for the Regional, Local and Contextual areas. For instance, Figure 14-1 shows 12 task flows.

    The Create Task Flow dialog shown here is displayed.

    Figure 14-12 Create Task Flow Dialog

    Described in the surrounding text.

    In the Create Task Flow dialog:

    1. The file name defaults to task-flow-definition.xml. Enter a descriptive file name.

      The file name should follow these patterns:

      • <Object><Function>.xml, such as PoSearch.xml.

      • <Object>.xml, such as PurchaseOrder.xml.

      The page name should convey the object it presents (an employee, a supplier, an item, a purchase order, an applicant, and so on), and the function being performed (search, promote, hire, approve, view). For some pages, the object is sufficient.

      For update or create pages, just the object is necessary (unless the create and update pages are different as shown in the examples).

      Never give pages step number names, such as PoCreateStep1.jsff or PoCreateStep2.jsff. Always describe the page function, such as PoDesc.jsff or PoLines.jsff.

    2. From the Use Page Template list, select UIShellMainArea.

      Note:

      The UIShellMainArea template is only for main area task flows, not regional area task flows.

  5. Ensure that the JSF page fragment file is selected in the Application Navigator and is displayed in the Edit view.

    1. In the Edit view, click the Source tab.

    2. Locate the line <f:facet name="localArea"/>.

    3. In the Application Navigator, select an applicable task flow, such as the one you created in Step 4, to add to the localArea. This should be an XML file located under ViewController > Web Content > WEB-INF > oracle > apps > application_name > ui > flow.

    4. Drag and drop the appropriate flow from the Navigator pane to immediately following <f:facet name="localArea"/>.

    5. From the Create menu that is displayed, select Region.

      The af:region tag is nested within the localArea facet and code resembling that shown in Example 14-2 will be inserted after it.

      In the Structure window, an af:region entry is added following the f:facet - localArea entry.

    6. Note: The instructions for the remainder of step 5 are optional. If you do not need a contextualArea, go to Step 6.

      In the Structure window, select f:facet - contextualArea.

    7. In the Component Palette, select ADF Faces > Layout.

    8. Click Panel Accordion. An af:showDetailItem entry is created automatically under af:panelAccordion.

    9. In the Source view, find and highlight the new <af:showDetailItem ...> entry.

    10. In the Application Navigator, select an applicable task flow, such as the one you created in Step 4, and drag and drop it onto the highlighted entry in the Source view.

    11. From the Create menu that is displayed, select Region.

    12. Click OK on the Edit Task Flow Binding dialog that is displayed.

      Code resembling that shown in Example 14-3 will be inserted after <af:showDetailItem ...> .

  6. Now that you have created the main area page fragment, you must wrap it in an ADF task flow.

    Again, select File > New > Web Tier > JSF > ADF Task Flow and in the Create ADF Task Flow dialog:

    1. Enter a descriptive name for the task flow.

      For example, enter def_main_task-flow-definition.xml.

    2. Ensure that the Create as Bounded Task Flow and the Create With Page Fragments boxes are selected.

      Do not change the other default settings.

  7. Click OK.

    The new task flow is displayed as a blank visual editor in the JDeveloper middle section.

  8. In the Application Navigator, select your recently created page fragment (.jsff file), and drag and drop it onto the editor.

    The page fragment itemNode appears in the editor, as shown in Figure 14-13.

    Figure 14-13 Page Fragment itemNode

    Described in the surrounding text.
  9. To load the menu metadata:

    Note:

    The menu data accomplishes several important jobs for you:

    • It defines properties of the page for you. For instance, it will be displayed in no-tab mode or with dynamic tabs, and define the width of the regional area.

    • It can create a task list menu for each page.

    • It can create labels for groups of tasks.

    1. In the Application Navigator, select the test_menu_taskmenu.xml file that you created using the ADF Menu Model dialog. For details about creating the menu, see How to Create an Applications Menu.

    2. In the test_menu_taskmenu.xml structure view menu tree, shown in Figure 14-14, right-click the itemNode item and choose Insert inside itemNode <task_flow_name> > itemNode.

    Figure 14-14 Task-Flow Item Node Menu Choices

    Described in the surrounding text.

    The Insert itemNode - Common Properties dialog, shown in Figure 14-15, is displayed.

    Figure 14-15 Insert itemNode - Common Properties Dialog

    Described in the surrounding text.
  10. In the id field, enter a unique ID using this standard format:

    <pageID>_<taskFlowName>

    This ID example consists of the concatenated page ID (or page name), an underscore, and the task flow name, for example, ExpenseWorkArea_CreateExpense.

  11. In the focusViewId field, enter the ADFc View Activity ID of the page under which you are registering the task flow.

  12. Click Finish.

    The new item node is displayed in the structure view, under the menu tree.

  13. With the item node selected in the structure view, click the Property Inspector tab, as shown in Figure 14-16.

    Figure 14-16 Task Flow Property Inspector

    Described in the surrounding text.
  14. In the label field, enter a label for the task flow, such as CreateExpense.

    This label will be the title of the tab that is opened by the Task Type defaultMain.

    Note:

    Do not leave this field null. This is the label that will appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Supporting No-Tab Work Areas ), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items.

  15. Select test_menu_taskmenu.xml in the Project Navigator tree, and your task flow in the structure view to display its Property Inspector, or select the Property Inspector tab.

    In the Advanced section of the Property Inspector, enter the following values:

    • Task Type: defaultMain (the task flow is displayed by default whenever the page is rendered).

      The Data Control Scope should have been set to isolated, inside the task flow definition for any task flow in the menu (defaultMain or dynamicMain) or any call from openMainTask. See dataControlScope in Table 14-1.

    • Task Flow Id: ID of the task flow to be loaded.

      To enter the ID, click the ellipsis to display the Select Task Flow Id dialog, shown in Figure 14-17, and browse to the task-flow definition location. By default, following the standard naming structure, the location will be in path_to_application directory\ViewController\public_html\WEB-INF.

      Figure 14-17 Select Task Flow Id Dialog

      Described in the surrounding text.

      Click Open to automatically enter the location in the Task Flow field. The task flow ID is a concatenation of the file location for the task-flow definition and the task-flow name. It typically resembles /WEB-INF/MyTaskFlow.xml#MyTaskFlow. The Property Inspector for the itemNode should resemble the example shown in Figure 14-16.

  16. To run the JSPX page, select the page in the Application Navigator, right-click the page file, and choose Run.

    The new page, similar to that shown in Figure 14-18, is displayed in a web browser.

    Figure 14-18 Rendered Page in Browser

    Described in the surrounding text.
  17. Check that the newly rendered page contains one tab whose content is the task flow that you defined in this procedure.

The available itemNode properties for main area and regional area task flows for application menus are shown in Table 14-2.

Table 14-2 itemNode Properties for Main and Regional Task Flows for Application Menus

itemNode Property Property Value What Happens on the Rendered Page

taskType

Note: taskType can have four values:

  • dynamicMain

  • defaultMain

  • defaultRegional

  • taskCategory

  • If the value is dynamicMain, the page contains a new link in the regional area. When you click the link, a new tab with the loaded task opens.

    If the no-tabs model is used, no new tab is opened. Rather, the current main area contents are replaced. (See Supporting No-Tab Work Areas .)

  • If the value is defaultMain, the page contains a tab already running this task in the main area.

    If the no-tabs model is used, only one itemNode should be defined as a defaultMain. (See Supporting No-Tab Work Areas .)

  • If the value is defaultRegional, the task is loaded into the regional area.

label

String

Note: When passing parameters, do not leave the label field null. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Supporting No-Tab Work Areas ), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items.

taskFlowId

ID of the task flow to be loaded.

The task flow ID is a concatenation of the file location for the task flow definition, and the task flow name. For example:

/WEB-INF/MyTaskFlow.xml#MyTaskFlow

 

reuseInstance (optional)

True or False

If True, when the link is clicked a second time, the tab is brought to the top.

A False value means that clicking the corresponding task link opens new tabs.

However, if the no-tabs model is used, no new tab is opened. Rather, the current main area contents are replaced. (See Supporting No-Tab Work Areas .)

keyList

String

Important: keyList is used with the task flow ID to identify the target tab in the main area. As such, keyList is only applicable in dynamic tabs mode, and is ignored in no-tabs mode.

keyList provides a way to identify a task flow instance. When reuseInstance is true, use the specified keyList in addition to the task flow ID to identify the target tab.

The keyList parameter has been implemented for the following FndUIShellController data control methods:

  • openMainTask

  • discloseRegionalTask

  • collapseRegionalTask

  • navigate

  • openSubTask

In dynamic tabs mode, when looking for a match of an existing tab, these APIs will first look for any instances of the task flow that is already open, which has the same task flow ID as the one passed into them as the parameter. In addition, it will compare the keyList values, such that the existing task flow will be picked only if its keyList values match the ones specified in the keyList parameter.

It does not matter if the task flow parameters are the same or different. If the keyList is not set in the menu metadata, you can reuse a tab only if you pass in a null keyList.

loadPopup

True or False

See Implementing the Task Popup.

This provides a way to load the task flow into a Popup when the user clicks one of the Task List links.

loadDependentFlow

True or False

The no-tab navigation mode can load a main area task flow and a dependent task flow simultaneously, while displaying only one flow at a time. (See Supporting No-Tab Work Areas .)

The UI Shell is limited to 12 task flows: 10 tabs in tab mode; 1 tab in no-tab mode and 1 dependent in no-tab mode.

Dependent Flow is applicable only to the no-tab navigation model. Instead of having only one region for the no-tab navigation model, there are two regions: one for the main task flow and another for the dependent flow. These regions are in a switcher, so that only one is visible at a time. If a dependent task flow is loaded, only the dependent task flow region is shown, and the main task flow region is hidden. When the dependent task flow is closed, the main task flow region is redisplayed, with its state preserved.

When loadDependentFlow is true, the openMainTask API will load the target task flow in the dependent region. Loading a new task flow in the main task flow will close both the existing main task flow and, if any, the existing dependent task flow. Loading a new task flow in the dependent task flow will replace only the existing dependent task flow, if any, and leave the main task flow intact.

forceRefresh

True or False

If forceRefresh = true, the contents are refreshed. If forceRefresh is set to false, if the task flow parameters are identical, no refresh will occur, but if they are different, the task flow is refreshed using the new parameters.

stretch

True (default) or False

When the UIShellMainArea stretch attribute is set to true, contents under localArea will be stretched when rendered in the local area. When set to false, contents under localAreaScroll will not be stretched, but will be rendered with a scroll bar, if necessary, in the local area. (This facet is contained within an af:panelGroupLayout with layout=scroll.)

disclosed (optional)

True or False

All the task flows will be rendered in the main area. The task flow that has disclosed set to true will be in focus.

More than one defaultRegional task can have a true disclosed value, because more than one detail item may be disclosed at a time under a panelAccordion component. If the disclosed value is true, the regional area is expanded. If the disclosed value is false, the regional area is collapsed.

active

True or False (default)

Task flow definitions use conditional activation. There are several cases in which Oracle Fusion Applications run with the regional area collapsed by default. Unless the user expands it, there is no need to activate the task flows for the regional area. However, some use cases depend on the task flow that is under the regional area being active even when collapsed. In this case, the active attribute can be set in the property inspector for the item node. active has three possible values:

  • default <False>

  • False

  • True

If you require that your task flows be activated or run even though they are not displayed, you must change the active property on the itemNode to True.

taskFlow

 

The Task List is exposed as a task flow. See How to Pass Parameters into Task Flows from Tasks List.

destination

String

The destination attribute is supported on the item nodes for Task List; that is, for item nodes that have the task type set to dynamicMain. The destination attribute is intended only for navigating to an external web site. When it is defined, it takes precedence over all other attributes. Example of the menu data:

<itemNode id="__ServiceRequest_itemNode_externalUrl"
   destination="http://www.yahoo.com"/>

parametersList

String

Use to specify which parameters to pass into a task flow. The value of this property is a delimited list of parameter name-value pairs. See How to Pass Parameters into Task Flows from Tasks List.

contextCode

Domain name in which the J2EE application belongs. Valid values are: CommonDomain, BI, FIN, SCM, CRM, PRJ, HCM, PRC, or IC.

This value would be used for the Auto-suggest feature in Global Search. See Implementing Auto-suggest.

objectType

String

Classification for the Recent Item object (for example: opportunity, contact, lead, quote). This value would be used for the Auto-suggest feature in Global Search.

objectName

String

User recognizable string for a given Recent Item instance. This value is used as a string to match keystrokes entered in the auto-suggest field of Global Search. This value will be in the language of the user at the point of navigation (that is, when the record is saved). It will not change if the user changes language.

Example 14-2 Creating Region localArea Facet Added Code

<af:region value="#{bindings.EmpCreateUpdateFlow1.regionModel}"
                 id="EmpCreateUpdateFlow1"/>
</f:facet>

Example 14-3 Example Edit Task Flow Binding Code

<af:region value="#{bindings.EmpSummaryTF2.regionModel}"
 id="EmpSummaryTF2"/>

14.2.3 How to Add Dynamic Main Area and Regional Area Task Flows to a Page

Unless otherwise noted, follow the procedure outlined in How to Add Default Main Area Task Flows to a Page, to insert the appropriate itemNode properties listed inTable 14-2.

  • To add a dynamic main area task flow, set taskType="dynamicMain".

  • To add a default regional area task flow, set taskType="defaultRegional".

14.2.3.1 Adding the Tasks List Menu to the Page

A tasks list is not a default widget as part of the UI Shell regional area. A tasks list is packaged as an ADF Controller task flow. You must manually add this task flow as you would any other defaultRegional task.

Specify the tasks list task flow as a defaultRegional task explicitly. If you do not do this, the tasks list does not render.

Add the following entry to your menu.xml file before the item node of tree structure and tree versions:

<itemNode id="__YourPage_itemNode__FndTasksList"
        focusViewId="/YourPage" label="#{applcoreBundle.TASKS}"
        taskType="defaultRegional"

Note: The taskFlowId value path must appear in a single line to avoid an exception during runtime.

        taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/
                    uishell/ui/publicFlow/TasksList.xml#TasksList"
        disclosed="true"
        parametersList="fndPageParams=
                             #{pageFlowScope.fndPageParams}"/>
  • Id must be unique within the menu metadata.

  • focusViewId is the focusViewId of your page.

  • Set label to the default label provided by the Oracle Fusion Middleware Extensions for Applications (Applications Core).

  • taskType should be defaultRegional.

  • taskFlowId should point to the tasks list task flow provided by Applications Core.

  • The disclosed attribute is usually set to true. Although, it can be set to false if you do not want to disclose tasks list by default.

  • parametersList should set fndPageParams as previously shown so that this object is available in the pageFlowScope of the tasks list task flow. This context is necessary for Single Object WorkArea. For more information, see Using the Single Object Context Workarea.

14.2.3.2 Group Tasks in the Tasks Pane into a Category

The Task Category is a label that is used to group tasks in a task list.

  1. In the Structure window for the menu, right-click the page itemNode whose taskType value is dynamicMain and choose Surround with... .

    The Surround dialog is displayed.

  2. Select itemNode and click OK.

    The Insert Item Node dialog page opens to the Common properties tab.

  3. In the Common properties tab, enter these values:
    • id field: Concatenation of the page ID and a short category name, using the following format, is suggested:

      pageId_categoryName

      For example, you might enter: ExpenseWorkArea_NewExpense.

    • focusViewId: Click the ellipsis to open the Advanced Editor.

      Select the focusViewId of the page.

  4. Click Finish.
  5. In the Property Inspector for itemNode - ExpenseWorkArea_NewExpense, enter these values:
    • label: Name of the label, such as NewExpense.

      Do not leave this field blank. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Supporting No-Tab Work Areas ), do not leave it blank because this label will be used in other ways, such as Add to Favorites or when the system tracks the Recent Items.

      Note:

      The label should be defined in a resource bundle so it can be translated more readily.

    • Task Type: taskCategory

  6. Run the page by right-clicking the JSPX page file in the Projects tree view and choosing Run

    Confirm that the page contains task links arranged by category. The Task List is in the left regional area of the page. Items in the Task List are bulleted to make it clear when a line wraps.

14.2.3.3 Linking to a Task Flow in a Different Page

The Tasks Pane can link to a task flow in a different JSPX and pass page-level and task-level parameters.

The navigateViewId attribute supports this feature.

Example 14-4 shows a sample of the metadata for a link in a Task List that links to another page.

Example 14-4 Example Metadata for a Link in a Task List that Links to Another Page

<itemNode id="__ServiceRequest_itemNode__toTestPage1"
                focusViewId="/ServiceRequest" label="Go to different page"
navigateViewId="/TestPage1"
                taskType="dynamicMain"
taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRTree.xml#SRTree"/>

14.2.3.4 Support No-Tab Work Areas

You can suppress dynamic tab navigation and just display one main area at a time. To do this, add isDynamicTabNavigation="false" to the itemNode that represents your JSPX page, as shown in Example 14-5.

Note that the default value of isDynamicTabNavigation is true.

You also can set the no-tab mode declaratively in the Property Inspector:

  1. Select the itemNode from the Structure window.
  2. Go to Property Inspector.
  3. Select Advanced > Page > Dynamic Tab Navigation. Selecting the Page tab lets you set attribute values for page-level item nodes.
  4. Set the Dynamic Tab Navigation property to false.

Example 14-5 Implementing a No-Tab Work Area

<itemNode focusViewId="/SelTestWorkarea" id="stp1" taskType="dynamicMain"
  taskFlowId="/WEBINF/oracle/.../ProductMainFlow.xml#ProductMainFlow"
  label="#{adfBundle
      ['oracle.apps....SelTestWorkarea_taskmenuBundle'].DEFINE_PRODUCT}"
  isDynamicTabNavigation="false"/>

Other menu metadata stay the same. Tasks List will continue to render. Clicking a Tasks Link will replace the current main area task flow with the new one.

14.2.3.5 Implementing the Task Popup

The Task Popup provides a way for you to:

  • Load a task flow into a popup when the user clicks one of the Tasks List links.

  • Cancel from the popup or open a new main area task flow, passing in parameter values from the popup.

Implementation Notes

The UI Shell provides an af:popup component with a modal af:panelWindow as its immediate child, which would contain a dynamic region defined in it. When selected by the user, the UI Shell will load the task flow into the dynamic region, and show the modal af:popup panelWindow without any buttons. Therefore, the task flow must include the OK and Cancel buttons that are used to open a dynamic tab and dismiss the popup, respectively. The dialog title will be set according to the label mentioned in the menu metadata of the dynamic task link. There is a refresh condition set on the dynamic region that refreshes the task flow and reloads it each time the popup is opened.

Remember the following when you implement the Task Popup feature:

  • For a dynamicMain task that you would like to load into the popup, specify the loadPopup property as true. For example, as shown in Example 14-6, the ChooseSR task flow would be loaded in a popup when the user clicks its link in the Tasks List. The label that is mentioned will be displayed as the dialog title of the popup that starts the task flow.

  • You can define any components within this task flow, except the af:popup and its child components, such as af:dialog, af:panelWindow, and af:menu.

  • You cannot have a UIShellMainArea page template or any other templates inside the popup task flow.

  • You must add the necessary buttons as part of the task flow. For example, if the task flow has a simple .jsff file, it should contain OK and Cancel buttons, along with other components.

  • Create a managed bean to set the action listener for the Cancel button. See Implementing OK and Cancel Buttons in a Popup.

  • Create another method for the OK button that calls the method in Example 18-5, and any additional processing logic. The common use case would be opening a new task in the main area by using the openMainTask API. For example, you can bind the OK button to a managed bean and add your own action listeners. See Implementing OK and Cancel Buttons in a Popup.

  • You then can pass the parameters directly from the managed bean to the openMainTask API bindings for the popup task flow page to open a new dynamic tab. The menu data entries for parameters will not have any bearing on the dynamic taskFlow tab that they are loading in the main area. The details of that task flow should come from the openMainTask API that is bound to the OK button.

Example 14-6 Example Use of loadPopup Property

<itemNode id="__ServiceRequest_itemNode__ChooseSR"
          focusViewId="/ServiceRequest" label="Choose SR"
          taskType="dynamicMain" taskFlowId="/WEB-INF/ChooseSR.xml#ChooseSR"
          parametersMap="#{pageFlowScope.Mybean.Map}"
          loadPopup="true"/>

14.2.4 How to Pass Parameters into Task Flows from Tasks List

Item nodes with a taskType of dynamicMain, defaultMain, and defaultRegional have parameter support. In addition to specifying the taskFlowId to load when the user clicks a task flow link, you can specify which parameters to pass into that task flow. This is accomplished with the parametersList and methodParameters properties on the itemNode.

For the itemNode where you would like to specify parameter passing, add the parametersList property. The value of this property is a delimited list of parameter name-value pairs that will resemble Example 14-7.

Code in the managed bean for passing a hashmap to the task flow would resemble Example 14-8. A hashmap is a data structure that uses a hash function to map identifying values, known as keys (such as a person's name), to their associated values (such as their telephone number).

Then, in the managed bean of the task flow, the Java object can be read, as shown in Example 14-9.

The testValue parameter is bound to an af:outputText value attribute, such as <af:outputText value="#{TestPanelSplitter1MBean.testValue}"/>, in the page fragment of the task flow.

Example 14-7 Using the parametersList Property

<itemNode id="__ServiceRequest_itemNode__SRDefault" focusViewId="/ServiceRequest" label="Pending Service Requests"
taskType="dynamicMain"
taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRTable.xml#SRTable"
parametersList="param1=value1;param2=value2;param3=#{ELForValue3}"/>

Example 14-8 Example Code for Passing a Hashmap

private FndMethodParameters fndMethodParams;
  ...
  public void setRichCommandLink1(RichCommandLink richCommandLink1)
  {
    this.richCommandLink1 = richCommandLink1;
    FndMethodParameters methodParams = new FndMethodParameters();
    HashMap testHashMap = new HashMap();
    testHashMap.put("param1", "12345");
    testHashMap.put("param2", "67890");
    methodParams.setCustomObject(testHashMap);
    fndMethodParams = methodParams;
  }

Example 14-9 Reading Java Object in Managed Bean

public String getTestValue()
  {
    Map pageFlowScope =
      AdfFacesContext.getCurrentInstance().getPageFlowScope();
    Object custom = pageFlowScope.get("fndCustomObject");
    String outputTextString = "";
    if (custom != null && custom instanceof HashMap)
    {
      HashMap myHashMap = (HashMap)custom;
      String temp1 = (String)myHashMap.get("param1");
      String temp2 = (String)myHashMap.get("param2");
      outputTextString = temp1 + temp2;
    }
    testValue = outputTextString;
    return testValue;
  }

14.2.5 How to Open Data Files from a Tasks List Link

The UI Shell implements this feature by using the URLView activity that is a task flow component of ADF. URLView generally is used to redirect the current request state of the application to an external or internal URL. With UI Shell, this URLView activity is only being used to open files that are internal to the current web application.

Therefore, the only input that the task list link will need is the internal path (within the webApp) of the file. After the path is provided to UI Shell, it will determine the current contextual root of the application and append it to the internal path of the file. After the Universal Resource Identifier (URI) for the file is generated, this is set on the URLView activity and an action expression is set on the task link to open the URL view. UI Shell also must call an actionEvent JavaScript method on the client side that will not allow the page to lose its current state upon redirection from the URLView activity.

Note:

You can only open data files that are part of your webApp, such as /oracle/apps/fin/acc/file1.xls. This feature supports only opening data files through the task list. Any other URI paths, such as a JSPX or a JSF page, are not supported.

Implementation Notes

For a dynamicMain task item that you would like to use to open the data file, there is a property called filePath in the Menu panel for the UI Shell page XML file. To enable this property in the Menu panel, during design time, the task type of the itemNode must be dynamicMain. The file URI path then should be specified against the filePath attribute in the Menu panel, as shown in Example 14-10.

You can specify any file type, such as xls, doc, pdf, txt, rtf, and ppt, that is within the application.

Example 14-10 Specifying the File URI Path

<itemNode id="__ServiceRequest_itemNode__ChooseSR"
          focusViewId="/ServiceRequest" label="Download File"
          taskType="dynamicMain" filePath="/WEB-INF/oracle/apps/Accounts.xls" />

14.3 Implementing Application Menu Security

Security of menus has two parts: actual access to the page or task flow, and the rendering of the menu itself. Any page or task flow is protected to run for a user only if that user has access to run the page or task flow. Directions for setting this up are in the Adding Security to an Oracle Fusion Web Application section in the Developing Fusion Web Applications with Oracle Application Development Framework.

Application menus and task list menus will automatically have their page security checked by the menu utilities. If the user does not have access, the menu entry will not be rendered. If the following three conditions are true, security checks if a logged-in user has view privilege for a given task flow:

  • The application has enabled authorization.

  • The taskType is dynamicMain for the itemNode.

  • The taskFlowId attribute is defined in the itemNode.

If any one of these conditions is not true, security is not checked and the itemNode will be protected only by the rendered attribute.

Application menus can have a security Expression Language expression on the rendered attribute that, if it returns false, will not render the menu entry. To do this, set the rendered attribute of the menu entry to an expression that evaluates to true or false. For instance, if the task list is to edit certain tax forms, this could be a business rule to hide or show links based on whether the customer is a nonprofit company. If it evaluates to false, the menu will not appear. For more information on all the security expressions, see the Adding Security to an Oracle Fusion Web Application section in the Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework.

If your UI Shell pages are secured by ADF Security, you must add a policy similar to that in Example 14-11 to the jazn-data.xml file.

Task Flow Example

Bounded task flows are secure by default, and require the policy shown in Example 14-12.

If the policy is missing, then framework-level checks will prevent access to the task flow (typically by throwing an error).

But how would a menu item or command link disable or hide itself based on a preliminary check of the same permission? Example 14-13 shows the generic Expression Language expression being used to perform a preliminary check of the Task Flow Permission. Note that this is only needed for an itemNode with taskType="defaultMain" or "defaultRegional". The security check is performed automatically for an itemNode with taskType="dynamicMain" (that is, what is in the tasks list).

Example 14-14 shows the task flow-specific Expression Language expression.

Note that both of these checks actually go directly against the policy store; that is, they do not query the task flow definition. This avoids the overhead of loading a large number of ADF artifacts to render links and menus.

Example 14-11 Adding a Security Policy to the jazn-data.xml File

<grant>
  <grantee>
     <principals>
        <principal>
           <class>oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl</class>
           <name>anonymous-role</name>
        </principal>
     </principals>
  </grantee>
  <permissions>
      <permission>
         <class>oracle.adf.share.security.authorization.RegionPermission</class>
         <name>oracle.apps.fnd.applcore.uicomponents.view.pageDefs.oracle_apps_fnd_applcore_templates_UIShellPageDef</name>
         <actions>view</actions>
     </permission>
     <permission>
        <class>oracle.adf.controller.security.TaskFlowPermission</class>
        <name>/oracle/apps/fnd/applcore/patterns/uishell/MainArea.xml#MainArea</name>
        <actions>view</actions>
     </permission>
     <permission>
        <class>oracle.adf.controller.security.TaskFlowPermission</class>
        <name>/oracle/apps/fnd/applcore/patterns/uishell/RegionalArea.xml#RegionalArea</name>
        <actions>view</actions>
     </permission>
     <permission>
        <class>oracle.adf.controller.security.TaskFlowPermission</class>
        <name>/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/TasksList.xml#TasksList</name>
        <actions>view</actions>
     </permission>
  </permissions>
</grant>

Example 14-12 Required Policy for Bounded Task Flows

<permission>  <class>oracle.adf.controller.security.TaskFlowPermission</class>  <name>/WEB-INF/audit-expense-report.xml#audit-expense-report</name>  <actions>view</actions></permission>

Example 14-13 Generic Expression Language Expression Used for Task Flow Permission Preliminary Check

rendered = "#{securityContext.userGrantedPermission['permissionClass=oracle.adf.controller.security.TaskFlowPermission;
               target=/WEB-INF/audit-expense-report.xml#audit-expense-report;
               action=view']}"

Example 14-14 Task Flow-specific Expression Language Expression Used for Task Flow Permission Preliminary Check

rendered="#{securityContext.taskflowViewable[/WEB-INF/audit-expense-report.xml#audit-expense-report]}"

14.4 Controlling the State of Main and Regional Area Task Flows

As described in How to Control Main Area Task Flows, UI Shell tasks to open or close a main area tab are exposed as data control methods so that you can create such UI artifacts through drag and drop. You do not need to create your own data control methods and manually raise Contextual Events.

Note:

openMainTask and closeMainTask only work when the calling task flow is loaded into the Main Area directly and locally.

For example, assume a UIShell page of Application1 that is running in Server1 is loading Taskflow1 in its Main Area. This Taskflow1 shows another task flow, Taskflow2, from Application2 running on Server2 and using a portlet mechanism or remote task flow mechanism.

If Taskflow2 uses openMainTask to open another task, it will not work. The task flow that invokes openMainTask should be loaded directly in the Main Area, and the task flow that is loaded should be available to the application locally.

14.4.1 How to Control Main Area Task Flows

The methodParameters parameter can be used to pass a Java object into the task flow that is specified in the taskFlowId parameter. Use the setCustomObject() method in FndMethodParameters to set the Java object. Note that passing a Java object is not supported in Navigate API.

Example of Passing a Java Object Using openMainTask

Bind the methodParameters parameter value to a managed bean property. Example 14-15 shows the methodAction binding in the page definition of the page fragment that calls openMainTask. Also see Table 14-2.

Data control APIs are:

  • FndUIShellController.openMainTask

    Note:

    When passing parameters, do not leave the label field null. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Supporting No-Tab Work Areas ), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items.

  • FndUIShellController.closeMainTask. See closeMainTask History for more information.

To open or close a main area tab, drag and drop the appropriate data control method to create the UI functionality. Having specified the parameter values for these methods, user clicks will prompt the UI Shell to react accordingly.

To use the openMainTask data control method:

  1. Expand the Data Controls and select the openMainTask item, as shown in Figure 14-19.

    Figure 14-19 Selecting openMainTask from Data Controls

    Described in the surrounding text.
  2. Drag openMainTask and drop it onto the page fragment. When you do, the Applications Context menu shown in Figure 14-20 is displayed so you can choose one of the three options.

    Figure 14-20 Selecting an Open Option from the Applications Context Menu

    Described in the surrounding text.

To use the closeMainTask data control method:

  1. Expand the Data Controls and select the closeMainTask item, as shown in Figure 14-21.

    Figure 14-21 Selecting closeMainTask from Data Controls

    Described in the surrounding text.
  2. Drag closeMainTask and drop it onto the page fragment. When you do, the Applications Context menu shown in Figure 14-22 is displayed so you can choose one of the three options.

    Figure 14-22 Selecting a Close Option from the Applications Context Menu

    Described in the surrounding text.

Bind the methodParameters parameter value to a managed bean property. Example 14-15 shows the methodAction binding in the page definition of the page fragment that calls the openMainTask method.

Example 14-8 shows code in a managed bean for passing a hashmap to the task flow.

Then, in the managed bean of the task flow, the Java object can be read, as was shown in Example 14-9.

The testValue parameter is bound to an af:outputText value attribute, such as <af:outputText value="#{TestPanelSplitter1MBean.testValue}"/>, in the page fragment of the task flow.

Example 14-15 methodAction Binding in Page Definition of Page Fragment That Calls openMainTask

    <methodAction id="openMainTask" RequiresUpdateModel="true"
                  Action="invokeMethod" MethodName="openMainTask"
                  IsViewObjectMethod="false" DataControl="FndUIShellController"
                  InstanceName="FndUIShellController.dataProvider"
                  ReturnName="FndUIShellController.methodResults.openMainTask_FndUIShellController_dataProvider_openMainTask_result">
      <NamedData NDName="taskFlowId"
                 NDValue="/WEB-INF/TestPanelSplitterTaskFlow#TestPanelSplitterTaskFlow"
                 NDType="java.lang.String"/>
      <NamedData NDName="keyList" NDType="java.lang.String"/>
      <NamedData NDName="parametersList" NDValue="" NDType="java.lang.String"/>
      <NamedData NDName="label" NDValue="Test App Panel"
                 NDType="java.lang.String"/>
      <NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
      <NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
      <NamedData NDName="loadDependentFlow" NDValue=""
                 NDType="java.lang.Boolean"/>
      <NamedData NDName="methodParameters" NDValue="#{TestOpenMainTaskMBean.fndMethodParams}"
                 NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
    </methodAction>

14.4.1.1 closeMainTask History

The dynamic tabs mode tracks the last tab that was displayed before the current tab. When the current tab is closed, that last tab is brought back into focus.

In no-tabs mode, a stack of all the task flows that were opened is maintained, along with the parameter values. When the current task is closed, the task flow (with its original parameters) that was open before the current one, is reinitialized.

There are two ways in which the previous tab information is set for a given tab. When a new tab is opened, the tab that was in focus is the new tab's previous tab. When the user clicks a tab UI, the last tab that had the focus becomes the current tab's previous tab.

The MainAreaHandler.handleOpenMainTaskEvent method has a mechanism to handle the new tab. The managed bean for the tab adds an additional property for the previous tab. When a new tab is configured to be opened, the current tab is set as the previous tab for the managed bean for the new tab.

A disclosure listener, the MainAreaBackingBean.setLastDisclosedItem, handles user clicks in the tab UI. When the user clicks a tab, two events occur: one for the tab that is going out of focus, and one for the tab that is coming into focus. First, during the out-of-focus event, the tab that is going out of focus is captured in the managed bean's instance variable. Then, during the in-focus event, that instance variable's value is set as the previous tab in the managed bean for the newly focused tab.

Through user clicks, it is possible to create a circular dependency in which TabA's previous tab is TabB, whose previous tab is TabA. In this case, when TabA is closed, TabB would come into focus. However, when TabB is consequently closed, TabA would have to be focused, but it has already been closed. This corner case is handled by moving the focus to the first tab in the main area.

No-Tab Navigation

To keep track of all task flows that have been opened, a Stack instance variable is introduced in the MainAreaHandler method. When a new task flow is opened, the task flow ID and its associated parameter values are added to the stack.

Having this information, the call to closeMainTask pops the stack to get the last task flow ID and its parameter values that were displayed, and reinitializes the main area with that task flow and parameter information.

See also Supporting No-Tab Work Areas .

14.4.2 How to Control Regional Area Task Flows

The UI Shell exposes the means to control the disclosure state of the regional area as a whole, and the disclosure state of individual panels within the regional area panel accordian.

Declarative support: Allows you to specify the initial state of the following on loading a work area JSPX page.

  • Within the regional area, whether a regional area task panel is collapsed or disclosed.

  • A given regional area panel that is disclosed on initial rendering of the page should reflect its assigned pixel height to determine how much screen real estate it occupies.

Programmatic support: Allows you to control the initial or subsequent state of the following within a work area JSPX page.

  • By default, the disclosure state is driven by what is specified declaratively. However, after initial page load, you can override the declarative default and, for example, render the work area with the regional area collapsed (overriding the declarative setting of rendering that work area with the regional area disclosed).Disclosing a collapsed regional area splitter programmatically in response to a UI action by the user (such as a button click or menu selection).

Declarative support is provided using attributes exposed on the respective item node in the Menu Model.

For regional panels:

There are separate APIs that expose parameters to refresh the task flow and set the disclosure state for the showDetail items in the panel accordian. The showDetail items are identified by the task flow ID specified.

Implementation Notes

  • Specify the default values for the regional or main splitter position and collapsed state in the menu for the item node that represents the page, using the regionalAreaWidth and isRegionalAreaCollapsed properties. A sample entry in the menu file resembles Example 14-16.

  • If these properties are not set in the menu for the top-level item node that represents the page, then these default values are used:

    regionalAreaWidth="256"
    isRegionalAreaCollapsed ="false"
    
  • For programmatic control, drag and drop one of the following corresponding methods from the FndUIShellController data control.

    • discloseRegionalArea

    • collapseRegionalArea

    • setRegionalAreaWidth

Two APIs shown in Example 14-17 are exposed as data control methods under FndUIShellController data control.

Note:

  • Declarative support allows the inflexibleHeight property to control the pixel height of the regional area panel. Programmatic support does not have this allowance.

  • Programmatic support allows the forceRefresh property to make it possible to refresh a task without passing in any parameters. Declarative support does not have this allowance.

  • Refreshing a regional area task without disclosing the task is not supported.

  • Multiple regional area tasks are allowed to be disclosed at the same time. A switch to force showing only one task at a time is not provided.

  • Support for persisting any of these settings explicitly altered by the user during a session, across sessions, is not a part of this feature.

Example 14-16 Sample Menu File Entry

<itemNode id="itemNode_SvcCenter"
            label="#{adfBundle['oracle.apps.fnd.applcore.patterns.demo.patterns_demo_menuBundle'].SERVICE_CENTER}"
            action="adfMenu_SvcCenter" focusViewId="/SvcCenter"
            isDynamicTabNavigation="false" regionalAreaWidth="250" isRegionalAreaCollapsed="false">

Example 14-17 APIs Exposed as Data Control Methods Under FndUIShellController

/**
   * Discloses a regional area task.
   *
   * @param taskFlowId Task flow to disclose
   * @param keyList Key list to locate the task flow instance.
   *                This is a semicolon-delimited keys or key-value pair.
   *                For example, "key1;key2=value2". If only the key is specified,
   *                the value is picked up from the parametersList with the same
   *                name as the key.
   * @param parametersList Parameters list for the task flow.
   *                       This is a semicolon-delimited String
   *                       of name-value pairs. For example,
   *                       "param1=value1;param2=value2".
   * @param label Label for the task flow*
   * @param forceRefresh Default false. If false, task flow reinitialization
   * depends on whether some parameters are passed into parametersList, where
   * the presence of parameter values causes reinitializaiton and the absence of
   * parameter values does not. forceRefresh true always causes reinitialization
   * of the task flow regardless of the value for parametersList.
   * @return For internal Contextual Event processing
   */
  public FndMethodParameters discloseRegionalTask(String taskFlowId,
                                                  String keyList,
                                                  String parametersList,
                                                  String label,
                                                  Boolean forceRefresh,
                                                  FndMethodParameters methodParameters)
 
  /**
   * Collapses a regional area task.
   *
   * @param taskFlowId Task flow to collapse
   * @param keyList Key list to locate the task flow instance.
   *                This is a semicolon-delimited list of key-value pairs.
   *                For example, "key1=value1;key2=value2".
   * @return For internal Contextual Event processing
   */
  public FndMethodParameters collapseRegionalTask(String taskFlowId,
                                        String keyList,
                                        FndMethodParameters methodParameters)

14.4.3 How to Control the State of the Contextual Area Splitter

The UI Shell provides the means to control the disclosure state of the contextual area through either declarative or programmatic support.

Declarative support lets you specify the initial state when loading a work area JSPX page. It determines whether the contextual area (as a whole) is collapsed or disclosed.

Programmatic support lets you control the initial or subsequent state of the contextual area within a work area JSPX page.

  • By default, the disclosure state is driven by what is specified declaratively. However, after the initial page load, you can override the declarative default and, for example, render the work area with the contextual area collapsed (overriding the declarative setting of rendering that work area with the contextual area disclosed).

  • Disclosing the collapsed contextual area splitter programmatically in response to a UI action by the user, such as a button click or menu selection.

Samples of Expected Behavior

  • A work area JSPX page loads with the contextual area collapsed or disclosed when the page renders, based on the declarative setting. If the work area is loaded because of a Main Menu invocation, then declarative options always are used for the disclosure state.

  • If a work area loads because of a page navigation from another work area, programmatically set options may override declarative settings.

14.4.3.1 Implement the Contextual Area Splitter

Follow these steps to implement the contextual area splitter:

  1. Extend the contextual-area-task-flow-template task flow template into the page task flow, as shown in Example 14-18.
  2. Specify values for the contextual area splitter position and the collapsed state in the menu for the item node that represents the page using the contextualAreaWidth and contextualAreaCollapsed properties. A sample entry in the menu file will resemble Example 14-19.
  3. If these properties are not set in the menu for the top-level item node that represents the page, then these default values are used:
    contextualAreaWidth="256"
    contextualAreaCollapsed ="false"
    
  4. For programmatic control, drag and drop one of the corresponding methods from the FndUIShellController data control:
    • collapseContextualArea

    • contextualAreaWidthSelection

  5. To set these values when opening a new task, drag and drop the openMainTask method from FndUIShellController data control and pass in the contextualAreaWidth and contextualAreaCollapsed parameters through "methodsParameters > NamedData" as shown in Example 14-20.

    Set the method in the page managed bean to set the contextualAreaWidth and contextualAreaCollapsed values, as shown in Example 14-20.

  6. To set these values using the Navigate API to navigate to a task flow, drag and drop the navigate method from FndUIShellController and pass in the contextualAreaWidth and contextualAreaCollapsed parameters through "methodsParameters > NamedData" as shown in Example 14-21.

    First you need to set the FndMethodParameters; this should be done by adding code similar to this to a managed bean that we will call myBean for this example.

    private methodParameters fndMethodParams;
      ...
      public void myNavParameters()
      {
        FndMethodParameters methodParams = new FndMethodParameters();
        HashMap testHashMap = new HashMap();
        testHashMap.put("contextualAreaWidth", "200");
        testHashMap.put("contextualAreaCollapsed ", "true");
        methodParams.setCustomObject(testHashMap);
        fndMethodParams = methodParams;
      }
    

Example 14-18 Extending the Task Flow Template

<template-reference>
   <document>/oracle/apps/fnd/applcore/patterns/uishell/templates/contextual-area-task-flow-template.xml</document>
   <id>contextual-area-task-flow-template</id>
</template-reference>

Example 14-19 Example of contextualAreaWidth and contextualAreaCollapsed Properties

<itemNode focusViewId="<focus_view_id>" id="<page_id>" label="<page_label>"
     taskType="dynamicMain"
     taskFlowId="/WEB-INF/page2-task-flow-definition.xml#page2-task-flow-definition"
     contextualAreaCollapsed="true"
     contextualAreaWidth="0"/>

Example 14-20 Setting the contextualAreaWidth and contextualAreaCollapsed Values for openMainTask

<methodAction id="openMainTask" RequiresUpdateModel="true"
            Action="invokeMethod" MethodName="openMainTask"
            IsViewObjectMethod="false" DataControl="FndUIShellController"
            InstanceName="FndUIShellController.dataProvider"
            ReturnName="FndUIShellController.methodResults.openMainTask_FndUIShellController_dataProvider_openMainTask_result">
      <NamedData NDName="taskFlowId"
       NDValue="/WEB-INF/page6-task-flow-definition.xml#
                                  page6-task-flow-definition"
            NDType="java.lang.String"/>
      <NamedData NDName="keyList" NDValue="" NDType="java.lang.String"/>
      <NamedData NDName="parametersList" NDType="java.lang.String"/>
      <NamedData NDName="label" NDType="java.lang.String"/>
      <NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
      <NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
      <NamedData NDName="loadDependentFlow" NDType="java.lang.Boolean"/>
      <NamedData NDName="methodParameters"
            NDValue="#{<ManagedBean.Method>}"
            NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.
                                        bean.FndMethodParameters"/>

Example 14-21 Setting the contextualAreaWidth and contextualAreaCollapsed Values for navigate

<methodAction id="navigate" RequiresUpdateModel="true" Action="invokeMethod"
       MethodName="navigate" IsViewObjectMethod="false"
       DataControl="FndUIShellController"
       InstanceName="FndUIShellController.dataProvider"
       ReturnName="FndUIShellController.methodResults.navigate_FndUIShellController_dataProvider_navigate_result">
    <NamedData NDName="viewId" NDType="java.lang.String"/>
    <NamedData NDName="webApp" NDType="java.lang.String"/>
    <NamedData NDName="pageParametersList" NDType="java.lang.String"/>
    <NamedData NDName="navTaskFlowId" NDType="java.lang.String"/>
    <NamedData NDName="navTaskKeyList" NDType="java.lang.String"/>
    <NamedData NDName="navTaskParametersList" NDType="java.lang.String"/>
    <NamedData NDName="navTaskLabel" NDType="java.lang.String"/>
    <NamedData NDName="methodParameters"
        NNDValue="#{myBean.myNavParameters}"
        NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.
                                     bean.FndMethodParameters"/>
</methodAction>

14.4.4 Sizing Regional Area Panels

Multiple regional area panels can be open at the same time, instead of showing only one panel at a time.

Because the desired size of each panel will be different, you can set the pixel height for each of the panels by specifying the inflexibleHeight property in the item node that represents a regional area panel, as shown in Example 14-22.

Example 14-22 Using inflexibleHeight to Set Panel Height

<itemNode id="__ServiceRequest_itemNode__SRSearch"
 focusViewId="/ServiceRequest" label="SR Search"
 taskType="defaultRegional"
 taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRSearch.xml#SRSearch"
 inflexibleHeight="200"/>

14.5 Working with the Global Menu Model

Menu metadata used in Oracle Fusion Applications is divided into global menu data, consisting of the Home page tabs, the Navigator (also known as the Main menu), and the Preferences menu.

The Navigator and Home page tabs contain information from different applications, yet each application must be able to be developed independently. To bring this information together, a Global Menu Model is provided.

Navigation to a page is accomplished by constructing and executing a URL. Matching the application name from the distributed menu metadata to its deployment information will dynamically create the host/port portion of the URL. Other page parameters are held in the existing page-level menu metadata.

The Task Menu, create URL, and navigation API allow other declarative and programmatic access to page navigation. The UI Shell global area also will support a Home page link for page navigations.

Global Menu Model Service

This model:

  • Contains at least the label, the application name, and the viewID

  • Calls the Policy Store (optimized bulk authorization) to get the subset of these menu items to be rendered for that user

  • [Restore post V1] Combines the results from all pillars and renders them

  • Is distributed for multiple pillars

Example of Global Menus

The Global Menu Model presents a cascading appearance, shown in Example 14-27.

Global Menu Behavior

  • Items to which the user does not have access will not be displayed.

  • A category is hidden if there is no child to display.

  • If a menu entry length is greater than 27 characters, ellipses (...)are displayed. The entire entry will be displayed in a tool tip when the pointer hovers over the entry.

  • Parent and children categories will not be split into different columns.

14.5.1 How to Implement a Global Menu

Note:

Before you create menus, you first must create JSF pages using the UI Shell template.

These global menus span JavaEE applications.

  • Navigator: This is the global menu that is displayed in the UI Shell global area.

  • Home Page Menu: The Home page tabs are actually each a JSPX page assembled using menu metadata.

  • Preferences Menu: The User Preferences page has a task list link to all other preferences pages within Oracle Fusion Middleware. This is assembled using menu metadata.

14.5.1.1 Menu Attributes Added by Oracle Fusion Middleware Extensions for Applications (Applications Core)

Table 14-3andTable 14-4list the menu attributes added by Applications Core to the menu XML in addition to what is provided by Oracle ADF.

Table 14-3 <groupNode> Attributes

Attribute Data Type Required Description

labelKey

xsd:string

N

Bundle key used for label; the key will be looked up in the resource bundle specified by the resourceBundle attribute of <menu>.

Table 14-4 <itemNode> Attributes for Global Menus

Attribute Data Type Required Description

webApp

xsd:string

Y

The webApp attribute is used to look up the host and port of the associated work area or Dashboard from the Oracle Fusion Applications Functional Core (ASK) deployment tables. These tables are populated at deployment time through Oracle Fusion Functional Setup Manager tasks.

focusViewId

xsd:string

N

This is the page ID. This can be found by looking in the adfc-config.xml file. The name under each page in the diagram view is the page ID.

securedResourceName

xsd:string

N

The resource name that is used for securing the item node.

applicationStripe

String

N/A

This attribute is used for pages. Check the security of the page against the policies that are located in LDAP. The applicationStripe name must be the same as the stripe name of the LDAP policy store, which is the same as the web.xml application.name attribute.

parametersList

String

N/A

This is a task-level itemNode attribute that is a parameters list to pass in to the task flow to open in the target workspace. This is a semicolon-delimited string of name-value pairs. For example, "param1=value1;param2=value2"

pageParametersList

String

N/A

This is a page-level itemNode attribute that is the parameters list for the page. This is a semicolon-delimited string of name-value pairs. For example, "param1=value1;param2=value2". If the Expression Language expression evaluates to an object, the toString value of that object will be passed as the value of the parameter.

destination

String

N/A

The destination attribute is supported on the item nodes for the Navigator. The destination is necessary only for navigating to an external web site. When it is defined, it takes precedence over all attributes. Example of the menu data:

<itemNode id="itemNode_otn"
destination="http://www.oracle.com/technology/index.html"/>

14.5.1.2 Displaying the Navigator

The Navigator, shown in Figure 14-23, is rendered when the Navigator icon is clicked on the UI Shell.

Figure 14-23 Navigator Example

Described in the surrounding text.

Items in bold are groups, and items in blue are links. So some groups also are links.

14.5.1.3 Implement a Global Menu

Note:

The Navigator is used as the example for how a developer implements a Global Menu, but the steps will be similar for the Preferences and Home menus.

The Navigator metadata may be pointing to target work area pages in various applications. To simplify the runtime behavior, one XML file contains all the menu entries. An Applications Core application will deploy these menus to Oracle Metadata Services (MDS). Each application will read these directly from MDS.

Each application must be configured so that the shared library can read the menus from MDS.

To implement a Global Menu:

  1. Verify that the web.xml file of the application has the correct Java Authentication and Authorization Service (JAAS) filter to enable checking menu security against Oracle Platform Security Services (OPSS), as shown in Example 14-23.

    The application.name parameter, as shown in the example, in the web.xml file is the application family value. The choices are crm, fscm, and hcm. This value is used to create the stripe in LDAP.

  2. Update the weblogic-application.xml file. As shown in Example 14-24, set the application-param that has the param-name jps.policystore.migration to OFF.
  3. In the weblogic-application.xml file, ensure that the application-param that has the param-name jps.policystore.applicationid is set to the correct stripe, as shown in Example 14-25. This is the same as the application.name property of the web.xml file.
  4. Add the following entry in the web.xml file:
    <listener> <listener-class>oracle.apps.fnd.applcore.menu.service.MenuFragmentServiceContextListener</listener-class>
    </listener>
    

Example 14-23 Sample JAAS Filter

<filter>
        <filter-name>JpsFilter</filter-name>
        <filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
        <init-param>
            <param-name>enable.anonymous</param-name>
            <param-value>true</param-value>
        </init-param>
        <init-param>
            <param-name>remove.anonymous.role</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
          <param-name>application.name</param-name>
          <param-value>crm</param-value>
        </init-param>
        <init-param>
          <param-name>oracle.security.jps.jaas.mode</param-name>
          <param-value>subjectOnly</param-value>
        </init-param>
</filter>

Example 14-24 Setting jps.policystore.migration to OFF

<application-param>
    <param-name>jps.policystore.migration</param-name>
    <param-value>OFF</param-value>
</application-param>

Example 14-25 Setting jps.policystore.applicationid to the Correct Stripe

<application-param>
    <param-name>jps.policystore.applicationid</param-name>
    <param-value>crm</param-value>
</application-param>

14.5.2 How to Set Up Global Menu Security

Global menu security depends on applications using a standalone LDAP server.

Note:

Global security only works with standalone WebLogic Server.

ADF Menu Security is enabled by default. If you need to disable menu security, such as for testing, start WebLogic Server after setting the JAVA_OPTIONS environment variable in the setDomainEnv.sh file:

JAVA_OPTIONS = -DAPPLCORE_TEST_SECURED_MENU=N

14.5.2.1 Enforcing User Privileges and Restrictions

Before you enforce user actions, define roles, principals, and actions in the database.

Functional security will always prevent a user from accessing a page or task flow for which the user does not have privilege. To improve the user experience, global menus can be hidden if the user does not have access to that page. There are two different security features for this:

  • The global menus have a securedResourceName attribute, which should be the value of the page resource against which security can be checked. For pages, this is the page definition file.

  • The menus also have a rendered attribute. This can be used to evaluate an Expression Language security expression. If rendered="false" (false being the outcome of the expression), the menu item will be hidden even if the user has access to the page. There are certain times you would want to do this. For instance, consider a person working in HR as a consultant, not an employee. You might want a menu entry for editing employee data under an HR category, without showing an entry under the Employee Self-Service category that also leads to the same page. See Example 14-26.

    The Expression Language expression should never check the page definition. However, you can use the Expression Language expression to check security of a person's role because that is in LDAP.

  • The applicationStripe attribute determines which LDAP stripe is checked for the securedResourceName attribute.

Example 14-26 Expression Language Expression to Evaluate a User's Access Rights

rendered="#{securityContext.userInRole['EMPLOYEE_ROLE']}"

14.5.3 How to Create the Navigator

Menu files will be referenced through MDS. This means they can be located in a table or in a file system directory. Determine where you want this directory to be located. This is where your root_menu.xmlfile and other menu files will be located. For Global menu attributes, see Menu Attributes Added by ().

  1. Create the Navigator.

    Example 14-27 shows a sample Navigator.

  2. Create the application's Navigator files.

    The next files in the menu hierarchy can contain groupNodes that appear as non-clickable categories, itemNodes that are clickable to start a page, or references to more menu files. If itemNodes were included that were not deployed, they will not appear because what was deployed is checked against the deployment tables. Applications Core requires that if a groupNode has no child nodes, which could happen through security enforcement, the groupNode itself will not be rendered.

Example 14-27 Example of a Navigator

<menu xmlns="http://myfaces.apache.org/trinidad/menu">
  <groupNode id="groupNode_my_information" 
    idref="_groupNode_my_information_" 
    label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].MY_INFORMATION}">
      <itemNode id="itemNode_my_information_my_portrait" 
         label="#{bundleVar.MY_PORTRAIT}" focusViewId="/MyPortrait" webApp="HcmCore" 
         securedResourceName="oracle.apps.hcm.people.portrait.ui.page.MyPortraitPageDef" 
    <groupNode id="groupNode_my_information_compensation" 
      idref="_groupNode_my_information_compensation_" 
      label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].COMPENSATION}">
      applicationStripe="hcm"
    </groupNode>
    <groupNode id="groupNode_my_information_career" 
      idref="_groupNode_my_information_career_" 
      label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].CAREER}">
         <itemNode id="itemNode_my_information_goals" 
            label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].GOALS}" 
            focusViewId="/ManageGoalsWorkArea" webApp="HcmTalent" 
            securedResourceName="oracle.apps.hcm.goals.core.publicUi.page.ManageGoalsWorkAreaPageDef"/>
              <itemNode id="itemNode_my_information_performance_management" 
                 label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PERFORMANCE}" 
        applicationStripe="hcm"
                 focusViewId="/PerformanceWorkArea" webApp="HcmTalent" 
                 securedResourceName="oracle.apps.hcm.performance.documents.publicUi.page.PerformanceWorkAreaPageDef"/>
    </groupNode>
    <groupNode id="groupNode_my_information_procurement" 
      idref="_groupNode_my_information_procurement_" 
      label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PROCUREMENT}">
         <itemNode id="itemNode_my_information_purchase_requisitions" 
            label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PURCHASE_REQUISITIONS}" 
            focusViewId="/PrcPorCreateReqWorkarea" webApp="Procurement" 
            securedResourceName="oracle.apps.prc.por.createReq.publicUi.page.PrcPorCreateReqWorkareaPageDef" applicationStripe="hcm"/>
               <itemNode id="itemNode_my_information_self_service_receipts" 
                   label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].RECEIPTS}" 
                   applicationStripe="hcm"
                   focusViewId="/RcvSelfServWorkarea" webApp="Logistics" 
                   securedResourceName="oracle.apps.scm.receiving.selfService.workarea.ui.page.RcvSelfServWorkareaPageDef"/>
       applicationStripe="hcm"/>
    </groupNode>
  </groupNode>
</menu>

14.5.3.1 Render the Navigator as Dropdown Buttons

There are situations, particularly with simpler applications, when the default enterprise-level menu structure is not suitable. In these cases, you may want to display the Navigator as a series of dropdown buttons.

To switch the UI Shell rendering so the Navigator renders as dropdown buttons in a horizontal row, set the isSelfService attribute to "true" on the .jspx page that extends the UI Shell template. That is, inside the <af:pageTemplate> tag, add the following:

<f:attribute name="isSelfService" value="true"/>

14.6 Using the Settings and Actions Menu

The Settings and Actions menu, shown in Figure 14-24, is accessed by clicking the name of the logged-in user on the right edge of the global area. It consolidates several menus that previously were stand-alone.

Figure 14-24 Settings and Actions Menu

Described in the surrounding text.
  • Sign In / Sign Out

    Note:

    When signing in, users always are directed to the application's home page.

    This list provides two possible scenarios during runtime:

    1. The application is not secured. In this case, there is no concept of the user being logged in (authenticated) or logged out (not authenticated).

    • The commandLink displays the text Sign In and is disabled.

    2. The application is secured with ADF Security.

    If the user is logged in:

    • The commandLink displays the text Sign Out and is enabled.

    • If Oracle WebLogic Server is configured to authenticate with Oracle Internet Directory LDAP, the user name is the display name of the authenticated user principal. The display name is indexed by a general end user preference. See How to Implement End User Preferences.

    If the user is logged out, the only way for an unauthenticated user to view a page is if a page either has no databinding (no pagedef) or has databinding but is granted to the anonymous role:

    • The commandLink displays the text Sign In and is enabled.

    When the Sign Out link is clicked, the page is redirected to the application's default home page if it is accessible. There are cases in which a default home page is not available to the current user. In such cases, the user application should implement the setLogoutUrl() API that is included in the oracle.apps.fnd.applcore.common.ApplSession class of the Oracle Fusion Middleware extensions for Applications Core API. This API is implemented as:

    public void setLogoutURL(String pLogoutURL);
    

    The UI Shell's Sign Out logic will get the logout URL from ApplSession using the getLogoutURL() API and redirect to it. This API is implemented as:

    public String getLogoutURL();
    

    If the logout URL was not set in ApplSession, the application will be redirected to the default home page.

    On clicking the Sign Out link, the user session is cleared from the cookie and terminated. If the home page is secured, the login prompt will first appear. If the home page is not secured, the page will appear and the Sign In link will be enabled.

  • Switch To / Impersonation

    The Switch To menu is available only if the user has the security privilege to impersonate others and has been given access to impersonate at least one other user. When clicked, the menu displays the name of the logged-in user and any user names he or she can impersonate.

    Figure 14-25 Switch To Menu

    Described in the surrounding text.

    See How to Set Up a Proxy User (Session Impersonation).

14.6.1 How to Use the Personalization Options

The options in the Personalization section of the Settings and Actions menu let you set your preferences, edit the current page, and reset the content and layout.

The Set Preferences option only appears if you have the ApplSession filter and mapping set up. See Configuring Your Project to Use Application User Sessions.

Set Preferences

You create the actual Preferences dialog, such as shown in Figure 14-28. See How to Implement End User Preferences for the details of how to implement the Preferences menu.

Edit Current Page

This option is displayed only if the displayed page has been marked as able to be user-edited (if the isPersonalizableInComposer attribute in af:pageTemplate is set to true). Selecting this option will start the editing feature and the page will resemble Figure 14-26. Click Close to return to the page. Click Customization Manager to change the displayed page in Oracle Composer. For more information about the Customization Manager, see the Oracle Fusion Middleware Developing WebCenter Portal Assets and Custom Components with Oracle JDeveloper guide. Note that changes are for just this user and therefore are called personalization. See Creating Customizable Applications .

Figure 14-26 Edit Current Page Display

Described in the surrounding text.

Reset to Default Content and Layout

Select this option to discard any personalization changes and return to the default settings. Note that resetting layout and content is for that page. In particular, if any task flows are personalized on that page using Oracle Composer, they are not reset by this menu item.

When you select this option, this confirmation dialog is displayed:

Figure 14-27 Confirm Reset Content and Layout

Described in the surrounding text.

14.6.2 How to Implement End User Preferences

The Set Preferences option provides easy access to setting preferences for the current application, general user preferences, or for any other application preference in Oracle Fusion Middleware. For more information about this Global menu, see Working with the Global Menu Model.

Preferences are pages that can set system wide settings that applications can access. There are general preferences that affect all applications, and there can be application-specific preferences. General preferences include language, date format, and currency. General preferences are stored in LDAP so they can be accessed from any application. Application preferences are usually stored in the applications on database tables, but they can be stored in LDAP also.

14.6.2.1 Using the Set Preferences Option

Click Set Preferences to open a work area that shows the preferences related to the currently displayed page.

Links in the left hand side will allow navigation to any Preferences work area page within the entire Oracle Fusion product. This page will be rendered using Applications Core menu federation abilities. As the developer, you will own the menu files.

If an application is not installed, or the user does not have access, the entry in the task list menu should not appear. If a user does not have access to a particular setting within a page, you must use the rendered property with a security expression behind it.

For each application, there should be a preferences page. The preferences page uses the same path of the current application, but it uses a page name of preferences.jspx.

If no associated preferences page exists, a default General Preferences page will be shown. This page shows global Applications Core most-used preferences.

If there are several preference pages associated with an application, such as a Common Setting page and more specific pages, only one preferences page as a target from the global preferences link can be defined per application. (There will be a default name for the target focusViewID of the preferences page for an application.) In the preferences work area, other links are available from the task list to more specific pages or task flows. (Links in the task list can contain other focusViewIDs that belong to the same application as the default preference page.)

When the first application is deployed, it will become the location of the General Preferences page.

Several pages of an application can all point to the same preferences page.

More than one application cannot point to the same preferences page. This implies that each application can have its own preferences page, and if two applications want to share a common preferences page, they can, but it can be navigated to only from the task list. Therefore, from the Preferences link, the user always sees the more specific preferences page of that application.

14.6.2.2 Using the Preferences Work Area Page

A preferences page will be like any other work area page. Preference values are not supported in integrated Oracle Weblogic Server LDAP, only an external LDAP is supported. The task list will be loaded as a defaultRegional task flow and the main area will be a defaultMain task flow.

Work Area Title

Each preferences page should display a title similar to {Category_name:Page_name}. This can be done though an Expression Language expression and will not be created automatically from the framework.

The name that appears in the task list can be different from the page title. This is allowed because the task list name is generated from the task list preference distributed menu metadata, while the page title will be from the local page-level menu metadata.

Tasklist and Navigation Pane

Each page needs its Application Menu metadata to specify that it wants the Preferences task list menu in the defaultRegional area as well as in the defaultMain task flow.

This menu can be a two-level menu having categories with links under each category.

Task List Federation

The task list will be a task flow that will contain links to all preference pages throughout Oracle Fusion Middleware.

Each application will provide the preferences menu files that contain task list links to preferences pages delivered by that application. The preferences task list should follow the Navigator architecture recommendations where it uses sharedNode references to bring in menus from each application so they can be patched independently. Applications Core will automatically federate the menu metadata so the task list that is rendered will contain all the entries from all applications (filtered by security).

Individual menu files will have versions like other distributed menu files, so any application can apply a patch and the new menu will take precedence over an older version when federated.

Task List Can Link Only to Full Pages (Not to Specific Task Flows)

The task list will not start task flows dynamically, but will load a Preferences workarea page. This is because the task list menu must be federated and only page-level entries are allowed in a federated menu.

No-Tabs Mode

The Preferences page should use a no-tabs mode. This is a standard, not controlled through any code. You can use tabs if all task flows are defaultMain. See Supporting No-Tab Work Areas for more information.

Task List Security

The task list will be filtered by functional page-level security for that user. If all entries in a category are restricted, then the category should not appear either.

Preferences Settings

Settings will be a view activity in a task flow. It will follow other user experience standards so it should be built using an Applications Panel. This means the action buttons will appear at the top.

Different preferences pages can change the same backend setting, depending upon applications design. If this is needed, it should be stored in a common area, such as LDAP, or be in the General Preferences page.

14.6.2.3 Deploying Preferences Pages and Designing General Preferences Content

Application preferences pages are deployed with the corresponding product pages.

The design should be similar to that shown in Figure 14-28.

Figure 14-28 General Preferences Example

Described in the surrounding text.

14.6.2.4 Configure and Implement End-User Preferences

After the WebLogic Server console is configured, follow these steps to create an Oracle Fusion web application that uses UI Shell pages:

  1. Create a UI Shell page that is used solely for the user preferences, such as PreferencesUI.jspx.
  2. Set the isDynamicTabNavigation property to false for the PreferencesUI page entry in the menu.
  3. Add the following task flow as a default regional area under the preferences page entry: "/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesFlow.xml#GeneralPreferencesFlow"

    The final menu entries for the page will appear similar to those shown in Example 14-28.

    The results of this example should display the basic Preferences menu entries in the default regional area that can be opened to display subflows for each preferences subtask (for instance, Accessibility and Appearance).

Example 14-28 Sample General Preferences Menu Entries

<itemNode id="itemNode_untitled2" label="Preferences"
          action="adfMenu_PreferencesUI" focusViewId="/PreferencesUI"
          isDynamicTabNavigation="false" webApp="Demo">
     <itemNode id="def1" focusViewId="/PreferencesUI" label="General Preferences"
              taskType="defaultRegional"
              taskFlowId= "/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesFlow.xml#GeneralPreferencesFlow"/>
</itemNode>
14.6.2.4.1 How to Use the Preferences Menu Model

The General Preferences task flow that is exposed also renders the Preferences Menu Model links by using a call to the Menu Service API.

The Preferences menu will be part of a central Utility application (menu web service) that will be deployed in the server. As a developer, you maintain the Preferences menu.

On any UI Shell page, the global area contains a Personalization menu that contains a Set Preferences link. This link will redirect the user to an application-specific Preferences page, depending upon the entry in the menu data.

Example 14-29 shows sample Preferences menu data.

In the example menu XML file, each parent item node represents a Preferences UIShell page. Its child nodes refer to the application-specific task flow in which the Preferences page exists.

For example, the first itemNode entry refers to the preferencesA page that is part of the FND webApp. The Service Flow child node is a task flow that belongs to the FND webApp.

For each parent itemNode, there is an attribute called prefForApps that contains a list of webApp names. This means that the itemNode is a common preferences page for those listed webApps.

For example, the Preferences page is common for two webApps -- gl and hr. This essentially means that all the Dashboards and work area UI Shell pages in the gl and hr webApps will be redirected to this preferencesA page, which is in webApp FND, when the Set Preferences link is clicked.

All the task flows under each preferences page itemNode will be displayed in the General Preferences task flow as navigation links. Therefore, all preferences pages will have access to these task flows.

Example 14-29 Example Preferences Menu Data

<?xml version="1.0" encoding="UTF-8" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu" version="1">
  <itemNode id="preferences_node_a" label="Preferences Page A"
            action="preferences_node_a" focusViewId="/preferencesA"
            webApp="fnd" prefForApps="gl, hr" >
    <itemNode id="Flow 1" label="Service Flow"
              focusViewId="/preferencesA"  taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/ServiceFlow.xml#ServiceFlow"
              parametersList="id=userName" />
  </itemNode>
  <itemNode id="preferences_node_b" label="Preferences Page B"
            action="preferences_node_b" focusViewId="/preferencesB"
            webApp="fnd" prefForApps="fn" >
     <itemNode id="Flow 2" label="Request Flow"
              focusViewId="/preferencesB"  taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/RequestFlow.xml#RequestFlow"
              parametersList="id=userName" />
  </itemNode>
  <itemNode id="preferences_node_d" label="Preferences Page D"
            action="preferences_node_d" focusViewId="/PreferencesUI"
            webApp="Demo" prefForApps="Demo"
     <itemNode id="Flow 2" label="Request Flow"
              focusViewId="/preferencesB"  taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/AcceptanceFlow.xml#AcceptanceFlow"
              />
  </itemNode>
</menu>
14.6.2.4.2 How to Configure User Session and ADF Security

To test the general preferences task flows, configure user session and ADF Security for the test application. See Implementing Application User Sessions.

When configuring ADF Security, there is no need to define users, because you already are using an Oracle Internet Directory store that will authenticate the users existing in the policy store.

14.6.2.4.3 How to Retrieve Preference Values and Check Accessibility Mode by Using an Expression Language Expression

See Working with Localization Formatting .

A use case exists where the UI must use an Expression Language expression to check whether the accessibility mode is set to screenReader to render screen reader-friendly components in screenReader mode. The recommended method to do this uses #{requestContext.accessibilityMode} and is documented in the How to Configure Accessibility Support in trinidad-config.xml section of the Fusion Middleware Developing Web User Interfaces with Oracle ADF Faces guide.

14.6.2.4.4 How to Implement the Password Management Page

The Password link on the General Preferences page will point to the Password Management page from the Oracle Identity Management administration application, as shown here:

Figure 14-29 OIM Password Management

OIM Password Management

For the Password link to redirect to the pwdmgmt.jspx page, the deployment information of the current application and the Oracle Identity Management administration application must be populated correctly in the Oracle Fusion Applications Functional Core (ASK) tables. You may need to talk to the person or team responsible for maintaining this information.

14.6.2.5 Using the Most Common Preferences

The Preferences most end users want to set are Language, Accessibility, and Regional. This section discusses how to configure these Preferences and what the default rules are, such as what happens if you do not set the Language Preference.

See Working with Localization Formatting for more information about localization of Preferences.

14.6.2.5.1 How to Configure the Language Preference

When a session is created, it will use the language provided in the ORA_COMMON_PREFS cookie if it is set to a valid language. Inside the cookie, the fusionapps_language attribute is used to determine the language. There also is a local attribute that is for non-Oracle Fusion applications so that Oracle Fusion applications have their own attribute in the cookie and allowing other applications to keep their own language preference. Oracle Identity Management knows which to use based on a system value oracle.fusion.appsmode that is set at provisioning time.

If it is not a valid language or if the cookie does not exist, the browser language is used.

If for some reason the browser language is not valid, the seeded FND_LANGUAGE profile option is checked to determine the default language, which defaults to American English. If accessing a protected page, the login screen appears. This login screen may allow the user to select a language for the session. If selected, this will override the language. If the user does not select anything on login and if the user has a language preference previously saved, this will override the language if it is an installed language. If saved, it would be held in the LDAP settings for the Oracle Fusion applications Language setting in the orclFALanguage attribute of the orclIDXPerson object. This is controlled by Oracle Identity Management.

Users can set the Language preference by selecting the Set Preferences link from the Personalization menu in the global area. The Language option will look similar to Figure 14-30.

Figure 14-30 Setting the User Preference Language Option

Described in the surrounding text.
14.6.2.5.2 How to Configure the Accessibility Preference

Oracle Fusion applications follow the Apache Trinidad standards for Accessibility.

Users can set the Accessibility preference by selecting the Set Preferences link from the Personalization menu in the global area. The Accessibility option will look similar to Figure 14-31.

Figure 14-31 Setting the Accessibility User Preference Options

Described in the surrounding text.
14.6.2.5.3 How to Configure the Regional Preferences

The default Regional settings are based on the selected Language setting unless the Regional setting is saved explicitly. That is, no matter how the current language is derived, whether it is from login, the browser or LDAP, if the Regional settings are not yet set, they will default from the language. But if the user sets the Regional settings and then sets the Language setting, the Regional settings will not be changed.

Users can set the Regional preferences by selecting the Set Preferences link from the Personalization menu in the global area. The Regional options will look similar to Figure 14-32.

Figure 14-32 Setting the Regional User Preferences Options

Described in the surrounding text.

14.6.3 How to Use the Administration Options

The Administration options in the Settings and Actions menu are displayed only if the logged-in user has the appropriate privileges. See Securing the Administration Menu.

Customize [name_of_page] Pages...

Select this option to customize the current page for multiple users using the customization layer picker dialog.

For information about customization, see Creating Customizable Applications .

Customize Global Page Template

Select this option to open the page in composer mode. All the global items can be selected so you can customize them. Customization is done at the site layer so it will apply to all pages, not just the one you are on. (When you use Customize [name of page] Pages, all the content except the global content is available for customization.)

Manage Customizations...

Select this option to start the Customization Manager.

For information about customization, see Creating Customizable Applications . For more information about the Customization Manager, see the Extending Runtime Editing Capabilities Using Composer" section and the "Introduction to Composer" section of Developing WebCenter Portal Assets and Custom Components with Oracle JDeveloper.

For information about defining and configuring namespaces when promoting a page fragment to a label, see "Updating Your Application's adf-config.xml File" in the "Performing Composer-Specific MDS Configurations" section of Developing WebCenter Portal Assets and Custom Components with Oracle JDeveloper.

Manage Sandboxes...

Select this option to manage sandboxes on your system.

The Sandbox is built on top of the standard Sandbox feature from Oracle Metadata Service.

Setup and Maintenance...

Select this option to start the Oracle Fusion Functional Setup Manager application. See the Oracle Fusion Functional Setup Manager User’s Guide.

Highlight Flexfields

No separate implementation is required. This option is available to any user who has the permission to view the Administration menu.

Select this option to highlight the Descriptive Flexfields (DFF), Key Flexfields (KFF) and Extensible Flexfields (EFF) on the runtime page.

When this mode is on, the page displays an information icon by each DFF, KFF and EFF. This will be displayed whether any Flexfield segments have been configured.

Hovering over the icon shows the Flexfield details. Administrators can note the DFF, KFF or EFF code so they can search for it in the Manage Descriptive Flexfields, Manage Key Flexfields, and Manage Extensible Flexfields setup tasks in Oracle Fusion Functional Setup Manager.

The option changes to Unhighlight Flexfields so that administrators can return to the normal view of the page.

For more information about Flexfields, see Getting Started with Flexfields.

14.6.3.1 Securing the Administration Menu

If you need the Administration link, include the privilege and the permission in the JAZN file as defined in Example 14-30. All administrator roles must inherit the Applications Core "Administration Link View Duty" duty role. This duty role gives access to the "View Administration Link" privilege.

Example 14-30 Required Privilege and Permission in JAZN File

<app-role>
  <name>FND_ADMINISTRATION_LINK_VIEW_DUTY</name>
  <display-name>Administration Link View Duty</display-name>
  <description>Provides access to the Administration Link on the UI Shell</description>
  <guid>EA1D0BF0BC096F11B18BDEBD5F4BDB48</guid>
  <class>oracle.security.jps.service.policystore.ApplicationRole
  </class>
 <members>
   <member>
     <class>oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl
     </class>
     <name>FND_APPLICATION_DEVELOPER_JOB</name>
     </member>
   <member>
     <class>oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl
     </class>
     <name>FND_APPLICATION_ADMINISTRATOR_JOB</name>
   </member>
 </members>
</app-role>
 
Privilege
 
<app-role>
  <name>FND_VIEW_ADMIN_LINK_PRIV</name>
  <display-name>View Administration Link</display-name>
  <description>Privilege to view administration link in UI shell. This privilege is available from Roles(s): Supply Chain Application Administrator,Cost Accountant,Application Implementation Consultant,Application Developer,Application Administrator</description>
  <guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
  <class>oracle.security.jps.service.policystore.ApplicationRole</class>
 <members>
   <member>
     <class>oracle.security.jps.service.policystore.ApplicationRole</class>
     <name>FND_ADMINISTRATION_LINK_VIEW_DUTY</name>
     <guid>EA1D0BF0BC096F11B18BDEBD5F4BDB48</guid>
  </member>
 </members>
</app-role>
 
Permission and Grant to be included in JAZN file
 
<grant>
 <grantee>
  <principals>
   <principal>
     <class>oracle.security.jps.service.policystore.ApplicationRole</class>
     <name>FND_VIEW_ADMIN_LINK_PRIV</name>
     <guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
   </principal>
  </principals>
 </grantee>
 <permissions>
   <permission>
     <class>oracle.security.jps.ResourcePermission</class>
     <name>resourceType=FNDResourceType,resourceName=FND_Administration_Menu</name>
     <actions>launch</actions>
   </permission>
 </permissions>
</grant>

14.6.4 How to Use the Troubleshooting Options

The Troubleshooting options provide user access to the standard help system and to troubleshooting and diagnostic tools.

Run Diagnostics Tests

Selecting this Settings and Actions menu Troubleshooting option opens the Diagnostics Dashboard user interface in a new window. For more information, see "Understanding Oracle Fusion Applications Incidents and Log Files" in the Administrator's Guide.

Troubleshooting Options

Select this option to display the Options dialog, as shown in Figure 14-33.

Figure 14-33 Troubleshooting Options Dialog

Described in the surrounding text.
  • Enable all: Select this option to enable all other options on the dialog. When Enable all is selected, removing the selection from any of the other check boxes will deselect Enable all.

    Applications logging, severity level and modules are stored as user-level profile options in profile tables. The corresponding profile option names are AFLOG_ENABLED, AFLOG_LEVEL, and AFLOG_MODULE. See "Configuring Settings for Log Files and Incidents" in Administrator's Guide for information.

    Because applications logging, severity level, and modules are profiles, when users click Save and Close, user-specific profile values will be inserted into the profiles. If users decide to revert the setting to the default site profile, they must use the Functional Setup Manager to remove their own profile.

    After making changes to any one of the options for applications logging, severity level, or modules, the user must log out of the Oracle Fusion application, close the browser session, and log back in for the new options to take effect. These logging profiles are cached in the user session and initialized when a user logs into an Oracle Fusion application.

  • Database trace: This option enables the SQL trace feature for all database connections used by the current user session.

    For SQL trace, the trace file will have the FND session ID appended to the end. For example, mysid_ora_4473_881497BF7770BEEEE040E40A0D807BB1.trc.

    The trace file can be found on the database host in the directory specified by the user_dump_dest init.ora parameter.

    • Capture bind variables:

      Select this option to enable the SQL trace option to also capture bind variables.

    • Capture wait events:

      Select this option to enable the SQL trace option to also capture wait events.

  • PL/SQL profiler: This option enables the PL/SQL hierarchical profiler for all the connections used by the current user session.

    For the PL/SQL profiler, the output will be in the directory defined by APPLLOG_DIR. The exact path for APPLLOG_DIR can be found on the database host by using the SQL statement:

    select directory_name, directory_path from dba_directories where directory_name like 'APPLLOG%'

    The file names would be PLS_<some number>_<FND session id>_<timestamp>.txt, such as PLS_49774696_88740EC94E3AAD2CE040E40A0D8036D8_100607104716.txt.

    To process the collected PL/SQL profiles and view results, run the plshprof command under the $ORACLE_HOME/bin directory.

  • Applications logging: Applications logging is selected by default. Disabling logging will warn users that no logging will take place.

    • Severity Level:

      Use this option to set what types of information to log, and how much of it to log.

      For more information, see "Understanding Oracle Fusion Applications Incidents and Log Files" in the Administrator's Guide.

    • Modules:

      This is the module filter for logging. This is a comma-separated list of modules to be logged. The percent sign (%) is used as a wildcard. For example, % or %financial%. The percent sign (%) is the default value and if no other value is specified, then it means everything will be logged.

      When a customer logs a service request with Oracle, the support person will help the customer enter the values necessary to filter the diagnostic logs for the needed information.

Tracing Options

This feature is designed for customers to collect diagnostic data to send back to Oracle for analysis.

When there is a performance issue that is reproducible, the tracing feature streamlines the data collection process by allowing the end user who is experiencing the problem to record a trace that will contain the necessary diagnostic information.

Before the user can access this function, the security administrator needs to assign the Business Flow Troubleshooting role to the user. On each managed server, a maximum of three users can be tracing at a time. By requiring the troubleshooting role to be granted, an administrator can grant access to users who actually need to trace, and revoke access when the issue is resolved.

To grant the role, the administrator will follow these basic steps:

  • Log in to Oracle Identity Management.

  • Click Administration on top right.

  • Search for and select the target user.

  • Click the Roles tab.

  • Click Assign.

  • Search for the display name Business Flow Troubleshooting.

  • Select the role in the search results and click Add.

To run the trace, the user will follow these steps:

  • Start the trace.

    The trace should be started only after navigating to the target managed server where the issue is happening. Note that the tracing feature only works within a single managed server; it will not span a flow involving more than one application (unless both applications happen to be on the same managed server).

    • Navigate to the target application.

    • Right before starting the problematic flow, select Troubleshooting > Tracing Options. The dialog shown in Figure 14-34 is displayed.

      Figure 14-34 Initial Tracing Options Dialog

      Described in the surrounding text.
    • Depending on the type of issue, select Performance or Functional trace type. The selection affects what diagnostic information is captured.

      In general, the user would select Performance when the problem is an application running too slowly, and Functional when the application does not behave as expected or when the information displayed is incorrect.

    • Trace Options defaults are based on the Trace type selection. Click Advanced Options to see what trace settings are enabled. For fine-grained control, select different trace options, as shown in Figure 14-35.

      Note:

      The user should accept the default settings or contact Oracle support for additional instructions.

      Figure 14-35 Advanced Tracing Options Dialog

      Described in the surrounding text.
    • Click Start Trace. A confirmation dialog, similar to Figure 14-36, with the trace ID will be displayed. Make a note of the trace ID.

      Figure 14-36 Trace Start Confirmation

      Described in the surrounding text.

      Subsequent clicks will be traced. The trace will run for a maximum of 30 minutes. If there are more than three simultaneous tracing sessions, an error message will be displayed.

      If the Applications Trace option is selected (enabled by default for the Performance trace type), the server also needs to have at least 200MB of free memory in the JVM heap.

  • Run the flow to reproduce the issue.

  • Stop the trace.

    • After executing the steps that have issues, select Troubleshooting > Tracing Options again. When tracing is active, only Stop Trace and Cancel will be active, as shown in Figure 14-37.

      Figure 14-37 Stop Trace

      Described in surrounding text.
    • Click Stop Trace. Figure 14-38 shows the two options to control whether to create an incident.

      Figure 14-38 Select Stop Trace Option

      Described in surrounding text.

      If the issue is reproduced, select Stop trace and create incident.

      Click OK. A confirmation will be displayed with the incident number. Note the incident number in addition to the trace ID captured earlier.

      The collected diagnostic information will be captured in an incident with the given incident number. See the "Troubleshooting Oracle Fusion Applications Using Incidents, Logs, QuickTrace, and Diagnostic Tests" chapter in the Administrator's Guide.

      If Stop trace and do not create incident is selected, then the confirmation will not have an incident number.

User Productivity Kit

The User Productivity Kit (UPK) is an optional, separately-purchased application that provides a content development, deployment, and maintenance platform for increasing project, program, and user productivity. The menu option will be available if Oracle UPK has been purchased, installed and configured.

This context-param entry must be added to the web.xml file:

<context-param>
  <description>This parameter notifies ADF Faces that the ExecutionContextProvider service provider is enabled.
    When enabled, this will start monitoring and aggregating user activity information for the client initiated
    requests. By default this param is not set or is false.
  </description>
  <param-name>oracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDER</param-name>
  <param-value>true</param-value>
</context-param>
For recording, it may be necessary to turn on automation if all client components need to be sent down. The following parameter should be present in the application web.xml:
 
<context-param>
  <description>
      This parameter notifies ADF Faces that test automation is being used.
      When enabled, this will cause the ids of components with testId
      attributes to be set to the value of the testId and the client component
      attribute of the component to be forced to true.
 
      TestId attribute is now deprecated; use the 'id' attribute instead.
  </description>
  <param-name>oracle.adf.view.rich.automation.ENABLED</param-name>
  <param-value>true</param-value>
</context-param>

Also, "upk" must be provisioned by the System Administrator. That is, an entry with DEPLOYED_MODULE_NAME = "upk" must be added in the ASK deployment tables. These tables are populated at deployment time through Oracle Fusion Functional Setup Manager tasks. Without the entry, the menu item "User Productivity Kit ..." will not be shown in the Help menu.

Applications Help

Select this option to open the help system in a separate window.

Privacy Statement

Select this option to display the privacy statement, which will appear in a new browser window. This option is always inactive until it is implemented. To set up the privacy statement, enter a fully-qualified URL in the PRIVACY_PAGE profile option.

Open the Setup and Maintenance work area, and use the Manage Applications Core Administrator Profile Values task to find the Privacy Statement URL profile option. In the Profile Value column, enter the full URL of the web page that contains the privacy content you want the menu item to link to.

Also see About Setting and Accessing Profile Values.

About Applications

Select this option to display the Oracle copyright statement and information about the application.

About This Page

Select this option to display version information for Oracle Fusion Applications, including details of the Oracle Application Development Framework, Oracle Metadata Services, the database, and the Applications Core. This makes it easier to know to which product the current page belongs and makes it easy to log a Service Request or find a patch for the correct product.

Note: This information is visible only to users with specific privileges. The privileges are controlled by the profile option FND_VIEW_VERSION_INFORMATION_PRIV, which an Administrator can enable or disable.

14.6.5 How to Set Up a Proxy User (Session Impersonation)

Session impersonation is a feature that enables a user (the impersonatee) to allow other users (impersonators) to log in and act as himself without sharing his password to the other user. The impersonator can login as himself and switch to the impersonatee. Once switched, he can access all the roles of the impersonatee. This switch will be valid only for the current session; it must be done again in the next login. The impersonator can switch back to himself at any time.

Note:

Only users who have the FND_IMPERSONATE_USER_PRIV privilege will be available for the impersonatee to grant impersonation. The administrator must associate this privilege to the users who can serve as proxy users and can revoke it at any time. The grant is stored in LDAP as part of the impersonatee user attribute, orclImpersonationGrantee.

To set up the impersonation, follow these steps.

  1. Log in as user Impersonatee (the user who will be impersonated by an authorized user).
  2. Click your user name to open the Settings and Actions menu.
  3. Click Set Preferences...
  4. In the Tasks list, select Proxies.

    Figure 14-39 Selecting the Proxies Task

    Described in the surrounding text.

    The Proxies pane is displayed.

    Figure 14-40 Proxies Pane

    Described in the surrounding text.
  5. In the Proxies pane, click the Create icon to open the Select and Add: People dialog.

    Figure 14-41 Initial Select and Add: People Dialog

    Described in the surrounding text.
  6. Enter known data in any of the fields and click Search. This example uses the User Name field and the APPLICATION_DEVELOPER name.

    Figure 14-42 Completing the Select and Add Dialog

    Described in the surrounding text.
  7. Highlight the name you want to use.
  8. Click OK. The information is entered on the Proxies pane, as shown here.

    Figure 14-43 Proxy Name Entered In Proxies Pane

    Described in the surrounding text.
  9. Enter the necessary dates in the Start Date and End Date fields and click Save.

    Now Impersonatee has granted proxy access to APPLICATION_DEVELOPER.

    APPLICATION_DEVELOPER can impersonate Impersonatee and perform transactions on his or her behalf.

  10. Open the Settings and Actions menu and click Sign Out.
  11. Sign back in as APPLICATION_DEVELOPER using the password for that user ID.
  12. Click Switch To. The menu shows the names of the logged-in user and the users he or she can impersonate.

    Figure 14-44 Switch To Menu

    Described in the surrounding text.
  13. Select the name of the Impersonatee. You will be asked to confirm the switch.

    Figure 14-45 Confirming the Impersonation

    Described in the surrounding text.

    The name of the impersonatee now is displayed with an icon indicating that the user is being impersonated.

    Figure 14-46 Icon Showing User Is Being Impersonated

    Described in the surrounding text.