fix: prefer qualified refs for call web service

Symptom: review noted that structured `call web service` references were
always emitted as string literals even when they were normal `Module.Document`
references.

Root cause: the grammar only accepted STRING_LITERAL references, so the
formatter had to quote resolved SOAP services, operations, and mappings.

Fix: add a webServiceReference rule that accepts qualifiedName for resolved
references and STRING_LITERAL only as a dangling raw-ID fallback. Formatter now
emits bare qualified refs when possible and quoted refs only when necessary.
Docs, examples, proposal, and skill guidance were updated to match.

Tests: regenerate the parser, run focused web-service visitor/formatter tests,
then make build and make test.

Author: hjothamendix

.claude/skills/mendix/write-microflows.md

@@ -736,19 +736,17 @@ for new integrations; this syntax exists mainly so existing projects can
 round-trip without dropping SOAP actions.
 
 ```mdl
--- Structured form. SOAP references are quoted strings by design: DESCRIBE
--- prefers Module.Document names when references are resolvable, but raw IDs
--- and legacy document names must also round-trip.
-$Root = call web service 'SampleSOAP.OrderService'
-operation 'FetchSampleItems'
-send mapping 'SampleSOAP.OrderRequest'
-receive mapping 'SampleSOAP.OrderResponse'
+-- Structured form. Resolved SOAP references use normal qualified names.
+$Root = call web service SampleSOAP.OrderService
+operation FetchSampleItems
+send mapping SampleSOAP.OrderRequest
+receive mapping SampleSOAP.OrderResponse
 timeout 30
 on error rollback;
 
--- Raw IDs are accepted when old project references are dangling or unavailable.
+-- Quoted raw IDs are accepted when old project references are dangling or unavailable.
 $Root = call web service 'sample-service-id'
-operation 'FetchSampleItems'
+operation FetchSampleItems
 send mapping 'sample-send-mapping-id'
 receive mapping 'sample-receive-mapping-id';
 

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -228,7 +228,7 @@ authentication basic, session
 | Call nanoflow | `$Result = call nanoflow Module.Name (Param = $value);` | |
 | Call JS action | `$Result = call javascript action Module.Name (Param = $value);` | JavaScript action (nanoflow/microflow) |
 | Call Java action | `$Result = call java action Module.Name (Param = $value);` | Java action (microflow only) |
-| Call web service | `$Result = call web service 'Module.Service' operation 'OperationName';` | Legacy SOAP; quoted refs preserve raw IDs and legacy names |
+| Call web service | `$Result = call web service Module.Service operation OperationName;` | Legacy SOAP; quoted refs are fallback for dangling raw IDs |
 | Call web service raw | `$Result = call web service raw 'base64-bson';` | Escape hatch for byte-for-byte legacy SOAP round-trip |
 | Show page | `show page Module.PageName ($Param = $value);` | Also accepts `(Param: $value)` |
 | Close page | `close page;` | |

docs/11-proposals/PROPOSAL_microflow_call_web_service_statement.md

@@ -7,14 +7,14 @@ Status: Draft
 Add MDL support for legacy Mendix SOAP `Microflows$CallWebServiceAction`.
 
 ```mdl
-$Root = call web service 'SampleSOAP.OrderService'
-operation 'FetchSampleItems'
-send mapping 'SampleSOAP.OrderRequest'
-receive mapping 'SampleSOAP.OrderResponse'
+$Root = call web service SampleSOAP.OrderService
+operation FetchSampleItems
+send mapping SampleSOAP.OrderRequest
+receive mapping SampleSOAP.OrderResponse
 timeout 30;
 
 $Root = call web service 'dangling-service-id'
-operation 'FetchSampleItems'
+operation FetchSampleItems
 send mapping 'dangling-send-mapping-id'
 receive mapping 'dangling-receive-mapping-id';
 
@@ -44,13 +44,18 @@ The immediate goal is therefore fidelity:
 callWebServiceStatement
     : (VARIABLE EQUALS)? CALL WEB SERVICE
       (RAW STRING_LITERAL
-      | STRING_LITERAL
-        (OPERATION STRING_LITERAL)?
-        (SEND MAPPING STRING_LITERAL)?
-        (RECEIVE MAPPING STRING_LITERAL)?
+      | webServiceReference
+        (OPERATION webServiceReference)?
+        (SEND MAPPING webServiceReference)?
+        (RECEIVE MAPPING webServiceReference)?
         (TIMEOUT expression)?)
       onErrorClause?
     ;
+
+webServiceReference
+    : qualifiedName
+    | STRING_LITERAL
+    ;
 ```
 
 ## Design Notes
@@ -62,7 +67,8 @@ and mapping references. During `describe`, mxcli resolves known
 `Module.DocumentName`.
 
 If a reference is dangling or the backend cannot resolve it, mxcli deliberately
-falls back to the raw ID string so unsupported legacy projects still round-trip.
+falls back to a quoted raw ID string so unsupported legacy projects still
+round-trip without pretending the ID is a normal document name.
 
 The `raw` form is an explicit escape hatch. Its string is base64-encoded BSON
 for the complete action payload and is authoritative when re-executed. It exists
@@ -80,13 +86,11 @@ syntax covers them.
 ## Resolved Questions
 
 - Service and mapping references are emitted as `Module.Document` names when
-  the backend can resolve them. Raw IDs remain the fallback for dangling
-  references and incomplete project metadata.
-- The structured syntax uses quoted strings for service and mapping references
-  instead of `qualifiedName` tokens because legacy SOAP projects can contain
-  raw IDs or document names that are not valid MDL identifiers. Resolved
-  references should still be written as `Module.Document` text inside the
-  string literal.
+  the backend can resolve them. Raw IDs remain quoted fallback references for
+  dangling references and incomplete project metadata.
+- Structured resolved references use `qualifiedName` tokens for consistency
+  with other MDL document references. `STRING_LITERAL` is only the fallback for
+  dangling raw IDs and names that cannot be emitted as bare identifiers.
 
 ## Open Questions
 

mdl-examples/doctype-tests/call_web_service.mdl

@@ -8,10 +8,10 @@ create entity SampleSOAP.OrderResponse (
 create microflow SampleSOAP.ACT_FetchItems ()
 returns SampleSOAP.OrderResponse as $Root
 begin
-  $Root = call web service 'SampleSOAP.OrderService'
-  operation 'FetchSampleItems'
-  send mapping 'SampleSOAP.OrderRequest'
-  receive mapping 'SampleSOAP.OrderResponse'
+  $Root = call web service SampleSOAP.OrderService
+  operation FetchSampleItems
+  send mapping SampleSOAP.OrderRequest
+  receive mapping SampleSOAP.OrderResponse
   timeout 30
   on error rollback;
 
@@ -22,9 +22,9 @@ end;
 create microflow SampleSOAP.ACT_FetchItemsDanglingRefs ()
 returns SampleSOAP.OrderResponse as $Root
 begin
-  -- Raw IDs are preserved when describe cannot resolve dangling legacy refs.
+  -- Quoted raw IDs are preserved when describe cannot resolve dangling legacy refs.
   $Root = call web service 'sample-service-id'
-  operation 'FetchSampleItems'
+  operation FetchSampleItems
   send mapping 'sample-send-mapping-id'
   receive mapping 'sample-receive-mapping-id';
 

mdl/executor/cmd_microflows_format_action.go

@@ -874,22 +874,59 @@ func formatWebServiceCallAction(ctx *ExecContext, a *microflows.WebServiceCallAc
 		return prefix + "call web service raw " + mdlQuote(raw) + ";"
 	}
 
-	parts := []string{prefix + "call web service " + mdlQuote(resolveWebServiceReference(ctx, a.ServiceID))}
+	parts := []string{prefix + "call web service " + formatWebServiceReference(resolveWebServiceReference(ctx, a.ServiceID))}
 	if a.OperationName != "" {
-		parts = append(parts, "operation "+mdlQuote(a.OperationName))
+		parts = append(parts, "operation "+formatWebServiceReference(a.OperationName))
 	}
 	if a.SendMappingID != "" {
-		parts = append(parts, "send mapping "+mdlQuote(resolveWebServiceMappingReference(ctx, a.SendMappingID, true)))
+		parts = append(parts, "send mapping "+formatWebServiceReference(resolveWebServiceMappingReference(ctx, a.SendMappingID, true)))
 	}
 	if a.ReceiveMappingID != "" {
-		parts = append(parts, "receive mapping "+mdlQuote(resolveWebServiceMappingReference(ctx, a.ReceiveMappingID, false)))
+		parts = append(parts, "receive mapping "+formatWebServiceReference(resolveWebServiceMappingReference(ctx, a.ReceiveMappingID, false)))
 	}
 	if a.TimeoutExpression != "" {
 		parts = append(parts, "timeout "+strings.TrimRight(a.TimeoutExpression, " \t\n\r"))
 	}
 	return strings.Join(parts, "\n") + ";"
 }
 
+func formatWebServiceReference(ref string) string {
+	if isBareQualifiedReference(ref) {
+		return ref
+	}
+	return mdlQuote(ref)
+}
+
+func isBareQualifiedReference(ref string) bool {
+	if ref == "" {
+		return false
+	}
+	for _, part := range strings.Split(ref, ".") {
+		if !isBareIdentifier(part) {
+			return false
+		}
+	}
+	return true
+}
+
+func isBareIdentifier(part string) bool {
+	if part == "" {
+		return false
+	}
+	for i, r := range part {
+		if i == 0 {
+			if r != '_' && (r < 'A' || r > 'Z') && (r < 'a' || r > 'z') {
+				return false
+			}
+			continue
+		}
+		if r != '_' && (r < 'A' || r > 'Z') && (r < 'a' || r > 'z') && (r < '0' || r > '9') {
+			return false
+		}
+	}
+	return true
+}
+
 func resolveWebServiceReference(ctx *ExecContext, id model.ID) string {
 	raw := string(id)
 	if raw == "" || ctx == nil || ctx.Backend == nil {

mdl/executor/cmd_microflows_format_action_test.go

@@ -1171,7 +1171,7 @@ func TestFormatAction_WebServiceCallResolvesKnownReferences(t *testing.T) {
 		UseReturnVariable: true,
 	}
 	got := formatAction(ctx, action, nil, nil)
-	want := "$Root = call web service 'SyntheticSOAP.OrderService'\noperation 'FetchOrders'\nsend mapping 'SyntheticSOAP.OrderRequest'\nreceive mapping 'SyntheticSOAP.OrderResponse';"
+	want := "$Root = call web service SyntheticSOAP.OrderService\noperation FetchOrders\nsend mapping SyntheticSOAP.OrderRequest\nreceive mapping SyntheticSOAP.OrderResponse;"
 	if got != want {
 		t.Errorf("got %q, want %q", got, want)
 	}
@@ -1200,7 +1200,7 @@ func TestFormatAction_WebServiceCallKeepsRawReferencesWhenUnknown(t *testing.T)
 		OutputVariable:   "Root",
 	}
 	got := formatAction(ctx, action, nil, nil)
-	want := "$Root = call web service 'dangling-service-id'\noperation 'FetchOrders'\nsend mapping 'dangling-send-id'\nreceive mapping 'dangling-receive-id';"
+	want := "$Root = call web service 'dangling-service-id'\noperation FetchOrders\nsend mapping 'dangling-send-id'\nreceive mapping 'dangling-receive-id';"
 	if got != want {
 		t.Errorf("got %q, want %q", got, want)
 	}

mdl/grammar/MDLParser.g4

@@ -1492,21 +1492,25 @@ callJavaScriptActionStatement
 
 // Legacy SOAP call. The preferred structured form stores service and mapping
 // references in STRING_LITERAL tokens rather than qualifiedName tokens because
-// old projects can contain raw IDs or SOAP document names that are not valid
-// MDL identifiers. DESCRIBE still prefers Module.Document text when references
-// resolve; unresolved values pass through as strings. Raw BSON remains the
-// escape hatch for unsupported SOAP payload details.
+// Structured references prefer qualifiedName tokens. STRING_LITERAL remains as
+// a fallback for dangling raw IDs that cannot be represented as identifiers.
+// Raw BSON remains the escape hatch for unsupported SOAP payload details.
 callWebServiceStatement
     : (VARIABLE EQUALS)? CALL WEB SERVICE
       (RAW STRING_LITERAL
-      | STRING_LITERAL
-        (OPERATION STRING_LITERAL)?
-        (SEND MAPPING STRING_LITERAL)?
-        (RECEIVE MAPPING STRING_LITERAL)?
+      | webServiceReference
+        (OPERATION webServiceReference)?
+        (SEND MAPPING webServiceReference)?
+        (RECEIVE MAPPING webServiceReference)?
         (TIMEOUT expression)?)
       onErrorClause?
     ;
 
+webServiceReference
+    : qualifiedName
+    | STRING_LITERAL
+    ;
+
 // $Result = EXECUTE DATABASE QUERY Module.Connection.QueryName (param = 'value');
 // $Result = EXECUTE DATABASE QUERY Module.Connection.QueryName DYNAMIC 'SELECT ...';
 // $Result = EXECUTE DATABASE QUERY Module.Connection.QueryName CONNECTION (DBSource = $Url, DBUsername = $User, DBPassword = $Pass);