Delay Recurring Task

Delay Recurring Tasks can be used to wait for a specified length of time or until a specified condition is satisfied. It is primarily intended to be used between other recurring tasks to allow the server or clients a chance to perform some kind of "catch up" between tasks.

Parent Component Properties dsconfig Usage

Parent Component

The Delay Recurring Task component inherits from the Recurring Task

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  None
 cancel-on-task-dependency-failure
 email-on-start
 email-on-success
 email-on-failure
 alert-on-start
 alert-on-success
 alert-on-failure
 sleep-duration
 duration-to-wait-for-work-queue-idle
 ldap-url-for-search-expected-to-return-entries
 search-interval
 search-time-limit
 duration-to-wait-for-search-to-return-entries
 task-return-state-if-timeout-is-encountered

Basic Properties

description

Description
A description for this Recurring Task
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

cancel-on-task-dependency-failure

Description
Indicates whether an instance of this Recurring Task should be canceled if the task immediately before it in the recurring task chain fails to complete successfully (including if it is canceled by an administrator before it starts or while it is running). If this is true, then the instance of this Recurring Task will also be considered a failure (with a state of "canceled before starting"), and if that instance is itself a dependency for any other Recurring Task instance, then that dependent task's cancel-on-task-dependency-failure property will be used to determine whether it should be canceled or preserved.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

email-on-start

Description
The email addresses to which a message should be sent whenever an instance of this Recurring Task starts running. If this option is used, then at least one smtp-server must be configured in the global configuration.
Default Value
No email message will be sent when instances of this Recurring Task start running.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

email-on-success

Description
The email addresses to which a message should be sent whenever an instance of this Recurring Task completes successfully. If this option is used, then at least one smtp-server must be configured in the global configuration.
Default Value
No email message will be sent when instances of this Recurring Task finish running.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

email-on-failure

Description
The email addresses to which a message should be sent if an instance of this Recurring Task fails to complete successfully. If this option is used, then at least one smtp-server must be configured in the global configuration.
Default Value
No email message will be sent when instances of this Recurring Task fail to complete successfully.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

alert-on-start

Description
Indicates whether the server should generate an administrative alert whenever an instance of this Recurring Task starts running.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

alert-on-success

Description
Indicates whether the server should generate an administrative alert whenever an instance of this Recurring Task completes successfully.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

alert-on-failure

Description
Indicates whether the server should generate an administrative alert whenever an instance of this Recurring Task fails to complete successfully.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

sleep-duration

Description
The length of time to sleep before the task completes. If this property has a value, and at least one of the duration-to-wait-for-work-queue-idle and ldap-url-for-search-expected-to-return-entries properties has a value, then the task will wait for the configured sleep duration after waiting for the other conditions to be met.
At least one of the sleep-duration, duration-to-wait-for-work-queue-idle, and ldap-url-for-search-expected-to-return-entries properties must have a value.
Default Value
None
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

duration-to-wait-for-work-queue-idle

Description
Indicates that task should wait for up to the specified length of time for the work queue to report that all worker threads are idle and there are no pending operations. Note that this primarily monitors operations that use worker threads, which does not include internal operations (for example, those invoked by extensions), and may not include requests from non-LDAP clients (for example, HTTP-based clients). If this property has a value, then the server will wait for the specified length of time for the work queue to report that it is idle. Note, however, that this may be a momentary condition and that there is no guarantee that the work queue will remain idle for any additional length of time (including the remaining duration of the task). If that is necessary, then it is recommended that some other mechanism (for example, placing the server in lockdown mode, or configuring the Directory Proxy Server to route around the server) be used to ensure that clients will not submit further requests.
If the work queue does not report that it is idle within the configured duration, then the task will use the return state specified by the task-return-state-if-timeout-is-encountered property.
If this property is used in conjunction with the sleep-duration property, then the sleep duration will be observed after the work queue reports that it is idle (or until the timeout occurs, whichever comes first).
At least one of the sleep-duration, duration-to-wait-for-work-queue-idle, and ldap-url-for-search-expected-to-return-entries properties must have a value.
Default Value
None
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

ldap-url-for-search-expected-to-return-entries

Description
An LDAP URL that provides the criteria for a search request that is expected to return at least one entry. The search will be performed internally, and only the base DN, scope, and filter from the URL will be used; any host, port, or requested attributes included in the URL will be ignored. For example, the LDAP URL "ldap:///cn=monitor??base?(!(unavailable-alert-type=*))" could be used to wait until the server's general monitor entry does not report any unavailable alert types. Similarly, the URL "ldap:///cn=monitor??base?(!(degraded-alert-type=*))" could be used to wait until there are no degraded alert types.
If this property has a value, then all of the search-interval, search-time-limit, and duration-to-wait-for-search-to-return-entries properties must also have values, and the server will perform repeated internal searches with a time limit specified by the search-time-limit property and an interval specified by the search-interval property. The search will be repeated until it returns at least one entry or until the length of time specified by the duration-to-wait-for-search-to-return-entries property has elapsed. If the duration-to-wait-for-search-to-return-entries time elapses without the search matching any entries, then the task will use the return state specified by the task-return-state-if-timeout-is-encountered property.
If this property has multiple values, then the searches will be performed consecutively, allowing for up to the duration-to-wait-for-search-to-return-entries time for each of the searches.
If this property is used in conjunction with the sleep-duration property, then the sleep duration will be observed after all of the internal searches have been performed.
At least one of the sleep-duration, duration-to-wait-for-work-queue-idle, and ldap-url-for-search-expected-to-return-entries properties must have a value.
Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

search-interval

Description
The length of time the server should sleep between searches performed using the criteria from the ldap-url-for-search-expected-to-return-entries property. If this property has a value, then all of the ldap-url-for-search-expected-to-return-entries, search-time-limit, and duration-to-wait-for-search-to-return-entries properties must also have values, and the search-interval value must be less than the duration-to-wait-for-search-to-return-entries value.
Default Value
None
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

search-time-limit

Description
The length of time that the server will wait for a response to each internal search performed using the criteria from the ldap-url-for-search-expected-to-return-entries property. If this property has a value, then all of the ldap-url-for-search-expected-to-return-entries, search-interval, and duration-to-wait-for-search-to-return-entries properties must also have values, and the search-time-limit value must be less than the duration-to-wait-for-search-to-return-entries value.
Default Value
None
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

duration-to-wait-for-search-to-return-entries

Description
The maximum length of time that the server will continue to perform internal searches using the criteria from the ldap-url-for-search-expected-to-return-entries property. If this property has a value, then all of the ldap-url-for-search-expected-to-return-entries, search-interval, and duration-to-wait-for-search-to-return-entries properties must also have values, and the duration-to-wait-for-search-to-return-entries value must be greater than both the search-interval and search-time-limit values.
Default Value
None
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

task-return-state-if-timeout-is-encountered

Description
The return state to use if a timeout is encountered while waiting for the server work queue to become idle (if the duration-to-wait-for-work-queue-idle property has a value), or if the time specified by the duration-to-wait-for-search-to-return-entries elapses without the associated search returning any entries.
Default Value
stopped-by-error
Allowed Values
stopped-by-error - Indicates that the task encountered an unrecoverable error and should not be considered successful. If there are any other tasks dependent upon this task, then those tasks may be canceled in accordance with the cancel-on-task-dependency-failure property.

completed-with-errors - Indicates that the task completed but encountered one or more errors and was therefore not completely successful. However, if there are any other tasks dependent upon this task, then those tasks will not consider this task to have been a failure, so the cancel-on-task-dependency-failure property will not come into play.

completed-successfully - Indicates that the task processing should be considered to have been completely successful.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Recurring Tasks:

dsconfig list-recurring-tasks
     [--property {propertyName}] ...

To view the configuration for an existing Recurring Task:

dsconfig get-recurring-task-prop
     --task-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Recurring Task:

dsconfig set-recurring-task-prop
     --task-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new Delay Recurring Task:

dsconfig create-recurring-task
     --task-name {name}
     --type delay
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Recurring Task:

dsconfig delete-recurring-task
     --task-name {name}