Task configuration

In this section, you will learn more about the task envelope and its possibilities.

A task in Taskurai consists of a uniform envelope that can contain custom properties. This way, tasks can be handled uniformly by developers, service desks, and help desks.

Reference task configuration

Here is an example task:

YAML

id: 5e41080b-8599-4ad5-b6f4-d5cf38f49186
config:
  command: testCommand
  arguments:
    - name: purchaseOrderId
      data: 3000911e-ef4f-4420-9271-abd03373de32
    - name: formatting
      data:
        paperSize: Letter
        orientation: Portrait
    - name: mailing
      sensitive: true
      data:
        includePurchaseOrderAttachment: true
        recipients:
          - purchase@company.net
          - finance@company.net
  secrets: []
  category: Purchase
  subject: Generate purchase order and email
  description: Generate purchase order PDF and email to recipients.
  externalId: PO-578934
  tags: {}
  isolationMode: true
  isolationKey: dd10b001-addd-45c2-94a6-932282b7515c
  correlationId: 5e41080b-8599-4ad5-b6f4-d5cf38f49186
  traceParent: 00-5e41080b85994ad5b6f4d5cf38f49186-9d2199efe6a42807-01
  id: 5e41080b-8599-4ad5-b6f4-d5cf38f49186
created: '2026-03-27T16:01:40.1667634+00:00'
createdBy: d8e9cb3f-ffeb-4915-bb15-6681a3bcd175
modified: '2026-03-27T16:01:40.2851177+00:00'
modifiedBy: d8e9cb3f-ffeb-4915-bb15-6681a3bcd175
status: created
archived: false
postponed: false
deleting: false
correlationId: 5e41080b-8599-4ad5-b6f4-d5cf38f49186
defaultStateStore: DefaultStateStore

JSON

{
  "id": "5e41080b-8599-4ad5-b6f4-d5cf38f49186",
  "config": {
    "command": "testCommand",
    "arguments": [
      {
        "name": "purchaseOrderId",
        "data": "3000911e-ef4f-4420-9271-abd03373de32"
      },
      {
        "name": "formatting",
        "data": {
          "paperSize": "Letter",
          "orientation": "Portrait"
        }
      },
      {
        "name": "mailing",
        "sensitive": true,
        "data": {
          "includePurchaseOrderAttachment": true,
          "recipients": [
            "purchase@company.net",
            "finance@company.net"
          ]
        }
      }
    ],
    "secrets": [],
    "category": "Purchase",
    "subject": "Generate purchase order and email",
    "description": "Generate purchase order PDF and email to recipients.",
    "externalId": "PO-578934",
    "tags": {},
    "isolationMode": true,
    "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
    "correlationId": "5e41080b-8599-4ad5-b6f4-d5cf38f49186",
    "traceParent": "00-5e41080b85994ad5b6f4d5cf38f49186-9d2199efe6a42807-01",
    "id": "5e41080b-8599-4ad5-b6f4-d5cf38f49186"
  },
  "created": "2026-03-27T16:01:40.1667634+00:00",
  "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "modified": "2026-03-27T16:01:40.2851177+00:00",
  "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "status": "created",
  "archived": false,
  "postponed": false,
  "deleting": false,
  "correlationId": "5e41080b-8599-4ad5-b6f4-d5cf38f49186",
  "defaultStateStore": "DefaultStateStore"
}

Task properties

Property	Type	Required	Description
id	string	Yes	Task ID
config	Task configuration	Yes	Task configuration
created	DateTimeOffset	Yes	Task created
modified	DateTimeOffset	No	Task modified
startAfter	DateTimeOffset	No	Task start after
notStartAfter	DateTimeOffset	No	Task not start after
started	DateTimeOffset	No	Task started
runStarted	DateTimeOffset	No	Task run started
retryAfter	DateTimeOffset	No	Task retry after
stopped	DateTimeOffset	No	Task stopped
status	Task status	No	Task status
statusCode	Task status code	No	Task status code
retryStatus	Task retry status	No	Task retry status
progress	Task progress	No	Task progress
result	Task result	No	Task result
error	Task error	No	Task error
archived	boolean	No	Task archived
postponed	boolean	No	Task postponed
deleting	boolean	No	Task deleting
runCount	long	No	Task run count
correlationId	string	No	Task correlation id
workerName	string	No	Task worker name where the last run of the task occurred
workerImage	string	No	Task worker image where the last run of the task occurred
defaultStateStore	string	No	Task default state store
cleanupStateAfterSeconds	int	No	Task cleanup state after seconds.

Task configuration

Some properties have fixed usage, such as:

Property	Type	Required	Description
id	string	Yes	Task ID
command	string	Yes	Task command
arguments	List of Task arguments	No	Task arguments
secrets	List of Task secrets	No	Task secrets
executionOptions	Execution options	No	Task execution options
unlisted	boolean	No	Mark task as unlisted
isolationMode	boolean	No	Run the task in isolation mode
isolationKey	string	No	Isolation key
correlationId	string	No	Override the task correlation id
parentId	string	No	Task parent ID

Other properties are commonly used but can be used in a way that suits your case best:

Property	Type	Required	Description
category	string	No	Task category
subject	string	No	Task subject
description	string	No	Task description
externalId	string	No	Task external ID
externalAccountId	string	No	Task external account ID
externalUserId	string	No	Task external user ID
tags	object	No	Task tags (dictionary)

Usually, the category and subject are used to provide additional information about tasks, such as:

• category: "Purchase", "Data processing", etc.
• subject: "Confirmation email for Contoso", "Processing upload myimage.png", etc.

The unlisted property is used to filter out internal tasks that you don't want to show in the end-user application.

You can choose whether the task contains all the data for the command or if the command looks up extra data afterwards.

info

The total size of the task is limited to 2 MB.

To pass in or return large quantities of data, use state management. The task arguments and task output can contain state references.

Using versioned commands

When commands are set up to be versioned, you can use specific versions of a command by using the following syntax:

commandName@version

caution

Before creating tasks with new command versions, ensure that workers containing the new versions are deployed.

Arguments

The task can optionally pass arguments to the task command:

Property	Type	Required	Description
name	string	Yes	Argument name
type	string	No	Argument type
data	string	No	Argument value
stateReference	string	No	Argument state reference (state id)
secretReference	string	No	Argument secret reference (task secret name)
sensitive	boolean	No	Consider this argument as sensitive (only return when scope Data/Buildby.Taskurai/sensitive/read is available)

Secrets

The task can optionally pass secrets to the task command:

Property	Type	Required	Description
name	string	Yes	Secret name
value	string	No	Secret value
secretReference	string	No	Secret secret reference (global secret name) (only when scope Data/Buildby.Taskurai/secrets/read is available)

While it is technically possible to define a secret value directly in the task configuration, it is highly recommended to use globally defined secrets in Taskurai and reference them in the task.

When passing in secrets as a value, do not include secrets in source code.

Secrets values can only be read by workers with a access token that has the scope Data/Buildby.Taskurai/secrets/read.

Execution options

Property	Type	Required	Description
defaultRetryPolicy	RetryPolicy	No	Default retry policy
timeoutRetryPolicy	RetryPolicy	No	Timeout retry policy
intermediateFailureRetryPolicy	RetryPolicy	No	Intermediate failure retry policy
failureRetryPolicy	RetryPolicy	No	Failure retry policy
maxDuration	long	No	Maximum duration in seconds
startAfter	After	No	Configure scheduled start
notStartAfter	After	No	Mark task as expired if not started after (seconds or fixed date time).

Retry policy

The retry policy configures how tasks are retried on completion:

Property	Type	Required	Default	Description
InitialDelaySec	double	No	15	The delay between retry attempts for a fixed approach or the delay on which to base calculations for a backoff-based approach. If the command provides a retryAfter response, the next retry is delayed by the duration specified by the retryAfter value. (Default: 15 sec, max 7 days).
MaxRuns	int	No		Max task runs (-1: unlimited, 0: single execution attempt, no retry, >= 1: total number of attempts/retries).
MaximumDelaySec	double	No	60	The maximum delay between retry attempts when the command doesn't provide a retryAfter response. If the service provides a retryAfter response, the next retry is delayed by the duration specified by the header value. (default 60 sec, max 7 days).
RetryMode	RetryMode	No	Exponential	Method to calculate retry delays (default: Exponential).

Default retry policies

Policy	InitialDelaySec	MaxRuns	MaximumDelaySec	RetryMode
DefaultRetryPolicy	15	0	3600	Exponential
TimeoutRetryPolicy	15	5	3600	Exponential
IntermediateFailureRetryPolicy	15	10	3600	Exponential
FailureRetryPolicy	15	5	3600	Exponential

info

The following task statuses will never be retried:

• Succeeded
• Canceled
• Fatal

The DefaultRetryPolicy will handle all task statuses not explicitly handled by the other policies.

Progress

While a task is running, a command can store intermediate progress reports for other applications to read. For example, to provide some interaction to the end-user or help desk:

Property	Type	Required	Description
percentage	double	No	Task percentage (0.0-100.0)
message	string	No	Progress message
heartbeat	DateTimeOffset	No	Heartbeat date time

Task Status

The following task statuses are possible:

Status	Description
Creating	Task is creating
Created	Task is created
Expired	Task is expired
Scheduled	Task is scheduled
Running	Task is running
RetryScheduled	Task retry is scheduled
Suspended	Task is suspended
WaitingForEvents	Task is waiting for events
CallTasks	Task is calling sub tasks
Resuming	Task is resuming
Succeeded	Task is succeeded
Timeout	Task is timed out
Failed	Task is failed
Fatal	Task is fatal
Canceled	Task is canceled
IntermediateFailure	Task has failed in an intermediate state (will not be dequeued and be retried)
Postponed	Task has been created but is not queued yet

The status codes Expired, Succeeded, Timeout, Failed, Fatal and Canceled are considered final states.

Status Code

The status code can be used to provide more details about the task status. HTTP response status codes are used.

Retry status

The following retry status codes are possible:

Status	Description
Scheduled	Task retry is scheduled
Retrying	Task is retrying
Stopped	Task retry is stopped

Result

The result can be set either during the execution of a task or when a task is complete. It can contain the following data as free-form fields:

Property	Type	Required	Description
output	list of Result output	No	Result output
messages	list of Result message	No	Result messages

Result output

Task result message:

Property	Type	Required	Description
name	string	No	Optional output name
type	string	No	Optional output type
value	string	No	Output value
stateReference	string	No	Output state reference (state id)
sensitive	boolean	No	Consider this output as sensitive (only return when scope Data/Buildby.Taskurai/sensitive/read is available)

Result message

Task result message:

Property	Type	Required	Description
code	string	Yes	Message code
message	string	Yes	Message
details	List of Result message	No	List of message details

Error

If an error occurs while executing the task, the following fields can be used to report it:

Property	Type	Required	Description
code	string	Yes	Error code
message	string	Yes	Error message
details	List of Error	No	List of errors