actions

アクション

同じ名前を持つものが3つあり、それぞれを見分けることが作業の大部分を占めます。

• アクションは、あるオブジェクトに対してインテグレーションが行う1つの操作です。 「NetSuite upsert customer」や「Enrich name」などです。カタログは actions リソースで、各アクションは id と integrationName を持ちます。
• アクション列は、テーブルに組み込まれたアクションです。どのアクションを使うか、 その params、および行のどの列をアクションに渡すかを示す input マッピングで 構成されます。テーブルの objectsColumns に保存されます（テーブルのスキルでは、 アクション列の追加と変更を扱います）。
• アクション実行は、1つの行に対する1つのアクション列の実行です。 試行が完了すると実行が保存されるため、ステータスは常に COMPLETED または FAILED です（API の列挙型には ACTIVE、DELAYED、WAITING もありますが、 これらのステータスで実行が保存されることはありません）。実行履歴は14日間保存されます。

RevOS MCP サーバーの汎用ツールを使ってアクセスします。

呼び出し	処理内容
api_read { "resource": "actions", "params": { "fields": "id,name,integrationName" } }	カタログです。テーブルで使われているアクションを取得するには "onlyUsed": "true" を追加します
api_read { "resource": "actions", "id": "<action id>" }	1つのアクションです。name、description、integrationName が含まれます
api_read { "resource": "actions", "id": "<action id>", "method": "errorInstructions" }	そのアクションのエラーについて組織が記載した内容です
api_read { "resource": "action-runs", "params": { … } }	実行履歴の一覧です。filter、orderBy、fields、pageSize を指定できます
api_read { "resource": "action-runs", "id": "<run id>" }	1つの実行です。input と result が含まれます
api_write { "resource": "action-runs", "data": { "tableId": "…", "columnId": "…" } }	アクション列を実行します。最初に references/run.md を参照してください

このスキルに記載されている呼び出しは、そのまま使えます。直接実行してください。 api_search と api_details は、呼び出しが拒否された場合や、このスキルに記載のない フィルターまたはフィールドが必要な場合に使います。

失敗が発生した場合：実行履歴から確認する

ここでの質問のほとんどは「なぜ失敗したのか」です。段階的に調べ、質問に答えが見つかった時点で止めてください。実行結果に失敗の原因がすでに示されているなら、テーブルのスキーマを調べる必要はありません。必要のない情報まで取得すると、ユーザーが求めていない詳細に埋もれ、回答が遅くなります。

**実行履歴を見つけます。**ユーザーが UI のアクション実行履歴ドロワーから取得した実行 ID を直接渡してくることもあります。より多いのは、レコードを指定するケースです。「deal 31415926535」、会社、連絡先などです。その ID は行の objectId です。通常、行にはソースシステム上のレコードと同じ ID が付いています。これは一意ではありません。同じレコードが複数のテーブルの行になることがあり、また、1つの行にはアクションごとにアクション列（NetSuite への同期と HubSpot への書き戻しなど）があり、それぞれに独自の実行履歴があります。そこで、まずレコードの最新の実行履歴を、ペイロードを含めずに一覧表示します（1つの実行の input と result は数千トークンになることがあります）。

api_read { "resource": "action-runs",
           "params": { "filter": "objectId == \"<record id>\"",
                       "orderBy": "createdAt desc", "pageSize": 5,
                       "fields": "id,actionId,columnId,modelId,objectName,status,createdAt" } }

テーブルがわかっている場合は、フィルターに && modelId == "<table id>" を追加します。 次に、質問の対象となるアクション列（modelId、columnId）の最新の実行を選び、 その実行を ID で読み込みます。ステータスが COMPLETED なら、そのレコードではもう 失敗していません。その旨を伝えてください。複数のテーブルやアクション列にまたがる 実行があり、依頼で対象が指定されていない場合（「NetSuite への」など）は、対象を列挙して どれか尋ねてください。

実行 ID もレコードもない場合は、ペイロードを含めずに失敗を一覧表示します。

api_read { "resource": "action-runs",
           "params": { "filter": "status == \"FAILED\" && modelId == \"<table id>\"",
                       "orderBy": "createdAt desc", "pageSize": 10,
                       "fields": "id,actionId,columnId,modelId,objectId,objectName,status,attemptsMade,createdAt" } }

modelId はテーブルの ID です。わかっている場合は columnId または objectId で絞り込みます。

**実行履歴を ID で読み込みます。**1回の呼び出しで、識別情報と両方のペイロードを取得できます。 actionId、columnId、modelId、objectId、objectName、status、attemptsMade、 input、result が含まれます。

実行履歴の actionId に対応する組織のエラー手順を読み込みます。 エラーがすでに明らかに見える場合でも、実行履歴を読んだ後は毎回、次にこの呼び出しを行います。 その ID を指定して actions に対する api_read を実行し、method: "errorInstructions" を 指定します。詳しくは以下を参照してください。 エラーメッセージから原因と修正方法を直接特定し、誰が修正するかも示されていることがよくあります。 エラーがどこにあるか。 エラー専用の列はありません。result には実行結果全体が格納されており、metadata.success を判別子とする ユニオン型です。失敗時には、次の情報が含まれます。

• metadata.error.message — 信頼して引用すべきメッセージです。単なる HTTP ステータス行（「Request failed with status code 400」）の場合、 ベンダー独自のメッセージは error.details.response.data にあります。 こちらを引用してください。
• metadata.error.aiMessage — 失敗が保存されたときに自動生成された、 AI による言い換えです（有料プランで、1 日あたりの上限があります）。 テーブルのセルには ❌ <aiMessage> として表示されるため、ユーザーが セルからコピーしたエラーテキストは通常、システムのメッセージではなく この言い換えです。これをシステム独自のエラーとして提示しないでください。
• error — message、code、details、isUnrecoverable、 retryAfter を含む正規化されたオブジェクトです。

error.isUnrecoverable: true は、フレームワークが再試行を停止したことを 意味します。対象となるのは、429 以外の HTTP 4xx、検証に失敗した入力、 または再試行不可を示したアクションです。変更せずに再実行しても同じように 失敗します。原因を修正すれば、成功する可能性があります。

失敗の多くは、ここにある情報だけで完全に説明できます。対象システムに 拒否された認証情報、権限、フィールド名と理由がすでに示された検証 メッセージなどです。組織の指示と合わせて result を読めば、ユーザーが 実行できることがわかる場合、それが答えです。その内容を引用し、 何をすべきかを伝えて、そこで終わってください。

ID から解決できない場合。 ID を指定した api_read は 404 ではなく data: null を返します。（ID は実行の jobId の場合もあります。 セルの metadata.jobId に含まれており、どちらでも解決できます。） 実行の背後にあるデータが削除された後も、テーブルのセルには失敗が 表示され続けます。そのため、ID が 14 日間の対象期間より古い実行を 指している場合があります。その旨を伝えて、そこで終わってください。 action-runs のページをどれだけ見ても、その実行は見つかりません。 ユーザーがエラーテキストを引用している場合は、そのテキストを改めて 読み返して伝える価値があります。その後、可能な対応を提案してください。 アクションを再実行して、新しい失敗を診断します。

実行結果だけでは答えられない場合 — エラーが欠落、空、または形式が 不正な値に関するものか、値の取得元をユーザーが尋ねている場合は、 references/debug.md に進んでください。マッピング、 系譜、問題の箇所の伝え方について説明されています。

組織のエラーに関する指示

組織は、アクションのエラーの意味と修正方法を記録しています。たとえば、 特定の NetSuite エラーがその組織にとって実際に何を意味するか、誰が何を 修正するか、CRM へのリンクをどう構築するかなどです。診断する失敗した 実行ごとに、実行の actionId を使って一度読み取ってください。

api_read { "resource": "actions", "id": "<the run's actionId>", "method": "errorInstructions" }

次の 3 つのテキストが返されます。何も記載されていない場合、各値は null です。

• global — この組織のすべてのアクションに適用されます。
• integration — このアクションのインテグレーションに属するすべての アクションに適用されます。
• action — このアクションだけに適用されます。

これらは互いに上書きするのではなく、積み重なります。アクションレベルの テキストを読む際は、インテグレーションレベルのテキストを読んでいる ことが前提です。

ここには、一見正しそうな推奨が誤りになるような規約が記されていることが あります。表現、リンク形式、または修正担当者が指定されている場合は、 その指示に従ってください。3 つすべてが null の場合、組織はこの アクションについて何も記載していません。指示なしで続行してください。 読み取りを拒否された場合は、再試行せず、実行結果に基づいて続行し、 指示を読み取れなかったことを伝えてください。

アクションの実行

実行すると接続先のシステムに作用し、顧客の CRM または ERP のレコードを 作成・更新します。そのため、ユーザーが依頼した場合にのみ実行し、 action-runs に対する最初の api_write を行う前に references/run.md を読んでください。

同期

「同期」には 2 つの意味があります。取り込みは、接続がソース システムから RevOS にデータを取り込むことです（「HubSpot を同期する」）。 有効化は、アクションが行を外部に送信することです（「この商談を NetSuite に同期する」）。取り込みには connections スキルを使います。 ID またはリンクを指定して今すぐ 1 件のレコードを同期する場合は、まず そのレコードを対応するキューブで確認してください。RevOS にそのレコードが ない場合、またはユーザーがそこで変更したばかりの場合に限り、ソースから 取り込んでから、その 1 行に対してアクションを実行します。詳細は references/sync-now.md を読んでください。

アクション列の追加または変更

これはアクションではなく、テーブルの変更です。テーブルスキルの列リファレンスを参照してください。このカタログでは、使用する actionId と、アクションの description を通じて必要な入力を確認できます。

報告する

まずユーザーの言葉で原因を伝え、次に対処方法と担当者を説明してください。修正にサードパーティが関わる場合は、metadata.error.message をそのまま引用してください。ベンダーのエラーを言い換えると、ユーザーがベンダーのサポートに問い合わせる際に役に立たないどころか、かえって妨げになります。行は ID ではなく objectName で示してください。input や result をそのまま出力しないでください。