Oracle WebLogic Integration Worklist provides Oracle WebLogic Worklist User Portal, a web-based user portal for interacting with tasks. This portal allows users to see the details of a task, and take actions on a task to move it through its life cycle. Each step in a task plan can define unique actions and thus present its own unique considerations to the user.
Worklist User Portal is an all-purpose user interface that uses the metadata for steps and actions to render a usable interface at each step. The user interface for a given step and action will differ from the user interface for other steps and actions by virtue of the differences in the metadata for those steps and actions. For example, when rendering the user interface at a given step, the Worklist User Portal shows the description and actions the task plan designer defined for that step. Worklist User Portal has only this information to work on when rendering the user interface, and cannot account for any more subtle needs a user may have with regard to this step (For example, summary information that would be needed to enter a value for an action's required properties, or calculations that may be applied to individual task properties to derive the result value for a property)
In some cases, like the previous examples, a given step or the actions that can be taken on that step may require a customized user interface. Worklist accounts for this need for extensibility by allowing a web developer to design a custom web user interface to be used for a given step, or an entire task plan. This custom web user interface is called a Custom Task User Interface. Custom Task UI allows a web developer to design custom pages only where needed, and still use the facilities of the default Worklist User Portal everywhere else. This allows a gradual investment in the customization of the user portal, instead of requiring a wholesale replacement of the Worklist User Portal interface.
A custom interface can be designed for just a step in a task plan or for the entire task plan.
This document provides the following information:
Typical workflow in creating a custom task user interface:
For a sample scenario, see Adding a Customized User Interface in Tutorial: Building a Worklist Application.
The custom task UI page flow can be implemented in one of two ways:
TaskUIPageFlowController
. Note: | This is the preferred method for implementing the custom task UI page flow and this is the method that is assumed in the rest of this section. For information about the various public helper methods available on the controller, see the Javadoc of the controller available at the following location: |
Note: |
http://edocs.bea.com/wli/docs102/worklist.javadoc/index.html |
PageFlowController
. For requirements that must be met when you use this controller, see Task UI Page Flow Requirements.
If you do not extend the custom controller using TaskUIPageFlowController
, you must manually meet the following requirements of a task UI PageFlowController
. These requirements allow a calling task work page flow to call into the task UI page flow and have that page flow return to it via actions the caller is guaranteed to have implemented.
com.bea.wli.worklist.TaskUIPageFlowController
to provide common utility method implementations.
@Jpf.Controller( nested=true )
annotation on the page flow controller class
TaskUIPageFlowController
, this method must call the super.beginActionHelper()
method to correctly initialize its state. Otherwise, this method should obtain an instance of TaskUIContextInfo
to provide context information about the task work controller. This can be obtained from the HTTP session as follows:
import com.bea.wli.worklist.WorklistUIContextHelper;
WorklistUIContextHelper helper =
new WorklistUIContextHelper(getSession());
TaskUIContextInfo contextInfo = helper.getTaskUIContextInfo();
done
action for the custom task UI. This will end the user's session in the custom task UI. What it means to leave a session depends on what the host application that contains the Worklist UI has defined for the lifetime of the session. For example, in Worklist User Portal, leaving a session means to leave the “Work on Task” page and return to the “Home” page of the portal. The UI component for this action (for example, button or link) should use the done
action
context and label text provided in the TaskUIContextInfo
.exit/return
action on the calling page flow.return
action using the taskUIStepDoneAction
on the caller. An example Forward annotation is given below:
@Jpf.Forward(name = "success",
returnAction = "taskUIStepDoneAction")
done
action UI component), the taskUI page flow must return from an internal return
action using the taskUISessionDoneAction
on the caller. What it means to leave a session depends on what the host application that contains the Worklist UI has defined for the lifetime of the session. For example, leaving a session might mean to logout. An example Forward annotation is given below:
@Jpf.Forward(name = "success",
returnAction = "taskUISessionDoneAction")
TaskUIContextInfo
instance passed into the begin action), the taskUI must return from an internal return
action using the taskUIShowTaskListAction
on the caller. An example Forward annotation is given below:
@Jpf.Forward(name = "success",
returnAction = " taskUIShowTaskListAction")
where the returned Forward
instance must have the selected task list view name (as a String
) set on it. An example internal action and Forward construction statement is given below:
@Jpf.Forward(name = "success",
returnAction="taskUIShowTaskListAction")
protected Forward showTaskListAction()
// JSP should pass the view name from the link/button
// etc. the user clicks on the page
String view = getRequest().getParameter("view");
After determining the look and feel of the customized user interface pages, you need to define the logic and use of these pages by creating a Beehive Page Flow. Page Flows allow the design of an user interface on which actions can be defined. Page Flows control the actions and navigation of the web pages in the custom task interface.
<web project name>\src
folder, and select New > Other. The Select a Wizard dialog appears. The Web project corresponds to the Web application of Worklist that acts as the user interface for the system. For more information, see “Worklist Application” in Creating and Managing Worklist Task Plans.
<page flow controller>.java
file@Jpf.Controller(nested = true, simpleActions = { @Jpf.SimpleAction(name = "begin", path = "index.jsp") })
public class <page flow controller> extends PageFlowController
@Jpf.Controller(nested = true)
public class <page flow controller> extends com.bea.wli.worklist.TaskUIPageFlowController {
Note: | This change will result in some compilation errors saying ‘Action "begin" was not found.’ This error will be resolved after you define the begin action. For information about the begin action, see Defining Actions on a Page Flow. To see a list of errors, warnings and information messages in the Problems View, select WindowShow ViewProblems. |
For each web page that you need in the custom task UI, you need to create a Form Bean. These form beans can be represented as inner java classes of the Page Flow Controller, or they can be standalone java classes. Form Beans should implement java.io.Serializable
as described in the JDK Javadoc.
Form Beans are the basis for the data handling done in the web pages for the custom task UI. The Form Bean is a JavaBean object with a number of properties. You need to generate the Setter and Getter methods for each of these properties.
To generate the setter and getter methods:
The Getter and Setter methods for all properties are now generated.
You define actions on the page flow to move between the web pages in your custom task interface and to take appropriate actions on the task. Page Flow actions are methods on the Page Flow Controller that allow navigation within the interface and optionally, calculate results and pass Form Beans to the required web pages.
Form Beans are passed from an action to a web page to populate display fields on the page. These field values are collected and placed into properties on the Form Bean when the web page is submitted back to the server for processing.
Action methods can accept a Form Bean populated as the result of clicking a Submit button on a web page by defining the Form Bean as a parameter to the action method. Action methods can also pass a Form Bean on to a target web page to which the action is forwarding. This is done by passing a Forward Object that has a Form Bean Object set on it.
Define page flow actions for all actions that are designed and required for your custom task interface. In addition, you need to define the begin
action for initializing the Page Flow Controller. The begin
action initializes this controller and calls the super class helper (beginActionhelper
) to initialize task context, standard form beans for a task and action, and property editing support.
Note: | begin() has to call the super class helper only if the custom page controller extends TaskUIPageFlowController . |
Action methods can accept Form Beans and forward to pages using Form Beans. When submitting a web page and in the process of calling the action associated with a Submit, the NetUI framework creates a new form bean instance by default (using the no-arg public constructor for the Form Bean class). This new bean instance is then populated via Java reflection with data from data binding tags in the submitted web page form.
This process has some limitations. For example, if your Form Bean contains transient, hidden information that is not represented in the web page JSP tags, the Form Bean that actually gets passed to the action method (the bean that is created by the NetUI framework) will not have this information.
To avoid the overhead and possible behavioral problems of creating new beans each time an action method is called, you can specify a useFormBean
field on the @Jpf.Action
annotation for an action
method. This allows to hold a single copy of the Form Bean in the Page Flow Controller’s state and the action method then just fetches the object from that state instead of creating a new form bean object.
Worklist provides some built-in support for editing properties in your custom task UI. It includes a JSP tag, default editors, and some helper methods in the base TaskUIPageFlowController
. These facilities allow you to easily edit the following types of properties using out-of-box UI:
In addition, the Property Editor facility allows human users using the custom task UI to easily edit properties using an inline editor (simple form field) as well as a standalone editor for the complex types mentioned above. This facility makes robust editing of properties a fairly simple matter.
Create the following actions in your custom page flow controller to handle task’s user property editor:
okPropAction
– The stand-alone editor returns to this action when you click OK to apply the edit. It returns on this action passing an EditorValueHolder
holding the value that was created or edited in the editor. This action should specify the _editorValue
field of your Page Flow in a useFormBean
attribute in the @Jpf.Action
annotation. This allows the returned or completed editor value form bean to be passed in the _editorValue
field and avoids creating a copy of this potentially large form bean. For an example of this action and its annotations, see Tutorial: Building a Worklist ApplicationcancelPropAction
– This is the action the stand-alone editor calls when the user clicks Cancel in the editor.<edit property action>
– This action handles an initiate stand-alone editor
call that comes from the JSP and the worklist propertyEditor
tag. Your action
method should call the TaskUIPageFlowController.editPropActionHelper
to calculate the stand-alone editor's URI, and then forwards to that URI. This editor is a nested page flow, and returns to this controller (the caller) via the okPropAction
and cancelPropAction
return actions. Note: | The actual name of the action is specified in the Worklist propertyEditor tag in the actionName attribute. |
To create actions on a page flow:
All the actions for the Page Flow are created. You should see code that is similar to the following:
@Jpf.Action()
public Forward newAction1(test_pageflow.Test_pageflowController.NewFormBean form) {
Forward forward = new Forward("success");
return forward;
}
Based on the interface mock ups that you designed, define JSP pages for the custom task UI using Beehive NetUI data binding JSP tags to render web forms that can read data from and write data into form beans. The use of these tags greatly simplifies the process of writing a data-driven JSP page.
You can create JSP files in the Page Flow perspective as follows:
Note: | In the Page Flow Controller, if there is a reference to a unavailable JSP, grayed out JSP pages are automatically listed under the Pages node in the Page Flow Explorer View. You can right-click on these JSPs and select Create to create the JSP file. |
<%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
<%@taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
<%@taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
<netui:html>
<head>
<netui:base/>
</head>
<netui:body>
<p>Beehive NetUI JavaServer Page - ${pageContext.request.requestURI}</p>
</netui:body>
</netui:html>
<p>Beehive NetUI JavaServer Page - ${pageContext.request.requestURI}</p>
and insert the text form in between the <netui:body>
and the </netui:body>
tag.
After designing the custom task UI for a step in a task plan or for an entire task plan, you need to register the custom task UI. To register the custom task UI, you need to add mapping entries to <Web project name>/WebContent/WEB-INF/task-ui-registry.xml
registry file.
Note: | The Web project corresponds to the Web application of Worklist that acts as the user interface for the system. For more information, see “Worklist Application” in Creating and Managing Worklist Task Plans. |
This XML registry file is associated with the schema for the Worklist Task UI Registry, and this schema is registered with Workshop.
Open the file to edit it. In the Source tab, the initial contents of this XML file should look something like this:
<task-ui-registry xmlns="http://www.bea.com/wli/worklist/taskuiregistry">
</task-ui-registry>
In the Design tab, you can right-click any node in the tree view to act on it. You can delete nodes, and add children to nodes.
To register the custom task UI, you need the following information:
Task Plan ID
– The ID of the task plan for which the custom task UI applies, in external format (example, /<path>/<task plan name>:<version>)Step Name
– Required only when registering the custom task UI for a specific step in the task plan. Custom Task UI URI
– The web URI of the Page Flow Controller that will control the UI to be applied to this step or task plan..jpf
extension even though the Page Flow Controller file is really .java
file. This is needed to allow servlet filters in the web application to fire correctly. Note: | Step name is not required if you are registering the custom task UI designed for the entire task plan and not just a step in the task plan. |
To edit task-ui-registry.xml
first switch to the Package Explorer view and then do the following in the Design tab of the editor:
task-ui-registry.xml
.Note: | The Web project corresponds to the Web application of Worklist that acts as the user interface for the system. For more information, see “Worklist Application” in Creating and Managing Worklist Task Plans. |
task-ui-registry.xml
, and select Add Child.Selectstep-override
or task-plan override
based on whether you created the custom task UI for a step or the entire task plan. This adds a new override element under the root element.step-override
or task-plan-override
element and specify the task plan ID, step name, and custom task UI URI. Note: | Step name is not required if you are registering the custom task UI designed for the entire task plan and not just a step in the task plan. |
To deploy the custom task user interface:
Note: | The Web project corresponds to the Web application of Worklist that acts as the user interface for the system. For more information, see “Worklist Application” in Creating and Managing Worklist Task Plans. |
.
The custom Task UI is deployed on the server.