API logging

API logging refers to log messages that are generated by the Content Engine and Process Engine Java APIs.

In the APIs, in contrast to the server, no logging is enabled by default and logging must be explicitly enabled using levels. For this purpose levels form a hierarchy, in which each level includes those preceding it in the table given earlier. For example, enabling summary tracing also enables error, warning and informational logging.

(V5.5.5 and earlier) Using log4j configuration

In releases 5.5.5 and earlier, client logging is configured using the capabilities provided through the Apache log4j framework.

Refer to (V5.5.5 and earlier) Working with the Apache log4j Configuration File for information about Content Engine client logging.

Refer to (V5.5.5 and earlier) Enabling trace logging for process clients for information about Process Engine client logging.

(V5.5.6 and later) Native Content Platform Engine configuration

Starting with V5.5.6 and coinciding with the switch from log4j to JUL, a new and simplified mechanism is employed, defined natively by the Content Platform Engine. This mechanism allows logging settings to be defined either entirely by JVM arguments or by a combination of JVM arguments and an easily understood properties file.

To configure a setting as JVM argument specify the raw setting name from one of the tables that follow prefixed with com.filenet.logging. in the usual -D fashion, as in the following example:

-Dcom.filenet.logging.LogFile=c:\logs\MyLog.txt

To specify settings through a properties file, use the JVM argument com.filenet.logging.ConfigFile to specify the path and name for the file, for example:

-Dcom.filenet.logging.ConfigFile=c:\logs\FileNetLogging.properties

Then in the specified properties file, give the settings in exactly the form given in the tables below. For example:

LogFile=c:\\logs\\MyLog.txt
CESubSystem.API=detail

Important: For Windows systems, in the properties file, use either double backslashes or single forward slashes.

Settings can be given either as JVM arguments or in the properties file, but those in the properties file will take precedence. As is standard for properties and JVM arguments, the setting name (to the left of the equals sign) must be given in matching case to what is documented here. A sample properties file is included in the Content Platform Engine server and client distributions and appears as FileNetLogging.properties in the config/samples subdirectory of the installation directory.

Any combination of Content Engine and Process Engine settings can be configured.

To change settings that are given by JVM arguments, including the ConfigFile setting, the JVM in question must be restarted. If a config file is specified, that file need not exist at the time the JVM is started – it can be added later and the settings within will take effect automatically (without a restart) within 5 minutes. That automatic refresh also applies if the file is changed – the modified settings will take effect within 5 minutes without requiring a JVM restart.

Logging levels

The verbosity of logging is determined by the specification of a logging level for a given subsystem or as a component-wide default. The possible levels are as follows in increasing degree of verbosity (each one includes the effect of the all the previous):

Error – Only errors are logged

Warning – Adds warning messages

Info – Adds informational messages

Summary – Includes summary trace messages

Moderate – Adds moderate trace messages

Detail – Adds detail trace messages

Timer – Adds timer trace messages (applies to CE only)

A subsystem value may also be set to Off to disable logging in that subsystem, overriding the component-wide default. Values are interpreted case-insensitively.

Log file settings

All logging produced by the combination of Content Engine and Process Engine API activities is written to a single file, specified by the LogFile setting as in the previous examples. These settings should specify the full path and name of the output file.

Ordinarily, each log message is written to this file as a single line of text, with any line breaks in the message body replaced by the escape sequence “\n”. This line per message format facilitates automatic processing of the log but makes it less readable, so the option is provided to retain the native line breaks in the message body, such that some messages may occupy several consecutive lines in the log file. This is accomplished by setting MultiLine=true.

Content Engine settings

The new settings for the Content Engine are defined in the following table.

Setting	Description and usage
CESubSystem.XYZ	Specifies the logging level for a subsystem identified by XYZ (possible values given later).
CELogLevel	Defines a default logging level for any Content Engine subsystem for which no explicit value is given by the setting above. This can be used for example to set a minimum level of, say, Warning across all subsystems.

The possible values for XYZ (the subsystem identifier) are the abbreviations from the server logging subsystem table and must be given in matching case.

Process Engine settings

Process Engine API logging refers to both logging by true client applications and by certain server-side components which are logically clients of the core server (such as the REST servlet). For the latter, the configuration settings must be applied to the server JVM.

Process Engine API logging has been moved to a subsystem-based configuration model, aligning it with that of the Content Engine. The Process Engine settings follow the same pattern as for the Content Engine, with the following supported settings:

Setting	Description and usage
PESubSystem.XYZ	Specifies the logging level for a subsystem identified by XYZ (possible values given later). Note that there is no Timer level for Process Engine tracing.
PELogLevel	Defines a default logging level for any Process Engine subsystem for which no explicit value is given by the setting above. The same values are accepted.

The Process Engine subsystem identifiers (XYZ in the above), which again must be given in matching case, are listed in the following table.

Activity	Subsystem identifier
General API operations	API
Applications (selectwf and taskman)	APPS
Toolkit activities	TKIT
Component Integrator	CMPI
WSDL API	WSDL
PE web service API	PEWS
Process Orchestration web service	POWS
Content Engine inter-operation	CEIF
Applet communications	ACOM
API transport logging	TSPT
RPC to server	RPC
Content Operations	COOP
REST service	REST
Case Analyzer	CA
Case History	CH

FileNet Deployment Manager Logging

FileNet Deployment Manager (FDM) is a client of both the Content Engine and Process Engine APIs, so any of the above described settings can be applied to the FileNet Deployment Manager process. In addition, there are two further subsystem settings specifically for FileNet Deployment Manager:

CESubSystem.FDM, for logging by FileNet Deployment Manager
CESubSystem.IMEX, for logging in the import-export library that is used by FileNet Deployment Manager

Logging for these subsystems can be enabled exactly as previously explained, in any combination with other Content Engine and Process Engine API subsystems.

[1] For Windows systems, either backslashes must be doubled in a properties file, or single forward slashes can be used instead.