feat(extensibility): migrate n8n hook execution to per-workflow MCP tool invocation

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sap-cloud-sdk"
-version = "0.53.0"
+version = "0.54.0"
 description = "SAP Cloud SDK for Python"
 readme = "README.md"
 license = "Apache-2.0"
@@ -41,7 +41,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-extensibility = ["a2a-sdk>=0.2.0,<2"]
+extensibility = ["a2a-sdk>=0.2.0,<1"]
 starlette = ["starlette>=0.40.0,<1"]
 fastapi = ["fastapi>=0.100.0,<1"]
 aiohttp = ["aiohttp>=3.9.0,<4"]
@@ -75,7 +75,7 @@ dev = [
     "sqlalchemy>=2.0.0",
     "django>=4.0",
     "flask>=3.0",
-    "a2a-sdk>=0.2.0",
+    "a2a-sdk>=0.2.0,<1",
     "langchain-core>=1.2.7",
     "langgraph>=0.2.0",
     "langchain-community>=0.3.0",

src/sap_cloud_sdk/core/telemetry/__init__.py

@@ -43,6 +43,7 @@
     ATTR_SUMMARY_TOOL_CALL_COUNT,
     ATTR_SUMMARY_HOOK_CALL_COUNT,
     ATTR_SUMMARY_HAS_INSTRUCTION,
+    ATTR_SUMMARY_JOULE_STUDIO_GSID,
     resolve_source_info,
     build_extension_span_attributes,
     reset_tool_call_metrics,
@@ -96,6 +97,7 @@
     "ATTR_SUMMARY_TOOL_CALL_COUNT",
     "ATTR_SUMMARY_HOOK_CALL_COUNT",
     "ATTR_SUMMARY_HAS_INSTRUCTION",
+    "ATTR_SUMMARY_JOULE_STUDIO_GSID",
     "resolve_source_info",
     "build_extension_span_attributes",
     "reset_tool_call_metrics",

src/sap_cloud_sdk/core/telemetry/extensions.py

@@ -217,6 +217,7 @@ def get_extension_context() -> dict[str, Any] | None:
 ATTR_SUMMARY_TOOL_CALL_COUNT = "sap.extension.summary.toolCallCount"
 ATTR_SUMMARY_HOOK_CALL_COUNT = "sap.extension.summary.hookCallCount"
 ATTR_SUMMARY_HAS_INSTRUCTION = "sap.extension.summary.hasInstruction"
+ATTR_SUMMARY_JOULE_STUDIO_GSID = "sap.extension.summary.joule_studio_gsid"
 
 # ---------------------------------------------------------------------------
 # Private state
@@ -612,6 +613,7 @@ def emit_extensions_summary_span(
     hook_call_count: int,
     has_instruction: bool,
     total_duration_ms: float,
+    joule_studio_gsid: str = "",
 ) -> None:
     """Emit a sibling summary span with aggregate extension metrics.
 
@@ -633,6 +635,8 @@ def emit_extensions_summary_span(
             into the system prompt.
         total_duration_ms: Wall-clock sum (milliseconds) of all extension
             operations.
+        joule_studio_gsid: Global solution ID of Joule Studio (empty string
+            if not available).
     """
     total = tool_call_count + hook_call_count + (1 if has_instruction else 0)
     attrs = {
@@ -642,6 +646,8 @@ def emit_extensions_summary_span(
         ATTR_SUMMARY_HOOK_CALL_COUNT: hook_call_count,
         ATTR_SUMMARY_HAS_INSTRUCTION: has_instruction,
     }
+    if joule_studio_gsid:
+        attrs[ATTR_SUMMARY_JOULE_STUDIO_GSID] = joule_studio_gsid
     span = _tracer.start_span("agent_extensions_summary", attributes=attrs)
     span.end()
 

src/sap_cloud_sdk/extensibility/_models.py

@@ -236,11 +236,17 @@ class N8nWorkflowConfig:
     """n8n workflow configuration embedded in a hook.
 
     Attributes:
-        workflow_id: n8n workflow ID.
+        ord_id: ORD ID of the API resource for this workflow.
+        card_ord_id: MCP translation card ORD ID (per ADR-021).
+        tool_name: MCP tool name (apiName segment of ordId, per ADR-021).
+        global_tenant_id: Global tenant ID of the n8n workflow tenant (per ADR-022).
         method: HTTP method for the n8n webhook call.
     """
 
-    workflow_id: str
+    ord_id: str
+    card_ord_id: str
+    tool_name: str
+    global_tenant_id: str
     method: HTTPMethod
 
     @classmethod
@@ -250,7 +256,10 @@ def from_dict(cls, obj: Dict[str, Any]) -> N8nWorkflowConfig:
         Expected JSON shape::
 
             {
-                "workflowId": "unique_n8n_workflow_id",
+                "ordId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice:v1",
+                "cardOrdId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice_mcp:v1",
+                "toolName": "postInvoice",
+                "globalTenantId": "tenant-abc",
                 "method": "POST"
             }
 
@@ -262,7 +271,10 @@ def from_dict(cls, obj: Dict[str, Any]) -> N8nWorkflowConfig:
         """
         method = _parse_http_method(obj.get("method", "POST")) or HTTPMethod.POST
         return cls(
-            workflow_id=obj.get("workflowId", ""),
+            ord_id=obj.get("ordId", ""),
+            card_ord_id=obj.get("cardOrdId", ""),
+            tool_name=obj.get("toolName", ""),
+            global_tenant_id=obj.get("globalTenantId", ""),
             method=method,
         )
 
@@ -338,7 +350,10 @@ def from_dict(cls, obj: Dict[str, Any]) -> Hook:
                 "order": 1,
                 "canShortCircuit": true,
                 "n8nWorkflowConfig": {
-                    "workflowId": "unique_n8n_workflow_id",
+                    "ordId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice:v1",
+                    "cardOrdId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice_mcp:v1",
+                    "toolName": "postInvoice",
+                    "globalTenantId": "tenant-abc",
                     "method": "POST"
                 }
             }
@@ -641,6 +656,9 @@ class ExtensionCapabilityImplementation:
         hooks: List of hooks attached for this extension capability.
         source: Per-tool and per-hook attribution mapping. ``None`` when the
             backend does not provide source information.
+        joule_studio_gsid: Global solution ID of Joule Studio. Set when a
+            single Joule Studio extension contributes to this capability;
+            empty string otherwise.
     """
 
     capability_id: str
@@ -649,6 +667,7 @@ class ExtensionCapabilityImplementation:
     instruction: Optional[str] = None
     hooks: List[Hook] = field(default_factory=list)
     source: Optional[ExtensionSourceMapping] = None
+    joule_studio_gsid: str = ""
 
     @classmethod
     def from_dict(cls, obj: Dict[str, Any]) -> ExtensionCapabilityImplementation:
@@ -679,7 +698,10 @@ def from_dict(cls, obj: Dict[str, Any]) -> ExtensionCapabilityImplementation:
                         "order": 1,
                         "canShortCircuit": true,
                         "n8nWorkflowConfig": {
-                            "workflowId": "unique_n8n_workflow_id",
+                            "ordId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice:v1",
+                            "cardOrdId": "sap.n8nwfrt:apiResource:invoice-po-solution_my-workflow.postInvoice_mcp:v1",
+                            "toolName": "postInvoice",
+                            "globalTenantId": "tenant-abc",
                             "method": "POST"
                         }
                     }

src/sap_cloud_sdk/extensibility/_ums_transport.py

@@ -74,7 +74,7 @@
             additions { type mcpConfig { globalTenantId ordId toolNames } }
           }
           hooks { id hookId type name onFailure timeout deploymentType canShortCircuit
-            n8nWorkflowConfig { workflowId method }
+            n8nWorkflowConfig { ordId cardOrdId toolName globalTenantId method }
           }
         }
       }
@@ -280,10 +280,11 @@ def _build_hook(raw: Dict[str, Any]) -> Optional[Hook]:
         return None
 
     n8n_config = raw.get("n8nWorkflowConfig") or {}
-    workflow_id = n8n_config.get("workflowId", "")
-    if not workflow_id:
+    tool_name = n8n_config.get("toolName", "")
+    card_ord_id = n8n_config.get("cardOrdId", "")
+    if not tool_name or not card_ord_id:
         logger.warning(
-            "Skipping hook with missing workflowId (hookId=%s)",
+            "Skipping hook with missing toolName or cardOrdId (hookId=%s)",
             raw.get("hookId"),
         )
         return None
@@ -295,7 +296,13 @@ def _build_hook(raw: Dict[str, Any]) -> Optional[Hook]:
     return Hook(
         id=raw.get("id", ""),
         hook_id=raw.get("hookId", ""),
-        n8n_workflow_config=N8nWorkflowConfig(workflow_id=workflow_id, method=method),
+        n8n_workflow_config=N8nWorkflowConfig(
+            ord_id=n8n_config.get("ordId", ""),
+            card_ord_id=n8n_config.get("cardOrdId", ""),
+            tool_name=tool_name,
+            global_tenant_id=n8n_config.get("globalTenantId", ""),
+            method=method,
+        ),
         name=raw.get("name", ""),
         type=hook_type,
         deployment_type=deployment_type,
@@ -404,13 +411,19 @@ def _transform_ums_response(
 
     instruction = "\n\n".join(instructions) if instructions else None
 
+    joule_studio_gsid = next(
+        (node.get("jouleStudioGsid") or "" for node in nodes if node.get("jouleStudioGsid")),
+        "",
+    )
+
     return ExtensionCapabilityImplementation(
         capability_id=capability_id,
         extension_names=extension_names,
         mcp_servers=mcp_servers,
         instruction=instruction,
         hooks=hooks,
         source=source,
+        joule_studio_gsid=joule_studio_gsid,
     )