スクリプティング概要

概要

Fess では、様々な場面でスクリプトを使用してカスタムロジックを実装できます。 スクリプトを活用することで、クロール時のデータ加工、URLの変換、 スケジュールジョブの実行などを柔軟に制御できます。

対応スクリプト言語

Fess は以下のスクリプト言語をサポートしています:

言語 識別子 説明
Groovy groovy 標準で登録されているスクリプト言語。Java互換で強力な機能を提供

注釈

Fess に標準で登録されているスクリプトエンジンはGroovyのみです。 デフォルトのスクリプト言語は groovy です（ Constants.DEFAULT_SCRIPT ）。 本ドキュメントのスクリプト例はすべてGroovy構文で記述しています。

スクリプトの使用場面

データストア設定

データストアコネクタでは、取得したデータをインデックスフィールドにマッピングするために スクリプトを使用します。設定は フィールド名=式 の形式で1行ごとに記述し、 各行はそれぞれ独立した1つのGroovy式として評価されます。

url=site_url
title=name
content=description
last_modified=updated_at

データストアスクリプトで参照できる変数名は、コネクタの種類によって異なります。 たとえばCSVデータストアやJSONデータストアでは、各カラム名・フィールド名が そのまま変数として利用できます（ data のような共通の接頭辞は付きません）。 ファイル系コネクタ（Box、Google Drive、OneDrive など）では file.* 、 Slackでは message.* など、コネクタごとに接頭辞が異なります。 利用できる変数の詳細は、各データストアコネクタのドキュメントを参照してください。

注釈

データストアの各行は1つの式として評価されるため、複数行にまたがる if ブロックや import 文、 def による変数宣言は使用できません。 条件によって値を変える場合は、フィールドごとに三項演算子を使用してください （例: title=enabled == "true" ? name : null ）。クラスを参照する場合は 完全修飾名（FQCN）をインラインで記述します。

パスマッピング

パスマッピングは、クロール対象のURLを正規化・変換するための機能です。 標準では「正規表現」と「置換文字列」のペアで設定し、Groovyスクリプトではありません。 たとえば、正規表現に http:// 、置換文字列に https:// を指定すると、 URLのスキームを置き換えられます。

置換文字列の先頭に groovy: を付けた場合に限り、以降の文字列がGroovyスクリプトとして 評価されます。このスクリプト内では、変換対象のURL文字列を表す url と、 正規表現の java.util.regex.Matcher を表す matcher が利用できます。

groovy:url.replaceAll("http://", "https://")

スケジュールジョブ

スケジュールジョブでは、カスタムの処理ロジックをGroovyスクリプトで記述できます。 スクリプトはスクリプト全体が1つのGroovyスクリプトとして評価されるため、 複数行の記述や import 文、 def による変数宣言も使用できます。

return container.getComponent("crawlJob").logLevel("info").gcLogging().execute(executor);

logLevel("info") などのメソッドはジョブクラス（ ExecJob とそのサブクラス）の メソッドで、メソッドチェーンで記述できます。 executor 変数については 「実行コンテキストと利用可能なオブジェクト」を参照してください。

基本的な構文

以下はGroovyの基本的な構文例です。コメントは // （行コメント）または /* */ （ブロックコメント）を使用します。 # で始まるコメントはGroovyでは 使用できない点に注意してください。

変数アクセス

// データストアのフィールド（CSV/JSONではカラム名・フィールド名でアクセス）
title

// DIコンテナからコンポーネントを取得
container.getComponent("systemHelper")

文字列操作

// 連結
title + " - " + category

// 置換
content.replaceAll("old", "new")

// 分割
tags.split(",")

条件分岐

// 三項演算子
status == "active" ? "有効" : "無効"

// null/空の場合のデフォルト値（Elvis演算子）
description ?: "説明なし"

日付操作

// 現在日時
new Date()

// フォーマット
new java.text.SimpleDateFormat("yyyy-MM-dd").format(updated_at)

実行コンテキストと利用可能なオブジェクト

スクリプト内で使用できるオブジェクトは、スクリプトを実行するコンテキストによって 異なります。 container のみがすべてのコンテキストで利用可能です。

実行コンテキスト 利用可能なオブジェクト 説明
すべてのコンテキスト container

DIコンテナ。 container.getComponent("systemHelper") や container.getComponent("fessConfig") で各コンポーネントにアクセス可能
データストアスクリプト コネクタ固有のフィールド変数

データストアから取得した各フィールドが変数として利用可能 （変数名・接頭辞はコネクタによって異なる。CSV/JSONはフィールド名がそのまま変数になる）
パスマッピング url matcher 変換対象のURL文字列と、正規表現の Matcher （ groovy: 接頭辞付きの置換時のみ）
スケジュールジョブ executor ジョブ実行インスタンス（ JobExecutor ）。ジョブのシャットダウン制御に使用

注釈

container 以外のオブジェクトは特定のコンテキストでのみ注入されます。 たとえば executor はスケジュールジョブでのみ利用可能で、データストアスクリプトや パスマッピングでは利用できません。

セキュリティ

警告

スクリプトは強力な機能を持つため、信頼できるソースからのみ使用してください。

  • スクリプトはサーバー上で実行されます

  • ファイルシステムやネットワークへのアクセスが可能です

  • 管理者権限を持つユーザーのみがスクリプトを編集できるようにしてください

  • スクリプトの実行は監査ログ（ audit.log ）に記録されます。 記録の有無は script.audit.log.enabled で制御し、デフォルトは true です。 記録されるスクリプト文字列の最大長は script.audit.log.max.length で制御し、 デフォルトは 100 文字です。

パフォーマンス

スクリプトのパフォーマンスを最適化するためのヒント:

  1. 複雑な処理を避ける: データストアスクリプトはドキュメントごとに実行されます

  2. 外部リソースへのアクセスを最小化: ネットワーク呼び出しは遅延の原因になります

  3. キャッシュを活用: 繰り返し使用する値はキャッシュを検討

デバッグ

スケジュールジョブのスクリプトでは、スクリプト全体が1つのGroovyスクリプトとして 評価されるため、ログ出力を活用してデバッグできます。 （データストアスクリプトは1行が1つの式として評価されるため、 import 文や 複数行の処理は使用できません。）

import org.apache.logging.log4j.LogManager
def logger = LogManager.getLogger("fess.script")
logger.info("executor = {}", executor)

上記の例では fess.script という名前のロガーを使用しています。 このログを出力するには、 app/WEB-INF/classes/log4j2.xml に対応するロガー設定を 追加します。

<Logger name="fess.script" level="DEBUG"/>

また、スクリプトエンジン自体のデバッグログを有効にするには、 org.codelibs.fess.script パッケージのログレベルを DEBUG に設定します。

<Logger name="org.codelibs.fess.script" level="DEBUG"/>

参考情報