20 Using Parameters in Task Flows

This chapter describes how to specify parameters in view activities and in bounded task flows.

This chapter includes the following sections:

Section 20.1, "About Using Parameters in Task Flows"
Section 20.2, "Passing Parameters to a View Activity"
Section 20.3, "Passing Parameters to a Bounded Task Flow"
Section 20.4, "Sharing Data Controls Between Task Flows"
Section 20.5, "Specifying a Return Value from a Bounded Task Flow"

20.1 About Using Parameters in Task Flows

A task flow´s ability to accept input parameters and return parameter values allow you to manipulate data in task flows and share data between task flows. Using these abilities, you can optimize the reuse of task flows in your Fusion web application.

You can use view activity input page parameters as aliases. The alias allows you to map bounded task flow input parameters to page parameters. The view activity input page parameters map managed beans and any information available to the calling task flow to a managed bean on the page itself. To pass values out of view activities, store values in page flow scope or managed beans. For information about using view activities in a task flow, see Section 19.2, "Using View Activities".

For example, a page might specify #{pageFlowScope.empNo} as a page parameter and a bounded task flow might specify #{pageFlowScope.employeeID} as the value of an input parameter definition.

The from-value on the view activity input page parameter would be #{pageFlowScope.employeeID} and the to-value would be #{pageFlowScope.empNo}. This enables reuse of both the page definition and bounded task flow because you do not have to redefine parameters for every context in which each is used.

Other values contained within the task flow can be mapped to input page parameters, not just bounded task flow input parameter definition values.

20.1.1 Task Flow Parameters Use Cases and Examples

Figure 20-1 shows how the check out bounded task flow in the Fusion Order Demo application defines input parameters to receive data about a customer who wants to purchase a product. For more information about the Fusion Order Demo, including how to access the source files, see Chapter 2, "Introduction to the ADF Sample Application."

Figure 20-1 Check Out Task Flow

20.1.2 Additional Functionality for Task Flows Using Parameters

You may find it helpful to understand other ADF features before you configure or use a task flow with parameters. 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.

Data controls can be shared between task flows. For more information about data controls, see Chapter 13, "Exposing Application Modules with Oracle ADF Data Controls."
Task flows can invoke managed beans. For more information about managed beans, see Section 24.4, "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 Chapter 35, "Enabling ADF Security in a Fusion Web Application."

20.2 Passing Parameters to a View Activity

Figure 20-2 illustrates how to specify an input page parameter mapping. You can pass a parameter to the Employee activity as a pageFlowScope value or a value on a managed bean. The Employee activity can pass a value to the Target activity by placing it within pageFlowScope or a managed bean to the Target activity, based on the EL expression you specified in the to-value.

Figure 20-2 Task Flow with Two Activities

20.2.1 How to Pass Parameters to a View Activity

You add one or more input page parameters to the view activity that you want to pass parameters to.

Before you begin:

It may be helpful to have an understanding of the configuration options available to you before you define an input page parameter for a view activity. For more information, see Section 20.2, "Passing Parameters to a View Activity."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 20.1.2, "Additional Functionality for Task Flows Using Parameters."

To define an input page parameter for a view activity:

In the Application Navigator, double-click the source file for the task flow that contains the view activity to which you want to pass a parameter.
Select the view activity in the diagram for the task flow and, in the Property Inspector, expand the Page Parameters category.
In the Property Inspector, click Page Parameters.
In the Input Page Parameter section, click the Add icon and enter values as follows:
- From Value: write an EL expression that, when evaluated, specifies where the view activity retrieves the value for the input page parameter. For example, write an EL expression similar to the following:
  
  #{pageFlowScope.EmployeeID}
  
  You can configure the view activity to retrieve a value that is input to the task flow if you write an EL expression for From Value that corresponds to the value for the input parameter that you defined for the task flow, as described in Section 20.3.1, "How to Pass an Input Parameter to a Bounded Task Flow."
- To Value: write an EL expression, that when evaluated, specifies where the page associated with the view activity can retrieve the value of the input page parameter. For example, write an EL expression similar to the following:
  
  #{pageFlowScope.EmployeeNo}

20.2.2 What Happens When You Pass Parameters to a View Activity

JDeveloper writes entries to the source file of the task flow at design time, as illustrated in Example 20-1.

Example 20-1 Metadata to Define an Input Page Parameter on a View Activity

<view id="reducedAccess">
 <page>/secured/Information.jspx</page>
      <input-page-parameter>
        <from-value>#{res['infoUsage.reducedAccess.messageHeader']}</from-value>
        <to-value>#{pageFlowScope.infoPageHeaderText}</to-value>
      </input-page-parameter>
      <input-page-parameter>
        <from-value>#{res['infoUsage.reducedAccess.messageHeader']}</from-value>
        <to-value>#{pageFlowScope.infoPageMsg}</to-value>
      </input-page-parameter>
      <input-page-parameter>
        <from-value>info</from-value>
        <to-value>#{pageFlowScope.infoPageType}</to-value>
      </input-page-parameter>
    </view>

At runtime, the view activity retrieves the value of the input parameter from the location you specified in the <from-value> element. The view activity makes the value of the parameter available to its associated page in the location you specified in the <to-value> element.

20.2.3 What You May Need to Know About Specifying Parameter Values

You can specify parameter values using standard EL expression if you call a bounded task flow using a task flow call activity or you render the bounded task flow in an ADF region or an ADF dynamic region. For example, you can specify parameters using the following syntax for EL expressions:

#{bindings.bindingId.inputValue}
#{bindings.bindingId}
#{inputValue}

Example 20-2 shows the metadata for a task flow binding that renders in an ADF region.

Example 20-2 ADF Region taskFlow Binding

<taskFlow id="Department1" taskFlowId="/WEB-INF/Department.xml#Department"
              xmlns="http://xmlns.oracle.com/adf/Controller/binding"
              Refresh="ifNeeded">
    <parameters>
        <parameter id="DepartmentId" value="#{bindings.DepartmentId.inputValue}"
                   xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
     </parameters>
</taskFlow>

Appending inputValue to the EL expression makes sure that you assign the parameter the value of the binding rather than the actual binding object.

20.3 Passing Parameters to a Bounded Task Flow

A called bounded task flow can accept input parameters from the task flow that calls it. To pass an input parameter to a bounded task flow, you specify one or more:

Input parameters on the task flow call activity in the calling task flow

Input parameters specify where the calling task flow stores parameter values.
Input parameter definitions on the called bounded task flow

Input parameter definitions specify where the called bounded task flow can retrieve parameter values at runtime.

Specify the same name for the input parameter that you define on the task flow call activity in the calling task flow and the input parameter definition on the called bounded task flow. Do this so you can map input parameter values to the called bounded task flow.

If you do not specify an EL expression to reference the value of the input parameter, the EL expression for value defaults to the following at runtime:

#{pageFlowScope.parmName}

where parmName is the value you entered for the input parameter name.

In an input parameter definition for a called bounded task flow, you can specify an input parameter as required. If the input parameter does not receive a value at runtime or design time, the task flow raises an error. An input parameter that you do not specify as required can be ignored during task flow call activity creation.

Task flow call activity input parameters can be passed by reference or passed by value when calling a task flow using a task flow call activity unless you are calling a task flow in an ADF region. If the task flow renders in an ADF region, the task flow call activity passes the input parameters by reference. By default, primitive types (for example, int, long, or boolean) are passed by value (pass-by-value).

The Pass By Value check box applies only to objects, not primitives and is used to override the default setting of passing by reference. Mixing the two, however, can lead to unexpected behavior in cases where parameters reference each other. If input parameter A on the task flow call activity is passed by value and if input parameter B on the task flow call activity is passed by reference, and B has a reference to A, the result can be two different instances of A and B.

Section 20.3.1, "How to Pass an Input Parameter to a Bounded Task Flow," describes how to pass an input parameter from a calling task flow to a called bounded task flow using a task flow call activity. Although you can pass parameter values from any activity on the calling task flow, the passed parameter in Section 20.3.1, "How to Pass an Input Parameter to a Bounded Task Flow" contain the value of an input text field on a page in the calling task flow.

If you call a bounded task flow using a URL rather than a task flow call activity, you pass parameters and values on the URL itself. For more information, see Section 19.6.4, "How to Call a Bounded Task Flow Using a URL".

Instead of explicitly passing data controls as parameters between task flows, you can simply share them by specifying the data-control-scope option on the called bounded task flow. For more information, see Section 20.4, "Sharing Data Controls Between Task Flows".

A called task flow can also return values to the task flow that called it when it exits. For more information about returning values from a bounded task flow, see Section 20.5, "Specifying a Return Value from a Bounded Task Flow."

20.3.1 How to Pass an Input Parameter to a Bounded Task Flow

You define values on the calling task flow and the called task flow.

Before you begin:

Create a calling and called task flow

The calling task flow can be bounded or unbounded. The called task flow must be bounded. For more information about creating task flows, see Section 18.2, "Creating a Task Flow.".
Add a task flow call activity to the calling task flow

Figure 20-3 shows an example where the view activity passes control to the task flow call activity.

Figure 20-3 Calling Task Flow
It may be helpful to have an understanding of the configuration options available to you before you configure a bounded task flow to receive an input parameter. For more information, Section 20.3, "Passing Parameters to a Bounded Task Flow."
You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 20.1.2, "Additional Functionality for Task Flows Using Parameters."

To pass an input parameter to a bounded task flow:

In the Application Navigator for your project, double-click the JSF page that contains an input component where an end user enters a value that gets passed to a bounded task flow as a parameter at runtime.

The JSF page that you open should be referenced by a view activity in the calling task flow.
Select an input text component on the JSF page where an end user enters a value at runtime.
In the Property Inspector, enter a value for the input text component.

You can specify the value as an EL expression, for example #{pageFlowScope.inputValue}.
In the Application Navigator, double-click the name of the called task flow to open its diagram.
Click the Overview tab for the called task flow.
In the overview editor, click the Parameters navigation tab and click the Add icon to define a new entry in the Input Parameter Definition section.
In the Name field, enter a name for the parameter, for example, inputParm1.
In the Value field, enter an EL expression where the parameter value is stored and referenced, for example, #{pageFlowScope.inputValue}.
In the editor, open the diagram for the calling task flow.
In the Application Navigator, drag the called bounded task flow and drop it on top of the task flow call activity that is located on the calling task flow.

Dropping a bounded task flow on top of a task flow call activity in a diagram automatically creates a task flow reference to the bounded task flow. As shown in Figure 20-4, the task flow reference contains the bounded task flow ID and a document name. The bounded task flow ID (id) is an attribute of the bounded task flow's <task-flow-definition> element. The document name points to the source file for the task flow that contains the ID.

Figure 20-4 Task Flow Reference in Property Inspector
In the Property Inspector for the task flow call activity, click Parameters and expand the Input Parameters section.
Enter a name that identifies the input parameter.

Because you dropped the bounded task flow on a task flow call activity having defined input parameters, the name should be already be specified. You must keep the same input parameter name.
Enter a parameter value, for example, #{pageFlowScope.parm1}.

The value on the task flow call activity input parameter specifies where the calling task flow stores parameter values.

The value on the input parameter definition for the called task flow specifies where the value will be retrieved from for use within the called bounded task flow once it is passed.
At runtime, the called task flow is able to use the input parameter. Since you specified pageFlowScope as the value in the input parameter definition for the called task flow, you can use the parameter value anywhere in the called bounded task flow. For example, you can pass it to a view activity on the called bounded task flow. For more information, see Section 19.2.1.2, "What Happens When You Pass Control Between View Activities".

20.3.2 What Happens When You Pass an Input Parameter to a Bounded Task Flow

JDeveloper writes entries to the source files for the calling task flow and called task flow based on the values that you select. Example 20-3 shows an input parameter definition specified on a a bounded task flow.

Example 20-3 Input Parameter Definition

<task-flow-definition id="sourceTaskflow">
...
   <input-parameter-definition>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.parmValue1}</value>
      <class>java.lang.String</class>
   </input-parameter-definition>
...
</task-flow-definition>

Example 20-4 shows the input parameter metadata for the task flow call activity that calls the bounded task flow shown in Example 20-3. At runtime, the task flow call activity calls the bounded task flow and passes it the value specified by its value element.

Example 20-4 Input Parameter on Task Flow Call Activity

<task-flow-call id="taskFlowCall1">
...
    <input-parameter>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.newCustomer}</value>
      <pass-by-value/>
    </input-parameter> 
... 
</task-flow-call>

20.4 Sharing Data Controls Between Task Flows

You can share data controls between task flows. A called bounded task flow can reference and modify the value of the data control owned by its calling task flow. This allows the called task flow to share the same data control instance as its parent. Both task flows look in the same place, the data control frame, to get the data control instance.

In the Fusion Order Demo application, for example, you may have a value that is used to display a row in a product table on a page. Clicking a button on the page updates a shopping cart form in an ADF region. The form updates with the product name, based on the selected value in the table.

A data control frame is the container associated with a task flow that contains data controls. A bounded task flow's transactions operate on data controls in the data control frame. A new DataControlFrame is created for each task flow that is entered. This results in each task flow having its own unique instance of any data control it uses.

To specify whether data controls are shared between the calling and called task flows, you must set a data-control-scope value of either shared or isolated on the called bounded task flow. The default value is shared.

If data-control-scope is set to shared on both the calling and called bounded task flow, the data control frame used will be the one for the calling task flow. In Example 20-5, the data control frame for Bounded Task Flow A will also be used by both B and C.If data-control-scope is set to isolated on both the calling and called bounded task flow, the task flows both use their own data control frames.

Example 20-5 Sharing Data Controls

Bounded Task Flow A - isolated
  Bounded Task Flow B - shared
    Bounded Task Flow C - shared

Note:

A task flow that is configured to share data controls cannot share data controls with the calling task flow if the calling task flow uses a URL to invoke the called task flow. ADF Controller throws an exception if this scenario occurs.

A caller of a bounded task flow can share its caller's data controls to any depth. For example, Task Flow A can share data controls with called bounded Task Flow B. Called Task Flow C can share the same data controls.

A bounded task flow that specifies data-control-scope as shared and is used within an ADF region shares the data controls of the task flow in the parent view port. For more information about view ports, see Section 21.1.2, "About View Ports and ADF Regions".

A new data control frame is created for the unbounded task flow in the call stack of each RootViewPort. Each browser window is isolated from all other browser windows within the same HTTP session. The browser windows do not share data controls. However, if an end user opens a new browser window, the two browser windows have the same server-side state and share data controls.

For performance reasons, data controls are not instantiated until needed. For more information about data controls, see Section 13.3, "Exposing Application Modules with Oracle ADF Data Controls".

20.4.1 How to Share a Data Control Between Task Flows

You share data controls between task flows by specifying a value for the data-control-scope element of the called task flow.

Before you begin:

It may be helpful to have an understanding of the properties that determine how you share data controls between task flows. For more information, see Section 20.4, "Sharing Data Controls Between Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features and parameters. For more information, see Section 20.1.2, "Additional Functionality for Task Flows Using Parameters."

To share a data control between task flows:

In the Property Inspector for the called task flow, expand the Behavior category.
Select the Share data controls with calling task flow check box.

Note:
After you select the Share data controls with calling task flow check box, you may need to configure transaction options for the task flow. For more information, see, Section 20.4.3, "What You May Need to Know About Managing Transactions".

20.4.2 What Happens When You Share a Data Control Between Task Flows

JDeveloper writes an entry in the source file for the called task flow when you select the Share data controls with calling task flow check box, as illustrated in Example 20-6.

At runtime, the called task flow shares data controls with the calling task flow.

Example 20-6 Metadata to Share Data Controls Between Task Flows

<task-flow-definition id="task-flow-definition">
    ...
    <data-control-scope id="__1">
      <shared/>
    </data-control-scope>
    ...
  </task-flow-definition>

20.4.3 What You May Need to Know About Managing Transactions

Data controls cannot be shared across more than one transaction at the same time. If your task flow is involved in managing transactions, the value you select for the data-control-scope option may affect the transaction option settings for a bounded task flow. Table 20-1 describes how these options interact.

Table 20-1 Interaction of transaction and data-control-scope option settings

transaction Option	data-control-scope Isolated Option	data-control-scope shared Option
`requires-existing-transaction`	Invalid.	If a transaction is not already open, an exception is thrown. The existing transaction is never committed.
`requires-transaction`	Always begins a new transaction.	Begins a new transaction if one is not already open.
`new-transaction`	Always begins a new transaction.	Begins a new transaction if one is not already open. If one is already open, an exception is thrown.
`<default> (none)`	A new data control frame is created without an open transaction.	The task flow uses the calling task flow's transaction for shared data controls and for any new data controls it creates. The task flow does not create or require a transaction.

20.5 Specifying a Return Value from a Bounded Task Flow

You can configure a bounded task flow to return a parameter value to the task flow that calls it. The value that the bounded task flow returns is in addition to the outcome that it returns to the caller when the bounded task flow invokes a task flow return activity, as described in Section 19.7, "Using Task Flow Return Activities." To return a value, you must specify:

Return value definitions on the called bounded task flow

The return value definition specifies where you store the value that you want to return when the called bounded task flow exits.
Return values on the task flow call activity in the calling task flow to identify where the calling task flow can find the returned value

You can configure the calling task flow to ignore return value definition from the called task flow by not identifying any return values on the task flow call activity in the calling task flow.

The task flow call activity returns values by reference. For this reason, you do not need to make a copy of the values that you want to return to the calling task flow.

20.5.1 How to Specify a Return Value from a Bounded Task Flow

You specify a return value definition on the called task flow and add a parameter to the task flow call activity in the calling task flow that retrieves the return value at runtime.

Before you begin:

Create a bounded or unbounded task flow (calling task flow) and a bounded task flow (called task flow). For more information, see Section 18.2, "Creating a Task Flow."

It may be helpful to have an understanding of the interaction between the calling task flow and the called task flow. For more information, see Section 20.5, "Specifying a Return Value from a Bounded Task Flow."

To specify a return value from a called bounded task flow:

In the Application Navigator, double-click the source file for the called task flow.
In the overview editor, click the Parameters navigation tab.
Click the Add icon next to the Return Value Definitions category and add values as follows to define a return value:
- Name: Enter a name to identify the return value. For example, returnValue1.
- Class: Enter a Java class that defines the data type of the return value. The default value is java.lang.String.
- Value: Enter an EL expression that specifies where to store the return value when the called task flow exits. For example, enter an EL expression similar to the following:
  
  #{pageFlowScope.ReturnValueDefinition}
In the Application Navigator, double-click the source file for the calling task flow.
In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a task call activity onto the diagram.
In the Property Inspector for the task flow activity, expand the Parameters section, click the Add icon next to the Return Values entry and add values as follows to define a return value:
- Name: Enter a name to identify the return value. For example, returnValue1.
  
  The value you enter must match the value you entered for the Name field when you defined the return value definition in step 3.
- Value: Enter an EL expression that specifies where to store the return value when the called task flow exits. For example, enter an EL expression similar to the following:
  
  #{pageFlowScope.ReturnValueDefinition}
  
  The value you enter must match the value you entered for the Value field when you defined the return value definition in step 3.

20.5.2 What Happens When You Specify a Return Value from a Bounded Task Flow

At design time, JDeveloper writes entries to the source files for the task flows that you configured. Example 20-7 shows an example entry that JDeveloper writes to the source file for the calling task flow.

Example 20-7 Metadata in the Calling Task Flow to Specify a Return Value

<task-flow-call id="taskFlowCall1">
      <return-value id="__3">
        <name id="__4">returnValue1</name>
                <value id="__2">#{pageFlowScope.ReturnValueDefinition}</value>
      </return-value>
    </task-flow-call>

Example 20-8 shows an example entry that JDeveloper writes to the source file for the called task flow.

Example 20-8 Metadata in the Called Task Flow to Specify a Return Value

<return-value-definition id="__2">
      <name id="__3">returnValue1</name>
      <value>#{pageFlowScope.ReturnValueDefinition}/</value>
      <class>java.lang.String</class>
 </return-value-definition>

At runtime, the called task flow returns a value. If configured to do so, the task flow call activity in the calling task flow retrieves this value.