Skip to content

Automate browser based workflows with AI

feat: add workflow-level inherited error_code_mapping (SKY-8855) (#5506)

Aaron Perezbded188adba7
diff --git a/skyvern/forge/sdk/workflow/models/block.py b/skyvern/forge/sdk/workflow/models/block.py
index 93beae61d..a22eabadc 100644
--- a/skyvern/forge/sdk/workflow/models/block.py
+++ b/skyvern/forge/sdk/workflow/models/block.py
@@ -794,14 +794,22 @@ class BaseTaskBlock(Block):
self.terminate_criterion, workflow_run_context
)
- if self.error_code_mapping:
+ # Inherit workflow-level error_code_mapping; block-level entries override on key conflicts.
+ workflow = getattr(workflow_run_context, "workflow", None)
+ workflow_error_code_mapping: dict[str, str] | None = None
+ if workflow is not None and workflow.workflow_definition is not None:
+ workflow_error_code_mapping = workflow.workflow_definition.error_code_mapping
+
+ if workflow_error_code_mapping or self.error_code_mapping:
+ merged_mapping = dict(workflow_error_code_mapping or {})
+ merged_mapping.update(self.error_code_mapping or {})
self.error_code_mapping = {
self.format_block_parameter_template_from_workflow_run_context(error_code, workflow_run_context): (
self.format_block_parameter_template_from_workflow_run_context(
error_description, workflow_run_context
)
)
- for error_code, error_description in self.error_code_mapping.items()
+ for error_code, error_description in merged_mapping.items()
}
@staticmethod
diff --git a/skyvern/forge/sdk/workflow/models/workflow.py b/skyvern/forge/sdk/workflow/models/workflow.py
index 29a71bc52..cddff396b 100644
--- a/skyvern/forge/sdk/workflow/models/workflow.py
+++ b/skyvern/forge/sdk/workflow/models/workflow.py
@@ -55,6 +55,7 @@ class WorkflowDefinition(BaseModel):
parameters: list[PARAMETER_TYPE]
blocks: List[BlockTypeVar]
finally_block_label: str | None = None
+ error_code_mapping: dict[str, str] | None = None
def validate(self) -> None:
all_labels: set[str] = set()
diff --git a/skyvern/forge/sdk/workflow/workflow_definition_converter.py b/skyvern/forge/sdk/workflow/workflow_definition_converter.py
index 213efa6f1..bc030de55 100644
--- a/skyvern/forge/sdk/workflow/workflow_definition_converter.py
+++ b/skyvern/forge/sdk/workflow/workflow_definition_converter.py
@@ -322,6 +322,7 @@ def convert_workflow_definition(
blocks=blocks,
version=dag_version,
finally_block_label=workflow_definition_yaml.finally_block_label,
+ error_code_mapping=workflow_definition_yaml.error_code_mapping,
)
LOG.info(
diff --git a/skyvern/schemas/workflows.py b/skyvern/schemas/workflows.py
index d938a70ab..043a5e146 100644
--- a/skyvern/schemas/workflows.py
+++ b/skyvern/schemas/workflows.py
@@ -79,6 +79,29 @@ def _replace_references_in_value(value: Any, old_key: str, new_key: str) -> Any:
return value
+def _rewrite_error_code_mapping_refs_atomic(mapping: Any, substitutions: list[tuple[str, str]]) -> Any:
+ """Atomically rewrites Jinja references (keys and values) in an error_code_mapping dict.
+
+ Uses unique sentinels so chained rewrites don't occur when one substitution's new
+ identifier matches another's old identifier (e.g. foo-bar -> foo_bar AND foo_bar -> foo_bar_2).
+ """
+ if not isinstance(mapping, dict) or not substitutions:
+ return mapping
+
+ sentinels = [(old, new, f"\x00SKY_SANITIZE_{i}\x00") for i, (old, new) in enumerate(substitutions)]
+
+ def _apply(text: str) -> str:
+ for old, _new, sentinel in sentinels:
+ text = replace_jinja_reference(text, old, sentinel)
+ for _old, new, sentinel in sentinels:
+ text = text.replace(sentinel, new)
+ return text
+
+ return {
+ (_apply(k) if isinstance(k, str) else k): (_apply(v) if isinstance(v, str) else v) for k, v in mapping.items()
+ }
+
+
def _replace_direct_string_in_value(value: Any, old_key: str, new_key: str) -> Any:
"""Recursively replaces exact string matches in a value (for fields like source_parameter_key)."""
if isinstance(value, str):
@@ -316,6 +339,20 @@ def sanitize_workflow_yaml_with_references(workflow_yaml: dict[str, Any]) -> dic
workflow_definition["parameters"], old_key, new_key
)
+ # Rewrite workflow-level error_code_mapping atomically so substitutions don't chain
+ # (e.g. foo-bar -> foo_bar and foo_bar -> foo_bar_2 must not combine into foo_bar_2).
+ if "error_code_mapping" in workflow_definition:
+ substitutions: list[tuple[str, str]] = []
+ for old_label, new_label in label_mapping.items():
+ # More specific output-key substitution must come before the bare label.
+ substitutions.append((f"{old_label}_output", f"{new_label}_output"))
+ substitutions.append((old_label, new_label))
+ for old_key, new_key in param_key_mapping.items():
+ substitutions.append((old_key, new_key))
+ workflow_definition["error_code_mapping"] = _rewrite_error_code_mapping_refs_atomic(
+ workflow_definition["error_code_mapping"], substitutions
+ )
+
# Step 5: Update parameter_keys arrays in blocks
if param_key_mapping and "blocks" in workflow_definition:
workflow_definition["blocks"] = _update_parameter_keys_in_blocks(
@@ -1039,6 +1076,7 @@ class WorkflowDefinitionYAML(BaseModel):
parameters: list[PARAMETER_YAML_TYPES]
blocks: list[BLOCK_YAML_TYPES]
finally_block_label: str | None = None
+ error_code_mapping: dict[str, str] | None = None
@model_validator(mode="after")
def validate_unique_block_labels(self) -> "WorkflowDefinitionYAML":
diff --git a/tests/unit/test_workflow_error_code_mapping_inheritance.py b/tests/unit/test_workflow_error_code_mapping_inheritance.py
new file mode 100644
index 000000000..fd0c4d365
--- /dev/null
+++ b/tests/unit/test_workflow_error_code_mapping_inheritance.py
@@ -0,0 +1,174 @@
+"""Tests for workflow-level error_code_mapping inheritance into blocks at execution time."""
+
+from datetime import datetime, timezone
+from unittest.mock import MagicMock
+
+from skyvern.forge.sdk.workflow.context_manager import WorkflowRunContext
+from skyvern.forge.sdk.workflow.models.block import TaskBlock
+from skyvern.forge.sdk.workflow.models.parameter import OutputParameter, ParameterType
+from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinition
+
+
+def _make_output_parameter() -> OutputParameter:
+ now = datetime.now(timezone.utc)
+ return OutputParameter(
+ parameter_type=ParameterType.OUTPUT,
+ key="task1_output",
+ description="test output",
+ output_parameter_id="op_task1",
+ workflow_id="w_test",
+ created_at=now,
+ modified_at=now,
+ )
+
+
+def _make_task_block(error_code_mapping: dict[str, str] | None = None) -> TaskBlock:
+ return TaskBlock(
+ label="task1",
+ output_parameter=_make_output_parameter(),
+ title="task title",
+ error_code_mapping=error_code_mapping,
+ )
+
+
+def _make_workflow(error_code_mapping: dict[str, str] | None) -> Workflow:
+ workflow_definition = WorkflowDefinition(
+ parameters=[],
+ blocks=[],
+ error_code_mapping=error_code_mapping,
+ )
+ now = datetime.now(timezone.utc)
+ return Workflow(
+ workflow_id="w_test",
+ organization_id="o_test",
+ title="test",
+ workflow_permanent_id="wpid_test",
+ version=1,
+ is_saved_task=False,
+ workflow_definition=workflow_definition,
+ created_at=now,
+ modified_at=now,
+ )
+
+
+def _make_workflow_run_context(workflow_error_code_mapping: dict[str, str] | None) -> WorkflowRunContext:
+ ctx = WorkflowRunContext(
+ workflow_title="test",
+ workflow_id="w_test",
+ workflow_permanent_id="wpid_test",
+ workflow_run_id="wr_test",
+ aws_client=MagicMock(),
+ workflow=_make_workflow(workflow_error_code_mapping),
+ )
+ return ctx
+
+
+class TestWorkflowLevelErrorCodeMappingInheritance:
+ def test_block_inherits_workflow_mapping_when_none(self) -> None:
+ block = _make_task_block(error_code_mapping=None)
+ ctx = _make_workflow_run_context({"ACCOUNT_NOT_FOUND": "If no records found, terminate"})
+
+ block.format_potential_template_parameters(ctx)
+
+ assert block.error_code_mapping == {"ACCOUNT_NOT_FOUND": "If no records found, terminate"}
+
+ def test_block_merges_with_workflow_mapping(self) -> None:
+ block = _make_task_block(error_code_mapping={"BLOCK_ERROR": "block-level error"})
+ ctx = _make_workflow_run_context({"WORKFLOW_ERROR": "workflow-level error"})
+
+ block.format_potential_template_parameters(ctx)
+
+ assert block.error_code_mapping == {
+ "WORKFLOW_ERROR": "workflow-level error",
+ "BLOCK_ERROR": "block-level error",
+ }
+
+ def test_block_level_overrides_workflow_on_conflict(self) -> None:
+ block = _make_task_block(error_code_mapping={"SHARED_KEY": "block wins"})
+ ctx = _make_workflow_run_context({"SHARED_KEY": "workflow loses"})
+
+ block.format_potential_template_parameters(ctx)
+
+ assert block.error_code_mapping == {"SHARED_KEY": "block wins"}
+
+ def test_no_workflow_mapping_preserves_block(self) -> None:
+ block = _make_task_block(error_code_mapping={"BLOCK_ERROR": "only block"})
+ ctx = _make_workflow_run_context(workflow_error_code_mapping=None)
+
+ block.format_potential_template_parameters(ctx)
+
+ assert block.error_code_mapping == {"BLOCK_ERROR": "only block"}
+
+ def test_both_none_stays_none(self) -> None:
+ block = _make_task_block(error_code_mapping=None)
+ ctx = _make_workflow_run_context(workflow_error_code_mapping=None)
+
+ block.format_potential_template_parameters(ctx)
+
+ assert block.error_code_mapping is None
+
+ def test_sanitizer_rewrites_references_in_workflow_error_code_mapping(self) -> None:
+ """Auto-sanitized labels/param keys must be rewritten inside workflow-level error_code_mapping."""
+ from skyvern.schemas.workflows import sanitize_workflow_yaml_with_references
+
+ workflow_yaml = {
+ "workflow_definition": {
+ "parameters": [{"key": "bad-key", "parameter_type": "workflow", "workflow_parameter_type": "string"}],
+ "blocks": [{"label": "block-1", "block_type": "task", "url": "https://example.com"}],
+ "error_code_mapping": {
+ "ERR": "reason {{ bad-key }} from {{ block-1_output }}",
+ "ERR_{{ bad-key }}": "key-side ref to {{ block-1_output }}",
+ },
+ }
+ }
+ sanitized = sanitize_workflow_yaml_with_references(workflow_yaml)
+ mapping = sanitized["workflow_definition"]["error_code_mapping"]
+ assert mapping == {
+ "ERR": "reason {{ bad_key }} from {{ block_1_output }}",
+ "ERR_{{ bad_key }}": "key-side ref to {{ block_1_output }}",
+ }
+
+ def test_sanitizer_does_not_chain_rewrites_in_error_code_mapping(self) -> None:
+ """Chained substitutions must not occur when one sanitized label collides with another's final name."""
+ from skyvern.schemas.workflows import sanitize_workflow_yaml_with_references
+
+ # Both labels need sanitization; the first normalizes to "foo_bar", colliding
+ # with the second whose normalization is "foo_bar", so it becomes "foo_bar_2".
+ workflow_yaml = {
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": [
+ {"label": "foo/bar", "block_type": "task", "url": "https://example.com"},
+ {"label": "foo-bar", "block_type": "task", "url": "https://example.com"},
+ ],
+ "error_code_mapping": {
+ "ERR": "first {{ foo/bar_output }}, second {{ foo-bar_output }}",
+ },
+ }
+ }
+ sanitized = sanitize_workflow_yaml_with_references(workflow_yaml)
+ # foo/bar -> foo_bar should stay as foo_bar (not chain-rewrite to foo_bar_2).
+ mapping = sanitized["workflow_definition"]["error_code_mapping"]
+ assert mapping == {"ERR": "first {{ foo_bar_output }}, second {{ foo_bar_2_output }}"}
+
+ def test_round_trip_does_not_bake_workflow_defaults(self) -> None:
+ """Regression: converted blocks must not persist workflow-level keys.
+
+ Without this guarantee, removing a workflow-level code would leave stale copies in each block
+ after a read-modify-write round-trip.
+ """
+ from skyvern.forge.sdk.workflow.workflow_definition_converter import block_yaml_to_block
+ from skyvern.schemas.workflows import TaskBlockYAML
+
+ block_yaml = TaskBlockYAML(
+ label="task1",
+ url="https://example.com",
+ navigation_goal="Do something",
+ error_code_mapping={"BLOCK_ERROR": "only block"},
+ )
+ output_param = _make_output_parameter()
+ parameters = {output_param.key: output_param}
+
+ block = block_yaml_to_block(block_yaml, parameters)
+ assert isinstance(block, TaskBlock)
+ assert block.error_code_mapping == {"BLOCK_ERROR": "only block"}