Documentation Center

Admin.XMLBackgroundTaskConfiguration.xml

The Admin.XMLBackgroundTaskConfiguration.xml file contains the data that enables the handling and processing of background tasks.

Changelog

File versionContent Manager versionNotes
1.011.0.0n/a
1.111.0.1Introducing IBackgroundTaskHandler, an extra handler .NET element to configure handlers in .NET.

Introduction

The background task configuration is accessible from the Content Manager Web Client using Settings > XML Background Task Settings

This configuration file contains
  • Service definitions with all information for a specific service role.
  • Handler definitions with the configuration for handling background tasks.

Service definition

Overview

Each service definition is identified by its role (e.g. Default).

The service definition specifies which of the following components the service is executing:
  • The poller component tries to get the next background task which can be executed by this service. The background tasks which can be polled are specified in the availability matrix.
  • The leaseRecovery component searches for background tasks which (probably) have failed because they are blocked/leased longer than the expected execution time extended with the grace period.
  • The aggregationRecovery component processes aggregations which failed during the synchronous processing
XML elements
NameDescription
serviceContains the service definition
service @roleIdentifies the behavior of the service
matrixContains the availability matrix which specifies for every group of event types the maximum number of parallel executions
groupGroups event types which have similar execution requirements
group @nameThe name of the group
group @maxExecutionsThe maximum number of parallel executions for this group
handlersContains the references to the handlers within this group
addThe reference to the handler with a specific event type
add @refThe name of the event type which needs to match with the eventType of one of the handler definitions
leaseRecoveryContains the configuration for the lease recovery
leaseRecovery @isEnabledSpecifies if the current service will do any lease recovery
leaseRecovery @intervalContains a time (in TimeSpan format) indicating how long the service will wait before searching for another blocked background task.
pollerContains the configuration for the poller
poller @isEnabledSpecifies if the current service will poll for background tasks to execute
poller @interval

Contains a time (in TimeSpan format) indicating how long the service will wait before searching for another background task.

aggregationRecoveryContains the configuration for the aggregation recovery
aggregationRecovery @isEnabledSpecifies if the current service will do any aggregation recovery
aggregationRecovery @gracePeriodSpecifies within which period (in TimeSpan format) the synchronous execution has to finish the aggregation before the service will start the recovery
aggregationRecovery @interval

Contains a time (in TimeSpan format) indicating how long the service will wait before searching for another aggregation task.

aggregationRecovery @maximumRetriesSpecifies the maximum number of attempts for the aggregation recovery
Example
<service role="Default">
  <matrix>
    <group name="Translations" maxExecutions="2">
      <handlers>
        <add ref="CREATETRANSLATIONFROMREPORT" />
        <add ref="CREATETRANSLATIONFROMLIST" />
        <add ref="CREATETRANSLATION" />
        <add ref="RELEASETRANSLATIONS" />
      </handlers>
    </group>
    <group name="Export" maxExecutions="2">
      <handlers>
        <add ref="EXPORTFORPUBLICATION" />
        <add ref="INBOXEXPORT" />
        <add ref="REPORTEXPORT" />
        <add ref="SEARCHEXPORT" />
        <add ref="PUBLICATIONEXPORT" />
      </handlers>
    </group>
    <group name="SynchronizeToLiveContent" maxExecutions="1">
      <handlers>
        <add ref="SYNCHRONIZETOLIVECONTENT" />
      </handlers>
    </group>
    <group name="Others" maxExecutions="2">
      <handlers>
        <add ref="THUMBNAILSUBMIT" />
        <add ref="ISHBATCHIMPORT" />
      </handlers>
    </group>
  </matrix>
  <leaseRecovery isEnabled="true" interval="00:05:00" />
  <poller isEnabled="true" interval="00:00:05" />
  <aggregationRecovery isEnabled="true" gracePeriod="00:10:00" interval="00:10:00" maximumRetries="3" />
</service>

Handler definition

XML elements
NameDescription
handlerContains the handler definition.
handler @eventTypeDefines the name of the event type.
schedulerDefines the schedule for the background task.
scheduler @executeSynchronouslySpecifies whether the background task is executed synchronously or asynchronously.
authorizationSpecifies the authorization used for the background task.
authorization @typeDefines the authorization type. For all legacy COM+ IEventHandler handlers, the authorization must be "authenticationContext".
executionContainer for the background task execution configuration.
execution @timeoutDefines the timeout interval for the background task in TimeSpan format.
execution @recoveryGracePeriodIf the background task times out, this attribute defines the grace period interval in TimeSpan format; when the grace period expires, the service starts recovery.
execution @isolationLevelDefines if the background task is executed in the same process as the service (None), in a new process (Process), or in a new AppDomain within the same process as the service (AppDomain).
execution @useSingleThreadApartmentDefines whether the background task must be executed with Single Thread Apartment.
activatorContainer for the activator configuration.
comIEventHandlerContainer for the COM+ IEventHandler activator configuration.
comIEventHandler @projectNameDefines the project name (e.g ISAuthorIso).
comIEventHandler @classNameDefines the class name (e.g CTranslationMgmt).
configurationContains all required information for the background task execution. The data is passed to the handler executing the background task.
netContains the configuration for the .NET activator.
net @nameSpecifies the handler name.
parametersContains parameters required to execute the background task.
parameterContains a value for a single parameter required to execute the background task.
parameter @nameSpecifies the name of the parameter required to execute the background task.
errorHandlerConfigures the error handling of the background task service which is limited to deciding if the task should be retried or not when a specific error is thrown by the background task handler.
errorHandler @maximumRetries
Specifies how many attempts will be executed when a background task fails
actionsConfigures the actions during error handling
addConfigures the action for a specific error
add @errorNumberContains the error number
add @actionSpecifies the action for a specific error. The possible values are
  • "Retry" to indicate that the background task must be retried for this error.
  • "Ignore" to indicate that the background task should not be retried for this error.
add @delayOptional attribute indicating if the retry must be delayed or can be done immediately
Example
<handler eventType="CREATETRANSLATIONFROMREPORT">
  <scheduler executeSynchronously="false"/>
  <authorization type="authenticationContext"/>  
  <execution timeout="01:00:00" recoveryGracePeriod="00:10:00" isolationLevel="None" useSingleThreadApartment="true"/>
  <activator>   
    <comIEventHandler projectName="ISAuthorIso" className="CTranslationMgmt">
      <configuration>
        <parameters>
          <parameter name="batchsize" type="value">1000</parameter>
        </parameters>
      </configuration>
    </comIEventHandler>
  </activator>
  <errorHandler maximumRetries="3">
    <actions>
    <add errorNumber="*" action="Retry" delay="00:01:00"/>
    </actions>
  </errorHandler>
</handler>

Remarks

For the interval and period attributes, we are expecting TimeSpan format. The following table contains some examples:
TimeSpanExplanation
00:00:055 seconds
00:10:0010 minutes
01:00:001 hour
1.00:00:0024 hours or 1 day
24:00:0024 days (not 24 hours)