Preserve jqQuery wrapper in dataset rule values (#325)

geymed · web-flow · commit d44de35ad781 · 2026-01-26T11:41:00.000+02:00
The DatasetValue.MarshalJSON method was incorrectly flattening jqQuery
values when sending to the Port API. Instead of outputting the required
{"jqQuery": "..."} format, it was outputting raw values.

This caused dynamic JQ expressions in dataset rules (like .form.field_name
or .user.teams) to be treated as literal strings, breaking entity filtering
in self-service actions.

Before: {"value": ".form.selected_team"}
After:  {"value": {"jqQuery": ".form.selected_team"}}
diff --git a/examples/resources/port_action/dynamic_form_filters/README.md b/examples/resources/port_action/dynamic_form_filters/README.md
@@ -0,0 +1,83 @@
+# Dynamic Form Filters Example
+
+This example demonstrates how to use dynamic JQ expressions in dataset rules to create dependent form fields where the options in one field are filtered based on the selection in another field.
+
+## Use Case
+
+When building self-service actions, you often need to filter entity selectors based on:
+- User's form selections (`.form.field_name`)
+- Current user's context (`.user.teams`, `.user.email`)
+- Entity context (`.entity.properties.field`)
+
+## How It Works
+
+1. User selects a team from the "Select Team" dropdown (e.g., "engineering")
+2. The "Target Service" entity selector automatically filters to show only services where:
+   - `team` matches the selected team (dynamic)
+   - `environment` is NOT "production" (literal string comparison)
+3. The filtering is dynamic - changing the team selection updates the available services
+
+## Key Configuration
+
+```hcl
+dataset = {
+  combinator = "and"
+  rules = [
+    # Dynamic JQ expression - evaluates form input at runtime
+    {
+      property = "team"
+      operator = "="
+      value = {
+        jq_query = ".form.selected_team"
+      }
+    },
+    # Literal string comparison - note the escaped quotes
+    {
+      property = "environment"
+      operator = "!="
+      value = {
+        jq_query = "\"production\""
+      }
+    }
+  ]
+}
+```
+
+## JQ Expression Types
+
+| Type | Example | Description |
+|------|---------|-------------|
+| Dynamic | `.form.selected_team` | Evaluates to the form field value at runtime |
+| Literal | `"\"production\""` | A literal string "production" (quotes inside) |
+
+## Running the Example
+
+```bash
+# Set credentials
+export TF_VAR_port_client_id="your-client-id"
+export TF_VAR_port_client_secret="your-client-secret"
+
+# Apply
+terraform init
+terraform apply
+
+# Cleanup
+terraform destroy
+```
+
+## Testing
+
+1. Go to Port UI → Self-Service Actions
+2. Find "Select Service by Team"
+3. Select "engineering" → see only `dev-api-service` (prod is filtered out)
+4. Select "platform" → see `staging-web-frontend` and `dev-web-frontend`
+
+## Common JQ Expressions
+
+| Expression | Description |
+|------------|-------------|
+| `.form.field_name` | Value from another form field |
+| `.user.teams` | Current user's team memberships |
+| `.user.email` | Current user's email |
+| `.entity.identifier` | Current entity's identifier |
+| `"literal"` | A literal string value |
diff --git a/examples/resources/port_action/dynamic_form_filters/main.tf b/examples/resources/port_action/dynamic_form_filters/main.tf
@@ -0,0 +1,166 @@
+# Example: Dynamic Form Filters with JQ Expressions
+#
+# This example demonstrates how to use dynamic JQ expressions in dataset rules
+# to filter entity selectors based on form input values.
+
+terraform {
+  required_providers {
+    port = {
+      source  = "port-labs/port-labs"
+      version = "~> 2.0"
+    }
+  }
+}
+
+provider "port" {
+  client_id = var.port_client_id
+  secret    = var.port_client_secret
+}
+
+variable "port_client_id" {
+  type        = string
+  description = "Port client ID"
+}
+
+variable "port_client_secret" {
+  type        = string
+  sensitive   = true
+  description = "Port client secret"
+}
+
+# Create a service blueprint
+resource "port_blueprint" "service" {
+  title      = "Service"
+  icon       = "Microservice"
+  identifier = "dynamic_filter_example_service"
+  properties = {
+    string_props = {
+      "environment" = {
+        title = "Environment"
+        enum  = ["development", "staging", "production"]
+      }
+      "team" = {
+        title = "Team"
+      }
+    }
+  }
+}
+
+# Create test entities - mix of environments and teams
+resource "port_entity" "service_dev_engineering" {
+  identifier = "service-dev-api"
+  title      = "dev-api-service"
+  blueprint  = port_blueprint.service.identifier
+  
+  properties = {
+    string_props = {
+      "environment" = "development"
+      "team"        = "engineering"
+    }
+  }
+}
+
+resource "port_entity" "service_staging_platform" {
+  identifier = "service-staging-web"
+  title      = "staging-web-frontend"
+  blueprint  = port_blueprint.service.identifier
+  
+  properties = {
+    string_props = {
+      "environment" = "staging"
+      "team"        = "platform"
+    }
+  }
+}
+
+resource "port_entity" "service_prod_engineering" {
+  identifier = "service-prod-api"
+  title      = "prod-api-service"
+  blueprint  = port_blueprint.service.identifier
+  
+  properties = {
+    string_props = {
+      "environment" = "production"
+      "team"        = "engineering"
+    }
+  }
+}
+
+resource "port_entity" "service_dev_platform" {
+  identifier = "service-dev-web"
+  title      = "dev-web-frontend"
+  blueprint  = port_blueprint.service.identifier
+  
+  properties = {
+    string_props = {
+      "environment" = "development"
+      "team"        = "platform"
+    }
+  }
+}
+
+# Action with dynamic form filtering
+# The entity selector filters based on the team selected in the form AND environment
+resource "port_action" "select_service" {
+  title      = "Select Service by Team"
+  identifier = "dynamic_filter_example_select_service"
+  
+  self_service_trigger = {
+    operation            = "DAY-2"
+    blueprint_identifier = port_blueprint.service.identifier
+    
+    order_properties = ["selected_team", "target_service"]
+    
+    user_properties = {
+      string_props = {
+        # First field: Team selector dropdown
+        selected_team = {
+          title       = "Select Team"
+          description = "Choose a team to filter services"
+          enum        = ["engineering", "platform"]
+        }
+        
+        # Second field: Entity selector filtered by the selected team AND non-prod environment
+        target_service = {
+          title      = "Target Service"
+          format     = "entity"
+          blueprint  = port_blueprint.service.identifier
+          depends_on = ["selected_team"]
+          
+          # Dynamic filtering using JQ expressions
+          dataset = {
+            combinator = "and"
+            rules = [
+              # Rule 1: Dynamic filter - team matches form selection
+              # .form.selected_team evaluates to the user's selection at runtime
+              {
+                property = "team"
+                operator = "="
+                value = {
+                  jq_query = ".form.selected_team"
+                }
+              },
+              # Rule 2: Literal string filter - only non-production environments
+              # The value is wrapped in quotes to indicate it's a literal string in JQ
+              {
+                property = "environment"
+                operator = "!="
+                value = {
+                  jq_query = "\"production\""
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+  
+  webhook_method = {
+    url = "https://example.com/webhook"
+  }
+}
+
+output "action_identifier" {
+  value = port_action.select_service.identifier
+}
diff --git a/internal/cli/models.go b/internal/cli/models.go
@@ -175,27 +175,17 @@ func (dv *DatasetValue) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
-// Custom MarshalJSON for DatasetValue to preserve the original format when possible
+// Custom MarshalJSON for DatasetValue to always preserve the jqQuery wrapper.
+// The Port API expects dataset rule values to be in the format {"jqQuery": "..."}
+// for dynamic JQ expression evaluation.
 func (dv DatasetValue) MarshalJSON() ([]byte, error) {
-
 	if dv.JqQuery == "" {
 		return []byte("null"), nil
 	}
 
-	if dv.JqQuery == "true" || dv.JqQuery == "false" {
-		return []byte(dv.JqQuery), nil
-	}
-
-	var numTest float64
-	if err := json.Unmarshal([]byte(dv.JqQuery), &numTest); err == nil {
-		return []byte(dv.JqQuery), nil
-	}
-
-	if len(dv.JqQuery) >= 2 && dv.JqQuery[0] == '"' && dv.JqQuery[len(dv.JqQuery)-1] == '"' {
-		return []byte(dv.JqQuery), nil
-	}
-
-	return json.Marshal(dv.JqQuery)
+	// Always output the jqQuery wrapper - the API requires this format
+	// for proper JQ expression evaluation in dataset rules
+	return json.Marshal(map[string]string{"jqQuery": dv.JqQuery})
 }
 
 type (
