pipefy-relations

接続とリレーション

MCP クライアントについては、references/mcp.mdを参照してください。CLI ユーザーについては、references/cli.mdを参照してください。以下の例では、共通の操作引数について説明します。

ワークフロー間でプロセスとカードをリンクします。

---

主な概念

• パイプリレーションは、パイプ間の親子構造（どのパイプがどのパイプに接続するか、制約、自動入力）を定義します。パイプでget_pipe_relationsを使用すると、リレーション ID とメタデータを一覧表示できます。
• カードリレーションは、既存のパイプリレーションを介して個々のカードを接続します。source_idにはパイプリレーションの ID（get_pipe_relationsから取得）を指定します。sourceTypeのデフォルトはPipeRelationです。API がフィールドベースのリンクを要求する場合は、extra_input（例：sourceType: Field）を使用してください。詳細はCreateCardRelationInputのintrospect_typeを参照してください。
• GraphQL のテーブルリレーションは、データベーステーブル ID ではなく、テーブルリレーション ID で読み込みます。get_table_relationsには、空でない ID リストを渡します。
• コネクターフィールドはカードのフィールド（接続型）であり、書き込み用のパイプリレーションではありません。operationに ADD/REMOVE を指定したfield_updatesでupdate_cardを使用してください（関連するカード ID、またはフィールドがデータベーステーブルに接続する場合はレコード ID）。他のパイプやテーブルの ID はエラーなしで除外されます。ADDは既存のリンクを保持し、有効な ID が指定されていないupdate_card_fieldはすべてのリンクをクリアします。書き込み後はリンクを読み戻してください。update_card_fieldは ID リスト全体を置き換えます。get_cardのvalueは表示タイトルのみのため、これを使ってリストを再構築しないでください。このスキルのget_card_relationsは、引き続きコネクターフィールドのリンクを（カード ID とともに）読み込みます。create_card_relation／delete_card_relationはパイプリレーションを介してリンクを書き込み、増分更新を行います。リンクの種類に合った方法を選択してください。delete_card_relationが削除するのは、パイプリレーションを介して作成されたリンクのみです。コネクターフィールドのリンクは削除しません。また、親カードを編集する権限が必要です。

---

ツール

操作	読み取り専用	用途
get_pipe_relations	はい	パイプのパイプ間リレーションを一覧表示します。
create_pipe_relation	いいえ	新しいパイプ間リレーションを作成します。
update_pipe_relation	いいえ	リレーションの設定（自動入力、制約）を変更します。すべての制約フラグを渡してください。「失敗の原因」を参照してください。
delete_pipe_relation	いいえ	破壊的操作です。事前に確認して承認してください。
get_table_relations	はい	リレーション ID でテーブルリレーションを読み込みます。
get_card_relations	はい	カード上のカード間リレーションをすべて一覧表示します。
create_card_relation	いいえ	既存のパイプリレーションを介して2枚のカードをリンクします。
delete_card_relation	いいえ	破壊的操作です。事前に確認して承認してください。

---

手順 — 既存のパイプリレーションを介して2枚のカードをリンクする

1. パイプリレーション ID を取得します。

   操作：get_pipe_relations(pipe_id=67890)

   リレーションのidフィールドを確認します（パイプ ID ではありません）。

2. カードリレーションを作成します。

   操作：create_card_relation(parent_id=<PARENT_CARD_ID>, child_id=<CHILD_CARD_ID>, source_id=<PIPE_RELATION_ID>)

3. 確認します。

   操作：get_card_relations(card_id=<CHILD_CARD_ID>)

---

手順 — 新しいパイプリレーションを作成する

1. 2つのパイプ間にリレーションを作成します。

   操作：create_pipe_relation(parent_id=111, child_id=222, name="Support Escalation")

2. リレーションを使用します — 親パイプ内のカードを、create_card_relationを使用して子パイプ内のカードにリンクできるようになります。

---

成功条件

• get_pipe_relationsが、両方のパイプ ID を含む新しいリレーションを返します。
• create_card_relationの実行後、get_card_relationsにリンクされたカード ID が表示されます。

失敗しやすいケース

• create_card_relation が「relation not found」で失敗する： source_id には、パイプ ID ではなく、get_pipe_relations で取得したパイプのリレーション IDを指定する必要があります。これらは異なる値です。
• テーブルのリレーションが空で返される： get_table_relations には、テーブル ID ではなくテーブルのリレーション ID が必要です。テーブルの接続設定からテーブルのリレーション ID を取得してください。
• update_pipe_relation は、指定しなかったフラグをリセットします。 Pipefy では、更新のたびに 8 つすべての制約フラグ（allChildrenMustBeDoneToFinishParent、allChildrenMustBeDoneToMoveParent、autoFillFieldEnabled、canConnectExistingItems、canConnectMultipleItems、canCreateNewItems、childMustExistToFinishParent、childMustExistToMoveParent）を指定する必要があります。渡さなかったフラグにはデフォルト値が設定されます。3 つの canConnect…／canCreateNewItems フラグは true、残りの 5 つは false になります。そのため、名前を変更するだけでもリレーションの制約が変わります。get_pipe_relations でリレーションを読み取り、各フラグの現在の値をすべて指定してください。自動入力マッピングを維持するには、ownFieldMaps は省略してください。指定すると、リスト全体が置き換えられます。
• 削除： 影響を受けるリレーションを提示し、削除する前に承認を得てください。

関連項目

• pipefy-pipes-and-cards — リンクする前にパイプとカードを作成してください。コネクタフィールドの更新と update_card_field の全置換に関する情報もこちらにあります。
• docs/mcp/tools/identifiers.md — フィールドおよびリレーションのツールで、どの引数にスラッグと数値 ID のどちらを指定するかについて説明しています。
• pipefy-introspection — 標準以外の sourceType が必要な場合に、CreateCardRelationInput を確認できます。