Running Tasks

Once you have a running worker, you’ll want to run your tasks. Hatchet provides a number of ways of triggering task runs, from which you should select the one(s) that best suit(s) your use case.

Tasks can be run, and have their results waited on
Tasks can be enqueued without waiting for their results (“fire and forget”).
Tasks can be run on cron schedules.
Tasks can be triggered by events.
Tasks can be scheduled for a later time.

Each of these methods for triggering tasks have their own uses in different scenarios, and the next few sections will give some examples of each.

These methods can be invoked directly from the workflow definition, or from other services.

Invoking Tasks from your Application

Often it is useful to trigger tasks from your application (i.e. an API service). Hatchet consistently serializes inputs so the invocation of a task is the same regardless of the language or framework you are using.

Creating a “Stub” Task on your External Service (Recommended)

The recommended way to trigger a task from an external service is to create a “stub” task on your external service. This is a hatchet task or workflow that has the same name and input/output types as the task you want to trigger on your hatchet worker, but without the function or other configuration.

This allows you to have polyglot, fully typed interface with full SDK support.

examples/typescript/simple/stub-workflow.ts

import { hatchet } from '../hatchet-client';

// (optional) Define the input type for the workflow
export type SimpleInput = {
  Message: string;
};

// (optional) Define the output type for the workflow
export type SimpleOutput = {
  'to-lower': {
    TransformedMessage: string;
  };
};

// declare the workflow with the same name as the
// workflow name on the worker
export const simple = hatchet.workflow<SimpleInput, SimpleOutput>({
  name: 'simple',
});

// you can use all the same run methods on the stub
// with full type-safety
simple.run({ Message: 'Hello, World!' });
simple.runNoWait({ Message: 'Hello, World!' });
simple.schedule(new Date(), { Message: 'Hello, World!' });
simple.cron('my-cron', '0 0 * * *', { Message: 'Hello, World!' });

Consider a task with an implementation like this:

examples/python/stubs/implementation.py

from pydantic import BaseModel

from hatchet_sdk import Context, Hatchet


class TaskInput(BaseModel):
    user_id: int


class TaskOutput(BaseModel):
    ok: bool


hatchet = Hatchet()


@hatchet.task(name="externally-triggered-task", input_validator=TaskInput)
async def externally_triggered_task(input: TaskInput, ctx: Context) -> TaskOutput:
    return TaskOutput(ok=True)

To trigger this task from a separate service, for instance, in a microservices architecture, where the code is not shared, start by defining models that match the input and output types of the task defined above.

examples/python/stubs/stub_trigger.py

class TaskInput(BaseModel):
    user_id: int


class TaskOutput(BaseModel):
    ok: bool

Next, create the stub task.

examples/python/stubs/stub_trigger.py

stub = hatchet.stubs.task(
    # make sure the name and schemas exactly match the implementation
    name="externally-triggered-task",
    input_validator=TaskInput,
    output_validator=TaskOutput,
)

Finally, use the stub to trigger the underlying task, and (optionally) retrieve the result.

examples/python/stubs/stub_trigger.py

# input type checks properly
result = await stub.aio_run(input=TaskInput(user_id=1234))

# `result.ok` type checks properly
print("Is successful:", result.ok)

examples/go/stubs/stub-workflow.go

package main

import (
	"context"
	"fmt"
	"log"

	hatchet "github.com/hatchet-dev/hatchet/sdks/go"
)

type StubInput struct {
	Message string `json:"message"`
}

type StubOutput struct {
	Ok bool `json:"ok"`
}

func StubWorkflow(client *hatchet.Client) *hatchet.StandaloneTask {
	return client.NewStandaloneTask("stub-workflow", func(ctx hatchet.Context, input StubInput) (StubOutput, error) {
		return StubOutput{
			Ok: true,
		}, nil
	})
}

func main() {
	client, err := hatchet.NewClient()
	if err != nil {
		log.Fatalf("failed to create hatchet client: %v", err)
	}

	task := StubWorkflow(client)

	// we are simply running the task here, but it can be implemented in another service / worker
	// and in another language with the same name and input-output types
	result, err := task.Run(context.Background(), StubInput{Message: "Hello, World!"})
	if err != nil {
		log.Fatalf("failed to run task: %v", err)
	}

	fmt.Println(result)
}

Environments Run and Wait Trigger

We use cookies

Running Tasks

Invoking Tasks from your Application

Creating a “Stub” Task on your External Service (Recommended)