Table of Contents
< All Topics

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:



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 selected.
  • Clear results only—Select to clear only the Task results. ???


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


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


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.


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

Task Failure

Tasks can be marked as critical, so failures 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 is greater than 0 or the $Critical parameter passed to the CreateTask function is true.

Sometimes, you want to retry a Task after a failure to give it a chance to succeed. With the Schedule function, you can configure the Task to execute again up to a set number of fail attempts. The error report is sent only when all failure attempts fail.

Task Command Variable

The $Task variable is the current Task.

Task Command Special Functions

Progress function

Allows you to show progress in the Gnosis Task App.

// Pass in a message for the Task Status.
// Pass in an integer between 0 and 100 to show the progress.
// Pass in both a message and progress percentage.
Progress(percentage, message)

The message for the task is shown in the Status column.

The progress is shown as a meter in the Progress column for the Task.

Commit function

It allows you to commit to the change rather than wait for the end of the Task.

Commit(message?, clearCache?)

The commit message is written to the history if the Item Type History is configured.

Clearing the cache frees up memory and increases performance. It should be used when there are many changes in the Task.

Built-in Task Commands

There are several built-in Task Commands.

Gnosis Script Commands

Create Gnosis Scripts in the /command folder in Gnosis Files that can be executed by the CreateTask function.

Task View Commands

Task-type Views are gsAction Gnosis Scripts that can be executed as Task Commands with the CreateTask function, the View Render function, and Custom Web API endpoints.

During development, the Gnosis View IDE automatically executes the Task View in the foreground using Simulation Mode for debugging.

Task Example

The following is a Task-type View that will create an Entity Item using the Name and Description passed in as parameters:

 * Creates an Entity.
 * @group Demo
 * @param Name : string // The Entity Name.
 * @param Description : string // The Entity Description
 * @result item 
 * @example CreateTask("Demo.CreateEntity", {"Name":"Test", "Description":"Test"});
// If no Name is passed in, generate a random name.
var name = $Params?.Name
	? $Params?.Name
	: "Random Name {Random(1, 100)}";

// If no Desctiontion is passed in, set add a description.
var desc = $Params?.Description 
	? $Params?.Description
	: "Created by Demo.CreateEntity Task View";

// Create a new Item and catch and log any error.
var item = Safe($.Demo.Entity.CreateItem({
	Name = name,
	Description = desc
}), e => LogError(e.Message));

Testing the Task View

// Get Authorization header with the OAuth access token.
OAuth(username, password) => (
	var url = $ServerUrl + "/v2/OAuth";
	var cred = {
	  "username": username,
	  "password": password,
	  "grant_type": "password"};
	var oauth = Ajax(url, cred, "POST");
	// The object is the last statement so it is the return value.
	{ "Authorization": "Bearer " + oauth.access_token }

// Credential variables
var user = "email";
var pwd = "password";

// The gsAction View path.
var gsAction = "Demo.CreateEntity";

var params = {
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by CreateTask function"

// Execute the gsActin using CreateTask function.
CreateTask(gsAction, params, missing, gsAction);

params = {
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by View Render function"

// Render the gsAction using the View function.
View(gsAction, params, true).Render();

params = {
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by {gsAction} Web v1 API"
// POST the gsAction using Gnosis v1 API.
	url = $ServerUrl + "/api/View/Action/" + gsAction,
	params = params,
	method = "POST",
	user = user,
	password = pwd

params = {
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by {gsAction} Web v2 API"

// POST the gsAction using Gnosis v2 API.
	$ServerUrl + "/v2/View/" + gsAction,
	missing, missing, missing,
	OAuth(user, pwd));