Rule: Domo App Platform Workflows (Toolkit-First)

WorkflowClient

Legacy endpoint-first guidance has been archived to

archive/legacy-rules/domo-workflow.md

.

Canonical Client

yarn add @domoinc/toolkit

import { WorkflowClient } from '@domoinc/toolkit';

const startResponse = await WorkflowClient.startModel('myWorkflow', {
  inputVar: 'value',
  anotherVar: 123
});
const instance = startResponse.body;

const statusResponse = await WorkflowClient.getInstance('myWorkflow', instance.id);
const status = statusResponse.body.status;

Correct method usage (aliases, not UUIDs)

WorkflowClient

manifest.json

workflowMapping

await WorkflowClient.startModel('myWorkflow', { inputVar: 'value' });
await WorkflowClient.getAllModels();          // or getAllModels(true)
await WorkflowClient.getModelDetails('myWorkflow');
await WorkflowClient.getInstance('myWorkflow', 'instance-id');

Manifest Requirements

workflowMapping

manifest.json

{
  "workflowMapping": [
    {
      "alias": "sendReport",
      "modelId": "d1373fa7-9df8-45d3-80ba-f931dda169b4",
      "parameters": [
        { "aliasedName": "reportType", "type": "string", "list": false, "children": null },
        { "aliasedName": "recipients", "type": "string", "list": true, "children": null }
      ]
    }
  ]
}

Card mapping and input contract reminder

• In Domo, map the app card to the intended workflow model in the card/app configuration UI (not just in source files).
• Confirm the workflow start-node input parameters are configured in the workflow and match the payload keys your app sends in

  WorkflowClient.startModel(workflowAlias, variables)

  .
• If parameter names/types/list settings do not match, workflow starts may fail or silently mis-handle inputs.
• When recommending or generating

  WorkflowClient.startModel(...)

  calls, the agent must explicitly tell the user the exact input variable names and types being passed.

Error Handling Pattern

async function runWorkflow(workflowAlias: string, payload: Record<string, unknown>) {
  try {
    const response = await WorkflowClient.startModel(workflowAlias, payload);
    return response.body;
  } catch (error) {
    console.error(`WorkflowClient.startModel failed for ${workflowAlias}`, error);
    throw error;
  }
}

Canonical Rules References

• Toolkit workflow methods:

  .cursor/rules/04-toolkit.mdc

• Workflow mapping requirements:

  .cursor/rules/06-manifest.mdc

• Runtime caveats:

  .cursor/rules/09-gotchas.mdc

Checklist

• workflowMapping

  is configured
• App card is mapped to the correct workflow in Domo UI
• Workflow start-node input parameters match app payload keys/types
• Calls use

  WorkflowClient

  alias-based methods (

  startModel

  ,

  getModelDetails

  ,

  getInstance

  )
• Agent states exact

  startModel

  input variable names/types in guidance
• Code passes workflow aliases (from

  workflowMapping.alias

  ) rather than workflow UUIDs
• Response parsing uses

  response.body

• Long-running workflow UX includes status checks or async user feedback