openSubTask and closeSubTask APIs

openSubTask and openMainTask seem to be related and have similar parameter lists. However, they behave differently and are used for different purposes. This article examines what openSubTask and closeSubTask does in details.

In a nutshell, openSubTask and closeSubTask APIs are programmatic support in Oracle Applications Core to notify recent items about a sub-flow launch.

Recent Items and Favorites^[1]

Recent Items in Oracle Fusion Web Applications tracks a list of the last 20 task flows visited by a user. The Recent Items list is persistent across user sessions and a task can be relaunched from the Recent Items list.

The Favorites menu is implemented on top of Recent Items. Any current task on the Recent Items list can be bookmarked and placed in Favorites' folders.

openMainTask and closeMainTask

Both openMainTask and openSubTask (or their close counterparts) are provided on FndUIShellController ^[2]data control. At design time, you can drag and drop both operations to UI components (for example, your page fragments) to create needed bindings objects in XML meta data files:

openMainTask is used to open a new Task in the Main Area of Oracle Fusion Web Applications that use UIShell templates^[5]. Besides opening a new tab, openMainTask also pushes a new Task Flow History object onto a stack, which is used to keep track of all task flows that have been opened. The Task Flow ID and its associated parameter values are encapsulated in the Task Flow History object.

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 re-initializes the Main Area with that Task Flow and parameter information.

Sub-Flow

When a task flow is called from the local area task flow via task flow call activity, it is called a 'sub-flow'. By default, subflows will not be recorded on the stack as described above. Two new APIs^[3] are exposed in FndUIShellController^[2] data control for registering sub-flows:

• openSubTask
• closeSubTask.

openSubTask and closeSubTask

When openSubTask is called before a sub-flow is launched, sub-flow ID and its parameter values are pushed onto the stack. Besides that, Applications Core implementation also notifies Recent Items & Favorites^[1] (or RI & Favs) implementation with recorded task flow information. Once tasks are recorded on the Recent Items list, they are also eligible for Favorites.
This essentially makes a sub-flow bookmarkable by RI & Favs and can be launched directly from the selection of menu items on Recent Items.
When a sub flow finishes execution, it should call closeSubTask on all of its exit paths. What closeSubTask API does is:

if topOfStack is SUB_FLOW type {
  Pop it from the stack;
  Notify RI&Favs for the new topOfStack entry;
} else {
  Look inside the stack to find a match based on sub flow ID and its keyList;
  if (found the first one) {
    Remove it from the Stack;
    Notify RI&Favs for the new topOfStack entry;
  }
}

Contextual events are fired when openSubTask or closeSubTask excute. The method outcome (i.e., sub-flow information encapsulated in FndMethodParameters) is delivered as the contextual event payload.
For openSubTask, an FND_OPEN_SUB_TASK event is fired and the event consumer is handleOpenSubTaskEvent method on the MainAreaHandler object.
Similarly, a FND_CLOSE_SUB_TASK event is fired when closeSubTask method executes and the event consumer is handleCloseSubTaskEvent method on the MainAreaHandler object. The main functionality of openSubTask and closeSubTask from the Applications Core side are both implemented in these event handlers.
When RI & Favs is notified with a new task flow, it does the following:

if user session (i.e., FND session) is not enabled or user is anonymous {
  do nothing and return;
}
if any of the following is not set, do nothing and return:
  Task flow ID
  Task flow label
  Task flow view ID
  Task flow webApp name
if an existing task flow on the RI list matches the new task flow based on the following condition:
  Same Task flow ID
  Same Task flow label
  Same Task flow view ID
  Same webApp name
  Same reuseInstance value
  Same keyList
then
Remove it from the list and move it to the top and update its information with new entry
else
  Add a new task flow history object to the list

Hope this article can help Oracle Fusion Developers to understand more on the functionality of Recent Items and Favorites within Oracle Fusion Web Applications. However, the details provided here are based on author's own understanding of Recent Items and Favorites implementation. These implementation details may evolve over time and there is no guarantee that they will remain valid in the future.

References

1. Implementing Recent Items
2. FndUIShellController
3. openSubTask and closeSubTask
4. openMainTask
5. Implementing the UI Shell
6. Oracle ADF Task Flow in a Nutshell