Workflow

Tracing Configuration

Prior to any configuration make sure the user EDBKERNEL has been created and is activated for the Workflow module because internal processes use the user EDBKERNEL as a reference user!
 

Errors in the workflow services can be debugged/traced by doing the following:

  For a detailed Trace- or Debug output the log4j.properties file has to be prepared with the optional parameters listed below.
The log4j.properties file was automatically deployed to your oracle application server during application creation. You must change the properties directly on the oracle application server.
The file can befound in <oracle_home>\j2ee\home\applications\BusinessService<application_name>\<application_name>Web\WEB-INF\log4j.properties
(e.g. D:\oracle\10.1.3\OracleAS_1\j2ee\home\applications\BusinessServicedemo\demoWeb\WEB-INF\log4j.properties).
To activate the tracing you have to restart the oracle application server application "BusinessService<application_name>" with the oracle application server control web interface.
 

Error Log Verbosity Levels

  Below is a list of the various trace levels that can be used.  The order begins with the highest level of detail to the lowest level of detail (i.e.. FATAL only lists fatal errors):
 
  1. DEBUG
  2. TRACE
  3. INFO
  4. WARN
  5. ERROR
  6. FATAL
  The log4j package which we use (see also http://jakarta.apache.org/log4j/docs/manual.html) defines the levels DEBUG, INFO, WARN, ERROR and FATAL. The TRACE level was defined by Agile.  In most cases, you will find that TRACE level provides the most efficient level of debugging for workflow issues.
 

Format

 

The general semantic for the trace configuration in the log4j.properties file can be written as follows:

log4j.category.{Java package name}={Verbosity Level}

Log file is written to <oracle_home>\j2ee\home\log\<hostname>-<application_name>.log (e.g. D:\oracle\10.1.3\OracleAS_1\j2ee\home\log\example.com-plmref.log) on the oracle application server.

 

Here is a sample list of Log4j filter definitions that can be added to the end of the file which can be used to trace various java packages. If you require an increased level of logging printed trace messages, you may substitute TRACE with DEBUG.

   
  The log output file can be configured by specifying the maximum file size as well as the number of backup files for the trace output in the corresponding lines of the following file appender.
  #
# The File appender
#
...
log4j.appender.Default.MaxFileSize=1MB
log4j.appender.Default.MaxBackupIndex=10
...
  When starting the tracing, the original log output file doesn't have a number as indicated by the (.x) at the end of the file. If this log output file exceeds the size specified in the file appender, then the tracing information will be written into the subsequent log output file which is identified by the number (1) at the end of the file. The sequence of log output files following each other depends on the number of backup files defined.
   
 

General Error Tracing

The general error tracing permanently checks all modules but only produces an output in case of an error. Therefore, it is recommended to have the general error tracing always activated with the following filter definition:

log4j.category.com.agile=ERROR
   
 

Specifying the Trace Configuration for each module

The trace configuration for each module can be specified; e.g. it is both possible to either trace an entire module or to trace specific components of a module as e.g. the user manager. As an example:

To only trace the entire prm module, write: log4j.category.com.agile.abs.prm=TRACE

To only trace the user manager of the prm module, write: log4j.category.com.agile.abs.prm.UserManager=TRACE

   
 

Activating the tracing for the most imortant components

  • Mails:
    log4j.category.com.agile.abs.workflow.messenger=TRACE
    or
    log4j.category.com.agile.abs.workflow.messenger=DEBUG

  • Watchdog:
    log4j.category.com.agile.abs.workflow.watchdog=TRACE

  • Notifier:
    log4j.category.com.agile.abs.workflow.notifier=TRACE

  • Database access:
    log4j.category.com.agile.abs.owh.adapter.SQLTRACE=TRACE
    or
    log4j.category.com.agile.abs.owh.adapter.JdbcAdapter=TRACE
  An entire list of all traceable components:
  Database communication:
  SQL-Trace:
log4j.category.com.agile.abs.owh.adapter.SQLTRACE=TRACE

Object Ware House:
log4j.category.com.agile.abs.owh=TRACE

Possible reasonable limitation:
log4j.category.com.agile.abs.owh.adapter.JdbcAdapter=TRACE
   
  Workflow Executor:
log4j.category.com.agile.abs.workflow.executor=TRACE

Possible reasonable limitation:
log4j.category.com.agile.abs.workflow.executor.process=TRACE
log4j.category.com.agile.abs.workflow.executor.history=TRACE
log4j.category.com.agile.abs.workflow.executor.activity=TRACE

Further possible limitations:
log4j.category.com.agile.abs.workflow.executor.activity.Activity=TRACE
log4j.category.com.agile.abs.workflow.executor.activity.SubProcessActivity=TRACE
log4j.category.com.agile.abs.workflow.executor.activity.DistributionActivity=TRACE
log4j.category.com.agile.abs.workflow.executor.activity.WorkItem=TRACE
   
  Watchdog:
log4j.category.com.agile.abs.workflow.watchdog=TRACE

Possible reasonable limitation:
log4j.category.com.agile.abs.workflow.watchdog.UrgentActivity=TRACE
   
  Notifier:
log4j.category.com.agile.abs.workflow.notifier=TRACE
   
  Mailing (normally combined with Notifier or Watchdog):
log4j.category.com.agile.abs.workflow.messenger=TRACE

Possible reasonable limitations:
log4j.category.com.agile.abs.workflow.messenger.Messenger=TRACE
log4j.category.com.agile.abs.workflow.messenger.ParseHTML=TRACE

The following normally together:
log4j.category.com.agile.abs.workflow.messenger.MailMessage=TRACE
log4j.category.com.agile.abs.workflow.messenger.AbstractMailMessage=TRACE
   
  UserManager:
log4j.category.com.agile.abs.prm=TRACE

Possible reasonable limitations:
log4j.category.com.agile.abs.prm.Job=TRACE
log4j.category.com.agile.abs.prm.Privilege=TRACE
log4j.category.com.agile.abs.prm.Role=TRACE
log4j.category.com.agile.abs.prm.Team=TRACE
log4j.category.com.agile.abs.prm.User=TRACE
   
 

Activate Tracing for Workflow Batch processes

 

Possible error causes:

1. The Java Daemon was not running so the server process couldn't be started.
2. The Java Daemon was running but the server process couldn't be started.
3. The Java Daemon was running and the server process could be started but an error occurred in the code or in a LGV procedure.

Trace possibilities:

Error cause 1: No trace, just start the daemon.
Error cause 2: Set EP_DEBUG _all_ in File <ep_root>/init/<envname>_cust(.cmd)
Error cause 3: Batch processes are running on a separate server without UI. Therefore, trace and debug information are only accessible via log files or database entries. Errors that occur during runtime of the batch process are written into the history of the corresponding activity. So first, one has to check via the corresponding activity history in which state the error occurred. Additionally, the LGV trace is needed. This can be created by activating the trace and debug mode for LGV. The following settings have to be done for the LGV defaults:

  • Change EDB-LGV-TRC for the user GLOBAL from OFF to ON/CONT.
  • Change EDB-LGV-DBG for the user GLOBAL from OFF to ON.

With this setting the created LGV trace (file name is in the format "lgv123456. trc") in the directory <ep_root>/tmp won't be deleted after ending the server process - as is the normal case.