Working with Task Flow Activities

24 Working with Task Flow Activities

This chapter describes how to use activities in ADF task flows that you create in your Fusion web application. The chapter contains detailed information about each task flow activity type that displays in the Components window in addition to describing the properties that you can configure for each task flow activity type.

This chapter includes the following sections:

About Task Flow Activities

The ADF task flow activity is a module or independent set of tasks to be executed to complete a task. You can add activities to both bounded and unbounded task flows; however, certain activities can only be added to a bounded task flow.

An activity represents a piece of work that is performed when the task flow runs. It displays in the task flow's diagram editor as a node. You can add most activities to both bounded and unbounded task flows, although some activity types can be added only to bounded task flows.

Figure 24-1 shows the emp-reg-task-flow-definition.xml bounded task flow from the Summit sample application for ADF task flows. This task flow contains the following activities:

A method call activity that invokes a CreateInsert action
A view activity that renders a page fragment where end users can enter general information about the employee to be created
A view activity that renders a page fragment where a confirmation message appears if the end user successfully creates the new employee

Figure 24-1 Bounded Task Flow with Task Flow Activities

This image is described in the surrounding text

A task flow consists of activities and control flow cases that define the transitions between activities. Table 24-1 describes the types of activities and control flows you can add to a task flow by dragging and dropping from the Components window.

Table 24-1 Task Flow Activities and Control Flows

Icon	Component Name	Description
	Method Call	Invokes a method, typically a method on a managed bean. A method call activity can be placed anywhere within an application's control flow to invoke application logic based on control flow rules. See Using Method Call Activities.
	Parent Action	Allows a bounded task flow to generate outcomes that are passed to its parent view activity. Typically used for a bounded task flow running in an ADF region that needs to trigger navigation of its parent view activity. See Navigating Outside an ADF Region's Task Flow.
	Router	Evaluates an EL expression and returns an outcome based on the value of the expression. For example, a router in a credit check task flow might evaluate the return value from a previous method call and generate success, failure, or retry outcomes based on various cases. These outcomes can then be used to route control to other activities in the task flow. See Using Router Activities.
	Save Point Restore	Restores a previous persistent save point, including application state and data, in an application supporting save for later functionality. A save point captures a snapshot of the Fusion web application at a specific instance. Save point restore enables the application to restore whatever was captured when the save point was originally created. See Using Save Points in Task Flows.
	Task Flow Call	Calls a bounded task flow from the unbounded task flow or another bounded task flow. See Using Task Flow Call Activities.
	Task Flow Return	Identifies when a bounded task flow completes and sends control flow back to the caller. (Available for bounded task flows only). See Using Task Flow Return Activities .
	URL View	Redirects the root view port (for example, a browser page) to any URL-addressable resource, even from within the context of an ADF region. For more information see Using URL View Activities.
	View	Displays a JSF page or page fragment. Multiple view activities can represent the same page or same page fragment. See Using View Activities for more information. For more information about pages and page fragments, see Creating a Web Page.
	Control Flow Case	Identifies how control passes from one activity to the next in the application. See About Control Flows.
	Wildcard Control Flow Rule	Represents a control flow case that can originate from any activities whose IDs match a wildcard expression. For example, it can represent a control case `from-activity-id` containing a trailing wildcard such as `foo*`. See How to Add a Wildcard Control Flow Rule .

Table 24-2 describes the annotations (notes and attachments) you can add to a task flow.

Table 24-2 Task Flow Diagram Annotations

Icon	Icon Name	Description
	Note	Adds a note to the task flow diagram. You can choose the note in the diagram to add or edit text.
	Note Attachment	Attaches an existing note to an activity or a control flow case in the diagram.

Task Flow Activities Use Cases and Examples

Figure 24-2 shows the diagram for the customer task flow in the Summit ADF task flow sample application. This task flow uses a number of the activities that a bounded task flow supports in order to complete a task. For more information about the Summit ADF sample applications, see Introduction to the ADF Sample Application.

Figure 24-2 Customers Task Flow in the Summit ADF Task Flow Sample Application

Description of "Figure 24-2 Customers Task Flow in the Summit ADF Task Flow Sample Application "

Additional Functionality for Task Flow Activities

You may find it helpful to understand other Oracle ADF features before you configure or use task flow activities. Additionally, you may want to read about what you can do with your configured task flows. Following are links to other functionality that may be of interest.

Task flows can invoke managed beans. For more information about managed beans, see Using a Managed Bean in a Fusion Web Application.
Bounded task flows can be secured by defining the privileges that are required for someone to use them. For more information, see Enabling ADF Security in a Fusion Web Application.
Bounded task flows can be packaged in ADF Library JARs. For more information, see Packaging a Reusable ADF Component into an ADF Library.
Task flow activities can be associated with page definition files. For more information about page definition files, see Working with Page Definition Files.

Using View Activities

The ADF task view activity allows you to display a JSF page or a page fragment. At runtime, you can transfer the control from one task flow to another. Users can bookmark a view activity within an unbounded task flow. Also, you can allow users to visit a URL by configuring a view activity.

One of the primary types of task flow activity is the view activity. A view activity displays a JSF page or page fragment. A page fragment is a JSF document that renders as content in another JSF page. Page fragments are typically used in bounded task flows that can be added to a JSF page as a region, as described in Creating an ADF Region.

Figure 24-3 shows the index view activity in the Summit ADF task flow sample application.

Figure 24-3 View Activity

Tip:

Click the + icon in the upper-left part of the view activity to see a thumbnail preview of the referenced page or page fragment.

XML metadata in the source file of the task flow associates a view activity with a physical JSF page or page fragment. An id attribute identifies the view activity. The <page> element identifies the page or page fragment's file name. The following example shows the metadata that corresponds to the view activity in Figure 24-3:

<view id="index">
   <page>/index.jsf</page>
 </view>

The view activity ID and page name do not have to be the same.

The steps for adding a view activity to a task flow are the same as those for adding any activity to a task flow diagram. For more information, see How to Add an Activity to a Task Flow. After you add the view activity, you can double-click it to display a wizard that allows you to create a new page or page fragment. The wizard allows you to choose between one of the following two document types for the JSF page or page fragments that you create:

Facelets

The file extension for pages in this document type is .jsf and .jsff for page fragments.
JSP XML

The file extension for pages in this document type is .jspx and .jsff for page fragments.

Use one document type only in your task flows. For example, do not use the Facelets document type for view activities in one task flow and the JSP XML document type for view activities in another task flow. For more information about the document types, see Implementing the User Interface with JSF.

You also use the wizard to choose the page layout for the page or page fragment that you create. For more information about page layouts, see the "Using Quick Start Layouts" section in Developing Web User Interfaces with Oracle ADF Faces. In addition, you can specify whether or not to automatically expose UI components on the page or page fragment in a managed bean. For more information, see Using a Managed Bean in a Fusion Web Application.

After you complete the wizard, JDeveloper automatically associates the completed page or page fragment with the view activity. As an alternative to using the wizard, you can associate a page or page fragment with a view activity by dragging an existing page or page fragment from the Applications window and dropping it on top of an existing view activity. If no view activity exists, drag a page or page fragment to any other location on the diagram. When you drop the page or page fragment, JDeveloper automatically creates a new view activity associated with the page or page fragment. During creation, a default id for the view activity is automatically generated (for example index) based on the name of the page or page fragment.

Passing Control Between View Activities

You can configure view activities in your task flow to pass control to each other at runtime. For example, to pass control from one view activity (view activity A) to a second view activity (view activity B), you could configure a command component (a button or a link) on the page associated with view activity A. Set the command component's Action attribute to the control flow case from-outcome that corresponds to the task flow activity that you want to invoke (for example, view activity B). At runtime, the end user initiates the control flow case by invoking the command component. You can navigate from a view activity to another activity using either a constant or dynamic value on the Action attribute of the UI component.

A constant value of the component's Action attribute is an action outcome, as shown in Figure 24-4, that always triggers the same control flow case. When an end user clicks the component, the activity specified in the control flow case is performed. There are no alternative control flows.

Figure 24-4 Edit Property Dialog

Description of "Figure 24-4 Edit Property Dialog"

A dynamic value of the component's Action attribute is bound to a managed bean or a method. The value returned by the method binding determines the next control flow case to invoke. For example, a method might verify user input on a page and return one value if the input is valid and another value if the input is invalid. Each of these different action values trigger different navigation cases, causing the application to navigate to one of two possible target pages.

You can also write an EL expression that must evaluate to true before control passes to the target view activity. You write the EL expression as a value for the <if> child element of the control flow case in the task flow. For more information, see How to Add a Control Flow Rule to a Task Flow.

How to Pass Control Between View Activities

You pass control to a view activity by specifying the value of the control flow case's from-outcome attribute as the value for the action attribute of the command component.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you configure the passing of control between view activities. For more information, see Passing Control Between View Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

You will need to complete these tasks:

Create a target view activity to receive control after an end user invokes the command component at runtime
Create a JSF page that will host a command component for the end user to invoke at runtime

To pass control to a view activity:

In the Applications window, double-click the JSF page.
In the editor window, use one of the following options to add a UI component to the JSF page:
- In the ADF Faces page of the Components window, from the General Controls panel, drag a navigation UI component, such as Button or Link, and drop it onto the page.
- From the Data Controls panel, drag and drop an operation or a method onto the JSF page and, from the context menu, choose ADF Button or ADF Link.
In the Properties window, expand the Common section, and select Edit in the dropdown menu that you invoke from the icon that appears when you hover over the Action property field.
In the Edit Property: Action dialog, select Action Outcome and choose a value from the associated dropdown list.

The list contains the control flow case already defined for the view activity associated with the page.

Tips:

The action attribute of the UI component can be bound either to a literal string to hard code a navigation case, or it can be bound to a method binding expression that points to a method, which takes no arguments and returns a String. It cannot be bound to any other type of EL expression.

What Happens When You Pass Control Between View Activities

The following example shows a control flow case defined in the XML source file for a bounded or unbounded task flow.

<control-flow-rule>
    <from-activity-id>Start</from-activity-id>
       <control-flow-case>
          <from-outcome>toOffices</from-outcome>
          <to-activity-id>WesternOffices</to-activity-id>
       </control-flow-case>
</control-flow-rule>

As shown in Example 24-1, a button on a JSF page associated with the Start view activity specifies toOffices as the action attribute. When the user clicks the button, control flow passes to the WesternOffices activity specified as the to-activity-id in the control flow metadata.

Example 24-1 Static Navigation Button Defined in a View Activity

<af:button text="Go" id="b1" action="toOffices">

Bookmarking View Activities

Bookmarking is available only for view activities within unbounded task flows.

When an end user bookmarks a page associated with a view activity, the URL that displays in the browser's address field for the view is saved as the bookmark. In most cases, this URL cannot be used to redisplay the page associated with the view. For example, the URL may contain state information that cannot be used to redisplay the page.

The bookmark URL should contain information that enables dynamic content on the page to be reproduced. For example, if an end user bookmarks a page displaying a customer's contact information, the bookmark URL needs to contain not only the page but also some identifier for the customer. This enables contact information for the same customer to display when the customer returns to the page using the bookmark.

To make sure that the URL for a page displayed in a browser can be used as a bookmark, identify the view activity associated with the page as bookmarkable.

At runtime, you can identify if a view activity within the unbounded task flow has been designated as bookmarkable using the isViewBookmarkable() method. The method is located off the view port context.

After you designate a view activity as bookmarkable, you can optionally specify one or more URL parameters. The value of url-parameter is an EL expression. The EL expression specifies where the parameters that will be included in the URL are retrieved when the bookmarkable URL is generated. The EL expression also stores a value from the URL when the bookmarkable URL is dereferenced. The converter option identifies a method that performs conversion and validation when parameters are passed via bookmarkable view activity URLs.

In addition, you can specify an optional method that is invoked after updating the application model with submitted URL parameter values and before rendering the view activity. You can use this method to retrieve additional information based on URL parameter key values.

The following example contains the URL syntax for a bookmarked view activity.

<server root>/<app_context>/faces/<view activity id>?<param name>=<param value>&...

The syntax of the URL for the bookmarked view activity is:

<server root>: Provided by customization at site or administrator level, for example, http://mycompany.com/internalApp.
<app context>: The web application context root, for example, myapp. The context root is the base path of a web application. For example, <app_context> maps to the physical location of the WEB-INF node on the server.
faces: The Faces servlet mapping. The value in faces points to the node containing the faces-config.xml configuration file.
<view activity id>: The identifier for the bookmarked view activity, for example, edit-customers.
<param name>: The name of the bookmarked view activity URL parameter, for example, customer-id.
<param value>: The parameter value, derived from an EL expression, for example, #{pageFlowScope.employee.id}. The value of the EL expression must be capable of being represented as a string.

Example 24-2 contains a sample URL for a bookmarkable view activity in an unbounded task flow.

Example 24-2 Sample URL for Bookmarkable View Activity

http://mycompany.com/internalApp/MyApp/faces/edit-customers?customer-id=1234&...

How to Create a Bookmarkable View Activity

To create a bookmarkable view activity, designate a view activity as bookmarkable, specify a URL parameter in the bookmark, and specify a method that is executed after the bookmark is dereferenced.

Before you begin:

It may be helpful to have an understanding of the syntax required to create a bookmarkable view activity. For more information, see Bookmarking View Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To designate a view activity as bookmarkable:

In the Applications window, expand the WEB-INF node and double-click the unbounded task flow where you want to designate a view activity as bookmarkable.
In the diagram for the unbounded task flow, choose the view activity that you want to designate as bookmarkable.
In the Properties window, expand the Bookmark section, and select true from the Bookmark dropdown list.
Enter an EL expression in the Method field to specify a method to invoke after ADF Controller updates the application model with the corresponding bookmark URL parameter values.
To add optional URL parameters to include in the URL for the bookmarked view activity, click Add and enter the URL parameter in the Bookmark URL Parameters list:
- Name: the name for the URL parameter.
- Value: A settable EL expression that, when evaluated, specifies the parameter value, for example, #{pageFlowScope.employeeID}. The value must be capable of being represented as a string.
  
  The value property is where the parameters to include in the URL are retrieved from when the bookmarkable URL is generated. In addition, parameters are stored here when the bookmarkable URL is dereferenced. If the EL expression returns NULL, the parameter is omitted from the bookmarked view activity URL. Example 24-2 shows how name and value are used to append a bookmark parameter to a view activity URL.
- Converter: (optional) Enter a value binding for the bookmark URL parameter value, for example: #{pageFlowScope.employee.idConverter}.
  
  The object that the EL expression references must implement: oracle.adf.controller.URLParameterConverter
  
  A URL parameter converter's getAsObject() method takes a single string value as its input parameter and returns an object of the appropriate type. ADF Controller invokes the converter method on the URL parameters before applying the parameter value to the application's model objects. Similarly, the URL parameter converter's getAsString() method takes an object as its input parameter and returns a string representation that is used on the URL.
  
  In a JSF application, data values are converted and validated using the converters and validators specified with the UI components on the submitting page. In a Fusion web application using a bookmarkable URL, there is no submitting page to handle conversion and validation. Therefore, you have the option of designating a converter to use for each URL parameter.

What Happens When You Designate a View as Bookmarkable

When you designate a view activity as bookmarkable, a bookmark element is added to the metadata for the view activity, as shown in the following example. The bookmark element can optionally contain metadata specifying URL parameters and a method to execute after the bookmark is dereferenced.

<view id="employee-view">
  <page>/folderA/folderB/display-employee-info.jsf</page>    
     <bookmark>
        <url-parameter>
          <name>employee-id</name>
          <value>#{pageFlowScope.employee.id}</value>
          <converter>#{pageFlowScope.employee.validateId}</converter>
        </url-parameter>
       <method>#{pageFlowScope.employee.queryData}</method>
     </bookmark>
</view>

Specifying HTTP Redirect for a View Activity

You can configure a view activity so that it redirects at runtime to a URL in response to a client request. This causes ADF Controller to create a new browser URL for the view activity. The original URL for the view activity is no longer used. You cannot configure HTTP redirect for a view activity if you have already made the view activity bookmarkable, as described in Bookmarking View Activities.

How to Specify HTTP Redirect for a View Activity

You set a view activity's redirect property to true.

Before you begin:

It may be helpful to have an understanding of the affect of setting a view activity's redirect property to true. For more information, see Specifying HTTP Redirect for a View Activity.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To specify HTTP redirect for a view activity:

In the Applications window, expand the WEB-INF node and double-click the task flow.
In the task flow diagram, select the view activity.
In the Properties window, expand the General section, and in the Redirect dropdown list, select true.

What Happens When You Specify HTTP Redirect for a View Activity

The ADF Controller issues an HTTP redirect in response to a view activity request. The redirected request creates a new browser URL for the view activity. The original view URL is no longer used.

When specified, a HTTP redirect occurs in response to a client GET request. For a client GET, the #{bindings} EL scope is invalid until ADF Controller and ADF Model set up a new bindings context for the page. Therefore, you cannot use EL expressions, such as the following, for view activities for which you specified HTTP redirect:

#{bindings.foo}

Note:

If you want http://www.mycompany.org/x.html to instead display what is at http://www.mycompany.org/y.html, do not use refresh techniques such as:

<META HTTP-EQUIV=REFRESH CONTENT="1; URL=http://www.example.org/bar">

This technique could adversely affect back button behavior. If an end user clicks a browser back button, the refresh occurs again, and navigation is forward, not backward as expected.

In this situation, use HTTP redirect instead.

Specifying URL Aliases for View Activities

The URL that a Fusion web application renders has a format that is generated at runtime based on the current context:

If the view activity is in a bounded task flow, the application renders a URL in the following format:
```
http://www.example.com/web-app-context-root/faces/task-flow-id/view-activity-ID
```
If the view activity is in an unbounded task flow, the application renders a URL in the following format:
```
http://www.example.com/web-app-context-root/faces/view-activity-ID
```

In order for end users to see a URL that may have a more meaningful name, you can specify a URL alias for a view activity. The URL alias value you specify renders instead of the default generated values. For example, in a task flow that manages data about fruit, you might have view activities to view and edit information about apples and oranges. In this scenario, your Fusion web application renders URL aliases like the following when an end user navigates to the view activity pages for apples and oranges:

http://www.example.com/web-app-context-root/faces/fruit/apples
http://www.example.com/web-app-context-root/faces/fruit/oranges

You can specify a number of different levels in URL aliases to communicate a hierarchy to end users. This means that both of the following values are valid for a view activity's URL alias:

/food/fruit/pineapple
/drink/juice/pineapple

However, the URL alias that you specify must be unique within the task flow that contains the view activity.

Specify URL aliases for view activities that render JSF pages, not JSF page fragments. This latter type of document does not render directly in the browser.

How to Specify a URL Alias for a View Activity

You specify a URL alias for a view activity by writing a value for the view activity's View-ID property (<view-id>).

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you specify a URL alias for a view activity. For more information, see Specifying URL Aliases for View Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

You will need to complete these tasks:

Create the view activity that renders a JSF page at runtime
Create the JSF page that the end user views at runtime

To specify a URL alias for a view activity:

In the Applications window, expand the WEB-INF node and double-click the task flow that contains the view activity for which you want to specify a URL alias.
In the diagram for the task flow, select the view activity for which you want to specify a URL alias.
In the Properties window, expand the General section, and enter the URL alias value in the View-ID field.

For example, enter a value in the following format:

/food/fruit/citrus/lemons

What Happens When You Specify a URL Alias for a View Activity

JDeveloper adds the value that you specify in the View-ID field to the metadata for the view activity, as shown in the following example.

<view id="view1">
    <page>/view1.jsf</page>
    <view-id>/food/fruit/citrus/lemons</view-id>
  </view>

Using URL View Activities

The ADF task flow activity can display URLs and allow users to navigate to an external resource when you use the URL view activity. You can use this activity to redirect users to a location within the same application or you can redirect users to navigate to a region out of the web application.

You can use a URL view activity to redirect the root view port (for example, a browser page) to any URL-addressable resource, even from within the context of an ADF region. URL addressable resources include:

Bounded task flows
View activities in the unbounded task flow
Addresses external to the current web application (for example, http://www.oracle.com)

To display the resource, you specify an EL expression that evaluates at runtime to generate the URL to the resource. In addition, you can specify EL expressions that, when evaluated, are added as parameters and parameter values to the URL.

A URL view activity redirects the client regardless of the view port (root view port or an ADF region) from which it is executed. The <redirect> element of a view activity performs in a similar way, except that it can be used only if the view activity is within the root view port. The <redirect> element is ignored within the context of an ADF region. See Specifying HTTP Redirect for a View Activity.

Redirecting elsewhere within the same application using URL view activities (not the <redirect> element) is handled similarly to back button navigation since the task flow stack is cleaned up. Redirecting out of the web application is handled like dereferencing a URL to a site external to the application.

How to Add a URL View Activity to a Task Flow

You can add a URL view activity to a bounded or unbounded task flow.

Before you begin:

It may be helpful to have an understanding of the affect of adding a URL view to the functionality of a task flow. For more information, see Using URL View Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To add a URL view activity to a task flow:

In the Applications window, expand the WEB-INF node and double-click the task flow to which you want to add a URL view activity.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag and drop a URL View onto the diagram.
In the Properties window, expand the General section, and enter an ID that identifies the URL view activity in the Activity ID field.
In the URL field, enter an EL expression that returns the URL at runtime. Click the icon that appears when you hover over the property field to use the Expression Builder if needed.

For example, Figure 24-5 shows a URL activity (register) in an application's myorders-task-flow.xml bounded task flow with an EL expression (#{myOrdersBean.registerNav}) that retrieves a URL at runtime.

Figure 24-5 URL View Activity
Expand the URL Parameters section to add optional URL parameters to include in the URL:
- Name: A name for the parameter.
- Value: An EL expression that, when evaluated, generates the parameter value.
- Converter: A settable EL expression that, when evaluated, specifies a method to perform conversion and validation when parameters are passed via bookmarkable view activity URLs. For more information, see Bookmarking View Activities.

What Happens When You Add a URL View Activity to a Task Flow

JDeveloper writes entries similar to those shown in the following example for the URL view activity in the source file of the task flow.

<url-view id="register">
      <url>#{myOrdersBean.registerNav}</url>
    </url-view>

What You May Need to Know About URL View Activities

Task flow URL view activities can be used within JSF portlets. Create the URL using one of the following options if you configure a task flow URL view activity for use within a JSF portlet:

Invoke one of the following methods from the ControllerContext class in the oracle.adf.controller package:
- getLocalViewActivityURL()
- getGlobalViewActivityURL()
Do not invoke the encodeActionURL() method from the ADFPortletContainerExternalContext class with the response from the getLocalViewActivityURL() or getGlobalViewActivityURL() methods before you invoke the redirect() method from the ADFPortletContainerExternalContext class. The getLocalViewActivityURL() and getGlobalViewActivityURL() methods both perform the necessary encoding of the URL.
Supply a fully qualified absolute URL.
Supply a context path relative URL.
Supply a URL relative to the current view.

A task flow URL view activity in a JSF portlet behaves as follows:

If the redirect URL refers to a location in the JSF portlet application and does not contain a queryString parameter named x_DirectLink with a value of true, the portlet in the containing page navigates to the URL specified in the URL view activity.
Otherwise, the client redirects to the URL specified in the URL view activity.

For more information about using a task flow's URL view activity, see Using URL View Activities.

For information about the methods that you can use to get a URL, see the Java API Reference for Oracle ADF Controller.

Using Router Activities

While creating a task flow you may need to direct users to the activities based on the runtime evaluation of EL expressions. The ADF router activity allows you to route such controls to the appropriate activities.

Use a router activity to route control to activities based on the runtime evaluation of EL expressions. Figure 24-6 shows a router activity (isCustomerLogin) in the customer-task-flow-definition.xml task flow from the Summit ADF task flow sample application that can branch to different control flows leading from it to different activities.

Figure 24-6 Router for Alternate Control Flow Cases

Each control flow corresponds to a different router case. Each router case uses the following elements to choose the activity to which control is next routed:

expression: an EL expression that evaluates to true or false at runtime.

The router activity returns the outcome that corresponds to the EL expression that returns true.
outcome: a value returned by the router activity if the EL expression evaluates to true, for example, customerLogin.

If the router case outcome matches a from-outcome on a control flow case, control passes to the activity that the control flow case points to. If none of the cases for the router activity evaluate to true, or if no router activity cases are specified, the outcome specified in the router Default Outcome field (if any) is used.

Figure 24-6, for example, shows a router activity that passes control flow based on the evaluation of an EL expression that determines if the user is logged in and has a specific application role. If true, control passes to the SetCurrentRowWithKeyValue method call activity. Otherwise, control passes to the Customers view activity.

Note:

Use a router activity if your routing condition can be expressed in an EL expression.

Using a router activity allows you to do more when you design the task flow that contains it. The router activity allows you to show more information about the condition on the task flow. This makes it more readable and useful to someone who looks at the diagram for your task flow.

Using a router activity also makes it easier to modify your application later. For example, you may want to modify or add a routing condition later.

How to Configure Control Flow Using a Router Activity

You define a control flow by dragging a router activity from the Components window to the diagram for the task flow. You configure the Activity ID and Default Outcome properties of the router activity and add router cases to the router activity.

Before you begin:

It may be helpful to have an understanding of the properties of a router activity that can affect functionality. For more information, see Using Router Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To configure control flow using the router activity:

In the Applications window, expand the WEB-INF node and double-click the task flow where you want to configure a control flow using a router activity.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag and drop a Router activity onto the diagram.
In the Properties window, expand the General section and enter values for the following:
- Activity ID: write a value that identifies the router activity in the task flow's source file.
- Default Outcome: specify an activity that the router activity passes control to if no control flow cases evaluate to true or if no control flow case is specified.
Click the Add icon for the Cases section and specify values for each router case that you add:
- Expression: An EL expression that evaluates to true or false at runtime.
  
  For example, to reference the value in an input text field of a view activity, write an EL expression similar to the following:
  
  #{pageFlowScope.value=='view2'}
  
  If this EL expression returns true, the router activity invokes the outcome that you specify in the Outcome field.
- Outcome: The outcome the router activity invokes if the EL expression specified by Expression returns true.
  
  Create a control flow case or a wildcard control flow rule for each outcome in the diagram of your task flow. For example, for each outcome in a control flow case, make sure that there is a corresponding from-outcome.

What Happens When You Configure Control Flow Using a Router Activity

JDeveloper writes values to the source file of the task flow based on the values that you specify for the properties of the router activity. Example 24-3 shows the values that appear in the customer-task-flow-definition.xml task flow from the Summit ADF task flow sample application that branch to different control flows leading from the router activity to different activities.

At runtime, the router activity passes control to the control flow case specified by outcome if the EL expression returns true.

Example 24-3 Router Activity in the Summit ADF Task Flow Sample Application

<router id="isCustomerLogin">
      <case id="__4">
        <expression>#{securityContext.userInRole['Application Customer Role']}</expression>
        <outcome>customerLogin</outcome>
      </case>
      <default-outcome>notCustomerLogin</default-outcome>
    </router>
...
<control-flow-case id="__7">
        <from-outcome>customerLogin</from-outcome>
        <to-activity-id>SetCurrentRowWithKeyValue</to-activity-id>
      </control-flow-case>

Using Method Call Activities

The ADF task flow allows you to call a custom method or invoke a built-in methods using method call activity. You can define the control flow to and from the method call activity. The method call outcome can be specified either as a fixed-outcome or as a to-string outcome.

Use a method call activity to call a custom or built-in method that invokes application logic from anywhere within an application's control flow. You can specify methods to perform tasks such as initialization before displaying a page, cleanup after exiting a page, exception handling, and so on.

Figure 24-7 shows the customers-task-flow-definition.xml task flow from the Summit ADF task flow sample application where the SetCurrentRowWithKeyValue method call activity invokes a setCurrentRowWithKeyValues operation from the BackOfficeAppModuleDataControl data control.

Figure 24-7 Method Call Activity to Set Row

You can set an outcome for the method that specifies a control flow case to pass control to after the method finishes. You can specify the outcome as either:

fixed-outcome: On successful completion, the method always returns this single outcome, for example, success. If the method does not complete successfully, an outcome is not returned. If the method type is void, you must specify a fixed-outcome, not a to-string.
to-string: If specified as true, the outcome is based on calling the toString() method on the Java object returned by the method. For example, if toString() returns editBasicInfo, navigation goes to a control flow case named editBasicInfo.

The following example shows the metadata for the method call activity in Figure 24-7 where the fixed-outcome element specifies setCurrentRowWithKey as the outcome to return.

<method-call id="SetCurrentRowWithKeyValue">
      <method>#{bindings.setCurrentRowWithKeyValue.execute}</method>
      <outcome>
        <fixed-outcome>setCurrentRowWithKey</fixed-outcome>
      </outcome>

For more information about control flows, see About Control Flows.

How to Add a Method Call Activity

Drag a method call activity from the Components window to the task flow diagram. You can associate the method call activity with an existing method by dropping a data control operation from the Data Controls panel directly onto the method call activity in the task flow diagram.

In the Summit ADF task flow sample application, for example, you could drag a setCurrentRowWithKey or setCurrentRowWithKeyValues operation to the diagram from the BackOfficeAppModuleDataControl data control in the Data Controls panel to create a method call activity that displays or selects the current row in a table.

Note:

Parameters for data control method parameters are defined in the page definition for the corresponding page rather than within ADF Controller metadata.

You can also drag methods and operations directly to the task flow diagram. A new method call activity is created automatically after you drop it on the diagram. You can specify an EL expression and other options for the method.

Tip:

To identify the method that a method call activity invokes, right-click the method call activity in the diagram of the task flow and choose Go to Method. JDeveloper navigates to the method that the method call activity invokes.

Before you begin:

It may be helpful to have an understanding of how the properties of a method call activity affect the functionality of a task flow. For more information, see Using Method Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

You will need to complete this task:

Create a bounded or unbounded task flow. For more information, see Creating a Task Flow.

To add a method call activity to a task flow:

In the Applications window, expand the WEB-INF node and double-click the task flow where you want to add a method call activity.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag and drop a method call activity onto the diagram.

The method call activity optionally displays a default activity ID, methodCalln, and a warning icon that indicates that a method EL expression has not yet been specified.

For more information about turning on the warning icons, see How to Add an Activity to a Task Flow.
In the Properties window, expand the General section, and enter an activity ID in the Activity ID field if you want to change the default value.

If you enter a new value, the new value appears under the method call activity in the diagram.
In the Method field, enter an EL expression that identifies the method to call.

For example, enter an EL binding expression similar to the following:

#{bindings.setCurrentRowWithKeyValue.execute}

Note:

The bindings variable in the EL expression references an ADF Model binding from the current binding container. In order to specify the bindings variable, you must specify a binding container definition or page definition. For more information, see Working with Page Definition Files.

You can also use the Expression Builder shown in Figure 24-8 to build the EL expression for the method:
1. Choose Method Expression Builder from the context menu that appears when you click the icon that appears when you over the Method property field.
2. In the Expression Builder dialog, navigate to the method that you want to invoke and select it.
  
  The Expression Builder dialog should look similar to Figure 24-8. In Figure 24-8, for example, the EL expression shown at the top of the Expression Builder references the CreateInsert action binding from the method call activity in the emp-reg-task-flow-definition.xml task flow of the Summit ADF task flow sample application.
  
  Figure 24-8 EL Expression for Method in Expression Builder Dialog
3. Click OK.
  
  Tip:
  
  If the method call activity is going to invoke a managed bean method, double-click the method call activity in the diagram. This invokes a dialog where you can specify the managed bean method you want to invoke.
In the Properties window, expand the General section, and specify one of the following in the Outcome group:
- Fixed Outcome: On successful completion, the method always returns this single outcome, for example, success. If the method does not complete successfully, an outcome is not returned. If the method type is void, you must specify a value for Fixed Outcome rather than for to-string.
- tostring(): If you select true, the outcome is based on calling the toString() method on the Java object returned by the method.

How to Specify Method Parameters and Return Values

You can specify parameters and return values for a method. Figure 24-9 shows the Properties window with a single parameter defined for a method called calculateSalesTax. The Value field contains an EL expression that evaluates to the parameter value at runtime.

Figure 24-9 Method Parameters in a Method Call

If parameters have not already been created by associating the method call activity to an existing method, add the parameters yourself.

Before you begin:

It may be helpful to have an understanding of how the properties of a method call activity affect the functionality of a task flow. For more information, see Using Method Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

You will need to complete this task:

Add a method call activity to the task flow diagram, as described in How to Add a Method Call Activity.

To add method parameters:

In the Applications window, expand the WEB-INF node and double-click the task flow that contains the method call activity to which you want to add method parameters.
In the task flow diagram, select the method call activity.
In the Properties window, expand the Parameters section, and click Add to set the following values for the parameter that you want to add:
- Class: Enter the parameter class, for example, java.lang.Double.
- Value: Enter an EL expression that retrieves the value of the parameter. For example:
  
  #{pageFlowScope.shoppingCart.totalPurchasePrice}
In the Return Value field, enter an EL expression that identifies where to store the method return value, for example, #{pageFlowScope.Return}.
Repeat the above steps to add additional parameters.

What Happens When You Add a Method Call Activity

After you specify parameters and return values for a method, the XML source file is updated. Example 24-4 shows the SetCurrentRowWithKeyValue method call activity in the customers-task-flow-definition.xml task flow from the Summit ADF task flow sample application.

Example 24-4 Method Call Activity in the Summit ADF Sample Application

<method-call id="SetCurrentRowWithKeyValue">
      <method>#{bindings.setCurrentRowWithKeyValue.execute}</method>
      <outcome>
        <fixed-outcome>setCurrentRowWithKey</fixed-outcome>
      </outcome>
    </method-call>

Using Task Flow Call Activities

The ADF task flow allows you to call a bounded task flow, to perform a set of activities, from a bounded or unbounded task flow. This is helpful when you want a set of activity to be performed repeatedly in your task flow or you want to perform an activity based on the outcome of another activity.

You can use a task flow call activity to call a bounded task flow from either the unbounded task flow or a bounded task flow. A task flow call activity allows you to call a bounded task flow located within the same or a different application.

The called bounded task flow executes its default activity first. There is no limit to the number of bounded task flows that can be called. For example, a called bounded task flow can call another bounded task flow, which can call another, and so on resulting in the creation of chained task flows where each task flow is a link in a chain of tasks.

To pass parameters into a bounded task flow, you must specify input parameter values on the task flow call activity. These values must correspond to the input parameter definitions on the called bounded task flow. For more information, see How to Specify Input Parameters on a Task Flow Call Activity .

Also note the following:

The value on the task flow call activity Input Parameter specifies where the value will be taken from within the calling task flow.
The value on the Input Parameter Definition for the called task flow specifies where the value will be stored within the called bounded task flow once it is passed.

Tip:

When a bounded task flow is associated with a task flow call activity, input parameters are automatically inserted on the task flow call activity based on the input parameter definitions defined on the bounded task flow. Therefore, the application developer needs only to assign values to the task flow call activity input parameters.

By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.

The technique for passing return values out of the bounded task flow to the caller is similar to the way that input parameters are passed. For more information, see Configuring a Return Value from a Bounded Task Flow.

To use a task flow call activity:

Call a bounded task flow using a task flow call activity.
Specify input parameters on a task flow call activity if you want to pass parameters into the bounded task flow.
Call a bounded task flow in another web application using a URL.
Specify before and after listeners on a task flow call activity.

How to Call a Bounded Task Flow Using a Task Flow Call Activity

Add a task flow call activity to the calling bounded or unbounded task flow to call a bounded task flow.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Using Task Flow Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To call a bounded task flow using a task flow call activity:

In the Applications window, expand the WEB-INF node and double-click the task flow (calling task flow) to which you are going to add a task flow call activity to call a bounded task flow.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag and drop a Task Flow Call activity onto the diagram.
Choose one of these options to identify the called task flow:
- In the task flow diagram, double-click the task flow call activity.
  
  The Create Bounded Task Flow dialog appears, where you specify options for creating a new bounded task flow.
- Drag an existing bounded task flow from the Applications window and drop it on the task flow call activity.
  
  Tips:
  
  You can drop a bounded task flow on a page or page fragment. If the bounded task flow consists of pages (not page fragments), you can choose the Task Flow Call as Button or Task Flow Call as Link menu options that appear to add a button or link component on the page where you drop the task flow. An end user can click the button or link to call the task flow. This may in turn automatically generate the task flow call activity if the page is already associated with an existing view activity in a task flow.
  
  You cannot drop a bounded task flow from one application to a task flow diagram contained in another application using the Applications window, even though both applications appear in the Applications window. In addition, you cannot drop a bounded task flow contained in one project onto a task flow diagram contained in another project.
  
  Instead, you can package the bounded task flow in an ADF library, then reuse it in your current application or project. You can then drag the bounded task flow from the Resources window or from the Components window page that is created when you import the library. For more information, see Using the Resources Window.
- If you know the name of the bounded task flow that you want to invoke, perform the following steps:
  1. In the task flow diagram, select the task flow call activity.
  2. In the Properties window, expand the General section, and select Static from the Task Flow Reference dropdown list.
  3. In the Document field, enter the name of the source file for the bounded task flow to call. For example, called-task-flow-definition.xml.
  4. In the ID field, enter the bounded task flow ID contained in the XML source file for the called bounded task flow, for example, targetTaskFlow.
- If you do not know the name of the bounded task flow to invoke and it is dependent on an end user selection at runtime, perform the following steps:
  1. In the task flow diagram, select the task flow call activity.
  2. In the Properties window, expand the General section, and select Dynamic from the Task Flow Reference dropdown list.
  3. Select Expression Builder from the context menu that appears when you click the icon that appears when you hover over the Dynamic Task Flow Reference property field.
  4. Write an EL expression that identifies the ID of the bounded task flow to invoke at runtime.
  Figure 24-10 shows the customers-task-flow task flow in the Summit ADF task flow sample application. This task flow contains a task flow call activity (create-edit-orders-task-flow-definition) that invokes the task flow of the same name.
  
  Figure 24-10 Task Flow Call Activity That Invokes a Bounded Task Flow

What Happens When You Call a Bounded Task Flow Using a Task Flow Call Activity

JDeveloper generates metadata entries in the source file for the task flow that calls the bounded task flow. Example 24-5 shows the metadata that corresponds to Figure 24-10 from the Summit ADF task flow sample application. At runtime, the task flow call activity invokes the orders-select-many-items task flow.

Example 24-5 Task Flow Call Activity in the Summit ADF Sample Application

<task-flow-call id="orders-select-many-items">
      <task-flow-reference>
        <document>/WEB-INF/flows/orders/orders-select-many-items.xml</document>
        <id>orders-select-many-items</id>
      </task-flow-reference>
      <run-as-dialog>
        <display-type>
          <inline-popup/>
        </display-type>
      </run-as-dialog>
    </task-flow-call>

How to Specify Input Parameters on a Task Flow Call Activity

The suggested method for mapping parameters between a task flow call activity and its called bounded task flow is to first specify input parameter definitions for the called bounded task flow. Then you can drag the bounded task flow from the Applications window and drop it on the task flow call activity. The task flow call activity input parameters will be created automatically based on the bounded task flow's input parameter definition. For more information, see Passing Parameters to a Bounded Task Flow.

You can, of course, first specify input parameters on the task flow call activity. Even if you have defined them first, they will automatically be replaced based on the input parameter definitions of the called bounded task flow, once it is associated with the task flow call activity.

If you have not yet created the called bounded task flow, you may still find it useful to specify input parameters on the task flow call activity. Doing so at this point allows you to identify any input parameters you expect the task flow call activity to eventually map when calling a bounded task flow.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Using Task Flow Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To specify input parameters on a task flow call activity:

In the Applications window, expand the WEB-INF node and double-click the task flow that contains the task flow call activity.
In the diagram, select the task flow call activity.
In the Properties window, expand the Parameters section, and click the Add icon to specify a new input parameter in the Input Parameters list as follows:
- Name: Enter a name to identify the input parameter.
- Value: Enter an EL expression that identifies the parameter value. The EL expression identifies where the parameter value will be retrieved from within the calling task flow. For example, enter an EL expression similar to the following:
  
  #{pageFlowScope.callingTaskflowParm}
  
  By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.
  
  Click in the Value field and use the dropdown list to use the Expression Builder if needed.
After you have specified an input parameter, you can specify a corresponding input parameter definition for the called bounded task flow. For more information, see Passing Parameters to a Bounded Task Flow.

Note:
If you call a task flow without the required input parameter, the task flow is not executed and an error is logged in the oracle.adfinternal.controller.activity logger. Therefore, it is difficult to know the error when a task flow fails to execute.
For a normal task flow call, an ActivityLogicException is thrown if the required input parameters are missing. When the task flow is invoked in a region or directly from the URL, without the required input parameters, the task flow is not processed and displays a blank region or page. In case of region, the rest of the page is rendered properly.

How to Call a Bounded Task Flow Using a URL

You can call a bounded task flow that does not use page fragments (.jsff) in another web application using a URL. Use a task flow call activity to call the bounded task flow that you want to invoke. You write an EL expression for the task flow call activity's remote-app-url property that, when evaluated, returns a URL.

In addition to writing a value for the remote-app-url property, you specify values for task flow reference properties that identify the bounded task flow to call. The task flow reference and the remote-app-url property are combined at runtime to generate a URL to the called bounded task flow in the remote web application.

You also need to set visibility properties for the bounded task flow in the remote web application that you want to call so that it invokes when it receives the URL generated from the task flow call activity in the calling task flow.

Be aware that JSF portlets provide all content from the same web application. As a result, do not configure your web application to invoke a task flow using a URL if you plan to use your web application in a JSF portlet.

Note:

If, in JDeveloper's Applications window, you right-click the bounded task flow that you want to call using a URL and select Run, the bounded task flow executes as if it were called using a URL at runtime. For this reason, make sure to set the visibility properties for the bounded task flow even if you want to execute it as part of testing in JDeveloper.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Using Task Flow Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To call a bounded task flow using a URL:

In the Applications window, expand the WEB-INF node and double-click the task flow that you want to configure to invoke a bounded task flow in a remote web application.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag a Task Flow Call activity and drop it on the diagram for the task flow.
In the Properties window, expand the General section and specify values to invoke a bounded task flow.

For more information, see How to Call a Bounded Task Flow Using a Task Flow Call Activity.
For the Remote Application URL property, use the Expression Builder to write an EL expression that, when evaluated, returns a string with the parts required to construct a URL of the remote web application. Invoke the Expression Builder by selecting Expression Builder from the context menu that appears when you click the icon that appears when you hover over the property field.

For example, the following EL expression invokes a managed bean method that returns a string with the parts required to construct a URL:

#{myOrdersBean.createOrder}
Open the bounded task flow in the remote web application that you want to invoke.

Note:

The bounded task flow you specify cannot use page fragments (.jsff).
In the Structure window, right-click the node for the bounded task flow (task-flow-definition- Task Flow ID) and choose Go to Properties.
In the Properties window, expand the General section and select values for the following:
- URL Invoke: select url-invoke-allowed from the dropdown list if you want to allow a URL to invoke the bounded task flow. Select url-invoke-disallowed if you do not want to allow a URL to invoke the bounded task flow. Selecting this value returns a HTTP 403 status code if a URL attempts to invoke the bounded task flow. The default value (calculated) allows a URL to invoke the bounded task flow if the bounded task flow does not specify an initializer and it has a view activity as its default activity. If the bounded task flow does not meet these conditions, a HTTP 403 status code is returned. Selecting url-invoke-allowed or url-invoke-disallowed overrides the default behavior.
- Library Internal: select true if you want the bounded task flow to be internal when you package it in an ADF Library JAR. The default value is false.
  
  For more information about packaging a bounded task flow in an ADF Library JAR, see Packaging a Reusable ADF Component into an ADF Library.
Save and close the bounded task flow.

What Happens When You Configure a Bounded Task Flow to be Invoked by a URL

JDeveloper generates metadata entries in the source file of the task flow that invokes the task flow call activity to the bounded task flow in a remote web application. The following example shows an entry for a task flow call activity.

<task-flow-call id="createOrder">
    <task-flow-reference>
      <document id="__6">myorders-task-flow.xml</document>
      <id id="__5">myorders-task-flow</id>
    </task-flow-reference>
    <remote-app-url id="__7">#{myOrdersBean.createOrder}</remote-app-url>
  </task-flow-call>

The createOrder method in the previous example returns a string with the URL syntax required to invoke a bounded task flow. For more information about the URL syntax, including descriptions of the required parts in the returned string and an example URL, see What You May Need to Know About Calling a Bounded Task Flow Using a URL.

JDeveloper also generates entries in the source file for the bounded task flow to invoke when you configure it so it can be called by a URL. The following example shows sample metadata entries that allow a bounded task flow to be invoked by a URL.

<task-flow-definition id="task-flow-definition3">
    <visibility id="__2">
      <url-invoke-allowed/>
      <library-internal/>
    </visibility>
  </task-flow-definition>

What You May Need to Know About Calling a Bounded Task Flow Using a URL

Adding a context parameter in your local application's deployment descriptor may ease the administration of interaction with a remote web application.

Context Parameter for Remote Web Application

Consider adding a context parameter to the deployment descriptor (web.xml) for your Fusion web application (local application) if you use a URL to invoke a bounded task flow in another Fusion web application (remote application). Set the value of the context parameter to the URL of the remote application. Use the context parameter name when writing EL expressions in the local application, as shown in the following example where remoteAppUrl is the name of the context parameter:

#{initParam.remoteAppUrl}

If the URL of the remote application changes, you can update the context parameter to reference the changed URL.

Object Type for Parameter Converters

Parameter converters, if specified, can be used to convert task flow parameter values to and from the string representations used in a URL. A parameter converter is an EL expression that evaluates to an object of the following type:

oracle.adf.controller.UrlParameterConverter

If you do not specify a parameter converter, a default converter checks the parameters for cross-site-scripting (XSS) attacks. If you know that the parameter values used in your application contain special characters, you should create your own implementation of UrlParameterConverter and use it to perform conversion of the task flow parameter values.

URL Syntax to Invoke a Bounded Task Flow

Typically, you write an EL expression that references a managed bean method which, in turn, retrieves the required parts of the URL or you could write an EL expression that returns the URL directly, as shown in the following example.

http://somecompany.com/internalApp/MyApp/faces/adf.task-flow?adf.tfId=displayHelp&
adf.tfDoc=%2FWEB-INF%2Fdisplayhelp.xml&topic=createPurchaseOrder

Example 24-6 describes the parts of the URL syntax to invoke a bounded task flow.

The following list describes each part of the URL syntax in Example 24-6:

<server root>: Provided by customization at site or administrator level. For example:

http://mycompany.com/internalApp

The <server root> value depends on the application server where you deploy the bounded task flow. The bounded task flow URL is a resource within the JSF servlet's URL path.
<app context>: The web application context root, for example, MyApp. The context root is the base path of a web application.
faces: Faces servlet mapping.
adf.task-flow: A reserved keyword that identifies ADF Controller for the remote web application.
adf.tfId: A URL parameter that supplies the task flow ID to call.
<task flow ID>: The identifier of the bounded task flow to call, for example, displayHelp. This is the same task flow ID that is used when calling locally. Note that this identifier is not the same as the task flow call activity instance ID. The parameter value must be represented as a string.
adf.tfDoc: A URL parameter that supplies the document name containing the bounded task flow ID to be called.
<document name>: A document name containing the bounded task flow ID to be called, for example, %2FWEB-INF%2FtoUppercase%2FdisplayHelp.xml. If you are handcrafting the bounded task flow URL, you are responsible for the appropriate encoding.
<named parameter>: (optional) The name of an input parameter definition for the called bounded task flow, for example, topic. You must supply all required input parameter definitions.
<named parameter value>: (optional) The value of the input parameter.

Note:

URL parameter names that begin with an underscore ('_') are intended for internal use only and should not be used. Although you may see these names on URLs generated by ADF Controller, you should not attempt to use or depend on them.

Example 24-6 URL Syntax for a Call to a Bounded Task Flow Using Named Parameters

<server root>/<app_context>/faces/adf.task-flow?adf.tfid=<task flow definition ID>&adf.tfDoc=<document name>&<named parameter>=<named parameter value>

How to Specify Before and After Listeners on a Task Flow Call Activity

Use task flow call activity before and after listeners to identify the start and end of a bounded task flow. Specifying a listener in the task flow call activity means that the listener executes on that specific usage of the called bounded task flow.

You specify the listener as an EL expression for a method that will be called upon entry or exit of a bounded task flow, for example:

<before-listener>#{global.showState}</before-listener}>

The method cannot have parameters.

Before listener: An EL expression for a Java method called before a bounded task flow is entered. It is used when the caller needs to know when a bounded task flow is being initiated.
After listener: An EL expression for a Java method called after a bounded task flow returns. It is used when the caller needs to know when a bounded task flow exits and control flow returns to the caller.

If multiple before listeners or multiple after listeners are specified, they are called in the order in which they appear in the source document for the unbounded or bounded task flow. A task flow call activity can have only have before listener and one after listener.

In order for the task flow call after listeners to be called, control flow must return from the bounded task flow using a control flow rule. If an end user leaves a bounded task flow using the browser back button or other URL, task flow call after listeners will not be called. You must use a bounded task flow finalizer to release all acquired resources and perform cleanup of a bounded task flow that the end user left by clicking a browser back button.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Using Task Flow Call Activities.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To specify a before or after listener on a task flow call activity:

In the Applications window, expand the WEB-INF node and double-click the calling task flow.
In the diagram for the calling bounded task flow, select the task flow call activity.
In the Properties window, expand the Listeners section and open the Expression Builder for either the Before Listener property or the After Listener property. To open the Expression Builder, choose Method Expression Builder from the context menu that invokes when you click the icon that appears when you hover over the property field.

Use the Expression Builder to navigate to the Java class that contains the method for the listener. For example, you might create an EL expression similar to the following:

#{pageFlowscope.managedBean.methodListener}
Click OK.

What Happens When You Add a Task Flow Call Activity

After you add a task flow call activity to a task flow diagram, you must specify a reference to the called bounded task flow using one of the methods described in How to Call a Bounded Task Flow Using a Task Flow Call Activity. For example, if you drop an existing bounded task flow on the task flow call activity, JDeveloper generates the task flow reference automatically. The task flow reference is used to invoke the called bounded task flow.

If the task flow reference is static, each task flow reference consists of:

Document: The name of the XML source file containing the ID of the called bounded task flow. If Document is not specified, adfc-config.xml is assumed.

The document is a physical XML file and must be accessible via MDS.
ID: The bounded task flow ID contained in the XML source file for the called bounded task flow. For example, a called task flow might have an ID called targetFlow. The same XML source file can contain multiple bounded task flows, each bounded task flow identified by a unique ID.

Note:

If you use JDeveloper to create the bounded task flow, there is only one bounded task flow per document.

The following example contains an example static task flow reference within a task flow call activity. In order to invoke a bounded task flow, you need to know its ID and the name of the file (<document>) containing the ID.

<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2" id="__1">
...
  <task-flow-definition id="task-flow-definition">
    <default-activity>view1</default-activity>
    <task-flow-call id="taskFlowCall">
      <task-flow-reference>
        <document>/WEB-INF/called-task-flow-definition.xml</document>
        <id>called-task-flow-definition</id>
      </task-flow-reference>
    </task-flow-call>
  </task-flow-definition>
...
</adfc-config>

The following example shows the metadata that JDeveloper generates for a dynamic task flow reference within a task flow call activity.

<?xml version="1.0" encoding="windows-1252" ?>
<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2"
             id="__1">
  <task-flow-definition id="bounded_tf">
    <default-activity id="__2">taskFlowCall1</default-activity>
    <task-flow-call id="taskFlowCall1">
      <dynamic-task-flow-reference id="__3">#{EL_Expression_Retrieve_
                            TaskflowID}</dynamic-task-flow-reference>
    </task-flow-call>
  </task-flow-definition>
</adfc-config>

What Happens at Runtime: How a Task Flow Call Activity Invokes a Task Flow

The ADF Controller performs the following steps when a bounded task flow is called using a task flow call activity:

Verifies that the user is authorized to call the bounded task flow.
Invokes task flow call activity before listener or listeners, if specified (see How to Specify Before and After Listeners on a Task Flow Call Activity).
Evaluates the input parameter values on the bounded task flow.
Pushes the called bounded task flow onto the stack and initializes its page flow scope.
Sets input parameter values in the called bounded task flow's context.
Invokes a bounded task flow initializer method, if one is specified.
Executes the bounded task flow's default activity.

Using Task Flow Return Activities

When the ADF task flow call activity is invoked and after it completes its default activity, it should return the control back to the invoked application. The task flow return activity is helpful in identifying and sending the control flow back to the caller application. This activity can be used only within a bounded task flow.

A task flow return activity identifies the point in an application's control flow where a bounded task flow completes and sends control flow back to the caller. You can use a task flow return activity only within a bounded task flow.

A gray circle around a task flow return activity icon indicates that the activity is an exit point for a bounded task flow. A bounded task flow can have zero to many task flow return activities. Figure 24-11 shows the orders-select-many-items.xml bounded task flow in the Summit ADF task flow sample application that contains task flow return activities named commit and rollback.

Each task flow return activity specifies an outcome that it returns to the calling task flow. For example, Figure 24-11 shows a task flow return activity in the Summit ADF task flow sample application. The value for the this task flow return activity's Outcome Name property is commit.

Figure 24-11 Multiple Task Flow Return Activities

The outcome returned to an invoking task flow depends on the end user action. You can configure control flow cases in the invoking task flow to determine the next action by the invoking task flow. Set the From Outcome property of a control flow case to the value returned by the task flow return activity's outcome to invoke an action based on that outcome. This determines control flow upon return from the called task flow.

Set a value for the Restore Save Point property to specify if model changes made in a bounded task flow are saved or discarded when the bounded task flow exits by using a task flow return activity. Set to true to roll back transactions to the ADF Model save point that was created when the Fusion web application first entered the bounded task flow. The default value is false. You can specify a value for this property only if the bounded task flow on which the task flow return activity is located was entered without starting a new transaction. See How to Enable Transactions in a Bounded Task Flow .

How to Add a Task Flow Return Activity to a Bounded Task Flow

You drag a task flow return activity from the Components window and drop it on the diagram for the bounded task flow.

Before you begin:

It may be helpful to have an understanding of how a task flow return activity interacts with a task flow. For more information, see Using Task Flow Return Activities .

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To add a task flow return activity to a bounded task flow:

In the Applications window, expand the WEB-INF node and double-click the bounded task flow to which you want to add a task flow return activity.
In the ADF Task Flow page of the Components window, from the Components panel, in the Activities group, drag and drop a Task Flow Return onto the diagram.
In the Properties window, expand the General section, and enter an outcome in the Name field.

The task flow return activity returns this outcome to the calling task flow when the current bounded task flow exits. You can specify only one outcome per task flow return activity. The calling task flow should define control flow rules to handle control flow upon return. For more information, see How to Add a Control Flow Rule to a Task Flow.
Expand the Behavior section and in the Reentry dropdown list, choose one of the following options:
- <default> (not outcome dependent): Reentry is not dependent on an outcome.
- reentry-allowed: Reentry is allowed on any view activity within the bounded task flow.
- reentry-not-allowed: Reentry of the bounded task flow is not allowed.
  
  If you specify reentry-not-allowed on a bounded task flow, an end user can still click the browser back button and return to a page within the bounded task flow. However, if the user does anything on the page such as clicking a button, an exception (for example, InvalidTaskFlowReentry) is thrown indicating the bounded task flow was reentered improperly. The actual reentry condition is identified upon the submit of the reentered page.
  
  For more information about reentering a bounded task flow, see Reentering Bounded Task Flows.
Your selection defines the default behavior when the bounded task flow is reentered by an end user clicking a browser's Back button. This selection applies only if reentry-outcome-dependent has been set on the bounded task flow where the task flow return activity is located. For more information, see Reentering Bounded Task Flows.
In the End Transaction dropdown list, choose one of the following options:
- commit: Select to commit the existing transaction to the database.
- rollback: Select to roll back the transaction to what it was on entry of the called task flow. This has the same effect as canceling the transaction, since it rolls back a new transaction to its initial state when it was started on entry of the bounded task flow.
  
  If you do not specify commit or rollback, the transaction is left open to be closed by the calling bounded task flow.
In the Restore Save Point dropdown list, select true when either of the following conditions apply:
- If Always Begin New Transaction (new-transaction) is not selected on the bounded task flow on which the task flow return activity is located
- ADF model changes made within a bounded task flow should be discarded when exiting using the task flow call activity. The transaction is rolled back to the save point created on entry of the bounded task flow.
For more information, see How to Enable Transactions in a Bounded Task Flow .

What Happens When You Add a Task Flow Return Activity to a Bounded Task Flow

JDeveloper generates metadata entries in the source file of the bounded task flow for the changes that you configure for the task flow return activity in the Properties window. The following example shows entries that appear in the orders-select-many-items.xml task flow of the Summit ADF task flow sample application.

 <task-flow-return id="commit">
      <outcome>
        <name>commit</name>
        <commit/>
      </outcome>
    </task-flow-return>
    <task-flow-return id="rollback">
      <outcome>
        <name>rollback</name>
        <rollback/>
      </outcome>
    </task-flow-return>

Using Task Flow Activities with Page Definition Files

A page definition file defines the binding objects that populate data in the ADF application at runtime. You can use the page definition files to bind the ADF task flow activities to data controls.

Page definition files define the binding objects that populate data at runtime. They are typically used in a Fusion web application to bind page UI components to data controls. A number of task flow activities can also use page definition files to bind to data controls. These are:

Method call

You can drag and drop a data control operation from the Data Controls panel onto a task flow to create a method call activity or onto an existing method call activity. In both cases, the method call activity binds to the data control operation.
Router

Associating a page definition file with a router activity creates a binding container. At runtime, this binding container makes sure that the router activity references the correct binding values when it evaluates the router activity cases' EL expressions. Each router activity case specifies an outcome to return if its EL expression evaluates to true. For this reason, only add data control operations to the page definition file that evaluate to true or false.
Task flow call

Associating a page definition file with a task flow call activity creates a binding container. At runtime, the binding container is in context when the task flow call activity passes input parameters. The binding container makes sure that the task flow call activity references the correct values if it references binding values when passing input parameters from a calling task flow to a called task flow.
View

You cannot directly associate a view activity with a page definition file. Instead, you associate the page that the view activity references.

If you right-click any of the above task flow activities (except view activity) in the diagrammer for a task flow, JDeveloper displays an option on the context menu that enables you to create a page definition file (Create Page Definition) if one does not yet exist. If a page definition file does exist, JDeveloper displays a context menu option for all task flow activities to go to the page definition file (Go to Page Definition). JDeveloper also displays a context menu option (Edit Binding) when you right-click a method call activity that is associated with a page definition file.

A task flow activity that is associated with a page definition file displays an icon in the lower-right section of the task flow activity icon. Figure 24-12 shows an example for each of the task flow activities.

Figure 24-12 Task Flow Activities Associated with Page Definition Files

Description of "Figure 24-12 Task Flow Activities Associated with Page Definition Files"

How to Associate a Page Definition File with a Task Flow Activity

JDeveloper provides a context menu option that you can access from the task flow activity. You use this context menu option to associate the task flow activity with a page definition file.

Before you begin:

It may be helpful to have an understanding of how task flow activities use page definition files. For more information, see Using Task Flow Activities with Page Definition Files.

You may also find it helpful to understand other ADF functionality and features. For more information, see Additional Functionality for Task Flow Activities.

To associate a page definition file with a task flow activity:

In the Applications window, expand the WEB-INF node and double-click the task flow that contains the task flow activity with which you want to associate a page definition file.
In the diagram, right-click the task flow activity for which you want to create a page definition file and choose Create Page Definition.
In the resulting page definition file, add the bindings that you want your task flow activity to reference at runtime.

For more information about page definition files, see Working with Page Definition Files.

What Happens When You Associate a Page Definition File with a Task Flow Activity

At design time, JDeveloper generates a page definition file for the task flow activity. The filename of the page definition file comprises the originating task flow and either the name of the task flow activity or the data control operation to invoke. For example, taskflowName_taskflowName_methodCall1PageDef.xml or taskflowName_taskflowName_CreateInsertPageDef.xml.

JDeveloper also generates an EL expression from the task flow activity to the binding in the created page definition file. The following example shows a method call activity that references a CreateInsert action binding.

<method-call id="CreateInsert">
      <method>#{bindings.CreateInsert.execute}</method>
      <outcome>
        <fixed-outcome>CreateInsert</fixed-outcome>
      </outcome>
    </method-call>

At runtime, a binding container makes sure that a task flow activities' EL expressions reference the correct value.