Friday Apr 26, 2013

Updated Best Practices and Production Configuration Whitepapers

The whitepapers available for the Oracle Utilties Application Framework are updated on a regular basis to include new and updated advice for past and the latest versions of the Oracle Utilties Application Framework. As part of that update cycle the following whitepapers have been updated:

  • Technical Best Practices for Oracle Utilities Application Framework Based Products (Doc Id: 560367.1) - Updated and new advice around security, database connectivity and monitoring.
  • Batch Best Practices for Oracle Utilities Application Framework based products (Doc Id: 836362.1) - Updated advice for Coherence tuning and monitoring.
  • Production Environment Configuration Guidelines (Doc Id: 1068958.1) - Latest advice from customer experiences and benchmarks for configuring production. Additonal advice has been added to optimize Coherence for increased batch stability.

The whitepapers are available from My Oracle Support.

Tuesday Apr 16, 2013

Installing OUAF in Oracle WebLogic native mode

As in a previous post it is possible to install an Oracle Utilities Application Framework based product in native mode as an alternative to the embedded mode offered by the default installation routine.

The basic process for this is as follows:

  • Install Oracle WebLogic as per the Oracle WebLogic documentation. If you are running Oracle ExaLogic then this may be already done as part of the Oracle ExaLogic deployment.
  • Using the Configuration Wizard shipped with Oracle WebLogic (or via Oracle Enterprise Manager) create a domain, create an administration server with the console deployed to it and create servers/clusters you want to deploy the product within.
  • You may need to alter the server startup definitions within the server definition to add additional java options and java memory settings for the product. The defaults shipped with Oracle WebLogic reflect the defaults of tha java version used and typically are set too small for the product.
  • Install the Oracle Utilities Application Framework based product as per the Installation Guide with a few additional settings specifically when specifying the host and port numbers (they should match the values you specified in the Configuration Wizard). You can optionally setup the product to use data sources, if you want to use them. If you do this then you need to deploy the data sources to the server allocated to the product BEFORE you deploy the product. 
  • Set the base location of the software in the startup for the servers you want to deploy the product. This tells the runtime to refer to the additional runtime components and product configuration files at runtime. This is simply making sure the environment variable (SPLEBASE) is set appropriately prior to server startup.
  • Create an XML Registry setting in the domain so that the correct parsers for the platform are used for the product.
  • Define your security realm settings for your domain including creating the product authentication group, JNDI user for JNDI lookups and initial product users.
  • Configure the domain to use advanced settings for each component of the product. This is simply setting a configuration flag on the domain realm.
  • Deploy the product Business Application Server (SPLService) into the servers using the deployment facilities of Oracle WebLogic or Oracle Enterprise Manager.
  • Deploy the product Web Application Server (SPLWeb) into the servers using the deployment facilities of Oracle WebLogic or Oracle Enterprise Manager. You will need to set the deployment order so that this component starts AFTER the startup of the Business Application Server.

The diagram below illustrates the process in detail:

Native Install Process

The product is now installed ready to be configured, managed and operated from the facilities in Oracle WebLogic Administration console or via Oracle Enterprise Manager.

This may look like a bit of effort but most of the work is wizard driven asking questions and simply settings the correct values. For a full detailed description of the process refer to Native Installation Oracle Utilities Application Framework (Doc Id: 1544969.1) whitepaper available from My Oracle Support.

Monday Apr 15, 2013

Supporting CLIENT-CERT

One of the additional configuration options for the authentication of the product is to implement a Single Sign On solution or implement client certificates. Whilst most of the configuration for these features is performed in the Single Sign On product and/or J2EE Application Server, the Oracle Utilities Application Framework has to be configured to use that facility.

In most cases, to use these facilities the login configuration for the product has to be changed from FORM or BASIC to CLIENT-CERT. This informs the product that the credentials will be passed directly from the J2EE Application Server (via the Single Sign On solution, security providers or via client certificates).

To make this change the following process must be performed:

  • Logon to the machine that houses the environment to change as the product administrator.
  • Take a copy of  the web.xml.template to cm.web.xml.template in the same directory the original is located (in Oracle Utilities Application Framework V2.x it is located in the etc directory of the environment; in Oracle Utilities Application Framework V4.x it is located in the templates directory). This will inform the Oracle Utilities Application Framework to use this new template instead of the base template.
  • Edit the cm.web.xml.template file and replace the login-config section with a section configuring the CLIENT-CERT configuration. For example:





Note: For Oracle Utilities Application Framework V4.x customers this may need to be repeated for the templates for AppViewer (web.xml.appViewer.template) and online help ( if you wish to include those components in the same solution.

  • Ensure the environment is shutdown prior to implementing any changes.
  • Execute the initialSetup[.sh] utility to implement the changes and rebuild the EAR files.

Note: As the web.xml file has been changed and EAR file rebuilt, customers using native mode will have to redeploy the SPLWeb application to reflect the change.

  • Optionally, changes can be verified by viewing the web.xml files generated under the etc\conf subdirectory.
  • Restart the product.

The product now is configured to use the CLIENT-CERT option.

Friday Apr 12, 2013

Using Native Installations of Oracle WebLogic

By default, when using Oracle WebLogic, the Oracle Utilities Application Framework based product is installed in embedded mode. This means that the configuration files and files within the product are used directly by Oracle WebLogic, including configuration files necessary for Oracle WebLogic itself (e.g. config.xml). The installation process generates the necessary configuration files and then using generated versions of Oracle WebLogic utilities points the Oracle WebLogic runtime to the files in the product environment. The term embedded is used to describe the fact that Oracle WebLogic uses files embedded in the product rather than its own files; it simply provides the runtime for the environment.

This default approach has advantages and disadvantages:

Advantages Disadvantages
Simple and easy to implement configuration, ideal for development and other non-production environments Changes to domain configuration within Oracle WebLogic console must be reflected in configuration files using user exits or custom templates to retain changes across patches/upgrades.
One Oracle WebLogic installation can be shared across many environments on the same host Does not support clustering without complex manual changes to configuration files
Default security setup Administration Server deployed with product
Common configuration change scenarios are handled by configuration settings Oracle Enterprise Manager does not recognize Oracle WebLogic targets without manual configuration of discovery
  Utilities provided must be used to manage product
  Limited changes to some features (such as domain)

This setup is ideal for development and other non-production environments where you need multiple copies of the product on a single host but may not be appropriate for production environments where advanced security setup and clustering are typically required.

The alternative is to install the product in what is termed, native mode. Typically Oracle WebLogic J2EE Web Applications are deployed directly to Oracle WebLogic and managed using capabilities within Oracle WebLogic. This has the advantage of gaining full access to the Oracle WebLogic facilities like advanced configuration and more importantly the ability cluster the product across multiple nodes. Oracle Utilities Application Framework V2.2 and above, can be installed using this mode with minor changes to the installation process. It is also possible to convert an embedded installation into a native installation with minor changes, if migration to this mode is appropriate.

The native mode allows the product to have access to support using the features of Oracle WebLogic with fewer configuration steps than embedded mode. The advantages and disadvantages of this mode are outlined in the table below:

Advantages Disadvantages
Native Support for Clustering/Managed Servers Support for multiple environments per domain is limited at present stage. Multiple WebLogic installs may be required if multiple environments are on the same host
Changes to domain do not require manual changes to templates Requires some manual effort in setting up domain, servers and security for environment
Administration Server can be separated from product servers   
Oracle Enterprise Manager natively recognizes Oracle WebLogic targets  
Native facilities in Oracle WebLogic and/or Oracle Enterprise Manager can be used to configure, operate and monitor the product  
Configuration and operational facilities of Oracle WebLogic can be used (including documented variations)  

The two modes have different attributes and different approaches applicable to different situations. The following recommendations should be consider when deciding which mode to use:

  • It is not impractical use different modes for different environments. One mode will not usually satisfy all the needs of all environments.
  • It is recommended to use native mode for production implementations as it offers flexibility, cluster support, separation of the Administration function and the ability to use the advanced configuration elements of Oracle WebLogic as well as Oracle Enterprise Manager (if applicable).
  • It is recommended to use native mode if each environment is housed in a separate virtual machine, which is common in virtualized implementations. This will allow configuration at the virtual machine level to be used and reduces maintenance efforts.
  • It is recommended to use embedded mode if more than one copy of the product exists on the same virtual or non-virtual host. The ability to share a common copy of Oracle WebLogic is reduces the maintenance efforts for multiple environments.
  • It is recommended to use embedded mode for development environments where java based development is taking place. This setup supports the use of the expanded mode features of Oracle WebLogic used by the Oracle Utilities SDK, which requires access to expanded directories for multi-user development.

For more information about native mode installation refer to the new whitepaper Native Installation for Oracle Utilities Application Framework (Doc Id: 1544969.1). For customers considering clustering and/or Oracle ExaLogic also refer to the Implementing Oracle ExaLogic and/or Oracle WebLogic Clustering (Doc Id: 1334558.1) whitepaper available from My Oracle Support.

Thursday Apr 11, 2013

Updated Oracle ExaLogic and Clustering Whitepaper

The Implementing Oracle ExaLogic and/or Oracle WebLogic Clustering  (Doc Id: 1334558.1) whitepaper available from My Oracle Support has been updated with additional advice.

The updated advice is around setting Java options within the console (instead of within a command utility) as well as adjusting timeouts that may occur during the deployment of the product EAR files.

Wednesday Apr 03, 2013

Using Oracle WebLogic datasources with OUAF based products

By default, the online (and XAI) components of the Oracle Utilities Application Framework use Universal Connection Pool (or c3p0 for Oracle Utilities Application Framework V2.x) for connection pooling. If you wish to use Oracle WebLogic JDBC based connection pooling for integration to other products or to use the GridLink features of Oracle WebLogic, then Oracle Utilities Application Framework needs to be configured to use Oracle WebLogic datasources.

The following process can be used for this:

  • Define the JDBC datasource to the product database, using the Oracle WebLogic console, with the following attributes:
    • The JNDI Name for the datasource should contain a directory name such as jdbc. For example, jdbc/demodb. The name of the JNDI should reflect your site requirements.
    • Ensure that Global Transaction Support is disabled on the JDBC connection. This is not appropriate for this integration.
    • The XA JDBC driver may be used but the product does not take advantage of the XA feature set.
    • The Instance or Service driver may be used but if there is no site preference use the Service driver.
    • The Database User and Password to use should be any database user with read/write access to the product such as CISUSER or SPLUSER. The value can correspond to the value of the DBUSER configuration variable in the ENVIRON.INI, if no site preference exists.


  • If your site is using Oracle WebLogic in embedded mode the above change will change the Oracle WebLogic config.xml to add the JDBC resource. To retain changes over upgrade and patches do the following:
    • For products using Oracle Utilities Application Framework V2.x, you should copy the config.xml.template (or for Windows) in the etc directory and create a cm version (add cm. as the name prefix) and add the following lines: 

Note: The values for name, target and descriptor-file-name tags should be altered to suit your JDBC connection. The internal-apps-deploy-on-demand-enabled is not required but is included for sequence reference purposes.

    •  For products using Oracle Utilities Application Framework V4.x then the above XML code should be placed in the cm_config.xml.exit_3.include file (or for Windows) in the templates directory. This is using the new user exit method introduced in Oracle Utilities Application Framework V4.x which avoids the need for a cm template altogether.
  •   To use the new JDBC datasource for online the following must be performed:
    • Copy the to within the relevant directory. For Oracle Utilities Application Framework V2.x the directory is the etc subdirectory, and Oracle Utilities Application Framework V4.x the directory is the template subdirectory. This will tell the utilities to override the base template with the custom template.
    • Add the following lines to the top of the cm template file:
hibernate.connection.datasource = <jdbc_jndi>
hibernate.connection.username = <jndi_user>
hibernate.connection.password = <jndi_user_password>

where :

<jdbc_jndi> - Full JNDI name for the JDBC connection
<jndi_user> - A user to access the JNDI (Substitution variable @WEB_WLSYSUSER@ can be used in the template).
<jndi_user_password> - The password for the user to access the JNDI (Substitution variable @WEB_WLSYSPASS@ can be used in the template).

    • Remove the following lines from the cm template file depending on the version of the Oracle Utilities Application Framework:  
       Framework Version  Lines to remove
       2.2.x, 4.0.x All hibernate.connection.url entries including any ifdef statements
      All hibernate.c3p0.* entries
       4.1.x, 4.2.x All hibernate.connection.url entries including any ifdef statements
      All hibernate.ucp.* entries
    • Change the hibernate.transaction.factory_class setting to org.hibernate.transaction.JDBCTransactionFactory
    • Change the hibernate.connection.provider_class to org.hibernate.connection.DatasourceConnectionProvider
    • Save the file. For Oracle Utilities Application Framework V4.2 and above the sample cm template is shown below:
hibernate.connection.driver_class = @DBDRIVER@
hibernate.connection.datasource = jdbc/demodb
hibernate.connection.username = @WEB_WLSYSUSER@
hibernate.connection.password = @WEB_WLSYSPASS@
hibernate.dialect = @DIALECT@
hibernate.show_sql = false
hibernate.max_fetch_depth = 2
hibernate.transaction.factory_class = org.hibernate.transaction.JDBCTransactionFactory
hibernate.jdbc.fetch_size = 100
hibernate.jdbc.batch_size = 30
hibernate.query.factory_class = org.hibernate.hql.internal.classic.ClassicQueryTranslatorFactory
hibernate.cache.use_second_level_cache = false
hibernate.query.substitutions = true 'Y', false 'N'
  • Execute the initialSetup[.sh] command to apply the changes and new templates.

Note: For products using the Oracle Utilities Application Framework V4.x you can execute the initialSetup[.sh] –t command to apply the changes. This avoids an EAR rebuild.

  • Restart the server to verify the connection is active 

Now the data source is used from Oracle WebLogic for online as well as XAI. This technique does not apply to batch as Oracle WebLogic is not used for batch, this will continue to use UCP or c3p0 (depending on the version of Oracle Utilities Application Framework is used).


Anthony Shorten
Hi, I am Anthony Shorten, I am the Principal Product Manager for the Oracle Utilities Application Framework. I have been working for over 20+ years in the IT Business and am the author of many a technical whitepaper, manual and training material. I am one of the product managers working on strategy and designs for the next generation of the technology used for the Utilities and Tax markets. This blog is provided to announce new features, document tips and techniques and also outline features of the Oracle Utilities Application Framework based products. These products include Oracle Utilities Customer Care and Billing, Oracle Utilities Meter Data Management, Oracle Utilities Mobile Workforce Management and Oracle Public Service Revenue Management. I am the product manager for the Management Pack for these products.


« April 2013 »