Lessons Learned Installing Oracle OER Workflows

This post lists the resolutions for various issues I encountered installing BPM Enterprise and BPM Studio and configuring OER workflows.

Configuration Tested

My installation was based on


I used a combination of the following documents:

    OER documentation
    http://docs.oracle.com/cd/E23943_01/soa_governance.htm

    The BPM 10g documentation
    http://docs.oracle.com/cd/E13154_01/bpm/docs65/index.html

    The Oracle Support Note named
    "Steps To Integration OER with OOBPM installed on WLS [ID1384103.1]"
     https://support.oracle.com/CSP/main/article?cmd=show&type=NOT&doctype=HOWTO&id=1384103.1


    The following diagram illustrates the tested configuration
configuration



WLS Version for BPM Enterprise

It is vital that the correct version of WLS be used with BPM Enterprise
The acceptable WLS versions for BPM are listed at the following link
http://www.oracle.com/technetwork/middleware/bpm/documentation/obpm-config-matrix-085247.html#bpmes1032
The link mentions WLS 10.0.1 and 10.3.0, and 10.3.3 depending on the version of BPM Enterprise.
These are the exact versions supported, newer versions of WLS are not compatible.
It is an easy mistake to assume later versions of WLS 10.3.X will be equivalent.
Attempts to use a later releases of WLS will lead to BPM configuration errors
such as ClassNotFound exceptions for specialized BPM Oracle Drivers which are not in newer WLS releases
and with errors related to passwords not containing at least one special character.



BPM Enterprise Configuration Issues

Issue 1:
BPM Enterprise Config Wizard fails.
Investigation reveals the WLST script ./configWizard/tmp/config.py fails contains the error
ClassNotFound for the BPM Oracle DB Driver
Cause:
The "BPM's Oracle Driver Versions: 10,11" driver classes are only distributed in supported version of WLS defined here
http://www.oracle.com/technetwork/middleware/bpm/documentation/obpm-config-matrix-085247.html#bpmes1032
Solution:
Install WLS 10.3 or other compatible version.



Issue 2:
BPM Config Wizard fails.
WLST script ./configWizard/tmp/config.py fails with error invalid password, the password must contain a special character
Cause:
Wrong version of WLS for BPM.
BPM 10g relies on older versions of WLS that accepted less secure passwords.
Solution:
Install WLS 10.3 or other compatible version.




OER Workflow OBPM_SetupScripts issues


Issue 3:
On linux systems the supplied setenv.sh script fails with the error
Bad interpretter: No such file or directory
Cause:
The line termination characters are incorrect in the script.  
Solution:
Fix the line termination characters in the file using dos2unix utility or using the vi editor.
  To use the vi editor method, edit the file using vi, and run the command
    :set fileformat=unix
     then save the file using the  :wq  command


Issue 4:
Ant import-orgdata
fails with message
Build Failed: Could not create task or type of type: http://ant.apache.org/manual/Types/antlib.html
Cause:
BPM Custom ant tasks could not be found. 
Solution:
Ensure the ANT_LIB path is correctly set in the environment.
On linux systems the setenv.sh script may need to be sourced to set the variables in the current shell.
for example . ./setenv.sh
  

Issue 5:
Ant import-orgdata
fails with message
fuego.directory.exception.InvalidSchemaException: Directory [default] has not been correctly initialized.
Detail: Even though a Directory Service is currently present at the specified location,
          the expected Oracle entries could not be found.
          Either the schema has not been created or the existing directory corresponds to a different Oracle version.
Cause:
BPM Domain not running, Directory Service Application unavailable
Solution:
Start the BPM Server domain
  
 
Issue 6:
Ant import-orgdata
  fails with message
  [fuego:publish] fuego.mami.exception.MAMIException:Engine aler_engine was not found.
Cause:
BPM Domain not running and therefore the Directory Service Application is unavailable,
 or the uri for the BPM server is incorrect in the build.properties file
Solution:
 Confirm the BPM server is running.
 Confirm the fuego.server.id property is set to the correct engine name in the build.propertiers file
 Confirm the correct server url and port are set in the build.properties
  
 

Issue 7:
The refresh_workflows script generates the following warning:
  Apr 2, 2012 8:41:28 AM org.apache.axis.utils.JavaUtils isAttachmentSupported
   WARNING: Unable to find required classes (javax.activation.DataHandler and     
    javax.mail.internet.MimeMultipart).
    Attachment support is disabled.
Cause:
mail.jar is missing in the classpath.
Solution:
  mail.jar is an optional package to Java SE and is included in Java Enterprise Edition
  http://www.oracle.com/technetwork/java/javamail/index.html
  Java Mail also requires Java Activation Framework (JAF) Note Only if jdk < 1.6
  Download Java Mail 1.4.5 from here
  http://www.oracle.com/technetwork/java/javamail/index-138643.html
  and JAF from here
  http://www.oracle.com/technetwork/java/javase/index-jsp-136939.html
  unzip javamail1_4_5.zip to a directory of your choice
  add mail.jar to the classpath for refresh_workflows.sh
  

OER / BPM Workflow Runtime issues


Issue 8:
event_monitor command fails to start with error
Could not connect to broker URL: tcp://localhost:61700. Reason: java.net.ConnectException: Connection refused
Cause:
The ActiveMQ server within the OER server is not running
Solution:
 Ensure the "Enable Event Manager" property is set in OER Admin under System Settings.
 This admin setting should update the cmee.eventframework.enabled property is set in the WEB-INF\classes\eventing.properties file of the deployed OER application.
 If OER is running on WLS, ensure the correct event.properties file is updated.
 There may be a copy of the OER app in the applications (hot deploy folder) and another in the stage directory. In such a case, the stage directory copy is the active copy
  

 

Issue 9:
OER unable to send events to BPM, the follow error appears in the cmee.log file
         AxisFault
            faultCode: {http://schemas.xmlsoap.org/soap/envelope/}Server.userException
            faultSubcode:
            faultString:
            faultActor:
            faultNode:
            faultDetail:
                  {}OperationException:
                      <message>Process access denied.</message>
Cause:
 A permission problem for the configured user id in the EndPointEventSubscription.xml
 The user specified does not have sufficient rights to call the workflow web services.
 Described here in OER documentation
  http://docs.oracle.com/cd/E17904_01/doc.1111/e16580/oerwf.htm
Solution:
  Update the EndPointEventSubscription.xml to use
  the user aler_workflow_user with the password aler_workflow_pass
  Note the aler_workflow_pass value must be encrypted in the EndPointEventSubscription.xml file.
  



Issue 10:
When workflows processes in BPM are executing, BPM Engine log shows error
ChangeManagment tab cannot be approved since asset is in wrong state, not submitted/accepted
Cause:
The default workflow.xml file is configured to autoApprove the ChangeManagement tab.
The approve fails because the asset is not in the accepted state.
The asset is not accepted because the autoApprove=true in the workflow.xml failed for the asset type.
The autoApprove failed because the asset was originially created using the Quick Submit function, which appears as the "Create Asset" link in the oer web page.
Solution:
Do not use the "Submit an Asset" link on the oer home page to create assets that will be involved in a workflow.
Create the asset using the Asset Editor, using the File->New   commands in the main menu.
This is documented in the OER documentation here
 http://docs.oracle.com/cd/E23943_01/admin.1111/e16580/oerwf.htm#sthref503 
  
         


Issue 11:
BPM OER Workflow event processing fails with the error
fuego.server.exception.MaxInstanceSizeRuntimeException: Max instance size exceeded.
Cause:
The "Maximum Instance Size" property for the BPM engine is too small.

Solution:
The "Maximum Instance Size" for the BPM engine must be set to 16000 (16 MB)
even for development.
This is mentioned in the Oracle documentation here
http://docs.oracle.com/cd/E17904_01/doc.1111/e16580/oerwf.htm#CJHDGBFB
For development the Instances Cache value can be lowered to 200
 


BPM Studio Installation Issues


Issue 12:
Freshly installed BPM Studio 10.3.2 on OEL 5.5 crashes with error
          Hotspot unexpected error  SIGSEV
          # Java VM: Java HotSpot(TM) Client VM (1.5.0_11-b03 mixed mode, sharing)
          # Problematic frame:
          # C  [libxul.so+0xe50e81]
Cause:
Wrong version of xulrunner library loaded by eclipse
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=236724#c50

Solution:
Add a property to eclipse.ini to point to the correct 32 bit version of xulrunner library
          -Dorg.eclipse.swt.browser.XULRunnerPath=/usr/lib/xulrunner-1.9.2
to the eclipse.ini file
 


Issue 13:
BPMStudioWorkspace included with OER fails to compile in BPM Studio
  3 compile errors of type
  java.lang.UnsupportedClassVersionError: Bad version number in .class file.
Cause:
The workspace contains Java 1.6 compiled classes and the internal Eclipse compiler is using Java 1.5
BPM Studio should be configured to use a 1.6 JDK and
the internal compiler must be set to use JDK 1.6
The workspace contains Java 1.6 compiled classes and the internal Eclipse compiler is using Java 1.5

Solution:
To update BPM Studio to use JDK 1.6.
add the -vm flag to the eclipse.ini file to point to the jdk 1.6 home
change the bootclasspath path to point to the tools.jar file in the 1.6 jdk home
The following shows an updated eclipse.ini file

            -vm /u02/app/java/jdk1.6.0_27/bin/java
            -showsplash
            fuego.eclipse.studio
            -vmargs
            -Xms128m
            -Xmx512m
            -Dfuego.fstudio=true
            -DprodMode=preProduction
            -Dbea.home=/home/oracle/OraBPMStudioHome/..
            -Djava.endorsed.dirs=""
            -Dsun.lang.ClassLoader.allowArraySyntax=true
            -Dfuego.studio.engine.java.options=-Dsun.lang.ClassLoader.allowArraySyntax=true
            -Dorg.eclipse.swt.browser.XULRunnerPath=/usr/lib/xulrunner-1.9.2
            -XX:PermSize=64M
            -XX:MaxPermSize=128M
            -Xbootclasspath/a:/u02/app/java/jdk1.6.0_27/lib/tools.jar

 To change the internal compiler to use JDK 1.6 see the following Oracle support document
  https://support.oracle.com/CSP/main/article?cmd=show&type=NOT&doctype=PROBLEM&id=852451.1

  In summary, to change internal compiler
  1) Install JDK 1.6
  2) Delete the directory jre from <BPM_STUDIO_INSTALL>\eclipse.
  3) Start the Studio from the command line using: <BPM_STUDIO_INSTALL>\eclipse\eclipse.exe -vm <JAVA_HOME>/bin
  4) Check Help->About->Configuration Details to confirm that the property "java.version" is 1.6
 


OER Issues


Issue 14:
OER application fails to start with error

[HTTP:101216]Servlet: "com.flashline.cmee.servlet.systemconfig.SystemEmailServlet"
failed to preload on startup in Web application: "/oer".
java.lang.NullPointerException
Cause:
OER was able to connect to the database but was unable to read configuration properties from the database.
The database password for the oer user may have expired.

Solution:
Verify the database credentials for the OER user.
refer to the   WEB-INF/classes/database.properties in the OER application deployment.
 
Sample database.properties file
db.tablespace.index=OER_INDEX
db.connectionclass=com.flashline.db.ext.OracleConnection
db.tablespace.data=OER_DATA
db.url=jdbc\:oracle\:thin\:@localhost\:1521\:orcl
db.driver=oracle.jdbc.driver.OracleDriver
db.username=OER
db.tablespace.blob=OER_LOB
db.usepool=true
db.password=v2_1.G+NTr3az8thaGGJBn0vwPg\=\=

Not the database password must be encrypted in the file.
http://docs.oracle.com/cd/E23943_01/admin.1111/e16580/password.htm#CIHBIDBB

Since OER will not start the diag method of password encryption desribed in the link above is unavailable.

An alternate approach is to use the encryption tool provided with the workflow package.
You can use the runWfSecurity.sh tool in the workflow-tools directory

${middleware_home}/repository111/core/workflow-tools/runWfSecurity.sh

Create an in.txt file and place the clear password in a <password> element for example

    <password>welcome1</password>   

./runWfSecurity.sh in.txt out.txt

out.txt will contain encrypted passwrd,

    v2_1.G+NTr3az8thaGGJBn0vwPg==

Place value in db.password field in database.properties
where the app is deployed

 
   

Issue 15:
When a new OER artifact store is configured , the browse button is disabled when trying to select files from the store.
Cause:
The browse button functionality is only available for the artifact store type of ClearCase.

Solution:
The artifact url must manually entered or supplied using a cut and paste operation.