カスタムパラメーター

最終更新: 2026.11.16

カスタムパラメーター

カスタムパラメーターは、ジョブごとに任意の変数や定数を定義し、データフロー内の各種プロセッサー(計算式、抽出条件、フィールド代入、出力先名など)で動的に参照・利用できる機能です。

集計期間(開始日・終了日)や税率、実行ユーザーが手動入力するフラグなど、外部から任意の条件値を注入してデータフローの処理を柔軟に制御できます。

主な特徴とユースケース

  • ジョブ単位で共通利用: パラメーターはジョブ単位で管理され、そのジョブに含まれるすべてのデータフロー内のプロセッサーから共通で参照できます。
  • 実行時ダイアログによる動的指定(手動実行):
    • 集計期間の動的指定: 一覧画面や詳細画面の実行ボタンを押下した際、「集計開始日(例:2026-04-01)」と「集計終了日(例:2026-04-30)」を日付ピッカーで入力し、指定した期間の売上レコードのみを絞り込んで集計・出力できます。
    • 処理区分や更新理由の入力: 「一括更新の理由」や「対象区分」を実行時に入力させ、レコードの更新内容や通知テキストに反映できます。
  • 共通定数としての利用(事前固定値設定): 消費税率(0.10)や手数料率、通知先メールアドレスなどを固定値として定義し、ジョブ内の全フローで共通参照できます。値の変更時はジョブ設定の1箇所を変更するだけで済みます。
  • 出力先アプリ名・ファイル名の動的生成: アプリ出力の新規アプリ名やファイル出力のファイル名にパラメーター値を埋め込み、日付や条件ごとに異なる名前で自動生成できます(例:売上集計_{%#$集計開始日$#/YYYYMMDD%}_{%#$集計終了日$#/YYYYMMDD%}、月次レポート_{{#$対象年月$#}})。

2つの設定方法(固定値と実行時入力)

カスタムパラメーターには、値の設定方法(入力モード)として「固定値(事前に設定)」と「実行時入力(実行ボタン押下時に入力)」の2種類があります。

設定方法 概要 主な用途・例
固定値(事前に設定) プラグイン設定画面であらかじめ固定の値を指定します。実行契機を問わず、常に指定した固定値が適用されます。 消費税率(0.10)、手数料率、共通メールアドレスなど、フロー全体で共有する定数。
実行時入力(実行ボタン押下時に入力) レコード一覧画面や詳細画面の実行ボタンを押下した際に、パラメーター入力ダイアログを表示してユーザーに入力させます。初期値(デフォルト値)や入力必須の設定が可能です。 集計期間(開始日・終了日)、対象年月(文字列(1行)型で指定)、一括処理理由、対象ステータスなど、実行ごとに変更したい条件値。

実行契機(トリガー)による値の決定ルール

同一のジョブに「実行ボタン(手動実行)」と「レコード保存時などの自動実行イベント」を同時に設定している場合、値は以下のように解決されます。

実行契機 固定値(事前設定) 実行時入力(実行時入力)
ボタン契機(手動実行)
(一覧画面、詳細画面の実行ボタン)
設定画面で指定された固定値を使用 入力ダイアログを表示。
ユーザーが入力・確定した値を使用(初期値にデフォルト値を表示)。
自動実行契機
(レコード追加/編集保存後、プロセス管理進行等)
設定画面で指定された固定値を使用 ダイアログは表示せず、設定されたデフォルト値を自動適用。


自動実行時にダイアログが表示されない理由
レコード保存などの自動実行イベントでは、すでにレコードの保存処理が完了しているため、入力ダイアログを表示してキャンセルされた場合にデータの不整合が発生します。そのため、自動実行時はダイアログを挟まず、事前設定されたデフォルト値を適用してバックグラウンドで安全に処理を完了させます。

これに伴い、自動実行トリガーを含むジョブで「入力を必須にする」を有効にした場合は、デフォルト値の設定が必須となります。

サポートするデータ型

kintoneのフィールド型に準拠した以下のデータ型をサポートしています。

タイプ 説明 選択肢の設定 計算式での利用
文字列(1行) 1行のテキスト 不要 ○
文字列(複数行) 複数行のテキスト 不要 ○
数値 数値(半角数値) 不要 ○
日付 日付(カレンダーピッカー、YYYY-MM-DD 形式) 不要 ○
時刻 時刻(タイムピッカー、HH:mm 形式) 不要 ○
日時 日時(日時ピッカー) 不要 ○
ドロップダウン 単一選択のドロップダウンリスト 必須 ○
ラジオボタン 単一選択のラジオボタン 必須 ○
チェックボックス 複数選択チェックボックス 必須 ○
複数選択 複数選択リスト 必須 ○
ユーザー選択 kintoneのユーザーから選択(複数選択可) 不要 ×
組織選択 kintoneの組織から選択(複数選択可) 不要 ×
グループ選択 kintoneのグループから選択(複数選択可) 不要 ×

  • ユーザー選択、組織選択、グループ選択は、計算式内での参照には対応していません(絞り込み条件や固定値代入、出力名のテンプレート置換などでは利用可能です)。

パラメーターの書式(コード)

カスタムパラメーターをデータフロー内で参照する際は、以下の書式を使用します。

  • 書式: #$パラメーターコード$#
    • 例:#$消費税率$#、#$対象年月$#、#$部署コード$#

コードの自動生成

パラメーターコードは、設定画面で「パラメーター名」を入力すると、kintoneのフィールドコード生成規則に準拠して自動生成されます。コードを手動で変更することはできません。

他のパラメーターとの記法の違い

データフローで利用できるパラメーターは、デリミタ(囲み記号)によって明確に区別されます。

  • #$カスタムパラメーターコード$#: カスタムパラメーター
  • #フィールドコード#: レコードフィールドパラメーター(トリガーとなったレコードのフィールド値)
  • #@基本パラメーター名@#: 基本パラメーター(システム変数:#@JobName@#、#@FlowName@#、#@ExecutedUser@# など)

カスタムパラメーターを利用できる設定

カスタムパラメーターは、データフロー内の各種プロセッサーで幅広く利用できます。

1. 計算式(数式)

データ変換やレコード抽出などの計算式設定で、変数として直接指定できます。

  • 数値計算の例:
    [単価] * [数量] * (1 + #$消費税率$#)
    
  • 文字列結合の例:
    CONCATENATE("集計期間:", #$集計開始日$#, " 〜 ", #$集計終了日$#)
    
  • 日付の年月変換と照合の例:
    IF(TEXT([売上日], "YYYY-MM") = #$対象年月$#, [金額], 0)
    
  • 条件判定の例:
    IF(#$処理区分$# = "会員", [金額] * 0.9, [金額])
    

  • 文字列リテラル内の扱い: ダブルクォートで囲まれた文字列リテラルの中(例:"#$消費税率$#")に記述した場合は、パラメーター展開されずそのままの文字列として扱われます。パラメーター値と文字列を結合したい場合は、& 演算子または CONCATENATE 関数を使用してください。
  • 空値の四則演算: 未設定(空)の数値型パラメーターは、四則演算において自動的に 0 として計算されます。
  • 空白判定: ISBLANK(#$コード$#) 関数を使用することで、パラメーター値が未入力(空)かどうかを安全に判定できます。

2. 検索・絞り込み条件

アプリ入力の標準絞り込み設定や、レコード抽出の絞り込み設定において、条件値としてカスタムパラメーターを選択・指定できます。

  • 単一値演算子(=、!=、>、>=、<、<= など):
    パラメーターの値を条件値として絞り込みます。
    • 期間指定の例: 日付 >= #$集計開始日$# かつ 日付 <= #$集計終了日$# と指定することで、実行時に入力した期間内のレコードのみを動的に絞り込めます。
    • 年月照合の例: 前段のデータ変換で日付から年月文字列を生成したフィールドに対して、年月 = #$対象年月$# と指定して該当月のレコードのみを抽出できます。
  • 複数値演算子(in、not in):
    チェックボックスや複数選択型のパラメーターを指定できます。
  • 関数引数(FROM_TODAY など):
    日数指定などの引数に数値型パラメーターを指定できます。


複数値条件(in / not in)の空値エラーについて
in や not in 条件に指定したパラメーターの値が空(選択肢が1つも選択されていない状態)の場合、条件が無視されて意図しない全件取得や全件更新が発生することを防ぐため、フローの開始時にエラーとして検知され、処理が安全に中断されます。

3. レコードのフィールド代入・追加

データ変換の「固定値」設定で、カスタムパラメーターの値をそのままレコードのフィールド値として代入・追加できます。

4. 新規アプリ名・出力ファイル名(テンプレート)

アプリ出力の新規作成アプリ名や、ファイル出力の出力ファイル名において、テンプレート記法を用いてパラメーター値を動的に埋め込むことができます。

  • 値の埋め込み({{...}}):
    • {{#$パラメーターコード$#}}
    • 例:売上データ_{{#$対象年月$#}}
    • 複数選択型の場合は、各選択値がアンダースコア(_)で連結されて展開されます。
  • 日時フォーマット指定({%.../フォーマット%}):
    • {%#$パラメーターコード$#/フォーマット%}
    • 日付(DATE)、日時(DATETIME)、時刻(TIME)型のパラメーター値を、指定したフォーマットに変換して埋め込めます。
    • 例:売上集計_{%#$集計開始日$#/YYYYMMDD%}_{%#$集計終了日$#/YYYYMMDD%}、月次レポート_{%#$集計開始日$#/YYYY-MM%}


出力ファイル名にスラッシュ(/)などのOS禁止文字(\ / : * ? " < > |)が含まれていた場合、ファイル保存時に自動的にアンダースコア(_)へ置換(サニタイズ)されて安全に出力されます。

設定手順

1. パラメーターを定義する

  1. プラグイン設定画面で「ジョブ追加」または対象のジョブの「ジョブ編集」をクリックし、ジョブ設定ダイアログを開きます。
  2. 「カスタムパラメーター」タブを選択します。

カスタムパラメーター設定

  1. 「+ パラメーターを追加」をクリックします。

パラメーター編集(static)
パラメーター編集(runtime)

  1. パラメーター編集画面で以下の項目を設定します。
設定項目 説明
パラメーター名 パラメーターの表示名を入力します(必須)。入力すると直下にパラメーターコード(#$コード$#)が自動生成されます。
タイプ データ型をドロップダウンから選択します(必須)。
説明文 実行時ダイアログなどに表示する入力ヒントや説明文を入力します(任意)。
選択肢 タイプがドロップダウン、ラジオボタン、チェックボックス、複数選択の場合に設定します。ドラッグ&ドロップで選択肢の並べ替えが可能です。
設定方法 「固定値(事前に設定)」または「実行時入力(実行ボタン押下時に入力)」を選択します。
固定値
(固定値選択時)
プラグイン設定画面であらかじめ保持する固定値を入力・選択します(任意)。
入力を必須にする
(実行時入力選択時)
実行時入力ダイアログでユーザーの入力を必須にする場合はチェックを入れます。
デフォルト値
(実行時入力選択時)
実行時入力ダイアログに初期表示する値を設定します(任意)。※自動実行トリガーを含むジョブで入力を必須にした場合は設定必須となります。
  1. 「保存」をクリックしてパラメーターを登録します。

2. 表示順(入力順)の並べ替え

カスタムパラメーター一覧の左端にあるドラッグハンドルアイコンをドラッグ&ドロップすることで、パラメーターの並び順を変更できます。

この並び順は、手動実行時のパラメーター入力ダイアログにおける項目の並び順や、プレビュー設定画面での表示順に反映されます。

プレビューでの確認方法

データフロー編集画面の「プレビュー」機能では、カスタムパラメーターにテスト値を設定して各ノードの出力結果を確認できます。

  1. データフロー編集画面のツールバーにある「プレビュー設定(歯車アイコン)」をクリックします。
  2. 「カスタムパラメーター」欄に、ジョブに定義されたパラメーターが表示されます。
    • 固定値: ジョブ設定で設定された値が読み取り専用で表示されます。
    • 実行時入力: 設定されたデフォルト値が初期表示されます。テストしたい値を自由に入力・変更できます。
  3. 「設定」をクリックすると、入力したテスト値をもとにフロー全体のプレビュー計算が即座に再実行されます。


プレビュー設定画面で入力したテスト値は、画面上での一時的なプレビュー用データです。プラグイン設定(ジョブ設定)として保存されることはありません。

ジョブ実行時の動作

ボタン実行時(手動実行)

  1. レコード一覧画面または詳細画面のジョブ実行ボタンをクリックします。
  2. ジョブに「実行時入力」のカスタムパラメーターが定義されている場合、「実行時パラメーター入力」ダイアログが表示されます。
  3. 説明文や初期値を確認しながら値を入力し、「実行」をクリックします。
    • 入力を取り消したい場合は「キャンセル」をクリックすると、フローを実行せずに終了します。
    • 必須項目が未入力の場合や、型に合致しない値が入力されている場合はエラーが表示され、実行できません。
  4. バリデーションを通過すると、確定した値がフローに渡され、処理が開始されます。


すべてのパラメーターが「固定値」として定義されているジョブでは、入力ダイアログは表示されず、ボタン押下後すぐに処理が開始されます。

自動実行時(レコード保存・プロセス管理進行など)

レコード保存成功後やプロセス管理のアクション実行時などの自動実行契機では、入力ダイアログは表示されません。
ジョブ設定で設定された「デフォルト値」(固定値の場合は「設定値」)が自動的に適用されてバックグラウンドで処理が実行されます。

注意事項・制約事項

1. フローで参照中のパラメーターの保護

データフロー内のいずれかのノード(計算式、抽出条件、フィールド代入、出力名テンプレートなど)で参照されているカスタムパラメーターは、フローの意図しない破損を防ぐため、削除・パラメーター名(コード)の変更・タイプの変更ができません。

一覧の削除ボタンや編集モーダルの該当項目が非活性(グレーアウト)となり、参照しているフロー名やノード名が表示されます。削除や変更を行う場合は、先にデータフロー側の各ノードで該当パラメーターの参照を解除してください。

2. 自動実行トリガーを含むジョブでの必須デフォルト値

レコード追加・編集などの自動実行トリガーを含むジョブにおいて、「実行時入力」かつ「入力を必須にする」を設定したパラメーターがある場合、自動実行時に値が未定義となって処理が失敗するのを防ぐため、デフォルト値の設定が必須となります。設定されていない状態ではジョブ設定を保存できません。

3. 別ジョブからのフローコピー時の整合性

「既存フローからコピー」機能で別のジョブからフローをコピーした場合、コピー元フローが参照しているカスタムパラメーターがコピー先のジョブに存在しない場合や、型が一致しない場合は、該当ノードがエラー表示となりジョブの実行がブロックされます。コピー先ジョブにも同名・同型のカスタムパラメーターを定義するか、ノードの設定を修正してください。