This chapter explains how to build a client application to display your process instances using the milestones you defined when creating your Guided Business Process.
This chapter includes the following sections:
Section 29.1, "Introduction to Building a Guided Business Process Client Application"
Section 29.2, "Developing a Guided Business Process Client Application with Oracle ADF"
Section 29.3, "Securing the Guided Business Process Client Application"
Section 29.4, "Localizing a Guided Business Process Client Application"
Guided Business Processes provide you with predefined ADF tasksflows that you can use to build an ADF application to display and run Guided Business Processes.
If the provided ADF taskflows do not satisfy your requirements, then you can use the set of APIs that Guided Business Processes provide, to obtain the information that your UI client applications displays. These APIs allow you to obtain data about the milestones and tasks using web services and Enterprise Java Beans.
A Guided Business Process client application provides a user interface for the Guided Business Process task flow. The client application can be developed in a simple ADF JSPX page in any configuration. Typically, a client application includes a region displaying the Activity Guide tree and another region displaying the details of the specific node selected from the tree.
One way to display these two regions is to include a dynamic region on the left side of a JSPX page and a human task flow on the right. However, any configuration is possible.
To develop a Guided Business Process client application:
In JDeveloper, create a new application.
Right-click the ViewController Project and then select Project Properties.
Select Libraries and Classpath.
Click Add JAR/Directory.
A file browser dialog box opens.
Select the oracle.bpm.activityguide-ui.jar file located under <JDEV_HOME>/jdeveloper/soa/modules.
Click Select.
Add the run-time shared library references oracle.soa.bpel. and oracle.soa.workflow.wc to the weblogic-application.xml file by adding the following code:
<library-ref> <library-name>oracle.soa.bpel</library-name></library-ref><library-ref> <library-name>oracle.soa.workflow.wc</library-name> </library-ref>
Create a new JSF Page (.jspx) in which to display the Activity Guide.
Drag and drop the following task flows onto the JSF Page (.jspx):
ag-tasktree-task-flow: for displaying the Activity Guide tree
ag-humantask-task-flow: for displaying the individual Activity Guide node
Note:
Dragging and dropping a task flow automatically creates a region for that task flow.Create a file with the Activity Guide properties.
Note:
Generally you name this fileactivityguide.properties. If you choose another name then you must provide its value to the ag-tasktree-task-flow using the parameter AGPropsBeanName.For more information on Activity Guide properties, see Section 28.7, "Configuring Activity Guide Properties".
If using identity propagation to secure the Activity Guide, then the properties WorkflowAdminUser and WorkflowAdminPassword are not required.
To enable a task flow popup with summary information, include the following properties in the Activity Guide properties file:
AGTasksPopupTaskFlowID: Use this parameter to display a task flow summary in ADF dynamic regions. Enter the relevant task flow ID.
If this parameter is not set then the popup shows the value of OutputText as the default task summary.
If you provide an invalid task flow region ID, then the Guided Business Process does not render the region and logs a message in the server log.
Configure the Activity Guide to display a refresh button in the Activity Guide tree., using the following alternative methods:
In the Activity Guide properties file, add the parameter ShowRefreshButton. Set its value to true to enable the display of a refresh button, and false or any other value to disable the refresh button.
In the Activity Guide tree task flow, add the parameter ShowRefreshButton and set its value to true. This task flow parameter overrides the value of the parameter set in the Activity Guide properties file.
If the value of the ShowRefreshButton parameter is 'empty' or 'null', then the property ShowRefreshButton in the file activityguide.properties defines if the refresh button is shown. If the activityguide.properties file does not specify a value for this property then the refresh button is not shown in the client.
Example 29-1 illustrates adding a ShowRefreshButton parameter to the tree task flow.
Example 29-1 Add the ShowRefreshButton Parameter to the Tree Task Flow
<taskFlow id="dynamicRegion1"
taskFlowId="${backingBeanScope.dynamicLeft.dynamicTaskFlowId}"
xmlns="http://xmlns.oracle.com/adf/controller/binding" >
<parameters>
<parameter id="ShowRefreshButton" value="true”
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
</parameters>
</taskFlow>
Edit the file adfc-config.xml to include the location of the activity.properties file. This should be the absolute path to the activityguide.properties file.
An example adfc-config.xml is shown in Example 29-2.
Example 29-2 adfc-config.xml File with Reference to activityguide.properties File
<managed-bean id="__10">
<managed-bean-name id="__12">agProps</managed-bean-name>
<managed-bean-class id="__11">oracle.bpel.activityguide.ui.beans.model.AGProperties</managed-bean-class>
<managed-bean-scope id="__9">session</managed-bean-scope>
<managed-property id="__15">
<property-name>agPropsFilePath</property-name>
<property-class>java.lang.String</property-class>
<value id="__14"><!-- relative path or absolute path should be given here-->/activityguide.properties</value>
</managed-property>
</managed-bean>
Create a Workflow Service client configuration file. An example is shown in Example 29-3.
Example 29-3 Workflow Services Client Configuration File
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflowServicesClientConfiguration xmlns="http://xmlns.oracle.com/bpel/services/client">
<server default="true" name="default">
<localClient>
<participateInClientTransaction>false</participateInClientTransaction>
</localClient>
<remoteClient>
<serverURL>t3://host:port</serverURL>
<initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactory>
<participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>
<soapClient>
<rootEndPointURL>http://host:port</rootEndPointURL>
<identityPropagation mode="dynamic" type="saml">
<policy-references>
<policy-reference enabled="true" category="security"
uri="oracle/wss10_saml_token_client_policy"/>
</policy-references>
</identityPropagation>
</soapClient>
</server>
A JDeveloper application with an ADF Web project is created. The application includes the following:
JSF page with two regions, one for the Activity Guide tree and the other for Activity Guide node details.
An activityguide.properties file.
At run time, the Oracle ADF application displays the Guided Business Process developed at design time. A contextual event mechanism in the common ADF layer handles communication between the Activity Guide tree and Activity Guide node details, respectively.
When you select a Guided Business Process instance, the Activity Guide tree displays the information for the Activity Guides, milestones, and tasks in that Guided Business Process instance.
Alternatively, you can configure the AGInstanceID property in the activityguide.properties file for the JSF Page to render the following information for a particular Guided Business Process instance:
Activity Guide
Milestones
Tasks
When selecting a milestone node in the Activity Guide tree, it retrieves or refreshes the sub-tree beneath the milestone.
When selecting a task node in the Activity Guide tree, it displays detailed task information for the task.
Securing the Guided Business Process client application ensures that only users with proper credentials can complete the tasks outlined in the Guided Business Process. Security features include authentication, authorization and policy enforcement.
If you localize a Guided Business Process client application then you can run the client in all the supported languages you defined.
If you want to localize a Guided Business Process application you must localize the following components when you design a Guided Business Process:
AG Title
AG Description
Milestone Title
Milestone Description
Task blocked explanation text
The Guided Business Process automatically translates String that are part of the user interface, such as "display title" or Description. Guided Business Processes support the following locales:
French
German
Italian
Spanish
Brazilian
Japanese
Korean
Simplified Chinese
Traditional Chinese
Arabic
Czech
Danish
Dutch
Finnish
Greek
Hebrew
Hungarian
Norwegian
Polish
Portuguese
Romanian
Russian
Slovak
Swedish
Thai
Turkish
See Section 29.4.1, "How to Configure the Supported Locales for a Guided Business Process Client Application" for more information on how to localize a Guided Business Process.
Before configuring a Guided Business Process application to support additional locales, ensure that you provided the required bundles for those locales when developing the Guided Business Process.
To configure the supported locales for a Guided Business Process Client application:
Open the client application in Oracle JDeveloper.
Open the jspx client page.
Select Source View and modify the locale using the following code:
<f:view locale= #{view.locale}>
Edit the faces-config.xml file located under Project_Root /public_html/WEB-INF.
Click the Overview tab in the editor window.
In the editor window, select Application.
In the Locale Config area, click New to open the Property Inspector to add the supported locales.
Add the supported locales.
Example 29-4 shows how the faces-config.xml file looks after adding a set of supported locales.
Example 29-4 faces-config.xml file
<locale-config> <default-locale>en</default-locale> <supported-locale>ar</supported-locale> <supported-locale>ca</supported-locale> <supported-locale>cs</supported-locale> <supported-locale>da</supported-locale> <supported-locale>de</supported-locale> <supported-locale>zh_CN</supported-locale> </locale-config>
Set the browser locale to a supported locale.
Run the client page.
Guided Business Processes provide you a set of APIs that enable you to get details about the available milestones and the tasks that compose them. If the predefined Activity Guide ADF taskflows do not satisfy your requirements then you can use these APIs to obtain the information that you display in the client application.
This API is designed to support the following user navigation scenarios in an application displaying a Guided Business Process:
Display a list of Guided Business Process instances using a filter. Available filters are:
MY: Guided Business Process instances containing active tasks assigned to the user.
REPORTEES: Guided Business Process instances containing active tasks assigned to reportees to the current user.
PREVIOUS: Guided Business Process instances containing completed tasks assigned to the user, and instances in which a particular task is reassigned to another user.
ADMIN: Guided Business Process instances visible to the Guided Business Process administrator. Active instances can be assigned to any user.
Note:
The BPMAGAdmin role maps to a user with an Administrator role assigned. This role enables the user to query for all the Guided Business Process instances available in the server, including completed, active, and instances with errors. The configuration file located in $DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml contains the definition of this role.Note:
The Guided Business Process APIs enables retrieving detailed task information by providing the task ID, but do not retrieve the task information. Other APIs, such as the Workflow service APIs, are required for this purpose.For more information about Workflow services, see "Introduction to Human Workflow Services" in Developer's Guide for Oracle SOA Suite.
Table 29-1 Guided Business Process Query Service API
| Method | Description |
|---|---|
|
|
Returns a list of AGDisplayInfo objects with fields defined in The You can assign the String parameter
As milestones and tasks are not visible from the Activity Guide instance views, it is recommended not to include the |
|
|
Returns the The You can assign the String parameter
The String parameter
|
|
|
Returns the display information for a milestone in an Activity Guide instance. The You can assign the String parameter
The String parameter
|
The following table describes the JNDI names for the Guided Business Process Enterprise Java Beans.
| Service Name | JNDI Names for the Enterprise JavaBeans |
|---|---|
| Activity Guide MetaData Store | ejb/bpel/services/workflow/AGMetadataService |
| Activity Guide Query Service | ejb/bpel/services/workflow/AGQueryService |
APIs enable accessing the Guided Business Process query and Metadata Services from within a custom application.
The following example illustrates the use of Java APIs to access Guided Business Process run-time services:
Example 29-5 Accessing the Guided Business Process Run-Time Service Using EJB
package client;
import com.oracle.bpel.activityguide.metadata.definition.model.AGDefinition;
import java.util.ArrayList;
import java.util.List;
import oracle.bpel.services.workflow.IWorkflowConstants;
import oracle.bpel.services.workflow.task.model.Task;
import oracle.bpel.services.workflow.verification.IWorkflowContext;
import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
import oracle.bpel.services.workflow.client.IWorkflowServiceClientConstants;
import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.query.impl.TaskQueryService;
import oracle.bpel.services.workflow.client.WorkflowServiceClientContext;
import oracle.bpel.services.workflow.metadata.config.ResourceBundleInfo;
import oracle.bpel.services.workflow.activityguide.query.IAGQueryService;
import oracle.bpel.services.workflow.activityguide.query.impl.AGQueryService;
import oracle.bpel.services.workflow.activityguide.query.model.AGDisplayInfo;
import oracle.bpel.services.workflow.activityguide.query.model.MilestoneDisplayInfo;
import oracle.bpel.services.workflow.activityguide.metadata.IAGMetadataService;
import oracle.bpel.services.workflow.activityguide.metadata.impl.AGMetadataService;
import sun.security.util.Password;
public class AGServiceSampleCode {
private static String USERNAME = "jcooper";
private static String PASSWORD = "welcome1";
private static IWorkflowServiceClient wfSvcClient;
private static IWorkflowContext sJCooperCtx;
public static void main(String[] args)
{
try {
testSetUp();
// GetAGDefinition API requires an AG instance as input, which is not easily accessible in customer's env.
// As a result, the sample code for invoking this API is not provided.
//testGetAGDefinition();
testGetAGDefinitionById();
testGetAGResourceBundleInfo();
testQueryAGDisplayInfos();
testQueryAGDisplayInfoDetailsById();
testQueryAGMilestoneDisplayInfo();
} catch (Exception e) {
e.printStackTrace();
}
}
private static void testSetUp()
throws Exception
{
wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.REMOTE_CLIENT);
sJCooperCtx =
wfSvcClient.getTaskQueryService().authenticate(USERNAME, PASSWORD, null);
}
private static void testGetAGDefinitionById()
throws Exception
{
String agDefinitionId = "HelpDeskRequestSCAApp/HelpDeskRequestComposite!1.0*2007-10-22_13-32-50_536//HelpDeskRequestProcess//HelpDeskRequestProcess.ag"; // Need to supply a valid AG definition id here
AGDefinition agDefinition =
wfSvcClient.getAGMetadataService().getAGDefinitionById (sJCooperCtx, agDefinitionId);
if (agDefinition != null)
{
System.out.println("ag def obtained");
System.out.println("ag def name: " + agDefinition.getName());
System.out.println("ag def milestone display mode: " + agDefinition.getMilestoneDisplayMode());
}
}
private static void testGetAGResourceBundleInfo()
throws Exception
{
String agDefinitionId = "HelpDeskRequestSCAApp/HelpDeskRequestComposite!1.0*2007-10-22_13-32-50_536//HelpDeskRequestProcess//HelpDeskRequestProcess.ag"; // Need to supply a valid AG definition id here
ResourceBundleInfo resourceBundleInfo = wfSvcClient.getAGMetadataService().getResourceBundleInfo(sJCooperCtx, agDefinitionId, sJCooperCtx.getLocale());
System.out.println("bundle name: " + resourceBundleInfo.getName());
}
private static void testQueryAGDisplayInfos()
throws Exception
{
List agQueryColumns = new ArrayList();
agQueryColumns.add("MILESTONE_STATE");
agQueryColumns.add("DEFINITION_ID");
// Query for all AG instances belonging to user jcooper
List agDisplayInfoList =
wfSvcClient.getAGQueryService().queryAGDisplayInfos(sJCooperCtx,
agQueryColumns,
IAGQueryService.AGAssignmentFilter.MY,
null, //agPredicate,
null, //ordering,
0,
0);
System.out.println("ag display info list size:" + agDisplayInfoList.size());
if ( agDisplayInfoList.size() > 0 )
{
AGDisplayInfo agDisplayInfo = (AGDisplayInfo) agDisplayInfoList.get(0);
System.out.println("AG title:" + agDisplayInfo.getTitle());
System.out.println("milestone display info list size:" + agDisplayInfo.getMilestoneDisplayInfo().size());
for (int i=0; i< agDisplayInfo.getMilestoneDisplayInfo().size(); i++)
{
System.out.println("i = " + i + " milestone display info:" + ((MilestoneDisplayInfo) agDisplayInfo.getMilestoneDisplayInfo().get(i)).getMilestoneInstance().getName());
}
}
}
private static void testQueryAGDisplayInfoDetailsById()
throws Exception
{
long cikey = 1; // Need to supply a valid AG cikey here
List taskQueryColumns = new ArrayList();
taskQueryColumns.add("TASKID");
taskQueryColumns.add("TITLE");
taskQueryColumns.add("OUTCOME");
AGDisplayInfo agDisplayInfo =
wfSvcClient.getAGQueryService().getAGDisplayInfoDetailsById (sJCooperCtx, cikey, taskQueryColumns);
System.out.println("AG display info status:" + agDisplayInfo.getAGInstanceInfo().getStatus());
System.out.println("AG display info bpel status:" + agDisplayInfo.getAGInstanceInfo().getBpelStatus());
}
private static void testQueryAGMilestoneDisplayInfo()
throws Exception
{
long cikey = 1; // Need to supply a valid AG cikey here
String milestoneName = "ApprovePricing"; // Need to supply a valid AG milestone name here
List taskQueryColumns = new ArrayList();
taskQueryColumns.add("TASKID");
taskQueryColumns.add("TITLE");
taskQueryColumns.add("OUTCOME");
MilestoneDisplayInfo milestoneDisplayInfo = null;
milestoneDisplayInfo =
wfSvcClient.getAGQueryService().getMilestoneDisplayInfo (sJCooperCtx, cikey, milestoneName, taskQueryColumns);
System.out.println("milestone display info name:" + milestoneDisplayInfo.getMilestoneInstance().getName());
System.out.println("milestone display info title:" + milestoneDisplayInfo.getTitle());
System.out.println("milestone display info task list size:" + milestoneDisplayInfo.getTask().size());
}
}
For more information regarding the EJB and Web Service APIS, see the Javadoc.
Guided Business Processes use a log file to store information about the different operations they perform. This file contains log messages that track the application behavior and possible errors that might occur while running the application.
You can use the information in this log file to find out the cause of an unexpected behavior in your application.
The importance of the log messages varies according to their level. The level of the messages used for debugging purposes is different to the level of the messages that contain warnings or errors.
You can configure Guided Business Process Logging to log only certain level of messages according to your needs.
You can configure Guided Business Processes to generate a log file on the client side.
To enable client side logging:
Locate the logging.xml file in the directory <DOMAIN_HOME>/config/fmwconfig/servers/Server Name
Open the logging.xml file for editing.
Add the following entry in the <loggers> element:
<logger name="oracle.bpel.activityguide.ui" level="NOTIFICATION:1" useParentHandlers='false'>
<handler name="odl-handler"/>
</logger>
Save the changes.
Re-start Web Logic Server.
You can configure Guided Business Processes to generate a log on the server side.
To enable server-side logging:
Locate the logging.xml file in the directory <DOMAIN_HOME>/config/fmwconfig/servers/Server Name
Open the logging.xml file for editing.
Add the following entry to the <loggers> element:
<logger name="oracle.bpm.services.activityguide.query" level="NOTIFICATION:1" useParentHandlers='true'>
Save the changes.
Re-start Web Logic Server.
Log messages contain a level that identifies the severity of the problem.
Table 28-3 shows the available log levels. The Severity column describes the common term used to identify a certain severity. The Log Level Value common specifies the value that you must use in the logging.xml file.
| Severity | Log Level Value | Description |
|---|---|---|
|
Fatal |
INCIDENT_ERROR:1 |
Indicates a serious problem caused by unknown reasons. Users cannot fix the problem by themselves, they must contact Oracle Support. |
|
Severe |
ERROR:1 |
Indicates a serious problem that requires immediate attention from the System Administrator |
|
Warning |
WARNING:1 |
Indicates a potential problem. The System Administrator should review these log messages. |
|
Information |
NOTIFICATION:1 |
Indicates a major lifecycle event such as the activation or deactivation of a primary sub-component or feature. |
|
Configuration |
NOTIFICATION:16 |
Specifies a normal event occurred at a lower level. |
|
Fine |
TRACE:1 |
Specifies trace or debug information for events that are meaningful to end users of the product, such as public API entry/exit points. |
|
Finer |
TRACE:16 |
Specifies a detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem. |
You can configure Guided Business Process Logging to specify the level of detail of the information stored in the Guided Business Process logs.
To set the log level must change the value of the attribute level in the logger element in the logging.xml file.
When you set the log level to a certain severity, all the messages that correspond to higher severities are also stored. For example, if you set the log level to severe, then the log messages of severity fatal are also logged.
Log messages are stored in the following file: <DOMAIN HOME>/servers/<Server Name>/logs/Server Name-diagnostic.log
You can view the file that contains the log messages using a text editor.
A log message contains information that helps you identify the problems in your Guided Business Process application.
Table 28-3 describes the items that compose a log message.
| Log Message Item | Description |
|---|---|
|
Date and Time |
Specifies the date and time when this log message was generated. |
|
Message Type |
Specifies the severity of the message. |
|
Execution Context ID (ECID) |
A global unique identifier and a sequence number that correspond to the thread where the originating component is running. You can use it to correlate messages from multiple components that may be involved in the same thread. |
|
Application Name |
Specifies the name of the application that generated the log message. |
|
Class Package Name |
Specifies the package of the class that generated the log message. |
|
Message ID |
Specifies a short identifier that uniquely identifies the message. |
|
Message Text |
Describes the event. This message is localized, thus it displays in the language that corresponds to the locale of your system. |
When you read a log file you must look for the message text, this text describes what happened. The message type helps you identify how serious the problem is. For more information about the different message types, see Table 29-2.
You can use the date and time of the log message to identify the action that caused the problem.
Note:
before contacting Oracle Support make sure you can provide them the message ID and the execution context ID.Example 29-6 Log Message Example
DefaultServer-diagnostic.log:[2009-07-10T17:39:35.220-07:00] [DefaultServer] [NOTIFICATION] [AGU-12605] [oracle.bpel.activityguide.ui.beans] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: jstein] [ecid: 0000I9bG2R3DScQ6ube9UH1ALxd1000007,0] [APP: AGNonUIshellApp#V2.0] [arg: jstein] Setting user, jstein as the loginUserId in server interfacing bean.[[
Example 28-12 shows a notification log message that contains information about a loginUserId change. In this example the different log message items are:
Date and Time: 2009-07-10T17:39:35.220-07:00
Message Type: NOTIFICATION
Execution Context ID: ecid: 0000I9bG2R3DScQ6ube9UH1ALxd1000007,0
Application Name: APP: AGNonUIshellApp#V2.0
Class Package Name: oracle.bpel.activityguide.ui.beans
Message ID: AGU-12605
Message Text: Setting user, jstein as the loginUserId in server interfacing bean.