Using the Task Manager

To access the Task Manager, navigate to System Operation > Task Manager.

You can also interact with the Task Manager using the Terminal, as described in Using ^TASKMGR. See Tasks for other methods of managing tasks.

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. This tool allows you to schedule a new task to run.

Note:

You can also use the Task Scheduler Wizard to edit an existing task by selecting the existing task from the Task Schedule page.

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, see Priority.
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 InterSystems IRIS® username you select; see License Login Special Considerations 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), 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:
- primary failover member only
- backup failover member and async members only (all except primary)
- all mirror members (primary, backup, and asyncs)
Important:

For a task to run on a mirror member, this option must be set for all tasks on the mirror member. Adding an instance to a mirror member does not automatically update this option 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.
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.
  
  Note:
  
  If the chosen date does not exist for a particular month, the closest existing date in that month is used.
- 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.

InterSystems IRIS includes a number of tasks that run by default. This table notes these defaults, which you may edit from the Task Schedule page.

Note:

You can define your own task types using the %SYS.Task.DefinitionOpens in a new tab API; for details, see the class documentation in the InterSystems Class Reference.

Task Type	Corresponding Default Task	Description
CheckLoggingOpens in a new tab	Check Logging activity — runs nightly; sends an alert after two days.	Checks that logging mechanisms (such as ^ISCSOAP) have not been left running unintentionally. Creates an alert after DaysForAlert days, and shuts off logging after DaysForShutoff days.
CumuIncrDBListOpens in a new tab	None	Runs a cumulative backup of databases in the defined list.
DiagnosticReportOpens in a new tab	Diagnostic Report — runs on demand.	Collects and delivers diagnostic reports to the WRC.
FullAllDatabasesOpens in a new tab	None	Runs a full backup of all databases.
FullDBListOpens in a new tab	None	Runs a full backup of databases in the defined list.
IncrementalDBListOpens in a new tab	None	Runs an incremental backup of databases in the defined list.
IntegrityCheckOpens in a new tab	Integrity Check — disabled by default.	Runs an integrity check of databases in the namespace. The Integrity Check task only appears when the %SYS namespace is selected.
InventoryScanOpens in a new tab	Inventory Scan — runs on demand.	Compiles an inventory scan of the instance.
PurgeAuditOpens in a new tab	Purge Audit Database — runs after the Switch Journal task.	Purges the audit database after a specified time following a journal switch.
PurgeBackupLogOpens in a new tab	Purge Backup Log — runs nightly.	Purges the backup log after a specified time following a database backup.
PurgeErrorsAndLogsOpens in a new tab	Purge errors and log files — runs nightly.	Purges error globals and messages.log based on settings in the iris.cpf file (see ErrorPurge and MaxConsoleLogSize parameters in the [Startup] section of the Configuration Parameter File Reference). Note: When System Monitor is running, it monitors and limits the size of the messages log.
PurgeJournalOpens in a new tab	Purge Journal — runs nightly.	Purges journal files that meet the purging criteria.
PurgeTaskHistoryOpens in a new tab	Purge Tasks — runs nightly.	Purges Task Manager history files.
RunLegacyTaskOpens in a new tab	None	Runs a legacy task (i.e. 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. InterSystems IRIS 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.
SecurityScanOpens in a new tab	Security Scan — runs nightly.	Disables expired user accounts and expires user passwords and web session tokens.
SwitchJournalOpens in a new tab	Switch Journal — runs nightly.	Switches to a new journal file.

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:

Task Name — 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 — Change the task definition and schedule using the Task Scheduler Wizard.
History — View the task’s history.
Resume/Suspend — Suspend a task/resume a suspended task, as on the Upcoming Tasks page.
Delete — Delete the task permanently.

Note:

You cannot delete a system task.
Export — Export a task to a file that can later be imported, including by another InterSystems IRIS instance.
Run — 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 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. To filter out system tasks, select the Show only user-defined task types check box at the top of the table.

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.

Note:

Tasks can only be imported from, or exported to, instances running the same version of InterSystems IRIS.

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:

Open the Terminal.
Enter set $namespace = "%SYS" to change to the %SYS namespace.
Enter do ^TASKMGR.

For more details about how to schedule or edit a task programmatically, see the %SYS.TaskOpens in a new tab 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 InterSystems IRIS 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:

Open the Terminal.
Enter set $namespace = "%SYS" to change to the %SYS namespace.
Enter do ^TASKMGR.
Select option 2.
Enter the task number you want to edit.
Press Enter to save the defaults of each option until you reach Task Expires?
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:

Open the Terminal.
Enter set $namespace = "%SYS" to change to the %SYS namespace.
Enter do ^TASKMGR.
Select option 2.
Enter the task number you want to edit.
Press Enter to save the defaults of each option until you reach Task Expires?
Enter Yes.
At the Expires in how many days? prompt, enter the number of days before the task should expire.
At the Expires in how many hours? prompt, enter the number of hours before the task should expire.
At the Expires in how many minutes? prompt, enter the number of minutes before the task should expire.

Using the Background Tasks Page

Controlling InterSystems IRIS Processes