Back to Details

cap-apps-code-engine

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rule: Domo App Platform Code Engine (Toolkit-First)

规则：Domo应用平台Code Engine（工具优先）

Use a contract-first pattern for Code Engine calls. In practice, prefer direct 
domo.post('/domo/codeengine/v2/packages/{alias}', params)
when wiring app calls.
Legacy endpoint-first guidance has been archived to 
archive/legacy-rules/domo-code-engine.md
.
对Code Engine调用采用契约优先模式。 实际操作中，在连接应用调用时，优先使用直接的
domo.post('/domo/codeengine/v2/packages/{alias}', params)
方式。
旧版的端点优先指南已归档至
archive/legacy-rules/domo-code-engine.md
。

Working call pattern (
domo.post
)

可行的调用模式（
domo.post
）

bash
npm install ryuu.js
typescript
import domo from 'ryuu.js';

const response = await domo.post('/domo/codeengine/v2/packages/calculateTax', {
  amount: 1000,
  state: 'CA'
});
bash
npm install ryuu.js
typescript
import domo from 'ryuu.js';

const response = await domo.post('/domo/codeengine/v2/packages/calculateTax', {
  amount: 1000,
  state: 'CA'
});

Response parsing requirement

响应解析要求

typescript
// First integration pass: inspect exact response shape for this function
console.log('Code Engine response:', response);

const body = response?.body ?? response?.data ?? response;

// Handle common output shapes
const output =
  body?.output ??
  body?.result ??
  body?.value ??
  body;

if (typeof output === 'number') {
  // numeric output
} else if (typeof output === 'string') {
  // string output
} else if (output && typeof output === 'object') {
  // structured object output
} else {
  throw new Error('Code Engine returned no usable output');
}
typescript
// First integration pass: inspect exact response shape for this function
console.log('Code Engine response:', response);

const body = response?.body ?? response?.data ?? response;

// Handle common output shapes
const output =
  body?.output ??
  body?.result ??
  body?.value ??
  body;

if (typeof output === 'number') {
  // numeric output
} else if (typeof output === 'string') {
  // string output
} else if (output && typeof output === 'object') {
  // structured object output
} else {
  throw new Error('Code Engine returned no usable output');
}

Manifest requirement: 
packagesMapping
(with 
s
)

清单要求：
packagesMapping
（带
s
）

Use 
packagesMapping
and define full parameter/output contracts.
json
{
  "packagesMapping": [
    {
      "name": "myPackage",
      "alias": "myFunction",
      "packageId": "00000000-0000-0000-0000-000000000000",
      "version": "1.0.0",
      "functionName": "myFunction",
      "parameters": [
        {
          "name": "param1",
          "displayName": "param1",
          "type": "decimal",
          "value": null,
          "nullable": false,
          "isList": false,
          "children": [],
          "entitySubType": null,
          "alias": "param1"
        }
      ],
      "output": {
        "name": "result",
        "displayName": "result",
        "type": "number",
        "value": null,
        "nullable": false,
        "isList": false,
        "children": [],
        "entitySubType": null,
        "alias": "result"
      }
    }
  ]
}
使用
packagesMapping
并定义完整的参数/输出契约。
json
{
  "packagesMapping": [
    {
      "name": "myPackage",
      "alias": "myFunction",
      "packageId": "00000000-0000-0000-0000-000000000000",
      "version": "1.0.0",
      "functionName": "myFunction",
      "parameters": [
        {
          "name": "param1",
          "displayName": "param1",
          "type": "decimal",
          "value": null,
          "nullable": false,
          "isList": false,
          "children": [],
          "entitySubType": null,
          "alias": "param1"
        }
      ],
      "output": {
        "name": "result",
        "displayName": "result",
        "type": "number",
        "value": null,
        "nullable": false,
        "isList": false,
        "children": [],
        "entitySubType": null,
        "alias": "result"
      }
    }
  ]
}

Required contract disclosure to user

必须向用户披露的契约信息

When recommending or generating Code Engine calls, the agent must explicitly tell the user:
  • exact input parameter names, types, and 
    nullable
    expectations
  • expected output name, type, and shape (number/string/object)
This is required so the user can build a matching Code Engine function and manifest contract.
在推荐或生成Code Engine调用时，代理必须明确告知用户：
  • 确切的输入参数名称、类型和
    nullable
    要求
  • 预期的输出名称、类型和结构（数字/字符串/对象）
这是必要的，以便用户可以构建匹配的Code Engine函数和清单契约。

Error Handling Pattern

错误处理模式

typescript
async function executeFunction(alias: string, payload: Record<string, unknown>) {
  try {
    const response = await domo.post(`/domo/codeengine/v2/packages/${alias}`, payload);
    console.log('Code Engine response:', response);
    return response?.body ?? response?.data ?? response;
  } catch (error) {
    console.error(`Code Engine call failed for alias ${alias}`, error);
    throw error;
  }
}
typescript
async function executeFunction(alias: string, payload: Record<string, unknown>) {
  try {
    const response = await domo.post(`/domo/codeengine/v2/packages/${alias}`, payload);
    console.log('Code Engine response:', response);
    return response?.body ?? response?.data ?? response;
  } catch (error) {
    console.error(`Code Engine call failed for alias ${alias}`, error);
    throw error;
  }
}

Canonical Rules References

标准规则参考

  • Toolkit patterns: 
    .cursor/rules/04-toolkit.mdc
  • Manifest mapping details: 
    .cursor/rules/06-manifest.mdc
  • Operational gotchas: 
    .cursor/rules/09-gotchas.mdc
  • 工具包模式：
    .cursor/rules/04-toolkit.mdc
  • 清单映射细节：
    .cursor/rules/06-manifest.mdc
  • 操作注意事项：
    .cursor/rules/09-gotchas.mdc

Checklist

检查清单

  • Calls use 
    domo.post('/domo/codeengine/v2/packages/{alias}', params)
    pattern
  • Manifest uses 
    packagesMapping
    (not 
    packageMapping
    )
  • packagesMapping.parameters
    and 
    output
    include full contract fields (
    name
    , 
    displayName
    , 
    type
    , 
    value
    , 
    nullable
    , 
    isList
    , 
    children
    , 
    entitySubType
    , 
    alias
    )
  • Agent states input parameter names, types, and nullable status to user
  • Agent states expected output name/type/shape to user
  • First implementation logs response and validates real response shape
  • Output parsing handles 
    body
    /
    data
    /raw response shape
  • Errors handled and surfaced to UI or logs
  • 调用使用
    domo.post('/domo/codeengine/v2/packages/{alias}', params)
    模式
  • 清单使用
    packagesMapping
    （而非
    packageMapping
    ）
  • packagesMapping.parameters
    和
    output
    包含完整的契约字段（
    name
    、
    displayName
    、
    type
    、
    value
    、
    nullable
    、
    isList
    、
    children
    、
    entitySubType
    、
    alias
    ）
  • 代理向用户说明输入参数的名称、类型和可空状态
  • 代理向用户说明预期的输出名称/类型/结构
  • 首次实现时记录响应并验证实际响应结构
  • 输出解析处理
    body
    /
    data
    /原始响应结构
  • 错误已处理并显示在UI或日志中