Using Archiver Replication Exceptions

This chapter explains how to use the Archiver Replication Exceptions feature to prevent failed Archiver imports from stopping replication in a Content Server instance.

This chapter covers the following topics:

• Understanding Archiver Replication Exceptions

• Administering and Using Archiver Replication Exceptions

Understanding Archiver Replication Exceptions

Archiver Replication Exceptions enables administrators to prevent failed imports from stopping replication. It does this by capturing such failed imports and putting them into an exceptions archive and sending email to the administrator that such a failed import has occurred.

The ArchiverReplicationExceptions component is installed and enabled by default with the Content Server instance.

• How Archiver Replication Exceptions Works

• Scenario 1

• Scenario 2

How Archiver Replication Exceptions Works

Several configuration entries must be manually added to the IntradocDir/config/config.cfg file to support Archiver Replication Exceptions. The configuration entries define a variety of conditions to determine the level of error reporting, to direct failed imports to an exceptions directory, and to ignore and handle multiple failed imports when a systemic error is detected. Parameters for both automatic and manual imports are provided.

Scenario 1

In this scenario an import of a document has failed because the content type “DOC” does not exist in the importing server. The error reporting level (ArchiverEmailErrorLevel) was set to collision, standard, severe, and the ArchiverErrorNotifyUser was set to sysadmin. The following is an example of an archiver import failure email notification:

Archiver Import Failure
There was a serious error during the import of a document which may prevent that 
document from being properly synchronized in state with the exporting content 
server. Content item 'test1' was not successfully checked in. The content 
type 'DOC' is not defined in the system.
Revision Being Imported
Collection:  idc
Archive Name:  ar1
Source Instance:  idc
Batch Name:  07-sep-24_15.15.41_766/07267151541~1.hda
Content ID:  test1
Title:  test1
Author:  sysadmin
Revision:  1
Release Date:  9/24/07 3:13 PM
Create Date:  9/24/07 3:14 PM

The Document Has Been Copied To An Exceptions Archive

Collection:  idc
Archive Name:  ImportExceptions
Batch Name:  07-sep-24_15.15.41_766/07267151541~1.hda
Total Captured In Archive:  1

Scenario 2

In this scenario an import is being attempted but continually fails. The system administrator is aware that there may be problems during the import, but does not want an email notification of every failure. By setting ArchiverMaxConsecutiveImportErrors (default is 10), the system administrator can set several failures that can occur before the cessation of email notification. E-mail is sent until this number of errors is reached. If any import from the exporter should succeed before the set number is reached, or if the Content Server instance is restarted, the counter is reset to 0. Note that when the maximum number of errors is reached the automated import of the archive is aborted.

Administering and Using Archiver Replication Exceptions

The primary purpose for the Archiver Replication Exceptions feature is to allow filtering of failed Archiver imports to optimize the handling and notification of such failures. For content items to be processed by Archiver Replication Exceptions, the administrator must manually set configuration entries in the IntradocDir/config/config.cfg file. The configuration variables customize the behavior of the importing Content Server instance to allow for certain situations and to distribute the error reporting based on the configured criteria.

The following configuration variables can be used to customize behavior. These values should be set in the IntradocDir/config/config.cfg file under #Additional Variables.

By prepending any of the configuration entries with the name of an archive, with a colon (:) as a separator, that configuration entry will only apply to that archive. For example, to enable capturing exceptions for the archive MyRemoteImportArchive, use the following entry in the config.cfg file:

MyRemoteImportArchive:IsArchiverCapturingExceptions=true

If an archive name prefix is not applied, then the value set is the global default for all archives.

• IsArchiverCapturingExceptions: The primary functionality of this component is not enabled unless this configuration entry is turned on.

  The default value is false.

• ArchiverImportExceptionsArchiveName: The name of the archive to hold failed imports. The archive will be created in the same archive collection as the archive that contained the document that failed an import.

  The default value is ImportExceptions.

• ArchiverMaxConsecutiveImportErrors: The maximum number of consecutive import errors before the import of the archive is aborted.

  The default value is 10.

• ArchiverErrorNotifyUser: The user to notify when there is an import failure. The default is sysadmin. The email is generated only if the import error is at a level that is configured to generate email.

  The entry can be a comma separated list of user names, but all the user names have to be defined in the Content Server instance and have associated email addresses.

• ArchiverEmailErrorLevels: The error levels at which an import error should generate email during automated import. The possible levels are as follows:

  • collision:The import failed because an existing revision of a document blocked it. Usually this is caused by the importing revision having a release date (or create date depending on configuration) that is earlier than the date of the latest revision of an existing document.

  • standard:The import failed because of a normal error. A typical such error would be a metadata field that has an invalid value.

  • severe:The import failed because of a severe unexpected error in the Content Server instance. A typical reason for this might be a network failure to either the file system or database.

  The configuration entry is set to a comma separated list of any of the above values. If an automated import error occurs, it is classified in one of the above levels and if the level is in the list configured for this parameter then an email is generated for that error.

  The default value is collision,standard,severe (or all).

• ArchiverManualImportEmailErrorLevels: This is similar to ArchiverEmailErrorLevels except it applies to manual archive imports. A manual import is one directly driven by an end user or administrator and is not part of an import done by a “registered automated importer”.

  The default value is empty (or none).

• ArchiverCaptureExceptionErrorLevels: A list of error levels for which an import error should capture a copy of the document and put it into the exceptions archive (see ArchiverImportExceptionsArchiveName). If the document is captured then the error will not stop an automated import. The automated import will delete the document from the archive when the batch file containing the document has been fully imported. See ArchiverEmailErrorLevels for a list of error levels and how to configure the entry.

  The default value is collision,standard.

• ArchiverManualImportCaptureExceptionErrorLevels: This is similar to the ArchiverCaptureExceptionErrorLevels parameter except it applies to manual archive imports (see ArchiverManualImportEmailErrorLevels for more on manual imports). If an import error is captured it is copied into the exceptions archive but it does not delete it from the originating archive. If the error is captured it will not count against the maximum number of errors allowed during a manual import (see the standard Content Server configuration entry MaxArchiveErrorsAllowed which defaults to 50).

  The default value is empty (or none).

• ArchiveExceptionsMaxNumberDocuments: The maximum number of documents that can be stored in the exceptions archive.

  When this number is reached, then import failure will again prevent continued automated import. However, email is sent to ArchiverErrorNotifyUser indicating that the import failed and that the exceptions archive is full. Unlike the other configuration entries, if you use an archive prefix (separated by a colon) to limit the configuration entry to a particular archive, the archive name must be the name of the exceptions archive not the archive with the originating documents being imported.

  The default value is 50.

The parameter ArchiverMaxConsecutiveImportErrors addresses the issue of skipping over errors and sending email notifications on the errors when the error is caused by a systemic problem (such as all documents having the same wrong metadata field on export). This results in numerous documents being unnecessarily captured and generating the attendant volume of unwanted email. This configuration entry helps detect such scenarios. During an automated import, if too many consecutive import errors are detected, then the current archive import is aborted. Manual imports follow the standard rules for maximum errors (see MaxarchiveErrorsAllowed).If any import (from any archive) is successful, then the consecutive import failure count is reset to 0.

If the same document fails an import (twice or more) sequentially email is sent out only for the first failure. If the same document fails an import but is from a different batch load file, the email for it is not suppressed if email for that document has already been sent for a previous error.