Advanced input configurations

This page covers advanced configuration options for workflow user inputs, including dependencies, visibility controls, and dynamic defaults.

Visibility controls

Control when inputs are visible using the visible property.

Static

{
  "hiddenInput": {
    "type": "string",
    "title": "Hidden Input",
    "visible": false
  }
}

Dynamic with JQ

{
  "properties": {
    "deploymentType": {
      "type": "string",
      "title": "Deployment Type",
      "enum": ["standard", "canary", "blue-green"]
    },
    "canaryPercentage": {
      "type": "number",
      "title": "Canary Percentage",
      "minimum": 1,
      "maximum": 100,
      "visible": {
        "jqQuery": ".form.deploymentType == \"canary\""
      }
    }
  }
}

The canaryPercentage input only appears when deploymentType is set to "canary".

Dynamic defaults

Set default values dynamically using JQ expressions.

Based on other inputs

{
  "properties": {
    "serviceName": {
      "type": "string",
      "title": "Service Name"
    },
    "repositoryName": {
      "type": "string",
      "title": "Repository Name",
      "default": {
        "jqQuery": ".form.serviceName + \"-repo\""
      }
    }
  }
}

Based on context

{
  "requestedBy": {
    "type": "string",
    "format": "user",
    "title": "Requested By",
    "default": {
      "jqQuery": ".trigger.by.user.email"
    },
    "readOnly": true
  }
}

Conditional defaults

{
  "properties": {
    "environment": {
      "type": "string",
      "title": "Environment",
      "enum": ["development", "production"]
    },
    "replicas": {
      "type": "number",
      "title": "Replicas",
      "default": {
        "jqQuery": "if .form.environment == \"production\" then 3 else 1 end"
      }
    }
  }
}

Read-only inputs

Mark inputs as read-only to display values that users cannot modify:

{
  "workflowRunId": {
    "type": "string",
    "title": "Workflow Run ID",
    "default": {
      "jqQuery": ".run.id"
    },
    "readOnly": true
  }
}

Disabled inputs

Use the disabled property to disable an input, preventing user interaction. Unlike readOnly, a disabled input:

• Is excluded from the submitted data - its value is not sent when the form is submitted.
• Is automatically removed from required validation - even if the input is listed in required, it will not block submission when disabled.

This is useful when you want to conditionally remove an input from the form based on other input values, while still showing it in a non-interactive state.

Static

{
  "properties": {
    "cluster": {
      "type": "string",
      "format": "entity",
      "blueprint": "cluster",
      "title": "Cluster",
      "disabled": true
    }
  }
}

Dynamic with JQ

{
  "properties": {
    "environment": {
      "type": "string",
      "title": "Environment",
      "enum": ["development", "staging", "production"]
    },
    "approver": {
      "type": "string",
      "format": "user",
      "title": "Approver",
      "disabled": {
        "jqQuery": ".form.environment != \"production\""
      }
    }
  }
}

The approver input is disabled unless the selected environment is "production". When disabled, its value is not submitted and it is not required.

Disabled vs. read-only

• readOnly - the input is visible with its value, the user cannot change it, but the value is included in the submitted data.
• disabled - the input is visible but grayed out, the user cannot interact with it, and the value is excluded from the submitted data and from required validation.

Form validations

Use the validations property to define custom validation rules that run when the form is submitted. Each rule uses a JQ expression to evaluate a constraint against the form data. If the constraint evaluates to false, the form displays an error message and submission is blocked.

You can define up to 10 validation rules. Each rule has the following fields:

Field	Type	Required	Description
constraint	string	Yes	A JQ expression that should evaluate to true for the form to be valid.
message	string	Yes	The error message displayed when the constraint evaluates to false (max 100 characters).

Top-level validations

Add validations to the userInputs object to validate across all inputs:

{
  "userInputs": {
    "properties": {
      "minReplicas": {
        "type": "number",
        "title": "Minimum Replicas"
      },
      "maxReplicas": {
        "type": "number",
        "title": "Maximum Replicas"
      }
    },
    "required": ["minReplicas", "maxReplicas"],
    "validations": [
      {
        "constraint": ".form.maxReplicas >= .form.minReplicas",
        "message": "Maximum replicas must be greater than or equal to minimum replicas"
      }
    ]
  }
}

Step-level validations

When using multi-step forms with steps, add validations to individual steps instead of the top level:

{
  "userInputs": {
    "properties": {
      "cpuLimit": {
        "type": "number",
        "title": "CPU Limit (cores)"
      },
      "memoryLimit": {
        "type": "number",
        "title": "Memory Limit (GB)"
      }
    },
    "steps": [
      {
        "title": "Resource Limits",
        "order": ["cpuLimit", "memoryLimit"],
        "validations": [
          {
            "constraint": ".form.cpuLimit <= 8",
            "message": "CPU limit cannot exceed 8 cores"
          },
          {
            "constraint": ".form.memoryLimit <= 32",
            "message": "Memory limit cannot exceed 32 GB"
          }
        ]
      }
    ]
  }
}

Validations and steps

Top-level validations cannot be used when steps is defined. Add validations to individual steps instead.

Input ordering

Control the display order of inputs using the order property:

{
  "properties": {
    "name": { "type": "string", "title": "Name" },
    "environment": { "type": "string", "title": "Environment" },
    "description": { "type": "string", "title": "Description" }
  },
  "order": ["environment", "name", "description"]
}

Example

This example shows a userInputs configuration that combines input dependencies, conditional defaults, visibility controls, disabled inputs, and form validations for a deployment form.

Deployment form configuration (click to expand)

{
  "userInputs": {
    "properties": {
      "environment": {
        "type": "string",
        "title": "Environment",
        "enum": ["development", "staging", "production"],
        "enumColors": {
          "development": "blue",
          "staging": "orange",
          "production": "green"
        }
      },
      "service": {
        "type": "string",
        "format": "entity",
        "blueprint": "service",
        "title": "Service",
        "dataset": {
          "combinator": "and",
          "rules": [
            {
              "property": "environment",
              "operator": "=",
              "value": { "jqQuery": ".form.environment" }
            }
          ]
        }
      },
      "version": {
        "type": "string",
        "title": "Version",
        "description": "Version tag to deploy"
      },
      "replicas": {
        "type": "number",
        "title": "Replicas",
        "default": {
          "jqQuery": "if .form.environment == \"production\" then 3 else 1 end"
        }
        "minimum": 1,
        "maximum": 10
      },
      "enableMonitoring": {
        "type": "boolean",
        "title": "Enable Monitoring",
        "default": {
          "jqQuery": ".form.environment == \"production\""
        }
      },
      "monitoringEndpoint": {
        "type": "string",
        "format": "url",
        "title": "Monitoring Endpoint",
        "visible": {
          "jqQuery": ".form.enableMonitoring == true"
        }
      },
      "approver": {
        "type": "string",
        "format": "user",
        "title": "Approver",
        "disabled": {
          "jqQuery": ".form.environment != \"production\""
        }
      }
    },
    "required": ["environment", "service", "version", "approver"],
    "order": [
      "environment",
      "service",
      "version",
      "replicas",
      "enableMonitoring",
      "monitoringEndpoint",
      "approver"
    ],
    "validations": [
      {
        "constraint": "if .form.environment == \"production\" then .form.replicas >= 2 else true end",
        "message": "Production deployments require at least 2 replicas"
      }
    ]
  }
}