Table of Contents
< All Topics
Print

Background Tasks

Gnosis Tasks are Gnosis Scripts executed in the background. They use a thread pool to execute background Tasks in parallel. If the Gnosis Application is shut down (e.g., OS reboot), all the Tasks currently in progress are automatically restarted when the Gnosis Application is started again.

Tasks are stored and contain the command, parameters, status, progress, and result or error when the Task ends.

Gnosis Tasks App

You can see the Tasks in the Gnosis Tasks App, accessible by users with Administrator or Developer roles:

/#dashboard:tasks

Clear

Click the Clear toolbar button to open the Clear Tasks dialog.

  • Before date—You can optionally select the before date to filter the Tasks to be cleared before the date specified.
  • Clear results only—Select to clear only the Task results.

Restart

Select the Tasks that you want to restart. Click the Restart toolbar button to restart the Tasks.

Remove

Select the Tasks that you want to remove. Click the Remove toolbar button to remove the selected Tasks.

Options

Select the Tasks that you want to configure. Click the Options toolbar button to open the Task Options dialog.

  • Fail Attempts—The number of attempts to retry on failure.
  • Wait Seconds—The number of seconds to wait before retrying.
  • Wait Multiplier—The multiplier will be applied to the wait seconds for each attempt.
  • Max Results—Limit the Task results. 0 = unlimited; -1 does not store the result; any number greater than 0 will keep that number of the most recent results.

Hide Succeeded

Select the Hide Succeeded option to hide Tasks that ended successfully.

Limit

Select the days to limit the lists or unlimited to show all Tasks.

$Task Variable

The $Task variable is the current Task in the Gnosis Script.

Task Properties

Id: Integer

Name: String—Entity name.

User: Identity—The current User during the Task execution (usually the person that created the Task).

Command: String—Indicates what command to execute (a built-in or custom script/view command).

Parameters: Dict—Task command parameters.

Priority: Integer—Task priority (the greater the priority, the more critical it is to start the Task).

CreateTime: Time—Task creation time.

UnlockTime: DateTime?—When will the Task be considered ready to start (scheduled Task), or will it be null to start immediately?

StartTime: DateTime?—When the Task was started. It is null if the Task has not started yet.

FinishTime: DateTime?—When the Task is finished. It is null if the Task has not finished yet.

Status: String—Task status.

  • Pending
  • InProcess
  • Failed
  • Succeeded
  • Paused

StatusMessage: String—Task status message.

Progress: Integer—Current task progress (between 0 and 100).

Result: Dict—Task result dictionary.

Error: Error—Task error, if any.

Paused: Boolean—Shortcut to check if the status is ‘Paused.’

Pending: Boolean—Shortcut to check if the status is ‘Pending.’

InProcess: Boolean—Shortcut to check if the status is ‘InProcess.’

Finished: Boolean—Shortcut to check if the status is ‘Succeeded’ or ‘Failed.’

Succeeded: Boolean—Shortcut to check if the status is ‘Succeeded.’

Failed: Boolean—Shortcut to check if the status is ‘Failed.’

Ready: Boolean—Indicates that the Task is ready to be executed.

FailAttempts: Integer—Number of attempts to re-execute the Task if it failed.Task to -1 to retry until the Task succeeds.

CurTask Attempt: Integer—Current attempt (equals 0 on normal execution, 1 on the first failed attempt).

FailWaitSeconds: Integer—Number of seconds to wait before the next attempt after fail.

FailWaitMultiplier: Integer—Wait multiplier. The formula calculates the number of seconds to wait: FailWaitSeconds * (1 + FailWaitMultiplier * CurrentAttempt).

MaxResults: Integer—The maximum length of the task results history. Set it to 0 (the default) to not limit the history, and set it to -1 to not track the history of results.

Accessible: Boolean—Indicates the current user has access to the Task.
The Task is accessible to the owner, an admin, or a developer.

Deferred: Boolean—Indicates that the task execution is deferred until the current transaction is finished.

Create Task

Create and execute Tasks in the background with the CreateTask function.

CreateTask(command, parameters?, callback?, name?, at?, priority = 0, paused = false, user?)

command: String—Known background command (built-in or custom script).

parameters: Dict?—Command parameters (specific to command).
Some special parameters apply to all commands:

  • $Critical: Boolean—An error log record is created to mark a task as critical, and an error report email is sent if the task fails.
  • $FailAttempts: Integer—Number of attempts to re-execute the task if it failed. Set to -1 to retry until the task succeeds.
  • $FailWaitSeconds: Integer—Number of seconds to wait before the next attempt after fail.
  • $FailWaitMultiplier: Integer—The number of seconds to wait is calculated by the formula: $FailWaitSeconds * (1 + $FailWaitMultiplier * Task.CurrentAttempt).
  • $MaxResults: Integer—Maximum length of the task results history. Set it to 0 (default) to not limit the history, and set it to -1 not to track the history of results.
  • $Name: String—Task name if not set by the ‘name’ argument.

callback: Function? – Parameterless callback function with special context variables $Task and $Result.

name: String?—Background task name.

at: DateTime?—If not null, specify when the task should be started.

  • Otherwise, the task will be started immediately (as soon as possible).
  • If DateTime, then starts at the specified time (UTC).
  • If Date, then starts at the beginning of the specified date (in UTC).
  • If Time, then specify the time in UTC for the current date.
  • If Duration, specify the period from now to the task’s start.
  • If Number, then specify the number of seconds from now to start the Task.

priority: Integer—The greater the number, the higher the task’s priority.

paused: Boolean—True to create a paused Task.

user: Identity?—The Task will be run for the specified user (the current user by default).

Examples:

CreateTask('AddTeamMember', { Team = Team('Solution Managers'), Member = $User });

Schedule Task

Some tasks are supposed to be executed more than once or even regularly. With the Schedule function, you can configure existing Tasks to execute again.

Schedule(task, at?, priority?, failAttempts?, failWaitSeconds?, failWaitMultiplier?, maxResults?)

task: BackgroundTask?

at: DateTime?—If not null, specify when the Task should be started.

  • Otherwise, the Task will be started immediately (as soon as possible).
  • If DateTime, then starts at the specified time (UTC).
  • If Date, then starts at the beginning of the specified date (in UTC).
  • If Time, then specify the time in UTC for the current date.
  • If Duration, specify the period from now to the task’s start.
  • If Number, then specify the number of seconds from now to start the Task.

priority: Integer?—Skip or set it to null to keep the current priority.

failAttempts: Integer?—Skip or set to null to keep the current value.

failWaitSeconds: Integer?—Skip or set to null to keep the current value.

failWaitMultiplier: Integer?—Skip or set to null to keep the current value.

maxResults: Integer?—Skip or set to null to keep the current value.

Schedule the Task as soon as possible:

$Task.Schedule();

Schedule the Task for 30 seconds:

$Task.Schedule(30);

Schedule the Task for 1 minute:

$Task.Schedule(Duration(0, 1));

Task Failure

When Tasks are marked as critical failures, they are recorded in the Error Log, and an email is sent to the comma-delimited list of email addresses set in the MailError Gnosis Configuration setting.

A Task is marked as critical if the Fail Attempts are greater than 0 or the $Critical parameter passed to the CreateTask function is true.

Command Files

Gnosis Scripts in the Gnosis Files /commands folder can be executed using the CreateTask function.

/#dashboard:files

Task-type Views

Task-type Views are Gnosis Scripts that can be executed as commands by the CreateTask function, as Solution and Item Type Static functions, with the View Render function, or as Custom Web API endpoints. In all cases, the Task runs in the background.

Built-in Task Commands

There are several built-in Task Commands.