19
Oracle Workflow

This chapter discusses the following topics:

• Section 19.1, "Configuration Issues and Workarounds"

• Section 19.2, "Administration Issues and Workarounds"

• Section 19.3, "Documentation Errata"

19.1 Configuration Issues and Workarounds

This section describes configuration issues and their workarounds for Oracle Workflow.

19.1.1 Oracle Workflow in Oracle Application Server and Oracle E-Business Suite

Do not install the standalone Oracle Workflow server in an Oracle E-Business Suite database. If you want to use the version of Oracle Workflow available with Oracle Application Server 10g (9.0.4), or any Oracle Application Server components that depend on this version of Oracle Workflow, then you must install the Oracle Workflow server into a database that is not used for an Oracle E-Business Suite instance.

If you implement Oracle Application Server 10g (9.0.4) with Oracle E-Business Suite, the Oracle Workflow Configuration Assistant will not install the standalone version of the Oracle Workflow server in that database. You can continue to use the version of the Oracle Workflow server embedded in Oracle E-Business Suite instead.

If you choose to install the Oracle Application Server Metadata Repository 10g (9.0.4) into a database used by Oracle E-Business Suite, the Oracle Workflow Configuration Assistant will not install the standalone version of the Oracle Workflow server in that database. You can continue to use the version of the Oracle Workflow server embedded in Oracle E-Business Suite instead, although there may be some limitations in Oracle Application Server functionality. Refer to OracleMetaLink Note 251627.1 (http://metalink.oracle.com) for more information.

19.1.2 Oracle Workflow Component Versions

The version of the Oracle Workflow server components installed in your database, including the Oracle Workflow schema, must match the version of your Oracle Workflow middle tier components. That is, if you want to use Oracle Workflow Release 2.6.3, then both the Oracle Workflow server and middle tier components must be the Release 2.6.3 components, available with Oracle Application Server 10g (9.0.4).

If you want to use an existing Oracle9i Application Server Release 2 (9.0.2) infrastructure database that already has Oracle Workflow Release 2.6.2 installed, then you must upgrade that Oracle Workflow server installation to Release 2.6.3 before using it with an Oracle Application Server 10g (9.0.4) middle tier home. To upgrade the Oracle Workflow server installation to Release 2.6.3, run the Oracle Workflow Configuration Assistant with the Upgrade option from the wf subdirectory in your Oracle Application Server 10g (9.0.4) middle tier home.

Note: Do not use the Oracle Application Server Repository Creation Assistant (OracleAS RepCA) to upgrade an existing Oracle Workflow server installation. Use the Oracle Workflow Configuration Assistant to properly upgrade to Oracle Workflow Release 2.6.3.

19.1.3 Configuring Oracle Workflow Manager

If you want to use the Oracle Workflow Manager component within the Oracle Enterprise Manager Application Server Control, including Oracle Workflow administration features and the Java-based Workflow Notification Mailer, run the Workflow Configuration Assistant to configure Oracle Workflow Manager.

• If you install Oracle Workflow from the Oracle Content Management Software Development Kit CD and the Oracle Universal Installer automatically launches the Workflow Configuration Assistant during the installation, Oracle Workflow Manager is configured automatically.

• If you run the Workflow Configuration Assistant manually, from any Oracle Home where Oracle Workflow files have been installed, then you must first edit the Workflow Configuration Assistant script to provide installation parameters that specify the Oracle Application Server instance and the database where your Oracle Workflow installation resides. The Workflow Configuration Assistant requires this information to configure Oracle Workflow Manager information in the targets.xml file for the Oracle Enterprise Manager Application Server Control.

If you want to configure Oracle Workflow Manager when running the Workflow Configuration Assistant manually, edit the Workflow Configuration Assistant script in the following directory:

• On UNIX: $ORACLE_HOME/wf/install/wfinstall.csh

• On Windows NT: %ORACLE_HOME%\wf\install\wfinstall.bat

Open the script in a text editor and locate the line similar to the following:

. . . repository.jar" WorkflowCA /wfdir <workflow_directory> /orahome <oracle_
home> /ospath $PATH

For example:

. . . repository.jar" WorkflowCA /wfdir /d1/iasinstall/m21pw1/wf /orahome 
/d1/iasinstall/m21pw1 /ospath $PATH

Edit the script to append the parameters required for Oracle Workflow Manager after the /wfdir, /orahome, and /ospath parameters:

. . . repository.jar" WorkflowCA /wfdir <workflow_directory> /orahome <oracle_
home> /ospath $PATH /iasname <schema_name.machine_name> /iasmachine <machine_
name> /iasport <port_number> /iassid <database_SID> /jdbcconnnode <connect_
string> /fileupdate true

Specify the parameter values as follows:

• /iasname - The name of your Oracle Application Server instance, specified in the following format: schema_name.machine_name

• /iasmachine - The host name of your Oracle Application Server instance.

• /iasport - The database listener port number for the database where the Oracle Workflow schema resides.

• /iassid - The System Identifier (SID) for the database where Oracle Workflow is installed.

• /jdbcconnnode - The JDBC connect identifier to access a remote database, specified in the following format: host:port:sid

• /fileupdate - You must specify true as the value of this parameter in order to update the targets.xml file for the Oracle Enterprise Manager Application Server Control.

Save your changes to the script, and start the Workflow Configuration Assistant using the following commands:

• On UNIX:

  $ORACLE_HOME/wf/install/wfinstall.csh
  

• On Windows NT:

  %ORACLE_HOME%\wf\install\wfinstall.bat
  

The Oracle Workflow Configuration Assistant window will appear to let you enter the remaining configuration parameters, including additional parameters required if you want to run the Workflow Notification Mailer. For more details, see your installation documentation.

19.1.4 Running the Workflow Configuration Assistant in Silent Mode

If you start the Workflow Configuration Assistant manually, you can choose to run it in silent mode by first editing the script to enter all your configuration parameters. In this case, you must specify all required parameters as well as any conditionally required parameters for features you want to use.

Edit the Workflow Configuration Assistant script in the following directory:

• On UNIX: $ORACLE_HOME/wf/install/wfinstall.csh

• On Windows NT: %ORACLE_HOME%\wf\install\wfinstall.bat

Open the script in a text editor and locate the line similar to the following:

. . . repository.jar" WorkflowCA /wfdir <workflow_directory> /orahome <oracle_
home> /ospath $PATH

For example:

. . . repository.jar" WorkflowCA /wfdir /d1/iasinstall/m21pw1/wf /orahome 
/d1/iasinstall/m21pw1 /ospath $PATH

Edit the script to append your additional parameters after the /wfdir, /orahome, and /ospath parameters:

. . . repository.jar" WorkflowCA /wfdir <workflow_directory> /orahome <oracle_
home> /ospath $PATH /wfacct <workflow_schema> /wfpasswd <workflow_schema_
password> /syspasswd <SYS_password> /instype <installation_type> /orasid 
<database_SID> /constr <connection_string>

The script must include the following required parameters to run the Workflow Configuration Assistant in silent mode:

• /wfdir - The Oracle Workflow directory within your Oracle Home directory. The default directory is: $ORACLE_HOME/wf

• /orahome - Your Oracle Home directory.

• /wfacct - The user name of your Oracle Workflow database account. The default Workflow account for a fresh installation is owf_mgr.

• /wfpasswd - The password for your Oracle Workflow database account.

• /syspasswd - Your SYS password. See your Oracle DBA if you need more information.

  Note: If you choose to enter these passwords in the script in order to run the Oracle Workflow Configuration Assistant in silent mode, ensure that you take precautions to protect the file so that only authorized administrators can access this sensitive information.

• /instype - Specify Install to perform a fresh installation of Oracle Workflow, or to reinstall Oracle Workflow Release 2.6.3. Specify Upgrade to upgrade an existing installation of Oracle Workflow Release 2.6.0, Release 2.6.1, or Release 2.6.2. Specify "add language" to load a language into your existing installation of Oracle Workflow.

• /nlsopt - If you specified Add language for the /instype parameter, then you must also specify the /nlsopt parameter with the language code for the language you want to add. Oracle Workflow Server supports the languages supported by Oracle Application Server:
  • AR - Arabic

  • PTB - Brazilian Portuguese

  • FRC - Canadian French

  • CS - Czech

  • DK - Danish

  • NL - Dutch

  • US - English

  • SF - Finnish

  • F - French

  • D - German

  • EL - Greek

  • IW - Hebrew

  • HU - Hungarian

  • I - Italian

  • JA - Japanese

  • KO - Korean

  • ESA - Latin American Spanish

  • N - Norwegian

  • PL - Polish

  • PT - Portuguese

  • RO - Romanian

  • RU - Russian

  • ZHS - Simplified Chinese

  • SK - Slovak

  • E - Spanish

  • S - Swedish

  • TH - Thai

  • ZHT - Traditional Chinese

  • TR - Turkish

  For a list of standard language abbreviations in the Oracle Database, see: Locale Data, Oracle National Language Support Guide.

• /orasid - The System Identifier (SID) or TNS name for the database where Oracle Workflow is installed.

• /constr - The connect string for the database where Oracle Workflow is installed.

You can also specify the following additional parameters if you want to use the corresponding features.

• /tablespace - A valid tablespace name that you want to assign to the Oracle Workflow database account. If you do not specify this parameter, the default tablespace for the Oracle Workflow database account in a fresh installation defaults to USERS. This parameter is valid only when you are performing a fresh installation of Oracle Workflow. You cannot change the tablespace for Oracle Workflow during an upgrade.

• /debug - Specify true if you want the Workflow Configuration Assistant to write debug information to the workflow.log file, or false if you do not want to log this information.

• Specify these parameters if you want to integrate with Oracle Internet Directory as your Oracle Workflow directory service.
  • /ldaphost - The name of the host on which your Lightweight Directory Access Protocol (LDAP) directory resides.

  • /ldapport - The port on the host.

  • /ldapuser - The LDAP user account used to connect to the LDAP server. This user name must have write privileges and is required to bind to the LDAP directory. For example: cn=orcladmin

  • /ldapopwd - The password for the LDAP user account.

  • /ldaplogbase - The LDAP node under which change logs are located. For example: cn=changelog

  • /ldapuserbase - The LDAP node under which user records can be found. For example: cn=Base, cn=OracleSchemaVersion

• Specify these parameters if you want to use Oracle Workflow Manager.
  • /iasname - The name of your Oracle Application Server instance, specified in the following format: schema_name.machine_name

  • /iasmachine - The host name of your Oracle Application Server instance.

  • /iasport - The database listener port number for the database where the Oracle Workflow schema resides.

  • /iassid - The System Identifier (SID) for the database where Oracle Workflow is installed.

  • /jdbcconnnode - The JDBC connect identifier to access a remote database, specified in the following format: host:port:sid

  • /fileupdate - You must specify true as the value of this parameter in order to update the targets.xml file for the Oracle Enterprise Manager Application Server Control.

• Specify these parameters if you want to use the Workflow Notification Mailer. Note that if you specify these parameters, you must also specify the Oracle Workflow Manager parameters.
  • /mailserver - The name of the inbound IMAP mail server.

  • /mailuser - The user name of the mail account that the notification mailer uses to send and receive e-mail messages.

  • /mailhtml - The base URL that identifies the Web agent defined for Oracle Workflow in Oracle HTTP Server. The HTML agent should be specified in the following format:

    http://<server.com:portID>/pls/wf
    

    where <server.com:portID> represents the server and TCP/IP port number on which your web listener accepts requests.

  • /mailhost - The name of the outbound SMTP mail server.

  • /mailreply - The address of the e-mail account that receives incoming messages, to which notification responses should be sent.

Save your changes to the script, and start the Workflow Configuration Assistant using the following commands:

• On UNIX:

  $ORACLE_HOME/wf/install/wfinstall.csh
  

• On Windows NT:

  %ORACLE_HOME%\wf\install\wfinstall.bat
  

If the script includes all the minimum required parameters, then it performs the configuration silently, without displaying the Oracle Workflow Configuration Assistant window.

19.1.5 LDAP Port

If you choose to integrate with Oracle Internet Directory, you specify Lightweight Directory Access Protocol (LDAP) server information for your LDAP directory, either in the Workflow Configuration Assistant or in the Global Workflow Preferences page within Oracle Workflow. The port you specify to connect to the LDAP server must be a non-Secure Sockets Layer (non-SSL) port.

19.1.6 ecxutils.jar Errors

In some cases the workflow.log file produced during installation and configuration of Oracle Workflow may show errors in loading a file named ecxutils.jar. You can safely ignore these errors.

19.1.7 Changing the Workflow Directory Service Implementation After Installation

During the installation and configuration of Oracle Workflow, you choose the type of directory service to implement. You can either integrate with Oracle Internet Directory (OID) and Oracle Application Server Single Sign-On, or you can use Oracle Database users and roles as your directory repository for Oracle Workflow.

If necessary, you can change your directory service implementation after the initial installation and configuration are complete.

For more information, see Setting Up Oracle Workflow, Oracle Workflow Administrator's Guide.

19.1.7.1 Converting from Oracle Database Users to Oracle Internet Directory

1. Ensure that the DBMS_LDAP PL/SQL package is loaded in your database. This package contains the functions and procedures that can be used to access data from LDAP servers and is required for LDAP synchronization. To check whether the DBMS_LDAP package is already installed, connect to SQL*Plus and use the following command:

   desc DBMS_LDAP
   

   If the DBMS_LDAP package does not already exist, load it manually by running the catldap.sql script located in the <ORACLE_HOME>/rdbms/admin directory. Run this script as the SYS user. For example, use the following command:

   sqlplus "SYS/<SYS password> as sysdba" @$ORACLE_HOME/rdbms/admin/catldap.sql
   

2. Run the <ORACLE_HOME>/wf/sql/wfdircsv.sql script to implement Oracle Workflow directory service views that support OID integration. For example, use the following command:

   sqlplus owf_mgr/<passwd> @$ORACLE_HOME/wf/sql/wfdircsv.sql
   

3. Load the appropriate version of the WFA_SEC package, which contains Oracle Workflow security functions and procedures. To load this package, log on to SQL*Plus as the Oracle Workflow database user and run the <ORACLE_HOME>/wf/sql/wfsecssb.sql script. For example, use the following command:

   sqlplus owf_mgr/<passwd> @$ORACLE_HOME/wf/sql/wfsecssb.sql
   

4. Update the Database Access Descriptor (DAD) for Oracle Workflow in the Oracle HTTP Server dads.conf file, specifying the following parameters. You can either use Oracle Enterprise Manager to update the DAD or edit the dads.conf file directly. The DAD should be named /pls/your_Workflow_DAD. For example: /pls/wf
   • PlsqlDatabaseUsername - Oracle Workflow schema

   • PlsqlDatabasePassword - Oracle Workflow schema password

   • PlsqlDatabaseConnectString - Database connect string

   • PlsqlDefaultPage - wfa_html.home

   • PlsqlSessionStateManagement - StatelessWithResetPackageState

   • PlsqlAuthenticationMode - Basic

5. Protect the Oracle Workflow DAD by adding the following entry in your mod_osso configuration file. Replace "your_Workflow_DAD" with the name of your DAD.

   <Location /pls/your_Workflow_DAD>
      require valid-user
      authType Basic
   </Location>
   

   For more information, see: Developing Applications Using mod_osso, Oracle Application Server Single Sign-On Application Developer's Guide.

   After you update the DAD and the mod_osso configuration file, restart Oracle HTTP Server.

6. Set the following LDAP preferences in the Global Workflow Preferences page. For details, see: To Set Global User Preferences, Oracle Workflow Administrator's Guide.
   • LDAP Host

   • LDAP Port

   • LDAP User Name

   • LDAP Password

   • LDAP Changelog Base Directory

   • LDAP User Base Directory

7. Migrate your existing Workflow user information to Oracle Internet Directory. You must perform a one-time migration of existing Oracle Workflow user information to OID to enable single sign-on and single administration. Ensure that you migrate all the necessary data from WF_LOCAL_USERS as well as any other user tables in which you previously stored user information. After performing the migration, you should maintain your user information only through OID.

   OID provides a migration tool called ldifmigrator. To use this tool, you must extract your user information from the database into an intermediate LDAP Data Interchange Format (LDIF) file, with substitution variables wherever necessary. The ldifmigrator tool converts the intermediate entries in the file to actual LDIF entries by replacing the variables based on arguments provided at runtime or information retrieved from the LDAP directory. The LDIF file produced by the ldifmigrator can then be uploaded into OID using OID bulk tools.

   For more information about the ldifmigrator, the format required for the intermediate LDIF file, and OID bulk upload tools, see: Appendix A: Syntax for LDIF and Command-Line Tools, Oracle Internet Directory Administrator's Guide.

8. Use the WF_LDAP APIs to periodically synchronize your Oracle Workflow directory service with OID. For instructions, see: Synchronizing Oracle Workflow Directory Services with Oracle Internet Directory, Setting Up Oracle Workflow, Oracle Workflow Administrator's Guide.

19.1.7.2 Converting from Oracle Internet Directory to Oracle Database Users

1. Stop any database jobs you have scheduled to execute the WF_LDAP APIs to synchronize your Oracle Workflow directory service with OID. For more information, see: Synchronizing Oracle Workflow Directory Services with Oracle Internet Directory, Setting Up Oracle Workflow, Oracle Workflow Administrator's Guide.

2. Update the Database Access Descriptor (DAD) for Oracle Workflow in the Oracle HTTP Server dads.conf file, specifying the following parameters. You can either use Oracle Enterprise Manager to update the DAD or edit the dads.conf file directly. The DAD should be named /pls/your_Workflow_DAD. For example: /pls/wf
   • PlsqlDatabaseConnectString - Database connect string

   • PlsqlDefaultPage - wfa_html.home

   • PlsqlSessionStateManagement - StatelessWithResetPackageState

   • PlsqlAuthenticationMode - Basic

   Ensure that you do not specify a database user name or password, in order to enable mod_plsql database authentication.

3. Delete the entry for your Workflow DAD from the mod_osso configuration file.

   After you update the DAD and the mod_osso configuration file, restart Oracle HTTP Server.

4. Run the <ORACLE_HOME>/wf/sql/wfdirouv.sql script to map the Oracle Workflow directory service views to your Oracle Database users and roles. For example, use the following command:

   sqlplus owf_mgr/<passwd> @$ORACLE_HOME/wf/sql/wfdirouv.sql
   

   The wfdirouv.sql script sets each native Oracle Database user's e-mail address to the user's respective username. As a minimal setup step, you should edit the script to either link your native Oracle Database users to an existing mail directory store through the WF_ROLES view definition or, if the usernames and e-mail account names match, then simply add the domain for your organization, such as '@oracle.com', to the usernames in the WF_USERS view definition. Typically, the columns that you change are EMAIL_ADDRESS in WF_USERS and EMAIL_ADDRESS in WF_ROLES. For more information, see: Setting Up Oracle Workflow, Oracle Workflow Administrator's Guide.

5. Load the appropriate version of the WFA_SEC package, which contains Oracle Workflow security functions and procedures. To load this package, log on to SQL*Plus as the Oracle Workflow database user and run the <ORACLE_HOME>/wf/sql/wfsecwsb.sql script. For example, use the following command:

   sqlplus owf_mgr/<passwd> @$ORACLE_HOME/wf/sql/wfsecwsb.sql
   

6. Clear the following LDAP preferences in the Global Workflow Preferences page. For details, see: To Set Global User Preferences, Oracle Workflow Administrator's Guide.
   • LDAP Host

   • LDAP Port

   • LDAP User Name

   • LDAP Password

   • LDAP Changelog Base Directory

   • LDAP User Base Directory

19.2 Administration Issues and Workarounds

This section describes administration issues and their workarounds for Oracle Workflow.

19.2.1 Java-Based Workflow Notification Mailer

In Release 2.6.3, Oracle Workflow includes a Java-based notification mailer program, implemented as a service component within the Generic Service Component Framework, which communicates notifications to users via e-mail and interprets responses. Oracle Workflow provides one seeded notification mailer service component called the Workflow Notification Mailer. This program requires an outbound SMTP mail server and an inbound IMAP mail server.

The new Java-based implementation of the notification mailer replaces the C-based Notification Mailer program that was used in previous releases of Oracle Workflow. If you are upgrading an existing installation of Oracle Workflow to Release 2.6.3, note that the executable file for the C-based Notification Mailer is replaced with a stub file during the upgrade, and you can no longer run that version of the Notification Mailer. Instead, use the Oracle Workflow Manager component within the Oracle Enterprise Manager Application Server Control to run the Java-based Workflow Notification Mailer.

19.3 Documentation Errata

This section describes known errors in the documentation.

19.3.1 Database Access Descriptor

In the Oracle Workflow Installation Notes for Oracle Content Management SDK, the description of the Workflow Configuration Assistant states that if you choose the Install or Upgrade options, the Workflow Configuration Assistant creates a Database Access Descriptor (DAD) for Oracle Workflow in the mod_osso configuration file within your Oracle HTTP Server installation. The DAD is actually created in the dads.conf file within your Oracle HTTP Server installation.

19.3.2 DBMS_LDAP Package

In the Oracle Workflow Installation Notes for Oracle Content Management SDK, the "Oracle Workflow Server Installation" section lists "Load DBMS_LDAP package (conditionally required)" as step 4, after running the Oracle Universal Installer and the Oracle Workflow Configuration Assistant. If you plan to integrate with Oracle Internet Directory (OID) and Oracle Application Server Single Sign-On as your Oracle Workflow directory service, this step should actually be performed as a pre-installation step. Please ensure that the DBMS_LDAP PL/SQL package is loaded in your database before you run the Oracle Universal Installer and the Oracle Workflow Configuration Assistant.

If you do run the Oracle Universal Installer and the Oracle Workflow Configuration Assistant, specifying LDAP values for OID integration, without having the DBMS_LDAP package installed in your database, you may encounter invalid packages after the Oracle Workflow Configuration Assistant completes. In this case, load the package as described in the Oracle Workflow Installation Notes for Oracle Content Management SDK, and then recompile the Oracle Workflow schema. For instructions, see the Oracle Database Supplied PL/SQL Packages and Types Reference.