beast-mode-creation

Beast Mode Generator

Create Domo beast modes (calculated fields) and output curl commands to execute them.

Beast modes are virtual columns computed from existing dataset columns using MySQL-style formulas. They can be scoped to a single card or shared across all cards on a dataset.

When to Use This Skill

• User asks for a field that doesn't exist in the schema
• A visualization needs a derived metric (percentages, concatenations, conditionals)
• User mentions "beast mode", "calculated field", "formula", or describes a computation
• You're building a card and realize the needed column must be computed

Core Workflow

1. Identify what to compute and from which columns
2. Build the formula (MySQL syntax, backticks around column names)
3. Fetch the column schema (if not already available)
4. Validate the formula via the Domo API
5. Choose scope: dataset-level (default) or card-level
6. Generate curl command(s)

---

Prerequisites

These values are typically available from the CLI tool context:

Parameter	Source	Required
instanceUrl	Domo instance (e.g., domo-gordon-pont.domo.com)	Always
devToken	CLI auth / developer token	Always
dataSourceId	Dataset UUID	Always
cardId	Card ID	For attaching to a card
userId	Current user's Domo ID	For dataset-level (owner field)

If any are missing, ask the user before generating commands.

---

Step 1: Build the Formula

Write formulas using MySQL syntax. Always wrap column names in backticks.

SUM(`hourly_cost_rate`)                              -- aggregate
CONCAT(`first_name`, ' ', `last_name`)               -- string
(`revenue` - `cost`) / `revenue` * 100               -- ratio
CASE WHEN `status` = 'active' THEN 1 ELSE 0 END      -- conditional

For a comprehensive list of supported functions and formula patterns, read references/formula-examples.md.

Quick syntax rules:

• Column names must be in backticks: column_name
• String literals use single quotes: 'active'
• CASE requires WHEN and END: CASE WHEN ... THEN ... ELSE ... END
• Domo follows older MySQL syntax — most standard MySQL functions work

Before writing the formula, check that every column you reference actually exists in the dataset schema. If you already have the schema (from context or a prior fetch), compare the user's requested columns against it. If a column doesn't exist, stop and tell the user — don't generate a formula with columns that aren't in the data. This catches errors early, before you even reach the validation step.

---

Step 2: Fetch the Column Schema

If you don't already have the dataset's columns, fetch them first. The schema is needed for formula validation and to confirm column names are correct.

curl -X GET "https://{instanceUrl}/api/query/v1/datasources/{dataSourceId}/schema/indexed?includeHidden=true" \
  -H "X-DOMO-Developer-Token: {devToken}"

The response returns an array of column objects. Each has name, type, and other metadata. Save this — you'll need it for validation.

---

Step 3: Validate the Formula

Always validate before generating the creation curl. This catches typos, missing columns, and syntax errors before they hit the API.

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

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": [
      {
        "id": "first_name",
        "name": "first_name",
        "label": "first_name",
        "type": "string",
        "isCalculation": false,
        "isVariable": false,
        "isAggregatable": true,
        "columnName": "first_name"
      }
    ],
    "formulas": {
      "{formulaId}": {
        "id": "{formulaId}",
        "name": "{fieldName}",
        "formula": "{formula}",
        "status": "valid",
        "dataType": "{dataType}"
      }
    }
  }'

The columns array must include every column in the dataset (use the schema response from Step 2). The formulas object is keyed by a unique ID you generate (e.g., calculation_abc123).

Success response:

{
  "allValid": true,
  "results": {
    "{formulaId}": {
      "status": "VALID",
      "dataType": "LONG",
      "containsAggregation": true,
      "columnPositions": [{"columnName": "`hourly_cost_rate`", "columnPosition": 4}]
    }
  }
}

If validation fails, check:

• invalidColumns — column name doesn't exist (typo? check schema)
• status: "INVALID" — formula syntax error
• Show the user the error and ask them to clarify before proceeding

Use the validation response to populate fields in the creation payload:

• dataType from the result (the API infers the correct return type)
• containsAggregation → maps to aggregated in the creation payload
• columnPositions → include in the creation payload

---

Step 4: Choose Scope

Default to dataset-level — it's reusable across all cards on the dataset and is the more common need.

Use card-level only when the user explicitly says it's single-use, or the formula is specific to one visualization's configuration.

Don't ask unless you genuinely can't tell. If the formula represents a business metric (revenue, margin, count, status flag), it almost certainly belongs on the dataset.

---

Step 5: Generate Curl Commands

Dataset-Level (Default) — Two Steps

Step 5a: Create the beast mode on the dataset

curl -X POST "https://{instanceUrl}/api/query/v1/functions/template?strict=false" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{fieldName}",
    "owner": {userId},
    "locked": false,
    "global": false,
    "expression": "{formula}",
    "links": [
      {
        "resource": {"type": "DATA_SOURCE", "id": "{dataSourceId}"},
        "visible": true,
        "active": false,
        "valid": "VALID"
      }
    ],
    "aggregated": {true|false},
    "analytic": false,
    "nonAggregatedColumns": [],
    "dataType": "{dataType}",
    "status": "VALID",
    "cacheWindow": "non_dynamic",
    "columnPositions": [{from validation response}],
    "functions": [],
    "functionTemplateDependencies": [],
    "archived": false,
    "hidden": false,
    "variable": false
  }'

Response — save the id and legacyId:

{
  "id": "calculation_549b9c1f-71cc-4227-bb9c-3ae5064be416",
  "legacyId": "calculation_549b9c1f-71cc-4227-bb9c-3ae5064be416",
  "templateId": 1161,
  ...
}

Step 5b: Read the existing card, merge, and update

The card update endpoint (PUT /content/v3/cards/kpi/{cardId}) replaces the full definition. You must read the card first, add the beast mode to formulas.dsUpdated, and PUT the whole thing back.

Read the card:

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}"
  }'

Merge the beast mode into the response by adding to definition.formulas.dsUpdated:

{
  "name": "{fieldName}",
  "id": "{legacyId from Step 5a response}",
  "persistedOnDataSource": true,
  "initialPersistedOnDataSource": false,
  "label": "{fieldName}",
  "type": "{dataType}",
  "formula": "{formula}",
  "value": "{formula}",
  "isVariable": false,
  "isCalculation": true,
  "isAggregatable": false,
  "status": "VALID",
  "dataType": "{dataType}",
  "templateId": {templateId from Step 5a response},
  "owner": {userId},
  "locked": false,
  "saved": false,
  "query": "{formula}",
  "containsAggregation": {true|false},
  "containsAnalytic": false,
  "cacheWindow": "non_dynamic",
  "columnPositions": [{from validation response}],
  "formulaId": "{id from Step 5a response}",
  "formulaDependencies": [],
  "legacyId": "{legacyId from Step 5a response}",
  "isControlled": false
}

PUT the merged card back:

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/{cardId}" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{merged card body}'

---

Card-Level — Single Step

Read the existing card first (same as above), then add to definition.formulas.card[] instead:

{
  "id": "{generate a UUID like calculation_<uuid>}",
  "name": "{fieldName}",
  "formula": "{formula}",
  "status": "VALID",
  "dataType": "{dataType}",
  "persistedOnDataSource": false,
  "isAggregatable": false,
  "bignumber": false,
  "nonAggregatedColumns": [],
  "templateId": -1,
  "legacyId": "{same as id}",
  "variable": false,
  "isCalculation": true,
  "initialPersistedOnDataSource": false,
  "saved": false,
  "query": "{formula}",
  "cacheWindow": "non_dynamic",
  "containsAggregation": {true|false},
  "containsAnalytic": false,
  "invalidColumns": [],
  "nonAggregatedExpressions": [],
  "formulaTemplateDependencies": [],
  "columnPositions": [{from validation response}],
  "formulaId": "{generate another UUID}",
  "formulaDependencies": [],
  "isControlled": false
}

Then PUT the full merged card body.

---

Key Differences: Card-Level vs Dataset-Level

Aspect	Card-Level	Dataset-Level
Where in payload	formulas.card[]	formulas.dsUpdated[]
persistedOnDataSource	false	true
templateId	-1	Server-assigned integer
owner	Not included	Required (user ID)
Visibility	This card only	All cards on this dataset
API calls	1 (read + merge + PUT)	2 (POST to create, then read + merge + PUT)
Reusable	No	Yes

---

Data Types

Use the type returned by the validation endpoint when possible. Common values:

Type	Use For
LONG	Integers, counts, boolean flags (0/1)
DECIMAL	Currency, percentages, ratios
DOUBLE	High-precision decimals
STRING	Text results (CONCAT, CASE returning strings)
DATE	Date calculations

---

Troubleshooting

Problem	Cause	Fix
Validation returns invalidColumns	Column name typo or missing backticks	Check schema, wrap in backticks
Validation returns INVALID status	Formula syntax error	Check parentheses, CASE/WHEN/END
PUT card returns 400	Incomplete card body	Make sure you read the card first and PUT the full merged body
Beast mode not visible in UI	Wrong persistedOnDataSource value	false = card-level, true = dataset-level
Card loses its chart/columns after PUT	PUT only included formulas, not full body	Always read the card definition first, merge, then PUT

---

Output Format

When generating curl commands for the user, provide:

1. What it does — one sentence explaining the beast mode
2. The formula — so they can verify the logic
3. Numbered curl commands — in execution order, ready to copy/paste
4. What to do with each response — especially saving legacyId from Step 5a
5. Verify — tell them to check the card in Domo after running