variable-creation

name	variable-creation
description	Create and manage Domo card variables (dropdowns, sliders, pills); function templates, control registration, card save flow, curl or CLI.

Variable Creation

Create Domo card variables (interactive controls) and output curl commands or CLI commands to execute them.

Variables are user-adjustable values that feed into Beast Mode formulas, enabling dynamic what-if analysis. They appear as dropdown, pill, slider, textbox, or date picker controls on cards and dashboards.

When to Use This Skill

• User asks for a dropdown, slider, or interactive control on a card
• User mentions "variable", "parameter", or describes wanting dynamic/adjustable values
• A card needs what-if analysis or user-selectable inputs
• You're building a card and realize a beast mode needs a user-controlled input

Core Workflow — 3-Step Creation

Variable creation requires three sequential API calls. All three are mandatory — skipping the middle step causes a 400 error on the card save.

1. Check name uniqueness (GET /query/v1/functions/variables/uniqueName)
2. Create the function template WITH embedded control (POST /query/v1/functions/template)
3. Register the variable control (PUT /content/v1/variable/controls)
4. Read the current card definition (PUT /content/v3/cards/kpi/definition)
5. Save the card with the new control (PUT /content/v3/cards/kpi/{cardId})

---

Prerequisites

Parameter	Source	Required
instanceUrl	Domo instance (e.g., domo-gordon-pont.domo.com)	Always
devToken	CLI auth / developer token	Always
cardId	Card ID	Always
dataSourceId	Dataset UUID (from card definition or columns)	For validation and card save

---

Variable Data Types

Data Type	Expression Examples	Compatible Controls
string	'TEST', 'Option A'	DROPDOWN, PILL, TEXTBOX
numeric	100, 0.5	DROPDOWN, PILL, SLIDER, TEXTBOX
date	CURRENT_DATE(), '2024-01-01'	DROPDOWN, DATE_PICKER

---

Variable Control Types

Type	Description	Best For
DROPDOWN	Select from a list of predefined values	Categorical selections, string/numeric/date
PILL	Inline toggle chips	Small number of options (2-5)
SLIDER	Numeric range slider	Numeric ranges with min/max
TEXTBOX	Free-text input	Open-ended string/numeric input
DATE_PICKER	Calendar date selector	Date variables

Expression Types by Data Type

Data Type	exprType
string	STRING_VALUE
numeric	NUMERIC_VALUE
date	DATE_VALUE

Values Array

For DROPDOWN and PILL controls, the values array defines the selectable options:

{"expression": {"value": "Option Text", "exprType": "STRING_VALUE"}}

For SLIDER controls, values define the min/max range:

[
  {"expression": {"value": "0", "exprType": "NUMERIC_VALUE"}},
  {"expression": {"value": "100", "exprType": "NUMERIC_VALUE"}}
]

---

Step 1: Check Name Uniqueness

Endpoint: GET /api/query/v1/functions/variables/uniqueName?name={name}

curl -X GET "https://{instanceUrl}/api/query/v1/functions/variables/uniqueName?name={variableName}" \
  -H "X-DOMO-Developer-Token: {devToken}"

Returns [] if the name is available. Returns an array of function template IDs if the name is already in use. Variable names must be globally unique across the entire Domo instance.

---

Step 2: Create the Function Template

Endpoint: POST /api/query/v1/functions/template

This creates the variable's function template. The request body must include an embedded control object — this is critical and differs from regular beast mode creation.

curl -X POST "https://{instanceUrl}/api/query/v1/functions/template" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{variableName}",
    "formula": "{defaultExpression}",
    "status": "VALID",
    "dataType": "{dataType}",
    "persistedOnDataSource": false,
    "isAggregatable": true,
    "bignumber": false,
    "owner": null,
    "nonAggregatedColumns": [],
    "legacyId": "calculation_{uuid}",
    "variable": true,
    "isCalculation": true,
    "initialPersistedOnDataSource": false,
    "saved": true,
    "query": "{defaultExpression}",
    "control": {
      "format": {"type": "default"},
      "controlType": "VARIABLE",
      "function": {
        "name": "{variableName}",
        "dataType": "{dataType}",
        "expression": "{defaultExpression}",
        "id": -201
      },
      "saveOverride": true,
      "description": "",
      "values": [
        {"expression": {"value": "{value1}", "exprType": "{exprType}"}},
        {"expression": {"value": "{value2}", "exprType": "{exprType}"}}
      ],
      "type": "{controlType}",
      "unsaved": true,
      "name": "{variableName}",
      "id": -101
    },
    "description": "",
    "locked": false,
    "cacheWindow": "non_dynamic",
    "containsAggregation": false,
    "containsAnalytic": false,
    "invalidColumns": [],
    "nonAggregatedExpressions": [],
    "formulaTemplateDependencies": [],
    "columnPositions": [],
    "formulaId": "calculation_{another_uuid}",
    "formulaDependencies": [],
    "isControlled": false,
    "global": true,
    "unsaved": true,
    "expression": "{defaultExpression}"
  }'

Key fields:

• variable: true — marks this as a variable function (not a regular beast mode)
• control — the embedded control definition with placeholder IDs (-201, -101)
• legacyId and formulaId — generate unique UUIDs in the format calculation_{uuid}
• global: true — variables are instance-wide
• owner: null — server assigns the owner

Response — save the id (numeric function template ID):

{
  "id": 1172,
  "name": "{variableName}",
  "legacyId": "calculation_{uuid}",
  "variable": true,
  ...
}

---

Step 3: Register the Variable Control

Endpoint: PUT /api/content/v1/variable/controls

This step registers the control with the Domo control system. Without this step, the card save will return 400.

curl -X PUT "https://{instanceUrl}/api/content/v1/variable/controls" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "format": {"type": "default"},
      "controlType": "VARIABLE",
      "function": {
        "name": "{variableName}",
        "dataType": "{dataType}",
        "expression": "{defaultExpression}",
        "id": {functionTemplateId from Step 2}
      },
      "saveOverride": true,
      "description": "",
      "values": [
        {"expression": {"value": "{value1}", "exprType": "{exprType}"}},
        {"expression": {"value": "{value2}", "exprType": "{exprType}"}}
      ],
      "type": "{controlType}",
      "unsaved": false,
      "name": "{variableName}"
    }
  ]'

Key differences from Step 2's control:

• function.id is now the real template ID from Step 2 (not -201)
• unsaved: false (not true)
• No id: -101 at the control level
• Body is an array of control objects

Response — returns an array with the registered control, including server-assigned id:

[
  {
    "id": 145,
    "function": {"id": 1172, ...},
    "type": "DROPDOWN",
    "values": [...],
    "controlType": "VARIABLE",
    ...
  }
]

---

Step 4: Read the Current Card Definition

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/definition" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dynamicText": true,
    "variables": true,
    "urn": "{cardId}"
  }'

Save the full response. You need definition.subscriptions, definition.controls, definition.charts, definition.modified, etc.

Get the dataSourceId from columns[].sourceId in the response.

---

Step 5: Save the Card with the New Control

Endpoint: PUT /api/content/v3/cards/kpi/{cardId}

Build the update payload by merging the new control into the card definition.

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/{cardId}" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "subscriptions": {existing subscriptions from card def — do NOT add dataSourceId here},
      "formulas": {"dsUpdated": [], "dsDeleted": [], "card": []},
      "annotations": {"new": [], "modified": [], "deleted": []},
      "conditionalFormats": {"card": [], "datasource": []},
      "controls": [{existing controls with saveOverride: true}, {new control}],
      "segments": {"active": [], "create": [], "update": [], "delete": []},
      "charts": {existing charts},
      "dynamicTitle": {existing dynamicTitle},
      "dynamicDescription": {"text": []},
      "chartVersion": "{existing chartVersion}",
      "allowTableDrill": true,
      "inputTable": false,
      "modified": {existing modified timestamp},
      "title": "{card title}",
      "description": ""
    },
    "dataProvider": {"dataSourceId": "{dataSourceId}"},
    "variables": true,
    "columns": false
  }'

Critical payload notes:

• variables: true and columns: false at the top level
• dataSourceId goes in dataProvider only — NOT in subscriptions.main
• formulas uses the {dsUpdated, dsDeleted, card} structure (not the array format from the read response)
• Existing controls must be passed in their full server format with saveOverride: true added
• The new control uses the simplified format with function.id = the template ID from Step 2
• The modified timestamp must match the card definition's value

---

Optional: Validate the Variable Formula

Endpoint: POST /api/query/v1/functions/validateFormulas

Validation is optional but recommended before creating. The formula entry must have "variable": true.

curl -X POST "https://{instanceUrl}/api/query/v1/functions/validateFormulas" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceId": "{dataSourceId}",
    "columns": [{column schema array}],
    "formulas": {
      "{formulaId}": {
        "id": "{formulaId}",
        "name": "{variableName}",
        "formula": "{defaultExpression}",
        "status": "valid",
        "dataType": "{dataType}",
        "variable": true,
        "templateId": null,
        "legacyId": "{formulaId}",
        "formulaDependencies": []
      }
    }
  }'

---

Using the Variable in a Beast Mode

A variable has no effect on a card unless it's referenced in a Beast Mode formula:

CASE
  WHEN `My Variable` = 'Option A' THEN `column_a`
  WHEN `My Variable` = 'Option B' THEN `column_b`
  ELSE `column_a`
END

Variables are referenced by name in backticks, just like dataset columns.

---

Three-Tier Control Hierarchy

Variables have three levels of override:

1. Default Control — Set in Beast Mode Editor (or via API). Baseline value.
2. Card Variable Control — Override in Analyzer for a specific card. Does NOT transfer to dashboards.
3. Dashboard Variable Control — Override on a specific dashboard. Resets on page refresh.

---

Using the CLI

The community-domo-cli handles the full 3-step flow automatically:

# Check if a variable name is available
community-domo-cli variables check-name "My Variable"

# List variables on a card
community-domo-cli variables list {cardId}

# Create a variable (handles all 3 steps internally)
community-domo-cli variables create {cardId} --body-file variable.json

# Validate a variable formula
community-domo-cli variables validate --body-file validate-payload.json

# Read full card definition (includes controls)
community-domo-cli cards definition {cardId}

Example: Create a string dropdown variable via CLI

variable.json:

{
  "name": "Region Selector",
  "type": "DROPDOWN",
  "function": {
    "name": "Region Selector",
    "dataType": "string",
    "expression": "'North'"
  },
  "description": "Select a region to filter by",
  "values": [
    {"expression": {"value": "North", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "South", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "East", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "West", "exprType": "STRING_VALUE"}}
  ]
}

community-domo-cli variables create 1810280719 --body-file variable.json --yes

The CLI automatically:

1. Checks name uniqueness
2. Creates the function template with embedded control
3. Registers the control via PUT /content/v1/variable/controls
4. Reads the card definition
5. Merges and saves the card

---

Troubleshooting

Problem	Cause	Fix
Variable not visible on card	Not referenced in any beast mode	Create a beast mode that uses the variable
Card save returns 400	Missing PUT /content/v1/variable/controls step	Must register the control before saving the card
Card save returns 400	dataSourceId in subscriptions.main	Remove it — only put dataSourceId in dataProvider
Card save returns 400	Existing controls not in full server format	Pass existing controls as-is from card def with saveOverride: true
500 Internal database error	Duplicate variable name	Check name with GET /query/v1/functions/variables/uniqueName first
Validation returns INVALID	Bad expression syntax	Check quotes for strings, function syntax for dates
Dashboard doesn't show variable control	Card-level override doesn't propagate	Set the control at dashboard level
Variable resets on dashboard refresh	Expected behavior	Dashboard controls reset to default on page load

---

Output Format

When generating commands for the user, provide:

1. What it does — one sentence explaining the variable
2. The variable definition — name, type, default, control type, options
3. Numbered commands — in execution order (all 3 steps), ready to copy/paste
4. What to do with each response — especially saving the function template ID from Step 2
5. Beast mode integration — show the formula that references the variable
6. Verify — tell them to check the card in Domo after running