Note: this component has a complexity level of "expert", which means that objects of this type are not expected to be created or altered. Please contact support for assistance if you believe that you have a need to create or modify this type of object.
Exec Recurring Tasks can be used to execute a specified command on a regular basis.
↓Parent Component
↓Properties
↓dsconfig Usage
The Exec Recurring Task component inherits from the Recurring Task
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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}