Skip Headers
Oracle® BPEL Process Manager Administrator's Guide
10g (10.1.3.1.0)

Part Number B28982-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 Service Configuration

This chapter describes configuration procedures for Oracle BPEL Process Manager services.

This chapter contains the following topics:

2.1 Configuring the Identity Service

The identity service is a thin Web service layer on top of the Oracle Application Server 10g security infrastructure, namely OracleAS JAAS Provider (JAZN), or any custom user repository. The identity service enables authentication and authorization of users and the lookup of user properties, roles, group memberships, and privileges.

The following sections describe how to configure the identity service.

See Also:

Oracle BPEL Process Manager Developer's Guide for details about creating realms, users, and groups; supported identity service providers; and user and group properties

2.1.1 Structure of the Identity Service Configuration File

The identity service configuration is defined in the is_config.xml file. The file must be located in a directory that is included in the CLASSPATH of Oracle BPEL Process Manager. By default, it is stored in

SOA_Oracle_Home\bpel\system\services\config

The XML schema for the is_config.xml file is stored in:

SOA_Oracle_Home\bpel\system\services\schema\is_config.xsd

Figure 2-1 shows the root element configuration, which can contain many configurations.

Figure 2-1 ISConfiguration Root Configuration

Description of wf1.gif follows
Description of the illustration wf1.gif

The identity service configuration file (as defined by is_config.xsd) consists of a root element ISConfiguration, which can have many configurations. Each configuration must be named in the realmName attribute. If several configurations are defined in is_config.xml, one configuration must be marked as default.

The identity service supports the following plug-in types: JAZN provider, third-party LDAP directories, or custom repository plug-ins. Each type defines providers used by the identity service.

You can specify more then one provider for each configuration. A provider is always associated with one of the possible services (identity, authorization, or authentication). By default, the provider uses the identity service, unless otherwise specified in the service attribute. At least one provider associated with the identity service must be defined in the configuration.

2.1.1.1 provider Element

The provider element specifies the providerType, which can be JAZN, LDAP, or CUSTOM, provider name (optional), and any provider-specific properties.

Figure 2-2 shows the provider element configuration.

Figure 2-2 provider Element

Description of wf104.gif follows
Description of the illustration wf104.gif

Note:

If the providerType is JAZN, the value for configuration attribute realmName must match the existing JAZN realm defined in jazn.xml.

For example, in the case of the JAZN XML provider, you must set the providerType attribute to JAZN and specify the value of the userPropertiesFile attribute. See "Configuration for the XML-Based JAZN Provider" for more information about userPropertiesFile.

Similarly, if you use a custom plug-in to the identity service, you must set the providerType attribute to CUSTOM. You then specify the class name for custom identity service plug-in implementation, as follows:

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
      <configuration realmName="jazn.com">
         <provider providerType="JAZN" name="xml" service="Identity">
            <property name="userPropertiesFile" value="users-properties.xml"/>
         </provider>
         <provider providerType="CUSTOM" 
                   name="CustomPlugIn" service="Authentication"
                   class="package.name.CustomAuthenticationService" />   
      </configuration>
   </configurations>
</ISConfiguration>
2.1.1.1.1 Multiple Service Providers

The identity service supports multiple service parameters. In the code example above, one configuration is defined with two service providers. The configuration has one JAZN provider associated with the default identity service and another CUSTOM provider used for the authentication service. Therefore, the custom provider is used for user authentication calls while the JAZN XML provider is used for all authorization and identity service inquires.

See Also:

The "Oracle BPEL Process Manager Workflow Services" chapter of Oracle BPEL Process Manager Developer's Guide for additional details about the authentication, authorization, and identity service providers
2.1.1.1.2 Optional Parameters

The provider can also define the following optional parameters in the configuration file. Most of these parameters apply to JAZN-based or LDAP-based providers, but can also be used by custom providers.

The provider element enables you to specify additional property elements, which can be used by custom plug-ins. An example follows:

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
      <configuration realmName="jazn.com">
          <provider providerType="CUSTOM"
                   name="CustomPlugIn" service="Identity"
                   class="package.name.CustomIdentityService">
            <property name="customProperty" value="customValue" />
      </configuration>
   </configurations>
</ISConfiguration>

In addition, the property element can be defined as part of any other elements (userControls, searchControls, search, and so on) in the configuration file.

2.1.1.2 connection Element

The connection element is used to specify the URL, the admin username (binddn- bind as this Distinguished name), the credential (password) for the LDAP or RDBMS connection used by the identity service, and a Boolean flag (encrypted) to specify that the password is either in plain text or is encrypted. The identity service overwrites the is_config.xml file after reading the configuration and encrypts the user password if it finds it in plain text. Figure 2-3 shows the structure of the connection configuration.

Figure 2-3 connection Configuration

Description of wf105.gif follows
Description of the illustration wf105.gif

The connection can specify connection pool properties by setting the following attributes on the pool element:

  • initsize—initial size of the connection pool

  • maxsize—maximum size of the connection pool

  • prefsize— preferred size of the pool

  • timeout—time after which the connection is released if there is no activity (in seconds)

The LDAP plug-in for the identity service uses the following default values:

  • initsize="2"

  • maxsize="25"

  • prefsize="10"

  • timeout="60"

If you are using a custom identity service plug-in, you can also specify any additional connection-specific properties as name-value pairs.

2.1.1.3 userControls and roleControls Elements

The userControls element is used to define user controls and to restrict the LDAP user search. Figure 2-4 shows the structure of the userControls element.

Figure 2-4 userControls Element

Description of wf106.gif follows
Description of the illustration wf106.gif

The roleControls element is used to define role controls and restrict the LDAP role search. Figure 2-5 shows the structure of the roleControls element.

Figure 2-5 roleControls Element

Description of wf107.gif follows
Description of the illustration wf107.gif

Both userControls and roleControls can have a search element that has the following optional attributes:

  • searchbase—a list of LDAP entries, the distinguished names (DNs) of user or group containers.

  • scope—determines the search level. The value can be onelevel, in which the search descends one level from the supplied DN, or subtree, in which the search descends the hierarchy from the DN to the lowest level in the tree.

  • maxSizeLimit—the maximum number of elements that are fetched from LDAP during a search operation

  • maxTimeLimit—the maximum time to wait to retrieve elements from an LDAP search

By default, the LDAP provider for the identity service uses the following values: maxSizeLimit ="1000", maxTimeLimit ="120" (sec), and scope="subtree".

2.1.2 Configuration for the XML-Based JAZN Provider

The default provider included with Oracle BPEL Process Manager is XML-based JAZN. The JAZN element is defined as follows:

jazn provider="XML" location="./system-jazn-data.xml"/

This element is in:

SOA_Oracle_Home\j2ee\home\config\jazn.xml

The identity service configuration file must specify the userPropertiesFile property and provide the value of the file name where all user properties are stored:

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
      <configuration realmName="jazn.com">
         <provider providerType="JAZN" name="xml" service="Identity">
            <property name="userPropertiesFile" value="users-properties.xml"/>
         </provider>
   </configurations>
</ISConfiguration>

Note that the users-properties.xml file stores all extended user's properties. This is not required for JAZN authorization or authentication. However, the BPEL identity service requires this file to get contact details and the organizational hierarchy for users. If this file is not created, the following can occur:

  • Certain workflow functionality such as notifications, manager views, or task escalation may not work.

  • Workflow rule creation is disabled for all users who do not have the BPMWorkflowAdmin role.

  • Workflow rule definitions for groups may not work.

By default, the identity service looks for users-properties.xml in the Oracle BPEL Process Manager classpath. Oracle Universal Installer stores the default users-properties.xml in

SOA_Oracle_Home\bpel\system\services\config

The XML schema for users-properties.xml is stored in

SOA_Oracle_Home\bpel\system\services\schema\IdentityService.xsd

Note:

JAZN realms, users, and roles and groups can be created with the JAZN Admintool. To add a user to a specified realm, issue the following command:

java -jar jazn.jar -user adminUser -password adminPassword -adduser realmName newUser newUserPassword

See Also:

  • JAZN documentation for information on how to configure the middle tier to use the XML-based JAZN provider and how to use the JAZN Admintool

  • The "Oracle BPEL Process Manager Workflow Services" chapter of the Oracle BPEL Process Manager Developer's Guide for additional information on creating identity service users and roles

2.1.3 Configuring Identity Service 10.1.3.1.0 with 10.1.2 Oracle Internet Directory

This section describes how to configure the identity service of Oracle BPEL Process Manager 10.1.3.1.0 with Oracle Internet Directory 10.1.2.

2.1.3.1 Task 1: Perform Preconfiguration Procedures

Note:

If you are using Oracle Internet Directory in an environment with multiple OC4J instances (for example, SOA_Oracle_Home/j2ee/home and SOA_Oracle_Home/j2ee/oc4j_soa), you must manually copy the relevant <jazn> element configuration section from the jazn.xml file of the home instance to the jazn.xml file of all other instances. See the section "Considering Multiple OC4J Instances when Associating Oracle Internet Directory" in the Oracle Identity Management chapter of the Oracle Containers for J2EE Security Guide for specific instructions.

Perform the following procedures to ensure that the Oracle Application Server instance is associated with Oracle Internet Directory.

  1. Log in to the Oracle Enterprise Manager 10g Application Server Control Console:

    http://hostname:port/em
    
    

    where hostname is name of the host on which Oracle BPEL Process Manager is installed and port is the Oracle HTTP Server port.

    The Cluster Topology page appears.

  2. Click the OC4J instance name in the Members section.

    The OC4J: oc4j_name page appears.

  3. Click the Administration tab.

  4. Go to the Security section in the Task Name column.

  5. Click the icon in the Go to Task column for Identity Management.

    Description of is_em1.gif follows
    Description of the illustration is_em1.gif

    If Oracle Internet Directory is configured with this Oracle Application Server instance, details appear on this page.

  6. See the following section based on whether Oracle Internet Directory is associated with an instance.

    See Also:

    Oracle Application Server Administrator's Guide for details on using Oracle Enterprise Manager 10g Application Server Control Console
2.1.3.1.1 Oracle Internet Directory is Associated with an Oracle Application Server Instance
  1. Review the details that appear on this page to ensure that this is the Oracle Internet Directory instance you want to use.

  2. Return to the Administration tab of the OC4J: oc4j_name page you accessed in Step 3.

  3. Go to the Security section.

  4. Click the icon in the Go to Task column for Security Providers.

    Description of is_em2.gif follows
    Description of the illustration is_em2.gif

  5. Go to the Application Name section.

    The orabpel (for Oracle BPEL Process Manager) and hw_services (for human workflow) applications appear.

    Description of is_em3.gif follows
    Description of the illustration is_em3.gif

  6. Click the Edit column for orabpel.

    The Security Provider page appears.

  7. Click Change Security Provider.

    The Change Security Provider page appears.

  8. Select Oracle Identity Management Security Provider from the Security Provider Type list.

  9. Click OK.

  10. Repeat Steps 6 through 9 for hw_services (human workflow).

2.1.3.1.2 Oracle Internet Directory is Not Associated with an Oracle Application Server Instance
  1. Click Configure to create a new association or Change to associate a different Oracle Internet Directory with the Oracle Application Server instance.

  2. Provide appropriate responses to the questions that appear. If you want to use SSL, provide the specific SSL port number of your Oracle Internet Directory instance. If not, specify the non-SSL port of your Oracle Internet Directory instance.

  3. Click Next.

  4. If you want to associate Oracle Enterprise Manager 10g Application Server Control Console with Oracle Internet Directory, provide appropriate details on this page.

  5. Click Next.

  6. Click orabpel and hw_services to use Oracle Internet Directory as the security provider.

  7. Click Configure.

2.1.3.2 Task 2: Perform Configuration Procedures

This section describes how to seed users into Oracle Internet Directory, configure the identity service, and grant privileges to BPM roles.

Note:

The path name delimiter used in this example, /, is for UNIX. If you are using Windows, assume that the path name delimiter is \.
  1. Ensure that the ORACLE_HOME environment variable is set to the root directory of the Oracle Application Server instance being configured.

  2. Open an operating system command prompt and go to the following directory, which includes the configuration scripts:

    SOA_Oracle_Home/bpel/system/services/install/ant-tasks
    
    
  3. Execute either configure_oid.bat (for Windows operating systems) or configure_oid.sh (for Unix operating system) with the required parameters. Oracle recommends you use the bash shell to execute the script on Linux. For example, to run this script on Linux:

    sh ./configure_oid.sh oid_admin_user oid_admin_passwd
    oid_nonssl_port ssl_enabled oid_realm_name seedAllUsers | seedRequiredUsers
    oc4j_admin_user oc4j_admin_passwd oc4j_container_name
    
    

    For example:

    sh ./configure_oid.sh orcladmin welcome 389 false us seedAllUsers oc4jadmin
    welcome1 oc4j_soa
    
    

    The execution of this command internally modifies the SOA_Oracle_Home/bpel/system/services/config/is_config.xml file. The file contents look as follows:

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <ISConfiguration
    xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
            <configurations>
                <configuration realmName="us" displayName="us Realm"> 
                  <provider providerType="JAZN" name="OID"> 
                       <connection url="ldap://my.oid.com:389"
                        binddn="cn=orcladmin" password="passwd" encrypted="false"/>
                  </provider>
                </configuration>
            </configurations>
    </ISConfiguration>
    
    

    The command also modifies the J2EE_Home/application-deployments/hw_services/orion-application.xml and J2EE_Home/application-deployments/orabpel/orion-application.xml files and adds the Oracle Internet Directory details to the descriptor.

    where J2EE_Home is:

    • SOA_Oracle_Home/j2ee/OC4J_Instance_Name for Oracle Application Server SOA installations.

    • SOA_Oracle_Home/bpel/system/appserver/oc4j/j2ee/OC4J_Instance_Name for Oracle BPEL Process Manager for OracleAS Middle Tier installations.

    The file contents look as follows:

    <?xml version = '1.0'?>
    <orion-application 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation=
            "http://xmlns.oracle.com/oracleas/schema/orion-application-10_0.xsd"
          deployment-version="10.1.3.1.0" 
          default-data-source="jdbc/OracleDS"
          component-classification="internal-BPEL" 
          schema-major-version="10"
          schema-minor-version="0">
       . . .
       . . .
       . . .
       <jazn provider="LDAP" jaas-mode="doAsPrivileged"/>
       . . .
       . . .
       . . .</orion-application>
    
    

    The configure_oid script also grants required privileges to the BPMSystemAdmin role and the BPMDefaultDomainAdmin role.

  4. If you encounter operating system-specific problems, proceed as follows:

    1. Ensure that OC4J_Home points to the correct directory. This is typically SOA_Oracle_Home/j2ee/home for an Oracle BPEL Process Manager for OracleAS Middle Tier install and SOA_Oracle_Home/bpel/ system/appserver/oc4j/j2ee/home for an Oracle BPEL Process Manager for Developers install.

    2. Ensure that Ant_Home points to the correct directory. This is typically SOA_Oracle_Home/ant for an Oracle BPEL Process Manager for OracleAS Middle Tier installation and SOA_Oracle_Home/bpel/ system/appserver/oc4j/ant for an Oracle BPEL Process Manager for Developer's installation.

    3. Ensure that Java_Home points to the correct directory. This is typically SOA_Oracle_Home/jdk.

    4. Ensure that your PATH variable points to Ant_Home/bin and Java_Home/bin.

    5. Verify that you correctly specified all parameter values in Step 3.

    6. Execute the following command (entered on a single, wrapping line):

      ant -f oid-config.xml -Doid.admin.user=oid_admin_user_name
      -Doid.admin.pwd=oid_admin_password 
      -Doid.nonssl.port=non_ssl_port
      -Dssl.enabled=is_ssl_enabled
      -Doid.realm=oid_realm_name
      -Doid.seed=seedAllUsers | seedRequiredUsers
      -Doc4j.admin.user=oc4j_admin_user_name
      -Doc4j.admin.pwd=oc4j_admin_password
      -Doc4j.container=oc4j_container_name
      
      

      For example:

      ant -f oid-config.xml -Doid.admin.user=orcladmmin
      -Doid.admin.pwd=welcome1 
      -Doid.nonssl.port=389 -Dssl.enabled=false
      -Doid.realm=us -Doid.seed=seedAllUsers
      -Doc4j.admin.user=oc4jadmin -Doc4j.admin.pwd=welcome1
      –Doc4j.container=oc4j_soa
      
      

      Note:

      The username and realm are not specified as cn=orcladmin or dc=us,dc=oracle,dc=com, respectively. Instead use orcladmin and us.

      The parameters you specify are defined as follows:

      Parameter Value
      oid.admin.user A user with administrative privileges over your Oracle Internet Directory instance. This is typically orcladmin.
      oid.admin.pwd The password of the user specified for the administrative user of Oracle Internet Directory.
      oid.nonssl.port The non-SSL port of the Oracle Internet Directory instance. The Oracle Internet Directory instance must be running on both the SSL and non-SSL ports.
      ssl.enabled Set to either of the following values:
      • true — Runs the identity service with SSL enabled. Note that JAZN must also be configured with SSL enabled.

      • false — Does not run the identity service with SSL enabled.

      oid.realm The realm under which you want to operate in Oracle Internet Directory.
      oid.seed Set either of the following values:
      • seedAllUsers — Seeds the demo users into Oracle Internet Directory

      • seedRequiredUsers — Seeds only those users required for proper functioning

      oc4j.admin.user A user with administrative privileges over your Oracle Application Server OC4J instance. This is typically oc4jadmin.
      oc4j.admin.pwd The password of the user specified for the administrative user of OC4J.
      oc4j.container The container name where the hw_services (for human workflow) and orabpel (for Oracle BPEL Process Manager) applications are deployed. To locate these names, go to SOA_Oracle_Home/j2ee and look for the following directories:
      • SOA_Oracle_Home/j2ee/oc4j_home/application-deployments/orabpel

      • SOA_Oracle_Home/j2ee/oc4j_home/application-deployments/hw_services


2.1.3.3 Step 3: Test the Oracle Internet Directory Configuration

There are multiple ways to test the Oracle Internet Directory configuration:

  • Use the IdentityService servlet to look up users and roles by going to http://localhost:9700/integration/services/IdentityService/identity?operation=lookupUser.

    You can test with the bpeladmin user name to see if the user is seeded correctly.

  • Go to the Oracle BPEL Worklist Application at http://localhost:9700/integration/worklistapp/Login and enter bpeladmin as the user name and welcome1 as the password to see if you can connect.

2.1.3.4 Task 4: Configure the Middle Tier to use the LDAP-based JAZN provider with Secure Socket Layer (SSL)

You must use NULL authentication when communicating with Oracle Internet Directory. NULL authentication means that data is encrypted with the Anonymous Diffie-Hellman cipher suite, but no certificates are used for authentication.

To use NULL authentication, add a <property> element to the <jazn> element in jazn.xml and to the <connection> element in is_config.xml to specify a protocol. You do not need to specify a wallet location or password, because NULL authentication does not use certificates.

Add the following property element to jazn.xml (shown in bold):

<jazn provider="LDAP" location="ldap://example.com:636" default-realm="us">
    <property name="ldap.user" value="cn=orcladmin"/>
    <property name="ldap.password" value="!welcome1"/>
    <property name="ldap.protocol" value="ssl"/>
</jazn>

See Also:

Oracle Containers for J2EE Security Guide for additional details about JAZN configuration

2.1.3.5 Troubleshooting

If you cannot log in to Oracle BPEL Worklist Application or Oracle BPEL Control, ensure that the steps described above have been executed correctly. If the problem persists, follow these steps:

  1. If you think the scripts did not complete successfully, perform the configuration steps again.

  2. Go to SOA_Oracle_Home/j2ee/home/application-deployments/hw_services.

  3. Open orion-application.xml in a text editor.

  4. Verify that the jaas-mode attribute for the JAZN provider configuration is set to doAsPrivileged. For example:

    <jazn provider="LDAP" jaas-mode="doAsPrivileged"/>
    
    
  5. Repeat these steps for SOA_Oracle_Home/j2ee/home/application-deployments/orabpel/orion-application.xml.

2.1.3.6 Reverting from Oracle Internet Directory to the XML-Based JAZN Provider

Follow these procedures if you need to revert from Oracle Internet Directory back to XML-based JAZN as the identity service provider.

  1. Log in to the Oracle Enterprise Manager 10g Application Server Control Console:

    http://hostname:port/em
    
    

    where hostname is the name of the host on which Oracle BPEL Process Manager is installed and port is the Oracle HTTP Server port.

    The Cluster Topology page appears.

  2. Click the OC4J instance name in the Members section.

    The OC4J: oc4j_name page appears.

  3. Click the Administration tab.

  4. Go to the Security section in the Task Name column.

  5. Click the icon in the Go to Task column for Security Providers.

  6. Go to the Application Name section.

    The orabpel (for Oracle BPEL Process Manager) and hw_services (for human workflow) applications appear.

  7. Click the Edit column for orabpel.

    The Security Provider page appears.

  8. Click Change Security Provider.

    The Change Security Provider page appears.

  9. Select File Based Security Provider from the Security Provider Type list

  10. Click OK.

  11. Repeat Steps 7 through 10 for hw_services.

  12. Log out of Oracle Enterprise Manager 10g Application Server Control Console.

  13. Go to the SOA_Oracle_home/bpel/system/services/config directory.

  14. Delete is_config.xml.

  15. Rename is_config.xml.BPM to is_config.xml.

  16. If you configured Oracle Internet Directory to use SSL in "Task 4: Configure the Middle Tier to use the LDAP-based JAZN provider with Secure Socket Layer (SSL)", change the following line in the jazn.xml file.

    <property name="ldap.protocol" value="ssl"/>
    
    

    to

    <property name="ldap.protocol" value="no-ssl"/>
    
    
  17. Restart the Oracle Application Server instance for the changes to take affect.

    SOA_Oracle_Home/opmn/bin> opmnctl stopall
    SOA_Oracle_Home/opmn/bin> opmnctl startall
    

2.1.4 Configuration for a Third-Party LDAP Server

Note the following considerations when using a third-party LDAP server. The configuration for Active Directory is slightly different. These differences are also described.

Note:

This section only describes Active Directory configuration on Windows 2003. This is because Windows 2000 does not permit nested security groups.
  1. The third-party LDAP servers must be configured to use the following standard objectClasses:

    For Active Directory For Other Third-Party LDAP Servers
    top top
    person person
    organizationalPerson organizationalPerson
    user inetOrgPerson
    group groupOfUniqueNames

    LDAP servers usually predefine the list of searchable attributes based on the cn, firstname, lastname, and email attributes. You can customize the attributes that can be searchable. The user manager attribute from inetOrgPerson objectClass should be searchable to allow workflow escalation. See the documentation for the third-party LDAP server you are using for how to set up the searchable attribute.

    The recommended searchable attribute list is cn, sn, givenName, uid, manager, title, mail, and telephoneNumber.

  2. When you seed Oracle BPEL Process Manager users and roles into the LDAP server, the process assumes that the users' and groups' container is created in LDAP. To create system and optionally demo ldif files, open the following template files in:

    SOA_Oracle_Home\bpel\system\services\config\ldap
    
    
    For Active Directory For Other Third-Party LDAP Servers
    system-winServer2003-ActDir.sbs system-ldap.sbs
    demo-winServer2003-ActDir.sbs demo-ldap.sbs
    demo-roleGrants-winServer2003-ActDir.sbs

    Replace the substitution variables with the appropriate values, as shown in the following examples. The actual values to enter depend upon your domain:

    LDAP Server Substitution Variable Replace With Value
    Active Directory %s_UserContainerDN% cn=Users,dc=us,dc=oracle,dc=com

    %s_GroupContainerDN% cn=Users,dc=us,dc=oracle,dc=com
    Other Third-Party LDAP Servers %s_UserCommonNamingAttribute% cn

    %s_UserContainerDN% ou=People,dc=ldapus,dc=acmeoracle,dc=com

    %s_GroupContainerDN% ou=Groups,dc=usldap,dc=acmeoracle,dc=com

    where:

    • %s_UserContainerDN% with a DN, value of the entry under which all users are supposed to be added. The users container with:

      • dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for Active Directory

      • dn: ou=People,dc=usldap,dc=acmeoracle,dc=com is used in this example for other third-party LDAP servers

    • %s_GroupContainerDN% with a DN value of the entry under which all public groups are supposed to be added. The groups' container with:

      • dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for Active Directory

      • dn: ou=Groups,dc=ldapus,dc=acmeoracle,dc=com is used in this example for other third-party LDAP servers

    • %s_UserCommonNamingAttribute% with the value used to construct the user's DN. In this example for other third-party LDAP servers, the cn value is used. %s_UserCommonNamingAttribute% and value are not applicable to Active Directory.

    Perform the following steps based on your type of third party LDAP server:

    • For Active Directory:

      Run the following commands at the DOS command prompt on Windows 2003:

      ldifde.exe -i -k -f system-winServer2003-ActDir.ldif
      ldifde.exe -i -k -f demo-winServer2003-ActDir.ldif
      ldifde.exe -i -k -f demo-roleGrants-winServer2003-ActDir.ldif
      
      

      See the following Microsoft Active Directory Documentation for details about all bulk import options for Active Directory's ldifde.exe:

      http://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies
      /directory/activedirectory/stepbystep/adbulk.mspx#ECAA
      
      

      The Windows system administrator must set passwords for all seeded users; otherwise, worklist application authentication does not work for those users.

    • For other third-party LDAP servers:

      Store changes in the system-ldap.ldif and demo-ldap.ldif files. Then load the system-ldap.ldif file to the LDAP server by using the ldapadd utility. Optionally, load demo-ldap.ldif with the ldapmodify utility.

      For example:

      $ldapadd -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f system-oid.ldif
      $ldapmodify -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f demo-oid.ldif
      
      

      See the documentation for the third-party LDAP server you are using for information about the ldapadd and ldapmodify commands.

  3. The identity service third-party LDAP provider must specify connection, userControls, and roleControls elements in the identity service configuration file.

    Identity service third-party LDAP provider implementation defines a set of user search properties that must be configured:

    • nameattribute—the name of the LDAP attribute that uniquely identifies the name of the user. In Sun Directory Server, it is uid; in Active Directory, it is user.

    • objectClass—the LDAP schema object class used to represent a user. In Sun Directory Server, it is inetOrgPerson.

    And a set of role search properties:

    • nameattribute—the name of the LDAP attribute that uniquely identifies the name of the role. In Sun Directory Server, it is uniqueMember; in Active Directory, it is member.

    • objectclass—the LDAP schema object class that is used to represent a group. In Sun Directory Server, it is groupOfUniqueNames. In Active Directory, it is group.

    • membershipsearchscope—specifies how deep in the LDAP directory tree to search for role membership. Supported values: onelevel or subtree.

    • memberattribute—The attribute of a static LDAP group object specifying the distinguished names (DNs) of the members of the group. In Sun Directory Server, it is uniqueMember; in Active Directory, it is member.

Both userControls and roleControl must define a search element with the searchbase attribute.

The searchbase attribute of the userControls search element is a space-separated list of DNs in the LDAP directory that contains users; for example, cn=users,dc=us,dc=oracle.com,dc=com.

The searchbase attribute of the roleControls search element is a space-separated list of DNs in the LDAP directory that contains roles; for example, cn=Groups,dc=us,dc=oracle,dc=com.

Examples of two realm LDAP server configurations are shown below:

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
    <configuration realmName="us" default="true">
         <provider providerType="LDAP" name="iPlanet" service="Identity">
            <connection url="ldap://host:port"
         binddn="uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot" 
         password="welcome1" encrypted="false">
               <pool initsize="2" maxsize="25" prefsize="10" timeout="60"/>
            </connection>
            <userControls>
               <property name="nameattribute" value="uid"/>
               <property name="objectclass" value="inetOrgPerson"/>
               <search searchbase="ou=People, dc=us,dc=oracle,dc=com "
                       scope="obelevel" maxSizeLimit="1000" maxTimeLimit="120"/>
            </userControls>
            <roleControls>
               <property name="nameattribute" value="cn"/>
               <property name="objectclass" value="groupOfUniqueNames"/>
               <property name="membershipsearchscope" value="onelevel"/>
               <property name="memberattribute" value="uniquemember"/>
               <search searchbase="ou=Groups,dc=us,dc=oracle,dc=com"
                       scope="onelevel" maxSizeLimit="1000" maxTimeLimit="120"/>
            </roleControls>
         </provider>
      </configuration>
      <configuration realmName="idc">
           <provider providerType="LDAP" name="openLDAP"> 
              <connection url="ldap://host:port"
                 binddn="cn=Manager,dc=oracle,dc=com" 
                 password="welcome1" encrypted="true">
                <pool initsize="2" maxsize="25" prefsize="10" timeout="300000"/>
              </connection>
              <userControls>
                 <property name="nameattribute" value="uid"/>
                 <property name="objectclass" value="inetOrgPerson"/>
                 <search searchbase="ou=People,dc=idc,dc=oracle,dc=com"
                         scope="onelevel" maxSizeLimit="1000"
                         maxTimeLimit="120000"/>
              </userControls>
              <roleControls>
                 <property name="nameattribute" value="cn"/>
                 <property name="objectclass" value="groupOfUniqueNames"/>
                 <property name="membershipsearchscope" value="onelevel"/>
                 <property name="memberattribute" value="uniquemember"/>
                 <search searchbase="ou=Groups,dc=idc,dc=oracle,dc=com"
                         scope="onelevel" maxSizeLimit="1000"
                         maxTimeLimit="120000"/>
              </roleControls>
           </provider>      
        </configuration>
     </configurations>
</ISConfiguration>

An example for Microsoft Active Directory 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="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>

2.1.5 Configuration for Custom Identity Repository Plug-ins

The following example shows how to use configuration properties to configure custom plug-ins. In this example, the CustomIdentityService class is used to demonstrate custom repository plug-ins. This class implements the BPMIdentityService interface.

<?xml version =3D '1.0' encoding =3D 'UTF-8'?>
<ISConfiguration=xmlns=3D"http://www.oracle.com/pcbpel/identityservice/isconfig">
   <configurations>
      <configuration realmName=3D"default">
        <provider providerType=3D"CUSTOM" name=3D"DBProvider" class=3D =
         "is.custom.plugin.CustomIdentityService">
        <connection url=3D"jdbc:polite4@host:1531:orabpel" >
            <property name=3D"driver" =value=3D"oracle.lite.poljdbc.POLJDBCDriver"/>
            <property name=3D"user" value=3D"system"/>
            <property name=3D"password" value=3D"manager"/>
         </connection>
        </provider>
      </configuration>
   </configurations>
</ISConfiguration>

In the proceeding example, the configuration defines a provider named DBProvider that is implemented by the is.custom.plugin.CustomIdentityService class. The provider uses custom connection properties for driver, user, and password.

In addition to the existing provider properties, you can define custom property elements that can be added to provider, connection, userControls, roleControls, and search elements in the configuration file to extend provider definitions.

2.1.6 Setting Up Group Ownership

The workflow rules for groups can be created and updated by users who are either the group owner or have the BPMWorkflowAdmin role. This user can own the group directly or indirectly. The user owns the group or role indirectly if they are a grantee for another role or group that owns the role or group.

2.1.6.1 Defining Group Ownership for JAZN XML-Based Providers

Group ownership is an extended role property that is stored in the SOA_Oracle_Home\bpel\system\services\config\users-properties.xml file in the <owners> element of the groupObject.

An owner can be either a user, application role, or group. The <owners> element value can have several owners separated by commas. For example:

<groupObject>
        <name>LoanAgentGroup</name>
        <email>user1@dlsun4254.us.oracle.com</email>
        <owners>fkafka, jcooper, BPMAnalyst</owners>
</groupObject>

2.1.6.2 Defining Group Ownership for JAZN Oracle Internet Directory-Based and LDAP-Based Providers

Group ownership is defined through the owner attribute. To create an owner of the group in Oracle Internet Directory, you must use Oracle Delegated Administration Services. For third-party LDAP servers, use the server's tools or the ldapmodify utility to set values to the group's owner attribute. The attribute name for owners can be overwritten with a property element of roleControls in the is_config.xml identity service configuration file:

<property name="roleOwnerAtribute"
  value="customOnwerAttribute" />

2.2 Configuring the Notification Services

The notification service in Oracle BPEL Process Manager enables you to send notifications from a BPEL process using a variety of channels. Oracle BPEL Process Manager can deliver these notifications by e-mail, voice message, fax, pager, or short message service (SMS). In addition to configuring notification channels in Oracle JDeveloper, you must also perform additional configuration procedures.

This section contains the following topics:

See Also:

Oracle BPEL Process Manager Developer's Guide for details about configuring notification channels in Oracle JDeveloper

2.2.1 Configuring the E-mail Server

The file ns_emails.xml in the directory SOA_Oracle_Home\bpel\system\services\config contains the configuration for e-mail accounts. Each EmailAccount element sets the configuration of a specific e-mail account. The name attribute in the EmailAccount element is the name of the account.

A default e-mail account is specified in the e-mail configuration file. This account is used when there is no account specified to send an e-mail notification. This account is also used to send task-related notifications. A default e-mail account must always be specified in the configuration file.

The EmailAccount element contains the OutgoingServerSettings and IncomingServerSettings attributes. For actionable notifications in a workflow, both IncomingServerSettings and OutgoingServerSettings are required.

Table 2-1 describes the XML elements for the e-mail notification configuration stored in the ns_emails.xml file.

Table 2-1 XML Elements for the E-mail Notification Configuration File

Name Description
EmailAccount/Name
Name of the account. This can be any name, but must be unique within this server.
EmailAccount/GeneralSettings/FromName
Name of the From e-mail address
EmailAccount/GeneralSettings/FromAddress
E-mail address for the From e-mail address
EmailAccount/OutgoingServerSettings/SMTPHost
Name of the outgoing SMTP server
EmailAccount/OutgoingServerSettings/SMTPPort
Port of the outgoing SMTP server
EmailAccount/OutgoingServerSettings/AuthenticationRequired Optional element to specify that authentication is required for the SMTP server
EmailAccount/OutgoingServerSettings/UserName Optional element to specify the user name for the SMTP account
EmailAccount/OutgoingServerSettings/Password Optional element to specify the password for the SMTP account
EmailAccount/OutgoingServerSettings/Password[encrypted] Encrypted attribute of the password. It is true if the password is encrypted and false if it is not. You generally set this to false when you first enter the password. The server automatically encrypts the password the first time it reads the configuration file and sets the attribute to true.
EmailAccount/IncomingServerSettings/Server
Name of the incoming e-mail server
EmailAccount/IncomingServerSettings/Port
Port of the incoming e-mail server
EmailAccount/IncomingServerSettings/UserName
User ID of the e-mail address
EmailAccount/IncomingServerSettings/Password
User password
EmailAccount/IncomingServerSettings/Password[encrypted
Encrypted attribute of the password. It is true if the password is encrypted and false if it is not. Generally, you should set this to false when you first enter the password. The server automatically encrypts the password the first time it reads the configuration file and sets the attribute to true.
EmailAccount/IncomingServerSettings/UseSSL
Secure sockets layer (SSL) attribute. It is true if the incoming server requires SSL and false if it does not.
EmailAccount/IncomingServerSettings/Folder
Name of the folder from which to read the incoming messages
EmailAccount/IncomingServerSettings/PollingFrequency
Polling interval for reading messages from the incoming messages folder
EmailMimeCharset MIME charset to be used to encode the e-mail from the address and the subject
NotificationMode The notification mode of the notification service. It is expected that the notification mode is set to either ALL or EMAIL after configuring the notification service for e-mail and other channels. By default, this value is set to NONE and therefore no notifications are sent. The possible values for this attribute are:
  • ALL – the e-mail, SMS, voice, fax, and pager channels are configured and notification is sent through any channel.

  • EMAIL – Only the e-mail channel is configured for sending notification messages.

  • NONE – No channel is configured for sending notification messages. This is the default setting.


2.2.1.1 Example ns_emails.xml File

<EmailAccounts 
xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService" 
               EmailMimeCharset="" 
               NotificationMode="NONE">
   <EmailAccount>
      <Name>Default</Name>
      <GeneralSettings>
         <FromName>Oracle BPM</FromName>
         <FromAddress>accountId@yourdomain.com</FromAddress>
      </GeneralSettings>
      <OutgoingServerSettings>
         <SMTPHost>yourdomain.com</SMTPHost>
         <SMTPPort>25</SMTPPort>
          <AuthenticationRequired>true</AuthenticationRequired>
          <UserName>userId</UserName>
          <Password encrypted="false"
             xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
             password</Password>      </OutgoingServerSettings> 
      <IncomingServerSettings>
         <Server>yourdomain.com</Server>
         <Port>110</Port>
         <Protocol>pop3</Protocol>
         <UserName>accountId</UserName>
         <Password ns0:encrypted="false"
            xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
            password</Password>
         <UseSSL>false</UseSSL>
         <Folder>Inbox</Folder>
         <PollingFrequency>1</PollingFrequency>
         <PostReadOperation>
            <MarkAsRead/>
         </PostReadOperation>
      </IncomingServerSettings>
   </EmailAccount>
</EmailAccounts>

2.2.2 Configuring the Wireless Provider for Voice

The configuration for the wireless service provider is stored in an XML file, ns_iaswconfig.xml, which is in

SOA_Oracle_Home\bpel\system\services\config

Table 2-2 describes the XML elements for the voice notification configuration stored in ns_iaswconfig.xml on the SOA_Oracle_Home server.

Table 2-2 XML Elements for the Voice Notification Configuration File

Name Description
/IASWConfiguration/SoapURL
URL of the wireless service provider
/IASWConfiguration/UserName
Name of the user account with the wireless service provider
/IASWConfiguration/Password
User password
/IASWConfiguration/Password[encrypted
Encrypted attribute of the password. It is true if the password is encrypted and false if it is not. Generally, you should set this to false when you first enter the password. The server automatically encrypts the password the first time it reads the configuration file and sets the attribute to true.
/IASWConfiguration/ProxyHost
Name of the proxy server
/IASWConfiguration/ProxyPort
Port number of the proxy server

Note:

The username and password are intentionally left blank at installation. If a username or password is not specified, the wireless server allows up to 50 notifications from a specific IP address. After 50 notifications, you must get a paid account from

http://messenger.oracle.com

You then specify the appropriate username and password in the configuration file, ns_iaswconfig.xml, or by using Oracle Enterprise Manager 10g Application Server Control Console.

2.2.2.1 Example ns_iaswconfig.xml File

<?xml version = '1.0' encoding = 'UTF-8'?>
<!--This XML file stores the details of the IAS Wireless Notification Service-->
<IASWConfiguration xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
  <!-- URL to the SOAP Service -->
  <SoapURL>http://messenger.oracle.com/xms/webservices</SoapURL>

  <!-- UserName - this username should exist in iAS Wireless schema -->
  <UserName>username</UserName>

  <Password ns0:encrypted="false"
xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">password
</Password>
</IASWConfiguration>

2.2.3 Configuring the Wireless Provider for SMS

As with the voice notification channel, the configuration for the wireless service provider for SMS is stored in the XML file ns_iaswconfig.xml, which is in

SOA_Oracle_Home\bpel\system\services\config

See "Configuring the Wireless Provider for Voice" to configure a wireless service provider for SMS.

2.2.4 Configuring the Wireless Provider for Fax

As with the voice notification channel, the configuration for the wireless service provider for fax is stored in the XML file ns_iaswconfig.xml, which is in

SOA_Oracle_Home\bpel\system\services\config

See "Configuring the Wireless Provider for Voice" to configure a wireless service provider for fax. Note that you cannot use the Oracle Enterprise Manager 10g Application Server Control Console to configure a fax provider for this release.

2.2.4.1 Configuring the Fax Cover Page

To add cover pages for a fax, you must edit the SOA_Oracle_Home\bpel\system\services\config\ns_faxcoverpages.xml. Use the cover page name to specify the cover page in the fax message.

<FaxCoverPages xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
  <FaxCoverPage>
     <Name>legal</Name>
     <MimeType>application/pdf</MimeType>
<FileLocation>C:\orabpel\bpel\runtime\config\faxcoverpages\003288.pdf</FileLocation>
  </FaxCoverPage>
</FaxCoverPages> 

2.2.5 Configuring the Wireless Provider for Pager

As with the voice notification channel, the configuration for the wireless service provider for pager is stored in the XML file ns_iaswconfig.xml, which is in

SOA_Oracle_Home\bpel\system\services\config

See "Configuring the Wireless Provider for Voice" to configure a wireless service provider for pager. Note that you cannot use the Oracle Enterprise Manager 10g Application Server Control Console to configure a pager provider for this release.

2.2.6 Configuring the Pluggable Notification Service

Custom notification service implementations can be plugged in and used instead of the default notification service providers. You can plug in a custom notification service for all channels or selectively for specific channels. For example, the notification service provides the ability to plug in an existing SMS implementation instead of the default SMS notification service.

2.2.6.1 Pluggable Notification Service Implementation

To plug in a notification service, you implement the oracle.tip.pc.services.notification.ICustomNotificationService interface. This interface has methods for the following channels:

  • E-mail

  • Voice

  • Fax

  • SMS

  • Instant messaging (IM)

  • Pager

The plugged-in notification service can override the default providers for one or more channels. When the custom notification service is overriding the default implementation for a subset of channels, the methods corresponding to the other channels (channels that are not overridden) are not called by the notification service. Those methods can just return null. Alternatively, the implementation can extend the abstract class oracle.tip.pc.services.notification.AbstractCustomNotificationServiceImpl, which provides empty implementations for each of the channels. In that case, the implementation can just extend the methods for the interested channels.

2.2.6.2 Pluggable Notification Service Registration

Once the implementation is available, you register it in the SOA_Oracle_Home\system\services\config\ns_iaswconfig.xml file. The section in ns_iaswconfig.xml to set is shown below. By default, all elements are empty.

<!-- Specify any custom implementation for sending notification via Voice, Fax,
 Pager, SMS or IM channels. 
       'All' refers to an implementation for all of the above specified channels.
  -->
  <CustomNotificationServices>
    <All/>
    <Email/>
    <Voice/>
    <Fax/>
    <Pager/>
    <SMS/>
    <IM/>
  </CustomNotificationServices>

If you are overriding the default implementation for all channels, set the All element with the complete class name of your implementation:

<CustomNotificationServices>
    <All>com.xyz.test.NotificationService</All>
    <Email/>
    <Voice/>
    <Fax/>
    <Pager/>
    <SMS/>
    <IM/>
  </CustomNotificationServices>

If you are overriding the default implementation for only the e-mail channel, set the Email element with the complete class name of your implementation:

<CustomNotificationServices>
    <All/>
    <Email>com.xyz.test.NotificationService</Email>
    <Voice/>
    <Fax/>
    <Pager/>
    <SMS/>
    <IM/>
  </CustomNotificationServices>

The override for other channels is configured the same way as the e-mail channel.

Note that the implementation and its dependent classes must be available in the classpath of Oracle BPEL Server.

2.3 Configuring the Workflow Service

The configuration for all workflow services is performed in the SOA_Oracle_Home\bpel\system\services\config\wf_config.xml file.

<workflowConfigurations
  xmlns="http://xmlns.oracle.com/pcbpel/humanworkflow/configurations"
  xmlns:user="http://xmlns.oracle.com/bpel/workflow/userMetadata">
  <taskAutoReleaseConfigurations>
     <taskAutoRelease priority="1" default="P1D" percentageOfExpiration="30"/>
     <taskAutoRelease priority="2" default="P2D" percentageOfExpiration="40"/>
     <taskAutoRelease priority="3" default="P3D" percentageOfExpiration="50"/>
     <taskAutoRelease priority="4" default="P4D" percentageOfExpiration="60"/>
     <taskAutoRelease priority="5" default="P5D" percentageOfExpiration="70"/>
  </taskAutoReleaseConfigurations>
  <worklistApplicationURL>http://mlkenned-pc.us.oracle.com:8888/integration/ 
      worklistapp/TaskDetails?taskId=PC_HW_TASK_ID_TAG</worklistApplicationURL>
  <actionableEmailAccountName/>
  <pushbackAssignee>INITIAL_ASSIGNEES</pushbackAssignee>
  <assigneeDelimiter><![CDATA[,]]></assigneeDelimiter>
  <shortHistoryActions>
    <action>ACQUIRE</action>
    <action>INFO_REQUEST</action>
    <action>INFO_SUBMIT</action>
    <action>RELEASE</action>
  </shortHistoryActions>
  <workflowServiceSessionTimeoutInMinutes>60</workflowServiceSessionTimeout
     InMinute>
  <user:ruleRepositoryInfo>     
    <user:ruleEngine>ORACLE</user:ruleEngine>
    <user:repositoryLocation>WFRepository</user:repositoryLocation>
    <user:dictionaryName>WFDictionary</user:dictionaryName>
    <user:reposProperty name="reposType">jar</user:reposProperty>
  </user:ruleRepositoryInfo>
    <property name="worklist.redirectpage" value="TaskDetails" />
    <property name="worklist.loginpage" value="Login.jsp" />
    <property name="worklist.errorpage" value="Error.jsp" />  
</workflowConfigurations>

This section describes the configuration parameters in this file:

See Also:

Oracle BPEL Process Manager Developer's Guide for additional details about the workflow services

2.3.1 taskAutoReleaseConfigurations

If a task is assigned to groups or multiple users, one of the users in the group or the list of users must acquire the task before acting on it. After the task is acquired, none of the initial assignees can see the task if the task was assigned to them. If the user does not act within a given time, the task is automatically released so that all other users in the group or list of users can see it. A particular business process can disable the autorelease by making autorelease a restricted action. The release duration is configurable in the wf_config.xml file.

The configurations for the autorelease durations are in the element taskAutoReleaseConfigurations. The release durations can be configured for tasks of each priority. For each priority, the autorelease duration can be specified as a percentage of the expiration (the percentageOfExpiration attribute) duration or a default value (the default attribute). The default values are used when the task does not have an expiration duration. The datatype of default is xsd:duration, whose format is defined by ISO 8601 under the form PnYnMnDTnHnMnS. The capital letters are delimiters and can be omitted when the corresponding member is not used. Examples include PT1004199059S, PT130S, PT2M10S, P1DT2S, -P1Y, or P1Y2M3DT5H20M30.123S.

For example, if the task of priority 3 is acquired at 3/24/2005 10:00 AM and the task expires at 3/31/2005 10:00 AM, then the time left for expiration is 7 days. If the percentageOfExpiration for priority 3 tasks was 50, then the task is released at 3/37/2005 10:00 PM (3 1/2 days from when it was acquired).

2.3.2 worklistApplicationURL

In the e-mails that are sent for tasks, the link to the Oracle BPEL Worklist Application is read from the worklistApplicationURL XML element in the wf_config.xml file.

The element worklistApplicationURL identifies the URL. Configuring this is useful if the custom Oracle BPEL Worklist Application is built. The tag PC_HW_TASK_ID_TAG in this URL is replaced with the task ID when constructing the URL for the e-mail.

2.3.3 actionableEmailAccountName

Task actions can be performed through e-mail. The actionable e-mail account is the account in which task action-related e-mails are received and processed. This e-mail account name is identified by the XML element actionableEmailAccountName in the wf_config.xml file.

2.3.4 pushbackAssignee

A task can be pushed back to the previous approver or previous original assignees. The original assignees do not need to be the approver, as they may have reassigned the task, escalated the task, and so. The XML element pushbackAssignee in the wf_config.xml file controls whether the task is pushed back to the original assignees or the approvers. The possible values for this element are as follows:

  • APPROVER

  • INITIAL_ASSIGNEES

2.3.5 assigneeDelimiter

Task assignees in the routing slip can be specified as a delimited string. For example, the following two are equivalent.

  • Listing 1:

    <participant name="Loan Agent">
          <resource isGroup="false" type="STATIC">jcooper, jstein</resource>
        </participant>
    
    
  • Listing 2:

    <participant name="Loan Agent">
          <resource isGroup="false" type="STATIC">jcooper </resource>
          <resource isGroup="false" type="STATIC">jstein</resource>
        </participant>
    
    

In the above example, a comma (,) was used as a delimiter. If a different delimiter is used in a particular environment, then the delimiter can be specified in the XML element assigneeDelimiter in the wf_config.xml file. Note that the dynamic assignee names are also interpreted for delimited strings. In the example below, if the XPath expression /task:task/task:payload/payload:assignee returns jcooper, stein, then this participant is the same as listing 2 above.

<participant name="Loan Agent">
      <resource isGroup="false"
 type="XPATH">/task:task/task:payload/payload:assignee</resource>
    </participant>

2.3.6 shortHistoryActions

The workflow service maintains two types of task history:

  • Detailed history

  • Short history

The detailed history contains all the changes made to the task. The short history contains only versions created by certain actions. By default, task initiation, reinitation, outcome update, complete, expiration, and withdrawn result in the version being in the short history. You can add other actions to the short history list in the XML element shortHistoryActions in the wf_config.xml file. The possible actions that can be added to the short history actions are listed below.

Action Action Action Action
ACQUIRE INFO_REQUEST RENEW OUTCOME_UPDATE_ROUTE
AUTO_RELEASE INFO_SUBMIT RESUME
ADHOC_ROUTE OVERRIDE_ROUTING_SLIP SKIP_CURRENT_ASSIGNMENT
DELEGATE PUSH_BACK SUSPEND
ERROR REASSIGN UPDATE
ESCALATE RELEASE OUTCOME_UPDATE

2.3.7 workflowServiceSessionTimeoutInMinutes

This is the length of time a workflowContext remains valid. If the client does not perform any activity for longer than the specified time, the workflowContext is marked as invalid, and a new authenticated context must be created.For the Oracle BPEL Worklist Application, this means that if a user remains logged into the application, but does not perform any activity for a time greater than the value specified in workflowServiceSessionTimeoutInMinutes, they are required to log into the application again.

2.3.8 user:ruleRepositoryInfo

The user metadata service stores the workflow rules for users and groups in an Oracle Business Rules repository file. The ruleRepositoryInfo section of the wf_config.xml file configures how to look up this file. The repository file can be accessed from the file system, or from a HTTP server through the WebDAV protocol. Accessing the repository through WebDAV is useful if you have several instances of the user metadata service on separate hosts that must access the same rule information. The separate instances can all point to the same WebDAV URL.

By default, the rule repository is the file WFRepository, located in the same directory as wf_config.xml.

When specifying a repository file on the file system, set the following properties for ruleRepositoryInfo:

  • ruleEngine: ORACLE (only the Oracle Business Rules Rules Engine is currently supported)

  • repositoryLocation: file path to the repository file, relative to the directory SOA_Oracle_Home\bpel\system\services\config.

  • dictionaryName: WFDictionary

  • reposProperty

    • name: reposType, value: jar

To host the workflow rules repository using WebDAV, set up a WebDAV Oracle Business Rules repository. Use the import utility in the Oracle Business Rules Rule Author to import the dictionary WFDictionary from the WFRepository file-based repository into your WebDAV-based repository.

Set the following properties for ruleRepositoryInfo:

  • ruleEngine: ORACLE (only the Oracle Business Rules Rules Engine is currently supported)

  • repositoryLocation: URL for the WebDAV repository

  • dictionaryName: WFDictionary

  • reposProperty

    • name: reposType, value: webDAV

    • name: proxyHost, value: Web proxy to use when accessing the WebDAV repository (this property is optional)

    • name: proxyPort, value: Web proxy port (this property is optional)

    • name: wallet, value: path (on local file system) to the wallet file containing the credentials for connecting to a secure WebDAV URL (this property is optional)

See Also:

2.4 Integrating Oracle BPEL Process Manager with the Oracle Application Server Service Registry

You can integrate Oracle BPEL Process Manager with Oracle Application Server Service Registry (OracleAS Service Registry).

OracleAS Service Registry is a version 3-compliant implementation of the Universal Description, Discovery and Integration (UDDI) specification, and is a key component of a Service Oriented Architecture (SOA). A UDDI registry provides a standards-based foundation for locating published services, invoking services, and managing metadata about services (security, transport, or quality of service). Consumers can browse and select published services that meet their needs.

Oracle BPEL Process Manager integration with OracleAS Service Registry also insulates Oracle BPEL Process Manager processes from any changes to service endpoints (physical hosted location, implementation, and so on).

The integration between Oracle BPEL Process Manager and OracleAS Service Registry is achieved by passing a reference to the service key (for the registered service in OracleAS Service Registry) at runtime. The registry service inquiry URI is identified at the Oracle BPEL Process Manager domain level by a configuration property. If the service endpoint for the published service changes, the new physical endpoint is discovered with the service key reference (which does not change).

This section provides an overview of how to integrate the RapidDistributors Web service of the OrderBooking tutorial with OracleAS Service Registry. This section contains the following topics:

2.4.1 Task 1: Installing the Oracle Application Server SOA Suite and OracleAS Service Registry

  1. Install an Oracle Application Server SOA Advanced install type (recommended). If you install the Oracle Application Server SOA Basic install type, you must perform additional configuration steps described in Step 3.

  2. Follow the instructions in Oracle Application Server Administrator's Guide to create a second OC4J instance through one of the following methods:

    • With the createinstance utility

    • With Oracle Enterprise Manager 10g Application Server Control Console

    For the procedures in this section, the second OC4J container is named registry.

    Notes:

    • Do not start the second OC4J instance.

    • The OracleAS Service Registry must not reside in the same OC4J container as your Oracle Application Server SOA install type.

  3. If you installed the Oracle Application Server SOA Basic install type, perform the following procedure:

    1. Open the SOA_Oracle_Home/opmn/config/opmn.xml file.

    2. Locate the registry component.

    3. Change default-web-site as follows:

      <port id="default-web-site" range="8889" protocol="http"/> 
      
      

      This assigns a fixed port (8889).

  4. Follow the instructions in Oracle Application Server Administrator's Guide to start the second OC4J instance created in Step 2.

  5. Download OracleAS Service Registry from the following Oracle Technology Network location:

    http://www.oracle.com/technology/tech/webservices/htdocs/uddi/index.html
    

    Note:

    These instructions assume you are familiar with OracleAS Service Registry and have read and used the following documentation included with the downloaded product:
    • OracleAS Service Registry 10.1.3 Product Documentation

    • Registry Step By Step Guide About Oracle Registry (online tutorial)

  6. Install OracleAS Service Registry by following the instructions in OracleAS Service Registry 10.1.3 Product Documentation, which is included in the downloaded ZIP file. Ensure that you use the same HTTP port (8889) specified for the OC4J container.

    Note that the OracleAS Service Registry must not be installed in the same OC4J container as Oracle BPEL Process Manager and Oracle Enterprise Service Bus. Depending on the Oracle Application Server SOA install type that you select, the container location is either in home or OC4J_SOA. The OC4J container name appears in your installation directory path. For example:

    • home — is the container name if you install the Oracle Application Server SOA Basic install type

    • OC4J_SOA — is the container name if you accept the default value when installing an Oracle Application Server SOA Advanced install type.

  7. Shut down your Oracle Application Server SOA install type:

    cd SOA_Oracle_Home/opmn/bin
    opmnctl stopall
    
  8. Copy the following library files from SOA_Oracle_Home/j2ee/registry/applications/registry/registry/WEB-INF/lib to SOA_Oracle_Home/j2ee/OC4J_Home/lib/api-ext:

    • security-ng.jar

    • security3-ng.jar

      where OC4J_Home is the name of the OC4J container for your install type:

      • home — for the Oracle Application Server SOA Basic install type

      • OC4J_SOA — for the Oracle Application Server SOA Advanced install types

      Note:

      If the api-ext directory does not exist, create it.
  9. Copy the following library files from the OracleAS Service Registry Registry_Installation_Home\lib directory to the SOA_Oracle_Home/bpel/registry/lib directory:

    • security2-ng.jar

    • security_providers_client.jar

  10. Back up the SOA_Oracle_Home/j2ee/OC4J_Home/config/server.xml file.

  11. Open the server.xml file.

  12. Locate the shared library named orabpel.common in the server.xml file.

  13. Add the following lines at the bottom:

    <code-source path="SOA_Oracle_Home/bpel/registry/lib/security2-ng.jar"/>
    <code-source path="SOA_Oracle_Home/bpel/registry/lib/security_providers_client.jar"/>
    
    

    Ensure that you replace SOA_Oracle_Home with the real path.

  14. Back up the SOA_Oracle_Home/j2ee/OC4J_Home/config/system-jazn-data.xml file.

  15. Open the system-jazn-data.xml file.

  16. Add new login modules to the <jazn-loginconfig> section:

    <application>
       <name>NamePasswordNoAN</name>
       <login-modules>
           <login-module>
              <class>com.idoox.security.jaas.NamePasswordLoginModuleNoAuth</class>
              <control-flag>required</control-flag>
              <options>
                 <option>
                    <name>debug</name>
                    <value>true</value>
                 </option>
              </options>
           </login-module>
       </login-modules>
    </application>
    
    <application>
       <name>NamePasswordAN</name>
       <login-modules>
           <login-module>
               <class>
     com.systinet.uddi.security.jaas.NamePasswordLoginModule</class>
               <control-flag>required</control-flag>
               <options>
                   <option>
                       <name>debug</name>
                       <value>true</value>
                   </option>
               </options>
           </login-module>
       </login-modules>
    </application>
    
    
  17. Back up the SOA_Oracle_Home/j2ee/registry/config/system-jazn-data.xml file.

  18. Open the system-jazn-data.xml file.

  19. Add new login modules to the <jazn-loginconfig> section:

    <application>
        <name>HttpRequest</name>
        <login-modules>
            <login-module>
                <class>com.systinet.uddi.security.jaas.SmLoginModule</class>
                <control-flag>required</control-flag>
                <options>
                    <option>
                        <name>debug</name>
                        <value>true</value>
                    </option>
                </options>
            </login-module>
        </login-modules>
     </application>
    
    <application>
       <name>NamePasswordNoAN</name>
       <login-modules>
           <login-module>
               <class>com.idoox.security.jaas.NamePasswordLoginModuleNoAuth</class>
               <control-flag>required</control-flag>
                  <options>
                     <option>
                        <name>debug</name>
                        <value>true</value>
                     </option>
                  </options>
           </login-module>
       </login-modules></application>
    
    <application>
       <name>NamePasswordAN</name>
       <login-modules>
           <login-module>
               <class>
     com.systinet.uddi.security.jaas.NamePasswordLoginModule</class>
               <control-flag>required</control-flag>
               <options>
                   <option>
                       <name>debug</name>
                       <value>true</value>
                   </option>
               </options>
           </login-module>
       </login-modules>
    </application>
    
    <application>
       <name>IdentityAsserter</name>
       <login-modules>
           <login-module><class>
                com.systinet.uddi.security.jaas.IdentityAsserterLoginModule</class>
               <control-flag>required</control-flag>
               <options>
                   <option>
                       <name>debug</name>
                       <value>true</value>
                   </option>
               </options>
           </login-module>
       </login-modules>
    </application>
    
    
  20. Follow the instructions in section 8, "Authentication Configuration" of OracleAS Service Registry 10.1.3 Product Documentation to enable OracleAS Service Registry basic authentication.

  21. Open SOA_Oracle_Home/j2ee/registry/application-deployments/registry/registry/orion-web.xml and change the value of search-local-classes-first to false.

  22. Start your Oracle Application Server SOA install type:

    cd SOA_Oracle_Home/opmn/bin
    opmnctl startall
    

2.4.2 Task 2: Deploying Web Services

You are now ready to deploy the RapidDistributors Web service.

  1. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Developer Prompt to open up an operating system command prompt at the SOA_Oracle_Home\bpel\samples directory.

  2. Change directories to the tutorials\127.OrderBookingTutorial subdirectory:

    cd tutorials\127.OrderBookingTutorial
    
    
  3. Enter the following command:

    ant
    
    

    This deploys and starts the required services, including RapidDistributors. If successful, a message appears at the end:

    BUILD SUCCESSFUL
    

2.4.3 Task 3: Publishing a Service and Adding Bindings

  1. Go to OracleAS Service Registry.

  2. Publish the RapidDistributors service to OracleAS Service Registry by following the instructions for creating a provider and publishing a service in "Publishing a Service" of OracleAS Service Registry 10.1.3 Product Documentation. The Registry Step By Step Guide About Oracle Registry also provides an example.

    After publishing a service (named RapidDistributors for this example), you are ready to add bindings. Bindings represent a Web service instance from which you obtain the access point of an instance. See "Publishing a Binding Template" of OracleAS Service Registry 10.1.3 Product Documentation for details.

  3. Right-click the published service and select Add binding.

    Description of binding.gif follows
    Description of the illustration binding.gif

    The Add Binding page appears.

  4. Enter the Web service access point for the RapidDistributors service:

    http://hostname:port/orabpel/default/RapidDistributors/1.0/
    
    
  5. Select an entry from the Use type list:

    • wsdlDeployment (This is a mandatory selection and refers to the physical endpoint of the service.)

      http://hostname:port/orabpel/default/RapidDistributors/1.0/RapidDistributors?wsdl
      
      
    • endPoint (This is an optional selection and refers to the WSDL endpoint.)

      http://hostname:port/orabpel/default/RapidDistributors/1.0/ 
      
      
    • other (This is an optional selection and refers to the abstract location of the service.)

      http://hostname:port/RapidDistributors?wsdl
      
      
    Description of binding2.gif follows
    Description of the illustration binding2.gif

  6. Click Add binding when complete.

    The bindings are added to the service. Note the service key value. You later specify this value in a deployment descriptor property in the bpel.xml file in "Task 7: Specifying the OracleAS Service Registry Service Key".

    Description of binding3.gif follows
    Description of the illustration binding3.gif

2.4.4 Task 4: Specifying the Registry Service Inquiry URL in Oracle BPEL Control

  1. Access Oracle BPEL Control through one of the following methods:

    • Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > BPEL Control

    • Go to the following URL:

      http://localhost:port/BPELConsole
      
      
  2. Select Manage BPEL Domain > Configuration.

  3. Enter a value for the uddiLocation property:

    http://hostname:port/registryname/uddi/inquiry
    
    

    This property must refer to the inquiry WSDL URL of the OracleAS Service Registry. For example:

    http://hostname.us.oracle.com:42461/registryrc7/uddi/inquiry?wsdl
    

    Note:

    There can only be one OracleAS Service Registry reference in a Oracle BPEL Process Manager Installation at any point in time.

2.4.5 Task 5: Creating a Connection to the UDDI Registry

You now create a connection to OracleAS Service Registry in Oracle JDeveloper.

  1. Select Connection Navigator from the View main menu in Oracle JDeveloper.

  2. Right click UDDI Registry.

  3. Select New UDDI Registry Connection.

  4. Click Next on the Welcome page.

  5. Enter the following connection information:

    Field Description
    Connection Name Enter a name for connecting to the registry.
    Inquiry Endpoint URL Enter the URL of the inquiry endpoint. For example:
    http://hostname.us.oracle.com:42461/registryrc7/uddi/inquiry?wsdl
    

    Note: The value you enter here is the same as the value specified in Oracle BPEL Control in Step 3 of "Task 4: Specifying the Registry Service Inquiry URL in Oracle BPEL Control".


  6. Click Next.

  7. Test the connection by clicking Test Connection. If the connection was successful, the following message appears:

    Successfully contacted UDDI inquiry endpoint
    
    
  8. Click Finish.

    The required endpoint service can now be selected in the Service Explorer window by browsing services under the UDDI Registry folder while a creating a partner link.

2.4.6 Task 6: Configuring the RapidDistributors Partner Link

You now configure the RapidDistributors partner link and select the Web service access point in OracleAS Service Registry.

  1. Open the SOA_Oracle_Home/bpel/samples/tutorials/127.OrderBookingTutorial/OrderBooking/OrderBooking.jpr file in Oracle JDeveloper.

  2. Double-click the RapidDistributors partner link in the designer window.

    The Edit Partner Link window appears.

  3. Click the flashlight (the second icon from the left named Service Explorer) to access the Service Explorer window for selecting the RapidDistributors service deployed in "Task 1: Installing the Oracle Application Server SOA Suite and OracleAS Service Registry".

  4. Expand the navigation tree and select the RapidDistributors service under the UDDI Registry.

    Description of registry1.gif follows
    Description of the illustration registry1.gif

2.4.7 Task 7: Specifying the OracleAS Service Registry Service Key

You now configure the service key value with the registryServiceKey property. This enables a partner link to invoke the Web service through OracleAS Service Registry.

  1. Add the following registryServiceKey property to the partner link for RapidDistributors in the respective partnerLinkBinding section of the bpel.xml file:

    <property name="registryServiceKey">uddi:e3955ac0-45a8-11db-9dd0-28bc5b509dce</property>
    
    

    The service key value was created in Step 6.

    At runtime, you can verify that the service for RapidDistributors is invoked from the service endpoint retrieved from OracleAS Service Registry.

2.4.8 Task 8: Securing the Client with Basic Authentication (Optional)

If you want to secure the client side with basic authentication, follow these procedures.

  1. Enable secure HTTP basic authentication by adding the following two properties to your bpel.xml file in the respective partnerLinkBinding section.

    <property name="registryUsername"> registry_username </property>
    <property name="registryPassword"> registry_password </property>
    
    

    where:

    • registry_username — the name of a registry user

    • registry_password — the password for this registry user

    You can also set these properties at the domain level in Oracle BPEL Control under Manage BPEL Domain > Configuration (as you set the uddiLocation property). If they are also set in the bpel.xml file, the settings in that file overwrite the ones set in Oracle BPEL Control.

2.4.9 Troubleshooting

This section describes troubleshooting procedures for OracleAS Service Registry and Oracle BPEL Process Manager integration.

  • A one-time binding fault occurs when OracleAS Service Registry is deployed on a remote Oracle Application Server SOA instance while the BPEL processes are deployed on another SOA instance of a different host. The following error displays the first time the calling BPEL process invokes the registry published service. All subsequent invocations of the service are performed successfully without error (after deployment).

    <bindingFault xmlns="http://schemas.oracle.com/bpel/extension"><part
    name="code"><code>GenericError</code>
    </part><part name="summary"><summary>http_client transport doesn't support
    nonProxyHosts with wildcards</summary>
    </part></bindingFault> 
    
    
  • If your WSDL URLs point to hosts using the DHCP communication protocol instead of static IP addresses, ensure that you update the SOA_Oracle_Home/opmn/conf/opmn.xml file to include this information. For example:

    -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80
    -Dhttp.nonProxyHosts=122.39.159.106|*acmecorp.com|*.acme.com|localhost|
       ser vices.xmethods.net|xmethods.net|*idc.acme.com|dhcp-idc-towers-122-
       39-159-106.idc.acme.com"/> 
    
    

    Otherwise, you can receive deployment errors.

2.5 Summary

This chapter describes how to configure the identity service, worklist service, and notification service.