Saga Orchestrator
Description
Manages long-running business transactions (sagas) that span multiple aggregates or bounded contexts, coordinating compensating actions if failures occur.
Definition Schema
The definition for a saga_orchestrator component expects the following structure:
{
"$defs": {
"ImportDefinitionDTO": {
"description": "Defines a custom import statement.",
"properties": {
"module": {
"title": "Module",
"type": "string"
},
"names": {
"items": {
"type": "string"
},
"title": "Names",
"type": "array"
}
},
"required": [
"module",
"names"
],
"title": "ImportDefinitionDTO",
"type": "object"
},
"SagaStepInputDTO": {
"description": "Defines a single step within a Saga.",
"example": {
"command_module": "app_root_name.application.payments.commands",
"command_name": "ProcessPaymentCommand",
"compensation_command_module": "app_root_name.application.payments.commands",
"compensation_command_name": "RefundPaymentCommand",
"failure_event_module": "app_root_name.domain.payments.events",
"failure_event_name": "PaymentFailedEvent",
"step_name": "ProcessPayment",
"success_event_module": "app_root_name.domain.payments.events",
"success_event_name": "PaymentProcessedEvent"
},
"properties": {
"step_name": {
"description": "Descriptive name for this saga step (e.g., 'ProcessPaymentStep')",
"title": "Step Name",
"type": "string"
},
"command_name": {
"description": "Name of the Command to execute for this step (e.g., 'ProcessPaymentCommand')",
"title": "Command Name",
"type": "string"
},
"command_module": {
"description": "Module path for the command_name (e.g., 'app_root_name.application.payments.commands')",
"title": "Command Module",
"type": "string"
},
"success_event_name": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Name(s) of the Event(s) indicating successful completion of this step (e.g., 'PaymentProcessedEvent' or ['EventA', 'EventB'])",
"title": "Success Event Name"
},
"success_event_module": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Module path(s) for the success_event_name(s) (e.g., 'app_root_name.domain.payments.events' or ['module.a', 'module.b'])",
"title": "Success Event Module"
},
"failure_event_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the Event indicating failure of this step (e.g., 'PaymentFailedEvent')",
"title": "Failure Event Name"
},
"failure_event_module": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Module path for the failure_event_name",
"title": "Failure Event Module"
},
"compensation_command_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the Command to execute for compensating this step (e.g., 'RefundPaymentCommand')",
"title": "Compensation Command Name"
},
"compensation_command_module": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Module path for the compensation_command_name",
"title": "Compensation Command Module"
},
"is_compensating_transaction": {
"default": false,
"description": "Indicates if this step itself is a compensating transaction.",
"title": "Is Compensating Transaction",
"type": "boolean"
},
"compensation_success_event_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event for successful compensation.",
"title": "Compensation Success Event Name"
},
"compensation_failure_event_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Event for failed compensation.",
"title": "Compensation Failure Event Name"
}
},
"required": [
"step_name",
"command_name",
"command_module",
"success_event_name",
"success_event_module"
],
"title": "SagaStepInputDTO",
"type": "object"
},
"TriggerEventConfigInputDTO": {
"description": "Defines how a saga is triggered by an event.",
"properties": {
"event_name": {
"title": "Event Name",
"type": "string"
},
"event_module": {
"title": "Event Module",
"type": "string"
},
"correlation_id_provider_str": {
"description": "Lambda string to extract correlation ID, e.g., 'lambda event: str(event.order_id)'",
"title": "Correlation Id Provider Str",
"type": "string"
}
},
"required": [
"event_name",
"event_module",
"correlation_id_provider_str"
],
"title": "TriggerEventConfigInputDTO",
"type": "object"
}
},
"description": "DTO for defining a Saga Orchestrator class.",
"example": {
"completion_event_module": "app_root_name.domain.ordering.events.order_events",
"completion_event_name": "OrderProcessingCompletedEvent",
"failure_event_module": "app_root_name.domain.ordering.events.order_events",
"failure_event_name": "OrderProcessingFailedEvent",
"name": "OrderProcessingSagaOrchestrator",
"saga_type": "OrderProcessingSaga",
"state_dto_module": "app_root_name.domain.ordering.sagas.order_processing_saga_state",
"state_dto_name": "OrderProcessingSagaState",
"state_repository_module": "app_root_name.infrastructure.persistence.ordering.repositories.order_processing_saga_state_repository",
"state_repository_name": "OrderProcessingSagaStateRepository",
"steps": [
{
"command_module": "app_root_name.application.payments.commands",
"command_name": "ProcessPaymentCommand",
"step_name": "ProcessPayment",
"success_event_module": "app_root_name.domain.payments.events",
"success_event_name": "PaymentProcessedEvent"
},
{
"command_module": "app_root_name.application.shipping.commands",
"command_name": "ShipOrderCommand",
"compensation_command_module": "app_root_name.application.shipping.commands",
"compensation_command_name": "CancelShipmentCommand",
"step_name": "ShipOrder",
"success_event_module": "app_root_name.domain.shipping.events",
"success_event_name": "OrderShippedEvent"
}
],
"triggering_events": [
{
"correlation_id_provider_str": "lambda event: str(event.order_id)",
"event_module": "app_root_name.domain.ordering.events.order_events",
"event_name": "OrderCreatedEvent"
}
]
},
"properties": {
"name": {
"description": "Name of the Saga Orchestrator class (e.g., 'OrderProcessingOrchestrator')",
"title": "Name",
"type": "string"
},
"saga_type": {
"description": "Unique type identifier for this saga (e.g., 'OrderProcessingSaga')",
"title": "Saga Type",
"type": "string"
},
"state_dto_name": {
"description": "Name of the in-memory Saga State DTO (e.g., 'OrderProcessingSagaState')",
"title": "State Dto Name",
"type": "string"
},
"state_dto_module": {
"description": "Module path for the state_dto_name",
"title": "State Dto Module",
"type": "string"
},
"state_repository_name": {
"description": "Name of the Saga State Repository (e.g., 'OrderProcessingSagaStateRepository')",
"title": "State Repository Name",
"type": "string"
},
"state_repository_module": {
"description": "Module path for the state_repository_name",
"title": "State Repository Module",
"type": "string"
},
"triggering_events": {
"description": "List of events that can initiate this Saga.",
"items": {
"$ref": "#/$defs/TriggerEventConfigInputDTO"
},
"title": "Triggering Events",
"type": "array"
},
"steps": {
"description": "List of steps defining the Saga's workflow.",
"items": {
"$ref": "#/$defs/SagaStepInputDTO"
},
"title": "Steps",
"type": "array"
},
"completion_event_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the Event indicating successful completion of the entire Saga.",
"title": "Completion Event Name"
},
"completion_event_module": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Module path for the completion_event_name.",
"title": "Completion Event Module"
},
"failure_event_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the Event indicating failure of the entire Saga (after compensations).",
"title": "Failure Event Name"
},
"failure_event_module": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Module path for the failure_event_name.",
"title": "Failure Event Module"
},
"imports": {
"description": "Custom imports needed for the orchestrator.",
"items": {
"$ref": "#/$defs/ImportDefinitionDTO"
},
"title": "Imports",
"type": "array"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional description for the saga orchestrator.",
"title": "Description"
}
},
"required": [
"name",
"saga_type",
"state_dto_name",
"state_dto_module",
"state_repository_name",
"state_repository_module",
"steps"
],
"title": "SagaOrchestratorInputDTO",
"type": "object"
}
Naming and Location Conventions
Class: PascalCase, typically ends with 'Orchestrator'. File: ${saga_orchestrator_name}.py (based on ${saga_orchestrator_name}). Location: app/domain/${bounded_ctx}/sagas. (Requires context: ['bounded_ctx'])
Example Definition
{
"name": "OrderProcessingSagaOrchestrator",
"saga_type": "OrderProcessingSaga",
"state_dto_name": "OrderProcessingSagaState",
"state_dto_module": "app_root_name.domain.ordering.sagas.order_processing_saga_state",
"state_repository_name": "OrderProcessingSagaStateRepository",
"state_repository_module": "app_root_name.infrastructure.persistence.ordering.repositories.order_processing_saga_state_repository",
"triggering_events": [
{
"event_name": "OrderCreatedEvent",
"event_module": "app_root_name.domain.ordering.events.order_events",
"correlation_id_provider_str": "lambda event: str(event.order_id)"
}
],
"steps": [
{
"step_name": "ProcessPayment",
"command_name": "ProcessPaymentCommand",
"command_module": "app_root_name.application.payments.commands",
"success_event_name": "PaymentProcessedEvent",
"success_event_module": "app_root_name.domain.payments.events"
},
{
"step_name": "ShipOrder",
"command_name": "ShipOrderCommand",
"command_module": "app_root_name.application.shipping.commands",
"success_event_name": "OrderShippedEvent",
"success_event_module": "app_root_name.domain.shipping.events",
"compensation_command_name": "CancelShipmentCommand",
"compensation_command_module": "app_root_name.application.shipping.commands"
}
],
"completion_event_name": "OrderProcessingCompletedEvent",
"completion_event_module": "app_root_name.domain.ordering.events.order_events",
"failure_event_name": "OrderProcessingFailedEvent",
"failure_event_module": "app_root_name.domain.ordering.events.order_events"
}