Skip to main content

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:

---
id: 89c46857-564c-478e-9607-fe9843202d04
config:
  id: 89c46857-564c-478e-9607-fe9843202d04
  command: testCommand@1
  arguments:
  - name: arg1
    value: abc-123
  - name: arg2
    data:
      Name: Test
      Value: Some value
      Properties:
      - Some property
      - Another property  
  externalId: my-id-123456
  accountId: my-account-5
  userId: user-john-do
  category: Console app
  subject: Samples
  description: This is a test task
  unlisted: false
created: '2023-06-23T08:40:39.02698+00:00'
modified: '2023-06-23T08:40:52.9212684+00:00'
started: '2023-06-23T08:40:47.3573226+00:00'
runStarted: '2023-06-23T08:40:47.3573226+00:00'
stopped: '2023-06-23T08:40:52.9212684+00:00'
status: Failed
statusCode: 408
runCount: 1
progress:
  progress: 95 
  message: Task failed.
result:
  messages:
  - code: 200
    message: Files are processed successfully.
    details:
    - message: Processed file1.pdf in 26 seconds.
    - message: Processed file2.pdf in 5 seconds.
  output:  
  - name: folderUri
    value: https://storage.com/container/folder
  - name: file1Uri
    type: fileUri
    value: https://storage.com/container/folder/file1.pdf 
  - name: file2Uri
    type: fileUri
    value: https://storage.com/container/folder/file2.pdf 
  - name: metadata
    data:
      ocrResults:
      - fileName: file1.pdf
        totalPrice: 122.5
      - fileName: file2.pdf
        totalPrice: 2.75
error:
  code: '408'
  message: Request Timeout
  details:
  - code: '503'
    message: The mailing service is temporarily unavailable.

Task properties​

PropertyTypeRequiredDescription
idstringYesTask ID
configTask configurationYesTask command
createdDateTimeYesTask created
modifiedDateTimeNoTask modified
startedDateTimeNoTask started
runStartedDateTimeNoTask run started
stoppedDateTimeNoTask stopped
statusTask statusNoTask status
statusCodeTask status codeNoTask status code
progressTask progressNoTask progress
resultTask resultNoTask result
errorTask errorNoTask error
archivedbooleanNoTask archived
postponedbooleanNoTask postponed
cancelledbooleanNoTask canceled
runCountlongNoTask run count
correlationIdstringNoTask correlation id
workerNamestringNoTask worker name where the last run of the task occurred
workerImagestringNoTask worker image where the last run of the task occurred

Task configuration​

Some properties have fixed usage, such as:

PropertyTypeRequiredDescription
idstringYesTask ID
commandstringYesTask command
argumentsList of Task argumentsNoTask arguments
secretsList of Task secretsNoTask secrets
executionOptionsExecution optionsNoTask execution options
unlistedbooleanNoMark task as unlisted
isolationModebooleanNoRun the task in isolation mode
localIdentifierstringNoLocal identifier
correlationIdstringNoOverride the task correlation id

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

PropertyTypeRequiredDescription
categorystringNoTask category
subjectstringNoTask subject
descriptionstringNoTask description
externalIdstringNoTask external ID
accountIdstringNoTask account ID
userIdstringNoTask user ID
tagsobjectNoTask tags (dictionary)

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

  • category: "Send confirmation email", "Processing upload", 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 afterward.

info

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

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:

PropertyTypeRequiredDescription
namestringYesArgument name
typestringNoArgument type
valuestringNoArgument value
stateReferencestringNoArgument state reference (state id)
secretReferencestringNoArgument secret reference (task secret name)
sensitivebooleanNoConsider this argument as sensitive (only return when scope Taskurai.Sensitive.Read is available)

Secrets​

The task can optionally pass secrets to the task command:

PropertyTypeRequiredDescription
namestringYesSecret name
valuestringNoSecret value
secretReferencestringNoSecret secret reference (global secret name) (only when scope Taskurai.Secret.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 Taskurai.Secret.Read.

Execution options​

Control how the task is executed:

PropertyTypeRequiredDescription
maxRunsAfterTimeoutintNoMaximum task runs after timeout (-1: unlimited, 0: single execution attempt before timeout, no retry, >= 1: total number of attempts/retries)
maxDurationlongNoMaximum duration in seconds (note: this will only prevent a reschedule or retry of a task, no tasks are terminated)

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:

PropertyTypeRequiredDescription
progressdoubleNoTask progress (0.0-100.0)
messagestringNoProgress message
heartbeatDateTimeNoHeartbeat date time

Task Status​

The following task status codes are possible:

StatusDescription
CreatingTask is creating
CreatedTask is created
RunningTask is running
SucceededTask is succeeded
FailedTask is failed
CanceledTask is canceled
IntermediateFailureTask has failed in an intermediate state (will not be dequeued and be retried)

The status codes Succeeded, Failed, 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.

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:

PropertyTypeRequiredDescription
outputlist of Result outputNoResult output
messageslist of Result messageNoResult messages

Result output​

Task result message:

PropertyTypeRequiredDescription
namestringNoOptional output name
typestringNoOptional output type
valuestringNoOutput value
stateReferencestringNoOutput state reference (state id)
sensitivebooleanNoConsider this output as sensitive (only return when scope Taskurai.Sensitive.Read is available)

Result message​

Task result message:

PropertyTypeRequiredDescription
codestringYesMessage code
messagestringYesMessage
detailsList of Result messageNoList of message details

Error​

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

PropertyTypeRequiredDescription
codestringYesError code
messagestringYesError message
detailsList of ErrorNoList of errors