Start a Workflow Once per Entity
Start a Workflow Once per Entity
Section titled “Start a Workflow Once per Entity”A deterministic workflow_id makes start() idempotent for one entity. The second start with the same id creates no second workflow. It returns a handle to the first one.
Why and When
Section titled “Why and When”Use this when more than one caller can start the same workflow for the same entity. Examples are a retried HTTP request, a duplicated event, or two producers that react to the same row.
Horsies does not know your entity key. It knows only the workflow_id. A random id (the default) makes every start a new workflow.
How To
Section titled “How To”Build a UUID from the entity key with uuid.uuid5. Use a fixed namespace UUID and include the workflow name in the key. Pass the string form as workflow_id.
import uuidfrom typing import Any
from horsies import ( Err, Horsies, Ok, TaskError, TaskResult, WorkflowDefinition, WorkflowSpec, WorkflowStartIdConflict,)from instance import app
# Fixed for the life of the project. A new value changes every derived id.WORKFLOW_ID_NAMESPACE = uuid.UUID("6f1d5c0e-8a54-4c57-9a0e-2b7a4f3c9d10")
@app.task("onboard_customer")def onboard_customer(*, customer_id: str) -> TaskResult[str, TaskError]: return TaskResult(ok=customer_id)
class OnboardingWorkflow(WorkflowDefinition[str]): name = "customer_onboarding" definition_key = "myapp.customer_onboarding.v1"
@classmethod def build_with( cls, app: Horsies, customer_id: str, *_args: Any, **_kwargs: Any, ) -> WorkflowSpec[str]: onboard = onboard_customer.node(node_id="onboard")(customer_id=customer_id) return app.workflow(name=cls.name, tasks=[onboard], output=onboard)
def onboarding_workflow_id(customer_id: str) -> str: """Return the same id for the same workflow name and the same customer.""" key = f"{OnboardingWorkflow.name}:{customer_id}" return str(uuid.uuid5(WORKFLOW_ID_NAMESPACE, key))
async def start_onboarding(customer_id: str) -> str: spec = OnboardingWorkflow.build_with(app, customer_id=customer_id) match await spec.start_async(workflow_id=onboarding_workflow_id(customer_id)): case Ok(handle): return f"workflow {handle.workflow_id} is running or finished" case Err(WorkflowStartIdConflict(existing_workflow_name=existing)): return f"the id belongs to workflow {existing}" case Err(start_error): return f"start failed: {start_error.code.value}"Semantics
Section titled “Semantics”The workflow row is inserted with ON CONFLICT (id) DO NOTHING. The result depends on the row that holds the id.
| State of the id | Result of start() |
|---|---|
| No row | A new workflow starts. Ok(handle). |
| Row with the same workflow name | Ok(handle) for the existing workflow. Horsies logs a warning. No node is inserted or enqueued. |
| Row with another workflow name | Err(WorkflowStartIdConflict), code WORKFLOW_ID_CONFLICT. The error has the field existing_workflow_name. Nothing is written. |
| Value that is not a UUID | Err(WorkflowStartValidationFailed). See HRS-032. |
Other rules:
- Horsies accepts any UUID version. The check parses the string as a UUID. It does not look at the version.
- Horsies does not compare the payload. A second start with other arguments and the same id returns the first workflow. The new arguments are dropped.
Ok(handle)does not tell whether this call created the workflow. The handle can point to a workflow that is alreadyCOMPLETEDorFAILED.- A start that failed before its transaction committed leaves no row. The same id can start again. See
retry_start()in Workflow API.
Retention Ends the Protection
Section titled “Retention Ends the Protection”The protection exists while the workflow row exists. The retention sweep deletes terminal workflow rows after terminal_record_retention_hours (default 720). After that, the same id starts a new workflow.
Set terminal_record_retention_hours=None to keep terminal rows. See Retention Config.
Things to Avoid
Section titled “Things to Avoid”Don’t leave the workflow name out of the key. The id is unique across all workflows. Two workflow types that use the same entity key get the same id. The second type fails with WORKFLOW_ID_CONFLICT.
Don’t put changing data in the key. A key that includes a timestamp or a status gives a new id for each change, so nothing deduplicates.
Don’t use hash() or a random value for the key. hash() of a string differs between Python processes. Use uuid5.
Don’t change the namespace UUID. Each derived id changes. Running workflows are no longer found by their old ids.
