pipefy-html-interfaces

HTML インターフェース

MCP クライアントは references/mcp.md を参照してください。CLI ユーザーは references/cli.md を参照してください。

HTML インターフェースは、単一の要素が 1 つの HTML ドキュメントを保持する customCode 要素であるページです。この要素は、HTML がソース ID で読み取るデータソース（パイプまたはテーブル）を宣言できます。HTML を書き込むと公開されます。下書きはありません。

使用する場面

• 「未対応のリクエストを表示するページを作って」「このパイプからダッシュボードページを作って」
• 「HTML インターフェースのレイアウト／文言／色を変更して」
• 「テーブル X をページのデータソースに追加して」
• 「HTML インターフェースを一覧表示して」「ページ Y の HTML を表示して」

ユーザーが「ページ」と依頼し、それが単独の HTML ページを指すのか、メインポータル内のページを指すのか不明な場合は、作業を始める前に確認してください。

使用しない場面： メインポータル、そのグリッドレイアウトのページと要素、サブポータルは pipefy-portal-setup にあります（list_portals と get_portal で確認でき、get_interface_html はこれらを拒否します）。パイプ、フィールド、カード自体は pipefy-pipes-and-cards にあります。ポータルのページまたは要素のツールを使って HTML インターフェースを変更しないでください。これらのツールはその customCode 要素を受け付けますが、ここにあるツールが実施するチェックを行わずに、そのメタデータとソースを置き換えます。

前提条件

• 組織で HTML インターフェースが有効になっていること。 Pipefy が組織ごとに有効化します。組織の管理者が有効化することはできません。この機能が有効になっていないために呼び出しが失敗した場合は、作業を中止し、組織で HTML インターフェースを有効にするよう Pipefy に依頼することをユーザーに伝えてください。有効化できるツールはありません。
• 組織 ID。 list_interface_repos が受け付けるのは数値の組織 ID のみです。create_html_interface と list_interfaces は数値 ID または UUID を受け付けます。通常、ユーザーが提示するのは UUID または名前なので、list_organizations の id を使って数値 ID を調べ、すべての操作で使用してください。
• ページに表示するパイプとテーブルへの管理者アクセス権。 list_interface_repos に表示されるのは、呼び出し元が管理する公開済みのパイプとテーブルのみです。

操作

操作	読み取り専用	目的
get_interface_html_guidelines	はい	HTML が従うべきルール、データのバインドに使う data-pfy-* の語彙、フィルター形式を取得します。include_design_system を指定すると、デザインシステムのカタログも取得します。
list_interface_repos	はい	データソースとして使用できるパイプとテーブルを一覧表示します。
get_interface_repo_fields	はい	ソースの fieldKeys を選ぶために、パイプまたはテーブルのカスタムフィールドを取得します。
list_interfaces	はい	組織の HTML インターフェースを visibility とともに一覧表示します。
get_interface_html	はい	1 つのインターフェースのページ、要素、データソース、公開中の HTML を取得します。
create_html_interface	いいえ	インターフェースを作成し、最初のページを書き込みます。ソースは任意で指定できます。
set_interface_sources	いいえ	要素のデータソースを置き換えます。
write_interface_html	いいえ	要素の HTML を置き換えて公開します。

すべてのフローに適用されるルール

• まずガイドラインを読みます。 HTML を書く前に get_interface_html_guidelines を呼び出し、その内容に従ってください。このスキルではルールを繰り返しません。ガイドラインが唯一の参照元であり、プラットフォームに応じて変更されます。デフォルトでは、ルールより数倍大きいコンポーネントカタログである designSystem は省略されます。ページのスタイルを設定する場合に限り、include_design_system を指定して取得してください。
• dataPfyVocabulary の指示どおりにデータをバインドします。 各 data-pfy-* 属性の役割、ほとんどの場合に属性を付ける要素、属性に設定する値が記載されています。バリデーターが確認するのは属性が許可されているかどうかだけなので、誤った場所にバインドしても受け入れられます。
• 書き込みはすべて即時反映されます。 create_html_interface、write_interface_html、set_interface_sources を実行すると、訪問者に表示される内容がすぐに変わります。ユーザーからの具体的な依頼（「見出しを X に変更して」など）は、その変更への承認とみなされます。ユーザーが言及していないマークアップの書き換えや、まだ使用中のソースの削除など、それ以外の変更を行う前に、変更内容をユーザーに見せて承認を得てください。
• 公開中のページが、宣言済みのソースだけを読み取るようにします。 要素が宣言していないソース ID を読み取る HTML は、エラーを表示せずに空白でレンダリングされます。そのソースを読み取る HTML を書く前に、ソースを追加してください。ソースの削除や名前の変更は、公開中の HTML がそのソースを読み取らなくなってから行ってください。
• 再度書き込む前に、違反をすべて修正します。 書き込みが拒否されると、何も保存されず、すべての違反が一覧表示されます。すべてを一度に修正してから、再度書き込んでください。HTML がユーザーから提供されたものの場合は、違反内容とルールに従ったバージョンをユーザーに見せ、ユーザーが同意してから公開してください。

手順 — ページの作成

1. ルールを読みます。 ページのスタイルを設定する場合は、デザインシステムのカタログも読みます。

   get_interface_html_guidelines
   get_interface_html_guidelines include_design_system=true
   

2. 名前が使用可能か確認します。 その名前のインターフェースがすでに存在する場合は、変更するか（次のセクションを参照）、別のインターフェースを作成するか、ユーザーに確認してください。

   list_interfaces organization_uuid=<org_id> search_term=<name>
   

3. データを選びます（ライブデータのないページでは省略）。候補となるリポジトリを一覧表示し、使用する各リポジトリのフィールドを一覧表示します。

   list_interface_repos organization_id=<org_id> repo_name=<name_fragment>
   get_interface_repo_fields repo_uuid=<repo_uuid>
   

   ソースは {"id", "name", "repoId", "fieldKeys", "filters"} です。repoId はリポジトリの uuid です。fieldKeys には 1〜30 個のキーを指定します。キーにはカスタムフィールドの uuid（id ではありません）、または title のような組み込みキーを指定できます（組み込みキーは、ガイドラインの filters.fixedColumnNames に記載されています）。filters は任意で、ガイドラインに記載されたフィルター形式に従います。id と name は要素内で一意であり、HTML は id でソースを読み取ります。1 つの要素が保持できるソースは最大 10 個です。

4. ガイドラインに従って HTML を記述し、dataPfyVocabulary の属性を使って各ソースをその id でバインドします。

5. 1 回の呼び出しで、ソースと HTML を含むインターフェースを作成します。

   create_html_interface organization_uuid=<org_id> name="Open requests" html=<document> data_sources=[{"id": "requests", "name": "Open requests", "repoId": <repo_uuid>, "fieldKeys": ["title", <field_uuid>]}]
   

   結果には、新しいインターフェースの uuid とページ ID、要素 ID が含まれます。インターフェースの名前と uuid をユーザーに伝えてください。

手順 — 既存のページを変更する

1. ページを探して読み取ります：

   list_interfaces organization_uuid=<org_id> search_term=<name_fragment>
   get_interface_html interface_uuid=<interface_uuid>
   

   ユーザーが指定したページにある、type が customCode の要素を使います。インターフェースに複数のページまたは customCode 要素がある場合は、それらを一覧表示してどれを使うか尋ねます。pages[].uuid から page_id を、pages[].elements[].uuid から element_id を取得し、要素の dataSources から現在のソースを取得して、htmlDocument.contentHash を記録します。

2. 新しい HTML でさらにデータが必要な場合は、ソースを追加します。ページでまだ読み取っていないフィールドの場合、ソースの repoId に対して get_interface_repo_fields を使い、その uuid を探します。現在のソースに新しいソースを加えた完全なリストを送信します。これは要素のソースを置き換えます。[] を送信すると、すべてのソースが削除されます。get_interface_html で読み取ったソースは、そのまま読み取り用として返せます。保持する各ソースの id は変更しないでください。

   set_interface_sources interface_uuid=<interface_uuid> page_id=<page_id> element_id=<element_id> data_sources=[...]
   

3. 読み取ったドキュメントを基に、新しい HTML を作成します。書き込む直前に、インターフェースを再度読み取ります。contentHash が変わっていた場合は、誰かがページを編集しています。その場合は新しいドキュメントを基にやり直し、ユーザーに変更内容を提示します。

   write_interface_html page_id=<page_id> element_id=<element_id> content=<document>
   

4. ユーザーが削除を希望する場合は、新しい HTML で読み取らなくなったソースを、完全なリストを送信する set_interface_sources の追加呼び出しで削除または名前変更します。

成功条件

• 作成または書き込みが、違反なしで成功を返します。
• get_interface_html に、新しいドキュメントと要素の想定どおりの dataSources が表示されます。
• HTML が読み取るすべてのソース ID が、要素の dataSources に含まれています。

失敗時の対応

• 作成は成功しましたが、書き込みに失敗しました。 空白のページがあるインターフェースが作成されています。エラーには、その uuid、page_id、element_id が示されます。エラーを解決し（HTML が拒否された場合は修正し）、それらの ID を使って write_interface_html を呼び出します。create_html_interface は再度呼び出さないでください。孤立したインターフェースがもう一つ作成されます。
• 作成の結果、書き込み先のページが返されませんでした。 インターフェースは存在している可能性があり、エラーにはその uuid が示されます。それ以上の操作をする前に get_interface_html で確認し、作成をむやみに再試行しないでください。
• 作成に失敗し、エラーに uuid がありません。 インターフェースは存在している可能性があります。再試行する前に list_interfaces を名前で検索し、同じ名前の新しいインターフェースが見つからない場合に限り、再度作成します。
• 書き込み時に HTML が拒否されました。 何も保存されていません。ガイドラインに照らして、一覧に示された違反をすべて修正してから、再度書き込みます。
• 違反が一覧表示されずに書き込みに失敗しました。 get_interface_html でページを読み取り、何が保存されているかを確認してから、もう一度書き込みます。再度失敗した場合は停止してユーザーに伝えます。
• ページのセクションが空白で表示されます。 HTML が読み取るソース ID が要素に宣言されていないか、名前変更または削除されています。get_interface_html の HTML と dataSources を比較して、ソースまたは HTML を修正します。
• インターフェースが重複しています。 両方の名前と uuid をユーザーに提示します。ユーザーの承認を得たうえで、追加のインターフェースの uuid を portal_uuid として指定し、確認を求める delete_portal で削除します。
• list_interface_repos にリポジトリがありません。 未公開か、呼び出し元がその管理者ではありません。空のリストは、組織 ID が間違っていることも意味します。この一覧取得では、存在しない組織やインターフェースは報告されません。
• get_interface_html がインターフェースを拒否します。 グリッドレイアウトのポータルまたはサブポータルです。pipefy-portal-setup を使用してください。
• ソースの更新内容が不明です。 set_interface_sources は、保存された内容ではなく送信されたソースを返します。get_interface_html でもう一度読み取ってください。

関連項目

• pipefy-portal-setup：メインポータル、そのグリッドレイアウトのページと要素、およびサブポータル。
• pipefy-pipes-and-cards：ページが読み取るパイプとフィールドを作成します。