dashboards

ダッシュボード

ダッシュボードは組織全体で共有されます。プライベートなものはないため、追加や変更を行うと全員に表示されます。各ダッシュボードには、順序付きのカードが含まれます。

フィールド	内容
measure	完全修飾された、数値の指標を1つ指定します：crm_deals.amount。
segmentId	カードが行を集計するセグメント、または —
filter	カード独自の条件（セグメントのフィルター構文）を指定します。両方は指定できません。
joinPaths	条件または内訳が参照する他の各キューブへの経路です：{ "crm_companies": "crm_deals.crm_companies" }。
breakdown	任意のディメンションです。指定すると、カードには1つの数値ではなく、上位のグループが表示されます。
visualization	内訳の表示方法です：bars（デフォルト）、columns、donut、table。breakdownなしでは絶対に送信しないでください：内訳のないカードは、ここで何を指定しても単一の数値になります。
title	指標名の代わりに表示されます。
position	ダッシュボード上の順序です。昇順で並びます。

厳守事項：breakdownなしでvisualizationを設定しないでください。 内訳のないカードは、visualizationの値にかかわらず単一の数値になります。分割するフィールドがないのにグラフ（棒、列、ドーナツ）を求められた場合は、どのフィールドで分割するかを尋ね、ユーザーの回答があるまで何も記述しないでください。

カードに保存されるのは質問であり、答えではありません。指標の選び方、対象範囲の設定方法、値の計算方法についてはmetricsスキルを参照してください。カードを追加したり、カードの表示内容を報告したりする前に必ず読んでください。

ツールの呼び出し

// Dashboards
api_read   { "resource": "dashboards", "params": { "fields": "id,name,description" } }
api_write  { "resource": "dashboards", "data": { "name": "Sales", "description": "…" } }
api_write  { "resource": "dashboards", "id": "<dashboard id>", "data": { "name": "…" } }
api_delete { "resource": "dashboards", "id": "<dashboard id>" }

// Cards — flat, not under the dashboard: list ONE dashboard's with a filter
api_read   { "resource": "dashboard-cards", "params": { "filter": "dashboardId == \"<dashboard id>\"", "pageSize": 200 } }
api_read   { "resource": "dashboard-cards", "id": "<card id>" }
api_write  { "resource": "dashboard-cards", "data": { "dashboardId": "…", "measure": "…" } }
api_write  { "resource": "dashboard-cards", "id": "<card id>", "data": { "title": "…" } }
api_delete { "resource": "dashboard-cards", "id": "<card id>" }

レコードは常にdataの下に指定します。ダッシュボードは古いものから順に一覧表示されます。最初のものがユーザーの最初の遷移先です。カードはposition順に返されます。 api_details({ resource: "dashboard-cards", operation: "create" })がリクエスト本文の正式な仕様です。読み取りにはViewerが必要です。書き込みにはMemberが必要です。403は、ユーザーのロールではダッシュボードを変更できないことを意味します。

ダッシュボードを読む

名前でダッシュボードを検索し（filter: "name == \"Sales\""）、カードの一覧を取得します。ユーザーが関心のある各カードについて、metricsスキルの説明に従って値を計算します。対象範囲にはsegmentIdまたはfilterを使い、結合のヒントにはセグメントのパス、続いてカードのjoinPathsを使い、内訳にはbreakdownを使います。各カードについて、title（または指標のタイトル）、値、集計対象を報告してください。

グラフには内訳が必要です

ユーザーが棒、列、ドーナツ、または「ビジュアライゼーション」を求めた場合、新しいカードでも既存のカードでも、breakdownとvisualizationをセットで送信してください。visualizationだけを送信してはいけません。保存自体は成功しますが、カードは単なる数値のままです（分割を示すタイトルを付けても変わりません）。ディメンションはユーザーの発言（「パイプライン別」「ステージ別」など）から特定します。指定がなければ、metaから適切なディメンションを2つか3つ提示して尋ねてください。自分で選んではいけません。回答があるまで何も記述しないでください。カードにグラフが表示されると伝える前に、読み取り結果でbreakdownが設定されていることを確認してください。

カードの追加

1. ダッシュボードのカードを一覧表示します。 同じスコープの同じ指標がすでにある場合は、重複して追加せず、そのカードを案内します。

2. 指標とスコープを選びます。 指標スキルを使います。指標は数値指標にします。スコープは、指標のキューブをルートとするセグメント、条件、または指定なしです。他のキューブを読み取る場合は、それぞれに結合パスを指定します。行数が多いキューブには条件を指定しません。

3. 作成します。 dashboardId と measure は必須です。必要に応じて segmentId または filter、joinPaths、breakdown、visualization、title を追加します。最後に追加する場合は position を省略します。visualization を指定できるのは breakdown がある場合だけです。フィールド名が指定されていないグラフを求められた場合は、ここで止めて、どのフィールドか尋ねます（上記を参照）。

   サーバーは、ダッシュボードとセグメントが存在すること、指標が数値指標であること、内訳がディメンションであること、各条件に存在する member が指定されていること、セグメントとフィルターが同時に設定されていないことを確認します。問題がある場合は、400 で一度にすべての問題が示されます。すべて修正してから送信してください。変更せずに再送信しないでください。 サーバーは、セグメントのルート、指標の条件、ファンアウト、joinPaths は確認しません。これらは保存できても、アプリではカードが利用不可として表示されます。

4. カードを読み戻して値を計算します。 ユーザーがカードに表示される内容を確認できるようにします。また、問題のあるカードをユーザーが気づく前に検出します。

カードの変更

変更するフィールドだけを送信します。null を指定すると、title、segmentId、breakdown、visualization がクリアされます。filter と joinPaths は全体が置き換わるため、必ず最新の読み取り結果をもとにしてください。

• フィルターからセグメントへ：{ "segmentId": "…", "filter": {} }。 セグメントからフィルターへ：{ "segmentId": null, "filter": { … } }。
• 条件または別のキューブの内訳を削除する場合：カード内でそのキューブを引き続き読み取るものが他にない限り、対応する joinPaths の項目も削除します。
• 並べ替え：新しい隣接項目の間の position を指定します（1 と 2 の間なら 1.5）。
• 移動：dashboardId を設定します。position を指定しない場合は最後に移動します。

サーバーが確認するのは、更新で指定された項目だけです。タイトルの変更では、他の項目は再検証されません。

カードが利用不可になったり、表示がおかしくなったりする理由

カードが参照するモデルやセグメントが変更されても、自動修復は行われません。また、カードから参照されているセグメントやキューブを、カードに触れずに削除できます。カード（およびそのセグメント）を読み取り、アプリで次の順に確認します。

1. 指標がなくなった — measure が meta にありません。
2. セグメントがなくなった — segmentId の参照先が見つかりません。
3. フィールドがなくなった — 条件の member（カードまたは動的セグメントのもの）、内訳、または静的セグメントの segment_… キューブが meta にありません。
4. 指標に条件が指定されている — カードまたは動的セグメントのフィルター内にあります。
5. 結合がなくなった — joinPaths またはセグメントのパスにある経路が、モデルで定義されなくなっています。
6. ファンアウトに条件が指定されている — 行数が多いキューブに条件が指定されています。

更新で修正します（名前変更後の member を参照し直す、条件を削除する、スコープを変更するなど）。または、モデルで何を変更する必要があるかを伝えます。何も問題として示されていないのに数値がおかしい場合は、別の結合経路、再スナップショットされていない静的セグメント、保存済みの値と表記が異なる文字列値、ファンアウトする内訳、または古いデータ（metadata.lastRefreshTime）が原因の可能性があります。

ダッシュボードの作成、名前変更、削除

• 作成：name（1～255 文字）と、任意の description を指定します。先に同じ名前のものがないか確認し、存在する場合はどうするか尋ねます。全員に表示されるため、試すだけの目的で作成しないでください。
• 名前変更：name / description のみを変更します。
• カードの削除：カードを特定できる情報（タイトル、または指標、スコープ、ダッシュボード）を伝え、確認を得ます。
• ダッシュボードの削除：そのダッシュボード上のすべてのカードが削除されます。カードを一覧表示し、件数と内容を伝え、組織全体から削除されることを説明してから、このダッシュボードの削除について明示的な確認を求めます。

削除を元に戻すことはできません。失敗した操作で自分が作成したカードやダッシュボードも例外ではありません。削除する前にその旨を伝えて確認を求めてください。