Troubleshooting and FAQ

This section presents an overview of troubleshooting topics.

Client-side logging

As a starting point for an error analysis you should consult the FIS log file “ImageMaster.log”. Within a command line interface call the location of the log file can be specified by the option:

-l <log directory>

By default the log file is written into the working directory of FIS.

Setting the initial log level

You may set the initial log level with the following environment variable:

ima_loglevel

The following log levels are available: SEVERE, WARNING, INFO, FINE, FINER, FINEST. In a Windows environment you can set the log level with the export command in the console which is used for starting FIS, e.g.:

export ima_loglevel=INFO

The log level may automatically change during a FIS run. As soon as FIS has established a connection with the server, the server-side log level will be set.

Server-side logging

The ImageMaster AdminClient [UM AdminClient] provides facilities for tuning the server-side log files of ImageMaster components. Here you may adjust the log level of the following class, which represents the FIS component:

com.tsystems.ima.fis

Protocol files

Protocol files will provide additional information in import processes on single items which are processed by FIS. They indicate one of the states (also see Directories and files for FIS import):

• error: indicating an error

• success: indicating successful processing

• state: indicating a running process

If protocol files are missing, check whether one of the scenarios from chapter FIS behavior in specific scenarios applies. No protocol files will be written in both of the following cases:

• An empty directory is targeted by the process.

• A non existing batch directory has been specified.

Separator character within pathname strings

The separator character, which must be used within pathname strings, depends on the underlying operating system. It will be one of the following options:

• “/” i.e. a slash for UNIX based systems

• “\”i.e. a back slash for Windows systems

Within the underlying JAVA implementation the system property “file.separator” is used for determining the valid separator.

The error message in such a case will indicate a parsing error:

FIS-00037: Error parsing metadata file

The message may also claim that the path is not absolute:

- Binary file location 'Z:/CIAO/2011/01/03/KKB_AFP_DBMXCNNB_KD_M1802_30122010.20101230234923_1of1/KKB_AFP_DBMXCNNB_KD_M1802_30122010.20101230234923_1of1.0000001.pdf' does not match the configuration. The file path has to be 'absolute'. –

License violation

If a license violation error is displayed, do the following:

• Check whether the license file is present in the class path directory which is defined in the starting script (see FIS start script – class path configuration and run parameters).

• Check whether the registered licenses are valid (see FIS basics chapter License information).

• Check the proper spelling of the FIS command, which is case-sensitive with an initial capital letter e.g. “ArchiveDocuments”.

Deletion of a revision fails

A revision cannot be deleted if it is the only revision left within one document (also see hint in section Example search definitions for deletion in chapter Search definition file for deletion).

SSL error “could not locate keystore”

If an SSL error occurs with a message such as “Could not locate Keystore”, make sure that there are no trailing blanks in the configuration file FIS.cfg particularly at line endings.

FIS process interruption recovery

In cases where the FIS process is interrupted, e.g. due to a hardware failure, it may be necessary to manually fix the status of the documents, which were being processed. Depending on the level of concurrency, this will only concern a few documents. If no parallel processing is used, there is only one document that could be affected. The FIS recovery operations manual [OM FIS Recovery] provides information on how to recover FIS processing in such a scenario.

Avoiding error “noroutetohostexception” in high performance scenarios

In scenarios where a great number of documents have to be processed in parallel, make sure to apply tuning parameters according to section “HTTP connection tuning for high performance scenarios”. If this is not done, it is likely that the exception “NoRouteToHost” occurs for a certain amount documents, which will then not be processed, because the system cannot allocate enough connections in parallel.

Processing large files depends on application server configuration

In the ImageMaster application server configuration a maximum post size can be set. If such a limit is set, make sure that the files to be archived by FIS do not exceed this limit or set the maximum post size to unlimited. For related details see the installation manual [IM ImageMaster].

The log file excerpts below illustrate the error output in such cases:

FIS client-side log file – Imagemaster.log

Application server – ImageMaster.log (example based on WildFly in subdirectory …/standalone/log/)

Application server – Server.log (example based on WildFly in subdirectory …/standalone/log/)

Unexpected errors related to character encoding

In case of unexpected errors that you cannot explain, check related configuration or control files for artifacts and broken special characters that may have resulted from a copy and paste action.

Unsupported key attribute type “text” causes errors

Some FIS operations rely on the internal “search by key” mechanism which expects key attributes as input parameters:

• searchLatestRevisionByKey

• searchAllRevisionsByKey

You can use the attribute type “string” instead, which has a size limitation, however, in contrast to the type “text”. String attributes by default support a length of 1000. Depending on your database, this limit can be increased by a database setting.