app-studio-build

App Studio ビルドオーケストレーター

ネイティブカード、ヒーローメトリクス、フィルター、洗練されたレイアウトを備えた App Studio アプリを作成します。すべての操作で community-domo-cli を使用します。

詳細については、以下のスキルに委任してください：

• card-creation — カード本文のスキーマ、チャートタイプのインデックス、特定のチャート設定を上書きするための参照ファイル

---

前提条件

開始する前に、以下が必要です。

1. すべてのカードのデータセット GUID。列を確認します：

community-domo-cli --output json datasets schema $DATASET_ID > schema.json

2. ページ定義 — 名前、アイコン、各ページで使用するデータセット
3. ヒーローメトリクスの定義 — 使用する列、集計、比較期間
4. チャートの選択 — 各ページで使用する badge_* タイプ（ページごとに変えてください）

---

ステップ 1：アプリとページの作成

アプリを作成する

community-domo-cli --output json -y app-studio create \
  --body '{"title": "APP_TITLE", "description": "APP_DESCRIPTION"}' > app.json

APP_ID=$(python3 -c "import json; print(json.load(open('app.json'))['dataAppId'])")
LANDING_PAGE=$(python3 -c "import json; print(json.load(open('app.json'))['landingViewId'])")

ページを追加する

ページごとに1回呼び出します。ランディングページはすでに存在します。必要に応じて名前を変更してください。

python3 -c "
import json
app = json.load(open('app.json'))
owner_id = app['owners'][0]['id']
body = {
    'owners': [{'id': owner_id, 'type': 'USER', 'displayName': None}],
    'type': 'dataappview', 'title': 'PAGE_NAME', 'pageName': 'PAGE_NAME',
    'locked': False, 'mobileEnabled': True, 'sharedViewPage': True, 'virtualPage': False
}
json.dump(body, open('view_body.json', 'w'))
"
community-domo-cli --output json -y app-studio create-view $APP_ID \
  --body-file view_body.json > view_PAGE_NAME.json
PAGE_ID=$(python3 -c "import json; print(json.load(open('view_PAGE_NAME.json'))['view']['pageId'])")

各ページについて繰り返します。すべてのページ ID を記録してください。

---

ステップ 2：テーマとアイコン

テーマを適用する

community-domo-cli --output json app-studio get $APP_ID > app_full.json

レスポンスの theme を変更します。テーマの主な基準：

theme = app['theme']

# Zero-chrome mandatory standards
# theme keys are plural arrays — iterate, don't index directly
for comp in theme.get('components', []):
    comp['borderRadius'] = 0
    comp['borderWidth'] = 0
    comp['dropShadow'] = 'NONE'
    comp['itemBorderRadius'] = 0
    if isinstance(comp.get('padding'), dict):
        comp['padding'] = {'left': 0, 'right': 0, 'top': 0, 'bottom': 0}

for tbl in theme.get('tables', []):
    tbl['borderRadius'] = 0

for nb in theme.get('notebooks', []):
    if 'borderRadius' in nb:
        nb['borderRadius'] = 0

# isDynamic and density are set on the layout JSON in Step 6, not on the theme.

# Colors use a reference system — you cannot assign hex strings directly.
# theme['colors'] is an array of 60 color objects: {"id": "c1", "value": {"value": "#333333", "type": "RGB_HEX"}, ...}
# Color fields on components/pages hold references: {"value": "c56", "type": "COLOR_REFERENCE"}
# To change a color, look up the referenced ID and update its hex in theme['colors']:
#
#   target_id = theme['components'][0]['backgroundColor']['value']  # e.g. 'c56'
#   for color in theme['colors']:
#       if color['id'] == target_id:
#           color['value']['value'] = '#1A1A2E'
#           break
#
# Skip color changes unless you know the target color ID.

書き戻します：

community-domo-cli --output json -y app-studio update $APP_ID --body-file app_full.json

カスタムアイコンをアップロードする（任意）

community-domo-cli --output json -y files upload --file-path icon.png > icon.json
DATA_FILE_ID=$(python3 -c "import json; print(json.load(open('icon.json'))['dataFileId'])")

アプリの更新本文で、iconDataFileId と navIconDataFileId に DATA_FILE_ID を設定します。

---

ステップ 3：ヒーローメトリクス

ヒーローには badge_pop_multi_value を使用します。これは最も失敗しやすいカードタイプです。必ず以下の手順に従ってください。

必須のサブスクリプション

{
  "subscriptions": {
    "big_number": {
      "name": "big_number",
      "columns": [{"column": "METRIC_COL", "aggregation": "SUM", "alias": "METRIC_NAME", "format": {"type": "abbreviated", "format": "#A"}}],
      "filters": []
    },
    "main": {
      "name": "main",
      "columns": [
        {"column": "DATE_COL", "mapping": "ITEM"},
        {"column": "METRIC_COL", "mapping": "VALUE", "aggregation": "SUM"}
      ],
      "filters": [],
      "orderBy": [],
      "groupBy": [{"column": "DATE_COL"}],
      "fiscal": false, "projection": false, "distinct": false
    }
  }
}

必須のチャート設定

{
  "charts": {
    "main": {
      "component": "main",
      "chartType": "badge_pop_multi_value",
      "overrides": {},
      "goal": null
    }
  }
}

ヒーローに関する重要な注意点

ルール	理由
ページごとに3～4個のヒーローを単一行に配置	5個以上は不可。2行配置も不可
"format": {"type": "abbreviated", "format": "#A"} のみ	他の形式（通貨、パーセンテージ）では 400 エラーが発生します
dateGrain を含めない	サブスクリプション構造と競合します

注： dateRangeFilter と time_period サブスクリプション（期間ごとの比較）を併用すると、カード作成エンドポイントで HTTP 400 が発生します。解決されるまで、両方とも省略してください。 ヒーローは YoY 差分のない単一値の KPI メトリクスとして表示されます。

ヒーローメトリクスごとにカードを1つ作成します：

community-domo-cli --output json -y cards create \
  --body-file hero_metric.json --page-id $PAGE_ID > hero_card.json

---

ステップ 4：ネイティブチャート

各ページにメインのビジュアライゼーション（全幅）と詳細カードを2～6枚配置します。ページごとにチャートタイプを変えてください。すべてのページで同じタイプを使用しないでください。

チャート選択の方針

データパターン	推奨タイプ
時系列の傾向	badge_two_trendline、badge_vert_area_overlay、badge_curvedline
カテゴリーの比較	badge_vert_bar、badge_horiz_bar、badge_vert_stackedbar
全体に対する構成比	badge_donut、badge_vert_100pct、badge_treemap
ランキング	badge_horiz_bar、badge_funnel、badge_bump
相関／散布図	badge_xybubble、badge_xy_line
表形式の詳細	badge_flex_table、badge_basic_table
複合グラフ（棒＋折れ線）	badge_line_bar、badge_symbol_bar

各カードを作成する

1. card-creation スキルの「Section 2: Body Schema」に従ってカード本文を作成します。このファイルと同じスキルディレクトリにあります。
2. 「Section 5」のチャートタイプのインデックスから chartType を選びます。
3. card-creation/references/（このファイルと同じスキルディレクトリ内）から該当する参照ファイルを読みます。主な参照ファイル：bar.md、line.md、pie.md、period-over-period.md、selector.md、table.md。
4. CLI で作成します：

community-domo-cli --output json -y cards create \
  --body-file chart_card.json --page-id $PAGE_ID > chart_response.json

メインのビジュアライゼーション：レイアウトで幅を60に設定します。詳細カード：幅を20または30に設定します（1行あたり2～3枚）。

---

ステップ 5：フィルターカード

ページ単位のフィルタリングを行うセレクターです。ほとんどのフィルターでは badge_dropdown_selector を使用します。

フィルターカード本文

{
  "definition": {
    "subscriptions": {
      "big_number": {
        "name": "big_number",
        "columns": [{"column": "FILTER_COL", "aggregation": "COUNT"}],
        "filters": []
      },
      "main": {
        "name": "main",
        "columns": [{"column": "FILTER_COL", "mapping": "ITEM"}],
        "filters": [],
        "groupBy": [{"column": "FILTER_COL"}],
        "orderBy": [], "fiscal": false, "projection": false, "distinct": false
      }
    },
    "formulas": {"dsUpdated": [], "dsDeleted": [], "card": []},
    "annotations": {"new": [], "modified": [], "deleted": []},
    "conditionalFormats": {"card": [], "datasource": []},
    "controls": [],
    "segments": {"active": [], "create": [], "update": [], "delete": []},
    "charts": {
      "main": {"component": "main", "chartType": "badge_dropdown_selector", "overrides": {}, "goal": null}
    },
    "dynamicTitle": {"text": [{"text": "FILTER_COL", "type": "TEXT"}]},
    "dynamicDescription": {"text": [{"text": "", "type": "TEXT"}], "displayOnCardDetails": true},
    "chartVersion": "12", "inputTable": false, "noDateRange": false,
    "title": "FILTER_COL", "description": ""
  },
  "dataProvider": {"dataSourceId": "DATASET_UUID"},
  "variables": true, "columns": false
}

重要： セレクターの big_number.columns を空にしてはいけません。フィルター列に COUNT を使用してください。列が空だと HTTP 400 が発生します。

最初のページに作成し、他のページと共有します：

# Create on first page
community-domo-cli --output json -y cards create \
  --body-file filter.json --page-id $FIRST_PAGE > filter_resp.json
FILTER_ID=$(python3 -c "import json; print(json.load(open('filter_resp.json'))['id'])")

# Add to other pages (goes to appendix — layout-set moves it to canvas)
community-domo-cli -y pages add-card $OTHER_PAGE $FILTER_ID

---

ステップ 6：レイアウトの組み立て

以下の表からレイアウトを選びます（デフォルトは Hero Grid です）。グリッド座標、card_positions、special_entries の詳細については、対応する レイアウト参照ファイルを読みます。

レイアウト一覧

レイアウト	ファイル	動的	スロット	最適な用途
デフォルト：ヒーローグリッド	layouts/layout-default-hero-grid.md	False	フィルター＋ヒーロー＋主要ビジュアライゼーション＋詳細行	KPI メトリクスを含む標準的なダッシュボード
A：右サイドバー	layouts/layout-a-right-sidebar.md	True	左側は広く、右側は狭い。ページ区切り付きの3セクション	マスター／詳細、解説パネル
B：対称グリッド	layouts/layout-b-symmetric-grid.md	False	全幅→半幅→3分割→6分割→全幅、区切り線	データ密度の高い比較ダッシュボード
C：左カラムの特徴表示	layouts/layout-c-left-column-feature.md	True	左側に狭いスタック、右側に広い領域、下部は2パネル	特徴的なビジュアライゼーションを備えたKPIサイドバー
D：フルキャンバス	layouts/layout-d-full-canvas.md	True	端から端まで広がる単一スロット	埋め込みアプリ、マップ、または全画面表示のビジュアライゼーション
E：左側のフィルター＋フォーム	layouts/layout-e-left-filter-form.md	False	左側にフィルター、右側に広い領域、スペーサー、フォーム＋カード、下部は全幅	データ入力／インタラクティブフォーム

構築前にレイアウトのリファレンスファイルを読んでください。 layout-builder.py または以下のインラインスクリプトに貼り付ける正確な card_positions、 special_entries、is_dynamic の値が記載されています。

重要： cards create --page-id はカードをレイアウトの content 配列に付録エントリとして自動的に追加します。 すべてのカードを作成した後に必ず layout-get を実行して、content 配列に値を設定してください。以下の Python ビルダーは既存のエントリを変更するもので、新しいエントリは作成しません。 カード作成前に layout-get を実行すると、配置するものがない空の content 配列になります。

community-domo-cli --output json app-studio layout-get $APP_ID $PAGE_ID > layout.json

デフォルトの y バンドグリッドパターン（ヒーローグリッド）

バンド	y	高さ	コンテンツ
バナー	0	14	ページバナー画像（pro-code）または HEADER
フィルター	14	6	横並びのフィルターカード
ヒーロー	20	14	1行に3～4個のヒーローメトリクス
セクションヘッダー	34	4	HEADER テキスト
主要ビジュアライゼーション	38	30	全幅チャート（幅60）
セクションヘッダー	68	4	HEADER テキスト
詳細カード	72	30	1行に2～3枚のカード（幅20または30）

コンテンツエントリの種類

種類	必須フィールド
CARD	contentKey、type: "CARD"、cardId、x、y、width、height、style: null、hideTitle: true/false、hideSummary: true、virtual: false、virtualAppendix: false
HEADER	contentKey、type: "HEADER"、text、x、y、width、height、virtual: false、virtualAppendix: false
PAGE_BREAK	contentKey、type: "PAGE_BREAK"、x、y、width、height: 0 — 視覚的なページ境界
SEPARATOR	contentKey、type: "SEPARATOR"、x、y、width、height — 水平線
SPACER	contentKey、type: "SPACER"、x、y、width、height — 空白領域
FORM	contentKey、type: "FORM"、x、y、width、height — 埋め込みフォーム領域

カードレイアウトのコンテンツエントリ

{
  "contentKey": 100,
  "type": "CARD",
  "cardId": CARD_ID_INT,
  "x": 0, "y": 38, "width": 60, "height": 30,
  "style": null,
  "hideTitle": false,
  "hideSummary": true,
  "hideBorder": false,
  "hideMargins": false,
  "fitToFrame": false,
  "virtual": false,
  "virtualAppendix": false,
  "children": null
}

ヒーローカードのエントリ — 追加フラグ：

{
  "hideTitle": true, "hideSummary": true,
  "hideBorder": true, "hideMargins": true, "fitToFrame": true,
  "style": null, "height": 14
}

フィルターカードのエントリ — 低プロファイル：

{
  "hideTitle": true, "hideSummary": true,
  "hideBorder": true, "hideMargins": true, "fitToFrame": true,
  "style": null, "height": 6
}

レイアウトの構築と適用

ショートカット： このファイルと同じスキルディレクトリにある layout-builder.py を作業 ディレクトリにコピーし、先頭の card_positions、header_positions、special_entries、is_dynamic に値を入力して（レイアウトのリファレンスファイルから値をコピー）、次を実行します： python3 layout-builder.py --layout layout_PAGE.json --out layout_PAGE_updated.json 以下のインラインスクリプト全体も同じ処理です。位置以外のカスタマイズが必要な場合は、こちらを使用してください。

import json, copy

layout = json.load(open('layout.json'))

# cards create --page-id puts every card in the appendix as a content entry.
# Build a cardId → contentKey lookup so positions can be keyed by cardId.
card_to_key = {}
for c in layout['content']:
    if c['type'] == 'CARD' and 'cardId' in c:
        card_to_key[c['cardId']] = c['contentKey']

# ── Define positions keyed by CARD ID (not contentKey) ──────────────────────
# Standard grid: total width = 60. Compact grid: total width = 12.
# hero=True  → hideTitle/hideSummary/hideBorder/hideMargins/fitToFrame all True, h=14
# filt=True  → same flags True, h=6
card_positions = {
    # CARD_ID: {'x': X, 'y': Y, 'w': W, 'h': H, 'cx': CX, 'cy': CY, 'cw': CW, 'ch': CH}
    # Hero example:   {'x':  0, 'y': 20, 'w': 15, 'h': 14, 'cx': 0, 'cy': 7,  'cw': 6,  'ch': 6,  'hero': True}
    # Filter example: {'x':  0, 'y': 14, 'w': 20, 'h':  6, 'cx': 0, 'cy': 0,  'cw': 12, 'ch': 4,  'filt': True}
    # Chart example:  {'x':  0, 'y': 38, 'w': 60, 'h': 30, 'cx': 0, 'cy': 19, 'cw': 12, 'ch': 20}
}

# Headers have no cardId — find their contentKey from the existing content array.
# layout['content'] will have one HEADER entry auto-created (text="Appendix").
# Add more by inspecting contentKeys after layout-get.
header_positions = {
    # CONTENT_KEY: {'text': 'Section Title', 'x': 0, 'y': 34, 'w': 60, 'h': 4, 'cx': 0, 'cy': 15, 'cw': 12, 'ch': 3}
}

# ── Build new arrays ─────────────────────────────────────────────────────────
new_content = []
std_template = []
cmp_template = []

# Preserve SEPARATOR (contentKey=0, template-only system entry — no matching content entry).
for entry in layout['standard']['template']:
    if entry.get('contentKey', -1) == 0:
        std_template.append({**entry, 'virtual': True, 'virtualAppendix': True})
for entry in layout['compact']['template']:
    if entry.get('contentKey', -1) == 0:
        cmp_template.append({**entry, 'virtual': True, 'virtualAppendix': True})

for c in layout['content']:
    key = c['contentKey']
    entry = copy.deepcopy(c)

    if c['type'] == 'HEADER' and key in header_positions:
        pos = header_positions[key]
        entry.update({'text': pos['text'], 'x': pos['x'], 'y': pos['y'],
                      'width': pos['w'], 'height': pos['h'],
                      'virtual': False, 'virtualAppendix': False})
        new_content.append(entry)
        std_template.append({'contentKey': key, 'type': 'HEADER',
                              'x': pos['x'], 'y': pos['y'], 'width': pos['w'], 'height': pos['h'],
                              'virtual': False, 'virtualAppendix': False, 'children': None})
        cmp_template.append({'contentKey': key, 'type': 'HEADER',
                              'x': pos['cx'], 'y': pos['cy'], 'width': pos['cw'], 'height': pos['ch'],
                              'virtual': False, 'virtualAppendix': False, 'children': None})

    elif c['type'] == 'CARD' and c.get('cardId') in card_positions:
        pos = card_positions[c['cardId']]
        hero = pos.get('hero', False)
        filt = pos.get('filt', False)
        flags = {'hideTitle': hero or filt, 'hideSummary': True,
                 'hideBorder': hero or filt, 'hideMargins': hero or filt,
                 'fitToFrame': hero or filt}
        entry.update({**flags, 'x': pos['x'], 'y': pos['y'],
                      'width': pos['w'], 'height': pos['h'],
                      'virtual': False, 'virtualAppendix': False})
        new_content.append(entry)
        std_template.append({**flags, 'contentKey': key, 'type': 'CARD',
                              'x': pos['x'], 'y': pos['y'], 'width': pos['w'], 'height': pos['h'],
                              'virtual': False, 'virtualAppendix': False, 'style': None, 'children': None})
        cmp_template.append({**flags, 'contentKey': key, 'type': 'CARD',
                              'x': pos['cx'], 'y': pos['cy'], 'width': pos['cw'], 'height': pos['ch'],
                              'virtual': False, 'virtualAppendix': False, 'style': None, 'children': None})

    else:
        # Leave in appendix (test cards, cards not yet positioned, etc.)
        entry.update({'virtual': True, 'virtualAppendix': True})
        new_content.append(entry)
        std_template.append({'contentKey': key, 'type': c['type'],
                              'x': 0, 'y': 0, 'width': 15, 'height': 14,
                              'virtual': True, 'virtualAppendix': True, 'style': None, 'children': None})
        cmp_template.append({'contentKey': key, 'type': c['type'],
                              'x': 0, 'y': 0, 'width': 6, 'height': 14,
                              'virtual': True, 'virtualAppendix': True, 'style': None, 'children': None})

# ── Special entries (PAGE_BREAK, SEPARATOR, SPACER, FORM) ────────────────────
# Copy these from the layout reference file. Empty list for default hero grid.
special_entries = [
    # {'type': 'PAGE_BREAK', 'x': 0, 'y': 51, 'w': 60, 'h': 0, 'cx': 0, 'cy': 51, 'cw': 12, 'ch': 0},
]

# Set from layout reference file. Default hero grid uses False.
is_dynamic = False

if special_entries:
    all_keys = [c.get('contentKey', 0) for c in new_content]
    all_keys += [e.get('contentKey', 0) for e in std_template]
    next_key = max(all_keys) + 100 if all_keys else 900
    for se in special_entries:
        ck = next_key
        next_key += 1
        base = {'contentKey': ck, 'type': se['type'],
                'virtual': False, 'virtualAppendix': False, 'children': None}
        new_content.append({**base, 'x': se['x'], 'y': se['y'],
                            'width': se['w'], 'height': se['h']})
        std_template.append({**base, 'x': se['x'], 'y': se['y'],
                              'width': se['w'], 'height': se['h']})
        cmp_template.append({**base, 'x': se['cx'], 'y': se['cy'],
                              'width': se['cw'], 'height': se['ch']})

layout['content'] = new_content
layout['standard']['template'] = std_template
layout['compact']['template'] = cmp_template
layout['isDynamic'] = is_dynamic
json.dump(layout, open('layout_updated.json', 'w'))

canvas = sum(1 for c in new_content if not c.get('virtualAppendix'))
appx   = sum(1 for c in new_content if c.get('virtualAppendix'))
print(f'Layout written: {canvas} canvas, {appx} appendix, isDynamic={is_dynamic}')

適用：

community-domo-cli --output json -y app-studio layout-set $APP_ID $PAGE_ID \
  --body-file layout_updated.json

ページごとに繰り返します。

---

ステップ 7：ナビゲーション

すべてのページで、カスタムアイコンを使用して向きを LEFT に設定します。

community-domo-cli --output json app-studio get $APP_ID > app_nav.json

import json
app = json.load(open('app_nav.json'))

app['navOrientation'] = 'LEFT'
app['showDomoNavigation'] = False
app['showTitle'] = False
app['showLogo'] = False

# nav['icon'] and nav['title'] are always silently ignored by the API — do not set them.
# Page titles in the nav come from the pageName set at create-view time, not from this update.
# To control a page's nav label, set 'pageName' and 'title' in the create-view body.

# Preserve system items (SEARCH, FAVORITES, etc.)
# They appear in navigations[] with type != 'VIEW' — don't remove them

json.dump(app, open('app_nav_updated.json', 'w'))

community-domo-cli --output json -y app-studio update $APP_ID --body-file app_nav_updated.json

注： navOrientation、showDomoNavigation、showTitle、showLogo は app-studio update で正しく更新されます。ナビゲーション項目の title と icon フィールドは、この API では常に無視されます。設定しないでください。ページのナビゲーションラベルには、create-view の実行時に設定した pageName が使用されます。

確認済みの Domo ネイティブアイコン名

Google Material アイコン名は機能しません。以下のみを使用してください。

カテゴリ	アイコン
ホーム	home
ダッシュボード	analytics、pop-chart、chart-bar-vertical、select-chart、badge-layout-8
オペレーション	gauge、dataflow、cube-filled、completed-submissions
品質	certified、checkbox-marked-outline、check-in-icon、approval-center
ロジスティクス	globe、data-app、local_shipping、warehouse、shopping_cart
小売	store、cube-filled、numbers、toolbox
財務	money-universal、money、benchmark、books、calculator
人員	people、person、person-card、person-plus
時間	clock、calendar-simple、calendar-time、alarm
AI	ai-chat、magic、wand、lightbulb、lightning-bolt
設定	controls、pages-gear、code-tags、pencil-box

---

ステップ 8：確認

すべてのページが完成したら：

1. カード数を確認します：

for PAGE in $LANDING_PAGE $PAGE2 $PAGE3 $PAGE4; do
  echo "Page $PAGE:"
  community-domo-cli --output json pages list-cards $PAGE | python3 -c "
import json,sys
data=json.load(sys.stdin)
cards=data.get('cards', [])
print(f'  {len(cards)} cards')
for c in cards: print(f'  - {c[\"id\"]}: {c.get(\"title\",\"untitled\")}')
"
done

2. ユーザーに報告します：
   • アプリ URL：https://INSTANCE.domo.com/app-studio/APP_ID
   • アプリ ID とすべてのページ ID
   • ページごとのカード数
   • 作成に失敗したカード（エラーの詳細を含む）

---

グローバル UI/UX 基準（必須）

これらは、このスキルで構築するすべての App Studio アプリに適用されます。

基準	値
borderRadius	カード、テーブル、ノートブック、コンポーネント、ボタン、タブのすべてで 0
borderWidth	すべてのカードで 0
dropShadow	すべてのカードで NONE
padding	すべてのカードで 0
isDynamic	false — 固定幅レイアウト
density	{compact: 8, standard: 8}
コントロールのカラー c8	#2563BE
ヒーロー	単一行、高さ 14、最大 4、hideTitle／hideSummary／hideBorder／hideMargins／fitToFrame はすべて true
フィルター	高さ 6、style: null、非表示フラグはすべて true
アプリを重複作成しない	再試行時は既存の appId を再利用
navOrientation	LEFT
showDomoNavigation	ナビゲーションが LEFT の場合は false