24 Working with Task Flows

Create custom task flows as containers for components such as data controls, portlets, content, and other task flows. You can reuse the same task flow on multiple portal pages.

Permissions:

To perform the tasks in this chapter, you need one of the following portal-level permissions:

• Assets: Create, Edit, and Delete Assets or Create Assets and Edit Assets (standard permissions)

• Task Flows: Create, Edit, and Delete Task Flows or Create Task Flows and Edit Task Flows (advanced permissions)

See About Roles and Permissions for a Portal.

Topics:

• About Task Flows

• Creating a Task Flow

• Editing a Task Flow

• Consuming a Data Control in a Task Flow

• Controlling the Data Displayed in a Task Flow Using a Data Control

• Adding a Task Flow to a Portal Page

• Managing a Task Flow

About Task Flows

Task flows are containers in which you can add components such as data controls, portlets, content, and other task flows. Task flows provide the advantage of being reusable, so that the same task flow can be consumed on multiple portal pages. You can create your own custom task flow, and add components to the task flow.

For example, data retrieved from a web service by a data control can be rendered on a portal page in a custom task flow. You can select how to present the data, appropriate to the specific data control. For example, the data can be shown as a table, graph, form, button, or label. You can enable users to control the data displayed by a data control by including a parameter form along with the data presentation. You can also wire data control parameters to task flow parameters so that the data control retrieves data based on the values specified for the task flow parameters. Users can change the value of the task flow parameters in the page editor to request the corresponding data from the data control.

The basic steps to accomplish this are:

1. Create a data control (see Creating a Web Service Data Control).

2. Create a custom task flow (see Creating a Task Flow).

3. Add the custom task flow component to a page, then add the data control you want to render on the page (see Consuming a Data Control in a Task Flow and Controlling the Data Displayed in a Task Flow Using a Data Control).

Creating a Task Flow

WebCenter Portal provides many built-in task flows, available through the resource catalog in the page editor. You can also create custom task flows as portal assets, which you can add to your portal pages to provide presentations of the data retrieved by web service data controls, along with other components such as portlets, content, and other task flows.

To create a task flow:

1. Navigate to one of the following:

   • To create an application-level task flow, go to the Shared Assets page. For more information, see Accessing Shared Assets.

   • To create a portal-level task flow, go to the Assets page for the portal in which you want to create the task flow. For more information, see Accessing Portal Assets.
2. In the left pane, under UI Components, click Task Flows.
3. In the toolbar, click Create to open the Create New Task Flow dialog.
4. In the Name field, enter a name for the task flow.

   The name is displayed in the resource catalog.

5. (Optional) In the Description field, enter a meaningful description for the task flow.

   The description is displayed in the resource catalog.

6. From the Task Flow Style drop-down list, select the task flow style to use for the task flow.

   For more information, see Working with Task Flow Styles.

7. Click Create.

   The newly created task flow is listed on the Assets or Shared Assets page. The empty check box in the Available column indicates that the task flow is not yet published and hence is not available for users to add to their pages. To publish the task flow, select the check box.

   For more information, see Showing and Hiding Assets.

You can now edit the new task flow using the page editor and populate it with different resources, including data controls, that are available from the resource catalog. For more information, see Editing a Task Flow and Consuming a Data Control in a Task Flow.

Editing a Task Flow

When you first create a task flow, it contains only the content specified by the selected task flow style. To add more content to the task flow, you must edit the task flow's view fragment. You can add a variety of resources to the view fragment from the resource catalog, including data controls. You may also want to edit your task flow to create or modify task flow parameters.

The most common way to edit a task flow is to use the page editor. However, if you prefer, you can edit the source code of the task flow directly. For example, you may want to clean up the page fragment and its page definition when you delete a referenced component, such as a data control, or make adjustments to the task flow's code. For more information, see Editing the Source Code of an Asset.

To edit a task flow in the page editor:

1. Navigate to one of the following, depending on where the task flow was created:

   • To edit an application-level task flow, go to the Shared Assets page. For more information, see Accessing Shared Assets.

   • To edit a portal-level task flow, go to the Assets page for the portal in which the task flow was created. For more information, see Accessing Portal Assets.

2. In the left pane, under UI Components, click Task Flows.
3. Click the Edit quick link for the task flow that you want to edit (Figure 24-1).

   Figure 24-1 The Edit Quick Link for a Task Flow

   
   Description of "Figure 24-1 The Edit Quick Link for a Task Flow"
4. In either Design view or Structure view of the page editor, add whatever resources you want to the task flow's view fragment.

   • For information about adding data controls to your task flow to determine what data you want to display, see Consuming a Data Control in a Task Flow.

   • For information about adding other content using the page editor, see Adding Components to a Page and Working in Structure View in the Page Editor.

5. Click Save to save your changes.

Consuming a Data Control in a Task Flow

When published, a data control is automatically available in the resource catalog and can therefore be added to task flows. You can consume a data control in a task flow and render it in different presentations, such as a table, graph, or form.

If the data control defines parameters, you can also include a parameter form in the task flow so that users can specify a values for a data control parameter and display data based on that value.

Note:

Adding the same data control more than once to the same task flow may produce unexpected results. If you wish to use the same data control multiple times on a page, then the recommended approach is to create separate task flows for each instance.

This section includes the following topics:

• Supported Presentations

• Adding a Data Control to a Task Flow

• Presenting Data as a Table

• Presenting Data as a Form

• Presenting Data as a Graph

• Repairing a Task Flow with Broken References to a Data Control

Supported Presentations

Data retrieved using a web service data control can be rendered in a task flow in different ways. While editing a task flow, when you click Add against a data control's objects in the resource catalog, the Add menu displays different drop handlers. The drop handlers enable you to add a data control's objects as UI elements such as tables, graphs, forms, buttons, or labels. Depending on the type of object and the flavors supported, you can add different UI elements.

• Table—This option is displayed when you select a data control accessor that returns a collection of objects that can be displayed in the columns of a table. Select this option to display data in a tabular layout.

  For more information, see Presenting Data as a Table.

• Form—This option is displayed when you select a data control accessor that returns a collection of objects that can be displayed in a form. Select this option to display source data in a form.

  For more information, see Presenting Data as a Form.

• Graph—This option is displayed when you select a data control accessor that returns a collection of objects that can be displayed as a graph. This is useful for the purpose of analysis, when you want to generate a report. Select this option to display your data graphically, as a bar, pie, line, or an area chart.

  For more information, see Presenting Data as a Graph.

• Button or Link—The ADF Button, ADF Link, ADF Image Link, and ADF Toolbar Button options are displayed when you select a data control's methods or operations that perform an action. Select any of the button or link options while adding methods or operations such as Create, Update, Delete, Commit, Rollback, Save, or Close. Different options are available for different data controls depending on the methods exposed by the data source.

• Text or Label—The ADF Output Text, ADF Output Text w/ Label, ADF Output Formatted, ADF Output Formatted w/ Label, ADF Input Text, ADF Input Text w/Label, and ADF Label options are displayed when you select a data control's attributes or methods that return a single object. An attribute can be a scalar parameter of an accessor, a method return, or an object member of a complex parameter. Select a text or label option depending on whether you want to display the value to users or want users to specify a value.

When you add a data control inside a task flow, you can wire data control parameters to task flow parameters so that the data control retrieves data based on a parameter value that you specify. For more information, see Binding a Data Control Parameter to a Task Flow Parameter.

Adding a Data Control to a Task Flow

When you add a data control, its accessors, or its methods to a task flow, you can select different options for visualizing the data.

Depending on the object you select and the presentations it supports, different options are listed in the Add menu. For more information, see Supported Presentations.

To add a data control to a task flow:

1. Edit the task flow in the page editor, as described in Editing a Task Flow.
2. In the resource catalog, navigate to the section that contains data controls.

   Tip:

   The location of data controls depends on the resource catalog used for editing pages. For example, in the default resource catalog, runtime-created data controls are located in the Data Controls folder, which is nested inside the Integration folder.

   See Also:

   Adding a Component to a Page.

3. Click the data control to display its content.
4. Drill down if necessary and click Add next to the data control accessor.
5. From the drop-down menu, select one of the following options, depending on how you want to visualize the data:

   • Table—For more information, see Presenting Data as a Table.

   • Form—For more information, see Presenting Data as a Form.

   • Graph—For more information, see Presenting Data as a Graph.

Presenting Data as a Table

The Table option is displayed only for data control accessors that return a collection of objects that can be displayed in the columns of a table.

When you add a data control to a task flow as a table, you have two options:

• Read-only Table—Add the data control as a read-only table. The content in the table cannot be edited.

• Table—Editable tables are not currently supported.

To present data as a table:

1. Follow the steps in Adding a Data Control to a Task Flow, choosing Table from the drop-down menu.
2. On the Type page of the Create Table wizard, select Read-only Table.
3. (Optional) In the Behavior section, select one or more of the following options to enable customization of the table:

   • Row Selection—Enables selection of a row on which the user can perform any operation.

     When you enable row selection in a table and select a row, internally, the column values of the selected row are added into a row selection bean. The column values are stored in the following EL format:

     #{dataComposerViewContext.dataSelection.COLUMN_NAME}
     

     You can use this format to reference the table columns from elsewhere in the task flow. Typically, this is useful in task flows where data presentations are wired in a master-detail relationship.

     If you need EL assistance, an application developer can provide an EL expression; see Expression Language Expressions in Developing for Oracle WebCenter Portal.

     Note:

     Row selection is not supported if the data control contains bind parameters.

   • Filtering—Displays a text field above each column in the table. Users can specify a filter criteria in these text fields to display only those rows that match the criteria.

   • Sorting—Displays Up and Down arrows in each column header that users can click to sort the table in ascending or descending order by that column.

4. Click Next.
5. On the Items page, by default all the accessor attributes are selected to display in the table. If there are any accessor attributes that you do not want to display in the table, select them in the Selected Items list and move them to the Available Items list.

   Note:

   If an item has a scalar value, you cannot add the item to the table after initial creation.

6. Use the arrow icons next to the Selected Items list to determine the order in which the attributes are displayed as columns in the table.
7. Click Next.
8. On the Columns page, for each column in the table, specify display options as follows:

   • Column Header—Specify a name to use as a header for the selected column.

   • Display As—Select an output format for the column:

     • Output Text—Display data records as styled read-only text.

     • Output Formatted—Display data records as read-only text with limited formatting.

     • Hyperlink—Display data in the selected column as a link, for example, when connecting to an employee database, you can display employee names as hyperlinks so that, when users click a link, it takes them to the employees profile page.

   • Align—Select whether the data in the table cells must be aligned to the center, end, left, right, or start.

   • URL—Create dynamic URLs based on the values coming from the data control. Specify the URL along with the EL value that must be appended to the URL. The URL field is enabled only if you selected Hyperlink in the Display As list.

     For example, if you are adding a WebCenter Portal service data control as a table that lists the portals of which the current user is a member, you can enter /spaces/#{row.item} in the URL field to display portal names as hyperlinks. Clicking a portal name in the table opens the portal.

   • Open in New Window—Select whether to open the URL in a separate window. This check box is available only if you selected Hyperlink in the Display As list.

9. If the data control has associated parameters that you want to expose on a parameter form, click Next.
   1. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      Any parameters you select in this way are displayed in a parameter form above the table, form, or graph that you are adding. Users can specify a value and click a button to refresh the data according to the values they specified.

   2. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      The initial value displayed in this field is specified when the data control was created. You can override this initial value to control the initial display of data.

   3. In the Submit Button Label field, enter the text that you want to be displayed on the button that users click to submit values on the parameter form.
10. Click Create.

Presenting Data as a Form

The Form option is displayed only for data control accessors that return a collection of objects that can be displayed as a form element.

When you add a data control to a task flow as a form, you have two options:

• Read-only Form—Add the data control as a read-only form. The form displays data based on your specification, but the data cannot be edited.

• Form—Currently editable forms are not supported.

To present data as a form:

1. Follow the steps in Adding a Data Control to a Task Flow, choosing Form from the drop-down menu.
2. On the Type page of the Create Form wizard, select Read-only Form.
3. Select Include Navigation Controls to display First, Previous, Next, and Last buttons on the form. Navigation controls are helpful when multiple records are retrieved from the data source.

   Note:

   Navigation controls may not work properly if the data control provides bind parameters.

4. Click Next.
5. On the Items page, by default all the accessor attributes are selected to display in the form. If there are any accessor attributes that you do not want to display in the form, select them in the Selected Items list and move them to the Available Items list.

   Note:

   If an item has a scalar value, you cannot add the item to the form after initial creation.

6. Use the arrow icons next to the Selected Items list to determine the order in which the attributes are displayed as fields in the form.
7. Click Next.
8. On the Fields page, for each field in the form, specify display options as follows:

   • Label—Specify text to use as a label for the selected field.

   • Form Component—Select Read Only Text to display the field as read-only text.

9. If the data control has associated parameters that you want to expose on a parameter form, click Next.
   1. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      Any parameters you select in this way are displayed in a parameter form above the table, form, or graph that you are adding. Users can specify a value and click a button to refresh the data according to the values they specified.

   2. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      The initial value displayed in this field is specified when the data control was created. You can override this initial value to control the initial display of data.

   3. In the Submit Button Label field, enter the text that you want to be displayed on the button that users click to submit values on the parameter form.
10. Click Create.

Presenting Data as a Graph

The Graph option is displayed only for data control accessors that return a collection of objects that can be displayed as a graph. You can display data as a bar, pie, line, or an area chart.

To present data as a graph:

1. Follow the steps in Adding a Data Control to a Task Flow, choosing Graph from the drop-down menu.
2. On the Type page of the Create Graph wizard, select the desired type of graph: Area, Bar, Line, or Pie, then click Next.
3. On the Sub-Type page, select a subtype of the type of graph you selected, then click Next.

   For example, you can display a bar graph as a Bar, Dual-Y Bar, Split Dual-Y Bar, Percent, Stacked Bar, Dual-Y Stacked Bar, Split Dual-Y Stacked Bar, or Floating Stacked Bar graph.

4. On the Layout page, select your desired layout of graph elements, such as the title, legend, and footnote, then click Next.
5. On the Placement page, select how you want each of the available accessor attributes to be used in the graph, then click Next.

   For example, select which accessor attribute to use to determine the values for the x-axis and the bars in a bar graph. Select <none> if you do not want to use an accessor attribute in the graph.

6. On the Format page, enter the text to use for each graph element, such as the title, legend, and footnote.
7. If the data control has associated parameters that you want to expose on a parameter form, click Next.
   1. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      Any parameters you select in this way are displayed in a parameter form above the table, form, or graph that you are adding. Users can specify a value and click a button to refresh the data according to the values they specified.

   2. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

      The initial value displayed in this field is specified when the data control was created. You can override this initial value to control the initial display of data.

   3. In the Submit Button Label field, enter the text that you want to be displayed on the button that users click to submit values on the parameter form.
8. Click Create.

Repairing a Task Flow with Broken References to a Data Control

If you add a data control to a task flow, editing or deleting the data control at a later date may break the task flow. You can repair the task flow by removing references to the data control from the task flow's source files.

To repair a task flow with broken references to a data control:

1. Edit the source code of the task flow, as described in Editing the Source Code of an Asset.
2. Click each of the three tabs, Taskflow Definition, Fragment, and Page Definition, and remove any references to the edited or deleted data control from the source files.

   Tip:

   To ensure that you do not end up with an invalid task flow that does not render properly, edit the source code very carefully.

3. Click OK.

Controlling the Data Displayed in a Task Flow Using a Data Control

Data control parameters are used to restrict the data retrieved by a data control based on the criteria you specify. For more information, see Creating a Web Service Data Control.

If a data control provides parameters, there are several ways you can change the values of those parameters after you have added the data control to a task flow.

This section includes the following subsections:

• Adding a Parameter Form to a Data Presentation

• Editing Data Control Parameter Values

• Binding a Data Control Parameter to a Task Flow Parameter

Adding a Parameter Form to a Data Presentation

If you want end users to be able to change the data displayed in the task flow, you can include the data control's parameters in a parameter form in the task flow. Users can enter values for the data control parameters in the parameter form and the data displayed in the task flow reflects the values specified.

To add a parameter form to a task flow used to present data on a portal page:

1. Add the data control to a task flow as a table, form, or graph, as described in Consuming a Data Control in a Task Flow.
2. On the Visualization Parameter page, select the check box next to the parameter for which you want users to be able to provide their own values.

   Any parameters you select in this way are displayed in a parameter form above the table, form, or graph that you are adding. Users can specify a value and click a button to refresh the data according to the values they specified.

3. In the Default Value field, enter the default value to use for the parameter.

   The initial value displayed in this field is specified when the data control was created. You can override this initial value to control the initial display of data.

4. In the Submit Button Label field, enter the text that you want to be displayed on the button that users click to submit values on the parameter form.
5. Click Create.

Editing Data Control Parameter Values

If you can edit the task flow where the data control is visualized, you can edit the data control's parameter values in the Component Properties dialog of the table, form, or graph to control the display of data.

To edit data control parameter values:

1. Edit the task flow in the page editor, as described in Editing a Task Flow.
2. Click the table, form, or graph, and choose Data from the View Actions menu.
3. In the Data dialog, modify the values for any of the listed parameters.
4. Click OK.
5. Click Save to save your changes.

   The table, form, or graph now displays data specific to the parameter values provided.

Binding a Data Control Parameter to a Task Flow Parameter

You can bind a data control parameter to a task flow parameter so that the data control retrieves data based on the value specified for the task flow parameter.

You can bind a data control parameter to a task flow parameter so that the data control retrieves data based on the value specified for the task flow parameter.

For example, if your task flow contains an employee information data control with a bind parameter to limit the data retrieved to a specified job role only, you can create a corresponding job parameter on the task flow. Users who can edit the task flow can specify a job title for the task flow parameter so that the data control displays the employees with the specified job.

To bind a data control parameter to a task flow parameter:

1. Create the task flow parameter as follows:
   1. Edit the task flow in the page editor.
      See Editing a Task Flow.
   2. Click the Task Flow Properties icon.

      Figure 24-2 The Task Flow Properties Icon

      
      Description of "Figure 24-2 The Task Flow Properties Icon"
   3. Enter a Name, Type, and Storage value for the task flow parameter.

      The Storage value identifies the scope for the parameter. It specifies the location for storing the parameter value. Out of the box, you are provided with four storage options, as described in the following table. However, you can specify any custom storage location by providing the EL value.

      If you need EL assistance, an application developer can provide an EL expression; see Expression Language Expressions in Developing for Oracle WebCenter Portal.

      Table 24-1 Storage Values

      Name	Description
      pageFlowScope	The value is available to all instances of the task flow on the page.
      viewScope	The value is available only to the selected instance, for the current user.
      applicationScope	The value is available to all instances of the task flow within the application or across applications.
      sessionScope	The value is available only to the current user, for the current session.

   4. Make a note of the value in the Storage field.
   5. Click OK.
2. Click the table, form, or graph that displays data from the data control, and choose Data from the View Actions menu.
3. In the Data dialog, paste the Storage value you copied earlier into the field for the data control parameter that you want to bind to the task flow parameter.
4. Click OK.

The data control parameter now uses the value of the task flow parameter to drive the content of the table, form, or graph.

Note:

If you are using a web service data control for which you have not defined a parameter value, you must set an initial value for the task flow parameter. If not, the task flow displays an empty presentation (table, form, or graph). Therefore, in the Data dialog for a web service data control, you must pass an initial value for the task flow parameter as shown in the following example:

#{empty pageFlowScope.stock_Quote ? 'ORCL' : pageFlowScope.stock_Quote}

Adding a Task Flow to a Portal Page

When published (marked as Available), task flows are automatically available in the resource catalog for selection to add to a page in the page editor. For information about creating task flows that can be used on a page to present the data retrieved by data controls, see Creating a Task Flow.

To add a task flow to a portal page:

1. Open the page in which you want to present the data in the page editor.

   For more information, see Opening a Page in the Page Editor.

2. Click Add Content in the area of the page where you want to add the task flow to open the resource catalog and select the task flow. For more information, see Adding a Component to a Page.

   Tip:

   The location of task flows in the resource catalog depends on the resource catalog being used by the page. For example, in the default resource catalog, task flows are present in the Task Flows folder which is nested inside the UI Components folder.

3. If the data control defines parameters that are bound to the task flow’s parameters, the task flow parameters drive the data that is displayed. Select the task flow on the page, click its View Actions menu, then select Parameters to open the Parameters dialog for the task flow. Change parameters as desired.
4. Click Save to save your changes.

   If the data presentation includes a parameter form, users can enter values to change the data displayed on the page.

Managing a Task Flow

The following options are available on the Assets and Shared Assets page to enable you to manage task flows.

See Also:

Accessing Portal Assets and Accessing Shared Assets

• Create—For more information, see Creating a Task Flow.

• Delete—You can delete task flows when they are no longer required.

  For more information, see Deleting an Asset.

• Upload—You can upload an archive file that contains a task flow from another portal.

  For more information, see Uploading an Asset.

  You cannot use the Upload option to upload a task flow that has been exported from Oracle JDeveloper.

  If the task flow that you are uploading consumes data controls, you must first upload those data controls. For more information, see Managing Web Service Data Controls.

• Download—You can download a task flow into an archive file for uploading into another portal or for importing into JDeveloper.

  Task flows created at runtime may contain components that are bound to data controls. When you download such a task flow, the referenced data controls are not downloaded. When you open the task flow in JDeveloper, you will not see a fully running task flow because the associated data controls are not available in JDeveloper. The task flow will work properly only when you upload it back into WebCenter Portal.

  For more information, see Downloading an Asset.

• Actions

  • Copy—You can create a copy of a task flow. The Copy feature enables you to replicate a local task flow in the runtime environment without having to actually export and upload the task flow.

    Fore more information, see Copying an Asset.

  • Security Settings—You can control whether all users or only specific users or groups can access the task flow that you created.

    For more information, see Setting Security for an Asset.

  • Show Properties—Each task flow has certain properties associated with it that control how it is displayed in a portal. These properties are summarized in the Show Properties dialog.

    For more information, see Viewing Information About an Asset.

  • Edit Source—For more information, see Editing the Source Code of an Asset. When editing the source code of a task flow, consider the following:

    • Do not refer to a Java bean that is not available on the portal server.

    • Do not refer to functions in JavaScript files that are not available on the portal server.

    • Do not refer to other task flows that are not available on the portal server.

    • Do not add a data control that has been created in JDeveloper. The data control may not be available on the portal server, which will cause the rendition of the task flow to break.

  • Edit Properties—Each task flow has certain properties associated with it that control how it is displayed in the portal. You can edit these properties through the Edit Properties dialog.

    For more information, see Setting Properties on an Asset.

• Preview—You can preview how the task flow will appear when displayed on a page.

  For more information, see Previewing an Asset.

• Available—You can control whether or not a task flow is included in the resource catalog, and therefore whether or not it is available for use in a portal.

  For more information, see Showing and Hiding Assets.

  Tip:

  In addition to showing or hiding a task flow in the resource catalog, you can also control whether a shared task flow is available to any, all, or selected portals in WebCenter Portal. For more information, see Setting Properties on an Asset.

• Edit—For more information, see Editing a Task Flow.