一般的な問題と解決策
ワークフローがトリガーされない
症状: 期待したタイミングでワークフローが実行されない。
考えられる原因:
- ワークフローが有効化されていない: ワークフローが “Draft” ではなく “Active” に設定されていることを確認する
- トリガー条件が満たされていない: トリガーが想定するイベントに一致しているか確認する
- フィールドが監視対象ではない: “Record is Updated” トリガーの場合、対象のフィールドが監視されていることを確認する
- 権限: ワークフローを実行する権限があるか確認する
解決策:
- ワークフロー一覧でワークフローのステータスを確認する
- 想定するアクションで実際にトリガーされるかテストする
- トリガー設定を見直す
- 権限について管理者に連絡する
ワークフローが早すぎるタイミングでトリガーされる（フィールドが空）
症状: UI でレコードを手動作成すると、すべてのフィールドを入力する前にワークフローがトリガーされる。 フィールド値がほぼ空の状態でワークフローが実行されてしまう。
原因: Twenty はすべてをリアルタイムで保存します — つまり、“edit” と “read” の別モードはありません。 レコードを作成すると即時に保存され、追加のフィールドを入力する前に “Record is created” イベントがトリガーされます。
“Record is created” が有効に機能するケース:
- API 呼び出しで作成されたレコード（1 回のリクエストでフィールドが入力される）
- インポートで作成されたレコード
- 他のワークフローからの自動レコード作成
解決策: UI で手動作成したレコードには、トリガーとして “Record is created or updated” を使用する。 このようにすることで:
- ユーザーが入力を完了しフィールドを保存した後にワークフローがトリガーされる
- 空の値ではなく完全なデータを取得できる
ワークフローをレコードごとに 1 回だけ実行したい場合は、createdAt equals updatedAt（初回保存）などのフィールドを確認するために Filter アクションを追加するか、ワークフローがすでに実行されたかを追跡するカスタムのチェックボックスフィールドを使用する。
アクションの失敗
症状: ワークフローは実行されるが、一部のアクションが失敗する。
考えられる原因:
- データ不足: 必須フィールドが空である
- 無効な参照: 以前のステップの変数が存在しない
- API エラー: 外部サービスがエラーを返している
- 権限の問題: アクションの実行に必要な権限が不足している
解決策:
- ワークフローの実行詳細でエラーメッセージを確認する
- すべての必須フィールドに値が入っていることを確認する
- API 接続を個別にテストする
- ロール権限を見直す
HTTP リクエストのエラー
症状: HTTP Request アクションが失敗する、または想定外の結果を返す。
一般的なエラーコード:
- 400: 不正なリクエスト - リクエストボディの形式を確認する
- 401: 認証エラー - API キーを確認する
- 403: アクセス拒否 - API の権限を確認する
- 404: 見つかりません - エンドポイントURLを確認する
- 429: リクエスト過多 - レート制限を実装する
- 500: サーバーエラー - 外部サービス側の問題
解決策:
- APIエンドポイントURLを確認する
- 認証ヘッダーを確認する
- まず Twenty の外で API 呼び出しをテストする
- Code アクションでエラーハンドリングを追加する
Code アクションのエラー
症状: JavaScript コードが実行に失敗する。
一般的な問題:
- 構文エラー: タイプミスまたは無効な JavaScript
- 未定義の変数: 存在しない変数を参照している
- 型エラー: 不適切なデータ型に対する操作
- タイムアウト: コードの実行に時間がかかりすぎている
解決策:
- 組み込みのコードエディタの検証機能を使用する
- まず JavaScript コンソールでコードロジックをテストする
- デバッグのために console.log を追加する
- 複雑な処理を簡素化する
メールが送信されない
症状: Send Email アクションでメールが配信されない。
考えられる原因:
- メールアカウントが未接続: Settings → Accounts を確認する
- 無効なメールアドレス: 受信者のメールアドレスの形式が正しくない
- 送信制限: メールプロバイダのレート制限に達している
- スパムフィルター: メールがブロックされている
解決策:
- メールアカウントの接続を確認する
- 受信者のメールアドレスを検証する
- メールプロバイダの制限を確認する
- スパム判定される可能性があるメール内容を見直す
ワークフローのデバッグ
ワークフロー実行の活用
- ワークフローエディタに移動する
- Runs パネルを開く
- 失敗した実行を探す
- クリックしてステップごとの詳細を表示する
- エラーメッセージと出力データを確認する
個別ステップのテスト
- Code アクションでは Test ボタンを使用する
- HTTP リクエストでは、エンドポイントを個別にテストする
- ワークフローをトリガーするテスト用レコードを作成する
- 制御されたテストには手動トリガーを使用する
一般的なデバッグパターン
ロギングを追加:
デバッグのために中間値をログ出力する Code アクションを使用する。
ステップを分離:
失敗箇所を特定するため、各ステップを個別にテストする。
データフローを確認:
各ステップが期待どおりの入力データを受け取っていることを確認する。
問題を避けるためのベストプラクティス
有効化前
- ドラフトモードで十分にテストする
- すべての API 接続を検証する
- トリガー条件を丁寧に見直す
- 想定される動作を文書化する
開発中
- 説明的なステップ名を使用する
- Code アクションにコメントを追加する
- 実データに近いデータでテストする
- エッジケースを想定して計画する
有効化後
- 初期の実行を綿密に監視する
- 失敗時のアラートを設定する
- 実行履歴を定期的に見直す
- 可能な限りワークフローをシンプルに保つ
