Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Using the Task Manager

Using the Task Manager

To use the Task Manager, select System Operation > Task Manager) to display the following menu options:

You can also interact with the Task Manager using the InterSystems Terminal, as described in the Using ^TASKMGR section.

Note:

The Task Manager polls every 60 seconds to see if there are any Tasks to be run. When you click Perform Action Now to schedule a Task, there may be a delay of up to 60 seconds before the newly scheduled Task actually runs.

New Task

The New Task option starts the Task Scheduler Wizard.

  1. On the first page of the Task Scheduler Wizard, provide the following details about the new task:

    • Task name

    • Description

    • Namespace to run task in — Choose from the list of defined namespaces in which to run the task

    • Task type — Choose from among the listed tasks. For details about the available tasks, see Task Types below.

      Note:

      Depending on the task type selected, you may be presented with a form in which to specify additional information; for example, if you are scheduling an IntegrityCheck, the form prompts you for Directory, Filename, and KeepDays (number of days to keep the file).

    • Task priority — Choose from Priority Normal, Priority Low, or Priority High. For more information about priority, read the Priority section of the “Process Management” chapter in Specialized System Tools and Utilities.

    • Run task as this user — Choose from the list of defined users. To choose a different user than the one you are logged in as, you must have the %Admin_Secure:Use privilege.

      Note:

      If the chosen user is disabled, the task is suspended until the user is enabled and the task is resumed manually. This does not apply to built-in System tasks, which run even when the chosen user is disabled.

      Each task consumes a license unit, with the license user ID based on the Caché username you select; see License Login Special Considerations in the “Managing Caché Licensing” chapter of this guide for more information.

    • Open output file when task is running and Output file — If the task creates output, the log file is written to the directory specified.

    • Suspend task on error? — Specify whether the task will be rescheduled and continue to run after an error, or suspended. The default is No, to reschedule and run the task after an error.

    • Reschedule task after system restart? — Specify whether you want to reschedule the task when the system restarts (that is, if the system is down when the task is scheduled to run):

      • No specifies that the task should run when the system restarts.

      • Yes specifies that the task should be rescheduled for the next logical time after the system restarts.

    • Send completion email notification to — If you have configured email settings for the Task Manager (see Configuring Task Manager Email Settings in the “Configuring Caché” chapter of this guide), enter a comma-separated list of email addresses to which a notification should be sent when the task ends successfully.

    • Send error email notification to — If you have configured email settings for the Task Manager, enter a comma-separated list of email addresses to which a notification should be sent when the task ends in error.

    • How should task run for Mirror — If this instance is a mirror member, specify the type of member the task can be run on:

      • run on primary failover member only

      • run on backup failover member and async members only (all except primary)

      • run on all mirror members (primary, backup, and asyncs)

      Important:

      This setting must be set for all tasks on the mirror member, the task will not run on a mirror member if not. Adding an instance to a mirror member does not automatically update this setting in user-defined tasks. As such, you must either:

      • Define this setting when you create a task even if the instance is not a mirror, so it can run if the instance is added to a mirror.

      • Make sure you review all user-defined tasks when an instance is added to a mirror and set How should task run for mirror.

      Note:

      When the status of a failover member is in transition, for example when the backup is in the process of taking over as primary, the Task Manager does not run any tasks on that member until its status as primary or backup is established.

    After you have filled in all the necessary fields, click Next.

  2. On the second page of the Task Scheduler Wizard, specify when the new task should run. The options are:

    • Daily — A daily interval (for example, every other day, or every third day).

    • Weekly — A weekly interval on specific days of the week.

    • Monthly — A monthly interval on a specific day of the month.

    • Monthly (by day) — A monthly interval on a specified day of the week (for example, first Monday, or third Wednesday).

    • After another task completes — After a specified task runs.

    • On demand — Only when manually executed.

    The Daily, Weekly, Monthly, and Monthly (by day) fields allow you to specify what time during the day the task should run:

    • Start Date — The first day the scheduled task should run.

    • End Date — The last day the scheduled task should run.

    • Task execution details, which specify what happens when a task executes as follows:

      • Run once at this time — At the specified time, the task executes once.

      • Run every ____ — During the specified time range, the task executes repeatedly at the specified interval.

      Note:

      By default, all new tasks expire if they miss their scheduled time for any reason. If you wish to change this behavior, see Changing Task Expiration Behavior below.

    After you have filled in all the necessary fields, click Finish to schedule the task.

Task Types

This section describes the predefined task types you can choose when creating or editing a task. Some tasks are only available from certain namespaces.

Note:

You can define your own task types using the %SYS.Task.Definition API; see the class documentation in the InterSystems Class Reference.

  • CheckLogging — creates an alert or turns off ^%ISCLOG or ^ISCSOAP logging if it has been running too long (by default, 2 days)

  • CleanSQLIndex— cleans up stale SQL Statement Index entries

  • CumuIncrDBList — a cumulative backup of databases in the defined list

  • DiagnosticReport — collects and delivers diagnostic reports to the WRC

  • FullAllDatabases — a full backup of all databases

  • FullDBList — a full backup of databases in the defined list

  • IncrementalDBList — an incremental backup of databases in the defined list

  • IntegrityCheck — an integrity check of databases in the namespace. The Integrity Check task only appears when the %SYS namespace is selected.

  • InventoryScan — compiles an inventory scan of the instance

  • PurgeAudit — purge the audit database after a specified time following a journal switch

  • PurgeBackupLog — purge the backup log after a specified time following a database backup

  • PurgeErrorsAndLogs — purge error globals and cconsole.log based on settings in the cache.cpf file (see ErrorPurge and MaxConsoleLogSize parameters in the Startup section of the “Introduction to the Caché Parameter File” chapter of the Caché Parameter File Reference)

    Note:

    When System Monitor is running, it monitors and limits the size of the console log.

  • PurgeJournal — purge journal files that meet the purging criteria

  • PurgeTaskHistory — purge task manager history files

  • RunLegacyTask — run a legacy task, that is, your own programmatic task; the line you enter in the text box, for example do ^MyCode, must be executable in the Terminal

    Note:

    Do not use the local variable Status in RunLegacyTask code. Caché uses this variable, and if it is modified by RunLegacyTask code, the task is likely to end with an error status.

    A legacy task that fails to complete due to an error is marked Suspended due to error and is not scheduled to run until the error is corrected and you resume the task.

  • SecurityScan — disables expired user accounts, and expires user passwords and CSP session tokens

  • ShadowPurge — purge shadow files

  • SuspendOnError — determines what happens if the Task returns an error %Status from the OnTask() method. Errors encountered by the Task Manager trying to execute the task (login error or no such Task found) do not check this flag.

  • SwitchJournal — switch to a new journal file

  • UpdateSQLStats — updates the information on SQL query statistics

On-demand Task

The On-demand Task page (System Operation > Task Manager > On-demand Task) lists the tasks you have scheduled as on-demand. The list includes the task name, a description, and an option to Run the task from this page. You can sort the information in the table by clicking any column heading. When you click Run, the Run Task Wizard page displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Upcoming Tasks

The Upcoming Tasks page (System Operation > Task Manager > Upcoming Tasks)lists the tasks scheduled to run within a certain interval. To select an interval, click an option in the Scheduled to run: search pane to the left of the task list. If you select the To a date option, you can either enter a date in yyyy-mm-dd format or click the calendar icon to select a date from the calendar.

You can sort the information in the task list by clicking any column heading. You can Suspend or Resume the scheduling of each task by clicking the appropriate option:

  • Suspend — Lets you suspend the task; a do you want to reschedule task when task is supposed to run? drop-down list lets you specify:

    • No. Upon resuming the task, the task manager attempts to run missed instances of the task before returning to the normal schedule.

    • Yes. Upon resuming the task, the task manager returns to the normal schedule without attempting to run missed instances.

  • Resume — Lets you resume a suspended task.

Task Schedule

The Task Schedule page (System Operation > Task Manager > Task Schedule) lists all scheduled tasks. You can sort the information in the table by clicking any column heading. You can view Details or History, as well as Run, a scheduled task by clicking the appropriate option:

  • taskname — Lets you view details about the task and perform operations on it.

  • History — Displays the task’s history.

  • Run — Lets you run the task. A Run Task wizard displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Task Details

To display detailed information about a scheduled task and perform one of several operations on it, click the task’s name in the Task Name column. The Task Details page displays information and execution details about the selected task. You can perform one of the following operations on the task by clicking the appropriate button:

  • Edit — Lets you change the task definition and schedule using the Task Scheduler Wizard.

  • History — Lets you view the task’s history.

  • Resume > Suspend— Let you suspend a task or resume a suspended task, as on the Upcoming Tasks page.

  • Delete — Lets you permanently delete the task.

  • Export — Lets you export a task to a file that can later be imported, including by another Caché instance.

  • Run — Lets you schedule the task. When you click Run, the Run Task Wizard page displays the task name and ID, and the date and time the task will run; click Perform Action Now to confirm the information and schedule the task.

Note:

Some of the actions options described are unavailable while a task is running.

Scheduled Task History

To display history information about an individual scheduled task, click the History link in the row of the item. The Task History page displays detailed history for the selected task. The Result column indicates the outcome the last time the task was run, showing either Success or an error message. You can sort the information in the table by clicking any column heading.

The Details link at the top of the page displays the Task Details page for the selected task.

Task History

The Task History page (System Operation > Task Manager > Task History) lists the history of all tasks executed by the Task Manager. You can sort the information in the table by clicking any column heading.

Import Tasks

The Import Tasks page (System Operation > Task Manager > Import Tasks) lets you import and run a task by browsing to a previously-exported task file, then clicking Perform Action Now. For information about exporting tasks to a file, see Task Details in this section.

Using ^TASKMGR

The ^TASKMGR routine allows you to configure the Task Manager using the Terminal. Except when noted otherwise, ^TASKMGR and the Management Portal contain the same options for configuring tasks; the one you use is a matter of preference.

To use ^TASKMGR:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

For more details about how to schedule or edit a task programmatically, see the %SYS.Task class documentation in the InterSystems Class Reference.

Changing Task Expiration Behavior

By default, all tasks are configured to expire if they miss their scheduled time. This could happen for a number of reasons; for example, when Caché is down during the scheduled time, or if the previous run of the task extends beyond the next scheduled time. When a task expires, it does not run until the next scheduled time.

The ^TASKMGR routine (but not the Management Portal) contains the option to change this behavior, such that a scheduled run is never skipped. To do so:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

  4. Select option 2.

  5. Enter the task number you want to edit.

  6. Press Enter to save the defaults of each option until you reach Task Expires?

  7. Enter No.

Alternatively, you can specify a grace period, such that the task does not expire immediately after it is missed. Instead, the Task Manager runs the missed task as soon as it is able. To adjust this grace period of when a specific task expires:

  1. Open the Terminal.

  2. Enter set $namespace = “%SYS” to change to the %SYS namespace.

  3. Enter do ^TASKMGR.

  4. Select option 2.

  5. Enter the task number you want to edit.

  6. Press Enter to save the defaults of each option until you reach Task Expires?

  7. Enter Yes.

  8. At the Expires in how many days? prompt, enter the number of days before the task should expire.

  9. At the Expires in how many hours? prompt, enter the number of hours before the task should expire.

  10. At the Expires in how many minutes? prompt, enter the number of minutes before the task should expire.

Next sectionUsing the Background Tasks Page
Previous sectionControlling Caché Processes
Feedback