5 Oracle BPEL Process Manager

5.1.1 Password Displays in Clear Text During Deinstallation

When deinstalling patch 10.1.3.4 on Windows and Linux, the following occurs:

• The password displays in clear text.

• You are prompted for the password three times.

• The password you enter is not validated and deinstallation continues.

5.1.2 Passwords Appear in Clear Text in /tmp Directory After Running IRCA.SH

After you run IRCA.SH to input the Oracle BPEL Process Manager schema into the database, the passwords for orabpel, oraesb, and orawsm display in clear text in the log files in the /tmp directory on Linux or UNIX or the temporary directory you have defined on Windows. Ensure that you delete the files in this directory.

5.1.3 BPEL Process Instances Do Not Display in Oracle BPEL Control when Using Oracle Database Lite

If you install Oracle BPEL Process Manager with the Basic Install option, Oracle Database Lite (Olite) is installed. If you then apply the 10.1.3.4 patch to this installation, BPEL process instances under the Instances tab in Oracle BPEL Control do not display.

As a workaround, use the Advanced Install option, which enables you to install a database other than Olite.

5.1.4 Task Details Application Does Not Start in a Standalone, Middle Tier-Based Installation

After upgrading a standalone Oracle BPEL Server installed on the middle tier, the task details application does not start.

As a workaround, log in to Oracle Enterprise Manager and manually start the task details application.

5.1.5 Applications Sometimes Do Not Start After Applying Patch 10.1.3.4

After applying patch 10.1.3.4, applications such as Oracle BPEL Worklist Application and others sometimes do not start. If this occurs, you must log in to Oracle Enterprise Manager and restart those applications.

1. Log into Oracle Enterprise Manager 10g Application Server Control Console:

   http://hostname:port/em
   

2. Click Applications.

3. Select Applications in the View list.

   View the list of applications to identify those that are currently not running.

4. Select applications requiring a restart and click Restart.

5.2.1 Use an XA Data Source for the BPELPM_CONNECTION_POOL Setting

When using release 10.1.3.4 in either single instance database environments or with an Oracle Real Application Clusters database as a dehydration store, set BPELPM_CONNECTION_POOL to use an XA data source in the SOA_Oracle_home\j2ee\oc4j_soa\config\data-sources.xml file.

<connection-pool name="BPELPM_CONNECTION_POOL"> 
<connection-factory factory-class="oracle.jdbc.xa.client.OracleXADataSource"
. . .
. . .
</connection-pool>

5.2.2 Associating Oracle Internet Directory with Oracle BPEL Process Manager

The hw_services.ear file is now divided into hw_services.ear and a new enterprise archive (EAR) file named deploy_service.ear that:

• Is installed in oc4j_soa with orabpel as the parent

• Contains the deployment module

All BPEL process deployments now go through deploy_service.ear instead of hw_services.ear. Deployment fails if the security provider is configured to use Oracle Internet Directory for both orabpel and hw_services in Oracle Enterprise Manager. This is because the new deploy_service module is configured to use the file-based security provider by default.

To prevent deployment failure, change the security provider for deploy_service in Oracle Enterprise Manager from file-based to Oracle Internet Directory by performing the following steps:

1. Log into Oracle Enterprise Manager 10g Application Server Control Console:

   http://hostname:port/em
   

2. Go to oc4j_soa > Administration > Security > Security Providers.

3. Expand Security Providers.

   A new application named deploy_service appears with orabpel as the parent. The security provider is file-based by default.

4. Go to orabpel > deploy_service > Administration > Security > Security Provider.

5. Click Change Security Provider.

6. Select Oracle Identity Management Security Provider.

7. Click OK.

8. Restart Oracle Application Server:

   opmnctl stopall 
   opmnctl startall
   

5.2.3 Do Not Enable Single Sign-On for deploy_service

When enabling single-sign on (SSO) for orabpel and hw_services in Oracle Enterprise Manager 10g Application Server Control Console, ensure that you do not also enable SSO for the new deploy_service.

5.2.4 Correlation Set Property Alias Gets Overwritten from the Designer

If you create correlation set property aliases in the designer window of Oracle JDeveloper, and create multiple entries for the same property alias, the second entry overwrites the first one in the BPEL artifact files. This leads to problems during BPEL process compilation.

As a workaround, create the second property alias definition (referring to the same property) in the Structure window in the lower left corner of Oracle JDeveloper.

5.2.5 Configuring Oracle BPEL Process Manager to Invoke a Service in UDDI

Follow these steps to configure a BPEL process to invoke a UDDI service:

1. Select Configuration > Domain in Oracle BPEL Control.

2. Specify the UDDI inquiry URL in the uddiLocaton property.

3. Restart Oracle BPEL Server.

4. Create a UDDI connection with the Create UDDI Registry Connection Wizard in Oracle JDeveloper.

5. Drag and drop a partner link activity into the designer.

6. Select the Service Explorer icon in the Create Partner Link window.

7. Select a UDDI service under the UDDI Registry folder.

8. Click OK.

9. Add registryServiceKey to bpel.xml:

   <partnerLinkBinding name="HelloBPELProcess"> 
       <property name="wsdlLocation">wsdllocation</property> 
       <property name="registryServiceKey">uddi:6644</property> 
   </partnerLinkBinding> 
   

5.2.6 Minimum List of JAR files Required when Using the BPEL Java Client API

The minimum list of JAR files required when using the BPEL Java Client API is based upon the environment in which you are using Oracle BPEL Process Manager. Table 5-1 lists the required files.

5.3.1 Oracle BPEL Worklist Application Undeploy Option Not Supported in Oracle Enterprise Manager

The undeploy feature in Oracle Enterprise Manager for undeploying an Oracle BPEL Worklist Application is not supported. The undeployment of the worklist application does not undeploy the BPEL application, but it does undeploy the task application. This prevents you from seeing task details in the worklist application. There is no workaround for this issue.

5.3.2 Increasing the nonFatalConnectionMaxRetry Property Value to 5

When using an Oracle Real Application Clusters database as a dehydration store, Oracle recommends that you increase the nonFatalConnectionMaxRetry property value to 5 from the default value of 2 in the SOA_Oracle_Home\bpel\system\config\collaxa-config.xml file. This setting ensures that Oracle BPEL Process Manager performs enough connection retries in the case of Oracle Real Application Clusters instance failover.

5.3.3 BPEL Process Deployment Fails (Vista and Windows 2008)

If you use Oracle JDeveloper or obant to deploy BPEL processes on Microsoft Vista and Windows 2008 systems, you must change the following line in the SOA_Oracle_Home\bpel\utilities\ant-orabpel.properties file from:

hostname  = hostname.us.oracle.com 

to:

hostname  = 127.0.0.1 

Otherwise, process deployment fails.

5.4.1 Parser Error When Opening the XSLT Mapper in Design Time

The XSLT Mapper may occasionally not open in design view due to an issue with the xmlparserv2.jar file. The error message indicates that the source or target schema cannot be opened:

Failed to open the source schema: Invalid value 'enumeration' specified for facet '{1}'.

As a workaround, extract the XMLDocument.class file from the xmlparserv2.jar file with the following commands and create an XMLDocument.jar file in the patches directory with the XMLDocument.class file in it:

1. Ensure that your jdk\bin directory is in your path or provide the full path to jar.exe.

2. Enter the following commands:

   cd jdev_home/lib
   jar xvf xmlparserv2.jar oracle/xml/parser/v2/XMLDocument.class
   jar cvf ../jdev/lib/patches/XMLDocument.jar oracle/xml/parser/v2/XMLDocument.class
   

5.5.1 Using SSL with Oracle Internet Directory and the Oracle BPEL Worklist Application

If you use Oracle Internet Directory as the identity provider for the Oracle BPEL Worklist Application and want to use the Secure socket layer (SSL) connection mode after upgrading to 10.1.3.4, you must add the following elements under the connection element in the SOA_Oracle_Home\bpel\system\services\config\is_config.xml file. Do not modify this file if you are using a non-SSL connection to Oracle Internet Directory.

<property name="SSLSocketFactoryImplClass"
@ value="oracle.tip.pc.services.identity.common.SSLSocketFactoryImpl"/>
      <property name="securityProtocol" value="ssl"/>
      <pool initsize="2" maxsize="25" prefsize="10" timeout="60"/>

5.5.2 Configuration Requirements for Active Directory or Other LDAP Servers Not Using the uid Attribute in the Schema

If you use human workflow with Active Directory or another LDAP server that does not use the uid schema attribute and upgrade to 10.1.3.4, you must add the nicknameAttribute property and sAMAccountName attribute to the SOA_Oracle_Home\bpel\system\services\config\is_config.xml file. This property and attribute are used for user login authentication.

Not adding these components causes authentication to fail. This is because Active Directory, unlike other LDAP servers such as Oracle Internet Directory, iPlanet, and openLDAP, does not use the uid attribute for user login authentication.

The nicknameAttribute property defines the name of the LDAP attribute used for identity service authentication (default value is uid). The value of that attribute is populated to the name attribute and uniquely identifies users in the identity service. The nameAttribute property stands for the name attribute that is used in the Users DN. For example, if the Users DN is the following:

cn=jcooper, cn=Users,dc=us,dc=oracle,dc=com

You define the nameAttribute as follows:

<property name="nameAttribute" value="cn"/>

The nicknameAttribute property is relevant to all LDAP servers in which the default uid value is used, unless it is overwritten in is_config.xml. Most LDAP servers support the uid attribute (refer to the inetOrgPerson object class for more details).

If a provider such as Active Directory does not support the uid attribute in the LDAP schema or you want to use a different attribute for authentication, you can overwrite the attribute name by using the nicknameAttribute property as follows:

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
    <configuration realmName="AD" >
       <provider providerType="LDAP" name="Active Directory" service="Identity">
                    <connection url="ldap://host:port" 
                       binddn="cn=administrator,cn=Users,dc=us,dc=oracle,dc=com" 
                       password="welcome1" encrypted="true">
                       <pool initsize="2" maxsize="25" prefsize="10"
                          timeout="300000"/>
                    </connection>
        <userControls>
           <property name="nameAttribute" value="cn"/>
           <property name="nicknameAttribute" value="sAMAccountName"/>
           <property name="objectClass" value="user"/> 
           <search searchbase="cn=Users,dc=us,dc=oracle,dc=com"
              scope="subtree" maxSizeLimit="1000" maxTimeLimit="120000"/>
        </userControls>
        <roleControls>
             <property name="nameAttribute" value="cn"/>
             <property name="objectClass" value="group"/>
             <property name="membershipSearchScope" value="onelevel"/>
             <property name="memberAttribute" value="member"/>
             <search searchbase="cn=Users,dc=us,dc=oracle,dc=com"
                scope="subtree" maxSizeLimit="1000" maxTimeLimit="120000"/>
        </roleControls>
       </provider>
      </configuration>
 </configurations>
</ISConfiguration>

5.5.3 Standard Views in the Oracle BPEL Worklist Application Do Not Work when Human Workflow is Configured with Active Directory

If you use human workflow with Active Directory, standard views in the Oracle BPEL Worklist Application do not work.

1. Go to My Tasks > My Work Queues > Standard Views in the Oracle BPEL Worklist Application.

2. Click the standard views High Priority Tasks, Tasks Due Soon, and New Tasks.

   An exception error similar to the following displays in the user interface:

   Internal Error in Verification Service for user createContext. {1}.
   If you need more information, please check with your administrator with the
   following exception-identifier: "*2008/07/15_02:04:03:826_jstein*" 
   

5.5.4 Cannot Approve Workflow Instances After Upgrading to 10.1.3.4

Restart Oracle BPEL Server if you receive the following error messages when attempting to approve a task in the Oracle BPEL Worklist Application:

• The following message displays in the Oracle BPEL Worklist Application:

  your request was not successful
  

• The following error message displays in the Oracle BPEL Server log file:

  <2008-06-05 19:05:30,246> <ERROR> <oracle.bpel.services.workflow> <::> The 
  Scheduler has been shutdown. 
  org.quartz.SchedulerException: The Scheduler has been shutdown. 
          at 
  org.quartz.core.QuartzScheduler.validateState(QuartzScheduler.java:502) 
          at 
  org.quartz.core.QuartzScheduler.unscheduleJob(QuartzScheduler.java:678) 
          at org.quartz.impl.StdScheduler.unscheduleJob(StdScheduler.java:268)
         at 
  oracle.bpel.services.workflow.task.impl.WorkflowTimerAgent.unscheduleExpiratio 
  n(WorkflowTimerAgent.java:294) 
          at 
  oracle.bpel.services.workflow.task.impl.WorkflowTimerAgent.unscheduleExpiratio 
  n(WorkflowTimerAgent.java:282) 
          at 
  oracle.bpel.services.workflow.task.impl.WorkflowTimerAgent.rescheduleExpiratio 
  n(WorkflowTimerAgent.java:321) 
          at 
  oracle.bpel.services.workflow.task.impl.WorkflowTimerAgent.scheduleTimers(Work 
  flowTimerAgent.java:115) 
          at 
  oracle.bpel.services.workflow.task.impl.TaskService.performPostActionOperation 
  (TaskService.java:3062) 
          at 
  oracle.bpel.services.workflow.task.impl.TaskService.performPostActionOperation 
  (TaskService.java:2918) 
  

5.5.5 Use the Default E-Mail Client for Actionable E-Mails

If actionable e-mail responses are not being sent (for example, you cannot approve or reject a task using links provided in an actionable e-mail), ensure that the e-mail client being used is the default mail client for the system. For example, to set the default e-mail client on Microsoft Windows XP, perform the following steps:

1. Go to the Start menu.

2. Select Control Panel > Network and Internet Connections > Internet Options > Programs.

3. Select the e-mail client as the default e-mail client.

5.5.6 Workflow Updates for a Case Agnostic User Directory

The behavior of workflow services when case agnostic (case insensitive) is as follows:

• User names can be in different cases during login to the Oracle BPEL Worklist Application in the task metadata (the .task file).

• All user names in the database are in lower case.

• Case is agnostic only for user names. Group names must be identical to what is seeded in the user directory.

• Values for the following task attributes are always in lower case: assigneeUsers, acquiredBy, updatedBy (also for comments and attachments), creator, ownerUser, and fromUser.

• Creators that are not in the user directory are stored in lower case. The default behavior is case sensitive. This should ideally be used against a case-sensitive user directory.

Workflow configuration in both case-sensitive or case-agnostic cases must be consistent with the underlying user directory. When workflow services are configured to be case sensitive (default configuration), the workflow user names must exactly match what is seeded in the user directory.

If you want workflow services to be case agnostic for user names in a workflow and you have workflow data in the database, upgrade the data to make the user data consistent with 10.1.3.4 patch capabilities. Upgrade the data with the SOA_Oracle_home\bpel\system\database\scripts\upgrade_WFUserIgnoreCase.sql script. Task assignment rules stored in rule dictionaries are not upgraded and must be recreated.

If you want workflow services to operate in a case-agnostic manner, the is_config.xml and wf_client_config.xml files must be updated. In is_config.xml, add <property name="caseSensitive" value="false"/> inside the ISConfiguration element:

<?xml version = '1.0' encoding = 'UTF-8'?> 
         <ISConfiguration 
xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig"> 
            <configurations> 
              ........... 
            </configurations> 
            <property name="caseSensitive" value="false"/> 
         </ISConfiguration> 

If workflow service client code is used by custom applications, the wf_client_config.xml file must be changed as follows:

<servicesClientConfigurations 
xmlns="http://xmlns.oracle.com/bpel/services/client">
            ..... 
            <caseSensitive>false</caseSensitive> 
         </servicesClientConfigurations>

If the is_config.xml file is updated, you must restart Oracle BPEL Server.

These settings result in the following behavior on different identity providers:

• Case-sensitive identity provider

  Setting caseSensitive to false has no impact. For example, assume jcooper is the seeded user in the identity provider. Logging in as Jcooper fails with this setting because the identity service provider is case sensitive.

• Case-agnostic identity provider

  Until caseSensitive is set to true, a task assigned to Jcooper, which is the same as jcooper, does not appear in the jcooper inbox. However, after setting caseSensitive to false, the task assigned to Jcooper appears in the jcooper inbox.

5.5.7 Identity Service Configuration Properties are Case Sensitive

All identity service configuration properties are case sensitive and must follow the same CamelCase notation. This issue is relevant to all 10.1.3.x releases. If you do not use the correct case, the specified property value is ignored and a default property value is used by the BPEL identity service. The following properties must use the case sensitivity shown below:

• usersPropertiesFile

• nicknameAttribute

• nameAttribute

• objectClass

• memberAttribute

• membershipSearchScope

• roleOwnerAttribute

• caseSensitive

5.5.8 Use Different E-Mails for Human Workflow and Notification End Users

For actionable e-mails, ensure that you use different e-mail addresses for the human workflow system and for the notification of end users. If both e-mail addresses are the same, this can lead to unpredictable behavior. This is because an actionable notification sent to an end user (for example, jstein) can be accessed by the human workflow system (and deleted from the e-mail server) before jstein gets a chance to view it.

Create separate addresses as follows:

• If using JAZN file-based security, edit the user-properties.xml file and provide one address (for example, jstein@example.com) as the address for jstein (for this example, the end user).

• Edit the ns_emails.xml file and provide a different e-mail address for the human workflow (for example, hwfaccount@example.com).

In addition, in the SOA_Oracle_Home\bpel\system\services\config\wf_config.xml file, the value for the actionableEmailAccountName element must map to the Name element in the SOA_Oracle_Home\bpel\system\services\config\ns_emails.xml file.

For example, if ns_emails.xml uses Default as the e-mail address:

<EmailAccount> 
 <Name>Default</Name> 
. . .
. . .
. . .
</EmailAccount> 

The actionableEmailAccountName value must also be set to Default in wf_config.xml:

<actionableEmailAccountName>Default</actionableEmailAccountName>

5.5.9 Case Sensitivity for E-Mail Protocols in the ns_emails.xml Files

When enabling notifications for human workflow, do not specify IMAP or POP3 in upper case in the SOA_Oracle_Home\bpel\system\services\config\ns_emails.xml file. Only lower case is supported. Using upper case results in the following error:

Email protocol not supported

5.5.10 Old Payload Mapping Remains After Re-editing the Task

If you attempt to remap a payload in the Task Parameters dialog of a human task, the old payload still remains. For example, performing the following steps causes the old payload mappings to remain.

1. Create a BPEL project using default project settings.

2. Add a human task after the receive activity. This opens the Add a Human Task dialog.

3. Create a new task definition by clicking the second icon to the right of the Task Definition field. This opens the Human Task Editor.

4. Create a parameter string named payload1 in the Add Task Parameter dialog of the Human Task Editor.

5. Save your changes and close the Human Task Editor.

6. Double-click the human task activity in the BPEL process to open the Human Task dialog.

7. Click the Browse icon in the Task Parameters table.

8. Map payload1 to inputVariable/client:input in the Task Parameters dialog, and click OK.

9. Return to the Human Task Editor for this human task.

10. Change the parameter name from payload1 to payload2 in the Edit Task Parameter dialog.

11. Save your changes and close the Human Task Editor.

12. Open the Human Task dialog again.

13. Remap payload2 to inputVariable/client:input in the Task Parameters dialog of the Human Task dialog, and click OK.

14. Switch to the source code mode and search for payload1. Note that payload1 still remains in the code.

    This causes a run-time error similar to the following:

    Error in <assign> expression: <to> value is empty at line "123". The XPath
    expression : "" returns zero node, when applied to document shown below:less
    

As a workaround, manually remove the copy operation of the old mapping (for payload1) from the source:

<copy>
   <from variable="inputVariable" part="payload"
       query="/client:BPELProcess1ProcessRequest/client:input"/>
    <to variable="initiateTaskInput" part="payload"
       query="/taskservice:initiateTask/task:task/task:payload/task:Payload1"/>
</copy>

5.5.11 Removing or Changing the Passwords of Default User Accounts

The default user accounts used for human workflow task assignments (for example, wfaulk or jstein) are included in the j2ee/home/config/system-jazn-data.xml file. For security reasons, you should consider changing the default passwords for these accounts or removing them completely if they are not needed.

1. Log into Oracle Enterprise Manager 10g Application Server Control Console:

   http://hostname:port/em
   

2. Click oc4j_soa (or a different OC4J instance that you are using).

3. Click Administration.

4. Click the Security Providers link under Security.

5. Click Instance Level Security.

6. Click Realms.

7. Click the link under Users in the jazn.com realm.

8. Follow the instructions below based on the action you want to perform.

   If You Want to...	Then...
   Delete a user	Click Delete.
   Change a user password	Click the appropriate user in the User Name column. Change the password.

   
   

5.6.1 SSL Is Not Supported and the UseSSL element Is Not Used

SSL is not supported and the UseSSL element in ns_emails.xml is not used.

5.6.2 Pager and Fax Channels Are Not Supported

The pager and fax channels are desupported and deprecated in Oracle's hosted wireless service.

5.6.3 Changes Needed for Demonstrating the Notification Service

For demonstrating the notification service, one e-mail account is required (for this example, hwfaccount is used) in the e-mail server used by the notification service. Other e-mail accounts (for example, jcooper, jstein, and wfaulk) are to be used by end users.

5.6.4 Debugging the Notification Service

To debug the notification service, first check the Oracle Process Manager and Notification Server (OPMN) logs. The logs may contain exception, error, or warning messages that provide details about incorrect behavior. Table 5-2 describes additional methods for debugging notification service problems.

<AuthenticationRequired>true
</AuthenticationRequired>
<UserName>SMTP_user_name</UserName>
<Password ns0:encrypted="false"xmlns:ns0=
"http://xmlns.oracle.com/ias/pcbpel/
NotificationService">'SMTP_password'</Password>

5.7.1 Errors Display When Initiating Test Instances for a Deployed BPEL Process with JDK 6

The following JSP errors are displayed when trying to initiate a test instance for a deployed BPEL process using JDK 6:

500 Internal Server Error 
OracleJSP: An error occurred. Consult your application/system administrator
for support. Programmers should consider  setting the init-param debug_mode to
"true" to see the complete exception message

To resolve this issue, perform the following steps:

1. Visit the Oracle MetaLink site:

   http://metalink.oracle.com
   

2. Download and install patch 7309482 by following the steps in the accompanying readme file.

5.7.2 Oracle BPEL Control Error Message Displays when 10.1.3.1 Completed Instances are Viewed in 10.1.3.4

If you perform the following procedures:

1. Install Oracle SOA Suite 10.1.3.1 through the Advanced installation option.

2. Deploy a sample such as vacation request and create several 10.1.3.1 instances.

3. Complete one instance from the Oracle BPEL Worklist Application.

4. Upgrade with the 10.1.3.4 patch.

5. Restart Oracle BPEL Server.

6. Complete another instance from the Oracle BPEL Worklist Application.

The instance completed in 10.1.3.4 displays the following error message in Oracle BPEL Control:

this.wi.state is null'

There is no loss of functionality and this message can be ignored. If you create new instances in 10.1.3.4, this message does not appear.

5.7.3 Fault Policy Changes Do Not Require a Restart of Oracle BPEL Server

Fault policies that have been changed can be reloaded from Oracle BPEL Control without having to restart Oracle BPEL Server.

1. Invoke the following JSP page:

   http://host:port/BPELConsole/domain_name/doReloadFaultPolicy.jsp 
   

2. Log into Oracle BPEL Control when prompted.

   The following message appears:

   Fault Policy and Fault Bindings file is reloaded
   
   All Fault Policy and Fault Binding cached for the BPEL domain your_domain_name
   have been reloaded. 
   

5.7.4 Using Oracle BPEL Process Manager When Oracle BPEL Server is SSL-Enabled

If Oracle BPEL Server is SSL-enabled, do the following to use Oracle BPEL Process Manager.

1. Open the Oracle BPEL Admin Console (http://soaSuiteServerHostName:port/BPELAdmin).

2. For the SoapServerUrl and SoapCallbackUrl properties, do the following:

   • Change http to https, with the hostname and full domain name in the URL.

   • Ensure that the correct SSL port is specified.

3. Test and verify that certificate-based HTTPS is now available. Substitute the host name and httpsPort with the target Oracle SOA Suite installation information: https://hostname:httpsPort/BPELConsole

5.7.5 Back Up Domain Data Before Deleting Domains in Oracle BPEL Admin Console

When you attempt to delete a domain in Oracle BPEL Admin Console, the following message appears:

To preserve deployed processes and data logs associated with the BPEL Domain,
check the keep directory box (the old domain directory will be moved to
home/domains/.deleted where home is the BPEL server installation directory).

There is no keep directory check box to select on this page if you want to preserve the data in this domain.

As a workaround, manually back up the domain data before deleting the domain. For example, perform the following steps on UNIX or Linux operating systems:

1. Change directories to the following location:

   cd $ORACLE_HOME/bpel/domains
   

2. Copy the underlying directory that represents the domain to a backup location.

5.7.6 Cannot Use Mozilla Firefox with Change All List for Setting Logging Levels in Oracle BPEL Admin Console

If you use Mozilla Firefox to set a logging level in the Change All list of the Logging tab of Oracle BPEL Admin Console, the logging level is not changed for all logging components.

As a workaround, use Microsoft Internet Explorer.

5.7.7 Cannot View Sensor Data in Oracle BPEL Control Activity Sensor Reports

You cannot view sensor data in activity sensor reports in Oracle BPEL Control. For example, if you perform the following steps:

1. Create database sensors on activities in a BPEL process in Oracle JDeveloper.

2. Deploy the BPEL process.

3. Create an instance of the BPEL process in Oracle BPEL Control.

4. Go to Processes > Deployed_BPEL_Process > Reports, and select Activity Sensor from the Report Type list.

5. Specify a query that includes the time interval in which the instance was completed, and click Go.

   The following message appears, even though activity sensor data exists:

   No Data Found
   

As a workaround, you can view sensor data for the activities of the BPEL process by selecting Instances > BPEL_Process_Name > Sensors in Oracle BPEL Control.

5.7.8 Access to Oracle BPEL Control Can Fail the First Time With Single Sign-On

Access to Oracle BPEL Control can fail the first time under the following conditions:

1. Configure single sign-on (SSO) for Oracle BPEL Control.

2. Log in first through the generic Java single sign-on (JSSO) page. For example:

   http://myhost.us.mycompany.com:47804/jsso/
   

3. Click the BPEL Control link in the Manage Your SOA Suite section of the JSSO page.

   Access is not provided to Oracle BPEL Control.

As a workaround, click the BPEL Control link a second time. This causes Oracle BPEL Control to appear. Or, bypass the JSSO page and log in directly to Oracle BPEL Control.

5.7.9 Oracle BPEL Control Shows Output Data Incorrectly for the toCDATA Function

When you use the toCDATA function in an assign activity of a BPEL process, Oracle BPEL Control shows the output data in the audit trail incorrectly.

[2008/05/01 16:20:33]  Updated variable "output"less
322 GE 12.3 750 true Hello 322 <![CDATA[322 ]]>

This problem only occurs with Oracle BPEL Control; the toCDATA function works correctly. Note that the toCDATA function displays correctly in the raw XML data.

5.8.1 Configuring HTTP GET and POST for Multibyte Data

For HTTP GET and POST to work with multibyte data, you must perform the following steps:

1. Add the following lines to SOA_Oracle_Home\opmn\conf\opmn.xml as the oc4j_soa startup option:

   <process-type id="oc4j_soa" module-id="OC4J" status="enabled">
       <module-data>
           <category id="start-parameters">
                        <data id="java-options" value="-server -XX:MaxPermSize=128M
    -ms512M -mx1024M -XX:AppendRatio=3 -Djava.security.policy=$ORACLE_HOME/j2ee/oc4j_
   soa/config/java2.policy -Djava.awt.headless=true -Dhttp.webdir.enable=false
    -Doraesb.home=/home/zhua/product/10.1.3.1/OracleAS_1/integration/esb
    -Dhttp.proxySet=false -Doc4j.userThreads=true -Doracle.mdb.fastUndeploy=60
    -Dorabpel.home=/home/zhua/product/10.1.3.1/OracleAS_1/bpel
    -Xbootclasspath^/p:/home/zhua/product/10.1.3.1/OracleAS_
   1/bpel/lib/orabpel-boot.jar  -Dhttp.proxySet=false -Dfile.encoding=UTF8"/>
           </category>
           . . .
           . . .
       <module-data>
       . . .
       . . .
   </process-type>
   

2. Restart oc4j_soa through one of the following methods:

   • From Oracle Enterprise Manager, log in as a user with the administrator role, select oc4j_soa on the Cluster Topology page, and click Restart.

   • With the opmnctl utility, enter the following command:

     opmnctl restartproc process-type=oc4j_soa
     

5.9.1 Passwords in Samples Directory Documentation

Some samples and tutorials included in the SOA_Oracle_Home\bpel\samples directory mention passwords.

If you are concerned about hosting samples, then remove the entire samples directory. This is especially true of any production servers on which you have installed SOA. This applies to all 10.1.3.x releases.

5.9.2 Resilient Flow Sample Documentation is Incomplete

The section in the PDF documentation in SOA_Oracle_Home\bpel\samples\demos\ResilientDemo\ResilientFlow that describes how to run the Resilient Flow sample is incomplete. You must also perform the following steps:

• Download and copy the Apache AXIS service to the $TOMCAT_HOME/webapps folder.

• Explicitly run the compilation target under ResilientDemo/AxisServices. Only after performing this step is the classes folder created.

5.9.3 Reassign To Action Description in Oracle BPEL Process Manager Developer's Guide

Section "Group Rules" of Chapter 16, "Worklist Application" of the Oracle BPEL Process Manager Developer's Guide includes the following description for the Reassign to action:

• Reassign to - As with user rules, you can reassign tasks to subordinates or groups you directly manage. If you have been granted the BPMWorkflowReassign role, then you can reassign tasks to any user or group (outside your management hierarchy).

This implies that reassignment permissions are determined by the user creating the rule, rather than the group for which the rule is being created. This description should read as follows:

• Reassign to - As with user rules, a group can reassign tasks to subordinates or groups the group directly manages. If the group has been granted the BPMWorkflowReassign role, then the group can reassign tasks to any user or group (outside its management hierarchy).

5.9.4 Incorrect Syntax for Configuring the TCP Listener for Synchronous Services

Section "Setting up a TCP Listener for Synchronous Services" of Chapter 5, "Invoking an Asynchronous Web Service" of the Oracle BPEL Process Manager Developer's Guide incorrectly mentions to use orabpel.apache.axis.utils.tcpmon when configuring the TCP tunnel included with Apache Axis. Instead, use org.collaxa.thirdparty.apache.axis.utils.tcpmon.

5.9.5 BPEL Test Suite OnMessage Event Does Not Support Synchronous Operations

When reading section "Asynchronous Event Emulation" of Chapter 20, "Testing BPEL Processes" of the Oracle BPEL Process Manager Developer's Guide, note that the onMessage event does not support synchronous (that is, two way) operations.

5.9.6 Changing the HTTP Port for Oracle BPEL Process Manager

Changing the HTTP port on Oracle Application Server is documented in Chapter 4, "Managing Ports" of the Oracle Application Server Administrator's Guide. If you are using Oracle BPEL Process Manager, you must make the following additional changes to the HTTP port:

1. Update the soapServerUrl and soapCallbackUrl properties in Oracle BPEL Admin Console or in the SOA_Oracle_Home\bpel\system\config\collaxa-config.xml file.

2. If you are using the Oracle BPEL Worklist Application or a customized worklist application, update identityService, identityConfigService, taskService, taskMetadataService, taskQueryService, userMetadataService, and runtimeConfigService soapEndPoint URL HTTP ports in the SOA_Oracle_Home\bpel\system\services\config\wf_client_config.xml file.

3. If you are using a customized worklist application, ensure that you have also modified wf_client_config.xml in the client code.

4. If you are using e-mail notifications with task updates, update worklistApplicationURL in the SOA_Oracle_Home\bpel\system\services\wf_config.xml file.

   Note:

   Note that some tutorials, demos, utilities, and references in the SOA_Oracle_Home\bpel\samples directory also use hardcoded HTTP ports.

5.9.7 Messages in an Operation

Section "Manipulating SOAP Headers in BPEL" of Chapter 3, "Manipulating XML Data in BPEL" of Oracle BPEL Process Manager Developer's Guide includes the following two paragraphs:

These default activities permit one variable to operate in each direction. For example, the invoke activity has inputVariable and outputVariable attributes. You can specify one variable for each of the two attributes. This is enough if the particular operation involved uses only one payload message in each direction.

However, WSDL supports more than one message in an operation. In the case of SOAP, multiple messages can be sent along the main payload message as SOAP headers. However, BPEL's default communication activities cannot accommodate the additional header messages.

These two paragraphs give the impression that WSDL supports multiple payload messages in an operation. This is incorrect. Message payload and headers are different entities. Headers are not meant to transmit message payloads.

The second paragraph states that WSDL supports more than one message in an operation. SOAP, and not WSDL, supports passing message headers as part of invoking the operation.

5.9.8 Property serviceProperties is Missing a Description

The property serviceProperties listed in Appendix C, "Deployment Descriptor Properties" of Oracle BPEL Process Manager Developer's Guide does not have a description. This property is an XML element that is passed to a WSIF provider.

5.10.1 Changes to Locations of Functionality in Oracle BPEL Control

There have been several changes to the locations of functionality in Oracle BPEL Control in 10.1.3.4.

• Several main tabs of Oracle BPEL Control are either new or have changed names. Table 5-3 describes these changes.

  Table 5-3 Changes to Main Tabs of Oracle BPEL Control

  Tab Names in Releases Prior to 10.1.3.4	Tab Names in Release 10.1.3.4
  Dashboard BPEL Process Instances Activities	Dashboard Processes Instances Activities Configuration Administration

  
  

• The functionality available under the Manage BPEL Domain pages in releases prior to 10.1.3.4 has been moved to the Configuration and Administration tabs. Some of the functionality available in the BPEL Processes and Instances tabs in releases prior to 10.1.3.4 has also been moved. Table 5-4 describes the new and old locations of this functionality in Oracle BPEL Control.

  Table 5-4 Changes to Tabs in Oracle BPEL Control

  Tab Name Locations in Oracle BPEL Control for Releases Prior to 10.1.3.4	Tab Name Locations in Oracle BPEL Control for Release 10.1.3.4
  Manage BPEL Domain > Configuration	Configuration > Domain
  Manage BPEL Domain > Logging	Configuration > Logging
  Manage BPEL Domain > XPath Library	Configuration > XPath Library
  Manage BPEL Domain > Threads	Administration > Threads
  Manage BPEL Domain > Statistics	Administration > Statistics
  Manage BPEL Domain > Adapter Stats	Administration > Adapter Stats
  BPEL Processes > View Process Log	Administration > Process Log
  BPEL Processes > Clear WSDL Cache	Administration > Actions > Clear WSDL Cache
  BPEL Processes > Refresh Alarm Table	Administration > Actions > Refresh Alarm Table
  BPEL Processes > Deploy New Process	Processes > Deploy New Process
  BPEL Processes > Perform Manual Recovery	Administration > Recover (Invokes) Administration > Recover (Callbacks) Administration > Recover (Activity)
  Instances > Purge All Instances	Administration > Action > Purge All Instances
  Instances > Purge Sensor Data	Administration > Action > Purge Sensor Data

  
  

5.10.2 Configuration Properties in Oracle BPEL Control

This section describes configuration property changes in Oracle BPEL Control.

5.10.3 Threads Tab Removed from Oracle BPEL Admin Console

The Threads tab of Oracle BPEL Admin Console has been removed. Threads functionality is available in Oracle BPEL Control. Select Administration > Threads to view details.

5.10.4 Dispatcher Queue Visibility and Usability Improvements

The Thread Allocation Statistics for this BPEL Domain page of Oracle BPEL Control includes the following enhancements:

• Improved visibility into BPEL dispatcher queues by displaying details on both pending and scheduled messages.

• Improved usability with a graph-like visualization tool that refreshes to minimize the number of clicks you must perform while monitoring Oracle BPEL Server performance.

Follow these steps to view dispatcher queue details in Oracle BPEL Control.

1. Select Administration > Threads.

   
   Description of the illustration bpel_queue1.gif
   
   

2. View details about pending and scheduled messages and Oracle BPEL Server performance.

5.10.5 Statistic Collection and Instance Level Viewing Improvements

The Analytics page of Oracle BPEL Control enables you to analyze the source code in a flow chart and monitor activity execution CPU time in a BPEL process.

The Analytics page collects statistics at the process level and allows viewing at the instance level (for the last n requests). This enables you to send a request and see where the problem activities are within that BPEL flow rather than having to determine from the aggregated statistics.

Perform the following steps to view instance level statistics in Oracle BPEL Control:

1. Click the Dashboard tab.

2. Select a deployed BPEL process for which to create a new instance. The Initiate tab appears.

3. Create a new instance, and click Post XML Message.

4. Click the Analytics tab.

5. Click Refresh Process Analytics Data or wait several seconds for the page to refresh.

   Details similar to the following appear:

5.10.6 Automatic Recovery of Messages

You can perform automatic recovery of BPEL process messages when situations such as an Oracle BPEL Server crash occur.

Follow these steps to configure the automatic recovery properties in Oracle BPEL Control.

1. Select Configuration > Auto-Recovery. The page is divided into two sets of configuration properties:

   • Startup schedule

     Recovery occurs immediately after Oracle BPEL Server is started. By default, startup recovery is disabled because startupRecoveryDuration is set to 0. Setting maxMessageRaiseSize to 0 also disables startup recovery.

   • Recurring schedule

     Recovery can be configured to occur once per day. By default, recurring recovery is disabled because startWindowTime and stopWindowTime are set to the same value. Setting maxMessageRaiseSize to 0 also disables recurring recovery.

   
   Description of the illustration bpel_recover1.gif
   
   

   The startup schedule properties are described below.

   Property	Description	Values
   maxMessageRaiseSize	Specifies the maximum number of messages to submit for each startup recovery attempt. This property can limit the impact of recovery on Oracle BPEL Server. This value specifies the maximum number of messages to filter from activity, invoke, and callback queries; that is, 50 messages from each of the activity, invoke, and callback tables. The default value is 50. A negative value causes all messages selected from the database to be submitted for recovery. A zero value causes no messages to be selected from the database (effectively disabling recovery).	The default value is 50.
   startupRecoveryDuration	Specifies the number of seconds for which the startup recovery period lasts. After Oracle BPEL Server starts, it goes into a startup recovery period. During this period, pending activities and undelivered callback and invocation messages are resubmitted for processing. The default value is 0 (0 minutes). A negative or zero value disables startup recovery.	The default value is 0.
   subsequentTriggerDelay	Specifies the number of seconds between recovery attempts during the Oracle BPEL Server startup recovery period. If the next recovery trigger falls outside the server startup period, that trigger is not scheduled and Oracle BPEL Server moves into the recurring recovery period. The default value is 300 (5 minutes). A negative value causes the default to be selected.	The default value is 300.

   
   
   
   Description of the illustration bpel_recover2.gif
   
   

   The recurring schedule properties are described below.

   Property	Description	Values
   maxMessageRaiseSize	Specifies the maximum number of messages to submit for each recurring recovery attempt. This property can limit the impact of recovery on Oracle BPEL Server. This value specifies the maximum number of messages to filter from activity, invoke, and callback queries; that is, 50 messages from each of the activity, invoke, and callback tables. The default value is 50. A negative value causes all messages selected from the database to be submitted for recovery. A zero value causes no messages to be selected from the database (effectively disabling recovery).	The default value is 50.
   startWindowTime	Specifies the start time for the daily recovery window, specified in 24-hour notations. Therefore, 2:00 pm is specified as 14:00. The leading zero does not need to be specified for single digit hour values (1:00-9:00). The default value is midnight (00:00). Any invalid, parsed time values default to midnight.	The default value is 00:00.
   stopWindowTime	Specifies the stop time for the daily recovery window, specified in 24-hour notations. Therefore, 2:00 pm is specified as 14:00. The leading zero does not need to be specified for single digit hour values (1:00-9:00). If daily recovery is not required, set the start and stop window times to be the same value. If the stop window time is earlier then the start window time, both the start and stop window times are changed to their respective default values. The default value is midnight (00:00). Any invalid, parsed time values are defaulted to 00:00.	The default value is 00:00.
   subsequentTriggerDelay	Specifies the number of seconds between recovery attempts during daily, recurring startup recovery periods. If the next recovery trigger falls outside of the current recovery period, that trigger is not scheduled until the next recurring recovery period (tomorrow). The default value is 300 (5 minutes). A negative value causes the default to be selected.	The default value is 300.

   
   

2. Edit these properties with values appropriate to your environment.

5.10.7 Statistics Collection for Diagnostic Purposes

You can collect logs, thread dumps, and run-time statistics over a short time period for diagnostic purposes. For example, if an instance fails, you can begin collecting statistics, invoke the failed instance again, and complete collection of statistics for the failed instance. These statistics can then be used for debugging the failed instance or attached to a bug report. This reduces the number of round trip interactions between you and support to debug the issue.

Follow these steps to start collecting statistics for diagnostic purposes on a failed instance in Oracle BPEL Control.

1. Select Administration > Diagnostics. The Diagnostics Collection page appears.

   
   Description of the illustration bpel_diag.gif
   
   

2. Click Start Collection to begin the collection of statistics. A message appears stating that diagnostics are being collected. All loggers are set to DEBUG mode. Statistics are collected every 10 seconds until five minutes is reached or Stop Collection is selected.

3. Return to the Dashboard tab to invoke an instance of a BPEL process that previously failed.

4. Return to the Diagnostics Collection page and note that statistics collection is continuing.

5. Wait five minutes or click Stop Collection when you want to stop the collection of statistics. A message appears stating that logs are being gathered.

6. When prompted, select to open or save the ZIP file containing the collected statistics, logs, and thread dumps. These statistics can be used to debug a failed instance or attached to a bug report.

   Note:

   You can export a ZIP file of a BPEL process by clicking Export Process under Dashboard > BPEL_process_name > Manage in Oracle BPEL Control.

5.10.8 XML Validation of Input Payloads

You can validate an XML input payload against the input message types for a BPEL process. This enables you to validate a payload before invoking an instance. This helps to prevent incorrect and invalid XML payloads from being delivered to a process and XPath errors from appearing in subsequent assign activities.

Follow these steps to validate XML payloads:

1. Select Dashboard > BPEL_process_name > Validate XML.

2. Enter the payload schema to validate. The payload can be either the entire SOAP envelope or the element type (without the soap:Body tag).

   
   Description of the illustration bpel_valid.gif
   
   

3. Click Validate XML.

   A message indicating whether validation was successful or unsuccessful appears. If validation was unsuccessful, the errors are described.

5.10.9 Encryption and Decryption Properties for BPEL Payloads

You can encrypt and decrypt sensitive payload data for a BPEL process being passed from boundary to boundary. In addition, this data is not visible in the audit and debug logs.

Follow these steps to encrypt and decrypt data.

1. Create properties and property aliases for the data elements to be encrypted in Oracle JDeveloper.

   • To create properties, right-click in the BPEL designer and select View > Properties, then highlight the Properties folder and click the Create icon.

     For this example, the properties ssn and rating are created.

   • To create property aliases, right-click and select View > Property Aliases, then highlight the Property Aliases folder and click the Create icon.

   When complete, the updates are reflected in the WSDL file of the BPEL process:

   <bpws:property name="ssn" type="xsd:string" xmlns:ssnns="http://a" />
       <bpws:property name="rating" type="xsd:string" xmlns:rating="http://b" />
       <bpws:propertyAlias xmlns:services="http://services.otn.com"
                           xmlns:rating="http://b"
                           propertyName="rating:creditrating"
                           messageType="services:LoanServiceRequestMessage"
                           part="payload"
                           query="/s1:loanApplication/s1:creditRating"/>
   
       <bpws:propertyAlias xmlns:services="http://services.otn.com"
                           xmlns:rating="http://b"
                           propertyName="rating:rating"
      messageType="services:CreditRatingServiceResponseMessage"
                           part="payload"
                           query="/services:rating"/>
   
       <bpws:propertyAlias xmlns:ssnns="http://a"
                           xmlns:services="http://services.otn.com"
                           propertyName="ssnns:ssn"
    messageType="services:CreditRatingServiceRequestMessage"
                           part="payload"
                           query="/services:ssn"/>
   
       <bpws:propertyAlias xmlns:ssnns="http://a"
                           xmlns:services="http://services.otn.com"
                           propertyName="ssnns:ssn"
                           messageType="services:LoanServiceRequestMessage"
                           part="payload"
                           query="/s1:loanApplication/s1:SSN"/>
   
       <bpws:propertyAlias xmlns:ssnns="http://a"
                           propertyName="ssnns:ssn"
                           messageType="tns:LoanFlowRequestMessage"
                           part="payload"
                           query="/s1:loanApplication/s1:SSN"/>
   

2. Open the bpel.xml file.

3. Add the encryptProperties and decryptProperties properties under the configurations section:

   <configurations>
           <property name="encryptProperties">{http://a}ssn 
              {http://b}rating</property>
           <property name="decryptProperties">{http://a}ssn 
              {http://b}creditrating</property>
      </configurations>
   

   All partner links now perform the following tasks:

   • Encrypt /s1:loanApplication/s1:SSN and /services:rating (based on the message type)

   • Decrypt /s1:loanApplication/s1:SSN and /s1:loanApplication/s1:creditRating (based on the message type)

5.10.10 Automatically Changing URLs and Properties for Development, Test, and Production Environments

In previous releases, when moving a BPEL process to and from development, test, and production server environments, you needed to modify several URLs and properties in the bpel.xml, WSDL, and schema files of the BPEL process. With release 10.1.3.4, you can create a BPEL deployment plan in an XML file in which you define the URL and property values to use for different environments. During process deployment, the deployment plan is used to search for files in the BPEL suitcase JAR file and replace them with files that include the URLs and properties appropriate to the environment.

5.10.11 Changes Made to Deployment Descriptor Properties in 10.1.3.3 and 10.1.3.4

Table 5-7 describes deployment descriptor property changes.

5.10.12 Fault Management Behavior When the Number of Instance Retries is Exceeded

With release 10.1.3.4, the behavior of the fault management framework has been changed for when you configure a fault policy to recover instances with the ora-retry action and the number of specified instance retries is exceeded. This change is described in Table 5-8.

Marking instances as open.faulted ensures that no instances are lost. You can then configure another fault handling action following the ora-retry action in the fault policy file, such as the following:

• Configure an ora-human-intervention action to manually perform instance recovery from Oracle BPEL Control

• Configure an ora-terminate action to close the instance (mark it as closed.faulted) and never retry again

However, if you do not set an action to be performed after an ora-retry action in the fault policy file and the number of instance retries is exceeded, the instance remains marked as open.faulted, and recovery attempts to handle the instance.

For example, if no action is defined in the following fault policy file after ora-retry:

<Action id="ora-retry">
       <retry>
          <retryCount>2</retryCount>
          <retryInterval>2</retryInterval>
          <exponentialBackoff/>
       </retry>
  </Action>

Oracle BPEL Server performs the following actions:

• Attempts the invoke activity (using the above-mentioned fault policy code to handle the fault)

• Retries two times at increasing intervals (after two seconds, then after four seconds)

• If all retry attempts fail, Oracle BPEL Server performs the following actions:

  • Logs a detailed fault error message in the audit trail

  • Marks the instance as open.faulted (in-flight state)

  • Picks up the instance and re-attempts the invoke activity

• Oracle BPEL Server recovery may also fail. In that case, the invoke activity is re-executed. Additional audit messages are logged.

http://www.oracle.com/technology/products/ias/bpel/index.html

5.10.13 Asynchronous Audit Trail

Prior to release 10.1.3.4, the audit trail and the BPEL process participated in the same transaction. Under certain circumstances, instances of a BPEL process did not appear in Oracle BPEL Control. This gave the impression that the process did not run. In fact, the process did run, but for whatever reason, the transaction was rolled back. This also rolled back the audit trail. Therefore, no evidence of the instance appeared in Oracle BPEL Control.

Oracle BPEL Server behaved correctly; that is, no data was committed that should not have been and no messages were lost. The last dehydrated message was available under the Perform Manual Recovery link in Oracle BPEL Control and the BPEL process was retrievable. However, there were some circumstances under which instances whose transactions were rolled back did not appear in Oracle BPEL Control.

In release 10.1.3.4, the audit trail participates in its own separate transaction. If a BPEL instance is rolled back, all behavior is the same. The only difference is that you can now see the instance in Oracle BPEL Control. In addition, the audit trail thread is asynchronous so the BPEL instance is not blocked while waiting for the audit trail to be saved to the dehydration store.