14 Implementing the UI Shell

14.1.2.1 Global Area Standard Links

The Global Area incorporates a number of built-in indicators and links.

• Home

  Click this link to return to the defined Home page. See Section 14.18, "Implementing the Oracle Fusion Home Page UI."

• Navigator

  The Navigator menu, shown in Figure 14-18, is rendered when the Navigator link is clicked on the UI Shell. See Section 14.5.1.2, "Displaying the Navigator Menu."

• Recent Items

  Recent Items tracks a list of the last 20 task flows visited by a user. See Section 14.11, "Implementing Recent Items."

• Favorites

  Add to Favorites takes the most recent Recent Item (see Section 14.11, "Implementing Recent Items") and persists it into the Favorites list.

• Tags

  Tagging is a service that allows users to add tags to arbitrary resources in Oracle Fusion Applications so they may collectively contribute to the overall taxonomy and discovery of resources others have visited. See Section 14.10, "Implementing Tagging Integration."

• Watchlist

  Watchlist is a user-accessible UI that provides a summary of items the user can track with drilldown shortcuts. See Section 14.12, "Implementing the Watchlist."

• Group Spaces

  Group Spaces bundle all the collaboration tools and provide an easy way for users to create their own ad hoc collaborative groups around a project or business artifact. See Section 14.13, "Implementing Group Spaces."

• Personalization

  The Personalization menu options let you set your preferences, edit the current page, and reset the content and layout. See Section 14.6, "Using the Personalization Menu."

• Accessibility

  The Accessibility link appears on pages that can be accessed without logging in. It will allow users to set their accessibility preferences because the Personalization menu, which includes preferences, is hidden for anonymous users.

• Administration

  The Administration menu options allow you to customize the current page at a multi-user level, allows you to manage sandboxes, and allows you access to the setup applications. See Section 14.8, "Using the Administration Menu."

• Help

  The Help menu options let you control trace levels, run diagnostics, and provide an About page that lists information about the application. See Section 14.9, "Using the Help Menu."

• Sign In / Sign Out

  There are two possible scenarios during run-time:

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

    • There is no user name displayed next to the commandLink.

  • The application is secured with ADF Security.

    If the user is Logged In:

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

    • The logged-in user name is displayed next to the Sign Out link.

    • If Oracle WebLogic Server is configured to authenticate with Oracle Internet Directory (OID) LDAP, the user name is the display name of the authenticated user principal.

    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.

    • No user name is displayed next to the Sign In link.

When the Sign Out link is clicked, the page is always redirected back to the current page. On clicking the Sign Out link, the user session is cleared from the cookie and terminated. If the page was secured, the user is logged out of ADF/SSO Authentication and redirected to a login page. If the page was not secured, or if the anonymous role has been granted view permission to the current page, the same page will be displayed with the Sign In link and a blank username.

14.2.1.1 Working with the Applications Menu Model

Page and task flow information are local to a particular JDeveloper application or project and are exposed using the Applications Menu Model.

An Applications Menu is related to a local JSPX file and includes the tasks list, defaultMain, and defaultRegional. A menu is created for each J2EE application.

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

You need to 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 prior to 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}"/>

where:

• Id needs to 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.

• 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 shown above 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 Section 14.19, "Using the Single Object Context Workarea."

14.2.3.2 Grouping 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 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 Section 14.2.3.4, "Supporting No-Tab Workareas"), 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.

   To run the page, right-click the JSPX page file in the Projects tree view and choose Run.

   Check 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. It can 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:

<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 Supporting No-Tab Workareas

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

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

Note that the default value of isDynamicTabNavigation is true.

You also can set 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.

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 product teams to:

• Load their 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, 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 again contain a dynamic region defined in it. On user click, the UI Shell will load the product team's task flow into the dynamic region, and show the modal af:popup panelWindow without any buttons. Therefore, the product team's task flow must include the OK and Cancel buttons that are used to launch a dynamic tab and dismiss the popup, respectively. The dialog title will be set according to the label mentioned in the menu meta data 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 launched.

Developer Implementation

There are several considerations to keep in mind when you implement the Task Popup:

• For a dynamicMain Task item 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 launches the task flow.

  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"/>
  

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

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

• Developers 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 Section 16.4.1.3, "Implementing OK and Cancel Buttons in a Popup."

• Create another method for the OK button that calls the method in Example 16-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 Section 16.4.1.3, "Implementing OK and Cancel Buttons in a Popup."

• Developers then can pass the parameters directly from the managed bean to the openMainTask API bindings for the popup task flow page to launch 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.

14.4.1.1 closeMainTask History

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.

MainAreaHandler.handleOpenMainTaskEvent 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 launched, the current tab is set as the previous tab for the managed bean for the new tab.

A disclosure listener, MainAreaBackingBean.setLastDisclosedItem, handles user clicks in the tab UI. When the user clicks a tab, two events fire: 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 end up in 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. When a new task flow is opened, the task flow ID and its associated parameter values are pushed onto 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 Section 14.2.3.4, "Supporting No-Tab Workareas."

14.4.3.1 Implementing the Contextual Area Splitter

• Extend the contextual-area-task-flow-template Task Flow Template into the page task flow, as shown in Example 14-22.

  Example 14-22 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>
  

• Specify values for the contextual area splitter position and the collapsed state in the menu for the item node that represents the page using contextualAreaWidth and contextualAreaCollapsed properties. A sample entry in the menu file will resemble Example 14-23.

  Example 14-23 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"/>
  

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

  contextualAreaWidth="256"
  contextualAreaCollapsed ="false"
  

• For programmatic control, drag and drop the corresponding method from the data control named FndUIShellController:

  • collapseContextualArea

  • contextualAreaWidthSelection

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

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

  Example 14-24 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"/>
  

• For setting 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-25.

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

  Example 14-25 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"
          NDValue="#{<ManagedBean.Method>}"   
          NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.
                                       bean.FndMethodParameters"/>
  </methodAction>
  

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

Table 14-3, Table 14-4, and Table 14-15 list the menu attributes added by Applications Core to the menu XML above what is provided by Oracle ADF.

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

14.5.1.2 Displaying the Navigator Menu

The Navigator menu, shown in Figure 14-18, is rendered when the Navigator link is clicked on the UI Shell.

Figure 14-18 Navigator Menu Example

14.5.1.3 Implementing a Global Menu

The Navigator menu metadata may be pointing to target workarea 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 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 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-27.

   Example 14-27 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>
   

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

2. Update weblogic-application.xml. As shown in Example 14-28, set the application-param that has the param-name jps.policystore.migration to OFF.

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

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

3. In weblogic-application.xml, make sure the application-param that has the param-name jps.policystore.applicationid is set to the correct stripe, as shown in Example 14-29. This is the same as the application.name property of web.xml.

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

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

4. Add the following entry in web.xml:

   <listener> <listener-class>oracle.apps.fnd.applcore.menu.service.MenuFragmentServiceContextListener</listener-class>
   </listener>
   

14.5.2.1 Enforcing User Privileges and Restrictions

Before you enforce user actions, you should already have defined roles, principals, and actions in the database.

Functional security will always prevent a user from accessing a page or task flow that the user does not have access to. 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, but not to show an entry under the Employee Self-Service category that also led to the same page. See Example 14-30.

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

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

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

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

14.5.3.1 Rendering the Navigator Menu as Pull-down Buttons

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

To switch the UI Shell rendering so the Navigator menu renders as pull-down 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.7.5.1 Implementing User General Preferences Flow

Once the WebLogic Server console is configured, 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 to false for the PreferencesUI page entry in the menu.

3. Add the following task flow as default regional under the preferences page entry: "/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesFlow.xml#GeneralPreferencesFlow"

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

   Example 14-32 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>
   

   This should display the basic Preferences in the default regional area that can be launched to display sub-flows for each preference sub task (for instance, Accessibility and Appearance).

14.7.5.2 Using the Preferences Menu Model

The General Preferences 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. The Preferences menu will be maintained by the development team.

On any UI Shell page, the Global Area contains a Personalization menu that contains a Set Preferences link. This Preference link will redirect the user to a webApp-specific Preference page, depending upon the entry in Menu data.

Example 14-33 shows sample 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>

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

For example, the first itemNode refers to the preferencesA page that is part of the FND webApp. The ServiceFlow child node is a task flow that belongs to 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 preference 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 Workarea UI Shell pages in 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 preference page itemNode will display in the General Preferences Flow as navigate links. Therefore, all preference pages will have access to these flows.

14.7.5.3 Configuring User Session and ADF Security

To test the general preferences flows, you need to configure user session and ADF Security for the test application. See Chapter 48, "Implementing Application User Sessions."

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

14.7.5.4 Using Static APIs to Retrieve Preference Values

The general user preferences can be obtained from the static APIs of the GeneralPreferences class. Example 14-34 shows the method signatures and the values they can return.

String getAccessibilityMode()
Return Values List : { 'default' , 'screenReader' }
 
boolean isAnimationEnabled()
Return Values List : { true , false }
 
String getColorContrast()
Return Values List : { 'STANDARD' , 'HIGH' }
 
String getFontSize()
Return Values List : { 'LARGE' , 'MEDIUM' }
 
String getSessionLanguage()
Return Values List : { Valid Oracle Fusion NLS values for Language }
 
String getApplicationLanguage()
Return Values List : { Valid Oracle Fusion NLS values for Language }
 
boolean isEmbeddedHelpEnabled()
Return Values List : { true , false }
 
String getTerritory()
Return Values List : { Valid Oracle Fusion NLS values for Territory }
 
String getCurrency()
Return Values List : { Valid Oracle Fusion NLS values for Currency }
 
String getCharacterEncoding()
Return Values List : { Valid Oracle Fusion NLS values for Character Encoding }
 
String getNumberFormat()
Return Values List : { English , German } (Use number NumberFormat class to interpret them}

14.7.5.5 Implementing 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. This page is maintained by the OIM team. For the Password link to redirect to the pwdmgmt.jspx page, the deployment information of the current application and the OIM administration application must be populated correctly in the ASK tables.

14.10.1.1 Tagging a Resource (Business Object)

Follow these steps to tag a resource:

1. From the Component Palette, select WebCenter Tagging Service. Drag and drop the Tagging Button onto the page. (If you do not find the button, make sure you added the WebCenter Tagging JSP Tag Library to your user interface project.)

2. Open the Property Inspector for the Tagging Button. Enter the bound values for ResourceId, ResourceName and ServiceId, similar to Example 14-36.

   Example 14-36 Entering Property Information for Tagging Button

   <tag:taggingButton
   resourceId="#{row.AuctionHeaderIdString}"
   resourceName="#{row.AuctionTitle}"
   serviceId="oracle.apps.pon.auctionheadersall"/>
   

   Note:

   Make sure all the values are of type String.

3. From the Resource Palette, under My Catalogs > WebCenter Services Catalog > Task Flows, drag and drop the Tagging Dialog (as a Region). If you do not find the Tagging Dialog, make sure you added the WebCenter Tagging Service View to your user interface project (Properties > Libraries and classpath). Note that you may drop multiple tagging buttons on your page depending upon your requirement. You need to drop the tagging dialog only once on the page. Whenever you click a tag icon (tagging button) on the page, it will call the same tag dialog region.

   Note:

   If placing tags within rows of a table, this region must be dropped outside of the table. Otherwise, it is instantiated for every row, which will not work.

   The ability to tag an object is now enabled on the page. The code will look similar to that shown in Example 14-37.

   Example 14-37 Enabling Tagging

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

If you have multiple objects to tag, there will be multiple tag buttons you will drop on your page, whereas there will be only one tagging dialog.

Tagging is enabled, but to see the Tagged resource in the Tag Center, you must create a service definition.

To create a service definition:

1. Expand Application Resources > Descriptors > ADF Meta-INF. If you already have the service-definition.xml file, open it. Otherwise, create the service-definition.xml file. Important fields are:

   • taskFlowId: The task flow where you want to go.

   • resourceParamList: The list of parameters which you want to pass to task flow. For example, your task flow takes invoiceId and invoiceType. If the RESOURCE_ID for the tagged item is 123.C45 where 123 is the invoice ID and C45 is the invoiceType, in resourceParamList you should specify invoiceId;invoiceType. The Applications Core class will parse the resource id 123.C45 and pass invoiceId=123,invoiceType=C45 to the task flow. To use a different delimiter, use the customDelimiter attribute.

   • taskParametersList: These are parameters that can be passed to the task flow in addition to the resourceParamList.

   • navTaskKeyList: Do not specify this if it is not used. Otherwise, task flows from TagCenter will always go to a specific tab while the same taskfow opened from the Tasklist or API will go to a different tab.

   • navTaskLabel: If using tabbed workareas, this is needed to give a title to the tab that opens showing the tagged object. An Expression Language expression can be used. It will be evaluated on page load, so it can be an Expression Language expression that the landing page can resolve.

   • pageResourceParamList: If the RESOURCE_ID for the tagged item is, for example, "EastCoast.C45" where EastCoast will be a page level parameter called Region and a taskflow parameter called InvoiceType. It is assumed an object will always need both composite keys to be identified as a unique entity. So, the resourceParamList will always contain the same number of parameter names as the composite keys. The taskflow must take both EastCoast and C45 as parameters. But the page level parameters can be called out in the pageParametersList. For example:

     resourceParamList = "Region,InvoiceType"
     pageResourceParamList = "Region"
     

   • pageParametersList: Additional page parameters where the value is static. Example: pageParametersList = "Campaign=Sales"

   • customDelimiter: This is optional. The default is a ".". If you want something different, add this parameter.

     For ease of deployment, service definition files will be stored in Oracle Metadata Services (MDS). Add the service-definition.xml file to the Metadata Archive (MAR) file definition.

     A sample service-definition.xml is provided in Example 14-38.

     Example 14-38 Sample service-definition.xml

     <service-definition id="FND_DEMO_DOC_TAG" version="11.1.1.0.0"  >
         <resource-view taskFlowId="/WEB-INF/task-flow-1.xml#task-flow-1" >
         <parameters>
             <parameter name="viewId"
                        value="RevenueWorkArea"/>
             <parameter name="webApp"
                        value="ProjectsFinancials"/>
             <parameter name="pageParametersList"
                        value="p1=viewContext"/>
             <parameter name="navTaskKeyList"
                        value="ViewRevenueItem"/>
             <parameter name="taskParametersList"
                       value="a=1;b=2"/>
             <parameter name="resourceParamList"
                         value="invoiceId;invoiceType" />
             <parameter name="navTaskLabel"
                        value="Details"/>
             <parameter name="customDelimiter"
                        value="," />
             <resource-type-key>PAGE_OBJECT_NAME</resource-type-key>
         </parameters>
         </resource-view>
         <name-key>CUSTOM_NA_KEY_TYPE</name-key>
         <description-key>CUSTOM_TY_DESCRIPTION_KEY</description-key>
     </service-definition>
     

     You want to put the service-definition.xml file in a standardized location so there are no conflicts. Create or copy the file, which by default is located at .adf/META_INF/service-definition.xml, to the new standardized location. There are two goals for where to put the service-definition.xml:

     • Make it unique so two teams are not trying to push files to the exact same location in MDS.

     • Standardize it to be in meta/oracle/apps/meta. The /oracle/apps/meta makes the location specific to Oracle applications. The parent meta/ directory is used for MAR selection. The directory structure and contents then resemble:

       meta/ (this directory plus a specific sub-directory structure goes into the MAR)
            oracle/apps/meta/ (namespace unique to MDS)
                 <product-specific-directory-structure>/ (each team has a unique name)
                      service-definition.xml (located in the product directory)
       

       If you use an application-level or project-level service-definition.xml file, you do not need to make any changes so long as your name will be unique to other applications and projects. You should never have two entries for the same SERVICE_ID, whether within the same service-definition.xml file or in separate service-definition.xml files.

       That is, the service-definition.xml file should be under the data model project that contains the entity objects and view objects used for the detail page. If the view object is:

       oracle.apps.scm.receiving.receipts.receiptSummary.protectedUiModel.view.ReceiptSummaryHeaderVO,

       the service-definition.xml location will be:

       oracle.apps.scm.receiving.receipts.receiptSummary.protectedUiModel.meta.oracle.apps.meta.scm.receiving.receipts.receiptSummary.service-definition.xml.

2. Add the directory, such as meta/oracle/apps/meta/<lba>/<product>/, into the MAR.

   • Open Application > Application Properties > Deployment. Select the MAR file and choose Edit.

   • In the Edit dialog, select User Metadata and choose Add. Browse to select the meta directory you just added and click OK.

   • Select the meta directory (under oracle/apps/) and click OK.

   • Click OK in the Edit MAR dialog.

3. Add the namespace path /oracle/apps/meta to adf-config.xml, as shown in Example 14-39.

   Example 14-39 Adding the Namespace Path to adf-config.xml

   <adf-config
     <adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config"
                     version="11.1.1.000">
       <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
          <persistence-config>
             <metadata-namespaces>
                <namespace path="/oracle/apps/meta"
                 metadata-store-usage="WebCenterFileMetadataStore"/>
             </metadata-namespaces>
             <metadata-store-usage id="WebCenterFileMetadataStore"
                default-cust-store="true" deploy-target="true">
                <metadata-store class-name="oracle.mds.dt.persistence.stores.file.SrcControlFileMetadataStore">
                     <property name="metadata-path" value="../../mds"/>
                </metadata-store>
             </metadata-store-usage>
          </persistence-config>
       </mds-config>
     </adf-mds-config>
   </adf-config>
   

4. Add the entry shown in Example 14-40 to your adf-config.xml to enable the default resource action handler from Applications Core:

   Example 14-40 Enabling the Default Resource Action Handler

   <wpsC:adf-service-config>
       <resource-handler class="oracle.apps.fnd.applcore.tags.handler.FndResourceActionViewHandler"/>
   </wpsC:adf-service-config>
   

   Add this instruction in the header:

   xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"

5. Run the page.

   • The tag icon will appear on the page. When you click the Tag icon, it will take you to the UI where you can enter a new Tag.

   • You can share the tag or not share it. Only shared tags are available to Oracle Fusion Applications Search.

   • After creating the tag for the first time, again hover the mouse over the icon. It will display My Tags and Popular Tags.

   • Clicking the Tag takes you to the Tag Center UI where you are shown all resources that have been tagged by that word.

   • Clicking a resource from TagCenter will navigate you to the task flow defined in your service definition, passing the parameters you specified so you can view the object.

14.10.1.2 Enabling Multiple Navigation Targets

Searchable and taggable objects are defined at the view object/logical business object level. The same view object/business object can be viewed and tagged in more than one workarea and taskflow. The requirement is that all users must be able to navigate from TagCenter to a detail taskflow for which they have privileges. If this taskflow is available in the current workarea, use this target before any other.

This is implemented by supplying multiple navigation targets in the current service-definition.xml. Each target will have its parameter separated by a caret (^).

Example 14-41 shows how to define a list of three targets:

<resource-view
    taskFlowId="/WEB-INF/dummy^/WEB-INF/dummy^/WEB-INF/Test1Frag2TF.xml#Test1Frag2TF">
  <parameters>
    <parameter name="viewId" value="DummyView^Region6UIShellPage^Test2"/>
    <parameter name="webApp"
      value="ApplCoreCRMDemo^ApplCoreCRMDemo^SimpleApplication1_application1"/>
    <parameter name="pageParametersList" value=""/>
    <parameter name="taskParametersList" value=""/>
    <parameter name="resourceParamList" value="val"/>
    <parameter name="navTaskLabel" value="My Employee Details^My Employee Details 2^My Employee Details"/>
    <parameter name="applicationStripe"
       value="ApplicationsCommon^ApplicationsCommon^AppStripe1"/>
    <parameter name="pageDefinitionName"
       value="pageDef.not.exist^oracle.apps.view.pageDefs.Region6UIShellPagePageDef^oracle.apps.view.pageDefs.Test1PageDef"/>
   </parameters>
</resource-view>

The lists of taskFlowId, viewId, webApp, and so on, are specified as a delimited string, with each value delimited by a caret. Two parameters, applicationStripe and pageDefinitionName, are available for checking security when the target is in a different webApp.

If the current view id matches any one of the viewId values in the target list, you take the corresponding task flow (that is, if the third viewId value matches the current view id, you take the third taskFlowId value) and launch it in the current page, if the user has view access to that task flow, which overrides the order of the list. Otherwise, you check a list of link targets for the first target to which the current user has access. Application teams are responsible for making sure that all users who can access this object have at least one match to a target taskflow defined in the service-definition.xml.

When the target is in a different webApp, the security check is performed by calling checkBulkAuthorization API. Therefore, using a standalone WebLogic Server and LDAP policy store are required. This requirement is optional when the lists of targets are within the same webApp.

14.10.1.3 Tagging a Resource at the Row Level of a Table

To add row-level tagging to a table, add a new empty column to hold the tag button/link.

All other steps remain the same as described in Section 14.10.1.1, "Tagging a Resource (Business Object).".

14.10.1.4 Searching for a Tag

The Applications Standard recommends that you do not add the Tag Search in your page. The standard way is to launch the Tag Center UI by clicking the Tag icon, or from Tags in the UI Shell global area and do the search there.

14.10.1.5 Resource Viewer for Tagged Items

It can be handy for a user to be able to click a tag and open a document. To do this, Web Center Tagging needs to know a resource viewer (a task flow) where it should take the user to show the required information.

Each development team will build a task flow where they can take the user for that resource and show the desired additional information.

1. Select or create a new task flow that will act as your resource viewer for a service (business object).

   1. In the task flow definition, define an input parameter that is called resourceId (in this example), class equal to java.lang.String, value equal to #{pageFlowScope.resourceId}, and required enabled.

      Note that the value for resourceId is set automatically when clicking a tagged item link in TagCenter.

   2. Create a method with a parameter of object id in the application module for a tagged item (named, for instance, setCurrentRow) to set the view object row based on the passed resource id parameter.

   3. Add the setCurrentRow method as the default activity in the task flow and bind the method (right click on the method in the task flow and go to page definition) with the parameter value of #{pageFlowScope.resourceId}, type java.lang.String, and name equal to the parameter variable name in the setCurrentRow method signature.

   4. Add to the new task flow the bounded task flow for the details/information page of the tagged item.

   5. Add a control flow case from the setCurrentRow method to the details/information page task flow, as shown in Figure 14-27.

      Figure 14-27 Adding A Control Flow to Details Task Flow

      
      

2. Register the new task flow in the service-definition.xml file. You will register the resource viewer for a particular service (business object) to its section in the service definition file. See Example 14-38 for samples of the service-definition and resource-view entries.

Basically, you have defined a task flow that takes the resource id as input. Use the resource id to uniquely identify the business object and display any desired extra detail. Note that clicking a tagged item in TagCenter displays the details/information page for the tagged item in the local area of the workarea page for that task flow.

14.11.2.1 Sub-Flow Registration APIs

Use the openSubFlow and closeSubFlow APIs to record sub-flows to Recent Items. Whenever an ADF Controller task flow call takes place, no notification is raised to Applications Core or UI Shell. So, unlike launching a task from a tasks list, product teams need to explicitly notify the UI Shell for sub-flow calls.

When openSubTask is called before a sub-flow is launched, the sub-flow ID and its parameter values are pushed onto the stack. Applications Core also notifies the Recent Items implementation with recorded task flow information. This essentially makes a sub-flow able to be bookmarked by Recent Items, and can be launched directly from the selection of menu items on Recent Items.

Note that registering sub-flows to Recent Items is optional. The decision is up to a product team's product manager.

Implementation

This API is exposed as the Data Control methods FndUIShellController.openSubTask and FndUIShellController.closeSubTask that developers will drag and drop to their page fragments to create links to notify UI Shell. The FndUIShellController Data Control is automatically available to all Oracle Fusion applications that reference Applications Core libraries.

Example 14-43 shows the signature and Javadoc of the method.

/**
* Notify UIShell to record given sub-flow on the stack and 
* also notify Recent Items to include it on the list.
*
* @param taskFlowId Task flow to open
* @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 keyList Key list to locate the task flow instance.
*                This is a semicolon delimited keys or key-value pairs.
*                For example, "key1;key2=value2". If only the key is specified,
*                the value is picked up from parametersList with the same
*                name as the key.
*
* @param taskParametersList 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."
*
* @param methodParameters This can be used for passing
*                Java object into the task flow that's specified 
*                in taskFlowId parameter. Use <code>setCustomObject() API</code>
*                in FndMethodParameters for setting the java object.
*
* @return For internal Contextual Event processing
*/
 
public FndMethodParameters openSubTask(String taskFlowId,
String parametersList,
String label,
String keyList,
String taskParametersList,
String viewId,
String webApp,
FndMethodParameters methodParameters)
 
/**
* Closes the currently-focused sub-task and the focus moves to the 
* task from which this sub-task was launched.
*
* @param methodParameters For future implementation. No-op for now.
* @return For internal Contextual Event processing
*/
public FndMethodParameters closeSubTask(FndMethodParameters methodParameters)

All the parameters required to be passed in openSubTask are exactly same as used by the Section 14.16, "Introducing the Navigate API.".

14.11.2.2 openSubTask API Labels

The openSubTask API accepts the same set of parameters as used by the Section 14.16, "Introducing the Navigate API." If no label is specified in the openSubTask API, Recent Items will register it with the name of the parent task flow's label. You should set a different label based on the business use case in the openSubTask API. Failing to do so will register this flow with the same label as the parent task flow's label and, therefore, will make it impossible to distinguish between the parent flow and the sub-flow entry in the Recent Items list.

14.11.2.3 Launching from Recent Items

Whatever task flow details are registered while invoking the openSubTask API will be used by Recent Items to launch it. Recent Items takes care of launching the task flow in the right work area and web application. Product teams do not need to do anything for that. Because the openSubTask API supports parametersList, product teams can pass some requirement-specific values to it while registering their task flow to Recent Items. On launching, those passed values are available in the pageFlowScope. So, product teams can analyze these values and make decisions, such as if they need to first initialize the parent flow, or if they need to set Visible to False on some of the actions on the page.

14.11.3.1 Implementing the Sub-flow Design Pattern

The parent task flow named ToParentSFFlow is shown in Figure 14-35.

Figure 14-35 Example Parent Task Flow

decideFlow is the router activity that decides whether the control flow should go to the original parent flow path (initParent) or to the sub-flow path (toChild). The condition used is defined as:

<router id="decideFlow">
  <case>
    <expression>#{pageFlowScope.Empno == null}</expression>
    <outcome id="__9">initParent</outcome>
  </case>
 
  <case>
    <expression>#{pageFlowScope.Empno != null}</expression>
    <outcome id="__10">toChild</outcome>
  </case>
 
  <default-outcome>initParent</default-outcome>
</router>

The test checks whether or not the Empno variable in the parent flow's pageFlowScope is null. #{pageFlowScope.Empno} is set using its input parameter Empno when the parent flow is called. The input parameters on the parent flow (that is, ToParentSFFlow) is defined as:

<input-parameter-definition>
  <name>Empno</name>
  <value>#{pageFlowScope.Empno}</value>
  <class>java.lang.String</class>
</input-parameter-definition>

When the parent flow is launched from the task List, the Empno parameter is not set (that is, it is not defined in the application menu's itemNode). Therefore, it is null and the router will route it to the initParent path.

When the sub-flow is recorded through the openSubTask API, Empno is set on the parametersList as:

<methodAction id="openSubTask" RequiresUpdateModel="true"
                 Action="invokeMethod" MethodName="openSubTask"
                 IsViewObjectMethod="false" DataControl="FndUIShellController"
                 InstanceName="FndUIShellController.dataProvider"
                 ReturnName="FndUIShellController.methodResults.openSubTask_FndUIShellController_dataProvider_openSubTask_result">
     <NamedData NDName="taskFlowId" NDType="java.lang.String"
         NDValue="/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToParentSFContainerFlow.xml#ToParentSFContainerFlow"/>
     <NamedData NDName="parametersList" NDType="java.lang.String"
                NDValue="Empno=#{row.Empno}"/>
     <NamedData NDName="label" NDType="java.lang.String"
                NDValue="#{row.Ename} complete details"/>
     <NamedData NDName="keyList" NDType="java.lang.String"/>
     <NamedData NDName="taskParametersList" NDType="java.lang.String"/>
     <NamedData NDName="viewId" NDType="java.lang.String"
                NDValue="/DemoWorkArea"/>
     <NamedData NDName="webApp" NDType="java.lang.String"
                NDValue="DemoAppSource"/>
     <NamedData NDName="methodParameters"
         NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>

You also set up:

• taskFlowId to be the parent flow's, not the sub-flow's

• label to be the sub-flow's

When end users click the link (the Ename) to which the openSubTask method is bound, openSubTask will be called. This link component is defined as:

<af:column sortProperty="Ename" sortable="false"
           headerText="#{bindings.ComplexSFEmpVO.hints.Ename.label}"
           id="resId1c2">
  <af:commandLink id="ot3" text="#{row.Ename}"
                  actionListener="#{bindings.openSubTask.execute}"
                  disabled="#{!bindings.openSubTask.enabled}"
                  action="toChild">
    <af:setActionListener from="#{row.Empno}"
                          to="#{pageFlowScope.Empno}"/>
  </af:commandLink>
</af:column>

Note that when the link is clicked:

• actionListener and the action specified on the link are executed, in that order.

• openSubTask needs to be called only from the original parent flow path (that is, initParent), not from the sub-flow path (that is, toChild).

EmployeeDetails activity in Figure 14-35 is a Task Flow Call activity that invokes the ToChildSFFlow sub-flow. Before the sub-flow is executed, you need to add initialization steps. These initialization steps could include, but are not limited to:

• Set up parent states. For this example, you need to set the selected employee's row to be the current row.

• Set up the contextual area state.

• Set up states to allow the sub-flow to navigate back to the parent flow.

There are two approaches to set up the initialization steps:

• In the parent flow

• In the sub-flow

For the first approach, you can add logic to initialize both paths before the task flow call activity in the parent flow. For the second approach, you initialize states in the sub-flow by using input parameters of the sub-flow. For example, the sub-flow will take an input parameter named Empno. In effect, the second approach just postpones the initialization to the sub-flow.

The definition of input parameters in the Task Flow Call activity is:

<task-flow-call id="EmployeeDetails">
     <task-flow-reference>
       <document>/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToChildSFFlow.xml</document>
       <id>ToChildSFFlow</id>
     </task-flow-reference>
     <input-parameter>
       <name>Empno</name>
       <value>#{pageFlowScope.Empno}</value>
     </input-parameter>
</task-flow-call>

Note that this means that the calling task flow needs to store the value of Empno in #{pageFlowScope.Empno}. For example, from the original parent flow path, it is set to be #{row.Empno} using the setActionListener tag. For the sub-flow path, it is set using the parent flow's input parameter Empno. On the sub-flow, you need to specify its input parameters as:

<task-flow-definition id="ToChildSFFlow">
   <default-activity>TochildSFPF</default-activity>
   <input-parameter-definition>
     <name>Empno</name>
     <value>#{pageFlowScope.Empno}</value>
     <class>java.lang.String</class>
   </input-parameter-definition>
   ...
</task-flow-definition>

Note that the name of the input parameter (Empno) needs to be the same as the parameter name defined on the Task Flow Call activity. When the parameter is available, ADF will place it in #{pageFlowScope.Empno} to be used within the sub-flow. However, this pageFlowScope is different from the one defined in the Task Flow Call activity because they have a different owning task flow (that is, parent task flow versus sub-flow).

The definition of the sub-flow is shown in Figure 14-36:

Figure 14-36 Example Sub-flow Definition

In the sample implementation, you chose to implement the initialization step in the sub-flow. Empno is passed as a parameter to the sub-flow and used to initialize the parent state. When the sub-flow is launched, the default view activity (ToChildSFPF) displays. Before it renders, the initPage method on the ChildSFBean will be executed. The page definition of the default page is defined as:

<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel">
 <parameters/>
 <executables>
   ...
   <invokeAction id="initPageId" Binds="initPage" Refresh="always"/>
 </executables>
 <bindings>
   ...
   <methodAction id="initPage" InstanceName="ChildSFBean.dataProvider"
                 DataControl="ChildSFBean" RequiresUpdateModel="true"
                 Action="invokeMethod" MethodName="initPage"
                 IsViewObjectMethod="false"
                 ReturnName="ChildSFBean.methodResults.initPage_ChildSFBean_dataProvider_initPage_result"/>
    ...
 </bindings>
</pageDefinition>

initPage is specified in the executables tag and will be invoked when the page is refreshed. The initPage method itself is defined as:

public void initPage()
{ 
    FacesContext facesContext = FacesContext.getCurrentInstance();
    ExpressionFactory exp = facesContext.getApplication().getExpressionFactory();
    DCBindingContainer bindingContainer =
      (DCBindingContainer)exp.createValueExpression(
          facesContext.getELContext(),"#{bindings}",DCBindingContainer.class).getValue(facesContext.getELContext());
    ApplicationModule am = bindingContainer.getDataControl().getApplicationModule();
 
    ViewObject vo = am.findViewObject("ComplexSFEmpVO");
    vo.executeQuery();
 
    Map map = AdfFacesContext.getCurrentInstance().getPageFlowScope();
    if(map !=null){
         Object empObj = map.get("Empno");
         if(empObj instanceof Integer){
             Integer empno =(Integer)map.get("Empno");// new Integer(empnoStr);
             Object[] obj = {empno};
             Key key = new Key(obj);
             Row row = vo.getRow(key);
             vo.setCurrentRow(row);
         }
         else
         {
             String empnoStr = (String)map.get("Empno");
             Integer empno = new Integer(empnoStr);
             Object[] obj = {empno};
             Key key = new Key(obj);
             Row row = vo.getRow(key);
             vo.setCurrentRow(row);
         }
     }
}

initPage takes the input parameter Empno from #{pageFlowScope.Empno} as a key to select a row and set it to be the current row in the master Employee table.

14.12.3.1 Asynchronous Items Overview: Expense Reports Saved Search

For asynchronous Watchlist items, the count is only updated upon request. For example, in Expenses, there is an expense reports search panel from which users can make searches and save them in MDS for future use. Users should be able to promote their saved searches to the Watchlist for tracking. This Watchlist item (of type USER_SAVED_SEARCH) is asynchronous in that the Watchlist count will only be updated upon request, and events that change the count will not simultaneously be updating the Watchlist. In this case, Watchlist code is responsible for querying the count of an asynchronous Watchlist item on demand. Figure 14-38 shows the flow of an asynchronous Watchlist item.

Figure 14-38 Asynchronous Watchlist Item Flow

For the Expense report saved search panel example:

• Since this item is of type USER_SAVED_SEARCH, Watchlist items are created when the user promotes a saved search on the search panel in Expenses. This invokes a Watchlist service on the Watchlist that does the Watchlist item creation. This is not needed for Watchlist items of type SEEDED_QUERY or SEEDED_SAVED_SEARCH.

• A request to refresh the Watchlist item count comes from the Watchlist portlet. This will invoke an exposed service, which delegates the call to a method on a provided Watchlist JAR file.

• The method on the Watchlist JAR file will take care of rerunning the query (on the expenses database) and taking the results to update the Watchlist item count (on the Watchlist database).

14.12.3.2 Summary of Implementation Tasks

At a high-level, for asynchronous Watchlist items, the developer tasks are:

• (Not needed for Human Task) Determine/set up view objects to execute the query for Watchlist count. You may want to include view criteria with bind variables and specify default values for bind variables.

  For example, most view objects seeded for the Watchlist would need to filter by user to show counts specific to the logged-in user. You could create a view criteria with a bind variable called userId and specify the default value as a groovy expression to determine the current user id from the security context. You then would seed this view criteria id in the setup table along with the view object. The Watchlist API would execute the view object by applying this view criteria to get the row count. Example 14-44 shows a code snippet from the view object xml for bind variable with default value.

  Example 14-44 Example Code from the View Object XML for Bind Variable with Default Value

  <Variable
              Name="userId"
              Kind="where"
              Type="java.lang.String">
              <TransientExpression><![CDATA[return adf.context.securityContext.userName;]]></TransientExpression>
            </Variable>
  

• (Optional) Set up a Summary view object to facilitate refresh count and specify the summary attribute in the Watchlist setup table. Watchlist code would use this information to query the count instead of doing a rowcount on the executed view object results.

• Include Watchlist model JAR files in your service project and set up a refreshWatchlistCategory service method. This method will only contain code to delegate the call to the nested Watchlist application module method that actually executes the view object queries by reading your Watchlist setup data. This requires that all the corresponding model projects are included as JAR files in this service project so view objects are available in the class path. This service should be exposed so that the Watchlist UI can use it to launch the refresh process.

• Determine/code task flows for drill-down from the Watchlist UI. There is no special coding required for these task flows; the key-value parameter string that you specify in the setup table will be used as the input parameter list when invoking the specified task flow for the UI drilldown on Watchlist items.

• (Optional) Enable saved search promotion to the Watchlist: Include Watchlist model JAR files in the corresponding project for query panel and work with Watchlist API. For promotion and unpromotion of user-saved searches, code will have to invoke a method in the provided Watchlist JAR, which will then handle interaction back to the Watchlist. Add promotion and unpromotion components on the search panel so that saved searches can be used as Watchlist items.

• Include Watchlist UI and Protected model JAR files in your UI Superweb project, to enable Watchlist menu drilldown in the UI Shell global area, as shown in Figure 14-39.

  Figure 14-39 Example Watchlist Menu Drilldown

  
  

• Create FND_LOOKUPS for displayed Watchlist category and item meaning (FND_STANDARD_LOOKUP_TYPES.LOOKUP_TYPE). Product teams will need to seed the lookup type with meaning for category (VIEW_APPLICATION_ID = 0 and SET_ID = 0). The translated lookup type meaning is shown in the Watchlist UI for category, while the corresponding lookup value meanings are shown in the Watchlist UI for items (user saved search item meanings come from saved search directly). Product teams will need to create seed data for this lookup.

• Example 14-45 presents sample code to create or update the lookup.

  Example 14-45 Sample Code to Create/Update Watchlist Lookup

  declare
  begin
  FND_LOOKUP_TYPES_PKG.CREATE_OR_UPDATE_ROW (
    X_VIEW_APPSNAME => 'FND',
    X_LOOKUP_TYPE => 'FIN_EXM_WATCHLIST_CATEGORY',
    X_APPLICATION_SHORT_NAME => 'EXM',
    X_MEANING => 'Expenses',
    X_DESCRIPTION => 'Expenses Watchlist Category',
    X_REFERENCE_GROUP_NAME => null
  );
  end;
   
  declare
  begin
  FND_LOOKUP_VALUES_PKG.CREATE_OR_UPDATE_ROW (
    X_LOOKUP_TYPE           => 'FIN_EXM_WATCHLIST_CATEGORY',
    X_VIEW_APPSNAME         => 'FND',
    X_LOOKUP_CODE           => 'SAVED_EXPENSE_REPORTS',
    X_MEANING               => 'In Progress Expense Reports'
  --  X_SET_CODE              IN VARCHAR2 DEFAULT NULL,
  --  X_DESCRIPTION           IN VARCHAR2 DEFAULT NULL,
  --  X_ENABLED_FLAG          IN VARCHAR2 DEFAULT 'Y',
  --  X_START_DATE_ACTIVE     IN VARCHAR2 DEFAULT NULL,
  --  X_END_DATE_ACTIVE       IN VARCHAR2 DEFAULT NULL,
  --  X_DISPLAY_SEQUENCE      IN NUMBER DEFAULT NULL
    );
  end;
  

Seed Watchlist categories and setup information. Create your category in ATK_WATCHLIST_CATEGORIES and then seed your items in the reference data table (ATK_WATCHLIST_SETUP). The watchlist_item_type determines how the Watchlist code will handle the item.

14.12.4.1 Making the Watchlist Link in UI Shell Global Area Work

To ensure the Watchlist link works in your pages, complete these steps.

• Add this ADF library JAR file to the SuperWeb user interface project for your application (the JAR file must be part of your WAR in WEB-INF/lib):

  fusionapps/jlib/AdfAtkWatchListPublicUi.jar

• Add this dependent model ADF library JAR file in your application (the JAR file must be part of your EAR in APP-INF/lib):

  fusionapps/jlib/AdfAtkWatchListProtectedModel.jar

• Add this dependent resource bundle ADF library JAR file in your application (the JAR file must be part of your EAR in APP-INF/lib):

  fusionapps/jlib/AdfAtkWatchListPublicResource.jar

• Add these resource-ref entries to web.xml in your SuperWeb user interface project:

  <resource-ref>
      <res-ref-name>wm/WorkManager</res-ref-name>
      <res-type>commonj.work.WorkManager</res-type>
      <res-auth>Container</res-auth>
  </resource-ref>
  <resource-ref>
      <res-ref-name>jdbc/ApplicationDBDS</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
  </resource-ref>
  

14.12.4.2 Seed Reference Data (All items)

Refer to Section 14.12.2, "Watchlist Physical Data Model Entities" for details of the entire Watchlist data model. Seed only ATK_WATCHLIST_CATEGORIES and ATK_WATCHLIST_SETUP.

14.12.4.3 Create Summary View Object (SEEDED_QUERY)

• By default, Watchlist code will access the application module/view object that is specified in the setup table, and rerun the query to refresh the Watchlist count. The summary view object is a way for a product team to get the count in its own way. Usually this will be for efficiency reasons.

• The product team can signal that it wants the Watchlist code to use its summary view object by seeding something in SUMMARY_VIEW_ATTRIBUTE of ATK_WATCHLIST_SETUP. If this is not null, the Watchlist code will get the view object, but instead of running the query, it will just take the first row and get the specified attribute.

• Thus, the developer task is to create a view object with the correct count in the attribute specified in the setup table.

14.12.4.4 Create Seeded Saved Searches in MDS (SEEDED_SAVED_SEARCH)

In addition to seeding seeded saved searches in the reference tables, the saved searches need to be seeded in MDS so that when the user visits the saved search panel, the saved search will show as one of the choices in the drop-down box. Currently, saved searches in MDS are stored in the file system as an XML file for each view object. The developer steps to create this file are:

• Make sure you have enabled MDS for your application.

• Run the application and visit the desired search page.

• Use the UI to create saved searches and name them. For each saved search, select Run Automatically.

• Examine the adf-config.xml file to determine where your file-based MDS repository is located.

• In a terminal, change to the directory:

  <MDS repository>/persdef/oracle/apps/.../mdssys/cust/user/<user>/

  <user> would be the user you used to save the search with, or 'anonymous' by default.

• Inside that directory, there should be an xxxVO.xml.xml file that contains the created saved searches. Keep that file.

• In that XML file, note the saved search id, which should match the View Criteria Id in the reference data.

  Note:

  This Id can be different than the display name that you entered in the saved search UI.

14.12.4.5 Creating Application Module/View Objects (All except HUMAN_TASK)

Refer to Section 14.12, "Implementing the Watchlist."

14.12.4.6 Setting Up Service (All except HUMAN_TASK)

For the same Watchlist items, the Watchlist portlet needs to be able to invoke a refresh. Each product team will set up and expose a service that includes local JAR files for this purpose. The nested Watchlist JAR file can use those local JAR files in its refresh code.

The service will expose the refreshCategory method, which will, in turn, delegate the call to the same method in the nested Watchlist application module. This method will be provided in the Watchlist JAR file and will contain code to perform the category-wide refresh.

14.12.4.7 Importing All Watchlist-Related AMs

Your Service project will need to import the other JAR files from your product that will need to be used by the Watchlist code.

14.12.4.8 Nesting Watchlist Application Module

Include AdfAtkWatchListProtectedModel.jar and AdfAtkWatchListPublicModel.jar in your service project, and nest AdfAtkWatchListPublicUi.jar in your service application module.

Set up the AppMasterDB connection that comes with it. Point it to the database where you have seeded your data in the Watchlist tables. This usually is your development database that is used for the ApplicationDB connection.

14.12.4.9 Using the refreshWatchlistCategory Method

public void refreshWatchlistCategory(String categoryCode)

This method, shown in Example 14-46, refreshes all Watchlist items in the corresponding category.

public void refreshWatchlistCategory(String categoryCode) {
    AtkWatchlistPublicAMImpl wlAM = this.getAtkWatchlistPublicAMImpl();
    wlAM.refreshWatchlistCategory(categoryCode);
}

14.12.4.10 Importing Watchlist JAR Files into the Saved Search Project (USER_SAVED_SEARCH)

For subsequent steps that require running Watchlist APIs from your code, you will need to import the Watchlist JAR files. These also contain an AppMasterDB connection that will need to point to the Watchlist database.

• Add AdfAtkWatchlistProtectedModel.jar and AdfAtkWatchlistPublicService.jar (fusionapps > jlib) as ADF libraries in the appropriate data model projects, preferably in a model project that is visible to both service and user interface model project application modules.

• Add AdfAtkWatchlistPublicUi.jar as an ADF library to your user interface project.

• Configure the AppMasterDB connection.

14.12.4.11 Promoting Saved Search to the ATK Watchlist (USER_SAVED_SEARCH)

Every Watchlist-enabled saved search panel will need to include a component to let the user control which of the saved searches to promote. The pre-seeded saved searches will be shown as static, while the user can use checkboxes to determine which of his or her own saved searches should be promoted. There will be listeners to this component that will publish Business Events to make the appropriate worklist changes.

Before you begin

Ensure that the following steps have been performed.

• Populate ATK tables with SEED watchlist category information. Product teams need to provide information about the service that refreshes the watchlist item count.

• Populate ATK tables with appropriate watchlist setup information. There must be a watchlist setup item of type "USER_SAVED_SEARCH".

• Make sure the application is MDS enabled so users can save their searches and that the saved searches exist across sessions.

• From the watchlist UI, users can drill down to the transactional UI flows. Make sure that the transactional UI flow is properly set up so that it can show the search page when the user clicks the watchlist item in the watchlist UI.

• In the application project, create a backing bean and register it as a backingBeanScope bean. In the backing bean, create the Java method shown in Example 14-47:

  Example 14-47 Creating the Backing Bean

  import oracle.adf.view.rich.model.QueryDescriptor;
  import oracle.adf.view.rich.model.QueryModel;
  ..................
   
      public List<String> getWatchListUserSavedSearchList() {
          if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
            AppsLogger.write(this, "Watchlist saved search promotion: Entering method getWatchListUserSavedSearchList", AppsLogger.FINEST);
          }
          List<String> WatchListUserSavedSearchList = new ArrayList<String>();
          QueryModel queryModel =
              (QueryModel)evaluateEL("#{bindings.ImplicitViewCriteriaQuery.queryModel}");//See next code sample for evaluateEL()
          if (queryModel != null) {
            if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
              AppsLogger.write(this, "Watchlist saved search promotion: getWatchListUserSavedSearchList method: queryModel is not null", AppsLogger.FINEST);
            }
              List userQueries = queryModel.getUserQueries();
              if (userQueries != null & userQueries.size() > 0) {
                if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
                  AppsLogger.write(this, "Watchlist saved search promotion: getWatchListUserSavedSearchList method: User Saved Searches exist", AppsLogger.FINEST);
                }
                  for (int i = 0; i < userQueries.size(); i++) {
                      QueryDescriptor qd = (QueryDescriptor)userQueries.get(i);
                      if(qd != null){
                        if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
                          AppsLogger.write(this, "Watchlist saved search promotion: getWatchListUserSavedSearchList method: Adding user saved search name to the watchListUserSavedSearchList using QueryDescriptor getName: " + qd.getName(), AppsLogger.FINEST);
                        }
                        WatchListUserSavedSearchList.add(qd.getName());
                      }
                  }
              }
          }
          if (AppsLogger.isEnabled(AppsLogger.FINEST)) {
            AppsLogger.write(this, "Watchlist saved search promotion: Exiting method getWatchListUserSavedSearchList: returning watchListUserSavedSearchList: " + WatchListUserSavedSearchList, AppsLogger.FINEST);
          }
          return WatchListUserSavedSearchList;
      }     
  

14.12.4.12 Code Task Flows to Accept Parameters (All except HUMAN_TASK)

If you have seeded the information properly, your normal task flows should work when drilled-down to from the Watchlist portlet.

Map pfs = RequestContext.getCurrentInstance().getPageFlowScope(); String vcName = (String) pfs.get("vcName");

if (vcName == null || vcName.equals("")) {
        // If no ViewCriteria is given, load default VC
        DCBindingContainer dcbc = 
(DCBindingContainer)BindingContext.getCurrent()
                .getCurrentBindingsEntry();
FacesCtrlSearchBinding fcsb = 
(FacesCtrlSearchBinding)dcbc
.findExecutableBinding("ImplicitViewCriteriaQuery");
FacesCtrlSearchDef def = (FacesCtrlSearchDef)fcsb.getDef();
DCParameterDef paramDef = 
(DCParameterDef)def.getParameterDef(
JUSearchBindingCustomizer.PARAMCRITERIA);
fcsb.evaluateParameter(paramDef.getExpression(),false));
} else {
        QueryModel model = search_query.getModel();
        QueryDescriptor selDescriptor = model.create(vcName, null);
if (selDescriptor != null) {
model.setCurrentDescriptor(selDescriptor);
}
BindingContainer bindings = 
BindingContext.getCurrent().getCurrentBindingsEntry();
OperationBinding method = (OperationBinding) 
bindings.getControlBinding("applyViewCriteriaByName");
method.getParamsMap().put("name", vcName);
method.execute();
}

14.12.4.13 Import Watchlist UI JAR File in User Interface Project

There is a link in the UI Shell for Watchlist in the global area. To make it work, the user interface project that you will ultimately run will need to include these Watchlist UI JAR files: AdfAtkWatchListPublicUI and its dependent model JAR file AdfAtkWatchListProtectedModel.

14.12.4.14 Additional Entries for Standalone Deployment

These entries are required for the Watchlist service and UI to be able to work in a standalone deployment.

• Add this entry in ejb-jar.xml in your service project that contains the watchlist service next to the similar entry for ApplicationDB. You need resource-ref entries for both ApplicationDB and AppMasterDB:

  <resource-ref> 
    <res-ref-name>jdbc/AppMasterDBDS</res-ref-name> 
    <res-type>javax.sql.DataSource</res-type> 
    <res-auth>Container</res-auth> 
  </resource-ref>
  

• Add this entry in web.xml in your SuperWeb project next to the similar entry for ApplicationDB. You need resource-ref entries for both ApplicationDB and AppMasterDB:

  <resource-ref> 
    <res-ref-name>jdbc/AppMasterDBDS</res-ref-name> 
    <res-type>javax.sql.DataSource</res-type> 
    <res-auth>Container</res-auth> 
  </resource-ref>
  

• connections.xml should have a valid database entry for AppMasterDB.

14.14.4.1 Defining and Publishing Business Events in JDeveloper

To define a Business Event, follow these steps:

1. In the Application Navigator, double-click an entity object.

2. In the overview editor, click the Business Events navigation tab.

3. On the Business Events page, expand the Event Publication section and click the Edit event publications icon.

4. In the Edit Event Publications dialog, click New to create a new event.

5. Double-click the new cell in the Event column, and select the appropriate event.

6. Double-click the corresponding cell in the Event Point column, and select the appropriate event point action.

7. You optionally can define conditions for raising the event using the Raise Conditions table.

8. Click OK.

An event definition in the Entity XML file would look similar to:

<EventDef  Name="OpportunityStatusUpdate">
  <Payload>
    <PayloadItem AttrName="OpptyId"/>
    <PayloadItem AttrName="Status"/>
    <PayloadItem AttrName="Customer.CustomerId"/>
  </Payload>
</EventDef>

14.14.4.2 Overriding isActivityPublishingEnabled() to Enable Activity Publishing

By default, Business Events are not published as Activities. Product teams should override the isActivityPublishingEnabled() method to enable Activity publishing for an Entity Object. Table 14-8 shows the details about the APIs exposed in OAEntityImpl that product teams can override.

Note that, except for the isActivityPublishingEnabled() method, other methods mentioned in Table 14-8 should be avoided in favor of transient attributes specified in Section 14.14.4.3, "Defining Activity Attributes Declaratively."

14.14.4.3 Defining Activity Attributes Declaratively

Some of the attributes, such as Actor, Service Ids and Additional Service Ids, can be passed as a part of the payload. The basic process steps are:

• Define a transient attribute in the Enterprise Object.

• Give a default value to the transient attribute.

• Include the transient attribute as a part of the payload.

The different transient attributes that can be passed with the payload are shown in Table 14-9.

14.14.5.1 Adding the ActivityStream UI Task Flow

To add the ActivityStream task flow:

1. Make sure your user interface project includes the WebCenter Activity Streaming Service library in the Libraries and Classpath section in the project properties dialog.

2. From Resource Catalog > TaskFlows, drag and drop either an "Activity Stream" or "Activity Stream Summary - View" task flow onto the page where you want to display the Activity Stream UI.

3. Set the taskFlow resourceId parameter to #{securityContext.userName}. This will tie the task flow to the current user at runtime.

4. For additional details about the Activity Stream task flow, see the "Integrating the People Connections Service" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

14.14.5.2 Defining Activities in service-definition.xml

The default location of the service-definition.xml file is under META-INF in the project. For Oracle Fusion Applications, this file will be stored in MDS so you need to put it into a directory that can be added to your Metadata Archive (MAR) file.

The standardized location that all applications should use is:

<app>/<lba>/<product>/<*project*>/*meta/oracle/apps/meta*/<lba>/<product>/service-definition.xml

The name must be unique, such as:

helpPortal/atk/helpPortal/model/meta/oracle/apps/meta/atk/helpPortal/service-definition.xml

To define Activities in service-definition.xml, follow these steps.

1. If necessary, add the directory to the application's MAR profile. To add a MAR, select Application > Application Properties > Deployment. In the dialog that displays, select the MAR file and click Edit.

2. In the Edit dialog, select User Metadata and click Add. Browse to the meta directory just added and click OK.

3. Set the id attribute on the service-definition element to the Entity Object name for which you want to define the Activities.

   <service-definition xmlns="http://xmlns.oracle.com/webcenter/framework/service"
                 id="oracle.apps.crmdemo.model.OpportunityEO"
                 version="11.1.1.0.0">
   

4. Define an activity-type for every business event in the Entity Object for which you want to display the Activities in the Activity Stream UI. Make sure the event name of the Entity Object matches the activity-type name attribute value.

   <activity-types>
     <generic-activity-category name="UPDATE">
       <activity-type name="OpportunityStatusUpdate"
                      displayName="Opportunity Status Update"
                      description="Opportunity Status Update"
                      messageFormatKey="OPPTY_STATUS_UPDATED"
                      iconURL=""
                      defaultPermissionLevel="SHARED"/>
     </generic-activity-category>
   </activity-types>
   

5. Set message format strings.

   Each activity-type should have a message format defined. The message format string can be translated and is stored in a ResourceBundle or an XLIFF bundle. Oracle Fusion Applications use XLIFF bundles to store the Activity message format strings. The activity-type element in the service-definition.xml file has messageFormatKey attributes that are used to refer to the format strings in the XLIFF bundle.

   Activity Stream supports only Java ResourceBundles. The Common String Repository is used for the message format strings.

   These attributes are supported on the activity-type element:

   • messageFormatKey - Used on Activity Stream full view task flow.

   • summaryByListMessageFormatKey - Used in summary view Activity Stream task flow.

   • summaryByCountMessageFormatKey - Used in summary view task flow.

   messageFormatKey

   The value of this attribute points to the key defined in ResourceBundle. These tokens are supported in the message format string.

   • {actor[0]}: Replaced by the display name of the user who triggered the event.

   • {object[0]}: Replaced by the value of the attribute in the event payload whose attribute name matches the object type name.

   • {custom[attr1].value}: Replaced by the value of the attr1 attribute in the event's payload.

   Sample using Java ResourceBundle:

   <resource-bundle-class>oracle.apps.crm.OpportunityResourceBundle</resource-bundle-class>
    <activity-types>
      <generic-activity-category name="OPPTYUPDATE">
        <activity-type name="OpptyStatusUpdate"
                       displayName="OPPTY_UPDATE"
                       description="OPPTY_UPDATE_DESCRIPTION"
                       messageFormatKey="OPPTY_STATUS_UPDATED"
                       defaultPermissionLevel="SHARED"/>
       </generic-activity-category>
    </activity-types>
   

   In OpportunityResourceBundle, the OPPTY_STATUS_UPDATED key is defined as:

   {"OPPTY_STATUS_UPDATED", "{actor\[0\]} updated {object\[0\]} status to {custom\['status'\].value}"}
   

   summaryByListMessageFormatKey and summaryByCountMessageFormatKey

   These attributes are used only when the Activity Stream summarized view task flow is used. The summarized view task flow is used on the portrait page in My Activities and Network Activities mini cards. In summarized view, the Activity messages are summarized or grouped based on an Activity Type. For instance, if multiple Activities of the same Type are published, they are combined and displayed as a single Activity message. Within the group of Activities of the same type, the following algorithm is used to generate summarized messages:

   1. Summarize activities by finding a common object referenced in the Activity.

   2. Summarize/aggregate the Actors either by listing them if there are 3 or fewer, or by counting them if there more than 3.

   3. For remaining activities, summarize by finding a common Actor. Summarize/aggregate the objects either by listing them if there are 3 or fewer, or by counting them if there are more than 3.

   For example, for the following activities:

   1. James updated Project Alpha tasks.

   2. Viju updated Project Alpha tasks.

   3. Ling updated Project Alpha tasks.

   4. Monty updated Oppty 200 laptops status

   5. Monty updated Oppty solaris workstations status

   6. Monty updated Oppty 2 DB machines status.

   In the summarized view, the Activities are summarized as follows:

   • Activities a-c : James, Viju, Ling updated Project Alpha tasks.

   • Activities d-f: Monty updated 200 laptops, solaris workstations, 2 DB machines opportunities status.

   Example 14-54 shows sample format strings for the above scenario.

   Example 14-54 Sample Format Strings for a Summarized View

   <resource-bundle-class>oracle.apps.crm.OpportunityResourceBundle</resource-bundle-class>
    <activity-types>
      <generic-activity-category name="OPPTYUPDATE">
        <activity-type name="OpptyStatusUpdate"
                  displayName="OPPTY_UPDATE"
                  description="OPPTY_UPDATE_DESCRIPTION"
                  messageFormatKey="OPPTY_STATUS_UPDATED"
                  summaryByListMessageFormatKey="OPPTY_STATUS_UPDATED_SUMMARY_LIST"
                  summaryByCountMessageFormatKey="OPPTY_STATUS_UPDATED_SUMMARY_CNT"
                  defaultPermissionLevel="SHARED"/>
       </generic-activity-category>
    </activity-types>
   

   In OpportunityResourceBundle, the keys are defined as:

   {"OPPTY_STATUS_UPDATED_SUMMARY_LIST", "{actor\[0\]} updated status for opportunity {object\[0\]} }"}
   {"OPPTY_STATUS_UPDATED_SUMMARY_CNT", "{actor\[0\]} updated {object\[0\].count} opportunities status"}
   

6. Define an object type for the Entity Object that is the source of the events. Even though WebCenter supports multiple object types, for Oracle Fusion Applications, only one object type that corresponds to the source of the events is supported. The value of the name attribute should match the name of the attribute in the Business Event's payload. This attribute's value will be used as the display name of the object when displayed in the Activity message. The primary key of the event source will be used as the object id.

   <object-types>
      <object-type name="OpptyId"
                   displayName="Opportunity Object"
                   description="Opportunity Object"
                   iconURL="">
      </object-type>
   </object-types>
   

7. ObjectType custom attributes can be used to provide additional metadata for handling business object references in Activity Stream messages. The custom attributes shown in Table 14-10 will be used.

   Table 14-10 ObjectType Custom Attributes

   Name	Description
   service-ref-id	id of the service-definition of a Business Object referenced in the Activity Message of the current Business Object. This is used when an Activity Message contains multiple object references and used to reference serviceId of some other Business Object.
   object-id-attr	The name of the attribute in the business event payload that should be used as the object-id for an Activity object. Typically this corresponds to the primary key attribute of a Business Object. If this attribute is not specified, the object-type element's name attribute is used as the default.
   display-name-attr	The name of the attribute in the business event payload that should be used as the display name of the Activity object. This attribute's value will be used to replace the {object} token in the Activity's message format.

   
   

   <object-type>
     <custom-attributes>
       <custom-attribute name="service-ref-id" defaultValue="oracle.apps.crm.model.OpptyEO"/>
       <custom-attribute name="object-id-attr" defaultValue="opptyId"/>
       <custom-attribute name="display-name-attr" defaultValue="opptyName"/>
     </custom-attributes>
   </object-type>
   

8. Define resource view handler parameters to allow custom navigation for links rendered in the Activity message. Navigation from the Actor link in the Activity message navigates to the user's portrait page. Custom navigation to the Business Object workarea is supported. Important fields include:

   • taskFlowId: The task flow where you want to go.

   • resourceParamList: The list of parameters that you want to pass to the task flow. For example, if a Business Object task flow takes the opptyId parameter, in resourceParamList you should specify "opptyId". If multiple parameters are required, the parameters should be separated by a semi-colon (;), for example "opptyId;opptyType". When the hyper link is clicked, parameters opptyId="oppty id value" and opptyType="type value" will be passed as input parameters to the task flow.

     <resource-view taskFlowId="/WEB-INF/OpportunityTF.xml#OpportunityTF">
       <parameters>
         <parameter name="viewId" value="Opportunity"/>
         <parameter name="webApp" value="CRMApp"/>
         <parameter name="pageParametersList" value=""/>
         <parameter name="taskParametersList" value=""/>
         <parameter name="resourceParamList" value="opptyId"/>
       </parameters>
     </resource-view>
     

     Custom navigation is handled by the Applications Core ResourceViewHandler registered in adf-config.xml. You must add this entry to all adf-config.xml files:

     <wpsC:adf-service-config xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service">
         <resource-handler class="oracle.apps.fnd.applcore.tags.handler.FndResourceActionViewHandler"/>
     </wpsC:adf-service-config>
     

14.14.7.1 Defining the Service Category

The Follow model is enforced for Activity Messages when the category-id of a service contains "business" in its name. A sample service-category-definition and its reference in service-definition are provided in Example 14-56 and Example 14-57.

Note that the id in the service-category-definition file matches the category-id in service-definition.xml and it contains "business".

<service-category-definition xmlns="http://xmlns.oracle.com/webcenter">
 <category id="oracle.apps.fnd.applcore.crmdemo.model.business.CasesEO"
           resourceBundle="oracle.apps.fnd.applcore.crmdemo.BusinessActivityServiceResourceBundle"
           titleKey="CASE_SERVICE_CATEGORY"
           icon="/a/s/g.gif"/>
</service-category-definition>

<category-id>oracle.apps.fnd.applcore.crmdemo.model.business.CasesEO</category-id>

14.14.7.2 Adding ActivityTypes for Follow and Unfollow

The ActivityTypes shown in Example 14-58 should be added to the service-definitions of all services that use the Follow model. These ActivityTypes are used to construct the message published when an object belonging to the service is Followed or Unfollowed.

<activity-type name="followObject"
   displayName="Follow Object"
   messageFormatKey="ACTIVITY_FOLLOW_OBJECT_MSG"
   description="Follow Object">
</activity-type>
 
<activity-type name="unfollowObject"
   displayName="Unfollow Object"
   messageFormatKey="ACTIVITY_UNFOLLOW_OBJECT_MSG"
   description="Unfollow Object">
</activity-type>

14.15.2.1 Search Results

After clicking Search, a modal dialog will display the results of the search. Hovering over the main link will show the last crawled date. Figure 14-54 shows typical results.

Figure 14-54 Search Results Example

To improve performance, the result set size is limited to 10.

The Search Results display consists of:

• A repetition of the fields displayed in the global area.

• A Filter Tree of Categories: Selected filter values will be applied to the search results. A remove filter icon will appear next to a filter value that has been added. Clicking this icon will remove the filter from the search criteria.

  A category is a group of related objects. Examples include any Oracle Fusion business object, and WebCenter objects such as wikis and blogs.

  Searchable Object is the second level. A searchable object is the view object.

  Facets are formed by the Lists of Values defined on an attribute in the Searchable Object. There may be many facets for a Searchable Object, and the facets may be hierarchical, such as is the case in Figure 14-54, where a State facet contains a City facet, which contains a County facet. Only the name of the highest level facet in the hierarchy is shown.

• A Results section. On the initial query, all selected Categories will be displayed. Only the first category will be displayed expanded. The other Categories will need to be manually expanded.

  Each result found under a category provides a navigation link back to the record.

Result Counts Do Not Add Up

It is possible when viewing the search results, and narrowing your selections using the facet tree, to see counts against the nodes that do not add up. For example, a search on Glasses might return 16. Then if you filter the result by color, you may find Blue (5) and Red (10), which do not add up to 16. This count is the Oracle Secure Enterprise Search (SES) Approximate count based on heuristics, and not an exact count. To make the count exact, launch SES and select Global Settings > Query Configuration, and click the Exact count radio button, as shown in Figure 14-55. Note that SES warns against this for performance reasons. See the Oracle Secure Enterprise Search Administration Online Help.

Figure 14-55 Setting the Exact Hit Count in SES

14.15.3.1 Using the Search API

Create the component and have an actionListener to a backing bean, as shown in Example 14-61. Note that GlobalSearchUtilBean is just an example, not a real bean.

<af:commandButton text="commandButton 1"
          actionListener="#{backingBeanScope.GlobalSearchUtilBean.runSearch}">
</af:commandButton>

From that backing bean, you can call the Oracle Fusion Applications Search API to run the search, as shown in Example 14-62.

public class GlobalSearchUtilBean {
    public GlobalSearchUtilBean()
    {
    }
    public void runSearch(ActionEvent actionEvent)
    {
      List<SearchCategory> categories =GlobalSearchUtil.getCategories();
      // manipulate search category list here
      String searchString = "some search string";
      GlobalSearchUtil.runSearch(categories, searchString, actionEvent);
    }
}

14.15.3.2 Running the Oracle Fusion Applications Search UI Under WebLogic Server

For details of running the ECSF artifacts, such as the SearchFeedServlet, see Chapter 27, "Creating Searchable Objects."

To run the UI Shell and Oracle Fusion Applications Search, follow the setup instructions for running Applications Core under WebLogic Server in Chapter 2, "Setting Up Your Development Environment" and the instructions on how to set up a UI Shell page, menu entries and task flows from Section 14.1, "Introduction to Implementing the UI Shell". This should give you a running UI Shell project.

Add the SearchDB database connection to the project. For more information about creating the SearchDB connection, see Section 31.5.1, "How to Create the SearchDB Connection on Oracle WebLogic Server Instance".

14.15.6.1 Implementing the URL Action Type

Figure 14-62 shows a URL Action.

Figure 14-62 Search Result Actions - URL Action

For URL Action Types, the Oracle Fusion Applications Search will open a new browser tab or window containing the URL. To configure this type, add a URL Search Result Action with these parameters.

• A unique name

• Action Type of URL

• An Action Target to the required destination, including groovy substitution parameters

• A Title

No Parameters are required; however a single iconURL parameter may be defined if an icon is required for the URL action. See Table 14-12.

This will be shown in the search results with the title given in the Title field. When clicked, a new browser tab or window will open with this URL.

14.15.6.2 Implementing the Task Action Type

Figure 14-63 shows a Task Action.

Figure 14-63 Search Result Actions - Task Action

For Action Types of Task, the Oracle Fusion Applications Search will open a UI Shell tab in the current page, or a new page containing the task flow. To configure this type, add a Task Search Result Action with these parameters.

• A unique name

• Action Type of Task

• A Title

• Parameters are shown in Table 14-13. Note that, although this table resembles Table 14-14, it presents the use case that the majority of users will use. The information in Table 14-14 is for a very small use case.

  This will be shown in the search results with the title given in the Title field. When clicked, a new UI Shell tab window will open with this task flow. If the viewId parameter is for the current page, the UI Shell tab will be in the current page; otherwise the current page will be replaced with a new UI Shell page with the search result.

  Note:

  Do not enter double quotes around the groovy expressions; use single quotes instead.

  Table 14-13 Task Action Type Parameters

  Name	Required	Description
  viewId	Y	Name of the page. This is shown in the browser URL bar. For example, in http://127.0.0.1:8989/context-root/faces/TestUIShellPage, it would be "/TestUIShellPage" (Note the leading slash).
  pageParametersList	N	Parameters list for the page. This is a semicolon delimited String of name value pairs. For example, "param1=value1;param2=value2"
  taskFile	Y	Name of the task definition file. For example, /WEB-INF/task-flow-definition.xml. See Section 14.15.6.3, "Passing Parameters in Oracle Fusion Applications Search".
  taskName	Y	The task flow definition id. Available from the task definition file <task-flow-definition> id attribute. For example, <task-flow-definition id='task-flow-definition'> would be "task-flow-definition". See Section 14.15.6.3, "Passing Parameters in Oracle Fusion Applications Search".
  navTaskKeyList	N	Key list to pass into the task flow to open in the target workspace. This is a semicolon delimited keys or key-value pairs. For example "key1;key2=value2"
  navTaskParametersList	N	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"
  iconURL	N	URL of icon to show next to the Action. Can be a relative reference such as '/media/search/mime_doc.gif' or a full URL such as 'http://host:port/path/to/icon.gif'
  toolTip	N	Tooltip of action. This also is available for URL actions.
  navTaskLabel	N	Label to show on the results tab. (Set the tab title of the tab that is opened after clicking a search result action.) If unset, it will use the Action Name (the value shown in the results).
  webApp	Y	The webApp attribute is used to look up the host and port of the associated WorkArea or Dashboard from the ASK deployment tables. These tables are populated at deployment time through Functional Setup tasks.

  
  

14.15.6.3 Passing Parameters in Oracle Fusion Applications Search

Normally, taskFlowID uses the format <path><name>.xml#<name>; for instance taskFlowID="/WEB-INF/CaseDetails.xml#CaseDetails". However, Oracle Fusion Applications Search has taskFile and taskName attributes as shown in Figure 14-63. The Oracle Fusion Applications Search code will merge them, adding the "#," so they become <taskFile>#<taskName>.

Parameters are always passed as Parameter Name=value. Often, it is either a literal value or an expression such as #{pageFlowScope.val}. Example 14-67 shows how it is done, passing four parameters.

<SearchResultActions>
  <Action
    Name="View Lookup Type"
    ActionType="Task"
    DefaultAction="true">
    <Title>
      <![CDATA["Lookup: " + Meaning]]>
    </Title>
    <ActionTarget>
      <![CDATA[null]]>
    </ActionTarget>
    <Parameters>
      <Parameter Name="navTaskParametersList">
        <Value>
          <![CDATA["lookupType=" + LookupType + ";viewApplicationId=" + ViewApplicationId + ";language=US;meaning=" + Meaning]]>
        </Value>
      </Parameter>
      <Parameter Name="webApp">
        <Value>
          <![CDATA['GlobalSearch']]>
        </Value>
      </Parameter>
      <Parameter Name="TaskFile">
        <Value>
          <![CDATA["/WEB-INF/LookupTypeSearchResultsTaskFlow.xml"]]>
        </Value>
      </Parameter>
      <Parameter Name="navTaskKeyList">
        <Value>
          <![CDATA["meaning=" + Meaning]]>
        </Value>
      </Parameter>
      <Parameter Name="TaskName">
        <Value>
          <![CDATA["LookupTypeSearchResultsTaskFlow"]]>
        </Value>
      </Parameter>
      <Parameter Name="viewId">
        <Value>
          <![CDATA["TestUIShellPage"]]>
        </Value>
      </Parameter>
    </Parameters>
  </Action>

14.15.6.4 Ordering the Other Actions

In the ECSF search UI in JDeveloper, it is possible to define no action, or a single default action.

If a default action is defined, it will be used. The other actions will be shown in sorted order based on task title. If no default action is defined, the first sorted action will be used as the default action.

This sorting mechanism is used as there is no way, using the current ECSF APIs, to provide a stable order of actions.

Due to this sorting mechanism, it is strongly recommended to have stable, sortable task titles (they may be groovy bound and therefore mutate based on an individual search result) to prevent confusing the end user.

14.15.6.5 Using Click Path and the Saved Search

When the user is using Oracle Fusion Applications Search prior to saving a search, he or she may perform a number of interactions with the UI including:

• Expanding the attribute filters by selection (performs searches)

• Narrowing the search terms

• Opening unsearched groups (which performs searches in those groups)

• Scrolling through results in a group

This is called the click path of the user.

When a search is saved, some of this information (the structural part at the tip of the click path) is saved, but prior actions and exact scroll positions are not. This means that when running a saved search, the following is not restored to the user:

• Exact expanded groups in the result at the time of save

• Scroll positions within a group

• Full LOV expansion state of attribute filters

When ECSF returns facet information, it returns only facet entries for the level below that which is selected. For example, if there are no filters, the facets will be shown correctly with one level of detail. If a first level facet is selected, that selection will be shown, but not its siblings. If there are facets below that level, this next level will be shown as these are returned. As the user starts to refine/expand the attribute filters, the search filters will be filled-in based on this new click path.

14.15.7.1 Oracle Business Intelligence Integration

Oracle Business Intelligence results will be shown in a results area separate from Oracle Fusion Applications Search view object results. To implement this separation, Oracle Fusion Applications Search shows results in a multi-tab format.

The tabs are named Applications, where all Search view objects and Oracle WebCenter results will reside, and Business Intelligence. The split is performed at a category (or searchable groups) level, so you will see a consolidated list of categories in the multi-select category dropdown. These categories are split at search time.

The business rule that splits categories into the Oracle Business Intelligence table is lower-case category_name, such as bi_%.

Although the formatting of Oracle Business Intelligence results will be slightly different, no developer uptake is required.

Oracle Secure Enterprise Search (SES) Setup

• Source

  See the Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Enterprise Edition for how to create your Oracle Business Intelligence source. Define a source based on the Oracle EBusiness Suite R12, and give the following parameters:

  SES Source Configuration:
  Configuration URL: http://10.156.30.40:9704/bisearch/crawler/oracle.biee.search.BISearchableTreeObject/ConfigFeed?forceInitialCrawl=true
  User ID: Administrator
  Password: Admin123
   
  Authorization Tab:
  HTTP endpoint for authorization: http://10.156.30.40:9704/bisearch/crawler/SecurityService
  User ID: Administrator
  Password: Admin123
  Business Component: oracle.biee.search.BISearchableTreeObject
  Display URL Prefix: http://10.156.30.40:9704/bisearch/urlbuilder
   
  where the IP address is your Oracle Business Intelligence server installation, and the username/password are for a sufficiently authorized Oracle Business Intelligence user.
   
  Leave all other values at default.
  

• Source Group

  Create a source group (SES Searchtab > Source groups) and name it bi_<some code name>.

  It must start with bi_ so Oracle Fusion Applications Search can recognize it as an Oracle Business Intelligence category.

  You may go into Global Settings and translate the group name so the users see a more friendly name.

  Import the group as an external category into ECSF. See "Importing Source Group into ECSF".

• Searching

  When Searching, the Oracle Business Intelligence results will display in a separate tab, as shown in Figure 14-64.

  Figure 14-64 Oracle Business Intelligence Search Results in New Tab

  
  

  If there are only Oracle Business Intelligence, or only Oracle Fusion Applications/Oracle WebCenter categories selected, only the one tab appropriate to those categories displays. Otherwise, you can search both and tab between the results.

  When you click a link, you will be redirected to Oracle Business Intelligence. If you do not have a consolidated OID setup, you will be asked to log in again.

14.15.7.2 Integrating the Oracle WebCenter

To set up and crawl an Oracle WebCenter environment, see "Managing the Search Service" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter and then import the searchable objects into ECSF as external categories.

Importing Source Group into ECSF

The group now should be searchable from within the SES Search UI.

To allow the group to be searchable from Oracle Fusion Applications Search, it needs to be imported via the cmdLineAdmin tool or Oracle Enterprise Manager Fusion Middleware Control. Follow these steps if you use the tool:

1. Launch the cmdLineAdmin tool. Its prompt will display.

2. Issue this command at the prompt:

   > manage instance 124 (where 124 differs for each developer).

   The prompt will change to show that an instance is being managed.

3. Enter this command:

   Instance: 124> list external categories

   This information displays:

   List of External Categories for Instance with ID 124:
   ---------------------------------------------------
   ID               | Name                           |
   ---------------------------------------------------
   100000000013878  | bi_SearchableTreeDirectory     |
   100000000013879  | WebCenter                      |
   

4. Enter this command:

   Instance: 124> import external categories

   This command should return an Import successful message.

5. Enter this command:

   Instance: 124> list external categories

   This information displays:

   List of External Categories for Instance with ID 124:
   List of External Categories for Instance with ID 124:
   ---------------------------------------------------
   ID               | Name                           |
   ---------------------------------------------------
   100000000014896  | bi_SearchableTreeDirectory     |
   100000000014897  | WebCenter Jive Forums          |
   100000000014898  | WebCenter Jive Announcements   |
   100000000014899  | WebCenter                      |
   

14.15.7.3 Ensuring Parity of Users

Users must be defined in multiple applications if you do not have a single authentication store.

Ensure you have a user defined that is common across both Oracle Fusion Applications and Oracle WebCenter.

For instance, you can create an fmwadmin user on the Oracle Fusion Applications side to do this by adding to the jazn-data.xml file.

With Oracle Secure Enterprise Search (SES) Authentication pointing to the ECSF SearchFeedServlet, which is using the WebLogic Server container security, this user will be verified by the SES authentication callbacks.

In a true enterprise environment, both the Oracle Fusion Applications web container and Oracle WebCenter would be set up with the same OID.

Using two different authentication stores will mean you get multiple logins when clicking results.

14.19.1.1 Developer Implementation

Enable the Bookmarkable property on the view activity for the single object context page and specify the URL parameter names with the corresponding fndPageParams viewScope Hashmap key where the value should be stored. See the "How to Create a Bookmarkable View Activity" section in Chapter 15, "Working with Task Flow Activities," of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Example 14-77 shows a sample entry in adfc-config.xml for such a view activity.

<view id="SingleDeptContextPage">
 <page>/oracle/apps/empdeptdemo/ui/page/SingleDeptContextPage.jspx</page>
 <bookmark>
  <url-parameter>
   <name>Deptno</name>
   <value>#{viewScope.fndPageParams.Deptno}</value>
  </url-parameter>
 </bookmark>
</view>

Product teams must create a bounded task flow for the Context Area that appears at the top of the page. This task flow must accept the context values as input parameters. This task flow is dropped as a static region onto the Context Area facet in the JSPX page based on the UI Shell template. In the task flow binding, set the input parameter values to the corresponding key in fndPageParms viewScope Hashmap.

Example 14-78 shows a sample entry in the page definition for the JSPX file for passing the viewScope values into the Context Area task flow as input parameter.

<taskFlow id="ContextDeptSummary1"
              taskFlowId="/WEB-INF/oracle/apps/empdeptdemo/ui/flow/ContextDeptSummary.xml#ContextDeptSummary"
              xmlns="http://xmlns.oracle.com/adf/controller/binding">
      <parameters>
        <parameter id="Deptno" value="#{viewScope.fndPageParams['Deptno']}"
                   xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
      </parameters>
    </taskFlow>

The UI Shell code passes this viewScope Hashmap onto the pageFlowScope of the main area and regional area task flows. Product team task flows, which are initialized in the regional and main area, can access this in pageFlowScope (of main/regional area container task flow owned by Applications Core) for the appropriate input parameters through the menu model and openMainTask API.

Example 14-79 shows a sample entry for a child item node for defaultMain task in the menu.xml to pass the appropriate deptno in the single object context to a task flow that is initialized based on this input value.

<itemNode id="SingleDeptContextPage_EmpListingDefaultTab"
              focusViewId="/SingleDeptContextPage"
              label="#{adfBundle['oracle.apps.empdeptdemo.ui.test_menuBundle'].EMPLOYEE_LISTING}"
              taskType="defaultMain" reuseInstance="false"
              taskFlowId="/WEB-INF/oracle/apps/empdeptdemo/ui/flow/ContainerTF.xml#ContainerTF"
              parametersList="Deptno=#{pageFlowScope.fndPageParams['Deptno']}"/>

Product teams can cause URL navigation (through the navigate data control method provided by UI Shell) for changing context or after updating context information. This will cause the entire page to be refreshed based on new context parameter values.

Product teams can also check for the input parameter values within the pageFlowScope of the context area task flow. If invalid, a modal dialog can be launched for the end user to choose a context (by providing links based on the navigate data control method provided by the UI Shell by passing required parameters in the pageParametersList) before proceeding. This can be achieved by defining an invoke action executable in the page def for the context area page fragment which checks for existence of the pageFlowScope value and programmatically shows a modal dialog for the user to choose the context. The other alternative is to use this approach to cause navigation to a completely different page where the user can select the context.

Also, it is important to note that all the bounded task flows that will be initialized in the Single Object Context Workarea need to check for input parameter values and show/query data ONLY if the input parameter values are passed. Basically, if the input parameter values are empty, the task flows handle that, such as in a router activity, and avoid showing any transaction data to the end user.