【Box】Box Relayの条件分岐で困った時の監査ログで原因を確認する方法

Box Relayで条件分岐(Condition)を設定したものの、思ったとおりに処理が進まず困った経験はないでしょうか。たとえば「ファイルがアップロードされたら担当者に通知する」という条件が無視されたり、別のフォルダに振り分けられたりするケースです。このような問題を解決するには、Boxの監査ログ(Audit Log)が強力な手がかりになります。監査ログにはRelayの各ステップでどの条件が評価され、どの分岐が選択されたかが詳細に記録されるため、原因を特定しやすくなります。本記事では、Relayの条件分岐トラブルを監査ログで切り分ける具体的な方法を、実務に即した手順とともに解説します。

1. Box Relayの条件分岐がうまく動かない主な原因

条件分岐が期待どおりに動作しない原因は、大別して4つのパターンに分類できます。それぞれの特徴を理解することで、監査ログを確認する際の着眼点が明確になります。

原因カテゴリ	具体例	監査ログでの確認ポイント
条件式の誤り	大文字小文字の不一致、メタデータフィールド名の間違い	「Condition evaluated to false」や「Invalid condition expression」の記録
権限不足	Relayの実行ユーザーが条件で参照するフォルダやファイルを読めない	「Permission denied」または「Access denied」のエラーログ
タイミング問題	メタデータ更新前にRelayが起動してしまい、条件に合致しない	トリガー時刻と条件評価時刻のずれ、ファイルバージョンの確認
Relay設定のミス	条件分岐の順序やデフォルト分岐の設定ミス	「Branch selected」の記録が想定と異なる分岐を示している

条件式の誤りによる失敗パターン

最も多い失敗は、条件式で使用するメタデータフィールド名や値のスペルミスです。Box Relayの条件は大文字小文字を区別するため、「department」と「Department」は別物として扱われます。例えば「ファイルのメタデータフィールド「ステータス」が「完了」の場合」という条件を設定した場合、フィールド名が「ステータス」で正しいか、値が全角半角どちらかを確認する必要があります。監査ログでは「Condition: status == Completed」のような評価結果が記録されるため、実際に評価された文字列と想定を比較することで誤りを特定できます。

権限不足による失敗パターン

Relayは設定された実行ユーザー(多くの場合はRelay作成者または指定のサービスアカウント)の権限で動作します。そのユーザーが条件で参照するファイルやフォルダに対する読み取り権限を持っていない場合、条件評価がスキップされたりエラーになります。監査ログには「error: insufficient permissions」や「access denied」が記録されるため、権限設定の見直しが必要です。特に、Relayが企業全体で共有されている場合は、実行ユーザーを適切に設定しなければなりません。

タイミング問題による失敗パターン

ファイルがアップロードされた直後にRelayが起動する場合、メタデータがまだ更新されていない可能性があります。たとえば「ファイルのメタデータフィールド「承認」が「Yes」の場合に通知」という条件を設定しても、アップロード後にメタデータ編集が行われるまでのタイムラグがあると、条件が常にfalseになってしまいます。監査ログでトリガーイベントと条件評価のタイムスタンプを比較し、適切な順序で処理されているかを確認します。必要に応じて、メタデータ更新をトリガーとする別のRelayを配置するなどの対策が有効です。

2. 監査ログを活用した原因特定の具体的な手順

では実際に監査ログを使って原因を特定していきましょう。以下の手順はBox管理コンソール(管理者専用)で行います。一般ユーザーの方は管理者に依頼してください。

1. Box管理コンソールにログイン – 「管理コンソール」→「監査ログ」に移動します。左側のメニューから「監査ログ」を選択してください。
2. エクスポート範囲とフィルターを設定 – 「エクスポート」タブを開き、問題が発生した日時を範囲指定します。さらに「アクションタイプ」フィルターで「RELAY」または「RELAY_CONDITION_EVALUATION」を含むように絞り込みます。必要に応じてユーザーやフォルダIDでもフィルター可能です。
3. CSVファイルをダウンロード – 「エクスポートの作成」をクリックし、生成されたCSVファイルをダウンロードします。ダウンロードには数分かかる場合があります。
4. CSVを開いて対象行を探す – エクスポートされたCSVをExcelやGoogleスプレッドシートで開きます。「Event Type」列で「RELAY_CONDITION_EVALUATION」(条件評価)や「RELAY_BRANCH_SELECTED」(分岐選択)を探します。
5. 詳細情報を確認 – 各ログの「Details」列にはJSON形式で条件式や評価結果が記録されています。たとえば「condition_expression: “folder.name == ‘請求書'”」と「result: false」のように書かれているため、どの条件がどのように評価されたかがわかります。想定と異なる結果が出ていれば、条件式を見直します。
6. 権限エラーの有無を確認 – 同じCSVの「Event Type」が「RELAY_ERROR」や「ACCESS_DENIED」の行がないか確認します。あれば権限設定や実行ユーザーの確認が必要です。

3. 監査ログでよく遭遇する失敗パターンとその読み解き方

実際の監査ログでは、以下のような具体的なエントリが記録されます。それぞれの読み方と対処法を紹介します。

パターン1: Condition evaluated to false(条件評価がfalse)

Details例: { "condition_expression": "file.extension == '.pdf'", "result": false, "file_path": "/共有/資料.docx" }。この場合、ファイル拡張子が.docxであり条件に合わないためfalseになっています。意図が違うなら条件式の修正(たとえば.docxも含める)が必要です。

パターン2: Invalid condition expression(条件式が無効)

Details例: { "error": "Invalid condition: unknown field 'staus'" }。これはフィールド名のスペルミスです。「staus」を「status」に修正します。監査ログのエラーメッセージが直接原因を指し示すため、すぐに訂正できます。

パターン3: Permission denied(権限拒否)

Details例: { "error": "Access denied; user 'relay-bot@company.com' cannot read folder '12345'" }。この場合、Relayの実行ユーザーであるrelay-botに該当フォルダの読み取り権限がないことがわかります。Box管理コンソールでフォルダの共有設定を確認し、適切な権限を付与します。

パターン4: Branch selected(選択された分岐)が想定と異なる

Details例: { "branch_id": "branch_02", "condition_evaluated": "file.size > 1000000", "result": true }。ファイルサイズが1MBを超えたためbranch_02が選ばれています。もしbranch_01を期待していたなら、条件式の不等号の向きや閾値を見直します。

4. 管理者へ依頼する際に伝えるべき情報

一般ユーザーが監査ログを直接見られない場合は、管理者に調査を依頼します。その際、以下の情報を具体的に伝えることで、効率的に原因を特定できます。

• 問題のRelay名とID – Relayの設定画面から名前とID(URL末尾の番号)をメモします。
• 発生した日時(タイムゾーン付き) – 問題が再現した正確な時間を伝えます。複数回ある場合はすべて列挙します。
• 期待した動作と実際の動作 – たとえば「ファイルがフォルダAにアップロードされたら、条件Xを満たす場合はフォルダBに移動し、満たさない場合はフォルダCに移動するはずが、すべてフォルダCに移動した」のように記述します。
• 関係するファイルやフォルダのパス – 対象ファイル名や親フォルダのパスを添えます。
• 条件式のスクリーンショット – Relay編集画面で設定している条件式のキャプチャを添付すると、管理者が再現しやすくなります。

5. よくある質問(FAQ)

Q1: 監査ログにRelayの条件評価ログが表示されません。なぜですか?

A: 監査ログのエクスポート範囲が正しくない可能性があります。Relayが実行された日時を正確に指定し、アクションタイプフィルターで「RELAY」を選択してください。また、Boxのエディションによっては監査ログの保持期間が異なるため、30日以上前のログは参照できない場合があります。

Q2: 条件評価はすべてtrueになるのに、なぜか意図しない分岐に進みます。

A: 条件分岐の評価順序やデフォルト分岐の設定を確認してください。Relayの条件は上から順に評価され、最初に一致した分岐が選択されます。すべてtrueになる条件がある場合、その条件が常に最初にマッチしていないか、あるいはデフォルト分岐が優先されていないかをチェックします。監査ログの「Branch selected」イベントで、どの分岐が選択されたかが記録されるため、それを基に順序を調整します。

Q3: 権限エラーが表示されるが、実行ユーザーはフォルダにアクセスできるはずです。

A: 実行ユーザーがRelayの設定画面で指定されているユーザーであることを確認してください。Relayは作成者の権限で動作する場合と、設定で別のユーザーを指定できる場合があります。また、フォルダの共有設定が親フォルダから継承されていない可能性もあるため、直接権限を付与してみます。

6. まとめ

Box Relayの条件分岐がうまくいかないときは、まず監査ログを取得して原因を切り分けましょう。監査ログには条件式の評価結果やエラー詳細が記録されているため、コードを書かずに問題の本質を把握できます。原因特定後は、条件式の修正、権限設定の見直し、トリガータイミングの調整など適切な対処を行ってください。もし自力で解決できない場合は、本記事で紹介した依頼情報をまとめて管理者に連絡するとスムーズです。監査ログを積極的に活用することで、Relayトラブルの解決時間を大幅に短縮できるはずです。