Skip to main content

Creating tasks

This section provides information on how to create new tasks.

API reference:

Required scopes:

  • Data/Buildby.Taskurai/tasks/create

Optional scopes:

  • Data/Buildby.Taskurai/sensitive/read: Can return sensitive data.
  • Data/Buildby.Taskurai/secrets/read: Can read global secrets.

Prerequisites​

Creating a new task​

In your application, you can create one or more tasks to offload workloads to asynchronous commands. You can store the returned task ID to provide updates to the end-user about the progress and outcome of the task.

var serializerOptions = new JsonSerializerOptions()
{
	WriteIndented = true,
	DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault,
	PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
	DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
	Converters =
  {
	new JsonStringEnumConverter(JsonNamingPolicy.CamelCase),
  }
};

var createTaskInput = new TaskConfig("testCommand")
{
	ExternalId = "PO-578934",
	Arguments = new List<TaskArgument>()
  {
	new TaskArgument("purchaseOrderId")
	{
	  Value = "3000911e-ef4f-4420-9271-abd03373de32"
	},
	new TaskArgument("formatting")
	{
	  Value = new
	  {
		PaperSize = "Letter",
		Orientation = "Portrait"
	  }
	},
	new TaskArgument("mailing")
	{
	  Value = new
	  {
		IncludePurchaseOrderAttachment = true,
		Recipients = new List<string>()
		{
		  "purchase@company.net",
		  "finance@company.net"
		}
	  },
	  Sensitive = true
	}
  },
	Category = "Purchase",
	Subject = "Generate purchase order and email",
	Description = "Generate purchase order PDF and email to recipients.",
};

var createdTask = taskurai.CreateTask(createTaskInput);

Console.WriteLine(JsonSerializer.Serialize(createdTask, serializerOptions));

Next, run the console application to validate:

dotnet run

The expected output should be similar to:

{
  "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"
}

Waiting for a task to be completed​

In most cases, the task is created and is not awaited for. Updates are provided after the task is handled by other means, such as sending notifications to the user application or sending messages via email, etc.

Taskurai does offer a construct to wait for an async task to be completed. This can be useful in services that do not have direct user interaction. By using this construct, the task works as a direct command, and the result is returned after the task is completed.

var createTaskInput = new TaskConfig("testCommand")
{
  ExternalId = "PO-578934",
  Arguments = new List<TaskArgument>()
  {
    new TaskArgument("purchaseOrderId")
    {
      Value = "3000911e-ef4f-4420-9271-abd03373de32"
    },
    new TaskArgument("formatting")
    {
      Value = new
      {
        PaperSize = "Letter",
        Orientation = "Portrait"
      }
    },
    new TaskArgument("mailing")
    {
      Value = new
      {
        IncludePurchaseOrderAttachment = true,
        Recipients = new List<string>()
        {
          "purchase@company.net",
          "finance@company.net"
        }
      },
      Sensitive = true
    }
  },
  Category = "Purchase",
  Subject = "Generate purchase order and email",
  Description = "Generate purchase order PDF and email to recipients.",
};

var taskResponse = taskurai.CreateTaskAndWaitForResult(createTaskInput, cancellationToken);

Console.WriteLine(JsonSerializer.Serialize(taskResponse, serializerOptions));

Waiting for a task result​

It is also possible to return the actual output data of the task (only one return value is supported):

var utcNow = await taskurai.CreateTaskAndWaitForResultAsync<DateTimeOffset>(new TaskConfig("utcNow"));

Console.WriteLine($"UTC now: {utcNow}");

Creating tasks with a scheduled start​

It is possible to create tasks with a scheduled start. A task can start after a predefined number of seconds or after a predefined date time.

var createdTask = await taskurai.CreateTaskAsync(
  new TaskConfig("StartOnboardingFlow")
    {
      Arguments = {
        new TaskArgument("fullName")
        {
          Value = manager.FullName
        },
        new TaskArgument("toEmail")
        {
          Value = manager.Email
        }
      },
      ExecutionOptions = new TaskExecutionOptions()
      {
        StartAfter = new After()
        {
          Seconds = 7200 // Start after 2 hours
        }
      }
    });