onBefore / onAfterは何が違う？Transform Mapの変換イベントスクリプトを実務目線で整理

onBefore / onAfterの違いは、要するに何か

Import Set と Transform Map を触り始めると、早い段階で出てくるのが 変換イベントスクリプトです。そこでよく見かけるのが onBefore と onAfter。名前は分かりやすいのに、実務では意外と迷います。

• 「値をちょっと加工したい。onBefore？ onAfter？」
• 「取り込み対象外にしたいから ignore = true。これって後続処理はどうなる？」
• 「onAfterで target.update() していいの？Business Ruleが暴れない？」

迷う理由はシンプルで、Transform Mapの中では“1行ずつ”処理が進み、しかも“保存の前後”でできることが変わるからです。

公式ドキュメントでは、タイミングを次のように説明しています。

• onBefore：ソース行がターゲット行に変換される前、行変換の開始時に処理
• onAfter：ソース行がターゲット行に変換されて保存された後、行変換の最後に処理

つまり、ざっくり言うとこうです。

• onBefore＝検査・整形・判定（この行を入れるかどうか）
• onAfter＝結果を使った後処理（保存されたレコードを前提に動く）

ここから先は、暗記ではなく「なぜそう使い分けるのか」を、例を交えて整理します。

---

変換前にやるべきことがはっきりしている

onBeforeの役割は「取り込みの入口で、品質を守ること」

onBeforeは、各行の変換が始まった瞬間に動きます。公式ドキュメントでも「変換される前に、行変換の開始時」と明記されています。

このタイミングが強いのは、次の理由です。

• まだ保存されていないので、**“入れる前の判断”**ができる
• ソースの値を見て、整形・補完してから変換に渡せる
• 条件次第で、その行をスキップできる

onBeforeで使える代表的な変数

公式ドキュメントの表では、onBeforeで参照できるオブジェクトが整理されています。たとえば以下が重要です。

• source：現在処理中のソース行（GlideRecord）
• target：現在処理中のターゲット行（GlideRecord）
• action：この行が insert される予定か update される予定か
• ignore：trueにすると、その行の変換をスキップ
• log：ログ出力用（log.info() など）

特に action は地味に効きます。
「この行は更新なのか新規なのか」で処理を分けたいケースは多いです。たとえば「更新時だけ特定フィールドは触らない」といった設計ができます。

典型パターン1：必須チェックで行をスキップする

よくあるのが「会社名が空なら取り込まない」「社員番号が無いなら除外する」みたいな品質チェックです。

公式ドキュメントの例にも、会社名が空なら ignore = true にしてログを残すサンプルが載っています。

ここで大事なのは、エラー扱いにするのか、スキップ扱いにするのかを分けること。

• “その行だけダメ”なら ignore = true（他の行は続ける）
• “全体が成立しない”なら error = true（取り込み自体を止める）

この判断は実務でも試験でも、考え方として扱われやすいポイントです。丸暗記というより「運用に強い設計」につながります。

典型パターン2：入力値の整形を先に済ませる

CSVや外部システム由来の値って、そのまま入れると後で地味に困ります。

• 電話番号のハイフンを除去して統一したい
• “０”や空文字や “N/A” を null相当にしたい
• 部署コードを部署レコードにひもづける前に正規化したい

こういう「揃える」処理は、保存前にやる方が安全です。保存後に直すと、余計な更新が増えたり、Business Ruleを二重で動かしたり、監査ログが汚れたりします。

---

保存された事実を使って「後処理」をする

onAfterの役割は「保存済みレコードを前提にした処理」

onAfterは、公式ドキュメントに「変換されて保存された後、行変換の最後」と書かれています。

この “保存された後” がポイントです。onAfterが向いているのは、たとえば以下。

• 生成されたターゲットレコードの sys_id を使って別テーブルを更新したい
• インポート結果をログに残したい
• 「新規作成された時だけ」関連レコードを作りたい

onAfterで使える代表的な変数

onAfterでも source / target / action / log などが使えます。
onBeforeとの大きな違いは、「targetが保存された後」という前提で考えられることです。

典型パターン1：取り込み後の関連データ作成

たとえば、ユーザーを取り込んだ後に

• 初期ロールを付与する
• 関連するプロファイルレコードを作る
• 初期のタスクを起票する

こういう処理は、ターゲットが存在してから動かしたいので、onAfterが自然です。

典型パターン2：結果の集計や通知のトリガー

「取り込み終わったら通知」みたいな要件は多いですが、行ごとにメールを飛ばすのは事故のもとです。
onAfterは“行ごと”なので、通知そのものは onComplete やイベント設計に逃がし、onAfterは「必要な印を残す」に留める、という設計が現場では安定します。

---

ここを押さえると混乱が減る

ignore = true でも onAfter が動くことがある

これ、初心者が一番「えっ？」となるところです。
公式ドキュメントには onBeforeで ignore を true にしても、onAfterスクリプトを定義している場合はその行に対して onAfter が実行される と書かれています。

つまり、設計としてはこう考えるのが安全です。

• onAfterは「必ず実行されうる」前提で、条件ガードを書く
• 「ignoreされた行では何もしない」なら、onAfter側にも判定ロジックを入れる

さらに、サポート情報として「onBeforeで ignore を true にしても onAfter が走る」ことに触れたKBもあります。
この挙動を知らないままだと、スキップしたはずの行で後処理が走って、ログや関連データが増えて混乱します。

onAfterで target.update を安易にやると、二重処理になりやすい

「保存後に値を直したいから onAfter で update」—やりたくなる気持ちは分かります。
ただし、これをやると

• Business Ruleの after が動く
• 監査や履歴が増える
• 取り込みが遅くなる
• 期待しない再計算が走る

など、取り込み全体のふるまいが変わりやすいです。

実務では基本方針として、

• “変換で入れる値”は onBefore で決め切る
• onAfterは、どうしても必要な“関連処理”に限定する

こう置くと、トラブルが減ります。

Business Ruleとの役割分担で迷ったら

Transform MapスクリプトとBusiness Ruleは、どちらもサーバサイドで動くので混ざりやすいです。

• 取り込み固有の加工や判定 → Transform Map（onBefore/onAfter）
• 取り込み以外も含めた一貫ルール → Business RuleやFlow

この分け方にしておくと、「インポートの時だけ特殊」になりにくく、運用がラクになります。CSAの学習としても、**“どこで何を保証するか”**の整理は前提として扱われやすいです。

どっちに書くか迷った時の判断基準

最後に、現場で使える判断基準を置いておきます。

• 保存前に決められるなら onBefore
  • 値の整形、必須チェック、スキップ判定
• 保存済みでないとできないなら onAfter
  • sys_id前提の関連作成、結果に基づく後処理
• 行ごとではなく全体の完了が基準なら onComplete
  • まとめて通知、集計、インポート完了イベント

公式ドキュメントでも onStart / onComplete のタイミングと参照可能オブジェクトが整理されているので、流れを一度通して眺めると理解が速いです。

---

暗記せず理解でいく

覚えるのは用語ではなく「処理の流れ」

CSAを目指す人がここでやりがちなのが、
「onBefore＝前」「onAfter＝後」だけで終わること。

でも実際に大事なのは、次の1本線です。

• Import Setに行が入る
• Transform Mapが1行ずつ処理する
• 保存の前に onBefore
• 保存の後に onAfter
• 全体の最初に onStart、全体の最後に onComplete

この流れが腑に落ちると、Transform Mapだけでなく、Business RuleのBefore/After/Asyncや、Flow Designerとの使い分けも理解がつながっていきます。

手を動かすなら、このミニ練習が効く

学習環境があるなら、次の順で小さく試すのがオススメです。

• CSVで3行だけ用意する
  • 1行目：正常
  • 2行目：必須項目が空
  • 3行目：更新になるデータ
• onBeforeで log.info() を入れ、action をログに出す
• 2行目だけ ignore = true にして挙動を見る
• onAfterでもログを出して、ignore時にも走るか確認する

この「自分の目で見る」経験が、試験対策としても一番強いです。理解していないと混乱しやすいところなので、丸暗記より再現性が出ます。

体系的に学べる教材の一例としてUdemyを使う

Import SetやTransform Mapは、断片で読むと分かった気になるのに、実務で急に迷います。
そこで、実機操作の流れを最初から最後まで一気通貫で見せてくれる講座を1本持っておくと、理解が固まりやすいです。

Udemyには、ServiceNow管理・開発の基礎（Import Set、Transform Map、Business Rule、Flowなど）を通しで扱う講座がいくつかあります。あなたの学習フェーズなら「管理者向け基礎」から入って、必要に応じて「開発寄り」に進むのが自然です。
ブログ内では、過度に煽らず「体系的に学べる教材の一例」として紹介すると、読者にも親切です。

---

onBeforeは入口、onAfterは結果を使う場所

onBefore / onAfterの違いは、言葉だけなら単純です。でも本質は「保存の前後で、できることと責任が変わる」点にあります。

• onBeforeは、変換の入口で品質を守る。整形、チェック、スキップ判定が得意。
• onAfterは、保存済みレコードを前提に後処理をする。関連作成や結果活用が得意。
• ignoreの挙動など、知っていないと混乱しやすい仕様もあるので、ログを出して一度挙動確認すると理解が定着する。

この考え方で整理できると、Transform Mapだけでなく、Business RuleやFlow Designerの「どこで何をやるべきか」も判断しやすくなります。CSA学習としては、用語暗記よりも、この判断軸を自分の中に作るのが近道です。