Exec Recurring Task

Exec Recurring Tasks can be used to execute a specified command on a regular basis.

Parent Component Properties dsconfig Usage

Parent Component

The Exec 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
 command-path
 command-arguments
 command-output-file-base-name
 retain-previous-output-file-count
 retain-previous-output-file-age
 log-command-output
 task-completion-state-for-nonzero-exit-code
 working-directory

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

command-path

Description
The absolute path to the command to execute. It must be an absolute path, the corresponding file must exist, and it must be listed in the config/exec-command-whitelist.txt file.
Default Value
None
Allowed Values
A filesystem path
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

command-arguments

Description
A string containing the arguments to provide to the command. If the command should be run without arguments, this property should be left undefined. If there should be multiple arguments, then they should be separated with spaces. If there are any special characters in any of the arguments (for example, spaces, quotation marks, asterisks, or backslashes), they should be escaped in exactly the same way as when running the corresponding command in a terminal.
The command will be invoked with a working directory that is set to the server root. If any of the command arguments represents a relative path, that path should be interpreted as relative to the server root.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

command-output-file-base-name

Description
The path and base name for a file to which the command output (both standard output and standard error) should be written. This may be left undefined if the command output should not be recorded into a file. If a value is provided, then the actual name for the output file for each task instance will be this base name followed by a period and a generalized time representation of the task's scheduled start time. The directory to which the output file will be written must already exist.
Default Value
None
Allowed Values
A filesystem path
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

retain-previous-output-file-count

Description
The minimum number of previous command output files that should be preserved after a new instance of the command is invoked. If a command-output-file-base-name value is set, then at least one of the retain-previous-output-file-count and retain-previous-output-file-age properties must also be set.
If both the retain-previous-output-file-count and retain-previous-output-file-age properties are set, then only output files that are outside the criteria for both properties will be considered for removal. If only one of these properties has a value, then only the criteria associated with that property will be used to determine which previous output files will be retained.
Default Value
If a retain-previous-output-file-age value is configured, then only that property will be used to determine which output files to retain, and any output files older than that may be removed.
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

retain-previous-output-file-age

Description
The minimum age of previous command output files that should be preserved after a new instance of the command is invoked. If a command-output-file-base-name value is set, then at least one of the retain-previous-output-file-count and retain-previous-output-file-age properties must also be set.
Values for this property should use the duration syntax, which consists of an integer value followed by a time unit (for example, "1w" for one week, "5d" for five days, or "12h" for twelve hours).
If both the retain-previous-output-file-count and retain-previous-output-file-age properties are set, then only output files that are outside the criteria for both properties will be considered for removal. If only one of these properties has a value, then only the criteria associated with that property will be used to determine which previous output files will be retained.
Default Value
If a retain-previous-output-file-count value is configured, then only that property will be used to determine which output files to retain, and any output files older than that may be removed.
Allowed Values
A duration. Lower limit is 0 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

log-command-output

Description
Indicates whether the command's output (both standard output and standard error) should be recorded in the server's error log. If this property is set with a value of true, then any non-blank lines written to either standard output or standard error will be written to the server's error log, and also captured in the task entry.
This option should generally only be considered for commands that produce text-based output. It is not recommended for commands whose output may contain bytes that do not represent printable characters or for commands whose output may contain text with very long lines (for example, thousands of characters per line). For commands that may produce non-text output, or for commands that may produce text output with very long lines, capturing the output in a file (via the command-output-file-base-name property) is a better option.
You may also want to avoid this option for tasks that produce a lot of output. In addition to the server error log, these log messages will be recorded in the task entry. For commands that generate a lot of output, this can cause a lot of updates to the task backing file. Further, because the server imposes an upper limit on the number of log messages that it will retain in the task entry (as controlled by the maximum-initial-task-log-messages-to-retain and maximum-final-task-log-messages-to-retain properties in the task backend configuration), only a portion of these messages may be retained in the task entry. This restriction does not apply when capturing the output in a file.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

task-completion-state-for-nonzero-exit-code

Description
The final task state that a task instance should have if the task executes the specified command and that command completes with a nonzero exit code, which generally means that the command did not complete successfully.
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

working-directory

Description
The absolute path to a working directory where the command should be executed. It must be an absolute path and the corresponding directory must exist.
Default Value
If this property is not specified, then the server instance root will be used as the default working directory.
Allowed Values
A filesystem path
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 Exec Recurring Task:

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

To delete an existing Recurring Task:

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