workflows-modify

Zapier ワークフローの変更

デプロイ済みのワークフローを変更する際は、対象の特定、取得、編集、テスト、公開、確認の手順に従います。すべての変更は、ワークフローのサーバードラフト（Zapier エディターと共有される作業用コピー）を経由します。変更をドラフトに保存し、必要に応じて未公開のドラフトをテストしたうえで、テスト済みのドラフトを公開するか、ユーザーが後から確認して公開できるように開いたままにします。

公開するとユーザーの Zapier アカウントに書き込まれるため、公開前に明示的な確認を得てください。

公開 SDK CLI の実験的なコマンドを使用してください。zapier-sdk-code-substrate は使用しないでください。

互換性チェック

このスキルを使用する前に、workflows-doctor バンドルの互換性チェックを実行してください。workflows-doctor がインストールされていない場合、または読み込めない場合は、続行する前に workflows-install を実行するか、zapier/agent-skills から workflows-doctor をインストールしてください。workflows-doctor が SDK／スキルの不整合を報告した場合は、その更新手順に従ってください。このスキルの実行を中止し、必要に応じてエージェントのワークスペースを再読み込みしたうえで、元のリクエストを再実行するようユーザーに依頼してください。

ステップ 1：ワークフローを特定する

ユーザーからワークフロー ID が提供された場合は、それを直接使用してください。そうでない場合は、ワークフローを一覧表示し、名前または説明で一致するものを探してください。

zapier-sdk --stability experimental list-workflows --json

一致するワークフローが複数ある場合は、候補を提示して、どのワークフローを変更するかユーザーに尋ねてください。

ステップ 2：未完了のドラフトを確認する

zapier-sdk --stability experimental list-workflow-drafts <workflow-id> --json

一覧には、最近編集されたものから順に未完了のドラフトが表示されます。未完了のドラフトには、必ず未公開の作業が含まれています（公開するとドラフトは消費されるため、残っているドラフトは公開されていません）。

• 未完了のドラフトがある場合： そのドラフトを使用してください。ユーザーが作業中の編集内容が含まれており、今回の変更はその上に適用されます。複数のドラフトがある場合は、ユーザーに伝えて、どれを使用するか確認してください。
• 未完了のドラフトがない場合： ステップ 3 で作成してください。

ユーザーの依頼が即時公開をすでに意味している場合（「修正して公開して」など）は、変更を保存してテストした後に公開してください。まず確認したい場合、段階的に作業を進めたい場合、またはエディターで作業を引き継ぎたい場合は、ドラフトを開いたままにしてください。意図が不明な場合は、「変更が準備できたら公開しますか。それとも、後で確認・公開できるようドラフトのままにしますか？」と尋ねてください。

ステップ 3：現在のソースを取得する

ドラフトが存在しない場合は作成します（ワークフローの現在のライブバージョンからフォークされます）。その後、ドラフトを取得します。

zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
zapier-sdk --stability experimental get-workflow-draft <workflow-id> <draft-id> --json

取得したドラフトから、次の情報を記録します。

• source_files。特に source_files["workflow.ts"] には未公開の編集内容が含まれている場合があります。古いデータではなく、ユーザーが作業中の内容として扱ってください。
• draft_revision。すべての書き込みで楽観的同時実行制御を行うために必要です。
• dependencies、zapier_durable_version、trigger、connections、app_versions。

また、ワークフロー自体も取得し、名前、有効状態、メタデータを確認します。

zapier-sdk --stability experimental get-workflow <workflow-id> --json

この読み戻しから現在の開始モードを判定してください。変更時に開始モードを暗黙に変更してはいけません。 ワークフローの開始モードは 2 種類です。トリガー付きのワークフローが、引き継がれずに再公開されることでトリガーなしに変わってしまうことがあります。

• trigger — 次のいずれかに該当する場合、トリガーありと判定します。取得したバージョンまたはドラフトのソースに trigger オブジェクトが含まれている、または get-workflow の triggers[] が空ではない。trigger の設定全体をそのまま記録してください。公開時（ステップ 6）にもドラフトに保持されていないと、新しいバージョンではトリガーが失われます。
• manual — どちらのシグナルもない場合です。取得したソースに trigger オブジェクトがなく、かつ triggers[] が空です。この場合、ワークフローはオンデマンドでのみ実行されます。

2 つのシグナルが一致しない場合、特に保存済みの trigger 設定がある一方で、ライブの triggers[] が空または古い場合（claim に失敗した、保留中、または無効化された場合）は、手動と判定してはいけません。トリガーを保持し、ユーザーと状況を確認するまで処理を停止してください。保存済みのトリガーを削除すると、意図せずトリガーなしになるという、この判定で防ぐべき問題が発生します。

現在のモードを判定する際は、triggers[] と取得したトリガー設定を基準にしてください。プラットフォームの開始モード入力（書き込み専用の manual フラグ）は、読み戻しには一切表示されないため、探す必要はありません。ユーザーから開始モードの変更（手動ワークフローへのトリガー追加、またはトリガーの削除）が明示的に依頼されない限り、変更時には開始モードを維持します。編集、公開、検証を通じて、記録したモードを引き継いでください。

このステップの残りの確認は、既存のドラフトに基づいて作業する場合にのみ適用されます（作成したばかりのドラフトでは、作成元と同一のため省略します）。

未公開のドラフト変更を確認します。 ドラフトを公開すると、編集内容だけでなく、ドラフト内のすべてが公開されます。そのため、ドラフトがライブの内容からすでに逸脱しているかどうかを把握する必要があります。ドラフトのベースバージョンを取得して比較してください。

zapier-sdk --stability experimental get-workflow-version <workflow-id> <base_version_id from the draft> --json

ドラフトの source_files、トリガー、接続、アプリバージョンがベースバージョンと異なる場合、ドラフトには未公開の作業が含まれています。差分の概要を簡潔に記録し、ステップ 6 の確認時にユーザーに伝えてください。確認なしに公開したり、確認なしに破棄したりしてはいけません。

ドラフトが古くなっていないか確認します。 ドラフトは作成時のライブバージョンからフォークされますが、その後ライブバージョンが更新されている場合があります。ドラフトの作成後に、別のドラフトが公開されている可能性もあります。最新バージョンの id とドラフトの base_version_id を比較してください。

zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json

• ベースが最新バージョンの場合： 古くなっていないため、続行します。

• 未公開の変更がなく古くなっている場合（上記の差分確認で変更が見つからなかった場合）：ドラフトは古いバージョンの残骸です。そのドラフトを基に作業してはいけません。破棄し、ライブから新しいドラフトをフォークしたうえで、そうしたことをユーザーに伝え、新しいドラフトで続行してください。

  zapier-sdk --stability experimental discard-workflow-draft <workflow-id> <draft-id> --json
  zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
  

• 未公開の変更があり、古くなっている場合： 処理を停止し、ユーザーに伝えてください。このドラフトをそのまま公開すると、フォーク後に公開されたすべての新しいバージョンの変更が元に戻ります。安全な方法は、ライブから新しいドラフトをフォークし、ドラフトの未公開変更（および今回の編集）をそこに移すことです。その方法を提案し、変更を移すか、古いドラフトをそのまま公開するか、ユーザーにはっきり選択してもらってください。ユーザーに代わって選択してはいけません。

ステップ 4：編集する

既存のローカルワークフローファイルがある場合は、そちらを編集してください。ない場合は、source_files["workflow.ts"] をワークフロー専用ディレクトリ内のローカルな workflow.ts に書き込み、そのコピーを編集してください。

依頼された変更は必要最小限にとどめてください。変更する理由がない限り、既存の Zod スキーマ、ctx.step の境界、接続エイリアス、依存関係のバージョン固定、永続ランタイムのバージョン、接続のバインディング、アプリバージョンのバインディング、トリガー設定、表示／有効状態を維持してください。依頼された変更に関係しない未公開のドラフト内容も保持してください。

new Date()、Date.now()、Math.random() など、リプレイ時に異なる値はステップ内に置き、一度だけジャーナルに記録されるようにしてください。ステップの外で計算された値はリプレイ時に変わり、DeterminismViolation によって実行が失敗します。

編集によって AI／LLM ステップを追加する場合は、workflows-create のフェーズ 2 にある AI by Zapier のガイダンスに従ってください。

ステップ 5：ドラフトのテストを計画する

重要な変更では、公開する前にテスト実行を提案してください。テストでは保存済みのドラフトを実行するため、編集を保存した後、ドラフトを公開する前のステップ 6 で実施します。実際の後続アクションが実行される場合があるため、副作用を要約し、確認を待ってください。

ステップ 6：確認してから公開する

書き込みを行う前に、ユーザーに以下を要約してください。

1. 診断内容。
2. コードまたは設定の変更内容。
3. 更新するワークフロー ID とドラフト。
4. 維持する値。依存関係、永続バージョン、有効状態、接続、アプリバージョン、トリガー設定を含めてください。
5. ステップ 3 で取得した開始モード（trigger または manual）と、この編集では変更されないこと。変更依頼の場合は、変更内容を明記してください（手動ワークフローへのトリガー追加、またはトリガー削除）。変更によって開始モードが意図せず変わることはありません。
6. 今すぐ公開するか、レビュー用にドラフトを残すか（ステップ 2）、およびステップ 3 で見つかった未公開のドラフト変更。ドラフトを公開すると、それらの変更も反映されます。

明示的な確認を待ってから、source_files を完全なマップとして構築してください。取得したドラフトの source_files に含まれるすべてのキーを残し、編集したファイルは置き換えます。更新ではマップ全体が置き換えられるため、含めなかったファイルは削除されます。取得したマップを FETCHED_SOURCE_FILES に保存し、編集したファイルごとに --rawfile を 1 つ追加してください。

SOURCE_FILES="$(jq -n --argjson base "$FETCHED_SOURCE_FILES" --rawfile workflow workflow.ts '$base + {"workflow.ts": $workflow}')"

公開する前に、公開予定のバージョンがステップ 3 で取得した開始モードと一致することを確認してください。 trigger モードのワークフローのドラフトにはトリガーが設定されている必要があり、--manual を付けずに公開してください。manual モードのワークフローのドラフトにはトリガーを設定せず、--manual を付けて公開してください（モード変更が明示的に依頼されている場合は、意図する新しいモードに合わせてください）。トリガーまたは --manual のどちらか一方だけを指定してください。プラットフォームの契約は判別可能なユニオンであり、両方を指定すると矛盾として拒否されます。trigger モードで再公開する際にトリガーが失われると、トリガーのないワークフローが気づかれずに生じる回帰になります。トリガーは保存済みのドラフトにあります。以下の開始モードの確認を参照してください。

ドラフトの保存、テスト、公開

ステップ 3 で未公開のドラフト変更が見つかった場合は、先に解決してください。ユーザーに、明示的に「今回の変更に含める」か「クリーンな状態から始める」かを尋ねてください。

• 含める： 記載どおりに進めます。ドラフト内容と編集内容をまとめて反映します。

• クリーンな状態から始める： ドラフトを破棄し、公開済みのバージョンから新しいドラフトをフォークしてから、新しいドラフトに編集を適用します（新しいドラフトに対してステップ 3～4 を再実行してください）。

  zapier-sdk --stability experimental discard-workflow-draft <workflow-id> <draft-id> --json
  zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
  

未公開の作業を破棄することが認められている方法は、破棄して再フォークすることだけです。ドラフト内容をその場で上書きして削除してはいけません。

読み取り時の draft_revision を渡して、編集内容をドラフトに保存してください。

zapier-sdk --stability experimental update-workflow-draft <workflow-id> <draft-id> "$SOURCE_FILES" \
  --draft-revision <draft_revision from Step 3> \
  --json

省略したフィールドには保存済みのドラフト値が保持されます。そのため、編集によって値を変更する場合に限り、--trigger、--connections、--app-versions、--dependencies、--zapier-durable-version を渡してください。--trigger、--connections、--app-versions に null を渡すと、保存済みの値がクリアされます。フィールドを「スキップ」するために、これらを null にしてはいけません。 開始モードの確認： トリガーは保存済みのドラフトに含まれており、publish-workflow-draft は --trigger フラグを受け取りません。つまり、ドラフトに保持されている内容がそのまま公開されます。そのため、正しい trigger モードのドラフトを公開するとき、公開時に --trigger を指定しないのは想定どおりであり、トリガーが失われたわけではありません。publish-workflow-draft の実行直前に、ドラフトに保存されている trigger が、取得済み（または意図した）開始モードと一致していることを必ず確認してください。trigger モードのドラフトには引き続きトリガーが設定され、manual モードのドラフトには設定されません。不明な場合は get-workflow-draft で読み戻してください。そのうえで、公開時に開始モードを指定します。manual モードのワークフローでは、下記のとおり publish-workflow-draft に --manual を指定します。trigger モードのワークフローでは、ドラフトにすでにトリガーが保持されているため、--manual を指定せずに公開します。保存済みのトリガーと --manual を絶対に併用しないでください。プラットフォームの仕様により、両方を指定すると拒否されます。上記の update-workflow-draft で --trigger null を指定してトリガーをクリアすることが、trigger モードのワークフローを意図せず manual モードに変えてしまう原因です。

ステップ 5 でテストが必要とされた場合は、保存済みのリビジョンをテストします。 ドラフトを読み取り、現在の draft_revision を確認してから（更新レスポンスにも返されます）、そのリビジョンを実行します。

zapier-sdk --stability experimental run-workflow-draft <workflow-id> <draft-id> <draft-revision> \
  --input '<JSON matching input schema>' \
  --json

ワークフローが入力を受け取らない場合は、--input を省略します。実行には、ドラフトに保存された依存関係、接続、アプリのバージョンが使用されます。返された id を取得し、get-workflow-run <run-id> --json をポーリングします。status が "finished"、output が変更によって生成されるべき内容、error が null、トップレベルの errors が空、kind が "draft" であり、workflow_id、workflow_draft_id、draft_revision がテストしたドラフトと一致すれば、テストは成功です。失敗した場合は、ソースを修正してドラフトを再度更新し、新しいリビジョンをテストしてください。

ユーザーが後で公開することを選んだ場合は、 ここで止めます。ドラフト ID とドラフトのエディターリンク（https://zapier.com/workflow/<workflow-id>/draft/<draft-slug>/workflow.ts）を伝えてください。<draft-slug> にはドラフトのレスポンスに含まれる slug を使います。ユーザーはエディターで内容を確認して公開するか、後続のやり取りであなたに公開を依頼できます。最終セグメントは、ドラフトの source_files キーのいずれかです（このスキルのフローでは workflow.ts）。

それ以外の場合は今すぐ公開します。 テスト済みの draft_revision を指定してください（テストしていない場合は、更新レスポンスの値を指定します）。これにより、同時編集された内容が未テストのまま公開されるのを防げます。開始モードに合った方法で公開します（ドラフトにはすでにトリガーが保持されており、違いは --manual を指定するかどうかだけです）。

trigger モード — 保存済みのトリガーがシグナルになるため、--manual を省略します。

zapier-sdk --stability experimental publish-workflow-draft <workflow-id> <draft-id> \
  --draft-revision <tested draft_revision> \
  --json

manual モード — ドラフトにトリガーは保持されていないため、--manual を指定します。

zapier-sdk --stability experimental publish-workflow-draft <workflow-id> <draft-id> \
  --draft-revision <tested draft_revision> \
  --manual \
  --json

ドラフトを公開すると、新しい不変バージョンが作成され、ライブポインターが更新され、ドラフトは破棄されます。公開によってドラフトは消費されるため、開いているドラフトがある場合は、常に未公開の変更が存在します。レスポンスには、新しい version と、消費されたドラフト（status: "discarded"）の両方が含まれます。以降の変更は、ステップ 2 から再開してください。

--enabled を省略して公開すると、ワークフローの現在の有効状態が維持されます。ユーザーが有効状態の変更を求めていない限り、省略してください。

競合（リビジョンの不一致）が発生した場合： 読み取り後、書き込み前に誰か（おそらくエディター上のユーザー）がドラフトを編集しました。無条件で上書きしてはいけません。ドラフトを再読み込みし（get-workflow-draft）、最新の source_files に変更を再適用して、新しい draft_revision で再試行してください。最新の内容と変更が重大な点で衝突する場合は、作業を中止してユーザーに確認してください。

ステップ 7：確認

変更を公開した場合は、ワークフローとバージョンを読み返します。

zapier-sdk --stability experimental get-workflow <workflow-id> --json
zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json

最新バージョンに公開内容が反映されていること、必要な場合はワークフローが引き続き有効になっていること、トリガー／接続／アプリバージョンのメタデータが保持されていることを確認します。

開始モードの保持をゲート条件にします。 デプロイされた開始モードを、ステップ 3 で記録したものと比較します。enabled の状態とトリガーの有無は別々に確認する必要があります。enabled のチェックだけではトリガーが失われていても検出できないため、triggers[] を直接確認してください。

• 記録したモードが trigger（かつ、編集でトリガーを削除する意図がなかった場合）→ 読み返した結果でも triggers[] が空でないこと、および enabled がワークフローの保持されるべき有効状態（ステップ 3 で記録）と一致することを必須とします。常に enabled: true を要求するわけではありません。編集前に無効だったワークフローは、無効のままでもこのゲートを通過します。enabled: true を要求するのは、編集前に有効だった場合、またはユーザーが有効化を依頼した場合だけです。triggers[] が空の場合、公開されたドラフトにトリガーが引き継がれていません（多くの場合、update-workflow-draft 呼び出しで --trigger null を渡したか、設定を変更したことが原因です）。変更が完了したと報告してはいけません。update-workflow-draft --trigger '<captured trigger JSON>' で記録した設定を復元し、新しいドラフトのリビジョンをテストしてから公開し、再確認してください。トリガーが保持されたことを証明するのは enabled の状態ではなく triggers[] の確認です。トリガー付きワークフローが正当に無効の場合もあり、トリガーを失った無効なワークフローでも enabled: false と表示されます。
• 記録したモードが manual（かつ、編集でトリガーを追加する意図がなかった場合）→ triggers[] が空のままであることを必須とします。予期せずトリガーが表示された場合も不一致です。作業を止め、ユーザーと調整してください。
• 依頼で開始モードを明示的に変更する場合は、読み返した結果が意図した新しいモードと一致することを確認します。この比較では triggers[] を基準にします。プラットフォームの書き込み専用 manual フラグは読み返し結果に表示されないため、探してはいけません。

トリガーの種類にかかわらず、triggers[] の該当エントリにある details.webhook_url を確認してください。値がある場合、それは外部サービスが呼び出すキャッチ URL であり、共有することを前提としています。ワークフローレベルの trigger_url とは異なります。ほとんどのトリガーには存在しませんが、これは正常です。ライブトリガーを実行しないと変更を検証しにくい場合は、ユーザーに送信すべきテストイベントと期待される結果を具体的に伝えてください。

最後に、次の内容を報告します。

• ワークフロー名と ID。
• 依頼された変更を公開したか、後で公開できるようドラフトに保存したか（ドラフト ID を含む）。
• 開始モード（trigger または manual）と、それが保持されたこと（変更依頼の場合は新しい値）を、ステップ 7 のゲートで確認した結果。
• トリガー、接続、アプリバージョンのメタデータが保持されたかどうか。
• ワークフローが有効かどうか。
• トリガーの webhook_url が存在する場合は、その値。
• Zapier エディターのリンク：https://zapier.com/workflow/<workflow-id>。変更をドラフトとして保存した場合は、ドラフトのリンク https://zapier.com/workflow/<workflow-id>/draft/<draft-slug>/workflow.ts。

元に戻す

以前のバージョンは読み取り専用の履歴として引き続き利用できます。元に戻すには、以前のバージョンのソースを取得します。

zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json
zapier-sdk --stability experimental get-workflow-version <workflow-id> <version-id> --json

その後、ステップ 6 と同様に公開します。以前のバージョンの source_files とメタデータを update-workflow-draft でドラフトに読み込み、テストしてからドラフトを公開します。ステップ 6 と同じ確認と競合処理を行います。